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