gopkg.in/tools/godep.v39@v39.0.0-20151216234527-2721f686f09e/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`.