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