github.com/alde/glide@v0.0.0-20160309204240-d5fc6b676a75/README.md (about) 1 # Glide: Vendor Package Management for Golang 2 3 ![glide logo](https://glide.sh/assets/logo-small.png) 4 5 Are you used to tools such as Cargo, npm, Composer, Nuget, Pip, Maven, Bundler, 6 or other modern package managers? If so, Glide is the comparable Go tool. 7 8 *Manage your vendor and vendored packages with ease.* Glide is a tool for 9 managing the `vendor` directory within a Go package. This feature, first 10 introduced in Go 1.5, allows each package to have a `vendor` directory 11 containing dependent packages for the project. These vendor packages can be 12 installed by a tool (e.g. glide), similar to `go get` or they can be vendored and 13 distributed with the package. 14 15 [![Build Status](https://travis-ci.org/Masterminds/glide.svg)](https://travis-ci.org/Masterminds/glide) [![Go Report Card](http://goreportcard.com/badge/Masterminds/glide)](http://goreportcard.com/report/Masterminds/glide) [![GoDoc](https://godoc.org/github.com/Masterminds/glide?status.svg)](https://godoc.org/github.com/Masterminds/glide) [![Documentation Status](https://readthedocs.org/projects/glide/badge/?version=latest)](http://glide.readthedocs.org/en/latest/?badge=latest) [![Join us on #masterminds on Freenode](https://www.irccloud.com/invite-svg?channel=%23masterminds&hostname=irc.freenode.net&port=6697&ssl=1)](https://www.irccloud.com/invite?channel=%23masterminds&hostname=irc.freenode.net&port=6697&ssl=1) 16 17 ### Features 18 19 * Ease dependency management 20 * Support **versioning packages** including [Semantic Versioning 21 2.0.0](http://semver.org/) support. Any constraint the [`github.com/Masterminds/semver`](https://github.com/Masterminds/semver) 22 package can parse can be used. 23 * Support **aliasing packages** (e.g. for working with github forks) 24 * Remove the need for munging import statements 25 * Work with all of the `go` tools 26 * Support the VCS tools that Go supports: 27 - git 28 - bzr 29 - hg 30 - svn 31 * Support custom local and global plugins (see docs/plugins.md) 32 * Repository caching including reuse of packages in the `$GOPATH` 33 * Flatten dependencies resolving version differences and avoiding the inclusion 34 of a package multiple times. 35 36 ## How It Works 37 38 The dependencies for a project are listed in a `glide.yaml` file. This can 39 include a version, VCS, repository location (that can be different from the 40 package name), etc. When `glide up` is run it downloads the packages (or updates) 41 to the `vendor` directory. It then recursively walks through the downloaded 42 packages looking for those with a `glide.yaml` file (or Godep, gb, or GPM config 43 file) that don't already have a `vendor` directory and installing their 44 dependencies to their `vendor` directories. Once Glide has downloaded and figured 45 out versions to use in the dependency tree it creates a `glide.lock` file 46 containing the complete dependency tree pinned to specific versions. To install 47 the correct versions use `glide install`. 48 49 A projects is structured like this: 50 51 ``` 52 - $GOPATH/src/myProject (Your project) 53 | 54 |-- glide.yaml 55 | 56 |-- glide.lock 57 | 58 |-- main.go (Your main go code can live here) 59 | 60 |-- mySubpackage (You can create your own subpackages, too) 61 | | 62 | |-- foo.go 63 | 64 |-- vendor 65 |-- github.com 66 | 67 |-- Masterminds 68 | 69 |-- ... etc. 70 ``` 71 72 *Take a look at [the Glide source code](http://github.com/Masterminds/glide) 73 to see this philosophy in action.* 74 75 ## Install 76 77 On Mac OS X you can install the latest release via [Homebrew](https://github.com/Homebrew/homebrew): 78 79 ``` 80 $ brew install glide 81 ``` 82 83 [Binary packages](https://github.com/Masterminds/glide/releases) are available for Mac, Linux and Windows. 84 85 To build from source you can: 86 87 1. Clone this repository into `$GOPATH/src/github.com/Masterminds/glide` and 88 change directory into it 89 2. Ensure that the environment variable GO15VENDOREXPERIMENT is set, f.ex. by 90 running `export GO15VENDOREXPERIMENT=1` 91 3. Run `make bootstrap`, followed by `make build` 92 93 This will leave you with `./glide`, which you can put in your `$PATH` if 94 you'd like. (You can also take a look at `make install` to install for 95 you.) 96 97 The Glide repo has now been configured to use glide to 98 manage itself, too. 99 100 ## Usage 101 102 ``` 103 $ glide create # Start a new workspace 104 $ open glide.yaml # and edit away! 105 $ glide get github.com/Masterminds/cookoo # Get a package and add to glide.yaml 106 $ glide install # Install packages and dependencies 107 # work, work, work 108 $ go build # Go tools work normally 109 $ glide up # Update to newest versions of the package 110 ``` 111 112 Check out the `glide.yaml` in this directory, or examples in the `docs/` 113 directory. 114 115 ### glide create (aliased to init) 116 117 Initialize a new workspace. Among other things, this creates a `glide.yaml` file 118 while attempting to guess the packages and versions to put in it. For example, 119 if your project is using Godep it will use the versions specified there. Glide 120 is smart enough to scan your codebase and detect the imports being used whether 121 they are specified with another package manager or not. 122 123 ``` 124 $ glide create 125 [INFO] Generating a YAML configuration file and guessing the dependencies 126 [INFO] Attempting to import from other package managers (use --skip-import to skip) 127 [INFO] Found reference to github.com/Sirupsen/logrus 128 [INFO] Adding sub-package hooks/syslog to github.com/Sirupsen/logrus 129 [INFO] Found reference to github.com/boltdb/bolt 130 [INFO] Found reference to github.com/gorilla/websocket 131 [INFO] Found reference to github.com/mndrix/ps 132 [INFO] Found reference to github.com/spf13/cobra 133 [INFO] Found reference to github.com/spf13/pflag 134 [INFO] Found reference to github.com/tinylib/msgp/msgp 135 [INFO] Found reference to github.com/unrolled/secure 136 [INFO] Found reference to github.com/xeipuuv/gojsonschema 137 [INFO] Found reference to github.com/zenazn/goji/graceful 138 [INFO] Adding sub-package web to github.com/zenazn/goji 139 [INFO] Adding sub-package web/mutil to github.com/zenazn/goji 140 ``` 141 142 ### glide get [package name] 143 144 You can download one or more packages to your `vendor` directory and have it added to your 145 `glide.yaml` file with `glide get`. 146 147 ``` 148 $ glide get github.com/Masterminds/cookoo 149 ``` 150 151 When `glide get` is used it will introspect the listed package to resolve its 152 dependencies including using Godep, GPM, and GB config files. 153 154 ### glide update (aliased to up) 155 156 Download or update all of the libraries listed in the `glide.yaml` file and put 157 them in the `vendor` directory. It will also recursively walk through the 158 dependency packages doing the same thing if no `vendor` directory exists. 159 160 ``` 161 $ glide up 162 ``` 163 164 This will recurse over the packages looking for other projects managed by Glide, 165 Godep, gb, and GPM. When one is found those packages will be installed as needed. 166 167 A `glide.lock` file will be created or updated with the dependencies pinned to 168 specific versions. For example, if in the `glide.yaml` file a version was 169 specified as a range (e.g., `^1.2.3`) it will be set to a specific commit id in 170 the `glide.lock` file. That allows for reproducible installs (see `glide install`). 171 172 ### glide install 173 174 When you want to install the specific versions from the `glide.lock` file use 175 `glide install`. 176 177 ``` 178 $ glide install 179 ``` 180 181 This will read the `glide.lock` file and install the commit id specific versions 182 there. 183 184 When the `glide.lock` file doesn't tie to the `glide.yaml` file, such as there 185 being a change, it will provide a warning. Running `glide up` will recreate the 186 `glide.lock` file when updating the dependency tree. 187 188 If no `glide.lock` file is present `glide install` will perform an `update` and 189 generate a lock file. 190 191 ## glide novendor (aliased to nv) 192 193 When you run commands like `go test ./...` it will iterate over all the 194 subdirectories including the `vendor` directory. When you are testing your 195 application you may want to test your application files without running all the 196 tests of your dependencies and their dependencies. This is where the `novendor` 197 command comes in. It lists all of the directories except `vendor`. 198 199 $ go test $(glide novendor) 200 201 This will run `go test` over all directories of your project except the 202 `vendor` directory. 203 204 ## glide name 205 206 When you're scripting with Glide there are occasions where you need to know 207 the name of the package you're working on. `glide name` returns the name of the 208 package listed in the `glide.yaml` file. 209 210 ### glide rebuild 211 212 Re-run `go install` on the packages in the `glide.yaml` file. This 213 (along with `glide install` and `glide update`) pays special attention 214 to the contents of the `subpackages:` directive in the YAML file. 215 216 ``` 217 $ glide rebuild 218 [INFO] Building dependencies. 219 [INFO] Running go build github.com/kylelemons/go-gypsy/yaml 220 [INFO] Running go build github.com/Masterminds/cookoo/cli 221 [INFO] Running go build github.com/Masterminds/cookoo 222 ``` 223 224 This is useful when you are working with large 3rd party libraries. It 225 will create the `.a` files, which can have a positive impact on your 226 build times. 227 228 ### glide tree 229 230 Glide includes a few commands that inspect code and give you details 231 about what is imported. `glide tree` is one such command. Running it 232 gives data like this: 233 234 ``` 235 $ glide tree 236 github.com/Masterminds/glide 237 github.com/Masterminds/cookoo (/Users/mfarina/Code/go/src/github.com/Masterminds/glide/vendor/github.com/Masterminds/cookoo) 238 github.com/Masterminds/cookoo/io (/Users/mfarina/Code/go/src/github.com/Masterminds/glide/vendor/github.com/Masterminds/cookoo/io) 239 github.com/Masterminds/glide/cmd (/Users/mfarina/Code/go/src/github.com/Masterminds/glide/cmd) 240 github.com/Masterminds/cookoo (/Users/mfarina/Code/go/src/github.com/Masterminds/glide/vendor/github.com/Masterminds/cookoo) 241 github.com/Masterminds/cookoo/io (/Users/mfarina/Code/go/src/github.com/Masterminds/glide/vendor/github.com/Masterminds/cookoo/io) 242 github.com/Masterminds/glide/gb (/Users/mfarina/Code/go/src/github.com/Masterminds/glide/gb) 243 github.com/Masterminds/glide/util (/Users/mfarina/Code/go/src/github.com/Masterminds/glide/util) 244 github.com/Masterminds/vcs (/Users/mfarina/Code/go/src/github.com/Masterminds/glide/vendor/github.com/Masterminds/vcs) 245 github.com/Masterminds/glide/yaml (/Users/mfarina/Code/go/src/github.com/Masterminds/glide/yaml) 246 github.com/Masterminds/glide/util (/Users/mfarina/Code/go/src/github.com/Masterminds/glide/util) 247 github.com/Masterminds/vcs (/Users/mfarina/Code/go/src/github.com/Masterminds/glide/vendor/github.com/Masterminds/vcs) 248 github.com/Masterminds/vcs (/Users/mfarina/Code/go/src/github.com/Masterminds/glide/vendor/github.com/Masterminds/vcs) 249 gopkg.in/yaml.v2 (/Users/mfarina/Code/go/src/gopkg.in/yaml.v2) 250 github.com/Masterminds/semver (/Users/mfarina/Code/go/src/github.com/Masterminds/glide/vendor/github.com/Masterminds/semver) 251 github.com/Masterminds/vcs (/Users/mfarina/Code/go/src/github.com/Masterminds/glide/vendor/github.com/Masterminds/vcs) 252 github.com/codegangsta/cli (/Users/mfarina/Code/go/src/github.com/Masterminds/glide/vendor/github.com/codegangsta/cli) 253 github.com/codegangsta/cli (/Users/mfarina/Code/go/src/github.com/Masterminds/glide/vendor/github.com/codegangsta/cli) 254 github.com/Masterminds/cookoo (/Users/mfarina/Code/go/src/github.com/Masterminds/glide/vendor/github.com/Masterminds/cookoo) 255 github.com/Masterminds/cookoo/io (/Users/mfarina/Code/go/src/github.com/Masterminds/glide/vendor/github.com/Masterminds/cookoo/io) 256 github.com/Masterminds/glide/gb (/Users/mfarina/Code/go/src/github.com/Masterminds/glide/gb) 257 github.com/Masterminds/glide/util (/Users/mfarina/Code/go/src/github.com/Masterminds/glide/util) 258 github.com/Masterminds/vcs (/Users/mfarina/Code/go/src/github.com/Masterminds/glide/vendor/github.com/Masterminds/vcs) 259 github.com/Masterminds/glide/yaml (/Users/mfarina/Code/go/src/github.com/Masterminds/glide/yaml) 260 github.com/Masterminds/glide/util (/Users/mfarina/Code/go/src/github.com/Masterminds/glide/util) 261 github.com/Masterminds/vcs (/Users/mfarina/Code/go/src/github.com/Masterminds/glide/vendor/github.com/Masterminds/vcs) 262 github.com/Masterminds/vcs (/Users/mfarina/Code/go/src/github.com/Masterminds/glide/vendor/github.com/Masterminds/vcs) 263 gopkg.in/yaml.v2 (/Users/mfarina/Code/go/src/gopkg.in/yaml.v2) 264 github.com/Masterminds/semver (/Users/mfarina/Code/go/src/github.com/Masterminds/glide/vendor/github.com/Masterminds/semver) 265 github.com/Masterminds/vcs (/Users/mfarina/Code/go/src/github.com/Masterminds/glide/vendor/github.com/Masterminds/vcs) 266 github.com/codegangsta/cli (/Users/mfarina/Code/go/src/github.com/Masterminds/glide/vendor/github.com/codegangsta/cli) 267 ``` 268 269 This shows a tree of imports, excluding core libraries. Because 270 vendoring makes it possible for the same package to live in multiple 271 places, `glide tree` also prints the location of the package being 272 imported. 273 274 ### glide list 275 276 Glide's `list` command shows an alphabetized list of all the packages 277 that a project imports. 278 279 ``` 280 $ glide list 281 INSTALLED packages: 282 vendor/github.com/Masterminds/cookoo 283 vendor/github.com/Masterminds/cookoo/fmt 284 vendor/github.com/Masterminds/cookoo/io 285 vendor/github.com/Masterminds/cookoo/web 286 vendor/github.com/Masterminds/semver 287 vendor/github.com/Masterminds/vcs 288 vendor/github.com/codegangsta/cli 289 vendor/gopkg.in/yaml.v2 290 ``` 291 292 ### glide help 293 294 Print the glide help. 295 296 ``` 297 $ glide help 298 ``` 299 300 ### glide --version 301 302 Print the version and exit. 303 304 ``` 305 $ glide --version 306 glide version 0.8.0 307 ``` 308 309 ### glide.yaml 310 311 The `glide.yaml` file does two critical things: 312 313 1. It names the current package 314 2. It declares external dependencies 315 316 A brief `glide.yaml` file looks like this: 317 318 ```yaml 319 package: github.com/Masterminds/glide 320 import: 321 - package: github.com/Masterminds/semver 322 - package: github.com/Masterminds/cookoo 323 vcs: git 324 version: ^1.2.0 325 repo: git@github.com:Masterminds/cookoo.git 326 ``` 327 328 The above tells `glide` that... 329 330 1. This package is named `github.com/Masterminds/glide` 331 2. That this package depends on two libraries. 332 333 334 The first library exemplifies a minimal package import. It merely gives 335 the fully qualified import path. 336 337 When Glide reads the definition for the second library, it will get the repo 338 from the source in `repo`, checkout the latest version between 1.2.0 and 2.0.0, 339 and put it in `github.com/Masterminds/cookoo` in the `vendor` directory. (Note 340 that `package` and `repo` can be completely different) 341 342 **TIP:** The version is either VCS dependent and can be anything that can be checked 343 out or a semantic version constraint that can be parsed by the [`github.com/ 344 Masterminds/semver`](https://github.com/Masterminds/semver) package. 345 For example, with Git this can be a branch, tag, or hash. This varies and 346 depends on what's supported in the VCS. 347 348 **TIP:** In general, you are advised to use the *base package name* for 349 importing a package, not a subpackage name. For example, use 350 `github.com/kylelemons/go-gypsy` and not 351 `github.com/kylelemons/go-gypsy/yaml`. 352 353 ### Controlling package and subpackage builds 354 355 In addition to fetching packages, Glide builds the packages with `go 356 install`. The YAML file can give special instructions about how to build 357 a package. Example: 358 359 ```yaml 360 package: github.com/technosophos/glide 361 import: 362 - package: github.com/kylelemons/go-gypsy 363 subpackages: 364 - yaml 365 - package: github.com/Masterminds/cookoo 366 subpackages: 367 - . 368 - cli 369 - web 370 - package: github.com/crowdmob/amz 371 subpackages: 372 - ... 373 ``` 374 375 According to the above, the following packages will be built: 376 377 1. The `go-gypsy/yaml` package 378 2. The `cookoo` package (`.`), along with `cookoo/web` and `cookoo/cli` 379 3. Everything in `amz` (`...`) 380 381 See the `docs/` folder for more examples. 382 383 ## Supported Version Control Systems 384 385 The Git, SVN, Mercurial (Hg), and Bzr source control systems are supported. This 386 happens through the [vcs package](https://github.com/masterminds/vcs). 387 388 ## Frequently Asked Questions (F.A.Q.) 389 390 #### Q: Why does Glide have the concept of sub-packages when Go doesn't? 391 392 In Go every directory is a package. This works well when you have one repo 393 containing all of your packages. When you have different packages in different 394 VCS locations things become a bit more complicated. A project containing a 395 collection of packages should be handled with the same information including 396 the version. By grouping packages this way we are able to manage the related 397 information. 398 399 #### Q: bzr (or hg) is not working the way I expected. Why? 400 401 These are works in progress, and may need some additional tuning. Please 402 take a look at the [vcs package](https://github.com/masterminds/vcs). If you 403 see a better way to handle it please let us know. 404 405 #### Q: Should I check `vendor/` into version control? 406 407 That's up to you. It's not necessary, but it may also cause you extra 408 work and lots of extra space in your VCS. There may also be unforeseen errors 409 ([see an example](https://github.com/mattfarina/golang-broken-vendor)). 410 411 #### Q: How do I import settings from GPM, Godep, gom or gb? 412 413 There are two parts to importing. 414 415 1. If a package you import has configuration for GPM, Godep, gom or gb Glide will 416 recursively install the dependencies automatically. 417 2. If you would like to import configuration from GPM, Godep, gom or gb to Glide see 418 the `glide import` command. For example, you can run `glide import godep` for 419 Glide to detect the projects Godep configuration and generate a `glide.yaml` 420 file for you. 421 422 Each of these will merge your existing `glide.yaml` file with the 423 dependencies it finds for those managers, and then emit the file as 424 output. **It will not overwrite your glide.yaml file.** 425 426 You can write it to file like this: 427 428 ``` 429 $ glide import godep -f glide.yaml 430 ``` 431 432 #### Q: Can Glide fetch a package based on OS or Arch? 433 434 A: Yes. Using the `os` and `arch` fields on a `package`, you can specify 435 which OSes and architectures the package should be fetched for. For 436 example, the following package will only be fetched for 64-bit 437 Darwin/OSX systems: 438 439 ```yaml 440 - package: some/package 441 os: 442 - darwin 443 arch: 444 - amd64 445 ``` 446 447 The package will not be fetched for other architectures or OSes. 448 449 ## LICENSE 450 451 This package is made available under an MIT-style license. See 452 LICENSE.txt. 453 454 ## Thanks! 455 456 We owe a huge debt of gratitude to the [GPM and 457 GVP](https://github.com/pote/gpm) projects, which 458 inspired many of the features of this package. If `glide` isn't the 459 right Go project manager for you, check out those. 460 461 The Composer (PHP), npm (JavaScript), and Bundler (Ruby) projects all 462 inspired various aspects of this tool, as well. 463 464 ## The Name 465 466 Aside from being catchy, "glide" is a contraction of "Go Elide". The 467 idea is to compress the tasks that normally take us lots of time into a 468 just a few seconds.