github.com/opsmatic/godep@v0.1.5/Readme.md (about)

     1  ### Godep
     2  
     3  Command godep helps build packages reproducibly by fixing their dependencies.
     4  
     5  This tool assumes you are working in a standard Go workspace,
     6  as described in http://golang.org/doc/code.html. We require Go 1.1
     7  or newer to build godep itself, but you can use it on any project
     8  that works with Go 1 or newer.
     9  
    10  ### Install
    11  
    12  	$ go get github.com/tools/godep
    13  
    14  #### Getting Started
    15  
    16  How to add godep in a new project.
    17  
    18  Assuming you've got everything working already, so you can
    19  build your project with `go install` and test it with `go test`,
    20  it's one command to start using:
    21  
    22  	$ godep save
    23  
    24  This will save a list of dependencies to the file Godeps/Godeps.json,
    25  and copy their source code into Godeps/_workspace.
    26  Read over its contents and make sure it looks reasonable.
    27  Then commit the file to version control.
    28  
    29  #### Restore
    30  
    31  The `godep restore` command is the opposite of `godep save`.
    32  It will install the package versions specified in
    33  Godeps/Godeps.json to your GOPATH.
    34  
    35  #### Edit-test Cycle
    36  
    37  1. Edit code
    38  2. Run `godep go test`
    39  3. (repeat)
    40  
    41  #### Add a Dependency
    42  
    43  To add a new package foo/bar, do this:
    44  
    45  1. Run `go get foo/bar`
    46  2. Edit your code to import foo/bar.
    47  3. Run `godep save` (or `godep save ./...`).
    48  
    49  #### Update a Dependency
    50  
    51  To update a package from your `$GOPATH`, do this:
    52  
    53  1. Run `go get -u foo/bar`
    54  2. Run `godep update foo/bar`. (You can use the `...` wildcard,
    55  for example `godep update foo/...`).
    56  
    57  Before committing the change, you'll probably want to inspect
    58  the changes to Godeps, for example with `git diff`,
    59  and make sure it looks reasonable.
    60  
    61  #### Multiple Packages
    62  
    63  If your repository has more than one package, you're probably
    64  accustomed to running commands like `go test ./...`,
    65  `go install ./...`, and `go fmt ./...`.
    66  Similarly, you should run `godep save ./...` to capture the
    67  dependencies of all packages.
    68  
    69  #### Using Other Tools
    70  
    71  The `godep path` command helps integrate with commands other
    72  than the standard go tool. This works with any tool that reads
    73  GOPATH from its environment, for example the recently-released
    74  [oracle command](http://godoc.org/code.google.com/p/go.tools/cmd/oracle).
    75  
    76  	$ GOPATH=`godep path`:$GOPATH
    77  	$ oracle -mode=implements .
    78  
    79  #### Old Format
    80  
    81  Old versions of godep wrote the dependency list to a file Godeps,
    82  and didn't copy source code. This mode no longer exists, but
    83  commands 'godep go' and 'godep path' will continue to read the old
    84  format for some time.
    85  
    86  ### File Format
    87  
    88  Godeps is a json file with the following structure:
    89  
    90  ```go
    91  type Godeps struct {
    92  	ImportPath string
    93  	GoVersion  string   // Abridged output of 'go version'.
    94  	Packages   []string // Arguments to godep save, if any.
    95  	Deps       []struct {
    96  		ImportPath string
    97  		Comment    string // Description of commit, if present.
    98  		Rev        string // VCS-specific commit ID.
    99  	}
   100  }
   101  ```
   102  
   103  Example Godeps:
   104  
   105  ```json
   106  {
   107  	"ImportPath": "github.com/kr/hk",
   108  	"GoVersion": "go1.1.2",
   109  	"Deps": [
   110  		{
   111  			"ImportPath": "code.google.com/p/go-netrc/netrc",
   112  			"Rev": "28676070ab99"
   113  		},
   114  		{
   115  			"ImportPath": "github.com/kr/binarydist",
   116  			"Rev": "3380ade90f8b0dfa3e363fd7d7e941fa857d0d13"
   117  		}
   118  	]
   119  }
   120  ```