Updated docs for new lockfile features
diff --git a/README.md b/README.md index 7890c50..ebfd0fa 100644 --- a/README.md +++ b/README.md
@@ -1,5 +1,8 @@ # Glide: Vendor Package Management for Golang +Are you used to tools such as Cargo, npm, Composer, Nuget, Pip, Maven, Bunder, +or other modern package managers? If so, Glide is the comparable Go tool. + *Manage your vendor and vendored packages with ease.* Glide is a tool for managing the `vendor` directory within a Go package. This feature, first introduced in Go 1.5, allows each package to have a `vendor` directory @@ -36,7 +39,10 @@ to the `vendor` directory. It then recursively walks through the downloaded packages looking for those with a `glide.yaml` file (or Godep, gb, or GPM config file) that don't already have a `vendor` directory and installing their -dependencies to their `vendor` directories. +dependencies to their `vendor` directories. Once Glide has downloaded and figured +out versions to use in the dependency tree it creates a `glide.lock` file +containing the complete dependency tree pinned to specific versions. To install +the correct versions use `glide install`. A projects is structured like this: @@ -45,6 +51,8 @@ | |-- glide.yaml | + |-- glide.lock + | |-- main.go (Your main go code can live here) | |-- mySubpackage (You can create your own subpackages, too) @@ -102,40 +110,46 @@ Check out the `glide.yaml` in this directory, or examples in the `docs/` directory. -### glide create [optional package name] +### glide create (aliased to init) -Initialize a new workspace. Among other things, this creates a stub -`glide.yaml` +Initialize a new workspace. Among other things, this creates a `glide.yaml` file +while attempting to guess the packages and versions to put in it. For example, +if your project is using Godep it will use the versions specified there. Glide +is smart enough to scan your codebase and detect the imports being used whether +they are specified with another package manager or not. ``` $ glide create -[INFO] Initialized. You can now edit 'glide.yaml' +[INFO] Generating a YAML configuration file and guessing the dependencies +[INFO] Attempting to import from other package managers (use --skip-import to skip) +[INFO] Found reference to github.com/Sirupsen/logrus +[INFO] Adding sub-package hooks/syslog to github.com/Sirupsen/logrus +[INFO] Found reference to github.com/boltdb/bolt +[INFO] Found reference to github.com/gorilla/websocket +[INFO] Found reference to github.com/mndrix/ps +[INFO] Found reference to github.com/spf13/cobra +[INFO] Found reference to github.com/spf13/pflag +[INFO] Found reference to github.com/tinylib/msgp/msgp +[INFO] Found reference to github.com/unrolled/secure +[INFO] Found reference to github.com/xeipuuv/gojsonschema +[INFO] Found reference to github.com/zenazn/goji/graceful +[INFO] Adding sub-package web to github.com/zenazn/goji +[INFO] Adding sub-package web/mutil to github.com/zenazn/goji ``` -If an optional package name is specified, Glide will add it to -glide.yaml as the name of your project. - ### glide get [package name] -You can download package to your `vendor` directory and have it added to your +You can download one or more packages to your `vendor` directory and have it added to your `glide.yaml` file with `glide get`. ``` $ glide get github.com/Masterminds/cookoo ``` -### glide guess and glide pin +When `glide get` is used it will introspect the listed package to resolve its +dependencies including using Godep, GPM, and GB config files. -To help with the creating and managing your `glide.yaml` files there are two -more helper commands. The `glide guess` command will look over your project, -read the imports, attempt to intelligently guess at the ones you need to list, -and create the text for a `glide.yaml` file. - -There are times you need to pin a dependency to a version, such as when you're -preparing to deploy to production. For that case there is the `glide pin` command -that will pin each dependency in the `glide.yaml` file to the current commit id. - -### glide up (aliased to update and install) +### glide update (aliased to up) Download or update all of the libraries listed in the `glide.yaml` file and put them in the `vendor` directory. It will also recursively walk through the @@ -148,6 +162,30 @@ This will recurse over the packages looking for other projects managed by Glide, Godep, gb, and GPM. When one is found those packages will be installed as needed. +A `glide.lock` file will be created or updated with the dependencies pinned to +specific versions. For example, if in the `glide.yaml` file a version was +specified as a range (e.g., `^1.2.3`) it will be set to a specific commit id in +the `glide.lock` file. That allows for reproducible installs (see `glide install`). + +### glide install + +When you want to install the specific versions from the `glide.lock` file use +`glide install`. + +``` +$ glide install +``` + +This will read the `glide.lock` file, making sure it's tied to the `glide.yaml` +file, and install the commit id specific versions there. + +When the `glide.lock` file doesn't tie to the `glide.yaml` file, such as there +being a change, it will provide an error. Running `glide up` will recreate the +`glide.lock` file when updating the dependency tree. + +If no `glide.lock` file is present `glide install` will perform an `update` and +generate a lock file. + ## glide novendor (aliased to nv) When you run commands like `go test ./...` it will iterate over all the @@ -238,21 +276,17 @@ ``` $ glide list -github.com/Masterminds/cookoo (Location: vendored) -github.com/Masterminds/cookoo/io (Location: vendored) -github.com/Masterminds/glide/cmd (Location: gopath) -github.com/Masterminds/glide/gb (Location: gopath) -github.com/Masterminds/glide/util (Location: gopath) -github.com/Masterminds/glide/yaml (Location: gopath) -github.com/Masterminds/semver (Location: vendored) -github.com/Masterminds/vcs (Location: vendored) -github.com/codegangsta/cli (Location: vendored) -gopkg.in/yaml.v2 (Location: vendored) +INSTALLED packages: + vendor/github.com/Masterminds/cookoo + vendor/github.com/Masterminds/cookoo/fmt + vendor/github.com/Masterminds/cookoo/io + vendor/github.com/Masterminds/cookoo/web + vendor/github.com/Masterminds/semver + vendor/github.com/Masterminds/vcs + vendor/github.com/codegangsta/cli + vendor/gopkg.in/yaml.v2 ``` -The possible locations for `list` are `vendored`, `gopath`, and `missing` (if -the package is not installed anywhere accessible). - ### glide help Print the glide help. @@ -267,7 +301,7 @@ ``` $ glide --version -glide version 0.7.0 +glide version 0.8.0 ``` ### glide.yaml @@ -347,7 +381,16 @@ The Git, SVN, Mercurial (Hg), and Bzr source control systems are supported. This happens through the [vcs package](https://github.com/masterminds/vcs). -## Troubleshooting +## Frequently Asked Questions (F.A.Q.) + +#### Q: Why does Glide have the concept of sub-packages when Go doesn't? + +In Go every directory is a package. This works well when you have one repo +containing all of your packages. When you have different packages in different +VCS locations things become a bit more complicated. A project containing a +collection of packages should be handled with the same information including +the version. By grouping packages this way we are able to manage the related +information. #### Q: bzr (or hg) is not working the way I expected. Why? @@ -379,7 +422,7 @@ You can write it to file like this: ``` -$ glide import godep > new-glide.yaml +$ glide import godep -f glide.yaml ``` #### Q: Can Glide fetch a package based on OS or Arch?
diff --git a/glide.go b/glide.go index b0a064f..b568270 100644 --- a/glide.go +++ b/glide.go
@@ -145,7 +145,7 @@ }, { Name: "get", - Usage: "Install one or more package into `vendor/` and add dependency to glide.yaml.", + Usage: "Install one or more packages into `vendor/` and add dependency to glide.yaml.", Description: `Gets one or more package (like 'go get') and then adds that file to the glide.yaml file. Multiple package names can be specified on one line. @@ -154,19 +154,14 @@ The above will install the project github.com/Masterminds/cookoo and add the subpackage 'web'. - If a fetched dependency has a glide.yaml file, 'get' will also install - all of the dependencies for that dependency. Those are installed in a scoped - vendor directory. So dependency vendor/foo/bar has its dependencies stored - in vendor/foo/bar/vendor. This behavior can be disabled using - '--no-recursive' + If a fetched dependency has a glide.yaml file, configuration from Godep, + GPM, or GB Glide that configuration will be used to find the dependencies + and versions to fetch. If those are not available the dependent packages will + be fetched as either a version specified elsewhere or the latest version. - If '--import' is set, this will also read the dependency projects, looking - for gb, Godep and GPM files. When it finds them, it will build a comparable - glide.yaml file, and then fetch all of the necessary dependencies. The - dependencies are then vendored in the appropriate project. Subsequent calls - to 'glide up' will use the glide.yaml to maintain those dependencies. - However, only if you call 'glide up --import' will the glide file be - rebuilt. When '--no-recursive' is used, '--import' does nothing. + When adding a new dependency Glide will perform an update to work out the + the versions to use from the dependency tree. This will generate an updated + glide.lock file with specific locked versions to use. `, Flags: []cli.Flag{ cli.BoolFlag{