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