Go
Latest commit 3c0ccb9 Jul 10, 2016 @freeformz freeformz Summarize paragraph
Failed to load latest commit information.
.github Add Issue Template May 27, 2016
.vscode vscode stuff May 9, 2016
Godeps Enable vendor/ for go1.7 & Godep workspace -> vendor/ Jun 1, 2016
vendor Fix the silly file Jun 1, 2016
.gitignore tighten up ignore pattern Oct 8, 2013
.travis.yml Don't need to build the toolchain either Apr 7, 2016
Changelog.md Enable vendor/ for go1.7 & Godep workspace -> vendor/ Jun 2, 2016
FAQ.md Summarize paragraph Jul 10, 2016
License import go tool subcommand machinery May 13, 2013
Readme.md Note the FAQ wrt restore Jul 10, 2016
dep.go 'determing' to 'determining' May 29, 2016
dep_test.go Support devel-<short sha> go versions May 3, 2016
diff.go Enable vendor/ for go1.7 & Godep workspace -> vendor/ Jun 2, 2016
diff_test.go Add godep version to Godeps.json file. Mar 14, 2016
doc.go new command: path Sep 13, 2013
errors.go Fix a bunch of GO15VENDOREXPERIMENT issues Dec 22, 2015
get.go Enforce requirement to be inside of a go src directory. Mar 18, 2016
go.go Enforce requirement to be inside of a go src directory. Mar 18, 2016
godepfile.go Handle missing deps a little better May 12, 2016
license.go Add UK spelling license/licence to the pile Jan 13, 2016
license_test.go Add UK spelling license/licence to the pile Jan 13, 2016
list.go Scan through new transitive deps and add them May 9, 2016
main.go Enable vendor/ for go1.7 & Godep workspace -> vendor/ Jun 2, 2016
match_test.go devel* should enable vendor/ May 16, 2016
msg.go Enable vendor/ for go1.7 & Godep workspace -> vendor/ Jun 2, 2016
path.go Enforce requirement to be inside of a go src directory. Mar 18, 2016
pkg.go Scan through new transitive deps and add them May 9, 2016
restore.go Enable vendor/ for go1.7 & Godep workspace -> vendor/ Jun 2, 2016
rewrite.go Enable vendor/ for go1.7 & Godep workspace -> vendor/ Jun 2, 2016
rewrite_test.go Fix a bunch of GO15VENDOREXPERIMENT issues Dec 23, 2015
save.go Enable vendor/ for go1.7 & Godep workspace -> vendor/ Jun 2, 2016
save_test.go Handle missing deps a little better May 12, 2016
update.go Handle missing deps a little better May 12, 2016
update_test.go Handle missing deps a little better May 12, 2016
util.go Consolidate path equality checks into pathEqual Feb 26, 2016
vcs.go Enable vendor/ for go1.7 & Godep workspace -> vendor/ Jun 2, 2016
vcs_test.go Improve handling of git remote show origin May 27, 2016
version.go Enable vendor/ for go1.7 & Godep workspace -> vendor/ Jun 2, 2016

Readme.md

Godep

Build Status

GoDoc

godep helps build packages reproducibly by fixing their dependencies.

This tool assumes you are working in a standard Go workspace, as described in http://golang.org/doc/code.html. We expect godep to build on Go 1.4* or newer, but you can use it on any project that works with Go 1 or newer.

Please check the FAQ if you have a question.

Install

$ go get github.com/tools/godep

How to use godep with a new project

Assuming you've got everything working already, so you can build your project with go install and test it with go test, it's one command to start using:

$ godep save

This will save a list of dependencies to the file Godeps/Godeps.json and copy their source code into vendor/ (or Godeps/_workspace/ when using older versions of Go). Godep does not copy:

  • files from source repositories that are not tracked in version control.
  • *_test.go files.
  • testdata directories.
  • files outside of the go packages.

Godep does not process the imports of .go files with either the ignore or appengine build tags.

Test files and testdata directories can be saved by adding -t.

Read over the contents of vendor/ and make sure it looks reasonable. Then commit the Godeps/ and vendor/ directories to version control.

The deprecated -r flag

For older versions of Go, the -r flag tells save to automatically rewrite package import paths. This allows your code to refer directly to the copied dependencies in Godeps/_workspace. So, a package C that depends on package D will actually import C/Godeps/_workspace/src/D. This makes C's repo self-contained and causes go get to build C with the right version of all dependencies.

If you don't use -r, when using older version of Go, then in order to use the fixed dependencies and get reproducible builds, you must make sure that every time you run a Go-related command, you wrap it in one of these two ways:

  • If the command you are running is just go, run it as godep go ..., e.g. godep go install -v ./...
  • When using a different command, set your $GOPATH using godep path as described below.

-r isn't necessary with go1.6+ and isn't allowed.

Additional Operations

Restore

The godep restore installs the package versions specified in Godeps/Godeps.json to your $GOPATH. This modifies the state of packages in your $GOPATH. NOTE: godep restore leaves git repositories in a detached state. go1.6+ no longer checks out the master branch when doing a go get, see here.

Please see the FAQ section about restore.

Edit-test Cycle

  1. Edit code
  2. Run godep go test
  3. (repeat)

Add a Dependency

To add a new package foo/bar, do this:

  1. Run go get foo/bar
  2. Edit your code to import foo/bar.
  3. Run godep save (or godep save ./...).

Update a Dependency

To update a package from your $GOPATH, do this:

  1. Run go get -u foo/bar
  2. Run godep update foo/bar. (You can use the ... wildcard, for example godep update foo/...).

Before comitting the change, you'll probably want to inspect the changes to Godeps, for example with git diff, and make sure it looks reasonable.

Multiple Packages

If your repository has more than one package, you're probably accustomed to running commands like go test ./..., go install ./..., and go fmt ./.... Similarly, you should run godep save ./... to capture the dependencies of all packages in your application.

File Format

Godeps is a json file with the following structure:

type Godeps struct {
    ImportPath   string
    GoVersion    string   // Abridged output of 'go version'.
    GodepVersion string   // Abridged output of 'godep version'
    Packages     []string // Arguments to godep save, if any.
    Deps         []struct {
        ImportPath string
        Comment    string // Description of commit, if present.
        Rev        string // VCS-specific commit ID.
    }
}

Example Godeps:

{
    "ImportPath": "github.com/kr/hk",
    "GoVersion": "go1.6",
    "Deps": [
        {
            "ImportPath": "code.google.com/p/go-netrc/netrc",
            "Rev": "28676070ab99"
        },
        {
            "ImportPath": "github.com/kr/binarydist",
            "Rev": "3380ade90f8b0dfa3e363fd7d7e941fa857d0d13"
        }
    ]
}

Migrating to vendor/

Godep supports the Go 1.5+ vendor/ experiment utilizing the same environment variable that the go tooling itself supports (GO15VENDOREXPERIMENT).

godep mostly works the same way as the go command line tool. If you have go 1.5.X and set GO15VENDOREXPERIMENT=1 or have go1.6.X (or devel) vendor/ is enabled. Unless you already have a Godeps/_workspace. This is a safety feature and godep warns you about this.

When vendor/ is enabled godep will write the vendored code into the top level ./vendor/ directory. A ./Godeps/Godeps.json file is created to track the dependencies and revisions. vendor/ is not compatible with rewrites.

There is currently no automated migration between the old Godeps workspace and the vendor directory, but the following steps should work:

# just to be safe
$ unset GO15VENDOREXPERIMENT

# restore currently vendored deps to the $GOPATH
$ godep restore

# The next line is only needed to automatically undo rewritten imports that were
# created with godep save -r.
$ godep save -r=false <pkg spec>

# Remove the old Godeps folder
$ rm -rf Godeps

# If on go1.5.X to enable `vendor/`
$ export GO15VENDOREXPERIMENT=1

# re-analyze deps and save to `vendor/`.
$ godep save <pkg spec>

# Add the changes to your VCS
$ git add -A . ; git commit -am "Godep workspace -> vendor/"

# You should see your Godeps/_workspace/src files "moved" to vendor/.

Releasing

  1. Increment the version in version.go.
  2. Tag the commit with the same version number.
  3. Update Changelog.md.