From 3891b7519d35b6bac3e81744c846ca2ed0bd1be2 Mon Sep 17 00:00:00 2001 From: Mike Frysinger Date: Fri, 5 Oct 2018 19:26:15 -0400 Subject: manifest-format: convert to markdown The gitiles system doesn't render .txt files, so convert this to .md for better display online. Change-Id: Ie12e46daf008dd8c97ae2ffd21fb68bd948fe625 --- docs/manifest-format.md | 399 +++++++++++++++++++++++++++++++++++++++++++++++ docs/manifest-format.txt | 395 ---------------------------------------------- docs/repo-hooks.md | 2 +- 3 files changed, 400 insertions(+), 396 deletions(-) create mode 100644 docs/manifest-format.md delete mode 100644 docs/manifest-format.txt (limited to 'docs') diff --git a/docs/manifest-format.md b/docs/manifest-format.md new file mode 100644 index 00000000..cf48698d --- /dev/null +++ b/docs/manifest-format.md @@ -0,0 +1,399 @@ +repo Manifest Format +==================== + +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 single `default.xml` XML file in the top level directory. + +Manifests are inherently version controlled, since they are kept +within a Git repository. Updates to manifests are automatically +obtained by clients during `repo sync`. + +[TOC] + + +XML File Format +--------------- + +A manifest XML file (e.g. `default.xml`) roughly conforms to the +following DTD: + +```xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +]> +``` + +A description of the elements and their attributes follows. + + +Element manifest +---------------- + +The root element of the file. + + +Element remote +-------------- + +One or more remote elements may be specified. Each remote element +specifies a Git URL shared by one or more projects and (optionally) +the Gerrit review server those projects upload changes through. + +Attribute `name`: A short name unique to this manifest file. The +name specified here is used as the remote name in each project's +.git/config, and is therefore automatically available to commands +like `git fetch`, `git remote`, `git pull` and `git push`. + +Attribute `alias`: The alias, if specified, is used to override +`name` to be set as the remote name in each project's .git/config. +Its value can be duplicated while attribute `name` has to be unique +in the manifest file. This helps each project to be able to have +same remote name which actually points to different remote url. + +Attribute `fetch`: The Git URL prefix for all projects which use +this remote. Each project's name is appended to this prefix to +form the actual URL used to clone the project. + +Attribute `pushurl`: The Git "push" URL prefix for all projects +which use this remote. Each project's name is appended to this +prefix to form the actual URL used to "git push" the project. +This attribute is optional; if not specified then "git push" +will use the same URL as the `fetch` attribute. + +Attribute `review`: Hostname of the Gerrit server where reviews +are uploaded to by `repo upload`. This attribute is optional; +if not specified then `repo upload` will not function. + +Attribute `revision`: Name of a Git branch (e.g. `master` or +`refs/heads/master`). Remotes with their own revision will override +the default revision. + +Element default +--------------- + +At most one default element may be specified. Its remote and +revision attributes are used when a project element does not +specify its own remote or revision attribute. + +Attribute `remote`: Name of a previously defined remote element. +Project elements lacking a remote attribute of their own will use +this remote. + +Attribute `revision`: Name of a Git branch (e.g. `master` or +`refs/heads/master`). Project elements lacking their own +revision attribute will use this revision. + +Attribute `dest-branch`: Name of a Git branch (e.g. `master`). +Project elements not setting their own `dest-branch` will inherit +this value. If this value is not set, projects will use `revision` +by default instead. + +Attribute `upstream`: Name of the Git ref in which a sha1 +can be found. Used when syncing a revision locked manifest in +-c mode to avoid having to sync the entire ref space. Project elements +not setting their own `upstream` will inherit this value. + +Attribute `sync-j`: Number of parallel jobs to use when synching. + +Attribute `sync-c`: Set to true to only sync the given Git +branch (specified in the `revision` attribute) rather than the +whole ref space. Project elements lacking a sync-c element of +their own will use this value. + +Attribute `sync-s`: Set to true to also sync sub-projects. + +Attribute `sync-tags`: Set to false to only sync the given Git +branch (specified in the `revision` attribute) rather than +the other ref tags. + + +Element manifest-server +----------------------- + +At most one manifest-server may be specified. The url attribute +is used to specify the URL of a manifest server, which is an +XML RPC service. + +The manifest server should implement the following RPC methods: + + GetApprovedManifest(branch, target) + +Return a manifest in which each project is pegged to a known good revision +for the current branch and target. This is used by repo sync when the +--smart-sync option is given. + +The target to use is defined by environment variables TARGET_PRODUCT +and TARGET_BUILD_VARIANT. These variables are used to create a string +of the form $TARGET_PRODUCT-$TARGET_BUILD_VARIANT, e.g. passion-userdebug. +If one of those variables or both are not present, the program will call +GetApprovedManifest without the target parameter and the manifest server +should choose a reasonable default target. + + GetManifest(tag) + +Return a manifest in which each project is pegged to the revision at +the specified tag. This is used by repo sync when the --smart-tag option +is given. + + +Element project +--------------- + +One or more project elements may be specified. Each element +describes a single Git repository to be cloned into the repo +client workspace. You may specify Git-submodules by creating a +nested project. Git-submodules will be automatically +recognized and inherit their parent's attributes, but those +may be overridden by an explicitly specified project element. + +Attribute `name`: A unique name for this project. The project's +name is appended onto its remote's fetch URL to generate the actual +URL to configure the Git remote with. The URL gets formed as: + + ${remote_fetch}/${project_name}.git + +where ${remote_fetch} is the remote's fetch attribute and +${project_name} is the project's name attribute. The suffix ".git" +is always appended as repo assumes the upstream is a forest of +bare Git repositories. If the project has a parent element, its +name will be prefixed by the parent's. + +The project name must match the name Gerrit knows, if Gerrit is +being used for code reviews. + +Attribute `path`: An optional path relative to the top directory +of the repo client where the Git working directory for this project +should be placed. If not supplied the project name is used. +If the project has a parent element, its path will be prefixed +by the parent's. + +Attribute `remote`: Name of a previously defined remote element. +If not supplied the remote given by the default element is used. + +Attribute `revision`: Name of the Git branch the manifest wants +to track for this project. Names can be relative to refs/heads +(e.g. just "master") or absolute (e.g. "refs/heads/master"). +Tags and/or explicit SHA-1s should work in theory, but have not +been extensively tested. If not supplied the revision given by +the remote element is used if applicable, else the default +element is used. + +Attribute `dest-branch`: Name of a Git branch (e.g. `master`). +When using `repo upload`, changes will be submitted for code +review on this branch. If unspecified both here and in the +default element, `revision` is used instead. + +Attribute `groups`: List of groups to which this project belongs, +whitespace or comma separated. All projects belong to the group +"all", and each project automatically belongs to a group of +its name:`name` and path:`path`. E.g. for +, that project +definition is implicitly in the following manifest groups: +default, name:monkeys, and path:barrel-of. If you place a project in the +group "notdefault", it will not be automatically downloaded by repo. +If the project has a parent element, the `name` and `path` here +are the prefixed ones. + +Attribute `sync-c`: Set to true to only sync the given Git +branch (specified in the `revision` attribute) rather than the +whole ref space. + +Attribute `sync-s`: Set to true to also sync sub-projects. + +Attribute `upstream`: Name of the Git ref in which a sha1 +can be found. Used when syncing a revision locked manifest in +-c mode to avoid having to sync the entire ref space. + +Attribute `clone-depth`: Set the depth to use when fetching this +project. If specified, this value will override any value given +to repo init with the --depth option on the command line. + +Attribute `force-path`: Set to true to force this project to create the +local mirror repository according to its `path` attribute (if supplied) +rather than the `name` attribute. This attribute only applies to the +local mirrors syncing, it will be ignored when syncing the projects in a +client working directory. + +Element extend-project +---------------------- + +Modify the attributes of the named project. + +This element is mostly useful in a local manifest file, to modify the +attributes of an existing project without completely replacing the +existing project definition. This makes the local manifest more robust +against changes to the original manifest. + +Attribute `path`: If specified, limit the change to projects checked out +at the specified path, rather than all projects with the given name. + +Attribute `groups`: List of additional groups to which this project +belongs. Same syntax as the corresponding element of `project`. + +Attribute `revision`: If specified, overrides the revision of the original +project. Same syntax as the corresponding element of `project`. + +Element annotation +------------------ + +Zero or more annotation elements may be specified as children of a +project element. Each element describes a name-value pair that will be +exported into each project's environment during a 'forall' command, +prefixed with REPO__. In addition, there is an optional attribute +"keep" which accepts the case insensitive values "true" (default) or +"false". This attribute determines whether or not the annotation will +be kept when exported with the manifest subcommand. + +Element copyfile +---------------- + +Zero or more copyfile elements may be specified as children of a +project element. Each element describes a src-dest pair of files; +the "src" file will be copied to the "dest" place during `repo sync` +command. +"src" is project relative, "dest" is relative to the top of the tree. + +Element linkfile +---------------- + +It's just like copyfile and runs at the same time as copyfile but +instead of copying it creates a symlink. + +Element remove-project +---------------------- + +Deletes the named project from the internal manifest table, possibly +allowing a subsequent project element in the same manifest file to +replace the project with a different source. + +This element is mostly useful in a local manifest file, where +the user can remove a project, and possibly replace it with their +own definition. + +Element include +--------------- + +This element provides the capability of including another manifest +file into the originating manifest. Normal rules apply for the +target manifest to include - it must be a usable manifest on its own. + +Attribute `name`: the manifest to include, specified relative to +the manifest repository's root. + + +Local Manifests +=============== + +Additional remotes and projects may be added through local manifest +files stored in `$TOP_DIR/.repo/local_manifests/*.xml`. + +For example: + + $ ls .repo/local_manifests + local_manifest.xml + another_local_manifest.xml + + $ cat .repo/local_manifests/local_manifest.xml + + + + + + +Users may add projects to the local manifest(s) prior to a `repo sync` +invocation, instructing repo to automatically download and manage +these extra projects. + +Manifest files stored in `$TOP_DIR/.repo/local_manifests/*.xml` will +be loaded in alphabetical order. + +Additional remotes and projects may also be added through a local +manifest, stored in `$TOP_DIR/.repo/local_manifest.xml`. This method +is deprecated in favor of using multiple manifest files as mentioned +above. + +If `$TOP_DIR/.repo/local_manifest.xml` exists, it will be loaded before +any manifest files stored in `$TOP_DIR/.repo/local_manifests/*.xml`. diff --git a/docs/manifest-format.txt b/docs/manifest-format.txt deleted file mode 100644 index 0c957dd5..00000000 --- a/docs/manifest-format.txt +++ /dev/null @@ -1,395 +0,0 @@ -repo Manifest Format -==================== - -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 single 'default.xml' XML file in the top level directory. - -Manifests are inherently version controlled, since they are kept -within a Git repository. Updates to manifests are automatically -obtained by clients during `repo sync`. - - -XML File Format ---------------- - -A manifest XML file (e.g. 'default.xml') roughly conforms to the -following DTD: - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - ]> - -A description of the elements and their attributes follows. - - -Element manifest ----------------- - -The root element of the file. - - -Element remote --------------- - -One or more remote elements may be specified. Each remote element -specifies a Git URL shared by one or more projects and (optionally) -the Gerrit review server those projects upload changes through. - -Attribute `name`: A short name unique to this manifest file. The -name specified here is used as the remote name in each project's -.git/config, and is therefore automatically available to commands -like `git fetch`, `git remote`, `git pull` and `git push`. - -Attribute `alias`: The alias, if specified, is used to override -`name` to be set as the remote name in each project's .git/config. -Its value can be duplicated while attribute `name` has to be unique -in the manifest file. This helps each project to be able to have -same remote name which actually points to different remote url. - -Attribute `fetch`: The Git URL prefix for all projects which use -this remote. Each project's name is appended to this prefix to -form the actual URL used to clone the project. - -Attribute `pushurl`: The Git "push" URL prefix for all projects -which use this remote. Each project's name is appended to this -prefix to form the actual URL used to "git push" the project. -This attribute is optional; if not specified then "git push" -will use the same URL as the `fetch` attribute. - -Attribute `review`: Hostname of the Gerrit server where reviews -are uploaded to by `repo upload`. This attribute is optional; -if not specified then `repo upload` will not function. - -Attribute `revision`: Name of a Git branch (e.g. `master` or -`refs/heads/master`). Remotes with their own revision will override -the default revision. - -Element default ---------------- - -At most one default element may be specified. Its remote and -revision attributes are used when a project element does not -specify its own remote or revision attribute. - -Attribute `remote`: Name of a previously defined remote element. -Project elements lacking a remote attribute of their own will use -this remote. - -Attribute `revision`: Name of a Git branch (e.g. `master` or -`refs/heads/master`). Project elements lacking their own -revision attribute will use this revision. - -Attribute `dest-branch`: Name of a Git branch (e.g. `master`). -Project elements not setting their own `dest-branch` will inherit -this value. If this value is not set, projects will use `revision` -by default instead. - -Attribute `upstream`: Name of the Git ref in which a sha1 -can be found. Used when syncing a revision locked manifest in --c mode to avoid having to sync the entire ref space. Project elements -not setting their own `upstream` will inherit this value. - -Attribute `sync-j`: Number of parallel jobs to use when synching. - -Attribute `sync-c`: Set to true to only sync the given Git -branch (specified in the `revision` attribute) rather than the -whole ref space. Project elements lacking a sync-c element of -their own will use this value. - -Attribute `sync-s`: Set to true to also sync sub-projects. - -Attribute `sync-tags`: Set to false to only sync the given Git -branch (specified in the `revision` attribute) rather than -the other ref tags. - - -Element manifest-server ------------------------ - -At most one manifest-server may be specified. The url attribute -is used to specify the URL of a manifest server, which is an -XML RPC service. - -The manifest server should implement the following RPC methods: - - GetApprovedManifest(branch, target) - -Return a manifest in which each project is pegged to a known good revision -for the current branch and target. This is used by repo sync when the ---smart-sync option is given. - -The target to use is defined by environment variables TARGET_PRODUCT -and TARGET_BUILD_VARIANT. These variables are used to create a string -of the form $TARGET_PRODUCT-$TARGET_BUILD_VARIANT, e.g. passion-userdebug. -If one of those variables or both are not present, the program will call -GetApprovedManifest without the target parameter and the manifest server -should choose a reasonable default target. - - GetManifest(tag) - -Return a manifest in which each project is pegged to the revision at -the specified tag. This is used by repo sync when the --smart-tag option -is given. - - -Element project ---------------- - -One or more project elements may be specified. Each element -describes a single Git repository to be cloned into the repo -client workspace. You may specify Git-submodules by creating a -nested project. Git-submodules will be automatically -recognized and inherit their parent's attributes, but those -may be overridden by an explicitly specified project element. - -Attribute `name`: A unique name for this project. The project's -name is appended onto its remote's fetch URL to generate the actual -URL to configure the Git remote with. The URL gets formed as: - - ${remote_fetch}/${project_name}.git - -where ${remote_fetch} is the remote's fetch attribute and -${project_name} is the project's name attribute. The suffix ".git" -is always appended as repo assumes the upstream is a forest of -bare Git repositories. If the project has a parent element, its -name will be prefixed by the parent's. - -The project name must match the name Gerrit knows, if Gerrit is -being used for code reviews. - -Attribute `path`: An optional path relative to the top directory -of the repo client where the Git working directory for this project -should be placed. If not supplied the project name is used. -If the project has a parent element, its path will be prefixed -by the parent's. - -Attribute `remote`: Name of a previously defined remote element. -If not supplied the remote given by the default element is used. - -Attribute `revision`: Name of the Git branch the manifest wants -to track for this project. Names can be relative to refs/heads -(e.g. just "master") or absolute (e.g. "refs/heads/master"). -Tags and/or explicit SHA-1s should work in theory, but have not -been extensively tested. If not supplied the revision given by -the remote element is used if applicable, else the default -element is used. - -Attribute `dest-branch`: Name of a Git branch (e.g. `master`). -When using `repo upload`, changes will be submitted for code -review on this branch. If unspecified both here and in the -default element, `revision` is used instead. - -Attribute `groups`: List of groups to which this project belongs, -whitespace or comma separated. All projects belong to the group -"all", and each project automatically belongs to a group of -its name:`name` and path:`path`. E.g. for -, that project -definition is implicitly in the following manifest groups: -default, name:monkeys, and path:barrel-of. If you place a project in the -group "notdefault", it will not be automatically downloaded by repo. -If the project has a parent element, the `name` and `path` here -are the prefixed ones. - -Attribute `sync-c`: Set to true to only sync the given Git -branch (specified in the `revision` attribute) rather than the -whole ref space. - -Attribute `sync-s`: Set to true to also sync sub-projects. - -Attribute `upstream`: Name of the Git ref in which a sha1 -can be found. Used when syncing a revision locked manifest in --c mode to avoid having to sync the entire ref space. - -Attribute `clone-depth`: Set the depth to use when fetching this -project. If specified, this value will override any value given -to repo init with the --depth option on the command line. - -Attribute `force-path`: Set to true to force this project to create the -local mirror repository according to its `path` attribute (if supplied) -rather than the `name` attribute. This attribute only applies to the -local mirrors syncing, it will be ignored when syncing the projects in a -client working directory. - -Element extend-project ----------------------- - -Modify the attributes of the named project. - -This element is mostly useful in a local manifest file, to modify the -attributes of an existing project without completely replacing the -existing project definition. This makes the local manifest more robust -against changes to the original manifest. - -Attribute `path`: If specified, limit the change to projects checked out -at the specified path, rather than all projects with the given name. - -Attribute `groups`: List of additional groups to which this project -belongs. Same syntax as the corresponding element of `project`. - -Attribute `revision`: If specified, overrides the revision of the original -project. Same syntax as the corresponding element of `project`. - -Element annotation ------------------- - -Zero or more annotation elements may be specified as children of a -project element. Each element describes a name-value pair that will be -exported into each project's environment during a 'forall' command, -prefixed with REPO__. In addition, there is an optional attribute -"keep" which accepts the case insensitive values "true" (default) or -"false". This attribute determines whether or not the annotation will -be kept when exported with the manifest subcommand. - -Element copyfile ----------------- - -Zero or more copyfile elements may be specified as children of a -project element. Each element describes a src-dest pair of files; -the "src" file will be copied to the "dest" place during 'repo sync' -command. -"src" is project relative, "dest" is relative to the top of the tree. - -Element linkfile ----------------- - -It's just like copyfile and runs at the same time as copyfile but -instead of copying it creates a symlink. - -Element remove-project ----------------------- - -Deletes the named project from the internal manifest table, possibly -allowing a subsequent project element in the same manifest file to -replace the project with a different source. - -This element is mostly useful in a local manifest file, where -the user can remove a project, and possibly replace it with their -own definition. - -Element include ---------------- - -This element provides the capability of including another manifest -file into the originating manifest. Normal rules apply for the -target manifest to include - it must be a usable manifest on its own. - -Attribute `name`: the manifest to include, specified relative to -the manifest repository's root. - - -Local Manifests -=============== - -Additional remotes and projects may be added through local manifest -files stored in `$TOP_DIR/.repo/local_manifests/*.xml`. - -For example: - - $ ls .repo/local_manifests - local_manifest.xml - another_local_manifest.xml - - $ cat .repo/local_manifests/local_manifest.xml - - - - - - -Users may add projects to the local manifest(s) prior to a `repo sync` -invocation, instructing repo to automatically download and manage -these extra projects. - -Manifest files stored in `$TOP_DIR/.repo/local_manifests/*.xml` will -be loaded in alphabetical order. - -Additional remotes and projects may also be added through a local -manifest, stored in `$TOP_DIR/.repo/local_manifest.xml`. This method -is deprecated in favor of using multiple manifest files as mentioned -above. - -If `$TOP_DIR/.repo/local_manifest.xml` exists, it will be loaded before -any manifest files stored in `$TOP_DIR/.repo/local_manifests/*.xml`. diff --git a/docs/repo-hooks.md b/docs/repo-hooks.md index 76113cc9..e198b390 100644 --- a/docs/repo-hooks.md +++ b/docs/repo-hooks.md @@ -24,7 +24,7 @@ repohooks project is updated and a hook is triggered. ## Manifest Settings -For the full syntax, see the [repo manifest format](./manifest-format.txt). +For the full syntax, see the [repo manifest format](./manifest-format.md). Here's a short example from [Android](https://android.googlesource.com/platform/manifest/+/master/default.xml). -- cgit v1.2.3-54-g00ecf