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