github.com/golang/dep@v0.5.4/docs/FAQ.md (about)

     1  ---
     2  title: FAQ
     3  ---
     4  
     5  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!
     6  
     7  ## Concepts
     8  
     9  * [Does `dep` replace `go get`?](#does-dep-replace-go-get)
    10  * [Why is it `dep ensure` instead of `dep install`?](#why-is-it-dep-ensure-instead-of-dep-install)
    11  * [What is a direct or transitive dependency?](#what-is-a-direct-or-transitive-dependency)
    12  
    13  ## Configuration
    14  
    15  * [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)
    16  * [How do I constrain a transitive dependency's version?](#how-do-i-constrain-a-transitive-dependency-s-version)
    17  * [How do I change the version of a dependency?](#how-do-i-change-the-version-of-a-dependency)
    18  * [Can I put the manifest and lock in the vendor directory?](#can-i-put-the-manifest-and-lock-in-the-vendor-directory)
    19  * [How do I get `dep` to authenticate to a `git` repo?](#how-do-i-get-dep-to-authenticate-to-a-git-repo)
    20  * [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)
    21  
    22  ## Behavior
    23  
    24  * [How does `dep` decide what version of a dependency to use?](#how-does-dep-decide-what-version-of-a-dependency-to-use)
    25  * [What is the default `dep ensure -update` behavior for dependencies that are imported but not included as a `[[Constraint]]` in `Gopkg.toml`?](#what-is-the-default-dep-ensure--update-behavior-for-dependencies-that-are-imported-but-not-included-as-a-constraint-in-gopkgtoml)
    26  * [What external tools are supported?](#what-external-tools-are-supported)
    27  * [Why is `dep` ignoring a version constraint in the manifest?](#why-is-dep-ignoring-a-version-constraint-in-the-manifest)
    28  * [Why did `dep` use a different revision for package X instead of the revision in the lock file?](#why-did-dep-use-a-different-revision-for-package-x-instead-of-the-revision-in-the-lock-file)
    29  * [Why is `dep` slow?](#why-is-dep-slow)
    30  * [How does `dep` handle symbolic links?](#how-does-dep-handle-symbolic-links)
    31  * [Does `dep` support relative imports?](#does-dep-support-relative-imports)
    32  * [How do I make `dep` resolve dependencies from my `GOPATH`?](#how-do-i-make-dep-resolve-dependencies-from-my-gopath)
    33  * [Will `dep` let me use git submodules to store dependencies in `vendor`?](#will-dep-let-me-use-git-submodules-to-store-dependencies-in-vendor)
    34  * [How does `dep` work without changing my packages imports?](#how-does-dep-work-without-changing-my-packages-imports)
    35  
    36  ## Best Practices
    37  
    38  * [Should I commit my vendor directory?](#should-i-commit-my-vendor-directory)
    39  * [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  * [What semver version should I use?](#what-semver-version-should-i-use)
    41  * [Is it OK to make backwards-incompatible changes now?](#is-it-ok-to-make-backwards-incompatible-changes-now)
    42  * [My dependers don't use `dep` yet. What should I do?](#my-dependers-don-t-use-dep-yet-what-should-i-do)
    43  * [How do I configure a dependency that doesn't tag its release](#how-do-i-configure-a-dependency-that-doesn-t-tag-its-releases)
    44  * [How do I use `dep` with Docker?](#how-do-i-use-dep-with-docker)
    45  * [How do I use `dep` in CI?](#how-do-i-use-dep-in-ci)
    46  
    47  ## Concepts
    48  
    49  ### Does `dep` replace `go get`?
    50  
    51  No. `dep` and `go get` serve mostly different purposes.
    52  
    53  Here are some suggestions for when you could use `dep` or `go get`:
    54  
    55  > I would say that dep doesn't replace go get, but they both can do similar things. Here's how I use them:
    56  >
    57  > `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.
    58  >
    59  > `dep ensure`: I have imported a new dependency in my code and want to download the dependency so I can start using it. My workflow is "add the import to the code, and then run dep ensure so that the manifest/lock/vendor are updated". This clones the repo under my project's vendor directory, and remembers the revision used so that everyone who works on my project is guaranteed to be using the same version of dependencies.
    60  >
    61  > [@carolynvs in #376](https://github.com/golang/dep/issues/376#issuecomment-293964655)
    62  
    63  > The long term vision is a sane, overall-consistent go tool. My general take is that `go get`
    64  > is for people consuming Go code, and dep-family commands are for people developing it.
    65  >
    66  > [@sdboyer in #376](https://github.com/golang/dep/issues/376#issuecomment-294045873)
    67  
    68  ### Why is it `dep ensure` instead of `dep install`?
    69  
    70  > Yeah, we went round and round on names. [A lot](https://gist.github.com/jessfraz/315db91b272441f510e81e449f675a8b).
    71  >
    72  > The idea of "ensure" is roughly, "ensure that all my local states - code tree, manifest, lock, and vendor - are in sync with each other." When arguments are passed, it becomes "ensure this argument is satisfied, along with synchronization between all my local states."
    73  >
    74  > We opted for this approach because we came to the conclusion that allowing the tool to perform partial work/exit in intermediate states ended up creating a tool that had more commands, had far more possible valid exit and input states, and was generally full of footguns. In this approach, the user has most of the same ultimate control, but exercises it differently (by modifying the code/manifest and re-running dep ensure).
    75  >
    76  > [@sdboyer in #371](https://github.com/golang/dep/issues/371#issuecomment-293246832)
    77  
    78  ### What is a direct or transitive dependency?
    79  
    80  * Direct dependencies are dependencies that are imported directly by your project: they appear in at least one import statement from your project.
    81  * Transitive dependencies are the dependencies of your dependencies. Necessary to compile but are not directly used by your code.
    82  
    83  ## Configuration
    84  
    85  ### What is the difference between `Gopkg.toml` (the "manifest") and `Gopkg.lock` (the "lock")?
    86  
    87  > 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.
    88  >
    89  > This flexibility is important because it allows us to provide easy commands (e.g. `dep ensure -update`) that can manage an update process for you, within the constraints you specify, AND because it allows your project, when imported by someone else, to collaboratively specify the constraints for your own dependencies.
    90  >
    91  > [@sdboyer in #281](https://github.com/golang/dep/issues/281#issuecomment-284118314)
    92  
    93  ## <a id="how-do-i-constrain-a-transitive-dependency-s-version"></a>How do I constrain a transitive dependency's version?
    94  
    95  First, if you're wondering about this because you're trying to keep the version
    96  of the transitive dependency from changing, then you're working against `dep`'s
    97  design. The lock file, `Gopkg.lock`, will keep the selected version of the
    98  transitive dependency stable, unless you explicitly request an upgrade or it's
    99  impossible to find a solution without changing that version.
   100  
   101  If that isn't your use case and you still need to constrain a transitive
   102  dependency, you have a couple of options:
   103  
   104  1.  Make the transitive dependency a direct one, either with a dummy import or an entry in the `required` list in `Gopkg.toml`.
   105  2.  Use an override.
   106  
   107  Overrides are a sledgehammer, and should only be used as a last resort. While
   108  constraints and overrides are declared in the same way in `Gopkg.toml`, they
   109  behave differently:
   110  
   111  * Constraints:
   112    1.  Can be declared by any project's manifest, yours or a dependency
   113    2.  Apply only to direct dependencies of the project declaring the constraint
   114    3.  Must not conflict with the `constraint` entries declared in any other project's manifest
   115  * Overrides:
   116    1.  Are only utilized from the current/your project's manifest
   117    2.  Apply globally, to direct and transitive dependencies
   118    3.  Supersede constraints declared in all manifests, yours or a dependency's
   119  
   120  Overrides are also discussed with some visuals in [the gps docs](https://github.com/sdboyer/gps/wiki/gps-for-Implementors#overrides).
   121  
   122  ## How do I change the version of a dependency
   123  
   124  If you want to:
   125  
   126  * Change the allowed `version`/`branch`/`revision`
   127  * Switch to using a fork
   128  
   129  for one or more dependencies, do the following:
   130  
   131  1.  Manually edit your `Gopkg.toml`.
   132  1.  Run
   133  
   134      ```sh
   135      $ dep ensure
   136      ```
   137  
   138  ## Can I put the manifest and lock in the vendor directory?
   139  
   140  No.
   141  
   142  > Placing these files inside `vendor/` would concretely bind us to `vendor/` in the long term.
   143  > We prefer to treat the `vendor/` as an implementation detail.
   144  >
   145  > [@sdboyer on go package management list](https://groups.google.com/d/msg/go-package-management/et1qFUjrkP4/LQFCHP4WBQAJ)
   146  
   147  ## How do I get dep to authenticate to a git repo?
   148  
   149  `dep` currently uses the `git` command under the hood, so configuring the credentials
   150  for each repository you wish to authenticate to will allow `dep` to use an
   151  authenticated repository.
   152  
   153  First, configure `git` to use the credentials option for the specific repository.
   154  
   155  For example, if you use GitLab, and you wish to access `https://gitlab.example.com/example/package.git`,
   156  then you would want to use the following configuration:
   157  
   158  ```
   159  $ git config --global credential.https://gitlab.example.com.example yourusername
   160  ```
   161  
   162  In the example the hostname `gitlab.example.com.example` string seems incorrect, but
   163  it's actually the hostname plus the name of the repo you are accessing which is `username`.
   164  The trailing 'yourusername' is the username you would use for the actual authentication.
   165  
   166  You also need to configure `git` with the authentication provider you wish to use. You can get
   167  a list of providers, with the command:
   168  
   169  ```
   170  $ git help -a | grep credential-
   171    credential-cache          remote-fd
   172    credential-cache--daemon  remote-ftp
   173    credential-osxkeychain    remote-ftps
   174    credential-store          remote-http
   175  ```
   176  
   177  You would then choose an appropriate provider. For example, to use the osxkeychain, you
   178  would use the following:
   179  
   180  ```
   181  git config --global credential.helper osxkeychain
   182  ```
   183  
   184  If you need to do this for a CI system, then you may want to use the "store" provider.
   185  Please see the documentation on how to configure that: https://git-scm.com/docs/git-credential-store
   186  
   187  After configuring `git`, you may need to use `git` manually once to have it store the
   188  credentials. Once you've checked out the repo manually, it will then use the stored
   189  credentials. This at least appears to be the behavior for the osxkeychain provider.
   190  
   191  ### How do I get dep to consume private git repos using a GitHub Token?
   192  
   193  Another alternative to make `dep` work with private repos is to use a [Personal GitHub
   194  Token](https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line/)
   195  and configure it inside the [`.netrc` file](https://www.gnu.org/software/inetutils/manual/html_node/The-_002enetrc-file.html)
   196  as the following example:
   197  
   198  ```
   199  machine github.com
   200      login [YOUR_GITHUB_USERNAME]
   201      password [YOUR_GITHUB_TOKEN]
   202  ```
   203  
   204  Once you have set that up, dep will automatically use that Token to authenticate to the repositories.
   205  
   206  ## How do I get dep to authenticate via SSH to a git repo?
   207  
   208  You can rewrite the repo url and use the git+ssh shema with follow example:
   209  
   210  ```
   211  git config --global url."git@github.yourEnterprise.com:".insteadOf "https://github.yourEnterprise.com/"
   212  
   213  ```
   214  
   215  
   216  ## Behavior
   217  
   218  ### How does `dep` decide what version of a dependency to use?
   219  
   220  The full algorithm is complex, but the most important thing to understand is
   221  that `dep` tries versions in a [certain
   222  order](https://godoc.org/github.com/golang/dep/gps#SortForUpgrade),
   223  checking to see a version is acceptable according to specified constraints.
   224  
   225  * All semver versions come first, and sort mostly according to the semver 2.0
   226    spec, with one exception:
   227    * Semver versions with a prerelease are sorted after _all_ non-prerelease
   228      semver. Within this subset they are sorted first by their numerical
   229      component, then lexicographically by their prerelease version.
   230  * The default branch(es) are next; the semantics of what "default branch" means
   231    are specific to the underlying source type, but this is generally what you'd
   232    get from a `go get`.
   233  * All other branches come next, sorted lexicographically.
   234  * All non-semver versions (tags) are next, sorted lexicographically.
   235  * Revisions, if any, are last, sorted lexicographically. Revisions do not
   236    typically appear in version lists, so the only invariant we maintain is
   237    determinism - deeper semantics, like chronology or topology, do not matter.
   238  
   239  So, given a slice of the following versions:
   240  
   241  * Branch: `master` `devel`
   242  * Semver tags: `v1.0.0` `v1.1.0` `v1.1.0-alpha1`
   243  * Non-semver tags: `footag`
   244  * Revision: `f6e74e8d`
   245  
   246  Sorting for upgrade will result in the following slice:
   247  
   248  `[v1.1.0 v1.0.0 v1.1.0-alpha1 master devel footag f6e74e8d]`
   249  
   250  There are a number of factors that can eliminate a version from consideration,
   251  the simplest of which is that it doesn't match a constraint. But if you're
   252  trying to figure out why `dep` is doing what it does, understanding that its
   253  basic action is to attempt versions in this order should help you to reason
   254  about what's going on.
   255  
   256  ## What is the default `dep ensure -update` behavior for dependencies that are imported but not included as a `[[Constraint]]` in `Gopkg.toml`?
   257  `dep` updates the dependency to the latest semver tag. If there are no semver tags, `dep` uses the tip of master.
   258  
   259  ## What external tools are supported?
   260  
   261  During `dep init` configuration from other dependency managers is detected
   262  and imported, unless `-skip-tools` is specified.
   263  
   264  The following tools are supported: `glide`, `godep`, `vndr`, `govend`, `gb`, `gvt`, `govendor` and `glock`.
   265  
   266  See [#186](https://github.com/golang/dep/issues/186#issuecomment-306363441) for
   267  how to add support for another tool.
   268  
   269  ## Why is `dep` ignoring a version constraint in the manifest?
   270  
   271  Only your project's directly imported dependencies are affected by a `constraint` entry
   272  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)?
   273  
   274  ## Why did `dep` use a different revision for package X instead of the revision in the lock file?
   275  
   276  Sometimes the revision specified in the lock file is no longer valid. There are a few
   277  ways this can occur:
   278  
   279  * When you generated the lock file, you had an unpushed commit in your local copy of package X's repository in your `GOPATH`. (This case will be going away soon)
   280  * After generating the lock file, new commits were force pushed to package X's repository, causing the commit revision in your lock file to no longer exist.
   281  
   282  To troubleshoot, you can revert dep's changes to your lock, and then run `dep ensure -v -n`.
   283  This retries the command in dry-run mode with verbose logs enabled. Check the output
   284  for a warning like the one below, indicating that a commit in the lock is no longer valid.
   285  
   286  ```
   287  Unable to update checked out version: fatal: reference is not a tree: 4dfc6a8a7e15229398c0a018b6d7a078cccae9c8
   288  ```
   289  
   290  > The lock file represents a set of precise, typically immutable versions for the entire transitive closure of dependencies for a project. But "the project" can be, and is, decomposed into just a bunch of arguments to an algorithm. When those inputs change, the lock may need to change as well.
   291  >
   292  > Under most circumstances, if those arguments don't change, then the lock remains fine and correct. You've hit one of the few cases where that guarantee doesn't apply. The fact that you ran dep ensure and it DID a solve is a product of some arguments changing; that solving failed because this particular commit had become stale is a separate problem.
   293  >
   294  > [@sdboyer in #405](https://github.com/golang/dep/issues/405#issuecomment-295998489)
   295  
   296  ## Why is `dep` slow?
   297  
   298  There are two things that really slow `dep` down. One is unavoidable; for the other, we have a plan.
   299  
   300  The unavoidable part is the initial clone. `dep` relies on a cache of local
   301  repositories (stored under `$GOPATH/pkg/dep`), which is populated on demand.
   302  Unfortunately, the first `dep` run, especially for a large project, may take a
   303  while, as all dependencies are cloned into the cache.
   304  
   305  Fortunately, this is just an _initial_ clone - pay it once, and you're done.
   306  The problem repeats itself a bit when you're running `dep` for the first time
   307  in a while and there's new changesets to fetch, but even then, these costs are
   308  only paid once per changeset.
   309  
   310  The other part is the work of retrieving information about dependencies. There are three parts to this:
   311  
   312  1.  Getting an up-to-date list of versions from the upstream source
   313  2.  Reading the `Gopkg.toml` for a particular version out of the local cache
   314  3.  Parsing the tree of packages for import statements at a particular version
   315  
   316  The first requires one or more network calls; the second two usually mean
   317  something like a `git checkout`, and the third is a filesystem walk, plus
   318  loading and parsing `.go` files. All of these are expensive operations.
   319  
   320  Fortunately, we can cache the second and third. And that cache can be permanent
   321  when keyed on an immutable identifier for the version - like a git commit SHA1
   322  hash. The first is a bit trickier, but there are reasonable staleness tradeoffs
   323  we can consider to avoid the network entirely. There's an issue to [implement
   324  persistent caching](https://github.com/golang/dep/issues/431) that's the
   325  gateway to all of these improvements.
   326  
   327  There's another major performance issue that's much harder - the process of picking versions itself is an NP-complete problem in `dep`'s current design. This is a much trickier problem 😜
   328  
   329  ## How does `dep` handle symbolic links?
   330  
   331  > 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)
   332  
   333  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`.
   334  
   335  When `dep` is invoked with a project root that is a symlink, it will be resolved according to the following rules:
   336  
   337  * 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`.
   338  * If the symlink is within a `GOPATH` and the resolved path is within a _different_ `GOPATH`, then an error is thrown.
   339  * If both the symlink and the resolved path are in the same `GOPATH`, then an error is thrown.
   340  * If neither the symlink nor the resolved path are in a `GOPATH`, then an error is thrown.
   341  
   342  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.
   343  
   344  ## Does `dep` support relative imports?
   345  
   346  No.
   347  
   348  > 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:
   349  >
   350  > * the toolchain already frowns heavily on them<br>
   351  > * it's worse for our case, as we start venturing into [dot dot hell](http://doc.cat-v.org/plan_9/4th_edition/papers/lexnames) territory when trying to prove that the import does not escape the tree of the project
   352  >
   353  > [@sdboyer in #899](https://github.com/golang/dep/issues/899#issuecomment-317904001)
   354  
   355  For a refresher on Go's recommended workspace organization, see the ["How To Write Go Code"](https://golang.org/doc/code.html) article in the Go docs. Organizing your code this way gives you a unique import path for every package.
   356  
   357  ## How do I make `dep` resolve dependencies from my `GOPATH`?
   358  
   359  `dep init` provides an option to scan the `GOPATH` for dependencies by doing
   360  `dep init -gopath`, which falls back to network mode when the packages are not
   361  found in `GOPATH`. `dep ensure` doesn't work with projects in `GOPATH`.
   362  
   363  ## Will `dep` let me use git submodules to store dependencies in `vendor`?
   364  
   365  No, with just one tiny exception: `dep` preserves `/vendor/.git`, if it exists. This was added at [cockroachdb](https://github.com/cockroachdb/cockroach)'s request, who rely on it to keep `vendor` from bloating their primary repository.
   366  
   367  The reasons why git submodules will not be a part of dep are best expressed as a pro/con list:
   368  
   369  **Pros**
   370  
   371  * git submodules provide a well-structured way of nesting repositories within repositories.
   372  
   373  **Cons**
   374  
   375  * The nesting that git submodules perform is no more powerful or expressive than what dep already does, but dep does it both more generally (for bzr and hg) and more domain-specifically (e.g. elimination of nested vendor directories).
   376  * Incorporating git submodules in any way would new fork new paths in the logic to handle the submodule cases, meaning nontrivial complexity increases.
   377  * dep does not currently know or care if the project it operates on is under version control. Relying on submodules would entail that dep start paying attention to that. That it would only be conditionally does not make it better - again, more forking paths in the logic, more complexity.
   378  * Incorporating submodules in a way that is at all visible to the user (and why else would you do it?) makes dep's workflows both more complicated and less predictable: _sometimes_ submodule-related actions are expected; _sometimes_ submodule-derived workflows are sufficient.
   379  * 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.
   380  
   381  ## How does `dep` work without changing my packages imports?
   382  
   383  `dep` doesn't require imports (or the `$GOPATH`) to be updated because [go has native support for a vendor directory since version 1.5](https://golang.org/cmd/go/#hdr-Vendor_Directories). You do not need to update import paths to be relative. For instance, `import github.com/user/awesome-project` will be found in the project's `/vendor/github.com/user/awesome-project` before looking to `$GOPATH/src/github.com/user/awesome-project`.
   384  
   385  ## Best Practices
   386  
   387  ### Should I commit my vendor directory?
   388  
   389  It's up to you:
   390  
   391  **Pros**
   392  
   393  * It's the only way to get truly reproducible builds, as it guards against upstream renames,
   394    deletes and commit history overwrites.
   395  * You don't need an extra `dep ensure` step to sync `vendor/` with `Gopkg.lock` after most operations,
   396    such as `go get`, cloning, getting latest, merging, etc.
   397  
   398  **Cons**
   399  
   400  * Your repo will be bigger, potentially a lot bigger,
   401    though [`prune`](Gopkg.toml.md#prune) can help minimize this problem.
   402  * PR diffs will include changes for files under `vendor/` when `Gopkg.lock` is modified,
   403    however files in `vendor/` are [hidden by default](https://github.com/github/linguist/blob/v5.2.0/lib/linguist/generated.rb#L328) on GitHub.
   404  
   405  ## How do I roll releases that `dep` will be able to use?
   406  
   407  In short: make sure you've committed your `Gopkg.toml` and `Gopkg.lock`, then
   408  just create a tag in your version control system and push it to the canonical
   409  location. `dep` is designed to work automatically with this sort of metadata
   410  from `git`, `bzr`, and `hg`.
   411  
   412  It's strongly preferred that you use [semver](http://semver.org)-compliant tag
   413  names. We hope to develop documentation soon that describes this more precisely,
   414  but in the meantime, the [npm](https://docs.npmjs.com/misc/semver) docs match
   415  our patterns pretty well.
   416  
   417  ## What semver version should I use?
   418  
   419  This can be a nuanced question, and the community is going to have to work out
   420  some accepted standards for how semver should be applied to Go projects. At the
   421  highest level, though, these are the rules:
   422  
   423  * Below `v1.0.0`, anything goes. Use these releases to figure out what you want
   424    your API to be.
   425  * Above `v1.0.0`, the general Go best practices continue to apply - don't make
   426    backwards-incompatible changes - exported identifiers can be added to, but
   427    not changed or removed.
   428  * If you must make a backwards-incompatible change, then bump the major version.
   429  
   430  It's important to note that having a `v1.0.0` does not preclude you from having
   431  alpha/beta/etc releases. The semver spec allows for [prerelease
   432  versions](http://semver.org/#spec-item-9), and `dep` is careful to _not_ allow
   433  such versions unless `Gopkg.toml` contains a range constraint that explicitly
   434  includes prereleases: if there exists a version `v1.0.1-alpha4`, then the
   435  constraint `>=1.0.0` will not match it, but `>=1.0.1-alpha1` will.
   436  
   437  Some work has been done towards [a tool
   438  to](https://github.com/bradleyfalzon/apicompat) that will analyze and compare
   439  your code with the last release, and suggest the next version you should use.
   440  
   441  ## Is it OK to make backwards-incompatible changes now?
   442  
   443  Yes. But.
   444  
   445  `dep` will make it possible for the Go ecosystem to handle
   446  backwards-incompatible changes more gracefully. However, `dep` is not some
   447  magical panacea. Version and dependency management is hard, and dependency hell
   448  is real. The longstanding community wisdom about avoiding breaking changes
   449  remains important. Any `v1.0.0` release should be accompanied by a plan for how
   450  to avoid future breaking API changes.
   451  
   452  One good strategy may be to add to your API instead of changing it, deprecating
   453  old versions as you progress. Then, when the time is right, you can roll a new
   454  major version and clean out a bunch of deprecated symbols all at once.
   455  
   456  Note that providing an incremental migration path across breaking changes (i.e.,
   457  shims) is tricky, and something we [don't have a good answer for
   458  yet](https://groups.google.com/forum/#!topic/go-package-management/fp2uBMf6kq4).
   459  
   460  ## <a id="my-dependers-don-t-use-dep-yet-what-should-i-do"></a>My dependers don't use `dep` yet. What should I do?
   461  
   462  For the most part, you needn't do anything differently.
   463  
   464  The only possible issue is if your project is ever consumed as a library. If
   465  so, then you may want to be wary about committing your `vendor/` directory, as
   466  it can [cause
   467  problems](https://groups.google.com/d/msg/golang-nuts/AnMr9NL6dtc/UnyUUKcMCAAJ).
   468  If your dependers are using `dep`, this is not a concern, as `dep` takes care of
   469  stripping out nested `vendor` directories.
   470  
   471  ## <a id="how-do-i-configure-a-dependency-that-doesn-t-tag-its-releases"></a>How do I configure a dependency that doesn't tag its releases?
   472  
   473  Add a constraint to `Gopkg.toml` that specifies `branch: "master"` (or whichever branch you need) in the `[[constraint]]` for that dependency. `dep ensure` will determine the current revision of your dependency's master branch, and place it in `Gopkg.lock` for you. See also: [What is the difference between Gopkg.toml and Gopkg.lock?](#what-is-the-difference-between-gopkgtoml-the-manifest-and-gopkglock-the-lock)
   474  
   475  ## How do I use `dep` with Docker?
   476  
   477  `dep ensure -vendor-only` creates the vendor folder from a valid `Gopkg.toml` and `Gopkg.lock` without checking for Go code.
   478  This is especially useful for builds inside docker utilizing cache layers.
   479  
   480  Sample Dockerfile:
   481  
   482  ```Dockerfile
   483  FROM golang:1.9 AS builder
   484  
   485  RUN curl -fsSL -o /usr/local/bin/dep https://github.com/golang/dep/releases/download/vX.X.X/dep-linux-amd64 && chmod +x /usr/local/bin/dep
   486  
   487  RUN mkdir -p /go/src/github.com/***
   488  WORKDIR /go/src/github.com/***
   489  
   490  COPY Gopkg.toml Gopkg.lock ./
   491  # copies the Gopkg.toml and Gopkg.lock to WORKDIR
   492  
   493  RUN dep ensure -vendor-only
   494  # install the dependencies without checking for go code
   495  
   496  ...
   497  ```
   498  
   499  ## How do I use `dep` in CI?
   500  
   501  Since `dep` is expected to change until `v1.0.0` is released, it is recommended to rely on a released version.
   502  You can find the latest binary from the [releases](https://github.com/golang/dep/releases) page.
   503  
   504  Sample configuration for Travis CI:
   505  
   506  ```yml
   507  # ...
   508  
   509  env:
   510    - DEP_VERSION="X.X.X"
   511  
   512  before_install:
   513    # Download the binary to bin folder in $GOPATH
   514    - curl -L -s https://github.com/golang/dep/releases/download/v${DEP_VERSION}/dep-linux-amd64 -o $GOPATH/bin/dep
   515    # Make the binary executable
   516    - chmod +x $GOPATH/bin/dep
   517  
   518  install:
   519    - dep ensure
   520  ```
   521  
   522  Caching can also be enabled but there are a couple of caveats you should be aware of:
   523  
   524  > Until recently, we have had intermittent cache corruption that would have been super annoying if it was breaking Travis build too.
   525  >
   526  > Also according to https://docs.travis-ci.com/user/caching/#Things-not-to-cache, they don't recommend it for larger caches.
   527  >
   528  > https://docs.travis-ci.com/user/caching/#How-does-the-caching-work%3F
   529  >
   530  > > Note that this makes our cache not network-local, it's still bound to network bandwidth and DNS resolutions for S3.
   531  > > That impacts what you can and should store in the cache. If you store archives larger than a few hundred megabytes in the cache, it's unlikely that you'll see a big speed improvement.
   532  >
   533  > [@carolynvs in #1293](https://github.com/golang/dep/pull/1293#issuecomment-342969292)
   534  
   535  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:
   536  
   537  ```yml
   538  # ...
   539  
   540  cache:
   541    directories:
   542      - $GOPATH/pkg/dep
   543  ```