More docs
diff --git a/docs/glide.lock.md b/docs/glide.lock.md
new file mode 100644
index 0000000..b208dd0
--- /dev/null
+++ b/docs/glide.lock.md
@@ -0,0 +1,9 @@
+# The glide.lock File
+
+Where a [`glide.yaml`](glide.yaml.md) file contains the dependencies, versions (including ranges), and other configuration for the local codebase, the related `glide.lock` file contains the complete dependency tree and the revision (commit id) in use.
+
+Knowing the complete dependency tree is useful for Glide. For example, when the complete tree is known the `glide install` command can install and set the proper revision for multiple dependencies concurrently. This is a fast operation to reproducibly install the dependencies.
+
+The lock file also provides a record of the complete tree, beyond the needs of your codebase, and the revisions used. This is useful for things like audits or detecting what changed in a dependency tree when troubleshooting a problem.
+
+The details of this file are not included here as this file should not be edited by hand. If you know how to read the [`glide.yaml`](glide.yaml.md) file you'll be able to generally understand the `glide.lock` file.
diff --git a/docs/vendor.md b/docs/vendor.md
new file mode 100644
index 0000000..1429818
--- /dev/null
+++ b/docs/vendor.md
@@ -0,0 +1,34 @@
+# Vendor Directories
+
+With the release of Go 1.5 the `vendor/` directory was added to the resolution locations for a dependent package in addition to the `GOPATH` and `GOROOT`. Prior to Go 1.6 you needed to opt-in before Go would look there by setting the environment variable `GO15VENDOREXPERIMENT=1`. In Go 1.6 this is an opt-out feature.
+
+_Note, even if you use the `vendor/` directories your codebase needs to be inside the `GOPATH`. With the `go` toolchain there is no escaping the `GOPATH`._
+
+The resolution locations for a dependent package are:
+
+* The `vendor/` directory within the current package.
+* Walk up the directory tree looking for the package in a parents `vendor/` directory.
+* Look for the package in the `GOPATH`.
+* Use the package in the `GOROOT` (where the standard library package reside) if present.
+
+## Recommendations
+
+Having worked with the `vendor/` directories since they were first released we've come to some conclusions and recommendations. Glide tries to help you with these.
+
+1. Libraries (codebases without a `main` package) should not store outside packages in a `vendor/` folder in their VCS unless they have a specific reason and understand why they're doing it.
+2. In applications (codebases with a `main` package) there should only be one `vendor/` directory at the top level of the codebase.
+
+There are some important reasons for these recommendations.
+
+* Each instance of a package, even the same package at the same version, in the directory structure will be in the resulting binaries. If everyone stores their own dependencies separately this will quickly lead to **binary bloat**.
+* Instances of a type created from a package in one location are **not compatible** with the same package, even at the exact same version, in another location. [You can see for yourself](https://github.com/mattfarina/golang-broken-vendor). That means loggers, database connections, and other shared instances won't work.
+
+Because of this Glide flattens the dependency tree into a single top level `vendor/` directory. If a package happens to have some dependencies in their own `vendor/` folder the `go` tool will properly resolve that version.
+
+## Why Use A `vendor` Directory?
+
+If we already have the `GOPATH` to store packages why is there a need for a `vendor/` directory? This is a perfectly valid question.
+
+What if multiple applications in the `GOPATH` use different versions of the same package? This is a valid problem that's both been encountered in Go applications and widely seen in languages that have been around for a lot longer.
+
+The `vendor/` directory allows differing codebases to have their own version available without having to be concerned with another codebase that needs a different version interfering with the version it needs. It provides a level of separation for each project.
diff --git a/glide.lock b/glide.lock
index dfda814..8655963 100644
--- a/glide.lock
+++ b/glide.lock
@@ -1,10 +1,10 @@
-hash: 09ed62a4652e67d17dbdb38700da87fbb8717a839b7851323d9e2c1aacc49754
-updated: 2016-02-16T06:23:14.3545207-05:00
+hash: 9057b90e0cd3fac45ad563ea3d62a6e57c845e5c07e68e87b6fc14818574eb4f
+updated: 2016-02-17T09:11:15.318323635-05:00
imports:
- name: github.com/codegangsta/cli
- version: b5232bb2934f606f9f27a1305f1eea224e8e8b88
+ version: c31a7975863e7810c92e2e288a9ab074f9a88f29
- name: github.com/Masterminds/semver
- version: 6333b7bd29aad1d79898ff568fd90a8aa533ae82
+ version: 513f3dcb3ecfb1248831fb5cb06a23a3cd5935dc
- name: github.com/Masterminds/vcs
version: 9c0db6583837118d5df7c2ae38ab1c194e434b35
- name: gopkg.in/yaml.v2
diff --git a/glide.yaml b/glide.yaml
index 882f7dd..59e169d 100644
--- a/glide.yaml
+++ b/glide.yaml
@@ -1,5 +1,5 @@
package: github.com/Masterminds/glide
-homepage: https://github.com/Masterminds/glide
+homepage: https://glide.sh
license: MIT
owners:
- name: Matt Butcher
diff --git a/mkdocs.yml b/mkdocs.yml
index ac74ca7..3a0150d 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -4,6 +4,8 @@
- Getting Started: getting-started.md
- The glide.yaml File: glide.yaml.md
- Versions and Ranges: versions.md
+- Lock file: glide.lock.md
- Commands: commands.md
+- Vendor Directories: vendor.md
- F.A.Q.: faq.md
theme: readthedocs
