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