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