README.md
1# The Vendor Tool for Go
2`go get -u github.com/kardianos/govendor`
3
4New users please read the [FAQ](doc/faq.md)
5
6Package developers should read the [developer guide](doc/dev-guide.md).
7
8For a high level overview read the [whitepaper](doc/whitepaper.md)
9
10Uses the go1.5+ vendor folder. Multiple workflows supported, single tool.
11
12[](https://travis-ci.org/kardianos/govendor)
13[](https://ci.appveyor.com/project/kardianos/govendor/branch/master)
14[](https://godoc.org/github.com/kardianos/govendor)
15
16 * Copy existing dependencies from $GOPATH with `govendor add/update`.
17 * If you ignore `vendor/*/`, restore dependencies with `govendor sync`.
18 * Pull in new dependencies or update existing dependencies directly from
19 remotes with `govendor fetch`.
20 * Migrate from legacy systems with `govendor migrate`.
21 * Supports Linux, OS X, Windows, probably all others.
22 * Supports git, hg, svn, bzr (must be installed an on the PATH).
23
24## Notes
25
26 * The project must be within a $GOPATH/src.
27 * If using go1.5, ensure you `set GO15VENDOREXPERIMENT=1`.
28
29### Quick Start, also see the [FAQ](doc/faq.md)
30```
31# Setup your project.
32cd "my project in GOPATH"
33govendor init
34
35# Add existing GOPATH files to vendor.
36govendor add +external
37
38# View your work.
39govendor list
40
41# Look at what is using a package
42govendor list -v fmt
43
44# Specify a specific version or revision to fetch
45govendor fetch golang.org/x/net/context@a4bbce9fcae005b22ae5443f6af064d80a6f5a55
46govendor fetch golang.org/x/net/context@v1 # Get latest v1.*.* tag or branch.
47govendor fetch golang.org/x/net/context@=v1 # Get the tag or branch named "v1".
48
49# Update a package to latest, given any prior version constraint
50govendor fetch golang.org/x/net/context
51
52# Format your repository only
53govendor fmt +local
54
55# Build everything in your repository only
56govendor install +local
57
58# Test your repository only
59govendor test +local
60
61```
62
63## Sub-commands
64```
65 init Create the "vendor" folder and the "vendor.json" file.
66 list List and filter existing dependencies and packages.
67 add Add packages from $GOPATH.
68 update Update packages from $GOPATH.
69 remove Remove packages from the vendor folder.
70 status Lists any packages missing, out-of-date, or modified locally.
71 fetch Add new or update vendor folder packages from remote repository.
72 sync Pull packages into vendor folder from remote repository with revisions
73 from vendor.json file.
74 migrate Move packages from a legacy tool to the vendor folder with metadata.
75 get Like "go get" but copies dependencies into a "vendor" folder.
76 license List discovered licenses for the given status or import paths.
77 shell Run a "shell" to make multiple sub-commands more efficient for large
78 projects.
79
80 go tool commands that are wrapped:
81 `+<status>` package selection may be used with them
82 fmt, build, install, clean, test, vet, generate, tool
83```
84
85## Status
86
87Packages can be specified by their "status".
88```
89 +local (l) packages in your project
90 +external (e) referenced packages in GOPATH but not in current project
91 +vendor (v) packages in the vendor folder
92 +std (s) packages in the standard library
93
94 +excluded (x) external packages explicitly excluded from vendoring
95 +unused (u) packages in the vendor folder, but unused
96 +missing (m) referenced packages but not found
97
98 +program (p) package is a main package
99
100 +outside +external +missing
101 +all +all packages
102```
103
104Status can be referenced by their initial letters.
105
106 * `+std` same as `+s`
107 * `+external` same as `+ext` same as `+e`
108 * `+excluded` same as `+exc` same as `+x`
109
110Status can be logically composed:
111
112 * `+local,program` (local AND program) local packages that are also programs
113 * `+local +vendor` (local OR vendor) local packages or vendor packages
114 * `+vendor,program +std` ((vendor AND program) OR std) vendor packages that are also programs
115 or std library packages
116 * `+vendor,^program` (vendor AND NOT program) vendor package that are not "main" packages.
117
118## Package specifier
119
120The full package-spec is:
121`<path>[::<origin>][{/...|/^}][@[<version-spec>]]`
122
123Some examples:
124
125 * `github.com/kardianos/govendor` specifies a single package and single folder.
126 * `github.com/kardianos/govendor/...` specifies `govendor` and all referenced
127 packages under that path.
128 * `github.com/kardianos/govendor/^` specifies the `govendor` folder and all
129 sub-folders. Useful for resources or if you don't want a partial repository.
130 * `github.com/kardianos/govendor/^::github.com/myself/govendor` same as above
131 but fetch from user "myself".
132 * `github.com/kardianos/govendor/...@abc12032` all referenced packages at
133 revision `abc12032`.
134 * `github.com/kardianos/govendor/...@v1` same as above, but get the most recent
135 "v1" tag, such as "v1.4.3".
136 * `github.com/kardianos/govendor/...@=v1` get the exact version "v1".
137
138## Packages and Status
139
140You may specify multiple package-specs and multiple status in a single command.
141Commands that accept status and package-spec:
142
143 * list
144 * add
145 * update
146 * remove
147 * fetch
148
149You may pass arguments to govendor through stdin if the last argument is a "-".
150For example `echo +vendor | govendor list -` will list all vendor packages.
151
152## Ignoring build tags and excluding packages
153Ignoring build tags is opt-out and is designed to be the opposite of the build
154file directives which are opt-in when specified. Typically a developer will
155want to support cross platform builds, but selectively opt out of tags, tests,
156and architectures as desired.
157
158To ignore additional tags edit the "vendor.json" file and add tag to the vendor
159"ignore" file field. The field uses spaces to separate tags to ignore.
160For example the following will ignore both test and appengine files.
161```
162{
163 "ignore": "test appengine",
164}
165```
166
167Similarly, some specific packages can be excluded from the vendoring process.
168These packages will be listed as `excluded` (`x`), and will not be copied to the
169"vendor" folder when running `govendor add|fetch|update`.
170
171Any sub-package `foo/bar` of an excluded package `foo` is also excluded (but
172package `bar/foo` is not). The import dependencies of excluded packages are not
173listed, and thus not vendored.
174
175To exclude packages, also use the "ignore" field of the "vendor.json" file.
176Packages are identified by their name, they should contain a "/" character
177(possibly at the end):
178```
179{
180 "ignore": "test appengine foo/",
181}
182```
183
){kind=link}
){kind=link}