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