Update docs to recommend using a vendor subdirectory

README.md

@@ -37,7 +37,7 @@ $ python setup.py install
 Create a configuration file (`gitman.yml` or `.gitman.yml`) in the root of your working tree:
 
 ```yaml
-location: vendor
+location: vendor/gitman
 sources:
 - name: framework
   repo: https://github.com/kstenerud/iOS-Universal-Framework
@@ -51,7 +51,7 @@ sources:
 Ignore the dependency storage location:
 
 ```sh
-$ echo vendor >> .gitignore
+$ echo vendor/gitman >> .gitignore
 ```
 
 # Usage
@@ -72,9 +72,9 @@ $ gitman update
 
 which will essentially:
 
-1. create a working tree at _(root)_/`<location>`/`<name>`
+1. create a working tree at `<root>`/`<location>`/`<name>`
 2. fetch from `repo` and checkout the specified `rev`
-3. symbolically link each `<location>`/`<name>` from _(root)_/`<link>` (if specified)
+3. symbolically link each `<location>`/`<name>` from `<root>`/`<link>` (if specified)
 4. repeat for all nested working trees containing a configuration file
 5. record the actual commit SHAs that were checked out (with `--lock` option)
 

docs/use-cases/branch-tracking.md

@@ -7,7 +7,7 @@ One common use case of `gitman` is to track versions of related product sub-comp
 A web app's `gitman.yml` might look something like:
 
 ```yaml
-location: vendor
+location: vendor/gitman
 sources:
 - name: api
   repo: https://github.com/example/api
@@ -25,7 +25,7 @@ package.json
 node_modules
 
 gitman.yml
-vendor/api  # dependency @ b27308
+vendor/gitman/api  # dependency @ b27308
 
 app
 tests

docs/use-cases/build-integration.md

@@ -26,7 +26,7 @@ clean:
 using a configuration file similar to:
 
 ```yaml
-location: vendor
+location: vendor/gitman
 sources:
 - name: lib_foo
   repo: https://github.com/example/lib_foo

docs/use-cases/linked-features.md

@@ -8,7 +8,7 @@ Another use case of `gitman` is to test experimental versions of related product
 By manually modifying the `sources_locked` section, a particular version of the API can be checked out to help finish the complete feature in the web app:
 
 ```yaml
-location: vendor
+location: vendor/gitman
 sources:
 - name: api
   repo: https://github.com/example/api