git-repo/docs/manifest_submodule.txt

repo Manifest Format (submodule)
================================

A repo manifest describes the structure of a repo client; that is
the directories that are visible and where they should be obtained
from with git.

The basic structure of a manifest is a bare Git repository holding
a 'gitmodules' file in the top level directory, and one or more
gitlink references pointing at commits from the referenced projects.
This is the same structure as used by 'git submodule'.

Manifests are inherently version controlled, since they are kept
within a Git repository.  Updates to manifests are automatically
obtained by clients during `repo sync`.

.gitmodules
===========

The '.gitmodules' file, located in the top-level directory of the
client's working tree (or manifest repository), is a text file with
a syntax matching the requirements of 'git config'.

This file contains one subsection per project (also called a
submodule by git), and the subsection value is a unique name to
describe the project. Each submodule section must contain the
following required keys:

  * path
  * url

submodule.<name>.path
---------------------

Defines the path, relative to the top-level directory of the client's
working tree, where the project is expected to be checked out. The
path name must not end with a '/'. All paths must be unique within
the .gitmodules file.

At the specified path within the manifest repository a gitlink
tree entry (an entry with file mode 160000) must exist referencing
a commit SHA-1 from the project.  This tree entry specifies the
exact version of the project that `repo sync` will synchronize the
client's working tree to.

submodule.<name>.url
--------------------

Defines a URL from where the project repository can be cloned.
By default `repo sync` will clone from this URL whenever a user
needs to access this project.

submodule.<name>.revision
-------------------------

Name of the branch in the project repository that Gerrit Code Review
should automatically refresh the project's gitlink entry from.

If set, during submit of a change within the referenced project,
Gerrit Code Review will automatically update the manifest
repository's corresponding gitlink to the new commit SHA-1 of
this branch.

Valid values are a short branch name (e.g. 'master'), a full ref
name (e.g. 'refs/heads/master'), or '.' to request using the same
branch name as the manifest branch itself.  Since '.' automatically
uses the manifest branch, '.' is the recommended value.

If this key is not set, Gerrit Code Review will NOT automatically
update the gitlink. An unset key requires the manifest maintainer
to manually update the gitlink when it is necessary to reference
a different revision of the project.

submodule.<name>.update
-----------------------

This key is not supported by repo.  If set, it will be ignored.

repo.notice
-----------

A message displayed when repo sync uses this manifest.


.review
=======

The optional '.review' file, located in the top-level directory of
the client's working tree (or manifest repository), is a text file
with a syntax matching the requirements of 'git config'.

This file describes how `repo upload` should interact with the
project's preferred code review system.

review.url
----------

URL of the default Gerrit Code Review server.  If a project does
not have a specific URL in the '.review' file, this default URL
will be used instead.

review.<name>.url
-----------------

Project specific URL of the Gerrit Code Review server, for the
submodule whose project name is <name>.

Example
=======

  $ cat .gitmodules
  [submodule "app/Clock"]
    path = clock
    url = git://vcs.example.com/ClockWidget.git
    revision = .
  [submodule "app/Browser"]
    path = net/browser
    url = git://netgroup.example.com/network/web/Browser.git
    revision = .

  $ cat .review
  [review]
    url = vcs-gerrit.example.com
  [review "app/Browser"]
    url = netgroup.example.com

In the above example, the app/Clock project will send its code
reviews to the default server, vcs-gerrit.example.com, while
app/Browser will send its code reviews to netgroup.example.com.

See Also
========

 * http://www.kernel.org/pub/software/scm/git/docs/gitmodules.html
 * http://www.kernel.org/pub/software/scm/git/docs/git-config.html
 * http://code.google.com/p/gerrit/
Introduce manifest format using git submodules If a manifest top level directory contains '.gitmodules' we now assume this is a git module format manifest and switch to using that code, rather than the legacy XML based manifest. At the same time, we move the bare repository for a project from $TOP/.repo/projects/$REPO_PATH.git to be $REPO_NAME.git instead. This makes it easier for us to later support a repo init from an existing work tree, as we can more accurately predict the path of the project's repository in the workspace. It also means that the $TOP/.repo/projects/ directory is layed out like a mirror would be. Signed-off-by: Shawn O. Pearce <sop@google.com> 2009-07-04 01:05:23 +00:00			`repo Manifest Format (submodule)`
			`================================`

			`A repo manifest describes the structure of a repo client; that is`
			`the directories that are visible and where they should be obtained`
			`from with git.`

			`The basic structure of a manifest is a bare Git repository holding`
			`a 'gitmodules' file in the top level directory, and one or more`
			`gitlink references pointing at commits from the referenced projects.`
			`This is the same structure as used by 'git submodule'.`

			`Manifests are inherently version controlled, since they are kept`
			`within a Git repository. Updates to manifests are automatically`
			obtained by clients during `repo sync`.

			`.gitmodules`
			`===========`

			`The '.gitmodules' file, located in the top-level directory of the`
			`client's working tree (or manifest repository), is a text file with`
			`a syntax matching the requirements of 'git config'.`

			`This file contains one subsection per project (also called a`
			`submodule by git), and the subsection value is a unique name to`
			`describe the project. Each submodule section must contain the`
			`following required keys:`

			`* path`
			`* url`

			`submodule.<name>.path`
			`---------------------`

			`Defines the path, relative to the top-level directory of the client's`
			`working tree, where the project is expected to be checked out. The`
			`path name must not end with a '/'. All paths must be unique within`
			`the .gitmodules file.`

			`At the specified path within the manifest repository a gitlink`
			`tree entry (an entry with file mode 160000) must exist referencing`
			`a commit SHA-1 from the project. This tree entry specifies the`
			exact version of the project that `repo sync` will synchronize the
			`client's working tree to.`

			`submodule.<name>.url`
			`--------------------`

			`Defines a URL from where the project repository can be cloned.`
			By default `repo sync` will clone from this URL whenever a user
			`needs to access this project.`

			`submodule.<name>.revision`
			`-------------------------`

			`Name of the branch in the project repository that Gerrit Code Review`
			`should automatically refresh the project's gitlink entry from.`

			`If set, during submit of a change within the referenced project,`
			`Gerrit Code Review will automatically update the manifest`
			`repository's corresponding gitlink to the new commit SHA-1 of`
			`this branch.`

			`Valid values are a short branch name (e.g. 'master'), a full ref`
			`name (e.g. 'refs/heads/master'), or '.' to request using the same`
			`branch name as the manifest branch itself. Since '.' automatically`
			`uses the manifest branch, '.' is the recommended value.`

			`If this key is not set, Gerrit Code Review will NOT automatically`
			`update the gitlink. An unset key requires the manifest maintainer`
			`to manually update the gitlink when it is necessary to reference`
			`a different revision of the project.`

			`submodule.<name>.update`
			`-----------------------`

			`This key is not supported by repo. If set, it will be ignored.`

Merge branch 'stable' * stable: (33 commits) Added feature to print a <notice> from manifest at the end of a sync. sync: Use --force-broken to continue other projects upload: Remove --replace option sync --quiet: be more quiet sync: Enable use of git clone --reference Only delete corrupt pickle config files if they exist Don't allow git fetch to start ControlMaster Check for existing SSH ControlMaster Fix for handling values of EDITOR which contain a space. upload: Fix --replace flag rebase: Pass through more options upload: Allow review.HOST.username to override email upload -t: Automatically include local branch name Warn users before uploading if there are local changes sync: Try fetching a tag as a last resort before giving up rebase: Automatically rebase branch on upstrea upload: Automatically --cc folks in review.URL.autocopy Fix format string bugs in grep Do not invoke ssh with -p argument when no port has been specified. Allow files to be copied into new folders ... Conflicts: git_config.py manifest_xml.py subcmds/init.py subcmds/sync.py subcmds/upload.py Change-Id: I4756a6908277e91505c35287a122a775b68f4df5 2010-12-07 18:31:19 +00:00			`repo.notice`
			`-----------`

			`A message displayed when repo sync uses this manifest.`


Introduce manifest format using git submodules If a manifest top level directory contains '.gitmodules' we now assume this is a git module format manifest and switch to using that code, rather than the legacy XML based manifest. At the same time, we move the bare repository for a project from $TOP/.repo/projects/$REPO_PATH.git to be $REPO_NAME.git instead. This makes it easier for us to later support a repo init from an existing work tree, as we can more accurately predict the path of the project's repository in the workspace. It also means that the $TOP/.repo/projects/ directory is layed out like a mirror would be. Signed-off-by: Shawn O. Pearce <sop@google.com> 2009-07-04 01:05:23 +00:00			`.review`
			`=======`

			`The optional '.review' file, located in the top-level directory of`
			`the client's working tree (or manifest repository), is a text file`
			`with a syntax matching the requirements of 'git config'.`

			This file describes how `repo upload` should interact with the
			`project's preferred code review system.`

			`review.url`
			`----------`

			`URL of the default Gerrit Code Review server. If a project does`
			`not have a specific URL in the '.review' file, this default URL`
			`will be used instead.`

			`review.<name>.url`
			`-----------------`

			`Project specific URL of the Gerrit Code Review server, for the`
			`submodule whose project name is <name>.`

			`Example`
			`=======`

			`$ cat .gitmodules`
			`[submodule "app/Clock"]`
			`path = clock`
			`url = git://vcs.example.com/ClockWidget.git`
			`revision = .`
			`[submodule "app/Browser"]`
			`path = net/browser`
			`url = git://netgroup.example.com/network/web/Browser.git`
			`revision = .`

			`$ cat .review`
			`[review]`
			`url = vcs-gerrit.example.com`
			`[review "app/Browser"]`
			`url = netgroup.example.com`

			`In the above example, the app/Clock project will send its code`
			`reviews to the default server, vcs-gerrit.example.com, while`
			`app/Browser will send its code reviews to netgroup.example.com.`

			`See Also`
			`========`

			`* http://www.kernel.org/pub/software/scm/git/docs/gitmodules.html`
			`* http://www.kernel.org/pub/software/scm/git/docs/git-config.html`
			`* http://code.google.com/p/gerrit/`