README.md - third_party/FiloSottile/gvt - Git at Google

 # gvt, the Go vendoring tool
 [![GoDoc](https://godoc.org/github.com/FiloSottile/gvt?status.svg)](https://godoc.org/github.com/FiloSottile/gvt)
 [![Build Status](https://travis-ci.org/FiloSottile/gvt.svg?branch=master)](https://travis-ci.org/FiloSottile/gvt)

 `gvt` is a simple vendoring tool made for Go native vendoring (aka
 [GO15VENDOREXPERIMENT](https://docs.google.com/document/d/1Bz5-UB7g2uPBdOx-rw5t9MxJwkfpx90cqG9AFL0JAYo/edit)),
 based on [gb-vendor](https://github.com/constabulary/gb).

 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](https://godoc.org/github.com/FiloSottile/gvt#hdr-Fetch_a_remote_dependency)
     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](https://golang.org/doc/code.html#GOPATH) 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](https://golang.org/cmd/go/#hdr-File_types) 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, ovelaps 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](https://github.com/robbyrussell/oh-my-zsh/pull/4841). 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.
	# gvt, the Go vendoring tool
	[![GoDoc](https://godoc.org/github.com/FiloSottile/gvt?status.svg)](https://godoc.org/github.com/FiloSottile/gvt)
	[![Build Status](https://travis-ci.org/FiloSottile/gvt.svg?branch=master)](https://travis-ci.org/FiloSottile/gvt)

	`gvt` is a simple vendoring tool made for Go native vendoring (aka
	[GO15VENDOREXPERIMENT](https://docs.google.com/document/d/1Bz5-UB7g2uPBdOx-rw5t9MxJwkfpx90cqG9AFL0JAYo/edit)),
	based on [gb-vendor](https://github.com/constabulary/gb).

	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](https://godoc.org/github.com/FiloSottile/gvt#hdr-Fetch_a_remote_dependency)
	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](https://golang.org/doc/code.html#GOPATH) 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](https://golang.org/cmd/go/#hdr-File_types) 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, ovelaps 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](https://github.com/robbyrussell/oh-my-zsh/pull/4841). 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.