gopkg.in/tools/godep.v54@v54.0.0-20160222173036-53bf4cf4341d/Readme.md (about) 1 ## Godep 2 3 [![Build Status](https://travis-ci.org/tools/godep.svg)](https://travis-ci.org/tools/godep) 4 5 [![GoDoc](https://godoc.org/github.com/tools/godep?status.svg)](https://godoc.org/github.com/tools/godep) 6 7 godep helps build packages reproducibly by fixing their dependencies. 8 9 This tool assumes you are working in a standard Go workspace, as described in 10 http://golang.org/doc/code.html. We expect godep to build on Go 1.4* or newer, 11 but you can use it on any project that works with Go 1 or newer. 12 13 ## Install 14 15 ```console 16 $ go get github.com/tools/godep 17 ``` 18 19 ## How to use godep with a new project 20 21 Assuming you've got everything working already, so you can build your project 22 with `go install` and test it with `go test`, it's one command to start using: 23 24 ```console 25 $ godep save -r 26 ``` 27 28 This will save a list of dependencies to the file `Godeps/Godeps.json`, copy 29 their source code into `Godeps/_workspace` and rewrite the dependencies. Godep 30 does **not copy**: 31 32 - files from source repositories that are not tracked in version control. 33 - `*_test.go` files. 34 - `testdata` directories. 35 36 Read over the contents of `Godeps/_workspace` and make sure it looks 37 reasonable. Then commit the whole Godeps directory to version control, 38 **including `Godeps/_workspace`**. 39 40 The additional flag `-r` tells save to automatically rewrite package import 41 paths. This allows your code to refer directly to the copied dependencies in 42 `Godeps/_workspace`. So, a package C that depends on package D will actually 43 import `C/Godeps/_workspace/src/D`. This makes C's repo self-contained and 44 causes `go get` to build C with the right version of all dependencies. 45 46 If you don't use `-r`, then in order to use the fixed dependencies and get 47 reproducible builds, you must make sure that **every time** you run a Go-related 48 command, you wrap it in one of these two ways: 49 50 - If the command you are running is just `go`, run it as `godep go ...`, e.g. 51 `godep go install -v ./...` 52 - When using a different command, set your `$GOPATH` using `godep path` as 53 described below. 54 55 Godep does not process the imports of `.go` files with either the `ignore` 56 or `appengine` build tags. 57 58 Test files and testdata directories can be saved by adding `-t`. 59 60 ## Additional Operations 61 62 ### Restore 63 64 The `godep restore` command is the opposite of `godep save`. It will install the 65 package versions specified in `Godeps/Godeps.json` to your `$GOPATH`. This modifies the state of packages in your `$GOPATH`. 66 67 ### Edit-test Cycle 68 69 1. Edit code 70 1. Run `godep go test` 71 1. (repeat) 72 73 ### Add a Dependency 74 75 To add a new package foo/bar, do this: 76 77 1. Run `go get foo/bar` 78 1. Edit your code to import foo/bar. 79 1. Run `godep save` (or `godep save ./...`). 80 81 ### Update a Dependency 82 83 To update a package from your `$GOPATH`, do this: 84 85 1. Run `go get -u foo/bar` 86 1. Run `godep update foo/bar`. (You can use the `...` wildcard, for example 87 `godep update foo/...`). 88 89 Before comitting the change, you'll probably want to inspect the changes to 90 Godeps, for example with `git diff`, and make sure it looks reasonable. 91 92 ## Multiple Packages 93 94 If your repository has more than one package, you're probably accustomed to 95 running commands like `go test ./...`, `go install ./...`, and `go fmt ./...`. 96 Similarly, you should run `godep save ./...` to capture the dependencies of all 97 packages. 98 99 ## Using Other Tools 100 101 The `godep path` command helps integrate with commands other than the standard 102 go tool. This works with any tool that reads GOPATH from its environment, for 103 example the recently-released [oracle 104 command](http://godoc.org/code.google.com/p/go.tools/cmd/oracle). 105 106 $ GOPATH=`godep path`:$GOPATH 107 $ oracle -mode=implements . 108 109 ## Old Format 110 111 Old versions of godep wrote the dependency list to a file Godeps, and didn't 112 copy source code. This mode no longer exists, but commands 'godep go' and 'godep 113 path' will continue to read the old format for some time. 114 115 ## File Format 116 117 Godeps is a json file with the following structure: 118 119 ```go 120 type Godeps struct { 121 ImportPath string 122 GoVersion string // Abridged output of 'go version'. 123 Packages []string // Arguments to godep save, if any. 124 Deps []struct { 125 ImportPath string 126 Comment string // Description of commit, if present. 127 Rev string // VCS-specific commit ID. 128 } 129 } 130 ``` 131 132 Example Godeps: 133 134 ```json 135 { 136 "ImportPath": "github.com/kr/hk", 137 "GoVersion": "go1.1.2", 138 "Deps": [ 139 { 140 "ImportPath": "code.google.com/p/go-netrc/netrc", 141 "Rev": "28676070ab99" 142 }, 143 { 144 "ImportPath": "github.com/kr/binarydist", 145 "Rev": "3380ade90f8b0dfa3e363fd7d7e941fa857d0d13" 146 } 147 ] 148 } 149 ``` 150 151 ## Migrating to vendor/ 152 153 Godep supports Go 1.5+ vendor/ 154 [experiment](https://github.com/golang/go/commit/183cc0cd41f06f83cb7a2490a499e3f9101befff) 155 utilizing the same environment variable that the go tooling itself supports 156 (`GO15VENDOREXPERIMENT`). 157 158 godep mostly works the same way as the `go` command line tool. If you have go 159 1.5.X and set `GO15VENDOREXPERIMENT=1` or have go1.6.X (or devel) `vendor/` 160 is enabled. **Unless** you already have a `Godeps/_workspace`. This is a safety 161 feature and godep warns you about this. 162 163 When `vendor/` is enabled godep will write the vendored code into the top level 164 `./vendor/` directory. A `./Godeps/Godeps.json` file is created to track 165 the dependencies and revisions. `vendor/` is not compatible with rewrites. 166 167 There is currently no automated migration between the old Godeps workspace and 168 the vendor directory, but the following steps should work: 169 170 ```term 171 # just to be safe 172 $ unset GO15VENDOREXPERIMENT 173 174 # restore currently vendored deps to the $GOPATH 175 $ godep restore 176 177 # The next line is only needed to automatically undo rewritten imports that were 178 # created with godep save -r. 179 $ godep save -r=false <pkg spec> 180 181 # Remove the old Godeps folder 182 $ rm -rf Godeps 183 184 # If on go1.5.X to enable `vendor/` 185 $ export GO15VENDOREXPERIMENT=1 186 187 # re-analyze deps and save to `vendor/`. 188 $ godep save <pkg spec> 189 190 # Add the changed to your VCS 191 $ git add -A . ; git commit -am "Godep workspace -> vendor/" 192 193 # You should see your Godeps/_workspace/src files "moved" to vendor/. 194 ``` 195 196 NOTE: There was a design decision wrt `vendor/` that makes using `./...` 197 consider all packages inside the vendor directory: 198 https://github.com/golang/go/issues/11659. This should not affect projects 199 unless the project also vendors its dependency's tests (off by default). 200 201 ## Releasing 202 203 1. Increment the version in `version.go`. 204 1. Tag the commit with the same version number. 205 1. Update `Changelog.md`.