gvt

README

gvt, the Go vendoring tool

gvt is a simple vendoring tool made for Go native vendoring (aka GO15VENDOREXPERIMENT), based on gb-vendor.

It lets you easily and "idiomatically" include external dependencies in your repository to get reproducible builds.

• No need to learn a new tool or format!
  You already know how to use gvt: just run gvt fetch when and like you would run go get. You can imagine what gvt update and gvt delete do. In addition, gvt also allows fetching specific commits or branch versions in packages, and fully accommodates private repos.

• No need to change how you build your project!
  gvt downloads packages to ./vendor/.... The stock Go compiler will find and use those dependencies automatically without import path rewriting or GOPATH changes.
  (Go 1.6+, or Go 1.5 with GO15VENDOREXPERIMENT=1 set required.)

• No need to manually chase, copy or cleanup dependencies!
  gvt works recursively as you would expect, and lets you update vendored dependencies. It also writes a manifest to ./vendor/manifest and never touches your system GOPATH. Finally, it strips the VCS metadata so that you can commit the vendored source cleanly.

• No need for your users and occasional contributors to install or even know about gvt!
  Packages whose dependencies are vendored with gvt are go build-able and go get-able out of the box by Go 1.6+, or Go 1.5 with GO15VENDOREXPERIMENT=1 set.

Note that projects must live within the GOPATH tree in order to be go build-able with native vendoring.

Installation

With a correctly configured Go installation:

go get -u github.com/FiloSottile/gvt

Basic usage

When you would use go get, just use gvt fetch instead.

$ gvt fetch github.com/fatih/color
2015/09/05 02:38:06 fetching recursive dependency github.com/mattn/go-isatty
2015/09/05 02:38:07 fetching recursive dependency github.com/shiena/ansicolor

gvt fetch downloads the dependency into the vendor folder.

Files and folders starting with . or _ are ignored. Only files relevant to the Go compiler are fetched. LICENSE files are always included, too. Test files and testdata folders can be included with -t. To include all files (except the repository metadata), use -a.

$ tree -d
.
└── vendor
    └── github.com
        ├── fatih
        │   └── color
        ├── mattn
        │   └── go-isatty
        └── shiena
            └── ansicolor
                └── ansicolor

9 directories

There's no step 2, you are ready to use the fetched dependency as you would normally do.

(Requires Go 1.6+, or 1.5 with GO15VENDOREXPERIMENT=1 set.)

$ cat > main.go
package main
import "github.com/fatih/color"
func main() {
    color.Red("Hello, world!")
}

# Only needed with Go 1.5, vendoring is on by default in 1.6
$ export GO15VENDOREXPERIMENT=1

$ go build .
$ ./hello
Hello, world!

Finally, remember to check in and commit the vendor folder.

$ git add main.go vendor/ && git commit

Full usage

fetch offers options to download specific versions, and there are update, list and delete commands that do what you would expect.

View the full manual on GoDoc: https://godoc.org/github.com/FiloSottile/gvt

Alternative: not checking in vendored source

Some developers prefer not to check in the source of the vendored dependencies. In that case you can add lines like these to e.g. your .gitignore

vendor/**
!vendor/manifest

When you check out the source again, you can then run gvt restore to fetch all the dependencies at the revisions specified in the vendor/manifest file.

Please consider that this approach has the following consequences:

• the package consumer will need gvt to fetch the dependencies
• the dependencies will need to remain available from the source repositories: if the original repository goes down or rewrites history, build reproducibility is lost
• go get won't work on your package
• unless you pin the gvt version, bugs and unintended changes introduced in how gvt restore behaves can affect your build

Vendoring a different fork

You might have your own version of a repository (i.e. a fork) but still want to vendor it at the original import path.

Since this is not a common use-case, there's no support in gvt fetch for it, however, you can manually edit the vendor/manifest file, changing repository and revision, and then run gvt restore.

gvt update will stay on your fork.

Overlapping dependencies

Since in the current manifest, inherited from gb-vendor, a dependency includes all subpackages, it is possible to get conflicts in the form of overlapping dependencies. For example, if we had one version of example.com/a and a different one of example.com/a/b.

To solve this cleanly, overlaps are disallowed. Subpackages of existing dependencies are silently treated as existing dependencies. Parents of existing dependencies are treated as missing and cause the subpackages to be deleted when they are fetched.

This rule might be arbitrary, but it is required to have determinism in situations like recursive fetches, where the orders and priorities of fetches are undefined. If it causes incompatibilities, they were for the human to fix anyway.

(There's an exception, if you want to nitpick, and it's that if you fetch a package at a revision, and its parent ends up being fetched by the recursive resolution, the parent will be fetched at the revision, not at master, because that's probably what you meant.)

Troubleshooting

fatal: Not a git repository [...]

error: tag 'fetch' not found.

These errors can occur because you have an alias for gvt pointing to git verify-tag (default if using oh-my-zsh).

Recent versions of oh-my-zsh removed the alias. You can update with upgrade_oh_my_zsh.

Alternatively, run this, and preferably add it to your ~/.bashrc / ~/.zshrc: unalias gvt.

go build can't find the vendored package

Make sure you are using at least Go 1.5, set GO15VENDOREXPERIMENT=1 if you are using Go 1.5 and didn't set GO15VENDOREXPERIMENT=0 if you are using Go 1.6.

Also note that native vendoring does not work outside the GOPATH source tree. That is, your project MUST be somewhere in a subfolder of $GOPATH/src/.

License

MIT licensed. See the LICENSE file for details.

Documentation

Overview

gvt, a simple go vendoring tool based on gb-vendor.

Usage:

gvt command [arguments]

The commands are:

fetch       fetch a remote dependency
restore     restore dependencies from manifest
update      update a local dependency
list        list dependencies one per line
delete      delete a local dependency

Use "gvt help [command]" for more information about a command.

Fetch a remote dependency

Usage:

gvt fetch [-branch branch] [-revision rev | -tag tag] [-precaire] [-no-recurse] [-t|-a] importpath

fetch vendors an upstream import path.

Recursive dependencies are fetched (at their master/tip/HEAD revision), unless they or their parent package are already present.

If a subpackage of a dependency being fetched is already present, it will be deleted.

The import path may include a url scheme. This may be useful when fetching dependencies from private repositories that cannot be probed.

Flags:

-t
	fetch also _test.go files and testdata.
-a
	fetch all files and subfolders, ignoring ONLY .git, .hg and .bzr.
-branch branch
	fetch from the named branch. Will also be used by gvt update.
	If not supplied the default upstream branch will be used.
-no-recurse
	do not fetch recursively.
-tag tag
	fetch the specified tag.
-revision rev
	fetch the specific revision from the branch or repository.
	If no revision supplied, the latest available will be fetched.
-precaire
	allow the use of insecure protocols.

Restore dependencies from manifest

Usage:

gvt restore [-precaire] [-connections N]

restore fetches the dependencies listed in the manifest.

It's meant for workflows that don't include checking in to VCS the vendored source, for example if .gitignore includes lines like

vendor/**
!vendor/manifest

Note that such a setup requires "gvt restore" to build the source, relies on the availability of the dependencies repositories and breaks "go get".

Flags:

-precaire
	allow the use of insecure protocols.
-connections
	count of parallel download connections.

Update a local dependency

Usage:

gvt update [ -all | importpath ]

update replaces the source with the latest available from the head of the fetched branch.

Updating from one copy of a dependency to another is ONLY possible when the dependency was fetched by branch, without using -tag or -revision. It will be updated to the HEAD of that branch, switching branches is not supported.

To update across branches, or from one tag/revision to another, you must first use delete to remove the dependency, then fetch [ -tag | -revision | -branch ] to replace it.

Flags:

-all
	update all dependencies in the manifest.
-precaire
	allow the use of insecure protocols.

List dependencies one per line

Usage:

gvt list [-f format]

list formats the contents of the manifest file.

Flags:

-f
	controls the template used for printing each manifest entry. If not supplied
	the default value is "{{.Importpath}}\t{{.Repository}}{{.Path}}\t{{.Branch}}\t{{.Revision}}"

Delete a local dependency

Usage:

gvt delete [-all] importpath

delete removes a dependency from the vendor directory and the manifest

Flags:

-all
	remove all dependencies