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