Omit local_manifest groups from superproject override.

When we create superproject_override.xml, do not include projects that are present from local_manifests/*. Such projects are fully under the control of the local_manifests/ file. Bug: b/238934278 Test: manual, ./run_tests Change-Id: I40382ceb82d9cf7b8dc7b5f2abed3f6d4d80017e Reviewed-on: https://gerrit-review.googlesource.com/c/git-repo/+/340877 Tested-by: Xin Li <delphij@google.com> Reviewed-by: Xin Li <delphij@google.com> Reviewed-by: Sam Saccone 🐐 <samccone@google.com>
status, diff: display correct path for multi-manifest
2026-01-12 17:40:52 +00:00 · 2022-07-15 23:32:24 +00:00 · 2022-07-14 16:00:18 +00:00 · 2022-07-11 17:58:06 +00:00 · 2022-07-11 17:57:43 +00:00 · 2022-07-11 16:42:23 +00:00
38 changed files with 652 additions and 89 deletions
--- a/command.py
+++ b/command.py
@@ -277,6 +277,18 @@ class Command(object):
  def GetProjects(self, args, manifest=None, groups='', missing_ok=False,
                  submodules_ok=False, all_manifests=False):
    """A list of projects that match the arguments.
+
+    Args:
+      args: a list of (case-insensitive) strings, projects to search for.
+      manifest: an XmlManifest, the manifest to use, or None for default.
+      groups: a string, the manifest groups in use.
+      missing_ok: a boolean, whether to allow missing projects.
+      submodules_ok: a boolean, whether to allow submodules.
+      all_manifests: a boolean, if True then all manifests and submanifests are
+                     used.  If False, then only the local (sub)manifest is used.
+
+    Returns:
+      A list of matching Project instances.
    """
    if all_manifests:
      if not manifest:
--- a/git_superproject.py
+++ b/git_superproject.py
@@ -18,7 +18,7 @@ For more information on superproject, check out:
 https://en.wikibooks.org/wiki/Git/Submodules_and_Superprojects

 Examples:
-  superproject = Superproject()
+  superproject = Superproject(manifest, name, remote, revision)
  UpdateProjectsResult = superproject.UpdateProjectsRevisionId(projects)
 """

@@ -99,8 +99,8 @@ class Superproject(object):
    self._work_git_name = git_name + _SUPERPROJECT_GIT_NAME
    self._work_git = os.path.join(self._superproject_path, self._work_git_name)

-    # The following are command arguemnts, rather then superproject attributes,
-    # and where included here originally.  They should eventually become
+    # The following are command arguemnts, rather than superproject attributes,
+    # and were included here originally.  They should eventually become
    # arguments that are passed down from the public methods, instead of being
    # treated as attributes.
    self._git_event_log = None
@@ -295,7 +295,8 @@ class Superproject(object):
    if not os.path.exists(self._superproject_path):
      self._LogWarning(f'missing superproject directory: {self._superproject_path}')
      return None
-    manifest_str = self._manifest.ToXml(groups=self._manifest.GetGroupsStr()).toxml()
+    manifest_str = self._manifest.ToXml(groups=self._manifest.GetGroupsStr(),
+                                        omit_local=True).toxml()
    manifest_path = self._manifest_path
    try:
      with open(manifest_path, 'w', encoding='utf-8') as fp:
@@ -329,7 +330,8 @@ class Superproject(object):
    """Update revisionId of every project in projects with the commit id.

    Args:
-      projects: List of projects whose revisionId needs to be updated.
+      projects: a list of projects whose revisionId needs to be updated.
+      git_event_log: an EventLog, for git tracing.

    Returns:
      UpdateProjectsResult
@@ -431,9 +433,15 @@ def UseSuperproject(use_superproject, manifest):
  Args:
    use_superproject: option value from optparse.
    manifest: manifest to use.
+
+  Returns:
+    Whether the superproject should be used.
  """

-  if use_superproject is not None:
+  if not manifest.superproject:
+    # This (sub) manifest does not have a superproject definition.
+    return False
+  elif use_superproject is not None:
    return use_superproject
  else:
    client_value = manifest.manifestProject.use_superproject
--- a/man/repo-abandon.1
+++ b/man/repo-abandon.1
@@ -1,5 +1,5 @@
 .\" DO NOT MODIFY THIS FILE!  It was generated by help2man.
-.TH REPO "1" "July 2021" "repo abandon" "Repo Manual"
+.TH REPO "1" "July 2022" "repo abandon" "Repo Manual"
 .SH NAME
 repo \- repo abandon - manual page for repo abandon
 .SH SYNOPSIS
@@ -32,5 +32,18 @@ show all output
 .TP
 \fB\-q\fR, \fB\-\-quiet\fR
 only show errors
+.SS Multi\-manifest options:
+.TP
+\fB\-\-outer\-manifest\fR
+operate starting at the outermost manifest
+.TP
+\fB\-\-no\-outer\-manifest\fR
+do not operate on outer manifests
+.TP
+\fB\-\-this\-manifest\-only\fR
+only operate on this (sub)manifest
+.TP
+\fB\-\-no\-this\-manifest\-only\fR, \fB\-\-all\-manifests\fR
+operate on this manifest and its submanifests
 .PP
 Run `repo help abandon` to view the detailed manual.
--- a/man/repo-branches.1
+++ b/man/repo-branches.1
@@ -1,5 +1,5 @@
 .\" DO NOT MODIFY THIS FILE!  It was generated by help2man.
-.TH REPO "1" "July 2021" "repo branches" "Repo Manual"
+.TH REPO "1" "July 2022" "repo branches" "Repo Manual"
 .SH NAME
 repo \- repo branches - manual page for repo branches
 .SH SYNOPSIS
@@ -55,5 +55,18 @@ show all output
 .TP
 \fB\-q\fR, \fB\-\-quiet\fR
 only show errors
+.SS Multi\-manifest options:
+.TP
+\fB\-\-outer\-manifest\fR
+operate starting at the outermost manifest
+.TP
+\fB\-\-no\-outer\-manifest\fR
+do not operate on outer manifests
+.TP
+\fB\-\-this\-manifest\-only\fR
+only operate on this (sub)manifest
+.TP
+\fB\-\-no\-this\-manifest\-only\fR, \fB\-\-all\-manifests\fR
+operate on this manifest and its submanifests
 .PP
 Run `repo help branches` to view the detailed manual.
--- a/man/repo-checkout.1
+++ b/man/repo-checkout.1
@@ -1,5 +1,5 @@
 .\" DO NOT MODIFY THIS FILE!  It was generated by help2man.
-.TH REPO "1" "July 2021" "repo checkout" "Repo Manual"
+.TH REPO "1" "July 2022" "repo checkout" "Repo Manual"
 .SH NAME
 repo \- repo checkout - manual page for repo checkout
 .SH SYNOPSIS
@@ -24,6 +24,19 @@ show all output
 .TP
 \fB\-q\fR, \fB\-\-quiet\fR
 only show errors
+.SS Multi\-manifest options:
+.TP
+\fB\-\-outer\-manifest\fR
+operate starting at the outermost manifest
+.TP
+\fB\-\-no\-outer\-manifest\fR
+do not operate on outer manifests
+.TP
+\fB\-\-this\-manifest\-only\fR
+only operate on this (sub)manifest
+.TP
+\fB\-\-no\-this\-manifest\-only\fR, \fB\-\-all\-manifests\fR
+operate on this manifest and its submanifests
 .PP
 Run `repo help checkout` to view the detailed manual.
 .SH DETAILS
--- a/man/repo-cherry-pick.1
+++ b/man/repo-cherry-pick.1
@@ -1,5 +1,5 @@
 .\" DO NOT MODIFY THIS FILE!  It was generated by help2man.
-.TH REPO "1" "July 2021" "repo cherry-pick" "Repo Manual"
+.TH REPO "1" "July 2022" "repo cherry-pick" "Repo Manual"
 .SH NAME
 repo \- repo cherry-pick - manual page for repo cherry-pick
 .SH SYNOPSIS
@@ -20,6 +20,19 @@ show all output
 .TP
 \fB\-q\fR, \fB\-\-quiet\fR
 only show errors
+.SS Multi\-manifest options:
+.TP
+\fB\-\-outer\-manifest\fR
+operate starting at the outermost manifest
+.TP
+\fB\-\-no\-outer\-manifest\fR
+do not operate on outer manifests
+.TP
+\fB\-\-this\-manifest\-only\fR
+only operate on this (sub)manifest
+.TP
+\fB\-\-no\-this\-manifest\-only\fR, \fB\-\-all\-manifests\fR
+operate on this manifest and its submanifests
 .PP
 Run `repo help cherry\-pick` to view the detailed manual.
 .SH DETAILS
--- a/man/repo-diff.1
+++ b/man/repo-diff.1
@@ -1,5 +1,5 @@
 .\" DO NOT MODIFY THIS FILE!  It was generated by help2man.
-.TH REPO "1" "July 2021" "repo diff" "Repo Manual"
+.TH REPO "1" "July 2022" "repo diff" "Repo Manual"
 .SH NAME
 repo \- repo diff - manual page for repo diff
 .SH SYNOPSIS
@@ -31,5 +31,18 @@ show all output
 .TP
 \fB\-q\fR, \fB\-\-quiet\fR
 only show errors
+.SS Multi\-manifest options:
+.TP
+\fB\-\-outer\-manifest\fR
+operate starting at the outermost manifest
+.TP
+\fB\-\-no\-outer\-manifest\fR
+do not operate on outer manifests
+.TP
+\fB\-\-this\-manifest\-only\fR
+only operate on this (sub)manifest
+.TP
+\fB\-\-no\-this\-manifest\-only\fR, \fB\-\-all\-manifests\fR
+operate on this manifest and its submanifests
 .PP
 Run `repo help diff` to view the detailed manual.
--- a/man/repo-diffmanifests.1
+++ b/man/repo-diffmanifests.1
@@ -1,5 +1,5 @@
 .\" DO NOT MODIFY THIS FILE!  It was generated by help2man.
-.TH REPO "1" "July 2021" "repo diffmanifests" "Repo Manual"
+.TH REPO "1" "July 2022" "repo diffmanifests" "Repo Manual"
 .SH NAME
 repo \- repo diffmanifests - manual page for repo diffmanifests
 .SH SYNOPSIS
@@ -29,6 +29,19 @@ show all output
 .TP
 \fB\-q\fR, \fB\-\-quiet\fR
 only show errors
+.SS Multi\-manifest options:
+.TP
+\fB\-\-outer\-manifest\fR
+operate starting at the outermost manifest
+.TP
+\fB\-\-no\-outer\-manifest\fR
+do not operate on outer manifests
+.TP
+\fB\-\-this\-manifest\-only\fR
+only operate on this (sub)manifest
+.TP
+\fB\-\-no\-this\-manifest\-only\fR, \fB\-\-all\-manifests\fR
+operate on this manifest and its submanifests
 .PP
 Run `repo help diffmanifests` to view the detailed manual.
 .SH DETAILS
--- a/man/repo-download.1
+++ b/man/repo-download.1
@@ -1,5 +1,5 @@
 .\" DO NOT MODIFY THIS FILE!  It was generated by help2man.
-.TH REPO "1" "July 2021" "repo download" "Repo Manual"
+.TH REPO "1" "July 2022" "repo download" "Repo Manual"
 .SH NAME
 repo \- repo download - manual page for repo download
 .SH SYNOPSIS
@@ -35,6 +35,19 @@ show all output
 .TP
 \fB\-q\fR, \fB\-\-quiet\fR
 only show errors
+.SS Multi\-manifest options:
+.TP
+\fB\-\-outer\-manifest\fR
+operate starting at the outermost manifest
+.TP
+\fB\-\-no\-outer\-manifest\fR
+do not operate on outer manifests
+.TP
+\fB\-\-this\-manifest\-only\fR
+only operate on this (sub)manifest
+.TP
+\fB\-\-no\-this\-manifest\-only\fR, \fB\-\-all\-manifests\fR
+operate on this manifest and its submanifests
 .PP
 Run `repo help download` to view the detailed manual.
 .SH DETAILS
--- a/man/repo-forall.1
+++ b/man/repo-forall.1
@@ -1,5 +1,5 @@
 .\" DO NOT MODIFY THIS FILE!  It was generated by help2man.
-.TH REPO "1" "July 2021" "repo forall" "Repo Manual"
+.TH REPO "1" "July 2022" "repo forall" "Repo Manual"
 .SH NAME
 repo \- repo forall - manual page for repo forall
 .SH SYNOPSIS
@@ -54,6 +54,19 @@ only show errors
 .TP
 \fB\-p\fR
 show project headers before output
+.SS Multi\-manifest options:
+.TP
+\fB\-\-outer\-manifest\fR
+operate starting at the outermost manifest
+.TP
+\fB\-\-no\-outer\-manifest\fR
+do not operate on outer manifests
+.TP
+\fB\-\-this\-manifest\-only\fR
+only operate on this (sub)manifest
+.TP
+\fB\-\-no\-this\-manifest\-only\fR, \fB\-\-all\-manifests\fR
+operate on this manifest and its submanifests
 .PP
 Run `repo help forall` to view the detailed manual.
 .SH DETAILS
@@ -93,6 +106,11 @@ REPO_PROJECT is set to the unique name of the project.
 .PP
 REPO_PATH is the path relative the the root of the client.
 .PP
+REPO_OUTERPATH is the path of the sub manifest's root relative to the root of
+the client.
+.PP
+REPO_INNERPATH is the path relative to the root of the sub manifest.
+.PP
 REPO_REMOTE is the name of the remote system from the manifest.
 .PP
 REPO_LREV is the name of the revision from the manifest, translated to a local
--- a/man/repo-gitc-delete.1
+++ b/man/repo-gitc-delete.1
@@ -1,5 +1,5 @@
 .\" DO NOT MODIFY THIS FILE!  It was generated by help2man.
-.TH REPO "1" "July 2021" "repo gitc-delete" "Repo Manual"
+.TH REPO "1" "July 2022" "repo gitc-delete" "Repo Manual"
 .SH NAME
 repo \- repo gitc-delete - manual page for repo gitc-delete
 .SH SYNOPSIS
@@ -23,6 +23,19 @@ show all output
 .TP
 \fB\-q\fR, \fB\-\-quiet\fR
 only show errors
+.SS Multi\-manifest options:
+.TP
+\fB\-\-outer\-manifest\fR
+operate starting at the outermost manifest
+.TP
+\fB\-\-no\-outer\-manifest\fR
+do not operate on outer manifests
+.TP
+\fB\-\-this\-manifest\-only\fR
+only operate on this (sub)manifest
+.TP
+\fB\-\-no\-this\-manifest\-only\fR, \fB\-\-all\-manifests\fR
+operate on this manifest and its submanifests
 .PP
 Run `repo help gitc\-delete` to view the detailed manual.
 .SH DETAILS
--- a/man/repo-gitc-init.1
+++ b/man/repo-gitc-init.1
@@ -1,5 +1,5 @@
 .\" DO NOT MODIFY THIS FILE!  It was generated by help2man.
-.TH REPO "1" "November 2021" "repo gitc-init" "Repo Manual"
+.TH REPO "1" "July 2022" "repo gitc-init" "Repo Manual"
 .SH NAME
 repo \- repo gitc-init - manual page for repo gitc-init
 .SH SYNOPSIS
@@ -109,6 +109,12 @@ not \fB\-\-partial\-clone\fR)
 \fB\-\-no\-clone\-bundle\fR
 disable use of \fI\,/clone.bundle\/\fP on HTTP/HTTPS (default if
 \fB\-\-partial\-clone\fR)
+.TP
+\fB\-\-git\-lfs\fR
+enable Git LFS support
+.TP
+\fB\-\-no\-git\-lfs\fR
+disable Git LFS support
 .SS repo Version options:
 .TP
 \fB\-\-repo\-url\fR=\fI\,URL\/\fR
@@ -130,6 +136,19 @@ Optional manifest file to use for this GITC client.
 .TP
 \fB\-c\fR GITC_CLIENT, \fB\-\-gitc\-client\fR=\fI\,GITC_CLIENT\/\fR
 Name of the gitc_client instance to create or modify.
+.SS Multi\-manifest:
+.TP
+\fB\-\-outer\-manifest\fR
+operate starting at the outermost manifest
+.TP
+\fB\-\-no\-outer\-manifest\fR
+do not operate on outer manifests
+.TP
+\fB\-\-this\-manifest\-only\fR
+only operate on this (sub)manifest
+.TP
+\fB\-\-no\-this\-manifest\-only\fR, \fB\-\-all\-manifests\fR
+operate on this manifest and its submanifests
 .PP
 Run `repo help gitc\-init` to view the detailed manual.
 .SH DETAILS
--- a/man/repo-grep.1
+++ b/man/repo-grep.1
@@ -1,5 +1,5 @@
 .\" DO NOT MODIFY THIS FILE!  It was generated by help2man.
-.TH REPO "1" "July 2021" "repo grep" "Repo Manual"
+.TH REPO "1" "July 2022" "repo grep" "Repo Manual"
 .SH NAME
 repo \- repo grep - manual page for repo grep
 .SH SYNOPSIS
@@ -24,6 +24,19 @@ show all output
 .TP
 \fB\-q\fR, \fB\-\-quiet\fR
 only show errors
+.SS Multi\-manifest options:
+.TP
+\fB\-\-outer\-manifest\fR
+operate starting at the outermost manifest
+.TP
+\fB\-\-no\-outer\-manifest\fR
+do not operate on outer manifests
+.TP
+\fB\-\-this\-manifest\-only\fR
+only operate on this (sub)manifest
+.TP
+\fB\-\-no\-this\-manifest\-only\fR, \fB\-\-all\-manifests\fR
+operate on this manifest and its submanifests
 .SS Sources:
 .TP
 \fB\-\-cached\fR
--- a/man/repo-help.1
+++ b/man/repo-help.1
@@ -1,5 +1,5 @@
 .\" DO NOT MODIFY THIS FILE!  It was generated by help2man.
-.TH REPO "1" "July 2021" "repo help" "Repo Manual"
+.TH REPO "1" "July 2022" "repo help" "Repo Manual"
 .SH NAME
 repo \- repo help - manual page for repo help
 .SH SYNOPSIS
@@ -26,6 +26,19 @@ show all output
 .TP
 \fB\-q\fR, \fB\-\-quiet\fR
 only show errors
+.SS Multi\-manifest options:
+.TP
+\fB\-\-outer\-manifest\fR
+operate starting at the outermost manifest
+.TP
+\fB\-\-no\-outer\-manifest\fR
+do not operate on outer manifests
+.TP
+\fB\-\-this\-manifest\-only\fR
+only operate on this (sub)manifest
+.TP
+\fB\-\-no\-this\-manifest\-only\fR, \fB\-\-all\-manifests\fR
+operate on this manifest and its submanifests
 .PP
 Run `repo help help` to view the detailed manual.
 .SH DETAILS
--- a/man/repo-info.1
+++ b/man/repo-info.1
@@ -1,5 +1,5 @@
 .\" DO NOT MODIFY THIS FILE!  It was generated by help2man.
-.TH REPO "1" "July 2021" "repo info" "Repo Manual"
+.TH REPO "1" "July 2022" "repo info" "Repo Manual"
 .SH NAME
 repo \- repo info - manual page for repo info
 .SH SYNOPSIS
@@ -36,5 +36,18 @@ show all output
 .TP
 \fB\-q\fR, \fB\-\-quiet\fR
 only show errors
+.SS Multi\-manifest options:
+.TP
+\fB\-\-outer\-manifest\fR
+operate starting at the outermost manifest
+.TP
+\fB\-\-no\-outer\-manifest\fR
+do not operate on outer manifests
+.TP
+\fB\-\-this\-manifest\-only\fR
+only operate on this (sub)manifest
+.TP
+\fB\-\-no\-this\-manifest\-only\fR, \fB\-\-all\-manifests\fR
+operate on this manifest and its submanifests
 .PP
 Run `repo help info` to view the detailed manual.
--- a/man/repo-init.1
+++ b/man/repo-init.1
@@ -1,5 +1,5 @@
 .\" DO NOT MODIFY THIS FILE!  It was generated by help2man.
-.TH REPO "1" "November 2021" "repo init" "Repo Manual"
+.TH REPO "1" "July 2022" "repo init" "Repo Manual"
 .SH NAME
 repo \- repo init - manual page for repo init
 .SH SYNOPSIS
@@ -109,6 +109,12 @@ not \fB\-\-partial\-clone\fR)
 \fB\-\-no\-clone\-bundle\fR
 disable use of \fI\,/clone.bundle\/\fP on HTTP/HTTPS (default if
 \fB\-\-partial\-clone\fR)
+.TP
+\fB\-\-git\-lfs\fR
+enable Git LFS support
+.TP
+\fB\-\-no\-git\-lfs\fR
+disable Git LFS support
 .SS repo Version options:
 .TP
 \fB\-\-repo\-url\fR=\fI\,URL\/\fR
@@ -123,6 +129,19 @@ do not verify repo source code
 .TP
 \fB\-\-config\-name\fR
 Always prompt for name/e\-mail
+.SS Multi\-manifest:
+.TP
+\fB\-\-outer\-manifest\fR
+operate starting at the outermost manifest
+.TP
+\fB\-\-no\-outer\-manifest\fR
+do not operate on outer manifests
+.TP
+\fB\-\-this\-manifest\-only\fR
+only operate on this (sub)manifest
+.TP
+\fB\-\-no\-this\-manifest\-only\fR, \fB\-\-all\-manifests\fR
+operate on this manifest and its submanifests
 .PP
 Run `repo help init` to view the detailed manual.
 .SH DETAILS
--- a/man/repo-list.1
+++ b/man/repo-list.1
@@ -1,5 +1,5 @@
 .\" DO NOT MODIFY THIS FILE!  It was generated by help2man.
-.TH REPO "1" "July 2021" "repo list" "Repo Manual"
+.TH REPO "1" "July 2022" "repo list" "Repo Manual"
 .SH NAME
 repo \- repo list - manual page for repo list
 .SH SYNOPSIS
@@ -47,6 +47,19 @@ show all output
 .TP
 \fB\-q\fR, \fB\-\-quiet\fR
 only show errors
+.SS Multi\-manifest options:
+.TP
+\fB\-\-outer\-manifest\fR
+operate starting at the outermost manifest
+.TP
+\fB\-\-no\-outer\-manifest\fR
+do not operate on outer manifests
+.TP
+\fB\-\-this\-manifest\-only\fR
+only operate on this (sub)manifest
+.TP
+\fB\-\-no\-this\-manifest\-only\fR, \fB\-\-all\-manifests\fR
+operate on this manifest and its submanifests
 .PP
 Run `repo help list` to view the detailed manual.
 .SH DETAILS
--- a/man/repo-manifest.1
+++ b/man/repo-manifest.1
@@ -1,5 +1,5 @@
 .\" DO NOT MODIFY THIS FILE!  It was generated by help2man.
-.TH REPO "1" "November 2021" "repo manifest" "Repo Manual"
+.TH REPO "1" "July 2022" "repo manifest" "Repo Manual"
 .SH NAME
 repo \- repo manifest - manual page for repo manifest
 .SH SYNOPSIS
@@ -40,7 +40,8 @@ format output for humans to read
 ignore local manifests
 .TP
 \fB\-o\fR \-|NAME.xml, \fB\-\-output\-file\fR=\fI\,\-\/\fR|NAME.xml
-file to save the manifest to
+file to save the manifest to. (Filename prefix for
+multi\-tree.)
 .SS Logging options:
 .TP
 \fB\-v\fR, \fB\-\-verbose\fR
@@ -48,6 +49,19 @@ show all output
 .TP
 \fB\-q\fR, \fB\-\-quiet\fR
 only show errors
+.SS Multi\-manifest options:
+.TP
+\fB\-\-outer\-manifest\fR
+operate starting at the outermost manifest
+.TP
+\fB\-\-no\-outer\-manifest\fR
+do not operate on outer manifests
+.TP
+\fB\-\-this\-manifest\-only\fR
+only operate on this (sub)manifest
+.TP
+\fB\-\-no\-this\-manifest\-only\fR, \fB\-\-all\-manifests\fR
+operate on this manifest and its submanifests
 .PP
 Run `repo help manifest` to view the detailed manual.
 .SH DETAILS
@@ -88,6 +102,7 @@ A manifest XML file (e.g. `default.xml`) roughly conforms to the following DTD:
 remote*,
 default?,
 manifest\-server?,
+submanifest*?,
 remove\-project*,
 project*,
 extend\-project*,
@@ -118,6 +133,16 @@ include*)>
 .IP
 <!ELEMENT manifest\-server EMPTY>
 <!ATTLIST manifest\-server url CDATA #REQUIRED>
+.IP
+<!ELEMENT submanifest EMPTY>
+<!ATTLIST submanifest name           ID #REQUIRED>
+<!ATTLIST submanifest remote         IDREF #IMPLIED>
+<!ATTLIST submanifest project        CDATA #IMPLIED>
+<!ATTLIST submanifest manifest\-name  CDATA #IMPLIED>
+<!ATTLIST submanifest revision       CDATA #IMPLIED>
+<!ATTLIST submanifest path           CDATA #IMPLIED>
+<!ATTLIST submanifest groups         CDATA #IMPLIED>
+<!ATTLIST submanifest default\-groups CDATA #IMPLIED>
 .TP
 <!ELEMENT project (annotation*,
 project*,
@@ -295,6 +320,65 @@ 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 \fB\-\-smart\-tag\fR option is given.
 .PP
+Element submanifest
+.PP
+One or more submanifest elements may be specified. Each element describes a
+single manifest to be checked out as a child.
+.PP
+Attribute `name`: A unique name (within the current (sub)manifest) for this
+submanifest. It acts as a default for `revision` below. The same name can be
+used for submanifests with different parent (sub)manifests.
+.PP
+Attribute `remote`: Name of a previously defined remote element. If not supplied
+the remote given by the default element is used.
+.PP
+Attribute `project`: The manifest project name. 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:
+.IP
+${remote_fetch}/${project_name}.git
+.PP
+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.
+.PP
+The project name must match the name Gerrit knows, if Gerrit is being used for
+code reviews.
+.PP
+`project` must not be empty, and may not be an absolute path or use "." or ".."
+path components. It is always interpreted relative to the remote's fetch
+settings, so if a different base path is needed, declare a different remote with
+the new settings needed.
+.PP
+If not supplied the remote and project for this manifest will be used: `remote`
+cannot be supplied.
+.PP
+Projects from a submanifest and its submanifests are added to the
+submanifest::path:<path_prefix> group.
+.PP
+Attribute `manifest\-name`: The manifest filename in the manifest project. If not
+supplied, `default.xml` is used.
+.PP
+Attribute `revision`: Name of a Git branch (e.g. "main" or "refs/heads/main"),
+tag (e.g. "refs/tags/stable"), or a commit hash. If not supplied, `name` is
+used.
+.PP
+Attribute `path`: An optional path relative to the top directory of the repo
+client where the submanifest repo client top directory should be placed. If not
+supplied, `revision` is used.
+.PP
+`path` may not be an absolute path or use "." or ".." path components.
+.PP
+Attribute `groups`: List of additional groups to which all projects in the
+included submanifest belong. This appends and recurses, meaning all projects in
+submanifests carry all parent submanifest groups. Same syntax as the
+corresponding element of `project`.
+.PP
+Attribute `default\-groups`: The list of manifest groups to sync if no
+`\-\-groups=` parameter was specified at init. When that list is empty, use this
+list instead of "default" as the list of groups to sync.
+.PP
 Element project
 .PP
 One or more project elements may be specified. Each element describes a single
@@ -513,8 +597,8 @@ restrictions are not enforced for [Local Manifests].
 .PP
 Attribute `groups`: List of additional groups to which all projects in the
 included manifest belong. This appends and recurses, meaning all projects in
-sub\-manifests carry all parent include groups. Same syntax as the corresponding
-element of `project`.
+included manifests carry all parent include groups. Same syntax as the
+corresponding element of `project`.
 .PP
 Local Manifests
 .PP
--- a/man/repo-overview.1
+++ b/man/repo-overview.1
@@ -1,5 +1,5 @@
 .\" DO NOT MODIFY THIS FILE!  It was generated by help2man.
-.TH REPO "1" "July 2021" "repo overview" "Repo Manual"
+.TH REPO "1" "July 2022" "repo overview" "Repo Manual"
 .SH NAME
 repo \- repo overview - manual page for repo overview
 .SH SYNOPSIS
@@ -26,6 +26,19 @@ show all output
 .TP
 \fB\-q\fR, \fB\-\-quiet\fR
 only show errors
+.SS Multi\-manifest options:
+.TP
+\fB\-\-outer\-manifest\fR
+operate starting at the outermost manifest
+.TP
+\fB\-\-no\-outer\-manifest\fR
+do not operate on outer manifests
+.TP
+\fB\-\-this\-manifest\-only\fR
+only operate on this (sub)manifest
+.TP
+\fB\-\-no\-this\-manifest\-only\fR, \fB\-\-all\-manifests\fR
+operate on this manifest and its submanifests
 .PP
 Run `repo help overview` to view the detailed manual.
 .SH DETAILS
--- a/man/repo-prune.1
+++ b/man/repo-prune.1
@@ -1,5 +1,5 @@
 .\" DO NOT MODIFY THIS FILE!  It was generated by help2man.
-.TH REPO "1" "July 2021" "repo prune" "Repo Manual"
+.TH REPO "1" "July 2022" "repo prune" "Repo Manual"
 .SH NAME
 repo \- repo prune - manual page for repo prune
 .SH SYNOPSIS
@@ -24,5 +24,18 @@ show all output
 .TP
 \fB\-q\fR, \fB\-\-quiet\fR
 only show errors
+.SS Multi\-manifest options:
+.TP
+\fB\-\-outer\-manifest\fR
+operate starting at the outermost manifest
+.TP
+\fB\-\-no\-outer\-manifest\fR
+do not operate on outer manifests
+.TP
+\fB\-\-this\-manifest\-only\fR
+only operate on this (sub)manifest
+.TP
+\fB\-\-no\-this\-manifest\-only\fR, \fB\-\-all\-manifests\fR
+operate on this manifest and its submanifests
 .PP
 Run `repo help prune` to view the detailed manual.
--- a/man/repo-rebase.1
+++ b/man/repo-rebase.1
@@ -1,5 +1,5 @@
 .\" DO NOT MODIFY THIS FILE!  It was generated by help2man.
-.TH REPO "1" "July 2021" "repo rebase" "Repo Manual"
+.TH REPO "1" "July 2022" "repo rebase" "Repo Manual"
 .SH NAME
 repo \- repo rebase - manual page for repo rebase
 .SH SYNOPSIS
@@ -46,6 +46,19 @@ only show errors
 .TP
 \fB\-i\fR, \fB\-\-interactive\fR
 interactive rebase (single project only)
+.SS Multi\-manifest options:
+.TP
+\fB\-\-outer\-manifest\fR
+operate starting at the outermost manifest
+.TP
+\fB\-\-no\-outer\-manifest\fR
+do not operate on outer manifests
+.TP
+\fB\-\-this\-manifest\-only\fR
+only operate on this (sub)manifest
+.TP
+\fB\-\-no\-this\-manifest\-only\fR, \fB\-\-all\-manifests\fR
+operate on this manifest and its submanifests
 .PP
 Run `repo help rebase` to view the detailed manual.
 .SH DETAILS
--- a/man/repo-selfupdate.1
+++ b/man/repo-selfupdate.1
@@ -1,5 +1,5 @@
 .\" DO NOT MODIFY THIS FILE!  It was generated by help2man.
-.TH REPO "1" "July 2021" "repo selfupdate" "Repo Manual"
+.TH REPO "1" "July 2022" "repo selfupdate" "Repo Manual"
 .SH NAME
 repo \- repo selfupdate - manual page for repo selfupdate
 .SH SYNOPSIS
@@ -20,6 +20,19 @@ show all output
 .TP
 \fB\-q\fR, \fB\-\-quiet\fR
 only show errors
+.SS Multi\-manifest options:
+.TP
+\fB\-\-outer\-manifest\fR
+operate starting at the outermost manifest
+.TP
+\fB\-\-no\-outer\-manifest\fR
+do not operate on outer manifests
+.TP
+\fB\-\-this\-manifest\-only\fR
+only operate on this (sub)manifest
+.TP
+\fB\-\-no\-this\-manifest\-only\fR, \fB\-\-all\-manifests\fR
+operate on this manifest and its submanifests
 .SS repo Version options:
 .TP
 \fB\-\-no\-repo\-verify\fR
--- a/man/repo-smartsync.1
+++ b/man/repo-smartsync.1
@@ -1,5 +1,5 @@
 .\" DO NOT MODIFY THIS FILE!  It was generated by help2man.
-.TH REPO "1" "November 2021" "repo smartsync" "Repo Manual"
+.TH REPO "1" "July 2022" "repo smartsync" "Repo Manual"
 .SH NAME
 repo \- repo smartsync - manual page for repo smartsync
 .SH SYNOPSIS
@@ -112,6 +112,19 @@ show all output
 .TP
 \fB\-q\fR, \fB\-\-quiet\fR
 only show errors
+.SS Multi\-manifest options:
+.TP
+\fB\-\-outer\-manifest\fR
+operate starting at the outermost manifest
+.TP
+\fB\-\-no\-outer\-manifest\fR
+do not operate on outer manifests
+.TP
+\fB\-\-this\-manifest\-only\fR
+only operate on this (sub)manifest
+.TP
+\fB\-\-no\-this\-manifest\-only\fR, \fB\-\-all\-manifests\fR
+operate on this manifest and its submanifests
 .SS repo Version options:
 .TP
 \fB\-\-no\-repo\-verify\fR
--- a/man/repo-stage.1
+++ b/man/repo-stage.1
@@ -1,5 +1,5 @@
 .\" DO NOT MODIFY THIS FILE!  It was generated by help2man.
-.TH REPO "1" "July 2021" "repo stage" "Repo Manual"
+.TH REPO "1" "July 2022" "repo stage" "Repo Manual"
 .SH NAME
 repo \- repo stage - manual page for repo stage
 .SH SYNOPSIS
@@ -23,6 +23,19 @@ only show errors
 .TP
 \fB\-i\fR, \fB\-\-interactive\fR
 use interactive staging
+.SS Multi\-manifest options:
+.TP
+\fB\-\-outer\-manifest\fR
+operate starting at the outermost manifest
+.TP
+\fB\-\-no\-outer\-manifest\fR
+do not operate on outer manifests
+.TP
+\fB\-\-this\-manifest\-only\fR
+only operate on this (sub)manifest
+.TP
+\fB\-\-no\-this\-manifest\-only\fR, \fB\-\-all\-manifests\fR
+operate on this manifest and its submanifests
 .PP
 Run `repo help stage` to view the detailed manual.
 .SH DETAILS
--- a/man/repo-start.1
+++ b/man/repo-start.1
@@ -1,5 +1,5 @@
 .\" DO NOT MODIFY THIS FILE!  It was generated by help2man.
-.TH REPO "1" "July 2021" "repo start" "Repo Manual"
+.TH REPO "1" "July 2022" "repo start" "Repo Manual"
 .SH NAME
 repo \- repo start - manual page for repo start
 .SH SYNOPSIS
@@ -33,6 +33,19 @@ show all output
 .TP
 \fB\-q\fR, \fB\-\-quiet\fR
 only show errors
+.SS Multi\-manifest options:
+.TP
+\fB\-\-outer\-manifest\fR
+operate starting at the outermost manifest
+.TP
+\fB\-\-no\-outer\-manifest\fR
+do not operate on outer manifests
+.TP
+\fB\-\-this\-manifest\-only\fR
+only operate on this (sub)manifest
+.TP
+\fB\-\-no\-this\-manifest\-only\fR, \fB\-\-all\-manifests\fR
+operate on this manifest and its submanifests
 .PP
 Run `repo help start` to view the detailed manual.
 .SH DETAILS
--- a/man/repo-status.1
+++ b/man/repo-status.1
@@ -1,5 +1,5 @@
 .\" DO NOT MODIFY THIS FILE!  It was generated by help2man.
-.TH REPO "1" "July 2021" "repo status" "Repo Manual"
+.TH REPO "1" "July 2022" "repo status" "Repo Manual"
 .SH NAME
 repo \- repo status - manual page for repo status
 .SH SYNOPSIS
@@ -28,6 +28,19 @@ show all output
 .TP
 \fB\-q\fR, \fB\-\-quiet\fR
 only show errors
+.SS Multi\-manifest options:
+.TP
+\fB\-\-outer\-manifest\fR
+operate starting at the outermost manifest
+.TP
+\fB\-\-no\-outer\-manifest\fR
+do not operate on outer manifests
+.TP
+\fB\-\-this\-manifest\-only\fR
+only operate on this (sub)manifest
+.TP
+\fB\-\-no\-this\-manifest\-only\fR, \fB\-\-all\-manifests\fR
+operate on this manifest and its submanifests
 .PP
 Run `repo help status` to view the detailed manual.
 .SH DETAILS
--- a/man/repo-sync.1
+++ b/man/repo-sync.1
@@ -1,5 +1,5 @@
 .\" DO NOT MODIFY THIS FILE!  It was generated by help2man.
-.TH REPO "1" "November 2021" "repo sync" "Repo Manual"
+.TH REPO "1" "July 2022" "repo sync" "Repo Manual"
 .SH NAME
 repo \- repo sync - manual page for repo sync
 .SH SYNOPSIS
@@ -119,6 +119,19 @@ show all output
 .TP
 \fB\-q\fR, \fB\-\-quiet\fR
 only show errors
+.SS Multi\-manifest options:
+.TP
+\fB\-\-outer\-manifest\fR
+operate starting at the outermost manifest
+.TP
+\fB\-\-no\-outer\-manifest\fR
+do not operate on outer manifests
+.TP
+\fB\-\-this\-manifest\-only\fR
+only operate on this (sub)manifest
+.TP
+\fB\-\-no\-this\-manifest\-only\fR, \fB\-\-all\-manifests\fR
+operate on this manifest and its submanifests
 .SS repo Version options:
 .TP
 \fB\-\-no\-repo\-verify\fR
--- a/man/repo-upload.1
+++ b/man/repo-upload.1
@@ -1,5 +1,5 @@
 .\" DO NOT MODIFY THIS FILE!  It was generated by help2man.
-.TH REPO "1" "July 2021" "repo upload" "Repo Manual"
+.TH REPO "1" "July 2022" "repo upload" "Repo Manual"
 .SH NAME
 repo \- repo upload - manual page for repo upload
 .SH SYNOPSIS
@@ -75,6 +75,19 @@ show all output
 .TP
 \fB\-q\fR, \fB\-\-quiet\fR
 only show errors
+.SS Multi\-manifest options:
+.TP
+\fB\-\-outer\-manifest\fR
+operate starting at the outermost manifest
+.TP
+\fB\-\-no\-outer\-manifest\fR
+do not operate on outer manifests
+.TP
+\fB\-\-this\-manifest\-only\fR
+only operate on this (sub)manifest
+.TP
+\fB\-\-no\-this\-manifest\-only\fR, \fB\-\-all\-manifests\fR
+operate on this manifest and its submanifests
 .SS pre\-upload hooks:
 .TP
 \fB\-\-no\-verify\fR
--- a/man/repo-version.1
+++ b/man/repo-version.1
@@ -1,5 +1,5 @@
 .\" DO NOT MODIFY THIS FILE!  It was generated by help2man.
-.TH REPO "1" "July 2021" "repo version" "Repo Manual"
+.TH REPO "1" "July 2022" "repo version" "Repo Manual"
 .SH NAME
 repo \- repo version - manual page for repo version
 .SH SYNOPSIS
@@ -20,5 +20,18 @@ show all output
 .TP
 \fB\-q\fR, \fB\-\-quiet\fR
 only show errors
+.SS Multi\-manifest options:
+.TP
+\fB\-\-outer\-manifest\fR
+operate starting at the outermost manifest
+.TP
+\fB\-\-no\-outer\-manifest\fR
+do not operate on outer manifests
+.TP
+\fB\-\-this\-manifest\-only\fR
+only operate on this (sub)manifest
+.TP
+\fB\-\-no\-this\-manifest\-only\fR, \fB\-\-all\-manifests\fR
+operate on this manifest and its submanifests
 .PP
 Run `repo help version` to view the detailed manual.
--- a/man/repo.1
+++ b/man/repo.1
@@ -1,5 +1,5 @@
 .\" DO NOT MODIFY THIS FILE!  It was generated by help2man.
-.TH REPO "1" "November 2021" "repo" "Repo Manual"
+.TH REPO "1" "July 2022" "repo" "Repo Manual"
 .SH NAME
 repo \- repository management tool built on top of git
 .SH SYNOPSIS
@@ -43,6 +43,9 @@ filename of event log to append timeline to
 .TP
 \fB\-\-git\-trace2\-event\-log\fR=\fI\,GIT_TRACE2_EVENT_LOG\/\fR
 directory to write git trace2 event log to
+.TP
+\fB\-\-submanifest\-path\fR=\fI\,REL_PATH\/\fR
+submanifest path
 .SS "The complete list of recognized repo commands is:"
 .TP
 abandon
--- a/manifest_xml.py
+++ b/manifest_xml.py
@@ -348,7 +348,7 @@ class XmlManifest(object):
          be |repodir|/|MANIFEST_FILE_NAME|.
      local_manifests: Full path to the directory of local override manifests.
          This will usually be |repodir|/|LOCAL_MANIFESTS_DIR_NAME|.
-      outer_client: RepoClient of the outertree.
+      outer_client: RepoClient of the outer manifest.
      parent_groups: a string, the groups to apply to this projects.
      submanifest_path: The submanifest root relative to the repo root.
      default_groups: a string, the default manifest groups to use.
@@ -502,7 +502,8 @@ https://gerrit.googlesource.com/git-repo/+/HEAD/docs/manifest-format.md
    """
    return [x for x in re.split(r'[,\s]+', field) if x]

-  def ToXml(self, peg_rev=False, peg_rev_upstream=True, peg_rev_dest_branch=True, groups=None):
+  def ToXml(self, peg_rev=False, peg_rev_upstream=True,
+            peg_rev_dest_branch=True, groups=None, omit_local=False):
    """Return the current manifest XML."""
    mp = self.manifestProject

@@ -583,6 +584,9 @@ https://gerrit.googlesource.com/git-repo/+/HEAD/docs/manifest-format.md
      if not p.MatchesGroups(groups):
        return

+      if omit_local and self.IsFromLocalManifest(p):
+        return
+
      name = p.name
      relpath = p.relpath
      if parent:
@@ -776,18 +780,21 @@ https://gerrit.googlesource.com/git-repo/+/HEAD/docs/manifest-format.md

  @property
  def is_submanifest(self):
-    """Whether this manifest is a submanifest"""
+    """Whether this manifest is a submanifest.
+
+    This is safe to use as long as the outermost manifest XML has been parsed.
+    """
    return self._outer_client and self._outer_client != self

  @property
  def outer_client(self):
-    """The instance of the outermost manifest client"""
+    """The instance of the outermost manifest client."""
    self._Load()
    return self._outer_client

  @property
  def all_manifests(self):
-    """Generator yielding all (sub)manifests."""
+    """Generator yielding all (sub)manifests, in depth-first order."""
    self._Load()
    outer = self._outer_client
    yield outer
@@ -796,7 +803,7 @@ https://gerrit.googlesource.com/git-repo/+/HEAD/docs/manifest-format.md

  @property
  def all_children(self):
-    """Generator yielding all child submanifests."""
+    """Generator yielding all (present) child submanifests."""
    self._Load()
    for child in self._submanifests.values():
      if child.repo_client:
@@ -813,7 +820,14 @@ https://gerrit.googlesource.com/git-repo/+/HEAD/docs/manifest-format.md

  @property
  def all_paths(self):
-    """All project paths for all (sub)manifests.  See `paths`."""
+    """All project paths for all (sub)manifests.
+
+    See also `paths`.
+
+    Returns:
+      A dictionary of {path: Project()}.  `path` is relative to the outer
+      manifest.
+    """
    ret = {}
    for tree in self.all_manifests:
      prefix = tree.path_prefix
@@ -829,7 +843,7 @@ https://gerrit.googlesource.com/git-repo/+/HEAD/docs/manifest-format.md
  def paths(self):
    """Return all paths for this manifest.

-    Return:
+    Returns:
      A dictionary of {path: Project()}.  `path` is relative to this manifest.
    """
    self._Load()
@@ -843,11 +857,13 @@ https://gerrit.googlesource.com/git-repo/+/HEAD/docs/manifest-format.md

  @property
  def remotes(self):
+    """Return a list of remotes for this manifest."""
    self._Load()
    return self._remotes

  @property
  def default(self):
+    """Return default values for this manifest."""
    self._Load()
    return self._default

@@ -1090,8 +1106,8 @@ https://gerrit.googlesource.com/git-repo/+/HEAD/docs/manifest-format.md
        if override:
          self.manifestFile = savedManifestFile

-      # Now that we have loaded this manifest, load any submanifest  manifests
-      # as well.  We need to do this after self._loaded is set to avoid looping.
+      # Now that we have loaded this manifest, load any submanifests as well.
+      # We need to do this after self._loaded is set to avoid looping.
      for name in self._submanifests:
        tree = self._submanifests[name]
        spec = tree.ToSubmanifestSpec()
@@ -1659,6 +1675,10 @@ https://gerrit.googlesource.com/git-repo/+/HEAD/docs/manifest-format.md
      name: a string, the name of the project.
      path: a string, the path of the project.
      remote: a string, the remote.name of the project.
+
+    Returns:
+      A tuple of (relpath, worktree, gitdir, objdir, use_git_worktrees) for the
+      project with |name| and |path|.
    """
    # The manifest entries might have trailing slashes.  Normalize them to avoid
    # unexpected filesystem behavior since we do string concatenation below.
@@ -1666,7 +1686,7 @@ https://gerrit.googlesource.com/git-repo/+/HEAD/docs/manifest-format.md
    name = name.rstrip('/')
    remote = remote.rstrip('/')
    use_git_worktrees = False
-    use_remote_name = bool(self._outer_client._submanifests)
+    use_remote_name = self.is_multimanifest
    relpath = path
    if self.IsMirror:
      worktree = None
@@ -1696,6 +1716,9 @@ https://gerrit.googlesource.com/git-repo/+/HEAD/docs/manifest-format.md
      name: a string, the name of the project.
      all_manifests: a boolean, if True, then all manifests are searched. If
                     False, then only this manifest is searched.
+
+    Returns:
+      A list of Project instances with name |name|.
    """
    if all_manifests:
      return list(itertools.chain.from_iterable(
@@ -1956,6 +1979,16 @@ class RepoClient(XmlManifest):
  """Manages a repo client checkout."""

  def __init__(self, repodir, manifest_file=None, submanifest_path='', **kwargs):
+    """Initialize.
+
+    Args:
+      repodir: Path to the .repo/ dir for holding all internal checkout state.
+          It must be in the top directory of the repo client checkout.
+      manifest_file: Full path to the manifest file to parse.  This will usually
+          be |repodir|/|MANIFEST_FILE_NAME|.
+      submanifest_path: The submanifest root relative to the repo root.
+      **kwargs: Additional keyword arguments, passed to XmlManifest.
+    """
    self.isGitcClient = False
    submanifest_path = submanifest_path or ''
    if submanifest_path:
--- a/project.py
+++ b/project.py
@@ -33,6 +33,7 @@ import fetch
 from git_command import GitCommand, git_require
 from git_config import GitConfig, IsId, GetSchemeFromUrl, GetUrlCookieFile, \
    ID_RE
+import git_superproject
 from git_trace2_event_log import EventLog
 from error import GitError, UploadError, DownloadError
 from error import ManifestInvalidRevisionError, ManifestInvalidPathError
@@ -463,7 +464,13 @@ class RemoteSpec(object):

 class Project(object):
  # These objects can be shared between several working trees.
-  shareable_dirs = ['hooks', 'rr-cache']
+  @property
+  def shareable_dirs(self):
+    """Return the shareable directories"""
+    if self.UseAlternates:
+      return ['hooks', 'rr-cache']
+    else:
+      return ['hooks', 'objects', 'rr-cache']

  def __init__(self,
               manifest,
@@ -593,6 +600,14 @@ class Project(object):
    self.bare_ref = GitRefs(self.gitdir)
    self.bare_objdir = self._GitGetByExec(self, bare=True, gitdir=self.objdir)

+  @property
+  def UseAlternates(self):
+    """Whether git alternates are in use.
+
+    This will be removed once migration to alternates is complete.
+    """
+    return _ALTERNATES or self.manifest.is_multimanifest
+
  @property
  def Derived(self):
    return self.is_derived
@@ -635,7 +650,7 @@ class Project(object):
      return True
    if self.work_git.DiffZ('diff-files'):
      return True
-    if consider_untracked and self.work_git.LsOthers():
+    if consider_untracked and self.UntrackedFiles():
      return True
    return False

@@ -764,33 +779,37 @@ class Project(object):
      if not get_all:
        return details

-    changes = self.work_git.LsOthers()
+    changes = self.UntrackedFiles()
    if changes:
      details.extend(changes)

    return details

+  def UntrackedFiles(self):
+    """Returns a list of strings, untracked files in the git tree."""
+    return self.work_git.LsOthers()
+
  def HasChanges(self):
    """Returns true if there are uncommitted changes.
    """
-    if self.UncommitedFiles(get_all=False):
-      return True
-    else:
-      return False
+    return bool(self.UncommitedFiles(get_all=False))

-  def PrintWorkTreeStatus(self, output_redir=None, quiet=False):
+  def PrintWorkTreeStatus(self, output_redir=None, quiet=False, local=False):
    """Prints the status of the repository to stdout.

    Args:
      output_redir: If specified, redirect the output to this object.
      quiet:  If True then only print the project name.  Do not print
              the modified files, branch name, etc.
+      local: a boolean, if True, the path is relative to the local
+             (sub)manifest.  If false, the path is relative to the
+             outermost manifest.
    """
    if not platform_utils.isdir(self.worktree):
      if output_redir is None:
        output_redir = sys.stdout
      print(file=output_redir)
-      print('project %s/' % self.relpath, file=output_redir)
+      print('project %s/' % self.RelPath(local), file=output_redir)
      print('  missing (run "repo sync")', file=output_redir)
      return

@@ -808,7 +827,7 @@ class Project(object):
    out = StatusColoring(self.config)
    if output_redir is not None:
      out.redirect(output_redir)
-    out.project('project %-40s', self.relpath + '/ ')
+    out.project('project %-40s', self.RelPath(local) + '/ ')

    if quiet:
      out.nl()
@@ -869,7 +888,8 @@ class Project(object):

    return 'DIRTY'

-  def PrintWorkTreeDiff(self, absolute_paths=False, output_redir=None):
+  def PrintWorkTreeDiff(self, absolute_paths=False, output_redir=None,
+                        local=False):
    """Prints the status of the repository to stdout.
    """
    out = DiffColoring(self.config)
@@ -880,8 +900,8 @@ class Project(object):
      cmd.append('--color')
    cmd.append(HEAD)
    if absolute_paths:
-      cmd.append('--src-prefix=a/%s/' % self.relpath)
-      cmd.append('--dst-prefix=b/%s/' % self.relpath)
+      cmd.append('--src-prefix=a/%s/' % self.RelPath(local))
+      cmd.append('--dst-prefix=b/%s/' % self.RelPath(local))
    cmd.append('--')
    try:
      p = GitCommand(self,
@@ -891,14 +911,14 @@ class Project(object):
      p.Wait()
    except GitError as e:
      out.nl()
-      out.project('project %s/' % self.relpath)
+      out.project('project %s/' % self.RelPath(local))
      out.nl()
      out.fail('%s', str(e))
      out.nl()
      return False
    if p.stdout:
      out.nl()
-      out.project('project %s/' % self.relpath)
+      out.project('project %s/' % self.RelPath(local))
      out.nl()
      out.write('%s', p.stdout)
    return p.Wait() == 0
@@ -1146,7 +1166,7 @@ class Project(object):
      self._UpdateHooks(quiet=quiet)
    self._InitRemote()

-    if _ALTERNATES or self.manifest.is_multimanifest:
+    if self.UseAlternates:
      # If gitdir/objects is a symlink, migrate it from the old layout.
      gitdir_objects = os.path.join(self.gitdir, 'objects')
      if platform_utils.islink(gitdir_objects):
@@ -1537,14 +1557,14 @@ class Project(object):
    if self.IsDirty():
      if force:
        print('warning: %s: Removing dirty project: uncommitted changes lost.' %
-              (self.relpath,), file=sys.stderr)
+              (self.RelPath(local=False),), file=sys.stderr)
      else:
        print('error: %s: Cannot remove project: uncommitted changes are '
-              'present.\n' % (self.relpath,), file=sys.stderr)
+              'present.\n' % (self.RelPath(local=False),), file=sys.stderr)
        return False

    if not quiet:
-      print('%s: Deleting obsolete checkout.' % (self.relpath,))
+      print('%s: Deleting obsolete checkout.' % (self.RelPath(local=False),))

    # Unlock and delink from the main worktree.  We don't use git's worktree
    # remove because it will recursively delete projects -- we handle that
@@ -1583,7 +1603,8 @@ class Project(object):
      if e.errno != errno.ENOENT:
        print('error: %s: %s' % (self.gitdir, e), file=sys.stderr)
        print('error: %s: Failed to delete obsolete checkout; remove manually, '
-              'then run `repo sync -l`.' % (self.relpath,), file=sys.stderr)
+              'then run `repo sync -l`.' % (self.RelPath(local=False),),
+              file=sys.stderr)
        return False

    # Delete everything under the worktree, except for directories that contain
@@ -1619,7 +1640,7 @@ class Project(object):
            print('error: %s: Failed to remove: %s' % (d, e), file=sys.stderr)
            failed = True
    if failed:
-      print('error: %s: Failed to delete obsolete checkout.' % (self.relpath,),
+      print('error: %s: Failed to delete obsolete checkout.' % (self.RelPath(local=False),),
            file=sys.stderr)
      print('       Remove manually, then run `repo sync -l`.', file=sys.stderr)
      return False
@@ -2034,7 +2055,7 @@ class Project(object):
  def _FetchArchive(self, tarpath, cwd=None):
    cmd = ['archive', '-v', '-o', tarpath]
    cmd.append('--remote=%s' % self.remote.url)
-    cmd.append('--prefix=%s/' % self.relpath)
+    cmd.append('--prefix=%s/' % self.RelPath(local=False))
    cmd.append(self.revisionExpr)

    command = GitCommand(self, cmd, cwd=cwd,
@@ -2180,6 +2201,8 @@ class Project(object):
    if prune:
      cmd.append('--prune')

+    # Always pass something for --recurse-submodules, git with GIT_DIR behaves
+    # incorrectly when not given `--recurse-submodules=no`. (b/218891912)
    cmd.append(f'--recurse-submodules={"on-demand" if submodules else "no"}')

    spec = []
@@ -2616,7 +2639,7 @@ class Project(object):
        if not filecmp.cmp(stock_hook, dst, shallow=False):
          if not quiet:
            _warn("%s: Not replacing locally modified %s hook",
-                  self.relpath, name)
+                  self.RelPath(local=False), name)
        continue
      try:
        platform_utils.symlink(
@@ -2711,7 +2734,7 @@ class Project(object):
                         'work tree. If you\'re comfortable with the '
                         'possibility of losing the work tree\'s git metadata,'
                         ' use `repo sync --force-sync {0}` to '
-                         'proceed.'.format(self.relpath))
+                         'proceed.'.format(self.RelPath(local=False)))

  def _ReferenceGitDir(self, gitdir, dotgit, copy_all):
    """Update |dotgit| to reference |gitdir|, using symlinks where possible.
@@ -3191,7 +3214,7 @@ class _InfoMessage(object):
    self.text = text

  def Print(self, syncbuf):
-    syncbuf.out.info('%s/: %s', self.project.relpath, self.text)
+    syncbuf.out.info('%s/: %s', self.project.RelPath(local=False), self.text)
    syncbuf.out.nl()


@@ -3203,7 +3226,7 @@ class _Failure(object):

  def Print(self, syncbuf):
    syncbuf.out.fail('error: %s/: %s',
-                     self.project.relpath,
+                     self.project.RelPath(local=False),
                     str(self.why))
    syncbuf.out.nl()

@@ -3216,7 +3239,7 @@ class _Later(object):

  def Run(self, syncbuf):
    out = syncbuf.out
-    out.project('project %s/', self.project.relpath)
+    out.project('project %s/', self.project.RelPath(local=False))
    out.nl()
    try:
      self.action()
@@ -3486,8 +3509,8 @@ class ManifestProject(MetaProject):
      git_event_log: an EventLog, for git tracing.
    """
    # TODO(lamontjones): when refactoring sync (and init?) consider how to
-    # better get the init options that we should use when syncing uncovers a new
-    # submanifest.
+    # better get the init options that we should use for new submanifests that
+    # are added when syncing an existing workspace.
    git_event_log = git_event_log or EventLog()
    spec = submanifest.ToSubmanifestSpec()
    # Use the init options from the existing manifestProject, or the parent if
@@ -3874,8 +3897,8 @@ class ManifestProject(MetaProject):
        )

    # Lastly, if the manifest has a <superproject> then have the superproject
-    # sync it if it will be used.
-    if self.manifest.superproject:
+    # sync it (if it will be used).
+    if git_superproject.UseSuperproject(use_superproject, self.manifest):
      sync_result = self.manifest.superproject.Sync(git_event_log)
      if not sync_result.success:
        print('warning: git update of superproject for '
--- a/subcmds/diff.py
+++ b/subcmds/diff.py
@@ -35,18 +35,21 @@ to the Unix 'patch' command.
                 dest='absolute', action='store_true',
                 help='paths are relative to the repository root')

-  def _ExecuteOne(self, absolute, project):
+  def _ExecuteOne(self, absolute, local, project):
    """Obtains the diff for a specific project.

    Args:
      absolute: Paths are relative to the root.
+      local: a boolean, if True, the path is relative to the local
+             (sub)manifest.  If false, the path is relative to the
+             outermost manifest.
      project: Project to get status of.

    Returns:
      The status of the project.
    """
    buf = io.StringIO()
-    ret = project.PrintWorkTreeDiff(absolute, output_redir=buf)
+    ret = project.PrintWorkTreeDiff(absolute, output_redir=buf, local=local)
    return (ret, buf.getvalue())

  def Execute(self, opt, args):
@@ -63,7 +66,7 @@ to the Unix 'patch' command.

    return self.ExecuteInParallel(
        opt.jobs,
-        functools.partial(self._ExecuteOne, opt.absolute),
+        functools.partial(self._ExecuteOne, opt.absolute, opt.this_manifest_only),
        all_projects,
        callback=_ProcessResults,
        ordered=True)
--- a/subcmds/status.py
+++ b/subcmds/status.py
@@ -83,7 +83,7 @@ the following meanings:
                 dest='orphans', action='store_true',
                 help="include objects in working directory outside of repo projects")

-  def _StatusHelper(self, quiet, project):
+  def _StatusHelper(self, quiet, local, project):
    """Obtains the status for a specific project.

    Obtains the status for a project, redirecting the output to
@@ -91,13 +91,17 @@ the following meanings:

    Args:
      quiet: Where to output the status.
+      local: a boolean, if True, the path is relative to the local
+             (sub)manifest.  If false, the path is relative to the
+             outermost manifest.
      project: Project to get status of.

    Returns:
      The status of the project.
    """
    buf = io.StringIO()
-    ret = project.PrintWorkTreeStatus(quiet=quiet, output_redir=buf)
+    ret = project.PrintWorkTreeStatus(quiet=quiet, output_redir=buf,
+                                      local=local)
    return (ret, buf.getvalue())

  def _FindOrphans(self, dirs, proj_dirs, proj_dirs_parents, outstring):
@@ -130,7 +134,7 @@ the following meanings:

    counter = self.ExecuteInParallel(
        opt.jobs,
-        functools.partial(self._StatusHelper, opt.quiet),
+        functools.partial(self._StatusHelper, opt.quiet, opt.this_manifest_only),
        all_projects,
        callback=_ProcessResults,
        ordered=True)
--- a/subcmds/sync.py
+++ b/subcmds/sync.py
@@ -316,7 +316,7 @@ later is required to fix a server side protocol bug.
    if not have_superproject:
      return

-    if opt.local_only:
+    if opt.local_only and manifest.superproject:
      manifest_path = manifest.superproject.manifest_path
      if manifest_path:
        self._ReloadManifest(manifest_path, manifest)
--- a/subcmds/upload.py
+++ b/subcmds/upload.py
@@ -204,6 +204,12 @@ Gerrit Code Review:  https://www.gerritcodereview.com/
    p.add_option('-y', '--yes',
                 default=False, action='store_true',
                 help='answer yes to all safe prompts')
+    p.add_option('--ignore-untracked-files',
+                 action='store_true', default=False,
+                 help='ignore untracked files in the working copy')
+    p.add_option('--no-ignore-untracked-files',
+                 dest='ignore_untracked_files', action='store_false',
+                 help='always ask about untracked files in the working copy')
    p.add_option('--no-cert-checks',
                 dest='validate_certs', action='store_false', default=True,
                 help='disable verifying ssl certs (unsafe)')
@@ -370,6 +376,10 @@ Gerrit Code Review:  https://www.gerritcodereview.com/

        # Check if there are local changes that may have been forgotten
        changes = branch.project.UncommitedFiles()
+        if opt.ignore_untracked_files:
+          untracked = set(branch.project.UntrackedFiles())
+          changes = [x for x in changes if x not in untracked]
+
        if changes:
          key = 'review.%s.autoupload' % branch.project.remote.review
          answer = branch.project.config.GetBoolean(key)
--- a/tests/test_git_superproject.py
+++ b/tests/test_git_superproject.py
@@ -312,9 +312,6 @@ class SuperprojectTestCase(unittest.TestCase):
              '<project groups="notdefault,platform-' + self.platform + '" '
              'name="platform/art" path="art" '
              'revision="2c2724cb36cd5a9cec6c852c681efc3b7c6b86ea" upstream="refs/heads/main"/>'
-              '<project clone-depth="1" groups="' + local_group + '" '
-              'name="platform/vendor/x" path="vendor/x" remote="goog" '
-              'revision="master-with-vendor"/>'
              '<superproject name="superproject"/>'
              '</manifest>')

--- a/tests/test_manifest_xml.py
+++ b/tests/test_manifest_xml.py
@@ -252,6 +252,37 @@ class XmlManifestTests(ManifestParseTestCase):
        '<manifest></manifest>')
    self.assertEqual(manifest.ToDict(), {})

+  def test_toxml_omit_local(self):
+    """Does not include local_manifests projects when omit_local=True."""
+    manifest = self.getXmlManifest(
+        '<?xml version="1.0" encoding="UTF-8"?><manifest>'
+        '<remote name="a" fetch=".."/><default remote="a" revision="r"/>'
+        '<project name="p" groups="local::me"/>'
+        '<project name="q"/>'
+        '<project name="r" groups="keep"/>'
+        '</manifest>')
+    self.assertEqual(
+        manifest.ToXml(omit_local=True).toxml(),
+        '<?xml version="1.0" ?><manifest>'
+        '<remote name="a" fetch=".."/><default remote="a" revision="r"/>'
+        '<project name="q"/><project name="r" groups="keep"/></manifest>')
+
+  def test_toxml_with_local(self):
+    """Does include local_manifests projects when omit_local=False."""
+    manifest = self.getXmlManifest(
+        '<?xml version="1.0" encoding="UTF-8"?><manifest>'
+        '<remote name="a" fetch=".."/><default remote="a" revision="r"/>'
+        '<project name="p" groups="local::me"/>'
+        '<project name="q"/>'
+        '<project name="r" groups="keep"/>'
+        '</manifest>')
+    self.assertEqual(
+        manifest.ToXml(omit_local=False).toxml(),
+        '<?xml version="1.0" ?><manifest>'
+        '<remote name="a" fetch=".."/><default remote="a" revision="r"/>'
+        '<project name="p" groups="local::me"/>'
+        '<project name="q"/><project name="r" groups="keep"/></manifest>')
+
  def test_repo_hooks(self):
    """Check repo-hooks settings."""
    manifest = self.getXmlManifest("""
Author	SHA1	Message	Date
LaMont Jones	a8cf575d68	Omit local_manifest groups from superproject override. When we create superproject_override.xml, do not include projects that are present from local_manifests/*. Such projects are fully under the control of the local_manifests/ file. Bug: b/238934278 Test: manual, ./run_tests Change-Id: I40382ceb82d9cf7b8dc7b5f2abed3f6d4d80017e Reviewed-on: https://gerrit-review.googlesource.com/c/git-repo/+/340877 Tested-by: Xin Li <delphij@google.com> Reviewed-by: Xin Li <delphij@google.com> Reviewed-by: Sam Saccone 🐐 <samccone@google.com>	2022-07-15 23:32:24 +00:00
LaMont Jones	8501d4602a	status, diff: display correct path for multi-manifest Display the project path relative to the outermost manifest by default, and relative to the sub manifest only when --this-manifest-only is specified. For project-related diagnostic messages, use the outermost manifest for messages. Change-Id: I4537d7dd412a2c182e77d6720e95c1b0ef70eb0e Reviewed-on: https://gerrit-review.googlesource.com/c/git-repo/+/340754 Reviewed-by: Mike Frysinger <vapier@google.com> Tested-by: LaMont Jones <lamontjones@google.com>	2022-07-14 16:00:18 +00:00
Martin Geisler	8db78c7d4d	project: simplify if-statement Change-Id: I05e4505b45963fe6e85cf74a669afafd00fc83c0 Reviewed-on: https://gerrit-review.googlesource.com/c/git-repo/+/340457 Reviewed-by: Mike Frysinger <vapier@google.com> Tested-by: Martin Geisler <mgeisler@google.com>	2022-07-11 17:58:06 +00:00
Martin Geisler	9fb64ae29c	upload: add ‘--ignore-untracked-files’ option This option will suppress the Uncommitted changes in ... (did you forget to amend?) prompt when there are untracked (unknown) files in the working copy. The prompt is still shown if tracked files are modified. Change-Id: Ia3fcc82989b7fad09b69214eda31e2d0dfc14600 Reviewed-on: https://gerrit-review.googlesource.com/c/git-repo/+/340456 Tested-by: Martin Geisler <mgeisler@google.com> Reviewed-by: Mike Frysinger <vapier@google.com>	2022-07-11 17:57:43 +00:00
Mike Frysinger	d47d9ff1cb	man: regenerate Change-Id: I3ca8ca8f502605b194ebe65b315eda08c51592a6 Reviewed-on: https://gerrit-review.googlesource.com/c/git-repo/+/340494 Reviewed-by: LaMont Jones <lamontjones@google.com> Tested-by: Mike Frysinger <vapier@google.com>	2022-07-11 16:42:23 +00:00
LaMont Jones	68d69635c7	Fix Projects.shareable_dirs If this tree is not using alternates for object sharing, then we need to continue to call it a shared directory. Bug: https://bugs.chromium.org/p/gerrit/issues/detail?id=15982 Test: manual Change-Id: I1750f10b192504ac67f552222f8ddb9809d344fe Reviewed-on: https://gerrit-review.googlesource.com/c/git-repo/+/338974 Tested-by: LaMont Jones <lamontjones@google.com> Reviewed-by: Mike Frysinger <vapier@google.com>	2022-06-08 16:49:08 +00:00
LaMont Jones	ff6b1dae1e	Only sync superproject if it will be used. If the user says `--no-use-superproject`, then do not bother syncing the superproject. Also add/update docstrings and comments throughout. Change-Id: I9cdad706130501bab9a22d3099a1dae605e9c194 Reviewed-on: https://gerrit-review.googlesource.com/c/git-repo/+/338975 Tested-by: LaMont Jones <lamontjones@google.com> Reviewed-by: Mike Frysinger <vapier@google.com>	2022-06-08 16:49:08 +00:00