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`.