Add <add-remote to-project="..."> to inject additional remotes

This way users can add forks they know about to an existing project
that was already declared in the primary manifest.  This is mostly
useful with the Linux kernel project, where multiple forks is quite
common for the main upstream tree (e.g. Linus' tree), a platform
architecture tree (e.g. ARM) and a device specific tree (e.g. the
msm7k tree used by Android).

Signed-off-by: Shawn O. Pearce <sop@google.com>

1 files changed, 23 insertions, 1 deletions

diff --git a/docs/manifest-format.txt b/docs/manifest-format.txt
index 2b49d466..5c014d6d 100644
--- a/docs/manifest-format.txt
+++ b/docs/manifest-format.txt
@@ -20,7 +20,10 @@ A manifest XML file (e.g. 'default.xml') roughly conforms to the
 following DTD:
 
 <!DOCTYPE manifest [
-  <!ELEMENT manifest (remote*, default?, project*)>
+  <!ELEMENT manifest (remote*,
+                      default?,
+                      project*,
+                      add-remote*)>
 
   <!ELEMENT remote (EMPTY)>
   <!ATTLIST remote name         ID    #REQUIRED>
@@ -37,6 +40,13 @@ following DTD:
   <!ATTLIST project path     CDATA #IMPLIED>
   <!ATTLIST project remote   IDREF #IMPLIED>
   <!ATTLIST project revision CDATA #IMPLIED>
+
+  <!ELEMENT add-remote (EMPTY)>
+  <!ATTLIST add-remote to-project   ID    #REQUIRED>
+  <!ATTLIST add-remote name         ID    #REQUIRED>
+  <!ATTLIST add-remote fetch        CDATA #REQUIRED>
+  <!ATTLIST add-remote review       CDATA #IMPLIED>
+  <!ATTLIST add-remote project-name CDATA #IMPLIED>
 ]>
 
 A description of the elements and their attributes follows.
@@ -74,6 +84,18 @@ Only permitted when the remote element is nested inside of a project
 element (see below).  If not given, defaults to the name supplied
 in the project's name attribute.
 
+Element add-remote
+------------------
+
+Adds a remote to an existing project, whose name is given by the
+to-project attribute.  This is functionally equivalent to nesting
+a remote element under the project, but has the advantage that it
+can be specified in the uesr's `local_manifest.xml` to add a remote
+to a project declared by the normal manifest.
+
+The element can be used to add a fork of an existing project that
+the user needs to work with.
+
 
 Element default
 ---------------