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