go.fuchsia.dev/jiri@v0.0.0-20240502161911-b66513b29486/manifest.md (about)

     1  # Jiri Manifest
     2  
     3  Jiri manifest files describe the set of projects that get synced when running "jiri update".
     4  
     5  The first manifest file that jiri reads is in [root]/.jiri\_manifest.  This root manifest
     6  **must** exist for the jiri tool to work.
     7  
     8  Usually the manifest in [root]/.jiri\_manifest will import other manifests from remote repositories via <import> tags, but it can contain its own list of projects as well.
     9  
    10  Manifests have the following XML schema:
    11  ```
    12  <manifest>
    13    <imports>
    14      <import remote="https://vanadium.googlesource.com/manifest"
    15              manifest="public"
    16              name="manifest"
    17      />
    18      <localimport file="/path/to/local/manifest"/>
    19      ...
    20    </imports>
    21    <projects>
    22      <project name="my-project"
    23               path="path/where/project/lives"
    24               protocol="git"
    25               remote="https://github.com/myorg/foo"
    26               revision="ed42c05d8688ab23"
    27               remotebranch="my-branch"
    28               gerrithost="https://myorg-review.googlesource.com"
    29               githooks="path/to/githooks-dir"
    30               gitsubmodules="true"
    31      />
    32      ...
    33    </projects>
    34    <packages>
    35      <package name="package/path"
    36               version="version"
    37               path="path/to/directory"
    38               internal="true"
    39               platforms="os-arch1,os-arch2..."
    40               attributes="attr1,attr2,..."
    41               flag="filename|content_successful|content_failed"
    42      />
    43      ...
    44    </packages>
    45    <overrides>
    46      <project ... />
    47    </overrides>
    48    <hooks>
    49      <hook name="update"
    50            project="mojo/public"
    51            action="update.sh"/>
    52      ...
    53    </hooks>
    54  
    55  </manifest>
    56  ```
    57  The &lt;import> and &lt;localimport> tags can be used to share common projects across multiple manifests.
    58  
    59  A &lt;localimport> tag should be used when the manifest being imported and the importing manifest are both in the same repository, or when neither one is in a repository.  The "file" attribute is the path to the
    60  manifest file being imported.  It can be absolute, or relative to the importing manifest file.
    61  
    62  If the manifest being imported and the importing manifest are in different repositories then an &lt;import> tag must be used, with the following attributes:
    63  
    64  * remote (required) - The remote url of the repository containing the manifest to be imported
    65  
    66  * manifest (required) - The path of the manifest file to be imported, relative to the repository root.
    67  
    68  * name (optional) - The name of the project corresponding to the manifest repository.  If your manifest contains a &lt;project> with the same remote as the manifest remote, then the "name" attribute of on the
    69  &lt;import> tag should match the "name" attribute on the &lt;project>.  Otherwise, jiri will clone the manifest repository on every update.
    70  
    71  The &lt;project> tags describe the projects to sync, and what state they should sync to, according to the following attributes:
    72  
    73  * name (required) - The name of the project.
    74  
    75  * path (required) - The location where the project will be located, relative to the jiri root.
    76  
    77  * remote (required) - The remote url of the project repository.
    78  
    79  * protocol (optional) - The protocol to use when cloning and syncing the repo. Currently "git" is the default and only supported protocol.
    80  
    81  * remotebranch (optional) - The remote branch that the project will sync to. Defaults to "main".  The "remotebranch" attribute is ignored if "revision" is specified.
    82  
    83  * revision (optional) - The specific revision (usually a git SHA) that the project will sync to.  If "revision" is  specified then the "remotebranch" attribute is ignored.
    84  
    85  * gerrithost (optional) - The url of the Gerrit host for the project.  If specified, then running "jiri cl upload" will upload a CL to this Gerrit host.
    86  
    87  * githooks (optional) - The path (relative to the jiri root) of a directory containing git hooks that will be installed in the projects .git/hooks directory during each update.
    88  
    89  * gitsubmodules (optional) - Whether the project has git submodules (https://git-scm.com/book/en/v2/Git-Tools-Submodules), this attribute needs to be set to `true`. By default it is `false`.
    90  
    91  * gitsubmoduleof (optional) - The superproject that the project is a part of when submodules are enabled. If specified and the superproject enabled for submodules, jiri will delete the project from the tree and add it as a submodule. By default it is empty.
    92  
    93  The &lt;packages> tags describe the CIPD packages to sync, and what version they should sync to, according to the following attributes:
    94  
    95  * name (required) - The CIPD path of the package.
    96  
    97  * version (required) - The version tag of the CIPD package. Floating refs are not recommended.
    98  
    99  * path (optional) - The local path this package should be stored. It should be a relative path based on `JIRI_ROOT`. If the manifest does not define this attribute, it will be put into `JIRI_ROOT/prebuilt` directory. Jiri allows the path to be platform specific, for example `path="buildtools/{{.OS}}-{{.Arch}}"`, if run jiri under linux-amd64, it will be expanded to `path="buildtools/linux-amd64"`
   100  
   101  * internal (optional) - Whether the package is accessible to the public. If a cipd package requires explicit permissions such as packages under fuchsia_internal, this attribute needs to be set to `true`. By default it is `false`.
   102  
   103  * platforms (optional) - The platforms supported by the package. By default, it is set to `linux-amd64,mac-amd64`. However, if this package supports other platforms, e.g. `linux-arm64`, this attribute needs to be explicitly defined.
   104  
   105  * attributes (optional) - If this is set for a package, it will not be fetched by default. These packages can be included by setting optional attributes using `jiri init -fetch-optional=attr1,attr2`.
   106  
   107  * flag (optional) - The flag needs to be written by jiri when this package is successfully fetched. The flag attribute has a format of `filename|content_successful|content_failed` When a package is successfully downloaded, jiri will write `content_succeful` to filename. If the package is not downloaded due to access reasons, jiri will write `content_failed` to filename.
   108  
   109  The projects in the &lt;overrides> tag replace existing projects defined by in the &lt;projects> tag (and from transitively imported &lt;projects> tags).
   110  Only the root manifest can contain overrides and repositories referenced using the
   111  &lt;import> tag (including from transitive imports) cannot be overridden.
   112  
   113  The &lt;hook> tag describes the hooks that must be executed after every 'jiri update' They are configured via the following attributes:
   114  
   115  * name (required) - The name of the of the hook to identify it
   116  
   117  * project (required) - The name of the project where the hook is present
   118  
   119  * action (required) - Action to be performed inside the project. It is mostly identified by a script