github.com/tonyghita/glide@v0.13.2-0.20171214012703-3e13fd16ed5b/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) 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 21 The Go community now has the [dep](https://github.com/golang/dep) project to 22 manage dependencies. Please consider trying to migrate from Glide to dep. If there 23 is an issue preventing you from migrating please file an issue with dep so the 24 problem can be corrected. Glide will continue to be supported for some time but 25 is 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 50 Glide scans the source code of your application or library to determine the needed 51 dependencies. To determine the versions and locations (such as aliases for forks) 52 Glide reads a `glide.yaml` file with the rules. With this information Glide retrieves 53 needed dependencies. 54 55 When a dependent package is encountered its imports are scanned to determine 56 dependencies of dependencies (transitive dependencies). If the dependent project 57 contains a `glide.yaml` file that information is used to help determine the 58 dependency rules when fetching from a location or version to use. Configuration 59 from Godep, GB, GOM, and GPM is also imported. 60 61 The dependencies are exported to the `vendor/` directory where the `go` tools 62 can find and use them. A `glide.lock` file is generated containing all the 63 dependencies, including transitive ones. 64 65 The `glide init` command can be use to setup a new project, `glide update` 66 regenerates the dependency versions using scanning and rules, and `glide install` 67 will install the versions listed in the `glide.lock` file, skipping scanning, 68 unless the `glide.lock` file is not found in which case it will perform an update. 69 70 A 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) 94 to see this philosophy in action.* 95 96 ## Install 97 98 The easiest way to install the latest release on Mac or Linux is with the following script: 99 100 ``` 101 curl https://glide.sh/get | sh 102 ``` 103 104 On 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 110 On Ubuntu Precise (12.04), Trusty (14.04), Wily (15.10) or Xenial (16.04) you can install from our PPA: 111 112 ``` 113 sudo add-apt-repository ppa:masterminds/glide && sudo apt-get update 114 sudo apt-get install glide 115 ``` 116 117 On 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 121 For a development version it is also possible to `go get github.com/Masterminds/glide`. 122 123 To build from source you can: 124 125 1. Clone this repository into `$GOPATH/src/github.com/Masterminds/glide` and 126 change directory into it 127 2. 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. 130 3. Run `make build` 131 132 This will leave you with `./glide`, which you can put in your `$PATH` if 133 you'd like. (You can also take a look at `make install` to install for 134 you.) 135 136 The Glide repo has now been configured to use glide to 137 manage 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 151 Check out the `glide.yaml` in this directory, or examples in the `docs/` 152 directory. 153 154 ### glide create (aliased to init) 155 156 Initialize a new workspace. Among other things, this creates a `glide.yaml` file 157 while attempting to guess the packages and versions to put in it. For example, 158 if your project is using Godep it will use the versions specified there. Glide 159 is smart enough to scan your codebase and detect the imports being used whether 160 they 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)? 175 n 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 182 The `config-wizard`, noted here, can be run here or manually run at a later time. 183 This wizard helps you figure out versions and ranges you can use for your 184 dependencies. 185 186 ### glide config-wizard 187 188 This runs a wizard that scans your dependencies and retrieves information on them 189 to offer up suggestions that you can interactively choose. For example, it can 190 discover if a dependency uses semantic versions and help you choose the version 191 ranges to use. 192 193 ### glide get [package name] 194 195 You 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 202 When `glide get` is used it will introspect the listed package to resolve its 203 dependencies including using Godep, GPM, Gom, and GB config files. 204 205 ### glide update (aliased to up) 206 207 Download or update all of the libraries listed in the `glide.yaml` file and put 208 them in the `vendor` directory. It will also recursively walk through the 209 dependency packages to fetch anything that's needed and read in any configuration. 210 211 ``` 212 $ glide up 213 ``` 214 215 This will recurse over the packages looking for other projects managed by Glide, 216 Godep, gb, gom, and GPM. When one is found those packages will be installed as needed. 217 218 A `glide.lock` file will be created or updated with the dependencies pinned to 219 specific versions. For example, if in the `glide.yaml` file a version was 220 specified as a range (e.g., `^1.2.3`) it will be set to a specific commit id in 221 the `glide.lock` file. That allows for reproducible installs (see `glide install`). 222 223 To remove any nested `vendor/` directories from fetched packages see the `-v` flag. 224 225 ### glide install 226 227 When you want to install the specific versions from the `glide.lock` file use 228 `glide install`. 229 230 ``` 231 $ glide install 232 ``` 233 234 This will read the `glide.lock` file and install the commit id specific versions 235 there. 236 237 When the `glide.lock` file doesn't tie to the `glide.yaml` file, such as there 238 being a change, it will provide a warning. Running `glide up` will recreate the 239 `glide.lock` file when updating the dependency tree. 240 241 If no `glide.lock` file is present `glide install` will perform an `update` and 242 generate a lock file. 243 244 To remove any nested `vendor/` directories from fetched packages see the `-v` flag. 245 246 ## glide novendor (aliased to nv) 247 248 When you run commands like `go test ./...` it will iterate over all the 249 subdirectories including the `vendor` directory. When you are testing your 250 application you may want to test your application files without running all the 251 tests of your dependencies and their dependencies. This is where the `novendor` 252 command comes in. It lists all of the directories except `vendor`. 253 254 $ go test $(glide novendor) 255 256 This will run `go test` over all directories of your project except the 257 `vendor` directory. 258 259 ## glide name 260 261 When you're scripting with Glide there are occasions where you need to know 262 the name of the package you're working on. `glide name` returns the name of the 263 package listed in the `glide.yaml` file. 264 265 ### glide tree 266 267 Glide includes a few commands that inspect code and give you details 268 about what is imported. `glide tree` is one such command. Running it 269 gives data like this: 270 271 ``` 272 $ glide tree 273 github.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 306 This shows a tree of imports, excluding core libraries. Because 307 vendoring makes it possible for the same package to live in multiple 308 places, `glide tree` also prints the location of the package being 309 imported. 310 311 _This command is deprecated and will be removed in the near future._ 312 313 ### glide list 314 315 Glide's `list` command shows an alphabetized list of all the packages 316 that a project imports. 317 318 ``` 319 $ glide list 320 INSTALLED 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 333 Print the glide help. 334 335 ``` 336 $ glide help 337 ``` 338 339 ### glide --version 340 341 Print the version and exit. 342 343 ``` 344 $ glide --version 345 glide version 0.12.0 346 ``` 347 348 ### glide.yaml 349 350 For full details on the `glide.yaml` files see [the documentation](https://glide.sh/docs/glide.yaml). 351 352 The `glide.yaml` file does two critical things: 353 354 1. It names the current package 355 2. It declares external dependencies 356 357 A brief `glide.yaml` file looks like this: 358 359 ```yaml 360 package: github.com/Masterminds/glide 361 import: 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 368 The above tells `glide` that... 369 370 1. This package is named `github.com/Masterminds/glide` 371 2. That this package depends on two libraries. 372 373 The first library exemplifies a minimal package import. It merely gives 374 the fully qualified import path. 375 376 When Glide reads the definition for the second library, it will get the repo 377 from the source in `repo`, checkout the latest version between 1.2.0 and 2.0.0, 378 and put it in `github.com/Masterminds/cookoo` in the `vendor` directory. (Note 379 that `package` and `repo` can be completely different) 380 381 **TIP:** The version is either VCS dependent and can be anything that can be checked 382 out or a semantic version constraint that can be parsed by the [`github.com/ 383 Masterminds/semver`](https://github.com/Masterminds/semver) package. 384 For example, with Git this can be a branch, tag, or hash. This varies and 385 depends on what's supported in the VCS. 386 387 **TIP:** In general, you are advised to use the *base package name* for 388 importing 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 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.