github.com/golang/dep@v0.5.4/docs/daily-dep.md (about) 1 --- 2 title: Daily Dep 3 --- 4 5 This guide is an introduction to the day-to-day use of dep. If you haven't set up a Go project at all yet, though, run through [Creating a New Project](new-project.md) first. 6 7 Dep is a tool you'll use regularly in the course of normal Go development. Regularly, but briefly - dependency management is never the place we want to be spending our time or energy! In keeping with Go's philosophy of minimizing knobs, dep has a sparse interface; there are only two commands you're likely to run regularly: 8 9 * `dep ensure` is the primary workhorse command, and is the only command that changes disk state. 10 * `dep status` reports on the state of your project, and the visible universe of Go software projects. 11 12 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!). 13 14 ## Basics 15 16 Let's start with words! 17 18 Dep's main command is `dep ensure`. The verb is "ensure" to imply that the action is not just some single, discrete action (like adding a dependency), but enforcing some kind of broader guarantee. If we wanted to express the `dep ensure` guarantee as a sentence, it would go something like this: 19 20 > "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." 21 22 As the narrative indicates, `dep ensure` is a holistic operation. Rather than offering a series of commands to run in succession that 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. 23 24 ## Using `dep ensure` 25 26 There are four times when you'll run `dep ensure`: 27 28 * To add a new dependency 29 * To update an existing dependency 30 * 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 31 * To catch up to a change to a rule in `Gopkg.toml` 32 33 If you're not sure if there have been changes to imports or `Gopkg.toml` rules, run `dep check`. It will tell you what is out of sync in your project. If anything is out of sync, running `dep ensure` will bring it back into line. 34 35 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). 36 37 ### Adding a new dependency 38 39 Let's say that we want to introduce a new dependency on `github.com/pkg/errors`. This can be accomplished with one command: 40 41 ```bash 42 $ dep ensure -add github.com/pkg/errors 43 ``` 44 45 > Much like git, `dep status` and `dep ensure` can also be run from any subdirectory of your project root (which is determined by the presence of a `Gopkg.toml` file). 46 47 This should succeed, resulting in an updated `Gopkg.lock` and `vendor/` directory, as well as injecting a best-guess version constraint for `github.com/pkg/errors` into our `Gopkg.toml`. But, it will also report a warning: 48 49 ```bash 50 "github.com/pkg/errors" is not imported by your project, and has been temporarily added to Gopkg.lock and vendor/. 51 If you run "dep ensure" again before actually importing it, it will disappear from Gopkg.lock and vendor/. 52 ``` 53 54 As the warning suggests, you should introduce an `import "github.com/pkg/errors"` in your code, the sooner the better. If you don't, a later `dep ensure` run will interpret your newly-added dependency as unused, and automatically remove it from `Gopkg.lock` and `vendor/`. This also means that if you want to add multiple dependencies at once, you'll need to do it in a single command, rather than one after the other: 55 56 ```bash 57 $ dep ensure -add github.com/pkg/errors github.com/foo/bar 58 ``` 59 60 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! 61 62 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. 63 64 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. 65 66 ### Updating dependencies 67 68 Ideally, updating a dependency project to a newer version is a single command: 69 70 ```bash 71 $ dep ensure -update github.com/foo/bar 72 ``` 73 74 This also works without arguments to try to update all dependencies (though it's generally not recommended): 75 76 ```bash 77 $ dep ensure -update 78 ``` 79 80 `dep ensure -update` searches for versions that work with the `branch`, `version`, or `revision` constraint defined in `Gopkg.toml`. These constraint types have different semantics, some of which allow `dep ensure -update` to effectively find a "newer" version, while others will necessitate hand-updating the `Gopkg.toml`. The [ensure mechanics](ensure-mechanics.md#update-and-constraint-types) guide explains this in greater detail, but if you want to know what effect a `dep ensure -update` is likely to have for a particular project, the `LATEST` field in `dep status` output will tell you. 81 82 ### Adding and removing `import` statements 83 84 As noted in [the section on adding dependencies](#adding-a-new-dependency), dep relies on the `import` statements in your code to figure out which dependencies your project actually needs. Thus, when you add or remove import statements, dep often needs to care about it. 85 86 Only if one of the following has occurred will a `dep ensure` be necessary to bring the project back in sync: 87 88 1. You've added the first `import` of a package, but already `import` other packages from that project. 89 2. You've removed the last `import` of a package, but still `import` other packages from that project. 90 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)) 91 4. You've removed the last `import` of a package from within a particular project. 92 93 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. `dep check` will quickly report any such issues, which will be resolved by running `dep ensure`. 94 95 ### Rule changes in `Gopkg.toml` 96 97 `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: 98 99 * `required`, which are mostly equivalent to `import` statements in `.go` files, except that it's OK to list a `main` package here 100 * `ignored`, which causes dep to black hole an import path (and any imports it uniquely introduces) 101 * `[[constraint]]`, stanzas that express version constraints and some other rules on a per-project dependency basis 102 * `[[override]]`, stanzas identical to `[[constraint]]` except that only the current project can express them and they supersede `[[constraint]]` in both the current project and dependencies 103 * `[prune]`, global and per-project rules that govern what kinds of files should be removed from `vendor/` 104 105 Changes to any one of these rules will likely necessitate changes in `Gopkg.lock` and `vendor/`; a single successful `dep ensure` run will incorporate all such changes at once, bringing your project back in sync. 106 107 ## Visualizing dependencies 108 109 Generate a visual representation of the dependency tree by piping the output of `dep status -dot` to [graphviz](http://www.graphviz.org/). 110 111 ### Linux 112 113 ``` 114 $ sudo apt-get install graphviz 115 $ dep status -dot | dot -T png | display 116 ``` 117 118 ### macOS 119 120 ``` 121 $ brew install graphviz 122 $ dep status -dot | dot -T png | open -f -a /Applications/Preview.app 123 ``` 124 125 ### Windows 126 127 ``` 128 > choco install graphviz.portable 129 > dep status -dot | dot -T png -o status.png; start status.png 130 ``` 131 132  133 134 ## Key Takeaways 135 136 Here are the key takeaways from this guide: 137 138 * `dep check` will quickly report any ways in which your project is out of [sync](glossary.md#sync). 139 * `dep ensure -update` is the preferred way to update dependencies, though it's less effective for projects that don't publish semver releases. 140 * `dep ensure -add` is usually the easiest way to introduce new dependencies, though you can also just add new `import` statements then run `dep ensure`. 141 * If you ever make a manual change in `Gopkg.toml`, it's best to run `dep ensure` to make sure everything's in sync. 142 * `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. 143 144 Also, a couple other miscellaneous tidbits: 145 146 * 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. 147 * 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.