From cabe1c2949777f9b25e772ad2f618909550531f2 Mon Sep 17 00:00:00 2001
From: Igor Wiedler <igor@wiedler.ch>
Date: Mon, 20 Feb 2012 01:04:35 +0100
Subject: [PATCH] [docs] add vcs repo section to repos chapter

---
 doc/04-schema.md       |  2 ++
 doc/05-repositories.md | 39 +++++++++++++++++++++++++++++++++++++--
 2 files changed, 39 insertions(+), 2 deletions(-)

diff --git a/doc/04-schema.md b/doc/04-schema.md
index 1d576c2ff..b48c5f798 100644
--- a/doc/04-schema.md
+++ b/doc/04-schema.md
@@ -252,6 +252,8 @@ Example:
 }
 ```
 
+> **Note:** Order is significant here. Repositories added later will take precedence. This also means that custom repositories can override packages that exist on packagist.
+
 You can also disable the packagist repository by setting `packagist` to `false`.
 
 ```json
diff --git a/doc/05-repositories.md b/doc/05-repositories.md
index 3a3e56fc7..3fb20f3a7 100644
--- a/doc/05-repositories.md
+++ b/doc/05-repositories.md
@@ -45,7 +45,7 @@ The main repository type is the `composer` repository. It uses a single `package
 }
 ```
 
-The `@composer.json` is the `composer.json` of that package version including as a minimum:
+The `@composer.json` marker would be the contents of the `composer.json` from that package version including as a minimum:
 
 * name
 * version
@@ -70,8 +70,43 @@ The `composer` repository is also what packagist uses. To reference a `composer`
 
 ### VCS
 
+VCS stands for version control system. This includes versioning systems like git, svn or hg. Composer has a repository type for installing packages from these systems.
+
+There are a few use cases for this. The most common one is maintaining your own fork of a third party library. If you are using a certain library for your project and you decide to change something in the library, you will want your project to use the patched version. If the library is on GitHub (this is the case most of the time), you can simply fork it there and push your changes to your fork. After that you update the project's `composer.json`. All you have to do is add your fork as a repository and update the version constraint to point to your custom branch.
+
+Example assuming you patched monolog to fix a bug in the `bugfix` branch:
+
+```json
+{
+    "repositories": [
+        {
+            "type": "vcs",
+            "url": "http://github.com/igorw/monolog"
+        }
+    ],
+    "require": {
+        "monolog/monolog": "dev-bugfix"
+    }
+}
+```
+
+When you run `php composer.phar update`, you should get your modified version of `monolog/monolog` instead of the one from packagist.
+
+Git is not the only version control system supported by the VCS repository. The following are supported:
+
+* **Git:** [git-scm.com](http://git-scm.com)
+* **Subversion:** [subversion.apache.org](http://subversion.apache.org)
+* **Mercurial:** [mercurial.selenic.com](http://mercurial.selenic.com)
+
+To use these systems you need to have them installed. That can be invonvenient. And for this reason there is special support for GitHub and BitBucket that use the APIs provided by these sites, to fetch the packages without having to install the version control system. The VCS repository provides `dist`s for them that fetch the packages as zips.
+
+* **GitHub:** [github.com](https://github.com) (Git)
+* **BitBucket:** [bitbucket.org](https://bitbucket.org) (Git and Mercurial)
+
+The VCS driver to be used is detected automatically based on the URL.
+
 ### PEAR
 
 ### Package
 
-## Hosting your own
\ No newline at end of file
+## Hosting your own