sync: Share final error handling logic between sync modes

Dedupe error reporting logic for phased and interleaved sync modes by
extracting it into _ReportErrors.

Error reporting will now distinguish between network and local failures
and lists the specific repos that failed in each phase.

Bug: 421935613
Change-Id: I4604a83943dbbd71d979158d7a1c4b8c243347d2
Reviewed-on: https://gerrit-review.googlesource.com/c/git-repo/+/484541
Tested-by: Gavin Mak <gavinmak@google.com>
Reviewed-by: Scott Lee <ddoman@google.com>
Commit-Queue: Gavin Mak <gavinmak@google.com>

.flake8

@@ -1,3 +1,17 @@
 [flake8]
-max-line-length=80
-ignore=E111,E114,E402
+max-line-length = 80
+per-file-ignores =
+    # E501: line too long
+    tests/test_git_superproject.py: E501
+extend-ignore =
+    # E203: Whitespace before ':'
+    # See https://github.com/PyCQA/pycodestyle/issues/373
+    E203,
+    # E402: Module level import not at top of file
+    E402,
+    # E731: do not assign a lambda expression, use a def
+    E731,
+exclude =
+    .venv,
+    venv,
+    .tox,

.github/workflows/close-pull-request.yml

@@ -0,0 +1,22 @@
+# GitHub actions workflow.
+# https://docs.github.com/en/actions/learn-github-actions/workflow-syntax-for-github-actions
+
+# https://github.com/superbrothers/close-pull-request
+name: Close Pull Request
+
+on:
+  pull_request_target:
+    types: [opened]
+
+jobs:
+  run:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: superbrothers/close-pull-request@v3
+      with:
+        comment: >
+          Thanks for your contribution!
+          Unfortunately, we don't use GitHub pull requests to manage code
+          contributions to this repository.
+          Instead, please see [README.md](../blob/HEAD/SUBMITTING_PATCHES.md)
+          which provides full instructions on how to get involved.

.github/workflows/flake8-postsubmit.yml

@@ -0,0 +1,23 @@
+# GitHub actions workflow.
+# https://help.github.com/en/actions/automating-your-workflow-with-github-actions/workflow-syntax-for-github-actions
+# https://github.com/marketplace/actions/python-flake8
+
+name: Flake8
+
+on:
+  push:
+    branches: [main]
+
+jobs:
+  lint:
+    name: Python Lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-python@v4
+        with:
+          python-version: "3.9"
+      - name: Run flake8
+        uses: julianwachholz/flake8-action@v2
+        with:
+          checkName: "Python Lint"

.github/workflows/test-ci.yml

@@ -0,0 +1,32 @@
+# GitHub actions workflow.
+# https://help.github.com/en/actions/automating-your-workflow-with-github-actions/workflow-syntax-for-github-actions
+
+name: Test CI
+
+on:
+  push:
+    branches: [main, repo-1, stable, maint]
+    tags: [v*]
+
+jobs:
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        # ubuntu-20.04 is the last version that supports python 3.6
+        os: [ubuntu-20.04, macos-latest, windows-latest]
+        python-version: ['3.6', '3.7', '3.8', '3.9', '3.10', '3.11', '3.12']
+    runs-on: ${{ matrix.os }}
+
+    steps:
+    - uses: actions/checkout@v3
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v4
+      with:
+        python-version: ${{ matrix.python-version }}
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        python -m pip install tox tox-gh-actions
+    - name: Test with tox
+      run: tox

.gitignore

@@ -1,3 +1,4 @@
+*.asc
 *.egg-info/
 *.log
 *.pyc
@@ -6,6 +7,7 @@ __pycache__
 .repopickle_*
 /repoc
 /.tox
+/.venv
 
 # PyCharm related
 /.idea/

.gitreview

@@ -0,0 +1,5 @@
+[gerrit]
+host=gerrit-review.googlesource.com
+scheme=https
+project=git-repo.git
+defaultbranch=main

.isort.cfg

@@ -0,0 +1,41 @@
+# Copyright 2023 The Android Open Source Project
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# Config file for the isort python module.
+# This is used to enforce import sorting standards.
+#
+# https://pycqa.github.io/isort/docs/configuration/options.html
+
+[settings]
+# Be compatible with `black` since it also matches what we want.
+profile = black
+
+line_length = 80
+length_sort = false
+force_single_line = true
+lines_after_imports = 2
+from_first = false
+case_sensitive = false
+force_sort_within_sections = true
+order_by_type = false
+
+# Ignore generated files.
+extend_skip_glob = *_pb2.py
+
+# Allow importing multiple classes on a single line from these modules.
+# https://google.github.io/styleguide/pyguide#s2.2-imports
+single_line_exclusions =
+    abc,
+    collections.abc,
+    typing,

.mailmap

@@ -4,6 +4,7 @@ Hu Xiuyun <xiuyun.hu@hisilicon.com>           Hu xiuyun <xiuyun.hu@hisilicon.com
 Hu Xiuyun <xiuyun.hu@hisilicon.com>           Hu Xiuyun <clouds08@qq.com>
 Jelly Chen <chenguodong@huawei.com>           chenguodong <chenguodong@huawei.com>
 Jia Bi <bijia@xiaomi.com>                     bijia <bijia@xiaomi.com>
+Jiri Tyr <jiri.tyr@gmail.com>                 Jiri tyr <jiri.tyr@gmail.com>
 JoonCheol Park <jooncheol@gmail.com>          Jooncheol Park <jooncheol@gmail.com>
 Sergii Pylypenko <x.pelya.x@gmail.com>        pelya <x.pelya.x@gmail.com>
 Shawn Pearce <sop@google.com>                 Shawn O. Pearce <sop@google.com>

README.md

@@ -6,15 +6,29 @@ development workflow.  Repo is not meant to replace Git, only to make it
 easier to work with Git.  The repo command is an executable Python script
 that you can put anywhere in your path.
 
-* Homepage: https://gerrit.googlesource.com/git-repo/
-* Bug reports: https://bugs.chromium.org/p/gerrit/issues/list?q=component:repo
-* Source: https://gerrit.googlesource.com/git-repo/
-* Overview: https://source.android.com/source/developing.html
-* Docs: https://source.android.com/source/using-repo.html
+* Homepage: <https://gerrit.googlesource.com/git-repo/>
+* Mailing list: [repo-discuss on Google Groups][repo-discuss]
+* Bug reports: <https://issues.gerritcodereview.com/issues?q=is:open%20componentid:1370071>
+* Source: <https://gerrit.googlesource.com/git-repo/>
+* Overview: <https://source.android.com/source/developing.html>
+* Docs: <https://source.android.com/source/using-repo.html>
 * [repo Manifest Format](./docs/manifest-format.md)
 * [repo Hooks](./docs/repo-hooks.md)
 * [Submitting patches](./SUBMITTING_PATCHES.md)
 * Running Repo in [Microsoft Windows](./docs/windows.md)
+* GitHub mirror: <https://github.com/GerritCodeReview/git-repo>
+* Postsubmit tests: <https://github.com/GerritCodeReview/git-repo/actions>
+
+## Contact
+
+Please use the [repo-discuss] mailing list or [issue tracker] for questions.
+
+You can [file a new bug report][new-bug] under the "repo" component.
+
+Please do not e-mail individual developers for support.
+They do not have the bandwidth for it, and often times questions have already
+been asked on [repo-discuss] or bugs posted to the [issue tracker].
+So please search those sites first.
 
 ## Install
 
@@ -34,3 +48,8 @@ $ PATH="${HOME}/.bin:${PATH}"
 $ curl https://storage.googleapis.com/git-repo-downloads/repo > ~/.bin/repo
 $ chmod a+rx ~/.bin/repo
 ```
+
+
+[new-bug]: https://issues.gerritcodereview.com/issues/new?component=1370071
+[issue tracker]: https://issues.gerritcodereview.com/issues?q=is:open%20componentid:1370071
+[repo-discuss]: https://groups.google.com/forum/#!forum/repo-discuss

SUBMITTING_PATCHES.md

@@ -1,19 +1,19 @@
+# Submitting Changes
+
+Here's a short overview of the process.
+
+*   Make small logical changes.
+*   [Provide a meaningful commit message][commit-message-style].
+*   Make sure all code is under the Apache License, 2.0.
+*   Publish your changes for review.
+    *   `git push origin HEAD:refs/for/main`
+*   Make corrections if requested.
+*   [Verify your changes on Gerrit.](#verify)
+*   [Send to the commit queue for testing & merging.](#cq)
+
 [TOC]
 
-# Short Version
-
- - Make small logical changes.
- - Provide a meaningful commit message.
- - Check for coding errors and style nits with pyflakes and flake8
- - Make sure all code is under the Apache License, 2.0.
- - Publish your changes for review.
- - Make corrections if requested.
- - Verify your changes on gerrit so they can be submitted.
-
-   `git push https://gerrit-review.googlesource.com/git-repo HEAD:refs/for/master`
-
-
-# Long Version
+## Long Version
 
 I wanted a file describing how to submit patches for repo,
 so I started with the one found in the core Git distribution
@@ -26,10 +26,11 @@ yourself with the following relevant bits.
 
 ## Make separate commits for logically separate changes.
 
-Unless your patch is really trivial, you should not be sending
-out a patch that was generated between your working tree and your
-commit head.  Instead, always make a commit with complete commit
-message and generate a series of patches from your repository.
+Unless your patch is really trivial, you should not be sending out a patch that
+was generated between your working tree and your commit head.
+Instead, always make a commit with a complete
+[commit message][commit-message-style] and generate a series of patches from
+your repository.
 It is a good discipline.
 
 Describe the technical detail of the change(s).
@@ -38,34 +39,39 @@ If your description starts to get too long, that's a sign that you
 probably need to split up your commit to finer grained pieces.
 
 
-## Check for coding errors and style nits with pyflakes and flake8
+## Linting and formatting code
 
-### Coding errors
+Lint any changes by running:
+```sh
+$ tox -e lint -- file.py
+```
 
-Run `pyflakes` on changed modules:
+And format with:
+```sh
+$ tox -e format -- file.py
+```
 
-    pyflakes file.py
+Or format everything:
+```sh
+$ tox -e format
+```
 
-Ideally there should be no new errors or warnings introduced.
+Repo uses [black](https://black.readthedocs.io/) with line length of 80 as its
+formatter and flake8 as its linter. Repo also follows
+[Google's Python Style Guide].
 
-### Style violations
+There should be no new errors or warnings introduced.
 
-Run `flake8` on changes modules:
+Warnings that cannot be avoided without going against the Google Style Guide
+may be suppressed inline individally using a `# noqa` comment as described
+in the [flake8 documentation].
 
-    flake8 file.py
+If there are many occurrences of the same warning, these may be suppressed for
+the entire project in the included `.flake8` file.
 
-Note that repo generally follows [Google's python style guide] rather than
-[PEP 8], so it's possible that the output of `flake8` will be quite noisy.
-It's not mandatory to avoid all warnings, but at least the maximum line
-length should be followed.
-
-If there are many occurrences of the same warning that cannot be
-avoided without going against the Google style guide, these may be
-suppressed in the included `.flake8` file.
-
-[Google's python style guide]: https://google.github.io/styleguide/pyguide.html
+[Google's Python Style Guide]: https://google.github.io/styleguide/pyguide.html
 [PEP 8]: https://www.python.org/dev/peps/pep-0008/
-
+[flake8 documentation]: https://flake8.pycqa.org/en/3.1.1/user/ignoring-errors.html#in-line-ignoring-errors
 
 ## Running tests
 
@@ -154,7 +160,7 @@ Push your patches over HTTPS to the review server, possibly through
 a remembered remote to make this easier in the future:
 
     git config remote.review.url https://gerrit-review.googlesource.com/git-repo
-    git config remote.review.push HEAD:refs/for/master
+    git config remote.review.push HEAD:refs/for/main
 
     git push review
 
@@ -169,9 +175,16 @@ commit. If you make the requested changes you will need to amend your commit
 and push it to the review server again.
 
 
-## Verify your changes on gerrit
+## Verify your changes on Gerrit {#verify}
 
 After you receive a Code-Review+2 from the maintainer, select the Verified
-button on the gerrit page for the change. This verifies that you have tested
+button on the Gerrit page for the change. This verifies that you have tested
 your changes and notifies the maintainer that they are ready to be submitted.
-The maintainer will then submit your changes to the repository.
+
+## Merge your changes via the commit queue {#cq}
+
+Once a change is ready to be merged, select the Commit-Queue+2 setting on the
+Gerrit page for it. This tells the CI system to test the change, and if it
+passes all the checks, automatically merges it.
+
+[commit-message-style]: https://chris.beams.io/posts/git-commit/

color.py

@@ -1,5 +1,3 @@
-# -*- coding:utf-8 -*-
-#
 # Copyright (C) 2008 The Android Open Source Project
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -19,195 +17,202 @@ import sys
 
 import pager
 
-COLORS = {None: -1,
-          'normal': -1,
-          'black': 0,
-          'red': 1,
-          'green': 2,
-          'yellow': 3,
-          'blue': 4,
-          'magenta': 5,
-          'cyan': 6,
-          'white': 7}
 
-ATTRS = {None: -1,
-         'bold': 1,
-         'dim': 2,
-         'ul': 4,
-         'blink': 5,
-         'reverse': 7}
+COLORS = {
+    None: -1,
+    "normal": -1,
+    "black": 0,
+    "red": 1,
+    "green": 2,
+    "yellow": 3,
+    "blue": 4,
+    "magenta": 5,
+    "cyan": 6,
+    "white": 7,
+}
+
+ATTRS = {None: -1, "bold": 1, "dim": 2, "ul": 4, "blink": 5, "reverse": 7}
 
 RESET = "\033[m"
 
 
 def is_color(s):
-  return s in COLORS
+    return s in COLORS
 
 
 def is_attr(s):
-  return s in ATTRS
+    return s in ATTRS
 
 
 def _Color(fg=None, bg=None, attr=None):
-  fg = COLORS[fg]
-  bg = COLORS[bg]
-  attr = ATTRS[attr]
+    fg = COLORS[fg]
+    bg = COLORS[bg]
+    attr = ATTRS[attr]
 
-  if attr >= 0 or fg >= 0 or bg >= 0:
-    need_sep = False
-    code = "\033["
+    if attr >= 0 or fg >= 0 or bg >= 0:
+        need_sep = False
+        code = "\033["
 
-    if attr >= 0:
-      code += chr(ord('0') + attr)
-      need_sep = True
+        if attr >= 0:
+            code += chr(ord("0") + attr)
+            need_sep = True
 
-    if fg >= 0:
-      if need_sep:
-        code += ';'
-      need_sep = True
+        if fg >= 0:
+            if need_sep:
+                code += ";"
+            need_sep = True
 
-      if fg < 8:
-        code += '3%c' % (ord('0') + fg)
-      else:
-        code += '38;5;%d' % fg
+            if fg < 8:
+                code += "3%c" % (ord("0") + fg)
+            else:
+                code += "38;5;%d" % fg
 
-    if bg >= 0:
-      if need_sep:
-        code += ';'
+        if bg >= 0:
+            if need_sep:
+                code += ";"
+
+            if bg < 8:
+                code += "4%c" % (ord("0") + bg)
+            else:
+                code += "48;5;%d" % bg
+        code += "m"
+    else:
+        code = ""
+    return code
 
-      if bg < 8:
-        code += '4%c' % (ord('0') + bg)
-      else:
-        code += '48;5;%d' % bg
-    code += 'm'
-  else:
-    code = ''
-  return code
 
 DEFAULT = None
 
 
 def SetDefaultColoring(state):
-  """Set coloring behavior to |state|.
+    """Set coloring behavior to |state|.
 
-  This is useful for overriding config options via the command line.
-  """
-  if state is None:
-    # Leave it alone -- return quick!
-    return
+    This is useful for overriding config options via the command line.
+    """
+    if state is None:
+        # Leave it alone -- return quick!
+        return
 
-  global DEFAULT
-  state = state.lower()
-  if state in ('auto',):
-    DEFAULT = state
-  elif state in ('always', 'yes', 'true', True):
-    DEFAULT = 'always'
-  elif state in ('never', 'no', 'false', False):
-    DEFAULT = 'never'
+    global DEFAULT
+    state = state.lower()
+    if state in ("auto",):
+        DEFAULT = state
+    elif state in ("always", "yes", "true", True):
+        DEFAULT = "always"
+    elif state in ("never", "no", "false", False):
+        DEFAULT = "never"
 
 
-class Coloring(object):
-  def __init__(self, config, section_type):
-    self._section = 'color.%s' % section_type
-    self._config = config
-    self._out = sys.stdout
+class Coloring:
+    def __init__(self, config, section_type):
+        self._section = "color.%s" % section_type
+        self._config = config
+        self._out = sys.stdout
 
-    on = DEFAULT
-    if on is None:
-      on = self._config.GetString(self._section)
-      if on is None:
-        on = self._config.GetString('color.ui')
+        on = DEFAULT
+        if on is None:
+            on = self._config.GetString(self._section)
+            if on is None:
+                on = self._config.GetString("color.ui")
 
-    if on == 'auto':
-      if pager.active or os.isatty(1):
-        self._on = True
-      else:
-        self._on = False
-    elif on in ('true', 'always'):
-      self._on = True
-    else:
-      self._on = False
-
-  def redirect(self, out):
-    self._out = out
-
-  @property
-  def is_on(self):
-    return self._on
-
-  def write(self, fmt, *args):
-    self._out.write(fmt % args)
-
-  def flush(self):
-    self._out.flush()
-
-  def nl(self):
-    self._out.write('\n')
-
-  def printer(self, opt=None, fg=None, bg=None, attr=None):
-    s = self
-    c = self.colorer(opt, fg, bg, attr)
-
-    def f(fmt, *args):
-      s._out.write(c(fmt, *args))
-    return f
-
-  def nofmt_printer(self, opt=None, fg=None, bg=None, attr=None):
-    s = self
-    c = self.nofmt_colorer(opt, fg, bg, attr)
-
-    def f(fmt):
-      s._out.write(c(fmt))
-    return f
-
-  def colorer(self, opt=None, fg=None, bg=None, attr=None):
-    if self._on:
-      c = self._parse(opt, fg, bg, attr)
-
-      def f(fmt, *args):
-        output = fmt % args
-        return ''.join([c, output, RESET])
-      return f
-    else:
-
-      def f(fmt, *args):
-        return fmt % args
-      return f
-
-  def nofmt_colorer(self, opt=None, fg=None, bg=None, attr=None):
-    if self._on:
-      c = self._parse(opt, fg, bg, attr)
-
-      def f(fmt):
-        return ''.join([c, fmt, RESET])
-      return f
-    else:
-      def f(fmt):
-        return fmt
-      return f
-
-  def _parse(self, opt, fg, bg, attr):
-    if not opt:
-      return _Color(fg, bg, attr)
-
-    v = self._config.GetString('%s.%s' % (self._section, opt))
-    if v is None:
-      return _Color(fg, bg, attr)
-
-    v = v.strip().lower()
-    if v == "reset":
-      return RESET
-    elif v == '':
-      return _Color(fg, bg, attr)
-
-    have_fg = False
-    for a in v.split(' '):
-      if is_color(a):
-        if have_fg:
-          bg = a
+        if on == "auto":
+            if pager.active or os.isatty(1):
+                self._on = True
+            else:
+                self._on = False
+        elif on in ("true", "always"):
+            self._on = True
         else:
-          fg = a
-      elif is_attr(a):
-        attr = a
+            self._on = False
 
-    return _Color(fg, bg, attr)
+    def redirect(self, out):
+        self._out = out
+
+    @property
+    def is_on(self):
+        return self._on
+
+    def write(self, fmt, *args):
+        self._out.write(fmt % args)
+
+    def flush(self):
+        self._out.flush()
+
+    def nl(self):
+        self._out.write("\n")
+
+    def printer(self, opt=None, fg=None, bg=None, attr=None):
+        s = self
+        c = self.colorer(opt, fg, bg, attr)
+
+        def f(fmt, *args):
+            s._out.write(c(fmt, *args))
+
+        return f
+
+    def nofmt_printer(self, opt=None, fg=None, bg=None, attr=None):
+        s = self
+        c = self.nofmt_colorer(opt, fg, bg, attr)
+
+        def f(fmt):
+            s._out.write(c(fmt))
+
+        return f
+
+    def colorer(self, opt=None, fg=None, bg=None, attr=None):
+        if self._on:
+            c = self._parse(opt, fg, bg, attr)
+
+            def f(fmt, *args):
+                output = fmt % args
+                return "".join([c, output, RESET])
+
+            return f
+        else:
+
+            def f(fmt, *args):
+                return fmt % args
+
+            return f
+
+    def nofmt_colorer(self, opt=None, fg=None, bg=None, attr=None):
+        if self._on:
+            c = self._parse(opt, fg, bg, attr)
+
+            def f(fmt):
+                return "".join([c, fmt, RESET])
+
+            return f
+        else:
+
+            def f(fmt):
+                return fmt
+
+            return f
+
+    def _parse(self, opt, fg, bg, attr):
+        if not opt:
+            return _Color(fg, bg, attr)
+
+        v = self._config.GetString(f"{self._section}.{opt}")
+        if v is None:
+            return _Color(fg, bg, attr)
+
+        v = v.strip().lower()
+        if v == "reset":
+            return RESET
+        elif v == "":
+            return _Color(fg, bg, attr)
+
+        have_fg = False
+        for a in v.split(" "):
+            if is_color(a):
+                if have_fg:
+                    bg = a
+                else:
+                    have_fg = True
+                    fg = a
+            elif is_attr(a):
+                attr = a
+
+        return _Color(fg, bg, attr)

command.py

@@ -1,5 +1,3 @@
-# -*- coding:utf-8 -*-
-#
 # Copyright (C) 2008 The Android Open Source Project
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -14,253 +12,538 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-import os
+import contextlib
+import multiprocessing
 import optparse
-import platform
+import os
 import re
-import sys
 
-from event_log import EventLog
-from error import NoSuchProjectError
 from error import InvalidProjectGroupsError
+from error import NoSuchProjectError
+from error import RepoExitError
+from event_log import EventLog
+import progress
 
 
-class Command(object):
-  """Base class for any command line action in repo.
-  """
+# Are we generating man-pages?
+GENERATE_MANPAGES = os.environ.get("_REPO_GENERATE_MANPAGES_") == " indeed! "
 
-  common = False
-  event_log = EventLog()
-  manifest = None
-  _optparse = None
 
-  def WantPager(self, _opt):
-    return False
+# Number of projects to submit to a single worker process at a time.
+# This number represents a tradeoff between the overhead of IPC and finer
+# grained opportunity for parallelism. This particular value was chosen by
+# iterating through powers of two until the overall performance no longer
+# improved. The performance of this batch size is not a function of the
+# number of cores on the system.
+WORKER_BATCH_SIZE = 32
 
-  def ReadEnvironmentOptions(self, opts):
-    """ Set options from environment variables. """
 
-    env_options = self._RegisteredEnvironmentOptions()
+# How many jobs to run in parallel by default?  This assumes the jobs are
+# largely I/O bound and do not hit the network.
+DEFAULT_LOCAL_JOBS = min(os.cpu_count(), 8)
 
-    for env_key, opt_key in env_options.items():
-      # Get the user-set option value if any
-      opt_value = getattr(opts, opt_key)
 
-      # If the value is set, it means the user has passed it as a command
-      # line option, and we should use that.  Otherwise we can try to set it
-      # with the value from the corresponding environment variable.
-      if opt_value is not None:
-        continue
+class UsageError(RepoExitError):
+    """Exception thrown with invalid command usage."""
 
-      env_value = os.environ.get(env_key)
-      if env_value is not None:
-        setattr(opts, opt_key, env_value)
 
-    return opts
+class Command:
+    """Base class for any command line action in repo."""
 
-  @property
-  def OptionParser(self):
-    if self._optparse is None:
-      try:
-        me = 'repo %s' % self.NAME
-        usage = self.helpUsage.strip().replace('%prog', me)
-      except AttributeError:
-        usage = 'repo %s' % self.NAME
-      self._optparse = optparse.OptionParser(usage=usage)
-      self._Options(self._optparse)
-    return self._optparse
+    # Singleton for all commands to track overall repo command execution and
+    # provide event summary to callers. Only used by sync subcommand currently.
+    #
+    # NB: This is being replaced by git trace2 events. See git_trace2_event_log.
+    event_log = EventLog()
 
-  def _Options(self, p):
-    """Initialize the option parser.
-    """
+    # Whether this command is a "common" one, i.e. whether the user would
+    # commonly use it or it's a more uncommon command. This is used by the help
+    # command to show short-vs-full summaries.
+    COMMON = False
 
-  def _RegisteredEnvironmentOptions(self):
-    """Get options that can be set from environment variables.
+    # Whether this command supports running in parallel. If greater than 0,
+    # it is the number of parallel jobs to default to.
+    PARALLEL_JOBS = None
 
-    Return a dictionary mapping environment variable name
-    to option key name that it can override.
+    # Whether this command supports Multi-manifest. If False, then main.py will
+    # iterate over the manifests and invoke the command once per (sub)manifest.
+    # This is only checked after calling ValidateOptions, so that partially
+    # migrated subcommands can set it to False.
+    MULTI_MANIFEST_SUPPORT = True
 
-    Example: {'REPO_MY_OPTION': 'my_option'}
+    # Shared data across parallel execution workers.
+    _parallel_context = None
 
-    Will allow the option with key value 'my_option' to be set
-    from the value in the environment variable named 'REPO_MY_OPTION'.
+    @classmethod
+    def get_parallel_context(cls):
+        assert cls._parallel_context is not None
+        return cls._parallel_context
 
-    Note: This does not work properly for options that are explicitly
-    set to None by the user, or options that are defined with a
-    default value other than None.
+    def __init__(
+        self,
+        repodir=None,
+        client=None,
+        manifest=None,
+        git_event_log=None,
+        outer_client=None,
+        outer_manifest=None,
+    ):
+        self.repodir = repodir
+        self.client = client
+        self.outer_client = outer_client or client
+        self.manifest = manifest
+        self.git_event_log = git_event_log
+        self.outer_manifest = outer_manifest
 
-    """
-    return {}
+        # Cache for the OptionParser property.
+        self._optparse = None
 
-  def Usage(self):
-    """Display usage and terminate.
-    """
-    self.OptionParser.print_usage()
-    sys.exit(1)
+    def WantPager(self, _opt):
+        return False
 
-  def ValidateOptions(self, opt, args):
-    """Validate the user options & arguments before executing.
+    def ReadEnvironmentOptions(self, opts):
+        """Set options from environment variables."""
 
-    This is meant to help break the code up into logical steps.  Some tips:
-    * Use self.OptionParser.error to display CLI related errors.
-    * Adjust opt member defaults as makes sense.
-    * Adjust the args list, but do so inplace so the caller sees updates.
-    * Try to avoid updating self state.  Leave that to Execute.
-    """
+        env_options = self._RegisteredEnvironmentOptions()
 
-  def Execute(self, opt, args):
-    """Perform the action, after option parsing is complete.
-    """
-    raise NotImplementedError
+        for env_key, opt_key in env_options.items():
+            # Get the user-set option value if any
+            opt_value = getattr(opts, opt_key)
 
-  def _ResetPathToProjectMap(self, projects):
-    self._by_path = dict((p.worktree, p) for p in projects)
+            # If the value is set, it means the user has passed it as a command
+            # line option, and we should use that. Otherwise we can try to set
+            # it with the value from the corresponding environment variable.
+            if opt_value is not None:
+                continue
 
-  def _UpdatePathToProjectMap(self, project):
-    self._by_path[project.worktree] = project
+            env_value = os.environ.get(env_key)
+            if env_value is not None:
+                setattr(opts, opt_key, env_value)
 
-  def _GetProjectByPath(self, manifest, path):
-    project = None
-    if os.path.exists(path):
-      oldpath = None
-      while path and \
-            path != oldpath and \
-            path != manifest.topdir:
+        return opts
+
+    @property
+    def OptionParser(self):
+        if self._optparse is None:
+            try:
+                me = "repo %s" % self.NAME
+                usage = self.helpUsage.strip().replace("%prog", me)
+            except AttributeError:
+                usage = "repo %s" % self.NAME
+            epilog = (
+                "Run `repo help %s` to view the detailed manual." % self.NAME
+            )
+            self._optparse = optparse.OptionParser(usage=usage, epilog=epilog)
+            self._CommonOptions(self._optparse)
+            self._Options(self._optparse)
+        return self._optparse
+
+    def _CommonOptions(self, p, opt_v=True):
+        """Initialize the option parser with common options.
+
+        These will show up for *all* subcommands, so use sparingly.
+        NB: Keep in sync with repo:InitParser().
+        """
+        g = p.add_option_group("Logging options")
+        opts = ["-v"] if opt_v else []
+        g.add_option(
+            *opts,
+            "--verbose",
+            dest="output_mode",
+            action="store_true",
+            help="show all output",
+        )
+        g.add_option(
+            "-q",
+            "--quiet",
+            dest="output_mode",
+            action="store_false",
+            help="only show errors",
+        )
+
+        if self.PARALLEL_JOBS is not None:
+            default = "based on number of CPU cores"
+            if not GENERATE_MANPAGES:
+                # Only include active cpu count if we aren't generating man
+                # pages.
+                default = f"%default; {default}"
+            p.add_option(
+                "-j",
+                "--jobs",
+                type=int,
+                default=self.PARALLEL_JOBS,
+                help=f"number of jobs to run in parallel (default: {default})",
+            )
+
+        m = p.add_option_group("Multi-manifest options")
+        m.add_option(
+            "--outer-manifest",
+            action="store_true",
+            default=None,
+            help="operate starting at the outermost manifest",
+        )
+        m.add_option(
+            "--no-outer-manifest",
+            dest="outer_manifest",
+            action="store_false",
+            help="do not operate on outer manifests",
+        )
+        m.add_option(
+            "--this-manifest-only",
+            action="store_true",
+            default=None,
+            help="only operate on this (sub)manifest",
+        )
+        m.add_option(
+            "--no-this-manifest-only",
+            "--all-manifests",
+            dest="this_manifest_only",
+            action="store_false",
+            help="operate on this manifest and its submanifests",
+        )
+
+    def _Options(self, p):
+        """Initialize the option parser with subcommand-specific options."""
+
+    def _RegisteredEnvironmentOptions(self):
+        """Get options that can be set from environment variables.
+
+        Return a dictionary mapping environment variable name
+        to option key name that it can override.
+
+        Example: {'REPO_MY_OPTION': 'my_option'}
+
+        Will allow the option with key value 'my_option' to be set
+        from the value in the environment variable named 'REPO_MY_OPTION'.
+
+        Note: This does not work properly for options that are explicitly
+        set to None by the user, or options that are defined with a
+        default value other than None.
+
+        """
+        return {}
+
+    def Usage(self):
+        """Display usage and terminate."""
+        self.OptionParser.print_usage()
+        raise UsageError()
+
+    def CommonValidateOptions(self, opt, args):
+        """Validate common options."""
+        opt.quiet = opt.output_mode is False
+        opt.verbose = opt.output_mode is True
+        if opt.outer_manifest is None:
+            # By default, treat multi-manifest instances as a single manifest
+            # from the user's perspective.
+            opt.outer_manifest = True
+
+    def ValidateOptions(self, opt, args):
+        """Validate the user options & arguments before executing.
+
+        This is meant to help break the code up into logical steps. Some tips:
+        * Use self.OptionParser.error to display CLI related errors.
+        * Adjust opt member defaults as makes sense.
+        * Adjust the args list, but do so inplace so the caller sees updates.
+        * Try to avoid updating self state. Leave that to Execute.
+        """
+
+    def Execute(self, opt, args):
+        """Perform the action, after option parsing is complete."""
+        raise NotImplementedError
+
+    @classmethod
+    @contextlib.contextmanager
+    def ParallelContext(cls):
+        """Obtains the context, which is shared to ExecuteInParallel workers.
+
+        Callers can store data in the context dict before invocation of
+        ExecuteInParallel. The dict will then be shared to child workers of
+        ExecuteInParallel.
+        """
+        assert cls._parallel_context is None
+        cls._parallel_context = {}
         try:
-          project = self._by_path[path]
-          break
-        except KeyError:
-          oldpath = path
-          path = os.path.dirname(path)
-      if not project and path == manifest.topdir:
+            yield
+        finally:
+            cls._parallel_context = None
+
+    @classmethod
+    def _InitParallelWorker(cls, context, initializer):
+        cls._parallel_context = context
+        if initializer:
+            initializer()
+
+    @classmethod
+    def ExecuteInParallel(
+        cls,
+        jobs,
+        func,
+        inputs,
+        callback,
+        output=None,
+        ordered=False,
+        chunksize=WORKER_BATCH_SIZE,
+        initializer=None,
+    ):
+        """Helper for managing parallel execution boiler plate.
+
+        For subcommands that can easily split their work up.
+
+        Args:
+            jobs: How many parallel processes to use.
+            func: The function to apply to each of the |inputs|. Usually a
+                functools.partial for wrapping additional arguments. It will be
+                run in a separate process, so it must be pickalable, so nested
+                functions won't work. Methods on the subcommand Command class
+                should work.
+            inputs: The list of items to process. Must be a list.
+            callback: The function to pass the results to for processing. It
+                will be executed in the main thread and process the results of
+                |func| as they become available. Thus it may be a local nested
+                function. Its return value is passed back directly. It takes
+                three arguments:
+                - The processing pool (or None with one job).
+                - The |output| argument.
+                - An iterator for the results.
+            output: An output manager. May be progress.Progess or
+                color.Coloring.
+            ordered: Whether the jobs should be processed in order.
+            chunksize: The number of jobs processed in batch by parallel
+                workers.
+            initializer: Worker initializer.
+
+        Returns:
+            The |callback| function's results are returned.
+        """
         try:
-          project = self._by_path[path]
-        except KeyError:
-          pass
-    else:
-      try:
-        project = self._by_path[path]
-      except KeyError:
-        pass
-    return project
+            # NB: Multiprocessing is heavy, so don't spin it up for one job.
+            if len(inputs) == 1 or jobs == 1:
+                return callback(None, output, (func(x) for x in inputs))
+            else:
+                with multiprocessing.Pool(
+                    jobs,
+                    initializer=cls._InitParallelWorker,
+                    initargs=(cls._parallel_context, initializer),
+                ) as pool:
+                    submit = pool.imap if ordered else pool.imap_unordered
+                    return callback(
+                        pool,
+                        output,
+                        submit(func, inputs, chunksize=chunksize),
+                    )
+        finally:
+            if isinstance(output, progress.Progress):
+                output.end()
 
-  def GetProjects(self, args, manifest=None, groups='', missing_ok=False,
-                  submodules_ok=False):
-    """A list of projects that match the arguments.
-    """
-    if not manifest:
-      manifest = self.manifest
-    all_projects_list = manifest.projects
-    result = []
+    def _ResetPathToProjectMap(self, projects):
+        self._by_path = {p.worktree: p for p in projects}
 
-    mp = manifest.manifestProject
+    def _UpdatePathToProjectMap(self, project):
+        self._by_path[project.worktree] = project
 
-    if not groups:
-      groups = mp.config.GetString('manifest.groups')
-    if not groups:
-      groups = 'default,platform-' + platform.system().lower()
-    groups = [x for x in re.split(r'[,\s]+', groups) if x]
+    def _GetProjectByPath(self, manifest, path):
+        project = None
+        if os.path.exists(path):
+            oldpath = None
+            while path and path != oldpath and path != manifest.topdir:
+                try:
+                    project = self._by_path[path]
+                    break
+                except KeyError:
+                    oldpath = path
+                    path = os.path.dirname(path)
+            if not project and path == manifest.topdir:
+                try:
+                    project = self._by_path[path]
+                except KeyError:
+                    pass
+        else:
+            try:
+                project = self._by_path[path]
+            except KeyError:
+                pass
+        return project
 
-    if not args:
-      derived_projects = {}
-      for project in all_projects_list:
-        if submodules_ok or project.sync_s:
-          derived_projects.update((p.name, p)
-                                  for p in project.GetDerivedSubprojects())
-      all_projects_list.extend(derived_projects.values())
-      for project in all_projects_list:
-        if (missing_ok or project.Exists) and project.MatchesGroups(groups):
-          result.append(project)
-    else:
-      self._ResetPathToProjectMap(all_projects_list)
+    def GetProjects(
+        self,
+        args,
+        manifest=None,
+        groups="",
+        missing_ok=False,
+        submodules_ok=False,
+        all_manifests=False,
+    ):
+        """A list of projects that match the arguments.
 
-      for arg in args:
-        # We have to filter by manifest groups in case the requested project is
-        # checked out multiple times or differently based on them.
-        projects = [project for project in manifest.GetProjectsWithName(arg)
-                    if project.MatchesGroups(groups)]
+        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.
 
-        if not projects:
-          path = os.path.abspath(arg).replace('\\', '/')
-          project = self._GetProjectByPath(manifest, path)
+        Returns:
+            A list of matching Project instances.
+        """
+        if all_manifests:
+            if not manifest:
+                manifest = self.manifest.outer_client
+            all_projects_list = manifest.all_projects
+        else:
+            if not manifest:
+                manifest = self.manifest
+            all_projects_list = manifest.projects
+        result = []
 
-          # If it's not a derived project, update path->project mapping and
-          # search again, as arg might actually point to a derived subproject.
-          if (project and not project.Derived and (submodules_ok or
-                                                   project.sync_s)):
-            search_again = False
-            for subproject in project.GetDerivedSubprojects():
-              self._UpdatePathToProjectMap(subproject)
-              search_again = True
-            if search_again:
-              project = self._GetProjectByPath(manifest, path) or project
+        if not groups:
+            groups = manifest.GetGroupsStr()
+        groups = [x for x in re.split(r"[,\s]+", groups) if x]
 
-          if project:
-            projects = [project]
+        if not args:
+            derived_projects = {}
+            for project in all_projects_list:
+                if submodules_ok or project.sync_s:
+                    derived_projects.update(
+                        (p.name, p) for p in project.GetDerivedSubprojects()
+                    )
+            all_projects_list.extend(derived_projects.values())
+            for project in all_projects_list:
+                if (missing_ok or project.Exists) and project.MatchesGroups(
+                    groups
+                ):
+                    result.append(project)
+        else:
+            self._ResetPathToProjectMap(all_projects_list)
 
-        if not projects:
-          raise NoSuchProjectError(arg)
+            for arg in args:
+                # We have to filter by manifest groups in case the requested
+                # project is checked out multiple times or differently based on
+                # them.
+                projects = [
+                    project
+                    for project in manifest.GetProjectsWithName(
+                        arg, all_manifests=all_manifests
+                    )
+                    if project.MatchesGroups(groups)
+                ]
 
-        for project in projects:
-          if not missing_ok and not project.Exists:
-            raise NoSuchProjectError('%s (%s)' % (arg, project.relpath))
-          if not project.MatchesGroups(groups):
-            raise InvalidProjectGroupsError(arg)
+                if not projects:
+                    path = os.path.abspath(arg).replace("\\", "/")
+                    tree = manifest
+                    if all_manifests:
+                        # Look for the deepest matching submanifest.
+                        for tree in reversed(list(manifest.all_manifests)):
+                            if path.startswith(tree.topdir):
+                                break
+                    project = self._GetProjectByPath(tree, path)
 
-        result.extend(projects)
+                    # If it's not a derived project, update path->project
+                    # mapping and search again, as arg might actually point to
+                    # a derived subproject.
+                    if (
+                        project
+                        and not project.Derived
+                        and (submodules_ok or project.sync_s)
+                    ):
+                        search_again = False
+                        for subproject in project.GetDerivedSubprojects():
+                            self._UpdatePathToProjectMap(subproject)
+                            search_again = True
+                        if search_again:
+                            project = (
+                                self._GetProjectByPath(manifest, path)
+                                or project
+                            )
 
-    def _getpath(x):
-      return x.relpath
-    result.sort(key=_getpath)
-    return result
+                    if project:
+                        projects = [project]
 
-  def FindProjects(self, args, inverse=False):
-    result = []
-    patterns = [re.compile(r'%s' % a, re.IGNORECASE) for a in args]
-    for project in self.GetProjects(''):
-      for pattern in patterns:
-        match = pattern.search(project.name) or pattern.search(project.relpath)
-        if not inverse and match:
-          result.append(project)
-          break
-        if inverse and match:
-          break
-      else:
-        if inverse:
-          result.append(project)
-    result.sort(key=lambda project: project.relpath)
-    return result
+                if not projects:
+                    raise NoSuchProjectError(arg)
+
+                for project in projects:
+                    if not missing_ok and not project.Exists:
+                        raise NoSuchProjectError(
+                            "%s (%s)"
+                            % (arg, project.RelPath(local=not all_manifests))
+                        )
+                    if not project.MatchesGroups(groups):
+                        raise InvalidProjectGroupsError(arg)
+
+                result.extend(projects)
+
+        def _getpath(x):
+            return x.relpath
+
+        result.sort(key=_getpath)
+        return result
+
+    def FindProjects(self, args, inverse=False, all_manifests=False):
+        """Find projects from command line arguments.
+
+        Args:
+            args: a list of (case-insensitive) strings, projects to search for.
+            inverse: a boolean, if True, then projects not matching any |args|
+                are returned.
+            all_manifests: a boolean, if True then all manifests and
+                submanifests are used. If False, then only the local
+                (sub)manifest is used.
+        """
+        result = []
+        patterns = [re.compile(r"%s" % a, re.IGNORECASE) for a in args]
+        for project in self.GetProjects("", all_manifests=all_manifests):
+            paths = [project.name, project.RelPath(local=not all_manifests)]
+            for pattern in patterns:
+                match = any(pattern.search(x) for x in paths)
+                if not inverse and match:
+                    result.append(project)
+                    break
+                if inverse and match:
+                    break
+            else:
+                if inverse:
+                    result.append(project)
+        result.sort(
+            key=lambda project: (project.manifest.path_prefix, project.relpath)
+        )
+        return result
+
+    def ManifestList(self, opt):
+        """Yields all of the manifests to traverse.
+
+        Args:
+            opt: The command options.
+        """
+        top = self.outer_manifest
+        if not opt.outer_manifest or opt.this_manifest_only:
+            top = self.manifest
+        yield top
+        if not opt.this_manifest_only:
+            yield from top.all_children
 
 
 class InteractiveCommand(Command):
-  """Command which requires user interaction on the tty and
-     must not run within a pager, even if the user asks to.
-  """
-  def WantPager(self, _opt):
-    return False
+    """Command which requires user interaction on the tty and must not run
+    within a pager, even if the user asks to.
+    """
+
+    def WantPager(self, _opt):
+        return False
 
 
 class PagedCommand(Command):
-  """Command which defaults to output in a pager, as its
-     display tends to be larger than one screen full.
-  """
-  def WantPager(self, _opt):
-    return True
+    """Command which defaults to output in a pager, as its display tends to be
+    larger than one screen full.
+    """
+
+    def WantPager(self, _opt):
+        return True
 
 
-class MirrorSafeCommand(object):
-  """Command permits itself to run within a mirror,
-     and does not require a working directory.
-  """
-
-
-class GitcAvailableCommand(object):
-  """Command that requires GITC to be available, but does
-     not require the local client to be a GITC client.
-  """
-
-
-class GitcClientCommand(object):
-  """Command that requires the local client to be a GITC
-     client.
-  """
+class MirrorSafeCommand:
+    """Command permits itself to run within a mirror, and does not require a
+    working directory.
+    """

completion.bash

@@ -0,0 +1,156 @@
+# Copyright 2021 The Android Open Source Project
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# Programmable bash completion.  https://github.com/scop/bash-completion
+
+# TODO: Handle interspersed options.  We handle `repo h<tab>`, but not
+# `repo --time h<tab>`.
+
+# Complete the list of repo subcommands.
+__complete_repo_list_commands() {
+  local repo=${COMP_WORDS[0]}
+  (
+  # Handle completions if running outside of a checkout.
+  if ! "${repo}" help --all 2>/dev/null; then
+    repo help 2>/dev/null
+  fi
+  ) | sed -n '/^  /{s/  \([^ ]\+\) .\+/\1/;p}'
+}
+
+# Complete list of all branches available in all projects in the repo client
+# checkout.
+__complete_repo_list_branches() {
+  local repo=${COMP_WORDS[0]}
+  "${repo}" branches 2>/dev/null | \
+    sed -n '/|/{s/[ *][Pp ] *\([^ ]\+\) .*/\1/;p}'
+}
+
+# Complete list of all projects available in the repo client checkout.
+__complete_repo_list_projects() {
+  local repo=${COMP_WORDS[0]}
+  "${repo}" list -n 2>/dev/null
+  "${repo}" list -p --relative-to=. 2>/dev/null
+}
+
+# Complete the repo <command> argument.
+__complete_repo_command() {
+  if [[ ${COMP_CWORD} -ne 1 ]]; then
+    return 1
+  fi
+
+  local command=${COMP_WORDS[1]}
+  COMPREPLY=($(compgen -W "$(__complete_repo_list_commands)" -- "${command}"))
+  return 0
+}
+
+# Complete repo subcommands that take <branch> <projects>.
+__complete_repo_command_branch_projects() {
+  local current=$1
+  if [[ ${COMP_CWORD} -eq 2 ]]; then
+    COMPREPLY=($(compgen -W "$(__complete_repo_list_branches)" -- "${current}"))
+  else
+    COMPREPLY=($(compgen -W "$(__complete_repo_list_projects)" -- "${current}"))
+  fi
+}
+
+# Complete repo subcommands that take only <projects>.
+__complete_repo_command_projects() {
+  local current=$1
+  COMPREPLY=($(compgen -W "$(__complete_repo_list_projects)" -- "${current}"))
+}
+
+# Complete `repo help`.
+__complete_repo_command_help() {
+  local current=$1
+  # CWORD=1 is "start".
+  # CWORD=2 is the <subcommand> which we complete here.
+  if [[ ${COMP_CWORD} -eq 2 ]]; then
+    COMPREPLY=(
+      $(compgen -W "$(__complete_repo_list_commands)" -- "${current}")
+    )
+  fi
+}
+
+# Complete `repo forall`.
+__complete_repo_command_forall() {
+  local current=$1
+  # CWORD=1 is "forall".
+  # CWORD=2+ are <projects> *until* we hit the -c option.
+  local i
+  for (( i = 0; i < COMP_CWORD; ++i )); do
+    if [[ "${COMP_WORDS[i]}" == "-c" ]]; then
+      return 0
+    fi
+  done
+
+  COMPREPLY=(
+    $(compgen -W "$(__complete_repo_list_projects)" -- "${current}")
+  )
+}
+
+# Complete `repo start`.
+__complete_repo_command_start() {
+  local current=$1
+  # CWORD=1 is "start".
+  # CWORD=2 is the <branch> which we don't complete.
+  # CWORD=3+ are <projects> which we complete here.
+  if [[ ${COMP_CWORD} -gt 2 ]]; then
+    COMPREPLY=(
+      $(compgen -W "$(__complete_repo_list_projects)" -- "${current}")
+    )
+  fi
+}
+
+# Complete the repo subcommand arguments.
+__complete_repo_arg() {
+  if [[ ${COMP_CWORD} -le 1 ]]; then
+    return 1
+  fi
+
+  local command=${COMP_WORDS[1]}
+  local current=${COMP_WORDS[COMP_CWORD]}
+  case ${command} in
+  abandon|checkout)
+    __complete_repo_command_branch_projects "${current}"
+    return 0
+    ;;
+
+  branch|branches|diff|info|list|overview|prune|rebase|smartsync|stage|status|\
+  sync|upload)
+    __complete_repo_command_projects "${current}"
+    return 0
+    ;;
+
+  help|start|forall)
+    __complete_repo_command_${command} "${current}"
+    return 0
+    ;;
+
+  *)
+    return 1
+    ;;
+  esac
+}
+
+# Complete the repo arguments.
+__complete_repo() {
+  COMPREPLY=()
+  __complete_repo_command && return 0
+  __complete_repo_arg && return 0
+  return 0
+}
+
+# Fallback to the default complete methods if we aren't able to provide anything
+# useful.  This will allow e.g. local paths to be used when it makes sense.
+complete -F __complete_repo -o bashdefault -o default repo

constraints.txt

@@ -0,0 +1,2 @@
+# NB: Keep in sync with run_tests.vpython3.
+black<26

docs/internal-fs-layout.md

@@ -23,6 +23,10 @@ It is always safe to re-run `repo init` in existing repo client checkouts.
 For example, if you want to change the manifest branch, you can simply run
 `repo init --manifest-branch=<new name>` and repo will take care of the rest.
 
+*   `config`: Per-repo client checkout settings using [git-config] file format.
+*   `.repo_config.json`: JSON cache of the `config` file for repo to
+    read/process quickly.
+
 ### repo/ state
 
 *   `repo/`: A git checkout of the repo project.  This is how `repo` re-execs
@@ -30,7 +34,7 @@ For example, if you want to change the manifest branch, you can simply run
 
     It tracks the git repository at `REPO_URL` using the `REPO_REV` branch.
     Those are specified at `repo init` time using the `--repo-url=<REPO_URL>`
-    and `--repo-branch=<REPO_REV>` options.
+    and `--repo-rev=<REPO_REV>` options.
 
     Any changes made to this directory will usually be automatically discarded
     by repo itself when it checks for updates.  If you want to update to the
@@ -38,14 +42,22 @@ For example, if you want to change the manifest branch, you can simply run
     change the git URL/branch that this tracks, re-run `repo init` with the new
     settings.
 
-*   `.repo_fetchtimes.json`: Used by `repo sync` to record stats when syncing
-    the various projects.
+*   `.repo_fetchtimes.json`: Used by `repo sync` to record fetch times when
+    syncing the various projects.
+
+*   `.repo_localsyncstate.json`: Used by `repo sync` to detect and warn on
+    on partial tree syncs.  Partial syncs are allowed by `repo` itself, but are
+    unsupported by many projects where `repo` is used.
 
 ### Manifests
 
 For more documentation on the manifest format, including the local_manifests
 support, see the [manifest-format.md] file.
 
+*   `submanifests/{submanifest.path}/`: The path prefix to the manifest state of
+    a submanifest included in a multi-manifest checkout.  The outermost manifest
+    manifest state is found adjacent to `submanifests/`.
+
 *   `manifests/`: A git checkout of the manifest project.  Its `.git/` state
     points to the `manifest.git` bare checkout (see below).  It tracks the git
     branch specified at `repo init` time via `--manifest-branch`.
@@ -64,13 +76,20 @@ support, see the [manifest-format.md] file.
     If you want to switch the tracking settings, re-run `repo init` with the
     new settings.
 
+*   `manifest.xml`: The manifest that repo uses.  It is generated at `repo init`
+    and uses the `--manifest-name` to determine what manifest file to load next
+    out of `manifests/`.
+
+    Do not try to modify this to load other manifests as it will confuse repo.
+    If you want to switch manifest files, re-run `repo init` with the new
+    setting.
+
+    Older versions of repo managed this with symlinks.
+
 *   `manifest.xml -> manifests/<manifest-name>.xml`: A symlink to the manifest
     that the user wishes to sync.  It is specified at `repo init` time via
     `--manifest-name`.
 
-    Do not try to repoint this symlink to other files as it will confuse repo.
-    If you want to switch manifest files, re-run `repo init` with the new
-    setting.
 
 *   `manifests.git/.repo_config.json`: JSON cache of the `manifests.git/config`
     file for repo to read/process quickly.
@@ -82,6 +101,25 @@ support, see the [manifest-format.md] file.
 
 ### Project objects
 
+*** note
+**Warning**: Please do not use repo's approach to projects/ & project-objects/
+layouts as a model for other tools to implement similar approaches.
+It has a number of known downsides like:
+*   [Symlinks do not work well under Windows](./windows.md).
+*   Git sometimes replaces symlinks under .git/ with real files (under unknown
+    circumstances), and then the internal state gets out of sync, and data loss
+    may ensue.
+*   When sharing project-objects between multiple project checkouts, Git might
+    automatically run `gc` or `prune` which may lead to data loss or corruption
+    (since those operate on leaf projects and miss refs in other leaves).  See
+    https://gerrit-review.googlesource.com/c/git-repo/+/254392 for more details.
+
+Instead, you should use standard Git workflows like [git worktree] or
+[gitsubmodules] with [superprojects].
+***
+
+*   `copy-link-files.json`: Tracking file used by `repo sync` to determine when
+    copyfile or linkfile are added or removed and need corresponding updates.
 *   `project.list`: Tracking file used by `repo sync` to determine when projects
     are added or removed and need corresponding updates in the checkout.
 *   `projects/`: Bare checkouts of every project synced by the manifest.  The
@@ -92,54 +130,147 @@ support, see the [manifest-format.md] file.
     Some git state is further split out under `project-objects/`.
 *   `project-objects/`: Git objects that are safe to share across multiple
     git checkouts.  The filesystem layout matches the `<project name=...`
-    setting in the manifest (i.e. the path on the remote server).  This allows
-    for multiple checkouts of the same remote git repo to share their objects.
-    For example, you could have different branches of `foo/bar.git` checked
-    out to `foo/bar-master`, `foo/bar-release`, etc...  There will be multiple
-    trees under `projects/` for each one, but only one under `project-objects/`.
+    setting in the manifest (i.e. the path on the remote server) with a `.git`
+    suffix.  This allows for multiple checkouts of the same remote git repo to
+    share their objects.  For example, you could have different branches of
+    `foo/bar.git` checked out to `foo/bar-main`, `foo/bar-release`, etc...
+    There will be multiple trees under `projects/` for each one, but only one
+    under `project-objects/`.
 
-    This can run into problems if different remotes use the same path on their
-    respective servers ...
-*   `subprojects/`: Like `projects/`, but for git submodules.
+    This layout is designed to allow people to sync against different remotes
+    (e.g. a local mirror & a public review server) while avoiding duplicating
+    the content.  However, this can run into problems if different remotes use
+    the same path on their respective servers.  Best to avoid that.
+*   `modules/`: Like `projects/`, but for git submodules.
 *   `subproject-objects/`: Like `project-objects/`, but for git submodules.
+*   `worktrees/`: Bare checkouts of every project synced by the manifest.  The
+    filesystem layout matches the `<project name=...` setting in the manifest
+    (i.e. the path on the remote server) with a `.git` suffix.  This has the
+    same advantages as the `project-objects/` layout above.
 
-### Settings
+    This is used when [git worktree]'s are enabled.
+
+### Global settings
 
 The `.repo/manifests.git/config` file is used to track settings for the entire
 repo client checkout.
+
 Most settings use the `[repo]` section to avoid conflicts with git.
+
+Everything under `[repo.syncstate.*]` is used to keep track of sync details for logging
+purposes.
+
 User controlled settings are initialized when running `repo init`.
 
-| Setting           | `repo init` Option        | Use/Meaning |
-|-------------------|---------------------------|-------------|
-| manifest.groups   | `--groups` & `--platform` | The manifest groups to sync |
-| repo.archive      | `--archive`               | Use `git archive` for checkouts |
-| repo.clonefilter  | `--clone-filter`          | Filter setting when using [partial git clones] |
-| repo.depth        | `--depth`                 | Create shallow checkouts when cloning |
-| repo.dissociate   | `--dissociate`            | Dissociate from any reference/mirrors after initial clone |
-| repo.mirror       | `--mirror`                | Checkout is a repo mirror |
-| repo.partialclone | `--partial-clone`         | Create [partial git clones] |
-| repo.reference    | `--reference`             | Reference repo client checkout |
-| repo.submodules   | `--submodules`            | Sync git submodules |
-| user.email        | `--config-name`           | User's e-mail address; Copied into `.git/config` when checking out a new project |
-| user.name         | `--config-name`           | User's name; Copied into `.git/config` when checking out a new project |
+| Setting                  | `repo init` Option        | Use/Meaning |
+|-------------------       |---------------------------|-------------|
+| manifest.groups          | `--groups` & `--platform` | The manifest groups to sync |
+| manifest.standalone      | `--standalone-manifest`   | Download manifest as static file instead of creating checkout |
+| repo.archive             | `--archive`               | Use `git archive` for checkouts |
+| repo.clonebundle         | `--clone-bundle`          | Whether the initial sync used clone.bundle explicitly |
+| repo.clonefilter         | `--clone-filter`          | Filter setting when using [partial git clones] |
+| repo.depth               | `--depth`                 | Create shallow checkouts when cloning |
+| repo.dissociate          | `--dissociate`            | Dissociate from any reference/mirrors after initial clone |
+| repo.git-lfs             | `--git-lfs`               | Enable [Git LFS] support |
+| repo.mirror              | `--mirror`                | Checkout is a repo mirror |
+| repo.partialclone        | `--partial-clone`         | Create [partial git clones] |
+| repo.partialcloneexclude | `--partial-clone-exclude` | Comma-delimited list of project names (not paths) to exclude while using [partial git clones] |
+| repo.reference           | `--reference`             | Reference repo client checkout |
+| repo.submodules          | `--submodules`            | Sync git submodules |
+| repo.superproject        | `--use-superproject`      | Sync [superproject] |
+| repo.worktree            | `--worktree`              | Use [git worktree] for checkouts |
+| user.email               | `--config-name`           | User's e-mail address; Copied into `.git/config` when checking out a new project |
+| user.name                | `--config-name`           | User's name; Copied into `.git/config` when checking out a new project |
 
 [partial git clones]: https://git-scm.com/docs/gitrepository-layout#_code_partialclone_code
+[superproject]: https://en.wikibooks.org/wiki/Git/Submodules_and_Superprojects
+
+### Repo hooks settings
+
+For more details on this feature, see the [repo-hooks docs](./repo-hooks.md).
+We'll just discuss the internal configuration settings.
+These are stored in the registered `<repo-hooks>` project itself, so if the
+manifest switches to a different project, the settings will not be copied.
+
+| Setting                              | Use/Meaning |
+|--------------------------------------|-------------|
+| repo.hooks.\<hook\>.approvedmanifest | User approval for secure manifest sources (e.g. https://) |
+| repo.hooks.\<hook\>.approvedhash     | User approval for insecure manifest sources (e.g. http://) |
+
+
+For example, if our manifest had the following entries, we would store settings
+under `.repo/projects/src/repohooks.git/config` (which would be reachable via
+`git --git-dir=src/repohooks/.git config`).
+```xml
+  <project path="src/repohooks" name="chromiumos/repohooks" ... />
+  <repo-hooks in-project="chromiumos/repohooks" ... />
+```
+
+If `<hook>` is `pre-upload`, the `.git/config` setting might be:
+```ini
+[repo "hooks.pre-upload"]
+	approvedmanifest = https://chromium.googlesource.com/chromiumos/manifest
+```
+
+## Per-project settings
+
+These settings are somewhat meant to be tweaked by the user on a per-project
+basis (e.g. `git config` in a checked out source repo).
+
+Where possible, we re-use standard git settings to avoid confusion, and we
+refrain from documenting those, so see [git-config] documentation instead.
+
+See `repo help upload` for documentation on `[review]` settings.
+
+The `[remote]` settings are automatically populated/updated from the manifest.
+
+The `[branch]` settings are updated by `repo start` and `git branch`.
+
+| Setting                               | Subcommands   | Use/Meaning |
+|---------------------------------------|---------------|-------------|
+| review.\<url\>.autocopy               | upload        | Automatically add to `--cc=<value>` |
+| review.\<url\>.autoreviewer           | upload        | Automatically add to `--reviewers=<value>` |
+| review.\<url\>.autoupload             | upload        | Automatically answer "yes" or "no" to all prompts |
+| review.\<url\>.uploadhashtags         | upload        | Automatically add to `--hashtag=<value>` |
+| review.\<url\>.uploadlabels           | upload        | Automatically add to `--label=<value>` |
+| review.\<url\>.uploadnotify           | upload        | [Notify setting][upload-notify] to use |
+| review.\<url\>.uploadtopic            | upload        | Default [topic] to use |
+| review.\<url\>.uploadwarningthreshold | upload        | Warn when attempting to upload more than this many CLs |
+| review.\<url\>.username               | upload        | Override username with `ssh://` review URIs |
+| remote.\<remote\>.fetch               | sync          | Set of refs to fetch |
+| remote.\<remote\>.projectname         | \<network\>   | The name of the project as it exists in Gerrit review |
+| remote.\<remote\>.pushurl             | upload        | The base URI for pushing CLs |
+| remote.\<remote\>.review              | upload        | The URI of the Gerrit review server |
+| remote.\<remote\>.url                 | sync & upload | The URI of the git project to fetch |
+| branch.\<branch\>.merge               | sync & upload | The branch to merge & upload & track |
+| branch.\<branch\>.remote              | sync & upload | The remote to track |
 
 ## ~/ dotconfig layout
 
-Repo will create & maintain a few files in the user's home directory.
+Repo will create & maintain a few files under the `.repoconfig/` directory.
+This is placed in the user's home directory by default but can be changed by
+setting `REPO_CONFIG_DIR`.
 
 *   `.repoconfig/`: Repo's per-user directory for all random config files/state.
+*   `.repoconfig/config`: Per-user settings using [git-config] file format.
 *   `.repoconfig/keyring-version`: Cache file for checking if the gnupg subdir
     has all the same keys as the repo launcher.  Used to avoid running gpg
     constantly as that can be quite slow.
 *   `.repoconfig/gnupg/`: GnuPG's internal state directory used when repo needs
     to run `gpg`.  This provides isolation from the user's normal `~/.gnupg/`.
 
+*   `.repoconfig/.repo_config.json`: JSON cache of the `.repoconfig/config`
+    file for repo to read/process quickly.
 *   `.repo_.gitconfig.json`: JSON cache of the `.gitconfig` file for repo to
     read/process quickly.
 
 
+[git-config]: https://git-scm.com/docs/git-config
+[Git LFS]: https://git-lfs.github.com/
+[git worktree]: https://git-scm.com/docs/git-worktree
+[gitsubmodules]: https://git-scm.com/docs/gitsubmodules
 [manifest-format.md]: ./manifest-format.md
 [local manifests]: ./manifest-format.md#Local-Manifests
+[superprojects]: https://en.wikibooks.org/wiki/Git/Submodules_and_Superprojects
+[topic]: https://gerrit-review.googlesource.com/Documentation/intro-user.html#topics
+[upload-notify]: https://gerrit-review.googlesource.com/Documentation/user-upload.html#notify

docs/manifest-format.md

@@ -21,19 +21,23 @@ following DTD:
 
 ```xml
 <!DOCTYPE manifest [
+
   <!ELEMENT manifest (notice?,
                       remote*,
                       default?,
                       manifest-server?,
+                      submanifest*?,
                       remove-project*,
                       project*,
                       extend-project*,
                       repo-hooks?,
+                      superproject?,
+                      contactinfo?,
                       include*)>
 
   <!ELEMENT notice (#PCDATA)>
 
-  <!ELEMENT remote EMPTY>
+  <!ELEMENT remote (annotation*)>
   <!ATTLIST remote name         ID    #REQUIRED>
   <!ATTLIST remote alias        CDATA #IMPLIED>
   <!ATTLIST remote fetch        CDATA #REQUIRED>
@@ -54,6 +58,16 @@ following DTD:
   <!ELEMENT manifest-server EMPTY>
   <!ATTLIST manifest-server url CDATA #REQUIRED>
 
+  <!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>
+
   <!ELEMENT project (annotation*,
                      project*,
                      copyfile*,
@@ -87,22 +101,45 @@ following DTD:
   <!ELEMENT extend-project EMPTY>
   <!ATTLIST extend-project name CDATA #REQUIRED>
   <!ATTLIST extend-project path CDATA #IMPLIED>
+  <!ATTLIST extend-project dest-path CDATA #IMPLIED>
   <!ATTLIST extend-project groups CDATA #IMPLIED>
   <!ATTLIST extend-project revision CDATA #IMPLIED>
   <!ATTLIST extend-project remote CDATA #IMPLIED>
+  <!ATTLIST extend-project dest-branch CDATA #IMPLIED>
+  <!ATTLIST extend-project upstream CDATA #IMPLIED>
+  <!ATTLIST extend-project base-rev CDATA #IMPLIED>
 
   <!ELEMENT remove-project EMPTY>
-  <!ATTLIST remove-project name  CDATA #REQUIRED>
+  <!ATTLIST remove-project name     CDATA #IMPLIED>
+  <!ATTLIST remove-project path     CDATA #IMPLIED>
+  <!ATTLIST remove-project optional CDATA #IMPLIED>
+  <!ATTLIST remove-project base-rev CDATA #IMPLIED>
 
   <!ELEMENT repo-hooks EMPTY>
   <!ATTLIST repo-hooks in-project CDATA #REQUIRED>
   <!ATTLIST repo-hooks enabled-list CDATA #REQUIRED>
 
+  <!ELEMENT superproject EMPTY>
+  <!ATTLIST superproject name     CDATA #REQUIRED>
+  <!ATTLIST superproject remote   IDREF #IMPLIED>
+  <!ATTLIST superproject revision CDATA #IMPLIED>
+
+  <!ELEMENT contactinfo EMPTY>
+  <!ATTLIST contactinfo bugurl  CDATA #REQUIRED>
+
   <!ELEMENT include EMPTY>
-  <!ATTLIST include name CDATA #REQUIRED>
+  <!ATTLIST include name     CDATA #REQUIRED>
+  <!ATTLIST include groups   CDATA #IMPLIED>
+  <!ATTLIST include revision CDATA #IMPLIED>
 ]>
 ```
 
+For compatibility purposes across repo releases, all unknown elements are
+silently ignored.  However, repo reserves all possible names for itself for
+future use.  If you want to use custom elements, the `x-*` namespace is
+reserved for that purpose, and repo guarantees to never allocate any
+corresponding names.
+
 A description of the elements and their attributes follows.
 
 
@@ -110,6 +147,10 @@ A description of the elements and their attributes follows.
 
 The root element of the file.
 
+### Element notice
+
+Arbitrary text that is displayed to users whenever `repo sync` finishes.
+The content is simply passed through as it exists in the manifest.
 
 ### Element remote
 
@@ -142,8 +183,8 @@ 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
+Attribute `revision`: Name of a Git branch (e.g. `main` or
+`refs/heads/main`). Remotes with their own revision will override
 the default revision.
 
 ### Element default
@@ -156,11 +197,11 @@ 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
+Attribute `revision`: Name of a Git branch (e.g. `main` or
+`refs/heads/main`).  Project elements lacking their own
 revision attribute will use this revision.
 
-Attribute `dest-branch`: Name of a Git branch (e.g. `master`).
+Attribute `dest-branch`: Name of a Git branch (e.g. `main`).
 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.
@@ -190,27 +231,68 @@ 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:
+See the [smart sync documentation](./smart-sync.md) for more details.
 
-    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.
+### Element submanifest
 
-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.
+One or more submanifest elements may be specified.  Each element describes a
+single manifest to be checked out as a child.
 
-    GetManifest(tag)
+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.
 
-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.
+Attribute `remote`: Name of a previously defined remote element.
+If not supplied the remote given by the default element is used.
 
+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:
+
+    ${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.
+
+`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.
+
+If not supplied the remote and project for this manifest will be used: `remote`
+cannot be supplied.
+
+Projects from a submanifest and its submanifests are added to the
+submanifest::path:<path_prefix> group.
+
+Attribute `manifest-name`: The manifest filename in the manifest project.  If
+not supplied, `default.xml` is used.
+
+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.
+
+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.
+
+`path` may not be an absolute path or use "." or ".." path components.
+
+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`.
+
+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.
 
 ### Element project
 
@@ -236,24 +318,37 @@ 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.
 
+"name" 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.
+These restrictions are not enforced for [Local Manifests].
+
 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.
+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.
 
+"path" may not be an absolute path or use "." or ".." path components.
+These restrictions are not enforced for [Local Manifests].
+
+If you want to place files into the root of the checkout (e.g. a README or
+Makefile or another build script), use the [copyfile] or [linkfile] elements
+instead.
+
 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").
+(e.g. just "main") or absolute (e.g. "refs/heads/main").
 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`).
+Attribute `dest-branch`: Name of a Git branch (e.g. `main`).
 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.
@@ -262,7 +357,7 @@ 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
-<project name="monkeys" path="barrel-of"/>, that project
+`<project name="monkeys" path="barrel-of"/>`, 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.
@@ -301,6 +396,11 @@ 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 `dest-path`: If specified, a path relative to the top directory
+of the repo client where the Git working directory for this project
+should be placed.  This is used to move a project in the checkout by
+overriding the existing `path` setting.
+
 Attribute `groups`: List of additional groups to which this project
 belongs.  Same syntax as the corresponding element of `project`.
 
@@ -310,15 +410,29 @@ project.  Same syntax as the corresponding element of `project`.
 Attribute `remote`: If specified, overrides the remote of the original
 project.  Same syntax as the corresponding element of `project`.
 
+Attribute `dest-branch`: If specified, overrides the dest-branch of the original
+project.  Same syntax as the corresponding element of `project`.
+
+Attribute `upstream`: If specified, overrides the upstream of the original
+project.  Same syntax as the corresponding element of `project`.
+
+Attribute `base-rev`: If specified, adds a check against the revision
+to be extended. Manifest parse will fail and give a list of mismatch extends
+if the revisions being extended have changed since base-rev was set.
+Intended for use with layered manifests using hash revisions to prevent
+patch branches hiding newer upstream revisions. Also compares named refs
+like branches or tags but is misleading if branches are used as base-rev.
+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.
+project or remote element. Each element describes a name-value pair.
+For projects, this name-value pair 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
 
@@ -351,7 +465,7 @@ of the repo client.
 
 ### Element remove-project
 
-Deletes the named project from the internal manifest table, possibly
+Deletes a 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.
 
@@ -359,6 +473,81 @@ 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.
 
+The project `name` or project `path` can be used to specify the remove target
+meaning one of them is required. If only name is specified, all
+projects with that name are removed.
+
+If both name and path are specified, only projects with the same name and
+path are removed, meaning projects with the same name but in other
+locations are kept.
+
+If only path is specified, a matching project is removed regardless of its
+name. Logic otherwise behaves like both are specified.
+
+Attribute `optional`: Set to true to ignore remove-project elements with no
+matching `project` element.
+
+Attribute `base-rev`: If specified, adds a check against the revision
+to be removed. Manifest parse will fail and give a list of mismatch removes
+if the revisions being removed have changed since base-rev was set.
+Intended for use with layered manifests using hash revisions to prevent
+patch branches hiding newer upstream revisions. Also compares named refs
+like branches or tags but is misleading if branches are used as base-rev.
+Same syntax as the corresponding element of `project`.
+
+### Element repo-hooks
+
+NB: See the [practical documentation](./repo-hooks.md) for using repo hooks.
+
+Only one repo-hooks element may be specified at a time.
+Attempting to redefine it will fail to parse.
+
+Attribute `in-project`: The project where the hooks are defined.  The value
+must match the `name` attribute (**not** the `path` attribute) of a previously
+defined `project` element.
+
+Attribute `enabled-list`: List of hooks to use, whitespace or comma separated.
+
+### Element superproject
+
+***
+*Note*: This is currently a WIP.
+***
+
+NB: See the [git superprojects documentation](
+https://en.wikibooks.org/wiki/Git/Submodules_and_Superprojects) for background
+information.
+
+This element is used to specify the URL of the superproject. It has "name" and
+"remote" as atrributes. Only "name" is required while the others have
+reasonable defaults. At most one superproject may be specified.
+Attempting to redefine it will fail to parse.
+
+Attribute `name`: A unique name for the superproject. This attribute has the
+same meaning as project's name attribute. See the
+[element project](#element-project) for more information.
+
+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 superproject. If not supplied the revision given
+by the remote element is used if applicable, else the default
+element is used.
+
+### Element contactinfo
+
+***
+*Note*: This is currently a WIP.
+***
+
+This element is used to let manifest authors self-register contact info.
+It has "bugurl" as a required atrribute. This element can be repeated,
+and any later entries will clobber earlier ones. This would allow manifest
+authors who extend manifests to specify their own contact info.
+
+Attribute `bugurl`: The URL to file a bug against the manifest owner.
+
 ### Element include
 
 This element provides the capability of including another manifest
@@ -368,8 +557,18 @@ 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.
 
+"name" may not be an absolute path or use "." or ".." path components.
+These restrictions are not enforced for [Local Manifests].
 
-## Local Manifests
+Attribute `groups`: List of additional groups to which all projects
+in the included manifest belong. This appends and recurses, meaning
+all projects in included manifests carry all parent include groups.
+Same syntax as the corresponding element of `project`.
+
+Attribute `revision`: Name of a Git branch (e.g. `main` or `refs/heads/main`)
+default to which all projects in the included manifest belong.
+
+## Local Manifests {#local-manifests}
 
 Additional remotes and projects may be added through local manifest
 files stored in `$TOP_DIR/.repo/local_manifests/*.xml`.
@@ -396,10 +595,12 @@ 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.
+Projects from local manifest files are added into
+local::<local manifest filename> group.
 
-If `$TOP_DIR/.repo/local_manifest.xml` exists, it will be loaded before
-any manifest files stored in `$TOP_DIR/.repo/local_manifests/*.xml`.
+The legacy `$TOP_DIR/.repo/local_manifest.xml` path is no longer supported.
+
+
+[copyfile]: #Element-copyfile
+[linkfile]: #Element-linkfile
+[Local Manifests]: #local-manifests

docs/python-support.md

@@ -1,47 +1,92 @@
 # Supported Python Versions
 
-With Python 2.7 officially going EOL on [01 Jan 2020](https://pythonclock.org/),
-we need a support plan for the repo project itself.
-Inevitably, there will be a long tail of users who still want to use Python 2 on
-their old LTS/corp systems and have little power to change the system.
+This documents the current supported Python versions, and tries to provide
+guidance for when we decide to drop support for older versions.
 
 ## Summary
 
-* Python 3.6 (released Dec 2016) is required by default starting with repo-2.x.
-* Older versions of Python (e.g. v2.7) may use the legacy feature-frozen branch
-  based on repo-1.x.
+*   Python 3.6 (released Dec 2016) is required starting with repo-2.0.
+*   Older versions of Python (e.g. v2.7) may use old releases via the repo-1.x
+    branch, but no support is provided.
 
-## Overview
-
-We provide a branch for Python 2 users that is feature-frozen.
-Bugfixes may be added on a best-effort basis or from the community, but largely
-no new features will be added, nor is support guaranteed.
-
-Users can select this during `repo init` time via the [repo launcher].
-Otherwise the default branches (e.g. stable & master) will be used which will
-require Python 3.
-
-This means the [repo launcher] needs to support both Python 2 & Python 3, but
-since it doesn't import any other repo code, this shouldn't be too problematic.
-
-The master branch will require Python 3.6 at a minimum.
-If the system has an older version of Python 3, then users will have to select
-the legacy Python 2 branch instead.
-
-### repo hooks
+## repo hooks
 
 Projects that use [repo hooks] run on independent schedules.
-They might migrate to Python 3 earlier or later than us.
-To support them, we'll probe the shebang of the hook script and if we find an
-interpreter in there that indicates a different version than repo is currently
-running under, we'll attempt to reexec ourselves under that.
+Since it's not possible to detect what version of Python the hooks were written
+or tested against, we always import & exec them with the active Python version.
 
-For example, a hook with a header like `#!/usr/bin/python2` will have repo
-execute `/usr/bin/python2` to execute the hook code specifically if repo is
-currently running Python 3.
+If the user's Python is too new for the [repo hooks], then it is up to the hooks
+maintainer to update.
 
-For more details, consult the [repo hooks] documentation.
+## Repo launcher
+
+The [repo launcher] is an independent script that can support older versions of
+Python without holding back the rest of the codebase.
+If it detects the current version of Python is too old, it will try to reexec
+via a newer version of Python via standard `pythonX.Y` interpreter names.
+
+However, this is provided as a nicety when it is not onerous, and there is no
+official support for older versions of Python than the rest of the codebase.
+
+If your default python interpreters are too old to run the launcher even though
+you have newer versions installed, your choices are:
+
+*   Modify the [repo launcher]'s shebang to suite your environment.
+*   Download an older version of the [repo launcher] and don't upgrade it.
+    Be aware that we do not guarantee old repo launchers will work with current
+    versions of repo.  Bug reports using old launchers will not be accepted.
+
+## When to drop support
+
+So far, Python 3.6 has provided most of the interesting features that we want
+(e.g. typing & f-strings), and there haven't been features in newer versions
+that are critical to us.
+
+That said, let's assume we need functionality that only exists in Python 3.7.
+How do we decide when it's acceptable to drop Python 3.6?
+
+1.  Review the [Project References](./release-process.md#project-references) to
+    see what major distros are using the previous version of Python, and when
+    they go EOL.  Generally we care about Ubuntu LTS & current/previous Debian
+    stable versions.
+    *   If they're all EOL already, then go for it, drop support.
+    *   If they aren't EOL, start a thread on [repo-discuss] to see how the user
+        base feels about the proposal.
+1.  Update the "soft" versions in the codebase.  This will start warning users
+    that the older version is deprecated.
+    *   Update [repo](/repo) if the launcher needs updating.
+        This only helps with people who download newer launchers.
+    *   Update [main.py](/main.py) for the main codebase.
+        This warns for everyone regardless of [repo launcher] version.
+    *   Update [requirements.json](/requirements.json).
+        This allows [repo launcher] to display warnings/errors without having
+        to execute the new codebase.  This helps in case of syntax or module
+        changes where older versions won't even be able to import the new code.
+1.  After some grace period (ideally at least 2 quarters after the first release
+    with the updated soft requirements), update the "hard" versions, and then
+    start using the new functionality.
+
+## Python 2.7 & 3.0-3.5
+
+> **There is no support for these versions.**
+> **Do not file bugs if you are using old Python versions.**
+> **Any such reports will be marked invalid and ignored.**
+> **Upgrade your distro and/or runtime instead.**
+
+Fetch an old version of the [repo launcher]:
+
+```sh
+$ curl https://storage.googleapis.com/git-repo-downloads/repo-2.32 > ~/.bin/repo-2.32
+$ chmod a+rx ~/.bin/repo-2.32
+```
+
+Then initialize an old version of repo:
+
+```sh
+$ repo-2.32 init --repo-rev=repo-1 ...
+```
 
 
+[repo-discuss]: https://groups.google.com/forum/#!forum/repo-discuss
 [repo hooks]: ./repo-hooks.md
 [repo launcher]: ../repo

docs/release-process.md

@@ -5,6 +5,37 @@ related topics and flows.
 
 [TOC]
 
+## Schedule
+
+There is no specific schedule for when releases are made.
+Usually it's more along the lines of "enough minor changes have been merged",
+or "there's a known issue the maintainers know should get fixed".
+If you find a fix has been merged for an issue important to you, but hasn't been
+released after a week or so, feel free to [contact] us to request a new release.
+
+### Release Freezes {#freeze}
+
+We try to observe a regular schedule for when **not** to release.
+If something goes wrong, staff need to be active in order to respond quickly &
+effectively.
+We also don't want to disrupt non-Google organizations if possible.
+
+We generally follow the rules:
+
+* Release during Mon - Thu, 9:00 - 14:00 [US PT]
+* Avoid holidays
+  * All regular [US holidays]
+  * Large international ones if possible
+  * All the various [New Years]
+    * Jan 1 in Gregorian calendar is the most obvious
+    * Check for large Lunar New Years too
+* Follow the normal [Google production freeze schedule]
+
+[US holidays]: https://en.wikipedia.org/wiki/Federal_holidays_in_the_United_States
+[US PT]: https://en.wikipedia.org/wiki/Pacific_Time_Zone
+[New Years]: https://en.wikipedia.org/wiki/New_Year
+[Google production freeze schedule]: http://goto.google.com/prod-freeze
+
 ## Launcher script
 
 The main repo script serves as a standalone program and is often referred to as
@@ -49,11 +80,12 @@ control how repo finds updates:
 
 *   `--repo-url`: This tells repo where to clone the full repo project itself.
     It defaults to the official project (`REPO_URL` in the launcher script).
-*   `--repo-branch`: This tells repo which branch to use for the full project.
+*   `--repo-rev`: This tells repo which branch to use for the full project.
     It defaults to the `stable` branch (`REPO_REV` in the launcher script).
 
-Whenever `repo sync` is run, repo will check to see if an update is available.
-It fetches the latest repo-branch from the repo-url.
+Whenever `repo sync` is run, repo will, once every 24 hours, see if an update
+is available.
+It fetches the latest repo-rev from the repo-url.
 Then it verifies that the latest commit in the branch has a valid signed tag
 using `git tag -v` (which uses gpg).
 If the tag is valid, then repo will update its internal checkout to it.
@@ -64,9 +96,17 @@ If that tag is valid, then repo will warn and use that commit instead.
 
 If that tag cannot be verified, it gives up and forces the user to resolve.
 
+If env variable `REPO_SKIP_SELF_UPDATE` is defined, this will
+bypass the self update algorithm.
+
+### Force an update
+
+The `repo selfupdate` command can be used to force an immediate update.
+It is not subject to the 24 hour limitation.
+
 ## Branch management
 
-All development happens on the `master` branch and should generally be stable.
+All development happens on the `main` branch and should generally be stable.
 
 Since the repo launcher defaults to tracking the `stable` branch, it is not
 normally updated until a new release is available.
@@ -81,7 +121,7 @@ For example, when `stable` moves from `v1.10.x` to `v1.11.x`, then the `maint`
 branch will be updated from `v1.9.x` to `v1.10.x`.
 
 We don't have parallel release branches/series.
-Typically all tags are made against the `master` branch and then pushed to the
+Typically all tags are made against the `main` branch and then pushed to the
 `stable` branch to make it available to the rest of the world.
 Since repo doesn't typically see a lot of changes, this tends to be OK.
 
@@ -89,10 +129,10 @@ Since repo doesn't typically see a lot of changes, this tends to be OK.
 
 When you want to create a new release, you'll need to select a good version and
 create a signed tag using a key registered in repo itself.
-Typically we just tag the latest version of the `master` branch.
+Typically we just tag the latest version of the `main` branch.
 The tag could be pushed now, but it won't be used by clients normally (since the
-default `repo-branch` setting is `stable`).
-This would allow some early testing on systems who explicitly select `master`.
+default `repo-rev` setting is `stable`).
+This would allow some early testing on systems who explicitly select `main`.
 
 ### Creating a signed tag
 
@@ -106,23 +146,14 @@ internal processes for accessing the restricted keys.
 ***
 
 ```sh
-# Set the gpg key directory.
-$ export GNUPGHOME=~/.gnupg/repo/
-
-# Verify the listed key is “Repo Maintainer”.
-$ gpg -K
-
-# Pick whatever branch or commit you want to tag.
-$ r=master
-
 # Pick the new version.
-$ t=1.12.10
+$ t=v2.30
 
-# Create the signed tag.
-$ git tag -s v$t -u "Repo Maintainer <repo@android.kernel.org>" -m "repo $t" $r
+# Create a new signed tag with the current HEAD.
+$ ./release/sign-tag.py $t
 
 # Verify the signed tag.
-$ git show v$t
+$ git show $t
 ```
 
 ### Push the new release
@@ -131,11 +162,11 @@ Once you're ready to make the release available to everyone, push it to the
 `stable` branch.
 
 Make sure you never push the tag itself to the stable branch!
-Only push the commit -- notice the use of `$t` and `$r` below.
+Only push the commit -- note the use of `^0` below.
 
 ```sh
-$ git push https://gerrit-review.googlesource.com/git-repo v$t
-$ git push https://gerrit-review.googlesource.com/git-repo $r:stable
+$ git push https://gerrit-review.googlesource.com/git-repo $t
+$ git push https://gerrit-review.googlesource.com/git-repo $t^0:stable
 ```
 
 If something goes horribly wrong, you can force push the previous version to the
@@ -158,10 +189,168 @@ You can create a short changelog using the command:
 ```sh
 # If you haven't pushed to the stable branch yet, you can use origin/stable.
 # If you have pushed, change origin/stable to the previous release tag.
-$ git log --format="%h (%aN) %s" --no-merges origin/stable..$r
+# This assumes "main" is the current tagged release.  If it's newer, change it
+# to the current release tag too.
+$ git log --format="%h (%aN) %s" --no-merges origin/stable..main
 ```
 
+## Project References
 
+Here's a table showing the relationship of major tools, their EOL dates, and
+their status in Ubuntu & Debian.
+Those distros tend to be good indicators of how long we need to support things.
+
+Things in bold indicate stuff to take note of, but does not guarantee that we
+still support them.
+Things in italics are things we used to care about but probably don't anymore.
+
+|   Date   |     EOL      | [Git][rel-g] | [Python][rel-p] | [SSH][rel-o] | [Ubuntu][rel-u] / [Debian][rel-d] | Git | Python | SSH |
+|:--------:|:------------:|:------------:|:---------------:|:------------:|-----------------------------------|:---:|:------:|:---:|
+| Apr 2008 |              |              |                 | 5.0          |
+| Jun 2008 |              |              |                 | 5.1          |
+| Oct 2008 | *Oct 2013*   |              | 2.6.0           |              | *10.04 Lucid* - 10.10 Maverick / *Squeeze* |
+| Dec 2008 | *Feb 2009*   |              | 3.0.0           |
+| Feb 2009 |              |              |                 | 5.2          |
+| Feb 2009 | *Mar 2012*   |              |                 |              | Debian 5 Lenny       | 1.5.6.5 | 2.5.2 |
+| Jun 2009 | *Jun 2016*   |              | 3.1.0           |              | *10.04 Lucid* - 10.10 Maverick / *Squeeze* |
+| Sep 2009 |              |              |                 | 5.3          | *10.04 Lucid* |
+| Feb 2010 | *Oct 2012*   | 1.7.0        |                 |              | *10.04 Lucid* - *12.04 Precise* - 12.10 Quantal |
+| Mar 2010 |              |              |                 | 5.4          |
+| Apr 2010 |              |              |                 | 5.5          | 10.10 Maverick |
+| Apr 2010 | *Apr 2015*   |              |                 |              | *10.04 Lucid*        | 1.7.0.4  | 2.6.5 3.1.2  | 5.3 |
+| Jul 2010 | *Dec 2019*   |              | *2.7.0*         |              | 11.04 Natty - *<current>* |
+| Aug 2010 |              |              |                 | 5.6          |
+| Oct 2010 |              |              |                 |              | 10.10 Maverick       | 1.7.1    | 2.6.6 3.1.3  | 5.5 |
+| Jan 2011 |              |              |                 | 5.7          |
+| Feb 2011 |              |              |                 | 5.8          | 11.04 Natty |
+| Feb 2011 | *Feb 2016*   |              |                 |              | Debian 6 Squeeze     | 1.7.2.5  | 2.6.6 3.1.3  |
+| Apr 2011 |              |              |                 |              | 11.04 Natty          | 1.7.4    | 2.7.1 3.2.0  | 5.8 |
+| Sep 2011 |              |              |                 | 5.9          | *12.04 Precise* |
+| Oct 2011 | *Feb 2016*   |              | 3.2.0           |              | 11.04 Natty - 12.10 Quantal |
+| Oct 2011 |              |              |                 |              | 11.10 Ocelot         | 1.7.5.4  | 2.7.2 3.2.2  | 5.8 |
+| Apr 2012 |              |              |                 | 6.0          | 12.10 Quantal |
+| Apr 2012 | *Apr 2019*   |              |                 |              | *12.04 Precise*      | 1.7.9.5  | 2.7.3 3.2.3  | 5.9 |
+| Aug 2012 |              |              |                 | 6.1          | 13.04 Raring |
+| Sep 2012 | *Sep 2017*   |              | 3.3.0           |              | 13.04 Raring - 13.10 Saucy |
+| Oct 2012 | *Dec 2014*   | 1.8.0        |                 |              | 13.04 Raring - 13.10 Saucy |
+| Oct 2012 |              |              |                 |              | 12.10 Quantal        | 1.7.10.4 | 2.7.3 3.2.3  | 6.0 |
+| Mar 2013 |              |              |                 | 6.2          | 13.10 Saucy |
+| Apr 2013 |              |              |                 |              | 13.04 Raring         | 1.8.1.2  | 2.7.4 3.3.1  | 6.1 |
+| May 2013 | *May 2018*   |              |                 |              | Debian 7 Wheezy      | 1.7.10.4 | 2.7.3 3.2.3  |
+| Sep 2013 |              |              |                 | 6.3          |
+| Oct 2013 |              |              |                 |              | 13.10 Saucy          | 1.8.3.2  | 2.7.5 3.3.2  | 6.2 |
+| Nov 2013 |              |              |                 | 6.4          |
+| Jan 2014 |              |              |                 | 6.5          |
+| Feb 2014 | *Dec 2014*   | **1.9.0**    |                 |              | *14.04 Trusty* |
+| Mar 2014 | *Mar 2019*   |              | *3.4.0*         |              | *14.04 Trusty* - 15.10 Wily / *Jessie* |
+| Mar 2014 |              |              |                 | 6.6          | *14.04 Trusty* - 14.10 Utopic |
+| Apr 2014 | *Apr 2024*   |              |                 |              | *14.04 Trusty*       | 1.9.1    | 2.7.5 3.4.0  | 6.6 |
+| May 2014 | *Dec 2014*   | 2.0.0        |
+| Aug 2014 | *Dec 2014*   | *2.1.0*      |                 |              | 14.10 Utopic - 15.04 Vivid / *Jessie* |
+| Oct 2014 |              |              |                 | 6.7          | 15.04 Vivid |
+| Oct 2014 |              |              |                 |              | 14.10 Utopic         | 2.1.0    | 2.7.8 3.4.2  | 6.6 |
+| Nov 2014 | *Sep 2015*   | 2.2.0        |
+| Feb 2015 | *Sep 2015*   | 2.3.0        |
+| Mar 2015 |              |              |                 | 6.8          |
+| Apr 2015 | *May 2017*   | 2.4.0        |
+| Apr 2015 | *Jun 2020*   |              |                 |              | *Debian 8 Jessie*    | 2.1.4    | 2.7.9 3.4.2  |
+| Apr 2015 |              |              |                 |              | 15.04 Vivid          | 2.1.4    | 2.7.9 3.4.3  | 6.7 |
+| Jul 2015 | *May 2017*   | 2.5.0        |                 |              | 15.10 Wily |
+| Jul 2015 |              |              |                 | 6.9          | 15.10 Wily |
+| Aug 2015 |              |              |                 | 7.0          |
+| Aug 2015 |              |              |                 | 7.1          |
+| Sep 2015 | *May 2017*   | 2.6.0        |
+| Sep 2015 | *Sep 2020*   |              | *3.5.0*         |              | *16.04 Xenial* - 17.04 Zesty / *Stretch* |
+| Oct 2015 |              |              |                 |              | 15.10 Wily           | 2.5.0    | 2.7.9 3.4.3  | 6.9 |
+| Jan 2016 | *Jul 2017*   | *2.7.0*      |                 |              | *16.04 Xenial* |
+| Feb 2016 |              |              |                 | 7.2          | *16.04 Xenial* |
+| Mar 2016 | *Jul 2017*   | 2.8.0        |
+| Apr 2016 | *Apr 2026*   |              |                 |              | *16.04 Xenial*       | 2.7.4    | 2.7.11 3.5.1 | 7.2 |
+| Jun 2016 | *Jul 2017*   | 2.9.0        |                 |              | 16.10 Yakkety |
+| Jul 2016 |              |              |                 | 7.3          | 16.10 Yakkety |
+| Sep 2016 | *Sep 2017*   | 2.10.0       |
+| Oct 2016 |              |              |                 |              | 16.10 Yakkety        | 2.9.3    | 2.7.11 3.5.1 | 7.3 |
+| Nov 2016 | *Sep 2017*   | *2.11.0*     |                 |              | 17.04 Zesty / *Stretch* |
+| Dec 2016 | **Dec 2021** |              | **3.6.0**       |              | 17.10 Artful - **18.04 Bionic** - 18.10 Cosmic |
+| Dec 2016 |              |              |                 | 7.4          | 17.04 Zesty / *Debian 9 Stretch* |
+| Feb 2017 | *Sep 2017*   | 2.12.0       |
+| Mar 2017 |              |              |                 | 7.5          | 17.10 Artful |
+| Apr 2017 |              |              |                 |              | 17.04 Zesty          | 2.11.0   | 2.7.13 3.5.3 | 7.4 |
+| May 2017 | *May 2018*   | 2.13.0       |
+| Jun 2017 | *Jun 2022*   |              |                 |              | *Debian 9 Stretch*   | 2.11.0   | 2.7.13 3.5.3 | 7.4 |
+| Aug 2017 | *Dec 2019*   | 2.14.0       |                 |              | 17.10 Artful |
+| Oct 2017 | *Dec 2019*   | 2.15.0       |
+| Oct 2017 |              |              |                 | 7.6          | **18.04 Bionic** |
+| Oct 2017 |              |              |                 |              | 17.10 Artful         | 2.14.1   | 2.7.14 3.6.3 | 7.5 |
+| Jan 2018 | *Dec 2019*   | 2.16.0       |
+| Apr 2018 | *Mar 2021*   | **2.17.0**   |                 |              | **18.04 Bionic**     |
+| Apr 2018 |              |              |                 | 7.7          | 18.10 Cosmic |
+| Apr 2018 | **Apr 2028** |              |                 |              | **18.04 Bionic**     | 2.17.0   | 2.7.15 3.6.5 | 7.6 |
+| Jun 2018 | *Mar 2021*   | 2.18.0       |
+| Jun 2018 | **Jun 2023** |              | 3.7.0           |              | 19.04 Disco - **Buster** |
+| Aug 2018 |              |              |                 | 7.8          |
+| Sep 2018 | *Mar 2021*   | 2.19.0       |                 |              | 18.10 Cosmic |
+| Oct 2018 |              |              |                 | 7.9          | 19.04 Disco / **Buster** |
+| Oct 2018 |              |              |                 |              | 18.10 Cosmic         | 2.19.1   | 2.7.15 3.6.6 | 7.7 |
+| Dec 2018 | *Mar 2021*   | **2.20.0**   |                 |              | 19.04 Disco - 19.10 Eoan / **Buster** |
+| Feb 2019 | *Mar 2021*   | 2.21.0       |
+| Apr 2019 |              |              |                 | 8.0          | 19.10 Eoan |
+| Apr 2019 |              |              |                 |              | 19.04 Disco          | 2.20.1   | 2.7.16 3.7.3 | 7.9 |
+| Jun 2019 |              | 2.22.0       |
+| Jul 2019 | **Jul 2024** |              |                 |              | **Debian 10 Buster** | 2.20.1   | 2.7.16 3.7.3 | 7.9 |
+| Aug 2019 | *Mar 2021*   | 2.23.0       |
+| Oct 2019 | **Oct 2024** |              | 3.8.0           |              | **20.04 Focal** - 20.10 Groovy |
+| Oct 2019 |              |              |                 | 8.1          |
+| Oct 2019 |              |              |                 |              | 19.10 Eoan           | 2.20.1   | 2.7.17 3.7.5 | 8.0 |
+| Nov 2019 | *Mar 2021*   | 2.24.0       |
+| Jan 2020 | *Mar 2021*   | 2.25.0       |                 |              | **20.04 Focal** |
+| Feb 2020 |              |              |                 | 8.2          | **20.04 Focal** |
+| Mar 2020 | *Mar 2021*   | 2.26.0       |
+| Apr 2020 | **Apr 2030** |              |                 |              | **20.04 Focal**      | 2.25.1   | 2.7.17 3.8.2 | 8.2 |
+| May 2020 | *Mar 2021*   | 2.27.0       |                 |              | 20.10 Groovy |
+| May 2020 |              |              |                 | 8.3          |
+| Jul 2020 | *Mar 2021*   | 2.28.0       |
+| Sep 2020 |              |              |                 | 8.4          | 21.04 Hirsute / **Bullseye** |
+| Oct 2020 | *Mar 2021*   | 2.29.0       |
+| Oct 2020 |              |              |                 |              | 20.10 Groovy         | 2.27.0   | 2.7.18 3.8.6 | 8.3 |
+| Oct 2020 | **Oct 2025** |              | 3.9.0           |              | 21.04 Hirsute / **Bullseye** |
+| Dec 2020 | *Mar 2021*   | 2.30.0       |                 |              | 21.04 Hirsute / **Bullseye** |
+| Mar 2021 |              | 2.31.0       |                 | 8.5          |
+| Apr 2021 |              |              |                 | 8.6          |
+| Apr 2021 | *Jan 2022*   |              |                 |              | 21.04 Hirsute        | 2.30.2   | 2.7.18 3.9.4 | 8.4 |
+| Jun 2021 |              | 2.32.0       |
+| Aug 2021 |              | 2.33.0       |                 | 8.7          |
+| Aug 2021 | **Aug 2026** |              |                 |              | **Debian 11 Bullseye** | 2.30.2 | 2.7.18 3.9.2 | 8.4 |
+| Sep 2021 |              |              |                 | 8.8          |
+| Oct 2021 |              | 2.34.0       | 3.10.0          |              | **22.04 Jammy** |
+| Jan 2022 |              | 2.35.0       |
+| Feb 2022 |              |              |                 | 8.9          | **22.04 Jammy** |
+| Apr 2022 |              | 2.36.0       |                 | 9.0          |
+| Apr 2022 | **Apr 2032** |              |                 |              | **22.04 Jammy**      | 2.34.1 | 2.7.18 3.10.6 | 8.9 |
+| Jun 2022 |              | 2.37.0       |
+| Oct 2022 |              | 2.38.0       |                 | 9.1          |
+| Oct 2022 |              |              | 3.11.0          |              | **Bookworm** |
+| Dec 2022 |              | 2.39.0       |                 |              | **Bookworm** |
+| Feb 2023 |              |              |                 | 9.2          | **Bookworm** |
+| Mar 2023 |              | 2.40.0       |                 | 9.3          |
+| Jun 2023 |              | 2.41.0       |
+| Jun 2023 | **Jun 2028** |              |                 |              | **Debian 12 Bookworm** | 2.39.2 | 3.11.2 | 9.2 |
+| Aug 2023 |              | 2.42.0       |                 | 9.4          |
+| Oct 2023 |              |              | 3.12.0          | 9.5          |
+| Nov 2022 |              | 2.43.0       |
+| Dec 2023 |              |              |                 | 9.6          |
+| Feb 2024 |              | 2.44.0       |
+| Mar 2024 |              |              |                 | 9.7          |
+| Oct 2024 |              |              | 3.13.0          |
+| **Date** |   **EOL**    | **[Git][rel-g]** | **[Python][rel-p]** | **[SSH][rel-o]** | **[Ubuntu][rel-u] / [Debian][rel-d]** | **Git** | **Python** | **SSH** |
+
+
+[contact]: ../README.md#contact
+[rel-d]: https://en.wikipedia.org/wiki/Debian_version_history
+[rel-g]: https://en.wikipedia.org/wiki/Git#Releases
+[rel-o]: https://www.openssh.com/releasenotes.html
+[rel-p]: https://en.wikipedia.org/wiki/History_of_Python#Table_of_versions
+[rel-u]: https://wiki.ubuntu.com/Releases
 [example announcement]: https://groups.google.com/d/topic/repo-discuss/UGBNismWo1M/discussion
 [repo-discuss@googlegroups.com]: https://groups.google.com/forum/#!forum/repo-discuss
 [go/repo-release]: https://goto.google.com/repo-release

docs/repo-hooks.md

@@ -27,7 +27,7 @@ repohooks project is updated and a hook is triggered.
 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).
+[Android](https://android.googlesource.com/platform/manifest/+/HEAD/default.xml).
 The `<project>` line checks out the repohooks git repo to the local
 `tools/repohooks/` path.  The `<repo-hooks>` line says to look in the project
 with the name `platform/tools/repohooks` for hooks to run during the

docs/smart-sync.md

@@ -0,0 +1,129 @@
+# repo Smart Syncing
+
+Repo normally fetches & syncs manifests from the same URL specified during
+`repo init`, and that often fetches the latest revisions of all projects in
+the manifest.  This flow works well for tracking and developing with the
+latest code, but often it's desirable to sync to other points.  For example,
+to get a local build matching a specific release or build to reproduce bugs
+reported by other people.
+
+Repo's sync subcommand has support for fetching manifests from a server over
+an XML-RPC connection.  The local configuration and network API are defined by
+repo, but individual projects have to host their own server for the client to
+communicate with.
+
+This process is called "smart syncing" -- instead of blindly fetching the latest
+revision of all projects and getting an unknown state to develop against, the
+client passes a request to the server and is given a matching manifest that
+typically specifies specific commits for every project to fetch a known source
+state.
+
+[TOC]
+
+## Manifest Configuration
+
+The manifest specifies the server to communicate with via the
+the [`<manifest-server>` element](manifest-format.md#Element-manifest_server)
+element.  This is how the client knows what service to talk to.
+
+```xml
+  <manifest-server url="https://example.com/your/manifest/server/url" />
+```
+
+If the URL starts with `persistent-`, then the
+[`git-remote-persistent-https` helper](https://github.com/git/git/blob/HEAD/contrib/persistent-https/README)
+is used to communicate with the server.
+
+## Credentials
+
+Credentials may be specified directly in typical `username:password`
+[URI syntax](https://en.wikipedia.org/wiki/URI#Syntax) in the
+`<manifest-server>` element directly in the manifest.
+
+If they are not specified, `repo sync` has `--manifest-server-username=USERNAME`
+and `--manifest-server-password=PASSWORD` options.
+
+If those are not used, then repo will look up the host in your
+[`~/.netrc`](https://docs.python.org/3/library/netrc.html) database.
+
+When making the connection, cookies matching the host are automatically loaded
+from the cookiejar specified in
+[Git's `http.cookiefile` setting](https://git-scm.com/docs/git-config#Documentation/git-config.txt-httpcookieFile).
+
+## Manifest Server
+
+Unfortunately, there are no public reference implementations.  Google has an
+internal one for Android, but it is written using Google's internal systems,
+so wouldn't be that helpful as a reference.
+
+That said, the XML-RPC API is pretty simple, so any standard XML-RPC server
+example would do.  Google's internal server uses Python's
+[xmlrpc.server.SimpleXMLRPCDispatcher](https://docs.python.org/3/library/xmlrpc.server.html).
+
+## Network API
+
+The manifest server should implement the following RPC methods.
+
+### GetApprovedManifest
+
+> `GetApprovedManifest(branch: str, target: Optional[str]) -> str`
+
+The meaning of `branch` and `target` is not strictly defined.  The server may
+interpret them however it wants.  The recommended interpretation is that the
+`branch` matches the manifest branch, and `target` is an identifier for your
+project that matches something users would build.
+
+See the client section below for how repo typically generates these values.
+
+The server will return a manifest or an error.  If it's an error, repo will
+show the output directly to the user to provide a limited feedback channel.
+
+If the user's request is ambiguous and could match multiple manifests, the
+server has to decide whether to pick one automatically (and silently such that
+the user won't know there were multiple matches), or return an error and force
+the user to be more specific.
+
+### GetManifest
+
+> `GetManifest(tag: str) -> str`
+
+The meaning of `tag` is not strictly defined.  Projects are encouraged to use
+a system where the tag matches a unique source state.
+
+See the client section below for how repo typically generates these values.
+
+The server will return a manifest or an error.  If it's an error, repo will
+show the output directly to the user to provide a limited feedback channel.
+
+If the user's request is ambiguous and could match multiple manifests, the
+server has to decide whether to pick one automatically (and silently such that
+the user won't know there were multiple matches), or return an error and force
+the user to be more specific.
+
+## Client Options
+
+Once repo has successfully downloaded the manifest from the server, it saves a
+copy into `.repo/manifests/smart_sync_override.xml` so users can examine it.
+The next time `repo sync` is run, this file is automatically replaced or removed
+based on the current set of options.
+
+### --smart-sync
+
+Repo will call `GetApprovedManifest(branch[, target])`.
+
+The `branch` is determined by the current manifest branch as specified by
+`--manifest-branch=BRANCH` when running `repo init`.
+
+The `target` is defined by environment variables in the order below.  If none
+of them match, then `target` is omitted.  These variables were decided as they
+match the settings Android build environments automatically setup.
+
+1.  `${SYNC_TARGET}`: If defined, the value is used directly.
+2.  `${TARGET_PRODUCT}-${TARGET_RELEASE}-${TARGET_BUILD_VARIANT}`: If these
+    variables are all defined, then they are merged with `-` and used.
+3.  `${TARGET_PRODUCT}-${TARGET_BUILD_VARIANT}`: If these variables are all
+    defined, then they are merged with `-` and used.
+
+### --smart-tag=TAG
+
+Repo will call `GetManifest(TAG)`.

docs/windows.md

@@ -19,7 +19,33 @@ also due to most developers not using Windows.
 We will never add code specific to older versions of Windows.
 It might work, but it most likely won't, so please don't bother asking.
 
-## Symlinks
+## Git worktrees
+
+*** note
+**Warning**: Repo's support for Git worktrees is new & experimental.
+Please report any bugs and be sure to maintain backups!
+***
+
+The Repo 2.4 release introduced support for [Git worktrees][git-worktree].
+You don't have to worry about or understand this particular feature, so don't
+worry if this section of the Git manual is particularly impenetrable.
+
+The salient point is that Git worktrees allow Repo to create repo client
+checkouts that do not require symlinks at all under Windows.
+This means users no longer need Administrator access to sync code.
+
+Simply use `--worktree` when running `repo init` to opt in.
+
+This does not effect specific Git repositories that use symlinks themselves.
+
+[git-worktree]: https://git-scm.com/docs/git-worktree
+
+## Symlinks by default
+
+*** note
+**NB**: This section applies to the default Repo behavior which does not use
+Git worktrees (see the previous section for more info).
+***
 
 Repo will use symlinks heavily internally.
 On *NIX platforms, this isn't an issue, but Windows makes it a bit difficult.
@@ -62,9 +88,8 @@ This also helps `tar` unpack symlinks, so that's nice.
 
 ## Python
 
-You should make sure to be running Python 3.6 or newer under Windows.
-Python 2 might work, but due to already limited platform testing, you should
-only run newer Python versions.
+Python 3.6 or newer is required.
+Python 2 is known to be broken when running under Windows.
 See our [Python Support](./python-support.md) document for more details.
 
 You can grab the latest Windows installer here:<br>

editor.py

@@ -1,5 +1,3 @@
-# -*- coding:utf-8 -*-
-#
 # Copyright (C) 2008 The Android Open Source Project
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -14,104 +12,108 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-from __future__ import print_function
 import os
 import re
-import sys
 import subprocess
+import sys
 import tempfile
 
 from error import EditorError
 import platform_utils
 
-class Editor(object):
-  """Manages the user's preferred text editor."""
 
-  _editor = None
-  globalConfig = None
+class Editor:
+    """Manages the user's preferred text editor."""
 
-  @classmethod
-  def _GetEditor(cls):
-    if cls._editor is None:
-      cls._editor = cls._SelectEditor()
-    return cls._editor
+    _editor = None
+    globalConfig = None
 
-  @classmethod
-  def _SelectEditor(cls):
-    e = os.getenv('GIT_EDITOR')
-    if e:
-      return e
+    @classmethod
+    def _GetEditor(cls):
+        if cls._editor is None:
+            cls._editor = cls._SelectEditor()
+        return cls._editor
 
-    if cls.globalConfig:
-      e = cls.globalConfig.GetString('core.editor')
-      if e:
-        return e
+    @classmethod
+    def _SelectEditor(cls):
+        e = os.getenv("GIT_EDITOR")
+        if e:
+            return e
 
-    e = os.getenv('VISUAL')
-    if e:
-      return e
+        if cls.globalConfig:
+            e = cls.globalConfig.GetString("core.editor")
+            if e:
+                return e
 
-    e = os.getenv('EDITOR')
-    if e:
-      return e
+        e = os.getenv("VISUAL")
+        if e:
+            return e
 
-    if os.getenv('TERM') == 'dumb':
-      print(
-"""No editor specified in GIT_EDITOR, core.editor, VISUAL or EDITOR.
+        e = os.getenv("EDITOR")
+        if e:
+            return e
+
+        if os.getenv("TERM") == "dumb":
+            print(
+                """No editor specified in GIT_EDITOR, core.editor, VISUAL or EDITOR.
 Tried to fall back to vi but terminal is dumb.  Please configure at
-least one of these before using this command.""", file=sys.stderr)
-      sys.exit(1)
+least one of these before using this command.""",  # noqa: E501
+                file=sys.stderr,
+            )
+            sys.exit(1)
 
-    return 'vi'
+        return "vi"
 
-  @classmethod
-  def EditString(cls, data):
-    """Opens an editor to edit the given content.
+    @classmethod
+    def EditString(cls, data):
+        """Opens an editor to edit the given content.
 
-    Args:
-      data: The text to edit.
+        Args:
+            data: The text to edit.
 
-    Returns:
-      New value of edited text.
+        Returns:
+            New value of edited text.
 
-    Raises:
-      EditorError: The editor failed to run.
-    """
-    editor = cls._GetEditor()
-    if editor == ':':
-      return data
+        Raises:
+            EditorError: The editor failed to run.
+        """
+        editor = cls._GetEditor()
+        if editor == ":":
+            return data
 
-    fd, path = tempfile.mkstemp()
-    try:
-      os.write(fd, data.encode('utf-8'))
-      os.close(fd)
-      fd = None
+        fd, path = tempfile.mkstemp()
+        try:
+            os.write(fd, data.encode("utf-8"))
+            os.close(fd)
+            fd = None
 
-      if platform_utils.isWindows():
-        # Split on spaces, respecting quoted strings
-        import shlex
-        args = shlex.split(editor)
-        shell = False
-      elif re.compile("^.*[$ \t'].*$").match(editor):
-        args = [editor + ' "$@"', 'sh']
-        shell = True
-      else:
-        args = [editor]
-        shell = False
-      args.append(path)
+            if platform_utils.isWindows():
+                # Split on spaces, respecting quoted strings
+                import shlex
 
-      try:
-        rc = subprocess.Popen(args, shell=shell).wait()
-      except OSError as e:
-        raise EditorError('editor failed, %s: %s %s'
-          % (str(e), editor, path))
-      if rc != 0:
-        raise EditorError('editor failed with exit status %d: %s %s'
-          % (rc, editor, path))
+                args = shlex.split(editor)
+                shell = False
+            elif re.compile("^.*[$ \t'].*$").match(editor):
+                args = [editor + ' "$@"', "sh"]
+                shell = True
+            else:
+                args = [editor]
+                shell = False
+            args.append(path)
 
-      with open(path, mode='rb') as fd2:
-        return fd2.read().decode('utf-8')
-    finally:
-      if fd:
-        os.close(fd)
-      platform_utils.remove(path)
+            try:
+                rc = subprocess.Popen(args, shell=shell).wait()
+            except OSError as e:
+                raise EditorError(f"editor failed, {str(e)}: {editor} {path}")
+            if rc != 0:
+                raise EditorError(
+                    "editor failed with exit status %d: %s %s"
+                    % (rc, editor, path)
+                )
+
+            with open(path, mode="rb") as fd2:
+                return fd2.read().decode("utf-8")
+        finally:
+            if fd:
+                os.close(fd)
+            platform_utils.remove(path)

error.py

@@ -1,5 +1,3 @@
-# -*- coding:utf-8 -*-
-#
 # Copyright (C) 2008 The Android Open Source Project
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -14,105 +12,178 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-class ManifestParseError(Exception):
-  """Failed to parse the manifest file.
-  """
-
-class ManifestInvalidRevisionError(Exception):
-  """The revision value in a project is incorrect.
-  """
-
-class ManifestInvalidPathError(Exception):
-  """A path used in <copyfile> or <linkfile> is incorrect.
-  """
-
-class NoManifestException(Exception):
-  """The required manifest does not exist.
-  """
-  def __init__(self, path, reason):
-    super(NoManifestException, self).__init__()
-    self.path = path
-    self.reason = reason
-
-  def __str__(self):
-    return self.reason
-
-class EditorError(Exception):
-  """Unspecified error from the user's text editor.
-  """
-  def __init__(self, reason):
-    super(EditorError, self).__init__()
-    self.reason = reason
-
-  def __str__(self):
-    return self.reason
-
-class GitError(Exception):
-  """Unspecified internal error from git.
-  """
-  def __init__(self, command):
-    super(GitError, self).__init__()
-    self.command = command
-
-  def __str__(self):
-    return self.command
-
-class UploadError(Exception):
-  """A bundle upload to Gerrit did not succeed.
-  """
-  def __init__(self, reason):
-    super(UploadError, self).__init__()
-    self.reason = reason
-
-  def __str__(self):
-    return self.reason
-
-class DownloadError(Exception):
-  """Cannot download a repository.
-  """
-  def __init__(self, reason):
-    super(DownloadError, self).__init__()
-    self.reason = reason
-
-  def __str__(self):
-    return self.reason
-
-class NoSuchProjectError(Exception):
-  """A specified project does not exist in the work tree.
-  """
-  def __init__(self, name=None):
-    super(NoSuchProjectError, self).__init__()
-    self.name = name
-
-  def __str__(self):
-    if self.name is None:
-      return 'in current directory'
-    return self.name
+from typing import List
 
 
-class InvalidProjectGroupsError(Exception):
-  """A specified project is not suitable for the specified groups
-  """
-  def __init__(self, name=None):
-    super(InvalidProjectGroupsError, self).__init__()
-    self.name = name
+class BaseRepoError(Exception):
+    """All repo specific exceptions derive from BaseRepoError."""
 
-  def __str__(self):
-    if self.name is None:
-      return 'in current directory'
-    return self.name
 
-class RepoChangedException(Exception):
-  """Thrown if 'repo sync' results in repo updating its internal
-     repo or manifest repositories.  In this special case we must
-     use exec to re-execute repo with the new code and manifest.
-  """
-  def __init__(self, extra_args=None):
-    super(RepoChangedException, self).__init__()
-    self.extra_args = extra_args or []
+class RepoError(BaseRepoError):
+    """Exceptions thrown inside repo that can be handled."""
 
-class HookError(Exception):
-  """Thrown if a 'repo-hook' could not be run.
+    def __init__(self, *args, project: str = None) -> None:
+        super().__init__(*args)
+        self.project = project
 
-  The common case is that the file wasn't present when we tried to run it.
-  """
+
+class RepoExitError(BaseRepoError):
+    """Exception thrown that result in termination of repo program.
+    - Should only be handled in main.py
+    """
+
+    def __init__(
+        self,
+        *args,
+        exit_code: int = 1,
+        aggregate_errors: List[Exception] = None,
+        **kwargs,
+    ) -> None:
+        super().__init__(*args, **kwargs)
+        self.exit_code = exit_code
+        self.aggregate_errors = aggregate_errors
+
+
+class RepoUnhandledExceptionError(RepoExitError):
+    """Exception that maintains error as reason for program exit."""
+
+    def __init__(
+        self,
+        error: BaseException,
+        **kwargs,
+    ) -> None:
+        super().__init__(error, **kwargs)
+        self.error = error
+
+
+class SilentRepoExitError(RepoExitError):
+    """RepoExitError that should no include CLI logging of issue/issues."""
+
+
+class ManifestParseError(RepoExitError):
+    """Failed to parse the manifest file."""
+
+
+class ManifestInvalidRevisionError(ManifestParseError):
+    """The revision value in a project is incorrect."""
+
+
+class ManifestInvalidPathError(ManifestParseError):
+    """A path used in <copyfile> or <linkfile> is incorrect."""
+
+
+class NoManifestException(RepoExitError):
+    """The required manifest does not exist."""
+
+    def __init__(self, path, reason, **kwargs):
+        super().__init__(path, reason, **kwargs)
+        self.path = path
+        self.reason = reason
+
+    def __str__(self):
+        return self.reason
+
+
+class EditorError(RepoError):
+    """Unspecified error from the user's text editor."""
+
+    def __init__(self, reason, **kwargs):
+        super().__init__(reason, **kwargs)
+        self.reason = reason
+
+    def __str__(self):
+        return self.reason
+
+
+class GitError(RepoError):
+    """Unspecified git related error."""
+
+    def __init__(self, message, command_args=None, **kwargs):
+        super().__init__(message, **kwargs)
+        self.message = message
+        self.command_args = command_args
+
+    def __str__(self):
+        return self.message
+
+
+class GitAuthError(RepoExitError):
+    """Cannot talk to remote due to auth issue."""
+
+
+class UploadError(RepoError):
+    """A bundle upload to Gerrit did not succeed."""
+
+    def __init__(self, reason, **kwargs):
+        super().__init__(reason, **kwargs)
+        self.reason = reason
+
+    def __str__(self):
+        return self.reason
+
+
+class DownloadError(RepoExitError):
+    """Cannot download a repository."""
+
+    def __init__(self, reason, **kwargs):
+        super().__init__(reason, **kwargs)
+        self.reason = reason
+
+    def __str__(self):
+        return self.reason
+
+
+class InvalidArgumentsError(RepoExitError):
+    """Invalid command Arguments."""
+
+
+class SyncError(RepoExitError):
+    """Cannot sync repo."""
+
+
+class UpdateManifestError(RepoExitError):
+    """Cannot update manifest."""
+
+
+class NoSuchProjectError(RepoExitError):
+    """A specified project does not exist in the work tree."""
+
+    def __init__(self, name=None, **kwargs):
+        super().__init__(**kwargs)
+        self.name = name
+
+    def __str__(self):
+        if self.name is None:
+            return "in current directory"
+        return self.name
+
+
+class InvalidProjectGroupsError(RepoExitError):
+    """A specified project is not suitable for the specified groups"""
+
+    def __init__(self, name=None, **kwargs):
+        super().__init__(**kwargs)
+        self.name = name
+
+    def __str__(self):
+        if self.name is None:
+            return "in current directory"
+        return self.name
+
+
+class RepoChangedException(BaseRepoError):
+    """Thrown if 'repo sync' results in repo updating its internal
+    repo or manifest repositories.  In this special case we must
+    use exec to re-execute repo with the new code and manifest.
+    """
+
+    def __init__(self, extra_args=None):
+        super().__init__(extra_args)
+        self.extra_args = extra_args or []
+
+
+class HookError(RepoError):
+    """Thrown if a 'repo-hook' could not be run.
+
+    The common case is that the file wasn't present when we tried to run it.
+    """

event_log.py

@@ -1,5 +1,3 @@
-# -*- coding:utf-8 -*-
-#
 # Copyright (C) 2017 The Android Open Source Project
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -14,164 +12,181 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-from __future__ import print_function
-
 import json
 import multiprocessing
 
-TASK_COMMAND = 'command'
-TASK_SYNC_NETWORK = 'sync-network'
-TASK_SYNC_LOCAL = 'sync-local'
 
-class EventLog(object):
-  """Event log that records events that occurred during a repo invocation.
+TASK_COMMAND = "command"
+TASK_SYNC_NETWORK = "sync-network"
+TASK_SYNC_LOCAL = "sync-local"
 
-  Events are written to the log as a consecutive JSON entries, one per line.
-  Each entry contains the following keys:
-  - id: A ('RepoOp', ID) tuple, suitable for storing in a datastore.
-        The ID is only unique for the invocation of the repo command.
-  - name: Name of the object being operated upon.
-  - task_name: The task that was performed.
-  - start: Timestamp of when the operation started.
-  - finish: Timestamp of when the operation finished.
-  - success: Boolean indicating if the operation was successful.
-  - try_count: A counter indicating the try count of this task.
 
-  Optionally:
-  - parent: A ('RepoOp', ID) tuple indicating the parent event for nested
-            events.
+class EventLog:
+    """Event log that records events that occurred during a repo invocation.
 
-  Valid task_names include:
-  - command: The invocation of a subcommand.
-  - sync-network: The network component of a sync command.
-  - sync-local: The local component of a sync command.
+    Events are written to the log as a consecutive JSON entries, one per line.
+    Each entry contains the following keys:
+    - id: A ('RepoOp', ID) tuple, suitable for storing in a datastore.
+          The ID is only unique for the invocation of the repo command.
+    - name: Name of the object being operated upon.
+    - task_name: The task that was performed.
+    - start: Timestamp of when the operation started.
+    - finish: Timestamp of when the operation finished.
+    - success: Boolean indicating if the operation was successful.
+    - try_count: A counter indicating the try count of this task.
 
-  Specific tasks may include additional informational properties.
-  """
+    Optionally:
+    - parent: A ('RepoOp', ID) tuple indicating the parent event for nested
+        events.
 
-  def __init__(self):
-    """Initializes the event log."""
-    self._log = []
-    self._parent = None
+    Valid task_names include:
+    - command: The invocation of a subcommand.
+    - sync-network: The network component of a sync command.
+    - sync-local: The local component of a sync command.
 
-  def Add(self, name, task_name, start, finish=None, success=None,
-          try_count=1, kind='RepoOp'):
-    """Add an event to the log.
-
-    Args:
-      name: Name of the object being operated upon.
-      task_name: A sub-task that was performed for name.
-      start: Timestamp of when the operation started.
-      finish: Timestamp of when the operation finished.
-      success: Boolean indicating if the operation was successful.
-      try_count: A counter indicating the try count of this task.
-      kind: The kind of the object for the unique identifier.
-
-    Returns:
-      A dictionary of the event added to the log.
+    Specific tasks may include additional informational properties.
     """
-    event = {
-        'id': (kind, _NextEventId()),
-        'name': name,
-        'task_name': task_name,
-        'start_time': start,
-        'try': try_count,
-    }
 
-    if self._parent:
-      event['parent'] = self._parent['id']
+    def __init__(self):
+        """Initializes the event log."""
+        self._log = []
+        self._parent = None
 
-    if success is not None or finish is not None:
-        self.FinishEvent(event, finish, success)
+    def Add(
+        self,
+        name,
+        task_name,
+        start,
+        finish=None,
+        success=None,
+        try_count=1,
+        kind="RepoOp",
+    ):
+        """Add an event to the log.
 
-    self._log.append(event)
-    return event
+        Args:
+            name: Name of the object being operated upon.
+            task_name: A sub-task that was performed for name.
+            start: Timestamp of when the operation started.
+            finish: Timestamp of when the operation finished.
+            success: Boolean indicating if the operation was successful.
+            try_count: A counter indicating the try count of this task.
+            kind: The kind of the object for the unique identifier.
 
-  def AddSync(self, project, task_name, start, finish, success):
-    """Add a event to the log for a sync command.
+        Returns:
+            A dictionary of the event added to the log.
+        """
+        event = {
+            "id": (kind, _NextEventId()),
+            "name": name,
+            "task_name": task_name,
+            "start_time": start,
+            "try": try_count,
+        }
 
-    Args:
-      project: Project being synced.
-      task_name: A sub-task that was performed for name.
-                 One of (TASK_SYNC_NETWORK, TASK_SYNC_LOCAL)
-      start: Timestamp of when the operation started.
-      finish: Timestamp of when the operation finished.
-      success: Boolean indicating if the operation was successful.
+        if self._parent:
+            event["parent"] = self._parent["id"]
 
-    Returns:
-      A dictionary of the event added to the log.
-    """
-    event = self.Add(project.relpath, task_name, start, finish, success)
-    if event is not None:
-      event['project'] = project.name
-      if project.revisionExpr:
-        event['revision'] = project.revisionExpr
-      if project.remote.url:
-        event['project_url'] = project.remote.url
-      if project.remote.fetchUrl:
-        event['remote_url'] = project.remote.fetchUrl
-      try:
-        event['git_hash'] = project.GetCommitRevisionId()
-      except Exception:
-        pass
-    return event
+        if success is not None or finish is not None:
+            self.FinishEvent(event, finish, success)
 
-  def GetStatusString(self, success):
-    """Converst a boolean success to a status string.
+        self._log.append(event)
+        return event
 
-    Args:
-      success: Boolean indicating if the operation was successful.
+    def AddSync(self, project, task_name, start, finish, success):
+        """Add a event to the log for a sync command.
 
-    Returns:
-      status string.
-    """
-    return 'pass' if success else 'fail'
+        Args:
+            project: Project being synced.
+            task_name: A sub-task that was performed for name.
+                One of (TASK_SYNC_NETWORK, TASK_SYNC_LOCAL)
+            start: Timestamp of when the operation started.
+            finish: Timestamp of when the operation finished.
+            success: Boolean indicating if the operation was successful.
 
-  def FinishEvent(self, event, finish, success):
-    """Finishes an incomplete event.
+        Returns:
+            A dictionary of the event added to the log.
+        """
+        event = self.Add(project.relpath, task_name, start, finish, success)
+        if event is not None:
+            event["project"] = project.name
+            if project.revisionExpr:
+                event["revision"] = project.revisionExpr
+            if project.remote.url:
+                event["project_url"] = project.remote.url
+            if project.remote.fetchUrl:
+                event["remote_url"] = project.remote.fetchUrl
+            try:
+                event["git_hash"] = project.GetCommitRevisionId()
+            except Exception:
+                pass
+        return event
 
-    Args:
-      event: An event that has been added to the log.
-      finish: Timestamp of when the operation finished.
-      success: Boolean indicating if the operation was successful.
+    def GetStatusString(self, success):
+        """Converst a boolean success to a status string.
 
-    Returns:
-      A dictionary of the event added to the log.
-    """
-    event['status'] =  self.GetStatusString(success)
-    event['finish_time'] = finish
-    return event
+        Args:
+            success: Boolean indicating if the operation was successful.
 
-  def SetParent(self, event):
-    """Set a parent event for all new entities.
+        Returns:
+            status string.
+        """
+        return "pass" if success else "fail"
 
-    Args:
-      event: The event to use as a parent.
-    """
-    self._parent = event
+    def FinishEvent(self, event, finish, success):
+        """Finishes an incomplete event.
 
-  def Write(self, filename):
-    """Writes the log out to a file.
+        Args:
+            event: An event that has been added to the log.
+            finish: Timestamp of when the operation finished.
+            success: Boolean indicating if the operation was successful.
 
-    Args:
-      filename: The file to write the log to.
-    """
-    with open(filename, 'w+') as f:
-      for e in self._log:
-        json.dump(e, f, sort_keys=True)
-        f.write('\n')
+        Returns:
+            A dictionary of the event added to the log.
+        """
+        event["status"] = self.GetStatusString(success)
+        event["finish_time"] = finish
+        return event
+
+    def SetParent(self, event):
+        """Set a parent event for all new entities.
+
+        Args:
+            event: The event to use as a parent.
+        """
+        self._parent = event
+
+    def Write(self, filename):
+        """Writes the log out to a file.
+
+        Args:
+            filename: The file to write the log to.
+        """
+        with open(filename, "w+") as f:
+            for e in self._log:
+                json.dump(e, f, sort_keys=True)
+                f.write("\n")
 
 
-# An integer id that is unique across this invocation of the program.
-_EVENT_ID = multiprocessing.Value('i', 1)
+# An integer id that is unique across this invocation of the program, to be set
+# by the first Add event. We can't set it here since it results in leaked
+# resources (see: https://issues.gerritcodereview.com/353656374).
+_EVENT_ID = None
+
 
 def _NextEventId():
-  """Helper function for grabbing the next unique id.
+    """Helper function for grabbing the next unique id.
 
-  Returns:
-    A unique, to this invocation of the program, integer id.
-  """
-  with _EVENT_ID.get_lock():
-    val = _EVENT_ID.value
-    _EVENT_ID.value += 1
-  return val
+    Returns:
+        A unique, to this invocation of the program, integer id.
+    """
+    global _EVENT_ID
+    if _EVENT_ID is None:
+        # There is a small chance of race condition - two parallel processes
+        # setting up _EVENT_ID. However, we expect TASK_COMMAND to happen before
+        # mp kicks in.
+        _EVENT_ID = multiprocessing.Value("i", 1)
+    with _EVENT_ID.get_lock():
+        val = _EVENT_ID.value
+        _EVENT_ID.value += 1
+    return val

fetch.py

@@ -0,0 +1,57 @@
+# Copyright (C) 2021 The Android Open Source Project
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""This module contains functions used to fetch files from various sources."""
+
+import subprocess
+import sys
+from urllib.parse import urlparse
+from urllib.request import urlopen
+
+from error import RepoExitError
+
+
+class FetchFileError(RepoExitError):
+    """Exit error when fetch_file fails."""
+
+
+def fetch_file(url, verbose=False):
+    """Fetch a file from the specified source using the appropriate protocol.
+
+    Returns:
+        The contents of the file as bytes.
+    """
+    scheme = urlparse(url).scheme
+    if scheme == "gs":
+        cmd = ["gsutil", "cat", url]
+        errors = []
+        try:
+            result = subprocess.run(
+                cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE, check=True
+            )
+            if result.stderr and verbose:
+                print(
+                    'warning: non-fatal error running "gsutil": %s'
+                    % result.stderr,
+                    file=sys.stderr,
+                )
+            return result.stdout
+        except subprocess.CalledProcessError as e:
+            errors.append(e)
+            print(
+                'fatal: error running "gsutil": %s' % e.stderr, file=sys.stderr
+            )
+        raise FetchFileError(aggregate_errors=errors)
+    with urlopen(url) as f:
+        return f.read()

git_command.py

@@ -1,5 +1,3 @@
-# -*- coding:utf-8 -*-
-#
 # Copyright (C) 2008 The Android Open Source Project
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -14,339 +12,639 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-from __future__ import print_function
+import functools
+import json
 import os
-import sys
+import re
 import subprocess
-import tempfile
-from signal import SIGTERM
+import sys
+from typing import Any, Optional
 
 from error import GitError
+from error import RepoExitError
 from git_refs import HEAD
+from git_trace2_event_log_base import BaseEventLog
 import platform_utils
-from repo_trace import REPO_TRACE, IsTrace, Trace
+from repo_logging import RepoLogger
+from repo_trace import IsTrace
+from repo_trace import REPO_TRACE
+from repo_trace import Trace
 from wrapper import Wrapper
 
-GIT = 'git'
-# Should keep in sync with the "repo" launcher file.
-MIN_GIT_VERSION = (2, 10, 2)
-GIT_DIR = 'GIT_DIR'
+
+GIT = "git"
+GIT_DIR = "GIT_DIR"
 
 LAST_GITDIR = None
 LAST_CWD = None
+DEFAULT_GIT_FAIL_MESSAGE = "git command failure"
+ERROR_EVENT_LOGGING_PREFIX = "RepoGitCommandError"
+# Common line length limit
+GIT_ERROR_STDOUT_LINES = 1
+GIT_ERROR_STDERR_LINES = 10
+INVALID_GIT_EXIT_CODE = 126
 
-_ssh_proxy_path = None
-_ssh_sock_path = None
-_ssh_clients = []
+logger = RepoLogger(__file__)
 
-def ssh_sock(create=True):
-  global _ssh_sock_path
-  if _ssh_sock_path is None:
-    if not create:
-      return None
-    tmp_dir = '/tmp'
-    if not os.path.exists(tmp_dir):
-      tmp_dir = tempfile.gettempdir()
-    _ssh_sock_path = os.path.join(
-      tempfile.mkdtemp('', 'ssh-', tmp_dir),
-      'master-%r@%h:%p')
-  return _ssh_sock_path
 
-def _ssh_proxy():
-  global _ssh_proxy_path
-  if _ssh_proxy_path is None:
-    _ssh_proxy_path = os.path.join(
-      os.path.dirname(__file__),
-      'git_ssh')
-  return _ssh_proxy_path
+class _GitCall:
+    @functools.lru_cache(maxsize=None)
+    def version_tuple(self):
+        ret = Wrapper().ParseGitVersion()
+        if ret is None:
+            msg = "fatal: unable to detect git version"
+            logger.error(msg)
+            raise GitRequireError(msg)
+        return ret
 
-def _add_ssh_client(p):
-  _ssh_clients.append(p)
+    def __getattr__(self, name):
+        name = name.replace("_", "-")
 
-def _remove_ssh_client(p):
-  try:
-    _ssh_clients.remove(p)
-  except ValueError:
-    pass
+        def fun(*cmdv):
+            command = [name]
+            command.extend(cmdv)
+            return GitCommand(None, command, add_event_log=False).Wait() == 0
 
-def terminate_ssh_clients():
-  global _ssh_clients
-  for p in _ssh_clients:
-    try:
-      os.kill(p.pid, SIGTERM)
-      p.wait()
-    except OSError:
-      pass
-  _ssh_clients = []
+        return fun
 
-_git_version = None
 
-class _GitCall(object):
-  def version_tuple(self):
-    global _git_version
-    if _git_version is None:
-      _git_version = Wrapper().ParseGitVersion()
-      if _git_version is None:
-        print('fatal: unable to detect git version', file=sys.stderr)
-        sys.exit(1)
-    return _git_version
-
-  def __getattr__(self, name):
-    name = name.replace('_','-')
-    def fun(*cmdv):
-      command = [name]
-      command.extend(cmdv)
-      return GitCommand(None, command).Wait() == 0
-    return fun
 git = _GitCall()
 
 
 def RepoSourceVersion():
-  """Return the version of the repo.git tree."""
-  ver = getattr(RepoSourceVersion, 'version', None)
+    """Return the version of the repo.git tree."""
+    ver = getattr(RepoSourceVersion, "version", None)
 
-  # We avoid GitCommand so we don't run into circular deps -- GitCommand needs
-  # to initialize version info we provide.
-  if ver is None:
-    env = GitCommand._GetBasicEnv()
+    # We avoid GitCommand so we don't run into circular deps -- GitCommand needs
+    # to initialize version info we provide.
+    if ver is None:
+        env = GitCommand._GetBasicEnv()
 
-    proj = os.path.dirname(os.path.abspath(__file__))
-    env[GIT_DIR] = os.path.join(proj, '.git')
+        proj = os.path.dirname(os.path.abspath(__file__))
+        env[GIT_DIR] = os.path.join(proj, ".git")
+        result = subprocess.run(
+            [GIT, "describe", HEAD],
+            stdout=subprocess.PIPE,
+            stderr=subprocess.DEVNULL,
+            encoding="utf-8",
+            env=env,
+            check=False,
+        )
+        if result.returncode == 0:
+            ver = result.stdout.strip()
+            if ver.startswith("v"):
+                ver = ver[1:]
+        else:
+            ver = "unknown"
+        setattr(RepoSourceVersion, "version", ver)
 
-    p = subprocess.Popen([GIT, 'describe', HEAD], stdout=subprocess.PIPE,
-                         env=env)
-    if p.wait() == 0:
-      ver = p.stdout.read().strip().decode('utf-8')
-      if ver.startswith('v'):
-        ver = ver[1:]
-    else:
-      ver = 'unknown'
-    setattr(RepoSourceVersion, 'version', ver)
-
-  return ver
+    return ver
 
 
-class UserAgent(object):
-  """Mange User-Agent settings when talking to external services
+@functools.lru_cache(maxsize=None)
+def GetEventTargetPath():
+    """Get the 'trace2.eventtarget' path from git configuration.
 
-  We follow the style as documented here:
-  https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/User-Agent
-  """
+    Returns:
+        path: git config's 'trace2.eventtarget' path if it exists, or None
+    """
+    path = None
+    cmd = ["config", "--get", "trace2.eventtarget"]
+    # TODO(https://crbug.com/gerrit/13706): Use GitConfig when it supports
+    # system git config variables.
+    p = GitCommand(
+        None,
+        cmd,
+        capture_stdout=True,
+        capture_stderr=True,
+        bare=True,
+        add_event_log=False,
+    )
+    retval = p.Wait()
+    if retval == 0:
+        # Strip trailing carriage-return in path.
+        path = p.stdout.rstrip("\n")
+        if path == "":
+            return None
+    elif retval != 1:
+        # `git config --get` is documented to produce an exit status of `1`
+        # if the requested variable is not present in the configuration.
+        # Report any other return value as an error.
+        logger.error(
+            "repo: error: 'git config --get' call failed with return code: "
+            "%r, stderr: %r",
+            retval,
+            p.stderr,
+        )
+    return path
 
-  _os = None
-  _repo_ua = None
-  _git_ua = None
 
-  @property
-  def os(self):
-    """The operating system name."""
-    if self._os is None:
-      os_name = sys.platform
-      if os_name.lower().startswith('linux'):
-        os_name = 'Linux'
-      elif os_name == 'win32':
-        os_name = 'Win32'
-      elif os_name == 'cygwin':
-        os_name = 'Cygwin'
-      elif os_name == 'darwin':
-        os_name = 'Darwin'
-      self._os = os_name
+class UserAgent:
+    """Mange User-Agent settings when talking to external services
 
-    return self._os
+    We follow the style as documented here:
+    https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/User-Agent
+    """
 
-  @property
-  def repo(self):
-    """The UA when connecting directly from repo."""
-    if self._repo_ua is None:
-      py_version = sys.version_info
-      self._repo_ua = 'git-repo/%s (%s) git/%s Python/%d.%d.%d' % (
-          RepoSourceVersion(),
-          self.os,
-          git.version_tuple().full,
-          py_version.major, py_version.minor, py_version.micro)
+    _os = None
+    _repo_ua = None
+    _git_ua = None
 
-    return self._repo_ua
+    @property
+    def os(self):
+        """The operating system name."""
+        if self._os is None:
+            os_name = sys.platform
+            if os_name.lower().startswith("linux"):
+                os_name = "Linux"
+            elif os_name == "win32":
+                os_name = "Win32"
+            elif os_name == "cygwin":
+                os_name = "Cygwin"
+            elif os_name == "darwin":
+                os_name = "Darwin"
+            self._os = os_name
 
-  @property
-  def git(self):
-    """The UA when running git."""
-    if self._git_ua is None:
-      self._git_ua = 'git/%s (%s) git-repo/%s' % (
-          git.version_tuple().full,
-          self.os,
-          RepoSourceVersion())
+        return self._os
+
+    @property
+    def repo(self):
+        """The UA when connecting directly from repo."""
+        if self._repo_ua is None:
+            py_version = sys.version_info
+            self._repo_ua = "git-repo/%s (%s) git/%s Python/%d.%d.%d" % (
+                RepoSourceVersion(),
+                self.os,
+                git.version_tuple().full,
+                py_version.major,
+                py_version.minor,
+                py_version.micro,
+            )
+
+        return self._repo_ua
+
+    @property
+    def git(self):
+        """The UA when running git."""
+        if self._git_ua is None:
+            self._git_ua = (
+                f"git/{git.version_tuple().full} ({self.os}) "
+                f"git-repo/{RepoSourceVersion()}"
+            )
+        return self._git_ua
 
-    return self._git_ua
 
 user_agent = UserAgent()
 
-def git_require(min_version, fail=False, msg=''):
-  git_version = git.version_tuple()
-  if min_version <= git_version:
-    return True
-  if fail:
-    need = '.'.join(map(str, min_version))
-    if msg:
-      msg = ' for ' + msg
-    print('fatal: git %s or later required%s' % (need, msg), file=sys.stderr)
-    sys.exit(1)
-  return False
 
-def _setenv(env, name, value):
-  env[name] = value.encode()
+def git_require(min_version, fail=False, msg=""):
+    git_version = git.version_tuple()
+    if min_version <= git_version:
+        return True
+    if fail:
+        need = ".".join(map(str, min_version))
+        if msg:
+            msg = " for " + msg
+        error_msg = f"fatal: git {need} or later required{msg}"
+        logger.error(error_msg)
+        raise GitRequireError(error_msg)
+    return False
 
-class GitCommand(object):
-  def __init__(self,
-               project,
-               cmdv,
-               bare = False,
-               provide_stdin = False,
-               capture_stdout = False,
-               capture_stderr = False,
-               disable_editor = False,
-               ssh_proxy = False,
-               cwd = None,
-               gitdir = None):
-    env = self._GetBasicEnv()
 
-    # If we are not capturing std* then need to print it.
-    self.tee = {'stdout': not capture_stdout, 'stderr': not capture_stderr}
+def _build_env(
+    _kwargs_only=(),
+    bare: Optional[bool] = False,
+    disable_editor: Optional[bool] = False,
+    ssh_proxy: Optional[Any] = None,
+    gitdir: Optional[str] = None,
+    objdir: Optional[str] = None,
+):
+    """Constucts an env dict for command execution."""
+
+    assert _kwargs_only == (), "_build_env only accepts keyword arguments."
+
+    env = GitCommand._GetBasicEnv()
 
     if disable_editor:
-      _setenv(env, 'GIT_EDITOR', ':')
+        env["GIT_EDITOR"] = ":"
     if ssh_proxy:
-      _setenv(env, 'REPO_SSH_SOCK', ssh_sock())
-      _setenv(env, 'GIT_SSH', _ssh_proxy())
-      _setenv(env, 'GIT_SSH_VARIANT', 'ssh')
-    if 'http_proxy' in env and 'darwin' == sys.platform:
-      s = "'http.proxy=%s'" % (env['http_proxy'],)
-      p = env.get('GIT_CONFIG_PARAMETERS')
-      if p is not None:
-        s = p + ' ' + s
-      _setenv(env, 'GIT_CONFIG_PARAMETERS', s)
-    if 'GIT_ALLOW_PROTOCOL' not in env:
-      _setenv(env, 'GIT_ALLOW_PROTOCOL',
-              'file:git:http:https:ssh:persistent-http:persistent-https:sso:rpc')
-    _setenv(env, 'GIT_HTTP_USER_AGENT', user_agent.git)
+        env["REPO_SSH_SOCK"] = ssh_proxy.sock()
+        env["GIT_SSH"] = ssh_proxy.proxy
+        env["GIT_SSH_VARIANT"] = "ssh"
+    if "http_proxy" in env and "darwin" == sys.platform:
+        s = f"'http.proxy={env['http_proxy']}'"
+        p = env.get("GIT_CONFIG_PARAMETERS")
+        if p is not None:
+            s = p + " " + s
+        env["GIT_CONFIG_PARAMETERS"] = s
+    if "GIT_ALLOW_PROTOCOL" not in env:
+        env["GIT_ALLOW_PROTOCOL"] = (
+            "file:git:http:https:ssh:persistent-http:persistent-https:sso:rpc"
+        )
+    env["GIT_HTTP_USER_AGENT"] = user_agent.git
 
-    if project:
-      if not cwd:
-        cwd = project.worktree
-      if not gitdir:
-        gitdir = project.gitdir
+    if objdir:
+        # Set to the place we want to save the objects.
+        env["GIT_OBJECT_DIRECTORY"] = objdir
 
-    command = [GIT]
-    if bare:
-      if gitdir:
-        _setenv(env, GIT_DIR, gitdir)
-      cwd = None
-    command.append(cmdv[0])
-    # Need to use the --progress flag for fetch/clone so output will be
-    # displayed as by default git only does progress output if stderr is a TTY.
-    if sys.stderr.isatty() and cmdv[0] in ('fetch', 'clone'):
-      if '--progress' not in cmdv and '--quiet' not in cmdv:
-        command.append('--progress')
-    command.extend(cmdv[1:])
+        alt_objects = os.path.join(gitdir, "objects") if gitdir else None
+        if alt_objects and os.path.realpath(alt_objects) != os.path.realpath(
+            objdir
+        ):
+            # Allow git to search the original place in case of local or unique
+            # refs that git will attempt to resolve even if we aren't fetching
+            # them.
+            env["GIT_ALTERNATE_OBJECT_DIRECTORIES"] = alt_objects
+    if bare and gitdir is not None:
+        env[GIT_DIR] = gitdir
 
-    if provide_stdin:
-      stdin = subprocess.PIPE
-    else:
-      stdin = None
-
-    stdout = subprocess.PIPE
-    stderr = subprocess.PIPE
-
-    if IsTrace():
-      global LAST_CWD
-      global LAST_GITDIR
-
-      dbg = ''
-
-      if cwd and LAST_CWD != cwd:
-        if LAST_GITDIR or LAST_CWD:
-          dbg += '\n'
-        dbg += ': cd %s\n' % cwd
-        LAST_CWD = cwd
-
-      if GIT_DIR in env and LAST_GITDIR != env[GIT_DIR]:
-        if LAST_GITDIR or LAST_CWD:
-          dbg += '\n'
-        dbg += ': export GIT_DIR=%s\n' % env[GIT_DIR]
-        LAST_GITDIR = env[GIT_DIR]
-
-      dbg += ': '
-      dbg += ' '.join(command)
-      if stdin == subprocess.PIPE:
-        dbg += ' 0<|'
-      if stdout == subprocess.PIPE:
-        dbg += ' 1>|'
-      if stderr == subprocess.PIPE:
-        dbg += ' 2>|'
-      Trace('%s', dbg)
-
-    try:
-      p = subprocess.Popen(command,
-                           cwd = cwd,
-                           env = env,
-                           stdin = stdin,
-                           stdout = stdout,
-                           stderr = stderr)
-    except Exception as e:
-      raise GitError('%s: %s' % (command[1], e))
-
-    if ssh_proxy:
-      _add_ssh_client(p)
-
-    self.process = p
-    self.stdin = p.stdin
-
-  @staticmethod
-  def _GetBasicEnv():
-    """Return a basic env for running git under.
-
-    This is guaranteed to be side-effect free.
-    """
-    env = os.environ.copy()
-    for key in (REPO_TRACE,
-                GIT_DIR,
-                'GIT_ALTERNATE_OBJECT_DIRECTORIES',
-                'GIT_OBJECT_DIRECTORY',
-                'GIT_WORK_TREE',
-                'GIT_GRAFT_FILE',
-                'GIT_INDEX_FILE'):
-      env.pop(key, None)
     return env
 
-  def Wait(self):
-    try:
-      p = self.process
-      rc = self._CaptureOutput()
-    finally:
-      _remove_ssh_client(p)
-    return rc
 
-  def _CaptureOutput(self):
-    p = self.process
-    s_in = platform_utils.FileDescriptorStreams.create()
-    s_in.add(p.stdout, sys.stdout, 'stdout')
-    s_in.add(p.stderr, sys.stderr, 'stderr')
-    self.stdout = ''
-    self.stderr = ''
+class GitCommand:
+    """Wrapper around a single git invocation."""
 
-    while not s_in.is_done:
-      in_ready = s_in.select()
-      for s in in_ready:
-        buf = s.read()
-        if not buf:
-          s_in.remove(s)
-          continue
-        if not hasattr(buf, 'encode'):
-          buf = buf.decode()
-        if s.std_name == 'stdout':
-          self.stdout += buf
-        else:
-          self.stderr += buf
-        if self.tee[s.std_name]:
-          s.dest.write(buf)
-          s.dest.flush()
-    return p.wait()
+    def __init__(
+        self,
+        project,
+        cmdv,
+        bare=False,
+        input=None,
+        capture_stdout=False,
+        capture_stderr=False,
+        merge_output=False,
+        disable_editor=False,
+        ssh_proxy=None,
+        cwd=None,
+        gitdir=None,
+        objdir=None,
+        verify_command=False,
+        add_event_log=True,
+        log_as_error=True,
+    ):
+        if project:
+            if not cwd:
+                cwd = project.worktree
+            if not gitdir:
+                gitdir = project.gitdir
+
+        self.project = project
+        self.cmdv = cmdv
+        self.verify_command = verify_command
+        self.stdout, self.stderr = None, None
+
+        # Git on Windows wants its paths only using / for reliability.
+        if platform_utils.isWindows():
+            if objdir:
+                objdir = objdir.replace("\\", "/")
+            if gitdir:
+                gitdir = gitdir.replace("\\", "/")
+
+        env = _build_env(
+            disable_editor=disable_editor,
+            ssh_proxy=ssh_proxy,
+            objdir=objdir,
+            gitdir=gitdir,
+            bare=bare,
+        )
+
+        command = [GIT]
+        if bare:
+            cwd = None
+        command_name = cmdv[0]
+        command.append(command_name)
+
+        if command_name in ("fetch", "clone"):
+            env["GIT_TERMINAL_PROMPT"] = "0"
+            # Need to use the --progress flag for fetch/clone so output will be
+            # displayed as by default git only does progress output if stderr is
+            # a TTY.
+            if sys.stderr.isatty():
+                if "--progress" not in cmdv and "--quiet" not in cmdv:
+                    command.append("--progress")
+        command.extend(cmdv[1:])
+
+        event_log = (
+            BaseEventLog(env=env, add_init_count=True)
+            if add_event_log
+            else None
+        )
+
+        try:
+            self._RunCommand(
+                command,
+                env,
+                capture_stdout=capture_stdout,
+                capture_stderr=capture_stderr,
+                merge_output=merge_output,
+                ssh_proxy=ssh_proxy,
+                cwd=cwd,
+                input=input,
+            )
+            self.VerifyCommand()
+        except GitCommandError as e:
+            if event_log is not None:
+                error_info = json.dumps(
+                    {
+                        "ErrorType": type(e).__name__,
+                        "Project": e.project,
+                        "CommandName": command_name,
+                        "Message": str(e),
+                        "ReturnCode": (
+                            str(e.git_rc) if e.git_rc is not None else None
+                        ),
+                        "IsError": log_as_error,
+                    }
+                )
+                event_log.ErrorEvent(
+                    f"{ERROR_EVENT_LOGGING_PREFIX}:{error_info}"
+                )
+                event_log.Write(GetEventTargetPath())
+            if isinstance(e, GitPopenCommandError):
+                raise
+
+    def _RunCommand(
+        self,
+        command,
+        env,
+        capture_stdout=False,
+        capture_stderr=False,
+        merge_output=False,
+        ssh_proxy=None,
+        cwd=None,
+        input=None,
+    ):
+        # Set subprocess.PIPE for streams that need to be captured.
+        stdin = subprocess.PIPE if input else None
+        stdout = subprocess.PIPE if capture_stdout else None
+        stderr = (
+            subprocess.STDOUT
+            if merge_output
+            else (subprocess.PIPE if capture_stderr else None)
+        )
+
+        # tee_stderr acts like a tee command for stderr, in that, it captures
+        # stderr from the subprocess and streams it back to sys.stderr, while
+        # keeping a copy in-memory.
+        # This allows us to store stderr logs from the subprocess into
+        # GitCommandError.
+        # Certain git operations, such as `git push`, writes diagnostic logs,
+        # such as, progress bar for pushing, into stderr. To ensure we don't
+        # break git's UX, we need to write to sys.stderr as we read from the
+        # subprocess. Setting encoding or errors makes subprocess return
+        # io.TextIOWrapper, which is line buffered. To avoid line-buffering
+        # while tee-ing stderr, we unset these kwargs. See GitCommand._Tee
+        # for tee-ing between the streams.
+        # We tee stderr iff the caller doesn't want to capture any stream to
+        # not disrupt the existing flow.
+        # See go/tee-repo-stderr for more context.
+        tee_stderr = False
+        kwargs = {"encoding": "utf-8", "errors": "backslashreplace"}
+        if not (stdin or stdout or stderr):
+            tee_stderr = True
+            # stderr will be written back to sys.stderr even though it is
+            # piped here.
+            stderr = subprocess.PIPE
+            kwargs = {}
+
+        dbg = ""
+        if IsTrace():
+            global LAST_CWD
+            global LAST_GITDIR
+
+            if cwd and LAST_CWD != cwd:
+                if LAST_GITDIR or LAST_CWD:
+                    dbg += "\n"
+                dbg += ": cd %s\n" % cwd
+                LAST_CWD = cwd
+
+            if GIT_DIR in env and LAST_GITDIR != env[GIT_DIR]:
+                if LAST_GITDIR or LAST_CWD:
+                    dbg += "\n"
+                dbg += ": export GIT_DIR=%s\n" % env[GIT_DIR]
+                LAST_GITDIR = env[GIT_DIR]
+
+            if "GIT_OBJECT_DIRECTORY" in env:
+                dbg += (
+                    ": export GIT_OBJECT_DIRECTORY=%s\n"
+                    % env["GIT_OBJECT_DIRECTORY"]
+                )
+            if "GIT_ALTERNATE_OBJECT_DIRECTORIES" in env:
+                dbg += ": export GIT_ALTERNATE_OBJECT_DIRECTORIES=%s\n" % (
+                    env["GIT_ALTERNATE_OBJECT_DIRECTORIES"]
+                )
+
+            dbg += ": "
+            dbg += " ".join(command)
+            if stdin == subprocess.PIPE:
+                dbg += " 0<|"
+            if stdout == subprocess.PIPE:
+                dbg += " 1>|"
+            if stderr == subprocess.PIPE:
+                dbg += " 2>|"
+            elif stderr == subprocess.STDOUT:
+                dbg += " 2>&1"
+
+        with Trace(
+            "git command %s %s with debug: %s", LAST_GITDIR, command, dbg
+        ):
+            try:
+                p = subprocess.Popen(
+                    command,
+                    cwd=cwd,
+                    env=env,
+                    stdin=stdin,
+                    stdout=stdout,
+                    stderr=stderr,
+                    **kwargs,
+                )
+            except Exception as e:
+                raise GitPopenCommandError(
+                    message=f"{command[1]}: {e}",
+                    project=self.project.name if self.project else None,
+                    command_args=self.cmdv,
+                )
+
+            if ssh_proxy:
+                ssh_proxy.add_client(p)
+
+            self.process = p
+
+            try:
+                if tee_stderr:
+                    # tee_stderr streams stderr to sys.stderr while capturing
+                    # a copy within self.stderr. tee_stderr is only enabled
+                    # when the caller wants to pipe no stream.
+                    self.stderr = self._Tee(p.stderr, sys.stderr)
+                else:
+                    self.stdout, self.stderr = p.communicate(input=input)
+            finally:
+                if ssh_proxy:
+                    ssh_proxy.remove_client(p)
+            self.rc = p.wait()
+
+    @staticmethod
+    def _Tee(in_stream, out_stream):
+        """Writes text from in_stream to out_stream while recording in buffer.
+
+        Args:
+            in_stream: I/O stream to be read from.
+            out_stream: I/O stream to write to.
+
+        Returns:
+            A str containing everything read from the in_stream.
+        """
+        buffer = ""
+        read_size = 1024 if sys.version_info < (3, 7) else -1
+        chunk = in_stream.read1(read_size)
+        while chunk:
+            # Convert to str.
+            if not hasattr(chunk, "encode"):
+                chunk = chunk.decode("utf-8", "backslashreplace")
+
+            buffer += chunk
+            out_stream.write(chunk)
+            out_stream.flush()
+
+            chunk = in_stream.read1(read_size)
+
+        return buffer
+
+    @staticmethod
+    def _GetBasicEnv():
+        """Return a basic env for running git under.
+
+        This is guaranteed to be side-effect free.
+        """
+        env = os.environ.copy()
+        for key in (
+            REPO_TRACE,
+            GIT_DIR,
+            "GIT_ALTERNATE_OBJECT_DIRECTORIES",
+            "GIT_OBJECT_DIRECTORY",
+            "GIT_WORK_TREE",
+            "GIT_GRAFT_FILE",
+            "GIT_INDEX_FILE",
+        ):
+            env.pop(key, None)
+        return env
+
+    def VerifyCommand(self):
+        if self.rc == 0:
+            return None
+        stdout = (
+            "\n".join(self.stdout.split("\n")[:GIT_ERROR_STDOUT_LINES])
+            if self.stdout
+            else None
+        )
+        stderr = (
+            "\n".join(self.stderr.split("\n")[:GIT_ERROR_STDERR_LINES])
+            if self.stderr
+            else None
+        )
+        project = self.project.name if self.project else None
+        raise GitCommandError(
+            project=project,
+            command_args=self.cmdv,
+            git_rc=self.rc,
+            git_stdout=stdout,
+            git_stderr=stderr,
+        )
+
+    def Wait(self):
+        if self.verify_command:
+            self.VerifyCommand()
+        return self.rc
+
+
+class GitRequireError(RepoExitError):
+    """Error raised when git version is unavailable or invalid."""
+
+    def __init__(self, message, exit_code: int = INVALID_GIT_EXIT_CODE):
+        super().__init__(message, exit_code=exit_code)
+
+
+class GitCommandError(GitError):
+    """
+    Error raised from a failed git command.
+    Note that GitError can refer to any Git related error (e.g. branch not
+    specified for project.py 'UploadForReview'), while GitCommandError is
+    raised exclusively from non-zero exit codes returned from git commands.
+    """
+
+    # Tuples with error formats and suggestions for those errors.
+    _ERROR_TO_SUGGESTION = [
+        (
+            re.compile("couldn't find remote ref .*"),
+            "Check if the provided ref exists in the remote.",
+        ),
+        (
+            re.compile("unable to access '.*': .*"),
+            (
+                "Please make sure you have the correct access rights and the "
+                "repository exists."
+            ),
+        ),
+        (
+            re.compile("'.*' does not appear to be a git repository"),
+            "Are you running this repo command outside of a repo workspace?",
+        ),
+        (
+            re.compile("not a git repository"),
+            "Are you running this repo command outside of a repo workspace?",
+        ),
+    ]
+
+    def __init__(
+        self,
+        message: str = DEFAULT_GIT_FAIL_MESSAGE,
+        git_rc: int = None,
+        git_stdout: str = None,
+        git_stderr: str = None,
+        **kwargs,
+    ):
+        super().__init__(
+            message,
+            **kwargs,
+        )
+        self.git_rc = git_rc
+        self.git_stdout = git_stdout
+        self.git_stderr = git_stderr
+
+    @property
+    @functools.lru_cache(maxsize=None)
+    def suggestion(self):
+        """Returns helpful next steps for the given stderr."""
+        if not self.git_stderr:
+            return self.git_stderr
+
+        for err, suggestion in self._ERROR_TO_SUGGESTION:
+            if err.search(self.git_stderr):
+                return suggestion
+
+        return None
+
+    def __str__(self):
+        args = "[]" if not self.command_args else " ".join(self.command_args)
+        error_type = type(self).__name__
+        string = f"{error_type}: '{args}' on {self.project} failed"
+
+        if self.message != DEFAULT_GIT_FAIL_MESSAGE:
+            string += f": {self.message}"
+
+        if self.git_stdout:
+            string += f"\nstdout: {self.git_stdout}"
+
+        if self.git_stderr:
+            string += f"\nstderr: {self.git_stderr}"
+
+        if self.suggestion:
+            string += f"\nsuggestion: {self.suggestion}"
+
+        return string
+
+
+class GitPopenCommandError(GitError):
+    """
+    Error raised when subprocess.Popen fails for a GitCommand
+    """

git_refs.py

@@ -1,5 +1,3 @@
-# -*- coding:utf-8 -*-
-#
 # Copyright (C) 2009 The Android Open Source Project
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -15,148 +13,153 @@
 # limitations under the License.
 
 import os
-from repo_trace import Trace
+
 import platform_utils
-
-HEAD      = 'HEAD'
-R_CHANGES = 'refs/changes/'
-R_HEADS   = 'refs/heads/'
-R_TAGS    = 'refs/tags/'
-R_PUB     = 'refs/published/'
-R_M       = 'refs/remotes/m/'
+from repo_trace import Trace
 
 
-class GitRefs(object):
-  def __init__(self, gitdir):
-    self._gitdir = gitdir
-    self._phyref = None
-    self._symref = None
-    self._mtime = {}
+HEAD = "HEAD"
+R_CHANGES = "refs/changes/"
+R_HEADS = "refs/heads/"
+R_TAGS = "refs/tags/"
+R_PUB = "refs/published/"
+R_WORKTREE = "refs/worktree/"
+R_WORKTREE_M = R_WORKTREE + "m/"
+R_M = "refs/remotes/m/"
 
-  @property
-  def all(self):
-    self._EnsureLoaded()
-    return self._phyref
 
-  def get(self, name):
-    try:
-      return self.all[name]
-    except KeyError:
-      return ''
+class GitRefs:
+    def __init__(self, gitdir):
+        self._gitdir = gitdir
+        self._phyref = None
+        self._symref = None
+        self._mtime = {}
 
-  def deleted(self, name):
-    if self._phyref is not None:
-      if name in self._phyref:
-        del self._phyref[name]
+    @property
+    def all(self):
+        self._EnsureLoaded()
+        return self._phyref
 
-      if name in self._symref:
-        del self._symref[name]
+    def get(self, name):
+        try:
+            return self.all[name]
+        except KeyError:
+            return ""
 
-      if name in self._mtime:
-        del self._mtime[name]
+    def deleted(self, name):
+        if self._phyref is not None:
+            if name in self._phyref:
+                del self._phyref[name]
 
-  def symref(self, name):
-    try:
-      self._EnsureLoaded()
-      return self._symref[name]
-    except KeyError:
-      return ''
+            if name in self._symref:
+                del self._symref[name]
 
-  def _EnsureLoaded(self):
-    if self._phyref is None or self._NeedUpdate():
-      self._LoadAll()
+            if name in self._mtime:
+                del self._mtime[name]
 
-  def _NeedUpdate(self):
-    Trace(': scan refs %s', self._gitdir)
+    def symref(self, name):
+        try:
+            self._EnsureLoaded()
+            return self._symref[name]
+        except KeyError:
+            return ""
 
-    for name, mtime in self._mtime.items():
-      try:
-        if mtime != os.path.getmtime(os.path.join(self._gitdir, name)):
-          return True
-      except OSError:
-        return True
-    return False
+    def _EnsureLoaded(self):
+        if self._phyref is None or self._NeedUpdate():
+            self._LoadAll()
 
-  def _LoadAll(self):
-    Trace(': load refs %s', self._gitdir)
+    def _NeedUpdate(self):
+        with Trace(": scan refs %s", self._gitdir):
+            for name, mtime in self._mtime.items():
+                try:
+                    if mtime != os.path.getmtime(
+                        os.path.join(self._gitdir, name)
+                    ):
+                        return True
+                except OSError:
+                    return True
+            return False
 
-    self._phyref = {}
-    self._symref = {}
-    self._mtime = {}
+    def _LoadAll(self):
+        with Trace(": load refs %s", self._gitdir):
+            self._phyref = {}
+            self._symref = {}
+            self._mtime = {}
 
-    self._ReadPackedRefs()
-    self._ReadLoose('refs/')
-    self._ReadLoose1(os.path.join(self._gitdir, HEAD), HEAD)
+            self._ReadPackedRefs()
+            self._ReadLoose("refs/")
+            self._ReadLoose1(os.path.join(self._gitdir, HEAD), HEAD)
 
-    scan = self._symref
-    attempts = 0
-    while scan and attempts < 5:
-      scan_next = {}
-      for name, dest in scan.items():
-        if dest in self._phyref:
-          self._phyref[name] = self._phyref[dest]
+            scan = self._symref
+            attempts = 0
+            while scan and attempts < 5:
+                scan_next = {}
+                for name, dest in scan.items():
+                    if dest in self._phyref:
+                        self._phyref[name] = self._phyref[dest]
+                    else:
+                        scan_next[name] = dest
+                scan = scan_next
+                attempts += 1
+
+    def _ReadPackedRefs(self):
+        path = os.path.join(self._gitdir, "packed-refs")
+        try:
+            fd = open(path)
+            mtime = os.path.getmtime(path)
+        except OSError:
+            return
+        try:
+            for line in fd:
+                line = str(line)
+                if line[0] == "#":
+                    continue
+                if line[0] == "^":
+                    continue
+
+                line = line[:-1]
+                p = line.split(" ")
+                ref_id = p[0]
+                name = p[1]
+
+                self._phyref[name] = ref_id
+        finally:
+            fd.close()
+        self._mtime["packed-refs"] = mtime
+
+    def _ReadLoose(self, prefix):
+        base = os.path.join(self._gitdir, prefix)
+        for name in platform_utils.listdir(base):
+            p = os.path.join(base, name)
+            # We don't implement the full ref validation algorithm, just the
+            # simple rules that would show up in local filesystems.
+            # https://git-scm.com/docs/git-check-ref-format
+            if name.startswith(".") or name.endswith(".lock"):
+                pass
+            elif platform_utils.isdir(p):
+                self._mtime[prefix] = os.path.getmtime(base)
+                self._ReadLoose(prefix + name + "/")
+            else:
+                self._ReadLoose1(p, prefix + name)
+
+    def _ReadLoose1(self, path, name):
+        try:
+            with open(path) as fd:
+                mtime = os.path.getmtime(path)
+                ref_id = fd.readline()
+        except (OSError, UnicodeError):
+            return
+
+        try:
+            ref_id = ref_id.decode()
+        except AttributeError:
+            pass
+        if not ref_id:
+            return
+        ref_id = ref_id[:-1]
+
+        if ref_id.startswith("ref: "):
+            self._symref[name] = ref_id[5:]
         else:
-          scan_next[name] = dest
-      scan = scan_next
-      attempts += 1
-
-  def _ReadPackedRefs(self):
-    path = os.path.join(self._gitdir, 'packed-refs')
-    try:
-      fd = open(path, 'r')
-      mtime = os.path.getmtime(path)
-    except IOError:
-      return
-    except OSError:
-      return
-    try:
-      for line in fd:
-        line = str(line)
-        if line[0] == '#':
-          continue
-        if line[0] == '^':
-          continue
-
-        line = line[:-1]
-        p = line.split(' ')
-        ref_id = p[0]
-        name = p[1]
-
-        self._phyref[name] = ref_id
-    finally:
-      fd.close()
-    self._mtime['packed-refs'] = mtime
-
-  def _ReadLoose(self, prefix):
-    base = os.path.join(self._gitdir, prefix)
-    for name in platform_utils.listdir(base):
-      p = os.path.join(base, name)
-      if platform_utils.isdir(p):
-        self._mtime[prefix] = os.path.getmtime(base)
-        self._ReadLoose(prefix + name + '/')
-      elif name.endswith('.lock'):
-        pass
-      else:
-        self._ReadLoose1(p, prefix + name)
-
-  def _ReadLoose1(self, path, name):
-    try:
-      with open(path) as fd:
-        mtime = os.path.getmtime(path)
-        ref_id = fd.readline()
-    except (IOError, OSError):
-      return
-
-    try:
-      ref_id = ref_id.decode()
-    except AttributeError:
-      pass
-    if not ref_id:
-      return
-    ref_id = ref_id[:-1]
-
-    if ref_id.startswith('ref: '):
-      self._symref[name] = ref_id[5:]
-    else:
-      self._phyref[name] = ref_id
-    self._mtime[name] = mtime
+            self._phyref[name] = ref_id
+        self._mtime[name] = mtime

git_superproject.py

@@ -0,0 +1,594 @@
+# Copyright (C) 2021 The Android Open Source Project
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Provide functionality to get projects and their commit ids from Superproject.
+
+For more information on superproject, check out:
+https://en.wikibooks.org/wiki/Git/Submodules_and_Superprojects
+
+Examples:
+  superproject = Superproject(manifest, name, remote, revision)
+  UpdateProjectsResult = superproject.UpdateProjectsRevisionId(projects)
+"""
+
+import functools
+import hashlib
+import os
+import sys
+import time
+from typing import NamedTuple
+import urllib.parse
+
+from git_command import git_require
+from git_command import GitCommand
+from git_config import RepoConfig
+from git_refs import GitRefs
+
+
+_SUPERPROJECT_GIT_NAME = "superproject.git"
+_SUPERPROJECT_MANIFEST_NAME = "superproject_override.xml"
+
+
+class SyncResult(NamedTuple):
+    """Return the status of sync and whether caller should exit."""
+
+    # Whether the superproject sync was successful.
+    success: bool
+    # Whether the caller should exit.
+    fatal: bool
+
+
+class CommitIdsResult(NamedTuple):
+    """Return the commit ids and whether caller should exit."""
+
+    # A dictionary with the projects/commit ids on success, otherwise None.
+    commit_ids: dict
+    # Whether the caller should exit.
+    fatal: bool
+
+
+class UpdateProjectsResult(NamedTuple):
+    """Return the overriding manifest file and whether caller should exit."""
+
+    # Path name of the overriding manifest file if successful, otherwise None.
+    manifest_path: str
+    # Whether the caller should exit.
+    fatal: bool
+
+
+class Superproject:
+    """Get commit ids from superproject.
+
+    Initializes a bare local copy of a superproject for the manifest. This
+    allows lookup of commit ids for all projects. It contains
+    _project_commit_ids which is a dictionary with project/commit id entries.
+    """
+
+    def __init__(
+        self,
+        manifest,
+        name,
+        remote,
+        revision,
+        superproject_dir="exp-superproject",
+    ):
+        """Initializes superproject.
+
+        Args:
+            manifest: A Manifest object that is to be written to a file.
+            name: The unique name of the superproject
+            remote: The RemoteSpec for the remote.
+            revision: The name of the git branch to track.
+            superproject_dir: Relative path under |manifest.subdir| to checkout
+                superproject.
+        """
+        self._project_commit_ids = None
+        self._manifest = manifest
+        self.name = name
+        self.remote = remote
+        self.revision = self._branch = revision
+        self._repodir = manifest.repodir
+        self._superproject_dir = superproject_dir
+        self._superproject_path = manifest.SubmanifestInfoDir(
+            manifest.path_prefix, superproject_dir
+        )
+        self._manifest_path = os.path.join(
+            self._superproject_path, _SUPERPROJECT_MANIFEST_NAME
+        )
+        git_name = hashlib.md5(remote.name.encode("utf8")).hexdigest() + "-"
+        self._remote_url = remote.url
+        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 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
+        self._quiet = False
+        self._print_messages = False
+
+    def SetQuiet(self, value):
+        """Set the _quiet attribute."""
+        self._quiet = value
+
+    def SetPrintMessages(self, value):
+        """Set the _print_messages attribute."""
+        self._print_messages = value
+
+    @property
+    def commit_id(self):
+        """Returns the commit ID of the superproject checkout."""
+        cmd = ["rev-parse", self.revision]
+        p = GitCommand(
+            None,  # project
+            cmd,
+            gitdir=self._work_git,
+            bare=True,
+            capture_stdout=True,
+            capture_stderr=True,
+        )
+        retval = p.Wait()
+        if retval != 0:
+            self._LogWarning(
+                "git rev-parse call failed, command: git {}, "
+                "return code: {}, stderr: {}",
+                cmd,
+                retval,
+                p.stderr,
+            )
+            return None
+        return p.stdout
+
+    @property
+    def project_commit_ids(self):
+        """Returns a dictionary of projects and their commit ids."""
+        return self._project_commit_ids
+
+    @property
+    def manifest_path(self):
+        """Returns the manifest path if the path exists or None."""
+        return (
+            self._manifest_path if os.path.exists(self._manifest_path) else None
+        )
+
+    @property
+    def repo_id(self):
+        """Returns the repo ID for the superproject.
+
+        For example, if the superproject points to:
+            https://android-review.googlesource.com/platform/superproject/
+        Then the repo_id would be:
+            android/platform/superproject
+        """
+        review_url = self.remote.review
+        if review_url:
+            parsed_url = urllib.parse.urlparse(review_url)
+            netloc = parsed_url.netloc
+            if netloc:
+                parts = netloc.split("-review", 1)
+                host = parts[0]
+                rev = GitRefs(self._work_git).get("HEAD")
+                return f"{host}/{self.name}@{rev}"
+        return None
+
+    def _LogMessage(self, fmt, *inputs):
+        """Logs message to stderr and _git_event_log."""
+        message = f"{self._LogMessagePrefix()} {fmt.format(*inputs)}"
+        if self._print_messages:
+            print(message, file=sys.stderr)
+        self._git_event_log.ErrorEvent(message, fmt)
+
+    def _LogMessagePrefix(self):
+        """Returns the prefix string to be logged in each log message"""
+        return (
+            f"repo superproject branch: {self._branch} url: {self._remote_url}"
+        )
+
+    def _LogError(self, fmt, *inputs):
+        """Logs error message to stderr and _git_event_log."""
+        self._LogMessage(f"error: {fmt}", *inputs)
+
+    def _LogWarning(self, fmt, *inputs):
+        """Logs warning message to stderr and _git_event_log."""
+        self._LogMessage(f"warning: {fmt}", *inputs)
+
+    def _Init(self):
+        """Sets up a local Git repository to get a copy of a superproject.
+
+        Returns:
+            True if initialization is successful, or False.
+        """
+        if not os.path.exists(self._superproject_path):
+            os.mkdir(self._superproject_path)
+        if not self._quiet and not os.path.exists(self._work_git):
+            print(
+                "%s: Performing initial setup for superproject; this might "
+                "take several minutes." % self._work_git
+            )
+        cmd = ["init", "--bare", self._work_git_name]
+        p = GitCommand(
+            None,
+            cmd,
+            cwd=self._superproject_path,
+            capture_stdout=True,
+            capture_stderr=True,
+        )
+        retval = p.Wait()
+        if retval:
+            self._LogWarning(
+                "git init call failed, command: git {}, "
+                "return code: {}, stderr: {}",
+                cmd,
+                retval,
+                p.stderr,
+            )
+            return False
+        return True
+
+    def _Fetch(self):
+        """Fetches a superproject for the manifest based on |_remote_url|.
+
+        This runs git fetch which stores a local copy the superproject.
+
+        Returns:
+            True if fetch is successful, or False.
+        """
+        if not os.path.exists(self._work_git):
+            self._LogWarning("git fetch missing directory: {}", self._work_git)
+            return False
+        if not git_require((2, 28, 0)):
+            self._LogWarning(
+                "superproject requires a git version 2.28 or later"
+            )
+            return False
+        cmd = [
+            "fetch",
+            self._remote_url,
+            "--depth",
+            "1",
+            "--force",
+            "--no-tags",
+            "--filter",
+            "blob:none",
+        ]
+
+        # Check if there is a local ref that we can pass to --negotiation-tip.
+        # If this is the first fetch, it does not exist yet.
+        # We use --negotiation-tip to speed up the fetch. Superproject branches
+        # do not share commits. So this lets git know it only needs to send
+        # commits reachable from the specified local refs.
+        rev_commit = GitRefs(self._work_git).get(f"refs/heads/{self.revision}")
+        if rev_commit:
+            cmd.extend(["--negotiation-tip", rev_commit])
+
+        if self._branch:
+            cmd += [self._branch + ":" + self._branch]
+        p = GitCommand(
+            None,
+            cmd,
+            gitdir=self._work_git,
+            bare=True,
+            capture_stdout=True,
+            capture_stderr=True,
+        )
+        retval = p.Wait()
+        if retval:
+            self._LogWarning(
+                "git fetch call failed, command: git {}, "
+                "return code: {}, stderr: {}",
+                cmd,
+                retval,
+                p.stderr,
+            )
+            return False
+        return True
+
+    def _LsTree(self):
+        """Gets the commit ids for all projects.
+
+        Works only in git repositories.
+
+        Returns:
+            data: data returned from 'git ls-tree ...'. None on error.
+        """
+        if not os.path.exists(self._work_git):
+            self._LogWarning(
+                "git ls-tree missing directory: {}", self._work_git
+            )
+            return None
+        data = None
+        branch = "HEAD" if not self._branch else self._branch
+        cmd = ["ls-tree", "-z", "-r", branch]
+
+        p = GitCommand(
+            None,
+            cmd,
+            gitdir=self._work_git,
+            bare=True,
+            capture_stdout=True,
+            capture_stderr=True,
+        )
+        retval = p.Wait()
+        if retval == 0:
+            data = p.stdout
+        else:
+            self._LogWarning(
+                "git ls-tree call failed, command: git {}, "
+                "return code: {}, stderr: {}",
+                cmd,
+                retval,
+                p.stderr,
+            )
+            return None
+        return data
+
+    def Sync(self, git_event_log):
+        """Gets a local copy of a superproject for the manifest.
+
+        Args:
+            git_event_log: an EventLog, for git tracing.
+
+        Returns:
+            SyncResult
+        """
+        self._git_event_log = git_event_log
+        if not self._manifest.superproject:
+            self._LogWarning(
+                "superproject tag is not defined in manifest: {}",
+                self._manifest.manifestFile,
+            )
+            return SyncResult(False, False)
+
+        should_exit = True
+        if not self._remote_url:
+            self._LogWarning(
+                "superproject URL is not defined in manifest: {}",
+                self._manifest.manifestFile,
+            )
+            return SyncResult(False, should_exit)
+
+        if not self._Init():
+            return SyncResult(False, should_exit)
+        if not self._Fetch():
+            return SyncResult(False, should_exit)
+        if not self._quiet:
+            print(
+                "%s: Initial setup for superproject completed." % self._work_git
+            )
+        return SyncResult(True, False)
+
+    def _GetAllProjectsCommitIds(self):
+        """Get commit ids for all projects from superproject and save them.
+
+        Commit ids are saved in _project_commit_ids.
+
+        Returns:
+            CommitIdsResult
+        """
+        sync_result = self.Sync(self._git_event_log)
+        if not sync_result.success:
+            return CommitIdsResult(None, sync_result.fatal)
+
+        data = self._LsTree()
+        if not data:
+            self._LogWarning(
+                "git ls-tree failed to return data for manifest: {}",
+                self._manifest.manifestFile,
+            )
+            return CommitIdsResult(None, True)
+
+        # Parse lines like the following to select lines starting with '160000'
+        # and build a dictionary with project path (last element) and its commit
+        # id (3rd element).
+        #
+        # 160000 commit 2c2724cb36cd5a9cec6c852c681efc3b7c6b86ea\tart\x00
+        # 120000 blob acc2cbdf438f9d2141f0ae424cec1d8fc4b5d97f\tbootstrap.bash\x00  # noqa: E501
+        commit_ids = {}
+        for line in data.split("\x00"):
+            ls_data = line.split(None, 3)
+            if not ls_data:
+                break
+            if ls_data[0] == "160000":
+                commit_ids[ls_data[3]] = ls_data[2]
+
+        self._project_commit_ids = commit_ids
+        return CommitIdsResult(commit_ids, False)
+
+    def _WriteManifestFile(self):
+        """Writes manifest to a file.
+
+        Returns:
+            manifest_path: Path name of the file into which manifest is written
+                instead of None.
+        """
+        if not os.path.exists(self._superproject_path):
+            self._LogWarning(
+                "missing superproject directory: {}", self._superproject_path
+            )
+            return None
+        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:
+                fp.write(manifest_str)
+        except OSError as e:
+            self._LogError("cannot write manifest to : {} {}", manifest_path, e)
+            return None
+        return manifest_path
+
+    def _SkipUpdatingProjectRevisionId(self, project):
+        """Checks if a project's revision id needs to be updated or not.
+
+        Revision id for projects from local manifest will not be updated.
+
+        Args:
+            project: project whose revision id is being updated.
+
+        Returns:
+            True if a project's revision id should not be updated, or False,
+        """
+        path = project.relpath
+        if not path:
+            return True
+        # Skip the project with revisionId.
+        if project.revisionId:
+            return True
+        # Skip the project if it comes from the local manifest.
+        return project.manifest.IsFromLocalManifest(project)
+
+    def UpdateProjectsRevisionId(self, projects, git_event_log):
+        """Update revisionId of every project in projects with the commit id.
+
+        Args:
+            projects: a list of projects whose revisionId needs to be updated.
+            git_event_log: an EventLog, for git tracing.
+
+        Returns:
+            UpdateProjectsResult
+        """
+        self._git_event_log = git_event_log
+        commit_ids_result = self._GetAllProjectsCommitIds()
+        commit_ids = commit_ids_result.commit_ids
+        if not commit_ids:
+            return UpdateProjectsResult(None, commit_ids_result.fatal)
+
+        projects_missing_commit_ids = []
+        for project in projects:
+            if self._SkipUpdatingProjectRevisionId(project):
+                continue
+            path = project.relpath
+            commit_id = commit_ids.get(path)
+            if not commit_id:
+                projects_missing_commit_ids.append(path)
+
+        # If superproject doesn't have a commit id for a project, then report an
+        # error event and continue as if do not use superproject is specified.
+        if projects_missing_commit_ids:
+            self._LogWarning(
+                "please file a bug using {} to report missing "
+                "commit_ids for: {}",
+                self._manifest.contactinfo.bugurl,
+                projects_missing_commit_ids,
+            )
+            return UpdateProjectsResult(None, False)
+
+        for project in projects:
+            if not self._SkipUpdatingProjectRevisionId(project):
+                project.SetRevisionId(commit_ids.get(project.relpath))
+
+        manifest_path = self._WriteManifestFile()
+        return UpdateProjectsResult(manifest_path, False)
+
+
+@functools.lru_cache(maxsize=None)
+def _UseSuperprojectFromConfiguration():
+    """Returns the user choice of whether to use superproject."""
+    user_cfg = RepoConfig.ForUser()
+    time_now = int(time.time())
+
+    user_value = user_cfg.GetBoolean("repo.superprojectChoice")
+    if user_value is not None:
+        user_expiration = user_cfg.GetInt("repo.superprojectChoiceExpire")
+        if (
+            user_expiration is None
+            or user_expiration <= 0
+            or user_expiration >= time_now
+        ):
+            # TODO(b/190688390) - Remove prompt when we are comfortable with the
+            # new default value.
+            if user_value:
+                print(
+                    (
+                        "You are currently enrolled in Git submodules "
+                        "experiment (go/android-submodules-quickstart).  Use "
+                        "--no-use-superproject to override.\n"
+                    ),
+                    file=sys.stderr,
+                )
+            else:
+                print(
+                    (
+                        "You are not currently enrolled in Git submodules "
+                        "experiment (go/android-submodules-quickstart).  Use "
+                        "--use-superproject to override.\n"
+                    ),
+                    file=sys.stderr,
+                )
+            return user_value
+
+    # We don't have an unexpired choice, ask for one.
+    system_cfg = RepoConfig.ForSystem()
+    system_value = system_cfg.GetBoolean("repo.superprojectChoice")
+    if system_value:
+        # The system configuration is proposing that we should enable the
+        # use of superproject. Treat the user as enrolled for two weeks.
+        #
+        # TODO(b/190688390) - Remove prompt when we are comfortable with the new
+        # default value.
+        userchoice = True
+        time_choiceexpire = time_now + (86400 * 14)
+        user_cfg.SetString(
+            "repo.superprojectChoiceExpire", str(time_choiceexpire)
+        )
+        user_cfg.SetBoolean("repo.superprojectChoice", userchoice)
+        print(
+            "You are automatically enrolled in Git submodules experiment "
+            "(go/android-submodules-quickstart) for another two weeks.\n",
+            file=sys.stderr,
+        )
+        return True
+
+    # For all other cases, we would not use superproject by default.
+    return False
+
+
+def PrintMessages(use_superproject, manifest):
+    """Returns a boolean if error/warning messages are to be printed.
+
+    Args:
+        use_superproject: option value from optparse.
+        manifest: manifest to use.
+    """
+    return use_superproject is not None or bool(manifest.superproject)
+
+
+def UseSuperproject(use_superproject, manifest):
+    """Returns a boolean if use-superproject option is enabled.
+
+    Args:
+        use_superproject: option value from optparse.
+        manifest: manifest to use.
+
+    Returns:
+        Whether the superproject should be used.
+    """
+
+    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
+        if client_value is not None:
+            return client_value
+        elif manifest.superproject:
+            return _UseSuperprojectFromConfiguration()
+        else:
+            return False

git_trace2_event_log.py

@@ -0,0 +1,32 @@
+from git_command import GetEventTargetPath
+from git_command import RepoSourceVersion
+from git_trace2_event_log_base import BaseEventLog
+
+
+class EventLog(BaseEventLog):
+    """Event log that records events that occurred during a repo invocation.
+
+    Events are written to the log as a consecutive JSON entries, one per line.
+    Entries follow the git trace2 EVENT format.
+
+    Each entry contains the following common keys:
+    - event: The event name
+    - sid: session-id - Unique string to allow process instance to be
+          identified.
+    - thread: The thread name.
+    - time: is the UTC time of the event.
+
+    Valid 'event' names and event specific fields are documented here:
+    https://git-scm.com/docs/api-trace2#_event_format
+    """
+
+    def __init__(self, **kwargs):
+        super().__init__(repo_source_version=RepoSourceVersion(), **kwargs)
+
+    def Write(self, path=None, **kwargs):
+        if path is None:
+            path = self._GetEventTargetPath()
+        return super().Write(path=path, **kwargs)
+
+    def _GetEventTargetPath(self):
+        return GetEventTargetPath()

git_trace2_event_log_base.py

@@ -0,0 +1,356 @@
+# Copyright (C) 2020 The Android Open Source Project
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Provide event logging in the git trace2 EVENT format.
+
+The git trace2 EVENT format is defined at:
+https://www.kernel.org/pub/software/scm/git/docs/technical/api-trace2.html#_event_format
+https://git-scm.com/docs/api-trace2#_the_event_format_target
+
+  Usage:
+
+  git_trace_log = EventLog()
+  git_trace_log.StartEvent()
+  ...
+  git_trace_log.ExitEvent()
+  git_trace_log.Write()
+"""
+
+
+import datetime
+import errno
+import json
+import os
+import socket
+import sys
+import tempfile
+import threading
+
+
+# Timeout when sending events via socket (applies to connect, send)
+SOCK_TIMEOUT = 0.5  # in seconds
+# BaseEventLog __init__ Counter that is consistent within the same process
+p_init_count = 0
+
+
+class BaseEventLog:
+    """Event log that records events that occurred during a repo invocation.
+
+    Events are written to the log as a consecutive JSON entries, one per line.
+    Entries follow the git trace2 EVENT format.
+
+    Each entry contains the following common keys:
+    - event: The event name
+    - sid: session-id - Unique string to allow process instance to be
+          identified.
+    - thread: The thread name.
+    - time: is the UTC time of the event.
+
+    Valid 'event' names and event specific fields are documented here:
+    https://git-scm.com/docs/api-trace2#_event_format
+    """
+
+    def __init__(
+        self, env=None, repo_source_version=None, add_init_count=False
+    ):
+        """Initializes the event log."""
+        global p_init_count
+        p_init_count += 1
+        self._log = []
+        # Try to get session-id (sid) from environment (setup in repo launcher).
+        KEY = "GIT_TRACE2_PARENT_SID"
+        if env is None:
+            env = os.environ
+
+        self.start = datetime.datetime.now(datetime.timezone.utc)
+
+        # Save both our sid component and the complete sid.
+        # We use our sid component (self._sid) as the unique filename prefix and
+        # the full sid (self._full_sid) in the log itself.
+        self._sid = (
+            f"repo-{self.start.strftime('%Y%m%dT%H%M%SZ')}-P{os.getpid():08x}"
+        )
+
+        if add_init_count:
+            self._sid = f"{self._sid}-{p_init_count}"
+
+        parent_sid = env.get(KEY)
+        # Append our sid component to the parent sid (if it exists).
+        if parent_sid is not None:
+            self._full_sid = parent_sid + "/" + self._sid
+        else:
+            self._full_sid = self._sid
+
+        # Set/update the environment variable.
+        # Environment handling across systems is messy.
+        try:
+            env[KEY] = self._full_sid
+        except UnicodeEncodeError:
+            env[KEY] = self._full_sid.encode()
+
+        if repo_source_version is not None:
+            # Add a version event to front of the log.
+            self._AddVersionEvent(repo_source_version)
+
+    @property
+    def full_sid(self):
+        return self._full_sid
+
+    def _AddVersionEvent(self, repo_source_version):
+        """Adds a 'version' event at the beginning of current log."""
+        version_event = self._CreateEventDict("version")
+        version_event["evt"] = "2"
+        version_event["exe"] = repo_source_version
+        self._log.insert(0, version_event)
+
+    def _CreateEventDict(self, event_name):
+        """Returns a dictionary with common keys/values for git trace2 events.
+
+        Args:
+            event_name: The event name.
+
+        Returns:
+            Dictionary with the common event fields populated.
+        """
+        return {
+            "event": event_name,
+            "sid": self._full_sid,
+            "thread": threading.current_thread().name,
+            "time": datetime.datetime.now(datetime.timezone.utc).isoformat(),
+        }
+
+    def StartEvent(self, argv):
+        """Append a 'start' event to the current log."""
+        start_event = self._CreateEventDict("start")
+        start_event["argv"] = argv
+        self._log.append(start_event)
+
+    def ExitEvent(self, result):
+        """Append an 'exit' event to the current log.
+
+        Args:
+            result: Exit code of the event
+        """
+        exit_event = self._CreateEventDict("exit")
+
+        # Consider 'None' success (consistent with event_log result handling).
+        if result is None:
+            result = 0
+        exit_event["code"] = result
+        time_delta = datetime.datetime.now(datetime.timezone.utc) - self.start
+        exit_event["t_abs"] = time_delta.total_seconds()
+        self._log.append(exit_event)
+
+    def CommandEvent(self, name, subcommands):
+        """Append a 'command' event to the current log.
+
+        Args:
+            name: Name of the primary command (ex: repo, git)
+            subcommands: List of the sub-commands (ex: version, init, sync)
+        """
+        command_event = self._CreateEventDict("cmd_name")
+        name = f"{name}-"
+        name += "-".join(subcommands)
+        command_event["name"] = name
+        command_event["hierarchy"] = name
+        self._log.append(command_event)
+
+    def LogConfigEvents(self, config, event_dict_name):
+        """Append a |event_dict_name| event for each config key in |config|.
+
+        Args:
+            config: Configuration dictionary.
+            event_dict_name: Name of the event dictionary for items to be logged
+                under.
+        """
+        for param, value in config.items():
+            event = self._CreateEventDict(event_dict_name)
+            event["param"] = param
+            event["value"] = value
+            self._log.append(event)
+
+    def DefParamRepoEvents(self, config):
+        """Append 'def_param' events for repo config keys to the current log.
+
+        This appends one event for each repo.* config key.
+
+        Args:
+            config: Repo configuration dictionary
+        """
+        # Only output the repo.* config parameters.
+        repo_config = {k: v for k, v in config.items() if k.startswith("repo.")}
+        self.LogConfigEvents(repo_config, "def_param")
+
+    def GetDataEventName(self, value):
+        """Returns 'data-json' if the value is an array else returns 'data'."""
+        return "data-json" if value[0] == "[" and value[-1] == "]" else "data"
+
+    def LogDataConfigEvents(self, config, prefix):
+        """Append a 'data' event for each entry in |config| to the current log.
+
+        For each keyX and valueX of the config, "key" field of the event is
+        '|prefix|/keyX' and the "value" of the "key" field is valueX.
+
+        Args:
+            config: Configuration dictionary.
+            prefix: Prefix for each key that is logged.
+        """
+        for key, value in config.items():
+            event = self._CreateEventDict(self.GetDataEventName(value))
+            event["key"] = f"{prefix}/{key}"
+            event["value"] = value
+            self._log.append(event)
+
+    def ErrorEvent(self, msg, fmt=None):
+        """Append a 'error' event to the current log."""
+        error_event = self._CreateEventDict("error")
+        if fmt is None:
+            fmt = msg
+        error_event["msg"] = f"RepoErrorEvent:{msg}"
+        error_event["fmt"] = f"RepoErrorEvent:{fmt}"
+        self._log.append(error_event)
+
+    def _WriteLog(self, write_fn):
+        """Writes the log out using a provided writer function.
+
+        Generate compact JSON output for each item in the log, and write it
+        using write_fn.
+
+        Args:
+            write_fn: A function that accepts byts and writes them to a
+                destination.
+        """
+
+        for e in self._log:
+            # Dump in compact encoding mode.
+            # See 'Compact encoding' in Python docs:
+            # https://docs.python.org/3/library/json.html#module-json
+            write_fn(
+                json.dumps(e, indent=None, separators=(",", ":")).encode(
+                    "utf-8"
+                )
+                + b"\n"
+            )
+
+    def Write(self, path=None):
+        """Writes the log out to a file or socket.
+
+        Log is only written if 'path' or 'git config --get trace2.eventtarget'
+        provide a valid path (or socket) to write logs to.
+
+        Logging filename format follows the git trace2 style of being a unique
+        (exclusive writable) file.
+
+        Args:
+            path: Path to where logs should be written. The path may have a
+                prefix of the form "af_unix:[{stream|dgram}:]", in which case
+                the path is treated as a Unix domain socket. See
+                https://git-scm.com/docs/api-trace2#_enabling_a_target for
+                details.
+
+        Returns:
+            log_path: Path to the log file or socket if log is written,
+                otherwise None
+        """
+        log_path = None
+        # If no logging path is specified, exit.
+        if path is None:
+            return None
+
+        path_is_socket = False
+        socket_type = None
+        if isinstance(path, str):
+            parts = path.split(":", 1)
+            if parts[0] == "af_unix" and len(parts) == 2:
+                path_is_socket = True
+                path = parts[1]
+                parts = path.split(":", 1)
+                if parts[0] == "stream" and len(parts) == 2:
+                    socket_type = socket.SOCK_STREAM
+                    path = parts[1]
+                elif parts[0] == "dgram" and len(parts) == 2:
+                    socket_type = socket.SOCK_DGRAM
+                    path = parts[1]
+            else:
+                # Get absolute path.
+                path = os.path.abspath(os.path.expanduser(path))
+        else:
+            raise TypeError("path: str required but got %s." % type(path))
+
+        # Git trace2 requires a directory to write log to.
+
+        # TODO(https://crbug.com/gerrit/13706): Support file (append) mode also.
+        if not (path_is_socket or os.path.isdir(path)):
+            return None
+
+        if path_is_socket:
+            if socket_type == socket.SOCK_STREAM or socket_type is None:
+                try:
+                    with socket.socket(
+                        socket.AF_UNIX, socket.SOCK_STREAM
+                    ) as sock:
+                        sock.settimeout(SOCK_TIMEOUT)
+                        sock.connect(path)
+                        self._WriteLog(sock.sendall)
+                    return f"af_unix:stream:{path}"
+                except OSError as err:
+                    # If we tried to connect to a DGRAM socket using STREAM,
+                    # ignore the attempt and continue to DGRAM below. Otherwise,
+                    # issue a warning.
+                    if err.errno != errno.EPROTOTYPE:
+                        print(
+                            f"repo: warning: git trace2 logging failed: {err}",
+                            file=sys.stderr,
+                        )
+                        return None
+            if socket_type == socket.SOCK_DGRAM or socket_type is None:
+                try:
+                    with socket.socket(
+                        socket.AF_UNIX, socket.SOCK_DGRAM
+                    ) as sock:
+                        self._WriteLog(lambda bs: sock.sendto(bs, path))
+                        return f"af_unix:dgram:{path}"
+                except OSError as err:
+                    print(
+                        f"repo: warning: git trace2 logging failed: {err}",
+                        file=sys.stderr,
+                    )
+                    return None
+            # Tried to open a socket but couldn't connect (SOCK_STREAM) or write
+            # (SOCK_DGRAM).
+            print(
+                "repo: warning: git trace2 logging failed: could not write to "
+                "socket",
+                file=sys.stderr,
+            )
+            return None
+
+        # Path is an absolute path
+        # Use NamedTemporaryFile to generate a unique filename as required by
+        # git trace2.
+        try:
+            with tempfile.NamedTemporaryFile(
+                mode="xb", prefix=self._sid, dir=path, delete=False
+            ) as f:
+                # TODO(https://crbug.com/gerrit/13706): Support writing events
+                # as they occur.
+                self._WriteLog(f.write)
+                log_path = f.name
+        except FileExistsError as err:
+            print(
+                "repo: warning: git trace2 logging failed: %r" % err,
+                file=sys.stderr,
+            )
+            return None
+        return log_path

gitc_utils.py

@@ -1,155 +0,0 @@
-# -*- coding:utf-8 -*-
-#
-# Copyright (C) 2015 The Android Open Source Project
-#
-# Licensed under the Apache License, Version 2.0 (the "License");
-# you may not use this file except in compliance with the License.
-# You may obtain a copy of the License at
-#
-#      http://www.apache.org/licenses/LICENSE-2.0
-#
-# Unless required by applicable law or agreed to in writing, software
-# distributed under the License is distributed on an "AS IS" BASIS,
-# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-# See the License for the specific language governing permissions and
-# limitations under the License.
-
-from __future__ import print_function
-import os
-import platform
-import re
-import sys
-import time
-
-import git_command
-import git_config
-import wrapper
-
-from error import ManifestParseError
-
-NUM_BATCH_RETRIEVE_REVISIONID = 32
-
-def get_gitc_manifest_dir():
-  return wrapper.Wrapper().get_gitc_manifest_dir()
-
-def parse_clientdir(gitc_fs_path):
-  return wrapper.Wrapper().gitc_parse_clientdir(gitc_fs_path)
-
-def _set_project_revisions(projects):
-  """Sets the revisionExpr for a list of projects.
-
-  Because of the limit of open file descriptors allowed, length of projects
-  should not be overly large. Recommend calling this function multiple times
-  with each call not exceeding NUM_BATCH_RETRIEVE_REVISIONID projects.
-
-  @param projects: List of project objects to set the revionExpr for.
-  """
-  # Retrieve the commit id for each project based off of it's current
-  # revisionExpr and it is not already a commit id.
-  project_gitcmds = [(
-      project, git_command.GitCommand(None,
-                                      ['ls-remote',
-                                       project.remote.url,
-                                       project.revisionExpr],
-                                      capture_stdout=True, cwd='/tmp'))
-      for project in projects if not git_config.IsId(project.revisionExpr)]
-  for proj, gitcmd in project_gitcmds:
-    if gitcmd.Wait():
-      print('FATAL: Failed to retrieve revisionExpr for %s' % proj)
-      sys.exit(1)
-    revisionExpr = gitcmd.stdout.split('\t')[0]
-    if not revisionExpr:
-      raise ManifestParseError('Invalid SHA-1 revision project %s (%s)' %
-                               (proj.remote.url, proj.revisionExpr))
-    proj.revisionExpr = revisionExpr
-
-def _manifest_groups(manifest):
-  """Returns the manifest group string that should be synced
-
-  This is the same logic used by Command.GetProjects(), which is used during
-  repo sync
-
-  @param manifest: The XmlManifest object
-  """
-  mp = manifest.manifestProject
-  groups = mp.config.GetString('manifest.groups')
-  if not groups:
-    groups = 'default,platform-' + platform.system().lower()
-  return groups
-
-def generate_gitc_manifest(gitc_manifest, manifest, paths=None):
-  """Generate a manifest for shafsd to use for this GITC client.
-
-  @param gitc_manifest: Current gitc manifest, or None if there isn't one yet.
-  @param manifest: A GitcManifest object loaded with the current repo manifest.
-  @param paths: List of project paths we want to update.
-  """
-
-  print('Generating GITC Manifest by fetching revision SHAs for each '
-        'project.')
-  if paths is None:
-    paths = list(manifest.paths.keys())
-
-  groups = [x for x in re.split(r'[,\s]+', _manifest_groups(manifest)) if x]
-
-  # Convert the paths to projects, and filter them to the matched groups.
-  projects = [manifest.paths[p] for p in paths]
-  projects = [p for p in projects if p.MatchesGroups(groups)]
-
-  if gitc_manifest is not None:
-    for path, proj in manifest.paths.items():
-      if not proj.MatchesGroups(groups):
-        continue
-
-      if not proj.upstream and not git_config.IsId(proj.revisionExpr):
-        proj.upstream = proj.revisionExpr
-
-      if not path in gitc_manifest.paths:
-        # Any new projects need their first revision, even if we weren't asked
-        # for them.
-        projects.append(proj)
-      elif not path in paths:
-        # And copy revisions from the previous manifest if we're not updating
-        # them now.
-        gitc_proj = gitc_manifest.paths[path]
-        if gitc_proj.old_revision:
-          proj.revisionExpr = None
-          proj.old_revision = gitc_proj.old_revision
-        else:
-          proj.revisionExpr = gitc_proj.revisionExpr
-
-  index = 0
-  while index < len(projects):
-    _set_project_revisions(
-        projects[index:(index+NUM_BATCH_RETRIEVE_REVISIONID)])
-    index += NUM_BATCH_RETRIEVE_REVISIONID
-
-  if gitc_manifest is not None:
-    for path, proj in gitc_manifest.paths.items():
-      if proj.old_revision and path in paths:
-        # If we updated a project that has been started, keep the old-revision
-        # updated.
-        repo_proj = manifest.paths[path]
-        repo_proj.old_revision = repo_proj.revisionExpr
-        repo_proj.revisionExpr = None
-
-  # Convert URLs from relative to absolute.
-  for _name, remote in manifest.remotes.items():
-    remote.fetchUrl = remote.resolvedFetchUrl
-
-  # Save the manifest.
-  save_manifest(manifest)
-
-def save_manifest(manifest, client_dir=None):
-  """Save the manifest file in the client_dir.
-
-  @param client_dir: Client directory to save the manifest in.
-  @param manifest: Manifest object to save.
-  """
-  if not client_dir:
-    client_dir = manifest.gitc_client_dir
-  with open(os.path.join(client_dir, '.manifest'), 'w') as f:
-    manifest.Save(f, groups=_manifest_groups(manifest))
-  # TODO(sbasi/jorg): Come up with a solution to remove the sleep below.
-  # Give the GITC filesystem time to register the manifest changes.
-  time.sleep(3)

hooks.py

@@ -0,0 +1,527 @@
+# Copyright (C) 2008 The Android Open Source Project
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import os
+import re
+import sys
+import traceback
+import urllib.parse
+
+from error import HookError
+from git_refs import HEAD
+
+
+# The API we've documented to hook authors.  Keep in sync with repo-hooks.md.
+_API_ARGS = {
+    "pre-upload": {"project_list", "worktree_list"},
+}
+
+
+class RepoHook:
+    """A RepoHook contains information about a script to run as a hook.
+
+    Hooks are used to run a python script before running an upload (for
+    instance, to run presubmit checks).  Eventually, we may have hooks for other
+    actions.
+
+    This shouldn't be confused with files in the 'repo/hooks' directory.  Those
+    files are copied into each '.git/hooks' folder for each project.  Repo-level
+    hooks are associated instead with repo actions.
+
+    Hooks are always python.  When a hook is run, we will load the hook into the
+    interpreter and execute its main() function.
+
+    Combinations of hook option flags:
+    - no-verify=False, verify=False (DEFAULT):
+      If stdout is a tty, can prompt about running hooks if needed.
+      If user denies running hooks, the action is cancelled. If stdout is
+      not a tty and we would need to prompt about hooks, action is
+      cancelled.
+    - no-verify=False, verify=True:
+      Always run hooks with no prompt.
+    - no-verify=True, verify=False:
+      Never run hooks, but run action anyway (AKA bypass hooks).
+    - no-verify=True, verify=True:
+      Invalid
+    """
+
+    def __init__(
+        self,
+        hook_type,
+        hooks_project,
+        repo_topdir,
+        manifest_url,
+        bug_url=None,
+        bypass_hooks=False,
+        allow_all_hooks=False,
+        ignore_hooks=False,
+        abort_if_user_denies=False,
+    ):
+        """RepoHook constructor.
+
+        Params:
+            hook_type: A string representing the type of hook. This is also used
+                to figure out the name of the file containing the hook. For
+                example: 'pre-upload'.
+            hooks_project: The project containing the repo hooks.
+                If you have a manifest, this is manifest.repo_hooks_project.
+                OK if this is None, which will make the hook a no-op.
+            repo_topdir: The top directory of the repo client checkout.
+                This is the one containing the .repo directory. Scripts will
+                run with CWD as this directory.
+                If you have a manifest, this is manifest.topdir.
+            manifest_url: The URL to the manifest git repo.
+            bug_url: The URL to report issues.
+            bypass_hooks: If True, then 'Do not run the hook'.
+            allow_all_hooks: If True, then 'Run the hook without prompting'.
+            ignore_hooks: If True, then 'Do not abort action if hooks fail'.
+            abort_if_user_denies: If True, we'll abort running the hook if the
+                user doesn't allow us to run the hook.
+        """
+        self._hook_type = hook_type
+        self._hooks_project = hooks_project
+        self._repo_topdir = repo_topdir
+        self._manifest_url = manifest_url
+        self._bug_url = bug_url
+        self._bypass_hooks = bypass_hooks
+        self._allow_all_hooks = allow_all_hooks
+        self._ignore_hooks = ignore_hooks
+        self._abort_if_user_denies = abort_if_user_denies
+
+        # Store the full path to the script for convenience.
+        if self._hooks_project:
+            self._script_fullpath = os.path.join(
+                self._hooks_project.worktree, self._hook_type + ".py"
+            )
+        else:
+            self._script_fullpath = None
+
+    def _GetHash(self):
+        """Return a hash of the contents of the hooks directory.
+
+        We'll just use git to do this.  This hash has the property that if
+        anything changes in the directory we will return a different has.
+
+        SECURITY CONSIDERATION:
+            This hash only represents the contents of files in the hook
+            directory, not any other files imported or called by hooks.  Changes
+            to imported files can change the script behavior without affecting
+            the hash.
+
+        Returns:
+            A string representing the hash.  This will always be ASCII so that
+            it can be printed to the user easily.
+        """
+        assert self._hooks_project, "Must have hooks to calculate their hash."
+
+        # We will use the work_git object rather than just calling
+        # GetRevisionId(). That gives us a hash of the latest checked in version
+        # of the files that the user will actually be executing.  Specifically,
+        # GetRevisionId() doesn't appear to change even if a user checks out a
+        # different version of the hooks repo (via git checkout) nor if a user
+        # commits their own revs.
+        #
+        # NOTE: Local (non-committed) changes will not be factored into this
+        # hash. I think this is OK, since we're really only worried about
+        # warning the user about upstream changes.
+        return self._hooks_project.work_git.rev_parse(HEAD)
+
+    def _GetMustVerb(self):
+        """Return 'must' if the hook is required; 'should' if not."""
+        if self._abort_if_user_denies:
+            return "must"
+        else:
+            return "should"
+
+    def _CheckForHookApproval(self):
+        """Check to see whether this hook has been approved.
+
+        We'll accept approval of manifest URLs if they're using secure
+        transports. This way the user can say they trust the manifest hoster.
+        For insecure hosts, we fall back to checking the hash of the hooks repo.
+
+        Note that we ask permission for each individual hook even though we use
+        the hash of all hooks when detecting changes.  We'd like the user to be
+        able to approve / deny each hook individually.  We only use the hash of
+        all hooks because there is no other easy way to detect changes to local
+        imports.
+
+        Returns:
+            True if this hook is approved to run; False otherwise.
+
+        Raises:
+            HookError: Raised if the user doesn't approve and
+                abort_if_user_denies was passed to the consturctor.
+        """
+        if self._ManifestUrlHasSecureScheme():
+            return self._CheckForHookApprovalManifest()
+        else:
+            return self._CheckForHookApprovalHash()
+
+    def _CheckForHookApprovalHelper(
+        self, subkey, new_val, main_prompt, changed_prompt
+    ):
+        """Check for approval for a particular attribute and hook.
+
+        Args:
+            subkey: The git config key under [repo.hooks.<hook_type>] to store
+                the last approved string.
+            new_val: The new value to compare against the last approved one.
+            main_prompt: Message to display to the user to ask for approval.
+            changed_prompt: Message explaining why we're re-asking for approval.
+
+        Returns:
+            True if this hook is approved to run; False otherwise.
+
+        Raises:
+            HookError: Raised if the user doesn't approve and
+                abort_if_user_denies was passed to the consturctor.
+        """
+        hooks_config = self._hooks_project.config
+        git_approval_key = f"repo.hooks.{self._hook_type}.{subkey}"
+
+        # Get the last value that the user approved for this hook; may be None.
+        old_val = hooks_config.GetString(git_approval_key)
+
+        if old_val is not None:
+            # User previously approved hook and asked not to be prompted again.
+            if new_val == old_val:
+                # Approval matched.  We're done.
+                return True
+            else:
+                # Give the user a reason why we're prompting, since they last
+                # told us to "never ask again".
+                prompt = f"WARNING: {changed_prompt}\n\n"
+        else:
+            prompt = ""
+
+        # Prompt the user if we're not on a tty; on a tty we'll assume "no".
+        if sys.stdout.isatty():
+            prompt += main_prompt + " (yes/always/NO)? "
+            response = input(prompt).lower()
+            print()
+
+            # User is doing a one-time approval.
+            if response in ("y", "yes"):
+                return True
+            elif response == "always":
+                hooks_config.SetString(git_approval_key, new_val)
+                return True
+
+        # For anything else, we'll assume no approval.
+        if self._abort_if_user_denies:
+            raise HookError(
+                "You must allow the %s hook or use --no-verify."
+                % self._hook_type
+            )
+
+        return False
+
+    def _ManifestUrlHasSecureScheme(self):
+        """Check if the URI for the manifest is a secure transport."""
+        secure_schemes = (
+            "file",
+            "https",
+            "ssh",
+            "persistent-https",
+            "sso",
+            "rpc",
+        )
+        parse_results = urllib.parse.urlparse(self._manifest_url)
+        return parse_results.scheme in secure_schemes
+
+    def _CheckForHookApprovalManifest(self):
+        """Check whether the user has approved this manifest host.
+
+        Returns:
+            True if this hook is approved to run; False otherwise.
+        """
+        return self._CheckForHookApprovalHelper(
+            "approvedmanifest",
+            self._manifest_url,
+            f"Run hook scripts from {self._manifest_url}",
+            f"Manifest URL has changed since {self._hook_type} was allowed.",
+        )
+
+    def _CheckForHookApprovalHash(self):
+        """Check whether the user has approved the hooks repo.
+
+        Returns:
+            True if this hook is approved to run; False otherwise.
+        """
+        prompt = (
+            "Repo %s run the script:\n"
+            "  %s\n"
+            "\n"
+            "Do you want to allow this script to run"
+        )
+        return self._CheckForHookApprovalHelper(
+            "approvedhash",
+            self._GetHash(),
+            prompt % (self._GetMustVerb(), self._script_fullpath),
+            f"Scripts have changed since {self._hook_type} was allowed.",
+        )
+
+    @staticmethod
+    def _ExtractInterpFromShebang(data):
+        """Extract the interpreter used in the shebang.
+
+        Try to locate the interpreter the script is using (ignoring `env`).
+
+        Args:
+            data: The file content of the script.
+
+        Returns:
+            The basename of the main script interpreter, or None if a shebang is
+            not used or could not be parsed out.
+        """
+        firstline = data.splitlines()[:1]
+        if not firstline:
+            return None
+
+        # The format here can be tricky.
+        shebang = firstline[0].strip()
+        m = re.match(r"^#!\s*([^\s]+)(?:\s+([^\s]+))?", shebang)
+        if not m:
+            return None
+
+        # If the using `env`, find the target program.
+        interp = m.group(1)
+        if os.path.basename(interp) == "env":
+            interp = m.group(2)
+
+        return interp
+
+    def _ExecuteHookViaImport(self, data, context, **kwargs):
+        """Execute the hook code in |data| directly.
+
+        Args:
+            data: The code of the hook to execute.
+            context: Basic Python context to execute the hook inside.
+            kwargs: Arbitrary arguments to pass to the hook script.
+
+        Raises:
+            HookError: When the hooks failed for any reason.
+        """
+        # Exec, storing global context in the context dict.  We catch exceptions
+        # and convert to a HookError w/ just the failing traceback.
+        try:
+            exec(compile(data, self._script_fullpath, "exec"), context)
+        except Exception:
+            raise HookError(
+                "%s\nFailed to import %s hook; see traceback above."
+                % (traceback.format_exc(), self._hook_type)
+            )
+
+        # Running the script should have defined a main() function.
+        if "main" not in context:
+            raise HookError('Missing main() in: "%s"' % self._script_fullpath)
+
+        # Call the main function in the hook.  If the hook should cause the
+        # build to fail, it will raise an Exception.  We'll catch that convert
+        # to a HookError w/ just the failing traceback.
+        try:
+            context["main"](**kwargs)
+        except Exception:
+            raise HookError(
+                "%s\nFailed to run main() for %s hook; see traceback "
+                "above." % (traceback.format_exc(), self._hook_type)
+            )
+
+    def _ExecuteHook(self, **kwargs):
+        """Actually execute the given hook.
+
+        This will run the hook's 'main' function in our python interpreter.
+
+        Args:
+            kwargs: Keyword arguments to pass to the hook.  These are often
+                specific to the hook type.  For instance, pre-upload hooks will
+                contain a project_list.
+        """
+        # Keep sys.path and CWD stashed away so that we can always restore them
+        # upon function exit.
+        orig_path = os.getcwd()
+        orig_syspath = sys.path
+
+        try:
+            # Always run hooks with CWD as topdir.
+            os.chdir(self._repo_topdir)
+
+            # Put the hook dir as the first item of sys.path so hooks can do
+            # relative imports.  We want to replace the repo dir as [0] so
+            # hooks can't import repo files.
+            sys.path = [os.path.dirname(self._script_fullpath)] + sys.path[1:]
+
+            # Initial global context for the hook to run within.
+            context = {"__file__": self._script_fullpath}
+
+            # Add 'hook_should_take_kwargs' to the arguments to be passed to
+            # main. We don't actually want hooks to define their main with this
+            # argument--it's there to remind them that their hook should always
+            # take **kwargs.
+            # For instance, a pre-upload hook should be defined like:
+            #   def main(project_list, **kwargs):
+            #
+            # This allows us to later expand the API without breaking old hooks.
+            kwargs = kwargs.copy()
+            kwargs["hook_should_take_kwargs"] = True
+
+            # See what version of python the hook has been written against.
+            data = open(self._script_fullpath).read()
+            interp = self._ExtractInterpFromShebang(data)
+            if interp:
+                prog = os.path.basename(interp)
+                if prog.startswith("python2"):
+                    raise HookError("Python 2 is not supported")
+
+            # Run the hook by importing directly.
+            self._ExecuteHookViaImport(data, context, **kwargs)
+        finally:
+            # Restore sys.path and CWD.
+            sys.path = orig_syspath
+            os.chdir(orig_path)
+
+    def _CheckHook(self):
+        # Bail with a nice error if we can't find the hook.
+        if not os.path.isfile(self._script_fullpath):
+            raise HookError(
+                "Couldn't find repo hook: %s" % self._script_fullpath
+            )
+
+    def Run(self, **kwargs):
+        """Run the hook.
+
+        If the hook doesn't exist (because there is no hooks project or because
+        this particular hook is not enabled), this is a no-op.
+
+        Args:
+            user_allows_all_hooks: If True, we will never prompt about running
+                the hook--we'll just assume it's OK to run it.
+            kwargs: Keyword arguments to pass to the hook.  These are often
+                specific to the hook type.  For instance, pre-upload hooks will
+                contain a project_list.
+
+        Returns:
+            True: On success or ignore hooks by user-request
+            False: The hook failed. The caller should respond with aborting the
+                action. Some examples in which False is returned:
+                * Finding the hook failed while it was enabled, or
+                * the user declined to run a required hook (from
+                    _CheckForHookApproval)
+                In all these cases the user did not pass the proper arguments to
+                ignore the result through the option combinations as listed in
+                AddHookOptionGroup().
+        """
+        # Make sure our own callers use the documented API.
+        exp_kwargs = _API_ARGS.get(self._hook_type, set())
+        got_kwargs = set(kwargs.keys())
+        if exp_kwargs != got_kwargs:
+            print(
+                "repo internal error: "
+                f"hook '{self._hook_type}' called incorrectly\n"
+                f"  got:      {sorted(got_kwargs)}\n"
+                f"  expected: {sorted(exp_kwargs)}\n"
+                f"Please file a bug: {self._bug_url}",
+                file=sys.stderr,
+            )
+            return False
+
+        # Do not do anything in case bypass_hooks is set, or
+        # no-op if there is no hooks project or if hook is disabled.
+        if (
+            self._bypass_hooks
+            or not self._hooks_project
+            or self._hook_type not in self._hooks_project.enabled_repo_hooks
+        ):
+            return True
+
+        passed = True
+        try:
+            self._CheckHook()
+
+            # Make sure the user is OK with running the hook.
+            if self._allow_all_hooks or self._CheckForHookApproval():
+                # Run the hook with the same version of python we're using.
+                self._ExecuteHook(**kwargs)
+        except SystemExit as e:
+            passed = False
+            print(
+                "ERROR: %s hooks exited with exit code: %s"
+                % (self._hook_type, str(e)),
+                file=sys.stderr,
+            )
+        except HookError as e:
+            passed = False
+            print("ERROR: %s" % str(e), file=sys.stderr)
+
+        if not passed and self._ignore_hooks:
+            print(
+                "\nWARNING: %s hooks failed, but continuing anyways."
+                % self._hook_type,
+                file=sys.stderr,
+            )
+            passed = True
+
+        return passed
+
+    @classmethod
+    def FromSubcmd(cls, manifest, opt, *args, **kwargs):
+        """Method to construct the repo hook class
+
+        Args:
+            manifest: The current active manifest for this command from which we
+                extract a couple of fields.
+            opt: Contains the commandline options for the action of this hook.
+                It should contain the options added by AddHookOptionGroup() in
+                which we are interested in RepoHook execution.
+        """
+        for key in ("bypass_hooks", "allow_all_hooks", "ignore_hooks"):
+            kwargs.setdefault(key, getattr(opt, key))
+        kwargs.update(
+            {
+                "hooks_project": manifest.repo_hooks_project,
+                "repo_topdir": manifest.topdir,
+                "manifest_url": manifest.manifestProject.GetRemote(
+                    "origin"
+                ).url,
+                "bug_url": manifest.contactinfo.bugurl,
+            }
+        )
+        return cls(*args, **kwargs)
+
+    @staticmethod
+    def AddOptionGroup(parser, name):
+        """Help options relating to the various hooks."""
+
+        # Note that verify and no-verify are NOT opposites of each other, which
+        # is why they store to different locations. We are using them to match
+        # 'git commit' syntax.
+        group = parser.add_option_group(name + " hooks")
+        group.add_option(
+            "--no-verify",
+            dest="bypass_hooks",
+            action="store_true",
+            help="Do not run the %s hook." % name,
+        )
+        group.add_option(
+            "--verify",
+            dest="allow_all_hooks",
+            action="store_true",
+            help="Run the %s hook without prompting." % name,
+        )
+        group.add_option(
+            "--ignore-hooks",
+            action="store_true",
+            help="Do not abort if %s hooks fail." % name,
+        )

hooks/commit-msg

@@ -1,5 +1,8 @@
 #!/bin/sh
-# From Gerrit Code Review 2.14.6
+# DO NOT EDIT THIS FILE
+# All updates should be sent upstream: https://gerrit.googlesource.com/gerrit/
+# This is synced from commit: 62f5bbea67f6dafa6e22a601a0c298214c510caf
+# DO NOT EDIT THIS FILE
 #
 # Part of Gerrit Code Review (https://www.gerritcodereview.com/)
 #
@@ -16,176 +19,95 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
-#
 
-unset GREP_OPTIONS
+set -u
 
-CHANGE_ID_AFTER="Bug|Depends-On|Issue|Test|Feature|Fixes|Fixed"
-MSG="$1"
+# avoid [[ which is not POSIX sh.
+if test "$#" != 1 ; then
+  echo "$0 requires an argument."
+  exit 1
+fi
 
-# Check for, and add if missing, a unique Change-Id
-#
-add_ChangeId() {
-	clean_message=`sed -e '
-		/^diff --git .*/{
-			s///
-			q
-		}
-		/^Signed-off-by:/d
-		/^#/d
-	' "$MSG" | git stripspace`
-	if test -z "$clean_message"
-	then
-		return
-	fi
+if test ! -f "$1" ; then
+  echo "file does not exist: $1"
+  exit 1
+fi
 
-	# Do not add Change-Id to temp commits
-	if echo "$clean_message" | head -1 | grep -q '^\(fixup\|squash\)!'
-	then
-		return
-	fi
-
-	if test "false" = "`git config --bool --get gerrit.createChangeId`"
-	then
-		return
-	fi
-
-	# Does Change-Id: already exist? if so, exit (no change).
-	if grep -i '^Change-Id:' "$MSG" >/dev/null
-	then
-		return
-	fi
-
-	id=`_gen_ChangeId`
-	T="$MSG.tmp.$$"
-	AWK=awk
-	if [ -x /usr/xpg4/bin/awk ]; then
-		# Solaris AWK is just too broken
-		AWK=/usr/xpg4/bin/awk
-	fi
-
-	# Get core.commentChar from git config or use default symbol
-	commentChar=`git config --get core.commentChar`
-	commentChar=${commentChar:-#}
-
-	# How this works:
-	# - parse the commit message as (textLine+ blankLine*)*
-	# - assume textLine+ to be a footer until proven otherwise
-	# - exception: the first block is not footer (as it is the title)
-	# - read textLine+ into a variable
-	# - then count blankLines
-	# - once the next textLine appears, print textLine+ blankLine* as these
-	#   aren't footer
-	# - in END, the last textLine+ block is available for footer parsing
-	$AWK '
-	BEGIN {
-		# while we start with the assumption that textLine+
-		# is a footer, the first block is not.
-		isFooter = 0
-		footerComment = 0
-		blankLines = 0
-	}
-
-	# Skip lines starting with commentChar without any spaces before it.
-	/^'"$commentChar"'/ { next }
-
-	# Skip the line starting with the diff command and everything after it,
-	# up to the end of the file, assuming it is only patch data.
-	# If more than one line before the diff was empty, strip all but one.
-	/^diff --git / {
-		blankLines = 0
-		while (getline) { }
-		next
-	}
-
-	# Count blank lines outside footer comments
-	/^$/ && (footerComment == 0) {
-		blankLines++
-		next
-	}
-
-	# Catch footer comment
-	/^\[[a-zA-Z0-9-]+:/ && (isFooter == 1) {
-		footerComment = 1
-	}
-
-	/]$/ && (footerComment == 1) {
-		footerComment = 2
-	}
-
-	# We have a non-blank line after blank lines. Handle this.
-	(blankLines > 0) {
-		print lines
-		for (i = 0; i < blankLines; i++) {
-			print ""
-		}
-
-		lines = ""
-		blankLines = 0
-		isFooter = 1
-		footerComment = 0
-	}
-
-	# Detect that the current block is not the footer
-	(footerComment == 0) && (!/^\[?[a-zA-Z0-9-]+:/ || /^[a-zA-Z0-9-]+:\/\//) {
-		isFooter = 0
-	}
-
-	{
-		# We need this information about the current last comment line
-		if (footerComment == 2) {
-			footerComment = 0
-		}
-		if (lines != "") {
-			lines = lines "\n";
-		}
-		lines = lines $0
-	}
-
-	# Footer handling:
-	# If the last block is considered a footer, splice in the Change-Id at the
-	# right place.
-	# Look for the right place to inject Change-Id by considering
-	# CHANGE_ID_AFTER. Keys listed in it (case insensitive) come first,
-	# then Change-Id, then everything else (eg. Signed-off-by:).
-	#
-	# Otherwise just print the last block, a new line and the Change-Id as a
-	# block of its own.
-	END {
-		unprinted = 1
-		if (isFooter == 0) {
-			print lines "\n"
-			lines = ""
-		}
-		changeIdAfter = "^(" tolower("'"$CHANGE_ID_AFTER"'") "):"
-		numlines = split(lines, footer, "\n")
-		for (line = 1; line <= numlines; line++) {
-			if (unprinted && match(tolower(footer[line]), changeIdAfter) != 1) {
-				unprinted = 0
-				print "Change-Id: I'"$id"'"
-			}
-			print footer[line]
-		}
-		if (unprinted) {
-			print "Change-Id: I'"$id"'"
-		}
-	}' "$MSG" > "$T" && mv "$T" "$MSG" || rm -f "$T"
-}
-_gen_ChangeIdInput() {
-	echo "tree `git write-tree`"
-	if parent=`git rev-parse "HEAD^0" 2>/dev/null`
-	then
-		echo "parent $parent"
-	fi
-	echo "author `git var GIT_AUTHOR_IDENT`"
-	echo "committer `git var GIT_COMMITTER_IDENT`"
-	echo
-	printf '%s' "$clean_message"
-}
-_gen_ChangeId() {
-	_gen_ChangeIdInput |
-	git hash-object -t commit --stdin
-}
+# Do not create a change id if requested
+case "$(git config --get gerrit.createChangeId)" in
+  false)
+    exit 0
+    ;;
+  always)
+    ;;
+  *)
+    # Do not create a change id for squash/fixup commits.
+    if head -n1 "$1" | LC_ALL=C grep -q '^[a-z][a-z]*! '; then
+      exit 0
+    fi
+    ;;
+esac
 
 
-add_ChangeId
+if git rev-parse --verify HEAD >/dev/null 2>&1; then
+  refhash="$(git rev-parse HEAD)"
+else
+  refhash="$(git hash-object -t tree /dev/null)"
+fi
+
+random=$({ git var GIT_COMMITTER_IDENT ; echo "$refhash" ; cat "$1"; } | git hash-object --stdin)
+dest="$1.tmp.${random}"
+
+trap 'rm -f "$dest" "$dest-2"' EXIT
+
+if ! cat "$1" | sed -e '/>8/q' | git stripspace --strip-comments > "${dest}" ; then
+   echo "cannot strip comments from $1"
+   exit 1
+fi
+
+if test ! -s "${dest}" ; then
+  echo "file is empty: $1"
+  exit 1
+fi
+
+reviewurl="$(git config --get gerrit.reviewUrl)"
+if test -n "${reviewurl}" ; then
+  token="Link"
+  value="${reviewurl%/}/id/I$random"
+  pattern=".*/id/I[0-9a-f]\{40\}"
+else
+  token="Change-Id"
+  value="I$random"
+  pattern=".*"
+fi
+
+if git interpret-trailers --parse < "$1" | grep -q "^$token: $pattern$" ; then
+  exit 0
+fi
+
+# There must be a Signed-off-by trailer for the code below to work. Insert a
+# sentinel at the end to make sure there is one.
+# Avoid the --in-place option which only appeared in Git 2.8
+if ! git interpret-trailers \
+         --trailer "Signed-off-by: SENTINEL" < "$1" > "$dest-2" ; then
+  echo "cannot insert Signed-off-by sentinel line in $1"
+  exit 1
+fi
+
+# Make sure the trailer appears before any Signed-off-by trailers by inserting
+# it as if it was a Signed-off-by trailer and then use sed to remove the
+# Signed-off-by prefix and the Signed-off-by sentinel line.
+# Avoid the --in-place option which only appeared in Git 2.8
+# Avoid the --where option which only appeared in Git 2.15
+if ! git -c trailer.where=before interpret-trailers \
+         --trailer "Signed-off-by: $token: $value" < "$dest-2" |
+     sed -e "s/^Signed-off-by: \($token: \)/\1/" \
+         -e "/^Signed-off-by: SENTINEL/d" > "$dest" ; then
+  echo "cannot insert $token line in $1"
+  exit 1
+fi
+
+if ! mv "${dest}" "$1" ; then
+  echo "cannot mv ${dest} to $1"
+  exit 1
+fi

hooks/pre-auto-gc

@@ -1,33 +1,25 @@
 #!/bin/sh
+# DO NOT EDIT THIS FILE
+# All updates should be sent upstream: https://github.com/git/git
+# This is synced from commit: 00e10ef10e161a913893b8cb33aa080d4ca5baa6
+# DO NOT EDIT THIS FILE
 #
 # An example hook script to verify if you are on battery, in case you
-# are running Windows, Linux or OS X. Called by git-gc --auto with no
-# arguments. The hook should exit with non-zero status after issuing an
-# appropriate message if it wants to stop the auto repacking.
-
-# This program is free software; you can redistribute it and/or modify
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation; either version 2 of the License, or
-# (at your option) any later version.
+# are running Linux or OS X. Called by git-gc --auto with no arguments.
+# The hook should exit with non-zero status after issuing an appropriate
+# message if it wants to stop the auto repacking.
 #
-# This program is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
+# This hook is stored in the contrib/hooks directory. Your distribution
+# may have put this somewhere else. If you want to use this hook, you
+# should make this script executable then link to it in the repository
+# you would like to use it in.
 #
-# You should have received a copy of the GNU General Public License
-# along with this program; if not, write to the Free Software
-# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
-
-if uname -s | grep -q "_NT-"
-then
-	if test -x $SYSTEMROOT/System32/Wbem/wmic
-	then
-		STATUS=$(wmic path win32_battery get batterystatus /format:list | tr -d '\r\n')
-		[ "$STATUS" = "BatteryStatus=2" ] && exit 0 || exit 1
-	fi
-	exit 0
-fi
+# For example, if the hook is stored in
+# /usr/share/git-core/contrib/hooks/pre-auto-gc-battery:
+#
+# cd /path/to/your/repository.git
+# ln -sf /usr/share/git-core/contrib/hooks/pre-auto-gc-battery \
+#	hooks/pre-auto-gc
 
 if test -x /sbin/on_ac_power && (/sbin/on_ac_power;test $? -ne 1)
 then
@@ -48,11 +40,6 @@ elif test -x /usr/bin/pmset && /usr/bin/pmset -g batt |
 	grep -q "drawing from 'AC Power'"
 then
 	exit 0
-elif test -d /sys/bus/acpi/drivers/battery && test 0 = \
-  "$(find /sys/bus/acpi/drivers/battery/ -type l | wc -l)";
-then
-	# No battery exists.
-	exit 0
 fi
 
 echo "Auto packing deferred; not on AC"

man/repo-abandon.1

@@ -0,0 +1,49 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man.
+.TH REPO "1" "July 2022" "repo abandon" "Repo Manual"
+.SH NAME
+repo \- repo abandon - manual page for repo abandon
+.SH SYNOPSIS
+.B repo
+\fI\,abandon \/\fR[\fI\,--all | <branchname>\/\fR] [\fI\,<project>\/\fR...]
+.SH DESCRIPTION
+Summary
+.PP
+Permanently abandon a development branch
+.PP
+This subcommand permanently abandons a development branch by
+deleting it (and all its history) from your local repository.
+.PP
+It is equivalent to "git branch \fB\-D\fR <branchname>".
+.SH OPTIONS
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+show this help message and exit
+.TP
+\fB\-j\fR JOBS, \fB\-\-jobs\fR=\fI\,JOBS\/\fR
+number of jobs to run in parallel (default: based on
+number of CPU cores)
+.TP
+\fB\-\-all\fR
+delete all branches in all projects
+.SS Logging options:
+.TP
+\fB\-v\fR, \fB\-\-verbose\fR
+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.

man/repo-branch.1

@@ -0,0 +1 @@
+.so man1/repo-branches.1

man/repo-branches.1

@@ -0,0 +1,72 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man.
+.TH REPO "1" "July 2022" "repo branches" "Repo Manual"
+.SH NAME
+repo \- repo branches - manual page for repo branches
+.SH SYNOPSIS
+.B repo
+\fI\,branches \/\fR[\fI\,<project>\/\fR...]
+.SH DESCRIPTION
+Summary
+.PP
+View current topic branches
+.PP
+Summarizes the currently available topic branches.
+.PP
+# Branch Display
+.PP
+The branch display output by this command is organized into four
+columns of information; for example:
+.TP
+*P nocolor
+| in repo
+.TP
+repo2
+|
+.PP
+The first column contains a * if the branch is the currently
+checked out branch in any of the specified projects, or a blank
+if no project has the branch checked out.
+.PP
+The second column contains either blank, p or P, depending upon
+the upload status of the branch.
+.IP
+(blank): branch not yet published by repo upload
+.IP
+P: all commits were published by repo upload
+p: only some commits were published by repo upload
+.PP
+The third column contains the branch name.
+.PP
+The fourth column (after the | separator) lists the projects that
+the branch appears in, or does not appear in.  If no project list
+is shown, then the branch appears in all projects.
+.SH OPTIONS
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+show this help message and exit
+.TP
+\fB\-j\fR JOBS, \fB\-\-jobs\fR=\fI\,JOBS\/\fR
+number of jobs to run in parallel (default: based on
+number of CPU cores)
+.SS Logging options:
+.TP
+\fB\-v\fR, \fB\-\-verbose\fR
+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.

man/repo-checkout.1

@@ -0,0 +1,49 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man.
+.TH REPO "1" "July 2022" "repo checkout" "Repo Manual"
+.SH NAME
+repo \- repo checkout - manual page for repo checkout
+.SH SYNOPSIS
+.B repo
+\fI\,checkout <branchname> \/\fR[\fI\,<project>\/\fR...]
+.SH DESCRIPTION
+Summary
+.PP
+Checkout a branch for development
+.SH OPTIONS
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+show this help message and exit
+.TP
+\fB\-j\fR JOBS, \fB\-\-jobs\fR=\fI\,JOBS\/\fR
+number of jobs to run in parallel (default: based on
+number of CPU cores)
+.SS Logging options:
+.TP
+\fB\-v\fR, \fB\-\-verbose\fR
+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
+.PP
+The 'repo checkout' command checks out an existing branch that was previously
+created by 'repo start'.
+.PP
+The command is equivalent to:
+.IP
+repo forall [<project>...] \fB\-c\fR git checkout <branchname>

man/repo-cherry-pick.1

@@ -0,0 +1,41 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man.
+.TH REPO "1" "July 2022" "repo cherry-pick" "Repo Manual"
+.SH NAME
+repo \- repo cherry-pick - manual page for repo cherry-pick
+.SH SYNOPSIS
+.B repo
+\fI\,cherry-pick <sha1>\/\fR
+.SH DESCRIPTION
+Summary
+.PP
+Cherry\-pick a change.
+.SH OPTIONS
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+show this help message and exit
+.SS Logging options:
+.TP
+\fB\-v\fR, \fB\-\-verbose\fR
+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
+.PP
+\&'repo cherry\-pick' cherry\-picks a change from one branch to another. The change
+id will be updated, and a reference to the old change id will be added.

man/repo-diff.1

@@ -0,0 +1,48 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man.
+.TH REPO "1" "July 2022" "repo diff" "Repo Manual"
+.SH NAME
+repo \- repo diff - manual page for repo diff
+.SH SYNOPSIS
+.B repo
+\fI\,diff \/\fR[\fI\,<project>\/\fR...]
+.SH DESCRIPTION
+Summary
+.PP
+Show changes between commit and working tree
+.PP
+The \fB\-u\fR option causes 'repo diff' to generate diff output with file paths
+relative to the repository root, so the output can be applied
+to the Unix 'patch' command.
+.SH OPTIONS
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+show this help message and exit
+.TP
+\fB\-j\fR JOBS, \fB\-\-jobs\fR=\fI\,JOBS\/\fR
+number of jobs to run in parallel (default: based on
+number of CPU cores)
+.TP
+\fB\-u\fR, \fB\-\-absolute\fR
+paths are relative to the repository root
+.SS Logging options:
+.TP
+\fB\-v\fR, \fB\-\-verbose\fR
+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.

man/repo-diffmanifests.1

@@ -0,0 +1,74 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man.
+.TH REPO "1" "July 2022" "repo diffmanifests" "Repo Manual"
+.SH NAME
+repo \- repo diffmanifests - manual page for repo diffmanifests
+.SH SYNOPSIS
+.B repo
+\fI\,diffmanifests manifest1.xml \/\fR[\fI\,manifest2.xml\/\fR] [\fI\,options\/\fR]
+.SH DESCRIPTION
+Summary
+.PP
+Manifest diff utility
+.SH OPTIONS
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+show this help message and exit
+.TP
+\fB\-\-raw\fR
+display raw diff
+.TP
+\fB\-\-no\-color\fR
+does not display the diff in color
+.TP
+\fB\-\-pretty\-format=\fR<FORMAT>
+print the log using a custom git pretty format string
+.SS Logging options:
+.TP
+\fB\-v\fR, \fB\-\-verbose\fR
+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
+.PP
+The repo diffmanifests command shows differences between project revisions of
+manifest1 and manifest2. if manifest2 is not specified, current manifest.xml
+will be used instead. Both absolute and relative paths may be used for
+manifests. Relative paths start from project's ".repo/manifests" folder.
+.PP
+The \fB\-\-raw\fR option Displays the diff in a way that facilitates parsing, the
+project pattern will be <status> <path> <revision from> [<revision to>] and the
+commit pattern will be <status> <onelined log> with status values respectively :
+.IP
+A = Added project
+R = Removed project
+C = Changed project
+U = Project with unreachable revision(s) (revision(s) not found)
+.PP
+for project, and
+.IP
+A = Added commit
+R = Removed commit
+.PP
+for a commit.
+.PP
+Only changed projects may contain commits, and commit status always starts with
+a space, and are part of last printed project. Unreachable revisions may occur
+if project is not up to date or if repo has not been initialized with all the
+groups, in which case some projects won't be synced and their revisions won't be
+found.

man/repo-download.1

@@ -0,0 +1,57 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man.
+.TH REPO "1" "July 2022" "repo download" "Repo Manual"
+.SH NAME
+repo \- repo download - manual page for repo download
+.SH SYNOPSIS
+.B repo
+\fI\,download {\/\fR[\fI\,project\/\fR] \fI\,change\/\fR[\fI\,/patchset\/\fR]\fI\,}\/\fR...
+.SH DESCRIPTION
+Summary
+.PP
+Download and checkout a change
+.SH OPTIONS
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+show this help message and exit
+.TP
+\fB\-b\fR BRANCH, \fB\-\-branch\fR=\fI\,BRANCH\/\fR
+create a new branch first
+.TP
+\fB\-c\fR, \fB\-\-cherry\-pick\fR
+cherry\-pick instead of checkout
+.TP
+\fB\-x\fR, \fB\-\-record\-origin\fR
+pass \fB\-x\fR when cherry\-picking
+.TP
+\fB\-r\fR, \fB\-\-revert\fR
+revert instead of checkout
+.TP
+\fB\-f\fR, \fB\-\-ff\-only\fR
+force fast\-forward merge
+.SS Logging options:
+.TP
+\fB\-v\fR, \fB\-\-verbose\fR
+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
+.PP
+The 'repo download' command downloads a change from the review system and makes
+it available in your project's local working directory. If no project is
+specified try to use current directory as a project.

man/repo-forall.1

@@ -0,0 +1,146 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man.
+.TH REPO "1" "July 2022" "repo forall" "Repo Manual"
+.SH NAME
+repo \- repo forall - manual page for repo forall
+.SH SYNOPSIS
+.B repo
+\fI\,forall \/\fR[\fI\,<project>\/\fR...] \fI\,-c <command> \/\fR[\fI\,<arg>\/\fR...]
+.SH DESCRIPTION
+Summary
+.PP
+Run a shell command in each project
+.PP
+repo forall \fB\-r\fR str1 [str2] ... \fB\-c\fR <command> [<arg>...]
+.SH OPTIONS
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+show this help message and exit
+.TP
+\fB\-j\fR JOBS, \fB\-\-jobs\fR=\fI\,JOBS\/\fR
+number of jobs to run in parallel (default: based on
+number of CPU cores)
+.TP
+\fB\-r\fR, \fB\-\-regex\fR
+execute the command only on projects matching regex or
+wildcard expression
+.TP
+\fB\-i\fR, \fB\-\-inverse\-regex\fR
+execute the command only on projects not matching
+regex or wildcard expression
+.TP
+\fB\-g\fR GROUPS, \fB\-\-groups\fR=\fI\,GROUPS\/\fR
+execute the command only on projects matching the
+specified groups
+.TP
+\fB\-c\fR, \fB\-\-command\fR
+command (and arguments) to execute
+.TP
+\fB\-e\fR, \fB\-\-abort\-on\-errors\fR
+abort if a command exits unsuccessfully
+.TP
+\fB\-\-ignore\-missing\fR
+silently skip & do not exit non\-zero due missing
+checkouts
+.TP
+\fB\-\-interactive\fR
+force interactive usage
+.SS Logging options:
+.TP
+\fB\-v\fR, \fB\-\-verbose\fR
+show all output
+.TP
+\fB\-q\fR, \fB\-\-quiet\fR
+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
+.PP
+Executes the same shell command in each project.
+.PP
+The \fB\-r\fR option allows running the command only on projects matching regex or
+wildcard expression.
+.PP
+By default, projects are processed non\-interactively in parallel. If you want to
+run interactive commands, make sure to pass \fB\-\-interactive\fR to force \fB\-\-jobs\fR 1.
+While the processing order of projects is not guaranteed, the order of project
+output is stable.
+.PP
+Output Formatting
+.PP
+The \fB\-p\fR option causes 'repo forall' to bind pipes to the command's stdin, stdout
+and stderr streams, and pipe all output into a continuous stream that is
+displayed in a single pager session. Project headings are inserted before the
+output of each command is displayed. If the command produces no output in a
+project, no heading is displayed.
+.PP
+The formatting convention used by \fB\-p\fR is very suitable for some types of
+searching, e.g. `repo forall \fB\-p\fR \fB\-c\fR git log \fB\-SFoo\fR` will print all commits that
+add or remove references to Foo.
+.PP
+The \fB\-v\fR option causes 'repo forall' to display stderr messages if a command
+produces output only on stderr. Normally the \fB\-p\fR option causes command output to
+be suppressed until the command produces at least one byte of output on stdout.
+.PP
+Environment
+.PP
+pwd is the project's working directory. If the current client is a mirror
+client, then pwd is the Git repository.
+.PP
+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
+tracking branch. If you need to pass the manifest revision to a locally executed
+git command, use REPO_LREV.
+.PP
+REPO_RREV is the name of the revision from the manifest, exactly as written in
+the manifest.
+.PP
+REPO_COUNT is the total number of projects being iterated.
+.PP
+REPO_I is the current (1\-based) iteration count. Can be used in conjunction with
+REPO_COUNT to add a simple progress indicator to your command.
+.PP
+REPO__* are any extra environment variables, specified by the "annotation"
+element under any project element. This can be useful for differentiating trees
+based on user\-specific criteria, or simply annotating tree details.
+.PP
+shell positional arguments ($1, $2, .., $#) are set to any arguments following
+<command>.
+.PP
+Example: to list projects:
+.IP
+repo forall \fB\-c\fR 'echo $REPO_PROJECT'
+.PP
+Notice that $REPO_PROJECT is quoted to ensure it is expanded in the context of
+running <command> instead of in the calling shell.
+.PP
+Unless \fB\-p\fR is used, stdin, stdout, stderr are inherited from the terminal and are
+not redirected.
+.PP
+If \fB\-e\fR is used, when a command exits unsuccessfully, 'repo forall' will abort
+without iterating through the remaining projects.

man/repo-gc.1

@@ -0,0 +1,47 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man.
+.TH REPO "1" "April 2025" "repo gc" "Repo Manual"
+.SH NAME
+repo \- repo gc - manual page for repo gc
+.SH SYNOPSIS
+.B repo
+\fI\,gc\/\fR
+.SH DESCRIPTION
+Summary
+.PP
+Cleaning up internal repo and Git state.
+.SH OPTIONS
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+show this help message and exit
+.TP
+\fB\-n\fR, \fB\-\-dry\-run\fR
+do everything except actually delete
+.TP
+\fB\-y\fR, \fB\-\-yes\fR
+answer yes to all safe prompts
+.TP
+\fB\-\-repack\fR
+repack all projects that use partial clone with
+filter=blob:none
+.SS Logging options:
+.TP
+\fB\-v\fR, \fB\-\-verbose\fR
+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 gc` to view the detailed manual.

man/repo-grep.1

@@ -0,0 +1,132 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man.
+.TH REPO "1" "July 2022" "repo grep" "Repo Manual"
+.SH NAME
+repo \- repo grep - manual page for repo grep
+.SH SYNOPSIS
+.B repo
+\fI\,grep {pattern | -e pattern} \/\fR[\fI\,<project>\/\fR...]
+.SH DESCRIPTION
+Summary
+.PP
+Print lines matching a pattern
+.SH OPTIONS
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+show this help message and exit
+.TP
+\fB\-j\fR JOBS, \fB\-\-jobs\fR=\fI\,JOBS\/\fR
+number of jobs to run in parallel (default: based on
+number of CPU cores)
+.SS Logging options:
+.TP
+\fB\-\-verbose\fR
+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
+Search the index, instead of the work tree
+.TP
+\fB\-r\fR TREEish, \fB\-\-revision\fR=\fI\,TREEish\/\fR
+Search TREEish, instead of the work tree
+.SS Pattern:
+.TP
+\fB\-e\fR PATTERN
+Pattern to search for
+.TP
+\fB\-i\fR, \fB\-\-ignore\-case\fR
+Ignore case differences
+.TP
+\fB\-a\fR, \fB\-\-text\fR
+Process binary files as if they were text
+.TP
+\fB\-I\fR
+Don't match the pattern in binary files
+.TP
+\fB\-w\fR, \fB\-\-word\-regexp\fR
+Match the pattern only at word boundaries
+.TP
+\fB\-v\fR, \fB\-\-invert\-match\fR
+Select non\-matching lines
+.TP
+\fB\-G\fR, \fB\-\-basic\-regexp\fR
+Use POSIX basic regexp for patterns (default)
+.TP
+\fB\-E\fR, \fB\-\-extended\-regexp\fR
+Use POSIX extended regexp for patterns
+.TP
+\fB\-F\fR, \fB\-\-fixed\-strings\fR
+Use fixed strings (not regexp) for pattern
+.SS Pattern Grouping:
+.TP
+\fB\-\-all\-match\fR
+Limit match to lines that have all patterns
+.TP
+\fB\-\-and\fR, \fB\-\-or\fR, \fB\-\-not\fR
+Boolean operators to combine patterns
+.TP
+\-(, \-)
+Boolean operator grouping
+.SS Output:
+.TP
+\fB\-n\fR
+Prefix the line number to matching lines
+.TP
+\fB\-C\fR CONTEXT
+Show CONTEXT lines around match
+.TP
+\fB\-B\fR CONTEXT
+Show CONTEXT lines before match
+.TP
+\fB\-A\fR CONTEXT
+Show CONTEXT lines after match
+.TP
+\fB\-l\fR, \fB\-\-name\-only\fR, \fB\-\-files\-with\-matches\fR
+Show only file names containing matching lines
+.TP
+\fB\-L\fR, \fB\-\-files\-without\-match\fR
+Show only file names not containing matching lines
+.PP
+Run `repo help grep` to view the detailed manual.
+.SH DETAILS
+.PP
+Search for the specified patterns in all project files.
+.PP
+Boolean Options
+.PP
+The following options can appear as often as necessary to express the pattern to
+locate:
+.HP
+\fB\-e\fR PATTERN
+.HP
+\fB\-\-and\fR, \fB\-\-or\fR, \fB\-\-not\fR, \-(, \-)
+.PP
+Further, the \fB\-r\fR/\-\-revision option may be specified multiple times in order to
+scan multiple trees. If the same file matches in more than one tree, only the
+first result is reported, prefixed by the revision name it was found under.
+.PP
+Examples
+.PP
+Look for a line that has '#define' and either 'MAX_PATH or 'PATH_MAX':
+.IP
+repo grep \fB\-e\fR '#define' \fB\-\-and\fR \-\e( \fB\-e\fR MAX_PATH \fB\-e\fR PATH_MAX \e)
+.PP
+Look for a line that has 'NODE' or 'Unexpected' in files that contain a line
+that matches both expressions:
+.IP
+repo grep \fB\-\-all\-match\fR \fB\-e\fR NODE \fB\-e\fR Unexpected

man/repo-help.1

@@ -0,0 +1,46 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man.
+.TH REPO "1" "July 2022" "repo help" "Repo Manual"
+.SH NAME
+repo \- repo help - manual page for repo help
+.SH SYNOPSIS
+.B repo
+\fI\,help \/\fR[\fI\,--all|command\/\fR]
+.SH DESCRIPTION
+Summary
+.PP
+Display detailed help on a command
+.SH OPTIONS
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+show this help message and exit
+.TP
+\fB\-a\fR, \fB\-\-all\fR
+show the complete list of commands
+.TP
+\fB\-\-help\-all\fR
+show the \fB\-\-help\fR of all commands
+.SS Logging options:
+.TP
+\fB\-v\fR, \fB\-\-verbose\fR
+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
+.PP
+Displays detailed usage information about a command.

man/repo-info.1

@@ -0,0 +1,53 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man.
+.TH REPO "1" "July 2022" "repo info" "Repo Manual"
+.SH NAME
+repo \- repo info - manual page for repo info
+.SH SYNOPSIS
+.B repo
+\fI\,info \/\fR[\fI\,-dl\/\fR] [\fI\,-o \/\fR[\fI\,-c\/\fR]] [\fI\,<project>\/\fR...]
+.SH DESCRIPTION
+Summary
+.PP
+Get info on the manifest branch, current branch or unmerged branches
+.SH OPTIONS
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+show this help message and exit
+.TP
+\fB\-d\fR, \fB\-\-diff\fR
+show full info and commit diff including remote
+branches
+.TP
+\fB\-o\fR, \fB\-\-overview\fR
+show overview of all local commits
+.TP
+\fB\-c\fR, \fB\-\-current\-branch\fR
+consider only checked out branches
+.TP
+\fB\-\-no\-current\-branch\fR
+consider all local branches
+.TP
+\fB\-l\fR, \fB\-\-local\-only\fR
+disable all remote operations
+.SS Logging options:
+.TP
+\fB\-v\fR, \fB\-\-verbose\fR
+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.

man/repo-init.1

@@ -0,0 +1,204 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man.
+.TH REPO "1" "September 2024" "repo init" "Repo Manual"
+.SH NAME
+repo \- repo init - manual page for repo init
+.SH SYNOPSIS
+.B repo
+\fI\,init \/\fR[\fI\,options\/\fR] [\fI\,manifest url\/\fR]
+.SH DESCRIPTION
+Summary
+.PP
+Initialize a repo client checkout in the current directory
+.SH OPTIONS
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+show this help message and exit
+.SS Logging options:
+.TP
+\fB\-v\fR, \fB\-\-verbose\fR
+show all output
+.TP
+\fB\-q\fR, \fB\-\-quiet\fR
+only show errors
+.SS Manifest options:
+.TP
+\fB\-u\fR URL, \fB\-\-manifest\-url\fR=\fI\,URL\/\fR
+manifest repository location
+.TP
+\fB\-b\fR REVISION, \fB\-\-manifest\-branch\fR=\fI\,REVISION\/\fR
+manifest branch or revision (use HEAD for default)
+.TP
+\fB\-\-manifest\-upstream\-branch\fR=\fI\,BRANCH\/\fR
+when a commit is provided to \fB\-\-manifest\-branch\fR, this
+is the name of the git ref in which the commit can be
+found
+.TP
+\fB\-m\fR NAME.xml, \fB\-\-manifest\-name\fR=\fI\,NAME\/\fR.xml
+initial manifest file
+.TP
+\fB\-g\fR GROUP, \fB\-\-groups\fR=\fI\,GROUP\/\fR
+restrict manifest projects to ones with specified
+group(s) [default|all|G1,G2,G3|G4,\-G5,\-G6]
+.TP
+\fB\-p\fR PLATFORM, \fB\-\-platform\fR=\fI\,PLATFORM\/\fR
+restrict manifest projects to ones with a specified
+platform group [auto|all|none|linux|darwin|...]
+.TP
+\fB\-\-submodules\fR
+sync any submodules associated with the manifest repo
+.TP
+\fB\-\-standalone\-manifest\fR
+download the manifest as a static file rather then
+create a git checkout of the manifest repo
+.TP
+\fB\-\-manifest\-depth\fR=\fI\,DEPTH\/\fR
+create a shallow clone of the manifest repo with given
+depth (0 for full clone); see git clone (default: 0)
+.SS Manifest (only) checkout options:
+.TP
+\fB\-c\fR, \fB\-\-current\-branch\fR
+fetch only current manifest branch from server
+(default)
+.TP
+\fB\-\-no\-current\-branch\fR
+fetch all manifest branches from server
+.TP
+\fB\-\-tags\fR
+fetch tags in the manifest
+.TP
+\fB\-\-no\-tags\fR
+don't fetch tags in the manifest
+.SS Checkout modes:
+.TP
+\fB\-\-mirror\fR
+create a replica of the remote repositories rather
+than a client working directory
+.TP
+\fB\-\-archive\fR
+checkout an archive instead of a git repository for
+each project. See git archive.
+.TP
+\fB\-\-worktree\fR
+use git\-worktree to manage projects
+.SS Project checkout optimizations:
+.TP
+\fB\-\-reference\fR=\fI\,DIR\/\fR
+location of mirror directory
+.TP
+\fB\-\-dissociate\fR
+dissociate from reference mirrors after clone
+.TP
+\fB\-\-depth\fR=\fI\,DEPTH\/\fR
+create a shallow clone with given depth; see git clone
+.TP
+\fB\-\-partial\-clone\fR
+perform partial clone (https://gitscm.com/docs/gitrepositorylayout#_code_partialclone_code)
+.TP
+\fB\-\-no\-partial\-clone\fR
+disable use of partial clone (https://gitscm.com/docs/gitrepositorylayout#_code_partialclone_code)
+.TP
+\fB\-\-partial\-clone\-exclude\fR=\fI\,PARTIAL_CLONE_EXCLUDE\/\fR
+exclude the specified projects (a comma\-delimited
+project names) from partial clone (https://gitscm.com/docs/gitrepositorylayout#_code_partialclone_code)
+.TP
+\fB\-\-clone\-filter\fR=\fI\,CLONE_FILTER\/\fR
+filter for use with \fB\-\-partial\-clone\fR [default:
+blob:none]
+.TP
+\fB\-\-use\-superproject\fR
+use the manifest superproject to sync projects;
+implies \fB\-c\fR
+.TP
+\fB\-\-no\-use\-superproject\fR
+disable use of manifest superprojects
+.TP
+\fB\-\-clone\-bundle\fR
+enable use of \fI\,/clone.bundle\/\fP on HTTP/HTTPS (default if
+not \fB\-\-partial\-clone\fR)
+.TP
+\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
+repo repository location ($REPO_URL)
+.TP
+\fB\-\-repo\-rev\fR=\fI\,REV\/\fR
+repo branch or revision ($REPO_REV)
+.TP
+\fB\-\-no\-repo\-verify\fR
+do not verify repo source code
+.SS Other options:
+.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
+.PP
+The 'repo init' command is run once to install and initialize repo. The latest
+repo source code and manifest collection is downloaded from the server and is
+installed in the .repo/ directory in the current working directory.
+.PP
+When creating a new checkout, the manifest URL is the only required setting. It
+may be specified using the \fB\-\-manifest\-url\fR option, or as the first optional
+argument.
+.PP
+The optional \fB\-b\fR argument can be used to select the manifest branch to checkout
+and use. If no branch is specified, the remote's default branch is used. This is
+equivalent to using \fB\-b\fR HEAD.
+.PP
+The optional \fB\-\-manifest\-upstream\-branch\fR argument can be used when a commit is
+provided to \fB\-\-manifest\-branch\fR (or \fB\-b\fR), to specify the name of the git ref in
+which the commit can be found.
+.PP
+The optional \fB\-m\fR argument can be used to specify an alternate manifest to be
+used. If no manifest is specified, the manifest default.xml will be used.
+.PP
+If the \fB\-\-standalone\-manifest\fR argument is set, the manifest will be downloaded
+directly from the specified \fB\-\-manifest\-url\fR as a static file (rather than setting
+up a manifest git checkout). With \fB\-\-standalone\-manifest\fR, the manifest will be
+fully static and will not be re\-downloaded during subsesquent `repo init` and
+`repo sync` calls.
+.PP
+The \fB\-\-reference\fR option can be used to point to a directory that has the content
+of a \fB\-\-mirror\fR sync. This will make the working directory use as much data as
+possible from the local reference directory when fetching from the server. This
+will make the sync go a lot faster by reducing data traffic on the network.
+.PP
+The \fB\-\-dissociate\fR option can be used to borrow the objects from the directory
+specified with the \fB\-\-reference\fR option only to reduce network transfer, and stop
+borrowing from them after a first clone is made by making necessary local copies
+of borrowed objects.
+.PP
+The \fB\-\-no\-clone\-bundle\fR option disables any attempt to use \fI\,$URL/clone.bundle\/\fP to
+bootstrap a new Git repository from a resumeable bundle file on a content
+delivery network. This may be necessary if there are problems with the local
+Python HTTP client or proxy configuration, but the Git binary works.
+.PP
+Switching Manifest Branches
+.PP
+To switch to another manifest branch, `repo init \fB\-b\fR otherbranch` may be used in
+an existing client. However, as this only updates the manifest, a subsequent
+`repo sync` (or `repo sync \fB\-d\fR`) is necessary to update the working directory
+files.

man/repo-list.1

@@ -0,0 +1,74 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man.
+.TH REPO "1" "July 2022" "repo list" "Repo Manual"
+.SH NAME
+repo \- repo list - manual page for repo list
+.SH SYNOPSIS
+.B repo
+\fI\,list \/\fR[\fI\,-f\/\fR] [\fI\,<project>\/\fR...]
+.SH DESCRIPTION
+Summary
+.PP
+List projects and their associated directories
+.PP
+repo list [\-f] \fB\-r\fR str1 [str2]...
+.SH OPTIONS
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+show this help message and exit
+.TP
+\fB\-r\fR, \fB\-\-regex\fR
+filter the project list based on regex or wildcard
+matching of strings
+.TP
+\fB\-g\fR GROUPS, \fB\-\-groups\fR=\fI\,GROUPS\/\fR
+filter the project list based on the groups the
+project is in
+.TP
+\fB\-a\fR, \fB\-\-all\fR
+show projects regardless of checkout state
+.TP
+\fB\-n\fR, \fB\-\-name\-only\fR
+display only the name of the repository
+.TP
+\fB\-p\fR, \fB\-\-path\-only\fR
+display only the path of the repository
+.TP
+\fB\-f\fR, \fB\-\-fullpath\fR
+display the full work tree path instead of the
+relative path
+.TP
+\fB\-\-relative\-to\fR=\fI\,PATH\/\fR
+display paths relative to this one (default: top of
+repo client checkout)
+.SS Logging options:
+.TP
+\fB\-v\fR, \fB\-\-verbose\fR
+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
+.PP
+List all projects; pass '.' to list the project for the cwd.
+.PP
+By default, only projects that currently exist in the checkout are shown. If you
+want to list all projects (using the specified filter settings), use the \fB\-\-all\fR
+option. If you want to show all projects regardless of the manifest groups, then
+also pass \fB\-\-groups\fR all.
+.PP
+This is similar to running: repo forall \fB\-c\fR 'echo "$REPO_PATH : $REPO_PROJECT"'.

man/repo-manifest.1

@@ -0,0 +1,671 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man.
+.TH REPO "1" "April 2025" "repo manifest" "Repo Manual"
+.SH NAME
+repo \- repo manifest - manual page for repo manifest
+.SH SYNOPSIS
+.B repo
+\fI\,manifest \/\fR[\fI\,-o {-|NAME.xml}\/\fR] [\fI\,-m MANIFEST.xml\/\fR] [\fI\,-r\/\fR]
+.SH DESCRIPTION
+Summary
+.PP
+Manifest inspection utility
+.SH OPTIONS
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+show this help message and exit
+.TP
+\fB\-r\fR, \fB\-\-revision\-as\-HEAD\fR
+save revisions as current HEAD
+.TP
+\fB\-m\fR NAME.xml, \fB\-\-manifest\-name\fR=\fI\,NAME\/\fR.xml
+temporary manifest to use for this sync
+.TP
+\fB\-\-suppress\-upstream\-revision\fR
+if in \fB\-r\fR mode, do not write the upstream field (only
+of use if the branch names for a sha1 manifest are
+sensitive)
+.TP
+\fB\-\-suppress\-dest\-branch\fR
+if in \fB\-r\fR mode, do not write the dest\-branch field
+(only of use if the branch names for a sha1 manifest
+are sensitive)
+.TP
+\fB\-\-format\fR=\fI\,FORMAT\/\fR
+output format: xml, json (default: xml)
+.TP
+\fB\-\-pretty\fR
+format output for humans to read
+.TP
+\fB\-\-no\-local\-manifests\fR
+ignore local manifests
+.TP
+\fB\-o\fR \-|NAME.xml, \fB\-\-output\-file\fR=\fI\,\-\/\fR|NAME.xml
+file to save the manifest to. (Filename prefix for
+multi\-tree.)
+.SS Logging options:
+.TP
+\fB\-v\fR, \fB\-\-verbose\fR
+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
+.PP
+With the \fB\-o\fR option, exports the current manifest for inspection. The manifest
+and (if present) local_manifests/ are combined together to produce a single
+manifest file. This file can be stored in a Git repository for use during future
+\&'repo init' invocations.
+.PP
+The \fB\-r\fR option can be used to generate a manifest file with project revisions set
+to the current commit hash. These are known as "revision locked manifests", as
+they don't follow a particular branch. In this case, the 'upstream' attribute is
+set to the ref we were on when the manifest was generated. The 'dest\-branch'
+attribute is set to indicate the remote ref to push changes to via 'repo
+upload'.
+.PP
+Multiple output formats are supported via \fB\-\-format\fR. The default output is XML,
+and formats are generally "condensed". Use \fB\-\-pretty\fR for more human\-readable
+variations.
+.PP
+repo Manifest Format
+.PP
+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.
+.PP
+The basic structure of a manifest is a bare Git repository holding a single
+`default.xml` XML file in the top level directory.
+.PP
+Manifests are inherently version controlled, since they are kept within a Git
+repository. Updates to manifests are automatically obtained by clients during
+`repo sync`.
+.PP
+[TOC]
+.PP
+XML File Format
+.PP
+A manifest XML file (e.g. `default.xml`) roughly conforms to the following DTD:
+.PP
+```xml <!DOCTYPE manifest [
+.TP
+<!ELEMENT manifest (notice?,
+remote*,
+default?,
+manifest\-server?,
+submanifest*?,
+remove\-project*,
+project*,
+extend\-project*,
+repo\-hooks?,
+superproject?,
+contactinfo?,
+include*)>
+.IP
+<!ELEMENT notice (#PCDATA)>
+.IP
+<!ELEMENT remote (annotation*)>
+<!ATTLIST remote name         ID    #REQUIRED>
+<!ATTLIST remote alias        CDATA #IMPLIED>
+<!ATTLIST remote fetch        CDATA #REQUIRED>
+<!ATTLIST remote pushurl      CDATA #IMPLIED>
+<!ATTLIST remote review       CDATA #IMPLIED>
+<!ATTLIST remote revision     CDATA #IMPLIED>
+.IP
+<!ELEMENT default EMPTY>
+<!ATTLIST default remote      IDREF #IMPLIED>
+<!ATTLIST default revision    CDATA #IMPLIED>
+<!ATTLIST default dest\-branch CDATA #IMPLIED>
+<!ATTLIST default upstream    CDATA #IMPLIED>
+<!ATTLIST default sync\-j      CDATA #IMPLIED>
+<!ATTLIST default sync\-c      CDATA #IMPLIED>
+<!ATTLIST default sync\-s      CDATA #IMPLIED>
+<!ATTLIST default sync\-tags   CDATA #IMPLIED>
+.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*,
+copyfile*,
+linkfile*)>
+.TP
+<!ATTLIST project name
+CDATA #REQUIRED>
+.TP
+<!ATTLIST project path
+CDATA #IMPLIED>
+.TP
+<!ATTLIST project remote
+IDREF #IMPLIED>
+.TP
+<!ATTLIST project revision
+CDATA #IMPLIED>
+.IP
+<!ATTLIST project dest\-branch CDATA #IMPLIED>
+<!ATTLIST project groups      CDATA #IMPLIED>
+<!ATTLIST project sync\-c      CDATA #IMPLIED>
+<!ATTLIST project sync\-s      CDATA #IMPLIED>
+<!ATTLIST project sync\-tags   CDATA #IMPLIED>
+<!ATTLIST project upstream CDATA #IMPLIED>
+<!ATTLIST project clone\-depth CDATA #IMPLIED>
+<!ATTLIST project force\-path CDATA #IMPLIED>
+.IP
+<!ELEMENT annotation EMPTY>
+<!ATTLIST annotation name  CDATA #REQUIRED>
+<!ATTLIST annotation value CDATA #REQUIRED>
+<!ATTLIST annotation keep  CDATA "true">
+.IP
+<!ELEMENT copyfile EMPTY>
+<!ATTLIST copyfile src  CDATA #REQUIRED>
+<!ATTLIST copyfile dest CDATA #REQUIRED>
+.IP
+<!ELEMENT linkfile EMPTY>
+<!ATTLIST linkfile src CDATA #REQUIRED>
+<!ATTLIST linkfile dest CDATA #REQUIRED>
+.IP
+<!ELEMENT extend\-project EMPTY>
+<!ATTLIST extend\-project name CDATA #REQUIRED>
+<!ATTLIST extend\-project path CDATA #IMPLIED>
+<!ATTLIST extend\-project dest\-path CDATA #IMPLIED>
+<!ATTLIST extend\-project groups CDATA #IMPLIED>
+<!ATTLIST extend\-project revision CDATA #IMPLIED>
+<!ATTLIST extend\-project remote CDATA #IMPLIED>
+<!ATTLIST extend\-project dest\-branch CDATA #IMPLIED>
+<!ATTLIST extend\-project upstream CDATA #IMPLIED>
+<!ATTLIST extend\-project base\-rev CDATA #IMPLIED>
+.IP
+<!ELEMENT remove\-project EMPTY>
+<!ATTLIST remove\-project name     CDATA #IMPLIED>
+<!ATTLIST remove\-project path     CDATA #IMPLIED>
+<!ATTLIST remove\-project optional CDATA #IMPLIED>
+<!ATTLIST remove\-project base\-rev CDATA #IMPLIED>
+.IP
+<!ELEMENT repo\-hooks EMPTY>
+<!ATTLIST repo\-hooks in\-project CDATA #REQUIRED>
+<!ATTLIST repo\-hooks enabled\-list CDATA #REQUIRED>
+.IP
+<!ELEMENT superproject EMPTY>
+<!ATTLIST superproject name     CDATA #REQUIRED>
+<!ATTLIST superproject remote   IDREF #IMPLIED>
+<!ATTLIST superproject revision CDATA #IMPLIED>
+.IP
+<!ELEMENT contactinfo EMPTY>
+<!ATTLIST contactinfo bugurl  CDATA #REQUIRED>
+.IP
+<!ELEMENT include EMPTY>
+<!ATTLIST include name     CDATA #REQUIRED>
+<!ATTLIST include groups   CDATA #IMPLIED>
+<!ATTLIST include revision CDATA #IMPLIED>
+.PP
+]>
+```
+.PP
+For compatibility purposes across repo releases, all unknown elements are
+silently ignored. However, repo reserves all possible names for itself for
+future use. If you want to use custom elements, the `x\-*` namespace is reserved
+for that purpose, and repo guarantees to never allocate any corresponding names.
+.PP
+A description of the elements and their attributes follows.
+.PP
+Element manifest
+.PP
+The root element of the file.
+.PP
+Element notice
+.PP
+Arbitrary text that is displayed to users whenever `repo sync` finishes. The
+content is simply passed through as it exists in the manifest.
+.PP
+Element remote
+.PP
+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.
+.PP
+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`.
+.PP
+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.
+.PP
+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.
+.PP
+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.
+.PP
+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.
+.PP
+Attribute `revision`: Name of a Git branch (e.g. `main` or `refs/heads/main`).
+Remotes with their own revision will override the default revision.
+.PP
+Element default
+.PP
+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.
+.PP
+Attribute `remote`: Name of a previously defined remote element. Project
+elements lacking a remote attribute of their own will use this remote.
+.PP
+Attribute `revision`: Name of a Git branch (e.g. `main` or `refs/heads/main`).
+Project elements lacking their own revision attribute will use this revision.
+.PP
+Attribute `dest\-branch`: Name of a Git branch (e.g. `main`). 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.
+.PP
+Attribute `upstream`: Name of the Git ref in which a sha1 can be found. Used
+when syncing a revision locked manifest in \fB\-c\fR mode to avoid having to sync the
+entire ref space. Project elements not setting their own `upstream` will inherit
+this value.
+.PP
+Attribute `sync\-j`: Number of parallel jobs to use when synching.
+.PP
+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.
+.PP
+Attribute `sync\-s`: Set to true to also sync sub\-projects.
+.PP
+Attribute `sync\-tags`: Set to false to only sync the given Git branch (specified
+in the `revision` attribute) rather than the other ref tags.
+.PP
+Element manifest\-server
+.PP
+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.
+.PP
+See the [smart sync documentation](./smart\-sync.md) for more details.
+.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
+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.
+.PP
+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:
+.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
+"name" 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. These restrictions are not enforced for [Local
+Manifests].
+.PP
+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.
+.PP
+"path" may not be an absolute path or use "." or ".." path components. These
+restrictions are not enforced for [Local Manifests].
+.PP
+If you want to place files into the root of the checkout (e.g. a README or
+Makefile or another build script), use the [copyfile] or [linkfile] elements
+instead.
+.PP
+Attribute `remote`: Name of a previously defined remote element. If not supplied
+the remote given by the default element is used.
+.PP
+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 "main") or absolute
+(e.g. "refs/heads/main"). 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.
+.PP
+Attribute `dest\-branch`: Name of a Git branch (e.g. `main`). 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.
+.PP
+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
+`<project name="monkeys" path="barrel\-of"/>`, 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.
+.PP
+Attribute `sync\-c`: Set to true to only sync the given Git branch (specified in
+the `revision` attribute) rather than the whole ref space.
+.PP
+Attribute `sync\-s`: Set to true to also sync sub\-projects.
+.PP
+Attribute `upstream`: Name of the Git ref in which a sha1 can be found. Used
+when syncing a revision locked manifest in \fB\-c\fR mode to avoid having to sync the
+entire ref space.
+.PP
+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
+\fB\-\-depth\fR option on the command line.
+.PP
+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.
+.PP
+Element extend\-project
+.PP
+Modify the attributes of the named project.
+.PP
+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.
+.PP
+Attribute `path`: If specified, limit the change to projects checked out at the
+specified path, rather than all projects with the given name.
+.PP
+Attribute `dest\-path`: If specified, a path relative to the top directory of the
+repo client where the Git working directory for this project should be placed.
+This is used to move a project in the checkout by overriding the existing `path`
+setting.
+.PP
+Attribute `groups`: List of additional groups to which this project belongs.
+Same syntax as the corresponding element of `project`.
+.PP
+Attribute `revision`: If specified, overrides the revision of the original
+project. Same syntax as the corresponding element of `project`.
+.PP
+Attribute `remote`: If specified, overrides the remote of the original project.
+Same syntax as the corresponding element of `project`.
+.PP
+Attribute `dest\-branch`: If specified, overrides the dest\-branch of the original
+project. Same syntax as the corresponding element of `project`.
+.PP
+Attribute `upstream`: If specified, overrides the upstream of the original
+project. Same syntax as the corresponding element of `project`.
+.PP
+Attribute `base\-rev`: If specified, adds a check against the revision to be
+extended. Manifest parse will fail and give a list of mismatch extends if the
+revisions being extended have changed since base\-rev was set. Intended for use
+with layered manifests using hash revisions to prevent patch branches hiding
+newer upstream revisions. Also compares named refs like branches or tags but is
+misleading if branches are used as base\-rev. Same syntax as the corresponding
+element of `project`.
+.PP
+Element annotation
+.PP
+Zero or more annotation elements may be specified as children of a project or
+remote element. Each element describes a name\-value pair. For projects, this
+name\-value pair 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.
+.PP
+Element copyfile
+.PP
+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.
+.PP
+"src" is project relative, "dest" is relative to the top of the tree. Copying
+from paths outside of the project or to paths outside of the repo client is not
+allowed.
+.PP
+"src" and "dest" must be files. Directories or symlinks are not allowed.
+Intermediate paths must not be symlinks either.
+.PP
+Parent directories of "dest" will be automatically created if missing.
+.PP
+Element linkfile
+.PP
+It's just like copyfile and runs at the same time as copyfile but instead of
+copying it creates a symlink.
+.PP
+The symlink is created at "dest" (relative to the top of the tree) and points to
+the path specified by "src" which is a path in the project.
+.PP
+Parent directories of "dest" will be automatically created if missing.
+.PP
+The symlink target may be a file or directory, but it may not point outside of
+the repo client.
+.PP
+Element remove\-project
+.PP
+Deletes a 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.
+.PP
+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.
+.PP
+The project `name` or project `path` can be used to specify the remove target
+meaning one of them is required. If only name is specified, all projects with
+that name are removed.
+.PP
+If both name and path are specified, only projects with the same name and path
+are removed, meaning projects with the same name but in other locations are
+kept.
+.PP
+If only path is specified, a matching project is removed regardless of its name.
+Logic otherwise behaves like both are specified.
+.PP
+Attribute `optional`: Set to true to ignore remove\-project elements with no
+matching `project` element.
+.PP
+Attribute `base\-rev`: If specified, adds a check against the revision to be
+removed. Manifest parse will fail and give a list of mismatch removes if the
+revisions being removed have changed since base\-rev was set. Intended for use
+with layered manifests using hash revisions to prevent patch branches hiding
+newer upstream revisions. Also compares named refs like branches or tags but is
+misleading if branches are used as base\-rev. Same syntax as the corresponding
+element of `project`.
+.PP
+Element repo\-hooks
+.PP
+NB: See the [practical documentation](./repo\-hooks.md) for using repo hooks.
+.PP
+Only one repo\-hooks element may be specified at a time. Attempting to redefine
+it will fail to parse.
+.PP
+Attribute `in\-project`: The project where the hooks are defined. The value must
+match the `name` attribute (**not** the `path` attribute) of a previously
+defined `project` element.
+.PP
+Attribute `enabled\-list`: List of hooks to use, whitespace or comma separated.
+.PP
+Element superproject
+.PP
+*** *Note*: This is currently a WIP. ***
+.PP
+NB: See the [git superprojects documentation](
+https://en.wikibooks.org/wiki/Git/Submodules_and_Superprojects) for background
+information.
+.PP
+This element is used to specify the URL of the superproject. It has "name" and
+"remote" as atrributes. Only "name" is required while the others have reasonable
+defaults. At most one superproject may be specified. Attempting to redefine it
+will fail to parse.
+.PP
+Attribute `name`: A unique name for the superproject. This attribute has the
+same meaning as project's name attribute. See the [element
+project](#element\-project) for more information.
+.PP
+Attribute `remote`: Name of a previously defined remote element. If not supplied
+the remote given by the default element is used.
+.PP
+Attribute `revision`: Name of the Git branch the manifest wants to track for
+this superproject. If not supplied the revision given by the remote element is
+used if applicable, else the default element is used.
+.PP
+Element contactinfo
+.PP
+*** *Note*: This is currently a WIP. ***
+.PP
+This element is used to let manifest authors self\-register contact info. It has
+"bugurl" as a required atrribute. This element can be repeated, and any later
+entries will clobber earlier ones. This would allow manifest authors who extend
+manifests to specify their own contact info.
+.PP
+Attribute `bugurl`: The URL to file a bug against the manifest owner.
+.PP
+Element include
+.PP
+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.
+.PP
+Attribute `name`: the manifest to include, specified relative to the manifest
+repository's root.
+.PP
+"name" may not be an absolute path or use "." or ".." path components. These
+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
+included manifests carry all parent include groups. Same syntax as the
+corresponding element of `project`.
+.PP
+Attribute `revision`: Name of a Git branch (e.g. `main` or `refs/heads/main`)
+default to which all projects in the included manifest belong.
+.PP
+Local Manifests
+.PP
+Additional remotes and projects may be added through local manifest files stored
+in `$TOP_DIR/.repo/local_manifests/*.xml`.
+.PP
+For example:
+.IP
+\f(CW$ ls .repo/local_manifests\fR
+.IP
+local_manifest.xml
+another_local_manifest.xml
+.IP
+\f(CW$ cat .repo/local_manifests/local_manifest.xml\fR
+.IP
+<?xml version="1.0" encoding="UTF\-8"?>
+<manifest>
+.IP
+<project path="manifest"
+.IP
+name="tools/manifest" />
+.IP
+<project path="platform\-manifest"
+.IP
+name="platform/manifest" />
+.IP
+</manifest>
+.PP
+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.
+.PP
+Manifest files stored in `$TOP_DIR/.repo/local_manifests/*.xml` will be loaded
+in alphabetical order.
+.PP
+Projects from local manifest files are added into local::<local manifest
+filename> group.
+.PP
+The legacy `$TOP_DIR/.repo/local_manifest.xml` path is no longer supported.
+.SS [copyfile]: #Element\-copyfile [linkfile]: #Element\-linkfile [Local Manifests]:
+.PP
+#local\-manifests

man/repo-overview.1

@@ -0,0 +1,52 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man.
+.TH REPO "1" "July 2022" "repo overview" "Repo Manual"
+.SH NAME
+repo \- repo overview - manual page for repo overview
+.SH SYNOPSIS
+.B repo
+\fI\,overview \/\fR[\fI\,--current-branch\/\fR] [\fI\,<project>\/\fR...]
+.SH DESCRIPTION
+Summary
+.PP
+Display overview of unmerged project branches
+.SH OPTIONS
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+show this help message and exit
+.TP
+\fB\-c\fR, \fB\-\-current\-branch\fR
+consider only checked out branches
+.TP
+\fB\-\-no\-current\-branch\fR
+consider all local branches
+.SS Logging options:
+.TP
+\fB\-v\fR, \fB\-\-verbose\fR
+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
+.PP
+The 'repo overview' command is used to display an overview of the projects
+branches, and list any local commits that have not yet been merged into the
+project.
+.PP
+The \fB\-c\fR/\-\-current\-branch option can be used to restrict the output to only
+branches currently checked out in each project. By default, all branches are
+displayed.

man/repo-prune.1

@@ -0,0 +1,41 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man.
+.TH REPO "1" "July 2022" "repo prune" "Repo Manual"
+.SH NAME
+repo \- repo prune - manual page for repo prune
+.SH SYNOPSIS
+.B repo
+\fI\,prune \/\fR[\fI\,<project>\/\fR...]
+.SH DESCRIPTION
+Summary
+.PP
+Prune (delete) already merged topics
+.SH OPTIONS
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+show this help message and exit
+.TP
+\fB\-j\fR JOBS, \fB\-\-jobs\fR=\fI\,JOBS\/\fR
+number of jobs to run in parallel (default: based on
+number of CPU cores)
+.SS Logging options:
+.TP
+\fB\-v\fR, \fB\-\-verbose\fR
+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.

man/repo-rebase.1

@@ -0,0 +1,68 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man.
+.TH REPO "1" "July 2022" "repo rebase" "Repo Manual"
+.SH NAME
+repo \- repo rebase - manual page for repo rebase
+.SH SYNOPSIS
+.B repo
+\fI\,rebase {\/\fR[\fI\,<project>\/\fR...] \fI\,| -i <project>\/\fR...\fI\,}\/\fR
+.SH DESCRIPTION
+Summary
+.PP
+Rebase local branches on upstream branch
+.SH OPTIONS
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+show this help message and exit
+.TP
+\fB\-\-fail\-fast\fR
+stop rebasing after first error is hit
+.TP
+\fB\-f\fR, \fB\-\-force\-rebase\fR
+pass \fB\-\-force\-rebase\fR to git rebase
+.TP
+\fB\-\-no\-ff\fR
+pass \fB\-\-no\-ff\fR to git rebase
+.TP
+\fB\-\-autosquash\fR
+pass \fB\-\-autosquash\fR to git rebase
+.TP
+\fB\-\-whitespace\fR=\fI\,WS\/\fR
+pass \fB\-\-whitespace\fR to git rebase
+.TP
+\fB\-\-auto\-stash\fR
+stash local modifications before starting
+.TP
+\fB\-m\fR, \fB\-\-onto\-manifest\fR
+rebase onto the manifest version instead of upstream
+HEAD (this helps to make sure the local tree stays
+consistent if you previously synced to a manifest)
+.SS Logging options:
+.TP
+\fB\-v\fR, \fB\-\-verbose\fR
+show all output
+.TP
+\fB\-q\fR, \fB\-\-quiet\fR
+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
+.PP
+\&'repo rebase' uses git rebase to move local changes in the current topic branch
+to the HEAD of the upstream history, useful when you have made commits in a
+topic branch but need to incorporate new upstream changes "underneath" them.

man/repo-selfupdate.1

@@ -0,0 +1,48 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man.
+.TH REPO "1" "July 2022" "repo selfupdate" "Repo Manual"
+.SH NAME
+repo \- repo selfupdate - manual page for repo selfupdate
+.SH SYNOPSIS
+.B repo
+\fI\,selfupdate\/\fR
+.SH DESCRIPTION
+Summary
+.PP
+Update repo to the latest version
+.SH OPTIONS
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+show this help message and exit
+.SS Logging options:
+.TP
+\fB\-v\fR, \fB\-\-verbose\fR
+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
+do not verify repo source code
+.PP
+Run `repo help selfupdate` to view the detailed manual.
+.SH DETAILS
+.PP
+The 'repo selfupdate' command upgrades repo to the latest version, if a newer
+version is available.
+.PP
+Normally this is done automatically by 'repo sync' and does not need to be
+performed by an end\-user.

man/repo-smartsync.1

@@ -0,0 +1,156 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man.
+.TH REPO "1" "June 2025" "repo smartsync" "Repo Manual"
+.SH NAME
+repo \- repo smartsync - manual page for repo smartsync
+.SH SYNOPSIS
+.B repo
+\fI\,smartsync \/\fR[\fI\,<project>\/\fR...]
+.SH DESCRIPTION
+Summary
+.PP
+Update working tree to the latest known good revision
+.SH OPTIONS
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+show this help message and exit
+.TP
+\fB\-j\fR JOBS, \fB\-\-jobs\fR=\fI\,JOBS\/\fR
+number of jobs to run in parallel (default: based on
+number of CPU cores)
+.TP
+\fB\-\-jobs\-network\fR=\fI\,JOBS\/\fR
+number of network jobs to run in parallel (defaults to
+\fB\-\-jobs\fR or 1). Ignored when \fB\-\-interleaved\fR is set
+.TP
+\fB\-\-jobs\-checkout\fR=\fI\,JOBS\/\fR
+number of local checkout jobs to run in parallel
+(defaults to \fB\-\-jobs\fR or 8). Ignored when \fB\-\-interleaved\fR
+is set
+.TP
+\fB\-f\fR, \fB\-\-force\-broken\fR
+obsolete option (to be deleted in the future)
+.TP
+\fB\-\-fail\-fast\fR
+stop syncing after first error is hit
+.TP
+\fB\-\-force\-sync\fR
+overwrite an existing git directory if it needs to
+point to a different object directory. WARNING: this
+may cause loss of data
+.TP
+\fB\-\-force\-checkout\fR
+force checkout even if it results in throwing away
+uncommitted modifications. WARNING: this may cause
+loss of data
+.TP
+\fB\-\-force\-remove\-dirty\fR
+force remove projects with uncommitted modifications
+if projects no longer exist in the manifest. WARNING:
+this may cause loss of data
+.TP
+\fB\-\-rebase\fR
+rebase local commits regardless of whether they are
+published
+.TP
+\fB\-l\fR, \fB\-\-local\-only\fR
+only update working tree, don't fetch
+.TP
+\fB\-\-no\-manifest\-update\fR, \fB\-\-nmu\fR
+use the existing manifest checkout as\-is. (do not
+update to the latest revision)
+.TP
+\fB\-\-interleaved\fR
+fetch and checkout projects in parallel (experimental)
+.TP
+\fB\-n\fR, \fB\-\-network\-only\fR
+fetch only, don't update working tree
+.TP
+\fB\-d\fR, \fB\-\-detach\fR
+detach projects back to manifest revision
+.TP
+\fB\-c\fR, \fB\-\-current\-branch\fR
+fetch only current branch from server
+.TP
+\fB\-\-no\-current\-branch\fR
+fetch all branches from server
+.TP
+\fB\-m\fR NAME.xml, \fB\-\-manifest\-name\fR=\fI\,NAME\/\fR.xml
+temporary manifest to use for this sync
+.TP
+\fB\-\-clone\-bundle\fR
+enable use of \fI\,/clone.bundle\/\fP on HTTP/HTTPS
+.TP
+\fB\-\-no\-clone\-bundle\fR
+disable use of \fI\,/clone.bundle\/\fP on HTTP/HTTPS
+.TP
+\fB\-u\fR MANIFEST_SERVER_USERNAME, \fB\-\-manifest\-server\-username\fR=\fI\,MANIFEST_SERVER_USERNAME\/\fR
+username to authenticate with the manifest server
+.TP
+\fB\-p\fR MANIFEST_SERVER_PASSWORD, \fB\-\-manifest\-server\-password\fR=\fI\,MANIFEST_SERVER_PASSWORD\/\fR
+password to authenticate with the manifest server
+.TP
+\fB\-\-fetch\-submodules\fR
+fetch submodules from server
+.TP
+\fB\-\-use\-superproject\fR
+use the manifest superproject to sync projects;
+implies \fB\-c\fR
+.TP
+\fB\-\-no\-use\-superproject\fR
+disable use of manifest superprojects
+.TP
+\fB\-\-tags\fR
+fetch tags
+.TP
+\fB\-\-no\-tags\fR
+don't fetch tags (default)
+.TP
+\fB\-\-optimized\-fetch\fR
+only fetch projects fixed to sha1 if revision does not
+exist locally
+.TP
+\fB\-\-retry\-fetches\fR=\fI\,RETRY_FETCHES\/\fR
+number of times to retry fetches on transient errors
+.TP
+\fB\-\-prune\fR
+delete refs that no longer exist on the remote
+(default)
+.TP
+\fB\-\-no\-prune\fR
+do not delete refs that no longer exist on the remote
+.TP
+\fB\-\-auto\-gc\fR
+run garbage collection on all synced projects
+.TP
+\fB\-\-no\-auto\-gc\fR
+do not run garbage collection on any projects
+(default)
+.SS Logging options:
+.TP
+\fB\-v\fR, \fB\-\-verbose\fR
+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
+do not verify repo source code
+.PP
+Run `repo help smartsync` to view the detailed manual.
+.SH DETAILS
+.PP
+The 'repo smartsync' command is a shortcut for sync \fB\-s\fR.

man/repo-stage.1

@@ -0,0 +1,43 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man.
+.TH REPO "1" "July 2022" "repo stage" "Repo Manual"
+.SH NAME
+repo \- repo stage - manual page for repo stage
+.SH SYNOPSIS
+.B repo
+\fI\,stage -i \/\fR[\fI\,<project>\/\fR...]
+.SH DESCRIPTION
+Summary
+.PP
+Stage file(s) for commit
+.SH OPTIONS
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+show this help message and exit
+.SS Logging options:
+.TP
+\fB\-v\fR, \fB\-\-verbose\fR
+show all output
+.TP
+\fB\-q\fR, \fB\-\-quiet\fR
+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
+.PP
+The 'repo stage' command stages files to prepare the next commit.

man/repo-start.1

@@ -0,0 +1,54 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man.
+.TH REPO "1" "July 2022" "repo start" "Repo Manual"
+.SH NAME
+repo \- repo start - manual page for repo start
+.SH SYNOPSIS
+.B repo
+\fI\,start <newbranchname> \/\fR[\fI\,--all | <project>\/\fR...]
+.SH DESCRIPTION
+Summary
+.PP
+Start a new branch for development
+.SH OPTIONS
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+show this help message and exit
+.TP
+\fB\-j\fR JOBS, \fB\-\-jobs\fR=\fI\,JOBS\/\fR
+number of jobs to run in parallel (default: based on
+number of CPU cores)
+.TP
+\fB\-\-all\fR
+begin branch in all projects
+.TP
+\fB\-r\fR REVISION, \fB\-\-rev\fR=\fI\,REVISION\/\fR, \fB\-\-revision\fR=\fI\,REVISION\/\fR
+point branch at this revision instead of upstream
+.TP
+\fB\-\-head\fR, \fB\-\-HEAD\fR
+abbreviation for \fB\-\-rev\fR HEAD
+.SS Logging options:
+.TP
+\fB\-v\fR, \fB\-\-verbose\fR
+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
+.PP
+\&'repo start' begins a new branch of development, starting from the revision
+specified in the manifest.

man/repo-status.1

@@ -0,0 +1,111 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man.
+.TH REPO "1" "July 2022" "repo status" "Repo Manual"
+.SH NAME
+repo \- repo status - manual page for repo status
+.SH SYNOPSIS
+.B repo
+\fI\,status \/\fR[\fI\,<project>\/\fR...]
+.SH DESCRIPTION
+Summary
+.PP
+Show the working tree status
+.SH OPTIONS
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+show this help message and exit
+.TP
+\fB\-j\fR JOBS, \fB\-\-jobs\fR=\fI\,JOBS\/\fR
+number of jobs to run in parallel (default: based on
+number of CPU cores)
+.TP
+\fB\-o\fR, \fB\-\-orphans\fR
+include objects in working directory outside of repo
+projects
+.SS Logging options:
+.TP
+\fB\-v\fR, \fB\-\-verbose\fR
+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
+.PP
+\&'repo status' compares the working tree to the staging area (aka index), and the
+most recent commit on this branch (HEAD), in each project specified. A summary
+is displayed, one line per file where there is a difference between these three
+states.
+.PP
+The \fB\-j\fR/\-\-jobs option can be used to run multiple status queries in parallel.
+.PP
+The \fB\-o\fR/\-\-orphans option can be used to show objects that are in the working
+directory, but not associated with a repo project. This includes unmanaged
+top\-level files and directories, but also includes deeper items. For example, if
+dir/subdir/proj1 and dir/subdir/proj2 are repo projects, dir/subdir/proj3 will
+be shown if it is not known to repo.
+.PP
+Status Display
+.PP
+The status display is organized into three columns of information, for example
+if the file 'subcmds/status.py' is modified in the project 'repo' on branch
+\&'devwork':
+.TP
+project repo/
+branch devwork
+.TP
+\fB\-m\fR
+subcmds/status.py
+.PP
+The first column explains how the staging area (index) differs from the last
+commit (HEAD). Its values are always displayed in upper case and have the
+following meanings:
+.TP
+\-:
+no difference
+.TP
+A:
+added         (not in HEAD,     in index                     )
+.TP
+M:
+modified      (    in HEAD,     in index, different content  )
+.TP
+D:
+deleted       (    in HEAD, not in index                     )
+.TP
+R:
+renamed       (not in HEAD,     in index, path changed       )
+.TP
+C:
+copied        (not in HEAD,     in index, copied from another)
+.TP
+T:
+mode changed  (    in HEAD,     in index, same content       )
+.TP
+U:
+unmerged; conflict resolution required
+.PP
+The second column explains how the working directory differs from the index. Its
+values are always displayed in lower case and have the following meanings:
+.TP
+\-:
+new / unknown (not in index,     in work tree                )
+.TP
+m:
+modified      (    in index,     in work tree, modified      )
+.TP
+d:
+deleted       (    in index, not in work tree                )

man/repo-sync.1

@@ -0,0 +1,255 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man.
+.TH REPO "1" "June 2025" "repo sync" "Repo Manual"
+.SH NAME
+repo \- repo sync - manual page for repo sync
+.SH SYNOPSIS
+.B repo
+\fI\,sync \/\fR[\fI\,<project>\/\fR...]
+.SH DESCRIPTION
+Summary
+.PP
+Update working tree to the latest revision
+.SH OPTIONS
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+show this help message and exit
+.TP
+\fB\-j\fR JOBS, \fB\-\-jobs\fR=\fI\,JOBS\/\fR
+number of jobs to run in parallel (default: based on
+number of CPU cores)
+.TP
+\fB\-\-jobs\-network\fR=\fI\,JOBS\/\fR
+number of network jobs to run in parallel (defaults to
+\fB\-\-jobs\fR or 1). Ignored when \fB\-\-interleaved\fR is set
+.TP
+\fB\-\-jobs\-checkout\fR=\fI\,JOBS\/\fR
+number of local checkout jobs to run in parallel
+(defaults to \fB\-\-jobs\fR or 8). Ignored when \fB\-\-interleaved\fR
+is set
+.TP
+\fB\-f\fR, \fB\-\-force\-broken\fR
+obsolete option (to be deleted in the future)
+.TP
+\fB\-\-fail\-fast\fR
+stop syncing after first error is hit
+.TP
+\fB\-\-force\-sync\fR
+overwrite an existing git directory if it needs to
+point to a different object directory. WARNING: this
+may cause loss of data
+.TP
+\fB\-\-force\-checkout\fR
+force checkout even if it results in throwing away
+uncommitted modifications. WARNING: this may cause
+loss of data
+.TP
+\fB\-\-force\-remove\-dirty\fR
+force remove projects with uncommitted modifications
+if projects no longer exist in the manifest. WARNING:
+this may cause loss of data
+.TP
+\fB\-\-rebase\fR
+rebase local commits regardless of whether they are
+published
+.TP
+\fB\-l\fR, \fB\-\-local\-only\fR
+only update working tree, don't fetch
+.TP
+\fB\-\-no\-manifest\-update\fR, \fB\-\-nmu\fR
+use the existing manifest checkout as\-is. (do not
+update to the latest revision)
+.TP
+\fB\-\-interleaved\fR
+fetch and checkout projects in parallel (experimental)
+.TP
+\fB\-n\fR, \fB\-\-network\-only\fR
+fetch only, don't update working tree
+.TP
+\fB\-d\fR, \fB\-\-detach\fR
+detach projects back to manifest revision
+.TP
+\fB\-c\fR, \fB\-\-current\-branch\fR
+fetch only current branch from server
+.TP
+\fB\-\-no\-current\-branch\fR
+fetch all branches from server
+.TP
+\fB\-m\fR NAME.xml, \fB\-\-manifest\-name\fR=\fI\,NAME\/\fR.xml
+temporary manifest to use for this sync
+.TP
+\fB\-\-clone\-bundle\fR
+enable use of \fI\,/clone.bundle\/\fP on HTTP/HTTPS
+.TP
+\fB\-\-no\-clone\-bundle\fR
+disable use of \fI\,/clone.bundle\/\fP on HTTP/HTTPS
+.TP
+\fB\-u\fR MANIFEST_SERVER_USERNAME, \fB\-\-manifest\-server\-username\fR=\fI\,MANIFEST_SERVER_USERNAME\/\fR
+username to authenticate with the manifest server
+.TP
+\fB\-p\fR MANIFEST_SERVER_PASSWORD, \fB\-\-manifest\-server\-password\fR=\fI\,MANIFEST_SERVER_PASSWORD\/\fR
+password to authenticate with the manifest server
+.TP
+\fB\-\-fetch\-submodules\fR
+fetch submodules from server
+.TP
+\fB\-\-use\-superproject\fR
+use the manifest superproject to sync projects;
+implies \fB\-c\fR
+.TP
+\fB\-\-no\-use\-superproject\fR
+disable use of manifest superprojects
+.TP
+\fB\-\-tags\fR
+fetch tags
+.TP
+\fB\-\-no\-tags\fR
+don't fetch tags (default)
+.TP
+\fB\-\-optimized\-fetch\fR
+only fetch projects fixed to sha1 if revision does not
+exist locally
+.TP
+\fB\-\-retry\-fetches\fR=\fI\,RETRY_FETCHES\/\fR
+number of times to retry fetches on transient errors
+.TP
+\fB\-\-prune\fR
+delete refs that no longer exist on the remote
+(default)
+.TP
+\fB\-\-no\-prune\fR
+do not delete refs that no longer exist on the remote
+.TP
+\fB\-\-auto\-gc\fR
+run garbage collection on all synced projects
+.TP
+\fB\-\-no\-auto\-gc\fR
+do not run garbage collection on any projects
+(default)
+.TP
+\fB\-s\fR, \fB\-\-smart\-sync\fR
+smart sync using manifest from the latest known good
+build
+.TP
+\fB\-t\fR SMART_TAG, \fB\-\-smart\-tag\fR=\fI\,SMART_TAG\/\fR
+smart sync using manifest from a known tag
+.SS Logging options:
+.TP
+\fB\-v\fR, \fB\-\-verbose\fR
+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
+do not verify repo source code
+.PP
+Run `repo help sync` to view the detailed manual.
+.SH DETAILS
+.PP
+The 'repo sync' command synchronizes local project directories with the remote
+repositories specified in the manifest. If a local project does not yet exist,
+it will clone a new local directory from the remote repository and set up
+tracking branches as specified in the manifest. If the local project already
+exists, 'repo sync' will update the remote branches and rebase any new local
+changes on top of the new remote changes.
+.PP
+\&'repo sync' will synchronize all projects listed at the command line. Projects
+can be specified either by name, or by a relative or absolute path to the
+project's local directory. If no projects are specified, 'repo sync' will
+synchronize all projects listed in the manifest.
+.PP
+The \fB\-d\fR/\-\-detach option can be used to switch specified projects back to the
+manifest revision. This option is especially helpful if the project is currently
+on a topic branch, but the manifest revision is temporarily needed.
+.PP
+The \fB\-s\fR/\-\-smart\-sync option can be used to sync to a known good build as
+specified by the manifest\-server element in the current manifest. The
+\fB\-t\fR/\-\-smart\-tag option is similar and allows you to specify a custom tag/label.
+.PP
+The \fB\-u\fR/\-\-manifest\-server\-username and \fB\-p\fR/\-\-manifest\-server\-password options can
+be used to specify a username and password to authenticate with the manifest
+server when using the \fB\-s\fR or \fB\-t\fR option.
+.PP
+If \fB\-u\fR and \fB\-p\fR are not specified when using the \fB\-s\fR or \fB\-t\fR option, 'repo sync' will
+attempt to read authentication credentials for the manifest server from the
+user's .netrc file.
+.PP
+\&'repo sync' will not use authentication credentials from \fB\-u\fR/\-p or .netrc if the
+manifest server specified in the manifest file already includes credentials.
+.PP
+By default, all projects will be synced. The \fB\-\-fail\-fast\fR option can be used to
+halt syncing as soon as possible when the first project fails to sync.
+.PP
+The \fB\-\-force\-sync\fR option can be used to overwrite existing git directories if
+they have previously been linked to a different object directory. WARNING: This
+may cause data to be lost since refs may be removed when overwriting.
+.PP
+The \fB\-\-force\-checkout\fR option can be used to force git to switch revs even if the
+index or the working tree differs from HEAD, and if there are untracked files.
+WARNING: This may cause data to be lost since uncommitted changes may be
+removed.
+.PP
+The \fB\-\-force\-remove\-dirty\fR option can be used to remove previously used projects
+with uncommitted changes. WARNING: This may cause data to be lost since
+uncommitted changes may be removed with projects that no longer exist in the
+manifest.
+.PP
+The \fB\-\-no\-clone\-bundle\fR option disables any attempt to use \fI\,$URL/clone.bundle\/\fP to
+bootstrap a new Git repository from a resumeable bundle file on a content
+delivery network. This may be necessary if there are problems with the local
+Python HTTP client or proxy configuration, but the Git binary works.
+.PP
+The \fB\-\-fetch\-submodules\fR option enables fetching Git submodules of a project from
+server.
+.PP
+The \fB\-c\fR/\-\-current\-branch option can be used to only fetch objects that are on the
+branch specified by a project's revision.
+.PP
+The \fB\-\-optimized\-fetch\fR option can be used to only fetch projects that are fixed
+to a sha1 revision if the sha1 revision does not already exist locally.
+.PP
+The \fB\-\-prune\fR option can be used to remove any refs that no longer exist on the
+remote.
+.PP
+The \fB\-\-auto\-gc\fR option can be used to trigger garbage collection on all projects.
+By default, repo does not run garbage collection.
+.PP
+SSH Connections
+.PP
+If at least one project remote URL uses an SSH connection (ssh://, git+ssh://,
+or user@host:path syntax) repo will automatically enable the SSH ControlMaster
+option when connecting to that host. This feature permits other projects in the
+same 'repo sync' session to reuse the same SSH tunnel, saving connection setup
+overheads.
+.PP
+To disable this behavior on UNIX platforms, set the GIT_SSH environment variable
+to 'ssh'. For example:
+.IP
+export GIT_SSH=ssh
+repo sync
+.PP
+Compatibility
+.PP
+This feature is automatically disabled on Windows, due to the lack of UNIX
+domain socket support.
+.PP
+This feature is not compatible with url.insteadof rewrites in the user's
+~/.gitconfig. 'repo sync' is currently not able to perform the rewrite early
+enough to establish the ControlMaster tunnel.
+.PP
+If the remote SSH daemon is Gerrit Code Review, version 2.0.10 or later is
+required to fix a server side protocol bug.

man/repo-upload.1

@@ -0,0 +1,215 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man.
+.TH REPO "1" "June 2024" "repo upload" "Repo Manual"
+.SH NAME
+repo \- repo upload - manual page for repo upload
+.SH SYNOPSIS
+.B repo
+\fI\,upload \/\fR[\fI\,--re --cc\/\fR] [\fI\,<project>\/\fR]...
+.SH DESCRIPTION
+Summary
+.PP
+Upload changes for code review
+.SH OPTIONS
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+show this help message and exit
+.TP
+\fB\-j\fR JOBS, \fB\-\-jobs\fR=\fI\,JOBS\/\fR
+number of jobs to run in parallel (default: based on
+number of CPU cores)
+.TP
+\fB\-t\fR, \fB\-\-topic\-branch\fR
+set the topic to the local branch name
+.TP
+\fB\-\-topic\fR=\fI\,TOPIC\/\fR
+set topic for the change
+.TP
+\fB\-\-hashtag\fR=\fI\,HASHTAGS\/\fR, \fB\-\-ht\fR=\fI\,HASHTAGS\/\fR
+add hashtags (comma delimited) to the review
+.TP
+\fB\-\-hashtag\-branch\fR, \fB\-\-htb\fR
+add local branch name as a hashtag
+.TP
+\fB\-l\fR LABELS, \fB\-\-label\fR=\fI\,LABELS\/\fR
+add a label when uploading
+.TP
+\fB\-\-pd\fR=\fI\,PATCHSET_DESCRIPTION\/\fR, \fB\-\-patchset\-description\fR=\fI\,PATCHSET_DESCRIPTION\/\fR
+description for patchset
+.TP
+\fB\-\-re\fR=\fI\,REVIEWERS\/\fR, \fB\-\-reviewers\fR=\fI\,REVIEWERS\/\fR
+request reviews from these people
+.TP
+\fB\-\-cc\fR=\fI\,CC\/\fR
+also send email to these email addresses
+.TP
+\fB\-\-br\fR=\fI\,BRANCH\/\fR, \fB\-\-branch\fR=\fI\,BRANCH\/\fR
+(local) branch to upload
+.TP
+\fB\-c\fR, \fB\-\-current\-branch\fR
+upload current git branch
+.TP
+\fB\-\-no\-current\-branch\fR
+upload all git branches
+.TP
+\fB\-\-ne\fR, \fB\-\-no\-emails\fR
+do not send e\-mails on upload
+.TP
+\fB\-p\fR, \fB\-\-private\fR
+upload as a private change (deprecated; use \fB\-\-wip\fR)
+.TP
+\fB\-w\fR, \fB\-\-wip\fR
+upload as a work\-in\-progress change
+.TP
+\fB\-r\fR, \fB\-\-ready\fR
+mark change as ready (clears work\-in\-progress setting)
+.TP
+\fB\-o\fR PUSH_OPTIONS, \fB\-\-push\-option\fR=\fI\,PUSH_OPTIONS\/\fR
+additional push options to transmit
+.TP
+\fB\-D\fR BRANCH, \fB\-\-destination\fR=\fI\,BRANCH\/\fR, \fB\-\-dest\fR=\fI\,BRANCH\/\fR
+submit for review on this target branch
+.TP
+\fB\-n\fR, \fB\-\-dry\-run\fR
+do everything except actually upload the CL
+.TP
+\fB\-y\fR, \fB\-\-yes\fR
+answer yes to all safe prompts
+.TP
+\fB\-\-ignore\-untracked\-files\fR
+ignore untracked files in the working copy
+.TP
+\fB\-\-no\-ignore\-untracked\-files\fR
+always ask about untracked files in the working copy
+.TP
+\fB\-\-no\-cert\-checks\fR
+disable verifying ssl certs (unsafe)
+.SS Logging options:
+.TP
+\fB\-v\fR, \fB\-\-verbose\fR
+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
+Do not run the pre\-upload hook.
+.TP
+\fB\-\-verify\fR
+Run the pre\-upload hook without prompting.
+.TP
+\fB\-\-ignore\-hooks\fR
+Do not abort if pre\-upload hooks fail.
+.PP
+Run `repo help upload` to view the detailed manual.
+.SH DETAILS
+.PP
+The 'repo upload' command is used to send changes to the Gerrit Code Review
+system. It searches for topic branches in local projects that have not yet been
+published for review. If multiple topic branches are found, 'repo upload' opens
+an editor to allow the user to select which branches to upload.
+.PP
+\&'repo upload' searches for uploadable changes in all projects listed at the
+command line. Projects can be specified either by name, or by a relative or
+absolute path to the project's local directory. If no projects are specified,
+\&'repo upload' will search for uploadable changes in all projects listed in the
+manifest.
+.PP
+If the \fB\-\-reviewers\fR or \fB\-\-cc\fR options are passed, those emails are added to the
+respective list of users, and emails are sent to any new users. Users passed as
+\fB\-\-reviewers\fR must already be registered with the code review system, or the
+upload will fail.
+.PP
+While most normal Gerrit options have dedicated command line options, direct
+access to the Gerit options is available via \fB\-\-push\-options\fR. This is useful when
+Gerrit has newer functionality that repo upload doesn't yet support, or doesn't
+have plans to support. See the Push Options documentation for more details:
+https://gerrit\-review.googlesource.com/Documentation/user\-upload.html#push_options
+.PP
+Configuration
+.PP
+review.URL.autoupload:
+.PP
+To disable the "Upload ... (y/N)?" prompt, you can set a per\-project or global
+Git configuration option. If review.URL.autoupload is set to "true" then repo
+will assume you always answer "y" at the prompt, and will not prompt you
+further. If it is set to "false" then repo will assume you always answer "n",
+and will abort.
+.PP
+review.URL.autoreviewer:
+.PP
+To automatically append a user or mailing list to reviews, you can set a
+per\-project or global Git option to do so.
+.PP
+review.URL.autocopy:
+.PP
+To automatically copy a user or mailing list to all uploaded reviews, you can
+set a per\-project or global Git option to do so. Specifically,
+review.URL.autocopy can be set to a comma separated list of reviewers who you
+always want copied on all uploads with a non\-empty \fB\-\-re\fR argument.
+.PP
+review.URL.username:
+.PP
+Override the username used to connect to Gerrit Code Review. By default the
+local part of the email address is used.
+.PP
+The URL must match the review URL listed in the manifest XML file, or in the
+\&.git/config within the project. For example:
+.IP
+[remote "origin"]
+.IP
+url = git://git.example.com/project.git
+review = http://review.example.com/
+.IP
+[review "http://review.example.com/"]
+.IP
+autoupload = true
+autocopy = johndoe@company.com,my\-team\-alias@company.com
+.PP
+review.URL.uploadtopic:
+.PP
+To add a topic branch whenever uploading a commit, you can set a per\-project or
+global Git option to do so. If review.URL.uploadtopic is set to "true" then repo
+will assume you always want the equivalent of the \fB\-t\fR option to the repo command.
+If unset or set to "false" then repo will make use of only the command line
+option.
+.PP
+review.URL.uploadhashtags:
+.PP
+To add hashtags whenever uploading a commit, you can set a per\-project or global
+Git option to do so. The value of review.URL.uploadhashtags will be used as
+comma delimited hashtags like the \fB\-\-hashtag\fR option.
+.PP
+review.URL.uploadlabels:
+.PP
+To add labels whenever uploading a commit, you can set a per\-project or global
+Git option to do so. The value of review.URL.uploadlabels will be used as comma
+delimited labels like the \fB\-\-label\fR option.
+.PP
+review.URL.uploadnotify:
+.PP
+Control e\-mail notifications when uploading.
+https://gerrit\-review.googlesource.com/Documentation/user\-upload.html#notify
+.PP
+review.URL.uploadwarningthreshold:
+.PP
+Repo will warn you if you are attempting to upload a large number of commits in
+one or more branches. By default, the threshold is five commits. This option
+allows you to override the warning threshold to a different value.
+.PP
+References
+.PP
+Gerrit Code Review: https://www.gerritcodereview.com/

man/repo-version.1

@@ -0,0 +1,37 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man.
+.TH REPO "1" "July 2022" "repo version" "Repo Manual"
+.SH NAME
+repo \- repo version - manual page for repo version
+.SH SYNOPSIS
+.B repo
+\fI\,version\/\fR
+.SH DESCRIPTION
+Summary
+.PP
+Display the version of repo
+.SH OPTIONS
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+show this help message and exit
+.SS Logging options:
+.TP
+\fB\-v\fR, \fB\-\-verbose\fR
+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.

man/repo.1

@@ -0,0 +1,137 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man.
+.TH REPO "1" "April 2025" "repo" "Repo Manual"
+.SH NAME
+repo \- repository management tool built on top of git
+.SH SYNOPSIS
+.B repo
+[\fI\,-p|--paginate|--no-pager\/\fR] \fI\,COMMAND \/\fR[\fI\,ARGS\/\fR]
+.SH OPTIONS
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+show this help message and exit
+.TP
+\fB\-\-help\-all\fR
+show this help message with all subcommands and exit
+.TP
+\fB\-p\fR, \fB\-\-paginate\fR
+display command output in the pager
+.TP
+\fB\-\-no\-pager\fR
+disable the pager
+.TP
+\fB\-\-color\fR=\fI\,COLOR\/\fR
+control color usage: auto, always, never
+.TP
+\fB\-\-trace\fR
+trace git command execution (REPO_TRACE=1)
+.TP
+\fB\-\-trace\-to\-stderr\fR
+trace outputs go to stderr in addition to
+\&.repo/TRACE_FILE
+.TP
+\fB\-\-trace\-python\fR
+trace python command execution
+.TP
+\fB\-\-time\fR
+time repo command execution
+.TP
+\fB\-\-version\fR
+display this version of repo
+.TP
+\fB\-\-show\-toplevel\fR
+display the path of the top\-level directory of the
+repo client checkout
+.TP
+\fB\-\-event\-log\fR=\fI\,EVENT_LOG\/\fR
+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
+Permanently abandon a development branch
+.TP
+branch
+View current topic branches
+.TP
+branches
+View current topic branches
+.TP
+checkout
+Checkout a branch for development
+.TP
+cherry\-pick
+Cherry\-pick a change.
+.TP
+diff
+Show changes between commit and working tree
+.TP
+diffmanifests
+Manifest diff utility
+.TP
+download
+Download and checkout a change
+.TP
+forall
+Run a shell command in each project
+.TP
+gc
+Cleaning up internal repo and Git state.
+.TP
+grep
+Print lines matching a pattern
+.TP
+help
+Display detailed help on a command
+.TP
+info
+Get info on the manifest branch, current branch or unmerged branches
+.TP
+init
+Initialize a repo client checkout in the current directory
+.TP
+list
+List projects and their associated directories
+.TP
+manifest
+Manifest inspection utility
+.TP
+overview
+Display overview of unmerged project branches
+.TP
+prune
+Prune (delete) already merged topics
+.TP
+rebase
+Rebase local branches on upstream branch
+.TP
+selfupdate
+Update repo to the latest version
+.TP
+smartsync
+Update working tree to the latest known good revision
+.TP
+stage
+Stage file(s) for commit
+.TP
+start
+Start a new branch for development
+.TP
+status
+Show the working tree status
+.TP
+sync
+Update working tree to the latest revision
+.TP
+upload
+Upload changes for code review
+.TP
+version
+Display the version of repo
+.PP
+See 'repo help <command>' for more information on a specific command.
+Bug reports: https://issues.gerritcodereview.com/issues/new?component=1370071

pager.py

@@ -1,5 +1,3 @@
-# -*- coding:utf-8 -*-
-#
 # Copyright (C) 2008 The Android Open Source Project
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -14,7 +12,6 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-from __future__ import print_function
 import os
 import select
 import subprocess
@@ -22,99 +19,112 @@ import sys
 
 import platform_utils
 
+
 active = False
 pager_process = None
 old_stdout = None
 old_stderr = None
 
-def RunPager(globalConfig):
-  if not os.isatty(0) or not os.isatty(1):
-    return
-  pager = _SelectPager(globalConfig)
-  if pager == '' or pager == 'cat':
-    return
 
-  if platform_utils.isWindows():
-    _PipePager(pager);
-  else:
-    _ForkPager(pager)
+def RunPager(globalConfig):
+    if not os.isatty(0) or not os.isatty(1):
+        return
+    pager = _SelectPager(globalConfig)
+    if pager == "" or pager == "cat":
+        return
+
+    if platform_utils.isWindows():
+        _PipePager(pager)
+    else:
+        _ForkPager(pager)
+
 
 def TerminatePager():
-  global pager_process, old_stdout, old_stderr
-  if pager_process:
-    sys.stdout.flush()
-    sys.stderr.flush()
-    pager_process.stdin.close()
-    pager_process.wait();
-    pager_process = None
-    # Restore initial stdout/err in case there is more output in this process
-    # after shutting down the pager process
-    sys.stdout = old_stdout
-    sys.stderr = old_stderr
+    global pager_process
+    if pager_process:
+        sys.stdout.flush()
+        sys.stderr.flush()
+        pager_process.stdin.close()
+        pager_process.wait()
+        pager_process = None
+        # Restore initial stdout/err in case there is more output in this
+        # process after shutting down the pager process.
+        sys.stdout = old_stdout
+        sys.stderr = old_stderr
+
 
 def _PipePager(pager):
-  global pager_process, old_stdout, old_stderr
-  assert pager_process is None, "Only one active pager process at a time"
-  # Create pager process, piping stdout/err into its stdin
-  pager_process = subprocess.Popen([pager], stdin=subprocess.PIPE, stdout=sys.stdout, stderr=sys.stderr)
-  old_stdout = sys.stdout
-  old_stderr = sys.stderr
-  sys.stdout = pager_process.stdin
-  sys.stderr = pager_process.stdin
+    global pager_process, old_stdout, old_stderr
+    assert pager_process is None, "Only one active pager process at a time"
+    # Create pager process, piping stdout/err into its stdin.
+    try:
+        pager_process = subprocess.Popen(
+            [pager], stdin=subprocess.PIPE, stdout=sys.stdout, stderr=sys.stderr
+        )
+    except FileNotFoundError:
+        sys.exit(f'fatal: cannot start pager "{pager}"')
+    old_stdout = sys.stdout
+    old_stderr = sys.stderr
+    sys.stdout = pager_process.stdin
+    sys.stderr = pager_process.stdin
+
 
 def _ForkPager(pager):
-  global active
-  # This process turns into the pager; a child it forks will
-  # do the real processing and output back to the pager. This
-  # is necessary to keep the pager in control of the tty.
-  #
-  try:
-    r, w = os.pipe()
-    pid = os.fork()
-    if not pid:
-      os.dup2(w, 1)
-      os.dup2(w, 2)
-      os.close(r)
-      os.close(w)
-      active = True
-      return
+    global active
+    # This process turns into the pager; a child it forks will
+    # do the real processing and output back to the pager. This
+    # is necessary to keep the pager in control of the tty.
+    try:
+        r, w = os.pipe()
+        pid = os.fork()
+        if not pid:
+            os.dup2(w, 1)
+            os.dup2(w, 2)
+            os.close(r)
+            os.close(w)
+            active = True
+            return
 
-    os.dup2(r, 0)
-    os.close(r)
-    os.close(w)
+        os.dup2(r, 0)
+        os.close(r)
+        os.close(w)
+
+        _BecomePager(pager)
+    except Exception:
+        print("fatal: cannot start pager '%s'" % pager, file=sys.stderr)
+        sys.exit(255)
 
-    _BecomePager(pager)
-  except Exception:
-    print("fatal: cannot start pager '%s'" % pager, file=sys.stderr)
-    sys.exit(255)
 
 def _SelectPager(globalConfig):
-  try:
-    return os.environ['GIT_PAGER']
-  except KeyError:
-    pass
+    try:
+        return os.environ["GIT_PAGER"]
+    except KeyError:
+        pass
 
-  pager = globalConfig.GetString('core.pager')
-  if pager:
-    return pager
+    pager = globalConfig.GetString("core.pager")
+    if pager:
+        return pager
 
-  try:
-    return os.environ['PAGER']
-  except KeyError:
-    pass
+    try:
+        return os.environ["PAGER"]
+    except KeyError:
+        pass
+
+    return "less"
 
-  return 'less'
 
 def _BecomePager(pager):
-  # Delaying execution of the pager until we have output
-  # ready works around a long-standing bug in popularly
-  # available versions of 'less', a better 'more'.
-  #
-  _a, _b, _c = select.select([0], [], [0])
+    # Delaying execution of the pager until we have output
+    # ready works around a long-standing bug in popularly
+    # available versions of 'less', a better 'more'.
+    _a, _b, _c = select.select([0], [], [0])
 
-  os.environ['LESS'] = 'FRSX'
+    # This matches the behavior of git, which sets $LESS to `FRX` if it is not
+    # set. See:
+    # https://git-scm.com/docs/git-config#Documentation/git-config.txt-corepager
+    os.environ.setdefault("LESS", "FRX")
 
-  try:
-    os.execvp(pager, [pager])
-  except OSError:
-    os.execv('/bin/sh', ['sh', '-c', pager])
+    try:
+        os.execvp(pager, [pager])
+    except OSError:
+        os.execv("/bin/sh", ["sh", "-c", pager])

platform_utils.py

@@ -1,5 +1,3 @@
-# -*- coding:utf-8 -*-
-#
 # Copyright (C) 2016 The Android Open Source Project
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -17,400 +15,245 @@
 import errno
 import os
 import platform
-import select
 import shutil
 import stat
 
-from pyversion import is_python3
-if is_python3():
-  from queue import Queue
-else:
-  from Queue import Queue
-
-from threading import Thread
-
 
 def isWindows():
-  """ Returns True when running with the native port of Python for Windows,
-  False when running on any other platform (including the Cygwin port of
-  Python).
-  """
-  # Note: The cygwin port of Python returns "CYGWIN_NT_xxx"
-  return platform.system() == "Windows"
-
-
-class FileDescriptorStreams(object):
-  """ Platform agnostic abstraction enabling non-blocking I/O over a
-  collection of file descriptors. This abstraction is required because
-  fctnl(os.O_NONBLOCK) is not supported on Windows.
-  """
-  @classmethod
-  def create(cls):
-    """ Factory method: instantiates the concrete class according to the
-    current platform.
+    """Returns True when running with the native port of Python for Windows,
+    False when running on any other platform (including the Cygwin port of
+    Python).
     """
-    if isWindows():
-      return _FileDescriptorStreamsThreads()
-    else:
-      return _FileDescriptorStreamsNonBlocking()
-
-  def __init__(self):
-    self.streams = []
-
-  def add(self, fd, dest, std_name):
-    """ Wraps an existing file descriptor as a stream.
-    """
-    self.streams.append(self._create_stream(fd, dest, std_name))
-
-  def remove(self, stream):
-    """ Removes a stream, when done with it.
-    """
-    self.streams.remove(stream)
-
-  @property
-  def is_done(self):
-    """ Returns True when all streams have been processed.
-    """
-    return len(self.streams) == 0
-
-  def select(self):
-    """ Returns the set of streams that have data available to read.
-    The returned streams each expose a read() and a close() method.
-    When done with a stream, call the remove(stream) method.
-    """
-    raise NotImplementedError
-
-  def _create_stream(self, fd, dest, std_name):
-    """ Creates a new stream wrapping an existing file descriptor.
-    """
-    raise NotImplementedError
-
-
-class _FileDescriptorStreamsNonBlocking(FileDescriptorStreams):
-  """ Implementation of FileDescriptorStreams for platforms that support
-  non blocking I/O.
-  """
-  class Stream(object):
-    """ Encapsulates a file descriptor """
-    def __init__(self, fd, dest, std_name):
-      self.fd = fd
-      self.dest = dest
-      self.std_name = std_name
-      self.set_non_blocking()
-
-    def set_non_blocking(self):
-      import fcntl
-      flags = fcntl.fcntl(self.fd, fcntl.F_GETFL)
-      fcntl.fcntl(self.fd, fcntl.F_SETFL, flags | os.O_NONBLOCK)
-
-    def fileno(self):
-      return self.fd.fileno()
-
-    def read(self):
-      return self.fd.read(4096)
-
-    def close(self):
-      self.fd.close()
-
-  def _create_stream(self, fd, dest, std_name):
-    return self.Stream(fd, dest, std_name)
-
-  def select(self):
-    ready_streams, _, _ = select.select(self.streams, [], [])
-    return ready_streams
-
-
-class _FileDescriptorStreamsThreads(FileDescriptorStreams):
-  """ Implementation of FileDescriptorStreams for platforms that don't support
-  non blocking I/O. This implementation requires creating threads issuing
-  blocking read operations on file descriptors.
-  """
-  def __init__(self):
-    super(_FileDescriptorStreamsThreads, self).__init__()
-    # The queue is shared accross all threads so we can simulate the
-    # behavior of the select() function
-    self.queue = Queue(10)  # Limit incoming data from streams
-
-  def _create_stream(self, fd, dest, std_name):
-    return self.Stream(fd, dest, std_name, self.queue)
-
-  def select(self):
-    # Return only one stream at a time, as it is the most straighforward
-    # thing to do and it is compatible with the select() function.
-    item = self.queue.get()
-    stream = item.stream
-    stream.data = item.data
-    return [stream]
-
-  class QueueItem(object):
-    """ Item put in the shared queue """
-    def __init__(self, stream, data):
-      self.stream = stream
-      self.data = data
-
-  class Stream(object):
-    """ Encapsulates a file descriptor """
-    def __init__(self, fd, dest, std_name, queue):
-      self.fd = fd
-      self.dest = dest
-      self.std_name = std_name
-      self.queue = queue
-      self.data = None
-      self.thread = Thread(target=self.read_to_queue)
-      self.thread.daemon = True
-      self.thread.start()
-
-    def close(self):
-      self.fd.close()
-
-    def read(self):
-      data = self.data
-      self.data = None
-      return data
-
-    def read_to_queue(self):
-      """ The thread function: reads everything from the file descriptor into
-      the shared queue and terminates when reaching EOF.
-      """
-      for line in iter(self.fd.readline, b''):
-        self.queue.put(_FileDescriptorStreamsThreads.QueueItem(self, line))
-      self.fd.close()
-      self.queue.put(_FileDescriptorStreamsThreads.QueueItem(self, None))
+    # Note: The cygwin port of Python returns "CYGWIN_NT_xxx"
+    return platform.system() == "Windows"
 
 
 def symlink(source, link_name):
-  """Creates a symbolic link pointing to source named link_name.
-  Note: On Windows, source must exist on disk, as the implementation needs
-  to know whether to create a "File" or a "Directory" symbolic link.
-  """
-  if isWindows():
-    import platform_utils_win32
-    source = _validate_winpath(source)
-    link_name = _validate_winpath(link_name)
-    target = os.path.join(os.path.dirname(link_name), source)
-    if isdir(target):
-      platform_utils_win32.create_dirsymlink(_makelongpath(source), link_name)
+    """Creates a symbolic link pointing to source named link_name.
+
+    Note: On Windows, source must exist on disk, as the implementation needs
+    to know whether to create a "File" or a "Directory" symbolic link.
+    """
+    if isWindows():
+        import platform_utils_win32
+
+        source = _validate_winpath(source)
+        link_name = _validate_winpath(link_name)
+        target = os.path.join(os.path.dirname(link_name), source)
+        if isdir(target):
+            platform_utils_win32.create_dirsymlink(
+                _makelongpath(source), link_name
+            )
+        else:
+            platform_utils_win32.create_filesymlink(
+                _makelongpath(source), link_name
+            )
     else:
-      platform_utils_win32.create_filesymlink(_makelongpath(source), link_name)
-  else:
-    return os.symlink(source, link_name)
+        return os.symlink(source, link_name)
 
 
 def _validate_winpath(path):
-  path = os.path.normpath(path)
-  if _winpath_is_valid(path):
-    return path
-  raise ValueError("Path \"%s\" must be a relative path or an absolute "
-                   "path starting with a drive letter".format(path))
+    path = os.path.normpath(path)
+    if _winpath_is_valid(path):
+        return path
+    raise ValueError(
+        f'Path "{path}" must be a relative path or an absolute '
+        "path starting with a drive letter"
+    )
 
 
 def _winpath_is_valid(path):
-  """Windows only: returns True if path is relative (e.g. ".\\foo") or is
-  absolute including a drive letter (e.g. "c:\\foo"). Returns False if path
-  is ambiguous (e.g. "x:foo" or "\\foo").
-  """
-  assert isWindows()
-  path = os.path.normpath(path)
-  drive, tail = os.path.splitdrive(path)
-  if tail:
-    if not drive:
-      return tail[0] != os.sep  # "\\foo" is invalid
+    """Windows only: returns True if path is relative (e.g. ".\\foo") or is
+    absolute including a drive letter (e.g. "c:\\foo"). Returns False if path
+    is ambiguous (e.g. "x:foo" or "\\foo").
+    """
+    assert isWindows()
+    path = os.path.normpath(path)
+    drive, tail = os.path.splitdrive(path)
+    if tail:
+        if not drive:
+            return tail[0] != os.sep  # "\\foo" is invalid
+        else:
+            return tail[0] == os.sep  # "x:foo" is invalid
     else:
-      return tail[0] == os.sep  # "x:foo" is invalid
-  else:
-    return not drive  # "x:" is invalid
+        return not drive  # "x:" is invalid
 
 
 def _makelongpath(path):
-  """Return the input path normalized to support the Windows long path syntax
-  ("\\\\?\\" prefix) if needed, i.e. if the input path is longer than the
-  MAX_PATH limit.
-  """
-  if isWindows():
-    # Note: MAX_PATH is 260, but, for directories, the maximum value is actually 246.
-    if len(path) < 246:
-      return path
-    if path.startswith(u"\\\\?\\"):
-      return path
-    if not os.path.isabs(path):
-      return path
-    # Append prefix and ensure unicode so that the special longpath syntax
-    # is supported by underlying Win32 API calls
-    return u"\\\\?\\" + os.path.normpath(path)
-  else:
-    return path
+    """Return the input path normalized to support the Windows long path syntax
+    ("\\\\?\\" prefix) if needed, i.e. if the input path is longer than the
+    MAX_PATH limit.
+    """
+    if isWindows():
+        # Note: MAX_PATH is 260, but, for directories, the maximum value is
+        # actually 246.
+        if len(path) < 246:
+            return path
+        if path.startswith("\\\\?\\"):
+            return path
+        if not os.path.isabs(path):
+            return path
+        # Append prefix and ensure unicode so that the special longpath syntax
+        # is supported by underlying Win32 API calls
+        return "\\\\?\\" + os.path.normpath(path)
+    else:
+        return path
 
 
 def rmtree(path, ignore_errors=False):
-  """shutil.rmtree(path) wrapper with support for long paths on Windows.
+    """shutil.rmtree(path) wrapper with support for long paths on Windows.
 
-  Availability: Unix, Windows."""
-  onerror = None
-  if isWindows():
-    path = _makelongpath(path)
-    onerror = handle_rmtree_error
-  shutil.rmtree(path, ignore_errors=ignore_errors, onerror=onerror)
+    Availability: Unix, Windows.
+    """
+    onerror = None
+    if isWindows():
+        path = _makelongpath(path)
+        onerror = handle_rmtree_error
+    shutil.rmtree(path, ignore_errors=ignore_errors, onerror=onerror)
 
 
 def handle_rmtree_error(function, path, excinfo):
-  # Allow deleting read-only files
-  os.chmod(path, stat.S_IWRITE)
-  function(path)
+    # Allow deleting read-only files.
+    os.chmod(path, stat.S_IWRITE)
+    function(path)
 
 
 def rename(src, dst):
-  """os.rename(src, dst) wrapper with support for long paths on Windows.
+    """os.rename(src, dst) wrapper with support for long paths on Windows.
 
-  Availability: Unix, Windows."""
-  if isWindows():
-    # On Windows, rename fails if destination exists, see
-    # https://docs.python.org/2/library/os.html#os.rename
+    Availability: Unix, Windows.
+    """
+    if isWindows():
+        # On Windows, rename fails if destination exists, see
+        # https://docs.python.org/2/library/os.html#os.rename
+        try:
+            os.rename(_makelongpath(src), _makelongpath(dst))
+        except OSError as e:
+            if e.errno == errno.EEXIST:
+                os.remove(_makelongpath(dst))
+                os.rename(_makelongpath(src), _makelongpath(dst))
+            else:
+                raise
+    else:
+        shutil.move(src, dst)
+
+
+def remove(path, missing_ok=False):
+    """Remove (delete) the file path. This is a replacement for os.remove that
+    allows deleting read-only files on Windows, with support for long paths and
+    for deleting directory symbolic links.
+
+    Availability: Unix, Windows.
+    """
+    longpath = _makelongpath(path) if isWindows() else path
     try:
-      os.rename(_makelongpath(src), _makelongpath(dst))
+        os.remove(longpath)
     except OSError as e:
-      if e.errno == errno.EEXIST:
-        os.remove(_makelongpath(dst))
-        os.rename(_makelongpath(src), _makelongpath(dst))
-      else:
-        raise
-  else:
-    os.rename(src, dst)
-
-
-def remove(path):
-  """Remove (delete) the file path. This is a replacement for os.remove that
-  allows deleting read-only files on Windows, with support for long paths and
-  for deleting directory symbolic links.
-
-  Availability: Unix, Windows."""
-  if isWindows():
-    longpath = _makelongpath(path)
-    try:
-      os.remove(longpath)
-    except OSError as e:
-      if e.errno == errno.EACCES:
-        os.chmod(longpath, stat.S_IWRITE)
-        # Directory symbolic links must be deleted with 'rmdir'.
-        if islink(longpath) and isdir(longpath):
-          os.rmdir(longpath)
+        if e.errno == errno.EACCES:
+            os.chmod(longpath, stat.S_IWRITE)
+            # Directory symbolic links must be deleted with 'rmdir'.
+            if islink(longpath) and isdir(longpath):
+                os.rmdir(longpath)
+            else:
+                os.remove(longpath)
+        elif (
+            e.errno == errno.EROFS
+            and missing_ok
+            and not os.path.exists(longpath)
+        ):
+            pass
+        elif missing_ok and e.errno == errno.ENOENT:
+            pass
         else:
-          os.remove(longpath)
-      else:
-        raise
-  else:
-    os.remove(path)
+            raise
 
 
 def walk(top, topdown=True, onerror=None, followlinks=False):
-  """os.walk(path) wrapper with support for long paths on Windows.
+    """os.walk(path) wrapper with support for long paths on Windows.
 
-  Availability: Windows, Unix.
-  """
-  if isWindows():
-    return _walk_windows_impl(top, topdown, onerror, followlinks)
-  else:
-    return os.walk(top, topdown, onerror, followlinks)
+    Availability: Windows, Unix.
+    """
+    if isWindows():
+        return _walk_windows_impl(top, topdown, onerror, followlinks)
+    else:
+        return os.walk(top, topdown, onerror, followlinks)
 
 
 def _walk_windows_impl(top, topdown, onerror, followlinks):
-  try:
-    names = listdir(top)
-  except Exception as err:
-    if onerror is not None:
-      onerror(err)
-    return
+    try:
+        names = listdir(top)
+    except Exception as err:
+        if onerror is not None:
+            onerror(err)
+        return
 
-  dirs, nondirs = [], []
-  for name in names:
-    if isdir(os.path.join(top, name)):
-      dirs.append(name)
-    else:
-      nondirs.append(name)
+    dirs, nondirs = [], []
+    for name in names:
+        if isdir(os.path.join(top, name)):
+            dirs.append(name)
+        else:
+            nondirs.append(name)
 
-  if topdown:
-    yield top, dirs, nondirs
-  for name in dirs:
-    new_path = os.path.join(top, name)
-    if followlinks or not islink(new_path):
-      for x in _walk_windows_impl(new_path, topdown, onerror, followlinks):
-        yield x
-  if not topdown:
-    yield top, dirs, nondirs
+    if topdown:
+        yield top, dirs, nondirs
+    for name in dirs:
+        new_path = os.path.join(top, name)
+        if followlinks or not islink(new_path):
+            yield from _walk_windows_impl(
+                new_path, topdown, onerror, followlinks
+            )
+    if not topdown:
+        yield top, dirs, nondirs
 
 
 def listdir(path):
-  """os.listdir(path) wrapper with support for long paths on Windows.
+    """os.listdir(path) wrapper with support for long paths on Windows.
 
-  Availability: Windows, Unix.
-  """
-  return os.listdir(_makelongpath(path))
+    Availability: Windows, Unix.
+    """
+    return os.listdir(_makelongpath(path))
 
 
 def rmdir(path):
-  """os.rmdir(path) wrapper with support for long paths on Windows.
+    """os.rmdir(path) wrapper with support for long paths on Windows.
 
-  Availability: Windows, Unix.
-  """
-  os.rmdir(_makelongpath(path))
+    Availability: Windows, Unix.
+    """
+    os.rmdir(_makelongpath(path))
 
 
 def isdir(path):
-  """os.path.isdir(path) wrapper with support for long paths on Windows.
+    """os.path.isdir(path) wrapper with support for long paths on Windows.
 
-  Availability: Windows, Unix.
-  """
-  return os.path.isdir(_makelongpath(path))
+    Availability: Windows, Unix.
+    """
+    return os.path.isdir(_makelongpath(path))
 
 
 def islink(path):
-  """os.path.islink(path) wrapper with support for long paths on Windows.
+    """os.path.islink(path) wrapper with support for long paths on Windows.
 
-  Availability: Windows, Unix.
-  """
-  if isWindows():
-    import platform_utils_win32
-    return platform_utils_win32.islink(_makelongpath(path))
-  else:
-    return os.path.islink(path)
+    Availability: Windows, Unix.
+    """
+    if isWindows():
+        import platform_utils_win32
+
+        return platform_utils_win32.islink(_makelongpath(path))
+    else:
+        return os.path.islink(path)
 
 
 def readlink(path):
-  """Return a string representing the path to which the symbolic link
-  points. The result may be either an absolute or relative pathname;
-  if it is relative, it may be converted to an absolute pathname using
-  os.path.join(os.path.dirname(path), result).
+    """Return a string representing the path to which the symbolic link
+    points. The result may be either an absolute or relative pathname;
+    if it is relative, it may be converted to an absolute pathname using
+    os.path.join(os.path.dirname(path), result).
 
-  Availability: Windows, Unix.
-  """
-  if isWindows():
-    import platform_utils_win32
-    return platform_utils_win32.readlink(_makelongpath(path))
-  else:
-    return os.readlink(path)
+    Availability: Windows, Unix.
+    """
+    if isWindows():
+        import platform_utils_win32
 
-
-def realpath(path):
-  """Return the canonical path of the specified filename, eliminating
-  any symbolic links encountered in the path.
-
-  Availability: Windows, Unix.
-  """
-  if isWindows():
-    current_path = os.path.abspath(path)
-    path_tail = []
-    for c in range(0, 100):  # Avoid cycles
-      if islink(current_path):
-        target = readlink(current_path)
-        current_path = os.path.join(os.path.dirname(current_path), target)
-      else:
-        basename = os.path.basename(current_path)
-        if basename == '':
-          path_tail.append(current_path)
-          break
-        path_tail.append(basename)
-        current_path = os.path.dirname(current_path)
-    path_tail.reverse()
-    result = os.path.normpath(os.path.join(*path_tail))
-    return result
-  else:
-    return os.path.realpath(path)
+        return platform_utils_win32.readlink(_makelongpath(path))
+    else:
+        return os.readlink(path)

platform_utils_win32.py

@@ -1,5 +1,3 @@
-# -*- coding:utf-8 -*-
-#
 # Copyright (C) 2016 The Android Open Source Project
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -14,22 +12,30 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+from ctypes import addressof
+from ctypes import byref
+from ctypes import c_buffer
+from ctypes import c_ubyte
+from ctypes import FormatError
+from ctypes import get_last_error
+from ctypes import Structure
+from ctypes import Union
+from ctypes import WinDLL
+from ctypes import WinError
+from ctypes.wintypes import BOOL
+from ctypes.wintypes import BOOLEAN
+from ctypes.wintypes import DWORD
+from ctypes.wintypes import HANDLE
+from ctypes.wintypes import LPCWSTR
+from ctypes.wintypes import LPDWORD
+from ctypes.wintypes import LPVOID
+from ctypes.wintypes import ULONG
+from ctypes.wintypes import USHORT
+from ctypes.wintypes import WCHAR
 import errno
 
-from pyversion import is_python3
-from ctypes import WinDLL, get_last_error, FormatError, WinError, addressof
-from ctypes import c_buffer
-from ctypes.wintypes import BOOL, BOOLEAN, LPCWSTR, DWORD, HANDLE
-from ctypes.wintypes import WCHAR, USHORT, LPVOID, ULONG
-if is_python3():
-  from ctypes import c_ubyte, Structure, Union, byref
-  from ctypes.wintypes import LPDWORD
-else:
-  # For legacy Python2 different imports are needed.
-  from ctypes.wintypes import POINTER, c_ubyte, Structure, Union, byref
-  LPDWORD = POINTER(DWORD)
 
-kernel32 = WinDLL('kernel32', use_last_error=True)
+kernel32 = WinDLL("kernel32", use_last_error=True)
 
 UCHAR = c_ubyte
 
@@ -41,14 +47,17 @@ ERROR_PRIVILEGE_NOT_HELD = 1314
 # Win32 API entry points
 CreateSymbolicLinkW = kernel32.CreateSymbolicLinkW
 CreateSymbolicLinkW.restype = BOOLEAN
-CreateSymbolicLinkW.argtypes = (LPCWSTR,  # lpSymlinkFileName In
-                                LPCWSTR,  # lpTargetFileName In
-                                DWORD)    # dwFlags In
+CreateSymbolicLinkW.argtypes = (
+    LPCWSTR,  # lpSymlinkFileName In
+    LPCWSTR,  # lpTargetFileName In
+    DWORD,  # dwFlags In
+)
 
 # Symbolic link creation flags
 SYMBOLIC_LINK_FLAG_FILE = 0x00
 SYMBOLIC_LINK_FLAG_DIRECTORY = 0x01
-# symlink support for CreateSymbolicLink() starting with Windows 10 (1703, v10.0.14972)
+# symlink support for CreateSymbolicLink() starting with Windows 10 (1703,
+# v10.0.14972)
 SYMBOLIC_LINK_FLAG_ALLOW_UNPRIVILEGED_CREATE = 0x02
 
 GetFileAttributesW = kernel32.GetFileAttributesW
@@ -60,13 +69,15 @@ FILE_ATTRIBUTE_REPARSE_POINT = 0x00400
 
 CreateFileW = kernel32.CreateFileW
 CreateFileW.restype = HANDLE
-CreateFileW.argtypes = (LPCWSTR,  # lpFileName In
-                        DWORD,    # dwDesiredAccess In
-                        DWORD,    # dwShareMode In
-                        LPVOID,   # lpSecurityAttributes In_opt
-                        DWORD,    # dwCreationDisposition In
-                        DWORD,    # dwFlagsAndAttributes In
-                        HANDLE)   # hTemplateFile In_opt
+CreateFileW.argtypes = (
+    LPCWSTR,  # lpFileName In
+    DWORD,  # dwDesiredAccess In
+    DWORD,  # dwShareMode In
+    LPVOID,  # lpSecurityAttributes In_opt
+    DWORD,  # dwCreationDisposition In
+    DWORD,  # dwFlagsAndAttributes In
+    HANDLE,  # hTemplateFile In_opt
+)
 
 CloseHandle = kernel32.CloseHandle
 CloseHandle.restype = BOOL
@@ -79,14 +90,16 @@ FILE_FLAG_OPEN_REPARSE_POINT = 0x00200000
 
 DeviceIoControl = kernel32.DeviceIoControl
 DeviceIoControl.restype = BOOL
-DeviceIoControl.argtypes = (HANDLE,   # hDevice In
-                            DWORD,    # dwIoControlCode In
-                            LPVOID,   # lpInBuffer In_opt
-                            DWORD,    # nInBufferSize In
-                            LPVOID,   # lpOutBuffer Out_opt
-                            DWORD,    # nOutBufferSize In
-                            LPDWORD,  # lpBytesReturned Out_opt
-                            LPVOID)   # lpOverlapped Inout_opt
+DeviceIoControl.argtypes = (
+    HANDLE,  # hDevice In
+    DWORD,  # dwIoControlCode In
+    LPVOID,  # lpInBuffer In_opt
+    DWORD,  # nInBufferSize In
+    LPVOID,  # lpOutBuffer Out_opt
+    DWORD,  # nOutBufferSize In
+    LPDWORD,  # lpBytesReturned Out_opt
+    LPVOID,  # lpOverlapped Inout_opt
+)
 
 # Device I/O control flags and options
 FSCTL_GET_REPARSE_POINT = 0x000900A8
@@ -96,134 +109,136 @@ MAXIMUM_REPARSE_DATA_BUFFER_SIZE = 0x4000
 
 
 class GENERIC_REPARSE_BUFFER(Structure):
-  _fields_ = (('DataBuffer', UCHAR * 1),)
+    _fields_ = (("DataBuffer", UCHAR * 1),)
 
 
 class SYMBOLIC_LINK_REPARSE_BUFFER(Structure):
-  _fields_ = (('SubstituteNameOffset', USHORT),
-              ('SubstituteNameLength', USHORT),
-              ('PrintNameOffset', USHORT),
-              ('PrintNameLength', USHORT),
-              ('Flags', ULONG),
-              ('PathBuffer', WCHAR * 1))
+    _fields_ = (
+        ("SubstituteNameOffset", USHORT),
+        ("SubstituteNameLength", USHORT),
+        ("PrintNameOffset", USHORT),
+        ("PrintNameLength", USHORT),
+        ("Flags", ULONG),
+        ("PathBuffer", WCHAR * 1),
+    )
 
-  @property
-  def PrintName(self):
-    arrayt = WCHAR * (self.PrintNameLength // 2)
-    offset = type(self).PathBuffer.offset + self.PrintNameOffset
-    return arrayt.from_address(addressof(self) + offset).value
+    @property
+    def PrintName(self):
+        arrayt = WCHAR * (self.PrintNameLength // 2)
+        offset = type(self).PathBuffer.offset + self.PrintNameOffset
+        return arrayt.from_address(addressof(self) + offset).value
 
 
 class MOUNT_POINT_REPARSE_BUFFER(Structure):
-  _fields_ = (('SubstituteNameOffset', USHORT),
-              ('SubstituteNameLength', USHORT),
-              ('PrintNameOffset', USHORT),
-              ('PrintNameLength', USHORT),
-              ('PathBuffer', WCHAR * 1))
+    _fields_ = (
+        ("SubstituteNameOffset", USHORT),
+        ("SubstituteNameLength", USHORT),
+        ("PrintNameOffset", USHORT),
+        ("PrintNameLength", USHORT),
+        ("PathBuffer", WCHAR * 1),
+    )
 
-  @property
-  def PrintName(self):
-    arrayt = WCHAR * (self.PrintNameLength // 2)
-    offset = type(self).PathBuffer.offset + self.PrintNameOffset
-    return arrayt.from_address(addressof(self) + offset).value
+    @property
+    def PrintName(self):
+        arrayt = WCHAR * (self.PrintNameLength // 2)
+        offset = type(self).PathBuffer.offset + self.PrintNameOffset
+        return arrayt.from_address(addressof(self) + offset).value
 
 
 class REPARSE_DATA_BUFFER(Structure):
-  class REPARSE_BUFFER(Union):
-    _fields_ = (('SymbolicLinkReparseBuffer', SYMBOLIC_LINK_REPARSE_BUFFER),
-                ('MountPointReparseBuffer', MOUNT_POINT_REPARSE_BUFFER),
-                ('GenericReparseBuffer', GENERIC_REPARSE_BUFFER))
-  _fields_ = (('ReparseTag', ULONG),
-              ('ReparseDataLength', USHORT),
-              ('Reserved', USHORT),
-              ('ReparseBuffer', REPARSE_BUFFER))
-  _anonymous_ = ('ReparseBuffer',)
+    class REPARSE_BUFFER(Union):
+        _fields_ = (
+            ("SymbolicLinkReparseBuffer", SYMBOLIC_LINK_REPARSE_BUFFER),
+            ("MountPointReparseBuffer", MOUNT_POINT_REPARSE_BUFFER),
+            ("GenericReparseBuffer", GENERIC_REPARSE_BUFFER),
+        )
+
+    _fields_ = (
+        ("ReparseTag", ULONG),
+        ("ReparseDataLength", USHORT),
+        ("Reserved", USHORT),
+        ("ReparseBuffer", REPARSE_BUFFER),
+    )
+    _anonymous_ = ("ReparseBuffer",)
 
 
 def create_filesymlink(source, link_name):
-  """Creates a Windows file symbolic link source pointing to link_name."""
-  _create_symlink(source, link_name, SYMBOLIC_LINK_FLAG_FILE)
+    """Creates a Windows file symbolic link source pointing to link_name."""
+    _create_symlink(source, link_name, SYMBOLIC_LINK_FLAG_FILE)
 
 
 def create_dirsymlink(source, link_name):
-  """Creates a Windows directory symbolic link source pointing to link_name.
-  """
-  _create_symlink(source, link_name, SYMBOLIC_LINK_FLAG_DIRECTORY)
+    """Creates a Windows directory symbolic link source pointing to link_name."""  # noqa: E501
+    _create_symlink(source, link_name, SYMBOLIC_LINK_FLAG_DIRECTORY)
 
 
 def _create_symlink(source, link_name, dwFlags):
-  if not CreateSymbolicLinkW(link_name, source, dwFlags | SYMBOLIC_LINK_FLAG_ALLOW_UNPRIVILEGED_CREATE):
-    # See https://github.com/golang/go/pull/24307/files#diff-b87bc12e4da2497308f9ef746086e4f0
-    # "the unprivileged create flag is unsupported below Windows 10 (1703, v10.0.14972).
-    # retry without it."
-    if not CreateSymbolicLinkW(link_name, source, dwFlags):
-      code = get_last_error()
-      error_desc = FormatError(code).strip()
-      if code == ERROR_PRIVILEGE_NOT_HELD:
-        raise OSError(errno.EPERM, error_desc, link_name)
-      _raise_winerror(
-          code,
-          'Error creating symbolic link \"%s\"'.format(link_name))
+    if not CreateSymbolicLinkW(
+        link_name,
+        source,
+        dwFlags | SYMBOLIC_LINK_FLAG_ALLOW_UNPRIVILEGED_CREATE,
+    ):
+        # See https://github.com/golang/go/pull/24307/files#diff-b87bc12e4da2497308f9ef746086e4f0  # noqa: E501
+        # "the unprivileged create flag is unsupported below Windows 10 (1703,
+        # v10.0.14972). retry without it."
+        if not CreateSymbolicLinkW(link_name, source, dwFlags):
+            code = get_last_error()
+            error_desc = FormatError(code).strip()
+            if code == ERROR_PRIVILEGE_NOT_HELD:
+                raise OSError(errno.EPERM, error_desc, link_name)
+            _raise_winerror(code, f'Error creating symbolic link "{link_name}"')
 
 
 def islink(path):
-  result = GetFileAttributesW(path)
-  if result == INVALID_FILE_ATTRIBUTES:
-    return False
-  return bool(result & FILE_ATTRIBUTE_REPARSE_POINT)
+    result = GetFileAttributesW(path)
+    if result == INVALID_FILE_ATTRIBUTES:
+        return False
+    return bool(result & FILE_ATTRIBUTE_REPARSE_POINT)
 
 
 def readlink(path):
-  reparse_point_handle = CreateFileW(path,
-                                     0,
-                                     0,
-                                     None,
-                                     OPEN_EXISTING,
-                                     FILE_FLAG_OPEN_REPARSE_POINT |
-                                     FILE_FLAG_BACKUP_SEMANTICS,
-                                     None)
-  if reparse_point_handle == INVALID_HANDLE_VALUE:
+    reparse_point_handle = CreateFileW(
+        path,
+        0,
+        0,
+        None,
+        OPEN_EXISTING,
+        FILE_FLAG_OPEN_REPARSE_POINT | FILE_FLAG_BACKUP_SEMANTICS,
+        None,
+    )
+    if reparse_point_handle == INVALID_HANDLE_VALUE:
+        _raise_winerror(
+            get_last_error(), f'Error opening symbolic link "{path}"'
+        )
+    target_buffer = c_buffer(MAXIMUM_REPARSE_DATA_BUFFER_SIZE)
+    n_bytes_returned = DWORD()
+    io_result = DeviceIoControl(
+        reparse_point_handle,
+        FSCTL_GET_REPARSE_POINT,
+        None,
+        0,
+        target_buffer,
+        len(target_buffer),
+        byref(n_bytes_returned),
+        None,
+    )
+    CloseHandle(reparse_point_handle)
+    if not io_result:
+        _raise_winerror(
+            get_last_error(), f'Error reading symbolic link "{path}"'
+        )
+    rdb = REPARSE_DATA_BUFFER.from_buffer(target_buffer)
+    if rdb.ReparseTag == IO_REPARSE_TAG_SYMLINK:
+        return rdb.SymbolicLinkReparseBuffer.PrintName
+    elif rdb.ReparseTag == IO_REPARSE_TAG_MOUNT_POINT:
+        return rdb.MountPointReparseBuffer.PrintName
+    # Unsupported reparse point type.
     _raise_winerror(
-        get_last_error(),
-        'Error opening symbolic link \"%s\"'.format(path))
-  target_buffer = c_buffer(MAXIMUM_REPARSE_DATA_BUFFER_SIZE)
-  n_bytes_returned = DWORD()
-  io_result = DeviceIoControl(reparse_point_handle,
-                              FSCTL_GET_REPARSE_POINT,
-                              None,
-                              0,
-                              target_buffer,
-                              len(target_buffer),
-                              byref(n_bytes_returned),
-                              None)
-  CloseHandle(reparse_point_handle)
-  if not io_result:
-    _raise_winerror(
-        get_last_error(),
-        'Error reading symbolic link \"%s\"'.format(path))
-  rdb = REPARSE_DATA_BUFFER.from_buffer(target_buffer)
-  if rdb.ReparseTag == IO_REPARSE_TAG_SYMLINK:
-    return _preserve_encoding(path, rdb.SymbolicLinkReparseBuffer.PrintName)
-  elif rdb.ReparseTag == IO_REPARSE_TAG_MOUNT_POINT:
-    return _preserve_encoding(path, rdb.MountPointReparseBuffer.PrintName)
-  # Unsupported reparse point type
-  _raise_winerror(
-      ERROR_NOT_SUPPORTED,
-      'Error reading symbolic link \"%s\"'.format(path))
-
-
-def _preserve_encoding(source, target):
-  """Ensures target is the same string type (i.e. unicode or str) as source."""
-
-  if is_python3():
-    return target
-
-  if isinstance(source, unicode):
-    return unicode(target)
-  return str(target)
+        ERROR_NOT_SUPPORTED, f'Error reading symbolic link "{path}"'
+    )
 
 
 def _raise_winerror(code, error_desc):
-  win_error_desc = FormatError(code).strip()
-  error_desc = "%s: %s".format(error_desc, win_error_desc)
-  raise WinError(code, error_desc)
+    win_error_desc = FormatError(code).strip()
+    error_desc = f"{error_desc}: {win_error_desc}"
+    raise WinError(code, error_desc)

progress.py

@@ -1,5 +1,3 @@
-# -*- coding:utf-8 -*-
-#
 # Copyright (C) 2009 The Android Open Source Project
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -16,78 +14,225 @@
 
 import os
 import sys
-from time import time
-from repo_trace import IsTrace
+import time
 
-_NOT_TTY = not os.isatty(2)
+
+try:
+    import threading as _threading
+except ImportError:
+    import dummy_threading as _threading
+
+from repo_trace import IsTraceToStderr
+
+
+_TTY = sys.stderr.isatty()
 
 # This will erase all content in the current line (wherever the cursor is).
 # It does not move the cursor, so this is usually followed by \r to move to
 # column 0.
-CSI_ERASE_LINE = '\x1b[2K'
+CSI_ERASE_LINE = "\x1b[2K"
 
-class Progress(object):
-  def __init__(self, title, total=0, units='', print_newline=False,
-               always_print_percentage=False):
-    self._title = title
-    self._total = total
-    self._done = 0
-    self._lastp = -1
-    self._start = time()
-    self._show = False
-    self._units = units
-    self._print_newline = print_newline
-    self._always_print_percentage = always_print_percentage
+# This will erase all content in the current line after the cursor.  This is
+# useful for partial updates & progress messages as the terminal can display
+# it better.
+CSI_ERASE_LINE_AFTER = "\x1b[K"
 
-  def update(self, inc=1, msg=''):
-    self._done += inc
 
-    if _NOT_TTY or IsTrace():
-      return
+def convert_to_hms(total):
+    """Converts a period of seconds to hours, minutes, and seconds."""
+    hours, rem = divmod(total, 3600)
+    mins, secs = divmod(rem, 60)
+    return int(hours), int(mins), secs
 
-    if not self._show:
-      if 0.5 <= time() - self._start:
-        self._show = True
-      else:
-        return
 
-    if self._total <= 0:
-      sys.stderr.write('%s\r%s: %d,' % (
-        CSI_ERASE_LINE,
-        self._title,
-        self._done))
-      sys.stderr.flush()
+def duration_str(total):
+    """A less noisy timedelta.__str__.
+
+    The default timedelta stringification contains a lot of leading zeros and
+    uses microsecond resolution.  This makes for noisy output.
+    """
+    hours, mins, secs = convert_to_hms(total)
+    ret = f"{secs:.3f}s"
+    if mins:
+        ret = f"{mins}m{ret}"
+    if hours:
+        ret = f"{hours}h{ret}"
+    return ret
+
+
+def elapsed_str(total):
+    """Returns seconds in the format [H:]MM:SS.
+
+    Does not display a leading zero for minutes if under 10 minutes. This should
+    be used when displaying elapsed time in a progress indicator.
+    """
+    hours, mins, secs = convert_to_hms(total)
+    ret = f"{int(secs):>02d}"
+    if total >= 3600:
+        # Show leading zeroes if over an hour.
+        ret = f"{mins:>02d}:{ret}"
     else:
-      p = (100 * self._done) / self._total
+        ret = f"{mins}:{ret}"
+    if hours:
+        ret = f"{hours}:{ret}"
+    return ret
 
-      if self._lastp != p or self._always_print_percentage:
-        self._lastp = p
-        sys.stderr.write('%s\r%s: %3d%% (%d%s/%d%s)%s%s%s' % (
-          CSI_ERASE_LINE,
-          self._title,
-          p,
-          self._done, self._units,
-          self._total, self._units,
-          ' ' if msg else '', msg,
-          "\n" if self._print_newline else ""))
+
+def jobs_str(total):
+    return f"{total} job{'s' if total > 1 else ''}"
+
+
+class Progress:
+    def __init__(
+        self,
+        title,
+        total=0,
+        units="",
+        delay=True,
+        quiet=False,
+        show_elapsed=False,
+        elide=False,
+    ):
+        self._title = title
+        self._total = total
+        self._done = 0
+        self._start = time.time()
+        self._show = not delay
+        self._units = units
+        self._elide = elide and _TTY
+        self._quiet = quiet
+
+        # Only show the active jobs section if we run more than one in parallel.
+        self._show_jobs = False
+        self._active = 0
+
+        # Save the last message for displaying on refresh.
+        self._last_msg = None
+        self._show_elapsed = show_elapsed
+        self._update_event = _threading.Event()
+        self._update_thread = _threading.Thread(
+            target=self._update_loop,
+        )
+        self._update_thread.daemon = True
+
+        if not quiet and show_elapsed:
+            self._update_thread.start()
+
+    def _update_loop(self):
+        while True:
+            self.update(inc=0)
+            if self._update_event.wait(timeout=1):
+                return
+
+    def _write(self, s):
+        s = "\r" + s
+        if self._elide:
+            col = os.get_terminal_size(sys.stderr.fileno()).columns
+            if len(s) > col:
+                s = s[: col - 1] + ".."
+        sys.stderr.write(s)
         sys.stderr.flush()
 
-  def end(self):
-    if _NOT_TTY or IsTrace() or not self._show:
-      return
+    def start(self, name):
+        self._active += 1
+        if not self._show_jobs:
+            self._show_jobs = self._active > 1
+        self.update(inc=0, msg="started " + name)
 
-    if self._total <= 0:
-      sys.stderr.write('%s\r%s: %d, done.\n' % (
-        CSI_ERASE_LINE,
-        self._title,
-        self._done))
-      sys.stderr.flush()
-    else:
-      p = (100 * self._done) / self._total
-      sys.stderr.write('%s\r%s: %3d%% (%d%s/%d%s), done.\n' % (
-        CSI_ERASE_LINE,
-        self._title,
-        p,
-        self._done, self._units,
-        self._total, self._units))
-      sys.stderr.flush()
+    def finish(self, name):
+        self.update(msg="finished " + name)
+        self._active -= 1
+
+    def update(self, inc=1, msg=None):
+        """Updates the progress indicator.
+
+        Args:
+            inc: The number of items completed.
+            msg: The message to display. If None, use the last message.
+        """
+        self._done += inc
+        if msg is None:
+            msg = self._last_msg
+        self._last_msg = msg
+
+        if not _TTY or IsTraceToStderr() or self._quiet:
+            return
+
+        elapsed_sec = time.time() - self._start
+        if not self._show:
+            if 0.5 <= elapsed_sec:
+                self._show = True
+            else:
+                return
+
+        if self._total <= 0:
+            self._write(
+                "%s: %d,%s" % (self._title, self._done, CSI_ERASE_LINE_AFTER)
+            )
+        else:
+            p = (100 * self._done) / self._total
+            if self._show_jobs:
+                jobs = f"[{jobs_str(self._active)}] "
+            else:
+                jobs = ""
+            if self._show_elapsed:
+                elapsed = f" {elapsed_str(elapsed_sec)} |"
+            else:
+                elapsed = ""
+            self._write(
+                "%s: %2d%% %s(%d%s/%d%s)%s %s%s"
+                % (
+                    self._title,
+                    p,
+                    jobs,
+                    self._done,
+                    self._units,
+                    self._total,
+                    self._units,
+                    elapsed,
+                    msg,
+                    CSI_ERASE_LINE_AFTER,
+                )
+            )
+
+    def display_message(self, msg):
+        """Clears the current progress line and prints a message above it.
+
+        The progress bar is then redrawn on the next line.
+        """
+        if not _TTY or IsTraceToStderr() or self._quiet:
+            return
+
+        # Erase the current line, print the message with a newline,
+        # and then immediately redraw the progress bar on the new line.
+        sys.stderr.write("\r" + CSI_ERASE_LINE)
+        sys.stderr.write(msg + "\n")
+        sys.stderr.flush()
+        self.update(inc=0)
+
+    def end(self):
+        self._update_event.set()
+        if not _TTY or IsTraceToStderr() or self._quiet:
+            return
+
+        duration = duration_str(time.time() - self._start)
+        if self._total <= 0:
+            self._write(
+                "%s: %d, done in %s%s\n"
+                % (self._title, self._done, duration, CSI_ERASE_LINE_AFTER)
+            )
+        else:
+            p = (100 * self._done) / self._total
+            self._write(
+                "%s: %3d%% (%d%s/%d%s), done in %s%s\n"
+                % (
+                    self._title,
+                    p,
+                    self._done,
+                    self._units,
+                    self._total,
+                    self._units,
+                    duration,
+                    CSI_ERASE_LINE_AFTER,
+                )
+            )

pyproject.toml

@@ -0,0 +1,23 @@
+# Copyright 2023 The Android Open Source Project
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+[tool.black]
+line-length = 80
+# NB: Keep in sync with tox.ini.
+target-version = ['py36', 'py37', 'py38', 'py39', 'py310', 'py311'] #, 'py312'
+
+[tool.pytest.ini_options]
+markers = """
+    skip_cq: Skip tests in the CQ. Should be rarely used!
+"""

release/README.md

@@ -0,0 +1,2 @@
+These are helper tools for managing official releases.
+See the [release process](../docs/release-process.md) document for more details.

release/sign-launcher.py

@@ -0,0 +1,165 @@
+#!/usr/bin/env python3
+# Copyright (C) 2020 The Android Open Source Project
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Helper tool for signing repo launcher scripts correctly.
+
+This is intended to be run only by the official Repo release managers.
+"""
+
+import argparse
+import os
+import re
+import subprocess
+import sys
+
+import util
+
+
+def sign(opts):
+    """Sign the launcher!"""
+    output = ""
+    for key in opts.keys:
+        # We use ! at the end of the key so that gpg uses this specific key.
+        # Otherwise it uses the key as a lookup into the overall key and uses
+        # the default signing key.  i.e. It will see that KEYID_RSA is a subkey
+        # of another key, and use the primary key to sign instead of the subkey.
+        cmd = [
+            "gpg",
+            "--homedir",
+            opts.gpgdir,
+            "-u",
+            f"{key}!",
+            "--batch",
+            "--yes",
+            "--armor",
+            "--detach-sign",
+            "--output",
+            "-",
+            opts.launcher,
+        ]
+        ret = util.run(opts, cmd, encoding="utf-8", stdout=subprocess.PIPE)
+        output += ret.stdout
+
+    # Save the combined signatures into one file.
+    with open(f"{opts.launcher}.asc", "w", encoding="utf-8") as fp:
+        fp.write(output)
+
+
+def check(opts):
+    """Check the signature."""
+    util.run(opts, ["gpg", "--verify", f"{opts.launcher}.asc"])
+
+
+def get_version(opts):
+    """Get the version from |launcher|."""
+    # Make sure we don't search $PATH when signing the "repo" file in the cwd.
+    launcher = os.path.join(".", opts.launcher)
+    cmd = [launcher, "--version"]
+    ret = util.run(opts, cmd, encoding="utf-8", stdout=subprocess.PIPE)
+    m = re.search(r"repo launcher version ([0-9.]+)", ret.stdout)
+    if not m:
+        sys.exit(f"{opts.launcher}: unable to detect repo version")
+    return m.group(1)
+
+
+def postmsg(opts, version):
+    """Helpful info to show at the end for release manager."""
+    print(
+        f"""
+Repo launcher bucket:
+  gs://git-repo-downloads/
+
+You should first upload it with a specific version:
+  gsutil cp -a public-read {opts.launcher} gs://git-repo-downloads/repo-{version}
+  gsutil cp -a public-read {opts.launcher}.asc gs://git-repo-downloads/repo-{version}.asc
+
+Then to make it the public default:
+  gsutil cp -a public-read gs://git-repo-downloads/repo-{version} gs://git-repo-downloads/repo
+  gsutil cp -a public-read gs://git-repo-downloads/repo-{version}.asc gs://git-repo-downloads/repo.asc
+
+NB: If a rollback is necessary, the GS bucket archives old versions, and may be
+    accessed by specifying their unique id number.
+  gsutil ls -la gs://git-repo-downloads/repo gs://git-repo-downloads/repo.asc
+  gsutil cp -a public-read gs://git-repo-downloads/repo#<unique id> gs://git-repo-downloads/repo
+  gsutil cp -a public-read gs://git-repo-downloads/repo.asc#<unique id> gs://git-repo-downloads/repo.asc
+"""  # noqa: E501
+    )
+
+
+def get_parser():
+    """Get a CLI parser."""
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument(
+        "-n",
+        "--dry-run",
+        dest="dryrun",
+        action="store_true",
+        help="show everything that would be done",
+    )
+    parser.add_argument(
+        "--gpgdir",
+        default=os.path.join(util.HOMEDIR, ".gnupg", "repo"),
+        help="path to dedicated gpg dir with release keys "
+        "(default: ~/.gnupg/repo/)",
+    )
+    parser.add_argument(
+        "--keyid",
+        dest="keys",
+        default=[],
+        action="append",
+        help="alternative signing keys to use",
+    )
+    parser.add_argument(
+        "launcher",
+        default=os.path.join(util.TOPDIR, "repo"),
+        nargs="?",
+        help="the launcher script to sign",
+    )
+    return parser
+
+
+def main(argv):
+    """The main func!"""
+    parser = get_parser()
+    opts = parser.parse_args(argv)
+
+    if not os.path.exists(opts.gpgdir):
+        parser.error(f"--gpgdir does not exist: {opts.gpgdir}")
+    if not os.path.exists(opts.launcher):
+        parser.error(f"launcher does not exist: {opts.launcher}")
+
+    opts.launcher = os.path.relpath(opts.launcher)
+    print(
+        f'Signing "{opts.launcher}" launcher script and saving to '
+        f'"{opts.launcher}.asc"'
+    )
+
+    if opts.keys:
+        print(f'Using custom keys to sign: {" ".join(opts.keys)}')
+    else:
+        print("Using official Repo release keys to sign")
+        opts.keys = [util.KEYID_DSA, util.KEYID_RSA, util.KEYID_ECC]
+        util.import_release_key(opts)
+
+    version = get_version(opts)
+    sign(opts)
+    check(opts)
+    postmsg(opts, version)
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))

release/sign-tag.py

@@ -0,0 +1,167 @@
+#!/usr/bin/env python3
+# Copyright (C) 2020 The Android Open Source Project
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Helper tool for signing repo release tags correctly.
+
+This is intended to be run only by the official Repo release managers, but it
+could be run by people maintaining their own fork of the project.
+
+NB: Check docs/release-process.md for production freeze information.
+"""
+
+import argparse
+import os
+import re
+import subprocess
+import sys
+
+import util
+
+
+# We currently sign with the old DSA key as it's been around the longest.
+# We should transition to RSA by Jun 2020, and ECC by Jun 2021.
+KEYID = util.KEYID_DSA
+
+# Regular expression to validate tag names.
+RE_VALID_TAG = r"^v([0-9]+[.])+[0-9]+$"
+
+
+def sign(opts):
+    """Tag the commit & sign it!"""
+    # We use ! at the end of the key so that gpg uses this specific key.
+    # Otherwise it uses the key as a lookup into the overall key and uses the
+    # default signing key.  i.e. It will see that KEYID_RSA is a subkey of
+    # another key, and use the primary key to sign instead of the subkey.
+    cmd = [
+        "git",
+        "tag",
+        "-s",
+        opts.tag,
+        "-u",
+        f"{opts.key}!",
+        "-m",
+        f"repo {opts.tag}",
+        opts.commit,
+    ]
+
+    key = "GNUPGHOME"
+    print("+", f'export {key}="{opts.gpgdir}"')
+    oldvalue = os.getenv(key)
+    os.putenv(key, opts.gpgdir)
+    util.run(opts, cmd)
+    if oldvalue is None:
+        os.unsetenv(key)
+    else:
+        os.putenv(key, oldvalue)
+
+
+def check(opts):
+    """Check the signature."""
+    util.run(opts, ["git", "tag", "--verify", opts.tag])
+
+
+def postmsg(opts):
+    """Helpful info to show at the end for release manager."""
+    cmd = ["git", "rev-parse", "remotes/origin/stable"]
+    ret = util.run(opts, cmd, encoding="utf-8", stdout=subprocess.PIPE)
+    current_release = ret.stdout.strip()
+
+    cmd = [
+        "git",
+        "log",
+        "--format=%h (%aN) %s",
+        "--no-merges",
+        f"remotes/origin/stable..{opts.tag}",
+    ]
+    ret = util.run(opts, cmd, encoding="utf-8", stdout=subprocess.PIPE)
+    shortlog = ret.stdout.strip()
+
+    print(
+        f"""
+Here's the short log since the last release.
+{shortlog}
+
+To push release to the public:
+  git push origin {opts.commit}:stable {opts.tag} -n
+NB: People will start upgrading to this version immediately.
+
+To roll back a release:
+  git push origin --force {current_release}:stable -n
+"""
+    )
+
+
+def get_parser():
+    """Get a CLI parser."""
+    parser = argparse.ArgumentParser(
+        description=__doc__,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument(
+        "-n",
+        "--dry-run",
+        dest="dryrun",
+        action="store_true",
+        help="show everything that would be done",
+    )
+    parser.add_argument(
+        "--gpgdir",
+        default=os.path.join(util.HOMEDIR, ".gnupg", "repo"),
+        help="path to dedicated gpg dir with release keys "
+        "(default: ~/.gnupg/repo/)",
+    )
+    parser.add_argument(
+        "-f", "--force", action="store_true", help="force signing of any tag"
+    )
+    parser.add_argument(
+        "--keyid", dest="key", help="alternative signing key to use"
+    )
+    parser.add_argument("tag", help='the tag to create (e.g. "v2.0")')
+    parser.add_argument(
+        "commit", default="HEAD", nargs="?", help="the commit to tag"
+    )
+    return parser
+
+
+def main(argv):
+    """The main func!"""
+    parser = get_parser()
+    opts = parser.parse_args(argv)
+
+    if not os.path.exists(opts.gpgdir):
+        parser.error(f"--gpgdir does not exist: {opts.gpgdir}")
+
+    if not opts.force and not re.match(RE_VALID_TAG, opts.tag):
+        parser.error(
+            f'tag "{opts.tag}" does not match regex "{RE_VALID_TAG}"; '
+            "use --force to sign anyways"
+        )
+
+    if opts.key:
+        print(f"Using custom key to sign: {opts.key}")
+    else:
+        print("Using official Repo release key to sign")
+        opts.key = KEYID
+        util.import_release_key(opts)
+
+    sign(opts)
+    check(opts)
+    postmsg(opts)
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))

release/update-hooks

@@ -0,0 +1,143 @@
+#!/usr/bin/env python3
+# Copyright (C) 2024 The Android Open Source Project
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Helper tool for updating hooks from their various upstreams."""
+
+import argparse
+import base64
+import json
+from pathlib import Path
+import sys
+from typing import List, Optional
+import urllib.request
+
+
+assert sys.version_info >= (3, 8), "Python 3.8+ required"
+
+
+TOPDIR = Path(__file__).resolve().parent.parent
+HOOKS_DIR = TOPDIR / "hooks"
+
+
+def update_hook_commit_msg() -> None:
+    """Update commit-msg hook from Gerrit."""
+    hook = HOOKS_DIR / "commit-msg"
+    print(
+        f"{hook.name}: Updating from https://gerrit.googlesource.com/gerrit/"
+        "+/HEAD/resources/com/google/gerrit/server/tools/root/hooks/commit-msg"
+    )
+
+    # Get the current commit.
+    url = "https://gerrit.googlesource.com/gerrit/+/HEAD?format=JSON"
+    with urllib.request.urlopen(url) as fp:
+        data = fp.read()
+    # Discard the xss protection.
+    data = data.split(b"\n", 1)[1]
+    data = json.loads(data)
+    commit = data["commit"]
+
+    # Fetch the data for that commit.
+    url = (
+        f"https://gerrit.googlesource.com/gerrit/+/{commit}/"
+        "resources/com/google/gerrit/server/tools/root/hooks/commit-msg"
+    )
+    with urllib.request.urlopen(f"{url}?format=TEXT") as fp:
+        data = fp.read()
+
+    # gitiles base64 encodes text data.
+    data = base64.b64decode(data)
+
+    # Inject header into the hook.
+    lines = data.split(b"\n")
+    lines = (
+        lines[:1]
+        + [
+            b"# DO NOT EDIT THIS FILE",
+            (
+                b"# All updates should be sent upstream: "
+                b"https://gerrit.googlesource.com/gerrit/"
+            ),
+            f"# This is synced from commit: {commit}".encode("utf-8"),
+            b"# DO NOT EDIT THIS FILE",
+        ]
+        + lines[1:]
+    )
+    data = b"\n".join(lines)
+
+    # Update the hook.
+    hook.write_bytes(data)
+    hook.chmod(0o755)
+
+
+def update_hook_pre_auto_gc() -> None:
+    """Update pre-auto-gc hook from git."""
+    hook = HOOKS_DIR / "pre-auto-gc"
+    print(
+        f"{hook.name}: Updating from https://github.com/git/git/"
+        "HEAD/contrib/hooks/pre-auto-gc-battery"
+    )
+
+    # Get the current commit.
+    headers = {
+        "Accept": "application/vnd.github+json",
+        "X-GitHub-Api-Version": "2022-11-28",
+    }
+    url = "https://api.github.com/repos/git/git/git/refs/heads/master"
+    req = urllib.request.Request(url, headers=headers)
+    with urllib.request.urlopen(req) as fp:
+        data = fp.read()
+    data = json.loads(data)
+
+    # Fetch the data for that commit.
+    commit = data["object"]["sha"]
+    url = (
+        f"https://raw.githubusercontent.com/git/git/{commit}/"
+        "contrib/hooks/pre-auto-gc-battery"
+    )
+    with urllib.request.urlopen(url) as fp:
+        data = fp.read()
+
+    # Inject header into the hook.
+    lines = data.split(b"\n")
+    lines = (
+        lines[:1]
+        + [
+            b"# DO NOT EDIT THIS FILE",
+            (
+                b"# All updates should be sent upstream: "
+                b"https://github.com/git/git/"
+            ),
+            f"# This is synced from commit: {commit}".encode("utf-8"),
+            b"# DO NOT EDIT THIS FILE",
+        ]
+        + lines[1:]
+    )
+    data = b"\n".join(lines)
+
+    # Update the hook.
+    hook.write_bytes(data)
+    hook.chmod(0o755)
+
+
+def main(argv: Optional[List[str]] = None) -> Optional[int]:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.parse_args(argv)
+
+    update_hook_commit_msg()
+    update_hook_pre_auto_gc()
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))

release/update-manpages

@@ -1,6 +1,5 @@
-# -*- coding:utf-8 -*-
-#
-# Copyright (C) 2013 The Android Open Source Project
+#!/usr/bin/env python3
+# Copyright (C) 2021 The Android Open Source Project
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -14,7 +13,14 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""Helper tool for generating manual page for all repo commands.
+
+This is intended to be run before every official Repo release.
+"""
+
 import sys
 
-def is_python3():
-  return sys.version_info[0] == 3
+import update_manpages
+
+
+sys.exit(update_manpages.main(sys.argv[1:]))

release/update_manpages.py

@@ -0,0 +1,183 @@
+# Copyright (C) 2021 The Android Open Source Project
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Helper tool for generating manual page for all repo commands.
+
+Most code lives in this module so it can be unittested.
+"""
+
+import argparse
+import functools
+import multiprocessing
+import os
+from pathlib import Path
+import re
+import shutil
+import subprocess
+import sys
+import tempfile
+from typing import List
+
+
+THIS_FILE = Path(__file__).resolve()
+TOPDIR = THIS_FILE.parent.parent
+MANDIR = TOPDIR.joinpath("man")
+
+# Load repo local modules.
+sys.path.insert(0, str(TOPDIR))
+from git_command import RepoSourceVersion
+import subcmds
+
+
+def worker(cmd, **kwargs):
+    subprocess.run(cmd, **kwargs)
+
+
+def get_parser() -> argparse.ArgumentParser:
+    """Get argument parser."""
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument(
+        "-n",
+        "--check",
+        "--dry-run",
+        action="store_const",
+        const=True,
+        help="Check if changes are necessary; don't actually change files",
+    )
+    return parser
+
+
+def main(argv: List[str]) -> int:
+    parser = get_parser()
+    opts = parser.parse_args(argv)
+
+    if not shutil.which("help2man"):
+        sys.exit("Please install help2man to continue.")
+
+    # Let repo know we're generating man pages so it can avoid some dynamic
+    # behavior (like probing active number of CPUs).  We use a weird name &
+    # value to make it less likely for users to set this var themselves.
+    os.environ["_REPO_GENERATE_MANPAGES_"] = " indeed! "
+
+    # "repo branch" is an alias for "repo branches".
+    del subcmds.all_commands["branch"]
+    (MANDIR / "repo-branch.1").write_text(".so man1/repo-branches.1")
+
+    version = RepoSourceVersion()
+    cmdlist = [
+        [
+            "help2man",
+            "-N",
+            "-n",
+            f"repo {cmd} - manual page for repo {cmd}",
+            "-S",
+            f"repo {cmd}",
+            "-m",
+            "Repo Manual",
+            f"--version-string={version}",
+            "-o",
+            MANDIR.joinpath(f"repo-{cmd}.1.tmp"),
+            "./repo",
+            "-h",
+            f"help {cmd}",
+        ]
+        for cmd in subcmds.all_commands
+    ]
+    cmdlist.append(
+        [
+            "help2man",
+            "-N",
+            "-n",
+            "repository management tool built on top of git",
+            "-S",
+            "repo",
+            "-m",
+            "Repo Manual",
+            f"--version-string={version}",
+            "-o",
+            MANDIR.joinpath("repo.1.tmp"),
+            "./repo",
+            "-h",
+            "--help-all",
+        ]
+    )
+
+    with tempfile.TemporaryDirectory() as tempdir:
+        tempdir = Path(tempdir)
+        repo_dir = tempdir / ".repo"
+        repo_dir.mkdir()
+        (repo_dir / "repo").symlink_to(TOPDIR)
+
+        # Create a repo wrapper using the active Python executable.  We can't
+        # pass this directly to help2man as it's too simple, so insert it via
+        # shebang.
+        data = (TOPDIR / "repo").read_text(encoding="utf-8")
+        tempbin = tempdir / "repo"
+        tempbin.write_text(f"#!{sys.executable}\n" + data, encoding="utf-8")
+        tempbin.chmod(0o755)
+
+        # Run all cmd in parallel, and wait for them to finish.
+        with multiprocessing.Pool() as pool:
+            pool.map(
+                functools.partial(worker, cwd=tempdir, check=True), cmdlist
+            )
+
+    ret = 0
+    for tmp_path in MANDIR.glob("*.1.tmp"):
+        path = tmp_path.parent / tmp_path.stem
+        old_data = path.read_text() if path.exists() else ""
+
+        data = tmp_path.read_text()
+        tmp_path.unlink()
+
+        data = replace_regex(data)
+
+        # If the only thing that changed was the date, don't refresh.  This
+        # avoids a lot of noise when only one file actually updates.
+        old_data = re.sub(
+            r'^(\.TH REPO "1" ")([^"]+)', r"\1", old_data, flags=re.M
+        )
+        new_data = re.sub(r'^(\.TH REPO "1" ")([^"]+)', r"\1", data, flags=re.M)
+        if old_data != new_data:
+            if opts.check:
+                ret = 1
+                print(
+                    f"{THIS_FILE.name}: {path.name}: "
+                    "man page needs regenerating",
+                    file=sys.stderr,
+                )
+            else:
+                path.write_text(data)
+
+    return ret
+
+
+def replace_regex(data):
+    """Replace semantically null regexes in the data.
+
+    Args:
+        data: manpage text.
+
+    Returns:
+        Updated manpage text.
+    """
+    regex = (
+        (r"(It was generated by help2man) [0-9.]+", r"\g<1>."),
+        (r"^\033\[[0-9;]*m([^\033]*)\033\[m", r"\g<1>"),
+        (r"^\.IP\n(.*:)\n", r".SS \g<1>\n"),
+        (r"^\.PP\nDescription", r".SH DETAILS"),
+    )
+    for pattern, replacement in regex:
+        data = re.sub(pattern, replacement, data, flags=re.M)
+    return data

release/util.py

@@ -0,0 +1,75 @@
+# Copyright (C) 2020 The Android Open Source Project
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Random utility code for release tools."""
+
+import os
+import re
+import shlex
+import subprocess
+import sys
+
+
+assert sys.version_info >= (3, 6), "This module requires Python 3.6+"
+
+
+TOPDIR = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+HOMEDIR = os.path.expanduser("~")
+
+
+# These are the release keys we sign with.
+KEYID_DSA = "8BB9AD793E8E6153AF0F9A4416530D5E920F5C65"
+KEYID_RSA = "A34A13BE8E76BFF46A0C022DA2E75A824AAB9624"
+KEYID_ECC = "E1F9040D7A3F6DAFAC897CD3D3B95DA243E48A39"
+
+
+def cmdstr(cmd):
+    """Get a nicely quoted shell command."""
+    return " ".join(shlex.quote(x) for x in cmd)
+
+
+def run(opts, cmd, check=True, **kwargs):
+    """Helper around subprocess.run to include logging."""
+    print("+", cmdstr(cmd))
+    if opts.dryrun:
+        cmd = ["true", "--"] + cmd
+    try:
+        return subprocess.run(cmd, check=check, **kwargs)
+    except subprocess.CalledProcessError as e:
+        print(f"aborting: {e}", file=sys.stderr)
+        sys.exit(1)
+
+
+def import_release_key(opts):
+    """Import the public key of the official release repo signing key."""
+    # Extract the key from our repo launcher.
+    launcher = getattr(opts, "launcher", os.path.join(TOPDIR, "repo"))
+    print(f'Importing keys from "{launcher}" launcher script')
+    with open(launcher, encoding="utf-8") as fp:
+        data = fp.read()
+
+    keys = re.findall(
+        r"\n-----BEGIN PGP PUBLIC KEY BLOCK-----\n[^-]*"
+        r"\n-----END PGP PUBLIC KEY BLOCK-----\n",
+        data,
+        flags=re.M,
+    )
+    run(opts, ["gpg", "--import"], input="\n".join(keys).encode("utf-8"))
+
+    print("Marking keys as fully trusted")
+    run(
+        opts,
+        ["gpg", "--import-ownertrust"],
+        input=f"{KEYID_DSA}:6:\n".encode("utf-8"),
+    )

repo_logging.py

@@ -0,0 +1,93 @@
+# Copyright (C) 2023 The Android Open Source Project
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Logic for printing user-friendly logs in repo."""
+
+import logging
+
+from color import Coloring
+from error import RepoExitError
+
+
+SEPARATOR = "=" * 80
+MAX_PRINT_ERRORS = 5
+
+
+class _ConfigMock:
+    """Default coloring config to use when Logging.config is not set."""
+
+    def __init__(self):
+        self.default_values = {"color.ui": "auto"}
+
+    def GetString(self, x):
+        return self.default_values.get(x, None)
+
+
+class _LogColoring(Coloring):
+    """Coloring outstream for logging."""
+
+    def __init__(self, config):
+        super().__init__(config, "logs")
+        self.error = self.nofmt_colorer("error", fg="red")
+        self.warning = self.nofmt_colorer("warn", fg="yellow")
+        self.levelMap = {
+            "WARNING": self.warning,
+            "ERROR": self.error,
+        }
+
+
+class _LogColoringFormatter(logging.Formatter):
+    """Coloring formatter for logging."""
+
+    def __init__(self, config=None, *args, **kwargs):
+        self.config = config if config else _ConfigMock()
+        self.colorer = _LogColoring(self.config)
+        super().__init__(*args, **kwargs)
+
+    def format(self, record):
+        """Formats |record| with color."""
+        msg = super().format(record)
+        colorer = self.colorer.levelMap.get(record.levelname)
+        return msg if not colorer else colorer(msg)
+
+
+class RepoLogger(logging.Logger):
+    """Repo Logging Module."""
+
+    def __init__(self, name: str, config=None, **kwargs):
+        super().__init__(name, **kwargs)
+        handler = logging.StreamHandler()
+        handler.setFormatter(_LogColoringFormatter(config))
+        self.addHandler(handler)
+
+    def log_aggregated_errors(self, err: RepoExitError):
+        """Print all aggregated logs."""
+        self.error(SEPARATOR)
+
+        if not err.aggregate_errors:
+            self.error("Repo command failed: %s", type(err).__name__)
+            self.error("\t%s", str(err))
+            return
+
+        self.error(
+            "Repo command failed due to the following `%s` errors:",
+            type(err).__name__,
+        )
+        self.error(
+            "\n".join(str(e) for e in err.aggregate_errors[:MAX_PRINT_ERRORS])
+        )
+
+        diff = len(err.aggregate_errors) - MAX_PRINT_ERRORS
+        if diff > 0:
+            self.error("+%d additional errors...", diff)

repo_trace.py

@@ -1,5 +1,3 @@
-# -*- coding:utf-8 -*-
-#
 # Copyright (C) 2008 The Android Open Source Project
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -17,24 +15,157 @@
 """Logic for tracing repo interactions.
 
 Activated via `repo --trace ...` or `REPO_TRACE=1 repo ...`.
+
+Temporary: Tracing is always on. Set `REPO_TRACE=0` to turn off.
+To also include trace outputs in stderr do `repo --trace_to_stderr ...`
 """
 
-from __future__ import print_function
-import sys
+import contextlib
 import os
+import sys
+import tempfile
+import time
+
+import platform_utils
+
 
 # Env var to implicitly turn on tracing.
-REPO_TRACE = 'REPO_TRACE'
+REPO_TRACE = "REPO_TRACE"
+
+# Temporarily set tracing to always on unless user expicitly sets to 0.
+_TRACE = os.environ.get(REPO_TRACE) != "0"
+_TRACE_TO_STDERR = False
+_TRACE_FILE = None
+_TRACE_FILE_NAME = "TRACE_FILE"
+_MAX_SIZE = 70  # in MiB
+_NEW_COMMAND_SEP = "+++++++++++++++NEW COMMAND+++++++++++++++++++"
+
+
+def IsTraceToStderr():
+    """Whether traces are written to stderr."""
+    return _TRACE_TO_STDERR
 
-_TRACE = os.environ.get(REPO_TRACE) == '1'
 
 def IsTrace():
-  return _TRACE
+    """Whether tracing is enabled."""
+    return _TRACE
+
+
+def SetTraceToStderr():
+    """Enables tracing logging to stderr."""
+    global _TRACE_TO_STDERR
+    _TRACE_TO_STDERR = True
+
 
 def SetTrace():
-  global _TRACE
-  _TRACE = True
+    """Enables tracing."""
+    global _TRACE
+    _TRACE = True
 
-def Trace(fmt, *args):
-  if IsTrace():
-    print(fmt % args, file=sys.stderr)
+
+def _SetTraceFile(quiet):
+    """Sets the trace file location."""
+    global _TRACE_FILE
+    _TRACE_FILE = _GetTraceFile(quiet)
+
+
+class Trace(contextlib.ContextDecorator):
+    """Used to capture and save git traces."""
+
+    def _time(self):
+        """Generate nanoseconds of time in a py3.6 safe way"""
+        return int(time.time() * 1e9)
+
+    def __init__(self, fmt, *args, first_trace=False, quiet=True):
+        """Initialize the object.
+
+        Args:
+            fmt: The format string for the trace.
+            *args: Arguments to pass to formatting.
+            first_trace: Whether this is the first trace of a `repo` invocation.
+            quiet: Whether to suppress notification of trace file location.
+        """
+        if not IsTrace():
+            return
+        self._trace_msg = fmt % args
+
+        if not _TRACE_FILE:
+            _SetTraceFile(quiet)
+
+        if first_trace:
+            _ClearOldTraces()
+            self._trace_msg = f"{_NEW_COMMAND_SEP} {self._trace_msg}"
+
+    def __enter__(self):
+        if not IsTrace():
+            return self
+
+        print_msg = (
+            f"PID: {os.getpid()} START: {self._time()} :{self._trace_msg}\n"
+        )
+
+        with open(_TRACE_FILE, "a") as f:
+            print(print_msg, file=f)
+
+        if _TRACE_TO_STDERR:
+            print(print_msg, file=sys.stderr)
+
+        return self
+
+    def __exit__(self, *exc):
+        if not IsTrace():
+            return False
+
+        print_msg = (
+            f"PID: {os.getpid()} END: {self._time()} :{self._trace_msg}\n"
+        )
+
+        with open(_TRACE_FILE, "a") as f:
+            print(print_msg, file=f)
+
+        if _TRACE_TO_STDERR:
+            print(print_msg, file=sys.stderr)
+
+        return False
+
+
+def _GetTraceFile(quiet):
+    """Get the trace file or create one."""
+    # TODO: refactor to pass repodir to Trace.
+    repo_dir = os.path.dirname(os.path.dirname(__file__))
+    trace_file = os.path.join(repo_dir, _TRACE_FILE_NAME)
+    if not quiet:
+        print(f"Trace outputs in {trace_file}", file=sys.stderr)
+    return trace_file
+
+
+def _ClearOldTraces():
+    """Clear the oldest commands if trace file is too big."""
+    try:
+        with open(_TRACE_FILE, errors="ignore") as f:
+            if os.path.getsize(f.name) / (1024 * 1024) <= _MAX_SIZE:
+                return
+            trace_lines = f.readlines()
+    except FileNotFoundError:
+        return
+
+    while sum(len(x) for x in trace_lines) / (1024 * 1024) > _MAX_SIZE:
+        for i, line in enumerate(trace_lines):
+            if "END:" in line and _NEW_COMMAND_SEP in line:
+                trace_lines = trace_lines[i + 1 :]
+                break
+        else:
+            # The last chunk is bigger than _MAX_SIZE, so just throw everything
+            # away.
+            trace_lines = []
+
+    while trace_lines and trace_lines[-1] == "\n":
+        trace_lines = trace_lines[:-1]
+    # Write to a temporary file with a unique name in the same filesystem
+    # before replacing the original trace file.
+    temp_dir, temp_prefix = os.path.split(_TRACE_FILE)
+    with tempfile.NamedTemporaryFile(
+        "w", dir=temp_dir, prefix=temp_prefix, delete=False
+    ) as f:
+        f.writelines(trace_lines)
+    platform_utils.rename(f.name, _TRACE_FILE)

requirements.json

@@ -0,0 +1,59 @@
+# This file declares various requirements for this version of repo.  The
+# launcher script will load it and check the constraints before trying to run
+# us.  This avoids issues of the launcher using an old version of Python (e.g.
+# 3.5) while the codebase has moved on to requiring something much newer (e.g.
+# 3.8).  If the launcher tried to import us, it would fail with syntax errors.
+
+# This is a JSON file with line-level comments allowed.
+
+# Always keep backwards compatibility in mine.  The launcher script is robust
+# against missing values, but when a field is renamed/removed, it means older
+# versions of the launcher script won't be able to enforce the constraint.
+
+# When requiring versions, always use lists as they are easy to parse & compare
+# in Python.  Strings would require futher processing to turn into a list.
+
+# Version constraints should be expressed in pairs: soft & hard.  Soft versions
+# are when we start warning users that their software too old and we're planning
+# on dropping support for it, so they need to start planning system upgrades.
+# Hard versions are when we refuse to work the tool.  Users will be shown an
+# error message before we abort entirely.
+
+# When deciding whether to upgrade a version requirement, check out the distro
+# lists to see who will be impacted:
+# https://gerrit.googlesource.com/git-repo/+/HEAD/docs/release-process.md#Project-References
+
+{
+  # The repo launcher itself.  This allows us to force people to upgrade as some
+  # ignore the warnings about it being out of date, or install ancient versions
+  # to start with for whatever reason.
+  #
+  # NB: Repo launchers started checking this file with repo-2.12, so listing
+  # versions older than that won't make a difference.
+  "repo": {
+    "hard": [2, 11],
+    "soft": [2, 11]
+  },
+
+  # Supported Python versions.
+  #
+  # python-3.6 is in Ubuntu Bionic.
+  # python-3.7 is in Debian Buster.
+  "python": {
+    "hard": [3, 6],
+    "soft": [3, 6]
+  },
+
+  # Supported git versions.
+  #
+  # git-1.9.1 is in Ubuntu Trusty.
+  # git-2.1.4 is in Debian Jessie.
+  # git-2.7.4 is in Ubuntu Xenial.
+  # git-2.11.0 is in Debian Stretch.
+  # git-2.17.0 is in Ubuntu Bionic.
+  # git-2.20.1 is in Debian Buster.
+  "git": {
+    "hard": [1, 9, 1],
+    "soft": [2, 7, 4]
+  }
+}

run_tests

@@ -1,5 +1,4 @@
-#!/usr/bin/env python
-# -*- coding:utf-8 -*-
+#!/usr/bin/env python3
 # Copyright 2019 The Android Open Source Project
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -14,40 +13,123 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-"""Wrapper to run pytest with the right settings."""
+"""Wrapper to run linters and pytest with the right settings."""
 
-from __future__ import print_function
-
-import errno
+import functools
 import os
+import shutil
 import subprocess
 import sys
+from typing import List
 
 
-def run_pytest(cmd, argv):
-  """Run the unittests via |cmd|."""
-  try:
-    return subprocess.call([cmd] + argv)
-  except OSError as e:
-    if e.errno == errno.ENOENT:
-      print('%s: unable to run `%s`: %s' % (__file__, cmd, e), file=sys.stderr)
-      print('%s: Try installing pytest: sudo apt-get install python-pytest' %
-            (__file__,), file=sys.stderr)
-      return 127
-    else:
-      raise
+ROOT_DIR = os.path.dirname(os.path.realpath(__file__))
+
+
+@functools.lru_cache()
+def is_ci() -> bool:
+    """Whether we're running in our CI system."""
+    return os.getenv("LUCI_CQ") == "yes"
+
+
+def run_pytest(argv: List[str]) -> int:
+    """Returns the exit code from pytest."""
+    if is_ci():
+        argv = ["-m", "not skip_cq"] + argv
+
+    return subprocess.run(
+        [sys.executable, "-m", "pytest"] + argv,
+        check=False,
+        cwd=ROOT_DIR,
+    ).returncode
+
+
+def run_pytest_py38(argv: List[str]) -> int:
+    """Returns the exit code from pytest under Python 3.8."""
+    if is_ci():
+        argv = ["-m", "not skip_cq"] + argv
+
+    try:
+        return subprocess.run(
+            [
+                "vpython3",
+                "-vpython-spec",
+                "run_tests.vpython3.8",
+                "-m",
+                "pytest",
+            ]
+            + argv,
+            check=False,
+            cwd=ROOT_DIR,
+        ).returncode
+    except FileNotFoundError:
+        # Skip if the user doesn't have vpython from depot_tools.
+        return 0
+
+
+def run_black():
+    """Returns the exit code from black."""
+    # Black by default only matches .py files.  We have to list standalone
+    # scripts manually.
+    extra_programs = [
+        "repo",
+        "run_tests",
+        "release/update-hooks",
+        "release/update-manpages",
+    ]
+    return subprocess.run(
+        [sys.executable, "-m", "black", "--check", ROOT_DIR] + extra_programs,
+        check=False,
+        cwd=ROOT_DIR,
+    ).returncode
+
+
+def run_flake8():
+    """Returns the exit code from flake8."""
+    return subprocess.run(
+        [sys.executable, "-m", "flake8", ROOT_DIR],
+        check=False,
+        cwd=ROOT_DIR,
+    ).returncode
+
+
+def run_isort():
+    """Returns the exit code from isort."""
+    return subprocess.run(
+        [sys.executable, "-m", "isort", "--check", ROOT_DIR],
+        check=False,
+        cwd=ROOT_DIR,
+    ).returncode
+
+
+def run_update_manpages() -> int:
+    """Returns the exit code from release/update-manpages."""
+    # Allow this to fail on CI, but not local devs.
+    if is_ci() and not shutil.which("help2man"):
+        print("update-manpages: help2man not found; skipping test")
+        return 0
+
+    return subprocess.run(
+        [sys.executable, "release/update-manpages", "--check"],
+        check=False,
+        cwd=ROOT_DIR,
+    ).returncode
 
 
 def main(argv):
-  """The main entry."""
-  # Add the repo tree to PYTHONPATH as the tests expect to be able to import
-  # modules directly.
-  topdir = os.path.dirname(os.path.realpath(__file__))
-  pythonpath = os.environ.get('PYTHONPATH', '')
-  os.environ['PYTHONPATH'] = '%s:%s' % (topdir, pythonpath)
-
-  return run_pytest('pytest', argv)
+    """The main entry."""
+    checks = (
+        functools.partial(run_pytest, argv),
+        functools.partial(run_pytest_py38, argv),
+        run_black,
+        run_flake8,
+        run_isort,
+        run_update_manpages,
+    )
+    # Run all the tests all the time to get full feedback.  Don't exit on the
+    # first error as that makes it more difficult to iterate in the CQ.
+    return 1 if sum(c() for c in checks) else 0
 
 
-if __name__ == '__main__':
-  sys.exit(main(sys.argv[1:]))
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))

run_tests.vpython3

@@ -0,0 +1,125 @@
+# This is a vpython "spec" file.
+#
+# Read more about `vpython` and how to modify this file here:
+#   https://chromium.googlesource.com/infra/infra/+/main/doc/users/vpython.md
+# List of available wheels:
+#   https://chromium.googlesource.com/infra/infra/+/main/infra/tools/dockerbuild/wheels.md
+
+python_version: "3.11"
+
+wheel: <
+  name: "infra/python/wheels/pytest-py3"
+  version: "version:8.3.4"
+>
+
+# Required by pytest==8.3.4
+wheel: <
+  name: "infra/python/wheels/py-py2_py3"
+  version: "version:1.11.0"
+>
+
+# Required by pytest==8.3.4
+wheel: <
+  name: "infra/python/wheels/iniconfig-py3"
+  version: "version:1.1.1"
+>
+
+# Required by pytest==8.3.4
+wheel: <
+  name: "infra/python/wheels/packaging-py3"
+  version: "version:23.0"
+>
+
+# Required by pytest==8.3.4
+wheel: <
+  name: "infra/python/wheels/pluggy-py3"
+  version: "version:1.5.0"
+>
+
+# Required by pytest==8.3.4
+wheel: <
+  name: "infra/python/wheels/toml-py3"
+  version: "version:0.10.1"
+>
+
+# Required by pytest==8.3.4
+wheel: <
+  name: "infra/python/wheels/pyparsing-py3"
+  version: "version:3.0.7"
+>
+
+# Required by pytest==8.3.4
+wheel: <
+  name: "infra/python/wheels/attrs-py2_py3"
+  version: "version:21.4.0"
+>
+
+# NB: Keep in sync with constraints.txt.
+wheel: <
+  name: "infra/python/wheels/black-py3"
+  version: "version:25.1.0"
+>
+
+# Required by black==25.1.0
+wheel: <
+  name: "infra/python/wheels/mypy-extensions-py3"
+  version: "version:0.4.3"
+>
+
+# Required by black==25.1.0
+wheel: <
+  name: "infra/python/wheels/tomli-py3"
+  version: "version:2.0.1"
+>
+
+# Required by black==25.1.0
+wheel: <
+  name: "infra/python/wheels/platformdirs-py3"
+  version: "version:2.5.2"
+>
+
+# Required by black==25.1.0
+wheel: <
+  name: "infra/python/wheels/pathspec-py3"
+  version: "version:0.9.0"
+>
+
+# Required by black==25.1.0
+wheel: <
+  name: "infra/python/wheels/typing-extensions-py3"
+  version: "version:4.3.0"
+>
+
+# Required by black==25.1.0
+wheel: <
+  name: "infra/python/wheels/click-py3"
+  version: "version:8.0.3"
+>
+
+wheel: <
+  name: "infra/python/wheels/flake8-py2_py3"
+  version: "version:6.0.0"
+>
+
+# Required by flake8==6.0.0
+wheel: <
+  name: "infra/python/wheels/mccabe-py2_py3"
+  version: "version:0.7.0"
+>
+
+# Required by flake8==6.0.0
+wheel: <
+  name: "infra/python/wheels/pyflakes-py2_py3"
+  version: "version:3.0.1"
+>
+
+# Required by flake8==6.0.0
+wheel: <
+  name: "infra/python/wheels/pycodestyle-py2_py3"
+  version: "version:2.10.0"
+>
+
+wheel: <
+  name: "infra/python/wheels/isort-py3"
+  version: "version:5.10.1"
+>

run_tests.vpython3.8

@@ -0,0 +1,67 @@
+# This is a vpython "spec" file.
+#
+# Read more about `vpython` and how to modify this file here:
+#   https://chromium.googlesource.com/infra/infra/+/main/doc/users/vpython.md
+# List of available wheels:
+#   https://chromium.googlesource.com/infra/infra/+/main/infra/tools/dockerbuild/wheels.md
+
+python_version: "3.8"
+
+wheel: <
+  name: "infra/python/wheels/pytest-py3"
+  version: "version:8.3.4"
+>
+
+# Required by pytest==8.3.4
+wheel: <
+  name: "infra/python/wheels/py-py2_py3"
+  version: "version:1.11.0"
+>
+
+# Required by pytest==8.3.4
+wheel: <
+  name: "infra/python/wheels/iniconfig-py3"
+  version: "version:1.1.1"
+>
+
+# Required by pytest==8.3.4
+wheel: <
+  name: "infra/python/wheels/packaging-py3"
+  version: "version:23.0"
+>
+
+# Required by pytest==8.3.4
+wheel: <
+  name: "infra/python/wheels/pluggy-py3"
+  version: "version:1.5.0"
+>
+
+# Required by pytest==8.3.4
+wheel: <
+  name: "infra/python/wheels/toml-py3"
+  version: "version:0.10.1"
+>
+
+# Required by pytest==8.3.4
+wheel: <
+  name: "infra/python/wheels/tomli-py3"
+  version: "version:2.1.0"
+>
+
+# Required by pytest==8.3.4
+wheel: <
+  name: "infra/python/wheels/pyparsing-py3"
+  version: "version:3.0.7"
+>
+
+# Required by pytest==8.3.4
+wheel: <
+  name: "infra/python/wheels/attrs-py2_py3"
+  version: "version:21.4.0"
+>
+
+# Required by pytest==8.3.4
+wheel: <
+  name: "infra/python/wheels/exceptiongroup-py3"
+  version: "version:1.1.2"
+>

setup.py

@@ -1,5 +1,4 @@
-#!/usr/bin/env python
-# -*- coding:utf-8 -*-
+#!/usr/bin/env python3
 # Copyright 2019 The Android Open Source Project
 #
 # Licensed under the Apache License, Version 2.0 (the 'License");
@@ -16,9 +15,8 @@
 
 """Python packaging for repo."""
 
-from __future__ import print_function
-
 import os
+
 import setuptools
 
 
@@ -26,38 +24,39 @@ TOPDIR = os.path.dirname(os.path.abspath(__file__))
 
 
 # Rip out the first intro paragraph.
-with open(os.path.join(TOPDIR, 'README.md')) as fp:
+with open(os.path.join(TOPDIR, "README.md")) as fp:
     lines = fp.read().splitlines()[2:]
-    end = lines.index('')
-    long_description = ' '.join(lines[0:end])
+    end = lines.index("")
+    long_description = " ".join(lines[0:end])
 
 
 # https://packaging.python.org/tutorials/packaging-projects/
 setuptools.setup(
-    name='repo',
-    version='1.13.8',
-    maintainer='Various',
-    maintainer_email='repo-discuss@googlegroups.com',
-    description='Repo helps manage many Git repositories',
+    name="repo",
+    version="2",
+    maintainer="Various",
+    maintainer_email="repo-discuss@googlegroups.com",
+    description="Repo helps manage many Git repositories",
     long_description=long_description,
-    long_description_content_type='text/plain',
-    url='https://gerrit.googlesource.com/git-repo/',
+    long_description_content_type="text/plain",
+    url="https://gerrit.googlesource.com/git-repo/",
     project_urls={
-        'Bug Tracker': 'https://bugs.chromium.org/p/gerrit/issues/list?q=component:repo',
+        "Bug Tracker": "https://issues.gerritcodereview.com/issues?q=is:open%20componentid:1370071",  # noqa: E501
     },
     # https://pypi.org/classifiers/
     classifiers=[
-        'Development Status :: 6 - Mature',
-        'Environment :: Console',
-        'Intended Audience :: Developers',
-        'License :: OSI Approved :: Apache Software License',
-        'Natural Language :: English',
-        'Operating System :: MacOS :: MacOS X',
-        'Operating System :: Microsoft :: Windows :: Windows 10',
-        'Operating System :: POSIX :: Linux',
-        'Topic :: Software Development :: Version Control :: Git',
+        "Development Status :: 6 - Mature",
+        "Environment :: Console",
+        "Intended Audience :: Developers",
+        "License :: OSI Approved :: Apache Software License",
+        "Natural Language :: English",
+        "Operating System :: MacOS :: MacOS X",
+        "Operating System :: Microsoft :: Windows :: Windows 10",
+        "Operating System :: POSIX :: Linux",
+        "Programming Language :: Python :: 3",
+        "Programming Language :: Python :: 3 :: Only",
+        "Topic :: Software Development :: Version Control :: Git",
     ],
-    # We support Python 2.7 and Python 3.6+.
-    python_requires='>=2.7, ' + ', '.join('!=3.%i.*' % x for x in range(0, 6)),
-    packages=['subcmds'],
+    python_requires=">=3.6",
+    packages=["subcmds"],
 )

ssh.py

@@ -0,0 +1,351 @@
+# Copyright (C) 2008 The Android Open Source Project
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Common SSH management logic."""
+
+import functools
+import multiprocessing
+import os
+import re
+import signal
+import subprocess
+import sys
+import tempfile
+import time
+
+from git_command import git
+import platform_utils
+from repo_trace import Trace
+
+
+PROXY_PATH = os.path.join(os.path.dirname(__file__), "git_ssh")
+
+
+def _run_ssh_version():
+    """run ssh -V to display the version number"""
+    return subprocess.check_output(
+        ["ssh", "-V"], stderr=subprocess.STDOUT
+    ).decode()
+
+
+def _parse_ssh_version(ver_str=None):
+    """parse a ssh version string into a tuple"""
+    if ver_str is None:
+        ver_str = _run_ssh_version()
+    m = re.match(r"^OpenSSH_([0-9.]+)(p[0-9]+)?[\s,]", ver_str)
+    if m:
+        return tuple(int(x) for x in m.group(1).split("."))
+    else:
+        return ()
+
+
+@functools.lru_cache(maxsize=None)
+def version():
+    """return ssh version as a tuple"""
+    try:
+        return _parse_ssh_version()
+    except FileNotFoundError:
+        print("fatal: ssh not installed", file=sys.stderr)
+        sys.exit(1)
+    except subprocess.CalledProcessError as e:
+        print(
+            "fatal: unable to detect ssh version"
+            f" (code={e.returncode}, output={e.stdout})",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+
+URI_SCP = re.compile(r"^([^@:]*@?[^:/]{1,}):")
+URI_ALL = re.compile(r"^([a-z][a-z+-]*)://([^@/]*@?[^/]*)/")
+
+
+class ProxyManager:
+    """Manage various ssh clients & masters that we spawn.
+
+    This will take care of sharing state between multiprocessing children, and
+    make sure that if we crash, we don't leak any of the ssh sessions.
+
+    The code should work with a single-process scenario too, and not add too
+    much overhead due to the manager.
+    """
+
+    # Path to the ssh program to run which will pass our master settings along.
+    # Set here more as a convenience API.
+    proxy = PROXY_PATH
+
+    def __init__(self, manager):
+        # Protect access to the list of active masters.
+        self._lock = multiprocessing.Lock()
+        # List of active masters (pid).  These will be spawned on demand, and we
+        # are responsible for shutting them all down at the end.
+        self._masters = manager.list()
+        # Set of active masters indexed by "host:port" information.
+        # The value isn't used, but multiprocessing doesn't provide a set class.
+        self._master_keys = manager.dict()
+        # Whether ssh masters are known to be broken, so we give up entirely.
+        self._master_broken = manager.Value("b", False)
+        # List of active ssh sesssions.  Clients will be added & removed as
+        # connections finish, so this list is just for safety & cleanup if we
+        # crash.
+        self._clients = manager.list()
+        # Path to directory for holding master sockets.
+        self._sock_path = None
+
+    def __enter__(self):
+        """Enter a new context."""
+        return self
+
+    def __exit__(self, exc_type, exc_value, traceback):
+        """Exit a context & clean up all resources."""
+        self.close()
+
+    def add_client(self, proc):
+        """Track a new ssh session."""
+        self._clients.append(proc.pid)
+
+    def remove_client(self, proc):
+        """Remove a completed ssh session."""
+        try:
+            self._clients.remove(proc.pid)
+        except ValueError:
+            pass
+
+    def add_master(self, proc):
+        """Track a new master connection."""
+        self._masters.append(proc.pid)
+
+    def _terminate(self, procs):
+        """Kill all |procs|."""
+        for pid in procs:
+            try:
+                os.kill(pid, signal.SIGTERM)
+                os.waitpid(pid, 0)
+            except OSError:
+                pass
+
+        # The multiprocessing.list() API doesn't provide many standard list()
+        # methods, so we have to manually clear the list.
+        while True:
+            try:
+                procs.pop(0)
+            except:  # noqa: E722
+                break
+
+    def close(self):
+        """Close this active ssh session.
+
+        Kill all ssh clients & masters we created, and nuke the socket dir.
+        """
+        self._terminate(self._clients)
+        self._terminate(self._masters)
+
+        d = self.sock(create=False)
+        if d:
+            try:
+                platform_utils.rmdir(os.path.dirname(d))
+            except OSError:
+                pass
+
+    def _open_unlocked(self, host, port=None):
+        """Make sure a ssh master session exists for |host| & |port|.
+
+        If one doesn't exist already, we'll create it.
+
+        We won't grab any locks, so the caller has to do that.  This helps keep
+        the business logic of actually creating the master separate from
+        grabbing locks.
+        """
+        # Check to see whether we already think that the master is running; if
+        # we think it's already running, return right away.
+        if port is not None:
+            key = f"{host}:{port}"
+        else:
+            key = host
+
+        if key in self._master_keys:
+            return True
+
+        if self._master_broken.value or "GIT_SSH" in os.environ:
+            # Failed earlier, so don't retry.
+            return False
+
+        # We will make two calls to ssh; this is the common part of both calls.
+        command_base = ["ssh", "-o", "ControlPath %s" % self.sock(), host]
+        if port is not None:
+            command_base[1:1] = ["-p", str(port)]
+
+        # Since the key wasn't in _master_keys, we think that master isn't
+        # running... but before actually starting a master, we'll double-check.
+        # This can be important because we can't tell that that 'git@myhost.com'
+        # is the same as 'myhost.com' where "User git" is setup in the user's
+        # ~/.ssh/config file.
+        check_command = command_base + ["-O", "check"]
+        with Trace("Call to ssh (check call): %s", " ".join(check_command)):
+            try:
+                check_process = subprocess.Popen(
+                    check_command,
+                    stdout=subprocess.PIPE,
+                    stderr=subprocess.PIPE,
+                )
+                check_process.communicate()  # read output, but ignore it...
+                isnt_running = check_process.wait()
+
+                if not isnt_running:
+                    # Our double-check found that the master _was_ infact
+                    # running.  Add to the list of keys.
+                    self._master_keys[key] = True
+                    return True
+            except Exception:
+                # Ignore excpetions.  We we will fall back to the normal command
+                # and print to the log there.
+                pass
+
+        # Git protocol V2 is a new feature in git 2.18.0, made default in
+        # git 2.26.0
+        # It is faster and more efficient than V1.
+        # To enable it when using SSH, the environment variable GIT_PROTOCOL
+        # must be set in the SSH side channel when establishing the connection
+        # to the git server.
+        # See https://git-scm.com/docs/protocol-v2#_ssh_and_file_transport
+        # Normally git does this by itself. But here, where the SSH connection
+        # is established manually over ControlMaster via the repo-tool, it must
+        # be passed in explicitly instead.
+        # Based on https://git-scm.com/docs/gitprotocol-pack#_extra_parameters,
+        # GIT_PROTOCOL is considered an "Extra Parameter" and must be ignored
+        # by servers that do not understand it. This means that it is safe to
+        # set it even when connecting to older servers.
+        # It should also be safe to set the environment variable for older
+        # local git versions, since it is only part of the ssh side channel.
+        git_protocol_version = _get_git_protocol_version()
+        ssh_git_protocol_args = [
+            "-o",
+            f"SetEnv GIT_PROTOCOL=version={git_protocol_version}",
+        ]
+
+        command = (
+            command_base[:1]
+            + ["-M", "-N", *ssh_git_protocol_args]
+            + command_base[1:]
+        )
+        p = None
+        try:
+            with Trace("Call to ssh: %s", " ".join(command)):
+                p = subprocess.Popen(command)
+        except Exception as e:
+            self._master_broken.value = True
+            print(
+                "\nwarn: cannot enable ssh control master for %s:%s\n%s"
+                % (host, port, str(e)),
+                file=sys.stderr,
+            )
+            return False
+
+        time.sleep(1)
+        ssh_died = p.poll() is not None
+        if ssh_died:
+            return False
+
+        self.add_master(p)
+        self._master_keys[key] = True
+        return True
+
+    def _open(self, host, port=None):
+        """Make sure a ssh master session exists for |host| & |port|.
+
+        If one doesn't exist already, we'll create it.
+
+        This will obtain any necessary locks to avoid inter-process races.
+        """
+        # Bail before grabbing the lock if we already know that we aren't going
+        # to try creating new masters below.
+        if sys.platform in ("win32", "cygwin"):
+            return False
+
+        # Acquire the lock.  This is needed to prevent opening multiple masters
+        # for the same host when we're running "repo sync -jN" (for N > 1) _and_
+        # the manifest <remote fetch="ssh://xyz"> specifies a different host
+        # from the one that was passed to repo init.
+        with self._lock:
+            return self._open_unlocked(host, port)
+
+    def preconnect(self, url):
+        """If |uri| will create a ssh connection, setup the ssh master for it."""  # noqa: E501
+        m = URI_ALL.match(url)
+        if m:
+            scheme = m.group(1)
+            host = m.group(2)
+            if ":" in host:
+                host, port = host.split(":")
+            else:
+                port = None
+            if scheme in ("ssh", "git+ssh", "ssh+git"):
+                return self._open(host, port)
+            return False
+
+        m = URI_SCP.match(url)
+        if m:
+            host = m.group(1)
+            return self._open(host)
+
+        return False
+
+    def sock(self, create=True):
+        """Return the path to the ssh socket dir.
+
+        This has all the master sockets so clients can talk to them.
+        """
+        if self._sock_path is None:
+            if not create:
+                return None
+            tmp_dir = "/tmp"
+            if not os.path.exists(tmp_dir):
+                tmp_dir = tempfile.gettempdir()
+            if version() < (6, 7):
+                tokens = "%r@%h:%p"
+            else:
+                tokens = "%C"  # hash of %l%h%p%r
+            self._sock_path = os.path.join(
+                tempfile.mkdtemp("", "ssh-", tmp_dir), "master-" + tokens
+            )
+        return self._sock_path
+
+
+@functools.lru_cache(maxsize=1)
+def _get_git_protocol_version() -> str:
+    """Return the git protocol version.
+
+    The version is found by first reading the global git config.
+    If no git config for protocol version exists, try to deduce the default
+    protocol version based on the git version.
+
+    See https://git-scm.com/docs/gitprotocol-v2 for details.
+    """
+    try:
+        return subprocess.check_output(
+            ["git", "config", "--get", "--global", "protocol.version"],
+            encoding="utf-8",
+            stderr=subprocess.PIPE,
+        ).strip()
+    except subprocess.CalledProcessError as e:
+        if e.returncode == 1:
+            # Exit code 1 means that the git config key was not found.
+            # Try to imitate the defaults that git would have used.
+            git_version = git.version_tuple()
+            if git_version >= (2, 26, 0):
+                # Since git version 2.26, protocol v2 is the default.
+                return "2"
+            return "1"
+        # Other exit codes indicate error with reading the config.
+        raise

subcmds/__init__.py

@@ -1,5 +1,3 @@
-# -*- coding:utf-8 -*-
-#
 # Copyright (C) 2008 The Android Open Source Project
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -16,35 +14,35 @@
 
 import os
 
+
+# A mapping of the subcommand name to the class that implements it.
 all_commands = {}
+all_modules = []
 
 my_dir = os.path.dirname(__file__)
 for py in os.listdir(my_dir):
-  if py == '__init__.py':
-    continue
+    if py == "__init__.py":
+        continue
 
-  if py.endswith('.py'):
-    name = py[:-3]
+    if py.endswith(".py"):
+        name = py[:-3]
 
-    clsn = name.capitalize()
-    while clsn.find('_') > 0:
-      h = clsn.index('_')
-      clsn = clsn[0:h] + clsn[h + 1:].capitalize()
+        clsn = name.capitalize()
+        while clsn.find("_") > 0:
+            h = clsn.index("_")
+            clsn = clsn[0:h] + clsn[h + 1 :].capitalize()
 
-    mod = __import__(__name__,
-                     globals(),
-                     locals(),
-                     ['%s' % name])
-    mod = getattr(mod, name)
-    try:
-      cmd = getattr(mod, clsn)()
-    except AttributeError:
-      raise SyntaxError('%s/%s does not define class %s' % (
-                         __name__, py, clsn))
+        mod = __import__(__name__, globals(), locals(), ["%s" % name])
+        mod = getattr(mod, name)
+        try:
+            cmd = getattr(mod, clsn)
+        except AttributeError:
+            raise SyntaxError(f"{__name__}/{py} does not define class {clsn}")
 
-    name = name.replace('_', '-')
-    cmd.NAME = name
-    all_commands[name] = cmd
+        name = name.replace("_", "-")
+        cmd.NAME = name
+        all_commands[name] = cmd
+        all_modules.append(mod)
 
-if 'help' in all_commands:
-  all_commands['help'].commands = all_commands
+# Add 'branch' as an alias for 'branches'.
+all_commands["branch"] = all_commands["branches"]

subcmds/abandon.py

@@ -1,5 +1,3 @@
-# -*- coding:utf-8 -*-
-#
 # Copyright (C) 2008 The Android Open Source Project
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -14,17 +12,30 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-from __future__ import print_function
-import sys
+import collections
+import functools
+import itertools
+
 from command import Command
-from collections import defaultdict
+from command import DEFAULT_LOCAL_JOBS
+from error import RepoError
+from error import RepoExitError
 from git_command import git
 from progress import Progress
+from repo_logging import RepoLogger
+
+
+logger = RepoLogger(__file__)
+
+
+class AbandonError(RepoExitError):
+    """Exit error when abandon command fails."""
+
 
 class Abandon(Command):
-  common = True
-  helpSummary = "Permanently abandon a development branch"
-  helpUsage = """
+    COMMON = True
+    helpSummary = "Permanently abandon a development branch"
+    helpUsage = """
 %prog [--all | <branchname>] [<project>...]
 
 This subcommand permanently abandons a development branch by
@@ -32,68 +43,118 @@ deleting it (and all its history) from your local repository.
 
 It is equivalent to "git branch -D <branchname>".
 """
-  def _Options(self, p):
-    p.add_option('--all',
-                 dest='all', action='store_true',
-                 help='delete all branches in all projects')
+    PARALLEL_JOBS = DEFAULT_LOCAL_JOBS
 
-  def ValidateOptions(self, opt, args):
-    if not opt.all and not args:
-      self.Usage()
+    def _Options(self, p):
+        p.add_option(
+            "--all",
+            action="store_true",
+            help="delete all branches in all projects",
+        )
 
-    if not opt.all:
-      nb = args[0]
-      if not git.check_ref_format('heads/%s' % nb):
-        self.OptionParser.error("'%s' is not a valid branch name" % nb)
-    else:
-      args.insert(0, "'All local branches'")
+    def ValidateOptions(self, opt, args):
+        if not opt.all and not args:
+            self.Usage()
 
-  def Execute(self, opt, args):
-    nb = args[0]
-    err = defaultdict(list)
-    success = defaultdict(list)
-    all_projects = self.GetProjects(args[1:])
+        if not opt.all:
+            branches = args[0].split()
+            invalid_branches = [
+                x for x in branches if not git.check_ref_format(f"heads/{x}")
+            ]
 
-    pm = Progress('Abandon %s' % nb, len(all_projects))
-    for project in all_projects:
-      pm.update()
-
-      if opt.all:
-        branches = list(project.GetBranches().keys())
-      else:
-        branches = [nb]
-
-      for name in branches:
-        status = project.AbandonBranch(name)
-        if status is not None:
-          if status:
-            success[name].append(project)
-          else:
-            err[name].append(project)
-    pm.end()
-
-    width = 25
-    for name in branches:
-      if width < len(name):
-        width = len(name)
-
-    if err:
-      for br in err.keys():
-        err_msg = "error: cannot abandon %s" %br
-        print(err_msg, file=sys.stderr)
-        for proj in err[br]:
-          print(' '*len(err_msg) + " | %s" % proj.relpath, file=sys.stderr)
-      sys.exit(1)
-    elif not success:
-      print('error: no project has local branch(es) : %s' % nb,
-            file=sys.stderr)
-      sys.exit(1)
-    else:
-      print('Abandoned branches:', file=sys.stderr)
-      for br in success.keys():
-        if len(all_projects) > 1 and len(all_projects) == len(success[br]):
-          result = "all project"
+            if invalid_branches:
+                self.OptionParser.error(
+                    f"{invalid_branches} are not valid branch names"
+                )
         else:
-          result = "%s" % (
-            ('\n'+' '*width + '| ').join(p.relpath for p in success[br]))
-        print("%s%s| %s\n" % (br,' '*(width-len(br)), result),file=sys.stderr)
+            args.insert(0, "'All local branches'")
+
+    @classmethod
+    def _ExecuteOne(cls, all_branches, nb, project_idx):
+        """Abandon one project."""
+        project = cls.get_parallel_context()["projects"][project_idx]
+        if all_branches:
+            branches = project.GetBranches()
+        else:
+            branches = nb
+
+        ret = {}
+        errors = []
+        for name in branches:
+            status = None
+            try:
+                status = project.AbandonBranch(name)
+            except RepoError as e:
+                status = False
+                errors.append(e)
+            if status is not None:
+                ret[name] = status
+
+        return (ret, project_idx, errors)
+
+    def Execute(self, opt, args):
+        nb = args[0].split()
+        err = collections.defaultdict(list)
+        success = collections.defaultdict(list)
+        aggregate_errors = []
+        all_projects = self.GetProjects(
+            args[1:], all_manifests=not opt.this_manifest_only
+        )
+        _RelPath = lambda p: p.RelPath(local=opt.this_manifest_only)
+
+        def _ProcessResults(_pool, pm, states):
+            for results, project_idx, errors in states:
+                project = all_projects[project_idx]
+                for branch, status in results.items():
+                    if status:
+                        success[branch].append(project)
+                    else:
+                        err[branch].append(project)
+                aggregate_errors.extend(errors)
+                pm.update(msg="")
+
+        with self.ParallelContext():
+            self.get_parallel_context()["projects"] = all_projects
+            self.ExecuteInParallel(
+                opt.jobs,
+                functools.partial(self._ExecuteOne, opt.all, nb),
+                range(len(all_projects)),
+                callback=_ProcessResults,
+                output=Progress(
+                    f"Abandon {nb}", len(all_projects), quiet=opt.quiet
+                ),
+                chunksize=1,
+            )
+
+        width = max(
+            itertools.chain(
+                [25], (len(x) for x in itertools.chain(success, err))
+            )
+        )
+        if err:
+            for br in err.keys():
+                err_msg = "error: cannot abandon %s" % br
+                logger.error(err_msg)
+                for proj in err[br]:
+                    logger.error(" " * len(err_msg) + " | %s", _RelPath(proj))
+            raise AbandonError(aggregate_errors=aggregate_errors)
+        elif not success:
+            logger.error("error: no project has local branch(es) : %s", nb)
+            raise AbandonError(aggregate_errors=aggregate_errors)
+        else:
+            # Everything below here is displaying status.
+            if opt.quiet:
+                return
+            print("Abandoned branches:")
+            for br in success.keys():
+                if len(all_projects) > 1 and len(all_projects) == len(
+                    success[br]
+                ):
+                    result = "all project"
+                else:
+                    result = "%s" % (
+                        ("\n" + " " * width + "| ").join(
+                            _RelPath(p) for p in success[br]
+                        )
+                    )
+                print(f"{br}{' ' * (width - len(br))}| {result}\n")

subcmds/branches.py

@@ -1,5 +1,3 @@
-# -*- coding:utf-8 -*-
-#
 # Copyright (C) 2009 The Android Open Source Project
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -14,56 +12,60 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-from __future__ import print_function
+import itertools
 import sys
+
 from color import Coloring
 from command import Command
+from command import DEFAULT_LOCAL_JOBS
+
 
 class BranchColoring(Coloring):
-  def __init__(self, config):
-    Coloring.__init__(self, config, 'branch')
-    self.current = self.printer('current', fg='green')
-    self.local   = self.printer('local')
-    self.notinproject = self.printer('notinproject', fg='red')
+    def __init__(self, config):
+        Coloring.__init__(self, config, "branch")
+        self.current = self.printer("current", fg="green")
+        self.local = self.printer("local")
+        self.notinproject = self.printer("notinproject", fg="red")
 
-class BranchInfo(object):
-  def __init__(self, name):
-    self.name = name
-    self.current = 0
-    self.published = 0
-    self.published_equal = 0
-    self.projects = []
 
-  def add(self, b):
-    if b.current:
-      self.current += 1
-    if b.published:
-      self.published += 1
-    if b.revision == b.published:
-      self.published_equal += 1
-    self.projects.append(b)
+class BranchInfo:
+    def __init__(self, name):
+        self.name = name
+        self.current = 0
+        self.published = 0
+        self.published_equal = 0
+        self.projects = []
 
-  @property
-  def IsCurrent(self):
-    return self.current > 0
+    def add(self, b):
+        if b.current:
+            self.current += 1
+        if b.published:
+            self.published += 1
+        if b.revision == b.published:
+            self.published_equal += 1
+        self.projects.append(b)
 
-  @property
-  def IsSplitCurrent(self):
-    return self.current != 0 and self.current != len(self.projects)
+    @property
+    def IsCurrent(self):
+        return self.current > 0
 
-  @property
-  def IsPublished(self):
-    return self.published > 0
+    @property
+    def IsSplitCurrent(self):
+        return self.current != 0 and self.current != len(self.projects)
 
-  @property
-  def IsPublishedEqual(self):
-    return self.published_equal == len(self.projects)
+    @property
+    def IsPublished(self):
+        return self.published > 0
+
+    @property
+    def IsPublishedEqual(self):
+        return self.published_equal == len(self.projects)
 
 
 class Branches(Command):
-  common = True
-  helpSummary = "View current topic branches"
-  helpUsage = """
+    COMMON = True
+    helpSummary = "View current topic branches"
+    helpUsage = """
 %prog [<project>...]
 
 Summarizes the currently available topic branches.
@@ -94,87 +96,120 @@ the branch appears in, or does not appear in.  If no project list
 is shown, then the branch appears in all projects.
 
 """
+    PARALLEL_JOBS = DEFAULT_LOCAL_JOBS
 
-  def Execute(self, opt, args):
-    projects = self.GetProjects(args)
-    out = BranchColoring(self.manifest.manifestProject.config)
-    all_branches = {}
-    project_cnt = len(projects)
+    @classmethod
+    def _ExpandProjectToBranches(cls, project_idx):
+        """Expands a project into a list of branch names & associated info.
 
-    for project in projects:
-      for name, b in project.GetBranches().items():
-        b.project = project
-        if name not in all_branches:
-          all_branches[name] = BranchInfo(name)
-        all_branches[name].add(b)
+        Args:
+            project_idx: project.Project index
 
-    names = list(sorted(all_branches))
+        Returns:
+            List[Tuple[str, git_config.Branch, int]]
+        """
+        branches = []
+        project = cls.get_parallel_context()["projects"][project_idx]
+        for name, b in project.GetBranches().items():
+            branches.append((name, b, project_idx))
+        return branches
 
-    if not names:
-      print('   (no branches)', file=sys.stderr)
-      return
+    def Execute(self, opt, args):
+        projects = self.GetProjects(
+            args, all_manifests=not opt.this_manifest_only
+        )
+        out = BranchColoring(self.manifest.manifestProject.config)
+        all_branches = {}
+        project_cnt = len(projects)
 
-    width = 25
-    for name in names:
-      if width < len(name):
-        width = len(name)
+        def _ProcessResults(_pool, _output, results):
+            for name, b, project_idx in itertools.chain.from_iterable(results):
+                b.project = projects[project_idx]
+                if name not in all_branches:
+                    all_branches[name] = BranchInfo(name)
+                all_branches[name].add(b)
 
-    for name in names:
-      i = all_branches[name]
-      in_cnt = len(i.projects)
+        with self.ParallelContext():
+            self.get_parallel_context()["projects"] = projects
+            self.ExecuteInParallel(
+                opt.jobs,
+                self._ExpandProjectToBranches,
+                range(len(projects)),
+                callback=_ProcessResults,
+            )
 
-      if i.IsCurrent:
-        current = '*'
-        hdr = out.current
-      else:
-        current = ' '
-        hdr = out.local
+        names = sorted(all_branches)
 
-      if i.IsPublishedEqual:
-        published = 'P'
-      elif i.IsPublished:
-        published = 'p'
-      else:
-        published = ' '
+        if not names:
+            print("   (no branches)", file=sys.stderr)
+            return
 
-      hdr('%c%c %-*s' % (current, published, width, name))
-      out.write(' |')
+        width = 25
+        for name in names:
+            if width < len(name):
+                width = len(name)
 
-      if in_cnt < project_cnt:
-        fmt = out.write
-        paths = []
-        non_cur_paths = []
-        if i.IsSplitCurrent or (in_cnt < project_cnt - in_cnt):
-          in_type = 'in'
-          for b in i.projects:
-            if not i.IsSplitCurrent or b.current:
-              paths.append(b.project.relpath)
+        for name in names:
+            i = all_branches[name]
+            in_cnt = len(i.projects)
+
+            if i.IsCurrent:
+                current = "*"
+                hdr = out.current
             else:
-              non_cur_paths.append(b.project.relpath)
-        else:
-          fmt = out.notinproject
-          in_type = 'not in'
-          have = set()
-          for b in i.projects:
-            have.add(b.project)
-          for p in projects:
-            if not p in have:
-              paths.append(p.relpath)
+                current = " "
+                hdr = out.local
 
-        s = ' %s %s' % (in_type, ', '.join(paths))
-        if not i.IsSplitCurrent and (width + 7 + len(s) < 80):
-          fmt = out.current if i.IsCurrent else fmt
-          fmt(s)
-        else:
-          fmt(' %s:' % in_type)
-          fmt = out.current if i.IsCurrent else out.write
-          for p in paths:
+            if i.IsPublishedEqual:
+                published = "P"
+            elif i.IsPublished:
+                published = "p"
+            else:
+                published = " "
+
+            # A branch name can contain a percent sign, so we need to escape it.
+            # Escape after f-string formatting to properly account for leading
+            # spaces.
+            hdr(f"{current}{published} {name:{width}}".replace("%", "%%"))
+            out.write(" |")
+
+            _RelPath = lambda p: p.RelPath(local=opt.this_manifest_only)
+            if in_cnt < project_cnt:
+                fmt = out.write
+                paths = []
+                non_cur_paths = []
+                if i.IsSplitCurrent or (in_cnt <= project_cnt - in_cnt):
+                    in_type = "in"
+                    for b in i.projects:
+                        relpath = _RelPath(b.project)
+                        if not i.IsSplitCurrent or b.current:
+                            paths.append(relpath)
+                        else:
+                            non_cur_paths.append(relpath)
+                else:
+                    fmt = out.notinproject
+                    in_type = "not in"
+                    have = set()
+                    for b in i.projects:
+                        have.add(_RelPath(b.project))
+                    for p in projects:
+                        if _RelPath(p) not in have:
+                            paths.append(_RelPath(p))
+
+                s = f" {in_type} {', '.join(paths)}"
+                if not i.IsSplitCurrent and (width + 7 + len(s) < 80):
+                    fmt = out.current if i.IsCurrent else fmt
+                    fmt(s)
+                else:
+                    fmt(" %s:" % in_type)
+                    fmt = out.current if i.IsCurrent else out.write
+                    for p in paths:
+                        out.nl()
+                        fmt(width * " " + "          %s" % p)
+                    fmt = out.write
+                    for p in non_cur_paths:
+                        out.nl()
+                        fmt(width * " " + "          %s" % p)
+            else:
+                out.write(" in all projects")
             out.nl()
-            fmt(width*' ' + '          %s' % p)
-          fmt = out.write
-          for p in non_cur_paths:
-            out.nl()
-            fmt(width*' ' + '          %s' % p)
-      else:
-        out.write(' in all projects')
-      out.nl()

subcmds/checkout.py

@@ -1,5 +1,3 @@
-# -*- coding:utf-8 -*-
-#
 # Copyright (C) 2009 The Android Open Source Project
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -14,18 +12,42 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-from __future__ import print_function
-import sys
+import functools
+from typing import NamedTuple
+
 from command import Command
+from command import DEFAULT_LOCAL_JOBS
+from error import GitError
+from error import RepoExitError
 from progress import Progress
+from repo_logging import RepoLogger
+
+
+logger = RepoLogger(__file__)
+
+
+class CheckoutBranchResult(NamedTuple):
+    # Whether the Project is on the branch (i.e. branch exists and no errors)
+    result: bool
+    project_idx: int
+    error: Exception
+
+
+class CheckoutCommandError(RepoExitError):
+    """Exception thrown when checkout command fails."""
+
+
+class MissingBranchError(RepoExitError):
+    """Exception thrown when no project has specified branch."""
+
 
 class Checkout(Command):
-  common = True
-  helpSummary = "Checkout a branch for development"
-  helpUsage = """
+    COMMON = True
+    helpSummary = "Checkout a branch for development"
+    helpUsage = """
 %prog <branchname> [<project>...]
 """
-  helpDescription = """
+    helpDescription = """
 The '%prog' command checks out an existing branch that was previously
 created by 'repo start'.
 
@@ -33,34 +55,60 @@ The command is equivalent to:
 
   repo forall [<project>...] -c git checkout <branchname>
 """
+    PARALLEL_JOBS = DEFAULT_LOCAL_JOBS
 
-  def ValidateOptions(self, opt, args):
-    if not args:
-      self.Usage()
+    def ValidateOptions(self, opt, args):
+        if not args:
+            self.Usage()
 
-  def Execute(self, opt, args):
-    nb = args[0]
-    err = []
-    success = []
-    all_projects = self.GetProjects(args[1:])
+    @classmethod
+    def _ExecuteOne(cls, nb, project_idx):
+        """Checkout one project."""
+        error = None
+        result = None
+        project = cls.get_parallel_context()["projects"][project_idx]
+        try:
+            result = project.CheckoutBranch(nb)
+        except GitError as e:
+            error = e
+        return CheckoutBranchResult(result, project_idx, error)
 
-    pm = Progress('Checkout %s' % nb, len(all_projects))
-    for project in all_projects:
-      pm.update()
+    def Execute(self, opt, args):
+        nb = args[0]
+        err = []
+        err_projects = []
+        success = []
+        all_projects = self.GetProjects(
+            args[1:], all_manifests=not opt.this_manifest_only
+        )
 
-      status = project.CheckoutBranch(nb)
-      if status is not None:
-        if status:
-          success.append(project)
-        else:
-          err.append(project)
-    pm.end()
+        def _ProcessResults(_pool, pm, results):
+            for result in results:
+                project = all_projects[result.project_idx]
+                if result.error is not None:
+                    err.append(result.error)
+                    err_projects.append(project)
+                elif result.result:
+                    success.append(project)
+                pm.update(msg="")
 
-    if err:
-      for p in err:
-        print("error: %s/: cannot checkout %s" % (p.relpath, nb),
-              file=sys.stderr)
-      sys.exit(1)
-    elif not success:
-      print('error: no project has branch %s' % nb, file=sys.stderr)
-      sys.exit(1)
+        with self.ParallelContext():
+            self.get_parallel_context()["projects"] = all_projects
+            self.ExecuteInParallel(
+                opt.jobs,
+                functools.partial(self._ExecuteOne, nb),
+                range(len(all_projects)),
+                callback=_ProcessResults,
+                output=Progress(
+                    f"Checkout {nb}", len(all_projects), quiet=opt.quiet
+                ),
+            )
+
+        if err_projects:
+            for p in err_projects:
+                logger.error("error: %s/: cannot checkout %s", p.relpath, nb)
+            raise CheckoutCommandError(aggregate_errors=err)
+        elif not success:
+            msg = f"error: no project has branch {nb}"
+            logger.error(msg)
+            raise MissingBranchError(msg)

subcmds/cherry_pick.py

@@ -1,5 +1,3 @@
-# -*- coding:utf-8 -*-
-#
 # Copyright (C) 2010 The Android Open Source Project
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -14,104 +12,134 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-from __future__ import print_function
 import re
 import sys
-from command import Command
-from git_command import GitCommand
 
-CHANGE_ID_RE = re.compile(r'^\s*Change-Id: I([0-9a-f]{40})\s*$')
+from command import Command
+from error import GitError
+from git_command import GitCommand
+from repo_logging import RepoLogger
+
+
+CHANGE_ID_RE = re.compile(r"^\s*Change-Id: I([0-9a-f]{40})\s*$")
+logger = RepoLogger(__file__)
+
 
 class CherryPick(Command):
-  common = True
-  helpSummary = "Cherry-pick a change."
-  helpUsage = """
+    COMMON = True
+    helpSummary = "Cherry-pick a change."
+    helpUsage = """
 %prog <sha1>
 """
-  helpDescription = """
+    helpDescription = """
 '%prog' cherry-picks a change from one branch to another.
 The change id will be updated, and a reference to the old
 change id will be added.
 """
 
-  def _Options(self, p):
-    pass
+    def ValidateOptions(self, opt, args):
+        if len(args) != 1:
+            self.Usage()
 
-  def ValidateOptions(self, opt, args):
-    if len(args) != 1:
-      self.Usage()
+    def Execute(self, opt, args):
+        reference = args[0]
 
-  def Execute(self, opt, args):
-    reference = args[0]
+        p = GitCommand(
+            None,
+            ["rev-parse", "--verify", reference],
+            capture_stdout=True,
+            capture_stderr=True,
+            verify_command=True,
+        )
+        try:
+            p.Wait()
+        except GitError:
+            logger.error(p.stderr)
+            raise
 
-    p = GitCommand(None,
-                   ['rev-parse', '--verify', reference],
-                   capture_stdout = True,
-                   capture_stderr = True)
-    if p.Wait() != 0:
-      print(p.stderr, file=sys.stderr)
-      sys.exit(1)
-    sha1 = p.stdout.strip()
+        sha1 = p.stdout.strip()
 
-    p = GitCommand(None, ['cat-file', 'commit', sha1], capture_stdout=True)
-    if p.Wait() != 0:
-      print("error: Failed to retrieve old commit message", file=sys.stderr)
-      sys.exit(1)
-    old_msg = self._StripHeader(p.stdout)
+        p = GitCommand(
+            None,
+            ["cat-file", "commit", sha1],
+            capture_stdout=True,
+            verify_command=True,
+        )
 
-    p = GitCommand(None,
-                   ['cherry-pick', sha1],
-                   capture_stdout = True,
-                   capture_stderr = True)
-    status = p.Wait()
+        try:
+            p.Wait()
+        except GitError:
+            logger.error("error: Failed to retrieve old commit message")
+            raise
 
-    print(p.stdout, file=sys.stdout)
-    print(p.stderr, file=sys.stderr)
+        old_msg = self._StripHeader(p.stdout)
 
-    if status == 0:
-      # The cherry-pick was applied correctly. We just need to edit the
-      # commit message.
-      new_msg = self._Reformat(old_msg, sha1)
+        p = GitCommand(
+            None,
+            ["cherry-pick", sha1],
+            capture_stdout=True,
+            capture_stderr=True,
+            verify_command=True,
+        )
 
-      p = GitCommand(None, ['commit', '--amend', '-F', '-'],
-                     provide_stdin = True,
-                     capture_stdout = True,
-                     capture_stderr = True)
-      p.stdin.write(new_msg)
-      p.stdin.close()
-      if p.Wait() != 0:
-        print("error: Failed to update commit message", file=sys.stderr)
-        sys.exit(1)
+        try:
+            p.Wait()
+        except GitError as e:
+            logger.error(e)
+            logger.warning(
+                "NOTE: When committing (please see above) and editing the "
+                "commit message, please remove the old Change-Id-line and "
+                "add:\n%s",
+                self._GetReference(sha1),
+            )
+            raise
 
-    else:
-      print('NOTE: When committing (please see above) and editing the commit '
-            'message, please remove the old Change-Id-line and add:')
-      print(self._GetReference(sha1), file=sys.stderr)
-      print(file=sys.stderr)
+        if p.stdout:
+            print(p.stdout.strip(), file=sys.stdout)
+        if p.stderr:
+            print(p.stderr.strip(), file=sys.stderr)
 
-  def _IsChangeId(self, line):
-    return CHANGE_ID_RE.match(line)
+        # The cherry-pick was applied correctly. We just need to edit
+        # the commit message.
+        new_msg = self._Reformat(old_msg, sha1)
 
-  def _GetReference(self, sha1):
-    return "(cherry picked from commit %s)" % sha1
+        p = GitCommand(
+            None,
+            ["commit", "--amend", "-F", "-"],
+            input=new_msg,
+            capture_stdout=True,
+            capture_stderr=True,
+            verify_command=True,
+        )
+        try:
+            p.Wait()
+        except GitError:
+            logger.error("error: Failed to update commit message")
+            raise
 
-  def _StripHeader(self, commit_msg):
-    lines = commit_msg.splitlines()
-    return "\n".join(lines[lines.index("")+1:])
+    def _IsChangeId(self, line):
+        return CHANGE_ID_RE.match(line)
 
-  def _Reformat(self, old_msg, sha1):
-    new_msg = []
+    def _GetReference(self, sha1):
+        return "(cherry picked from commit %s)" % sha1
 
-    for line in old_msg.splitlines():
-      if not self._IsChangeId(line):
-        new_msg.append(line)
+    def _StripHeader(self, commit_msg):
+        lines = commit_msg.splitlines()
+        return "\n".join(lines[lines.index("") + 1 :])
 
-    # Add a blank line between the message and the change id/reference
-    try:
-      if new_msg[-1].strip() != "":
-        new_msg.append("")
-    except IndexError:
-      pass
+    def _Reformat(self, old_msg, sha1):
+        new_msg = []
 
-    new_msg.append(self._GetReference(sha1))
-    return "\n".join(new_msg)
+        for line in old_msg.splitlines():
+            if not self._IsChangeId(line):
+                new_msg.append(line)
+
+        # Add a blank line between the message and the change id/reference.
+        try:
+            if new_msg[-1].strip() != "":
+                new_msg.append("")
+        except IndexError:
+            pass
+
+        new_msg.append(self._GetReference(sha1))
+        return "\n".join(new_msg)

subcmds/diff.py

@@ -1,5 +1,3 @@
-# -*- coding:utf-8 -*-
-#
 # Copyright (C) 2008 The Android Open Source Project
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -14,31 +12,75 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+import functools
+import io
+
+from command import DEFAULT_LOCAL_JOBS
 from command import PagedCommand
 
+
 class Diff(PagedCommand):
-  common = True
-  helpSummary = "Show changes between commit and working tree"
-  helpUsage = """
+    COMMON = True
+    helpSummary = "Show changes between commit and working tree"
+    helpUsage = """
 %prog [<project>...]
 
 The -u option causes '%prog' to generate diff output with file paths
 relative to the repository root, so the output can be applied
 to the Unix 'patch' command.
 """
+    PARALLEL_JOBS = DEFAULT_LOCAL_JOBS
 
-  def _Options(self, p):
-    def cmd(option, opt_str, value, parser):
-      setattr(parser.values, option.dest, list(parser.rargs))
-      while parser.rargs:
-        del parser.rargs[0]
-    p.add_option('-u', '--absolute',
-                 dest='absolute', action='store_true',
-                 help='Paths are relative to the repository root')
+    def _Options(self, p):
+        p.add_option(
+            "-u",
+            "--absolute",
+            action="store_true",
+            help="paths are relative to the repository root",
+        )
 
-  def Execute(self, opt, args):
-    ret = 0
-    for project in self.GetProjects(args):
-      if not project.PrintWorkTreeDiff(opt.absolute):
-        ret = 1
-    return ret
+    @classmethod
+    def _ExecuteOne(cls, absolute, local, project_idx):
+        """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_idx: Project index to get status of.
+
+        Returns:
+            The status of the project.
+        """
+        buf = io.StringIO()
+        project = cls.get_parallel_context()["projects"][project_idx]
+        ret = project.PrintWorkTreeDiff(absolute, output_redir=buf, local=local)
+        return (ret, buf.getvalue())
+
+    def Execute(self, opt, args):
+        all_projects = self.GetProjects(
+            args, all_manifests=not opt.this_manifest_only
+        )
+
+        def _ProcessResults(_pool, _output, results):
+            ret = 0
+            for state, output in results:
+                if output:
+                    print(output, end="")
+                if not state:
+                    ret = 1
+            return ret
+
+        with self.ParallelContext():
+            self.get_parallel_context()["projects"] = all_projects
+            return self.ExecuteInParallel(
+                opt.jobs,
+                functools.partial(
+                    self._ExecuteOne, opt.absolute, opt.this_manifest_only
+                ),
+                range(len(all_projects)),
+                callback=_ProcessResults,
+                ordered=True,
+                chunksize=1,
+            )

subcmds/diffmanifests.py

@@ -1,5 +1,3 @@
-# -*- coding:utf-8 -*-
-#
 # Copyright (C) 2014 The Android Open Source Project
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -16,26 +14,28 @@
 
 from color import Coloring
 from command import PagedCommand
-from manifest_xml import XmlManifest
+from manifest_xml import RepoClient
+
 
 class _Coloring(Coloring):
-  def __init__(self, config):
-    Coloring.__init__(self, config, "status")
+    def __init__(self, config):
+        Coloring.__init__(self, config, "status")
+
 
 class Diffmanifests(PagedCommand):
-  """ A command to see logs in projects represented by manifests
+    """A command to see logs in projects represented by manifests
 
-  This is used to see deeper differences between manifests. Where a simple
-  diff would only show a diff of sha1s for example, this command will display
-  the logs of the project between both sha1s, allowing user to see diff at a
-  deeper level.
-  """
+    This is used to see deeper differences between manifests. Where a simple
+    diff would only show a diff of sha1s for example, this command will display
+    the logs of the project between both sha1s, allowing user to see diff at a
+    deeper level.
+    """
 
-  common = True
-  helpSummary = "Manifest diff utility"
-  helpUsage = """%prog manifest1.xml [manifest2.xml] [options]"""
+    COMMON = True
+    helpSummary = "Manifest diff utility"
+    helpUsage = """%prog manifest1.xml [manifest2.xml] [options]"""
 
-  helpDescription = """
+    helpDescription = """
 The %prog command shows differences between project revisions of manifest1 and
 manifest2. if manifest2 is not specified, current manifest.xml will be used
 instead. Both absolute and relative paths may be used for manifests. Relative
@@ -65,142 +65,198 @@ synced and their revisions won't be found.
 
 """
 
-  def _Options(self, p):
-    p.add_option('--raw',
-                 dest='raw', action='store_true',
-                 help='Display raw diff.')
-    p.add_option('--no-color',
-                 dest='color', action='store_false', default=True,
-                 help='does not display the diff in color.')
-    p.add_option('--pretty-format',
-                 dest='pretty_format', action='store',
-                 metavar='<FORMAT>',
-                 help='print the log using a custom git pretty format string')
+    def _Options(self, p):
+        p.add_option(
+            "--raw",
+            action="store_true",
+            help="display raw diff",
+        )
+        p.add_option(
+            "--no-color",
+            dest="color",
+            action="store_false",
+            default=True,
+            help="does not display the diff in color",
+        )
+        p.add_option(
+            "--pretty-format",
+            action="store",
+            metavar="<FORMAT>",
+            help="print the log using a custom git pretty format string",
+        )
 
-  def _printRawDiff(self, diff):
-    for project in diff['added']:
-      self.printText("A %s %s" % (project.relpath, project.revisionExpr))
-      self.out.nl()
-
-    for project in diff['removed']:
-      self.printText("R %s %s" % (project.relpath, project.revisionExpr))
-      self.out.nl()
-
-    for project, otherProject in diff['changed']:
-      self.printText("C %s %s %s" % (project.relpath, project.revisionExpr,
-                                     otherProject.revisionExpr))
-      self.out.nl()
-      self._printLogs(project, otherProject, raw=True, color=False)
-
-    for project, otherProject in diff['unreachable']:
-      self.printText("U %s %s %s" % (project.relpath, project.revisionExpr,
-                                     otherProject.revisionExpr))
-      self.out.nl()
-
-  def _printDiff(self, diff, color=True, pretty_format=None):
-    if diff['added']:
-      self.out.nl()
-      self.printText('added projects : \n')
-      self.out.nl()
-      for project in diff['added']:
-        self.printProject('\t%s' % (project.relpath))
-        self.printText(' at revision ')
-        self.printRevision(project.revisionExpr)
-        self.out.nl()
-
-    if diff['removed']:
-      self.out.nl()
-      self.printText('removed projects : \n')
-      self.out.nl()
-      for project in diff['removed']:
-        self.printProject('\t%s' % (project.relpath))
-        self.printText(' at revision ')
-        self.printRevision(project.revisionExpr)
-        self.out.nl()
-
-    if diff['changed']:
-      self.out.nl()
-      self.printText('changed projects : \n')
-      self.out.nl()
-      for project, otherProject in diff['changed']:
-        self.printProject('\t%s' % (project.relpath))
-        self.printText(' changed from ')
-        self.printRevision(project.revisionExpr)
-        self.printText(' to ')
-        self.printRevision(otherProject.revisionExpr)
-        self.out.nl()
-        self._printLogs(project, otherProject, raw=False, color=color,
-                        pretty_format=pretty_format)
-        self.out.nl()
-
-    if diff['unreachable']:
-      self.out.nl()
-      self.printText('projects with unreachable revisions : \n')
-      self.out.nl()
-      for project, otherProject in diff['unreachable']:
-        self.printProject('\t%s ' % (project.relpath))
-        self.printRevision(project.revisionExpr)
-        self.printText(' or ')
-        self.printRevision(otherProject.revisionExpr)
-        self.printText(' not found')
-        self.out.nl()
-
-  def _printLogs(self, project, otherProject, raw=False, color=True,
-                 pretty_format=None):
-
-    logs = project.getAddedAndRemovedLogs(otherProject,
-                                          oneline=(pretty_format is None),
-                                          color=color,
-                                          pretty_format=pretty_format)
-    if logs['removed']:
-      removedLogs = logs['removed'].split('\n')
-      for log in removedLogs:
-        if log.strip():
-          if raw:
-            self.printText(' R ' + log)
-            self.out.nl()
-          else:
-            self.printRemoved('\t\t[-] ')
-            self.printText(log)
+    def _printRawDiff(self, diff, pretty_format=None, local=False):
+        _RelPath = lambda p: p.RelPath(local=local)
+        for project in diff["added"]:
+            self.printText(f"A {_RelPath(project)} {project.revisionExpr}")
             self.out.nl()
 
-    if logs['added']:
-      addedLogs = logs['added'].split('\n')
-      for log in addedLogs:
-        if log.strip():
-          if raw:
-            self.printText(' A ' + log)
-            self.out.nl()
-          else:
-            self.printAdded('\t\t[+] ')
-            self.printText(log)
+        for project in diff["removed"]:
+            self.printText(f"R {_RelPath(project)} {project.revisionExpr}")
             self.out.nl()
 
-  def ValidateOptions(self, opt, args):
-    if not args or len(args) > 2:
-      self.OptionParser.error('missing manifests to diff')
+        for project, otherProject in diff["changed"]:
+            self.printText(
+                f"C {_RelPath(project)} {project.revisionExpr} "
+                f"{otherProject.revisionExpr}"
+            )
+            self.out.nl()
+            self._printLogs(
+                project,
+                otherProject,
+                raw=True,
+                color=False,
+                pretty_format=pretty_format,
+            )
 
-  def Execute(self, opt, args):
-    self.out = _Coloring(self.manifest.globalConfig)
-    self.printText = self.out.nofmt_printer('text')
-    if opt.color:
-      self.printProject = self.out.nofmt_printer('project', attr = 'bold')
-      self.printAdded = self.out.nofmt_printer('green', fg = 'green', attr = 'bold')
-      self.printRemoved = self.out.nofmt_printer('red', fg = 'red', attr = 'bold')
-      self.printRevision = self.out.nofmt_printer('revision', fg = 'yellow')
-    else:
-      self.printProject = self.printAdded = self.printRemoved = self.printRevision = self.printText
+        for project, otherProject in diff["unreachable"]:
+            self.printText(
+                f"U {_RelPath(project)} {project.revisionExpr} "
+                f"{otherProject.revisionExpr}"
+            )
+            self.out.nl()
 
-    manifest1 = XmlManifest(self.manifest.repodir)
-    manifest1.Override(args[0], load_local_manifests=False)
-    if len(args) == 1:
-      manifest2 = self.manifest
-    else:
-      manifest2 = XmlManifest(self.manifest.repodir)
-      manifest2.Override(args[1], load_local_manifests=False)
+    def _printDiff(self, diff, color=True, pretty_format=None, local=False):
+        _RelPath = lambda p: p.RelPath(local=local)
+        if diff["added"]:
+            self.out.nl()
+            self.printText("added projects : \n")
+            self.out.nl()
+            for project in diff["added"]:
+                self.printProject("\t%s" % (_RelPath(project)))
+                self.printText(" at revision ")
+                self.printRevision(project.revisionExpr)
+                self.out.nl()
 
-    diff = manifest1.projectsDiff(manifest2)
-    if opt.raw:
-      self._printRawDiff(diff)
-    else:
-      self._printDiff(diff, color=opt.color, pretty_format=opt.pretty_format)
+        if diff["removed"]:
+            self.out.nl()
+            self.printText("removed projects : \n")
+            self.out.nl()
+            for project in diff["removed"]:
+                self.printProject("\t%s" % (_RelPath(project)))
+                self.printText(" at revision ")
+                self.printRevision(project.revisionExpr)
+                self.out.nl()
+
+        if diff["missing"]:
+            self.out.nl()
+            self.printText("missing projects : \n")
+            self.out.nl()
+            for project in diff["missing"]:
+                self.printProject("\t%s" % (_RelPath(project)))
+                self.printText(" at revision ")
+                self.printRevision(project.revisionExpr)
+                self.out.nl()
+
+        if diff["changed"]:
+            self.out.nl()
+            self.printText("changed projects : \n")
+            self.out.nl()
+            for project, otherProject in diff["changed"]:
+                self.printProject("\t%s" % (_RelPath(project)))
+                self.printText(" changed from ")
+                self.printRevision(project.revisionExpr)
+                self.printText(" to ")
+                self.printRevision(otherProject.revisionExpr)
+                self.out.nl()
+                self._printLogs(
+                    project,
+                    otherProject,
+                    raw=False,
+                    color=color,
+                    pretty_format=pretty_format,
+                )
+                self.out.nl()
+
+        if diff["unreachable"]:
+            self.out.nl()
+            self.printText("projects with unreachable revisions : \n")
+            self.out.nl()
+            for project, otherProject in diff["unreachable"]:
+                self.printProject("\t%s " % (_RelPath(project)))
+                self.printRevision(project.revisionExpr)
+                self.printText(" or ")
+                self.printRevision(otherProject.revisionExpr)
+                self.printText(" not found")
+                self.out.nl()
+
+    def _printLogs(
+        self, project, otherProject, raw=False, color=True, pretty_format=None
+    ):
+        logs = project.getAddedAndRemovedLogs(
+            otherProject,
+            oneline=(pretty_format is None),
+            color=color,
+            pretty_format=pretty_format,
+        )
+        if logs["removed"]:
+            removedLogs = logs["removed"].split("\n")
+            for log in removedLogs:
+                if log.strip():
+                    if raw:
+                        self.printText(" R " + log)
+                        self.out.nl()
+                    else:
+                        self.printRemoved("\t\t[-] ")
+                        self.printText(log)
+                        self.out.nl()
+
+        if logs["added"]:
+            addedLogs = logs["added"].split("\n")
+            for log in addedLogs:
+                if log.strip():
+                    if raw:
+                        self.printText(" A " + log)
+                        self.out.nl()
+                    else:
+                        self.printAdded("\t\t[+] ")
+                        self.printText(log)
+                        self.out.nl()
+
+    def ValidateOptions(self, opt, args):
+        if not args or len(args) > 2:
+            self.OptionParser.error("missing manifests to diff")
+        if opt.this_manifest_only is False:
+            raise self.OptionParser.error(
+                "`diffmanifest` only supports the current tree"
+            )
+
+    def Execute(self, opt, args):
+        self.out = _Coloring(self.client.globalConfig)
+        self.printText = self.out.nofmt_printer("text")
+        if opt.color:
+            self.printProject = self.out.nofmt_printer("project", attr="bold")
+            self.printAdded = self.out.nofmt_printer(
+                "green", fg="green", attr="bold"
+            )
+            self.printRemoved = self.out.nofmt_printer(
+                "red", fg="red", attr="bold"
+            )
+            self.printRevision = self.out.nofmt_printer("revision", fg="yellow")
+        else:
+            self.printProject = self.printAdded = self.printRemoved = (
+                self.printRevision
+            ) = self.printText
+
+        manifest1 = RepoClient(self.repodir)
+        manifest1.Override(args[0], load_local_manifests=False)
+        if len(args) == 1:
+            manifest2 = self.manifest
+        else:
+            manifest2 = RepoClient(self.repodir)
+            manifest2.Override(args[1], load_local_manifests=False)
+
+        diff = manifest1.projectsDiff(manifest2)
+        if opt.raw:
+            self._printRawDiff(
+                diff,
+                pretty_format=opt.pretty_format,
+                local=opt.this_manifest_only,
+            )
+        else:
+            self._printDiff(
+                diff,
+                color=opt.color,
+                pretty_format=opt.pretty_format,
+                local=opt.this_manifest_only,
+            )

subcmds/download.py

@@ -1,5 +1,3 @@
-# -*- coding:utf-8 -*-
-#
 # Copyright (C) 2008 The Android Open Source Project
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -14,101 +12,201 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-from __future__ import print_function
 import re
 import sys
 
 from command import Command
 from error import GitError
+from error import NoSuchProjectError
+from error import RepoExitError
+from repo_logging import RepoLogger
+
+
+CHANGE_RE = re.compile(r"^([1-9][0-9]*)(?:[/\.-]([1-9][0-9]*))?$")
+logger = RepoLogger(__file__)
+
+
+class DownloadCommandError(RepoExitError):
+    """Error raised when download command fails."""
 
-CHANGE_RE = re.compile(r'^([1-9][0-9]*)(?:[/\.-]([1-9][0-9]*))?$')
 
 class Download(Command):
-  common = True
-  helpSummary = "Download and checkout a change"
-  helpUsage = """
+    COMMON = True
+    helpSummary = "Download and checkout a change"
+    helpUsage = """
 %prog {[project] change[/patchset]}...
 """
-  helpDescription = """
+    helpDescription = """
 The '%prog' command downloads a change from the review system and
 makes it available in your project's local working directory.
 If no project is specified try to use current directory as a project.
 """
 
-  def _Options(self, p):
-    p.add_option('-c', '--cherry-pick',
-                 dest='cherrypick', action='store_true',
-                 help="cherry-pick instead of checkout")
-    p.add_option('-r', '--revert',
-                 dest='revert', action='store_true',
-                 help="revert instead of checkout")
-    p.add_option('-f', '--ff-only',
-                 dest='ffonly', action='store_true',
-                 help="force fast-forward merge")
+    def _Options(self, p):
+        p.add_option("-b", "--branch", help="create a new branch first")
+        p.add_option(
+            "-c",
+            "--cherry-pick",
+            dest="cherrypick",
+            action="store_true",
+            help="cherry-pick instead of checkout",
+        )
+        p.add_option(
+            "-x",
+            "--record-origin",
+            action="store_true",
+            help="pass -x when cherry-picking",
+        )
+        p.add_option(
+            "-r",
+            "--revert",
+            action="store_true",
+            help="revert instead of checkout",
+        )
+        p.add_option(
+            "-f",
+            "--ff-only",
+            dest="ffonly",
+            action="store_true",
+            help="force fast-forward merge",
+        )
 
-  def _ParseChangeIds(self, args):
-    if not args:
-      self.Usage()
+    def _ParseChangeIds(self, opt, args):
+        if not args:
+            self.Usage()
 
-    to_get = []
-    project = None
+        to_get = []
+        project = None
 
-    for a in args:
-      m = CHANGE_RE.match(a)
-      if m:
-        if not project:
-          project = self.GetProjects(".")[0]
-        chg_id = int(m.group(1))
-        if m.group(2):
-          ps_id = int(m.group(2))
-        else:
-          ps_id = 1
-          refs = 'refs/changes/%2.2d/%d/' % (chg_id % 100, chg_id)
-          output = project._LsRemote(refs + '*')
-          if output:
-            regex = refs + r'(\d+)'
-            rcomp = re.compile(regex, re.I)
-            for line in output.splitlines():
-              match = rcomp.search(line)
-              if match:
-                ps_id = max(int(match.group(1)), ps_id)
-        to_get.append((project, chg_id, ps_id))
-      else:
-        project = self.GetProjects([a])[0]
-    return to_get
+        for a in args:
+            m = CHANGE_RE.match(a)
+            if m:
+                if not project:
+                    project = self.GetProjects(".")[0]
+                    print("Defaulting to cwd project", project.name)
+                chg_id = int(m.group(1))
+                if m.group(2):
+                    ps_id = int(m.group(2))
+                else:
+                    ps_id = 1
+                    refs = "refs/changes/%2.2d/%d/" % (chg_id % 100, chg_id)
+                    output = project._LsRemote(refs + "*")
+                    if output:
+                        regex = refs + r"(\d+)"
+                        rcomp = re.compile(regex, re.I)
+                        for line in output.splitlines():
+                            match = rcomp.search(line)
+                            if match:
+                                ps_id = max(int(match.group(1)), ps_id)
+                to_get.append((project, chg_id, ps_id))
+            else:
+                projects = self.GetProjects(
+                    [a], all_manifests=not opt.this_manifest_only
+                )
+                if len(projects) > 1:
+                    # If the cwd is one of the projects, assume they want that.
+                    try:
+                        project = self.GetProjects(".")[0]
+                    except NoSuchProjectError:
+                        project = None
+                    if project not in projects:
+                        logger.error(
+                            "error: %s matches too many projects; please "
+                            "re-run inside the project checkout.",
+                            a,
+                        )
+                        for project in projects:
+                            logger.error(
+                                "  %s/ @ %s",
+                                project.RelPath(local=opt.this_manifest_only),
+                                project.revisionExpr,
+                            )
+                        raise NoSuchProjectError()
+                else:
+                    project = projects[0]
+                    print("Defaulting to cwd project", project.name)
+        return to_get
 
-  def Execute(self, opt, args):
-    for project, change_id, ps_id in self._ParseChangeIds(args):
-      dl = project.DownloadPatchSet(change_id, ps_id)
-      if not dl:
-        print('[%s] change %d/%d not found'
-              % (project.name, change_id, ps_id),
-              file=sys.stderr)
-        sys.exit(1)
+    def ValidateOptions(self, opt, args):
+        if opt.record_origin:
+            if not opt.cherrypick:
+                self.OptionParser.error(
+                    "-x only makes sense with --cherry-pick"
+                )
 
-      if not opt.revert and not dl.commits:
-        print('[%s] change %d/%d has already been merged'
-              % (project.name, change_id, ps_id),
-              file=sys.stderr)
-        continue
+            if opt.ffonly:
+                self.OptionParser.error(
+                    "-x and --ff are mutually exclusive options"
+                )
 
-      if len(dl.commits) > 1:
-        print('[%s] %d/%d depends on %d unmerged changes:' \
-              % (project.name, change_id, ps_id, len(dl.commits)),
-              file=sys.stderr)
-        for c in dl.commits:
-          print('  %s' % (c), file=sys.stderr)
-      if opt.cherrypick:
+    def Execute(self, opt, args):
         try:
-          project._CherryPick(dl.commit)
-        except GitError:
-          print('[%s] Could not complete the cherry-pick of %s' \
-                % (project.name, dl.commit), file=sys.stderr)
-          sys.exit(1)
+            self._ExecuteHelper(opt, args)
+        except Exception as e:
+            if isinstance(e, RepoExitError):
+                raise e
+            raise DownloadCommandError(aggregate_errors=[e])
 
-      elif opt.revert:
-        project._Revert(dl.commit)
-      elif opt.ffonly:
-        project._FastForward(dl.commit, ffonly=True)
-      else:
-        project._Checkout(dl.commit)
+    def _ExecuteHelper(self, opt, args):
+        for project, change_id, ps_id in self._ParseChangeIds(opt, args):
+            dl = project.DownloadPatchSet(change_id, ps_id)
+
+            if not opt.revert and not dl.commits:
+                logger.error(
+                    "[%s] change %d/%d has already been merged",
+                    project.name,
+                    change_id,
+                    ps_id,
+                )
+                continue
+
+            if len(dl.commits) > 1:
+                logger.error(
+                    "[%s] %d/%d depends on %d unmerged changes:",
+                    project.name,
+                    change_id,
+                    ps_id,
+                    len(dl.commits),
+                )
+                for c in dl.commits:
+                    print("  %s" % (c), file=sys.stderr)
+
+            if opt.cherrypick:
+                mode = "cherry-pick"
+            elif opt.revert:
+                mode = "revert"
+            elif opt.ffonly:
+                mode = "fast-forward merge"
+            else:
+                mode = "checkout"
+
+            # We'll combine the branch+checkout operation, but all the rest need
+            # a dedicated branch start.
+            if opt.branch and mode != "checkout":
+                project.StartBranch(opt.branch)
+
+            try:
+                if opt.cherrypick:
+                    project._CherryPick(
+                        dl.commit,
+                        ffonly=opt.ffonly,
+                        record_origin=opt.record_origin,
+                    )
+                elif opt.revert:
+                    project._Revert(dl.commit)
+                elif opt.ffonly:
+                    project._FastForward(dl.commit, ffonly=True)
+                else:
+                    if opt.branch:
+                        project.StartBranch(opt.branch, revision=dl.commit)
+                    else:
+                        project._Checkout(dl.commit)
+
+            except GitError:
+                logger.error(
+                    "[%s] Could not complete the %s of %s",
+                    project.name,
+                    mode,
+                    dl.commit,
+                )
+                raise

subcmds/forall.py

@@ -1,5 +1,3 @@
-# -*- coding:utf-8 -*-
-#
 # Copyright (C) 2008 The Android Open Source Project
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -14,46 +12,56 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-from __future__ import print_function
 import errno
-import multiprocessing
-import re
+import functools
+import io
 import os
+import re
 import signal
-import sys
 import subprocess
+import sys
 
 from color import Coloring
-from command import Command, MirrorSafeCommand
-import platform_utils
+from command import Command
+from command import DEFAULT_LOCAL_JOBS
+from command import MirrorSafeCommand
+from error import ManifestInvalidRevisionError
+from repo_logging import RepoLogger
 
+
+logger = RepoLogger(__file__)
 _CAN_COLOR = [
-  'branch',
-  'diff',
-  'grep',
-  'log',
+    "branch",
+    "diff",
+    "grep",
+    "log",
 ]
 
 
 class ForallColoring(Coloring):
-  def __init__(self, config):
-    Coloring.__init__(self, config, 'forall')
-    self.project = self.printer('project', attr='bold')
+    def __init__(self, config):
+        Coloring.__init__(self, config, "forall")
+        self.project = self.printer("project", attr="bold")
 
 
 class Forall(Command, MirrorSafeCommand):
-  common = False
-  helpSummary = "Run a shell command in each project"
-  helpUsage = """
+    COMMON = False
+    helpSummary = "Run a shell command in each project"
+    helpUsage = """
 %prog [<project>...] -c <command> [<arg>...]
-%prog -r str1 [str2] ... -c <command> [<arg>...]"
+%prog -r str1 [str2] ... -c <command> [<arg>...]
 """
-  helpDescription = """
+    helpDescription = """
 Executes the same shell command in each project.
 
 The -r option allows running the command only on projects matching
 regex or wildcard expression.
 
+By default, projects are processed non-interactively in parallel.  If you want
+to run interactive commands, make sure to pass --interactive to force --jobs 1.
+While the processing order of projects is not guaranteed, the order of project
+output is stable.
+
 # Output Formatting
 
 The -p option causes '%prog' to bind pipes to the command's stdin,
@@ -80,6 +88,11 @@ REPO_PROJECT is set to the unique name of the project.
 
 REPO_PATH is the path relative the the root of the client.
 
+REPO_OUTERPATH is the path of the sub manifest's root relative to the root of
+the client.
+
+REPO_INNERPATH is the path relative to the root of the sub manifest.
+
 REPO_REMOTE is the name of the remote system from the manifest.
 
 REPO_LREV is the name of the revision from the manifest, translated
@@ -116,286 +129,288 @@ terminal and are not redirected.
 If -e is used, when a command exits unsuccessfully, '%prog' will abort
 without iterating through the remaining projects.
 """
+    PARALLEL_JOBS = DEFAULT_LOCAL_JOBS
 
-  def _Options(self, p):
-    def cmd(option, opt_str, value, parser):
-      setattr(parser.values, option.dest, list(parser.rargs))
-      while parser.rargs:
-        del parser.rargs[0]
-    p.add_option('-r', '--regex',
-                 dest='regex', action='store_true',
-                 help="Execute the command only on projects matching regex or wildcard expression")
-    p.add_option('-i', '--inverse-regex',
-                 dest='inverse_regex', action='store_true',
-                 help="Execute the command only on projects not matching regex or wildcard expression")
-    p.add_option('-g', '--groups',
-                 dest='groups',
-                 help="Execute the command only on projects matching the specified groups")
-    p.add_option('-c', '--command',
-                 help='Command (and arguments) to execute',
-                 dest='command',
-                 action='callback',
-                 callback=cmd)
-    p.add_option('-e', '--abort-on-errors',
-                 dest='abort_on_errors', action='store_true',
-                 help='Abort if a command exits unsuccessfully')
-    p.add_option('--ignore-missing', action='store_true',
-                 help='Silently skip & do not exit non-zero due missing '
-                      'checkouts')
+    @staticmethod
+    def _cmd_option(option, _opt_str, _value, parser):
+        setattr(parser.values, option.dest or "command", list(parser.rargs))
+        while parser.rargs:
+            del parser.rargs[0]
 
-    g = p.add_option_group('Output')
-    g.add_option('-p',
-                 dest='project_header', action='store_true',
-                 help='Show project headers before output')
-    g.add_option('-v', '--verbose',
-                 dest='verbose', action='store_true',
-                 help='Show command error messages')
-    g.add_option('-j', '--jobs',
-                 dest='jobs', action='store', type='int', default=1,
-                 help='number of commands to execute simultaneously')
+    def _Options(self, p):
+        p.add_option(
+            "-r",
+            "--regex",
+            action="store_true",
+            help="execute the command only on projects matching regex or "
+            "wildcard expression",
+        )
+        p.add_option(
+            "-i",
+            "--inverse-regex",
+            action="store_true",
+            help="execute the command only on projects not matching regex or "
+            "wildcard expression",
+        )
+        p.add_option(
+            "-g",
+            "--groups",
+            help="execute the command only on projects matching the specified "
+            "groups",
+        )
+        p.add_option(
+            "-c",
+            "--command",
+            help="command (and arguments) to execute",
+            action="callback",
+            callback=self._cmd_option,
+        )
+        p.add_option(
+            "-e",
+            "--abort-on-errors",
+            action="store_true",
+            help="abort if a command exits unsuccessfully",
+        )
+        p.add_option(
+            "--ignore-missing",
+            action="store_true",
+            help="silently skip & do not exit non-zero due missing "
+            "checkouts",
+        )
 
-  def WantPager(self, opt):
-    return opt.project_header and opt.jobs == 1
+        g = p.get_option_group("--quiet")
+        g.add_option(
+            "-p",
+            dest="project_header",
+            action="store_true",
+            help="show project headers before output",
+        )
+        p.add_option(
+            "--interactive", action="store_true", help="force interactive usage"
+        )
 
-  def _SerializeProject(self, project):
-    """ Serialize a project._GitGetByExec instance.
+    def WantPager(self, opt):
+        return opt.project_header and opt.jobs == 1
 
-    project._GitGetByExec is not pickle-able. Instead of trying to pass it
-    around between processes, make a dict ourselves containing only the
-    attributes that we need.
+    def ValidateOptions(self, opt, args):
+        if not opt.command:
+            self.Usage()
 
-    """
-    if not self.manifest.IsMirror:
-      lrev = project.GetRevisionId()
-    else:
-      lrev = None
-    return {
-      'name': project.name,
-      'relpath': project.relpath,
-      'remote_name': project.remote.name,
-      'lrev': lrev,
-      'rrev': project.revisionExpr,
-      'annotations': dict((a.name, a.value) for a in project.annotations),
-      'gitdir': project.gitdir,
-      'worktree': project.worktree,
-    }
+    def Execute(self, opt, args):
+        cmd = [opt.command[0]]
+        all_trees = not opt.this_manifest_only
 
-  def ValidateOptions(self, opt, args):
-    if not opt.command:
-      self.Usage()
+        shell = True
+        if re.compile(r"^[a-z0-9A-Z_/\.-]+$").match(cmd[0]):
+            shell = False
 
-  def Execute(self, opt, args):
-    cmd = [opt.command[0]]
+        if shell:
+            cmd.append(cmd[0])
+        cmd.extend(opt.command[1:])
 
-    shell = True
-    if re.compile(r'^[a-z0-9A-Z_/\.-]+$').match(cmd[0]):
-      shell = False
+        # Historically, forall operated interactively, and in serial.  If the
+        # user has selected 1 job, then default to interacive mode.
+        if opt.jobs == 1:
+            opt.interactive = True
 
-    if shell:
-      cmd.append(cmd[0])
-    cmd.extend(opt.command[1:])
+        if opt.project_header and not shell and cmd[0] == "git":
+            # If this is a direct git command that can enable colorized
+            # output and the user prefers coloring, add --color into the
+            # command line because we are going to wrap the command into
+            # a pipe and git won't know coloring should activate.
+            #
+            for cn in cmd[1:]:
+                if not cn.startswith("-"):
+                    break
+            else:
+                cn = None
+            if cn and cn in _CAN_COLOR:
 
-    if  opt.project_header \
-    and not shell \
-    and cmd[0] == 'git':
-      # If this is a direct git command that can enable colorized
-      # output and the user prefers coloring, add --color into the
-      # command line because we are going to wrap the command into
-      # a pipe and git won't know coloring should activate.
-      #
-      for cn in cmd[1:]:
-        if not cn.startswith('-'):
-          break
-      else:
-        cn = None
-      if cn and cn in _CAN_COLOR:
-        class ColorCmd(Coloring):
-          def __init__(self, config, cmd):
-            Coloring.__init__(self, config, cmd)
-        if ColorCmd(self.manifest.manifestProject.config, cn).is_on:
-          cmd.insert(cmd.index(cn) + 1, '--color')
+                class ColorCmd(Coloring):
+                    def __init__(self, config, cmd):
+                        Coloring.__init__(self, config, cmd)
 
-    mirror = self.manifest.IsMirror
-    rc = 0
+                if ColorCmd(self.manifest.manifestProject.config, cn).is_on:
+                    cmd.insert(cmd.index(cn) + 1, "--color")
 
-    smart_sync_manifest_name = "smart_sync_override.xml"
-    smart_sync_manifest_path = os.path.join(
-      self.manifest.manifestProject.worktree, smart_sync_manifest_name)
+        mirror = self.manifest.IsMirror
 
-    if os.path.isfile(smart_sync_manifest_path):
-      self.manifest.Override(smart_sync_manifest_path)
+        smart_sync_manifest_name = "smart_sync_override.xml"
+        smart_sync_manifest_path = os.path.join(
+            self.manifest.manifestProject.worktree, smart_sync_manifest_name
+        )
 
-    if opt.regex:
-      projects = self.FindProjects(args)
-    elif opt.inverse_regex:
-      projects = self.FindProjects(args, inverse=True)
-    else:
-      projects = self.GetProjects(args, groups=opt.groups)
+        if os.path.isfile(smart_sync_manifest_path):
+            self.manifest.Override(smart_sync_manifest_path)
 
-    os.environ['REPO_COUNT'] = str(len(projects))
+        if opt.regex:
+            projects = self.FindProjects(args, all_manifests=all_trees)
+        elif opt.inverse_regex:
+            projects = self.FindProjects(
+                args, inverse=True, all_manifests=all_trees
+            )
+        else:
+            projects = self.GetProjects(
+                args, groups=opt.groups, all_manifests=all_trees
+            )
 
-    pool = multiprocessing.Pool(opt.jobs, InitWorker)
-    try:
-      config = self.manifest.manifestProject.config
-      results_it = pool.imap(
-         DoWorkWrapper,
-         self.ProjectArgs(projects, mirror, opt, cmd, shell, config))
-      pool.close()
-      for r in results_it:
-        rc = rc or r
-        if r != 0 and opt.abort_on_errors:
-          raise Exception('Aborting due to previous error')
-    except (KeyboardInterrupt, WorkerKeyboardInterrupt):
-      # Catch KeyboardInterrupt raised inside and outside of workers
-      print('Interrupted - terminating the pool')
-      pool.terminate()
-      rc = rc or errno.EINTR
-    except Exception as e:
-      # Catch any other exceptions raised
-      print('Got an error, terminating the pool: %s: %s' %
-              (type(e).__name__, e),
-            file=sys.stderr)
-      pool.terminate()
-      rc = rc or getattr(e, 'errno', 1)
-    finally:
-      pool.join()
-    if rc != 0:
-      sys.exit(rc)
+        os.environ["REPO_COUNT"] = str(len(projects))
+
+        def _ProcessResults(_pool, _output, results):
+            rc = 0
+            first = True
+            for r, output in results:
+                if output:
+                    if first:
+                        first = False
+                    elif opt.project_header:
+                        print()
+                    # To simplify the DoWorkWrapper, take care of automatic
+                    # newlines.
+                    end = "\n"
+                    if output[-1] == "\n":
+                        end = ""
+                    print(output, end=end)
+                rc = rc or r
+                if r != 0 and opt.abort_on_errors:
+                    raise Exception("Aborting due to previous error")
+            return rc
+
+        try:
+            config = self.manifest.manifestProject.config
+            with self.ParallelContext():
+                self.get_parallel_context()["projects"] = projects
+                rc = self.ExecuteInParallel(
+                    opt.jobs,
+                    functools.partial(
+                        self.DoWorkWrapper, mirror, opt, cmd, shell, config
+                    ),
+                    range(len(projects)),
+                    callback=_ProcessResults,
+                    ordered=True,
+                    initializer=self.InitWorker,
+                    chunksize=1,
+                )
+        except (KeyboardInterrupt, WorkerKeyboardInterrupt):
+            # Catch KeyboardInterrupt raised inside and outside of workers
+            rc = errno.EINTR
+        except Exception as e:
+            # Catch any other exceptions raised
+            logger.error(
+                "forall: unhandled error, terminating the pool: %s: %s",
+                type(e).__name__,
+                e,
+            )
+            rc = getattr(e, "errno", 1)
+        if rc != 0:
+            sys.exit(rc)
+
+    @classmethod
+    def InitWorker(cls):
+        signal.signal(signal.SIGINT, signal.SIG_IGN)
+
+    @classmethod
+    def DoWorkWrapper(cls, mirror, opt, cmd, shell, config, project_idx):
+        """A wrapper around the DoWork() method.
+
+        Catch the KeyboardInterrupt exceptions here and re-raise them as a
+        different, ``Exception``-based exception to stop it flooding the console
+        with stacktraces and making the parent hang indefinitely.
+
+        """
+        project = cls.get_parallel_context()["projects"][project_idx]
+        try:
+            return DoWork(project, mirror, opt, cmd, shell, project_idx, config)
+        except KeyboardInterrupt:
+            print("%s: Worker interrupted" % project.name)
+            raise WorkerKeyboardInterrupt()
 
-  def ProjectArgs(self, projects, mirror, opt, cmd, shell, config):
-    for cnt, p in enumerate(projects):
-      try:
-        project = self._SerializeProject(p)
-      except Exception as e:
-        print('Project list error on project %s: %s: %s' %
-                (p.name, type(e).__name__, e),
-              file=sys.stderr)
-        return
-      except KeyboardInterrupt:
-        print('Project list interrupted',
-              file=sys.stderr)
-        return
-      yield [mirror, opt, cmd, shell, cnt, config, project]
 
 class WorkerKeyboardInterrupt(Exception):
-  """ Keyboard interrupt exception for worker processes. """
-  pass
-
-
-def InitWorker():
-  signal.signal(signal.SIGINT, signal.SIG_IGN)
-
-def DoWorkWrapper(args):
-  """ A wrapper around the DoWork() method.
-
-  Catch the KeyboardInterrupt exceptions here and re-raise them as a different,
-  ``Exception``-based exception to stop it flooding the console with stacktraces
-  and making the parent hang indefinitely.
-
-  """
-  project = args.pop()
-  try:
-    return DoWork(project, *args)
-  except KeyboardInterrupt:
-    print('%s: Worker interrupted' % project['name'])
-    raise WorkerKeyboardInterrupt()
+    """Keyboard interrupt exception for worker processes."""
 
 
 def DoWork(project, mirror, opt, cmd, shell, cnt, config):
-  env = os.environ.copy()
-  def setenv(name, val):
-    if val is None:
-      val = ''
-    if hasattr(val, 'encode'):
-      val = val.encode()
-    env[name] = val
+    env = os.environ.copy()
 
-  setenv('REPO_PROJECT', project['name'])
-  setenv('REPO_PATH', project['relpath'])
-  setenv('REPO_REMOTE', project['remote_name'])
-  setenv('REPO_LREV', project['lrev'])
-  setenv('REPO_RREV', project['rrev'])
-  setenv('REPO_I', str(cnt + 1))
-  for name in project['annotations']:
-    setenv("REPO__%s" % (name), project['annotations'][name])
+    def setenv(name, val):
+        if val is None:
+            val = ""
+        env[name] = val
 
-  if mirror:
-    setenv('GIT_DIR', project['gitdir'])
-    cwd = project['gitdir']
-  else:
-    cwd = project['worktree']
+    setenv("REPO_PROJECT", project.name)
+    setenv("REPO_OUTERPATH", project.manifest.path_prefix)
+    setenv("REPO_INNERPATH", project.relpath)
+    setenv("REPO_PATH", project.RelPath(local=opt.this_manifest_only))
+    setenv("REPO_REMOTE", project.remote.name)
+    try:
+        # If we aren't in a fully synced state and we don't have the ref the
+        # manifest wants, then this will fail.  Ignore it for the purposes of
+        # this code.
+        lrev = "" if mirror else project.GetRevisionId()
+    except ManifestInvalidRevisionError:
+        lrev = ""
+    setenv("REPO_LREV", lrev)
+    setenv("REPO_RREV", project.revisionExpr)
+    setenv("REPO_UPSTREAM", project.upstream)
+    setenv("REPO_DEST_BRANCH", project.dest_branch)
+    setenv("REPO_I", str(cnt + 1))
+    for annotation in project.annotations:
+        setenv("REPO__%s" % (annotation.name), annotation.value)
 
-  if not os.path.exists(cwd):
-    # Allow the user to silently ignore missing checkouts so they can run on
-    # partial checkouts (good for infra recovery tools).
-    if opt.ignore_missing:
-      return 0
-    if ((opt.project_header and opt.verbose)
-        or not opt.project_header):
-      print('skipping %s/' % project['relpath'], file=sys.stderr)
-    return 1
+    if mirror:
+        setenv("GIT_DIR", project.gitdir)
+        cwd = project.gitdir
+    else:
+        cwd = project.worktree
 
-  if opt.project_header:
-    stdin = subprocess.PIPE
-    stdout = subprocess.PIPE
-    stderr = subprocess.PIPE
-  else:
-    stdin = None
-    stdout = None
-    stderr = None
+    if not os.path.exists(cwd):
+        # Allow the user to silently ignore missing checkouts so they can run on
+        # partial checkouts (good for infra recovery tools).
+        if opt.ignore_missing:
+            return (0, "")
 
-  p = subprocess.Popen(cmd,
-                       cwd=cwd,
-                       shell=shell,
-                       env=env,
-                       stdin=stdin,
-                       stdout=stdout,
-                       stderr=stderr)
+        output = ""
+        if (opt.project_header and opt.verbose) or not opt.project_header:
+            output = "skipping %s/" % project.RelPath(
+                local=opt.this_manifest_only
+            )
+        return (1, output)
 
-  if opt.project_header:
-    out = ForallColoring(config)
-    out.redirect(sys.stdout)
-    empty = True
-    errbuf = ''
+    if opt.verbose:
+        stderr = subprocess.STDOUT
+    else:
+        stderr = subprocess.DEVNULL
 
-    p.stdin.close()
-    s_in = platform_utils.FileDescriptorStreams.create()
-    s_in.add(p.stdout, sys.stdout, 'stdout')
-    s_in.add(p.stderr, sys.stderr, 'stderr')
+    stdin = None if opt.interactive else subprocess.DEVNULL
 
-    while not s_in.is_done:
-      in_ready = s_in.select()
-      for s in in_ready:
-        buf = s.read().decode()
-        if not buf:
-          s.close()
-          s_in.remove(s)
-          continue
+    result = subprocess.run(
+        cmd,
+        cwd=cwd,
+        shell=shell,
+        env=env,
+        check=False,
+        encoding="utf-8",
+        errors="replace",
+        stdin=stdin,
+        stdout=subprocess.PIPE,
+        stderr=stderr,
+    )
 
-        if not opt.verbose:
-          if s.std_name == 'stderr':
-            errbuf += buf
-            continue
-
-        if empty and out:
-          if not cnt == 0:
+    output = result.stdout
+    if opt.project_header:
+        if output:
+            buf = io.StringIO()
+            out = ForallColoring(config)
+            out.redirect(buf)
+            if mirror:
+                project_header_path = project.name
+            else:
+                project_header_path = project.RelPath(
+                    local=opt.this_manifest_only
+                )
+            out.project("project %s/" % project_header_path)
             out.nl()
-
-          if mirror:
-            project_header_path = project['name']
-          else:
-            project_header_path = project['relpath']
-          out.project('project %s/', project_header_path)
-          out.nl()
-          out.flush()
-          if errbuf:
-            sys.stderr.write(errbuf)
-            sys.stderr.flush()
-            errbuf = ''
-          empty = False
-
-        s.dest.write(buf)
-        s.dest.flush()
-
-  r = p.wait()
-  return r
+            buf.write(output)
+            output = buf.getvalue()
+    return (result.returncode, output)

subcmds/gc.py

@@ -0,0 +1,294 @@
+# Copyright (C) 2024 The Android Open Source Project
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import os
+from typing import List, Set
+
+from command import Command
+from git_command import GitCommand
+import platform_utils
+from progress import Progress
+from project import Project
+
+
+class Gc(Command):
+    COMMON = True
+    helpSummary = "Cleaning up internal repo and Git state."
+    helpUsage = """
+%prog
+"""
+
+    def _Options(self, p):
+        p.add_option(
+            "-n",
+            "--dry-run",
+            dest="dryrun",
+            default=False,
+            action="store_true",
+            help="do everything except actually delete",
+        )
+        p.add_option(
+            "-y",
+            "--yes",
+            default=False,
+            action="store_true",
+            help="answer yes to all safe prompts",
+        )
+        p.add_option(
+            "--repack",
+            default=False,
+            action="store_true",
+            help="repack all projects that use partial clone with "
+            "filter=blob:none",
+        )
+
+    def _find_git_to_delete(
+        self, to_keep: Set[str], start_dir: str
+    ) -> Set[str]:
+        """Searches no longer needed ".git" directories.
+
+        Scans the file system starting from `start_dir` and removes all
+        directories that end with ".git" that are not in the `to_keep` set.
+        """
+        to_delete = set()
+        for root, dirs, _ in platform_utils.walk(start_dir):
+            for directory in dirs:
+                if not directory.endswith(".git"):
+                    continue
+
+                path = os.path.join(root, directory)
+                if path not in to_keep:
+                    to_delete.add(path)
+
+        return to_delete
+
+    def delete_unused_projects(self, projects: List[Project], opt):
+        print(f"Scanning filesystem under {self.repodir}...")
+
+        project_paths = set()
+        project_object_paths = set()
+
+        for project in projects:
+            project_paths.add(project.gitdir)
+            project_object_paths.add(project.objdir)
+
+        to_delete = self._find_git_to_delete(
+            project_paths, os.path.join(self.repodir, "projects")
+        )
+
+        to_delete.update(
+            self._find_git_to_delete(
+                project_object_paths,
+                os.path.join(self.repodir, "project-objects"),
+            )
+        )
+
+        if not to_delete:
+            print("Nothing to clean up.")
+            return 0
+
+        print("Identified the following projects are no longer used:")
+        print("\n".join(to_delete))
+        print("")
+        if not opt.yes:
+            print(
+                "If you proceed, any local commits in those projects will be "
+                "destroyed!"
+            )
+            ask = input("Proceed? [y/N] ")
+            if ask.lower() != "y":
+                return 1
+
+        pm = Progress(
+            "Deleting",
+            len(to_delete),
+            delay=False,
+            quiet=opt.quiet,
+            show_elapsed=True,
+            elide=True,
+        )
+
+        for path in to_delete:
+            if opt.dryrun:
+                print(f"\nWould have deleted ${path}")
+            else:
+                tmp_path = os.path.join(
+                    os.path.dirname(path),
+                    f"to_be_deleted_{os.path.basename(path)}",
+                )
+                platform_utils.rename(path, tmp_path)
+                platform_utils.rmtree(tmp_path)
+            pm.update(msg=path)
+        pm.end()
+
+        return 0
+
+    def _generate_promisor_files(self, pack_dir: str):
+        """Generates promisor files for all pack files in the given directory.
+
+        Promisor files are empty files with the same name as the corresponding
+        pack file but with the ".promisor" extension. They are used by Git.
+        """
+        for root, _, files in platform_utils.walk(pack_dir):
+            for file in files:
+                if not file.endswith(".pack"):
+                    continue
+                with open(os.path.join(root, f"{file[:-4]}promisor"), "w"):
+                    pass
+
+    def repack_projects(self, projects: List[Project], opt):
+        repack_projects = []
+        # Find all projects eligible for repacking:
+        # - can't be shared
+        # - have a specific fetch filter
+        for project in projects:
+            if project.config.GetBoolean("extensions.preciousObjects"):
+                continue
+            if not project.clone_depth:
+                continue
+            if project.manifest.CloneFilterForDepth != "blob:none":
+                continue
+
+            repack_projects.append(project)
+
+        if opt.dryrun:
+            print(f"Would have repacked {len(repack_projects)} projects.")
+            return 0
+
+        pm = Progress(
+            "Repacking (this will take a while)",
+            len(repack_projects),
+            delay=False,
+            quiet=opt.quiet,
+            show_elapsed=True,
+            elide=True,
+        )
+
+        for project in repack_projects:
+            pm.update(msg=f"{project.name}")
+
+            pack_dir = os.path.join(project.gitdir, "tmp_repo_repack")
+            if os.path.isdir(pack_dir):
+                platform_utils.rmtree(pack_dir)
+            os.mkdir(pack_dir)
+
+            # Prepare workspace for repacking - remove all unreachable refs and
+            # their objects.
+            GitCommand(
+                project,
+                ["reflog", "expire", "--expire-unreachable=all"],
+                verify_command=True,
+            ).Wait()
+            pm.update(msg=f"{project.name} | gc", inc=0)
+            GitCommand(
+                project,
+                ["gc"],
+                verify_command=True,
+            ).Wait()
+
+            # Get all objects that are reachable from the remote, and pack them.
+            pm.update(msg=f"{project.name} | generating list of objects", inc=0)
+            remote_objects_cmd = GitCommand(
+                project,
+                [
+                    "rev-list",
+                    "--objects",
+                    f"--remotes={project.remote.name}",
+                    "--filter=blob:none",
+                    "--tags",
+                ],
+                capture_stdout=True,
+                verify_command=True,
+            )
+
+            # Get all local objects and pack them.
+            local_head_objects_cmd = GitCommand(
+                project,
+                ["rev-list", "--objects", "HEAD^{tree}"],
+                capture_stdout=True,
+                verify_command=True,
+            )
+            local_objects_cmd = GitCommand(
+                project,
+                [
+                    "rev-list",
+                    "--objects",
+                    "--all",
+                    "--reflog",
+                    "--indexed-objects",
+                    "--not",
+                    f"--remotes={project.remote.name}",
+                    "--tags",
+                ],
+                capture_stdout=True,
+                verify_command=True,
+            )
+
+            remote_objects_cmd.Wait()
+
+            pm.update(msg=f"{project.name} | remote repack", inc=0)
+            GitCommand(
+                project,
+                ["pack-objects", os.path.join(pack_dir, "pack")],
+                input=remote_objects_cmd.stdout,
+                capture_stderr=True,
+                capture_stdout=True,
+                verify_command=True,
+            ).Wait()
+
+            # create promisor file for each pack file
+            self._generate_promisor_files(pack_dir)
+
+            local_head_objects_cmd.Wait()
+            local_objects_cmd.Wait()
+
+            pm.update(msg=f"{project.name} | local repack", inc=0)
+            GitCommand(
+                project,
+                ["pack-objects", os.path.join(pack_dir, "pack")],
+                input=local_head_objects_cmd.stdout + local_objects_cmd.stdout,
+                capture_stderr=True,
+                capture_stdout=True,
+                verify_command=True,
+            ).Wait()
+
+            # Swap the old pack directory with the new one.
+            platform_utils.rename(
+                os.path.join(project.objdir, "objects", "pack"),
+                os.path.join(project.objdir, "objects", "pack_old"),
+            )
+            platform_utils.rename(
+                pack_dir,
+                os.path.join(project.objdir, "objects", "pack"),
+            )
+            platform_utils.rmtree(
+                os.path.join(project.objdir, "objects", "pack_old")
+            )
+
+        pm.end()
+        return 0
+
+    def Execute(self, opt, args):
+        projects: List[Project] = self.GetProjects(
+            args, all_manifests=not opt.this_manifest_only
+        )
+
+        ret = self.delete_unused_projects(projects, opt)
+        if ret != 0:
+            return ret
+
+        if not opt.repack:
+            return
+
+        return self.repack_projects(projects, opt)

subcmds/gitc_delete.py

@@ -1,52 +0,0 @@
-# -*- coding:utf-8 -*-
-#
-# Copyright (C) 2015 The Android Open Source Project
-#
-# Licensed under the Apache License, Version 2.0 (the "License");
-# you may not use this file except in compliance with the License.
-# You may obtain a copy of the License at
-#
-#      http://www.apache.org/licenses/LICENSE-2.0
-#
-# Unless required by applicable law or agreed to in writing, software
-# distributed under the License is distributed on an "AS IS" BASIS,
-# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-# See the License for the specific language governing permissions and
-# limitations under the License.
-
-from __future__ import print_function
-import sys
-
-from command import Command, GitcClientCommand
-import platform_utils
-
-from pyversion import is_python3
-if not is_python3():
-  input = raw_input
-
-class GitcDelete(Command, GitcClientCommand):
-  common = True
-  visible_everywhere = False
-  helpSummary = "Delete a GITC Client."
-  helpUsage = """
-%prog
-"""
-  helpDescription = """
-This subcommand deletes the current GITC client, deleting the GITC manifest
-and all locally downloaded sources.
-"""
-
-  def _Options(self, p):
-    p.add_option('-f', '--force',
-                 dest='force', action='store_true',
-                 help='Force the deletion (no prompt).')
-
-  def Execute(self, opt, args):
-    if not opt.force:
-      prompt = ('This will delete GITC client: %s\nAre you sure? (yes/no) ' %
-                self.gitc_manifest.gitc_client_name)
-      response = input(prompt).lower()
-      if not response == 'yes':
-        print('Response was not "yes"\n Exiting...')
-        sys.exit(1)
-    platform_utils.rmtree(self.gitc_manifest.gitc_client_dir)

subcmds/gitc_init.py

@@ -1,83 +0,0 @@
-# -*- coding:utf-8 -*-
-#
-# Copyright (C) 2015 The Android Open Source Project
-#
-# Licensed under the Apache License, Version 2.0 (the "License");
-# you may not use this file except in compliance with the License.
-# You may obtain a copy of the License at
-#
-#      http://www.apache.org/licenses/LICENSE-2.0
-#
-# Unless required by applicable law or agreed to in writing, software
-# distributed under the License is distributed on an "AS IS" BASIS,
-# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-# See the License for the specific language governing permissions and
-# limitations under the License.
-
-from __future__ import print_function
-import os
-import sys
-
-import gitc_utils
-from command import GitcAvailableCommand
-from manifest_xml import GitcManifest
-from subcmds import init
-import wrapper
-
-
-class GitcInit(init.Init, GitcAvailableCommand):
-  common = True
-  helpSummary = "Initialize a GITC Client."
-  helpUsage = """
-%prog [options] [client name]
-"""
-  helpDescription = """
-The '%prog' command is ran to initialize a new GITC client for use
-with the GITC file system.
-
-This command will setup the client directory, initialize repo, just
-like repo init does, and then downloads the manifest collection
-and installs it in the .repo/directory of the GITC client.
-
-Once this is done, a GITC manifest is generated by pulling the HEAD
-SHA for each project and generates the properly formatted XML file
-and installs it as .manifest in the GITC client directory.
-
-The -c argument is required to specify the GITC client name.
-
-The optional -f argument can be used to specify the manifest file to
-use for this GITC client.
-"""
-
-  def _Options(self, p):
-    super(GitcInit, self)._Options(p, gitc_init=True)
-    g = p.add_option_group('GITC options')
-    g.add_option('-f', '--manifest-file',
-                 dest='manifest_file',
-                 help='Optional manifest file to use for this GITC client.')
-    g.add_option('-c', '--gitc-client',
-                 dest='gitc_client',
-                 help='The name of the gitc_client instance to create or modify.')
-
-  def Execute(self, opt, args):
-    gitc_client = gitc_utils.parse_clientdir(os.getcwd())
-    if not gitc_client or (opt.gitc_client and gitc_client != opt.gitc_client):
-      print('fatal: Please update your repo command. See go/gitc for instructions.', file=sys.stderr)
-      sys.exit(1)
-    self.client_dir = os.path.join(gitc_utils.get_gitc_manifest_dir(),
-                                   gitc_client)
-    super(GitcInit, self).Execute(opt, args)
-
-    manifest_file = self.manifest.manifestFile
-    if opt.manifest_file:
-      if not os.path.exists(opt.manifest_file):
-        print('fatal: Specified manifest file %s does not exist.' %
-              opt.manifest_file)
-        sys.exit(1)
-      manifest_file = opt.manifest_file
-
-    manifest = GitcManifest(self.repodir, gitc_client)
-    manifest.Override(manifest_file)
-    gitc_utils.generate_gitc_manifest(None, manifest)
-    print('Please run `cd %s` to view your GITC client.' %
-          os.path.join(wrapper.Wrapper().GITC_FS_ROOT_DIR, gitc_client))

subcmds/grep.py

@@ -1,5 +1,3 @@
-# -*- coding:utf-8 -*-
-#
 # Copyright (C) 2009 The Android Open Source Project
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -14,28 +12,53 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-from __future__ import print_function
-
+import functools
 import sys
+from typing import NamedTuple
 
 from color import Coloring
+from command import DEFAULT_LOCAL_JOBS
 from command import PagedCommand
 from error import GitError
-from git_command import git_require, GitCommand
+from error import InvalidArgumentsError
+from error import SilentRepoExitError
+from git_command import GitCommand
+from repo_logging import RepoLogger
+
+
+logger = RepoLogger(__file__)
+
 
 class GrepColoring(Coloring):
-  def __init__(self, config):
-    Coloring.__init__(self, config, 'grep')
-    self.project = self.printer('project', attr='bold')
-    self.fail = self.printer('fail', fg='red')
+    def __init__(self, config):
+        Coloring.__init__(self, config, "grep")
+        self.project = self.printer("project", attr="bold")
+        self.fail = self.printer("fail", fg="red")
+
+
+class ExecuteOneResult(NamedTuple):
+    """Result from an execute instance."""
+
+    project_idx: int
+    rc: int
+    stdout: str
+    stderr: str
+    error: GitError
+
+
+class GrepCommandError(SilentRepoExitError):
+    """Grep command failure. Since Grep command
+    output already outputs errors ensure that
+    aggregate errors exit silently."""
+
 
 class Grep(PagedCommand):
-  common = True
-  helpSummary = "Print lines matching a pattern"
-  helpUsage = """
+    COMMON = True
+    helpSummary = "Print lines matching a pattern"
+    helpUsage = """
 %prog {pattern | -e pattern} [<project>...]
 """
-  helpDescription = """
+    helpDescription = """
 Search for the specified patterns in all project files.
 
 # Boolean Options
@@ -63,195 +86,323 @@ contain a line that matches both expressions:
   repo grep --all-match -e NODE -e Unexpected
 
 """
+    PARALLEL_JOBS = DEFAULT_LOCAL_JOBS
 
-  def _Options(self, p):
-    def carry(option,
-              opt_str,
-              value,
-              parser):
-      pt = getattr(parser.values, 'cmd_argv', None)
-      if pt is None:
-        pt = []
-        setattr(parser.values, 'cmd_argv', pt)
+    @staticmethod
+    def _carry_option(_option, opt_str, value, parser):
+        pt = getattr(parser.values, "cmd_argv", None)
+        if pt is None:
+            pt = []
+            setattr(parser.values, "cmd_argv", pt)
 
-      if opt_str == '-(':
-        pt.append('(')
-      elif opt_str == '-)':
-        pt.append(')')
-      else:
-        pt.append(opt_str)
+        if opt_str == "-(":
+            pt.append("(")
+        elif opt_str == "-)":
+            pt.append(")")
+        else:
+            pt.append(opt_str)
 
-      if value is not None:
-        pt.append(value)
+        if value is not None:
+            pt.append(value)
 
-    g = p.add_option_group('Sources')
-    g.add_option('--cached',
-                 action='callback', callback=carry,
-                 help='Search the index, instead of the work tree')
-    g.add_option('-r', '--revision',
-                 dest='revision', action='append', metavar='TREEish',
-                 help='Search TREEish, instead of the work tree')
+    def _CommonOptions(self, p):
+        """Override common options slightly."""
+        super()._CommonOptions(p, opt_v=False)
 
-    g = p.add_option_group('Pattern')
-    g.add_option('-e',
-                 action='callback', callback=carry,
-                 metavar='PATTERN', type='str',
-                 help='Pattern to search for')
-    g.add_option('-i', '--ignore-case',
-                 action='callback', callback=carry,
-                 help='Ignore case differences')
-    g.add_option('-a', '--text',
-                 action='callback', callback=carry,
-                 help="Process binary files as if they were text")
-    g.add_option('-I',
-                 action='callback', callback=carry,
-                 help="Don't match the pattern in binary files")
-    g.add_option('-w', '--word-regexp',
-                 action='callback', callback=carry,
-                 help='Match the pattern only at word boundaries')
-    g.add_option('-v', '--invert-match',
-                 action='callback', callback=carry,
-                 help='Select non-matching lines')
-    g.add_option('-G', '--basic-regexp',
-                 action='callback', callback=carry,
-                 help='Use POSIX basic regexp for patterns (default)')
-    g.add_option('-E', '--extended-regexp',
-                 action='callback', callback=carry,
-                 help='Use POSIX extended regexp for patterns')
-    g.add_option('-F', '--fixed-strings',
-                 action='callback', callback=carry,
-                 help='Use fixed strings (not regexp) for pattern')
+    def _Options(self, p):
+        g = p.add_option_group("Sources")
+        g.add_option(
+            "--cached",
+            action="callback",
+            callback=self._carry_option,
+            help="Search the index, instead of the work tree",
+        )
+        g.add_option(
+            "-r",
+            "--revision",
+            action="append",
+            metavar="TREEish",
+            help="Search TREEish, instead of the work tree",
+        )
 
-    g = p.add_option_group('Pattern Grouping')
-    g.add_option('--all-match',
-                 action='callback', callback=carry,
-                 help='Limit match to lines that have all patterns')
-    g.add_option('--and', '--or', '--not',
-                 action='callback', callback=carry,
-                 help='Boolean operators to combine patterns')
-    g.add_option('-(', '-)',
-                 action='callback', callback=carry,
-                 help='Boolean operator grouping')
+        g = p.add_option_group("Pattern")
+        g.add_option(
+            "-e",
+            action="callback",
+            callback=self._carry_option,
+            metavar="PATTERN",
+            type="str",
+            help="Pattern to search for",
+        )
+        g.add_option(
+            "-i",
+            "--ignore-case",
+            action="callback",
+            callback=self._carry_option,
+            help="Ignore case differences",
+        )
+        g.add_option(
+            "-a",
+            "--text",
+            action="callback",
+            callback=self._carry_option,
+            help="Process binary files as if they were text",
+        )
+        g.add_option(
+            "-I",
+            action="callback",
+            callback=self._carry_option,
+            help="Don't match the pattern in binary files",
+        )
+        g.add_option(
+            "-w",
+            "--word-regexp",
+            action="callback",
+            callback=self._carry_option,
+            help="Match the pattern only at word boundaries",
+        )
+        g.add_option(
+            "-v",
+            "--invert-match",
+            action="callback",
+            callback=self._carry_option,
+            help="Select non-matching lines",
+        )
+        g.add_option(
+            "-G",
+            "--basic-regexp",
+            action="callback",
+            callback=self._carry_option,
+            help="Use POSIX basic regexp for patterns (default)",
+        )
+        g.add_option(
+            "-E",
+            "--extended-regexp",
+            action="callback",
+            callback=self._carry_option,
+            help="Use POSIX extended regexp for patterns",
+        )
+        g.add_option(
+            "-F",
+            "--fixed-strings",
+            action="callback",
+            callback=self._carry_option,
+            help="Use fixed strings (not regexp) for pattern",
+        )
 
-    g = p.add_option_group('Output')
-    g.add_option('-n',
-                 action='callback', callback=carry,
-                 help='Prefix the line number to matching lines')
-    g.add_option('-C',
-                 action='callback', callback=carry,
-                 metavar='CONTEXT', type='str',
-                 help='Show CONTEXT lines around match')
-    g.add_option('-B',
-                 action='callback', callback=carry,
-                 metavar='CONTEXT', type='str',
-                 help='Show CONTEXT lines before match')
-    g.add_option('-A',
-                 action='callback', callback=carry,
-                 metavar='CONTEXT', type='str',
-                 help='Show CONTEXT lines after match')
-    g.add_option('-l', '--name-only', '--files-with-matches',
-                 action='callback', callback=carry,
-                 help='Show only file names containing matching lines')
-    g.add_option('-L', '--files-without-match',
-                 action='callback', callback=carry,
-                 help='Show only file names not containing matching lines')
+        g = p.add_option_group("Pattern Grouping")
+        g.add_option(
+            "--all-match",
+            action="callback",
+            callback=self._carry_option,
+            help="Limit match to lines that have all patterns",
+        )
+        g.add_option(
+            "--and",
+            "--or",
+            "--not",
+            action="callback",
+            callback=self._carry_option,
+            help="Boolean operators to combine patterns",
+        )
+        g.add_option(
+            "-(",
+            "-)",
+            action="callback",
+            callback=self._carry_option,
+            help="Boolean operator grouping",
+        )
 
+        g = p.add_option_group("Output")
+        g.add_option(
+            "-n",
+            action="callback",
+            callback=self._carry_option,
+            help="Prefix the line number to matching lines",
+        )
+        g.add_option(
+            "-C",
+            action="callback",
+            callback=self._carry_option,
+            metavar="CONTEXT",
+            type="str",
+            help="Show CONTEXT lines around match",
+        )
+        g.add_option(
+            "-B",
+            action="callback",
+            callback=self._carry_option,
+            metavar="CONTEXT",
+            type="str",
+            help="Show CONTEXT lines before match",
+        )
+        g.add_option(
+            "-A",
+            action="callback",
+            callback=self._carry_option,
+            metavar="CONTEXT",
+            type="str",
+            help="Show CONTEXT lines after match",
+        )
+        g.add_option(
+            "-l",
+            "--name-only",
+            "--files-with-matches",
+            action="callback",
+            callback=self._carry_option,
+            help="Show only file names containing matching lines",
+        )
+        g.add_option(
+            "-L",
+            "--files-without-match",
+            action="callback",
+            callback=self._carry_option,
+            help="Show only file names not containing matching lines",
+        )
 
-  def Execute(self, opt, args):
-    out = GrepColoring(self.manifest.manifestProject.config)
+    @classmethod
+    def _ExecuteOne(cls, cmd_argv, project_idx):
+        """Process one project."""
+        project = cls.get_parallel_context()["projects"][project_idx]
+        try:
+            p = GitCommand(
+                project,
+                cmd_argv,
+                bare=False,
+                capture_stdout=True,
+                capture_stderr=True,
+                verify_command=True,
+            )
+        except GitError as e:
+            return ExecuteOneResult(project_idx, -1, None, str(e), e)
 
-    cmd_argv = ['grep']
-    if out.is_on and git_require((1, 6, 3)):
-      cmd_argv.append('--color')
-    cmd_argv.extend(getattr(opt, 'cmd_argv', []))
+        try:
+            error = None
+            rc = p.Wait()
+        except GitError as e:
+            rc = 1
+            error = e
+        return ExecuteOneResult(project_idx, rc, p.stdout, p.stderr, error)
 
-    if '-e' not in cmd_argv:
-      if not args:
-        self.Usage()
-      cmd_argv.append('-e')
-      cmd_argv.append(args[0])
-      args = args[1:]
+    @staticmethod
+    def _ProcessResults(
+        full_name, have_rev, opt, projects, _pool, out, results
+    ):
+        git_failed = False
+        bad_rev = False
+        have_match = False
+        _RelPath = lambda p: p.RelPath(local=opt.this_manifest_only)
+        errors = []
 
-    projects = self.GetProjects(args)
+        for result in results:
+            project = projects[result.project_idx]
+            if result.rc < 0:
+                git_failed = True
+                out.project("--- project %s ---" % _RelPath(project))
+                out.nl()
+                out.fail("%s", result.stderr)
+                out.nl()
+                errors.append(result.error)
+                continue
 
-    full_name = False
-    if len(projects) > 1:
-      cmd_argv.append('--full-name')
-      full_name = True
+            if result.rc:
+                # no results
+                if result.stderr:
+                    if (
+                        have_rev
+                        and "fatal: ambiguous argument" in result.stderr
+                    ):
+                        bad_rev = True
+                    else:
+                        out.project("--- project %s ---" % _RelPath(project))
+                        out.nl()
+                        out.fail("%s", result.stderr.strip())
+                        out.nl()
+                    if result.error is not None:
+                        errors.append(result.error)
+                continue
+            have_match = True
 
-    have_rev = False
-    if opt.revision:
-      if '--cached' in cmd_argv:
-        print('fatal: cannot combine --cached and --revision', file=sys.stderr)
-        sys.exit(1)
-      have_rev = True
-      cmd_argv.extend(opt.revision)
-    cmd_argv.append('--')
+            # We cut the last element, to avoid a blank line.
+            r = result.stdout.split("\n")
+            r = r[0:-1]
 
-    git_failed = False
-    bad_rev = False
-    have_match = False
+            if have_rev and full_name:
+                for line in r:
+                    rev, line = line.split(":", 1)
+                    out.write("%s", rev)
+                    out.write(":")
+                    out.project(_RelPath(project))
+                    out.write("/")
+                    out.write("%s", line)
+                    out.nl()
+            elif full_name:
+                for line in r:
+                    out.project(_RelPath(project))
+                    out.write("/")
+                    out.write("%s", line)
+                    out.nl()
+            else:
+                for line in r:
+                    print(line)
 
-    for project in projects:
-      try:
-        p = GitCommand(project,
-                       cmd_argv,
-                       bare=False,
-                       capture_stdout=True,
-                       capture_stderr=True)
-      except GitError as e:
-        git_failed = True
-        out.project('--- project %s ---' % project.relpath)
-        out.nl()
-        out.fail('%s', str(e))
-        out.nl()
-        continue
+        return (git_failed, bad_rev, have_match, errors)
 
-      if p.Wait() != 0:
-        # no results
-        #
-        if p.stderr:
-          if have_rev and 'fatal: ambiguous argument' in p.stderr:
-            bad_rev = True
-          else:
-            out.project('--- project %s ---' % project.relpath)
-            out.nl()
-            out.fail('%s', p.stderr.strip())
-            out.nl()
-        continue
-      have_match = True
+    def Execute(self, opt, args):
+        out = GrepColoring(self.manifest.manifestProject.config)
 
-      # We cut the last element, to avoid a blank line.
-      #
-      r = p.stdout.split('\n')
-      r = r[0:-1]
+        cmd_argv = ["grep"]
+        if out.is_on:
+            cmd_argv.append("--color")
+        cmd_argv.extend(getattr(opt, "cmd_argv", []))
 
-      if have_rev and full_name:
-        for line in r:
-          rev, line = line.split(':', 1)
-          out.write("%s", rev)
-          out.write(':')
-          out.project(project.relpath)
-          out.write('/')
-          out.write("%s", line)
-          out.nl()
-      elif full_name:
-        for line in r:
-          out.project(project.relpath)
-          out.write('/')
-          out.write("%s", line)
-          out.nl()
-      else:
-        for line in r:
-          print(line)
+        if "-e" not in cmd_argv:
+            if not args:
+                self.Usage()
+            cmd_argv.append("-e")
+            cmd_argv.append(args[0])
+            args = args[1:]
 
-    if git_failed:
-      sys.exit(1)
-    elif have_match:
-      sys.exit(0)
-    elif have_rev and bad_rev:
-      for r in opt.revision:
-        print("error: can't search revision %s" % r, file=sys.stderr)
-      sys.exit(1)
-    else:
-      sys.exit(1)
+        projects = self.GetProjects(
+            args, all_manifests=not opt.this_manifest_only
+        )
+
+        full_name = False
+        if len(projects) > 1:
+            cmd_argv.append("--full-name")
+            full_name = True
+
+        have_rev = False
+        if opt.revision:
+            if "--cached" in cmd_argv:
+                msg = "fatal: cannot combine --cached and --revision"
+                logger.error(msg)
+                raise InvalidArgumentsError(msg)
+            have_rev = True
+            cmd_argv.extend(opt.revision)
+        cmd_argv.append("--")
+
+        with self.ParallelContext():
+            self.get_parallel_context()["projects"] = projects
+            git_failed, bad_rev, have_match, errors = self.ExecuteInParallel(
+                opt.jobs,
+                functools.partial(self._ExecuteOne, cmd_argv),
+                range(len(projects)),
+                callback=functools.partial(
+                    self._ProcessResults, full_name, have_rev, opt, projects
+                ),
+                output=out,
+                ordered=True,
+                chunksize=1,
+            )
+
+        if git_failed:
+            raise GrepCommandError(
+                "error: git failures", aggregate_errors=errors
+            )
+        elif have_match:
+            sys.exit(0)
+        elif have_rev and bad_rev:
+            for r in opt.revision:
+                logger.error("error: can't search revision %s", r)
+        raise GrepCommandError(aggregate_errors=errors)

subcmds/help.py

@@ -1,5 +1,3 @@
-# -*- coding:utf-8 -*-
-#
 # Copyright (C) 2008 The Android Open Source Project
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -14,156 +12,182 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-from __future__ import print_function
 import re
 import sys
-from formatter import AbstractFormatter, DumbWriter
+import textwrap
 
 from color import Coloring
-from command import PagedCommand, MirrorSafeCommand, GitcAvailableCommand, GitcClientCommand
-import gitc_utils
+from command import MirrorSafeCommand
+from command import PagedCommand
+from error import RepoExitError
+from subcmds import all_commands
+from wrapper import Wrapper
+
+
+class InvalidHelpCommand(RepoExitError):
+    """Invalid command passed into help."""
+
 
 class Help(PagedCommand, MirrorSafeCommand):
-  common = False
-  helpSummary = "Display detailed help on a command"
-  helpUsage = """
+    COMMON = False
+    helpSummary = "Display detailed help on a command"
+    helpUsage = """
 %prog [--all|command]
 """
-  helpDescription = """
+    helpDescription = """
 Displays detailed usage information about a command.
 """
 
-  def _PrintCommands(self, commandNames):
-    """Helper to display |commandNames| summaries."""
-    maxlen = 0
-    for name in commandNames:
-      maxlen = max(maxlen, len(name))
-    fmt = '  %%-%ds  %%s' % maxlen
+    def _PrintCommands(self, commandNames):
+        """Helper to display |commandNames| summaries."""
+        maxlen = 0
+        for name in commandNames:
+            maxlen = max(maxlen, len(name))
+        fmt = "  %%-%ds  %%s" % maxlen
 
-    for name in commandNames:
-      command = self.commands[name]
-      try:
-        summary = command.helpSummary.strip()
-      except AttributeError:
-        summary = ''
-      print(fmt % (name, summary))
+        for name in commandNames:
+            command = all_commands[name]()
+            try:
+                summary = command.helpSummary.strip()
+            except AttributeError:
+                summary = ""
+            print(fmt % (name, summary))
 
-  def _PrintAllCommands(self):
-    print('usage: repo COMMAND [ARGS]')
-    print('The complete list of recognized repo commands are:')
-    commandNames = list(sorted(self.commands))
-    self._PrintCommands(commandNames)
-    print("See 'repo help <command>' for more information on a "
-          'specific command.')
+    def _PrintAllCommands(self):
+        print("usage: repo COMMAND [ARGS]")
+        self.PrintAllCommandsBody()
 
-  def _PrintCommonCommands(self):
-    print('usage: repo COMMAND [ARGS]')
-    print('The most commonly used repo commands are:')
+    def PrintAllCommandsBody(self):
+        print("The complete list of recognized repo commands is:")
+        commandNames = list(sorted(all_commands))
+        self._PrintCommands(commandNames)
+        print(
+            "See 'repo help <command>' for more information on a "
+            "specific command."
+        )
+        print("Bug reports:", Wrapper().BUG_URL)
 
-    def gitc_supported(cmd):
-      if not isinstance(cmd, GitcAvailableCommand) and not isinstance(cmd, GitcClientCommand):
-        return True
-      if self.manifest.isGitcClient:
-        return True
-      if isinstance(cmd, GitcClientCommand):
-        return False
-      if gitc_utils.get_gitc_manifest_dir():
-        return True
-      return False
+    def _PrintCommonCommands(self):
+        print("usage: repo COMMAND [ARGS]")
+        self.PrintCommonCommandsBody()
 
-    commandNames = list(sorted([name
-                    for name, command in self.commands.items()
-                    if command.common and gitc_supported(command)]))
-    self._PrintCommands(commandNames)
+    def PrintCommonCommandsBody(self):
+        print("The most commonly used repo commands are:")
 
-    print(
-"See 'repo help <command>' for more information on a specific command.\n"
-"See 'repo help --all' for a complete list of recognized commands.")
+        commandNames = list(
+            sorted(
+                name for name, command in all_commands.items() if command.COMMON
+            )
+        )
+        self._PrintCommands(commandNames)
 
-  def _PrintCommandHelp(self, cmd, header_prefix=''):
-    class _Out(Coloring):
-      def __init__(self, gc):
-        Coloring.__init__(self, gc, 'help')
-        self.heading = self.printer('heading', attr='bold')
+        print(
+            "See 'repo help <command>' for more information on a specific "
+            "command.\nSee 'repo help --all' for a complete list of recognized "
+            "commands."
+        )
+        print("Bug reports:", Wrapper().BUG_URL)
 
-        self.wrap = AbstractFormatter(DumbWriter())
+    def _PrintCommandHelp(self, cmd, header_prefix=""):
+        class _Out(Coloring):
+            def __init__(self, gc):
+                Coloring.__init__(self, gc, "help")
+                self.heading = self.printer("heading", attr="bold")
+                self._first = True
 
-      def _PrintSection(self, heading, bodyAttr):
-        try:
-          body = getattr(cmd, bodyAttr)
-        except AttributeError:
-          return
-        if body == '' or body is None:
-          return
+            def _PrintSection(self, heading, bodyAttr):
+                try:
+                    body = getattr(cmd, bodyAttr)
+                except AttributeError:
+                    return
+                if body == "" or body is None:
+                    return
 
-        self.nl()
+                if not self._first:
+                    self.nl()
+                self._first = False
 
-        self.heading('%s%s', header_prefix, heading)
-        self.nl()
-        self.nl()
+                self.heading("%s%s", header_prefix, heading)
+                self.nl()
+                self.nl()
 
-        me = 'repo %s' % cmd.NAME
-        body = body.strip()
-        body = body.replace('%prog', me)
+                me = "repo %s" % cmd.NAME
+                body = body.strip()
+                body = body.replace("%prog", me)
 
-        asciidoc_hdr = re.compile(r'^\n?#+ (.+)$')
-        for para in body.split("\n\n"):
-          if para.startswith(' '):
-            self.write('%s', para)
-            self.nl()
-            self.nl()
-            continue
+                # Extract the title, but skip any trailing {#anchors}.
+                asciidoc_hdr = re.compile(r"^\n?#+ ([^{]+)(\{#.+\})?$")
+                for para in body.split("\n\n"):
+                    if para.startswith(" "):
+                        self.write("%s", para)
+                        self.nl()
+                        self.nl()
+                        continue
 
-          m = asciidoc_hdr.match(para)
-          if m:
-            self.heading('%s%s', header_prefix, m.group(1))
-            self.nl()
-            self.nl()
-            continue
+                    m = asciidoc_hdr.match(para)
+                    if m:
+                        self.heading("%s%s", header_prefix, m.group(1))
+                        self.nl()
+                        self.nl()
+                        continue
 
-          self.wrap.add_flowing_data(para)
-          self.wrap.end_paragraph(1)
-        self.wrap.end_paragraph(0)
+                    lines = textwrap.wrap(
+                        para.replace("  ", " "),
+                        width=80,
+                        break_long_words=False,
+                        break_on_hyphens=False,
+                    )
+                    for line in lines:
+                        self.write("%s", line)
+                        self.nl()
+                    self.nl()
 
-    out = _Out(self.manifest.globalConfig)
-    out._PrintSection('Summary', 'helpSummary')
-    cmd.OptionParser.print_help()
-    out._PrintSection('Description', 'helpDescription')
+        out = _Out(self.client.globalConfig)
+        out._PrintSection("Summary", "helpSummary")
+        cmd.OptionParser.print_help()
+        out._PrintSection("Description", "helpDescription")
 
-  def _PrintAllCommandHelp(self):
-    for name in sorted(self.commands):
-      cmd = self.commands[name]
-      cmd.manifest = self.manifest
-      self._PrintCommandHelp(cmd, header_prefix='[%s] ' % (name,))
+    def _PrintAllCommandHelp(self):
+        for name in sorted(all_commands):
+            cmd = all_commands[name](manifest=self.manifest)
+            self._PrintCommandHelp(cmd, header_prefix=f"[{name}] ")
 
-  def _Options(self, p):
-    p.add_option('-a', '--all',
-                 dest='show_all', action='store_true',
-                 help='show the complete list of commands')
-    p.add_option('--help-all',
-                 dest='show_all_help', action='store_true',
-                 help='show the --help of all commands')
+    def _Options(self, p):
+        p.add_option(
+            "-a",
+            "--all",
+            dest="show_all",
+            action="store_true",
+            help="show the complete list of commands",
+        )
+        p.add_option(
+            "--help-all",
+            dest="show_all_help",
+            action="store_true",
+            help="show the --help of all commands",
+        )
 
-  def Execute(self, opt, args):
-    if len(args) == 0:
-      if opt.show_all_help:
-        self._PrintAllCommandHelp()
-      elif opt.show_all:
-        self._PrintAllCommands()
-      else:
-        self._PrintCommonCommands()
+    def Execute(self, opt, args):
+        if len(args) == 0:
+            if opt.show_all_help:
+                self._PrintAllCommandHelp()
+            elif opt.show_all:
+                self._PrintAllCommands()
+            else:
+                self._PrintCommonCommands()
 
-    elif len(args) == 1:
-      name = args[0]
+        elif len(args) == 1:
+            name = args[0]
 
-      try:
-        cmd = self.commands[name]
-      except KeyError:
-        print("repo: '%s' is not a repo command." % name, file=sys.stderr)
-        sys.exit(1)
+            try:
+                cmd = all_commands[name](manifest=self.manifest)
+            except KeyError:
+                print(
+                    "repo: '%s' is not a repo command." % name, file=sys.stderr
+                )
+                raise InvalidHelpCommand(name)
 
-      cmd.manifest = self.manifest
-      self._PrintCommandHelp(cmd)
+            self._PrintCommandHelp(cmd)
 
-    else:
-      self._PrintCommandHelp(self)
+        else:
+            self._PrintCommandHelp(self)

subcmds/info.py

@@ -1,5 +1,3 @@
-# -*- coding:utf-8 -*-
-#
 # Copyright (C) 2012 The Android Open Source Project
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -14,197 +12,247 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-from command import PagedCommand
+import optparse
+
 from color import Coloring
+from command import PagedCommand
+from git_refs import R_HEADS
 from git_refs import R_M
 
+
 class _Coloring(Coloring):
-  def __init__(self, config):
-    Coloring.__init__(self, config, "status")
+    def __init__(self, config):
+        Coloring.__init__(self, config, "status")
+
 
 class Info(PagedCommand):
-  common = True
-  helpSummary = "Get info on the manifest branch, current branch or unmerged branches"
-  helpUsage = "%prog [-dl] [-o [-b]] [<project>...]"
+    COMMON = True
+    helpSummary = (
+        "Get info on the manifest branch, current branch or unmerged branches"
+    )
+    helpUsage = "%prog [-dl] [-o [-c]] [<project>...]"
 
-  def _Options(self, p):
-    p.add_option('-d', '--diff',
-                 dest='all', action='store_true',
-                 help="show full info and commit diff including remote branches")
-    p.add_option('-o', '--overview',
-                 dest='overview', action='store_true',
-                 help='show overview of all local commits')
-    p.add_option('-b', '--current-branch',
-                 dest="current_branch", action="store_true",
-                 help="consider only checked out branches")
-    p.add_option('-l', '--local-only',
-                 dest="local", action="store_true",
-                 help="Disable all remote operations")
+    def _Options(self, p):
+        p.add_option(
+            "-d",
+            "--diff",
+            dest="all",
+            action="store_true",
+            help="show full info and commit diff including remote branches",
+        )
+        p.add_option(
+            "-o",
+            "--overview",
+            action="store_true",
+            help="show overview of all local commits",
+        )
+        p.add_option(
+            "-c",
+            "--current-branch",
+            action="store_true",
+            help="consider only checked out branches",
+        )
+        p.add_option(
+            "--no-current-branch",
+            dest="current_branch",
+            action="store_false",
+            help="consider all local branches",
+        )
+        # Turn this into a warning & remove this someday.
+        p.add_option(
+            "-b",
+            dest="current_branch",
+            action="store_true",
+            help=optparse.SUPPRESS_HELP,
+        )
+        p.add_option(
+            "-l",
+            "--local-only",
+            dest="local",
+            action="store_true",
+            help="disable all remote operations",
+        )
 
+    def Execute(self, opt, args):
+        self.out = _Coloring(self.client.globalConfig)
+        self.heading = self.out.printer("heading", attr="bold")
+        self.headtext = self.out.nofmt_printer("headtext", fg="yellow")
+        self.redtext = self.out.printer("redtext", fg="red")
+        self.sha = self.out.printer("sha", fg="yellow")
+        self.text = self.out.nofmt_printer("text")
+        self.dimtext = self.out.printer("dimtext", attr="dim")
 
-  def Execute(self, opt, args):
-    self.out = _Coloring(self.manifest.globalConfig)
-    self.heading = self.out.printer('heading', attr = 'bold')
-    self.headtext = self.out.nofmt_printer('headtext', fg = 'yellow')
-    self.redtext = self.out.printer('redtext', fg = 'red')
-    self.sha = self.out.printer("sha", fg = 'yellow')
-    self.text = self.out.nofmt_printer('text')
-    self.dimtext = self.out.printer('dimtext', attr = 'dim')
+        self.opt = opt
 
-    self.opt = opt
+        if not opt.this_manifest_only:
+            self.manifest = self.manifest.outer_client
+        manifestConfig = self.manifest.manifestProject.config
+        mergeBranch = manifestConfig.GetBranch("default").merge
+        manifestGroups = self.manifest.GetGroupsStr()
 
-    manifestConfig = self.manifest.manifestProject.config
-    mergeBranch = manifestConfig.GetBranch("default").merge
-    manifestGroups = (manifestConfig.GetString('manifest.groups')
-                      or 'all,-notdefault')
+        self.heading("Manifest branch: ")
+        if self.manifest.default.revisionExpr:
+            self.headtext(self.manifest.default.revisionExpr)
+        self.out.nl()
+        self.heading("Manifest merge branch: ")
+        # The manifest might not have a merge branch if it isn't in a git repo,
+        # e.g. if `repo init --standalone-manifest` is used.
+        self.headtext(mergeBranch or "")
+        self.out.nl()
+        self.heading("Manifest groups: ")
+        self.headtext(manifestGroups)
+        self.out.nl()
+        sp = self.manifest.superproject
+        srev = sp.commit_id if sp and sp.commit_id else "None"
+        self.heading("Superproject revision: ")
+        self.headtext(srev)
 
-    self.heading("Manifest branch: ")
-    if self.manifest.default.revisionExpr:
-        self.headtext(self.manifest.default.revisionExpr)
-    self.out.nl()
-    self.heading("Manifest merge branch: ")
-    self.headtext(mergeBranch)
-    self.out.nl()
-    self.heading("Manifest groups: ")
-    self.headtext(manifestGroups)
-    self.out.nl()
+        self.printSeparator()
 
-    self.printSeparator()
+        if not opt.overview:
+            self._printDiffInfo(opt, args)
+        else:
+            self._printCommitOverview(opt, args)
 
-    if not opt.overview:
-      self.printDiffInfo(args)
-    else:
-      self.printCommitOverview(args)
-
-  def printSeparator(self):
-    self.text("----------------------------")
-    self.out.nl()
-
-  def printDiffInfo(self, args):
-    # We let exceptions bubble up to main as they'll be well structured.
-    projs = self.GetProjects(args)
-
-    for p in projs:
-      self.heading("Project: ")
-      self.headtext(p.name)
-      self.out.nl()
-
-      self.heading("Mount path: ")
-      self.headtext(p.worktree)
-      self.out.nl()
-
-      self.heading("Current revision: ")
-      self.headtext(p.GetRevisionId())
-      self.out.nl()
-
-      currentBranch = p.CurrentBranch
-      if currentBranch:
-        self.heading('Current branch: ')
-        self.headtext(currentBranch)
+    def printSeparator(self):
+        self.text("----------------------------")
         self.out.nl()
 
-      self.heading("Manifest revision: ")
-      self.headtext(p.revisionExpr)
-      self.out.nl()
+    def _printDiffInfo(self, opt, args):
+        # We let exceptions bubble up to main as they'll be well structured.
+        projs = self.GetProjects(args, all_manifests=not opt.this_manifest_only)
 
-      localBranches = list(p.GetBranches().keys())
-      self.heading("Local Branches: ")
-      self.redtext(str(len(localBranches)))
-      if localBranches:
-        self.text(" [")
-        self.text(", ".join(localBranches))
-        self.text("]")
-      self.out.nl()
+        for p in projs:
+            self.heading("Project: ")
+            self.headtext(p.name)
+            self.out.nl()
 
-      if self.opt.all:
-        self.findRemoteLocalDiff(p)
+            self.heading("Mount path: ")
+            self.headtext(p.worktree)
+            self.out.nl()
 
-      self.printSeparator()
+            self.heading("Current revision: ")
+            self.headtext(p.GetRevisionId())
+            self.out.nl()
 
-  def findRemoteLocalDiff(self, project):
-    #Fetch all the latest commits
-    if not self.opt.local:
-      project.Sync_NetworkHalf(quiet=True, current_branch_only=True)
+            currentBranch = p.CurrentBranch
+            if currentBranch:
+                self.heading("Current branch: ")
+                self.headtext(currentBranch)
+                self.out.nl()
 
-    logTarget = R_M + self.manifest.manifestProject.config.GetBranch("default").merge
+            self.heading("Manifest revision: ")
+            self.headtext(p.revisionExpr)
+            self.out.nl()
 
-    bareTmp = project.bare_git._bare
-    project.bare_git._bare = False
-    localCommits = project.bare_git.rev_list(
-        '--abbrev=8',
-        '--abbrev-commit',
-        '--pretty=oneline',
-        logTarget + "..",
-        '--')
+            localBranches = list(p.GetBranches().keys())
+            self.heading("Local Branches: ")
+            self.redtext(str(len(localBranches)))
+            if localBranches:
+                self.text(" [")
+                self.text(", ".join(localBranches))
+                self.text("]")
+            self.out.nl()
 
-    originCommits = project.bare_git.rev_list(
-        '--abbrev=8',
-        '--abbrev-commit',
-        '--pretty=oneline',
-        ".." + logTarget,
-        '--')
-    project.bare_git._bare = bareTmp
+            if self.opt.all:
+                self.findRemoteLocalDiff(p)
 
-    self.heading("Local Commits: ")
-    self.redtext(str(len(localCommits)))
-    self.dimtext(" (on current branch)")
-    self.out.nl()
+            self.printSeparator()
 
-    for c in localCommits:
-      split = c.split()
-      self.sha(split[0] + " ")
-      self.text(" ".join(split[1:]))
-      self.out.nl()
+    def findRemoteLocalDiff(self, project):
+        # Fetch all the latest commits.
+        if not self.opt.local:
+            project.Sync_NetworkHalf(quiet=True, current_branch_only=True)
 
-    self.printSeparator()
+        branch = self.manifest.manifestProject.config.GetBranch("default").merge
+        if branch.startswith(R_HEADS):
+            branch = branch[len(R_HEADS) :]
+        logTarget = R_M + branch
 
-    self.heading("Remote Commits: ")
-    self.redtext(str(len(originCommits)))
-    self.out.nl()
+        bareTmp = project.bare_git._bare
+        project.bare_git._bare = False
+        localCommits = project.bare_git.rev_list(
+            "--abbrev=8",
+            "--abbrev-commit",
+            "--pretty=oneline",
+            logTarget + "..",
+            "--",
+        )
 
-    for c in originCommits:
-      split = c.split()
-      self.sha(split[0] + " ")
-      self.text(" ".join(split[1:]))
-      self.out.nl()
+        originCommits = project.bare_git.rev_list(
+            "--abbrev=8",
+            "--abbrev-commit",
+            "--pretty=oneline",
+            ".." + logTarget,
+            "--",
+        )
+        project.bare_git._bare = bareTmp
 
-  def printCommitOverview(self, args):
-    all_branches = []
-    for project in self.GetProjects(args):
-      br = [project.GetUploadableBranch(x)
-            for x in project.GetBranches()]
-      br = [x for x in br if x]
-      if self.opt.current_branch:
-        br = [x for x in br if x.name == project.CurrentBranch]
-      all_branches.extend(br)
-
-    if not all_branches:
-      return
-
-    self.out.nl()
-    self.heading('Projects Overview')
-    project = None
-
-    for branch in all_branches:
-      if project != branch.project:
-        project = branch.project
-        self.out.nl()
-        self.headtext(project.relpath)
+        self.heading("Local Commits: ")
+        self.redtext(str(len(localCommits)))
+        self.dimtext(" (on current branch)")
         self.out.nl()
 
-      commits = branch.commits
-      date = branch.date
-      self.text('%s %-33s (%2d commit%s, %s)' % (
-        branch.name == project.CurrentBranch and '*' or ' ',
-        branch.name,
-        len(commits),
-        len(commits) != 1 and 's' or '',
-        date))
-      self.out.nl()
+        for c in localCommits:
+            split = c.split()
+            self.sha(split[0] + " ")
+            self.text(" ".join(split[1:]))
+            self.out.nl()
 
-      for commit in commits:
-        split = commit.split()
-        self.text('{0:38}{1} '.format('','-'))
-        self.sha(split[0] + " ")
-        self.text(" ".join(split[1:]))
+        self.printSeparator()
+
+        self.heading("Remote Commits: ")
+        self.redtext(str(len(originCommits)))
         self.out.nl()
+
+        for c in originCommits:
+            split = c.split()
+            self.sha(split[0] + " ")
+            self.text(" ".join(split[1:]))
+            self.out.nl()
+
+    def _printCommitOverview(self, opt, args):
+        all_branches = []
+        for project in self.GetProjects(
+            args, all_manifests=not opt.this_manifest_only
+        ):
+            br = [project.GetUploadableBranch(x) for x in project.GetBranches()]
+            br = [x for x in br if x]
+            if self.opt.current_branch:
+                br = [x for x in br if x.name == project.CurrentBranch]
+            all_branches.extend(br)
+
+        if not all_branches:
+            return
+
+        self.out.nl()
+        self.heading("Projects Overview")
+        project = None
+
+        for branch in all_branches:
+            if project != branch.project:
+                project = branch.project
+                self.out.nl()
+                self.headtext(project.RelPath(local=opt.this_manifest_only))
+                self.out.nl()
+
+            commits = branch.commits
+            date = branch.date
+            self.text(
+                "%s %-33s (%2d commit%s, %s)"
+                % (
+                    branch.name == project.CurrentBranch and "*" or " ",
+                    branch.name,
+                    len(commits),
+                    len(commits) != 1 and "s" or "",
+                    date,
+                )
+            )
+            self.out.nl()
+
+            for commit in commits:
+                split = commit.split()
+                self.text(f"{'':38}{'-'} ")
+                self.sha(split[0] + " ")
+                self.text(" ".join(split[1:]))
+                self.out.nl()

subcmds/init.py

@@ -1,5 +1,3 @@
-# -*- coding:utf-8 -*-
-#
 # Copyright (C) 2008 The Android Open Source Project
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -14,48 +12,60 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-from __future__ import print_function
 import os
-import platform
-import re
 import sys
 
-from pyversion import is_python3
-if is_python3():
-  import urllib.parse
-else:
-  import imp
-  import urlparse
-  urllib = imp.new_module('urllib')
-  urllib.parse = urlparse
-
 from color import Coloring
-from command import InteractiveCommand, MirrorSafeCommand
-from error import ManifestParseError
-from project import SyncBuffer
-from git_config import GitConfig
-from git_command import git_require, MIN_GIT_VERSION
-import platform_utils
+from command import InteractiveCommand
+from command import MirrorSafeCommand
+from error import RepoUnhandledExceptionError
+from error import UpdateManifestError
+from git_command import git_require
+from repo_logging import RepoLogger
+from wrapper import Wrapper
+from wrapper import WrapperDir
+
+
+logger = RepoLogger(__file__)
+
+_REPO_ALLOW_SHALLOW = os.environ.get("REPO_ALLOW_SHALLOW")
+
 
 class Init(InteractiveCommand, MirrorSafeCommand):
-  common = True
-  helpSummary = "Initialize repo in the current directory"
-  helpUsage = """
-%prog [options]
+    COMMON = True
+    MULTI_MANIFEST_SUPPORT = True
+    helpSummary = "Initialize a repo client checkout in the current directory"
+    helpUsage = """
+%prog [options] [manifest url]
 """
-  helpDescription = """
+    helpDescription = """
 The '%prog' command is run once to install and initialize repo.
 The latest repo source code and manifest collection is downloaded
 from the server and is installed in the .repo/ directory in the
 current working directory.
 
+When creating a new checkout, the manifest URL is the only required setting.
+It may be specified using the --manifest-url option, or as the first optional
+argument.
+
 The optional -b argument can be used to select the manifest branch
-to checkout and use.  If no branch is specified, master is assumed.
+to checkout and use.  If no branch is specified, the remote's default
+branch is used.  This is equivalent to using -b HEAD.
+
+The optional --manifest-upstream-branch argument can be used when a commit is
+provided to --manifest-branch (or -b), to specify the name of the git ref in
+which the commit can be found.
 
 The optional -m argument can be used to specify an alternate manifest
 to be used. If no manifest is specified, the manifest default.xml
 will be used.
 
+If the --standalone-manifest argument is set, the manifest will be downloaded
+directly from the specified --manifest-url as a static file (rather than
+setting up a manifest git checkout). With --standalone-manifest, the manifest
+will be fully static and will not be re-downloaded during subsesquent
+`repo init` and `repo sync` calls.
+
 The --reference option can be used to point to a directory that
 has the content of a --mirror sync. This will make the working
 directory use as much data as possible from the local reference
@@ -81,384 +91,320 @@ manifest, a subsequent `repo sync` (or `repo sync -d`) is necessary
 to update the working directory files.
 """
 
-  def _Options(self, p, gitc_init=False):
-    # Logging
-    g = p.add_option_group('Logging options')
-    g.add_option('-q', '--quiet',
-                 dest="quiet", action="store_true", default=False,
-                 help="be quiet")
+    def _CommonOptions(self, p):
+        """Disable due to re-use of Wrapper()."""
 
-    # Manifest
-    g = p.add_option_group('Manifest options')
-    g.add_option('-u', '--manifest-url',
-                 dest='manifest_url',
-                 help='manifest repository location', metavar='URL')
-    g.add_option('-b', '--manifest-branch',
-                 dest='manifest_branch',
-                 help='manifest branch or revision', metavar='REVISION')
-    cbr_opts = ['--current-branch']
-    # The gitc-init subcommand allocates -c itself, but a lot of init users
-    # want -c, so try to satisfy both as best we can.
-    if not gitc_init:
-      cbr_opts += ['-c']
-    g.add_option(*cbr_opts,
-                 dest='current_branch_only', action='store_true',
-                 help='fetch only current manifest branch from server')
-    g.add_option('-m', '--manifest-name',
-                 dest='manifest_name', default='default.xml',
-                 help='initial manifest file', metavar='NAME.xml')
-    g.add_option('--mirror',
-                 dest='mirror', action='store_true',
-                 help='create a replica of the remote repositories '
-                      'rather than a client working directory')
-    g.add_option('--reference',
-                 dest='reference',
-                 help='location of mirror directory', metavar='DIR')
-    g.add_option('--dissociate',
-                 dest='dissociate', action='store_true',
-                 help='dissociate from reference mirrors after clone')
-    g.add_option('--depth', type='int', default=None,
-                 dest='depth',
-                 help='create a shallow clone with given depth; see git clone')
-    g.add_option('--partial-clone', action='store_true',
-                 dest='partial_clone',
-                 help='perform partial clone (https://git-scm.com/'
-                 'docs/gitrepository-layout#_code_partialclone_code)')
-    g.add_option('--clone-filter', action='store', default='blob:none',
-                 dest='clone_filter',
-                 help='filter for use with --partial-clone [default: %default]')
-    g.add_option('--archive',
-                 dest='archive', action='store_true',
-                 help='checkout an archive instead of a git repository for '
-                      'each project. See git archive.')
-    g.add_option('--submodules',
-                 dest='submodules', action='store_true',
-                 help='sync any submodules associated with the manifest repo')
-    g.add_option('-g', '--groups',
-                 dest='groups', default='default',
-                 help='restrict manifest projects to ones with specified '
-                      'group(s) [default|all|G1,G2,G3|G4,-G5,-G6]',
-                 metavar='GROUP')
-    g.add_option('-p', '--platform',
-                 dest='platform', default='auto',
-                 help='restrict manifest projects to ones with a specified '
-                      'platform group [auto|all|none|linux|darwin|...]',
-                 metavar='PLATFORM')
-    g.add_option('--no-clone-bundle',
-                 dest='no_clone_bundle', action='store_true',
-                 help='disable use of /clone.bundle on HTTP/HTTPS')
-    g.add_option('--no-tags',
-                 dest='no_tags', action='store_true',
-                 help="don't fetch tags in the manifest")
+    def _Options(self, p):
+        Wrapper().InitParser(p)
+        m = p.add_option_group("Multi-manifest")
+        m.add_option(
+            "--outer-manifest",
+            action="store_true",
+            default=True,
+            help="operate starting at the outermost manifest",
+        )
+        m.add_option(
+            "--no-outer-manifest",
+            dest="outer_manifest",
+            action="store_false",
+            help="do not operate on outer manifests",
+        )
+        m.add_option(
+            "--this-manifest-only",
+            action="store_true",
+            default=None,
+            help="only operate on this (sub)manifest",
+        )
+        m.add_option(
+            "--no-this-manifest-only",
+            "--all-manifests",
+            dest="this_manifest_only",
+            action="store_false",
+            help="operate on this manifest and its submanifests",
+        )
 
-    # Tool
-    g = p.add_option_group('repo Version options')
-    g.add_option('--repo-url',
-                 dest='repo_url',
-                 help='repo repository location', metavar='URL')
-    g.add_option('--repo-branch',
-                 dest='repo_branch',
-                 help='repo branch or revision', metavar='REVISION')
-    g.add_option('--no-repo-verify',
-                 dest='no_repo_verify', action='store_true',
-                 help='do not verify repo source code')
+    def _RegisteredEnvironmentOptions(self):
+        return {
+            "REPO_MANIFEST_URL": "manifest_url",
+            "REPO_MIRROR_LOCATION": "reference",
+        }
 
-    # Other
-    g = p.add_option_group('Other options')
-    g.add_option('--config-name',
-                 dest='config_name', action="store_true", default=False,
-                 help='Always prompt for name/e-mail')
+    def _SyncManifest(self, opt):
+        """Call manifestProject.Sync with arguments from opt.
 
-  def _RegisteredEnvironmentOptions(self):
-    return {'REPO_MANIFEST_URL': 'manifest_url',
-            'REPO_MIRROR_LOCATION': 'reference'}
+        Args:
+            opt: options from optparse.
+        """
+        # Normally this value is set when instantiating the project, but the
+        # manifest project is special and is created when instantiating the
+        # manifest which happens before we parse options.
+        self.manifest.manifestProject.clone_depth = opt.manifest_depth
+        self.manifest.manifestProject.upstream = opt.manifest_upstream_branch
+        clone_filter_for_depth = (
+            "blob:none" if (_REPO_ALLOW_SHALLOW == "0") else None
+        )
+        if not self.manifest.manifestProject.Sync(
+            manifest_url=opt.manifest_url,
+            manifest_branch=opt.manifest_branch,
+            standalone_manifest=opt.standalone_manifest,
+            groups=opt.groups,
+            platform=opt.platform,
+            mirror=opt.mirror,
+            dissociate=opt.dissociate,
+            reference=opt.reference,
+            worktree=opt.worktree,
+            submodules=opt.submodules,
+            archive=opt.archive,
+            partial_clone=opt.partial_clone,
+            clone_filter=opt.clone_filter,
+            partial_clone_exclude=opt.partial_clone_exclude,
+            clone_filter_for_depth=clone_filter_for_depth,
+            clone_bundle=opt.clone_bundle,
+            git_lfs=opt.git_lfs,
+            use_superproject=opt.use_superproject,
+            verbose=opt.verbose,
+            current_branch_only=opt.current_branch_only,
+            tags=opt.tags,
+            depth=opt.depth,
+            git_event_log=self.git_event_log,
+            manifest_name=opt.manifest_name,
+        ):
+            manifest_name = opt.manifest_name
+            raise UpdateManifestError(
+                f"Unable to sync manifest {manifest_name}"
+            )
 
-  def _SyncManifest(self, opt):
-    m = self.manifest.manifestProject
-    is_new = not m.Exists
+    def _Prompt(self, prompt, value):
+        print("%-10s [%s]: " % (prompt, value), end="", flush=True)
+        a = sys.stdin.readline().strip()
+        if a == "":
+            return value
+        return a
 
-    if is_new:
-      if not opt.manifest_url:
-        print('fatal: manifest url (-u) is required.', file=sys.stderr)
-        sys.exit(1)
+    def _ShouldConfigureUser(self, opt, existing_checkout):
+        gc = self.client.globalConfig
+        mp = self.manifest.manifestProject
 
-      if not opt.quiet:
-        print('Get %s' % GitConfig.ForUser().UrlInsteadOf(opt.manifest_url),
-              file=sys.stderr)
+        # If we don't have local settings, get from global.
+        if not mp.config.Has("user.name") or not mp.config.Has("user.email"):
+            if not gc.Has("user.name") or not gc.Has("user.email"):
+                return True
 
-      # The manifest project object doesn't keep track of the path on the
-      # server where this git is located, so let's save that here.
-      mirrored_manifest_git = None
-      if opt.reference:
-        manifest_git_path = urllib.parse.urlparse(opt.manifest_url).path[1:]
-        mirrored_manifest_git = os.path.join(opt.reference, manifest_git_path)
-        if not mirrored_manifest_git.endswith(".git"):
-          mirrored_manifest_git += ".git"
-        if not os.path.exists(mirrored_manifest_git):
-          mirrored_manifest_git = os.path.join(opt.reference,
-                                               '.repo/manifests.git')
+            mp.config.SetString("user.name", gc.GetString("user.name"))
+            mp.config.SetString("user.email", gc.GetString("user.email"))
 
-      m._InitGitDir(mirror_git=mirrored_manifest_git)
+        if not opt.quiet and not existing_checkout or opt.verbose:
+            print()
+            print(
+                "Your identity is: %s <%s>"
+                % (
+                    mp.config.GetString("user.name"),
+                    mp.config.GetString("user.email"),
+                )
+            )
+            print(
+                "If you want to change this, please re-run 'repo init' with "
+                "--config-name"
+            )
+        return False
 
-      if opt.manifest_branch:
-        m.revisionExpr = opt.manifest_branch
-      else:
-        m.revisionExpr = 'refs/heads/master'
-    else:
-      if opt.manifest_branch:
-        m.revisionExpr = opt.manifest_branch
-      else:
-        m.PreSync()
+    def _ConfigureUser(self, opt):
+        mp = self.manifest.manifestProject
 
-    self._ConfigureDepth(opt)
+        while True:
+            if not opt.quiet:
+                print()
+            name = self._Prompt("Your Name", mp.UserName)
+            email = self._Prompt("Your Email", mp.UserEmail)
 
-    if opt.manifest_url:
-      r = m.GetRemote(m.remote.name)
-      r.url = opt.manifest_url
-      r.ResetFetch()
-      r.Save()
+            if not opt.quiet:
+                print()
+            print(f"Your identity is: {name} <{email}>")
+            print("is this correct [y/N]? ", end="", flush=True)
+            a = sys.stdin.readline().strip().lower()
+            if a in ("yes", "y", "t", "true"):
+                break
 
-    groups = re.split(r'[,\s]+', opt.groups)
-    all_platforms = ['linux', 'darwin', 'windows']
-    platformize = lambda x: 'platform-' + x
-    if opt.platform == 'auto':
-      if (not opt.mirror and
-          not m.config.GetString('repo.mirror') == 'true'):
-        groups.append(platformize(platform.system().lower()))
-    elif opt.platform == 'all':
-      groups.extend(map(platformize, all_platforms))
-    elif opt.platform in all_platforms:
-      groups.append(platformize(opt.platform))
-    elif opt.platform != 'none':
-      print('fatal: invalid platform flag', file=sys.stderr)
-      sys.exit(1)
+        if name != mp.UserName:
+            mp.config.SetString("user.name", name)
+        if email != mp.UserEmail:
+            mp.config.SetString("user.email", email)
 
-    groups = [x for x in groups if x]
-    groupstr = ','.join(groups)
-    if opt.platform == 'auto' and groupstr == 'default,platform-' + platform.system().lower():
-      groupstr = None
-    m.config.SetString('manifest.groups', groupstr)
+    def _HasColorSet(self, gc):
+        for n in ["ui", "diff", "status"]:
+            if gc.Has("color.%s" % n):
+                return True
+        return False
 
-    if opt.reference:
-      m.config.SetString('repo.reference', opt.reference)
+    def _ConfigureColor(self):
+        gc = self.client.globalConfig
+        if self._HasColorSet(gc):
+            return
 
-    if opt.dissociate:
-      m.config.SetString('repo.dissociate', 'true')
+        class _Test(Coloring):
+            def __init__(self):
+                Coloring.__init__(self, gc, "test color display")
+                self._on = True
 
-    if opt.archive:
-      if is_new:
-        m.config.SetString('repo.archive', 'true')
-      else:
-        print('fatal: --archive is only supported when initializing a new '
-              'workspace.', file=sys.stderr)
-        print('Either delete the .repo folder in this workspace, or initialize '
-              'in another location.', file=sys.stderr)
-        sys.exit(1)
+        out = _Test()
 
-    if opt.mirror:
-      if is_new:
-        m.config.SetString('repo.mirror', 'true')
-      else:
-        print('fatal: --mirror is only supported when initializing a new '
-              'workspace.', file=sys.stderr)
-        print('Either delete the .repo folder in this workspace, or initialize '
-              'in another location.', file=sys.stderr)
-        sys.exit(1)
+        print()
+        print("Testing colorized output (for 'repo diff', 'repo status'):")
 
-    if opt.partial_clone:
-      if opt.mirror:
-        print('fatal: --mirror and --partial-clone are mutually exclusive',
-              file=sys.stderr)
-        sys.exit(1)
-      m.config.SetString('repo.partialclone', 'true')
-      if opt.clone_filter:
-        m.config.SetString('repo.clonefilter', opt.clone_filter)
-    else:
-      opt.clone_filter = None
+        for c in ["black", "red", "green", "yellow", "blue", "magenta", "cyan"]:
+            out.write(" ")
+            out.printer(fg=c)(" %-6s ", c)
+        out.write(" ")
+        out.printer(fg="white", bg="black")(" %s " % "white")
+        out.nl()
 
-    if opt.submodules:
-      m.config.SetString('repo.submodules', 'true')
+        for c in ["bold", "dim", "ul", "reverse"]:
+            out.write(" ")
+            out.printer(fg="black", attr=c)(" %-6s ", c)
+        out.nl()
 
-    if not m.Sync_NetworkHalf(is_new=is_new, quiet=opt.quiet,
-        clone_bundle=not opt.no_clone_bundle,
-        current_branch_only=opt.current_branch_only,
-        no_tags=opt.no_tags, submodules=opt.submodules,
-        clone_filter=opt.clone_filter):
-      r = m.GetRemote(m.remote.name)
-      print('fatal: cannot obtain manifest %s' % r.url, file=sys.stderr)
+        print(
+            "Enable color display in this user account (y/N)? ",
+            end="",
+            flush=True,
+        )
+        a = sys.stdin.readline().strip().lower()
+        if a in ("y", "yes", "t", "true", "on"):
+            gc.SetString("color.ui", "auto")
 
-      # Better delete the manifest git dir if we created it; otherwise next
-      # time (when user fixes problems) we won't go through the "is_new" logic.
-      if is_new:
-        platform_utils.rmtree(m.gitdir)
-      sys.exit(1)
+    def _DisplayResult(self):
+        if self.manifest.IsMirror:
+            init_type = "mirror "
+        else:
+            init_type = ""
 
-    if opt.manifest_branch:
-      m.MetaBranchSwitch(submodules=opt.submodules)
+        print()
+        print(
+            "repo %shas been initialized in %s"
+            % (init_type, self.manifest.topdir)
+        )
 
-    syncbuf = SyncBuffer(m.config)
-    m.Sync_LocalHalf(syncbuf, submodules=opt.submodules)
-    syncbuf.Finish()
+        current_dir = os.getcwd()
+        if current_dir != self.manifest.topdir:
+            print(
+                "If this is not the directory in which you want to initialize "
+                "repo, please run:"
+            )
+            print("   rm -r %s" % os.path.join(self.manifest.topdir, ".repo"))
+            print("and try again.")
 
-    if is_new or m.CurrentBranch is None:
-      if not m.StartBranch('default'):
-        print('fatal: cannot create default in manifest', file=sys.stderr)
-        sys.exit(1)
+    def ValidateOptions(self, opt, args):
+        if opt.reference:
+            opt.reference = os.path.expanduser(opt.reference)
 
-  def _LinkManifest(self, name):
-    if not name:
-      print('fatal: manifest name (-m) is required.', file=sys.stderr)
-      sys.exit(1)
+        # Check this here, else manifest will be tagged "not new" and init won't
+        # be possible anymore without removing the .repo/manifests directory.
+        if opt.mirror:
+            if opt.archive:
+                self.OptionParser.error(
+                    "--mirror and --archive cannot be used " "together."
+                )
+            if opt.use_superproject is not None:
+                self.OptionParser.error(
+                    "--mirror and --use-superproject cannot be "
+                    "used together."
+                )
+        if opt.archive and opt.use_superproject is not None:
+            self.OptionParser.error(
+                "--archive and --use-superproject cannot be used " "together."
+            )
 
-    try:
-      self.manifest.Link(name)
-    except ManifestParseError as e:
-      print("fatal: manifest '%s' not available" % name, file=sys.stderr)
-      print('fatal: %s' % str(e), file=sys.stderr)
-      sys.exit(1)
+        if opt.standalone_manifest and (
+            opt.manifest_branch or opt.manifest_name != "default.xml"
+        ):
+            self.OptionParser.error(
+                "--manifest-branch and --manifest-name cannot"
+                " be used with --standalone-manifest."
+            )
 
-  def _Prompt(self, prompt, value):
-    print('%-10s [%s]: ' % (prompt, value), end='')
-    # TODO: When we require Python 3, use flush=True w/print above.
-    sys.stdout.flush()
-    a = sys.stdin.readline().strip()
-    if a == '':
-      return value
-    return a
+        if opt.manifest_upstream_branch and opt.manifest_branch is None:
+            self.OptionParser.error(
+                "--manifest-upstream-branch cannot be used without "
+                "--manifest-branch."
+            )
 
-  def _ShouldConfigureUser(self):
-    gc = self.manifest.globalConfig
-    mp = self.manifest.manifestProject
+        if args:
+            if opt.manifest_url:
+                self.OptionParser.error(
+                    "--manifest-url option and URL argument both specified: "
+                    "only use one to select the manifest URL."
+                )
 
-    # If we don't have local settings, get from global.
-    if not mp.config.Has('user.name') or not mp.config.Has('user.email'):
-      if not gc.Has('user.name') or not gc.Has('user.email'):
-        return True
+            opt.manifest_url = args.pop(0)
 
-      mp.config.SetString('user.name', gc.GetString('user.name'))
-      mp.config.SetString('user.email', gc.GetString('user.email'))
+            if args:
+                self.OptionParser.error("too many arguments to init")
 
-    print()
-    print('Your identity is: %s <%s>' % (mp.config.GetString('user.name'),
-                                         mp.config.GetString('user.email')))
-    print('If you want to change this, please re-run \'repo init\' with --config-name')
-    return False
+    def Execute(self, opt, args):
+        wrapper = Wrapper()
 
-  def _ConfigureUser(self):
-    mp = self.manifest.manifestProject
+        reqs = wrapper.Requirements.from_dir(WrapperDir())
+        git_require(reqs.get_hard_ver("git"), fail=True)
+        min_git_version_soft = reqs.get_soft_ver("git")
+        if not git_require(min_git_version_soft):
+            logger.warning(
+                "repo: warning: git-%s+ will soon be required; "
+                "please upgrade your version of git to maintain "
+                "support.",
+                ".".join(str(x) for x in min_git_version_soft),
+            )
 
-    while True:
-      print()
-      name  = self._Prompt('Your Name', mp.UserName)
-      email = self._Prompt('Your Email', mp.UserEmail)
+        rp = self.manifest.repoProject
 
-      print()
-      print('Your identity is: %s <%s>' % (name, email))
-      print('is this correct [y/N]? ', end='')
-      # TODO: When we require Python 3, use flush=True w/print above.
-      sys.stdout.flush()
-      a = sys.stdin.readline().strip().lower()
-      if a in ('yes', 'y', 't', 'true'):
-        break
+        # Handle new --repo-url requests.
+        if opt.repo_url:
+            remote = rp.GetRemote("origin")
+            remote.url = opt.repo_url
+            remote.Save()
 
-    if name != mp.UserName:
-      mp.config.SetString('user.name', name)
-    if email != mp.UserEmail:
-      mp.config.SetString('user.email', email)
+        # Handle new --repo-rev requests.
+        if opt.repo_rev:
+            try:
+                remote_ref, rev = wrapper.check_repo_rev(
+                    rp.worktree,
+                    opt.repo_rev,
+                    repo_verify=opt.repo_verify,
+                    quiet=opt.quiet,
+                )
+            except wrapper.CloneFailure as e:
+                err_msg = "fatal: double check your --repo-rev setting."
+                logger.error(err_msg)
+                self.git_event_log.ErrorEvent(err_msg)
+                raise RepoUnhandledExceptionError(e)
 
-  def _HasColorSet(self, gc):
-    for n in ['ui', 'diff', 'status']:
-      if gc.Has('color.%s' % n):
-        return True
-    return False
+            branch = rp.GetBranch("default")
+            branch.merge = remote_ref
+            rp.work_git.reset("--hard", rev)
+            branch.Save()
 
-  def _ConfigureColor(self):
-    gc = self.manifest.globalConfig
-    if self._HasColorSet(gc):
-      return
+        if opt.worktree:
+            # Older versions of git supported worktree, but had dangerous gc
+            # bugs.
+            git_require((2, 15, 0), fail=True, msg="git gc worktree corruption")
 
-    class _Test(Coloring):
-      def __init__(self):
-        Coloring.__init__(self, gc, 'test color display')
-        self._on = True
-    out = _Test()
+        # Provide a short notice that we're reinitializing an existing checkout.
+        # Sometimes developers might not realize that they're in one, or that
+        # repo doesn't do nested checkouts.
+        existing_checkout = self.manifest.manifestProject.Exists
+        if not opt.quiet and existing_checkout:
+            print(
+                "repo: reusing existing repo client checkout in",
+                self.manifest.topdir,
+            )
 
-    print()
-    print("Testing colorized output (for 'repo diff', 'repo status'):")
+        self._SyncManifest(opt)
 
-    for c in ['black', 'red', 'green', 'yellow', 'blue', 'magenta', 'cyan']:
-      out.write(' ')
-      out.printer(fg=c)(' %-6s ', c)
-    out.write(' ')
-    out.printer(fg='white', bg='black')(' %s ' % 'white')
-    out.nl()
+        if os.isatty(0) and os.isatty(1) and not self.manifest.IsMirror:
+            if opt.config_name or self._ShouldConfigureUser(
+                opt, existing_checkout
+            ):
+                self._ConfigureUser(opt)
+            self._ConfigureColor()
 
-    for c in ['bold', 'dim', 'ul', 'reverse']:
-      out.write(' ')
-      out.printer(fg='black', attr=c)(' %-6s ', c)
-    out.nl()
-
-    print('Enable color display in this user account (y/N)? ', end='')
-    # TODO: When we require Python 3, use flush=True w/print above.
-    sys.stdout.flush()
-    a = sys.stdin.readline().strip().lower()
-    if a in ('y', 'yes', 't', 'true', 'on'):
-      gc.SetString('color.ui', 'auto')
-
-  def _ConfigureDepth(self, opt):
-    """Configure the depth we'll sync down.
-
-    Args:
-      opt: Options from optparse.  We care about opt.depth.
-    """
-    # Opt.depth will be non-None if user actually passed --depth to repo init.
-    if opt.depth is not None:
-      if opt.depth > 0:
-        # Positive values will set the depth.
-        depth = str(opt.depth)
-      else:
-        # Negative numbers will clear the depth; passing None to SetString
-        # will do that.
-        depth = None
-
-      # We store the depth in the main manifest project.
-      self.manifest.manifestProject.config.SetString('repo.depth', depth)
-
-  def _DisplayResult(self):
-    if self.manifest.IsMirror:
-      init_type = 'mirror '
-    else:
-      init_type = ''
-
-    print()
-    print('repo %shas been initialized in %s'
-          % (init_type, self.manifest.topdir))
-
-    current_dir = os.getcwd()
-    if current_dir != self.manifest.topdir:
-      print('If this is not the directory in which you want to initialize '
-            'repo, please run:')
-      print('   rm -r %s/.repo' % self.manifest.topdir)
-      print('and try again.')
-
-  def ValidateOptions(self, opt, args):
-    if opt.reference:
-      opt.reference = os.path.expanduser(opt.reference)
-
-    # Check this here, else manifest will be tagged "not new" and init won't be
-    # possible anymore without removing the .repo/manifests directory.
-    if opt.archive and opt.mirror:
-      self.OptionParser.error('--mirror and --archive cannot be used together.')
-
-  def Execute(self, opt, args):
-    git_require(MIN_GIT_VERSION, fail=True)
-
-    self._SyncManifest(opt)
-    self._LinkManifest(opt.manifest_name)
-
-    if os.isatty(0) and os.isatty(1) and not self.manifest.IsMirror:
-      if opt.config_name or self._ShouldConfigureUser():
-        self._ConfigureUser()
-      self._ConfigureColor()
-
-    self._DisplayResult()
+        if not opt.quiet:
+            self._DisplayResult()

subcmds/list.py

@@ -1,5 +1,3 @@
-# -*- coding:utf-8 -*-
-#
 # Copyright (C) 2011 The Android Open Source Project
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -14,74 +12,122 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-from __future__ import print_function
-import sys
+import os
+
+from command import Command
+from command import MirrorSafeCommand
 
-from command import Command, MirrorSafeCommand
 
 class List(Command, MirrorSafeCommand):
-  common = True
-  helpSummary = "List projects and their associated directories"
-  helpUsage = """
+    COMMON = True
+    helpSummary = "List projects and their associated directories"
+    helpUsage = """
 %prog [-f] [<project>...]
-%prog [-f] -r str1 [str2]..."
+%prog [-f] -r str1 [str2]...
 """
-  helpDescription = """
+    helpDescription = """
 List all projects; pass '.' to list the project for the cwd.
 
+By default, only projects that currently exist in the checkout are shown.  If
+you want to list all projects (using the specified filter settings), use the
+--all option.  If you want to show all projects regardless of the manifest
+groups, then also pass --groups all.
+
 This is similar to running: repo forall -c 'echo "$REPO_PATH : $REPO_PROJECT"'.
 """
 
-  def _Options(self, p):
-    p.add_option('-r', '--regex',
-                 dest='regex', action='store_true',
-                 help="Filter the project list based on regex or wildcard matching of strings")
-    p.add_option('-g', '--groups',
-                 dest='groups',
-                 help="Filter the project list based on the groups the project is in")
-    p.add_option('-f', '--fullpath',
-                 dest='fullpath', action='store_true',
-                 help="Display the full work tree path instead of the relative path")
-    p.add_option('-n', '--name-only',
-                 dest='name_only', action='store_true',
-                 help="Display only the name of the repository")
-    p.add_option('-p', '--path-only',
-                 dest='path_only', action='store_true',
-                 help="Display only the path of the repository")
+    def _Options(self, p):
+        p.add_option(
+            "-r",
+            "--regex",
+            action="store_true",
+            help="filter the project list based on regex or wildcard matching "
+            "of strings",
+        )
+        p.add_option(
+            "-g",
+            "--groups",
+            help="filter the project list based on the groups the project is "
+            "in",
+        )
+        p.add_option(
+            "-a",
+            "--all",
+            action="store_true",
+            help="show projects regardless of checkout state",
+        )
+        p.add_option(
+            "-n",
+            "--name-only",
+            action="store_true",
+            help="display only the name of the repository",
+        )
+        p.add_option(
+            "-p",
+            "--path-only",
+            action="store_true",
+            help="display only the path of the repository",
+        )
+        p.add_option(
+            "-f",
+            "--fullpath",
+            action="store_true",
+            help="display the full work tree path instead of the relative path",
+        )
+        p.add_option(
+            "--relative-to",
+            metavar="PATH",
+            help="display paths relative to this one (default: top of repo "
+            "client checkout)",
+        )
 
-  def ValidateOptions(self, opt, args):
-    if opt.fullpath and opt.name_only:
-      self.OptionParser.error('cannot combine -f and -n')
+    def ValidateOptions(self, opt, args):
+        if opt.fullpath and opt.name_only:
+            self.OptionParser.error("cannot combine -f and -n")
 
-  def Execute(self, opt, args):
-    """List all projects and the associated directories.
+        # Resolve any symlinks so the output is stable.
+        if opt.relative_to:
+            opt.relative_to = os.path.realpath(opt.relative_to)
 
-    This may be possible to do with 'repo forall', but repo newbies have
-    trouble figuring that out.  The idea here is that it should be more
-    discoverable.
+    def Execute(self, opt, args):
+        """List all projects and the associated directories.
 
-    Args:
-      opt: The options.
-      args: Positional args.  Can be a list of projects to list, or empty.
-    """
-    if not opt.regex:
-      projects = self.GetProjects(args, groups=opt.groups)
-    else:
-      projects = self.FindProjects(args)
+        This may be possible to do with 'repo forall', but repo newbies have
+        trouble figuring that out.  The idea here is that it should be more
+        discoverable.
 
-    def _getpath(x):
-      if opt.fullpath:
-        return x.worktree
-      return x.relpath
+        Args:
+            opt: The options.
+            args: Positional args.  Can be a list of projects to list, or empty.
+        """
+        if not opt.regex:
+            projects = self.GetProjects(
+                args,
+                groups=opt.groups,
+                missing_ok=opt.all,
+                all_manifests=not opt.this_manifest_only,
+            )
+        else:
+            projects = self.FindProjects(
+                args, all_manifests=not opt.this_manifest_only
+            )
 
-    lines = []
-    for project in projects:
-      if opt.name_only and not opt.path_only:
-        lines.append("%s" % ( project.name))
-      elif opt.path_only and not opt.name_only:
-        lines.append("%s" % (_getpath(project)))
-      else:
-        lines.append("%s : %s" % (_getpath(project), project.name))
+        def _getpath(x):
+            if opt.fullpath:
+                return x.worktree
+            if opt.relative_to:
+                return os.path.relpath(x.worktree, opt.relative_to)
+            return x.RelPath(local=opt.this_manifest_only)
 
-    lines.sort()
-    print('\n'.join(lines))
+        lines = []
+        for project in projects:
+            if opt.name_only and not opt.path_only:
+                lines.append("%s" % (project.name))
+            elif opt.path_only and not opt.name_only:
+                lines.append("%s" % (_getpath(project)))
+            else:
+                lines.append(f"{_getpath(project)} : {project.name}")
+
+        if lines:
+            lines.sort()
+            print("\n".join(lines))

subcmds/manifest.py

@@ -1,5 +1,3 @@
-# -*- coding:utf-8 -*-
-#
 # Copyright (C) 2009 The Android Open Source Project
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -14,67 +12,194 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-from __future__ import print_function
+import enum
+import json
+import optparse
 import os
 import sys
 
 from command import PagedCommand
+from repo_logging import RepoLogger
+
+
+logger = RepoLogger(__file__)
+
+
+class OutputFormat(enum.Enum):
+    """Type for the requested output format."""
+
+    # Canonicalized manifest in XML format.
+    XML = enum.auto()
+
+    # Canonicalized manifest in JSON format.
+    JSON = enum.auto()
+
 
 class Manifest(PagedCommand):
-  common = False
-  helpSummary = "Manifest inspection utility"
-  helpUsage = """
-%prog [-o {-|NAME.xml} [-r]]
+    COMMON = False
+    helpSummary = "Manifest inspection utility"
+    helpUsage = """
+%prog [-o {-|NAME.xml}] [-m MANIFEST.xml] [-r]
 """
-  _helpDescription = """
+    _helpDescription = """
 
 With the -o option, exports the current manifest for inspection.
-The manifest and (if present) local_manifest.xml are combined
+The manifest and (if present) local_manifests/ are combined
 together to produce a single manifest file.  This file can be stored
 in a Git repository for use during future 'repo init' invocations.
 
+The -r option can be used to generate a manifest file with project
+revisions set to the current commit hash.  These are known as
+"revision locked manifests", as they don't follow a particular branch.
+In this case, the 'upstream' attribute is set to the ref we were on
+when the manifest was generated.  The 'dest-branch' attribute is set
+to indicate the remote ref to push changes to via 'repo upload'.
+
+Multiple output formats are supported via --format.  The default output
+is XML, and formats are generally "condensed".  Use --pretty for more
+human-readable variations.
 """
 
-  @property
-  def helpDescription(self):
-    helptext = self._helpDescription + '\n'
-    r = os.path.dirname(__file__)
-    r = os.path.dirname(r)
-    with open(os.path.join(r, 'docs', 'manifest-format.md')) as fd:
-      for line in fd:
-        helptext += line
-    return helptext
+    @property
+    def helpDescription(self):
+        helptext = self._helpDescription + "\n"
+        r = os.path.dirname(__file__)
+        r = os.path.dirname(r)
+        with open(os.path.join(r, "docs", "manifest-format.md")) as fd:
+            for line in fd:
+                helptext += line
+        return helptext
 
-  def _Options(self, p):
-    p.add_option('-r', '--revision-as-HEAD',
-                 dest='peg_rev', action='store_true',
-                 help='Save revisions as current HEAD')
-    p.add_option('--suppress-upstream-revision', dest='peg_rev_upstream',
-                 default=True, action='store_false',
-                 help='If in -r mode, do not write the upstream field.  '
-                 'Only of use if the branch names for a sha1 manifest are '
-                 'sensitive.')
-    p.add_option('-o', '--output-file',
-                 dest='output_file',
-                 default='-',
-                 help='File to save the manifest to',
-                 metavar='-|NAME.xml')
+    def _Options(self, p):
+        p.add_option(
+            "-r",
+            "--revision-as-HEAD",
+            dest="peg_rev",
+            action="store_true",
+            help="save revisions as current HEAD",
+        )
+        p.add_option(
+            "-m",
+            "--manifest-name",
+            help="temporary manifest to use for this sync",
+            metavar="NAME.xml",
+        )
+        p.add_option(
+            "--suppress-upstream-revision",
+            dest="peg_rev_upstream",
+            default=True,
+            action="store_false",
+            help="if in -r mode, do not write the upstream field "
+            "(only of use if the branch names for a sha1 manifest are "
+            "sensitive)",
+        )
+        p.add_option(
+            "--suppress-dest-branch",
+            dest="peg_rev_dest_branch",
+            default=True,
+            action="store_false",
+            help="if in -r mode, do not write the dest-branch field "
+            "(only of use if the branch names for a sha1 manifest are "
+            "sensitive)",
+        )
+        # Replaced with --format=json.  Kept for backwards compatibility.
+        # Can delete in Jun 2026 or later.
+        p.add_option(
+            "--json",
+            action="store_const",
+            dest="format",
+            const=OutputFormat.JSON.name.lower(),
+            help=optparse.SUPPRESS_HELP,
+        )
+        formats = tuple(x.lower() for x in OutputFormat.__members__.keys())
+        p.add_option(
+            "--format",
+            default=OutputFormat.XML.name.lower(),
+            choices=formats,
+            help=f"output format: {', '.join(formats)} (default: %default)",
+        )
+        p.add_option(
+            "--pretty",
+            default=False,
+            action="store_true",
+            help="format output for humans to read",
+        )
+        p.add_option(
+            "--no-local-manifests",
+            default=False,
+            action="store_true",
+            dest="ignore_local_manifests",
+            help="ignore local manifests",
+        )
+        p.add_option(
+            "-o",
+            "--output-file",
+            default="-",
+            help="file to save the manifest to. (Filename prefix for "
+            "multi-tree.)",
+            metavar="-|NAME.xml",
+        )
 
-  def _Output(self, opt):
-    if opt.output_file == '-':
-      fd = sys.stdout
-    else:
-      fd = open(opt.output_file, 'w')
-    self.manifest.Save(fd,
-                       peg_rev = opt.peg_rev,
-                       peg_rev_upstream = opt.peg_rev_upstream)
-    fd.close()
-    if opt.output_file != '-':
-      print('Saved manifest to %s' % opt.output_file, file=sys.stderr)
+    def _Output(self, opt):
+        # If alternate manifest is specified, override the manifest file that
+        # we're using.
+        if opt.manifest_name:
+            self.manifest.Override(opt.manifest_name, False)
 
-  def ValidateOptions(self, opt, args):
-    if args:
-      self.Usage()
+        output_format = OutputFormat[opt.format.upper()]
 
-  def Execute(self, opt, args):
-    self._Output(opt)
+        for manifest in self.ManifestList(opt):
+            output_file = opt.output_file
+            if output_file == "-":
+                fd = sys.stdout
+            else:
+                if manifest.path_prefix:
+                    output_file = (
+                        f"{opt.output_file}:"
+                        f'{manifest.path_prefix.replace("/", "%2f")}'
+                    )
+                fd = open(output_file, "w")
+
+            manifest.SetUseLocalManifests(not opt.ignore_local_manifests)
+
+            if output_format == OutputFormat.JSON:
+                doc = manifest.ToDict(
+                    peg_rev=opt.peg_rev,
+                    peg_rev_upstream=opt.peg_rev_upstream,
+                    peg_rev_dest_branch=opt.peg_rev_dest_branch,
+                )
+
+                json_settings = {
+                    # JSON style guide says Unicode characters are fully
+                    # allowed.
+                    "ensure_ascii": False,
+                    # We use 2 space indent to match JSON style guide.
+                    "indent": 2 if opt.pretty else None,
+                    "separators": (",", ": ") if opt.pretty else (",", ":"),
+                    "sort_keys": True,
+                }
+                fd.write(json.dumps(doc, **json_settings) + "\n")
+            else:
+                manifest.Save(
+                    fd,
+                    peg_rev=opt.peg_rev,
+                    peg_rev_upstream=opt.peg_rev_upstream,
+                    peg_rev_dest_branch=opt.peg_rev_dest_branch,
+                )
+            if output_file != "-":
+                fd.close()
+                if manifest.path_prefix:
+                    logger.warning(
+                        "Saved %s submanifest to %s",
+                        manifest.path_prefix,
+                        output_file,
+                    )
+                else:
+                    logger.warning("Saved manifest to %s", output_file)
+
+    def ValidateOptions(self, opt, args):
+        if args:
+            self.Usage()
+
+    def Execute(self, opt, args):
+        self._Output(opt)

subcmds/overview.py

@@ -1,5 +1,3 @@
-# -*- coding:utf-8 -*-
-#
 # Copyright (C) 2012 The Android Open Source Project
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -14,72 +12,97 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-from __future__ import print_function
+import optparse
+
 from color import Coloring
 from command import PagedCommand
 
 
 class Overview(PagedCommand):
-  common = True
-  helpSummary = "Display overview of unmerged project branches"
-  helpUsage = """
+    COMMON = True
+    helpSummary = "Display overview of unmerged project branches"
+    helpUsage = """
 %prog [--current-branch] [<project>...]
 """
-  helpDescription = """
+    helpDescription = """
 The '%prog' command is used to display an overview of the projects branches,
 and list any local commits that have not yet been merged into the project.
 
-The -b/--current-branch option can be used to restrict the output to only
+The -c/--current-branch option can be used to restrict the output to only
 branches currently checked out in each project.  By default, all branches
 are displayed.
 """
 
-  def _Options(self, p):
-    p.add_option('-b', '--current-branch',
-                 dest="current_branch", action="store_true",
-                 help="Consider only checked out branches")
+    def _Options(self, p):
+        p.add_option(
+            "-c",
+            "--current-branch",
+            action="store_true",
+            help="consider only checked out branches",
+        )
+        p.add_option(
+            "--no-current-branch",
+            dest="current_branch",
+            action="store_false",
+            help="consider all local branches",
+        )
+        # Turn this into a warning & remove this someday.
+        p.add_option(
+            "-b",
+            dest="current_branch",
+            action="store_true",
+            help=optparse.SUPPRESS_HELP,
+        )
 
-  def Execute(self, opt, args):
-    all_branches = []
-    for project in self.GetProjects(args):
-      br = [project.GetUploadableBranch(x)
-            for x in project.GetBranches()]
-      br = [x for x in br if x]
-      if opt.current_branch:
-        br = [x for x in br if x.name == project.CurrentBranch]
-      all_branches.extend(br)
+    def Execute(self, opt, args):
+        all_branches = []
+        for project in self.GetProjects(
+            args, all_manifests=not opt.this_manifest_only
+        ):
+            br = [project.GetUploadableBranch(x) for x in project.GetBranches()]
+            br = [x for x in br if x]
+            if opt.current_branch:
+                br = [x for x in br if x.name == project.CurrentBranch]
+            all_branches.extend(br)
 
-    if not all_branches:
-      return
+        if not all_branches:
+            return
 
-    class Report(Coloring):
-      def __init__(self, config):
-        Coloring.__init__(self, config, 'status')
-        self.project = self.printer('header', attr='bold')
-        self.text = self.printer('text')
+        class Report(Coloring):
+            def __init__(self, config):
+                Coloring.__init__(self, config, "status")
+                self.project = self.printer("header", attr="bold")
+                self.text = self.printer("text")
 
-    out = Report(all_branches[0].project.config)
-    out.text("Deprecated. See repo info -o.")
-    out.nl()
-    out.project('Projects Overview')
-    out.nl()
-
-    project = None
-
-    for branch in all_branches:
-      if project != branch.project:
-        project = branch.project
+        out = Report(all_branches[0].project.config)
+        out.text("Deprecated. See repo info -o.")
         out.nl()
-        out.project('project %s/' % project.relpath)
+        out.project("Projects Overview")
         out.nl()
 
-      commits = branch.commits
-      date = branch.date
-      print('%s %-33s (%2d commit%s, %s)' % (
-            branch.name == project.CurrentBranch and '*' or ' ',
-            branch.name,
-            len(commits),
-            len(commits) != 1 and 's' or ' ',
-            date))
-      for commit in commits:
-        print('%-35s   - %s' % ('', commit))
+        project = None
+
+        for branch in all_branches:
+            if project != branch.project:
+                project = branch.project
+                out.nl()
+                out.project(
+                    "project %s/"
+                    % project.RelPath(local=opt.this_manifest_only)
+                )
+                out.nl()
+
+            commits = branch.commits
+            date = branch.date
+            print(
+                "%s %-33s (%2d commit%s, %s)"
+                % (
+                    branch.name == project.CurrentBranch and "*" or " ",
+                    branch.name,
+                    len(commits),
+                    len(commits) != 1 and "s" or " ",
+                    date,
+                )
+            )
+            for commit in commits:
+                print("%-35s   - %s" % ("", commit))

subcmds/prune.py

@@ -1,5 +1,3 @@
-# -*- coding:utf-8 -*-
-#
 # Copyright (C) 2008 The Android Open Source Project
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -14,53 +12,86 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-from __future__ import print_function
+import itertools
+
 from color import Coloring
+from command import DEFAULT_LOCAL_JOBS
 from command import PagedCommand
 
+
 class Prune(PagedCommand):
-  common = True
-  helpSummary = "Prune (delete) already merged topics"
-  helpUsage = """
+    COMMON = True
+    helpSummary = "Prune (delete) already merged topics"
+    helpUsage = """
 %prog [<project>...]
 """
+    PARALLEL_JOBS = DEFAULT_LOCAL_JOBS
 
-  def Execute(self, opt, args):
-    all_branches = []
-    for project in self.GetProjects(args):
-      all_branches.extend(project.PruneHeads())
+    @classmethod
+    def _ExecuteOne(cls, project_idx):
+        """Process one project."""
+        project = cls.get_parallel_context()["projects"][project_idx]
+        return project.PruneHeads()
 
-    if not all_branches:
-      return
+    def Execute(self, opt, args):
+        projects = self.GetProjects(
+            args, all_manifests=not opt.this_manifest_only
+        )
 
-    class Report(Coloring):
-      def __init__(self, config):
-        Coloring.__init__(self, config, 'status')
-        self.project = self.printer('header', attr='bold')
+        # NB: Should be able to refactor this module to display summary as
+        # results come back from children.
+        def _ProcessResults(_pool, _output, results):
+            return list(itertools.chain.from_iterable(results))
 
-    out = Report(all_branches[0].project.config)
-    out.project('Pending Branches')
-    out.nl()
+        with self.ParallelContext():
+            self.get_parallel_context()["projects"] = projects
+            all_branches = self.ExecuteInParallel(
+                opt.jobs,
+                self._ExecuteOne,
+                range(len(projects)),
+                callback=_ProcessResults,
+                ordered=True,
+            )
 
-    project = None
+        if not all_branches:
+            return
 
-    for branch in all_branches:
-      if project != branch.project:
-        project = branch.project
-        out.nl()
-        out.project('project %s/' % project.relpath)
+        class Report(Coloring):
+            def __init__(self, config):
+                Coloring.__init__(self, config, "status")
+                self.project = self.printer("header", attr="bold")
+
+        out = Report(all_branches[0].project.config)
+        out.project("Pending Branches")
         out.nl()
 
-      print('%s %-33s ' % (
-            branch.name == project.CurrentBranch and '*' or ' ',
-            branch.name), end='')
+        project = None
 
-      if not branch.base_exists:
-        print('(ignoring: tracking branch is gone: %s)' % (branch.base,))
-      else:
-        commits = branch.commits
-        date = branch.date
-        print('(%2d commit%s, %s)' % (
-            len(commits),
-            len(commits) != 1 and 's' or ' ',
-            date))
+        for branch in all_branches:
+            if project != branch.project:
+                project = branch.project
+                out.nl()
+                out.project(
+                    "project %s/"
+                    % project.RelPath(local=opt.this_manifest_only)
+                )
+                out.nl()
+
+            print(
+                "%s %-33s "
+                % (
+                    branch.name == project.CurrentBranch and "*" or " ",
+                    branch.name,
+                ),
+                end="",
+            )
+
+            if not branch.base_exists:
+                print(f"(ignoring: tracking branch is gone: {branch.base})")
+            else:
+                commits = branch.commits
+                date = branch.date
+                print(
+                    "(%2d commit%s, %s)"
+                    % (len(commits), len(commits) != 1 and "s" or " ", date)
+                )

subcmds/rebase.py

@@ -1,5 +1,3 @@
-# -*- coding:utf-8 -*-
-#
 # Copyright (C) 2010 The Android Open Source Project
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -14,156 +12,196 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-from __future__ import print_function
 import sys
 
 from color import Coloring
 from command import Command
 from git_command import GitCommand
+from repo_logging import RepoLogger
+
+
+logger = RepoLogger(__file__)
 
 
 class RebaseColoring(Coloring):
-  def __init__(self, config):
-    Coloring.__init__(self, config, 'rebase')
-    self.project = self.printer('project', attr='bold')
-    self.fail = self.printer('fail', fg='red')
+    def __init__(self, config):
+        Coloring.__init__(self, config, "rebase")
+        self.project = self.printer("project", attr="bold")
+        self.fail = self.printer("fail", fg="red")
 
 
 class Rebase(Command):
-  common = True
-  helpSummary = "Rebase local branches on upstream branch"
-  helpUsage = """
+    COMMON = True
+    helpSummary = "Rebase local branches on upstream branch"
+    helpUsage = """
 %prog {[<project>...] | -i <project>...}
 """
-  helpDescription = """
+    helpDescription = """
 '%prog' uses git rebase to move local changes in the current topic branch to
 the HEAD of the upstream history, useful when you have made commits in a topic
 branch but need to incorporate new upstream changes "underneath" them.
 """
 
-  def _Options(self, p):
-    p.add_option('-i', '--interactive',
-                dest="interactive", action="store_true",
-                help="interactive rebase (single project only)")
+    def _Options(self, p):
+        g = p.get_option_group("--quiet")
+        g.add_option(
+            "-i",
+            "--interactive",
+            action="store_true",
+            help="interactive rebase (single project only)",
+        )
 
-    p.add_option('--fail-fast',
-                 dest='fail_fast', action='store_true',
-                 help='Stop rebasing after first error is hit')
-    p.add_option('-f', '--force-rebase',
-                 dest='force_rebase', action='store_true',
-                 help='Pass --force-rebase to git rebase')
-    p.add_option('--no-ff',
-                 dest='no_ff', action='store_true',
-                 help='Pass --no-ff to git rebase')
-    p.add_option('-q', '--quiet',
-                 dest='quiet', action='store_true',
-                 help='Pass --quiet to git rebase')
-    p.add_option('--autosquash',
-                 dest='autosquash', action='store_true',
-                 help='Pass --autosquash to git rebase')
-    p.add_option('--whitespace',
-                 dest='whitespace', action='store', metavar='WS',
-                 help='Pass --whitespace to git rebase')
-    p.add_option('--auto-stash',
-                 dest='auto_stash', action='store_true',
-                 help='Stash local modifications before starting')
-    p.add_option('-m', '--onto-manifest',
-                 dest='onto_manifest', action='store_true',
-                 help='Rebase onto the manifest version instead of upstream '
-                      'HEAD.  This helps to make sure the local tree stays '
-                      'consistent if you previously synced to a manifest.')
+        p.add_option(
+            "--fail-fast",
+            action="store_true",
+            help="stop rebasing after first error is hit",
+        )
+        p.add_option(
+            "-f",
+            "--force-rebase",
+            action="store_true",
+            help="pass --force-rebase to git rebase",
+        )
+        p.add_option(
+            "--no-ff",
+            dest="ff",
+            default=True,
+            action="store_false",
+            help="pass --no-ff to git rebase",
+        )
+        p.add_option(
+            "--autosquash",
+            action="store_true",
+            help="pass --autosquash to git rebase",
+        )
+        p.add_option(
+            "--whitespace",
+            action="store",
+            metavar="WS",
+            help="pass --whitespace to git rebase",
+        )
+        p.add_option(
+            "--auto-stash",
+            action="store_true",
+            help="stash local modifications before starting",
+        )
+        p.add_option(
+            "-m",
+            "--onto-manifest",
+            action="store_true",
+            help="rebase onto the manifest version instead of upstream "
+            "HEAD (this helps to make sure the local tree stays "
+            "consistent if you previously synced to a manifest)",
+        )
 
-  def Execute(self, opt, args):
-    all_projects = self.GetProjects(args)
-    one_project = len(all_projects) == 1
+    def Execute(self, opt, args):
+        all_projects = self.GetProjects(
+            args, all_manifests=not opt.this_manifest_only
+        )
+        one_project = len(all_projects) == 1
 
-    if opt.interactive and not one_project:
-      print('error: interactive rebase not supported with multiple projects',
-            file=sys.stderr)
-      if len(args) == 1:
-        print('note: project %s is mapped to more than one path' % (args[0],),
-            file=sys.stderr)
-      return 1
+        if opt.interactive and not one_project:
+            logger.error(
+                "error: interactive rebase not supported with multiple projects"
+            )
 
-    # Setup the common git rebase args that we use for all projects.
-    common_args = ['rebase']
-    if opt.whitespace:
-      common_args.append('--whitespace=%s' % opt.whitespace)
-    if opt.quiet:
-      common_args.append('--quiet')
-    if opt.force_rebase:
-      common_args.append('--force-rebase')
-    if opt.no_ff:
-      common_args.append('--no-ff')
-    if opt.autosquash:
-      common_args.append('--autosquash')
-    if opt.interactive:
-      common_args.append('-i')
+            if len(args) == 1:
+                logger.warning(
+                    "note: project %s is mapped to more than one path", args[0]
+                )
 
-    config = self.manifest.manifestProject.config
-    out = RebaseColoring(config)
-    out.redirect(sys.stdout)
+            return 1
 
-    ret = 0
-    for project in all_projects:
-      if ret and opt.fail_fast:
-        break
+        # Setup the common git rebase args that we use for all projects.
+        common_args = ["rebase"]
+        if opt.whitespace:
+            common_args.append("--whitespace=%s" % opt.whitespace)
+        if opt.quiet:
+            common_args.append("--quiet")
+        if opt.force_rebase:
+            common_args.append("--force-rebase")
+        if not opt.ff:
+            common_args.append("--no-ff")
+        if opt.autosquash:
+            common_args.append("--autosquash")
+        if opt.interactive:
+            common_args.append("-i")
 
-      cb = project.CurrentBranch
-      if not cb:
-        if one_project:
-          print("error: project %s has a detached HEAD" % project.relpath,
-                file=sys.stderr)
-          return 1
-        # ignore branches with detatched HEADs
-        continue
+        config = self.manifest.manifestProject.config
+        out = RebaseColoring(config)
+        out.redirect(sys.stdout)
+        _RelPath = lambda p: p.RelPath(local=opt.this_manifest_only)
 
-      upbranch = project.GetBranch(cb)
-      if not upbranch.LocalMerge:
-        if one_project:
-          print("error: project %s does not track any remote branches"
-                % project.relpath, file=sys.stderr)
-          return 1
-        # ignore branches without remotes
-        continue
+        ret = 0
+        for project in all_projects:
+            if ret and opt.fail_fast:
+                break
 
-      args = common_args[:]
-      if opt.onto_manifest:
-        args.append('--onto')
-        args.append(project.revisionExpr)
+            cb = project.CurrentBranch
+            if not cb:
+                if one_project:
+                    logger.error(
+                        "error: project %s has a detached HEAD",
+                        _RelPath(project),
+                    )
+                    return 1
+                # Ignore branches with detached HEADs.
+                continue
 
-      args.append(upbranch.LocalMerge)
+            upbranch = project.GetBranch(cb)
+            if not upbranch.LocalMerge:
+                if one_project:
+                    logger.error(
+                        "error: project %s does not track any remote branches",
+                        _RelPath(project),
+                    )
+                    return 1
+                # Ignore branches without remotes.
+                continue
 
-      out.project('project %s: rebasing %s -> %s',
-                  project.relpath, cb, upbranch.LocalMerge)
-      out.nl()
-      out.flush()
+            args = common_args[:]
+            if opt.onto_manifest:
+                args.append("--onto")
+                args.append(project.revisionExpr)
 
-      needs_stash = False
-      if opt.auto_stash:
-        stash_args = ["update-index", "--refresh", "-q"]
+            args.append(upbranch.LocalMerge)
 
-        if GitCommand(project, stash_args).Wait() != 0:
-          needs_stash = True
-          # Dirty index, requires stash...
-          stash_args = ["stash"]
+            out.project(
+                "project %s: rebasing %s -> %s",
+                _RelPath(project),
+                cb,
+                upbranch.LocalMerge,
+            )
+            out.nl()
+            out.flush()
 
-          if GitCommand(project, stash_args).Wait() != 0:
-            ret += 1
-            continue
+            needs_stash = False
+            if opt.auto_stash:
+                stash_args = ["update-index", "--refresh", "-q"]
 
-      if GitCommand(project, args).Wait() != 0:
-        ret += 1
-        continue
+                if GitCommand(project, stash_args).Wait() != 0:
+                    needs_stash = True
+                    # Dirty index, requires stash...
+                    stash_args = ["stash"]
 
-      if needs_stash:
-        stash_args.append('pop')
-        stash_args.append('--quiet')
-        if GitCommand(project, stash_args).Wait() != 0:
-          ret += 1
+                    if GitCommand(project, stash_args).Wait() != 0:
+                        ret += 1
+                        continue
 
-    if ret:
-      out.fail('%i projects had errors', ret)
-      out.nl()
+            if GitCommand(project, args).Wait() != 0:
+                ret += 1
+                continue
 
-    return ret
+            if needs_stash:
+                stash_args.append("pop")
+                stash_args.append("--quiet")
+                if GitCommand(project, stash_args).Wait() != 0:
+                    ret += 1
+
+        if ret:
+            msg_fmt = "%d projects had errors"
+            self.git_event_log.ErrorEvent(msg_fmt % (ret), msg_fmt)
+            out.fail(msg_fmt, ret)
+            out.nl()
+
+        return ret

subcmds/selfupdate.py

@@ -1,5 +1,3 @@
-# -*- coding:utf-8 -*-
-#
 # Copyright (C) 2009 The Android Open Source Project
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -14,21 +12,30 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-from __future__ import print_function
-from optparse import SUPPRESS_HELP
-import sys
+import optparse
 
-from command import Command, MirrorSafeCommand
-from subcmds.sync import _PostRepoUpgrade
+from command import Command
+from command import MirrorSafeCommand
+from error import RepoExitError
+from repo_logging import RepoLogger
 from subcmds.sync import _PostRepoFetch
+from subcmds.sync import _PostRepoUpgrade
+
+
+logger = RepoLogger(__file__)
+
+
+class SelfupdateError(RepoExitError):
+    """Exit error for failed selfupdate command."""
+
 
 class Selfupdate(Command, MirrorSafeCommand):
-  common = False
-  helpSummary = "Update repo to the latest version"
-  helpUsage = """
+    COMMON = False
+    helpSummary = "Update repo to the latest version"
+    helpUsage = """
 %prog
 """
-  helpDescription = """
+    helpDescription = """
 The '%prog' command upgrades repo to the latest version, if a
 newer version is available.
 
@@ -36,28 +43,33 @@ Normally this is done automatically by 'repo sync' and does not
 need to be performed by an end-user.
 """
 
-  def _Options(self, p):
-    g = p.add_option_group('repo Version options')
-    g.add_option('--no-repo-verify',
-                 dest='no_repo_verify', action='store_true',
-                 help='do not verify repo source code')
-    g.add_option('--repo-upgraded',
-                 dest='repo_upgraded', action='store_true',
-                 help=SUPPRESS_HELP)
+    def _Options(self, p):
+        g = p.add_option_group("repo Version options")
+        g.add_option(
+            "--no-repo-verify",
+            dest="repo_verify",
+            default=True,
+            action="store_false",
+            help="do not verify repo source code",
+        )
+        g.add_option(
+            "--repo-upgraded",
+            action="store_true",
+            help=optparse.SUPPRESS_HELP,
+        )
 
-  def Execute(self, opt, args):
-    rp = self.manifest.repoProject
-    rp.PreSync()
+    def Execute(self, opt, args):
+        rp = self.manifest.repoProject
+        rp.PreSync()
 
-    if opt.repo_upgraded:
-      _PostRepoUpgrade(self.manifest)
+        if opt.repo_upgraded:
+            _PostRepoUpgrade(self.manifest)
 
-    else:
-      if not rp.Sync_NetworkHalf():
-        print("error: can't update repo", file=sys.stderr)
-        sys.exit(1)
+        else:
+            result = rp.Sync_NetworkHalf()
+            if result.error:
+                logger.error("error: can't update repo")
+                raise SelfupdateError(aggregate_errors=[result.error])
 
-      rp.bare_git.gc('--auto')
-      _PostRepoFetch(rp,
-                     no_repo_verify = opt.no_repo_verify,
-                     verbose = True)
+            rp.bare_git.gc("--auto")
+            _PostRepoFetch(rp, repo_verify=opt.repo_verify, verbose=True)

subcmds/smartsync.py

@@ -1,5 +1,3 @@
-# -*- coding:utf-8 -*-
-#
 # Copyright (C) 2010 The Android Open Source Project
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -16,19 +14,20 @@
 
 from subcmds.sync import Sync
 
+
 class Smartsync(Sync):
-  common = True
-  helpSummary = "Update working tree to the latest known good revision"
-  helpUsage = """
+    COMMON = True
+    helpSummary = "Update working tree to the latest known good revision"
+    helpUsage = """
 %prog [<project>...]
 """
-  helpDescription = """
+    helpDescription = """
 The '%prog' command is a shortcut for sync -s.
 """
 
-  def _Options(self, p):
-    Sync._Options(self, p, show_smart=False)
+    def _Options(self, p):
+        Sync._Options(self, p, show_smart=False)
 
-  def Execute(self, opt, args):
-    opt.smart_sync = True
-    Sync.Execute(self, opt, args)
+    def Execute(self, opt, args):
+        opt.smart_sync = True
+        Sync.Execute(self, opt, args)

subcmds/stage.py

@@ -1,5 +1,3 @@
-# -*- coding:utf-8 -*-
-#
 # Copyright (C) 2008 The Android Open Source Project
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -14,97 +12,122 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-from __future__ import print_function
 import sys
 
 from color import Coloring
 from command import InteractiveCommand
 from git_command import GitCommand
+from repo_logging import RepoLogger
+
+
+logger = RepoLogger(__file__)
+
 
 class _ProjectList(Coloring):
-  def __init__(self, gc):
-    Coloring.__init__(self, gc, 'interactive')
-    self.prompt = self.printer('prompt', fg='blue', attr='bold')
-    self.header = self.printer('header', attr='bold')
-    self.help = self.printer('help', fg='red', attr='bold')
+    def __init__(self, gc):
+        Coloring.__init__(self, gc, "interactive")
+        self.prompt = self.printer("prompt", fg="blue", attr="bold")
+        self.header = self.printer("header", attr="bold")
+        self.help = self.printer("help", fg="red", attr="bold")
+
 
 class Stage(InteractiveCommand):
-  common = True
-  helpSummary = "Stage file(s) for commit"
-  helpUsage = """
+    COMMON = True
+    helpSummary = "Stage file(s) for commit"
+    helpUsage = """
 %prog -i [<project>...]
 """
-  helpDescription = """
+    helpDescription = """
 The '%prog' command stages files to prepare the next commit.
 """
 
-  def _Options(self, p):
-    p.add_option('-i', '--interactive',
-                 dest='interactive', action='store_true',
-                 help='use interactive staging')
+    def _Options(self, p):
+        g = p.get_option_group("--quiet")
+        g.add_option(
+            "-i",
+            "--interactive",
+            action="store_true",
+            help="use interactive staging",
+        )
 
-  def Execute(self, opt, args):
-    if opt.interactive:
-      self._Interactive(opt, args)
-    else:
-      self.Usage()
+    def Execute(self, opt, args):
+        if opt.interactive:
+            self._Interactive(opt, args)
+        else:
+            self.Usage()
 
-  def _Interactive(self, opt, args):
-    all_projects = [p for p in self.GetProjects(args) if p.IsDirty()]
-    if not all_projects:
-      print('no projects have uncommitted modifications', file=sys.stderr)
-      return
+    def _Interactive(self, opt, args):
+        all_projects = [
+            p
+            for p in self.GetProjects(
+                args, all_manifests=not opt.this_manifest_only
+            )
+            if p.IsDirty()
+        ]
+        if not all_projects:
+            logger.error("no projects have uncommitted modifications")
+            return
 
-    out = _ProjectList(self.manifest.manifestProject.config)
-    while True:
-      out.header('        %s', 'project')
-      out.nl()
+        out = _ProjectList(self.manifest.manifestProject.config)
+        while True:
+            out.header("        %s", "project")
+            out.nl()
 
-      for i in range(len(all_projects)):
-        project = all_projects[i]
-        out.write('%3d:    %s', i + 1, project.relpath + '/')
-        out.nl()
-      out.nl()
+            for i in range(len(all_projects)):
+                project = all_projects[i]
+                out.write(
+                    "%3d:    %s",
+                    i + 1,
+                    project.RelPath(local=opt.this_manifest_only) + "/",
+                )
+                out.nl()
+            out.nl()
 
-      out.write('%3d: (', 0)
-      out.prompt('q')
-      out.write('uit)')
-      out.nl()
+            out.write("%3d: (", 0)
+            out.prompt("q")
+            out.write("uit)")
+            out.nl()
 
-      out.prompt('project> ')
-      try:
-        a = sys.stdin.readline()
-      except KeyboardInterrupt:
-        out.nl()
-        break
-      if a == '':
-        out.nl()
-        break
+            out.prompt("project> ")
+            out.flush()
+            try:
+                a = sys.stdin.readline()
+            except KeyboardInterrupt:
+                out.nl()
+                break
+            if a == "":
+                out.nl()
+                break
 
-      a = a.strip()
-      if a.lower() in ('q', 'quit', 'exit'):
-        break
-      if not a:
-        continue
+            a = a.strip()
+            if a.lower() in ("q", "quit", "exit"):
+                break
+            if not a:
+                continue
 
-      try:
-        a_index = int(a)
-      except ValueError:
-        a_index = None
+            try:
+                a_index = int(a)
+            except ValueError:
+                a_index = None
 
-      if a_index is not None:
-        if a_index == 0:
-          break
-        if 0 < a_index and a_index <= len(all_projects):
-          _AddI(all_projects[a_index - 1])
-          continue
+            if a_index is not None:
+                if a_index == 0:
+                    break
+                if 0 < a_index and a_index <= len(all_projects):
+                    _AddI(all_projects[a_index - 1])
+                    continue
+
+            projects = [
+                p
+                for p in all_projects
+                if a in [p.name, p.RelPath(local=opt.this_manifest_only)]
+            ]
+            if len(projects) == 1:
+                _AddI(projects[0])
+                continue
+        print("Bye.")
 
-      projects = [p for p in all_projects if a in [p.name, p.relpath]]
-      if len(projects) == 1:
-        _AddI(projects[0])
-        continue
-    print('Bye.')
 
 def _AddI(project):
-  p = GitCommand(project, ['add', '--interactive'], bare=False)
-  p.Wait()
+    p = GitCommand(project, ["add", "--interactive"], bare=False)
+    p.Wait()

subcmds/start.py

@@ -1,5 +1,3 @@
-# -*- coding:utf-8 -*-
-#
 # Copyright (C) 2008 The Android Open Source Project
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -14,111 +12,146 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-from __future__ import print_function
-import os
-import sys
+import functools
+from typing import NamedTuple
 
 from command import Command
-from git_config import IsImmutable
+from command import DEFAULT_LOCAL_JOBS
+from error import RepoExitError
 from git_command import git
-import gitc_utils
+from git_config import IsImmutable
 from progress import Progress
-from project import SyncBuffer
+from repo_logging import RepoLogger
+
+
+logger = RepoLogger(__file__)
+
+
+class ExecuteOneResult(NamedTuple):
+    project_idx: int
+    error: Exception
+
+
+class StartError(RepoExitError):
+    """Exit error for failed start command."""
+
 
 class Start(Command):
-  common = True
-  helpSummary = "Start a new branch for development"
-  helpUsage = """
+    COMMON = True
+    helpSummary = "Start a new branch for development"
+    helpUsage = """
 %prog <newbranchname> [--all | <project>...]
 """
-  helpDescription = """
+    helpDescription = """
 '%prog' begins a new branch of development, starting from the
 revision specified in the manifest.
 """
+    PARALLEL_JOBS = DEFAULT_LOCAL_JOBS
 
-  def _Options(self, p):
-    p.add_option('--all',
-                 dest='all', action='store_true',
-                 help='begin branch in all projects')
-    p.add_option('-r', '--rev', '--revision', dest='revision',
-                 help='point branch at this revision instead of upstream')
-    p.add_option('--head', dest='revision', action='store_const', const='HEAD',
-                 help='abbreviation for --rev HEAD')
+    def _Options(self, p):
+        p.add_option(
+            "--all",
+            action="store_true",
+            help="begin branch in all projects",
+        )
+        p.add_option(
+            "-r",
+            "--rev",
+            "--revision",
+            dest="revision",
+            help="point branch at this revision instead of upstream",
+        )
+        p.add_option(
+            "--head",
+            "--HEAD",
+            dest="revision",
+            action="store_const",
+            const="HEAD",
+            help="abbreviation for --rev HEAD",
+        )
 
-  def ValidateOptions(self, opt, args):
-    if not args:
-      self.Usage()
+    def ValidateOptions(self, opt, args):
+        if not args:
+            self.Usage()
 
-    nb = args[0]
-    if not git.check_ref_format('heads/%s' % nb):
-      self.OptionParser.error("'%s' is not a valid name" % nb)
+        nb = args[0]
+        if not git.check_ref_format("heads/%s" % nb):
+            self.OptionParser.error("'%s' is not a valid name" % nb)
 
-  def Execute(self, opt, args):
-    nb = args[0]
-    err = []
-    projects = []
-    if not opt.all:
-      projects = args[1:]
-      if len(projects) < 1:
-        projects = ['.',]  # start it in the local project by default
+    @classmethod
+    def _ExecuteOne(cls, revision, nb, default_revisionExpr, project_idx):
+        """Start one project."""
+        # If the current revision is immutable, such as a SHA1, a tag or
+        # a change, then we can't push back to it. Substitute with
+        # dest_branch, if defined; or with manifest default revision instead.
+        branch_merge = ""
+        error = None
+        project = cls.get_parallel_context()["projects"][project_idx]
+        if IsImmutable(project.revisionExpr):
+            if project.dest_branch:
+                branch_merge = project.dest_branch
+            else:
+                branch_merge = default_revisionExpr
 
-    all_projects = self.GetProjects(projects,
-                                    missing_ok=bool(self.gitc_manifest))
+        try:
+            project.StartBranch(
+                nb, branch_merge=branch_merge, revision=revision
+            )
+        except Exception as e:
+            logger.error("error: unable to checkout %s: %s", project.name, e)
+            error = e
+        return ExecuteOneResult(project_idx, error)
 
-    # This must happen after we find all_projects, since GetProjects may need
-    # the local directory, which will disappear once we save the GITC manifest.
-    if self.gitc_manifest:
-      gitc_projects = self.GetProjects(projects, manifest=self.gitc_manifest,
-                                       missing_ok=True)
-      for project in gitc_projects:
-        if project.old_revision:
-          project.already_synced = True
-        else:
-          project.already_synced = False
-          project.old_revision = project.revisionExpr
-        project.revisionExpr = None
-      # Save the GITC manifest.
-      gitc_utils.save_manifest(self.gitc_manifest)
+    def Execute(self, opt, args):
+        nb = args[0]
+        err_projects = []
+        err = []
+        projects = []
+        if not opt.all:
+            projects = args[1:]
+            if len(projects) < 1:
+                projects = ["."]  # start it in the local project by default
 
-      # Make sure we have a valid CWD
-      if not os.path.exists(os.getcwd()):
-        os.chdir(self.manifest.topdir)
+        all_projects = self.GetProjects(
+            projects,
+            all_manifests=not opt.this_manifest_only,
+        )
 
-    pm = Progress('Starting %s' % nb, len(all_projects))
-    for project in all_projects:
-      pm.update()
+        def _ProcessResults(_pool, pm, results):
+            for result in results:
+                if result.error:
+                    project = all_projects[result.project_idx]
+                    err_projects.append(project)
+                    err.append(result.error)
+                pm.update(msg="")
 
-      if self.gitc_manifest:
-        gitc_project = self.gitc_manifest.paths[project.relpath]
-        # Sync projects that have not been opened.
-        if not gitc_project.already_synced:
-          proj_localdir = os.path.join(self.gitc_manifest.gitc_client_dir,
-                                       project.relpath)
-          project.worktree = proj_localdir
-          if not os.path.exists(proj_localdir):
-            os.makedirs(proj_localdir)
-          project.Sync_NetworkHalf()
-          sync_buf = SyncBuffer(self.manifest.manifestProject.config)
-          project.Sync_LocalHalf(sync_buf)
-          project.revisionId = gitc_project.old_revision
+        with self.ParallelContext():
+            self.get_parallel_context()["projects"] = all_projects
+            self.ExecuteInParallel(
+                opt.jobs,
+                functools.partial(
+                    self._ExecuteOne,
+                    opt.revision,
+                    nb,
+                    self.manifest.default.revisionExpr,
+                ),
+                range(len(all_projects)),
+                callback=_ProcessResults,
+                output=Progress(
+                    f"Starting {nb}", len(all_projects), quiet=opt.quiet
+                ),
+                chunksize=1,
+            )
 
-      # If the current revision is immutable, such as a SHA1, a tag or
-      # a change, then we can't push back to it. Substitute with
-      # dest_branch, if defined; or with manifest default revision instead.
-      branch_merge = ''
-      if IsImmutable(project.revisionExpr):
-        if project.dest_branch:
-          branch_merge = project.dest_branch
-        else:
-          branch_merge = self.manifest.default.revisionExpr
-
-      if not project.StartBranch(
-          nb, branch_merge=branch_merge, revision=opt.revision):
-        err.append(project)
-    pm.end()
-
-    if err:
-      for p in err:
-        print("error: %s/: cannot start %s" % (p.relpath, nb),
-              file=sys.stderr)
-      sys.exit(1)
+        if err_projects:
+            for p in err_projects:
+                logger.error(
+                    "error: %s/: cannot start %s",
+                    p.RelPath(local=opt.this_manifest_only),
+                    nb,
+                )
+            msg_fmt = "cannot start %d project(s)"
+            self.git_event_log.ErrorEvent(
+                msg_fmt % (len(err_projects)), msg_fmt
+            )
+            raise StartError(aggregate_errors=err)

subcmds/status.py

@@ -1,5 +1,3 @@
-# -*- coding:utf-8 -*-
-#
 # Copyright (C) 2008 The Android Open Source Project
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -14,30 +12,24 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-from __future__ import print_function
-
-from command import PagedCommand
-
-try:
-  import threading as _threading
-except ImportError:
-  import dummy_threading as _threading
-
+import functools
 import glob
-
-import itertools
+import io
 import os
 
 from color import Coloring
+from command import DEFAULT_LOCAL_JOBS
+from command import PagedCommand
 import platform_utils
 
+
 class Status(PagedCommand):
-  common = True
-  helpSummary = "Show the working tree status"
-  helpUsage = """
+    COMMON = True
+    helpSummary = "Show the working tree status"
+    helpUsage = """
 %prog [<project>...]
 """
-  helpDescription = """
+    helpDescription = """
 '%prog' compares the working tree to the staging area (aka index),
 and the most recent commit on this branch (HEAD), in each project
 specified.  A summary is displayed, one line per file where there
@@ -84,114 +76,132 @@ the following meanings:
  d:  deleted       (    in index, not in work tree                )
 
 """
+    PARALLEL_JOBS = DEFAULT_LOCAL_JOBS
 
-  def _Options(self, p):
-    p.add_option('-j', '--jobs',
-                 dest='jobs', action='store', type='int', default=2,
-                 help="number of projects to check simultaneously")
-    p.add_option('-o', '--orphans',
-                 dest='orphans', action='store_true',
-                 help="include objects in working directory outside of repo projects")
-    p.add_option('-q', '--quiet', action='store_true',
-                 help="only print the name of modified projects")
+    def _Options(self, p):
+        p.add_option(
+            "-o",
+            "--orphans",
+            action="store_true",
+            help="include objects in working directory outside of repo "
+            "projects",
+        )
 
-  def _StatusHelper(self, project, clean_counter, sem, quiet):
-    """Obtains the status for a specific project.
+    @classmethod
+    def _StatusHelper(cls, quiet, local, project_idx):
+        """Obtains the status for a specific project.
 
-    Obtains the status for a project, redirecting the output to
-    the specified object. It will release the semaphore
-    when done.
+        Obtains the status for a project, redirecting the output to
+        the specified object.
 
-    Args:
-      project: Project to get status of.
-      clean_counter: Counter for clean projects.
-      sem: Semaphore, will call release() when complete.
-      output: Where to output the status.
-    """
-    try:
-      state = project.PrintWorkTreeStatus(quiet=quiet)
-      if state == 'CLEAN':
-        next(clean_counter)
-    finally:
-      sem.release()
+        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_idx: Project index to get status of.
 
-  def _FindOrphans(self, dirs, proj_dirs, proj_dirs_parents, outstring):
-    """find 'dirs' that are present in 'proj_dirs_parents' but not in 'proj_dirs'"""
-    status_header = ' --\t'
-    for item in dirs:
-      if not platform_utils.isdir(item):
-        outstring.append(''.join([status_header, item]))
-        continue
-      if item in proj_dirs:
-        continue
-      if item in proj_dirs_parents:
-        self._FindOrphans(glob.glob('%s/.*' % item) +
-            glob.glob('%s/*' % item),
-            proj_dirs, proj_dirs_parents, outstring)
-        continue
-      outstring.append(''.join([status_header, item, '/']))
+        Returns:
+            The status of the project.
+        """
+        buf = io.StringIO()
+        project = cls.get_parallel_context()["projects"][project_idx]
+        ret = project.PrintWorkTreeStatus(
+            quiet=quiet, output_redir=buf, local=local
+        )
+        return (ret, buf.getvalue())
 
-  def Execute(self, opt, args):
-    all_projects = self.GetProjects(args)
-    counter = itertools.count()
+    def _FindOrphans(self, dirs, proj_dirs, proj_dirs_parents, outstring):
+        """find 'dirs' that are present in 'proj_dirs_parents' but not in 'proj_dirs'"""  # noqa: E501
+        status_header = " --\t"
+        for item in dirs:
+            if not platform_utils.isdir(item):
+                outstring.append("".join([status_header, item]))
+                continue
+            if item in proj_dirs:
+                continue
+            if item in proj_dirs_parents:
+                self._FindOrphans(
+                    glob.glob("%s/.*" % item) + glob.glob("%s/*" % item),
+                    proj_dirs,
+                    proj_dirs_parents,
+                    outstring,
+                )
+                continue
+            outstring.append("".join([status_header, item, "/"]))
 
-    if opt.jobs == 1:
-      for project in all_projects:
-        state = project.PrintWorkTreeStatus(quiet=opt.quiet)
-        if state == 'CLEAN':
-          next(counter)
-    else:
-      sem = _threading.Semaphore(opt.jobs)
-      threads = []
-      for project in all_projects:
-        sem.acquire()
+    def Execute(self, opt, args):
+        all_projects = self.GetProjects(
+            args, all_manifests=not opt.this_manifest_only
+        )
 
-        t = _threading.Thread(target=self._StatusHelper,
-                              args=(project, counter, sem, opt.quiet))
-        threads.append(t)
-        t.daemon = True
-        t.start()
-      for t in threads:
-        t.join()
-    if not opt.quiet and len(all_projects) == next(counter):
-      print('nothing to commit (working directory clean)')
+        def _ProcessResults(_pool, _output, results):
+            ret = 0
+            for state, output in results:
+                if output:
+                    print(output, end="")
+                if state == "CLEAN":
+                    ret += 1
+            return ret
 
-    if opt.orphans:
-      proj_dirs = set()
-      proj_dirs_parents = set()
-      for project in self.GetProjects(None, missing_ok=True):
-        proj_dirs.add(project.relpath)
-        (head, _tail) = os.path.split(project.relpath)
-        while head != "":
-          proj_dirs_parents.add(head)
-          (head, _tail) = os.path.split(head)
-      proj_dirs.add('.repo')
+        with self.ParallelContext():
+            self.get_parallel_context()["projects"] = all_projects
+            counter = self.ExecuteInParallel(
+                opt.jobs,
+                functools.partial(
+                    self._StatusHelper, opt.quiet, opt.this_manifest_only
+                ),
+                range(len(all_projects)),
+                callback=_ProcessResults,
+                ordered=True,
+                chunksize=1,
+            )
 
-      class StatusColoring(Coloring):
-        def __init__(self, config):
-          Coloring.__init__(self, config, 'status')
-          self.project = self.printer('header', attr = 'bold')
-          self.untracked = self.printer('untracked', fg = 'red')
+        if not opt.quiet and len(all_projects) == counter:
+            print("nothing to commit (working directory clean)")
 
-      orig_path = os.getcwd()
-      try:
-        os.chdir(self.manifest.topdir)
+        if opt.orphans:
+            proj_dirs = set()
+            proj_dirs_parents = set()
+            for project in self.GetProjects(
+                None, missing_ok=True, all_manifests=not opt.this_manifest_only
+            ):
+                relpath = project.RelPath(local=opt.this_manifest_only)
+                proj_dirs.add(relpath)
+                (head, _tail) = os.path.split(relpath)
+                while head != "":
+                    proj_dirs_parents.add(head)
+                    (head, _tail) = os.path.split(head)
+            proj_dirs.add(".repo")
 
-        outstring = []
-        self._FindOrphans(glob.glob('.*') +
-            glob.glob('*'),
-            proj_dirs, proj_dirs_parents, outstring)
+            class StatusColoring(Coloring):
+                def __init__(self, config):
+                    Coloring.__init__(self, config, "status")
+                    self.project = self.printer("header", attr="bold")
+                    self.untracked = self.printer("untracked", fg="red")
 
-        if outstring:
-          output = StatusColoring(self.manifest.globalConfig)
-          output.project('Objects not within a project (orphans)')
-          output.nl()
-          for entry in outstring:
-            output.untracked(entry)
-            output.nl()
-        else:
-          print('No orphan files or directories')
+            orig_path = os.getcwd()
+            try:
+                os.chdir(self.manifest.topdir)
 
-      finally:
-        # Restore CWD.
-        os.chdir(orig_path)
+                outstring = []
+                self._FindOrphans(
+                    glob.glob(".*") + glob.glob("*"),
+                    proj_dirs,
+                    proj_dirs_parents,
+                    outstring,
+                )
+
+                if outstring:
+                    output = StatusColoring(self.client.globalConfig)
+                    output.project("Objects not within a project (orphans)")
+                    output.nl()
+                    for entry in outstring:
+                        output.untracked(entry)
+                        output.nl()
+                else:
+                    print("No orphan files or directories")
+
+            finally:
+                # Restore CWD.
+                os.chdir(orig_path)

subcmds/version.py

@@ -1,5 +1,3 @@
-# -*- coding:utf-8 -*-
-#
 # Copyright (C) 2009 The Android Open Source Project
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -14,40 +12,58 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-from __future__ import print_function
+import platform
 import sys
-from command import Command, MirrorSafeCommand
-from git_command import git, RepoSourceVersion, user_agent
+
+from command import Command
+from command import MirrorSafeCommand
+from git_command import git
+from git_command import RepoSourceVersion
+from git_command import user_agent
 from git_refs import HEAD
+from wrapper import Wrapper
+
 
 class Version(Command, MirrorSafeCommand):
-  wrapper_version = None
-  wrapper_path = None
+    wrapper_version = None
+    wrapper_path = None
 
-  common = False
-  helpSummary = "Display the version of repo"
-  helpUsage = """
+    COMMON = False
+    helpSummary = "Display the version of repo"
+    helpUsage = """
 %prog
 """
 
-  def Execute(self, opt, args):
-    rp = self.manifest.repoProject
-    rem = rp.GetRemote(rp.remote.name)
+    def Execute(self, opt, args):
+        rp = self.manifest.repoProject
+        rem = rp.GetRemote()
+        branch = rp.GetBranch("default")
 
-    # These might not be the same.  Report them both.
-    src_ver = RepoSourceVersion()
-    rp_ver = rp.bare_git.describe(HEAD)
-    print('repo version %s' % rp_ver)
-    print('       (from %s)' % rem.url)
+        # These might not be the same.  Report them both.
+        src_ver = RepoSourceVersion()
+        rp_ver = rp.bare_git.describe(HEAD)
+        print(f"repo version {rp_ver}")
+        print(f"       (from {rem.url})")
+        print(f"       (tracking {branch.merge})")
+        print(f"       ({rp.bare_git.log('-1', '--format=%cD', HEAD)})")
 
-    if Version.wrapper_path is not None:
-      print('repo launcher version %s' % Version.wrapper_version)
-      print('       (from %s)' % Version.wrapper_path)
+        if self.wrapper_path is not None:
+            print(f"repo launcher version {self.wrapper_version}")
+            print(f"       (from {self.wrapper_path})")
 
-      if src_ver != rp_ver:
-        print('       (currently at %s)' % src_ver)
+            if src_ver != rp_ver:
+                print(f"       (currently at {src_ver})")
 
-    print('repo User-Agent %s' % user_agent.repo)
-    print('git %s' % git.version_tuple().full)
-    print('git User-Agent %s' % user_agent.git)
-    print('Python %s' % sys.version)
+        print(f"repo User-Agent {user_agent.repo}")
+        print(f"git {git.version_tuple().full}")
+        print(f"git User-Agent {user_agent.git}")
+        print(f"Python {sys.version}")
+        uname = platform.uname()
+        if sys.version_info.major < 3:
+            # Python 3 returns a named tuple, but Python 2 is simpler.
+            print(uname)
+        else:
+            print(f"OS {uname.system} {uname.release} ({uname.version})")
+            processor = uname.processor if uname.processor else "unknown"
+            print(f"CPU {uname.machine} ({processor})")
+        print("Bug reports:", Wrapper().BUG_URL)

tests/conftest.py

@@ -0,0 +1,83 @@
+# Copyright 2022 The Android Open Source Project
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Common fixtures for pytests."""
+
+import pathlib
+
+import pytest
+
+import platform_utils
+import repo_trace
+
+
+@pytest.fixture(autouse=True)
+def disable_repo_trace(tmp_path):
+    """Set an environment marker to relax certain strict checks for test code."""  # noqa: E501
+    repo_trace._TRACE_FILE = str(tmp_path / "TRACE_FILE_from_test")
+
+
+# adapted from pytest-home 0.5.1
+def _set_home(monkeypatch, path: pathlib.Path):
+    """
+    Set the home dir using a pytest monkeypatch context.
+    """
+    win = platform_utils.isWindows()
+    vars = ["HOME"] + win * ["USERPROFILE"]
+    for var in vars:
+        monkeypatch.setenv(var, str(path))
+    return path
+
+
+# copied from
+# https://github.com/pytest-dev/pytest/issues/363#issuecomment-1335631998
+@pytest.fixture(scope="session")
+def monkeysession():
+    with pytest.MonkeyPatch.context() as mp:
+        yield mp
+
+
+@pytest.fixture(autouse=True, scope="session")
+def session_tmp_home_dir(tmp_path_factory, monkeysession):
+    """Set HOME to a temporary directory, avoiding user's .gitconfig.
+
+    b/302797407
+
+    Set home at session scope to take effect prior to
+    ``test_wrapper.GitCheckoutTestCase.setUpClass``.
+    """
+    return _set_home(monkeysession, tmp_path_factory.mktemp("home"))
+
+
+# adapted from pytest-home 0.5.1
+@pytest.fixture(autouse=True)
+def tmp_home_dir(monkeypatch, tmp_path_factory):
+    """Set HOME to a temporary directory.
+
+    Ensures that state doesn't accumulate in $HOME across tests.
+
+    Note that in conjunction with session_tmp_homedir, the HOME
+    dir is patched twice, once at session scope, and then again at
+    the function scope.
+    """
+    return _set_home(monkeypatch, tmp_path_factory.mktemp("home"))
+
+
+@pytest.fixture(autouse=True)
+def setup_user_identity(monkeysession, scope="session"):
+    """Set env variables for author and committer name and email."""
+    monkeysession.setenv("GIT_AUTHOR_NAME", "Foo Bar")
+    monkeysession.setenv("GIT_COMMITTER_NAME", "Foo Bar")
+    monkeysession.setenv("GIT_AUTHOR_EMAIL", "foo@bar.baz")
+    monkeysession.setenv("GIT_COMMITTER_EMAIL", "foo@bar.baz")

tests/fixtures/gitc_config

@@ -1 +0,0 @@
-gitc_dir=/test/usr/local/google/gitc

tests/fixtures/test.gitconfig

@@ -1,3 +1,21 @@
 [section]
 	empty
 	nonempty = true
+	boolinvalid = oops
+	booltrue = true
+	boolfalse = false
+	intinvalid = oops
+	inthex = 0x10
+	inthexk = 0x10k
+	int = 10
+	intk = 10k
+	intm = 10m
+	intg = 10g
+
+[color "status"]
+	one = yellow
+	two = magenta cyan
+	three = black red ul
+	reset = reset
+	none
+	empty =

tests/test_color.py

@@ -0,0 +1,74 @@
+# Copyright (C) 2024 The Android Open Source Project
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Unittests for the color.py module."""
+
+import os
+import unittest
+
+import color
+import git_config
+
+
+def fixture(*paths):
+    """Return a path relative to test/fixtures."""
+    return os.path.join(os.path.dirname(__file__), "fixtures", *paths)
+
+
+class ColoringTests(unittest.TestCase):
+    """tests of the Coloring class."""
+
+    def setUp(self):
+        """Create a GitConfig object using the test.gitconfig fixture."""
+        config_fixture = fixture("test.gitconfig")
+        self.config = git_config.GitConfig(config_fixture)
+        color.SetDefaultColoring("true")
+        self.color = color.Coloring(self.config, "status")
+
+    def test_Color_Parse_all_params_none(self):
+        """all params are None"""
+        val = self.color._parse(None, None, None, None)
+        self.assertEqual("", val)
+
+    def test_Color_Parse_first_parameter_none(self):
+        """check fg & bg & attr"""
+        val = self.color._parse(None, "black", "red", "ul")
+        self.assertEqual("\x1b[4;30;41m", val)
+
+    def test_Color_Parse_one_entry(self):
+        """check fg"""
+        val = self.color._parse("one", None, None, None)
+        self.assertEqual("\033[33m", val)
+
+    def test_Color_Parse_two_entry(self):
+        """check fg & bg"""
+        val = self.color._parse("two", None, None, None)
+        self.assertEqual("\033[35;46m", val)
+
+    def test_Color_Parse_three_entry(self):
+        """check fg & bg & attr"""
+        val = self.color._parse("three", None, None, None)
+        self.assertEqual("\033[4;30;41m", val)
+
+    def test_Color_Parse_reset_entry(self):
+        """check reset entry"""
+        val = self.color._parse("reset", None, None, None)
+        self.assertEqual("\033[m", val)
+
+    def test_Color_Parse_empty_entry(self):
+        """check empty entry"""
+        val = self.color._parse("none", "blue", "white", "dim")
+        self.assertEqual("\033[2;34;47m", val)
+        val = self.color._parse("empty", "green", "white", "bold")
+        self.assertEqual("\033[1;32;47m", val)

tests/test_editor.py

@@ -1,5 +1,3 @@
-# -*- coding:utf-8 -*-
-#
 # Copyright (C) 2019 The Android Open Source Project
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -16,45 +14,43 @@
 
 """Unittests for the editor.py module."""
 
-from __future__ import print_function
-
 import unittest
 
 from editor import Editor
 
 
 class EditorTestCase(unittest.TestCase):
-  """Take care of resetting Editor state across tests."""
+    """Take care of resetting Editor state across tests."""
 
-  def setUp(self):
-    self.setEditor(None)
+    def setUp(self):
+        self.setEditor(None)
 
-  def tearDown(self):
-    self.setEditor(None)
+    def tearDown(self):
+        self.setEditor(None)
 
-  @staticmethod
-  def setEditor(editor):
-    Editor._editor = editor
+    @staticmethod
+    def setEditor(editor):
+        Editor._editor = editor
 
 
 class GetEditor(EditorTestCase):
-  """Check GetEditor behavior."""
+    """Check GetEditor behavior."""
 
-  def test_basic(self):
-    """Basic checking of _GetEditor."""
-    self.setEditor(':')
-    self.assertEqual(':', Editor._GetEditor())
+    def test_basic(self):
+        """Basic checking of _GetEditor."""
+        self.setEditor(":")
+        self.assertEqual(":", Editor._GetEditor())
 
 
 class EditString(EditorTestCase):
-  """Check EditString behavior."""
+    """Check EditString behavior."""
 
-  def test_no_editor(self):
-    """Check behavior when no editor is available."""
-    self.setEditor(':')
-    self.assertEqual('foo', Editor.EditString('foo'))
+    def test_no_editor(self):
+        """Check behavior when no editor is available."""
+        self.setEditor(":")
+        self.assertEqual("foo", Editor.EditString("foo"))
 
-  def test_cat_editor(self):
-    """Check behavior when editor is `cat`."""
-    self.setEditor('cat')
-    self.assertEqual('foo', Editor.EditString('foo'))
+    def test_cat_editor(self):
+        """Check behavior when editor is `cat`."""
+        self.setEditor("cat")
+        self.assertEqual("foo", Editor.EditString("foo"))

tests/test_error.py

@@ -0,0 +1,70 @@
+# Copyright 2021 The Android Open Source Project
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Unittests for the error.py module."""
+
+import inspect
+import pickle
+import unittest
+
+import command
+import error
+import fetch
+import git_command
+import project
+from subcmds import all_modules
+
+
+imports = all_modules + [
+    error,
+    project,
+    git_command,
+    fetch,
+    command,
+]
+
+
+class PickleTests(unittest.TestCase):
+    """Make sure all our custom exceptions can be pickled."""
+
+    def getExceptions(self):
+        """Return all our custom exceptions."""
+        for entry in imports:
+            for name in dir(entry):
+                cls = getattr(entry, name)
+                if isinstance(cls, type) and issubclass(cls, Exception):
+                    yield cls
+
+    def testExceptionLookup(self):
+        """Make sure our introspection logic works."""
+        classes = list(self.getExceptions())
+        self.assertIn(error.HookError, classes)
+        # Don't assert the exact number to avoid being a change-detector test.
+        self.assertGreater(len(classes), 10)
+
+    def testPickle(self):
+        """Try to pickle all the exceptions."""
+        for cls in self.getExceptions():
+            args = inspect.getfullargspec(cls.__init__).args[1:]
+            obj = cls(*args)
+            p = pickle.dumps(obj)
+            try:
+                newobj = pickle.loads(p)
+            except Exception as e:  # pylint: disable=broad-except
+                self.fail(
+                    "Class %s is unable to be pickled: %s\n"
+                    "Incomplete super().__init__(...) call?" % (cls, e)
+                )
+            self.assertIsInstance(newobj, cls)
+            self.assertEqual(str(obj), str(newobj))

tests/test_git_command.py

@@ -1,5 +1,3 @@
-# -*- coding:utf-8 -*-
-#
 # Copyright 2019 The Android Open Source Project
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -16,63 +14,335 @@
 
 """Unittests for the git_command.py module."""
 
-from __future__ import print_function
-
+import io
+import os
 import re
+import subprocess
 import unittest
+from unittest import mock
+
+import pytest
 
 import git_command
+import wrapper
+
+
+class GitCommandTest(unittest.TestCase):
+    """Tests the GitCommand class (via git_command.git)."""
+
+    def setUp(self):
+        def realpath_mock(val):
+            return val
+
+        mock.patch.object(
+            os.path, "realpath", side_effect=realpath_mock
+        ).start()
+
+    def tearDown(self):
+        mock.patch.stopall()
+
+    def test_alternative_setting_when_matching(self):
+        r = git_command._build_env(
+            objdir=os.path.join("zap", "objects"), gitdir="zap"
+        )
+
+        self.assertIsNone(r.get("GIT_ALTERNATE_OBJECT_DIRECTORIES"))
+        self.assertEqual(
+            r.get("GIT_OBJECT_DIRECTORY"), os.path.join("zap", "objects")
+        )
+
+    def test_alternative_setting_when_different(self):
+        r = git_command._build_env(
+            objdir=os.path.join("wow", "objects"), gitdir="zap"
+        )
+
+        self.assertEqual(
+            r.get("GIT_ALTERNATE_OBJECT_DIRECTORIES"),
+            os.path.join("zap", "objects"),
+        )
+        self.assertEqual(
+            r.get("GIT_OBJECT_DIRECTORY"), os.path.join("wow", "objects")
+        )
+
+
+class GitCommandWaitTest(unittest.TestCase):
+    """Tests the GitCommand class .Wait()"""
+
+    def setUp(self):
+        class MockPopen:
+            rc = 0
+
+            def __init__(self):
+                self.stdout = io.BufferedReader(io.BytesIO())
+                self.stderr = io.BufferedReader(io.BytesIO())
+
+            def communicate(
+                self, input: str = None, timeout: float = None
+            ) -> [str, str]:
+                """Mock communicate fn."""
+                return ["", ""]
+
+            def wait(self, timeout=None):
+                return self.rc
+
+        self.popen = popen = MockPopen()
+
+        def popen_mock(*args, **kwargs):
+            return popen
+
+        def realpath_mock(val):
+            return val
+
+        mock.patch.object(subprocess, "Popen", side_effect=popen_mock).start()
+
+        mock.patch.object(
+            os.path, "realpath", side_effect=realpath_mock
+        ).start()
+
+    def tearDown(self):
+        mock.patch.stopall()
+
+    def test_raises_when_verify_non_zero_result(self):
+        self.popen.rc = 1
+        r = git_command.GitCommand(None, ["status"], verify_command=True)
+        with self.assertRaises(git_command.GitCommandError):
+            r.Wait()
+
+    def test_returns_when_no_verify_non_zero_result(self):
+        self.popen.rc = 1
+        r = git_command.GitCommand(None, ["status"], verify_command=False)
+        self.assertEqual(1, r.Wait())
+
+    def test_default_returns_non_zero_result(self):
+        self.popen.rc = 1
+        r = git_command.GitCommand(None, ["status"])
+        self.assertEqual(1, r.Wait())
+
+
+class GitCommandStreamLogsTest(unittest.TestCase):
+    """Tests the GitCommand class stderr log streaming cases."""
+
+    def setUp(self):
+        self.mock_process = mock.MagicMock()
+        self.mock_process.communicate.return_value = (None, None)
+        self.mock_process.wait.return_value = 0
+
+        self.mock_popen = mock.MagicMock()
+        self.mock_popen.return_value = self.mock_process
+        mock.patch("subprocess.Popen", self.mock_popen).start()
+
+    def tearDown(self):
+        mock.patch.stopall()
+
+    def test_does_not_stream_logs_when_input_is_set(self):
+        git_command.GitCommand(None, ["status"], input="foo")
+
+        self.mock_popen.assert_called_once_with(
+            ["git", "status"],
+            cwd=None,
+            env=mock.ANY,
+            encoding="utf-8",
+            errors="backslashreplace",
+            stdin=subprocess.PIPE,
+            stdout=None,
+            stderr=None,
+        )
+        self.mock_process.communicate.assert_called_once_with(input="foo")
+        self.mock_process.stderr.read1.assert_not_called()
+
+    def test_does_not_stream_logs_when_stdout_is_set(self):
+        git_command.GitCommand(None, ["status"], capture_stdout=True)
+
+        self.mock_popen.assert_called_once_with(
+            ["git", "status"],
+            cwd=None,
+            env=mock.ANY,
+            encoding="utf-8",
+            errors="backslashreplace",
+            stdin=None,
+            stdout=subprocess.PIPE,
+            stderr=None,
+        )
+        self.mock_process.communicate.assert_called_once_with(input=None)
+        self.mock_process.stderr.read1.assert_not_called()
+
+    def test_does_not_stream_logs_when_stderr_is_set(self):
+        git_command.GitCommand(None, ["status"], capture_stderr=True)
+
+        self.mock_popen.assert_called_once_with(
+            ["git", "status"],
+            cwd=None,
+            env=mock.ANY,
+            encoding="utf-8",
+            errors="backslashreplace",
+            stdin=None,
+            stdout=None,
+            stderr=subprocess.PIPE,
+        )
+        self.mock_process.communicate.assert_called_once_with(input=None)
+        self.mock_process.stderr.read1.assert_not_called()
+
+    def test_does_not_stream_logs_when_merge_output_is_set(self):
+        git_command.GitCommand(None, ["status"], merge_output=True)
+
+        self.mock_popen.assert_called_once_with(
+            ["git", "status"],
+            cwd=None,
+            env=mock.ANY,
+            encoding="utf-8",
+            errors="backslashreplace",
+            stdin=None,
+            stdout=None,
+            stderr=subprocess.STDOUT,
+        )
+        self.mock_process.communicate.assert_called_once_with(input=None)
+        self.mock_process.stderr.read1.assert_not_called()
+
+    @mock.patch("sys.stderr")
+    def test_streams_stderr_when_no_stream_is_set(self, mock_stderr):
+        logs = "\n".join(
+            [
+                "Enumerating objects: 5, done.",
+                "Counting objects: 100% (5/5), done.",
+                "Writing objects: 100% (3/3), 330 bytes | 330 KiB/s, done.",
+                "remote: Processing changes: refs: 1, new: 1, done ",
+                "remote: SUCCESS",
+            ]
+        )
+        self.mock_process.stderr = io.BufferedReader(
+            io.BytesIO(bytes(logs, "utf-8"))
+        )
+
+        cmd = git_command.GitCommand(None, ["push"])
+
+        self.mock_popen.assert_called_once_with(
+            ["git", "push"],
+            cwd=None,
+            env=mock.ANY,
+            stdin=None,
+            stdout=None,
+            stderr=subprocess.PIPE,
+        )
+        self.mock_process.communicate.assert_not_called()
+        mock_stderr.write.assert_called_once_with(logs)
+        self.assertEqual(cmd.stderr, logs)
 
 
 class GitCallUnitTest(unittest.TestCase):
-  """Tests the _GitCall class (via git_command.git)."""
+    """Tests the _GitCall class (via git_command.git)."""
 
-  def test_version_tuple(self):
-    """Check git.version_tuple() handling."""
-    ver = git_command.git.version_tuple()
-    self.assertIsNotNone(ver)
+    def test_version_tuple(self):
+        """Check git.version_tuple() handling."""
+        ver = git_command.git.version_tuple()
+        self.assertIsNotNone(ver)
 
-    # We don't dive too deep into the values here to avoid having to update
-    # whenever git versions change.  We do check relative to this min version
-    # as this is what `repo` itself requires via MIN_GIT_VERSION.
-    MIN_GIT_VERSION = (2, 10, 2)
-    self.assertTrue(isinstance(ver.major, int))
-    self.assertTrue(isinstance(ver.minor, int))
-    self.assertTrue(isinstance(ver.micro, int))
+        # We don't dive too deep into the values here to avoid having to update
+        # whenever git versions change.  We do check relative to this min
+        # version as this is what `repo` itself requires via MIN_GIT_VERSION.
+        MIN_GIT_VERSION = (2, 10, 2)
+        self.assertTrue(isinstance(ver.major, int))
+        self.assertTrue(isinstance(ver.minor, int))
+        self.assertTrue(isinstance(ver.micro, int))
 
-    self.assertGreater(ver.major, MIN_GIT_VERSION[0] - 1)
-    self.assertGreaterEqual(ver.micro, 0)
-    self.assertGreaterEqual(ver.major, 0)
+        self.assertGreater(ver.major, MIN_GIT_VERSION[0] - 1)
+        self.assertGreaterEqual(ver.micro, 0)
+        self.assertGreaterEqual(ver.major, 0)
 
-    self.assertGreaterEqual(ver, MIN_GIT_VERSION)
-    self.assertLess(ver, (9999, 9999, 9999))
+        self.assertGreaterEqual(ver, MIN_GIT_VERSION)
+        self.assertLess(ver, (9999, 9999, 9999))
 
-    self.assertNotEqual('', ver.full)
+        self.assertNotEqual("", ver.full)
 
 
 class UserAgentUnitTest(unittest.TestCase):
-  """Tests the UserAgent function."""
+    """Tests the UserAgent function."""
 
-  def test_smoke_os(self):
-    """Make sure UA OS setting returns something useful."""
-    os_name = git_command.user_agent.os
-    # We can't dive too deep because of OS/tool differences, but we can check
-    # the general form.
-    m = re.match(r'^[^ ]+$', os_name)
-    self.assertIsNotNone(m)
+    def test_smoke_os(self):
+        """Make sure UA OS setting returns something useful."""
+        os_name = git_command.user_agent.os
+        # We can't dive too deep because of OS/tool differences, but we can
+        # check the general form.
+        m = re.match(r"^[^ ]+$", os_name)
+        self.assertIsNotNone(m)
 
-  def test_smoke_repo(self):
-    """Make sure repo UA returns something useful."""
-    ua = git_command.user_agent.repo
-    # We can't dive too deep because of OS/tool differences, but we can check
-    # the general form.
-    m = re.match(r'^git-repo/[^ ]+ ([^ ]+) git/[^ ]+ Python/[0-9.]+', ua)
-    self.assertIsNotNone(m)
+    @pytest.mark.skip_cq("TODO(b/266734831): Find out why this fails in CQ")
+    def test_smoke_repo(self):
+        """Make sure repo UA returns something useful."""
+        ua = git_command.user_agent.repo
+        # We can't dive too deep because of OS/tool differences, but we can
+        # check the general form.
+        m = re.match(r"^git-repo/[^ ]+ ([^ ]+) git/[^ ]+ Python/[0-9.]+", ua)
+        self.assertIsNotNone(m)
 
-  def test_smoke_git(self):
-    """Make sure git UA returns something useful."""
-    ua = git_command.user_agent.git
-    # We can't dive too deep because of OS/tool differences, but we can check
-    # the general form.
-    m = re.match(r'^git/[^ ]+ ([^ ]+) git-repo/[^ ]+', ua)
-    self.assertIsNotNone(m)
+    @pytest.mark.skip_cq("TODO(b/266734831): Find out why this fails in CQ")
+    def test_smoke_git(self):
+        """Make sure git UA returns something useful."""
+        ua = git_command.user_agent.git
+        # We can't dive too deep because of OS/tool differences, but we can
+        # check the general form.
+        m = re.match(r"^git/[^ ]+ ([^ ]+) git-repo/[^ ]+", ua)
+        self.assertIsNotNone(m)
+
+
+class GitRequireTests(unittest.TestCase):
+    """Test the git_require helper."""
+
+    def setUp(self):
+        self.wrapper = wrapper.Wrapper()
+        ver = self.wrapper.GitVersion(1, 2, 3, 4)
+        mock.patch.object(
+            git_command.git, "version_tuple", return_value=ver
+        ).start()
+
+    def tearDown(self):
+        mock.patch.stopall()
+
+    def test_older_nonfatal(self):
+        """Test non-fatal require calls with old versions."""
+        self.assertFalse(git_command.git_require((2,)))
+        self.assertFalse(git_command.git_require((1, 3)))
+        self.assertFalse(git_command.git_require((1, 2, 4)))
+        self.assertFalse(git_command.git_require((1, 2, 3, 5)))
+
+    def test_newer_nonfatal(self):
+        """Test non-fatal require calls with newer versions."""
+        self.assertTrue(git_command.git_require((0,)))
+        self.assertTrue(git_command.git_require((1, 0)))
+        self.assertTrue(git_command.git_require((1, 2, 0)))
+        self.assertTrue(git_command.git_require((1, 2, 3, 0)))
+
+    def test_equal_nonfatal(self):
+        """Test require calls with equal values."""
+        self.assertTrue(git_command.git_require((1, 2, 3, 4), fail=False))
+        self.assertTrue(git_command.git_require((1, 2, 3, 4), fail=True))
+
+    def test_older_fatal(self):
+        """Test fatal require calls with old versions."""
+        with self.assertRaises(git_command.GitRequireError) as e:
+            git_command.git_require((2,), fail=True)
+            self.assertNotEqual(0, e.code)
+
+    def test_older_fatal_msg(self):
+        """Test fatal require calls with old versions and message."""
+        with self.assertRaises(git_command.GitRequireError) as e:
+            git_command.git_require((2,), fail=True, msg="so sad")
+            self.assertNotEqual(0, e.code)
+
+
+class GitCommandErrorTest(unittest.TestCase):
+    """Test for the GitCommandError class."""
+
+    def test_augument_stderr(self):
+        self.assertEqual(
+            git_command.GitCommandError(
+                git_stderr="couldn't find remote ref refs/heads/foo"
+            ).suggestion,
+            "Check if the provided ref exists in the remote.",
+        )
+
+        self.assertEqual(
+            git_command.GitCommandError(
+                git_stderr="'foobar' does not appear to be a git repository"
+            ).suggestion,
+            "Are you running this repo command outside of a repo workspace?",
+        )

tests/test_git_config.py

@@ -1,5 +1,3 @@
-# -*- coding:utf-8 -*-
-#
 # Copyright (C) 2009 The Android Open Source Project
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -16,57 +14,177 @@
 
 """Unittests for the git_config.py module."""
 
-from __future__ import print_function
-
 import os
+import tempfile
 import unittest
 
 import git_config
 
+
 def fixture(*paths):
-  """Return a path relative to test/fixtures.
-  """
-  return os.path.join(os.path.dirname(__file__), 'fixtures', *paths)
+    """Return a path relative to test/fixtures."""
+    return os.path.join(os.path.dirname(__file__), "fixtures", *paths)
 
-class GitConfigUnitTest(unittest.TestCase):
-  """Tests the GitConfig class.
-  """
-  def setUp(self):
-    """Create a GitConfig object using the test.gitconfig fixture.
-    """
-    config_fixture = fixture('test.gitconfig')
-    self.config = git_config.GitConfig(config_fixture)
 
-  def test_GetString_with_empty_config_values(self):
-    """
-    Test config entries with no value.
+class GitConfigReadOnlyTests(unittest.TestCase):
+    """Read-only tests of the GitConfig class."""
 
-    [section]
-        empty
+    def setUp(self):
+        """Create a GitConfig object using the test.gitconfig fixture."""
+        config_fixture = fixture("test.gitconfig")
+        self.config = git_config.GitConfig(config_fixture)
 
-    """
-    val = self.config.GetString('section.empty')
-    self.assertEqual(val, None)
+    def test_GetString_with_empty_config_values(self):
+        """
+        Test config entries with no value.
 
-  def test_GetString_with_true_value(self):
-    """
-    Test config entries with a string value.
+        [section]
+            empty
 
-    [section]
-        nonempty = true
+        """
+        val = self.config.GetString("section.empty")
+        self.assertEqual(val, None)
 
-    """
-    val = self.config.GetString('section.nonempty')
-    self.assertEqual(val, 'true')
+    def test_GetString_with_true_value(self):
+        """
+        Test config entries with a string value.
 
-  def test_GetString_from_missing_file(self):
-    """
-    Test missing config file
-    """
-    config_fixture = fixture('not.present.gitconfig')
-    config = git_config.GitConfig(config_fixture)
-    val = config.GetString('empty')
-    self.assertEqual(val, None)
+        [section]
+            nonempty = true
 
-if __name__ == '__main__':
-  unittest.main()
+        """
+        val = self.config.GetString("section.nonempty")
+        self.assertEqual(val, "true")
+
+    def test_GetString_from_missing_file(self):
+        """
+        Test missing config file
+        """
+        config_fixture = fixture("not.present.gitconfig")
+        config = git_config.GitConfig(config_fixture)
+        val = config.GetString("empty")
+        self.assertEqual(val, None)
+
+    def test_GetBoolean_undefined(self):
+        """Test GetBoolean on key that doesn't exist."""
+        self.assertIsNone(self.config.GetBoolean("section.missing"))
+
+    def test_GetBoolean_invalid(self):
+        """Test GetBoolean on invalid boolean value."""
+        self.assertIsNone(self.config.GetBoolean("section.boolinvalid"))
+
+    def test_GetBoolean_true(self):
+        """Test GetBoolean on valid true boolean."""
+        self.assertTrue(self.config.GetBoolean("section.booltrue"))
+
+    def test_GetBoolean_false(self):
+        """Test GetBoolean on valid false boolean."""
+        self.assertFalse(self.config.GetBoolean("section.boolfalse"))
+
+    def test_GetInt_undefined(self):
+        """Test GetInt on key that doesn't exist."""
+        self.assertIsNone(self.config.GetInt("section.missing"))
+
+    def test_GetInt_invalid(self):
+        """Test GetInt on invalid integer value."""
+        self.assertIsNone(self.config.GetBoolean("section.intinvalid"))
+
+    def test_GetInt_valid(self):
+        """Test GetInt on valid integers."""
+        TESTS = (
+            ("inthex", 16),
+            ("inthexk", 16384),
+            ("int", 10),
+            ("intk", 10240),
+            ("intm", 10485760),
+            ("intg", 10737418240),
+        )
+        for key, value in TESTS:
+            self.assertEqual(value, self.config.GetInt(f"section.{key}"))
+
+
+class GitConfigReadWriteTests(unittest.TestCase):
+    """Read/write tests of the GitConfig class."""
+
+    def setUp(self):
+        self.tmpfile = tempfile.NamedTemporaryFile()
+        self.config = self.get_config()
+
+    def get_config(self):
+        """Get a new GitConfig instance."""
+        return git_config.GitConfig(self.tmpfile.name)
+
+    def test_SetString(self):
+        """Test SetString behavior."""
+        # Set a value.
+        self.assertIsNone(self.config.GetString("foo.bar"))
+        self.config.SetString("foo.bar", "val")
+        self.assertEqual("val", self.config.GetString("foo.bar"))
+
+        # Make sure the value was actually written out.
+        config = self.get_config()
+        self.assertEqual("val", config.GetString("foo.bar"))
+
+        # Update the value.
+        self.config.SetString("foo.bar", "valll")
+        self.assertEqual("valll", self.config.GetString("foo.bar"))
+        config = self.get_config()
+        self.assertEqual("valll", config.GetString("foo.bar"))
+
+        # Delete the value.
+        self.config.SetString("foo.bar", None)
+        self.assertIsNone(self.config.GetString("foo.bar"))
+        config = self.get_config()
+        self.assertIsNone(config.GetString("foo.bar"))
+
+    def test_SetBoolean(self):
+        """Test SetBoolean behavior."""
+        # Set a true value.
+        self.assertIsNone(self.config.GetBoolean("foo.bar"))
+        for val in (True, 1):
+            self.config.SetBoolean("foo.bar", val)
+            self.assertTrue(self.config.GetBoolean("foo.bar"))
+
+        # Make sure the value was actually written out.
+        config = self.get_config()
+        self.assertTrue(config.GetBoolean("foo.bar"))
+        self.assertEqual("true", config.GetString("foo.bar"))
+
+        # Set a false value.
+        for val in (False, 0):
+            self.config.SetBoolean("foo.bar", val)
+            self.assertFalse(self.config.GetBoolean("foo.bar"))
+
+        # Make sure the value was actually written out.
+        config = self.get_config()
+        self.assertFalse(config.GetBoolean("foo.bar"))
+        self.assertEqual("false", config.GetString("foo.bar"))
+
+        # Delete the value.
+        self.config.SetBoolean("foo.bar", None)
+        self.assertIsNone(self.config.GetBoolean("foo.bar"))
+        config = self.get_config()
+        self.assertIsNone(config.GetBoolean("foo.bar"))
+
+    def test_GetSyncAnalysisStateData(self):
+        """Test config entries with a sync state analysis data."""
+        superproject_logging_data = {}
+        superproject_logging_data["test"] = False
+        options = type("options", (object,), {})()
+        options.verbose = "true"
+        options.mp_update = "false"
+        TESTS = (
+            ("superproject.test", "false"),
+            ("options.verbose", "true"),
+            ("options.mpupdate", "false"),
+            ("main.version", "1"),
+        )
+        self.config.UpdateSyncAnalysisState(options, superproject_logging_data)
+        sync_data = self.config.GetSyncAnalysisStateData()
+        for key, value in TESTS:
+            self.assertEqual(
+                sync_data[f"{git_config.SYNC_STATE_PREFIX}{key}"], value
+            )
+        self.assertTrue(
+            sync_data[f"{git_config.SYNC_STATE_PREFIX}main.synctime"]
+        )

tests/test_git_superproject.py

@@ -0,0 +1,539 @@
+# Copyright (C) 2021 The Android Open Source Project
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Unittests for the git_superproject.py module."""
+
+import json
+import os
+import platform
+import tempfile
+import unittest
+from unittest import mock
+
+import pytest
+from test_manifest_xml import sort_attributes
+
+import git_superproject
+import git_trace2_event_log
+import manifest_xml
+
+
+class SuperprojectTestCase(unittest.TestCase):
+    """TestCase for the Superproject module."""
+
+    PARENT_SID_KEY = "GIT_TRACE2_PARENT_SID"
+    PARENT_SID_VALUE = "parent_sid"
+    SELF_SID_REGEX = r"repo-\d+T\d+Z-.*"
+    FULL_SID_REGEX = rf"^{PARENT_SID_VALUE}/{SELF_SID_REGEX}"
+
+    def setUp(self):
+        """Set up superproject every time."""
+        self.tempdirobj = tempfile.TemporaryDirectory(prefix="repo_tests")
+        self.tempdir = self.tempdirobj.name
+        self.repodir = os.path.join(self.tempdir, ".repo")
+        self.manifest_file = os.path.join(
+            self.repodir, manifest_xml.MANIFEST_FILE_NAME
+        )
+        os.mkdir(self.repodir)
+        self.platform = platform.system().lower()
+
+        # By default we initialize with the expected case where
+        # repo launches us (so GIT_TRACE2_PARENT_SID is set).
+        env = {
+            self.PARENT_SID_KEY: self.PARENT_SID_VALUE,
+        }
+        self.git_event_log = git_trace2_event_log.EventLog(env=env)
+
+        # The manifest parsing really wants a git repo currently.
+        gitdir = os.path.join(self.repodir, "manifests.git")
+        os.mkdir(gitdir)
+        with open(os.path.join(gitdir, "config"), "w") as fp:
+            fp.write(
+                """[remote "origin"]
+        url = https://localhost:0/manifest
+"""
+            )
+
+        manifest = self.getXmlManifest(
+            """
+<manifest>
+  <remote name="default-remote" fetch="http://localhost" />
+  <default remote="default-remote" revision="refs/heads/main" />
+  <superproject name="superproject"/>
+  <project path="art" name="platform/art" groups="notdefault,platform-"""
+            + self.platform
+            + """
+  " /></manifest>
+"""
+        )
+        self._superproject = git_superproject.Superproject(
+            manifest,
+            name="superproject",
+            remote=manifest.remotes.get("default-remote").ToRemoteSpec(
+                "superproject"
+            ),
+            revision="refs/heads/main",
+        )
+
+    def tearDown(self):
+        """Tear down superproject every time."""
+        self.tempdirobj.cleanup()
+
+    def getXmlManifest(self, data):
+        """Helper to initialize a manifest for testing."""
+        with open(self.manifest_file, "w") as fp:
+            fp.write(data)
+        return manifest_xml.XmlManifest(self.repodir, self.manifest_file)
+
+    def verifyCommonKeys(self, log_entry, expected_event_name, full_sid=True):
+        """Helper function to verify common event log keys."""
+        self.assertIn("event", log_entry)
+        self.assertIn("sid", log_entry)
+        self.assertIn("thread", log_entry)
+        self.assertIn("time", log_entry)
+
+        # Do basic data format validation.
+        self.assertEqual(expected_event_name, log_entry["event"])
+        if full_sid:
+            self.assertRegex(log_entry["sid"], self.FULL_SID_REGEX)
+        else:
+            self.assertRegex(log_entry["sid"], self.SELF_SID_REGEX)
+        self.assertRegex(
+            log_entry["time"], r"^\d+-\d+-\d+T\d+:\d+:\d+\.\d+\+00:00$"
+        )
+
+    def readLog(self, log_path):
+        """Helper function to read log data into a list."""
+        log_data = []
+        with open(log_path, mode="rb") as f:
+            for line in f:
+                log_data.append(json.loads(line))
+        return log_data
+
+    def verifyErrorEvent(self):
+        """Helper to verify that error event is written."""
+
+        with tempfile.TemporaryDirectory(prefix="event_log_tests") as tempdir:
+            log_path = self.git_event_log.Write(path=tempdir)
+            self.log_data = self.readLog(log_path)
+
+        self.assertEqual(len(self.log_data), 2)
+        error_event = self.log_data[1]
+        self.verifyCommonKeys(self.log_data[0], expected_event_name="version")
+        self.verifyCommonKeys(error_event, expected_event_name="error")
+        # Check for 'error' event specific fields.
+        self.assertIn("msg", error_event)
+        self.assertIn("fmt", error_event)
+
+    def test_superproject_get_superproject_no_superproject(self):
+        """Test with no url."""
+        manifest = self.getXmlManifest(
+            """
+<manifest>
+</manifest>
+"""
+        )
+        self.assertIsNone(manifest.superproject)
+
+    @pytest.mark.skip_cq("TODO(b/266734831): Find out why this takes 8m+ in CQ")
+    def test_superproject_get_superproject_invalid_url(self):
+        """Test with an invalid url."""
+        manifest = self.getXmlManifest(
+            """
+<manifest>
+  <remote name="test-remote" fetch="localhost" />
+  <default remote="test-remote" revision="refs/heads/main" />
+  <superproject name="superproject"/>
+</manifest>
+"""
+        )
+        superproject = git_superproject.Superproject(
+            manifest,
+            name="superproject",
+            remote=manifest.remotes.get("test-remote").ToRemoteSpec(
+                "superproject"
+            ),
+            revision="refs/heads/main",
+        )
+        sync_result = superproject.Sync(self.git_event_log)
+        self.assertFalse(sync_result.success)
+        self.assertTrue(sync_result.fatal)
+
+    @pytest.mark.skip_cq("TODO(b/266734831): Find out why this takes 8m+ in CQ")
+    def test_superproject_get_superproject_invalid_branch(self):
+        """Test with an invalid branch."""
+        manifest = self.getXmlManifest(
+            """
+<manifest>
+  <remote name="test-remote" fetch="localhost" />
+  <default remote="test-remote" revision="refs/heads/main" />
+  <superproject name="superproject"/>
+</manifest>
+"""
+        )
+        self._superproject = git_superproject.Superproject(
+            manifest,
+            name="superproject",
+            remote=manifest.remotes.get("test-remote").ToRemoteSpec(
+                "superproject"
+            ),
+            revision="refs/heads/main",
+        )
+        with mock.patch.object(self._superproject, "_branch", "junk"):
+            sync_result = self._superproject.Sync(self.git_event_log)
+            self.assertFalse(sync_result.success)
+            self.assertTrue(sync_result.fatal)
+            self.verifyErrorEvent()
+
+    def test_superproject_get_superproject_mock_init(self):
+        """Test with _Init failing."""
+        with mock.patch.object(self._superproject, "_Init", return_value=False):
+            sync_result = self._superproject.Sync(self.git_event_log)
+            self.assertFalse(sync_result.success)
+            self.assertTrue(sync_result.fatal)
+
+    def test_superproject_get_superproject_mock_fetch(self):
+        """Test with _Fetch failing."""
+        with mock.patch.object(self._superproject, "_Init", return_value=True):
+            os.mkdir(self._superproject._superproject_path)
+            with mock.patch.object(
+                self._superproject, "_Fetch", return_value=False
+            ):
+                sync_result = self._superproject.Sync(self.git_event_log)
+                self.assertFalse(sync_result.success)
+                self.assertTrue(sync_result.fatal)
+
+    def test_superproject_get_all_project_commit_ids_mock_ls_tree(self):
+        """Test with LsTree being a mock."""
+        data = (
+            "120000 blob 158258bdf146f159218e2b90f8b699c4d85b5804\tAndroid.bp\x00"
+            "160000 commit 2c2724cb36cd5a9cec6c852c681efc3b7c6b86ea\tart\x00"
+            "160000 commit e9d25da64d8d365dbba7c8ee00fe8c4473fe9a06\tbootable/recovery\x00"
+            "120000 blob acc2cbdf438f9d2141f0ae424cec1d8fc4b5d97f\tbootstrap.bash\x00"
+            "160000 commit ade9b7a0d874e25fff4bf2552488825c6f111928\tbuild/bazel\x00"
+        )
+        with mock.patch.object(self._superproject, "_Init", return_value=True):
+            with mock.patch.object(
+                self._superproject, "_Fetch", return_value=True
+            ):
+                with mock.patch.object(
+                    self._superproject, "_LsTree", return_value=data
+                ):
+                    commit_ids_result = (
+                        self._superproject._GetAllProjectsCommitIds()
+                    )
+                    self.assertEqual(
+                        commit_ids_result.commit_ids,
+                        {
+                            "art": "2c2724cb36cd5a9cec6c852c681efc3b7c6b86ea",
+                            "bootable/recovery": "e9d25da64d8d365dbba7c8ee00fe8c4473fe9a06",
+                            "build/bazel": "ade9b7a0d874e25fff4bf2552488825c6f111928",
+                        },
+                    )
+                    self.assertFalse(commit_ids_result.fatal)
+
+    def test_superproject_write_manifest_file(self):
+        """Test with writing manifest to a file after setting revisionId."""
+        self.assertEqual(len(self._superproject._manifest.projects), 1)
+        project = self._superproject._manifest.projects[0]
+        project.SetRevisionId("ABCDEF")
+        # Create temporary directory so that it can write the file.
+        os.mkdir(self._superproject._superproject_path)
+        manifest_path = self._superproject._WriteManifestFile()
+        self.assertIsNotNone(manifest_path)
+        with open(manifest_path) as fp:
+            manifest_xml_data = fp.read()
+        self.assertEqual(
+            sort_attributes(manifest_xml_data),
+            '<?xml version="1.0" ?><manifest>'
+            '<remote fetch="http://localhost" name="default-remote"/>'
+            '<default remote="default-remote" revision="refs/heads/main"/>'
+            '<project groups="notdefault,platform-' + self.platform + '" '
+            'name="platform/art" path="art" revision="ABCDEF" upstream="refs/heads/main"/>'
+            '<superproject name="superproject"/>'
+            "</manifest>",
+        )
+
+    def test_superproject_update_project_revision_id(self):
+        """Test with LsTree being a mock."""
+        self.assertEqual(len(self._superproject._manifest.projects), 1)
+        projects = self._superproject._manifest.projects
+        data = (
+            "160000 commit 2c2724cb36cd5a9cec6c852c681efc3b7c6b86ea\tart\x00"
+            "160000 commit e9d25da64d8d365dbba7c8ee00fe8c4473fe9a06\tbootable/recovery\x00"
+        )
+        with mock.patch.object(self._superproject, "_Init", return_value=True):
+            with mock.patch.object(
+                self._superproject, "_Fetch", return_value=True
+            ):
+                with mock.patch.object(
+                    self._superproject, "_LsTree", return_value=data
+                ):
+                    # Create temporary directory so that it can write the file.
+                    os.mkdir(self._superproject._superproject_path)
+                    update_result = self._superproject.UpdateProjectsRevisionId(
+                        projects, self.git_event_log
+                    )
+                    self.assertIsNotNone(update_result.manifest_path)
+                    self.assertFalse(update_result.fatal)
+                    with open(update_result.manifest_path) as fp:
+                        manifest_xml_data = fp.read()
+                    self.assertEqual(
+                        sort_attributes(manifest_xml_data),
+                        '<?xml version="1.0" ?><manifest>'
+                        '<remote fetch="http://localhost" name="default-remote"/>'
+                        '<default remote="default-remote" revision="refs/heads/main"/>'
+                        '<project groups="notdefault,platform-'
+                        + self.platform
+                        + '" '
+                        'name="platform/art" path="art" '
+                        'revision="2c2724cb36cd5a9cec6c852c681efc3b7c6b86ea" upstream="refs/heads/main"/>'
+                        '<superproject name="superproject"/>'
+                        "</manifest>",
+                    )
+
+    def test_superproject_update_project_revision_id_no_superproject_tag(self):
+        """Test update of commit ids of a manifest without superproject tag."""
+        manifest = self.getXmlManifest(
+            """
+<manifest>
+  <remote name="default-remote" fetch="http://localhost" />
+  <default remote="default-remote" revision="refs/heads/main" />
+  <project name="test-name"/>
+</manifest>
+"""
+        )
+        self.maxDiff = None
+        self.assertIsNone(manifest.superproject)
+        self.assertEqual(
+            sort_attributes(manifest.ToXml().toxml()),
+            '<?xml version="1.0" ?><manifest>'
+            '<remote fetch="http://localhost" name="default-remote"/>'
+            '<default remote="default-remote" revision="refs/heads/main"/>'
+            '<project name="test-name"/>'
+            "</manifest>",
+        )
+
+    def test_superproject_update_project_revision_id_from_local_manifest_group(
+        self,
+    ):
+        """Test update of commit ids of a manifest that have local manifest no superproject group."""
+        local_group = manifest_xml.LOCAL_MANIFEST_GROUP_PREFIX + ":local"
+        manifest = self.getXmlManifest(
+            """
+<manifest>
+  <remote name="default-remote" fetch="http://localhost" />
+  <remote name="goog" fetch="http://localhost2" />
+  <default remote="default-remote" revision="refs/heads/main" />
+  <superproject name="superproject"/>
+  <project path="vendor/x" name="platform/vendor/x" remote="goog"
+           groups=\""""
+            + local_group
+            + """
+         " revision="master-with-vendor" clone-depth="1" />
+  <project path="art" name="platform/art" groups="notdefault,platform-"""
+            + self.platform
+            + """
+  " /></manifest>
+"""
+        )
+        self.maxDiff = None
+        self._superproject = git_superproject.Superproject(
+            manifest,
+            name="superproject",
+            remote=manifest.remotes.get("default-remote").ToRemoteSpec(
+                "superproject"
+            ),
+            revision="refs/heads/main",
+        )
+        self.assertEqual(len(self._superproject._manifest.projects), 2)
+        projects = self._superproject._manifest.projects
+        data = "160000 commit 2c2724cb36cd5a9cec6c852c681efc3b7c6b86ea\tart\x00"
+        with mock.patch.object(self._superproject, "_Init", return_value=True):
+            with mock.patch.object(
+                self._superproject, "_Fetch", return_value=True
+            ):
+                with mock.patch.object(
+                    self._superproject, "_LsTree", return_value=data
+                ):
+                    # Create temporary directory so that it can write the file.
+                    os.mkdir(self._superproject._superproject_path)
+                    update_result = self._superproject.UpdateProjectsRevisionId(
+                        projects, self.git_event_log
+                    )
+                    self.assertIsNotNone(update_result.manifest_path)
+                    self.assertFalse(update_result.fatal)
+                    with open(update_result.manifest_path) as fp:
+                        manifest_xml_data = fp.read()
+                    # Verify platform/vendor/x's project revision hasn't
+                    # changed.
+                    self.assertEqual(
+                        sort_attributes(manifest_xml_data),
+                        '<?xml version="1.0" ?><manifest>'
+                        '<remote fetch="http://localhost" name="default-remote"/>'
+                        '<remote fetch="http://localhost2" name="goog"/>'
+                        '<default remote="default-remote" revision="refs/heads/main"/>'
+                        '<project groups="notdefault,platform-'
+                        + self.platform
+                        + '" '
+                        'name="platform/art" path="art" '
+                        'revision="2c2724cb36cd5a9cec6c852c681efc3b7c6b86ea" upstream="refs/heads/main"/>'
+                        '<superproject name="superproject"/>'
+                        "</manifest>",
+                    )
+
+    def test_superproject_update_project_revision_id_with_pinned_manifest(self):
+        """Test update of commit ids of a pinned manifest."""
+        manifest = self.getXmlManifest(
+            """
+<manifest>
+  <remote name="default-remote" fetch="http://localhost" />
+  <default remote="default-remote" revision="refs/heads/main" />
+  <superproject name="superproject"/>
+  <project path="vendor/x" name="platform/vendor/x" revision="" />
+  <project path="vendor/y" name="platform/vendor/y"
+           revision="52d3c9f7c107839ece2319d077de0cd922aa9d8f" />
+  <project path="art" name="platform/art" groups="notdefault,platform-"""
+            + self.platform
+            + """
+  " /></manifest>
+"""
+        )
+        self.maxDiff = None
+        self._superproject = git_superproject.Superproject(
+            manifest,
+            name="superproject",
+            remote=manifest.remotes.get("default-remote").ToRemoteSpec(
+                "superproject"
+            ),
+            revision="refs/heads/main",
+        )
+        self.assertEqual(len(self._superproject._manifest.projects), 3)
+        projects = self._superproject._manifest.projects
+        data = (
+            "160000 commit 2c2724cb36cd5a9cec6c852c681efc3b7c6b86ea\tart\x00"
+            "160000 commit e9d25da64d8d365dbba7c8ee00fe8c4473fe9a06\tvendor/x\x00"
+        )
+        with mock.patch.object(self._superproject, "_Init", return_value=True):
+            with mock.patch.object(
+                self._superproject, "_Fetch", return_value=True
+            ):
+                with mock.patch.object(
+                    self._superproject, "_LsTree", return_value=data
+                ):
+                    # Create temporary directory so that it can write the file.
+                    os.mkdir(self._superproject._superproject_path)
+                    update_result = self._superproject.UpdateProjectsRevisionId(
+                        projects, self.git_event_log
+                    )
+                    self.assertIsNotNone(update_result.manifest_path)
+                    self.assertFalse(update_result.fatal)
+                    with open(update_result.manifest_path) as fp:
+                        manifest_xml_data = fp.read()
+                    # Verify platform/vendor/x's project revision hasn't
+                    # changed.
+                    self.assertEqual(
+                        sort_attributes(manifest_xml_data),
+                        '<?xml version="1.0" ?><manifest>'
+                        '<remote fetch="http://localhost" name="default-remote"/>'
+                        '<default remote="default-remote" revision="refs/heads/main"/>'
+                        '<project groups="notdefault,platform-'
+                        + self.platform
+                        + '" '
+                        'name="platform/art" path="art" '
+                        'revision="2c2724cb36cd5a9cec6c852c681efc3b7c6b86ea" upstream="refs/heads/main"/>'
+                        '<project name="platform/vendor/x" path="vendor/x" '
+                        'revision="e9d25da64d8d365dbba7c8ee00fe8c4473fe9a06" upstream="refs/heads/main"/>'
+                        '<project name="platform/vendor/y" path="vendor/y" '
+                        'revision="52d3c9f7c107839ece2319d077de0cd922aa9d8f"/>'
+                        '<superproject name="superproject"/>'
+                        "</manifest>",
+                    )
+
+    def test_Fetch(self):
+        manifest = self.getXmlManifest(
+            """
+<manifest>
+  <remote name="default-remote" fetch="http://localhost" />
+  <default remote="default-remote" revision="refs/heads/main" />
+  <superproject name="superproject"/>
+  " /></manifest>
+"""
+        )
+        self.maxDiff = None
+        self._superproject = git_superproject.Superproject(
+            manifest,
+            name="superproject",
+            remote=manifest.remotes.get("default-remote").ToRemoteSpec(
+                "superproject"
+            ),
+            revision="refs/heads/main",
+        )
+        os.mkdir(self._superproject._superproject_path)
+        os.mkdir(self._superproject._work_git)
+        with mock.patch.object(self._superproject, "_Init", return_value=True):
+            with mock.patch(
+                "git_superproject.GitCommand", autospec=True
+            ) as mock_git_command:
+                with mock.patch(
+                    "git_superproject.GitRefs.get", autospec=True
+                ) as mock_git_refs:
+                    instance = mock_git_command.return_value
+                    instance.Wait.return_value = 0
+                    mock_git_refs.side_effect = ["", "1234"]
+
+                    self.assertTrue(self._superproject._Fetch())
+                    self.assertEqual(
+                        # TODO: Once we require Python 3.8+,
+                        #  use 'mock_git_command.call_args.args'.
+                        mock_git_command.call_args[0],
+                        (
+                            None,
+                            [
+                                "fetch",
+                                "http://localhost/superproject",
+                                "--depth",
+                                "1",
+                                "--force",
+                                "--no-tags",
+                                "--filter",
+                                "blob:none",
+                                "refs/heads/main:refs/heads/main",
+                            ],
+                        ),
+                    )
+
+                    # If branch for revision exists, set as --negotiation-tip.
+                    self.assertTrue(self._superproject._Fetch())
+                    self.assertEqual(
+                        # TODO: Once we require Python 3.8+,
+                        #  use 'mock_git_command.call_args.args'.
+                        mock_git_command.call_args[0],
+                        (
+                            None,
+                            [
+                                "fetch",
+                                "http://localhost/superproject",
+                                "--depth",
+                                "1",
+                                "--force",
+                                "--no-tags",
+                                "--filter",
+                                "blob:none",
+                                "--negotiation-tip",
+                                "1234",
+                                "refs/heads/main:refs/heads/main",
+                            ],
+                        ),
+                    )

tests/test_git_trace2_event_log.py

@@ -0,0 +1,406 @@
+# Copyright (C) 2020 The Android Open Source Project
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Unittests for the git_trace2_event_log.py module."""
+
+import json
+import os
+import socket
+import tempfile
+import threading
+import unittest
+from unittest import mock
+
+import git_trace2_event_log
+import platform_utils
+
+
+def serverLoggingThread(socket_path, server_ready, received_traces):
+    """Helper function to receive logs over a Unix domain socket.
+
+    Appends received messages on the provided socket and appends to
+    received_traces.
+
+    Args:
+        socket_path: path to a Unix domain socket on which to listen for traces
+        server_ready: a threading.Condition used to signal to the caller that
+            this thread is ready to accept connections
+        received_traces: a list to which received traces will be appended (after
+            decoding to a utf-8 string).
+    """
+    platform_utils.remove(socket_path, missing_ok=True)
+    data = b""
+    with socket.socket(socket.AF_UNIX, socket.SOCK_STREAM) as sock:
+        sock.bind(socket_path)
+        sock.listen(0)
+        with server_ready:
+            server_ready.notify()
+        with sock.accept()[0] as conn:
+            while True:
+                recved = conn.recv(4096)
+                if not recved:
+                    break
+                data += recved
+    received_traces.extend(data.decode("utf-8").splitlines())
+
+
+class EventLogTestCase(unittest.TestCase):
+    """TestCase for the EventLog module."""
+
+    PARENT_SID_KEY = "GIT_TRACE2_PARENT_SID"
+    PARENT_SID_VALUE = "parent_sid"
+    SELF_SID_REGEX = r"repo-\d+T\d+Z-.*"
+    FULL_SID_REGEX = rf"^{PARENT_SID_VALUE}/{SELF_SID_REGEX}"
+
+    def setUp(self):
+        """Load the event_log module every time."""
+        self._event_log_module = None
+        # By default we initialize with the expected case where
+        # repo launches us (so GIT_TRACE2_PARENT_SID is set).
+        env = {
+            self.PARENT_SID_KEY: self.PARENT_SID_VALUE,
+        }
+        self._event_log_module = git_trace2_event_log.EventLog(env=env)
+        self._log_data = None
+
+    def verifyCommonKeys(
+        self, log_entry, expected_event_name=None, full_sid=True
+    ):
+        """Helper function to verify common event log keys."""
+        self.assertIn("event", log_entry)
+        self.assertIn("sid", log_entry)
+        self.assertIn("thread", log_entry)
+        self.assertIn("time", log_entry)
+
+        # Do basic data format validation.
+        if expected_event_name:
+            self.assertEqual(expected_event_name, log_entry["event"])
+        if full_sid:
+            self.assertRegex(log_entry["sid"], self.FULL_SID_REGEX)
+        else:
+            self.assertRegex(log_entry["sid"], self.SELF_SID_REGEX)
+        self.assertRegex(
+            log_entry["time"], r"^\d+-\d+-\d+T\d+:\d+:\d+\.\d+\+00:00$"
+        )
+
+    def readLog(self, log_path):
+        """Helper function to read log data into a list."""
+        log_data = []
+        with open(log_path, mode="rb") as f:
+            for line in f:
+                log_data.append(json.loads(line))
+        return log_data
+
+    def remove_prefix(self, s, prefix):
+        """Return a copy string after removing |prefix| from |s|, if present or
+        the original string."""
+        if s.startswith(prefix):
+            return s[len(prefix) :]
+        else:
+            return s
+
+    def test_initial_state_with_parent_sid(self):
+        """Test initial state when 'GIT_TRACE2_PARENT_SID' is set by parent."""
+        self.assertRegex(self._event_log_module.full_sid, self.FULL_SID_REGEX)
+
+    def test_initial_state_no_parent_sid(self):
+        """Test initial state when 'GIT_TRACE2_PARENT_SID' is not set."""
+        # Setup an empty environment dict (no parent sid).
+        self._event_log_module = git_trace2_event_log.EventLog(env={})
+        self.assertRegex(self._event_log_module.full_sid, self.SELF_SID_REGEX)
+
+    def test_version_event(self):
+        """Test 'version' event data is valid.
+
+        Verify that the 'version' event is written even when no other
+        events are addded.
+
+        Expected event log:
+        <version event>
+        """
+        with tempfile.TemporaryDirectory(prefix="event_log_tests") as tempdir:
+            log_path = self._event_log_module.Write(path=tempdir)
+            self._log_data = self.readLog(log_path)
+
+        # A log with no added events should only have the version entry.
+        self.assertEqual(len(self._log_data), 1)
+        version_event = self._log_data[0]
+        self.verifyCommonKeys(version_event, expected_event_name="version")
+        # Check for 'version' event specific fields.
+        self.assertIn("evt", version_event)
+        self.assertIn("exe", version_event)
+        # Verify "evt" version field is a string.
+        self.assertIsInstance(version_event["evt"], str)
+
+    def test_start_event(self):
+        """Test and validate 'start' event data is valid.
+
+        Expected event log:
+        <version event>
+        <start event>
+        """
+        self._event_log_module.StartEvent([])
+        with tempfile.TemporaryDirectory(prefix="event_log_tests") as tempdir:
+            log_path = self._event_log_module.Write(path=tempdir)
+            self._log_data = self.readLog(log_path)
+
+        self.assertEqual(len(self._log_data), 2)
+        start_event = self._log_data[1]
+        self.verifyCommonKeys(self._log_data[0], expected_event_name="version")
+        self.verifyCommonKeys(start_event, expected_event_name="start")
+        # Check for 'start' event specific fields.
+        self.assertIn("argv", start_event)
+        self.assertTrue(isinstance(start_event["argv"], list))
+
+    def test_exit_event_result_none(self):
+        """Test 'exit' event data is valid when result is None.
+
+        We expect None result to be converted to 0 in the exit event data.
+
+        Expected event log:
+        <version event>
+        <exit event>
+        """
+        self._event_log_module.ExitEvent(None)
+        with tempfile.TemporaryDirectory(prefix="event_log_tests") as tempdir:
+            log_path = self._event_log_module.Write(path=tempdir)
+            self._log_data = self.readLog(log_path)
+
+        self.assertEqual(len(self._log_data), 2)
+        exit_event = self._log_data[1]
+        self.verifyCommonKeys(self._log_data[0], expected_event_name="version")
+        self.verifyCommonKeys(exit_event, expected_event_name="exit")
+        # Check for 'exit' event specific fields.
+        self.assertIn("code", exit_event)
+        # 'None' result should convert to 0 (successful) return code.
+        self.assertEqual(exit_event["code"], 0)
+
+    def test_exit_event_result_integer(self):
+        """Test 'exit' event data is valid when result is an integer.
+
+        Expected event log:
+        <version event>
+        <exit event>
+        """
+        self._event_log_module.ExitEvent(2)
+        with tempfile.TemporaryDirectory(prefix="event_log_tests") as tempdir:
+            log_path = self._event_log_module.Write(path=tempdir)
+            self._log_data = self.readLog(log_path)
+
+        self.assertEqual(len(self._log_data), 2)
+        exit_event = self._log_data[1]
+        self.verifyCommonKeys(self._log_data[0], expected_event_name="version")
+        self.verifyCommonKeys(exit_event, expected_event_name="exit")
+        # Check for 'exit' event specific fields.
+        self.assertIn("code", exit_event)
+        self.assertEqual(exit_event["code"], 2)
+
+    def test_command_event(self):
+        """Test and validate 'command' event data is valid.
+
+        Expected event log:
+        <version event>
+        <command event>
+        """
+        self._event_log_module.CommandEvent(
+            name="repo", subcommands=["init", "this"]
+        )
+        with tempfile.TemporaryDirectory(prefix="event_log_tests") as tempdir:
+            log_path = self._event_log_module.Write(path=tempdir)
+            self._log_data = self.readLog(log_path)
+
+        self.assertEqual(len(self._log_data), 2)
+        command_event = self._log_data[1]
+        self.verifyCommonKeys(self._log_data[0], expected_event_name="version")
+        self.verifyCommonKeys(command_event, expected_event_name="cmd_name")
+        # Check for 'command' event specific fields.
+        self.assertIn("name", command_event)
+        self.assertEqual(command_event["name"], "repo-init-this")
+
+    def test_def_params_event_repo_config(self):
+        """Test 'def_params' event data outputs only repo config keys.
+
+        Expected event log:
+        <version event>
+        <def_param event>
+        <def_param event>
+        """
+        config = {
+            "git.foo": "bar",
+            "repo.partialclone": "true",
+            "repo.partialclonefilter": "blob:none",
+        }
+        self._event_log_module.DefParamRepoEvents(config)
+
+        with tempfile.TemporaryDirectory(prefix="event_log_tests") as tempdir:
+            log_path = self._event_log_module.Write(path=tempdir)
+            self._log_data = self.readLog(log_path)
+
+        self.assertEqual(len(self._log_data), 3)
+        def_param_events = self._log_data[1:]
+        self.verifyCommonKeys(self._log_data[0], expected_event_name="version")
+
+        for event in def_param_events:
+            self.verifyCommonKeys(event, expected_event_name="def_param")
+            # Check for 'def_param' event specific fields.
+            self.assertIn("param", event)
+            self.assertIn("value", event)
+            self.assertTrue(event["param"].startswith("repo."))
+
+    def test_def_params_event_no_repo_config(self):
+        """Test 'def_params' event data won't output non-repo config keys.
+
+        Expected event log:
+        <version event>
+        """
+        config = {
+            "git.foo": "bar",
+            "git.core.foo2": "baz",
+        }
+        self._event_log_module.DefParamRepoEvents(config)
+
+        with tempfile.TemporaryDirectory(prefix="event_log_tests") as tempdir:
+            log_path = self._event_log_module.Write(path=tempdir)
+            self._log_data = self.readLog(log_path)
+
+        self.assertEqual(len(self._log_data), 1)
+        self.verifyCommonKeys(self._log_data[0], expected_event_name="version")
+
+    def test_data_event_config(self):
+        """Test 'data' event data outputs all config keys.
+
+        Expected event log:
+        <version event>
+        <data event>
+        <data event>
+        """
+        config = {
+            "git.foo": "bar",
+            "repo.partialclone": "false",
+            "repo.syncstate.superproject.hassuperprojecttag": "true",
+            "repo.syncstate.superproject.sys.argv": ["--", "sync", "protobuf"],
+        }
+        prefix_value = "prefix"
+        self._event_log_module.LogDataConfigEvents(config, prefix_value)
+
+        with tempfile.TemporaryDirectory(prefix="event_log_tests") as tempdir:
+            log_path = self._event_log_module.Write(path=tempdir)
+            self._log_data = self.readLog(log_path)
+
+        self.assertEqual(len(self._log_data), 5)
+        data_events = self._log_data[1:]
+        self.verifyCommonKeys(self._log_data[0], expected_event_name="version")
+
+        for event in data_events:
+            self.verifyCommonKeys(event)
+            # Check for 'data' event specific fields.
+            self.assertIn("key", event)
+            self.assertIn("value", event)
+            key = event["key"]
+            key = self.remove_prefix(key, f"{prefix_value}/")
+            value = event["value"]
+            self.assertEqual(
+                self._event_log_module.GetDataEventName(value), event["event"]
+            )
+            self.assertTrue(key in config and value == config[key])
+
+    def test_error_event(self):
+        """Test and validate 'error' event data is valid.
+
+        Expected event log:
+        <version event>
+        <error event>
+        """
+        msg = "invalid option: --cahced"
+        fmt = "invalid option: %s"
+        self._event_log_module.ErrorEvent(msg, fmt)
+        with tempfile.TemporaryDirectory(prefix="event_log_tests") as tempdir:
+            log_path = self._event_log_module.Write(path=tempdir)
+            self._log_data = self.readLog(log_path)
+
+        self.assertEqual(len(self._log_data), 2)
+        error_event = self._log_data[1]
+        self.verifyCommonKeys(self._log_data[0], expected_event_name="version")
+        self.verifyCommonKeys(error_event, expected_event_name="error")
+        # Check for 'error' event specific fields.
+        self.assertIn("msg", error_event)
+        self.assertIn("fmt", error_event)
+        self.assertEqual(error_event["msg"], f"RepoErrorEvent:{msg}")
+        self.assertEqual(error_event["fmt"], f"RepoErrorEvent:{fmt}")
+
+    def test_write_with_filename(self):
+        """Test Write() with a path to a file exits with None."""
+        self.assertIsNone(self._event_log_module.Write(path="path/to/file"))
+
+    def test_write_with_git_config(self):
+        """Test Write() uses the git config path when 'git config' call
+        succeeds."""
+        with tempfile.TemporaryDirectory(prefix="event_log_tests") as tempdir:
+            with mock.patch.object(
+                self._event_log_module,
+                "_GetEventTargetPath",
+                return_value=tempdir,
+            ):
+                self.assertEqual(
+                    os.path.dirname(self._event_log_module.Write()), tempdir
+                )
+
+    def test_write_no_git_config(self):
+        """Test Write() with no git config variable present exits with None."""
+        with mock.patch.object(
+            self._event_log_module, "_GetEventTargetPath", return_value=None
+        ):
+            self.assertIsNone(self._event_log_module.Write())
+
+    def test_write_non_string(self):
+        """Test Write() with non-string type for |path| throws TypeError."""
+        with self.assertRaises(TypeError):
+            self._event_log_module.Write(path=1234)
+
+    def test_write_socket(self):
+        """Test Write() with Unix domain socket for |path| and validate received
+        traces."""
+        received_traces = []
+        with tempfile.TemporaryDirectory(
+            prefix="test_server_sockets"
+        ) as tempdir:
+            socket_path = os.path.join(tempdir, "server.sock")
+            server_ready = threading.Condition()
+            # Start "server" listening on Unix domain socket at socket_path.
+            server_thread = threading.Thread(
+                target=serverLoggingThread,
+                args=(socket_path, server_ready, received_traces),
+            )
+            try:
+                server_thread.start()
+
+                with server_ready:
+                    server_ready.wait(timeout=120)
+
+                self._event_log_module.StartEvent([])
+                path = self._event_log_module.Write(
+                    path=f"af_unix:{socket_path}"
+                )
+            finally:
+                server_thread.join(timeout=5)
+
+        self.assertEqual(path, f"af_unix:stream:{socket_path}")
+        self.assertEqual(len(received_traces), 2)
+        version_event = json.loads(received_traces[0])
+        start_event = json.loads(received_traces[1])
+        self.verifyCommonKeys(version_event, expected_event_name="version")
+        self.verifyCommonKeys(start_event, expected_event_name="start")
+        # Check for 'start' event specific fields.
+        self.assertIn("argv", start_event)
+        self.assertIsInstance(start_event["argv"], list)

tests/test_hooks.py

@@ -0,0 +1,55 @@
+# Copyright (C) 2019 The Android Open Source Project
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Unittests for the hooks.py module."""
+
+import unittest
+
+import hooks
+
+
+class RepoHookShebang(unittest.TestCase):
+    """Check shebang parsing in RepoHook."""
+
+    def test_no_shebang(self):
+        """Lines w/out shebangs should be rejected."""
+        DATA = ("", "#\n# foo\n", "# Bad shebang in script\n#!/foo\n")
+        for data in DATA:
+            self.assertIsNone(hooks.RepoHook._ExtractInterpFromShebang(data))
+
+    def test_direct_interp(self):
+        """Lines whose shebang points directly to the interpreter."""
+        DATA = (
+            ("#!/foo", "/foo"),
+            ("#! /foo", "/foo"),
+            ("#!/bin/foo ", "/bin/foo"),
+            ("#! /usr/foo ", "/usr/foo"),
+            ("#! /usr/foo -args", "/usr/foo"),
+        )
+        for shebang, interp in DATA:
+            self.assertEqual(
+                hooks.RepoHook._ExtractInterpFromShebang(shebang), interp
+            )
+
+    def test_env_interp(self):
+        """Lines whose shebang launches through `env`."""
+        DATA = (
+            ("#!/usr/bin/env foo", "foo"),
+            ("#!/bin/env foo", "foo"),
+            ("#! /bin/env /bin/foo ", "/bin/foo"),
+        )
+        for shebang, interp in DATA:
+            self.assertEqual(
+                hooks.RepoHook._ExtractInterpFromShebang(shebang), interp
+            )

tests/test_platform_utils.py

@@ -0,0 +1,52 @@
+# Copyright 2021 The Android Open Source Project
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Unittests for the platform_utils.py module."""
+
+import os
+import tempfile
+import unittest
+
+import platform_utils
+
+
+class RemoveTests(unittest.TestCase):
+    """Check remove() helper."""
+
+    def testMissingOk(self):
+        """Check missing_ok handling."""
+        with tempfile.TemporaryDirectory() as tmpdir:
+            path = os.path.join(tmpdir, "test")
+
+            # Should not fail.
+            platform_utils.remove(path, missing_ok=True)
+
+            # Should fail.
+            self.assertRaises(OSError, platform_utils.remove, path)
+            self.assertRaises(
+                OSError, platform_utils.remove, path, missing_ok=False
+            )
+
+            # Should not fail if it exists.
+            open(path, "w").close()
+            platform_utils.remove(path, missing_ok=True)
+            self.assertFalse(os.path.exists(path))
+
+            open(path, "w").close()
+            platform_utils.remove(path)
+            self.assertFalse(os.path.exists(path))
+
+            open(path, "w").close()
+            platform_utils.remove(path, missing_ok=False)
+            self.assertFalse(os.path.exists(path))

tests/test_project.py

@@ -1,5 +1,3 @@
-# -*- coding:utf-8 -*-
-#
 # Copyright (C) 2019 The Android Open Source Project
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -16,325 +14,523 @@
 
 """Unittests for the project.py module."""
 
-from __future__ import print_function
-
 import contextlib
 import os
-import shutil
+from pathlib import Path
 import subprocess
 import tempfile
 import unittest
 
 import error
+import git_command
 import git_config
+import manifest_xml
+import platform_utils
 import project
 
 
 @contextlib.contextmanager
 def TempGitTree():
-  """Create a new empty git checkout for testing."""
-  # TODO(vapier): Convert this to tempfile.TemporaryDirectory once we drop
-  # Python 2 support entirely.
-  try:
-    tempdir = tempfile.mkdtemp(prefix='repo-tests')
-    subprocess.check_call(['git', 'init'], cwd=tempdir)
-    yield tempdir
-  finally:
-    shutil.rmtree(tempdir)
+    """Create a new empty git checkout for testing."""
+    with tempfile.TemporaryDirectory(prefix="repo-tests") as tempdir:
+        # Tests need to assume, that main is default branch at init,
+        # which is not supported in config until 2.28.
+        cmd = ["git", "init"]
+        if git_command.git_require((2, 28, 0)):
+            cmd += ["--initial-branch=main"]
+        else:
+            # Use template dir for init.
+            templatedir = tempfile.mkdtemp(prefix=".test-template")
+            with open(os.path.join(templatedir, "HEAD"), "w") as fp:
+                fp.write("ref: refs/heads/main\n")
+            cmd += ["--template", templatedir]
+        subprocess.check_call(cmd, cwd=tempdir)
+        yield tempdir
 
 
-class RepoHookShebang(unittest.TestCase):
-  """Check shebang parsing in RepoHook."""
+class FakeProject:
+    """A fake for Project for basic functionality."""
 
-  def test_no_shebang(self):
-    """Lines w/out shebangs should be rejected."""
-    DATA = (
-        '',
-        '# -*- coding:utf-8 -*-\n',
-        '#\n# foo\n',
-        '# Bad shebang in script\n#!/foo\n'
-    )
-    for data in DATA:
-      self.assertIsNone(project.RepoHook._ExtractInterpFromShebang(data))
-
-  def test_direct_interp(self):
-    """Lines whose shebang points directly to the interpreter."""
-    DATA = (
-        ('#!/foo', '/foo'),
-        ('#! /foo', '/foo'),
-        ('#!/bin/foo ', '/bin/foo'),
-        ('#! /usr/foo ', '/usr/foo'),
-        ('#! /usr/foo -args', '/usr/foo'),
-    )
-    for shebang, interp in DATA:
-      self.assertEqual(project.RepoHook._ExtractInterpFromShebang(shebang),
-                       interp)
-
-  def test_env_interp(self):
-    """Lines whose shebang launches through `env`."""
-    DATA = (
-        ('#!/usr/bin/env foo', 'foo'),
-        ('#!/bin/env foo', 'foo'),
-        ('#! /bin/env /bin/foo ', '/bin/foo'),
-    )
-    for shebang, interp in DATA:
-      self.assertEqual(project.RepoHook._ExtractInterpFromShebang(shebang),
-                       interp)
-
-
-class FakeProject(object):
-  """A fake for Project for basic functionality."""
-
-  def __init__(self, worktree):
-    self.worktree = worktree
-    self.gitdir = os.path.join(worktree, '.git')
-    self.name = 'fakeproject'
-    self.work_git = project.Project._GitGetByExec(
-        self, bare=False, gitdir=self.gitdir)
-    self.bare_git = project.Project._GitGetByExec(
-        self, bare=True, gitdir=self.gitdir)
-    self.config = git_config.GitConfig.ForRepository(gitdir=self.gitdir)
+    def __init__(self, worktree):
+        self.worktree = worktree
+        self.gitdir = os.path.join(worktree, ".git")
+        self.name = "fakeproject"
+        self.work_git = project.Project._GitGetByExec(
+            self, bare=False, gitdir=self.gitdir
+        )
+        self.bare_git = project.Project._GitGetByExec(
+            self, bare=True, gitdir=self.gitdir
+        )
+        self.config = git_config.GitConfig.ForRepository(gitdir=self.gitdir)
 
 
 class ReviewableBranchTests(unittest.TestCase):
-  """Check ReviewableBranch behavior."""
+    """Check ReviewableBranch behavior."""
 
-  def test_smoke(self):
-    """A quick run through everything."""
-    with TempGitTree() as tempdir:
-      fakeproj = FakeProject(tempdir)
+    def test_smoke(self):
+        """A quick run through everything."""
+        with TempGitTree() as tempdir:
+            fakeproj = FakeProject(tempdir)
 
-      # Generate some commits.
-      with open(os.path.join(tempdir, 'readme'), 'w') as fp:
-        fp.write('txt')
-      fakeproj.work_git.add('readme')
-      fakeproj.work_git.commit('-mAdd file')
-      fakeproj.work_git.checkout('-b', 'work')
-      fakeproj.work_git.rm('-f', 'readme')
-      fakeproj.work_git.commit('-mDel file')
+            # Generate some commits.
+            with open(os.path.join(tempdir, "readme"), "w") as fp:
+                fp.write("txt")
+            fakeproj.work_git.add("readme")
+            fakeproj.work_git.commit("-mAdd file")
+            fakeproj.work_git.checkout("-b", "work")
+            fakeproj.work_git.rm("-f", "readme")
+            fakeproj.work_git.commit("-mDel file")
 
-      # Start off with the normal details.
-      rb = project.ReviewableBranch(
-          fakeproj, fakeproj.config.GetBranch('work'), 'master')
-      self.assertEqual('work', rb.name)
-      self.assertEqual(1, len(rb.commits))
-      self.assertIn('Del file', rb.commits[0])
-      d = rb.unabbrev_commits
-      self.assertEqual(1, len(d))
-      short, long = next(iter(d.items()))
-      self.assertTrue(long.startswith(short))
-      self.assertTrue(rb.base_exists)
-      # Hard to assert anything useful about this.
-      self.assertTrue(rb.date)
+            # Start off with the normal details.
+            rb = project.ReviewableBranch(
+                fakeproj, fakeproj.config.GetBranch("work"), "main"
+            )
+            self.assertEqual("work", rb.name)
+            self.assertEqual(1, len(rb.commits))
+            self.assertIn("Del file", rb.commits[0])
+            d = rb.unabbrev_commits
+            self.assertEqual(1, len(d))
+            short, long = next(iter(d.items()))
+            self.assertTrue(long.startswith(short))
+            self.assertTrue(rb.base_exists)
+            # Hard to assert anything useful about this.
+            self.assertTrue(rb.date)
 
-      # Now delete the tracking branch!
-      fakeproj.work_git.branch('-D', 'master')
-      rb = project.ReviewableBranch(
-          fakeproj, fakeproj.config.GetBranch('work'), 'master')
-      self.assertEqual(0, len(rb.commits))
-      self.assertFalse(rb.base_exists)
-      # Hard to assert anything useful about this.
-      self.assertTrue(rb.date)
+            # Now delete the tracking branch!
+            fakeproj.work_git.branch("-D", "main")
+            rb = project.ReviewableBranch(
+                fakeproj, fakeproj.config.GetBranch("work"), "main"
+            )
+            self.assertEqual(0, len(rb.commits))
+            self.assertFalse(rb.base_exists)
+            # Hard to assert anything useful about this.
+            self.assertTrue(rb.date)
+
+
+class ProjectTests(unittest.TestCase):
+    """Check Project behavior."""
+
+    def test_encode_patchset_description(self):
+        self.assertEqual(
+            project.Project._encode_patchset_description("abcd00!! +"),
+            "abcd00%21%21_%2b",
+        )
 
 
 class CopyLinkTestCase(unittest.TestCase):
-  """TestCase for stub repo client checkouts.
+    """TestCase for stub repo client checkouts.
 
-  It'll have a layout like:
-    tempdir/          # self.tempdir
-      checkout/       # self.topdir
-        git-project/  # self.worktree
+    It'll have a layout like this:
+      tempdir/          # self.tempdir
+        checkout/       # self.topdir
+          git-project/  # self.worktree
 
-  Attributes:
-    tempdir: A dedicated temporary directory.
-    worktree: The top of the repo client checkout.
-    topdir: The top of a project checkout.
-  """
+    Attributes:
+      tempdir: A dedicated temporary directory.
+      worktree: The top of the repo client checkout.
+      topdir: The top of a project checkout.
+    """
 
-  def setUp(self):
-    self.tempdir = tempfile.mkdtemp(prefix='repo_tests')
-    self.topdir = os.path.join(self.tempdir, 'checkout')
-    self.worktree = os.path.join(self.topdir, 'git-project')
-    os.makedirs(self.topdir)
-    os.makedirs(self.worktree)
+    def setUp(self):
+        self.tempdirobj = tempfile.TemporaryDirectory(prefix="repo_tests")
+        self.tempdir = self.tempdirobj.name
+        self.topdir = os.path.join(self.tempdir, "checkout")
+        self.worktree = os.path.join(self.topdir, "git-project")
+        os.makedirs(self.topdir)
+        os.makedirs(self.worktree)
 
-  def tearDown(self):
-    shutil.rmtree(self.tempdir, ignore_errors=True)
+    def tearDown(self):
+        self.tempdirobj.cleanup()
 
-  @staticmethod
-  def touch(path):
-    with open(path, 'w') as f:
-      pass
+    @staticmethod
+    def touch(path):
+        with open(path, "w"):
+            pass
 
-  def assertExists(self, path, msg=None):
-    """Make sure |path| exists."""
-    if os.path.exists(path):
-      return
+    def assertExists(self, path, msg=None):
+        """Make sure |path| exists."""
+        if os.path.exists(path):
+            return
 
-    if msg is None:
-      msg = ['path is missing: %s' % path]
-      while path != '/':
-        path = os.path.dirname(path)
-        if not path:
-          # If we're given something like "foo", abort once we get to "".
-          break
-        result = os.path.exists(path)
-        msg.append('\tos.path.exists(%s): %s' % (path, result))
-        if result:
-          msg.append('\tcontents: %r' % os.listdir(path))
-          break
-      msg = '\n'.join(msg)
+        if msg is None:
+            msg = ["path is missing: %s" % path]
+            while path != "/":
+                path = os.path.dirname(path)
+                if not path:
+                    # If we're given something like "foo", abort once we get to
+                    # "".
+                    break
+                result = os.path.exists(path)
+                msg.append(f"\tos.path.exists({path}): {result}")
+                if result:
+                    msg.append("\tcontents: %r" % os.listdir(path))
+                    break
+            msg = "\n".join(msg)
 
-    raise self.failureException(msg)
+        raise self.failureException(msg)
 
 
 class CopyFile(CopyLinkTestCase):
-  """Check _CopyFile handling."""
+    """Check _CopyFile handling."""
 
-  def CopyFile(self, src, dest):
-    return project._CopyFile(self.worktree, src, self.topdir, dest)
+    def CopyFile(self, src, dest):
+        return project._CopyFile(self.worktree, src, self.topdir, dest)
 
-  def test_basic(self):
-    """Basic test of copying a file from a project to the toplevel."""
-    src = os.path.join(self.worktree, 'foo.txt')
-    self.touch(src)
-    cf = self.CopyFile('foo.txt', 'foo')
-    cf._Copy()
-    self.assertExists(os.path.join(self.topdir, 'foo'))
+    def test_basic(self):
+        """Basic test of copying a file from a project to the toplevel."""
+        src = os.path.join(self.worktree, "foo.txt")
+        self.touch(src)
+        cf = self.CopyFile("foo.txt", "foo")
+        cf._Copy()
+        self.assertExists(os.path.join(self.topdir, "foo"))
 
-  def test_src_subdir(self):
-    """Copy a file from a subdir of a project."""
-    src = os.path.join(self.worktree, 'bar', 'foo.txt')
-    os.makedirs(os.path.dirname(src))
-    self.touch(src)
-    cf = self.CopyFile('bar/foo.txt', 'new.txt')
-    cf._Copy()
-    self.assertExists(os.path.join(self.topdir, 'new.txt'))
+    def test_src_subdir(self):
+        """Copy a file from a subdir of a project."""
+        src = os.path.join(self.worktree, "bar", "foo.txt")
+        os.makedirs(os.path.dirname(src))
+        self.touch(src)
+        cf = self.CopyFile("bar/foo.txt", "new.txt")
+        cf._Copy()
+        self.assertExists(os.path.join(self.topdir, "new.txt"))
 
-  def test_dest_subdir(self):
-    """Copy a file to a subdir of a checkout."""
-    src = os.path.join(self.worktree, 'foo.txt')
-    self.touch(src)
-    cf = self.CopyFile('foo.txt', 'sub/dir/new.txt')
-    self.assertFalse(os.path.exists(os.path.join(self.topdir, 'sub')))
-    cf._Copy()
-    self.assertExists(os.path.join(self.topdir, 'sub', 'dir', 'new.txt'))
+    def test_dest_subdir(self):
+        """Copy a file to a subdir of a checkout."""
+        src = os.path.join(self.worktree, "foo.txt")
+        self.touch(src)
+        cf = self.CopyFile("foo.txt", "sub/dir/new.txt")
+        self.assertFalse(os.path.exists(os.path.join(self.topdir, "sub")))
+        cf._Copy()
+        self.assertExists(os.path.join(self.topdir, "sub", "dir", "new.txt"))
 
-  def test_update(self):
-    """Make sure changed files get copied again."""
-    src = os.path.join(self.worktree, 'foo.txt')
-    dest = os.path.join(self.topdir, 'bar')
-    with open(src, 'w') as f:
-      f.write('1st')
-    cf = self.CopyFile('foo.txt', 'bar')
-    cf._Copy()
-    self.assertExists(dest)
-    with open(dest) as f:
-      self.assertEqual(f.read(), '1st')
+    def test_update(self):
+        """Make sure changed files get copied again."""
+        src = os.path.join(self.worktree, "foo.txt")
+        dest = os.path.join(self.topdir, "bar")
+        with open(src, "w") as f:
+            f.write("1st")
+        cf = self.CopyFile("foo.txt", "bar")
+        cf._Copy()
+        self.assertExists(dest)
+        with open(dest) as f:
+            self.assertEqual(f.read(), "1st")
 
-    with open(src, 'w') as f:
-      f.write('2nd!')
-    cf._Copy()
-    with open(dest) as f:
-      self.assertEqual(f.read(), '2nd!')
+        with open(src, "w") as f:
+            f.write("2nd!")
+        cf._Copy()
+        with open(dest) as f:
+            self.assertEqual(f.read(), "2nd!")
 
-  def test_src_block_symlink(self):
-    """Do not allow reading from a symlinked path."""
-    src = os.path.join(self.worktree, 'foo.txt')
-    sym = os.path.join(self.worktree, 'sym')
-    self.touch(src)
-    os.symlink('foo.txt', sym)
-    self.assertExists(sym)
-    cf = self.CopyFile('sym', 'foo')
-    self.assertRaises(error.ManifestInvalidPathError, cf._Copy)
+    def test_src_block_symlink(self):
+        """Do not allow reading from a symlinked path."""
+        src = os.path.join(self.worktree, "foo.txt")
+        sym = os.path.join(self.worktree, "sym")
+        self.touch(src)
+        platform_utils.symlink("foo.txt", sym)
+        self.assertExists(sym)
+        cf = self.CopyFile("sym", "foo")
+        self.assertRaises(error.ManifestInvalidPathError, cf._Copy)
 
-  def test_src_block_symlink_traversal(self):
-    """Do not allow reading through a symlink dir."""
-    src = os.path.join(self.worktree, 'bar', 'passwd')
-    os.symlink('/etc', os.path.join(self.worktree, 'bar'))
-    self.assertExists(src)
-    cf = self.CopyFile('bar/foo.txt', 'foo')
-    self.assertRaises(error.ManifestInvalidPathError, cf._Copy)
+    def test_src_block_symlink_traversal(self):
+        """Do not allow reading through a symlink dir."""
+        realfile = os.path.join(self.tempdir, "file.txt")
+        self.touch(realfile)
+        src = os.path.join(self.worktree, "bar", "file.txt")
+        platform_utils.symlink(self.tempdir, os.path.join(self.worktree, "bar"))
+        self.assertExists(src)
+        cf = self.CopyFile("bar/file.txt", "foo")
+        self.assertRaises(error.ManifestInvalidPathError, cf._Copy)
 
-  def test_src_block_dir(self):
-    """Do not allow copying from a directory."""
-    src = os.path.join(self.worktree, 'dir')
-    os.makedirs(src)
-    cf = self.CopyFile('dir', 'foo')
-    self.assertRaises(error.ManifestInvalidPathError, cf._Copy)
+    def test_src_block_copy_from_dir(self):
+        """Do not allow copying from a directory."""
+        src = os.path.join(self.worktree, "dir")
+        os.makedirs(src)
+        cf = self.CopyFile("dir", "foo")
+        self.assertRaises(error.ManifestInvalidPathError, cf._Copy)
 
-  def test_dest_block_symlink(self):
-    """Do not allow writing to a symlink."""
-    src = os.path.join(self.worktree, 'foo.txt')
-    self.touch(src)
-    os.symlink('dest', os.path.join(self.topdir, 'sym'))
-    cf = self.CopyFile('foo.txt', 'sym')
-    self.assertRaises(error.ManifestInvalidPathError, cf._Copy)
+    def test_dest_block_symlink(self):
+        """Do not allow writing to a symlink."""
+        src = os.path.join(self.worktree, "foo.txt")
+        self.touch(src)
+        platform_utils.symlink("dest", os.path.join(self.topdir, "sym"))
+        cf = self.CopyFile("foo.txt", "sym")
+        self.assertRaises(error.ManifestInvalidPathError, cf._Copy)
 
-  def test_dest_block_symlink_traversal(self):
-    """Do not allow writing through a symlink dir."""
-    src = os.path.join(self.worktree, 'foo.txt')
-    self.touch(src)
-    os.symlink('/tmp', os.path.join(self.topdir, 'sym'))
-    cf = self.CopyFile('foo.txt', 'sym/foo.txt')
-    self.assertRaises(error.ManifestInvalidPathError, cf._Copy)
+    def test_dest_block_symlink_traversal(self):
+        """Do not allow writing through a symlink dir."""
+        src = os.path.join(self.worktree, "foo.txt")
+        self.touch(src)
+        platform_utils.symlink(
+            tempfile.gettempdir(), os.path.join(self.topdir, "sym")
+        )
+        cf = self.CopyFile("foo.txt", "sym/foo.txt")
+        self.assertRaises(error.ManifestInvalidPathError, cf._Copy)
 
-  def test_src_block_dir(self):
-    """Do not allow copying to a directory."""
-    src = os.path.join(self.worktree, 'foo.txt')
-    self.touch(src)
-    os.makedirs(os.path.join(self.topdir, 'dir'))
-    cf = self.CopyFile('foo.txt', 'dir')
-    self.assertRaises(error.ManifestInvalidPathError, cf._Copy)
+    def test_src_block_copy_to_dir(self):
+        """Do not allow copying to a directory."""
+        src = os.path.join(self.worktree, "foo.txt")
+        self.touch(src)
+        os.makedirs(os.path.join(self.topdir, "dir"))
+        cf = self.CopyFile("foo.txt", "dir")
+        self.assertRaises(error.ManifestInvalidPathError, cf._Copy)
 
 
 class LinkFile(CopyLinkTestCase):
-  """Check _LinkFile handling."""
+    """Check _LinkFile handling."""
 
-  def LinkFile(self, src, dest):
-    return project._LinkFile(self.worktree, src, self.topdir, dest)
+    def LinkFile(self, src, dest):
+        return project._LinkFile(self.worktree, src, self.topdir, dest)
 
-  def test_basic(self):
-    """Basic test of linking a file from a project into the toplevel."""
-    src = os.path.join(self.worktree, 'foo.txt')
-    self.touch(src)
-    lf = self.LinkFile('foo.txt', 'foo')
-    lf._Link()
-    dest = os.path.join(self.topdir, 'foo')
-    self.assertExists(dest)
-    self.assertTrue(os.path.islink(dest))
-    self.assertEqual('git-project/foo.txt', os.readlink(dest))
+    def test_basic(self):
+        """Basic test of linking a file from a project into the toplevel."""
+        src = os.path.join(self.worktree, "foo.txt")
+        self.touch(src)
+        lf = self.LinkFile("foo.txt", "foo")
+        lf._Link()
+        dest = os.path.join(self.topdir, "foo")
+        self.assertExists(dest)
+        self.assertTrue(os.path.islink(dest))
+        self.assertEqual(
+            os.path.join("git-project", "foo.txt"), os.readlink(dest)
+        )
 
-  def test_src_subdir(self):
-    """Link to a file in a subdir of a project."""
-    src = os.path.join(self.worktree, 'bar', 'foo.txt')
-    os.makedirs(os.path.dirname(src))
-    self.touch(src)
-    lf = self.LinkFile('bar/foo.txt', 'foo')
-    lf._Link()
-    self.assertExists(os.path.join(self.topdir, 'foo'))
+    def test_src_subdir(self):
+        """Link to a file in a subdir of a project."""
+        src = os.path.join(self.worktree, "bar", "foo.txt")
+        os.makedirs(os.path.dirname(src))
+        self.touch(src)
+        lf = self.LinkFile("bar/foo.txt", "foo")
+        lf._Link()
+        self.assertExists(os.path.join(self.topdir, "foo"))
 
-  def test_dest_subdir(self):
-    """Link a file to a subdir of a checkout."""
-    src = os.path.join(self.worktree, 'foo.txt')
-    self.touch(src)
-    lf = self.LinkFile('foo.txt', 'sub/dir/foo/bar')
-    self.assertFalse(os.path.exists(os.path.join(self.topdir, 'sub')))
-    lf._Link()
-    self.assertExists(os.path.join(self.topdir, 'sub', 'dir', 'foo', 'bar'))
+    def test_src_self(self):
+        """Link to the project itself."""
+        dest = os.path.join(self.topdir, "foo", "bar")
+        lf = self.LinkFile(".", "foo/bar")
+        lf._Link()
+        self.assertExists(dest)
+        self.assertEqual(os.path.join("..", "git-project"), os.readlink(dest))
 
-  def test_update(self):
-    """Make sure changed targets get updated."""
-    dest = os.path.join(self.topdir, 'sym')
+    def test_dest_subdir(self):
+        """Link a file to a subdir of a checkout."""
+        src = os.path.join(self.worktree, "foo.txt")
+        self.touch(src)
+        lf = self.LinkFile("foo.txt", "sub/dir/foo/bar")
+        self.assertFalse(os.path.exists(os.path.join(self.topdir, "sub")))
+        lf._Link()
+        self.assertExists(os.path.join(self.topdir, "sub", "dir", "foo", "bar"))
 
-    src = os.path.join(self.worktree, 'foo.txt')
-    self.touch(src)
-    lf = self.LinkFile('foo.txt', 'sym')
-    lf._Link()
-    self.assertEqual('git-project/foo.txt', os.readlink(dest))
+    def test_src_block_relative(self):
+        """Do not allow relative symlinks."""
+        BAD_SOURCES = (
+            "./",
+            "..",
+            "../",
+            "foo/.",
+            "foo/./bar",
+            "foo/..",
+            "foo/../foo",
+        )
+        for src in BAD_SOURCES:
+            lf = self.LinkFile(src, "foo")
+            self.assertRaises(error.ManifestInvalidPathError, lf._Link)
 
-    # Point the symlink somewhere else.
-    os.unlink(dest)
-    os.symlink('/', dest)
-    lf._Link()
-    self.assertEqual('git-project/foo.txt', os.readlink(dest))
+    def test_update(self):
+        """Make sure changed targets get updated."""
+        dest = os.path.join(self.topdir, "sym")
+
+        src = os.path.join(self.worktree, "foo.txt")
+        self.touch(src)
+        lf = self.LinkFile("foo.txt", "sym")
+        lf._Link()
+        self.assertEqual(
+            os.path.join("git-project", "foo.txt"), os.readlink(dest)
+        )
+
+        # Point the symlink somewhere else.
+        os.unlink(dest)
+        platform_utils.symlink(self.tempdir, dest)
+        lf._Link()
+        self.assertEqual(
+            os.path.join("git-project", "foo.txt"), os.readlink(dest)
+        )
+
+
+class MigrateWorkTreeTests(unittest.TestCase):
+    """Check _MigrateOldWorkTreeGitDir handling."""
+
+    _SYMLINKS = {
+        "config",
+        "description",
+        "hooks",
+        "info",
+        "logs",
+        "objects",
+        "packed-refs",
+        "refs",
+        "rr-cache",
+        "shallow",
+        "svn",
+    }
+    _FILES = {
+        "COMMIT_EDITMSG",
+        "FETCH_HEAD",
+        "HEAD",
+        "index",
+        "ORIG_HEAD",
+        "unknown-file-should-be-migrated",
+    }
+    _CLEAN_FILES = {
+        "a-vim-temp-file~",
+        "#an-emacs-temp-file#",
+    }
+
+    @classmethod
+    @contextlib.contextmanager
+    def _simple_layout(cls):
+        """Create a simple repo client checkout to test against."""
+        with tempfile.TemporaryDirectory() as tempdir:
+            tempdir = Path(tempdir)
+
+            gitdir = tempdir / ".repo/projects/src/test.git"
+            gitdir.mkdir(parents=True)
+            cmd = ["git", "init", "--bare", str(gitdir)]
+            subprocess.check_call(cmd)
+
+            dotgit = tempdir / "src/test/.git"
+            dotgit.mkdir(parents=True)
+            for name in cls._SYMLINKS:
+                (dotgit / name).symlink_to(
+                    f"../../../.repo/projects/src/test.git/{name}"
+                )
+            for name in cls._FILES | cls._CLEAN_FILES:
+                (dotgit / name).write_text(name)
+
+            yield tempdir
+
+    def test_standard(self):
+        """Migrate a standard checkout that we expect."""
+        with self._simple_layout() as tempdir:
+            dotgit = tempdir / "src/test/.git"
+            project.Project._MigrateOldWorkTreeGitDir(str(dotgit))
+
+            # Make sure the dir was transformed into a symlink.
+            self.assertTrue(dotgit.is_symlink())
+            self.assertEqual(
+                os.readlink(dotgit),
+                os.path.normpath("../../.repo/projects/src/test.git"),
+            )
+
+            # Make sure files were moved over.
+            gitdir = tempdir / ".repo/projects/src/test.git"
+            for name in self._FILES:
+                self.assertEqual(name, (gitdir / name).read_text())
+            # Make sure files were removed.
+            for name in self._CLEAN_FILES:
+                self.assertFalse((gitdir / name).exists())
+
+    def test_unknown(self):
+        """A checkout with unknown files should abort."""
+        with self._simple_layout() as tempdir:
+            dotgit = tempdir / "src/test/.git"
+            (tempdir / ".repo/projects/src/test.git/random-file").write_text(
+                "one"
+            )
+            (dotgit / "random-file").write_text("two")
+            with self.assertRaises(error.GitError):
+                project.Project._MigrateOldWorkTreeGitDir(str(dotgit))
+
+            # Make sure no content was actually changed.
+            self.assertTrue(dotgit.is_dir())
+            for name in self._FILES:
+                self.assertTrue((dotgit / name).is_file())
+            for name in self._CLEAN_FILES:
+                self.assertTrue((dotgit / name).is_file())
+            for name in self._SYMLINKS:
+                self.assertTrue((dotgit / name).is_symlink())
+
+
+class ManifestPropertiesFetchedCorrectly(unittest.TestCase):
+    """Ensure properties are fetched properly."""
+
+    def setUpManifest(self, tempdir):
+        repodir = os.path.join(tempdir, ".repo")
+        manifest_dir = os.path.join(repodir, "manifests")
+        manifest_file = os.path.join(repodir, manifest_xml.MANIFEST_FILE_NAME)
+        os.mkdir(repodir)
+        os.mkdir(manifest_dir)
+        manifest = manifest_xml.XmlManifest(repodir, manifest_file)
+
+        return project.ManifestProject(
+            manifest, "test/manifest", os.path.join(tempdir, ".git"), tempdir
+        )
+
+    def test_manifest_config_properties(self):
+        """Test we are fetching the manifest config properties correctly."""
+
+        with TempGitTree() as tempdir:
+            fakeproj = self.setUpManifest(tempdir)
+
+            # Set property using the expected Set method, then ensure
+            # the porperty functions are using the correct Get methods.
+            fakeproj.config.SetString(
+                "manifest.standalone", "https://chicken/manifest.git"
+            )
+            self.assertEqual(
+                fakeproj.standalone_manifest_url, "https://chicken/manifest.git"
+            )
+
+            fakeproj.config.SetString(
+                "manifest.groups", "test-group, admin-group"
+            )
+            self.assertEqual(
+                fakeproj.manifest_groups, "test-group, admin-group"
+            )
+
+            fakeproj.config.SetString("repo.reference", "mirror/ref")
+            self.assertEqual(fakeproj.reference, "mirror/ref")
+
+            fakeproj.config.SetBoolean("repo.dissociate", False)
+            self.assertFalse(fakeproj.dissociate)
+
+            fakeproj.config.SetBoolean("repo.archive", False)
+            self.assertFalse(fakeproj.archive)
+
+            fakeproj.config.SetBoolean("repo.mirror", False)
+            self.assertFalse(fakeproj.mirror)
+
+            fakeproj.config.SetBoolean("repo.worktree", False)
+            self.assertFalse(fakeproj.use_worktree)
+
+            fakeproj.config.SetBoolean("repo.clonebundle", False)
+            self.assertFalse(fakeproj.clone_bundle)
+
+            fakeproj.config.SetBoolean("repo.submodules", False)
+            self.assertFalse(fakeproj.submodules)
+
+            fakeproj.config.SetBoolean("repo.git-lfs", False)
+            self.assertFalse(fakeproj.git_lfs)
+
+            fakeproj.config.SetBoolean("repo.superproject", False)
+            self.assertFalse(fakeproj.use_superproject)
+
+            fakeproj.config.SetBoolean("repo.partialclone", False)
+            self.assertFalse(fakeproj.partial_clone)
+
+            fakeproj.config.SetString("repo.depth", "48")
+            self.assertEqual(fakeproj.depth, 48)
+
+            fakeproj.config.SetString("repo.depth", "invalid_depth")
+            self.assertEqual(fakeproj.depth, None)
+
+            fakeproj.config.SetString("repo.clonefilter", "blob:limit=10M")
+            self.assertEqual(fakeproj.clone_filter, "blob:limit=10M")
+
+            fakeproj.config.SetString(
+                "repo.partialcloneexclude", "third_party/big_repo"
+            )
+            self.assertEqual(
+                fakeproj.partial_clone_exclude, "third_party/big_repo"
+            )
+
+            fakeproj.config.SetString("manifest.platform", "auto")
+            self.assertEqual(fakeproj.manifest_platform, "auto")

tests/test_repo_logging.py

@@ -0,0 +1,101 @@
+# Copyright (C) 2023 The Android Open Source Project
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Unit test for repo_logging module."""
+
+import contextlib
+import io
+import logging
+import unittest
+from unittest import mock
+
+from color import SetDefaultColoring
+from error import RepoExitError
+from repo_logging import RepoLogger
+
+
+class TestRepoLogger(unittest.TestCase):
+    @mock.patch.object(RepoLogger, "error")
+    def test_log_aggregated_errors_logs_aggregated_errors(self, mock_error):
+        """Test if log_aggregated_errors logs a list of aggregated errors."""
+        logger = RepoLogger(__name__)
+        logger.log_aggregated_errors(
+            RepoExitError(
+                aggregate_errors=[
+                    Exception("foo"),
+                    Exception("bar"),
+                    Exception("baz"),
+                    Exception("hello"),
+                    Exception("world"),
+                    Exception("test"),
+                ]
+            )
+        )
+
+        mock_error.assert_has_calls(
+            [
+                mock.call("=" * 80),
+                mock.call(
+                    "Repo command failed due to the following `%s` errors:",
+                    "RepoExitError",
+                ),
+                mock.call("foo\nbar\nbaz\nhello\nworld"),
+                mock.call("+%d additional errors...", 1),
+            ]
+        )
+
+    @mock.patch.object(RepoLogger, "error")
+    def test_log_aggregated_errors_logs_single_error(self, mock_error):
+        """Test if log_aggregated_errors logs empty aggregated_errors."""
+        logger = RepoLogger(__name__)
+        logger.log_aggregated_errors(RepoExitError())
+
+        mock_error.assert_has_calls(
+            [
+                mock.call("=" * 80),
+                mock.call("Repo command failed: %s", "RepoExitError"),
+            ]
+        )
+
+    def test_log_with_format_string(self):
+        """Test different log levels with format strings."""
+
+        # Set color output to "always" for consistent test results.
+        # This ensures the logger's behavior is uniform across different
+        # environments and git configurations.
+        SetDefaultColoring("always")
+
+        # Regex pattern to match optional ANSI color codes.
+        # \033    - Escape character
+        # \[      - Opening square bracket
+        # [0-9;]* - Zero or more digits or semicolons
+        # m       - Ending 'm' character
+        # ?       - Makes the entire group optional
+        opt_color = r"(\033\[[0-9;]*m)?"
+
+        for level in (logging.INFO, logging.WARN, logging.ERROR):
+            name = logging.getLevelName(level)
+
+            with self.subTest(level=level, name=name):
+                output = io.StringIO()
+
+                with contextlib.redirect_stderr(output):
+                    logger = RepoLogger(__name__)
+                    logger.log(level, "%s", "100% pass")
+
+                self.assertRegex(
+                    output.getvalue().strip(),
+                    f"^{opt_color}100% pass{opt_color}$",
+                    f"failed for level {name}",
+                )

tests/test_repo_trace.py

@@ -0,0 +1,60 @@
+# Copyright 2022 The Android Open Source Project
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Unittests for the repo_trace.py module."""
+
+import os
+import unittest
+from unittest import mock
+
+import repo_trace
+
+
+class TraceTests(unittest.TestCase):
+    """Check Trace behavior."""
+
+    def testTrace_MaxSizeEnforced(self):
+        content = "git chicken"
+
+        with repo_trace.Trace(content, first_trace=True):
+            pass
+        first_trace_size = os.path.getsize(repo_trace._TRACE_FILE)
+
+        with repo_trace.Trace(content):
+            pass
+        self.assertGreater(
+            os.path.getsize(repo_trace._TRACE_FILE), first_trace_size
+        )
+
+        # Check we clear everything is the last chunk is larger than _MAX_SIZE.
+        with mock.patch("repo_trace._MAX_SIZE", 0):
+            with repo_trace.Trace(content, first_trace=True):
+                pass
+            self.assertEqual(
+                first_trace_size, os.path.getsize(repo_trace._TRACE_FILE)
+            )
+
+            # Check we only clear the chunks we need to.
+            repo_trace._MAX_SIZE = (first_trace_size + 1) / (1024 * 1024)
+            with repo_trace.Trace(content, first_trace=True):
+                pass
+            self.assertEqual(
+                first_trace_size * 2, os.path.getsize(repo_trace._TRACE_FILE)
+            )
+
+            with repo_trace.Trace(content, first_trace=True):
+                pass
+            self.assertEqual(
+                first_trace_size * 2, os.path.getsize(repo_trace._TRACE_FILE)
+            )

tests/test_ssh.py

@@ -0,0 +1,80 @@
+# Copyright 2019 The Android Open Source Project
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Unittests for the ssh.py module."""
+
+import multiprocessing
+import subprocess
+import unittest
+from unittest import mock
+
+import ssh
+
+
+class SshTests(unittest.TestCase):
+    """Tests the ssh functions."""
+
+    def test_parse_ssh_version(self):
+        """Check _parse_ssh_version() handling."""
+        ver = ssh._parse_ssh_version("Unknown\n")
+        self.assertEqual(ver, ())
+        ver = ssh._parse_ssh_version("OpenSSH_1.0\n")
+        self.assertEqual(ver, (1, 0))
+        ver = ssh._parse_ssh_version(
+            "OpenSSH_6.6.1p1 Ubuntu-2ubuntu2.13, OpenSSL 1.0.1f 6 Jan 2014\n"
+        )
+        self.assertEqual(ver, (6, 6, 1))
+        ver = ssh._parse_ssh_version(
+            "OpenSSH_7.6p1 Ubuntu-4ubuntu0.3, OpenSSL 1.0.2n  7 Dec 2017\n"
+        )
+        self.assertEqual(ver, (7, 6))
+        ver = ssh._parse_ssh_version("OpenSSH_9.0p1, LibreSSL 3.3.6\n")
+        self.assertEqual(ver, (9, 0))
+
+    def test_version(self):
+        """Check version() handling."""
+        with mock.patch("ssh._run_ssh_version", return_value="OpenSSH_1.2\n"):
+            self.assertEqual(ssh.version(), (1, 2))
+
+    def test_context_manager_empty(self):
+        """Verify context manager with no clients works correctly."""
+        with multiprocessing.Manager() as manager:
+            with ssh.ProxyManager(manager):
+                pass
+
+    def test_context_manager_child_cleanup(self):
+        """Verify orphaned clients & masters get cleaned up."""
+        with multiprocessing.Manager() as manager:
+            with ssh.ProxyManager(manager) as ssh_proxy:
+                client = subprocess.Popen(["sleep", "964853320"])
+                ssh_proxy.add_client(client)
+                master = subprocess.Popen(["sleep", "964853321"])
+                ssh_proxy.add_master(master)
+        # If the process still exists, these will throw timeout errors.
+        client.wait(0)
+        master.wait(0)
+
+    def test_ssh_sock(self):
+        """Check sock() function."""
+        manager = multiprocessing.Manager()
+        proxy = ssh.ProxyManager(manager)
+        with mock.patch("tempfile.mkdtemp", return_value="/tmp/foo"):
+            # Old ssh version uses port.
+            with mock.patch("ssh.version", return_value=(6, 6)):
+                self.assertTrue(proxy.sock().endswith("%p"))
+
+            proxy._sock_path = None
+            # New ssh version uses hash.
+            with mock.patch("ssh.version", return_value=(6, 7)):
+                self.assertTrue(proxy.sock().endswith("%C"))

tests/test_subcmds.py

@@ -0,0 +1,132 @@
+# Copyright (C) 2020 The Android Open Source Project
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Unittests for the subcmds module (mostly __init__.py than subcommands)."""
+
+import optparse
+import unittest
+
+import subcmds
+
+
+class AllCommands(unittest.TestCase):
+    """Check registered all_commands."""
+
+    def test_required_basic(self):
+        """Basic checking of registered commands."""
+        # NB: We don't test all subcommands as we want to avoid "change
+        # detection" tests, so we just look for the most common/important ones
+        # here that are unlikely to ever change.
+        for cmd in {"cherry-pick", "help", "init", "start", "sync", "upload"}:
+            self.assertIn(cmd, subcmds.all_commands)
+
+    def test_naming(self):
+        """Verify we don't add things that we shouldn't."""
+        for cmd in subcmds.all_commands:
+            # Reject filename suffixes like "help.py".
+            self.assertNotIn(".", cmd)
+
+            # Make sure all '_' were converted to '-'.
+            self.assertNotIn("_", cmd)
+
+            # Reject internal python paths like "__init__".
+            self.assertFalse(cmd.startswith("__"))
+
+    def test_help_desc_style(self):
+        """Force some consistency in option descriptions.
+
+        Python's optparse & argparse has a few default options like --help.
+        Their option description text uses lowercase sentence fragments, so
+        enforce our options follow the same style so UI is consistent.
+
+        We enforce:
+        * Text starts with lowercase.
+        * Text doesn't end with period.
+        """
+        for name, cls in subcmds.all_commands.items():
+            cmd = cls()
+            parser = cmd.OptionParser
+            for option in parser.option_list:
+                if option.help == optparse.SUPPRESS_HELP:
+                    continue
+
+                c = option.help[0]
+                self.assertEqual(
+                    c.lower(),
+                    c,
+                    msg=f"subcmds/{name}.py: {option.get_opt_string()}: "
+                    f'help text should start with lowercase: "{option.help}"',
+                )
+
+                self.assertNotEqual(
+                    option.help[-1],
+                    ".",
+                    msg=f"subcmds/{name}.py: {option.get_opt_string()}: "
+                    f'help text should not end in a period: "{option.help}"',
+                )
+
+    def test_cli_option_style(self):
+        """Force some consistency in option flags."""
+        for name, cls in subcmds.all_commands.items():
+            cmd = cls()
+            parser = cmd.OptionParser
+            for option in parser.option_list:
+                for opt in option._long_opts:
+                    self.assertNotIn(
+                        "_",
+                        opt,
+                        msg=f"subcmds/{name}.py: {opt}: only use dashes in "
+                        "options, not underscores",
+                    )
+
+    def test_cli_option_dest(self):
+        """Block redundant dest= arguments."""
+
+        def _check_dest(opt):
+            if opt.dest is None or not opt._long_opts:
+                return
+
+            long = opt._long_opts[0]
+            assert long.startswith("--")
+            # This matches optparse's behavior.
+            implicit_dest = long[2:].replace("-", "_")
+            if implicit_dest == opt.dest:
+                bad_opts.append((str(opt), opt.dest))
+
+        # Hook the option check list.
+        optparse.Option.CHECK_METHODS.insert(0, _check_dest)
+
+        # Gather all the bad options up front so people can see all bad options
+        # instead of failing at the first one.
+        all_bad_opts = {}
+        for name, cls in subcmds.all_commands.items():
+            bad_opts = all_bad_opts[name] = []
+            cmd = cls()
+            # Trigger construction of parser.
+            cmd.OptionParser
+
+        errmsg = None
+        for name, bad_opts in sorted(all_bad_opts.items()):
+            if bad_opts:
+                if not errmsg:
+                    errmsg = "Omit redundant dest= when defining options.\n"
+                errmsg += f"\nSubcommand {name} (subcmds/{name}.py):\n"
+                errmsg += "".join(
+                    f"    {opt}: dest='{dest}'\n" for opt, dest in bad_opts
+                )
+        if errmsg:
+            self.fail(errmsg)
+
+        # Make sure we aren't popping the wrong stuff.
+        assert optparse.Option.CHECK_METHODS.pop(0) is _check_dest

tests/test_subcmds_forall.py

@@ -0,0 +1,156 @@
+# Copyright (C) 2024 The Android Open Source Project
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Unittests for the forall subcmd."""
+
+from io import StringIO
+import os
+from shutil import rmtree
+import subprocess
+import tempfile
+import unittest
+from unittest import mock
+
+import git_command
+import manifest_xml
+import project
+import subcmds
+
+
+class AllCommands(unittest.TestCase):
+    """Check registered all_commands."""
+
+    def setUp(self):
+        """Common setup."""
+        self.tempdirobj = tempfile.TemporaryDirectory(prefix="forall_tests")
+        self.tempdir = self.tempdirobj.name
+        self.repodir = os.path.join(self.tempdir, ".repo")
+        self.manifest_dir = os.path.join(self.repodir, "manifests")
+        self.manifest_file = os.path.join(
+            self.repodir, manifest_xml.MANIFEST_FILE_NAME
+        )
+        self.local_manifest_dir = os.path.join(
+            self.repodir, manifest_xml.LOCAL_MANIFESTS_DIR_NAME
+        )
+        os.mkdir(self.repodir)
+        os.mkdir(self.manifest_dir)
+
+    def tearDown(self):
+        """Common teardown."""
+        rmtree(self.tempdir, ignore_errors=True)
+
+    def initTempGitTree(self, git_dir):
+        """Create a new empty git checkout for testing."""
+
+        # Tests need to assume, that main is default branch at init,
+        # which is not supported in config until 2.28.
+        cmd = ["git", "init", "-q"]
+        if git_command.git_require((2, 28, 0)):
+            cmd += ["--initial-branch=main"]
+        else:
+            # Use template dir for init
+            templatedir = os.path.join(self.tempdirobj.name, ".test-template")
+            os.makedirs(templatedir)
+            with open(os.path.join(templatedir, "HEAD"), "w") as fp:
+                fp.write("ref: refs/heads/main\n")
+            cmd += ["--template", templatedir]
+        cmd += [git_dir]
+        subprocess.check_call(cmd)
+
+    def getXmlManifestWith8Projects(self):
+        """Create and return a setup of 8 projects with enough dummy
+        files and setup to execute forall."""
+
+        # Set up a manifest git dir for parsing to work
+        gitdir = os.path.join(self.repodir, "manifests.git")
+        os.mkdir(gitdir)
+        with open(os.path.join(gitdir, "config"), "w") as fp:
+            fp.write(
+                """[remote "origin"]
+                    url = https://localhost:0/manifest
+                    verbose = false
+                """
+            )
+
+        # Add the manifest data
+        manifest_data = """
+                <manifest>
+                    <remote name="origin" fetch="http://localhost" />
+                    <default remote="origin" revision="refs/heads/main" />
+                    <project name="project1" path="tests/path1" />
+                    <project name="project2" path="tests/path2" />
+                    <project name="project3" path="tests/path3" />
+                    <project name="project4" path="tests/path4" />
+                    <project name="project5" path="tests/path5" />
+                    <project name="project6" path="tests/path6" />
+                    <project name="project7" path="tests/path7" />
+                    <project name="project8" path="tests/path8" />
+                </manifest>
+            """
+        with open(self.manifest_file, "w", encoding="utf-8") as fp:
+            fp.write(manifest_data)
+
+        # Set up 8 empty projects to match the manifest
+        for x in range(1, 9):
+            os.makedirs(
+                os.path.join(
+                    self.repodir, "projects/tests/path" + str(x) + ".git"
+                )
+            )
+            os.makedirs(
+                os.path.join(
+                    self.repodir, "project-objects/project" + str(x) + ".git"
+                )
+            )
+            git_path = os.path.join(self.tempdir, "tests/path" + str(x))
+            self.initTempGitTree(git_path)
+
+        return manifest_xml.XmlManifest(self.repodir, self.manifest_file)
+
+    # Use mock to capture stdout from the forall run
+    @unittest.mock.patch("sys.stdout", new_callable=StringIO)
+    def test_forall_all_projects_called_once(self, mock_stdout):
+        """Test that all projects get a command run once each."""
+
+        manifest_with_8_projects = self.getXmlManifestWith8Projects()
+
+        cmd = subcmds.forall.Forall()
+        cmd.manifest = manifest_with_8_projects
+
+        # Use echo project names as the test of forall
+        opts, args = cmd.OptionParser.parse_args(["-c", "echo $REPO_PROJECT"])
+        opts.verbose = False
+
+        # Mock to not have the Execute fail on remote check
+        with mock.patch.object(
+            project.Project, "GetRevisionId", return_value="refs/heads/main"
+        ):
+            # Run the forall command
+            cmd.Execute(opts, args)
+
+            # Verify that we got every project name in the prints
+            for x in range(1, 9):
+                self.assertIn("project" + str(x), mock_stdout.getvalue())
+
+            # Split the captured output into lines to count them
+            line_count = 0
+            for line in mock_stdout.getvalue().split("\n"):
+                # A commented out print to stderr as a reminder
+                # that stdout is mocked, include sys and uncomment if needed
+                # print(line, file=sys.stderr)
+                if len(line) > 0:
+                    line_count += 1
+
+            # Verify that we didn't get more lines than expected
+            assert line_count == 8

tests/test_subcmds_init.py

@@ -0,0 +1,46 @@
+# Copyright (C) 2020 The Android Open Source Project
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Unittests for the subcmds/init.py module."""
+
+import unittest
+
+from subcmds import init
+
+
+class InitCommand(unittest.TestCase):
+    """Check registered all_commands."""
+
+    def setUp(self):
+        self.cmd = init.Init()
+
+    def test_cli_parser_good(self):
+        """Check valid command line options."""
+        ARGV = ([],)
+        for argv in ARGV:
+            opts, args = self.cmd.OptionParser.parse_args(argv)
+            self.cmd.ValidateOptions(opts, args)
+
+    def test_cli_parser_bad(self):
+        """Check invalid command line options."""
+        ARGV = (
+            # Too many arguments.
+            ["url", "asdf"],
+            # Conflicting options.
+            ["--mirror", "--archive"],
+        )
+        for argv in ARGV:
+            opts, args = self.cmd.OptionParser.parse_args(argv)
+            with self.assertRaises(SystemExit):
+                self.cmd.ValidateOptions(opts, args)

tests/test_subcmds_manifest.py

@@ -0,0 +1,156 @@
+# Copyright (C) 2025 The Android Open Source Project
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Unittests for the subcmds/manifest.py module."""
+
+import json
+from pathlib import Path
+from unittest import mock
+
+import manifest_xml
+from subcmds import manifest
+
+
+_EXAMPLE_MANIFEST = """\
+<?xml version="1.0" encoding="UTF-8"?>
+<manifest>
+  <remote name="test-remote" fetch="http://localhost" />
+  <default remote="test-remote" revision="refs/heads/main" />
+  <project name="repohooks" path="src/repohooks"/>
+  <repo-hooks in-project="repohooks" enabled-list="a, b"/>
+</manifest>
+"""
+
+
+def _get_cmd(repodir: Path) -> manifest.Manifest:
+    """Instantiate a manifest command object to test."""
+    manifests_git = repodir / "manifests.git"
+    manifests_git.mkdir()
+    (manifests_git / "config").write_text(
+        """
+[remote "origin"]
+\turl = http://localhost/manifest
+"""
+    )
+    client = manifest_xml.RepoClient(repodir=str(repodir))
+    git_event_log = mock.MagicMock(ErrorEvent=mock.Mock(return_value=None))
+    return manifest.Manifest(
+        repodir=client.repodir,
+        client=client,
+        manifest=client.manifest,
+        outer_client=client,
+        outer_manifest=client.manifest,
+        git_event_log=git_event_log,
+    )
+
+
+def test_output_format_xml_file(tmp_path):
+    """Test writing XML to a file."""
+    path = tmp_path / "manifest.xml"
+    path.write_text(_EXAMPLE_MANIFEST)
+    outpath = tmp_path / "output.xml"
+    cmd = _get_cmd(tmp_path)
+    opt, args = cmd.OptionParser.parse_args(["--output-file", str(outpath)])
+    cmd.Execute(opt, args)
+    # Normalize the output a bit as we don't exactly care.
+    normalize = lambda data: "\n".join(
+        x.strip() for x in data.splitlines() if x.strip()
+    )
+    assert (
+        normalize(outpath.read_text())
+        == """<?xml version="1.0" encoding="UTF-8"?>
+<manifest>
+<remote name="test-remote" fetch="http://localhost"/>
+<default remote="test-remote" revision="refs/heads/main"/>
+<project name="repohooks" path="src/repohooks"/>
+<repo-hooks in-project="repohooks" enabled-list="a b"/>
+</manifest>"""
+    )
+
+
+def test_output_format_xml_stdout(tmp_path, capsys):
+    """Test writing XML to stdout."""
+    path = tmp_path / "manifest.xml"
+    path.write_text(_EXAMPLE_MANIFEST)
+    cmd = _get_cmd(tmp_path)
+    opt, args = cmd.OptionParser.parse_args(["--format", "xml"])
+    cmd.Execute(opt, args)
+    # Normalize the output a bit as we don't exactly care.
+    normalize = lambda data: "\n".join(
+        x.strip() for x in data.splitlines() if x.strip()
+    )
+    stdout = capsys.readouterr().out
+    assert (
+        normalize(stdout)
+        == """<?xml version="1.0" encoding="UTF-8"?>
+<manifest>
+<remote name="test-remote" fetch="http://localhost"/>
+<default remote="test-remote" revision="refs/heads/main"/>
+<project name="repohooks" path="src/repohooks"/>
+<repo-hooks in-project="repohooks" enabled-list="a b"/>
+</manifest>"""
+    )
+
+
+def test_output_format_json(tmp_path, capsys):
+    """Test writing JSON."""
+    path = tmp_path / "manifest.xml"
+    path.write_text(_EXAMPLE_MANIFEST)
+    cmd = _get_cmd(tmp_path)
+    opt, args = cmd.OptionParser.parse_args(["--format", "json"])
+    cmd.Execute(opt, args)
+    obj = json.loads(capsys.readouterr().out)
+    assert obj == {
+        "default": {"remote": "test-remote", "revision": "refs/heads/main"},
+        "project": [{"name": "repohooks", "path": "src/repohooks"}],
+        "remote": [{"fetch": "http://localhost", "name": "test-remote"}],
+        "repo-hooks": {"enabled-list": "a b", "in-project": "repohooks"},
+    }
+
+
+def test_output_format_json_pretty(tmp_path, capsys):
+    """Test writing pretty JSON."""
+    path = tmp_path / "manifest.xml"
+    path.write_text(_EXAMPLE_MANIFEST)
+    cmd = _get_cmd(tmp_path)
+    opt, args = cmd.OptionParser.parse_args(["--format", "json", "--pretty"])
+    cmd.Execute(opt, args)
+    stdout = capsys.readouterr().out
+    assert (
+        stdout
+        == """\
+{
+  "default": {
+    "remote": "test-remote",
+    "revision": "refs/heads/main"
+  },
+  "project": [
+    {
+      "name": "repohooks",
+      "path": "src/repohooks"
+    }
+  ],
+  "remote": [
+    {
+      "fetch": "http://localhost",
+      "name": "test-remote"
+    }
+  ],
+  "repo-hooks": {
+    "enabled-list": "a b",
+    "in-project": "repohooks"
+  }
+}
+"""
+    )

tests/test_subcmds_sync.py

@@ -0,0 +1,918 @@
+# Copyright (C) 2022 The Android Open Source Project
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Unittests for the subcmds/sync.py module."""
+
+import os
+import shutil
+import tempfile
+import time
+import unittest
+from unittest import mock
+
+import pytest
+
+import command
+from error import GitError
+from error import RepoExitError
+from project import SyncNetworkHalfResult
+from subcmds import sync
+
+
+@pytest.mark.parametrize(
+    "use_superproject, cli_args, result",
+    [
+        (True, ["--current-branch"], True),
+        (True, ["--no-current-branch"], True),
+        (True, [], True),
+        (False, ["--current-branch"], True),
+        (False, ["--no-current-branch"], False),
+        (False, [], None),
+    ],
+)
+def test_get_current_branch_only(use_superproject, cli_args, result):
+    """Test Sync._GetCurrentBranchOnly logic.
+
+    Sync._GetCurrentBranchOnly should return True if a superproject is
+    requested, and otherwise the value of the current_branch_only option.
+    """
+    cmd = sync.Sync()
+    opts, _ = cmd.OptionParser.parse_args(cli_args)
+
+    with mock.patch(
+        "git_superproject.UseSuperproject", return_value=use_superproject
+    ):
+        assert cmd._GetCurrentBranchOnly(opts, cmd.manifest) == result
+
+
+# Used to patch os.cpu_count() for reliable results.
+OS_CPU_COUNT = 24
+
+
+@pytest.mark.parametrize(
+    "argv, jobs_manifest, jobs, jobs_net, jobs_check",
+    [
+        # No user or manifest settings.
+        ([], None, OS_CPU_COUNT, 1, command.DEFAULT_LOCAL_JOBS),
+        # No user settings, so manifest settings control.
+        ([], 3, 3, 3, 3),
+        # User settings, but no manifest.
+        (["--jobs=4"], None, 4, 4, 4),
+        (["--jobs=4", "--jobs-network=5"], None, 4, 5, 4),
+        (["--jobs=4", "--jobs-checkout=6"], None, 4, 4, 6),
+        (["--jobs=4", "--jobs-network=5", "--jobs-checkout=6"], None, 4, 5, 6),
+        (
+            ["--jobs-network=5"],
+            None,
+            OS_CPU_COUNT,
+            5,
+            command.DEFAULT_LOCAL_JOBS,
+        ),
+        (["--jobs-checkout=6"], None, OS_CPU_COUNT, 1, 6),
+        (["--jobs-network=5", "--jobs-checkout=6"], None, OS_CPU_COUNT, 5, 6),
+        # User settings with manifest settings.
+        (["--jobs=4"], 3, 4, 4, 4),
+        (["--jobs=4", "--jobs-network=5"], 3, 4, 5, 4),
+        (["--jobs=4", "--jobs-checkout=6"], 3, 4, 4, 6),
+        (["--jobs=4", "--jobs-network=5", "--jobs-checkout=6"], 3, 4, 5, 6),
+        (["--jobs-network=5"], 3, 3, 5, 3),
+        (["--jobs-checkout=6"], 3, 3, 3, 6),
+        (["--jobs-network=5", "--jobs-checkout=6"], 3, 3, 5, 6),
+        # Settings that exceed rlimits get capped.
+        (["--jobs=1000000"], None, 83, 83, 83),
+        ([], 1000000, 83, 83, 83),
+    ],
+)
+def test_cli_jobs(argv, jobs_manifest, jobs, jobs_net, jobs_check):
+    """Tests --jobs option behavior."""
+    mp = mock.MagicMock()
+    mp.manifest.default.sync_j = jobs_manifest
+
+    cmd = sync.Sync()
+    opts, args = cmd.OptionParser.parse_args(argv)
+    cmd.ValidateOptions(opts, args)
+
+    with mock.patch.object(sync, "_rlimit_nofile", return_value=(256, 256)):
+        with mock.patch.object(os, "cpu_count", return_value=OS_CPU_COUNT):
+            cmd._ValidateOptionsWithManifest(opts, mp)
+            assert opts.jobs == jobs
+            assert opts.jobs_network == jobs_net
+            assert opts.jobs_checkout == jobs_check
+
+
+class LocalSyncState(unittest.TestCase):
+    """Tests for LocalSyncState."""
+
+    _TIME = 10
+
+    def setUp(self):
+        """Common setup."""
+        self.topdir = tempfile.mkdtemp("LocalSyncState")
+        self.repodir = os.path.join(self.topdir, ".repo")
+        os.makedirs(self.repodir)
+
+        self.manifest = mock.MagicMock(
+            topdir=self.topdir,
+            repodir=self.repodir,
+            repoProject=mock.MagicMock(relpath=".repo/repo"),
+        )
+        self.state = self._new_state()
+
+    def tearDown(self):
+        """Common teardown."""
+        shutil.rmtree(self.topdir)
+
+    def _new_state(self, time=_TIME):
+        with mock.patch("time.time", return_value=time):
+            return sync.LocalSyncState(self.manifest)
+
+    def test_set(self):
+        """Times are set."""
+        p = mock.MagicMock(relpath="projA")
+        self.state.SetFetchTime(p)
+        self.state.SetCheckoutTime(p)
+        self.assertEqual(self.state.GetFetchTime(p), self._TIME)
+        self.assertEqual(self.state.GetCheckoutTime(p), self._TIME)
+
+    def test_update(self):
+        """Times are updated."""
+        with open(self.state._path, "w") as f:
+            f.write(
+                """
+            {
+              "projB": {
+                "last_fetch": 5,
+                "last_checkout": 7
+              }
+            }
+            """
+            )
+
+        # Initialize state to read from the new file.
+        self.state = self._new_state()
+        projA = mock.MagicMock(relpath="projA")
+        projB = mock.MagicMock(relpath="projB")
+        self.assertEqual(self.state.GetFetchTime(projA), None)
+        self.assertEqual(self.state.GetFetchTime(projB), 5)
+        self.assertEqual(self.state.GetCheckoutTime(projB), 7)
+
+        self.state.SetFetchTime(projA)
+        self.state.SetFetchTime(projB)
+        self.assertEqual(self.state.GetFetchTime(projA), self._TIME)
+        self.assertEqual(self.state.GetFetchTime(projB), self._TIME)
+        self.assertEqual(self.state.GetCheckoutTime(projB), 7)
+
+    def test_save_to_file(self):
+        """Data is saved under repodir."""
+        p = mock.MagicMock(relpath="projA")
+        self.state.SetFetchTime(p)
+        self.state.Save()
+        self.assertEqual(
+            os.listdir(self.repodir), [".repo_localsyncstate.json"]
+        )
+
+    def test_partial_sync(self):
+        """Partial sync state is detected."""
+        with open(self.state._path, "w") as f:
+            f.write(
+                """
+            {
+              "projA": {
+                "last_fetch": 5,
+                "last_checkout": 5
+              },
+              "projB": {
+                "last_fetch": 5,
+                "last_checkout": 5
+              }
+            }
+            """
+            )
+
+        # Initialize state to read from the new file.
+        self.state = self._new_state()
+        projB = mock.MagicMock(relpath="projB")
+        self.assertEqual(self.state.IsPartiallySynced(), False)
+
+        self.state.SetFetchTime(projB)
+        self.state.SetCheckoutTime(projB)
+        self.assertEqual(self.state.IsPartiallySynced(), True)
+
+    def test_ignore_repo_project(self):
+        """Sync data for repo project is ignored when checking partial sync."""
+        p = mock.MagicMock(relpath="projA")
+        self.state.SetFetchTime(p)
+        self.state.SetCheckoutTime(p)
+        self.state.SetFetchTime(self.manifest.repoProject)
+        self.state.Save()
+        self.assertEqual(self.state.IsPartiallySynced(), False)
+
+        self.state = self._new_state(self._TIME + 1)
+        self.state.SetFetchTime(self.manifest.repoProject)
+        self.assertEqual(
+            self.state.GetFetchTime(self.manifest.repoProject), self._TIME + 1
+        )
+        self.assertEqual(self.state.GetFetchTime(p), self._TIME)
+        self.assertEqual(self.state.IsPartiallySynced(), False)
+
+    def test_nonexistent_project(self):
+        """Unsaved projects don't have data."""
+        p = mock.MagicMock(relpath="projC")
+        self.assertEqual(self.state.GetFetchTime(p), None)
+        self.assertEqual(self.state.GetCheckoutTime(p), None)
+
+    def test_prune_removed_projects(self):
+        """Removed projects are pruned."""
+        with open(self.state._path, "w") as f:
+            f.write(
+                """
+            {
+              "projA": {
+                "last_fetch": 5
+              },
+              "projB": {
+                "last_fetch": 7
+              }
+            }
+            """
+            )
+
+        def mock_exists(path):
+            if "projA" in path:
+                return False
+            return True
+
+        projA = mock.MagicMock(relpath="projA")
+        projB = mock.MagicMock(relpath="projB")
+        self.state = self._new_state()
+        self.assertEqual(self.state.GetFetchTime(projA), 5)
+        self.assertEqual(self.state.GetFetchTime(projB), 7)
+        with mock.patch("os.path.exists", side_effect=mock_exists):
+            self.state.PruneRemovedProjects()
+        self.assertIsNone(self.state.GetFetchTime(projA))
+
+        self.state = self._new_state()
+        self.assertIsNone(self.state.GetFetchTime(projA))
+        self.assertEqual(self.state.GetFetchTime(projB), 7)
+
+    def test_prune_removed_and_symlinked_projects(self):
+        """Removed projects that still exists on disk as symlink are pruned."""
+        with open(self.state._path, "w") as f:
+            f.write(
+                """
+            {
+              "projA": {
+                "last_fetch": 5
+              },
+              "projB": {
+                "last_fetch": 7
+              }
+            }
+            """
+            )
+
+        def mock_exists(path):
+            return True
+
+        def mock_islink(path):
+            if "projB" in path:
+                return True
+            return False
+
+        projA = mock.MagicMock(relpath="projA")
+        projB = mock.MagicMock(relpath="projB")
+        self.state = self._new_state()
+        self.assertEqual(self.state.GetFetchTime(projA), 5)
+        self.assertEqual(self.state.GetFetchTime(projB), 7)
+        with mock.patch("os.path.exists", side_effect=mock_exists):
+            with mock.patch("os.path.islink", side_effect=mock_islink):
+                self.state.PruneRemovedProjects()
+        self.assertIsNone(self.state.GetFetchTime(projB))
+
+        self.state = self._new_state()
+        self.assertIsNone(self.state.GetFetchTime(projB))
+        self.assertEqual(self.state.GetFetchTime(projA), 5)
+
+
+class FakeProject:
+    def __init__(self, relpath, name=None, objdir=None):
+        self.relpath = relpath
+        self.name = name or relpath
+        self.objdir = objdir or relpath
+
+        self.use_git_worktrees = False
+        self.UseAlternates = False
+        self.manifest = mock.MagicMock()
+        self.manifest.GetProjectsWithName.return_value = [self]
+        self.config = mock.MagicMock()
+        self.EnableRepositoryExtension = mock.MagicMock()
+
+    def RelPath(self, local=None):
+        return self.relpath
+
+    def __str__(self):
+        return f"project: {self.relpath}"
+
+    def __repr__(self):
+        return str(self)
+
+
+class SafeCheckoutOrder(unittest.TestCase):
+    def test_no_nested(self):
+        p_f = FakeProject("f")
+        p_foo = FakeProject("foo")
+        out = sync._SafeCheckoutOrder([p_f, p_foo])
+        self.assertEqual(out, [[p_f, p_foo]])
+
+    def test_basic_nested(self):
+        p_foo = p_foo = FakeProject("foo")
+        p_foo_bar = FakeProject("foo/bar")
+        out = sync._SafeCheckoutOrder([p_foo, p_foo_bar])
+        self.assertEqual(out, [[p_foo], [p_foo_bar]])
+
+    def test_complex_nested(self):
+        p_foo = FakeProject("foo")
+        p_foobar = FakeProject("foobar")
+        p_foo_dash_bar = FakeProject("foo-bar")
+        p_foo_bar = FakeProject("foo/bar")
+        p_foo_bar_baz_baq = FakeProject("foo/bar/baz/baq")
+        p_bar = FakeProject("bar")
+        out = sync._SafeCheckoutOrder(
+            [
+                p_foo_bar_baz_baq,
+                p_foo,
+                p_foobar,
+                p_foo_dash_bar,
+                p_foo_bar,
+                p_bar,
+            ]
+        )
+        self.assertEqual(
+            out,
+            [
+                [p_bar, p_foo, p_foo_dash_bar, p_foobar],
+                [p_foo_bar],
+                [p_foo_bar_baz_baq],
+            ],
+        )
+
+
+class Chunksize(unittest.TestCase):
+    """Tests for _chunksize."""
+
+    def test_single_project(self):
+        """Single project."""
+        self.assertEqual(sync._chunksize(1, 1), 1)
+
+    def test_low_project_count(self):
+        """Multiple projects, low number of projects to sync."""
+        self.assertEqual(sync._chunksize(10, 1), 10)
+        self.assertEqual(sync._chunksize(10, 2), 5)
+        self.assertEqual(sync._chunksize(10, 4), 2)
+        self.assertEqual(sync._chunksize(10, 8), 1)
+        self.assertEqual(sync._chunksize(10, 16), 1)
+
+    def test_high_project_count(self):
+        """Multiple projects, high number of projects to sync."""
+        self.assertEqual(sync._chunksize(2800, 1), 32)
+        self.assertEqual(sync._chunksize(2800, 16), 32)
+        self.assertEqual(sync._chunksize(2800, 32), 32)
+        self.assertEqual(sync._chunksize(2800, 64), 32)
+        self.assertEqual(sync._chunksize(2800, 128), 21)
+
+
+class GetPreciousObjectsState(unittest.TestCase):
+    """Tests for _GetPreciousObjectsState."""
+
+    def setUp(self):
+        """Common setup."""
+        self.cmd = sync.Sync()
+        self.project = p = mock.MagicMock(
+            use_git_worktrees=False, UseAlternates=False
+        )
+        p.manifest.GetProjectsWithName.return_value = [p]
+
+        self.opt = mock.Mock(spec_set=["this_manifest_only"])
+        self.opt.this_manifest_only = False
+
+    def test_worktrees(self):
+        """False for worktrees."""
+        self.project.use_git_worktrees = True
+        self.assertFalse(
+            self.cmd._GetPreciousObjectsState(self.project, self.opt)
+        )
+
+    def test_not_shared(self):
+        """Singleton project."""
+        self.assertFalse(
+            self.cmd._GetPreciousObjectsState(self.project, self.opt)
+        )
+
+    def test_shared(self):
+        """Shared project."""
+        self.project.manifest.GetProjectsWithName.return_value = [
+            self.project,
+            self.project,
+        ]
+        self.assertTrue(
+            self.cmd._GetPreciousObjectsState(self.project, self.opt)
+        )
+
+    def test_shared_with_alternates(self):
+        """Shared project, with alternates."""
+        self.project.manifest.GetProjectsWithName.return_value = [
+            self.project,
+            self.project,
+        ]
+        self.project.UseAlternates = True
+        self.assertFalse(
+            self.cmd._GetPreciousObjectsState(self.project, self.opt)
+        )
+
+    def test_not_found(self):
+        """Project not found in manifest."""
+        self.project.manifest.GetProjectsWithName.return_value = []
+        self.assertFalse(
+            self.cmd._GetPreciousObjectsState(self.project, self.opt)
+        )
+
+
+class SyncCommand(unittest.TestCase):
+    """Tests for cmd.Execute."""
+
+    def setUp(self):
+        """Common setup."""
+        self.repodir = tempfile.mkdtemp(".repo")
+        self.manifest = manifest = mock.MagicMock(
+            repodir=self.repodir,
+        )
+
+        git_event_log = mock.MagicMock(ErrorEvent=mock.Mock(return_value=None))
+        self.outer_client = outer_client = mock.MagicMock()
+        outer_client.manifest.IsArchive = True
+        manifest.manifestProject.worktree = "worktree_path/"
+        manifest.repoProject.LastFetch = time.time()
+        self.sync_network_half_error = None
+        self.sync_local_half_error = None
+        self.cmd = sync.Sync(
+            manifest=manifest,
+            outer_client=outer_client,
+            git_event_log=git_event_log,
+        )
+
+        def Sync_NetworkHalf(*args, **kwargs):
+            return SyncNetworkHalfResult(True, self.sync_network_half_error)
+
+        def Sync_LocalHalf(*args, **kwargs):
+            if self.sync_local_half_error:
+                raise self.sync_local_half_error
+
+        self.project = p = mock.MagicMock(
+            use_git_worktrees=False,
+            UseAlternates=False,
+            name="project",
+            Sync_NetworkHalf=Sync_NetworkHalf,
+            Sync_LocalHalf=Sync_LocalHalf,
+            RelPath=mock.Mock(return_value="rel_path"),
+        )
+        p.manifest.GetProjectsWithName.return_value = [p]
+
+        mock.patch.object(
+            sync,
+            "_PostRepoFetch",
+            return_value=None,
+        ).start()
+
+        mock.patch.object(
+            self.cmd, "GetProjects", return_value=[self.project]
+        ).start()
+
+        opt, _ = self.cmd.OptionParser.parse_args([])
+        opt.clone_bundle = False
+        opt.jobs = 4
+        opt.quiet = True
+        opt.use_superproject = False
+        opt.current_branch_only = True
+        opt.optimized_fetch = True
+        opt.retry_fetches = 1
+        opt.prune = False
+        opt.auto_gc = False
+        opt.repo_verify = False
+        self.opt = opt
+
+    def tearDown(self):
+        mock.patch.stopall()
+
+    def test_command_exit_error(self):
+        """Ensure unsuccessful commands raise expected errors."""
+        self.sync_network_half_error = GitError(
+            "sync_network_half_error error", project=self.project
+        )
+        self.sync_local_half_error = GitError(
+            "sync_local_half_error", project=self.project
+        )
+        with self.assertRaises(RepoExitError) as e:
+            self.cmd.Execute(self.opt, [])
+            self.assertIn(self.sync_local_half_error, e.aggregate_errors)
+            self.assertIn(self.sync_network_half_error, e.aggregate_errors)
+
+
+class SyncUpdateRepoProject(unittest.TestCase):
+    """Tests for Sync._UpdateRepoProject."""
+
+    def setUp(self):
+        """Common setup."""
+        self.repodir = tempfile.mkdtemp(".repo")
+        self.manifest = manifest = mock.MagicMock(repodir=self.repodir)
+        # Create a repoProject with a mock Sync_NetworkHalf.
+        repoProject = mock.MagicMock(name="repo")
+        repoProject.Sync_NetworkHalf = mock.Mock(
+            return_value=SyncNetworkHalfResult(True, None)
+        )
+        manifest.repoProject = repoProject
+        manifest.IsArchive = False
+        manifest.CloneFilter = None
+        manifest.PartialCloneExclude = None
+        manifest.CloneFilterForDepth = None
+
+        git_event_log = mock.MagicMock(ErrorEvent=mock.Mock(return_value=None))
+        self.cmd = sync.Sync(manifest=manifest, git_event_log=git_event_log)
+
+        opt, _ = self.cmd.OptionParser.parse_args([])
+        opt.local_only = False
+        opt.repo_verify = False
+        opt.verbose = False
+        opt.quiet = True
+        opt.force_sync = False
+        opt.clone_bundle = False
+        opt.tags = False
+        opt.optimized_fetch = False
+        opt.retry_fetches = 0
+        opt.prune = False
+        self.opt = opt
+        self.errors = []
+
+        mock.patch.object(sync.Sync, "_GetCurrentBranchOnly").start()
+
+    def tearDown(self):
+        shutil.rmtree(self.repodir)
+        mock.patch.stopall()
+
+    def test_fetches_when_stale(self):
+        """Test it fetches when the repo project is stale."""
+        self.manifest.repoProject.LastFetch = time.time() - (
+            sync._ONE_DAY_S + 1
+        )
+
+        with mock.patch.object(sync, "_PostRepoFetch") as mock_post_fetch:
+            self.cmd._UpdateRepoProject(self.opt, self.manifest, self.errors)
+            self.manifest.repoProject.Sync_NetworkHalf.assert_called_once()
+            mock_post_fetch.assert_called_once()
+            self.assertEqual(self.errors, [])
+
+    def test_skips_when_fresh(self):
+        """Test it skips fetch when repo project is fresh."""
+        self.manifest.repoProject.LastFetch = time.time()
+
+        with mock.patch.object(sync, "_PostRepoFetch") as mock_post_fetch:
+            self.cmd._UpdateRepoProject(self.opt, self.manifest, self.errors)
+            self.manifest.repoProject.Sync_NetworkHalf.assert_not_called()
+            mock_post_fetch.assert_not_called()
+
+    def test_skips_local_only(self):
+        """Test it does nothing with --local-only."""
+        self.opt.local_only = True
+        self.manifest.repoProject.LastFetch = time.time() - (
+            sync._ONE_DAY_S + 1
+        )
+
+        with mock.patch.object(sync, "_PostRepoFetch") as mock_post_fetch:
+            self.cmd._UpdateRepoProject(self.opt, self.manifest, self.errors)
+            self.manifest.repoProject.Sync_NetworkHalf.assert_not_called()
+            mock_post_fetch.assert_not_called()
+
+    def test_post_repo_fetch_skipped_on_env_var(self):
+        """Test _PostRepoFetch is skipped when REPO_SKIP_SELF_UPDATE is set."""
+        self.manifest.repoProject.LastFetch = time.time()
+
+        with mock.patch.dict(os.environ, {"REPO_SKIP_SELF_UPDATE": "1"}):
+            with mock.patch.object(sync, "_PostRepoFetch") as mock_post_fetch:
+                self.cmd._UpdateRepoProject(
+                    self.opt, self.manifest, self.errors
+                )
+                mock_post_fetch.assert_not_called()
+
+    def test_fetch_failure_is_handled(self):
+        """Test that a fetch failure is recorded and doesn't crash."""
+        self.manifest.repoProject.LastFetch = time.time() - (
+            sync._ONE_DAY_S + 1
+        )
+        fetch_error = GitError("Fetch failed")
+        self.manifest.repoProject.Sync_NetworkHalf.return_value = (
+            SyncNetworkHalfResult(False, fetch_error)
+        )
+
+        with mock.patch.object(sync, "_PostRepoFetch") as mock_post_fetch:
+            self.cmd._UpdateRepoProject(self.opt, self.manifest, self.errors)
+            self.manifest.repoProject.Sync_NetworkHalf.assert_called_once()
+            mock_post_fetch.assert_not_called()
+            self.assertEqual(self.errors, [fetch_error])
+
+
+class InterleavedSyncTest(unittest.TestCase):
+    """Tests for interleaved sync."""
+
+    def setUp(self):
+        """Set up a sync command with mocks."""
+        self.repodir = tempfile.mkdtemp(".repo")
+        self.manifest = mock.MagicMock(repodir=self.repodir)
+        self.manifest.repoProject.LastFetch = time.time()
+        self.manifest.repoProject.worktree = self.repodir
+        self.manifest.manifestProject.worktree = self.repodir
+        self.manifest.IsArchive = False
+        self.manifest.CloneBundle = False
+        self.manifest.default.sync_j = 1
+
+        self.outer_client = mock.MagicMock()
+        self.outer_client.manifest.IsArchive = False
+        self.cmd = sync.Sync(
+            manifest=self.manifest, outer_client=self.outer_client
+        )
+        self.cmd.outer_manifest = self.manifest
+
+        # Mock projects.
+        self.projA = FakeProject("projA", objdir="objA")
+        self.projB = FakeProject("projB", objdir="objB")
+        self.projA_sub = FakeProject(
+            "projA/sub", name="projA_sub", objdir="objA_sub"
+        )
+        self.projC = FakeProject("projC", objdir="objC")
+
+        # Mock methods that are not part of the core interleaved sync logic.
+        mock.patch.object(self.cmd, "_UpdateAllManifestProjects").start()
+        mock.patch.object(self.cmd, "_UpdateProjectsRevisionId").start()
+        mock.patch.object(self.cmd, "_ValidateOptionsWithManifest").start()
+        mock.patch.object(sync, "_PostRepoUpgrade").start()
+        mock.patch.object(sync, "_PostRepoFetch").start()
+
+        # Mock parallel context for worker tests.
+        self.parallel_context_patcher = mock.patch(
+            "subcmds.sync.Sync.get_parallel_context"
+        )
+        self.mock_get_parallel_context = self.parallel_context_patcher.start()
+        self.sync_dict = {}
+        self.mock_context = {
+            "projects": [],
+            "sync_dict": self.sync_dict,
+        }
+        self.mock_get_parallel_context.return_value = self.mock_context
+
+        # Mock _GetCurrentBranchOnly for worker tests.
+        mock.patch.object(sync.Sync, "_GetCurrentBranchOnly").start()
+
+    def tearDown(self):
+        """Clean up resources."""
+        shutil.rmtree(self.repodir)
+        mock.patch.stopall()
+
+    def test_interleaved_fail_fast(self):
+        """Test that --fail-fast is respected in interleaved mode."""
+        opt, args = self.cmd.OptionParser.parse_args(
+            ["--interleaved", "--fail-fast", "-j2"]
+        )
+        opt.quiet = True
+
+        # With projA/sub, _SafeCheckoutOrder creates two batches:
+        # 1. [projA, projB]
+        # 2. [projA/sub]
+        # We want to fail on the first batch and ensure the second isn't run.
+        all_projects = [self.projA, self.projB, self.projA_sub]
+        mock.patch.object(
+            self.cmd, "GetProjects", return_value=all_projects
+        ).start()
+
+        # Mock ExecuteInParallel to simulate a failed run on the first batch of
+        # projects.
+        execute_mock = mock.patch.object(
+            self.cmd, "ExecuteInParallel", return_value=False
+        ).start()
+
+        with self.assertRaises(sync.SyncFailFastError):
+            self.cmd._SyncInterleaved(
+                opt,
+                args,
+                [],
+                self.manifest,
+                self.manifest.manifestProject,
+                all_projects,
+                {},
+            )
+
+        execute_mock.assert_called_once()
+
+    def test_interleaved_shared_objdir_serial(self):
+        """Test that projects with shared objdir are processed serially."""
+        opt, args = self.cmd.OptionParser.parse_args(["--interleaved", "-j4"])
+        opt.quiet = True
+
+        # Setup projects with a shared objdir.
+        self.projA.objdir = "common_objdir"
+        self.projC.objdir = "common_objdir"
+
+        all_projects = [self.projA, self.projB, self.projC]
+        mock.patch.object(
+            self.cmd, "GetProjects", return_value=all_projects
+        ).start()
+
+        def execute_side_effect(jobs, target, work_items, **kwargs):
+            # The callback is a partial object. The first arg is the set we
+            # need to update to avoid the stall detection.
+            synced_relpaths_set = kwargs["callback"].args[0]
+            projects_in_pass = self.cmd.get_parallel_context()["projects"]
+            for item in work_items:
+                for project_idx in item:
+                    synced_relpaths_set.add(
+                        projects_in_pass[project_idx].relpath
+                    )
+            return True
+
+        execute_mock = mock.patch.object(
+            self.cmd, "ExecuteInParallel", side_effect=execute_side_effect
+        ).start()
+
+        self.cmd._SyncInterleaved(
+            opt,
+            args,
+            [],
+            self.manifest,
+            self.manifest.manifestProject,
+            all_projects,
+            {},
+        )
+
+        execute_mock.assert_called_once()
+        jobs_arg, _, work_items = execute_mock.call_args.args
+        self.assertEqual(jobs_arg, 2)
+        work_items_sets = {frozenset(item) for item in work_items}
+        expected_sets = {frozenset([0, 2]), frozenset([1])}
+        self.assertEqual(work_items_sets, expected_sets)
+
+    def _get_opts(self, args=None):
+        """Helper to get default options for worker tests."""
+        if args is None:
+            args = ["--interleaved"]
+        opt, _ = self.cmd.OptionParser.parse_args(args)
+        # Set defaults for options used by the worker.
+        opt.quiet = True
+        opt.verbose = False
+        opt.force_sync = False
+        opt.clone_bundle = False
+        opt.tags = False
+        opt.optimized_fetch = False
+        opt.retry_fetches = 0
+        opt.prune = False
+        opt.detach_head = False
+        opt.force_checkout = False
+        opt.rebase = False
+        return opt
+
+    def test_worker_successful_sync(self):
+        """Test _SyncProjectList with a successful fetch and checkout."""
+        opt = self._get_opts()
+        project = self.projA
+        project.Sync_NetworkHalf = mock.Mock(
+            return_value=SyncNetworkHalfResult(error=None, remote_fetched=True)
+        )
+        project.Sync_LocalHalf = mock.Mock()
+        project.manifest.manifestProject.config = mock.MagicMock()
+        self.mock_context["projects"] = [project]
+
+        with mock.patch("subcmds.sync.SyncBuffer") as mock_sync_buffer:
+            mock_sync_buf_instance = mock.MagicMock()
+            mock_sync_buf_instance.Finish.return_value = True
+            mock_sync_buffer.return_value = mock_sync_buf_instance
+
+            result_obj = self.cmd._SyncProjectList(opt, [0])
+
+            self.assertEqual(len(result_obj.results), 1)
+            result = result_obj.results[0]
+            self.assertTrue(result.fetch_success)
+            self.assertTrue(result.checkout_success)
+            self.assertIsNone(result.fetch_error)
+            self.assertIsNone(result.checkout_error)
+            project.Sync_NetworkHalf.assert_called_once()
+            project.Sync_LocalHalf.assert_called_once()
+
+    def test_worker_fetch_fails(self):
+        """Test _SyncProjectList with a failed fetch."""
+        opt = self._get_opts()
+        project = self.projA
+        fetch_error = GitError("Fetch failed")
+        project.Sync_NetworkHalf = mock.Mock(
+            return_value=SyncNetworkHalfResult(
+                error=fetch_error, remote_fetched=False
+            )
+        )
+        project.Sync_LocalHalf = mock.Mock()
+        self.mock_context["projects"] = [project]
+
+        result_obj = self.cmd._SyncProjectList(opt, [0])
+        result = result_obj.results[0]
+
+        self.assertFalse(result.fetch_success)
+        self.assertFalse(result.checkout_success)
+        self.assertEqual(result.fetch_error, fetch_error)
+        self.assertIsNone(result.checkout_error)
+        project.Sync_NetworkHalf.assert_called_once()
+        project.Sync_LocalHalf.assert_not_called()
+
+    def test_worker_fetch_fails_exception(self):
+        """Test _SyncProjectList with an exception during fetch."""
+        opt = self._get_opts()
+        project = self.projA
+        fetch_error = GitError("Fetch failed")
+        project.Sync_NetworkHalf = mock.Mock(side_effect=fetch_error)
+        project.Sync_LocalHalf = mock.Mock()
+        self.mock_context["projects"] = [project]
+
+        result_obj = self.cmd._SyncProjectList(opt, [0])
+        result = result_obj.results[0]
+
+        self.assertFalse(result.fetch_success)
+        self.assertFalse(result.checkout_success)
+        self.assertEqual(result.fetch_error, fetch_error)
+        project.Sync_NetworkHalf.assert_called_once()
+        project.Sync_LocalHalf.assert_not_called()
+
+    def test_worker_checkout_fails(self):
+        """Test _SyncProjectList with an exception during checkout."""
+        opt = self._get_opts()
+        project = self.projA
+        project.Sync_NetworkHalf = mock.Mock(
+            return_value=SyncNetworkHalfResult(error=None, remote_fetched=True)
+        )
+        checkout_error = GitError("Checkout failed")
+        project.Sync_LocalHalf = mock.Mock(side_effect=checkout_error)
+        project.manifest.manifestProject.config = mock.MagicMock()
+        self.mock_context["projects"] = [project]
+
+        with mock.patch("subcmds.sync.SyncBuffer"):
+            result_obj = self.cmd._SyncProjectList(opt, [0])
+            result = result_obj.results[0]
+
+            self.assertTrue(result.fetch_success)
+            self.assertFalse(result.checkout_success)
+            self.assertIsNone(result.fetch_error)
+            self.assertEqual(result.checkout_error, checkout_error)
+            project.Sync_NetworkHalf.assert_called_once()
+            project.Sync_LocalHalf.assert_called_once()
+
+    def test_worker_local_only(self):
+        """Test _SyncProjectList with --local-only."""
+        opt = self._get_opts(["--interleaved", "--local-only"])
+        project = self.projA
+        project.Sync_NetworkHalf = mock.Mock()
+        project.Sync_LocalHalf = mock.Mock()
+        project.manifest.manifestProject.config = mock.MagicMock()
+        self.mock_context["projects"] = [project]
+
+        with mock.patch("subcmds.sync.SyncBuffer") as mock_sync_buffer:
+            mock_sync_buf_instance = mock.MagicMock()
+            mock_sync_buf_instance.Finish.return_value = True
+            mock_sync_buffer.return_value = mock_sync_buf_instance
+
+            result_obj = self.cmd._SyncProjectList(opt, [0])
+            result = result_obj.results[0]
+
+            self.assertTrue(result.fetch_success)
+            self.assertTrue(result.checkout_success)
+            project.Sync_NetworkHalf.assert_not_called()
+            project.Sync_LocalHalf.assert_called_once()
+
+    def test_worker_network_only(self):
+        """Test _SyncProjectList with --network-only."""
+        opt = self._get_opts(["--interleaved", "--network-only"])
+        project = self.projA
+        project.Sync_NetworkHalf = mock.Mock(
+            return_value=SyncNetworkHalfResult(error=None, remote_fetched=True)
+        )
+        project.Sync_LocalHalf = mock.Mock()
+        self.mock_context["projects"] = [project]
+
+        result_obj = self.cmd._SyncProjectList(opt, [0])
+        result = result_obj.results[0]
+
+        self.assertTrue(result.fetch_success)
+        self.assertTrue(result.checkout_success)
+        project.Sync_NetworkHalf.assert_called_once()
+        project.Sync_LocalHalf.assert_not_called()

tests/test_subcmds_upload.py

@@ -0,0 +1,70 @@
+# Copyright (C) 2023 The Android Open Source Project
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Unittests for the subcmds/upload.py module."""
+
+import unittest
+from unittest import mock
+
+from error import GitError
+from error import UploadError
+from subcmds import upload
+
+
+class UnexpectedError(Exception):
+    """An exception not expected by upload command."""
+
+
+class UploadCommand(unittest.TestCase):
+    """Check registered all_commands."""
+
+    def setUp(self):
+        self.cmd = upload.Upload()
+        self.branch = mock.MagicMock()
+        self.people = mock.MagicMock()
+        self.opt, _ = self.cmd.OptionParser.parse_args([])
+        mock.patch.object(
+            self.cmd, "_AppendAutoList", return_value=None
+        ).start()
+        mock.patch.object(self.cmd, "git_event_log").start()
+
+    def tearDown(self):
+        mock.patch.stopall()
+
+    def test_UploadAndReport_UploadError(self):
+        """Check UploadExitError raised when UploadError encountered."""
+        side_effect = UploadError("upload error")
+        with mock.patch.object(
+            self.cmd, "_UploadBranch", side_effect=side_effect
+        ):
+            with self.assertRaises(upload.UploadExitError):
+                self.cmd._UploadAndReport(self.opt, [self.branch], self.people)
+
+    def test_UploadAndReport_GitError(self):
+        """Check UploadExitError raised when GitError encountered."""
+        side_effect = GitError("some git error")
+        with mock.patch.object(
+            self.cmd, "_UploadBranch", side_effect=side_effect
+        ):
+            with self.assertRaises(upload.UploadExitError):
+                self.cmd._UploadAndReport(self.opt, [self.branch], self.people)
+
+    def test_UploadAndReport_UnhandledError(self):
+        """Check UnexpectedError passed through."""
+        side_effect = UnexpectedError("some os error")
+        with mock.patch.object(
+            self.cmd, "_UploadBranch", side_effect=side_effect
+        ):
+            with self.assertRaises(type(side_effect)):
+                self.cmd._UploadAndReport(self.opt, [self.branch], self.people)

tests/test_update_manpages.py

@@ -0,0 +1,28 @@
+# Copyright 2022 The Android Open Source Project
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Unittests for the update_manpages module."""
+
+import unittest
+
+from release import update_manpages
+
+
+class UpdateManpagesTest(unittest.TestCase):
+    """Tests the update-manpages code."""
+
+    def test_replace_regex(self):
+        """Check that replace_regex works."""
+        data = "\n\033[1mSummary\033[m\n"
+        self.assertEqual(update_manpages.replace_regex(data), "\nSummary\n")

tests/test_wrapper.py

@@ -1,5 +1,3 @@
-# -*- coding:utf-8 -*-
-#
 # Copyright (C) 2015 The Android Open Source Project
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -16,65 +14,557 @@
 
 """Unittests for the wrapper.py module."""
 
-from __future__ import print_function
-
+import io
 import os
+import re
+import subprocess
+import sys
+import tempfile
 import unittest
+from unittest import mock
 
+import git_command
+import main
 import wrapper
 
+
 def fixture(*paths):
-  """Return a path relative to tests/fixtures.
-  """
-  return os.path.join(os.path.dirname(__file__), 'fixtures', *paths)
+    """Return a path relative to tests/fixtures."""
+    return os.path.join(os.path.dirname(__file__), "fixtures", *paths)
 
-class RepoWrapperUnitTest(unittest.TestCase):
-  """Tests helper functions in the repo wrapper
-  """
-  def setUp(self):
-    """Load the wrapper module every time
-    """
-    wrapper._wrapper_module = None
-    self.wrapper = wrapper.Wrapper()
 
-  def test_get_gitc_manifest_dir_no_gitc(self):
-    """
-    Test reading a missing gitc config file
-    """
-    self.wrapper.GITC_CONFIG_FILE = fixture('missing_gitc_config')
-    val = self.wrapper.get_gitc_manifest_dir()
-    self.assertEqual(val, '')
+class RepoWrapperTestCase(unittest.TestCase):
+    """TestCase for the wrapper module."""
 
-  def test_get_gitc_manifest_dir(self):
-    """
-    Test reading the gitc config file and parsing the directory
-    """
-    self.wrapper.GITC_CONFIG_FILE = fixture('gitc_config')
-    val = self.wrapper.get_gitc_manifest_dir()
-    self.assertEqual(val, '/test/usr/local/google/gitc')
+    def setUp(self):
+        """Load the wrapper module every time."""
+        wrapper.Wrapper.cache_clear()
+        self.wrapper = wrapper.Wrapper()
 
-  def test_gitc_parse_clientdir_no_gitc(self):
-    """
-    Test parsing the gitc clientdir without gitc running
-    """
-    self.wrapper.GITC_CONFIG_FILE = fixture('missing_gitc_config')
-    self.assertEqual(self.wrapper.gitc_parse_clientdir('/something'), None)
-    self.assertEqual(self.wrapper.gitc_parse_clientdir('/gitc/manifest-rw/test'), 'test')
 
-  def test_gitc_parse_clientdir(self):
-    """
-    Test parsing the gitc clientdir
-    """
-    self.wrapper.GITC_CONFIG_FILE = fixture('gitc_config')
-    self.assertEqual(self.wrapper.gitc_parse_clientdir('/something'), None)
-    self.assertEqual(self.wrapper.gitc_parse_clientdir('/gitc/manifest-rw/test'), 'test')
-    self.assertEqual(self.wrapper.gitc_parse_clientdir('/gitc/manifest-rw/test/'), 'test')
-    self.assertEqual(self.wrapper.gitc_parse_clientdir('/gitc/manifest-rw/test/extra'), 'test')
-    self.assertEqual(self.wrapper.gitc_parse_clientdir('/test/usr/local/google/gitc/test'), 'test')
-    self.assertEqual(self.wrapper.gitc_parse_clientdir('/test/usr/local/google/gitc/test/'), 'test')
-    self.assertEqual(self.wrapper.gitc_parse_clientdir('/test/usr/local/google/gitc/test/extra'), 'test')
-    self.assertEqual(self.wrapper.gitc_parse_clientdir('/gitc/manifest-rw/'), None)
-    self.assertEqual(self.wrapper.gitc_parse_clientdir('/test/usr/local/google/gitc/'), None)
+class RepoWrapperUnitTest(RepoWrapperTestCase):
+    """Tests helper functions in the repo wrapper"""
 
-if __name__ == '__main__':
-  unittest.main()
+    def test_version(self):
+        """Make sure _Version works."""
+        with self.assertRaises(SystemExit) as e:
+            with mock.patch("sys.stdout", new_callable=io.StringIO) as stdout:
+                with mock.patch(
+                    "sys.stderr", new_callable=io.StringIO
+                ) as stderr:
+                    self.wrapper._Version()
+        self.assertEqual(0, e.exception.code)
+        self.assertEqual("", stderr.getvalue())
+        self.assertIn("repo launcher version", stdout.getvalue())
+
+    def test_python_constraints(self):
+        """The launcher should never require newer than main.py."""
+        self.assertGreaterEqual(
+            main.MIN_PYTHON_VERSION_HARD, self.wrapper.MIN_PYTHON_VERSION_HARD
+        )
+        self.assertGreaterEqual(
+            main.MIN_PYTHON_VERSION_SOFT, self.wrapper.MIN_PYTHON_VERSION_SOFT
+        )
+        # Make sure the versions are themselves in sync.
+        self.assertGreaterEqual(
+            self.wrapper.MIN_PYTHON_VERSION_SOFT,
+            self.wrapper.MIN_PYTHON_VERSION_HARD,
+        )
+
+    def test_init_parser(self):
+        """Make sure 'init' GetParser works."""
+        parser = self.wrapper.GetParser()
+        opts, args = parser.parse_args([])
+        self.assertEqual([], args)
+        self.assertIsNone(opts.manifest_url)
+
+
+class SetGitTrace2ParentSid(RepoWrapperTestCase):
+    """Check SetGitTrace2ParentSid behavior."""
+
+    KEY = "GIT_TRACE2_PARENT_SID"
+    VALID_FORMAT = re.compile(r"^repo-[0-9]{8}T[0-9]{6}Z-P[0-9a-f]{8}$")
+
+    def test_first_set(self):
+        """Test env var not yet set."""
+        env = {}
+        self.wrapper.SetGitTrace2ParentSid(env)
+        self.assertIn(self.KEY, env)
+        value = env[self.KEY]
+        self.assertRegex(value, self.VALID_FORMAT)
+
+    def test_append(self):
+        """Test env var is appended."""
+        env = {self.KEY: "pfx"}
+        self.wrapper.SetGitTrace2ParentSid(env)
+        self.assertIn(self.KEY, env)
+        value = env[self.KEY]
+        self.assertTrue(value.startswith("pfx/"))
+        self.assertRegex(value[4:], self.VALID_FORMAT)
+
+    def test_global_context(self):
+        """Check os.environ gets updated by default."""
+        os.environ.pop(self.KEY, None)
+        self.wrapper.SetGitTrace2ParentSid()
+        self.assertIn(self.KEY, os.environ)
+        value = os.environ[self.KEY]
+        self.assertRegex(value, self.VALID_FORMAT)
+
+
+class RunCommand(RepoWrapperTestCase):
+    """Check run_command behavior."""
+
+    def test_capture(self):
+        """Check capture_output handling."""
+        ret = self.wrapper.run_command(["echo", "hi"], capture_output=True)
+        # echo command appends OS specific linesep, but on Windows + Git Bash
+        # we get UNIX ending, so we allow both.
+        self.assertIn(ret.stdout, ["hi" + os.linesep, "hi\n"])
+
+    def test_check(self):
+        """Check check handling."""
+        self.wrapper.run_command(["true"], check=False)
+        self.wrapper.run_command(["true"], check=True)
+        self.wrapper.run_command(["false"], check=False)
+        with self.assertRaises(subprocess.CalledProcessError):
+            self.wrapper.run_command(["false"], check=True)
+
+
+class RunGit(RepoWrapperTestCase):
+    """Check run_git behavior."""
+
+    def test_capture(self):
+        """Check capture_output handling."""
+        ret = self.wrapper.run_git("--version")
+        self.assertIn("git", ret.stdout)
+
+    def test_check(self):
+        """Check check handling."""
+        with self.assertRaises(self.wrapper.CloneFailure):
+            self.wrapper.run_git("--version-asdfasdf")
+        self.wrapper.run_git("--version-asdfasdf", check=False)
+
+
+class ParseGitVersion(RepoWrapperTestCase):
+    """Check ParseGitVersion behavior."""
+
+    def test_autoload(self):
+        """Check we can load the version from the live git."""
+        ret = self.wrapper.ParseGitVersion()
+        self.assertIsNotNone(ret)
+
+    def test_bad_ver(self):
+        """Check handling of bad git versions."""
+        ret = self.wrapper.ParseGitVersion(ver_str="asdf")
+        self.assertIsNone(ret)
+
+    def test_normal_ver(self):
+        """Check handling of normal git versions."""
+        ret = self.wrapper.ParseGitVersion(ver_str="git version 2.25.1")
+        self.assertEqual(2, ret.major)
+        self.assertEqual(25, ret.minor)
+        self.assertEqual(1, ret.micro)
+        self.assertEqual("2.25.1", ret.full)
+
+    def test_extended_ver(self):
+        """Check handling of extended distro git versions."""
+        ret = self.wrapper.ParseGitVersion(
+            ver_str="git version 1.30.50.696.g5e7596f4ac-goog"
+        )
+        self.assertEqual(1, ret.major)
+        self.assertEqual(30, ret.minor)
+        self.assertEqual(50, ret.micro)
+        self.assertEqual("1.30.50.696.g5e7596f4ac-goog", ret.full)
+
+
+class CheckGitVersion(RepoWrapperTestCase):
+    """Check _CheckGitVersion behavior."""
+
+    def test_unknown(self):
+        """Unknown versions should abort."""
+        with mock.patch.object(
+            self.wrapper, "ParseGitVersion", return_value=None
+        ):
+            with self.assertRaises(self.wrapper.CloneFailure):
+                self.wrapper._CheckGitVersion()
+
+    def test_old(self):
+        """Old versions should abort."""
+        with mock.patch.object(
+            self.wrapper,
+            "ParseGitVersion",
+            return_value=self.wrapper.GitVersion(1, 0, 0, "1.0.0"),
+        ):
+            with self.assertRaises(self.wrapper.CloneFailure):
+                self.wrapper._CheckGitVersion()
+
+    def test_new(self):
+        """Newer versions should run fine."""
+        with mock.patch.object(
+            self.wrapper,
+            "ParseGitVersion",
+            return_value=self.wrapper.GitVersion(100, 0, 0, "100.0.0"),
+        ):
+            self.wrapper._CheckGitVersion()
+
+
+class Requirements(RepoWrapperTestCase):
+    """Check Requirements handling."""
+
+    def test_missing_file(self):
+        """Don't crash if the file is missing (old version)."""
+        testdir = os.path.dirname(os.path.realpath(__file__))
+        self.assertIsNone(self.wrapper.Requirements.from_dir(testdir))
+        self.assertIsNone(
+            self.wrapper.Requirements.from_file(
+                os.path.join(testdir, "xxxxxxxxxxxxxxxxxxxxxxxx")
+            )
+        )
+
+    def test_corrupt_data(self):
+        """If the file can't be parsed, don't blow up."""
+        self.assertIsNone(self.wrapper.Requirements.from_file(__file__))
+        self.assertIsNone(self.wrapper.Requirements.from_data(b"x"))
+
+    def test_valid_data(self):
+        """Make sure we can parse the file we ship."""
+        self.assertIsNotNone(self.wrapper.Requirements.from_data(b"{}"))
+        rootdir = os.path.dirname(os.path.dirname(os.path.realpath(__file__)))
+        self.assertIsNotNone(self.wrapper.Requirements.from_dir(rootdir))
+        self.assertIsNotNone(
+            self.wrapper.Requirements.from_file(
+                os.path.join(rootdir, "requirements.json")
+            )
+        )
+
+    def test_format_ver(self):
+        """Check format_ver can format."""
+        self.assertEqual(
+            "1.2.3", self.wrapper.Requirements._format_ver((1, 2, 3))
+        )
+        self.assertEqual("1", self.wrapper.Requirements._format_ver([1]))
+
+    def test_assert_all_unknown(self):
+        """Check assert_all works with incompatible file."""
+        reqs = self.wrapper.Requirements({})
+        reqs.assert_all()
+
+    def test_assert_all_new_repo(self):
+        """Check assert_all accepts new enough repo."""
+        reqs = self.wrapper.Requirements({"repo": {"hard": [1, 0]}})
+        reqs.assert_all()
+
+    def test_assert_all_old_repo(self):
+        """Check assert_all rejects old repo."""
+        reqs = self.wrapper.Requirements({"repo": {"hard": [99999, 0]}})
+        with self.assertRaises(SystemExit):
+            reqs.assert_all()
+
+    def test_assert_all_new_python(self):
+        """Check assert_all accepts new enough python."""
+        reqs = self.wrapper.Requirements({"python": {"hard": sys.version_info}})
+        reqs.assert_all()
+
+    def test_assert_all_old_python(self):
+        """Check assert_all rejects old python."""
+        reqs = self.wrapper.Requirements({"python": {"hard": [99999, 0]}})
+        with self.assertRaises(SystemExit):
+            reqs.assert_all()
+
+    def test_assert_ver_unknown(self):
+        """Check assert_ver works with incompatible file."""
+        reqs = self.wrapper.Requirements({})
+        reqs.assert_ver("xxx", (1, 0))
+
+    def test_assert_ver_new(self):
+        """Check assert_ver allows new enough versions."""
+        reqs = self.wrapper.Requirements(
+            {"git": {"hard": [1, 0], "soft": [2, 0]}}
+        )
+        reqs.assert_ver("git", (1, 0))
+        reqs.assert_ver("git", (1, 5))
+        reqs.assert_ver("git", (2, 0))
+        reqs.assert_ver("git", (2, 5))
+
+    def test_assert_ver_old(self):
+        """Check assert_ver rejects old versions."""
+        reqs = self.wrapper.Requirements(
+            {"git": {"hard": [1, 0], "soft": [2, 0]}}
+        )
+        with self.assertRaises(SystemExit):
+            reqs.assert_ver("git", (0, 5))
+
+
+class NeedSetupGnuPG(RepoWrapperTestCase):
+    """Check NeedSetupGnuPG behavior."""
+
+    def test_missing_dir(self):
+        """The ~/.repoconfig tree doesn't exist yet."""
+        with tempfile.TemporaryDirectory(prefix="repo-tests") as tempdir:
+            self.wrapper.home_dot_repo = os.path.join(tempdir, "foo")
+            self.assertTrue(self.wrapper.NeedSetupGnuPG())
+
+    def test_missing_keyring(self):
+        """The keyring-version file doesn't exist yet."""
+        with tempfile.TemporaryDirectory(prefix="repo-tests") as tempdir:
+            self.wrapper.home_dot_repo = tempdir
+            self.assertTrue(self.wrapper.NeedSetupGnuPG())
+
+    def test_empty_keyring(self):
+        """The keyring-version file exists, but is empty."""
+        with tempfile.TemporaryDirectory(prefix="repo-tests") as tempdir:
+            self.wrapper.home_dot_repo = tempdir
+            with open(os.path.join(tempdir, "keyring-version"), "w"):
+                pass
+            self.assertTrue(self.wrapper.NeedSetupGnuPG())
+
+    def test_old_keyring(self):
+        """The keyring-version file exists, but it's old."""
+        with tempfile.TemporaryDirectory(prefix="repo-tests") as tempdir:
+            self.wrapper.home_dot_repo = tempdir
+            with open(os.path.join(tempdir, "keyring-version"), "w") as fp:
+                fp.write("1.0\n")
+            self.assertTrue(self.wrapper.NeedSetupGnuPG())
+
+    def test_new_keyring(self):
+        """The keyring-version file exists, and is up-to-date."""
+        with tempfile.TemporaryDirectory(prefix="repo-tests") as tempdir:
+            self.wrapper.home_dot_repo = tempdir
+            with open(os.path.join(tempdir, "keyring-version"), "w") as fp:
+                fp.write("1000.0\n")
+            self.assertFalse(self.wrapper.NeedSetupGnuPG())
+
+
+class SetupGnuPG(RepoWrapperTestCase):
+    """Check SetupGnuPG behavior."""
+
+    def test_full(self):
+        """Make sure it works completely."""
+        with tempfile.TemporaryDirectory(prefix="repo-tests") as tempdir:
+            self.wrapper.home_dot_repo = tempdir
+            self.wrapper.gpg_dir = os.path.join(
+                self.wrapper.home_dot_repo, "gnupg"
+            )
+            self.assertTrue(self.wrapper.SetupGnuPG(True))
+            with open(os.path.join(tempdir, "keyring-version")) as fp:
+                data = fp.read()
+            self.assertEqual(
+                ".".join(str(x) for x in self.wrapper.KEYRING_VERSION),
+                data.strip(),
+            )
+
+
+class VerifyRev(RepoWrapperTestCase):
+    """Check verify_rev behavior."""
+
+    def test_verify_passes(self):
+        """Check when we have a valid signed tag."""
+        desc_result = subprocess.CompletedProcess([], 0, "v1.0\n", "")
+        gpg_result = subprocess.CompletedProcess([], 0, "", "")
+        with mock.patch.object(
+            self.wrapper, "run_git", side_effect=(desc_result, gpg_result)
+        ):
+            ret = self.wrapper.verify_rev(
+                "/", "refs/heads/stable", "1234", True
+            )
+            self.assertEqual("v1.0^0", ret)
+
+    def test_unsigned_commit(self):
+        """Check we fall back to signed tag when we have an unsigned commit."""
+        desc_result = subprocess.CompletedProcess([], 0, "v1.0-10-g1234\n", "")
+        gpg_result = subprocess.CompletedProcess([], 0, "", "")
+        with mock.patch.object(
+            self.wrapper, "run_git", side_effect=(desc_result, gpg_result)
+        ):
+            ret = self.wrapper.verify_rev(
+                "/", "refs/heads/stable", "1234", True
+            )
+            self.assertEqual("v1.0^0", ret)
+
+    def test_verify_fails(self):
+        """Check we fall back to signed tag when we have an unsigned commit."""
+        desc_result = subprocess.CompletedProcess([], 0, "v1.0-10-g1234\n", "")
+        gpg_result = Exception
+        with mock.patch.object(
+            self.wrapper, "run_git", side_effect=(desc_result, gpg_result)
+        ):
+            with self.assertRaises(Exception):
+                self.wrapper.verify_rev("/", "refs/heads/stable", "1234", True)
+
+
+class GitCheckoutTestCase(RepoWrapperTestCase):
+    """Tests that use a real/small git checkout."""
+
+    GIT_DIR = None
+    REV_LIST = None
+
+    @classmethod
+    def setUpClass(cls):
+        # Create a repo to operate on, but do it once per-class.
+        cls.tempdirobj = tempfile.TemporaryDirectory(prefix="repo-rev-tests")
+        cls.GIT_DIR = cls.tempdirobj.name
+        run_git = wrapper.Wrapper().run_git
+
+        remote = os.path.join(cls.GIT_DIR, "remote")
+        os.mkdir(remote)
+
+        # Tests need to assume, that main is default branch at init,
+        # which is not supported in config until 2.28.
+        if git_command.git_require((2, 28, 0)):
+            initstr = "--initial-branch=main"
+        else:
+            # Use template dir for init.
+            templatedir = tempfile.mkdtemp(prefix=".test-template")
+            with open(os.path.join(templatedir, "HEAD"), "w") as fp:
+                fp.write("ref: refs/heads/main\n")
+            initstr = "--template=" + templatedir
+
+        run_git("init", initstr, cwd=remote)
+        run_git("commit", "--allow-empty", "-minit", cwd=remote)
+        run_git("branch", "stable", cwd=remote)
+        run_git("tag", "v1.0", cwd=remote)
+        run_git("commit", "--allow-empty", "-m2nd commit", cwd=remote)
+        cls.REV_LIST = run_git(
+            "rev-list", "HEAD", cwd=remote
+        ).stdout.splitlines()
+
+        run_git("init", cwd=cls.GIT_DIR)
+        run_git(
+            "fetch",
+            remote,
+            "+refs/heads/*:refs/remotes/origin/*",
+            cwd=cls.GIT_DIR,
+        )
+
+    @classmethod
+    def tearDownClass(cls):
+        if not cls.tempdirobj:
+            return
+
+        cls.tempdirobj.cleanup()
+
+
+class ResolveRepoRev(GitCheckoutTestCase):
+    """Check resolve_repo_rev behavior."""
+
+    def test_explicit_branch(self):
+        """Check refs/heads/branch argument."""
+        rrev, lrev = self.wrapper.resolve_repo_rev(
+            self.GIT_DIR, "refs/heads/stable"
+        )
+        self.assertEqual("refs/heads/stable", rrev)
+        self.assertEqual(self.REV_LIST[1], lrev)
+
+        with self.assertRaises(self.wrapper.CloneFailure):
+            self.wrapper.resolve_repo_rev(self.GIT_DIR, "refs/heads/unknown")
+
+    def test_explicit_tag(self):
+        """Check refs/tags/tag argument."""
+        rrev, lrev = self.wrapper.resolve_repo_rev(
+            self.GIT_DIR, "refs/tags/v1.0"
+        )
+        self.assertEqual("refs/tags/v1.0", rrev)
+        self.assertEqual(self.REV_LIST[1], lrev)
+
+        with self.assertRaises(self.wrapper.CloneFailure):
+            self.wrapper.resolve_repo_rev(self.GIT_DIR, "refs/tags/unknown")
+
+    def test_branch_name(self):
+        """Check branch argument."""
+        rrev, lrev = self.wrapper.resolve_repo_rev(self.GIT_DIR, "stable")
+        self.assertEqual("refs/heads/stable", rrev)
+        self.assertEqual(self.REV_LIST[1], lrev)
+
+        rrev, lrev = self.wrapper.resolve_repo_rev(self.GIT_DIR, "main")
+        self.assertEqual("refs/heads/main", rrev)
+        self.assertEqual(self.REV_LIST[0], lrev)
+
+    def test_tag_name(self):
+        """Check tag argument."""
+        rrev, lrev = self.wrapper.resolve_repo_rev(self.GIT_DIR, "v1.0")
+        self.assertEqual("refs/tags/v1.0", rrev)
+        self.assertEqual(self.REV_LIST[1], lrev)
+
+    def test_full_commit(self):
+        """Check specific commit argument."""
+        commit = self.REV_LIST[0]
+        rrev, lrev = self.wrapper.resolve_repo_rev(self.GIT_DIR, commit)
+        self.assertEqual(commit, rrev)
+        self.assertEqual(commit, lrev)
+
+    def test_partial_commit(self):
+        """Check specific (partial) commit argument."""
+        commit = self.REV_LIST[0][0:20]
+        rrev, lrev = self.wrapper.resolve_repo_rev(self.GIT_DIR, commit)
+        self.assertEqual(self.REV_LIST[0], rrev)
+        self.assertEqual(self.REV_LIST[0], lrev)
+
+    def test_unknown(self):
+        """Check unknown ref/commit argument."""
+        with self.assertRaises(self.wrapper.CloneFailure):
+            self.wrapper.resolve_repo_rev(self.GIT_DIR, "boooooooya")
+
+
+class CheckRepoVerify(RepoWrapperTestCase):
+    """Check check_repo_verify behavior."""
+
+    def test_no_verify(self):
+        """Always fail with --no-repo-verify."""
+        self.assertFalse(self.wrapper.check_repo_verify(False))
+
+    def test_gpg_initialized(self):
+        """Should pass if gpg is setup already."""
+        with mock.patch.object(
+            self.wrapper, "NeedSetupGnuPG", return_value=False
+        ):
+            self.assertTrue(self.wrapper.check_repo_verify(True))
+
+    def test_need_gpg_setup(self):
+        """Should pass/fail based on gpg setup."""
+        with mock.patch.object(
+            self.wrapper, "NeedSetupGnuPG", return_value=True
+        ):
+            with mock.patch.object(self.wrapper, "SetupGnuPG") as m:
+                m.return_value = True
+                self.assertTrue(self.wrapper.check_repo_verify(True))
+
+                m.return_value = False
+                self.assertFalse(self.wrapper.check_repo_verify(True))
+
+
+class CheckRepoRev(GitCheckoutTestCase):
+    """Check check_repo_rev behavior."""
+
+    def test_verify_works(self):
+        """Should pass when verification passes."""
+        with mock.patch.object(
+            self.wrapper, "check_repo_verify", return_value=True
+        ):
+            with mock.patch.object(
+                self.wrapper, "verify_rev", return_value="12345"
+            ):
+                rrev, lrev = self.wrapper.check_repo_rev(self.GIT_DIR, "stable")
+        self.assertEqual("refs/heads/stable", rrev)
+        self.assertEqual("12345", lrev)
+
+    def test_verify_fails(self):
+        """Should fail when verification fails."""
+        with mock.patch.object(
+            self.wrapper, "check_repo_verify", return_value=True
+        ):
+            with mock.patch.object(
+                self.wrapper, "verify_rev", side_effect=Exception
+            ):
+                with self.assertRaises(Exception):
+                    self.wrapper.check_repo_rev(self.GIT_DIR, "stable")
+
+    def test_verify_ignore(self):
+        """Should pass when verification is disabled."""
+        with mock.patch.object(
+            self.wrapper, "verify_rev", side_effect=Exception
+        ):
+            rrev, lrev = self.wrapper.check_repo_rev(
+                self.GIT_DIR, "stable", repo_verify=False
+            )
+        self.assertEqual("refs/heads/stable", rrev)
+        self.assertEqual(self.REV_LIST[1], lrev)

tox.ini

@@ -15,8 +15,49 @@
 # https://tox.readthedocs.io/
 
 [tox]
-envlist = py27, py36, py37, py38
+envlist = lint, py36, py37, py38, py39, py310, py311, py312
+requires = virtualenv<20.22.0
+
+[gh-actions]
+python =
+    3.6: py36
+    3.7: py37
+    3.8: py38
+    3.9: py39
+    3.10: py310
+    3.11: py311
+    3.12: py312
 
 [testenv]
-deps = pytest
-commands = {toxinidir}/run_tests
+deps =
+    -c constraints.txt
+    black
+    flake8
+    isort
+    pytest
+    pytest-timeout
+commands = {envpython} run_tests {posargs}
+setenv =
+    GIT_AUTHOR_NAME = Repo test author
+    GIT_COMMITTER_NAME = Repo test committer
+    EMAIL = repo@gerrit.nodomain
+
+[testenv:lint]
+skip_install = true
+deps =
+    -c constraints.txt
+    black
+    flake8
+commands =
+    black --check {posargs:. repo run_tests release/update-hooks release/update-manpages}
+    flake8
+
+[testenv:format]
+skip_install = true
+deps =
+    -c constraints.txt
+    black
+    flake8
+commands =
+    black {posargs:. repo run_tests release/update-hooks release/update-manpages}
+    flake8

wrapper.py

@@ -1,5 +1,3 @@
-# -*- coding:utf-8 -*-
-#
 # Copyright (C) 2014 The Android Open Source Project
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -14,22 +12,25 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-from __future__ import print_function
-try:
-  from importlib.machinery import SourceFileLoader
-  _loader = lambda *args: SourceFileLoader(*args).load_module()
-except ImportError:
-  import imp
-  _loader = lambda *args: imp.load_source(*args)
+import functools
+import importlib.machinery
+import importlib.util
 import os
 
 
-def WrapperPath():
-  return os.path.join(os.path.dirname(__file__), 'repo')
+def WrapperDir():
+    return os.path.dirname(__file__)
 
-_wrapper_module = None
+
+def WrapperPath():
+    return os.path.join(WrapperDir(), "repo")
+
+
+@functools.lru_cache(maxsize=None)
 def Wrapper():
-  global _wrapper_module
-  if not _wrapper_module:
-    _wrapper_module = _loader('wrapper', WrapperPath())
-  return _wrapper_module
+    modname = "wrapper"
+    loader = importlib.machinery.SourceFileLoader(modname, WrapperPath())
+    spec = importlib.util.spec_from_loader(modname, loader)
+    module = importlib.util.module_from_spec(spec)
+    loader.exec_module(module)
+    return module