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