Updating the Readme for the 0.7.0 release
diff --git a/README.md b/README.md
index 2d93340..94c4f94 100644
--- a/README.md
+++ b/README.md
@@ -1,4 +1,4 @@
-# Glide: The Lightweight Vendor Package Manager
+# Glide: Vendor Package Management for Golang
*Manage your vendor and vendored packages with ease.* Glide is a tool for
managing the `vendor` directory within a Go package. This feature, first
@@ -13,9 +13,8 @@
* Ease dependency management
* Support **versioning packages** including [Semantic Versioning
- 2.0.0](http://semver.org/) support. Any constraint the [`github.com/
- Masterminds/semver`](https://github.com/Masterminds/semver) package can parse
- can be used.
+ 2.0.0](http://semver.org/) support. Any constraint the [`github.com/Masterminds/semver`](https://github.com/Masterminds/semver)
+ package can parse can be used.
* Support **aliasing packages** (e.g. for working with github forks)
* Remove the need for munging import statements
* Work with all of the `go` tools
@@ -26,6 +25,8 @@
- svn
* Support custom local and global plugins (see docs/plugins.md)
* Repository caching including reuse of packages in the `$GOPATH`
+* Flatten dependencies resolving version differences and avoiding the inclusion
+ of a package multiple times.
## How It Works
@@ -33,11 +34,11 @@
include a version, VCS, repository location (that can be different from the
package name), etc. When `glide up` is run it downloads the packages (or updates)
to the `vendor` directory. It then recursively walks through the downloaded
-packages looking for those with a `glide.yaml` file that don't already have
-a `vendor` directory and installing their dependencies to their `vendor`
-directories.
+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.
- A projects is structured like this:
+A projects is structured like this:
```
- $GOPATH/src/myProject (Your project)
@@ -141,17 +142,15 @@
$ glide up
```
-If the dependent vendor packages listed in your `glide.yaml` file use GPM or
-Godep you can use the `--import` flag to import them. If an import occurs a
-`vendor` directory will be created in each project with with dependencies being
-imported. A `glide.yaml` file will also be created for each project.
+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.
## glide novendor (aliased to nv)
When you run commands like `go test ./...` it will iterate over all the
subdirectories including the `vendor` directory. When you are testing your
application you may want to test your application files without running all the
-tests of your dependencies and their dependencies. This is where the novendor
+tests of your dependencies and their dependencies. This is where the `novendor`
command comes in. It lists all of the directories except `vendor`.
$ go test $(glide novendor)
@@ -192,15 +191,36 @@
```
$ glide tree
github.com/Masterminds/glide
- github.com/Masterminds/cookoo (/Users/mbutcher/Code/Go/src/github.com/Masterminds/glide/vendor/github.com/Masterminds/cookoo)
- github.com/Masterminds/cookoo/io (/Users/mbutcher/Code/Go/src/github.com/Masterminds/glide/vendor/github.com/Masterminds/cookoo/io)
- github.com/Masterminds/glide/cmd (/Users/mbutcher/Code/Go/src/github.com/Masterminds/glide/cmd)
- github.com/Masterminds/cookoo (/Users/mbutcher/Code/Go/src/github.com/Masterminds/glide/vendor/github.com/Masterminds/cookoo)
- github.com/Masterminds/cookoo/io (/Users/mbutcher/Code/Go/src/github.com/Masterminds/glide/vendor/github.com/Masterminds/cookoo/io)
- github.com/Masterminds/vcs (/Users/mbutcher/Code/Go/src/github.com/Masterminds/glide/vendor/github.com/Masterminds/vcs)
- github.com/codegangsta/cli (/Users/mbutcher/Code/Go/src/github.com/Masterminds/glide/vendor/github.com/codegangsta/cli)
- github.com/kylelemons/go-gypsy/yaml (/Users/mbutcher/Code/Go/src/github.com/Masterminds/glide/vendor/github.com/kylelemons/go-gypsy/yaml)
- github.com/codegangsta/cli (/Users/mbutcher/Code/Go/src/github.com/Masterminds/glide/vendor/github.com/codegangsta/cli)
+ github.com/Masterminds/cookoo (/Users/mfarina/Code/go/src/github.com/Masterminds/glide/vendor/github.com/Masterminds/cookoo)
+ github.com/Masterminds/cookoo/io (/Users/mfarina/Code/go/src/github.com/Masterminds/glide/vendor/github.com/Masterminds/cookoo/io)
+ github.com/Masterminds/glide/cmd (/Users/mfarina/Code/go/src/github.com/Masterminds/glide/cmd)
+ github.com/Masterminds/cookoo (/Users/mfarina/Code/go/src/github.com/Masterminds/glide/vendor/github.com/Masterminds/cookoo)
+ github.com/Masterminds/cookoo/io (/Users/mfarina/Code/go/src/github.com/Masterminds/glide/vendor/github.com/Masterminds/cookoo/io)
+ github.com/Masterminds/glide/gb (/Users/mfarina/Code/go/src/github.com/Masterminds/glide/gb)
+ github.com/Masterminds/glide/util (/Users/mfarina/Code/go/src/github.com/Masterminds/glide/util)
+ github.com/Masterminds/vcs (/Users/mfarina/Code/go/src/github.com/Masterminds/glide/vendor/github.com/Masterminds/vcs)
+ github.com/Masterminds/glide/yaml (/Users/mfarina/Code/go/src/github.com/Masterminds/glide/yaml)
+ github.com/Masterminds/glide/util (/Users/mfarina/Code/go/src/github.com/Masterminds/glide/util)
+ github.com/Masterminds/vcs (/Users/mfarina/Code/go/src/github.com/Masterminds/glide/vendor/github.com/Masterminds/vcs)
+ github.com/Masterminds/vcs (/Users/mfarina/Code/go/src/github.com/Masterminds/glide/vendor/github.com/Masterminds/vcs)
+ gopkg.in/yaml.v2 (/Users/mfarina/Code/go/src/gopkg.in/yaml.v2)
+ github.com/Masterminds/semver (/Users/mfarina/Code/go/src/github.com/Masterminds/glide/vendor/github.com/Masterminds/semver)
+ github.com/Masterminds/vcs (/Users/mfarina/Code/go/src/github.com/Masterminds/glide/vendor/github.com/Masterminds/vcs)
+ github.com/codegangsta/cli (/Users/mfarina/Code/go/src/github.com/Masterminds/glide/vendor/github.com/codegangsta/cli)
+ github.com/codegangsta/cli (/Users/mfarina/Code/go/src/github.com/Masterminds/glide/vendor/github.com/codegangsta/cli)
+ github.com/Masterminds/cookoo (/Users/mfarina/Code/go/src/github.com/Masterminds/glide/vendor/github.com/Masterminds/cookoo)
+ github.com/Masterminds/cookoo/io (/Users/mfarina/Code/go/src/github.com/Masterminds/glide/vendor/github.com/Masterminds/cookoo/io)
+ github.com/Masterminds/glide/gb (/Users/mfarina/Code/go/src/github.com/Masterminds/glide/gb)
+ github.com/Masterminds/glide/util (/Users/mfarina/Code/go/src/github.com/Masterminds/glide/util)
+ github.com/Masterminds/vcs (/Users/mfarina/Code/go/src/github.com/Masterminds/glide/vendor/github.com/Masterminds/vcs)
+ github.com/Masterminds/glide/yaml (/Users/mfarina/Code/go/src/github.com/Masterminds/glide/yaml)
+ github.com/Masterminds/glide/util (/Users/mfarina/Code/go/src/github.com/Masterminds/glide/util)
+ github.com/Masterminds/vcs (/Users/mfarina/Code/go/src/github.com/Masterminds/glide/vendor/github.com/Masterminds/vcs)
+ github.com/Masterminds/vcs (/Users/mfarina/Code/go/src/github.com/Masterminds/glide/vendor/github.com/Masterminds/vcs)
+ gopkg.in/yaml.v2 (/Users/mfarina/Code/go/src/gopkg.in/yaml.v2)
+ github.com/Masterminds/semver (/Users/mfarina/Code/go/src/github.com/Masterminds/glide/vendor/github.com/Masterminds/semver)
+ github.com/Masterminds/vcs (/Users/mfarina/Code/go/src/github.com/Masterminds/glide/vendor/github.com/Masterminds/vcs)
+ github.com/codegangsta/cli (/Users/mfarina/Code/go/src/github.com/Masterminds/glide/vendor/github.com/codegangsta/cli)
```
This shows a tree of imports, excluding core libraries. Because
@@ -215,16 +235,20 @@
```
$ glide list
-github.com/Masterminds/cookoo (Present: yes)
-github.com/Masterminds/cookoo/io (Present: yes)
-github.com/Masterminds/glide/cmd (Present: yes)
-github.com/Masterminds/vcs (Present: yes)
-github.com/codegangsta/cli (Present: yes)
-github.com/kylelemons/go-gypsy/yaml (Present: yes)
+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)
```
-If it finds a reference to a package that has not been installed,
-`Present` is set to `no`.
+The possible locations for `list` are `vendored`, `gopath`, and `missing` (if
+the package is not installed anywhere accessible).
### glide help
@@ -240,7 +264,7 @@
```
$ glide --version
-glide version 0.5.0
+glide version 0.7.0
```
### glide.yaml
@@ -255,10 +279,10 @@
```yaml
package: github.com/Masterminds/glide
import:
- - package: github.com/kylelemons/go-gypsy
+ - package: github.com/Masterminds/semver
- package: github.com/Masterminds/cookoo
vcs: git
- version: master
+ version: ^1.2.0
repo: git@github.com:Masterminds/cookoo.git
```
@@ -272,9 +296,9 @@
the fully qualified import path.
When Glide reads the definition for the second library, it will get the repo
-from the source in `repo`, checkout the master branch, and put it in
-`github.com/Masterminds/cookoo` in the `vendor` directory. (Note that `package`
-and `repo` can be completely different)
+from the source in `repo`, checkout the latest version between 1.2.0 and 2.0.0,
+and put it in `github.com/Masterminds/cookoo` in the `vendor` directory. (Note
+that `package` and `repo` can be completely different)
**TIP:** The version is either VCS dependent and can be anything that can be checked
out or a semantic version constraint that can be parsed by the [`github.com/
@@ -322,30 +346,28 @@
## Troubleshooting
-**Q: bzr (or hg) is not working the way I expected. Why?**
+#### Q: bzr (or hg) is not working the way I expected. Why?
These are works in progress, and may need some additional tuning. Please
take a look at the [vcs package](https://github.com/masterminds/vcs). If you
see a better way to handle it please let us know.
-**Q: Should I check `vendor/` into version control?**
+#### Q: Should I check `vendor/` into version control?
That's up to you. It's not necessary, but it may also cause you extra
-work and lots of extra space in your VCS.
+work and lots of extra space in your VCS. There may also be unforeseen errors
+([see an example](https://github.com/mattfarina/golang-broken-vendor)).
-**Q: How do I import settings from GPM or Godep?**
+#### Q: How do I import settings from GPM, Godep, or gb?
-There are two ways to approach importing. The first is when you use `glide up`
-or `glide get` there is an `--import` flag. It will attempt to import from GPM
-and Godep automatically. If fetching is happening recursively this will be
-applied to recursive packages as well.
+There are two parts to importing.
-Alternatively, Glide can import from GPM's `Godeps` file format or from Godep's
-`Godeps/Godeps.json` file format with the `import` command.
-
-For GPM, use `glide import gpm`.
-
-For Godep, use `glide import godep`.
+1. If a package you import has configuration for GPM, Godep, or gb Glide will
+ recursively install the dependencies automatically.
+2. If you would like to import configuration from GPM, Godep, or gb to Glide see
+ the `glide import` command. For example, you can run `glide import godep` for
+ Glide to detect the projects Godep configuration and generate a `glide.yaml`
+ file for you.
Each of these will merge your existing `glide.yaml` file with the
dependencies it finds for those managers, and then emit the file as
@@ -357,7 +379,7 @@
$ glide import godep > new-glide.yaml
```
-**Q: Can Glide fetch a package based on OS or Arch?**
+#### Q: Can Glide fetch a package based on OS or Arch?
A: Yes. Using the `os` and `arch` fields on a `package`, you can specify
which OSes and architectures the package should be fetched for. For
@@ -374,10 +396,6 @@
The package will not be fetched for other architectures or OSes.
-**Q: How do I prevent vendored packages from importing the same package**
-
-You can use the `flatten: true` config option on the entire project or just one specific dependency.
-
## LICENSE
This package is made available under an MIT-style license. See
