github.com/michaeltrobinson/godep@v0.0.0-20160912215839-8088bcf2e78b/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  Please see the [FAQ](https://github.com/tools/godep/blob/master/FAQ.md#should-i-use-godep-restore) section about restore.
    79  
    80  ### Edit-test Cycle
    81  
    82  1. Edit code
    83  1. Run `godep go test`
    84  1. (repeat)
    85  
    86  ### Add a Dependency
    87  
    88  To add a new package foo/bar, do this:
    89  
    90  1. Run `go get foo/bar`
    91  1. Edit your code to import foo/bar.
    92  1. Run `godep save` (or `godep save ./...`).
    93  
    94  ### Update a Dependency
    95  
    96  To update a package from your `$GOPATH`, do this:
    97  
    98  1. Run `go get -u foo/bar`
    99  1. Run `godep update foo/bar`. (You can use the `...` wildcard, for example
   100  `godep update foo/...`).
   101  
   102  Before comitting the change, you'll probably want to inspect the changes to
   103  Godeps, for example with `git diff`, and make sure it looks reasonable.
   104  
   105  ## Multiple Packages
   106  
   107  If your repository has more than one package, you're probably accustomed to
   108  running commands like `go test ./...`, `go install ./...`, and `go fmt ./...`.
   109  Similarly, you should run `godep save ./...` to capture the dependencies of all
   110  packages in your application.
   111  
   112  
   113  ## File Format
   114  
   115  Godeps is a json file with the following structure:
   116  
   117  ```go
   118  type Godeps struct {
   119  	ImportPath   string
   120  	GoVersion    string   // Abridged output of 'go version'.
   121  	GodepVersion string   // Abridged output of 'godep version'
   122  	Packages     []string // Arguments to godep save, if any.
   123  	Deps         []struct {
   124  		ImportPath string
   125  		Comment    string // Description of commit, if present.
   126  		Rev        string // VCS-specific commit ID.
   127  	}
   128  }
   129  ```
   130  
   131  Example Godeps:
   132  
   133  ```json
   134  {
   135  	"ImportPath": "github.com/kr/hk",
   136  	"GoVersion": "go1.6",
   137  	"Deps": [
   138  		{
   139  			"ImportPath": "code.google.com/p/go-netrc/netrc",
   140  			"Rev": "28676070ab99"
   141  		},
   142  		{
   143  			"ImportPath": "github.com/kr/binarydist",
   144  			"Rev": "3380ade90f8b0dfa3e363fd7d7e941fa857d0d13"
   145  		}
   146  	]
   147  }
   148  ```
   149  
   150  ## Migrating to vendor/
   151  
   152  Godep supports the Go 1.5+ vendor/
   153  [experiment](https://github.com/golang/go/commit/183cc0cd41f06f83cb7a2490a499e3f9101befff)
   154  utilizing the same environment variable that the go tooling itself supports
   155  (`GO15VENDOREXPERIMENT`).
   156  
   157  godep mostly works the same way as the `go` command line tool. If you have go
   158  1.5.X and set `GO15VENDOREXPERIMENT=1` or have go1.6.X (or devel) `vendor/`
   159  is enabled. **Unless** you already have a `Godeps/_workspace`. This is a safety
   160  feature and godep warns you about this.
   161  
   162  When `vendor/` is enabled godep will write the vendored code into the top level
   163  `./vendor/` directory. A `./Godeps/Godeps.json` file is created to track
   164  the dependencies and revisions. `vendor/` is not compatible with rewrites.
   165  
   166  There is currently no automated migration between the old Godeps workspace and
   167  the vendor directory, but the following steps should work:
   168  
   169  ```term
   170  # just to be safe
   171  $ unset GO15VENDOREXPERIMENT
   172  
   173  # restore currently vendored deps to the $GOPATH
   174  $ godep restore
   175  
   176  # The next line is only needed to automatically undo rewritten imports that were
   177  # created with godep save -r.
   178  $ godep save -r=false <pkg spec>
   179  
   180  # Remove the old Godeps folder
   181  $ rm -rf Godeps
   182  
   183  # If on go1.5.X to enable `vendor/`
   184  $ export GO15VENDOREXPERIMENT=1
   185  
   186  # re-analyze deps and save to `vendor/`.
   187  $ godep save <pkg spec>
   188  
   189  # Add the changes to your VCS
   190  $ git add -A . ; git commit -am "Godep workspace -> vendor/"
   191  
   192  # You should see your Godeps/_workspace/src files "moved" to vendor/.
   193  ```
   194  
   195  ## Releasing
   196  
   197  1. Increment the version in `version.go`.
   198  1. Tag the commit with the same version number.
   199  1. Update `Changelog.md`.