Merge pull request #1751 from mastertinner/master

Fix typos and optimize images

docs/FAQ.md

@@ -5,19 +5,22 @@ title: FAQ
 The FAQ predated the introduction of the rest of the documentation. If something in here conflicts with other guides or reference documents, it's probably here that it's wrong - please file a PR!
 
 ## Concepts
+
 * [Does `dep` replace `go get`?](#does-dep-replace-go-get)
 * [Why is it `dep ensure` instead of `dep install`?](#why-is-it-dep-ensure-instead-of-dep-install)
 * [What is a direct or transitive dependency?](#what-is-a-direct-or-transitive-dependency)
 
 ## Configuration
+
 * [What is the difference between Gopkg.toml (the "manifest") and Gopkg.lock (the "lock")?](#what-is-the-difference-between-gopkgtoml-the-manifest-and-gopkglock-the-lock)
 * [How do I constrain a transitive dependency's version?](#how-do-i-constrain-a-transitive-dependency-s-version)
-* [How do I change the version of a dependecy?](#how-do-i-change-the-version-of-a-dependecy)
+* [How do I change the version of a dependency?](#how-do-i-change-the-version-of-a-dependecy)
 * [Can I put the manifest and lock in the vendor directory?](#can-i-put-the-manifest-and-lock-in-the-vendor-directory)
 * [How do I get `dep` to authenticate to a `git` repo?](#how-do-i-get-dep-to-authenticate-to-a-git-repo)
-* [How do I get `dep` to consume private `git` repos using a Github Token?](#how-do-i-get-dep-to-consume-private-git-repos-using-a-github-token)
+* [How do I get `dep` to consume private `git` repos using a GitHub Token?](#how-do-i-get-dep-to-consume-private-git-repos-using-a-github-token)
 
 ## Behavior
+
 * [How does `dep` decide what version of a dependency to use?](#how-does-dep-decide-what-version-of-a-dependency-to-use)
 * [What external tools are supported?](#what-external-tools-are-supported)
 * [Why is `dep` ignoring a version constraint in the manifest?](#why-is-dep-ignoring-a-version-constraint-in-the-manifest)
@@ -29,6 +32,7 @@ The FAQ predated the introduction of the rest of the documentation. If something
 * [Will `dep` let me use git submodules to store dependencies in `vendor`?](#will-dep-let-me-use-git-submodules-to-store-dependencies-in-vendor)
 
 ## Best Practices
+
 * [Should I commit my vendor directory?](#should-i-commit-my-vendor-directory)
 * [How do I test changes to a dependency?](#how-do-i-test-changes-to-a-dependency)
 * [How do I roll releases that `dep` will be able to use?](#how-do-i-roll-releases-that-dep-will-be-able-to-use)
@@ -40,11 +44,13 @@ The FAQ predated the introduction of the rest of the documentation. If something
 * [How do I use `dep` in CI?](#how-do-i-use-dep-in-ci)
 
 ## Concepts
+
 ### Does `dep` replace `go get`?
 
 No. `dep` and `go get` serve mostly different purposes.
 
 Here are some suggestions for when you could use `dep` or `go get`:
+
 > I would say that dep doesn't replace go get, but they both can do similar things. Here's how I use them:
 >
 > `go get`: I want to download the source code for a go project so that I can work on it myself, or to install a tool. This clones the repo under GOPATH for all to use.
@@ -69,10 +75,12 @@ Here are some suggestions for when you could use `dep` or `go get`:
 > [@sdboyer in #371](https://github.com/golang/dep/issues/371#issuecomment-293246832)
 
 ### What is a direct or transitive dependency?
+
 * Direct dependencies are dependencies that are imported directly by your project: they appear in at least one import statement from your project.
 * Transitive dependencies are the dependencies of your dependencies. Necessary to compile but are not directly used by your code.
 
 ## Configuration
+
 ### What is the difference between `Gopkg.toml` (the "manifest") and `Gopkg.lock` (the "lock")?
 
 > The manifest describes user intent, and the lock describes computed outputs. There's flexibility in manifests that isn't present in locks..., as the "branch": "master" constraint will match whatever revision master HAPPENS to be at right now, whereas the lock is nailed down to a specific revision.
@@ -82,6 +90,7 @@ Here are some suggestions for when you could use `dep` or `go get`:
 > [@sdboyer in #281](https://github.com/golang/dep/issues/281#issuecomment-284118314)
 
 ## <a id="how-do-i-constrain-a-transitive-dependency-s-version"></a>How do I constrain a transitive dependency's version?
+
 First, if you're wondering about this because you're trying to keep the version
 of the transitive dependency from changing, then you're working against `dep`'s
 design. The lock file, `Gopkg.lock`, will keep the selected version of the
@@ -91,21 +100,21 @@ impossible to find a solution without changing that version.
 If that isn't your use case and you still need to constrain a transitive
 dependency, you have a couple of options:
 
-1. Make the transitive dependency a direct one, either with a dummy import or an entry in the `required` list in `Gopkg.toml`.
-2. Use an override.
+1.  Make the transitive dependency a direct one, either with a dummy import or an entry in the `required` list in `Gopkg.toml`.
+2.  Use an override.
 
 Overrides are a sledgehammer, and should only be used as a last resort. While
 constraints and overrides are declared in the same way in `Gopkg.toml`, they
 behave differently:
 
 * Constraints:
-   1. Can be declared by any project's manifest, yours or a dependency
-   2. Apply only to direct dependencies of the project declaring the constraint
-   3. Must not conflict with the `constraint` entries declared in any other project's manifest
+  1.  Can be declared by any project's manifest, yours or a dependency
+  2.  Apply only to direct dependencies of the project declaring the constraint
+  3.  Must not conflict with the `constraint` entries declared in any other project's manifest
 * Overrides:
-   1. Are only utilized from the current/your project's manifest
-   2. Apply globally, to direct and transitive dependencies
-   3. Supersede constraints declared in all manifests, yours or a dependency's
+  1.  Are only utilized from the current/your project's manifest
+  2.  Apply globally, to direct and transitive dependencies
+  3.  Supersede constraints declared in all manifests, yours or a dependency's
 
 Overrides are also discussed with some visuals in [the gps docs](https://github.com/sdboyer/gps/wiki/gps-for-Implementors#overrides).
 
@@ -118,13 +127,15 @@ If you want to:
 
 for one or more dependencies, do the following:
 
-1. Manually edit your `Gopkg.toml`.
-1. Run
+1.  Manually edit your `Gopkg.toml`.
+1.  Run
 
     ```sh
     $ dep ensure
     ```
+
 ## Can I put the manifest and lock in the vendor directory?
+
 No.
 
 > Placing these files inside `vendor/` would concretely bind us to `vendor/` in the long term.
@@ -140,7 +151,7 @@ authenticated repository.
 
 First, configure `git` to use the credentials option for the specific repository.
 
-For example, if you use gitlab, and you wish to access `https://gitlab.example.com/example/package.git`,
+For example, if you use GitLab, and you wish to access `https://gitlab.example.com/example/package.git`,
 then you would want to use the following configuration:
 
 ```
@@ -176,12 +187,13 @@ After configuring `git`, you may need to use `git` manually once to have it stor
 credentials. Once you've checked out the repo manually, it will then use the stored
 credentials. This at least appears to be the behavior for the osxkeychain provider.
 
-### How do I get dep to consume private git repos using a Github Token?
+### How do I get dep to consume private git repos using a GitHub Token?
 
-Another alternative to make `dep` work with private repos is to use a [Personal Github
+Another alternative to make `dep` work with private repos is to use a [Personal GitHub
 Token](https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line/)
 and configure it inside the [`.netrc` file](https://www.gnu.org/software/inetutils/manual/html_node/The-_002enetrc-file.html)
 as the following example:
+
 ```
 machine github.com
     login [YOUR_GITHUB_USERNAME]
@@ -191,6 +203,7 @@ machine github.com
 Once you have set that up, dep will automatically use that Token to authenticate to the repositories.
 
 ## Behavior
+
 ### How does `dep` decide what version of a dependency to use?
 
 The full algorithm is complex, but the most important thing to understand is
@@ -198,26 +211,26 @@ that `dep` tries versions in a [certain
 order](https://godoc.org/github.com/golang/dep/gps#SortForUpgrade),
 checking to see a version is acceptable according to specified constraints.
 
-- All semver versions come first, and sort mostly according to the semver 2.0
+* All semver versions come first, and sort mostly according to the semver 2.0
   spec, with one exception:
-  - Semver versions with a prerelease are sorted after *all* non-prerelease
+  * Semver versions with a prerelease are sorted after _all_ non-prerelease
     semver. Within this subset they are sorted first by their numerical
     component, then lexicographically by their prerelease version.
-- The default branch(es) are next; the semantics of what "default branch" means
+* The default branch(es) are next; the semantics of what "default branch" means
   are specific to the underlying source type, but this is generally what you'd
   get from a `go get`.
-- All other branches come next, sorted lexicographically.
-- All non-semver versions (tags) are next, sorted lexicographically.
-- Revisions, if any, are last, sorted lexicographically. Revisions do not
+* All other branches come next, sorted lexicographically.
+* All non-semver versions (tags) are next, sorted lexicographically.
+* Revisions, if any, are last, sorted lexicographically. Revisions do not
   typically appear in version lists, so the only invariant we maintain is
   determinism - deeper semantics, like chronology or topology, do not matter.
 
 So, given a slice of the following versions:
 
-- Branch: `master` `devel`
-- Semver tags: `v1.0.0` `v1.1.0` `v1.1.0-alpha1`
-- Non-semver tags: `footag`
-- Revision: `f6e74e8d`
+* Branch: `master` `devel`
+* Semver tags: `v1.0.0` `v1.1.0` `v1.1.0-alpha1`
+* Non-semver tags: `footag`
+* Revision: `f6e74e8d`
 
 Sorting for upgrade will result in the following slice:
 
@@ -230,6 +243,7 @@ basic action is to attempt versions in this order should help you to reason
 about what's going on.
 
 ## What external tools are supported?
+
 During `dep init` configuration from other dependency managers is detected
 and imported, unless `-skip-tools` is specified.
 
@@ -239,10 +253,12 @@ See [#186](https://github.com/golang/dep/issues/186#issuecomment-306363441) for
 how to add support for another tool.
 
 ## Why is `dep` ignoring a version constraint in the manifest?
+
 Only your project's directly imported dependencies are affected by a `constraint` entry
 in the manifest. Transitive dependencies are unaffected. See [How do I constrain a transitive dependency's version](#how-do-i-constrain-a-transitive-dependency-s-version)?
 
 ## Why did `dep` use a different revision for package X instead of the revision in the lock file?
+
 Sometimes the revision specified in the lock file is no longer valid. There are a few
 ways this can occur:
 
@@ -279,9 +295,9 @@ only paid once per changeset.
 
 The other part is the work of retrieving information about dependencies. There are three parts to this:
 
-1. Getting an up-to-date list of versions from the upstream source
-2. Reading the `Gopkg.toml` for a particular version out of the local cache
-3. Parsing the tree of packages for import statements at a particular version
+1.  Getting an up-to-date list of versions from the upstream source
+2.  Reading the `Gopkg.toml` for a particular version out of the local cache
+3.  Parsing the tree of packages for import statements at a particular version
 
 The first requires one or more network calls; the second two usually mean
 something like a `git checkout`, and the third is a filesystem walk, plus
@@ -298,23 +314,23 @@ There's another major performance issue that's much harder - the process of pick
 
 ## How does `dep` handle symbolic links?
 
-> because we're not crazy people who delight in inviting chaos into our lives, we need to work within one `GOPATH` at a time.
-> -[@sdboyer in #247](https://github.com/golang/dep/pull/247#issuecomment-284181879)
+> because we're not crazy people who delight in inviting chaos into our lives, we need to work within one `GOPATH` at a time. -[@sdboyer in #247](https://github.com/golang/dep/pull/247#issuecomment-284181879)
 
 Out of convenience, one might create a symlink to a directory within their `GOPATH/src`, e.g. `ln -s ~/go/src/github.com/user/awesome-project ~/Code/awesome-project`.
 
 When `dep` is invoked with a project root that is a symlink, it will be resolved according to the following rules:
 
-- If the symlink is outside `GOPATH` and links to a directory within a `GOPATH`, or vice versa, then `dep` will choose whichever path is within `GOPATH`.
-- If the symlink is within a `GOPATH` and the resolved path is within a *different* `GOPATH`, then an error is thrown.
-- If both the symlink and the resolved path are in the same `GOPATH`, then an error is thrown.
-- If neither the symlink nor the resolved path are in a `GOPATH`, then an error is thrown.
+* If the symlink is outside `GOPATH` and links to a directory within a `GOPATH`, or vice versa, then `dep` will choose whichever path is within `GOPATH`.
+* If the symlink is within a `GOPATH` and the resolved path is within a _different_ `GOPATH`, then an error is thrown.
+* If both the symlink and the resolved path are in the same `GOPATH`, then an error is thrown.
+* If neither the symlink nor the resolved path are in a `GOPATH`, then an error is thrown.
 
 This is the only symbolic link support that `dep` really intends to provide. In keeping with the general practices of the `go` tool, `dep` tends to either ignore symlinks (when walking) or copy the symlink itself, depending on the filesystem operation being performed.
 
 ## Does `dep` support relative imports?
 
 No.
+
 > dep simply doesn't allow relative imports. this is one of the few places where we restrict a case that the toolchain itself allows. we disallow them only because:
 >
 > * the toolchain already frowns heavily on them<br>
@@ -349,43 +365,44 @@ The reasons why git submodules will not be a part of dep are best expressed as a
 * Nesting one repository within another implies that changes could, potentially, be made directly in that subrepository. This is directly contrary to dep's foundational principle that `vendor` is dead code, and directly modifying anything in there is an error.
 
 ## Best Practices
+
 ### Should I commit my vendor directory?
 
 It's up to you:
 
 **Pros**
 
-- It's the only way to get truly reproducible builds, as it guards against upstream renames,
+* It's the only way to get truly reproducible builds, as it guards against upstream renames,
   deletes and commit history overwrites.
-- You don't need an extra `dep ensure` step to sync `vendor/` with Gopkg.lock after most operations,
+* You don't need an extra `dep ensure` step to sync `vendor/` with Gopkg.lock after most operations,
   such as `go get`, cloning, getting latest, merging, etc.
 
 **Cons**
 
-- Your repo will be bigger, potentially a lot bigger,
+* Your repo will be bigger, potentially a lot bigger,
   though [`prune`](Gopkg.toml.md#prune) can help minimize this problem.
-- PR diffs will include changes for files under `vendor/` when Gopkg.lock is modified,
-  however files in `vendor/` are [hidden by default](https://github.com/github/linguist/blob/v5.2.0/lib/linguist/generated.rb#L328) on Github.
+* PR diffs will include changes for files under `vendor/` when Gopkg.lock is modified,
+  however files in `vendor/` are [hidden by default](https://github.com/github/linguist/blob/v5.2.0/lib/linguist/generated.rb#L328) on GitHub.
 
-## How do I test changes to a dependency? 
+## How do I test changes to a dependency?
 
 Making changes in your `vendor/` directory directly is not recommended, as dep
 will overwrite any changes. Instead:
 
-1. Delete the dependency from the `vendor/` directory.
+1.  Delete the dependency from the `vendor/` directory.
 
     ```sh
     rm -rf vendor/<dependency>
     ```
 
-1. Add that dependency to your `GOPATH`, if it isn't already.
+1.  Add that dependency to your `GOPATH`, if it isn't already.
 
     ```sh
     $ go get <dependency>
     ```
 
-1. Modify the dependency in `$GOPATH/src/<dependency>`.
-1. Test, build, etc.
+1.  Modify the dependency in `$GOPATH/src/<dependency>`.
+1.  Test, build, etc.
 
 Don't run `dep ensure` until you're done. `dep ensure` will reinstall the
 dependency into `vendor/` based on your manifest, as if you were installing from
@@ -472,7 +489,7 @@ Add a constraint to `Gopkg.toml` that specifies `branch: "master"` (or whichever
 `dep ensure -vendor-only` creates the vendor folder from a valid `Gopkg.toml` and `Gopkg.lock` without checking for Go code.
 This is especially useful for builds inside docker utilizing cache layers.
 
-Sample dockerfile:
+Sample Dockerfile:
 
 ```Dockerfile
 FROM golang:1.9 AS builder
@@ -527,7 +544,7 @@ Caching can also be enabled but there are a couple of caveats you should be awar
 >
 > [@carolynvs in #1293](https://github.com/golang/dep/pull/1293#issuecomment-342969292)
 
-If you are sure you want to enable caching on travis, it can be done by adding `$GOPATH/pkg/dep`, the default location for `dep` cache, to the cached directories:
+If you are sure you want to enable caching on Travis, it can be done by adding `$GOPATH/pkg/dep`, the default location for `dep` cache, to the cached directories:
 
 ```yml
 # ...

docs/Gopkg.lock.md

@@ -10,7 +10,7 @@ The `Gopkg.lock` file is generated by `dep ensure` and `dep init`. It is the out
 
 `Gopkg.lock` also contains some metadata about the algorithm used to arrive at the final graph, under `[solve-meta]`.
 
-`Gopkg.lock` always includes a `revision` for all listed dependencies, as the semantics of `revision`  guarantee them to be immutable. Thus, the `Gopkg.lock` acts as a reproducible build list - as long as the upstream remains available, all dependencies can be precisely reproduced.
+`Gopkg.lock` always includes a `revision` for all listed dependencies, as the semantics of `revision` guarantee them to be immutable. Thus, the `Gopkg.lock` acts as a reproducible build list - as long as the upstream remains available, all dependencies can be precisely reproduced.
 
 `Gopkg.lock` is autogenerated; editing it manually is generally an antipattern. If there is a goal you can only achieve by hand-editing `Gopkg.lock`, it is at least a feature request, and likely a bug.
 
@@ -75,7 +75,7 @@ The solver is the algorithm behind [the solving function](ensure-mechanics.md#fu
 
 The solver is named because, like the analyzer, it is pluggable; an alternative algorithm could be written that applies different rules to achieve the same goal. The one dep uses, "gps-cdcl", is named after [the general class of SAT solving algorithm it most resembles](https://en.wikipedia.org/wiki/Conflict-Driven_Clause_Learning), though the algorithm is actually a specialized, domain-specific [SMT solver](https://en.wikipedia.org/wiki/Satisfiability_modulo_theories).
 
-The same general principles of version-bumping apply to the solver version: if the solver starts enforcing [Go 1.4 import path comments](https://golang.org/cmd/go/#hdr-Import_path_checking), that entails a bump, because it can only narrow the solution set. If it were to later relax that requirement, it would not require a bump, as that can only expand the solution set. 
+The same general principles of version-bumping apply to the solver version: if the solver starts enforcing [Go 1.4 import path comments](https://golang.org/cmd/go/#hdr-Import_path_checking), that entails a bump, because it can only narrow the solution set. If it were to later relax that requirement, it would not require a bump, as that can only expand the solution set.
 
 ### `inputs-digest`
 
@@ -83,4 +83,4 @@ A SHA256 hash digest of all the [inputs to the solving function](ensure-mechanic
 
 ```
 dep hash-inputs | tr -d “\n” | shasum -a256
-```
+```

docs/Gopkg.toml.md

@@ -15,7 +15,7 @@ There is a full [example](#example) `Gopkg.toml` file at the bottom of this docu
 
 ## Dependency rules: `[[constraint]]` and `[[override]]`
 
-Most of the rule declarations in a `Gopkg.toml` will be either `[[constraint]]` or `[[override]]` stanzas.  Both of these types of stanzas allow exactly the same types of values, but dep interprets them differently. Each allows the following values:
+Most of the rule declarations in a `Gopkg.toml` will be either `[[constraint]]` or `[[override]]` stanzas. Both of these types of stanzas allow exactly the same types of values, but dep interprets them differently. Each allows the following values:
 
 * `name` - the import path corresponding to the [source root](glossary.md#source-root) of a dependency (generally: where the VCS root is)
 * At most one [version rule](#version-rules)
@@ -54,7 +54,7 @@ A `[[constraint]]` stanza defines rules for how a [direct dependency](glossary.m
 
 An `[[override]]` stanza differs from a `[[constraint]]` in that it applies to all dependencies, [direct](glossary.md#direct-dependency) and [transitive](glossary.md#transitive-dependency), and supersedes all other `[[constraint]]` declarations for that project. However, only overrides from the current project's `Gopkg.toml` are incorporated.
 
-**Use this for:** Overrides are primarily intended as a way of eliminating disagreements between multiple irreconcilable `[[constraint]]` declarations on a single dependency. However, they will also be your primary recourse if you need to [constrain a transitive dependency's version?](FAQ.md#how-do-i-constrain-a-transitive-dependencys-version) 
+**Use this for:** Overrides are primarily intended as a way of eliminating disagreements between multiple irreconcilable `[[constraint]]` declarations on a single dependency. However, they will also be your primary recourse if you need to [constrain a transitive dependency's version?](FAQ.md#how-do-i-constrain-a-transitive-dependencys-version)
 
 Overrides should be used cautiously and temporarily, when possible.
 
@@ -80,20 +80,21 @@ Specifying semantic version ranges can be done using the following operators:
 * `<`: less than
 * `>=`: greater than or equal to
 * `<=`: less than or equal to
-* `-`: literal range. Eg: 1.2 - 1.4.5 is equivalent to >= 1.2, <= 1.4.5
-* `~`: minor range. Eg: ~1.2.3 is equivalent to >= 1.2.3, < 1.3.0
-* `^`: major range. Eg: ^1.2.3 is equivalent to >= 1.2.3, < 2.0.0
-* `[xX*]`: wildcard. Eg: 1.2.x is equivalent to >= 1.2.0, < 1.3.0
+* `-`: literal range. E.g., 1.2 - 1.4.5 is equivalent to >= 1.2, <= 1.4.5
+* `~`: minor range. E.g., ~1.2.3 is equivalent to >= 1.2.3, < 1.3.0
+* `^`: major range. E.g., ^1.2.3 is equivalent to >= 1.2.3, < 2.0.0
+* `[xX*]`: wildcard. E.g., 1.2.x is equivalent to >= 1.2.0, < 1.3.0
 
 You might, for example, include a rule that specifies `version = "=2.0.0"` to pin a dependency to version 2.0.0, or constrain to minor releases with: `version = "~2.1.0"`. Refer to the [semver library](https://github.com/Masterminds/semver) documentation for more info.
 
-**Note**: When you specify a version *without an operator*, `dep` automatically uses the `^` operator by default. `dep ensure` will interpret the given version as the min-boundary of a range, for example:
+**Note**: When you specify a version _without an operator_, `dep` automatically uses the `^` operator by default. `dep ensure` will interpret the given version as the min-boundary of a range, for example:
 
 * `1.2.3` becomes the range `>=1.2.3, <2.0.0`
 * `0.2.3` becomes the range `>=0.2.3, <0.3.0`
 * `0.0.3` becomes the range `>=0.0.3, <0.1.0`
 
 `~` and `=` operators can be used with the versions. When a version is specified without any operator, `dep` automatically adds a caret operator, `^`. The caret operator pins the left-most non-zero digit in the version. For example:
+
 ```
 ^1.2.3 means 1.2.3 <= X < 2.0.0
 ^0.2.3 means 0.2.3 <= X < 0.3.0
@@ -101,6 +102,7 @@ You might, for example, include a rule that specifies `version = "=2.0.0"` to pi
 ```
 
 To pin a version of direct dependency in manifest, prefix the version with `=`. For example:
+
 ```toml
 [[constraint]]
   name = "github.com/pkg/errors"
@@ -115,7 +117,7 @@ In general, you should prefer semantic versions to branches, when a project has
 
 #### `revision`
 
-A `revision` is the underlying immutable identifier - like a git commit SHA1. While it is allowed to constrain to a `revision`, doing so is almost always an antipattern. 
+A `revision` is the underlying immutable identifier - like a git commit SHA1. While it is allowed to constrain to a `revision`, doing so is almost always an antipattern.
 
 Usually, folks are inclined to pin to a revision because they feel it will somehow improve their project's reproducibility. That is not a good reason. `Gopkg.lock` provides reproducibility. Only use `revision` if you have a good reason to believe that _no_ other version of that dependency _could_ work.
 
@@ -126,6 +128,7 @@ As part of normal operation, dep analyzes import statements in Go code. These im
 ### `required`
 
 `required` lists a set of packages (not projects) that must be included in Gopkg.lock. This list is merged with the set of packages imported by the current project.
+
 ```toml
 required = ["github.com/user/thing/cmd/thing"]
 ```
@@ -136,7 +139,7 @@ required = ["github.com/user/thing/cmd/thing"]
 * Aren't `import`ed by your project, [directly or transitively](FAQ.md#what-is-a-direct-or-transitive-dependency)
 * You don't want to put them in your `GOPATH`, and/or you want to lock the version
 
-Please note that this only pulls in the sources of these dependencies. It does not install or compile them. So, if you need the tool to be installed you should still run the following (manually or from a `Makefile`)  after each `dep ensure`:
+Please note that this only pulls in the sources of these dependencies. It does not install or compile them. So, if you need the tool to be installed you should still run the following (manually or from a `Makefile`) after each `dep ensure`:
 
 ```bash
 cd vendor/pkg/to/install
@@ -152,8 +155,8 @@ export PATH=$GOBIN:$PATH
 
 You might also try [virtualgo](https://github.com/GetStream/vg), which installs dependencies in the `required` list automatically in a project specific `GOBIN`.
 
-
 ### `ignored`
+
 `ignored` lists a set of packages (not projects) that are ignored when dep statically analyzes source code. Ignored packages can be in this project, or in a dependency.
 
 ```toml
@@ -169,11 +172,13 @@ ignored = ["github.com/user/project/badpkg*"]
 **Use this for:** preventing a package, and any of that package's unique dependencies, from being incorporated in `Gopkg.lock`.
 
 ## `metadata`
+
 `metadata` can exist at the root as well as under `constraint` and `override` declarations.
 
 `metadata` declarations are ignored by dep and are meant for usage by other independent systems.
 
 The root `metadata` declaration defines information about the project itself, while a `metadata` declaration under a `[[constraint]]` or an `[[override]]` defines metadata about that rule, for the `name`d project.
+
 ```toml
 [metadata]
 key1 = "value that convey data to other systems"
@@ -186,6 +191,7 @@ system2-data = "value that is used by another system"
 `prune` defines the global and per-project prune options for dependencies. The options determine which files are discarded when writing the `vendor/` tree.
 
 The following are the current available options:
+
 * `unused-packages` indicates that files from directories that do not appear in the package import graph should be pruned.
 * `non-go` prunes files that are not used by Go.
 * `go-tests` prunes Go test files.
@@ -200,8 +206,7 @@ Pruning options are disabled by default. However, generating a `Gopkg.toml` via
   unused-packages = true
 ```
 
-The same prune options can be defined per-project. An addtional `name` field is required and, as with `[[constraint]]` and `[[override]]`, should be a [source root](glossary.md#source-root), not just any import path.
-
+The same prune options can be defined per-project. An additional `name` field is required and, as with `[[constraint]]` and `[[override]]`, should be a [source root](glossary.md#source-root), not just any import path.
 
 ```toml
 [prune]
@@ -212,6 +217,7 @@ The same prune options can be defined per-project. An addtional `name` field is
     go-tests = true
     non-go = false
 ```
+
 Almost all projects will be fine without setting any project-specific rules, and enabling the following pruning rules globally:
 
 ```toml
@@ -219,37 +225,38 @@ Almost all projects will be fine without setting any project-specific rules, and
   unused-packages = true
   go-tests = true
 ```
+
 It is usually safe to set `non-go = true`, as well. However, as dep only has a clear model for the role played by Go files, and non-Go files necessarily fall outside that model, there can be no comparable general definition of safety.
 
 ## Scope
 
 `dep` evaluates
+
 * `[[override]]`
 * `required`
 * `ignored`
 
 only in the root project, i.e. the project where `dep` runs. For example,
 
-You have a project: `github.com/urname/goproject`. 
+You have a project: `github.com/urname/goproject`.
 
-`github.com/foo/bar` is a dependency  for your project.
+`github.com/foo/bar` is a dependency for your project.
 
 Here `dep` evaluates the `Gopkg.toml` files of these packages as follows.
 
-|github.com/urname/goproject     |      github.com/foo/bar|
-|--------------------------------|---------------------------|
-|[[constraint]] ✔                |      [[constraint]] ✔|
-|[[override]] ✔                   |      [[override]] ✖|
-|required ✔                       |      required ✖|
-|ignored ✔                       |      ignored ✖|
+| github.com/urname/goproject | github.com/foo/bar |
+| --------------------------- | ------------------ |
+| [[constraint]] ✔            | [[constraint]] ✔   |
+| [[override]] ✔              | [[override]] ✖     |
+| required ✔                  | required ✖         |
+| ignored ✔                   | ignored ✖          |
 
 ️✔ : Evaluated
 ✖ ️: Not evaluated
 
-
 # Example
 
-A sample  `Gopkg.toml` with most elements present:
+A sample `Gopkg.toml` with most elements present:
 
 ```toml
 required = ["github.com/user/thing/cmd/thing"]

docs/daily-dep.md

@@ -9,7 +9,7 @@ Dep is a tool you'll use regularly in the course of normal Go development. Regul
 * `dep ensure` is the primary workhorse command, and is the only command that changes disk state.
 * `dep status` reports on the state of your project, and the visible universe of Go software projects.
 
-This guide primarily centers on  `dep ensure`, as that's the command you run to effect changes on your project. The [Models and Mechanisms](ensure-mechanics.md) reference document details how the things work under the hood, and is worth reading if you're encountering a confusing `dep ensure` behavior (or just curious!).
+This guide primarily centers on `dep ensure`, as that's the command you run to effect changes on your project. The [Models and Mechanisms](ensure-mechanics.md) reference document details how the things work under the hood, and is worth reading if you're encountering a confusing `dep ensure` behavior (or just curious!).
 
 ## Basics
 
@@ -19,21 +19,20 @@ Dep's main command is `dep ensure`. The verb is "ensure" to imply that the actio
 
 > Hey dep, please make sure that [my project](glossary.md#current-project) is [in sync](glossary.md#sync): that [`Gopkg.lock`](Gopkg.lock.md) satisfies all the imports in my project, and all the rules in[ `Gopkg.toml`](Gopkg.toml.md), and that `vendor/` contains exactly what `Gopkg.lock` says it should."
 
-As the narrative indicates, `dep ensure` is a holistic operation; rather than offering a series of commands that you run in succession to incrementally achieve some final state, each run of `dep ensure` delivers a safe, complete, and reproducible set of dependencies with respect to the current state of your project. You might imagine repeated runs of `dep ensure` as being a bit like a frog, hopping from one lilypad to the next.
-
- `dep ensure` also guarantees that, barring `kill -9`, power failure, or a critical bug, its disk writes are all-or-nothing: on any given run, either nothing changes (and you get an error), or you're on the nearest safe lilypad. This makes `dep ensure` fine to run at most any time.
+As the narrative indicates, `dep ensure` is a holistic operation; rather than offering a series of commands that you run in succession to incrementally achieve some final state, each run of `dep ensure` delivers a safe, complete, and reproducible set of dependencies with respect to the current state of your project. You might imagine repeated runs of `dep ensure` as being a bit like a frog, hopping from one lily pad to the next.
 
+`dep ensure` also guarantees that, barring `kill -9`, power failure, or a critical bug, its disk writes are all-or-nothing: on any given run, either nothing changes (and you get an error), or you're on the nearest safe lily pad. This makes `dep ensure` fine to run at most any time.
 
 ## Using `dep ensure`
 
 There are four times when you'll run `dep ensure`:
 
-- To add a new dependency
-- To update an existing dependency
-- To catch up after importing a package for the first time in your project, or removing the last import of a package in your project
-- To catch up to a change to a rule in `Gopkg.toml`
+* To add a new dependency
+* To update an existing dependency
+* To catch up after importing a package for the first time in your project, or removing the last import of a package in your project
+* To catch up to a change to a rule in `Gopkg.toml`
 
-There's also an implicit fifth time: when you're not sure if one of the above has happened. Running `dep ensure` without any additional flags will get your project back in sync - a known good state. As such, it's generally safe to defensively run `dep ensure`  as a way of simply making sure that your project is in that state.
+There's also an implicit fifth time: when you're not sure if one of the above has happened. Running `dep ensure` without any additional flags will get your project back in sync - a known good state. As such, it's generally safe to defensively run `dep ensure` as a way of simply making sure that your project is in that state.
 
 Let's explore each of these moments. To play along, you'll need to `cd` into a project that's already been set up by `dep init`. If you haven't done that yet, check out the guides for [new projects](new-project.md) and [migrations](migrating.md).
 
@@ -62,7 +61,7 @@ $ dep ensure -add github.com/pkg/errors github.com/foo/bar
 
 Dep works this way because it considers the import statements it discovers through static analysis of your project's code to be the canonical indicator of what dependencies must be present. That choice does add some pain at this moment, but it reduces friction and automates cleanup elsewhere. Tradeoffs!
 
-Of course, given this model, you don't _have to_ use `dep ensure -add` to add new dependencies - you can also just add an appropriate `import` statement in your code, then run `dep ensure`. However, this approach doesn't always play nicely with  [`goimports`](https://godoc.org/golang.org/x/tools/cmd/goimports), and also won't append a `[[constraint]]` into `Gopkg.toml`. Still, it can be useful at times, often for rapid iteration and off-the-cuff experimenting.
+Of course, given this model, you don't _have to_ use `dep ensure -add` to add new dependencies - you can also just add an appropriate `import` statement in your code, then run `dep ensure`. However, this approach doesn't always play nicely with [`goimports`](https://godoc.org/golang.org/x/tools/cmd/goimports), and also won't append a `[[constraint]]` into `Gopkg.toml`. Still, it can be useful at times, often for rapid iteration and off-the-cuff experimenting.
 
 The [ensure mechanics section on `-add`](ensure-mechanics.md#add) has a more thorough exploration, including some ways that `dep ensure -add`'s behavior subtly varies depending on the state of your project.
 
@@ -88,10 +87,10 @@ As noted in [the section on adding dependencies](#adding-a-new-dependency), dep
 
 It's only "might," though, because most of the time, adding or removing imports doesn't matter to dep. Only if one of the following has occurred will a `dep ensure` be necessary to bring the project back in sync:
 
-1. You've added the first `import` of a package, but already `import` other packages from that project.
-2. You've removed the last `import` of a package, but still `import` other packages from that project.
-3. You've added the first `import` of any package within a particular project. (Note: this is the [alternate adding approach](#adding-a-new-dependency))
-4. You've removed the last `import` of a package from within a particular project.
+1.  You've added the first `import` of a package, but already `import` other packages from that project.
+2.  You've removed the last `import` of a package, but still `import` other packages from that project.
+3.  You've added the first `import` of any package within a particular project. (Note: this is the [alternate adding approach](#adding-a-new-dependency))
+4.  You've removed the last `import` of a package from within a particular project.
 
 In short, dep is concerned with the set of unique import paths across your entire project, and only cares when you make a change that adds or removes an import path from that set.
 
@@ -101,7 +100,7 @@ Only if it is the first/last import of a project being added/removed - cases 3 a
 
 ### Rule changes in `Gopkg.toml`
 
-`Gopkg.toml` files contain five basic types of rules. The  [`Gopkg.toml` docs](Gopkg.toml.md) explain them in detail, but here's an overview:
+`Gopkg.toml` files contain five basic types of rules. The [`Gopkg.toml` docs](Gopkg.toml.md) explain them in detail, but here's an overview:
 
 * `required`, which are mostly equivalent to `import` statements in `.go` files, except that it's OK to list a `main` package here
 * `ignored`, which causes dep to black hole an import path (and any imports it uniquely introduces)
@@ -122,7 +121,8 @@ $ sudo apt-get install graphviz
 $ dep status -dot | dot -T png | display
 ```
 
-### MacOS
+### macOS
+
 ```
 $ brew install graphviz
 $ dep status -dot | dot -T png | open -f -a /Applications/Preview.app
@@ -141,13 +141,12 @@ $ dep status -dot | dot -T png | open -f -a /Applications/Preview.app
 
 Here are the key takeaways from this guide:
 
-- `dep ensure -update` is the preferred way to update dependencies, though it's less effective for projects that don't publish semver releases.
-- `dep ensure -add` is usually the easiest way to introduce new dependencies, though it's not the only one. To add more than one at a time, you'll need to use multiple arguments, not multiple invocations - and make sure to add real `import` statements for the projects after the command completes!
-- If you ever make a manual change in `Gopkg.toml`, it's best to run `dep ensure` to make sure everything's in sync.
-- `dep ensure` is almost never the wrong thing to run; if you're not sure what's going on, running it will bring you back to safety ("the nearest lilypad"), or fail informatively.
+* `dep ensure -update` is the preferred way to update dependencies, though it's less effective for projects that don't publish semver releases.
+* `dep ensure -add` is usually the easiest way to introduce new dependencies, though it's not the only one. To add more than one at a time, you'll need to use multiple arguments, not multiple invocations - and make sure to add real `import` statements for the projects after the command completes!
+* If you ever make a manual change in `Gopkg.toml`, it's best to run `dep ensure` to make sure everything's in sync.
+* `dep ensure` is almost never the wrong thing to run; if you're not sure what's going on, running it will bring you back to safety ("the nearest lilypad"), or fail informatively.
 
 Also, a couple other miscellaneous tidbits:
 
-- As in the Go toolchain generally, avoid symlinks within your own project. dep tolerates a bit of this, but like the Go toolchain itself, is generally not terribly supportive of symlinks.
-- Never directly edit anything in `vendor/`; dep will unconditionally overwrite such changes. If you need to modify a dependency, fork it and do it properly.
-
+* As in the Go toolchain generally, avoid symlinks within your own project. dep tolerates a bit of this, but like the Go toolchain itself, is generally not terribly supportive of symlinks.
+* Never directly edit anything in `vendor/`; dep will unconditionally overwrite such changes. If you need to modify a dependency, fork it and do it properly.

docs/deduction.md

@@ -4,8 +4,8 @@ title: Import Path Deduction
 
 Deduction is dep's algorithm for looking at an import path and determining the portion of the path that corresponds to the source root. The algorithm has a static component, by which a small set of known, popular hosts like GitHub and Bitbucket have their roots deduced:
 
-- `github.com/golang/dep/gps` -> `github.com/golang/dep`
-- `bitbucket.org/foo/bar/baz` -> `bitbucket.org/foo/bar`
+* `github.com/golang/dep/gps` -> `github.com/golang/dep`
+* `bitbucket.org/foo/bar/baz` -> `bitbucket.org/foo/bar`
 
 The set of hosts supported by static deduction are the same as [those supported by `go get`](https://golang.org/cmd/go/#hdr-Remote_import_paths):
 
@@ -23,4 +23,3 @@ Import path deduction is applied to all of the following:
 * `import` statements found in all `.go` files
 * Import paths in the [`required`](Gopkg.toml.md#required) list in `Gopkg.toml`
 * `name` properties in both [`[[constraint]]`](Gopkg.toml.md#constraint) and [`[[override]]`](Gopkg.toml.md#override) stanzas in `Gopkg.toml`. This is solely for validation purposes, enforcing that these names correspond only to project/source roots.
-

docs/ensure-mechanics.md

@@ -10,10 +10,10 @@ Dep is centered around the idea of the "four state system" - a model for classif
 
 Briefly, the four states are:
 
-1. The [current project's](glossary.md#current-project) source code.
-2. A [manifest](glossary.md#manifest) - a file describing the current project's dependency requirements. In dep, this is the [`Gopkg.toml`](Gopkg.toml.md) file.
-3. A [lock](glossary.md#lock) - a file containing a transitively-complete, reproducible description of the dependency graph. In dep, this is the [`Gopkg.lock`](Gopkg.lock.md) file.
-4. The source code of the dependences themselves. In dep's current design, this is the `vendor/` directory.
+1.  The [current project's](glossary.md#current-project) source code.
+2.  A [manifest](glossary.md#manifest) - a file describing the current project's dependency requirements. In dep, this is the [`Gopkg.toml`](Gopkg.toml.md) file.
+3.  A [lock](glossary.md#lock) - a file containing a transitively-complete, reproducible description of the dependency graph. In dep, this is the [`Gopkg.lock`](Gopkg.lock.md) file.
+4.  The source code of the dependences themselves. In dep's current design, this is the `vendor/` directory.
 
 We can visually represent these four states as follows:
 
@@ -44,7 +44,7 @@ type SolveParameters struct {
 
 The vendoring function is [`gps.WriteDepTree()`](https://godoc.org/github.com/golang/dep/gps#WriteDepTree). While it takes a handful of arguments, the relevant one is a [`gps.Lock`](https://godoc.org/github.com/golang/dep/gps#Lock) - an interface representing an abstracted form of the data held in a `Gopkg.lock`.
 
-The four state system, and these functional flows through it, are the foundation on which all of dep's behavior is built. If you want to understand dep's mechanics, keep this model at the forefront of your mind. 
+The four state system, and these functional flows through it, are the foundation on which all of dep's behavior is built. If you want to understand dep's mechanics, keep this model at the forefront of your mind.
 
 ### Staying in sync
 
@@ -63,26 +63,25 @@ Each of `dep ensure`'s various flags affects the behavior of the solving and ven
 
 ### `-no-vendor` and `-vendor-only`
 
-These two flags are mutually exclusive, and determine which of `dep ensure`'s two functions are actually performed. Passing `-no-vendor` will cause only the solving function to be run, resulting in the creation of a new `Gopkg.lock`;  `-vendor-only` will skip solving and run only the vendoring function, causing `vendor/` to be repopulated from the pre-existing `Gopkg.lock`.
+These two flags are mutually exclusive, and determine which of `dep ensure`'s two functions are actually performed. Passing `-no-vendor` will cause only the solving function to be run, resulting in the creation of a new `Gopkg.lock`; `-vendor-only` will skip solving and run only the vendoring function, causing `vendor/` to be repopulated from the pre-existing `Gopkg.lock`.
 
 ![Flags to run only one or the other of dep's functions](assets/func-toggles.png)
 
-Passing `-no-vendor` has the additional effect of causing the solving function to run unconditionally,  bypassing the pre-check ordinarily made against `Gopkg.lock` to see if it already satisfies all inputs.
+Passing `-no-vendor` has the additional effect of causing the solving function to run unconditionally, bypassing the pre-check ordinarily made against `Gopkg.lock` to see if it already satisfies all inputs.
 
 ### `-add`
 
-The general purpose of `dep ensure -add`  is to facilitate the introduction of new dependencies into the depgraph. Whereas `-update` is restricted to [source roots](glossary.md#source-root), (e.g. `github.com/foo/bar`), `-add` can take any package import path as an argument (e.g. `github.com/foo/bar` OR `github.com/foo/bar/baz`).
+The general purpose of `dep ensure -add` is to facilitate the introduction of new dependencies into the depgraph. Whereas `-update` is restricted to [source roots](glossary.md#source-root), (e.g. `github.com/foo/bar`), `-add` can take any package import path as an argument (e.g. `github.com/foo/bar` OR `github.com/foo/bar/baz`).
 
 Conceptually, there are two possible things that `-add` might be introducing. Any `dep ensure -add` run will do at least one of these:
 
-1. Running the solving function in order to generate a new `Gopkg.lock`  with the new dependenc(ies)
-2. Appending a version constraint into `Gopkg.toml`
+1.  Running the solving function in order to generate a new `Gopkg.lock` with the new dependenc(ies)
+2.  Appending a version constraint into `Gopkg.toml`
 
 This implies two preconditions for `dep ensure -add`, at least one of which must be met:
 
-1. The named import path is not currently in the project's import statements, or in `Gopkg.toml`'s `required` list
-2. There is no `[[constraint]]` stanza in `Gopkg.toml` for the project root corresponding to the named import path
-
+1.  The named import path is not currently in the project's import statements, or in `Gopkg.toml`'s `required` list
+2.  There is no `[[constraint]]` stanza in `Gopkg.toml` for the project root corresponding to the named import path
 
 It is also possible to explicitly specify a version constraint:
 
@@ -94,14 +93,14 @@ When no version constraint is included in the argument, the solving function wil
 
 The behavioral variations that arise from the assorted differences in input and current project state are best expressed as a matrix:
 
-| Argument to `dep ensure -add` | Has `[[constraint]]` stanza in `Gopkg.toml` | In imports or `required` | Result                                   |
-| ----------------------------- | ---------------------------------------- | ------------------------ | ---------------------------------------- |
-| `github.com/foo/bar`          | N                                        | N                        | Added temporarily to `Gopkg.lock` & `vendor/`; inferred version constraint appended to `Gopkg.toml` |
-| `github.com/foo/bar@v1.0.0`   | N                                        | N                        | Added temporarily to `Gopkg.lock` & `vendor/`; specified version constraint appended to `Gopkg.toml` |
-| `github.com/foo/bar`          | Y                                        | N                        | Added temporarily to `Gopkg.lock` & `vendor/` |
-| `github.com/foo/bar@v1.0.0`   | Y                                        | -                        | **Immediate error**: constraint already present in `Gopkg.toml` |
-| `github.com/foo/bar`          | N                                        | Y                        | Infer version constraint from `Gopkg.lock` and add to `Gopkg.toml` |
-| `github.com/foo/bar`          | Y                                        | Y                        | **Immediate error:** nothing to do       |
+| Argument to `dep ensure -add` | Has `[[constraint]]` stanza in `Gopkg.toml` | In imports or `required` | Result                                                                                               |
+| ----------------------------- | ------------------------------------------- | ------------------------ | ---------------------------------------------------------------------------------------------------- |
+| `github.com/foo/bar`          | N                                           | N                        | Added temporarily to `Gopkg.lock` & `vendor/`; inferred version constraint appended to `Gopkg.toml`  |
+| `github.com/foo/bar@v1.0.0`   | N                                           | N                        | Added temporarily to `Gopkg.lock` & `vendor/`; specified version constraint appended to `Gopkg.toml` |
+| `github.com/foo/bar`          | Y                                           | N                        | Added temporarily to `Gopkg.lock` & `vendor/`                                                        |
+| `github.com/foo/bar@v1.0.0`   | Y                                           | -                        | **Immediate error**: constraint already present in `Gopkg.toml`                                      |
+| `github.com/foo/bar`          | N                                           | Y                        | Infer version constraint from `Gopkg.lock` and add to `Gopkg.toml`                                   |
+| `github.com/foo/bar`          | Y                                           | Y                        | **Immediate error:** nothing to do                                                                   |
 
 For any of the paths where `dep ensure -add` needs to run the solving function in order to generate an updated `Gopkg.lock`, the relevant information from CLI arguments is applied to the in-memory representation of `Gopkg.toml`:
 
@@ -133,7 +132,7 @@ As such, the lock is another one of the properties encoded onto the [previously-
 
 ```go
 type SolveParameters struct {
- 	...
+	...
 	Lock gps.Lock // Gopkg.lock
 	ToChange []gps.ProjectRoot // args to -update
 	ChangeAll bool // true if no -update args passed
@@ -173,7 +172,7 @@ So, barring some other conflict, `v1.2.0` is selected, resulting in the desired
 
 Continuing with our example, it's important to note that updates with `-update` are achieved incidentally - the solver never explicitly targets a newer version. It just skips adding a hint from the lock, then selects the first version in the queue that satisfies constraints. Consequently, `-update` is only effective with certain types of constraints.
 
-It does work with branch constraints, which we can observe by including the underlying revision. If the user has constrained on `branch = "master"`, and `Gopkg.lock` points at a topologically older revision (say, `aabbccd`) than the tip of the canonical source's `master` branch (say, `bbccdde`), then `dep ensure` will end up contructing a queue that looks like this:
+It does work with branch constraints, which we can observe by including the underlying revision. If the user has constrained on `branch = "master"`, and `Gopkg.lock` points at a topologically older revision (say, `aabbccd`) than the tip of the canonical source's `master` branch (say, `bbccdde`), then `dep ensure` will end up constructing a queue that looks like this:
 
 ```bash
 [master@aabbccd, v1.1.0, v1.2.0, v1.1.1, v1.1.0, v1.0.0, master@bbccdde]
@@ -191,13 +190,11 @@ Thus, even if an upstream tag is force-pushed in one of your project's dependenc
 
 The key takeaway here is that `-update`'s behavior is governed by the type of constraints specified:
 
-| `Gopkg.toml` version constraint type | Constraint example | `dep ensure -update` behavior            |
-| ------------------------------------ | ------------------ | ---------------------------------------- |
-| `version` (semver range)             | `"^1.0.0"`         | Tries to get the latest version allowed by the range |
-| `branch`                             | `"master"`         | Tries to move to the current tip of the named branch |
-| `version` (non-range semver)         | `"=1.0.0"`         | Change can only occur if the upstream release was moved (e.g. `git push --force <tag>`) |
-| `version` (non-semver)               | `"foo"`            | Change can only occur if the upstream release was moved |
-| `revision`                           | `aabbccd...`       | No change is possible                    |
+| `Gopkg.toml` version constraint type | Constraint example | `dep ensure -update` behavior                                                                                                             |
+| ------------------------------------ | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| `version` (semver range)             | `"^1.0.0"`         | Tries to get the latest version allowed by the range                                                                                      |
+| `branch`                             | `"master"`         | Tries to move to the current tip of the named branch                                                                                      |
+| `version` (non-range semver)         | `"=1.0.0"`         | Change can only occur if the upstream release was moved (e.g. `git push --force <tag>`)                                                   |
+| `version` (non-semver)               | `"foo"`            | Change can only occur if the upstream release was moved                                                                                   |
+| `revision`                           | `aabbccd...`       | No change is possible                                                                                                                     |
 | (none)                               | (none)             | The first version that works, according to [the sort order](https://godoc.org/github.com/golang/dep/gps#SortForUpgrade) (not recommended) |
-
-

docs/failure-modes.md

@@ -26,14 +26,13 @@ dep talks to the network at several different points. These vary somewhat depend
 * Updating a local cache (in git terms, `git fetch`) with the latest changes from an upstream source.
 * Writing out code trees under `vendor` is typically done from the local cache, but under some circumstances a tarball may be fetched on-the-fly from a remote source.
 
-
 Network failures that you actually may observe are biased towards the earlier items in the list, simply because those operations tend to happen first: you generally don't see update failures as much as version-listing failures, because they usually have the same underlying cause (source host is down, network partition, etc.), but the version-list request happens first on most paths.
 
 #### Persistent network failures
 
 Although most network failures are ephemeral, there are three well-defined cases where they're more permanent:
 
-* **The network on which the source resides is permanently unreachable from the user's location:** in practice, this generally means one of two things: you've forgotten to log into your company VPN, or you're behind [the GFW](https://en.wikipedia.org/wiki/Great_Firewall). In the latter case, setting the *de facto* standard HTTP proxy environment variables that [`http.ProxyFromEnvironment()`](https://golang.org/pkg/net/http/#ProxyFromEnvironment) respects will cause dep's `go-get` HTTP metadata requests, as well as git, bzr, and hg subcommands, to utilize the proxy.
+* **The network on which the source resides is permanently unreachable from the user's location:** in practice, this generally means one of two things: you've forgotten to log into your company VPN, or you're behind [the GFW](https://en.wikipedia.org/wiki/Great_Firewall). In the latter case, setting the _de facto_ standard HTTP proxy environment variables that [`http.ProxyFromEnvironment()`](https://golang.org/pkg/net/http/#ProxyFromEnvironment) respects will cause dep's `go-get` HTTP metadata requests, as well as git, bzr, and hg subcommands, to utilize the proxy.
 
   * Remediation is also exactly the same when the custom `go-get` HTTP metadata service for a source is similarly unreachable. The failure messages, however, will look like [deduction failures](#deduction-failures).
 
@@ -79,11 +78,11 @@ There are no known cases where, in the course of normal operations, dep can irre
 
 Dep may encounter errors while attempting to write out the `vendor` directory itself (any such errors will result in a full rollback; causing no changes to be made to disk). To help pinpoint where the problem may be, know that this is the flow for populating `vendor`:
 
-1. Allocate a new temporary directory within the system temporary directory.
-2. Rename the existing `vendor` directory to `vendor.orig`. Do this within the current project's root directory if possible; if not, rename and move it to the tempdir.
-3. Create a new `vendor` directory within the tempdir and concurrently populate it with all the projects named in `Gopkg.lock`.
-4. Move the new `vendor` directory into place in the current project's root directory.
-5. Delete the old `vendor` directory.
+1.  Allocate a new temporary directory within the system temporary directory.
+2.  Rename the existing `vendor` directory to `vendor.orig`. Do this within the current project's root directory if possible; if not, rename and move it to the tempdir.
+3.  Create a new `vendor` directory within the tempdir and concurrently populate it with all the projects named in `Gopkg.lock`.
+4.  Move the new `vendor` directory into place in the current project's root directory.
+5.  Delete the old `vendor` directory.
 
 Note: this flow will become more targeted after [vendor verification]() allows dep to identify and target the subset of projects currently in `vendor` that need to be changed.
 
@@ -94,7 +93,7 @@ Known problems in this category include:
 
 ## Logical failures
 
-Logical failures encompass everything that can happen within dep's logical problem-solving domain - after 
+Logical failures encompass everything that can happen within dep's logical problem-solving domain - after
 
 Some of these failures can be as straightforward as typos, and are just as easily resolved. Others, unfortunately, may necessitate forking and modifying an upstream project - although such cases are very rare.
 
@@ -172,7 +171,7 @@ When `dep ensure` or `dep init` exit with an error message looking something lik
 $ dep init
 init failed: unable to solve the dependency graph: Solving failure: No versions of github.com/foo/bar met constraints:
 	v1.0.1: Could not introduce github.com/foo/bar@v1.13.1, as its subpackage github.com/foo/bar/foo is missing. (Package is required by (root).)
-	v1.0.0: Could not introduce github.com/foo/bar@v1.13.0, as... 
+	v1.0.0: Could not introduce github.com/foo/bar@v1.13.0, as...
 	v0.1.0: (another error)
 	master: (another error)
 ```
@@ -185,20 +184,18 @@ These rules, and specific remediations for failing to meet them, are described i
 
 * **`[[constraint]]` conflicts:** when projects in the dependency graph disagree on what [versions](Gopkg.toml.md#version-rules) are acceptable for a project, or where to [source](Gopkg.toml.md#source) it from.
   * Remediation will usually be either changing a `[[constraint]]` or adding an `[[override]]`, but genuine conflicts may require forking and hacking code.
-* **Package validity failure:** when an imported package is quite obviously not capable of being built. 
+* **Package validity failure:** when an imported package is quite obviously not capable of being built.
   * There usually isn't much remediation here beyond "stop importing that," as it indicates something broken at a particular version.
 * **Import comment failure:** when the import path used to address a package differs from the [import comment](https://golang.org/cmd/go/#hdr-Import_path_checking) the package uses to specify how it should be imported.
   * Remediation is to use the specified import path, instead of whichever one you used.
 * **Case-only import variation failure:** when two equal-except-for-case imports exist in the same build.
   * Remediation is to pick one case variation to use throughout your project, then manually update all projects in your depgraph to use the new casing.
 
-
 Let's break down the process of addressing a solving failure into a series of steps:
 
-1. First, look through the failed versions list for a version of the dependency that works for you (or a failure that seems fixable), then try to work that one out. Often enough, you'll see a single failure repeated across the entire version list, which makes it pretty clear what problem you need to solve.
-2. Take the remediation steps specific to that failure.
-3. Re-run the same command you ran that produced the failure. There are three possible outcomes:
-   1. Success!
-   2. Your fix was ineffective - the same failure re-occurs. Either re-examine your fix (step 2), or look for a new failure to fix (step 1).
-   3. Your fix was effective, but some new failure arose. Return to step 1 with the new failure list.
-
+1.  First, look through the failed versions list for a version of the dependency that works for you (or a failure that seems fixable), then try to work that one out. Often enough, you'll see a single failure repeated across the entire version list, which makes it pretty clear what problem you need to solve.
+2.  Take the remediation steps specific to that failure.
+3.  Re-run the same command you ran that produced the failure. There are three possible outcomes:
+    1.  Success!
+    2.  Your fix was ineffective - the same failure re-occurs. Either re-examine your fix (step 2), or look for a new failure to fix (step 1).
+    3.  Your fix was effective, but some new failure arose. Return to step 1 with the new failure list.

docs/glossary.md

@@ -59,17 +59,17 @@ Deduction is the process of determining the subset of an import path that corres
 
 A project's direct dependencies are those that it _imports_ from one or more of its packages, or includes in its [`required`](Gopkg.toml.md#required) list in `Gopkg.toml`.
 
- If each letter in `A -> B -> C -> D` represents a distinct project containing only a single package, and `->` indicates an import statement, then `B` is  `A`'s direct dependency, whereas `C` and `D` are [transitive dependencies](#transitive-dependency) of `A`.
+If each letter in `A -> B -> C -> D` represents a distinct project containing only a single package, and `->` indicates an import statement, then `B` is `A`'s direct dependency, whereas `C` and `D` are [transitive dependencies](#transitive-dependency) of `A`.
 
 Dep only incorporates the `required` rules from the [current project's](#current-project) `Gopkg.toml`. Therefore, if `=>` represents `required` rather than a standard import, and `A -> B => C`, then `C` is a direct dependency of `B` _only_ when `B` is the current project. Because the `B`-to-`C` link does not exist when `A` is the current project, then `C` won't actually be in the graph at all.
 
 ### External Import
 
-An `import` statement that points to a package in a project other than the one in which it originates. For example, an `import` in package `github.com/foo/bar` will be considered an external import if it points to anything _other_ than stdlib or  `github.com/foo/bar/*`.
+An `import` statement that points to a package in a project other than the one in which it originates. For example, an `import` in package `github.com/foo/bar` will be considered an external import if it points to anything _other_ than stdlib or `github.com/foo/bar/*`.
 
 ### GPS
 
-Stands for "Go packaging solver", it is [a subtree of library-style packages within dep](https://godoc.org/github.com/golang/dep/gps), and is the engine around which dep is built. Most commonly referred to as "gps." 
+Stands for "Go packaging solver", it is [a subtree of library-style packages within dep](https://godoc.org/github.com/golang/dep/gps), and is the engine around which dep is built. Most commonly referred to as "gps."
 
 ### Local cache
 
@@ -95,7 +95,7 @@ Variously referenced as "HTTP metadata service", "`go-get` HTTP metadata service
 
 ### Override
 
-An override is a [`[[override]]`](Gopkg.toml.md#override) stanza in `Gopkg.toml`. 
+An override is a [`[[override]]`](Gopkg.toml.md#override) stanza in `Gopkg.toml`.
 
 ### Project
 
@@ -108,7 +108,7 @@ The root import path for a project. A project root is defined as:
 * For the current project, the location of the `Gopkg.toml` file defines the project root
 * For dependencies, the root of the network [source](#source) (VCS repository) is treated as the project root
 
-These are generally one and the same, though not always. When using dep inside a monorepo, multiple `Gopkg.toml` files may exist at subpaths for discrete projects, designating each of those import paths as Project Roots. This works fine when working directly on those projects. If, however, any project not in the repository seeks to import the monorepo, dep will treat the monorepo's as one big Project, with the root directory being the Project Root; it will disregard any and all  `Gopkg.toml` files in subdirectories.
+These are generally one and the same, though not always. When using dep inside a monorepo, multiple `Gopkg.toml` files may exist at subpaths for discrete projects, designating each of those import paths as Project Roots. This works fine when working directly on those projects. If, however, any project not in the repository seeks to import the monorepo, dep will treat the monorepo's as one big Project, with the root directory being the Project Root; it will disregard any and all `Gopkg.toml` files in subdirectories.
 
 This may also be referred to as the "import root" or "root import path."
 
@@ -118,7 +118,7 @@ This may also be referred to as the "import root" or "root import path."
 
 ### Source
 
-The remote entities that hold versioned code. Sources are specifically the entity containing the code, not any particular version of thecode itself.
+The remote entities that hold versioned code. Sources are specifically the entity containing the code, not any particular version of the code itself.
 
 "Source" is used in lieu of "VCS" because Go package management tools will soon learn to use more than just VCS systems.
 
@@ -134,6 +134,6 @@ This concept is explored in detail on [the ensure mechanics reference page](ensu
 
 ### Transitive Dependency
 
-A project's transitive dependencies are those dependencies that it does not import itself, but are imported by one of its dependencies. 
+A project's transitive dependencies are those dependencies that it does not import itself, but are imported by one of its dependencies.
 
-If each letter in `A -> B -> C -> D` represents a distinct project containing only a single package, and `->` indicates an import statement, then  `C` and `D` are  `A`'s transitive dependencies, whereas `B` is a [direct dependency](#transitive-dependency) of `A`.
+If each letter in `A -> B -> C -> D` represents a distinct project containing only a single package, and `->` indicates an import statement, then `C` and `D` are `A`'s transitive dependencies, whereas `B` is a [direct dependency](#transitive-dependency) of `A`.

docs/installation.md

@@ -4,7 +4,6 @@ title: Installation
 
 It is strongly recommended that you use a released version of dep. While tip is never purposefully broken, its stability is not guaranteed.
 
-
 ## Binary Installation
 
 Pre-compiled binaries are available on the [releases](https://github.com/golang/dep/releases) page. You can use the `install.sh` script to automatically install one for your local platform:
@@ -33,6 +32,7 @@ makepkg -si
 ```
 
 ## Install From Source
+
 The snippet below installs the latest release of dep from source and sets the
 version in the binary so that `dep version` works as expected.
 
@@ -56,4 +56,5 @@ If you want to hack on dep, you can install via `go get`:
 ```sh
 go get -u github.com/golang/dep/cmd/dep
 ```
+
 Note that dep requires a functioning Go workspace and GOPATH. If you're unfamiliar with Go workspaces and GOPATH, have a look at [the language documentation](https://golang.org/doc/code.html#Organization) and get your local workspace set up. Dep's model could lead to being able to work without GOPATH, but we're not there yet.

docs/introduction.md

@@ -3,9 +3,8 @@ id: introduction
 title: Getting Started
 ---
 
-
 Welcome! This is documentation for dep, the "official experiment" dependency management tool for the Go language. Dep is a tool intended primarily for use by developers, to support the work of actually writing and shipping code. It is _not_ intended for end users who are installing Go software - that's what `go get` does.
 
 This site has both guides and reference documents. The guides are practical explanations of how to actually do things with dep, whereas the reference material provides deeper dives on specific topics. Of particular note is the [glossary](glossary.md) - if you're unfamiliar with terminology used in this documentation, make sure to check there!
 
-After [installing dep](installation.md), if you're using it for the first time, check out [Creating a New Project](new-project.md). Or, if you have an existing Go project that you want to convert to dep, [Migrating to Dep](migrating.md) is probably the place to start.
+After [installing dep](installation.md), if you're using it for the first time, check out [Creating a New Project](new-project.md). Or, if you have an existing Go project that you want to convert to dep, [Migrating to Dep](migrating.md) is probably the place to start.

docs/migrating.md

@@ -11,9 +11,9 @@ $ dep init
 
 For many projects, this will just work. `dep init` will make educated guesses about what versions to use for your dependencies, generate sane `Gopkg.toml`, `Gopkg.lock`, and `vendor/`, and if your tests pass and builds work, then you're probably done. (If so, congratulations! You should check out [Daily Dep](daily-dep.md) next.)
 
-The migration process is still difficult for some projects. If you're trying dep for the first time, this can be particularly frustrating, as you're trying to simultaneously learn how to use dep, and how your project *should* be managed in dep. The good news is,  `dep init` is usually the big difficulty hump; once you're over it, things get much easier.
+The migration process is still difficult for some projects. If you're trying dep for the first time, this can be particularly frustrating, as you're trying to simultaneously learn how to use dep, and how your project _should_ be managed in dep. The good news is, `dep init` is usually the big difficulty hump; once you're over it, things get much easier.
 
-The goal of this guide is to provide enough information for you to reason about what's happening during `dep init`, so that you can at least understand what class of problems you're encountering, and what steps you might take to address them. To that end, we'll start with an overview of what  `dep init` is doing. 
+The goal of this guide is to provide enough information for you to reason about what's happening during `dep init`, so that you can at least understand what class of problems you're encountering, and what steps you might take to address them. To that end, we'll start with an overview of what `dep init` is doing.
 
 > Note: the first run of `dep init` can take quite a long time, as dep is creating fresh clones of all your dependencies into a special location, `$GOPATH/pkg/dep/sources/`. This is necessary for dep's normal operations, and is largely a one-time cost.
 
@@ -21,10 +21,10 @@ The goal of this guide is to provide enough information for you to reason about
 
 When migrating existing projects, the primary goal of `dep init` is to automate as much of the work of creating a `Gopkg.toml` as possible. This is necessarily a heuristic goal, as dep may not have a 1:1 correspondence for everything you may have done before. As such, it's important to only expect that `dep init`'s automated migrations are operating on a best-effort basis.
 
-The behavior of  `dep init` varies depending on what's in your existing codebase, and the flags that are passed to it. However, it always proceeds in two phases:
+The behavior of `dep init` varies depending on what's in your existing codebase, and the flags that are passed to it. However, it always proceeds in two phases:
 
-1. *Inference phase:* Infer, from various sources, rules and hints about which versions of dependencies to use.
-2. *Solving phase:* Work out a solution that is acceptable under dep's model, while incorporating the above inferences as much as possible.
+1.  _Inference phase:_ Infer, from various sources, rules and hints about which versions of dependencies to use.
+2.  _Solving phase:_ Work out a solution that is acceptable under dep's model, while incorporating the above inferences as much as possible.
 
 ### The Inference Phase
 
@@ -35,9 +35,9 @@ The inference phase is where `dep init`'s behavior varies. By default, `dep init
 
 There are three circumstances that can lead dep not to make any tool-based inferences:
 
-- Your project doesn't use a package management tool
-- dep doesn't yet support the tool you use yet
-- You tell it not to, by running `dep init -skip-tools`
+* Your project doesn't use a package management tool
+* dep doesn't yet support the tool you use yet
+* You tell it not to, by running `dep init -skip-tools`
 
 After tool-based inference is complete, dep will normally proceed to the solving phase. However, if the user passes the `-gopath` flag, dep will first try to fill in any holes in the inferences drawn from tool metadata by checking the current project's containing GOPATH. Only hints are gleaned from GOPATH, and they will never supersede inferences from tool metadata. If you want to put GOPATH fully in charge, pass both flags: `dep init -skip-tools -gopath`.
 
@@ -45,7 +45,7 @@ Once dep has compiled its set of inferences, it proceeds to solving.
 
 ### The Solving Phase
 
-Once the inference phase is completed, the set of rules and hints dep has assembled will be passed to its [solver](solver.md) to work out a transitively complete depgraph, which will ultimately be recorded as the `Gopkg.lock`. This is the same solving process used by `dep ensure`, and completing it successfully means that dep has found a combination of dependency versions that respects all inferred rules, and as many inferred hints as possible. If solving succeeds, then the hard work is done; most of what remains is writing out `Gopkg.toml`, `Gopkg.lock`, and `vendor/`. 
+Once the inference phase is completed, the set of rules and hints dep has assembled will be passed to its [solver](solver.md) to work out a transitively complete depgraph, which will ultimately be recorded as the `Gopkg.lock`. This is the same solving process used by `dep ensure`, and completing it successfully means that dep has found a combination of dependency versions that respects all inferred rules, and as many inferred hints as possible. If solving succeeds, then the hard work is done; most of what remains is writing out `Gopkg.toml`, `Gopkg.lock`, and `vendor/`.
 
 The solver returns a solution, which itself is just [a representation](https://godoc.org/github.com/golang/dep/gps#Solution) of [the data stored in a `Gopkg.lock`](https://godoc.org/github.com/golang/dep#Lock): a transitively-complete, reproducible snapshot of the entire dependency graph. Writing out the `Gopkg.lock` from a solution is little more than a copy-and-encode operation, and writing `vendor/` is a matter of placing each project listed in the solution into its appropriate place, at the designated revision. This is exactly the same as `dep ensure`'s behavior.
 
@@ -65,12 +65,12 @@ While dep contributors have invested enormous effort into creating automated mig
 
 Because these are deep assumptions, their symptoms can be varied and surprising. Keeping these assumptions in mind could save you some hair-pulling later on.
 
-- dep does not allow nested `vendor/` directories; it flattens all dependencies to the topmost `vendor/` directory, at the root of your project. This is foundational to dep's model, and cannot be disabled.
-- dep wholly controls `vendor`, and will blow away any manual changes or additions made to it that deviate from the version of an upstream source dep selects.
-- dep requires that all packages from a given project/repository be at the same version.
-- dep generally does not care about what's on your GOPATH; it deals exclusively with projects sourced from remote network locations. (Hint inference is the only exception to this; once solving begins, GOPATH - and any custom changes you've made to code therein - is ignored.)
-- dep generally prefers semantic versioning-tagged releases to branches (when not given any additional rules). This is a significant shift from the "default branch" model of `go get` and some other tools. It can result in dep making surprising choices for dependencies for which it could not infer a rule.
-- dep assumes that all generated code exists, and has been committed to the source.
+* dep does not allow nested `vendor/` directories; it flattens all dependencies to the topmost `vendor/` directory, at the root of your project. This is foundational to dep's model, and cannot be disabled.
+* dep wholly controls `vendor`, and will blow away any manual changes or additions made to it that deviate from the version of an upstream source dep selects.
+* dep requires that all packages from a given project/repository be at the same version.
+* dep generally does not care about what's on your GOPATH; it deals exclusively with projects sourced from remote network locations. (Hint inference is the only exception to this; once solving begins, GOPATH - and any custom changes you've made to code therein - is ignored.)
+* dep generally prefers semantic versioning-tagged releases to branches (when not given any additional rules). This is a significant shift from the "default branch" model of `go get` and some other tools. It can result in dep making surprising choices for dependencies for which it could not infer a rule.
+* dep assumes that all generated code exists, and has been committed to the source.
 
 A small number of projects that have reported being unable, thus far, to find a reasonable way of adapting to these requirements. If you can't figure out how to make your project fit, please file an issue - while dep necessarily cannot accommodate every single existing approach, it is dep's goal is define rules to which all Go projects can reasonably adapt.
 
@@ -86,7 +86,7 @@ In the meantime, if the particular errors you are encountering do entail `Gopkg.
 
 ### Soft failures
 
-Soft failures are cases where `dep init` appears to exit cleanly, but a subsequent `go build` or `go test` fails. Dep's soft failures are usually more drastically than subtly wrong - e.g., an explosion of type errors when you try to build, because a wildly incorrect version for some dependency got selected. 
+Soft failures are cases where `dep init` appears to exit cleanly, but a subsequent `go build` or `go test` fails. Dep's soft failures are usually more drastically than subtly wrong - e.g., an explosion of type errors when you try to build, because a wildly incorrect version for some dependency got selected.
 
 If you do encounter problems like this, `dep status` is your first diagnostic step; it will report what versions were selected for all your dependencies. It may be clear which dependencies are a problem simply from your building or testing error messages. If not, compare the `dep status` list against the versions recorded by your previous tool to find the differences.
 
@@ -100,4 +100,4 @@ For each of the following items, assume that you should run `dep ensure` after m
 * If one of your direct dependencies is at the wrong version and there's no `[[constraint]]` on it in `Gopkg.toml` already, then define an appropriate one.
   * As with the transitive dependencies, if the version you need is a specific git commit, prefer doing that manually in `Gopkg.lock`.
 
-Hopefully this information is enough to get you through your project's migration to dep. If not, please feel free to file an issue, or join us in [#vendor on the Gopher's slack](https://gophers.slack.com/messages/C0M5YP9LN) for help!
+Hopefully this information is enough to get you through your project's migration to dep. If not, please feel free to file an issue, or join us in [#vendor on the Gopher's slack](https://gophers.slack.com/messages/C0M5YP9LN) for help!

docs/new-project.md

@@ -4,10 +4,10 @@ title: Creating a New Project
 
 Once you have [dep installed](installation.md), we need to pick a root directory for our project. This is primarily about picking the right root import path, and corresponding directory beneath `$GOPATH/src`, at which to situate your project. There are four basic possibilities:
 
-1. A project that is now or eventually may be shared with or imported by other projects/people. In this case, pick the import path corresponding to the VCS root of its intended network location, e.g., `$GOPATH/src/github.com/golang/dep`.
-2. An entirely local project - one that you have no intention of pushing to a central server (like GitHub). In this case, any subdirectory beneath `$GOPATH/src` will do.
-3. A project that needs to live within a large repository, such as a company monorepo. This may be possible, but gets more complicated. (Unfortunately, no docs on this yet - coming soon!)
-4. Treat the entire GOPATH as a single project, where `$GOPATH/src` is the root. dep [does not currently support this](https://github.com/golang/dep/issues/417) - it needs a non-empty import path to treat as the root of your project's import namespace.
+1.  A project that is now or eventually may be shared with or imported by other projects/people. In this case, pick the import path corresponding to the VCS root of its intended network location, e.g., `$GOPATH/src/github.com/golang/dep`.
+2.  An entirely local project - one that you have no intention of pushing to a central server (like GitHub). In this case, any subdirectory beneath `$GOPATH/src` will do.
+3.  A project that needs to live within a large repository, such as a company monorepo. This may be possible, but gets more complicated. (Unfortunately, no docs on this yet - coming soon!)
+4.  Treat the entire GOPATH as a single project, where `$GOPATH/src` is the root. Dep [does not currently support this](https://github.com/golang/dep/issues/417) - it needs a non-empty import path to treat as the root of your project's import namespace.
 
 We'll assume the first case, as it's the most common. Create and move into the directory:
 
@@ -34,4 +34,4 @@ At this point, our project is initialized, and we're ready to start writing code
 $ dep ensure -add github.com/foo/bar github.com/baz/quux
 ```
 
-Now you're ready to move on to [Daily Dep](daily-dep.md)!
+Now you're ready to move on to [Daily Dep](daily-dep.md)!

docs/the-solver.md

@@ -13,7 +13,7 @@ The solver guarantees certain invariants in every complete solution it returns.
 * All rules specified in activated `[[constraint]]` stanzas in both the current project and dependency projects will be satisfied, unless superseded by a `[[override]]` stanza in the current project.
 * For all import paths pointing into a given project, the version of the project selected will contain "valid" Go packages in the corresponding directory.
 * If an [import comment](https://golang.org/cmd/go/#hdr-Import_path_checking) is specified by a package, any import paths addressing that package will be of the form specified in the comment.
-* For any given import path, all instances of that import path will use the exact same casing. 
+* For any given import path, all instances of that import path will use the exact same casing.
 
 The solver is an iterative algorithm, working its way project-by-project through possible dependency graphs. In order to select a project, it must first prove that, to the best of its current knowledge, all of the above conditions are met. When the solver cannot find a solution, failure is defined in terms of a project's version's inability to meet one of the above criteria.
 
@@ -21,7 +21,7 @@ The solver is an iterative algorithm, working its way project-by-project through
 
 As described in the `Gopkg.toml` docs, each [`[[constraint]]`](Gopkg.toml.md#constraint) stanza is associated with a single project, and each stanza can contain both [a version rule](Gopkg.toml.md#version-rules) and a [source rule](Gopkg.toml.md#source). For any given project `P`, all dependers on `P` whose constraint rules are "activated" must express mutually compatible rules. That means:
 
-* For version rules, all activated constraints on `P` must [intersect](https://en.wikipedia.org/wiki/Intersection_(set_theory)), and and there must be at least one published version must exist in the intersecting space. Intersection varies depending on version rule type:
+* For version rules, all activated constraints on `P` must [intersect](<https://en.wikipedia.org/wiki/Intersection_(set_theory)>), and and there must be at least one published version must exist in the intersecting space. Intersection varies depending on version rule type:
   * For `revision` and `branch`, it must be a string-literal match.
   * For `version`, if the string is not a valid semantic version, then it must be a string-literal match.
   * For `version` that are valid semantic version ranges, intersection is standard set-theoretic intersection of the possible values in each range range. Semantic versions without ranges are treated as a single element set (e.g., `version = "=v1.0.0"`) for intersection purposes.
@@ -47,7 +47,7 @@ The reasoning behind this behavior is explained further [in this gist](https://g
 
 ### Package validity
 
-dep does only superficial validaton of code in packages, but it does do some. For a package to be considered valid, three things must be true:
+dep does only superficial validation of code in packages, but it does do some. For a package to be considered valid, three things must be true:
 
 * There must be at least one `.go` file.
 * No errors are reported from [`parser.ParseFile()`](https://golang.org/pkg/go/parser/#ParseFile) when called with [`parser.ImportsOnly|parser.ParseComments`](https://golang.org/pkg/go/parser/#Mode) on any file in the package directory.
@@ -81,4 +81,4 @@ The standard Go toolchain compiler [does not](https://github.com/golang/go/issue
 
 The solver keeps track of the accepted case variant for each import path it's processed. Any subsequent projects it sees that introduces a case-only variation for a known import path will be rejected.
 
-**Remediation:** Pick a casing variation (all lowercase is usually the right answer), and enforce it universally across the depgraph. As it has to be respected in all dependencies, as well, this may necessitate pull requests and possibly forking of dependencies, if you don't control them directly.
+**Remediation:** Pick a casing variation (all lowercase is usually the right answer), and enforce it universally across the depgraph. As it has to be respected in all dependencies, as well, this may necessitate pull requests and possibly forking of dependencies, if you don't control them directly.

gps/pkgtree/digest_test.go

@@ -148,7 +148,7 @@ func TestVerifyDepTree(t *testing.T) {
 		"github.com/bob/emptyDigest":   nil, // empty hash result
 		"github.com/bob/match":         {0x7e, 0x10, 0x6, 0x2f, 0x8, 0x3, 0x3c, 0x76, 0xae, 0xbc, 0xa4, 0xc9, 0xec, 0x73, 0x67, 0x15, 0x70, 0x2b, 0x0, 0x89, 0x27, 0xbb, 0x61, 0x9d, 0xc7, 0xc3, 0x39, 0x46, 0x3, 0x91, 0xb7, 0x3b},
 		"github.com/charlie/notInTree": nil, // not in tree result ought to superseede empty digest result
-		// matching result at seldomly found directory level
+		// matching result at seldom found directory level
 		"launchpad.net/match": {0x7e, 0x10, 0x6, 0x2f, 0x8, 0x3, 0x3c, 0x76, 0xae, 0xbc, 0xa4, 0xc9, 0xec, 0x73, 0x67, 0x15, 0x70, 0x2b, 0x0, 0x89, 0x27, 0xbb, 0x61, 0x9d, 0xc7, 0xc3, 0x39, 0x46, 0x3, 0x91, 0xb7, 0x3b},
 	}
 

gps/prune.go

@@ -245,7 +245,7 @@ func collectUnusedPackagesFiles(fsState filesystemState, unusedPackages map[stri
 	files := make([]string, 0, len(unusedPackages))
 
 	for _, path := range fsState.files {
-		// Keep perserved files.
+		// Keep preserved files.
 		if isPreservedFile(filepath.Base(path)) {
 			continue
 		}
@@ -295,7 +295,7 @@ func pruneNonGoFiles(fsState filesystemState) error {
 			continue
 		}
 
-		// Ignore perserved files.
+		// Ignore preserved files.
 		if isPreservedFile(filepath.Base(path)) {
 			continue
 		}

gps/prune_test.go

@@ -31,7 +31,7 @@ func TestCascadingPruneOptions(t *testing.T) {
 			},
 		},
 		{
-			name: "all overriden",
+			name: "all overridden",
 			co: CascadingPruneOptions{
 				DefaultOptions: PruneNestedVendorDirs,
 				PerProjectOptions: map[ProjectRoot]PruneOptionSet{