java/Documentation/about.md

SUMMARY
=======

The SuperManifest plugin is for projects that use the 'repo' tool to piece
together a tree of git repositories. The repo tool reads an XML file that
describes the layout of the tree.

The file is usually called `default.xml`, and the repository is usually called
`manifest`.

Notable projects that use 'repo' include the Android Open Source Project.

The plugin will update a superproject to contain the submodules defined in the
manifest XML file whenever the manifest repo is changed.


CONFIGURATION
=============

It should be configured by adding `supermanifest.config` to the
`All-Projects` project. The format for configuration is as follows:


```
[superproject "submodules:refs/heads/nyc"]
   srcRepo = platforms/manifest
   srcRef = refs/heads/nyc
   srcPath = manifest.xml
   toolType = repo
```

this configures a repository called `submodules` to have a branch
`nyc`, for which the contents corresponds to the manifest file
`manifest.xml` on branch `refs/heads/nyc` in project `platforms/manifest`.

valid value(s) for `toolType` right now is `repo`. It can be left blank to
default to `repo`.

The plugin supports the following options:

*  `groups` (defaults to `default`). Sets the groups setting for JGit's
   RepoCommand

*  `recordSubmoduleLabels` (defaults to false). Sets recordSubmoduleLabels
   setting for JGit's RepoCommand

*  `ignoreRemoteFailures = true` (defaults to false). Sets ignoreRemoteFailures.
   Setting it true will cause repos that are not accessible to be ignored.


For the destination branch, you may also specify `refs/heads/*` to copy all
branches in the manifest repository. In this case the `srcRef` field is not
required (it will be ignored if present).

Branches that match the srcRef can still be skipped with the `exclude`
option. Its value is a comma-separated list of refs or ref patterns. Both of
them fully qualified (i.e. with the `refs/heads/` prefix). Note that git ref
patterns allow only one '*'.

```
[superproject "submodules:refs/heads/*"]
   srcRepo = platforms/manifest
   srcPath = manifest.xml
   exclude = refs/heads/ignoreme, refs/heads/*-release, refs/heads/auto-*
```

This plugin bypasses visibility restrictions, so edits to the manifest repo can
be used to reveal existence of hidden repositories or branches.


MANUAL TRIGGER
==============

Users that have the `administrateServer` permission may simulate an update to
the manifest repository. This is useful for debugging, and provides diagnostics
that are otherwise written into the server logs. To do so, issue the following
call

```sh
curl -X POST
  http://HOST/a/projects/platform%2Fmanifest/branches/master/update_manifest
```


JIRI
====

There is also support for the Jiri manifest file used in the Fuchsia OS.

```
[superproject "submodules:refs/heads/master"]
   srcRepo = platforms/manifest
   srcRef = refs/heads/master
   srcPath = manifest.xml
   toolType = jiri
```

TODO(anmittal): provide more documentation.