gopkg.in/tools/godep.v41@v41.0.0-20151217180337-fe5ce707f879/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 Test files and testdata directories can be saved by adding `-t`. 56 57 ## Additional Operations 58 59 ### Restore 60 61 The `godep restore` command is the opposite of `godep save`. It will install the 62 package versions specified in `Godeps/Godeps.json` to your `$GOPATH`. This modifies the state of packages in your `$GOPATH`. 63 64 ### Edit-test Cycle 65 66 1. Edit code 67 1. Run `godep go test` 68 1. (repeat) 69 70 ### Add a Dependency 71 72 To add a new package foo/bar, do this: 73 74 1. Run `go get foo/bar` 75 1. Edit your code to import foo/bar. 76 1. Run `godep save` (or `godep save ./...`). 77 78 ### Update a Dependency 79 80 To update a package from your `$GOPATH`, do this: 81 82 1. Run `go get -u foo/bar` 83 1. Run `godep update foo/bar`. (You can use the `...` wildcard, for example 84 `godep update foo/...`). 85 86 Before committing the change, you'll probably want to inspect the changes to 87 Godeps, for example with `git diff`, and make sure it looks reasonable. 88 89 ## Multiple Packages 90 91 If your repository has more than one package, you're probably accustomed to 92 running commands like `go test ./...`, `go install ./...`, and `go fmt ./...`. 93 Similarly, you should run `godep save ./...` to capture the dependencies of all 94 packages. 95 96 ## Using Other Tools 97 98 The `godep path` command helps integrate with commands other than the standard 99 go tool. This works with any tool that reads GOPATH from its environment, for 100 example the recently-released [oracle 101 command](http://godoc.org/code.google.com/p/go.tools/cmd/oracle). 102 103 $ GOPATH=`godep path`:$GOPATH 104 $ oracle -mode=implements . 105 106 ## Old Format 107 108 Old versions of godep wrote the dependency list to a file Godeps, and didn't 109 copy source code. This mode no longer exists, but commands 'godep go' and 'godep 110 path' will continue to read the old format for some time. 111 112 ## File Format 113 114 Godeps is a json file with the following structure: 115 116 ```go 117 type Godeps struct { 118 ImportPath string 119 GoVersion string // Abridged output of 'go version'. 120 Packages []string // Arguments to godep save, if any. 121 Deps []struct { 122 ImportPath string 123 Comment string // Description of commit, if present. 124 Rev string // VCS-specific commit ID. 125 } 126 } 127 ``` 128 129 Example Godeps: 130 131 ```json 132 { 133 "ImportPath": "github.com/kr/hk", 134 "GoVersion": "go1.1.2", 135 "Deps": [ 136 { 137 "ImportPath": "code.google.com/p/go-netrc/netrc", 138 "Rev": "28676070ab99" 139 }, 140 { 141 "ImportPath": "github.com/kr/binarydist", 142 "Rev": "3380ade90f8b0dfa3e363fd7d7e941fa857d0d13" 143 } 144 ] 145 } 146 ``` 147 148 ## Go 1.5 vendor/ experiment 149 150 Godep has preliminary support for the Go 1.5 vendor/ 151 [experiment](https://github.com/golang/go/commit/183cc0cd41f06f83cb7a2490a499e3f9101befff) 152 utilizing the same environment variable that the go tooling itself supports: 153 `export GO15VENDOREXPERIMENT=1` 154 155 When `GO15VENDOREXPERIMENT=1` godep will write the vendored code into the local 156 package's `vendor` directory. A `Godeps/Godeps.json` file is created, just like 157 during normal operation. The vendor experiment is not compatible with rewrites. 158 159 There is currently no automated migration between the old Godeps workspace and 160 the vendor directory, but the following steps should work: 161 162 ```term 163 $ unset GO15VENDOREXPERIMENT 164 $ godep restore 165 # The next line is only needed to automatically undo rewritten imports that were 166 # created with godep save -r. 167 $ godep save ./... 168 $ rm -rf Godeps 169 $ export GO15VENDOREXPERIMENT=1 170 $ godep save ./... 171 $ git add -A 172 # You should see your Godeps/_workspace/src files "moved" to vendor/. 173 ``` 174 175 NOTE: There is a "bug" in the vendor experiment that makes using `./...` with 176 the go tool (like go install) consider all packages inside the vendor directory: 177 https://github.com/golang/go/issues/11659. As a workaround you can do: 178 179 ```term 180 $ go <cmd> $(go list ./... | grep -v /vendor/) 181 ``` 182 183 ## Releasing 184 185 1. Increment the version in `version.go`. 186 1. Tag the commit with the same version number. 187 1. Update `Changelog.md`.