info: reuse branch snapshots and combine history walks

Derive the current branch from GetBranches so attached HEAD and refs are
resolved once, including overview reporting. Replace the two
complementary rev-list calls in --all output with one --left-right
symmetric-difference walk and partition its records in memory.

Bug: 553599402
Change-Id: I01d5db804cbf591ecc0e08d6605971f0f5a38538
Reviewed-on: https://gerrit-review.googlesource.com/c/git-repo/+/634005
Tested-by: Gavin Mak <gavinmak@google.com>
Reviewed-by: Brian Gan <brgan@google.com>
Commit-Queue: Gavin Mak <gavinmak@google.com>

.gitignore

@@ -12,3 +12,8 @@ __pycache__
 
 # PyCharm related
 /.idea/
+
+# AI tool related.
+/AGENTS.md
+/CLAUDE.md
+/GEMINI.md

agents/README.md

@@ -0,0 +1,42 @@
+# git-repo AI Review Agents (WIP)
+
+**Note:** This project is a work in progress and is subject to change.
+
+This directory contains configurations and skills for AI review agents that
+automatically analyze changes in the `git-repo` codebase.
+
+These agents help maintain code quality, enforce style guidelines, and catch
+common pitfalls before code is merged.
+
+## Directory Structure
+
+*   [`agent_configs.txtpb`](agent_configs.txtpb): Defines the active AI
+    agents, their configurations, and which skills they are equipped with.
+*   [`skills/`](skills/): Contains the "skills" (rules, guidelines, and traps)
+    used by the agents.
+    *   [`code_review_workflow/`](skills/code_review_workflow/SKILL.md):
+        Guidelines for code review processes, commit messages, and testing.
+    *   [`core_internals/`](skills/core_internals/SKILL.md): Technical
+        guidelines for `git-repo` core logic (sync, manifest, git integration,
+        etc.).
+
+## How It Works
+
+The agents defined in `agent_configs.txtpb` are configured to run
+automatically on new changes. They analyze the diffs against the rules defined
+in their respective skills and provide feedback in the code review interface
+(e.g., Gerrit).
+
+## Contributing
+
+To improve the agent's review quality or add new rules:
+
+1.  **Update existing skills**: Modify the `SKILL.md` files under `skills/` to
+    add new rules, "What" explanations, "Why" rationales, and "Traps"
+    (Don't/Do code examples).
+2.  **Add new skills**:
+    *   Create a new directory under `skills/`.
+    *   Add a `SKILL.md` following the established format (see existing skills
+        for reference).
+    *   Register the new skill in `agent_configs.txtpb` by adding it to the
+        `skills` field of an agent configuration.

agents/agent_configs.txtpb

@@ -0,0 +1,26 @@
+# proto-file: google/corp/android/engprod/codereviewagentconfiguration/v1/agent.proto
+# proto-message: HostAgents
+
+# Code Review Workflow Agent
+configs {
+  id: "code-review-workflow"
+  display_name: "Code Review Workflow"
+  description: "Analyzes git-repo Gerrit submission labeling, commit metadata, Python linting, and testing strategy."
+  skills: "code_review_workflow"
+  include_filters {
+    project: "git-repo"
+  }
+  automatic: false
+}
+
+# Core Internals Agent
+configs {
+  id: "core-internals"
+  display_name: "Core Internals"
+  description: "Analyzes git-repo synchronization, multiprocessing, manifest parsing, git integration, worktree layouts, and CLI commands."
+  skills: "core_internals"
+  include_filters {
+    project: "git-repo"
+  }
+  automatic: false
+}

agents/skills/code_review_workflow/SKILL.md

@@ -0,0 +1,968 @@
+---
+name: code-review-workflow
+description: Provides guidance and best practices on Gerrit submission labeling, CI builder execution, Python code formatting/linting, commit metadata standardization, and testing strategy in git-repo.
+---
+
+# Code Review Workflow Engineering Guide
+
+## Executive Summary
+
+Welcome to the authoritative engineering guide for the Code Review Workflow.
+This living repository exists to capture critical folk knowledge, prevent the
+recurrence of historical failure modes, and enforce strict architectural and
+procedural boundaries across our integration pipeline. By standardizing these
+protocols, we ensure high development velocity while maintaining rock-solid
+codebase stability and traceability.
+
+This guide covers the complete lifecycle of a change list (CL) from local
+development to automated submission. It defines the strict Gerrit labeling
+mechanisms required to trigger the Commit-Queue, mandates comprehensive CI
+builder environment checks, and enforces centralized Python static analysis.
+Furthermore, it outlines uncompromising standards for atomic commit metadata and
+pragmatic testing state isolation to guarantee that every integration is fully
+bisectable and verifiable.
+
+For incoming engineers, adherence to these mandates eliminates the friction of
+stalled pipelines, unreviewable monolithic changes, and silent CI regressions.
+Treat this guide as your primary roadmap for navigating the repository's strict
+submission requirements, enabling seamless transitions from peer approval to
+successfully integrated code.
+
+## Summary
+
+| Chapter Theme / Title            | Scope & Objective                         |
+| :------------------------------- | :---------------------------------------- |
+| **Gerrit Submission and Labeling | Dictates strict access controls, review   |
+: Workflow**                       : enforcement protocols, and Gerrit         :
+:                                  : labeling mechanisms required to advance   :
+:                                  : changes through the CI pipeline, ensuring :
+:                                  : seamless transitions to automated         :
+:                                  : integration via the Commit-Queue.         :
+| **CI Builder Environment and     | Defines guidelines for ensuring build     |
+: Execution Integrity**            : script resilience against missing         :
+:                                  : dependencies and managing process         :
+:                                  : execution contexts within LUCI and local  :
+:                                  : testing environments to prevent silent    :
+:                                  : builder failures.                         :
+| **Python Code Formatting and     | Governs the automated enforcement of      |
+: Linting**                        : Python style guidelines, mandating strict :
+:                                  : PEP-8 compliance, import sorting, and     :
+:                                  : consistent string quoting to ensure       :
+:                                  : codebase uniformity and prevent CI        :
+:                                  : regressions.                              :
+| **Commit Metadata and History    | Establishes the structural composition    |
+: Standardization**                : and metadata formatting of change lists   :
+:                                  : (CLs) to ensure precise issue tracker     :
+:                                  : integration, reliable CI/CD parsing, and  :
+:                                  : an atomic, bisectable repository history. :
+| **Testing Strategy and State     | Outlines test implementation boundaries,  |
+: Isolation**                      : emphasizing pragmatic mocking limits to   :
+:                                  : prevent false positives and detailing     :
+:                                  : acceptable workflows for deferred test    :
+:                                  : coverage while maintaining verification   :
+:                                  : integrity.                                :
+
+--------------------------------------------------------------------------------
+--------------------------------------------------------------------------------
+
+## Chapter: Gerrit Submission and Labeling Workflow
+
+**Context:** This domain dictates the strict access controls, review enforcement
+protocols, and specific Gerrit labeling mechanisms required to advance changes
+through the CI pipeline. Adherence ensures seamless transitions from peer
+approval to automated integration via the Commit-Queue.
+
+### Summary
+
+| Rule ID   | Principle / Constraint          | Priority | Primary Symptom /  |
+:           :                                 :          : Trap               :
+| :-------- | :------------------------------ | :------- | :----------------- |
+| **T1-01** | Explicit Labeling for Gerrit    | High     | Leaving a change   |
+:           : Automated Submission            :          : idle after         :
+:           :                                 :          : addressing         :
+:           :                                 :          : comments or        :
+:           :                                 :          : receiving a        :
+:           :                                 :          : reviewer's LGTM,   :
+:           :                                 :          : expecting the      :
+:           :                                 :          : reviewer to merge  :
+:           :                                 :          : it.                :
+| **T1-02** | Automated Submission via        | Medium   | Requesting a       |
+:           : Commit-Queue (CQ)               :          : manual push or     :
+:           :                                 :          : direct submit from :
+:           :                                 :          : repository         :
+:           :                                 :          : maintainers after  :
+:           :                                 :          : receiving code     :
+:           :                                 :          : review approval.   :
+| **T1-03** | Gerrit Trusted Contributor      | Medium   | Relying on a       |
+:           : Review Enforcement Verification :          : standard +2 vote   :
+:           :                                 :          : from a non-trusted :
+:           :                                 :          : contributor to     :
+:           :                                 :          : fulfill strict     :
+:           :                                 :          : Review-Enforcement :
+:           :                                 :          : requirements.      :
+| **T1-04** | Mandatory Gerrit Labels for     | High     | Acknowledging an   |
+:           : Automated Submission            :          : approval but       :
+:           :                                 :          : failing to apply   :
+:           :                                 :          : the appropriate    :
+:           :                                 :          : Gerrit labels to   :
+:           :                                 :          : initiate the merge :
+:           :                                 :          : pipeline.          :
+| **T1-05** | Gerrit Automated Submission     | Medium   | Leaving an         |
+:           : Triggers                        :          : approved patchset  :
+:           :                                 :          : idle and waiting   :
+:           :                                 :          : for maintainers to :
+:           :                                 :          : manually merge it. :
+| **T1-06** | Active Reviewer Rerouting for   | Medium   | Waiting weeks or   |
+:           : Stalled Changes                 :          : months for an      :
+:           :                                 :          : inactive or OOO    :
+:           :                                 :          : reviewer to        :
+:           :                                 :          : respond to a       :
+:           :                                 :          : patchset update.   :
+
+--------------------------------------------------------------------------------
+
+### Rules
+
+#### T1-01: Explicit Labeling for Gerrit Automated Submission
+
+> **Rule:** Always apply `Verified+1` and `Commit-Queue+2` explicitly to trigger
+> the final submission phase. Never assume a code approval automatically
+> initiates the pipeline.
+>
+> **What:** Changes are not merged automatically upon receiving approval;
+> contributors must explicitly set the `Verified+1` and `Commit-Queue+2` labels
+> to trigger the final submission phase.
+>
+> **Applies To:** Gerrit review UI and change submission pipeline as defined in
+> `CONTRIBUTING.md`.
+>
+> **Why:** Contributors often mistakenly assume an LGTM implies an immediate
+> merge, leading to stalled changes. The project relies on explicitly triggering
+> the Commit-Queue to finalize CI checks and perform the merge. Failing to
+> adhere to this typically results in **Stalled Submission Pipeline**.
+
+**Trap 1: Leaving a change idle after addressing comments or receiving a
+reviewer's LGTM, expecting the reviewer to merge it.**
+
+**Don't:**
+
+*   Waiting indefinitely after reviewer posts 'LGTM'.
+
+**Do:**
+
+*   Vote `Verified+1` and `Commit-Queue+2` manually to submit the change to the
+    automated queue.
+
+**Exceptions:** Contributors lacking trusted permissions must ping a repository
+maintainer to apply the final `Commit-Queue+2` vote.
+
+--------------------------------------------------------------------------------
+
+#### T1-02: Automated Submission via Commit-Queue (CQ)
+
+> **Rule:** Must utilize the Gerrit Commit-Queue (CQ) labeling system to merge
+> code. Maintainers must never perform direct manual submissions.
+>
+> **What:** Merging code must be triggered via the Gerrit Commit-Queue (CQ)
+> labeling system rather than relying on direct manual submission by
+> maintainers.
+>
+> **Applies To:** Gerrit code review UI and CI/CD submission workflow.
+>
+> **Why:** Contributors would request maintainers to directly merge patches once
+> approved, bypassing the automated commit-queue pipeline, which guarantees that
+> final integration tests pass before pushing to the target branch. Failing to
+> adhere to this typically results in **Bypassed CI / Direct Submit**.
+
+**Trap 1: Requesting a manual push or direct submit from repository maintainers
+after receiving code review approval.**
+
+**Don't:**
+
+*   Leaving a comment: "I believe everything is ready for integrating this. So
+    if either of you can submit it, it would be appreciated."
+
+**Do:**
+
+*   Applying the `Commit-Queue+2` (CQ+2) label in Gerrit, which delegates
+    testing and the final merge operation to the automated bot.
+
+--------------------------------------------------------------------------------
+
+#### T1-03: Gerrit Trusted Contributor Review Enforcement Verification
+
+> **Rule:** Verify review enforcement requirements are satisfied by contributors
+> within the explicitly configured trusted group. Never cast misleading +2 votes
+> if you lack valid trusted group privileges.
+>
+> **What:** Gerrit submission requirements may mandate specific approval levels
+> (e.g., two trusted contributors). Votes from users with +2 access who are not
+> in the designated 'trusted' group do not satisfy the 'Review-Enforcement'
+> submit requirement.
+>
+> **Applies To:** Gerrit repository administration and code review voting
+> workflows.
+>
+> **Why:** Non-trusted contributors with +2 rights were casting +2 votes on
+> changes. These votes did not fulfill the 'Two trusted contributors'
+> Review-Enforcement requirement, leading to stalled submissions and confusion
+> regarding why the UI showed a +2 but blocked submission. Failing to adhere to
+> this typically results in **Blocked Submission / Silent Requirement Failure**.
+
+**Trap 1: Relying on a standard +2 vote from a non-trusted contributor to
+fulfill strict Review-Enforcement requirements.**
+
+**Don't:**
+
+*   Leaving a +2 vote on a change as a non-trusted contributor, creating the
+    false appearance that the Review-Enforcement requirement has been partially
+    or fully met.
+
+**Do:**
+
+*   Verifying the reviewer is in the explicitly configured trusted group for the
+    repository. If not, the reviewer should manually downgrade their invalid +2
+    vote to a +1 to clearly indicate that their vote does not count toward the
+    enforcement threshold.
+
+**Exceptions:** Repositories where specific non-employee groups have been
+explicitly added to the trusted administrators list.
+
+--------------------------------------------------------------------------------
+
+#### T1-04: Mandatory Gerrit Labels for Automated Submission
+
+> **Rule:** Always apply `Verified+1` and `Commit-Queue+2` labels to initiate
+> the CI merge process. Never leave an approved CL in a technically unlabeled
+> state.
+>
+> **What:** A code change must receive explicit `Verified+1` and
+> `Commit-Queue+2` labels by the author or reviewer to trigger the automated CI
+> merge process.
+>
+> **Applies To:** Gerrit workflow / Merge execution phase.
+>
+> **Why:** Historically, leaving a Change List (CL) in an approved but unlabeled
+> state causes the integration pipeline to stall indefinitely, requiring manual
+> intervention or reviewer pinging to trigger the CI queue. Failing to adhere to
+> this typically results in **Merge Pipeline Stall**.
+
+**Trap 1: Acknowledging an approval but failing to apply the appropriate Gerrit
+labels to initiate the merge pipeline.**
+
+**Don't:**
+
+*   Leaving the CL in an approved state and waiting for auto-submission without
+    applying the `Verified+1` or `Commit-Queue+2` labels.
+
+**Do:**
+
+*   Explicitly applying `Verified+1` (and `Commit-Queue+2` if ready) once
+    reviewers have approved the logic, to instruct the automation to merge the
+    code.
+
+--------------------------------------------------------------------------------
+
+#### T1-05: Gerrit Automated Submission Triggers
+
+> **Rule:** Must actively signal patch readiness to Gerrit systems using proper
+> label thresholds. Avoid leaving patchsets idle assuming upstream maintainer
+> action.
+>
+> **What:** A patchset requires specific label thresholds ('Verified+1' and
+> 'Commit-Queue+2') to trigger automated submission in the Gerrit workflow.
+>
+> **Applies To:** Gerrit review UI and automated CI/CD submission process for
+> the git-repo codebase.
+>
+> **Why:** Contributors frequently asked how to integrate changes after
+> receiving an approval, leading to stalled patches because the automated
+> pipeline was not explicitly triggered. Failing to adhere to this typically
+> results in **Stalled Patch Integration**.
+
+**Trap 1: Leaving an approved patchset idle and waiting for maintainers to
+manually merge it.**
+
+**Don't:**
+
+*   Waiting indefinitely after receiving an 'LGTM' without setting workflow
+    labels.
+
+**Do:**
+
+*   The patch author manually sets the 'Verified' flag (if locally tested) and
+    applies the 'Commit-Queue+2' vote to signal readiness for automated merge.
+
+--------------------------------------------------------------------------------
+
+#### T1-06: Active Reviewer Rerouting for Stalled Changes
+
+> **Rule:** Actively reroute reviews stalled by unresponsive or out-of-office
+> (OOO) primary reviewers. Must explicitly tag alternate maintainers and
+> document the absence to prevent lifecycle stalls.
+>
+> **What:** If the primary reviewer is out-of-office (OOO) or unresponsive for
+> an extended period, contributors must actively CC and reroute the review to
+> another active maintainer.
+>
+> **Applies To:** Gerrit review cycle and reviewer assignment process.
+>
+> **Why:** Patchsets have historically stalled for over a month due to reviewers
+> taking extended leave without actively delegating their review queues. Failing
+> to adhere to this typically results in **Indefinite Review Stalls**.
+
+**Trap 1: Waiting weeks or months for an inactive or OOO reviewer to respond to
+a patchset update.**
+
+**Don't:**
+
+*   Leaving a review assigned strictly to an unresponsive reviewer without
+    notifying other maintainers or attempting to escalate.
+
+**Do:**
+
+*   Tag a new reviewer with 'PTAL' (Please Take A Look) in the thread,
+    explicitly noting the original reviewer's absence, and confirm alignment
+    with the original author.
+
+--------------------------------------------------------------------------------
+
+### Cross-Domain Dependencies
+
+*   **Upstream:** T4 | Python Code Formatting and Linting - *Proper formatting
+    and static analysis are enforced before changes become eligible for final
+    Gerrit review and automated integration.*
+*   **Upstream:** T5 | Commit Metadata and History Standardization - *Accurate
+    commit messaging and isolated history must be validated by reviewers prior
+    to receiving approval labels.*
+*   **Downstream:** T3 | CI Builder Environment and Execution Integrity -
+    *Triggering the Commit-Queue directly invokes downstream LUCI environments
+    to guarantee execution integrity prior to branch merge.*
+
+## Chapter: CI Builder Environment and Execution Integrity
+
+**Context:** This section defines strict guidelines for ensuring the resilience
+of build scripts against missing dependencies and managing process execution
+contexts within LUCI and local testing environments. Adherence guarantees robust
+verification across diverse operating systems and CI pipelines while preventing
+silent builder failures.
+
+### Summary
+
+| Rule ID   | Principle / Constraint    | Priority | Primary Symptom / Trap    |
+| :-------- | :------------------------ | :------- | :------------------------ |
+| **T3-01** | Verification Against      | High     | Running a standard local  |
+:           : Breaking Change Build     :          : `make` without testing    :
+:           : Configurations            :          : strict configurations or  :
+:           :                           :          : breaking-change flags.    :
+| **T3-02** | Windows Developer Mode    | Medium   | Attempting to run full    |
+:           : Requirements for Tool     :          : local verification on a   :
+:           : Verification              :          : standard Windows user     :
+:           :                           :          : account.                  :
+| **T3-03** | Graceful Degradation for  | Medium   | Assuming all local        |
+:           : Missing Builder Utilities :          : developer utilities exist :
+:           :                           :          : in the strict CI builder  :
+:           :                           :          : environment and           :
+:           :                           :          : unconditionally executing :
+:           :                           :          : them.                     :
+| **T3-04** | Contextual Diagnostic     | High     | Observing a generic CI    |
+:           : Logging for LUCI CI       :          : failure without isolating :
+:           : Failures                  :          : the specific process      :
+:           :                           :          : execution context or      :
+:           :                           :          : dependency resolution     :
+:           :                           :          : step.                     :
+
+--------------------------------------------------------------------------------
+
+### Rules
+
+#### T3-01: Verification Against Breaking Change Build Configurations
+
+> **Rule:** Always explicitly test core build structure modifications with
+> breaking changes enabled to ensure forward compatibility.
+>
+> **What:** When modifying core build structures, the build must be tested
+> explicitly with breaking changes enabled to ensure forward compatibility and
+> correct regeneration of generated files.
+>
+> **Applies To:** Local build environments and Makefile targets.
+>
+> **Why:** Changes might succeed in a standard default build but fail when
+> breaking change toggles are activated, hiding underlying dependency or
+> regeneration issues. Failing to adhere to this typically results in **Build
+> Breakage / Stale Artifacts**.
+
+**Trap 1: Running a standard local `make` without testing strict configurations
+or breaking-change flags.**
+
+**Don't:**
+
+```bash
+make -j
+```
+
+**Do:**
+
+```bash
+make -j WITH_BREAKING_CHANGES=1
+```
+
+--------------------------------------------------------------------------------
+
+#### T3-02: Windows Developer Mode Requirements for Tool Verification
+
+> **Rule:** Must execute local tool verification on Windows (gWindows) using an
+> Administrator account to enable Developer Mode.
+>
+> **What:** Local verification of git-repo tooling on Windows (gWindows)
+> explicitly requires the host environment to be running with Administrator
+> privileges to enable Developer Mode.
+>
+> **Applies To:** Windows (gWindows) test environments verifying file system
+> operations.
+>
+> **Why:** Without Developer Mode enabled (which necessitates Admin rights),
+> features relying on advanced OS-level file system operations (like symlinks)
+> cannot execute, permanently blocking full local test suite execution on
+> standard accounts. Failing to adhere to this typically results in
+> **Verification Blocked / OS Permission Error**.
+
+**Trap 1: Attempting to run full local verification on a standard Windows user
+account.**
+
+**Don't:**
+
+*   Executing the test suite from a non-elevated command prompt on Windows
+    without Developer Mode.
+
+**Do:**
+
+*   Elevate to an Administrator account to enable Developer Mode before
+    executing the test suite on gWindows.
+
+--------------------------------------------------------------------------------
+
+#### T3-03: Graceful Degradation for Missing Builder Utilities
+
+> **Rule:** Always implement auto-skip logic for optional utilities in build
+> scripts rather than hard-failing when unavailable on the CI builder.
+>
+> **What:** Build scripts and test suites must implement auto-skip logic for
+> optional, environment-specific utilities rather than hard-failing when the
+> utility is unavailable on the CI builder.
+>
+> **Applies To:** CI Builder environment scripts and test suites, specifically
+> testing external CLI utilities (e.g., `help2man`).
+>
+> **Why:** When a required utility was not pre-installed on the CI builder
+> image, the build hard-failed. Adding auto-skip logic allows the CI pipeline to
+> remain unblocked while still providing local testing benefits for developers
+> who have the tool installed. Failing to adhere to this typically results in
+> **Build Failure / Blocked CI**.
+
+**Trap 1: Assuming all local developer utilities exist in the strict CI builder
+environment and unconditionally executing them.**
+
+**Don't:**
+
+```python
+# BAD: Hard failure if utility is missing
+subprocess.run(["help2man", "repo"], check=True)
+```
+
+**Do:**
+
+```python
+# GOOD: Auto-skip test if utility is missing in the environment
+if not shutil.which("help2man"):
+    self.skipTest("help2man not installed")
+subprocess.run(["help2man", "repo"], check=True)
+```
+
+**Exceptions:** Core dependencies required for fundamental build steps cannot be
+skipped and must be installed on the bot image.
+
+--------------------------------------------------------------------------------
+
+#### T3-04: Contextual Diagnostic Logging for LUCI CI Failures
+
+> **Rule:** Must investigate CI builder failures by extracting and analyzing
+> full execution context logs to isolate environmental roadblocks.
+>
+> **What:** CI builder failures must be investigated using full execution
+> context logs (e.g., LUCI context, vpython3 resolution, and retcode outputs) to
+> isolate environmental roadblocks.
+>
+> **Applies To:** LUCI builder execution environment, vpython3 resolution, and
+> CI pipeline debugging.
+>
+> **Why:** CI commands failed with `retcode 1` due to external factors like
+> specific URLs being flagged as suspect by internal security tools, breaking
+> the build environment. Failing to adhere to this typically results in **Silent
+> Builder Failure**.
+
+**Trap 1: Observing a generic CI failure without isolating the specific process
+execution context or dependency resolution step.**
+
+**Don't:**
+
+*   Restarting the CI pipeline blindly when a job fails with a generic retcode,
+    ignoring potential external network or security blockers.
+
+**Do:**
+
+*   Extract the step-by-step LUCI context log, verify path resolution (e.g.,
+    CIPD packages), and explicitly document external blockers like security
+    flags in the review.
+
+--------------------------------------------------------------------------------
+
+### Cross-Domain Dependencies
+
+*   **Upstream:** T6 | Testing Strategy and State Isolation - *Test
+    implementation dictates how missing builder utilities are mocked or
+    gracefully skipped during execution.*
+*   **Downstream:** T1 | Gerrit Submission and Labeling Workflow - *Automated
+    Verified+1 labels rely entirely on the stable, unblocked execution of CI
+    builder pipelines.*
+
+## Chapter: Python Code Formatting and Linting
+
+**Context:** This domain governs the automated enforcement of Python style
+guidelines, mandating strict PEP-8 compliance, import sorting, and consistent
+string quoting. All Python modifications must pass centralized static analysis
+pipelines before integration to ensure codebase uniformity and prevent CI
+regressions.
+
+### Summary
+
+| Rule ID   | Principle / Constraint   | Priority | Primary Symptom / Trap    |
+| :-------- | :----------------------- | :------- | :------------------------ |
+| **T4-01** | Automated Flake8         | Medium   | Relying purely on manual  |
+:           : Post-Submit Verification :          : code review or sporadic   :
+:           :                          :          : local linting without a   :
+:           :                          :          : continuous integration    :
+:           :                          :          : check.                    :
+| **T4-02** | Mandatory Python         | High     | Using single quotes for   |
+:           : Formatting and Import    :          : strings and appending new :
+:           : Sorting                  :          : imports to the bottom of  :
+:           :                          :          : the import block without  :
+:           :                          :          : alphabetical or           :
+:           :                          :          : categorical sorting.      :
+| **T4-03** | Strict Python Import     | High     | Mixing local application  |
+:           : Ordering                 :          : imports with standard     :
+:           :                          :          : library imports, causing  :
+:           :                          :          : linting tools to fail the :
+:           :                          :          : CQ job.                   :
+
+--------------------------------------------------------------------------------
+
+### Rules
+
+#### T4-01: Automated Flake8 Post-Submit Verification
+
+> **Rule:** Always configure and maintain centralized CI workflows to
+> automatically run static analysis and validate Python code styling
+> post-submit.
+>
+> **What:** Static analysis and Python linting must be automated via a
+> centralized CI pipeline (e.g., Flake8 post-submit workflows) to enforce
+> consistent style and prevent basic errors.
+>
+> **Applies To:** All Python files in the git-repo codebase; specifically
+> validated via `.github/workflows/flake8-postsubmit.yml`.
+>
+> **Why:** Relying strictly on manual code review to catch styling and linting
+> violations is error-prone. Automation ensures a baseline of code quality on
+> every code push without consuming human review cycles. Failing to adhere to
+> this typically results in **Linting Regression / Style Violation**.
+
+**Trap 1: Relying purely on manual code review or sporadic local linting without
+a continuous integration check.**
+
+**Don't:**
+
+*   Committing Python code without an active CI linting workflow configuration.
+
+**Do:**
+
+*   Maintain `.github/workflows/flake8-postsubmit.yml` to automatically run
+    flake8 on target branches.
+
+--------------------------------------------------------------------------------
+
+#### T4-02: Mandatory Python Formatting and Import Sorting
+
+> **Rule:** Must format Python code to enforce double-quoted strings and
+> alphabetically sorted import blocks to satisfy automated formatting checks.
+>
+> **What:** Python code modifications must pass automated style and linting
+> checks ('Verify git-repo CL'), which strictly enforce string quote conventions
+> (preferring double quotes), import block sorting, and PEP-8 style formatting.
+>
+> **Applies To:** All Python source files modified in the git-repo codebase.
+>
+> **Why:** Developers submitting patches with single-quoted strings or unsorted
+> imports triggered automated CI failures in the `Verify git-repo CL` job,
+> completely blocking code submission until formatting tools were executed
+> locally. Failing to adhere to this typically results in **CI Pipeline
+> Failure**.
+
+**Trap 1: Using single quotes for strings and appending new imports to the
+bottom of the import block without alphabetical or categorical sorting.**
+
+**Don't:**
+
+```python
+import sys
+import os
+
+msg = 'This is an error'
+```
+
+**Do:**
+
+```python
+import os
+import sys
+
+msg = "This is an error"
+```
+
+--------------------------------------------------------------------------------
+
+#### T4-03: Strict Python Import Ordering
+
+> **Rule:** Always segment and order Python imports strictly according to
+> project standards (standard library, third-party, local) to prevent CQ
+> pipeline failures.
+>
+> **What:** Python module imports must adhere strictly to the project's
+> formatting rules (e.g., standard library, third-party, local module ordering)
+> to pass automated Commit-Queue (CQ) checks.
+>
+> **Applies To:** Python source files.
+>
+> **Why:** Non-standard import blocks cause the automated CI/CQ linting pipeline
+> to fail, completely blocking submission even if the core functional logic of
+> the patch is flawless. Failing to adhere to this typically results in **CI
+> Linting Failure**.
+
+**Trap 1: Mixing local application imports with standard library imports,
+causing linting tools to fail the CQ job.**
+
+**Don't:**
+
+```python
+import sys
+import my_local_module
+import os
+```
+
+**Do:**
+
+```python
+import os
+import sys
+
+import my_local_module
+```
+
+--------------------------------------------------------------------------------
+
+### Cross-Domain Dependencies
+
+*   **Upstream:** T3 | CI Builder Environment and Execution Integrity -
+    *Reliable CI builder environments must be available to execute the static
+    analysis and Python formatting verifications.*
+*   **Downstream:** T1 | Gerrit Submission and Labeling Workflow - *Formatting
+    and linting rules must be fully satisfied before automated mechanisms like
+    the Commit-Queue (CQ+2) will merge code into the repository.*
+
+## Chapter: Commit Metadata and History Standardization
+
+**Context:** This domain governs the structural composition and metadata
+formatting of change lists (CLs) within the git-repo codebase. Strict adherence
+ensures precise issue tracker integration, reliable CI/CD parsing, and atomic,
+bisectable repository history.
+
+### Summary
+
+| Rule ID   | Principle / Constraint    | Priority | Primary Symptom / Trap    |
+| :-------- | :------------------------ | :------- | :------------------------ |
+| **T5-01** | Strict Commit Message Bug | Medium   | Providing free-text       |
+:           : Tag Formatting            :          : descriptions, arbitrary   :
+:           :                           :          : prefixes, or non-standard :
+:           :                           :          : bug references in the     :
+:           :                           :          : commit block.             :
+| **T5-02** | Atomic and Bisectable     | High     | Waiting for an entire     |
+:           : Change Integration        :          : feature stack of multiple :
+:           :                           :          : interdependent CLs to be  :
+:           :                           :          : approved before merging   :
+:           :                           :          : the base commits.         :
+| **T5-03** | Explicit Bug Tracker      | Medium   | Submitting a fix or       |
+:           : Linking for Context       :          : revert without            :
+:           : Restoration               :          : referencing the           :
+:           :                           :          : corresponding bug tracker :
+:           :                           :          : issue detailing the       :
+:           :                           :          : specific regression or    :
+:           :                           :          : stack trace.              :
+| **T5-04** | Atomic Change List        | Medium   | Submitting a single large |
+:           : Decomposition             :          : CL that touches multiple  :
+:           :                           :          : isolated components or    :
+:           :                           :          : implements several        :
+:           :                           :          : distinct features         :
+:           :                           :          : simultaneously.           :
+
+--------------------------------------------------------------------------------
+
+### Rules
+
+#### T5-01: Strict Commit Message Bug Tag Formatting
+
+> **Rule:** Must use the exact `Bug: <number>` syntax in commit messages to
+> properly link issue trackers.
+>
+> **What:** Commit messages must link directly to issue trackers using the
+> explicit 'Bug: <number>' syntax to allow reliable parsing by CI/CD and history
+> tracking systems.
+>
+> **Applies To:** Commit messages across all git-repo changes.
+>
+> **Why:** Improperly formatted bug tags fail to link with the external issue
+> tracker, severing historical context and breaking automated post-submit
+> tracking workflows. Failing to adhere to this typically results in **Broken
+> Traceability / Pre-submit Failure**.
+
+**Trap 1: Providing free-text descriptions, arbitrary prefixes, or non-standard
+bug references in the commit block.**
+
+**Don't:**
+
+```text
+Fixes bug 486536908
+Closes issue 486536908
+```
+
+**Do:**
+
+```text
+Bug: 486536908
+```
+
+--------------------------------------------------------------------------------
+
+#### T5-02: Atomic and Bisectable Change Integration
+
+> **Rule:** Always submit code incrementally as isolated, functional units
+> rather than hoarding monolithic stacks.
+>
+> **What:** Code changes must be submitted incrementally as isolated, functional
+> units rather than waiting to merge a massive interdependent stack all at once.
+>
+> **Applies To:** Git commit history, PR structuring, and stack-based code
+> integration.
+>
+> **Why:** Contributors accustomed to integrating full monolithic stacks at once
+> held off on landing initial, stable changes. This practice hinders the ability
+> to isolate regressions via `git bisect` and prevents foundational code from
+> "baking" in production. Failing to adhere to this typically results in
+> **Bisection Breakage / Monolithic Rollbacks**.
+
+**Trap 1: Waiting for an entire feature stack of multiple interdependent CLs to
+be approved before merging the base commits.**
+
+**Don't:**
+
+*   Holding all changes in a stack locally or in code review until the final
+    feature patch is approved, then landing 10+ patches simultaneously.
+
+**Do:**
+
+*   Landing initial, independent CLs one-by-one as soon as they are approved.
+    Ensuring each commit is independently usable and does not break the build.
+
+--------------------------------------------------------------------------------
+
+#### T5-03: Explicit Bug Tracker Linking for Context Restoration
+
+> **Rule:** Must include a direct URL to the relevant bug tracker issue
+> documenting the failure traceback when submitting a regression fix or revert.
+>
+> **What:** When submitting a change (especially a revert or bug fix) addressing
+> a specific runtime regression, the commit metadata or patchset-level comments
+> must include a direct link to the bug tracker issue documenting the failure
+> traceback.
+>
+> **Applies To:** Commit messages and patchset documentation during code
+> reviews, particularly for reverts.
+>
+> **Why:** A previous commit caused a runtime regression (e.g., an
+> AttributeError related to a missing object attribute). Without linking the
+> specific issue containing the traceback, reviewers lacked the necessary
+> context to justify restoring the previous codebase state. Failing to adhere to
+> this typically results in **Undocumented Regression / Context Loss**.
+
+**Trap 1: Submitting a fix or revert without referencing the corresponding bug
+tracker issue detailing the specific regression or stack trace.**
+
+**Don't:**
+
+*   Reverting a change with a vague description like "Fixing previous breakage"
+    or "Reverting due to pipeline failure" without providing the traceback
+    source.
+
+**Do:**
+
+*   Linking the specific issue tracker URL containing the exact failure mode.
+    Example: "for more context, see
+    https://g-issues.gerritcodereview.com/issues/[ISSUE_ID]#comment4"
+
+--------------------------------------------------------------------------------
+
+#### T5-04: Atomic Change List Decomposition
+
+> **Rule:** Never submit large, monolithic change lists; always decompose them
+> into logically independent patchsets.
+>
+> **What:** Large, monolithic change lists (CLs) must be broken down into
+> smaller, logically independent patchsets to ensure accurate review and
+> historical bisectability.
+>
+> **Applies To:** Version control history and code review scoping.
+>
+> **Why:** Massive CLs heavily increase reviewer cognitive load, making thorough
+> reviews impossible and complicating future `git bisect` operations when
+> tracking down the origin of a regression. Failing to adhere to this typically
+> results in **Unreviewable Monolithic Change**.
+
+**Trap 1: Submitting a single large CL that touches multiple isolated components
+or implements several distinct features simultaneously.**
+
+**Don't:**
+
+*   A single CL containing sweeping refactoring, new feature implementation, and
+    unrelated bug fixes.
+
+**Do:**
+
+*   Breaking the monolithic change into smaller, logically dependent or
+    independent CLs where each addresses one specific piece of the feature or
+    refactor.
+
+--------------------------------------------------------------------------------
+
+### Cross-Domain Dependencies
+
+*   **Downstream:** T1 | Gerrit Submission and Labeling Workflow - *Gerrit and
+    CI pipelines strictly rely on standardized commit metadata to link tracking
+    issues and depend on atomic patchsets to execute automated review and
+    verification correctly.*
+
+## Chapter: Testing Strategy and State Isolation
+
+**Context:** This chapter governs test implementation boundaries, emphasizing
+pragmatic mocking limits to prevent false positives and detailing acceptable
+workflows for deferred test coverage. Strict adherence ensures robust state
+isolation and maintains development velocity without compromising verification
+integrity.
+
+### Summary
+
+| Rule ID   | Principle / Constraint   | Priority | Primary Symptom / Trap     |
+| :-------- | :----------------------- | :------- | :------------------------- |
+| **T6-01** | Pragmatic Mocking        | Medium   | Mocking the entire core    |
+:           : Boundaries in Unit Tests :          : state or framework         :
+:           :                          :          : dependencies just to force :
+:           :                          :          : a unit test for a highly   :
+:           :                          :          : integrated function.       :
+| **T6-02** | Deferred Test            | Medium   | Submitting functional code |
+:           : Implementation via       :          : without matching test      :
+:           : Follow-up                :          : coverage and stalling the  :
+:           :                          :          : merge while complex tests  :
+:           :                          :          : are written.               :
+
+--------------------------------------------------------------------------------
+
+### Rules
+
+#### T6-01: Pragmatic Mocking Boundaries in Unit Tests
+
+> **Rule:** Always restrict unit tests to isolated methods and avoid aggressive
+> mocking of core functionality to prevent brittle, false-positive verification.
+>
+> **What:** Do not aggressively mock core functionality in unit tests; restrict
+> unit tests to isolated methods to avoid creating brittle tests based on false
+> assumptions when an integration framework is unavailable.
+>
+> **Applies To:** Test suite implementation (Unit vs. Integration testing
+> boundaries).
+>
+> **Why:** Over-mocking complex systems in unit tests leads to scenarios where
+> tests pass but the core integration fails in production because the unit test
+> mocks assumed incorrect behavior about the underlying environment. Failing to
+> adhere to this typically results in **False Positive Test Passage**.
+
+**Trap 1: Mocking the entire core state or framework dependencies just to force
+a unit test for a highly integrated function.**
+
+**Don't:**
+
+*   Mocking file systems, external processes, and global state heavily to test a
+    core workflow orchestrator in a unit test suite.
+
+**Do:**
+
+*   Limiting unit tests strictly to isolated utility methods (e.g., adding
+    promisor files) and explicitly documenting testing gaps that require
+    integration test frameworks.
+
+**Exceptions:** Isolated helper methods or purely functional data
+transformations should be fully unit tested with appropriate mocked inputs.
+
+--------------------------------------------------------------------------------
+
+#### T6-02: Deferred Test Implementation via Follow-up
+
+> **Rule:** Never stall critical feature merges indefinitely for test
+> implementation if maintainers authorize formalized, immediate follow-up test
+> coverage.
+>
+> **What:** New logic requires automated tests; however, reviewers may permit
+> test coverage to be implemented in a subsequent follow-up CL to maintain
+> development velocity.
+>
+> **Applies To:** Feature development, regression testing, and code review
+> criteria.
+>
+> **Why:** Reviewers identified a lack of test coverage for new functionality
+> but opted not to block the immediate patchset, instead formalizing the test
+> requirement as a near-term follow-up task. Failing to adhere to this typically
+> results in **Missing Test Coverage**.
+
+**Trap 1: Submitting functional code without matching test coverage and stalling
+the merge while complex tests are written.**
+
+**Don't:**
+
+*   Blocking a necessary feature indefinitely due to missing unit tests when a
+    follow-up CL is viable and acceptable to maintainers.
+
+**Do:**
+
+*   Approve the feature with an explicit, documented 'TODO' for a follow-up CL
+    dedicated strictly to adding the corresponding automated tests.
+
+**Exceptions:** Critical path features or security fixes where a lack of
+immediate coverage introduces an unacceptable regression risk.
+
+--------------------------------------------------------------------------------
+
+### Cross-Domain Dependencies
+
+*   **Upstream:** T1 | Gerrit Submission and Labeling Workflow - *Reviewer
+    approval mechanisms and label enforcement dictate when a feature can merge
+    while deferring tests to a follow-up CL.*
+*   **Downstream:** T3 | CI Builder Environment and Execution Integrity -
+    *Pragmatically bounded unit and integration tests ensure reliable CI
+    pipeline execution without false-positive success markers.*

color.py

@@ -85,28 +85,43 @@ def _Color(fg=None, bg=None, attr=None):
 DEFAULT = None
 
 
+class _CheckConsoleSentinel:
+    """Sentinel for checking console coloring."""
+
+
+# Placholder value that indicates we need to check if the user is in an
+# interactive terminal session to determine if we turn on color or not.
+_CHECK_CONSOLE = _CheckConsoleSentinel()
+
+# https://git-scm.com/docs/git-config#Documentation/git-config.txt-colorui
+_CONFIG_TO_COLOR_SETTING = {
+    "false": False,
+    "never": False,
+    "no": False,
+    "auto": _CHECK_CONSOLE,
+    "true": _CHECK_CONSOLE,
+    "yes": _CHECK_CONSOLE,
+    "always": True,
+}
+
+
 def SetDefaultColoring(state: Optional[str]) -> None:
     """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
 
     global DEFAULT
-    state = state.lower()
-    if state in ("auto",):
+
+    if isinstance(state, str):
+        state = state.lower()
+    if state in _CONFIG_TO_COLOR_SETTING:
         DEFAULT = state
-    elif state in ("always", "yes", "true"):
-        DEFAULT = "always"
-    elif state in ("never", "no", "false"):
-        DEFAULT = "never"
 
 
 class Coloring:
     def __init__(self, config, section_type):
-        self._section = "color.%s" % section_type
+        self._section = f"color.{section_type}"
         self._config = config
         self._out = sys.stdout
 
@@ -115,16 +130,12 @@ class Coloring:
             on = self._config.GetString(self._section)
             if on is None:
                 on = self._config.GetString("color.ui")
+        if isinstance(on, str):
+            on = on.lower()
 
-        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
+        self._on = _CONFIG_TO_COLOR_SETTING.get(on, _CHECK_CONSOLE)
+        if self._on is _CHECK_CONSOLE:
+            self._on = pager.active or os.isatty(1)
 
     def redirect(self, out):
         self._out = out

command.py

@@ -17,6 +17,7 @@ import multiprocessing
 import optparse
 import os
 import re
+from typing import List, Optional, TYPE_CHECKING
 
 from error import InvalidProjectGroupsError
 from error import NoSuchProjectError
@@ -25,6 +26,10 @@ from event_log import EventLog
 import progress
 
 
+if TYPE_CHECKING:
+    from project import Project
+
+
 # Are we generating man-pages?
 GENERATE_MANPAGES = os.environ.get("_REPO_GENERATE_MANPAGES_") == " indeed! "
 
@@ -61,6 +66,10 @@ class Command:
     # command to show short-vs-full summaries.
     COMMON = False
 
+    # Whether this command should respect the smart sync override manifest if
+    # it exists.
+    RESPECT_SMART_SYNC_OVERRIDE = True
+
     # Whether this command supports running in parallel. If greater than 0,
     # it is the number of parallel jobs to default to.
     PARALLEL_JOBS = None
@@ -143,6 +152,20 @@ class Command:
             self._Options(self._optparse)
         return self._optparse
 
+    @staticmethod
+    def _GetHelpForCpuJobCount(
+        default_jobs: Optional[int] = None,
+    ) -> str:
+        """Return CPU-based job help, with an explicit default when needed.
+
+        Specify default_jobs when additional logic computes effective default.
+        """
+        if GENERATE_MANPAGES:
+            return "based on number of CPU cores"
+
+        default = "%default" if default_jobs is None else str(default_jobs)
+        return f"{default}; based on number of CPU cores"
+
     def _CommonOptions(self, p, opt_v=True):
         """Initialize the option parser with common options.
 
@@ -167,11 +190,7 @@ class Command:
         )
 
         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}"
+            default = self._GetHelpForCpuJobCount()
             p.add_option(
                 "-j",
                 "--jobs",
@@ -242,6 +261,12 @@ class Command:
             # from the user's perspective.
             opt.outer_manifest = True
 
+        if self.RESPECT_SMART_SYNC_OVERRIDE:
+            if self.manifest:
+                self.TryOverrideManifestWithSmartSync(self.manifest)
+            if self.outer_manifest and self.outer_manifest != self.manifest:
+                self.TryOverrideManifestWithSmartSync(self.outer_manifest)
+
     def ValidateOptions(self, opt, args):
         """Validate the user options & arguments before executing.
 
@@ -375,7 +400,7 @@ class Command:
         manifest=None,
         groups="",
         missing_ok=False,
-        submodules_ok=False,
+        submodules_ok=None,
         all_manifests=False,
     ):
         """A list of projects that match the arguments.
@@ -383,9 +408,15 @@ class Command:
         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.
+            groups: a string, the manifest group selection to apply.
+                Non-empty values apply to all candidate projects in this call.
+                When empty or omitted, single-manifest calls use the selected
+                manifest's effective groups; all-manifest calls use each
+                candidate project's owning manifest's effective groups.
             missing_ok: a boolean, whether to allow missing projects.
-            submodules_ok: a boolean, whether to allow submodules.
+            submodules_ok: whether to allow submodules. True allows them for
+                all projects, False disallows them for all projects, and None
+                defers to each project's sync-s setting.
             all_manifests: a boolean, if True then all manifests and
                 submanifests are used. If False, then only the local
                 (sub)manifest is used.
@@ -403,23 +434,50 @@ class Command:
             all_projects_list = manifest.projects
         result = []
 
-        if not groups:
-            groups = manifest.GetManifestGroupsStr()
-        groups = [x for x in re.split(r"[,\s]+", groups) if x]
+        def should_include_submodules(project: "Project") -> bool:
+            if submodules_ok is None:
+                return project.sync_s
+            return submodules_ok
+
+        def parse_groups(value: str) -> List[str]:
+            return [x for x in re.split(r"[,\s]+", value) if x]
+
+        if groups:
+            groups_for_all_projects = parse_groups(groups)
+        elif all_manifests:
+            # In all-manifest mode, each project uses its owning
+            # manifest's effective groups.
+            groups_for_all_projects = None
+        else:
+            groups_for_all_projects = parse_groups(
+                manifest.GetManifestGroupsStr()
+            )
+
+        groups_by_manifest = {}
+
+        def matches_groups(project: "Project") -> bool:
+            if groups_for_all_projects is not None:
+                return project.MatchesGroups(groups_for_all_projects)
+
+            project_manifest = project.manifest
+            if project_manifest not in groups_by_manifest:
+                groups_by_manifest[project_manifest] = parse_groups(
+                    project_manifest.GetManifestGroupsStr()
+                )
+
+            return project.MatchesGroups(groups_by_manifest[project_manifest])
 
         if not args:
             derived_projects = {}
             for project in all_projects_list:
-                if submodules_ok or project.sync_s:
+                if should_include_submodules(project):
                     derived_projects.update(
                         (p.RelPath(local=False), 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
-                ):
+                if (missing_ok or project.Exists) and matches_groups(project):
                     result.append(project)
         else:
             self._ResetPathToProjectMap(all_projects_list)
@@ -433,7 +491,7 @@ class Command:
                     for project in manifest.GetProjectsWithName(
                         arg, all_manifests=all_manifests
                     )
-                    if project.MatchesGroups(groups)
+                    if matches_groups(project)
                 ]
 
                 if not projects:
@@ -452,7 +510,7 @@ class Command:
                     if (
                         project
                         and not project.Derived
-                        and (submodules_ok or project.sync_s)
+                        and should_include_submodules(project)
                     ):
                         search_again = False
                         for subproject in project.GetDerivedSubprojects():
@@ -476,7 +534,7 @@ class Command:
                             "%s (%s)"
                             % (arg, project.RelPath(local=not all_manifests))
                         )
-                    if not project.MatchesGroups(groups):
+                    if not matches_groups(project):
                         raise InvalidProjectGroupsError(arg)
 
                 result.extend(projects)
@@ -487,7 +545,14 @@ class Command:
         result.sort(key=_getpath)
         return result
 
-    def FindProjects(self, args, inverse=False, all_manifests=False):
+    def FindProjects(
+        self,
+        args: List[str],
+        inverse: bool = False,
+        all_manifests: bool = False,
+        groups: Optional[str] = "",
+        missing_ok: Optional[bool] = False,
+    ) -> List["Project"]:
         """Find projects from command line arguments.
 
         Args:
@@ -497,10 +562,18 @@ class Command:
             all_manifests: a boolean, if True then all manifests and
                 submanifests are used. If False, then only the local
                 (sub)manifest is used.
+            groups: a string specifying manifest groups. If empty or None, use
+                each manifest's effective groups.
+            missing_ok: a boolean, whether to allow missing projects.
         """
         result = []
         patterns = [re.compile(r"%s" % a, re.IGNORECASE) for a in args]
-        for project in self.GetProjects("", all_manifests=all_manifests):
+        for project in self.GetProjects(
+            "",
+            groups=groups,
+            missing_ok=missing_ok,
+            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)

completion.zsh

@@ -322,7 +322,10 @@ _repo() {
         '--no-clone-bundle[Do not use clone bundle]' \
         '(-u --manifest-server-username)'{-u,--manifest-server-username=}'[Username for manifest server]:username:' \
         '(-p --manifest-server-password)'{-p,--manifest-server-password=}'[Password for manifest server]:password:' \
-        '--fetch-submodules[Fetch submodules]' \
+        '--recurse-submodules[Sync submodules]' \
+        '--no-recurse-submodules[Do not sync submodules]' \
+        '--fetch-submodules[Deprecated alias for --recurse-submodules]' \
+        '--no-fetch-submodules[Deprecated alias for --no-recurse-submodules]' \
         '--use-superproject[Use superproject]' \
         '--no-use-superproject[Do not use superproject]' \
         '--tags[Sync tags]' \
@@ -397,6 +400,7 @@ _repo() {
         '--no-verify[Do not verify]' \
         '--verify[Verify]' \
         '--ignore-hooks[Ignore hooks]' \
+        '--fix[Automatically fix]' \
         '*: :->project'
       ;;
     version)

docs/fetch-cmd.md

@@ -0,0 +1,66 @@
+# Fetch Command Contract
+
+The `repo.fetchcmd` configuration allows specifying a custom command to be
+executed during `repo sync` to fetch objects, instead of using standard
+`git fetch`. This is particularly useful in environments with virtualized
+filesystems or lazy checkouts where fetching metadata and downloading file
+contents should be decoupled.
+
+The checkout half of a sync has a counterpart, `repo.reprojectcmd`; see
+`docs/reproject-cmd.md`.
+
+## Configuration
+
+To use this feature, set the following in `.repo/manifests.git/config`:
+```ini
+[repo]
+	fetchcmd = "your custom command here"
+	uselocalgitdirs = true
+```
+Setting `repo.fetchcmd` **requires** `repo.uselocalgitdirs` to be set to `true`.
+
+## Environment Variables
+
+The custom command is executed in a subshell populated with standard
+project-context environment variables. For details on standard variables (such
+as `REPO_PROJECT`, `REPO_PATH`, `REPO_PROJECT_FETCH_URL`, etc.), see the
+Environment section in `repo help forall` or `subcmds/forall.py`.
+
+The following environment variable is specific to `repo.fetchcmd`:
+
+*   `REPO_TREV`: The target revision resolved to a full commit hash.
+
+## Contract
+
+### Postconditions on exit 0
+
+After the fetch command exits with status 0, `repo` expects the following
+postconditions to be met:
+
+1.  `git cat-file -e REPO_TREV` succeeds (the commit must exist in the object
+    store).
+2.  The mapped local tracking ref (e.g. `refs/remotes/REPO_REMOTE/<branch>`
+    for a branch revision, or the tag ref itself for a tag) must point to
+    `REPO_TREV`.
+3.  `FETCH_HEAD` must point to `REPO_TREV`.
+4.  The commit graph from `REPO_TREV` must be reachable far enough to compute
+    merge bases with local branches.
+
+### Invariants
+
+*   The command should be idempotent; fetching the same `REPO_TREV` twice should
+    be a no-op.
+*   Only `FETCH_HEAD` and `refs/remotes/*` should be modified to preserve
+    `repo sync --network-only` semantics. `HEAD` and local branches must not be
+    touched by the fetch command.
+*   Dirty worktree state must be preserved.
+*   The command is **not** executed for `MetaProject`s (i.e. the internal `repo`
+    repository itself at `.repo/repo` and the `manifests` repository at
+    `.repo/manifests`).
+
+### Failure
+
+*   A non-zero exit status aborts the project's sync, and the command's stderr
+    is surfaced to the user.
+*   `repo` verifies the tracking ref and target reachability after exit 0. Any
+    mismatch is treated as a failure.

docs/internal-fs-layout.md

@@ -182,7 +182,7 @@ User controlled settings are initialized when running `repo init`.
 | 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
+[partial git clones]: https://git-scm.com/docs/partial-clone
 [superproject]: https://en.wikibooks.org/wiki/Git/Submodules_and_Superprojects
 
 ### Repo hooks settings

docs/manifest-format.md

@@ -58,6 +58,7 @@ following DTD:
 
   <!ELEMENT manifest-server EMPTY>
   <!ATTLIST manifest-server url CDATA #REQUIRED>
+  <!ATTLIST manifest-server helper CDATA #IMPLIED>
 
   <!ELEMENT submanifest EMPTY>
   <!ATTLIST submanifest name           ID    #REQUIRED>
@@ -239,6 +240,11 @@ XML RPC service.
 
 See the [smart sync documentation](./smart-sync.md) for more details.
 
+Attribute `url`: The URL of the manifest server.
+
+Attribute `helper`: Optional name of a remote helper binary to execute to
+resolve proxying or authentication for the manifest server.
+
 
 ### Element submanifest
 

docs/repo-hooks.md

@@ -83,6 +83,20 @@ then check it directly.  Hooks should not normally modify the active git repo
 the user.  Although user interaction is discouraged in the common case, it can
 be useful when deploying automatic fixes.
 
+### Safe Prompts
+
+If the repo command that triggered the hook supports a "yes" option (e.g.,
+`repo upload --yes`), this option is propagated to the hook's `main` function
+as `yes` parameter (defaulting to `False`).  Hooks can use this to bypass
+interactive confirmation prompts for safe non-modifying operations.
+
+### Automated Fixes
+
+If the repo command that triggered the hook supports a "fix" option (e.g.,
+`repo upload --fix`), this option is propagated to the hook's `main` function
+as `fix` parameter (defaulting to `False`).  Hooks can use this to automatically
+apply fixes without prompting the user.
+
 ### Shebang Handling
 
 *** note
@@ -119,7 +133,7 @@ This hook runs when people run `repo upload`.
 The `pre-upload.py` file should be defined like:
 
 ```py
-def main(project_list, worktree_list=None, **kwargs):
+def main(project_list, worktree_list=None, fix=False, yes=False, **kwargs):
     """Main function invoked directly by repo.
 
     We must use the name "main" as that is what repo requires.
@@ -130,6 +144,9 @@ def main(project_list, worktree_list=None, **kwargs):
           project_list, so that each entry in project_list matches with a
           directory in worktree_list.  If None, we will attempt to calculate
           the directories automatically.
+      fix: Whether to automatically apply fixes without prompting.
+      yes: Whether to answer yes to all safe prompts (see
+          [Safe Prompts](#safe-prompts)).
       kwargs: Leave this here for forward-compatibility.
     """
 ```

docs/reproject-cmd.md

@@ -0,0 +1,126 @@
+# Reproject Command Contract
+
+The `repo.reprojectcmd` configuration names a command that `repo sync` runs
+instead of Git to move a project's index and worktree to the tree of the
+target commit. It is the checkout-side counterpart of `repo.fetchcmd` (see
+`docs/fetch-cmd.md`): together they let an external tool take over both the
+network fetch and the materialization of a project. This is useful on
+virtualized filesystems that address content by hash, where a tree can be
+materialized far faster than `git checkout` can write every file.
+
+The command only materializes the tree. `repo` then makes the ref write that
+Git would have made, using `git update-ref`.
+
+## Configuration
+
+To use this feature, set the following in `.repo/manifests.git/config`:
+```ini
+[repo]
+	reprojectcmd = "your custom command here"
+	uselocalgitdirs = true
+```
+Setting `repo.reprojectcmd` **requires** `repo.uselocalgitdirs` to be set to
+`true`.
+
+For reference, this command does with Git what `repo` would otherwise do
+itself:
+```ini
+[repo]
+	reprojectcmd = "git -C $REPO_PATH read-tree -m -u $REPO_TREV"
+	uselocalgitdirs = true
+```
+The one-tree merge applies the change to the target, keeps local changes to
+every other path, and refuses to overwrite a modified or untracked file, so it
+enforces the preconditions below by itself. It also works for a project that
+has nothing checked out yet.
+
+## Environment Variables
+
+The command is executed in a subshell, from the root of the client, populated
+with standard project-context environment variables. For details on standard
+variables (such as `REPO_PROJECT`, `REPO_PATH`, `REPO_REMOTE`, etc.), see the
+Environment section in `repo help forall` or `subcmds/forall.py`.
+
+The variables the command typically needs are:
+
+*   `REPO_PATH`: The project path relative to the root of the client.
+*   `REPO_TREV`: The target revision resolved to a full commit hash. Match this
+    commit's tree.
+
+There is no force mode: a project that would need one never reaches the
+command (see the preconditions below).
+
+## When the command runs
+
+`repo sync` already classifies each project and picks a Git operation. The
+command replaces the three that are a materialization of a target tree:
+
+1.  The checkout that detaches HEAD at the target. This is the common case: a
+    project on a detached HEAD, a project on a branch that does not track
+    upstream, and `repo sync -d`.
+2.  The fast-forward of the checked out branch to the target.
+3.  The hard reset of the checked out branch to the target, when the commits
+    it carried were dropped upstream.
+
+After the command exits 0, `repo` writes the ref itself: it detaches `HEAD` at
+`REPO_TREV`, or moves the checked out branch to `REPO_TREV`.
+
+The command is **not** run:
+
+*   When `HEAD` already names `REPO_TREV`.
+*   At the fast-forward step when `HEAD` is ahead of `REPO_TREV`, where Git's
+    merge would be a no-op.
+*   For a rebase. A branch carrying local commits has them replayed onto the
+    target by `git rebase`, which is not a materialization of a target tree.
+*   For `MetaProject`s (i.e. the internal `repo` repository itself at
+    `.repo/repo` and the `manifests` repository at `.repo/manifests`).
+
+## Contract
+
+### Preconditions
+
+Before invoking the command, `repo` ensures that:
+
+*   The index has no staged changes (the index matches `HEAD`, or is empty on an unborn `HEAD`).
+*   No rebase, cherry-pick, merge, or revert is in progress.
+
+Detecting collisions with untracked files or unstaged working-tree modifications is the responsibility of the reproject command itself (e.g. via `git read-tree -m -u $REPO_TREV` or a custom virtual filesystem checkout tool). If local changes collide with the target tree, the command must abort with a non-zero exit code. Local modifications and untracked files outside the diff between `HEAD` and `REPO_TREV` must be preserved.
+
+### Postconditions on exit 0
+
+After the command exits with status 0, `repo` expects the following
+postconditions to be met:
+
+1.  `git diff-index --quiet --cached REPO_TREV^{tree}` exits 0 (the index
+    matches the target tree).
+2.  `HEAD` still names what it did before the command, and its resolved commit
+    object ID has not changed.
+
+### Invariants
+
+The command may modify the worktree and the index, and may write project-local
+Git config. The command must:
+
+*   Apply the change from `HEAD`'s tree to `REPO_TREV`'s tree and leave every
+    other path alone. Local modifications and untracked files outside that
+    change must survive: the command applies a diff, it does not reset the
+    tree.
+*   Not write any ref, including `HEAD` and `ORIG_HEAD`. `repo` owns every ref
+    write.
+*   Not create or replace `.git/`, and not touch anything under `.repo/`.
+*   Not require the Git remote, to preserve `repo sync --local-only`.
+*   Be idempotent. Running it twice on the same target is a no-op.
+
+### Failure
+
+*   A non-zero exit status, a failed precondition or a failed postcondition
+    fails that project's sync, and the command's or Git's output is surfaced
+    to the user.
+*   Other projects continue, and `repo sync` exits non-zero.
+
+## Limitations
+
+Nested projects are out of scope: a project whose path lies inside another
+project's path, a `<project>` nested in another `<project>` in the manifest,
+and a submodule discovered with `sync-s` or `--recurse-submodules`. `repo sync`
+fails if the manifest has one while `repo.reprojectcmd` is set.

docs/smart-sync.md

@@ -27,13 +27,44 @@ 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" />
+  <manifest-server url="https://example.com/your/manifest/server/url"
+                   helper="repo-remote-helper-name" />
 ```
 
 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.
 
+### Pluggable Remote Helpers
+
+For custom proxying or authentication, Repo supports pluggable remote helpers.
+You can declare a helper binary via the optional `helper` attribute on the
+`<manifest-server>` element.
+
+If the `helper` attribute is present in `<manifest-server>`:
+1.  Repo searches your system `PATH` for the specified helper binary (e.g.,
+    `repo-remote-sso`). If the helper cannot be found in `PATH`, Repo will raise
+    a `SmartSyncError` and abort the sync.
+2.  The helper is executed with the manifest server URL as its first argument:
+    ```bash
+    <helper-binary-name> <url>
+    ```
+3.  The helper must output a single-line JSON object on stdout and exit:
+    *   On success, return `status: "ok"` and a loopback proxy URL (including
+        scheme, e.g., `http://127.0.0.1:999`):
+        ```json
+        {"status": "ok", "message": "http://127.0.0.1:999"}
+        ```
+    *   On failure, return `status: "error"` and a detailed error message:
+        ```json
+        {"status": "error", "message": "unauthorized"}
+        ```
+4.  Repo routes the XML-RPC request through the returned proxy address.
+
+**Timeout Constraint**: The remote helper must complete and exit within 10
+seconds. If it hangs or exceeds this limit, Repo will force-terminate (`kill`)
+the process and abort the synchronization.
+
 ## Credentials
 
 Credentials may be specified directly in typical `username:password`

git_command.py

@@ -70,6 +70,19 @@ class _GitCall:
 git = _GitCall()
 
 
+def IsValidBranchName(name: str) -> bool:
+    """Return whether |name| is valid where Git expects a branch name."""
+    p = GitCommand(
+        None,
+        ["check-ref-format", "--branch", name],
+        capture_stdout=True,
+        capture_stderr=True,
+        add_event_log=False,
+        log_as_error=False,
+    )
+    return p.Wait() == 0
+
+
 def RepoSourceVersion():
     """Return the version of the repo.git tree."""
     ver = getattr(RepoSourceVersion, "version", None)
@@ -270,6 +283,7 @@ class GitCommand:
         bare=False,
         input=None,
         capture_stdout=False,
+        capture_stdout_bytes: bool = False,
         capture_stderr=False,
         merge_output=False,
         disable_editor=False,
@@ -291,6 +305,12 @@ class GitCommand:
         self.cmdv = cmdv
         self.verify_command = verify_command
         self.stdout, self.stderr = None, None
+        if capture_stdout_bytes:
+            if merge_output:
+                raise ValueError(
+                    "capture_stdout_bytes cannot be combined with merge_output"
+                )
+            capture_stdout = True
 
         # Git on Windows wants its paths only using / for reliability.
         if platform_utils.isWindows():
@@ -334,6 +354,7 @@ class GitCommand:
                 command,
                 env,
                 capture_stdout=capture_stdout,
+                capture_stdout_bytes=capture_stdout_bytes,
                 capture_stderr=capture_stderr,
                 merge_output=merge_output,
                 ssh_proxy=ssh_proxy,
@@ -367,6 +388,7 @@ class GitCommand:
         command,
         env,
         capture_stdout=False,
+        capture_stdout_bytes: bool = False,
         capture_stderr=False,
         merge_output=False,
         ssh_proxy=None,
@@ -399,6 +421,10 @@ class GitCommand:
         # See go/tee-repo-stderr for more context.
         tee_stderr = False
         kwargs = {"encoding": "utf-8", "errors": "backslashreplace"}
+        if capture_stdout_bytes:
+            kwargs = {}
+            if isinstance(input, str):
+                input = input.encode("utf-8", "surrogateescape")
         if not (stdin or stdout or stderr):
             tee_stderr = True
             # stderr will be written back to sys.stderr even though it is
@@ -477,6 +503,10 @@ class GitCommand:
                     self.stderr = self._Tee(p.stderr, sys.stderr)
                 else:
                     self.stdout, self.stderr = p.communicate(input=input)
+                    if capture_stdout_bytes and isinstance(self.stderr, bytes):
+                        self.stderr = self.stderr.decode(
+                            "utf-8", "backslashreplace"
+                        ).replace("\r\n", "\n")
             finally:
                 if ssh_proxy:
                     ssh_proxy.remove_client(p)
@@ -528,17 +558,35 @@ class GitCommand:
             env.pop(key, None)
         return env
 
-    def VerifyCommand(self):
+    def VerifyCommand(self) -> None:
         if self.rc == 0:
             return None
-        stdout = (
-            "\n".join(self.stdout.split("\n")[:GIT_ERROR_STDOUT_LINES])
-            if self.stdout
-            else None
-        )
+        raw_stdout = self.stdout
+        if isinstance(raw_stdout, bytes):
+            first_records = re.split(
+                rb"\r\n|[\r\n\0]", raw_stdout, maxsplit=GIT_ERROR_STDOUT_LINES
+            )[:GIT_ERROR_STDOUT_LINES]
+            stdout = (
+                "\n".join(
+                    r.decode("utf-8", "backslashreplace") for r in first_records
+                )
+                if raw_stdout
+                else None
+            )
+        elif raw_stdout:
+            first_records = re.split(
+                r"\r\n|[\r\n\0]", raw_stdout, maxsplit=GIT_ERROR_STDOUT_LINES
+            )[:GIT_ERROR_STDOUT_LINES]
+            stdout = "\n".join(first_records)
+        else:
+            stdout = None
+
+        raw_stderr = self.stderr
+        if isinstance(raw_stderr, bytes):
+            raw_stderr = raw_stderr.decode("utf-8", "backslashreplace")
         stderr = (
-            "\n".join(self.stderr.split("\n")[:GIT_ERROR_STDERR_LINES])
-            if self.stderr
+            "\n".join(raw_stderr.split("\n")[:GIT_ERROR_STDERR_LINES])
+            if raw_stderr
             else None
         )
         project = self.project.name if self.project else None

git_config.py

@@ -40,7 +40,7 @@ from repo_trace import Trace
 # that is saved in the config.
 SYNC_STATE_PREFIX = "repo.syncstate."
 
-ID_RE = re.compile(r"^[0-9a-f]{40}$")
+ID_RE = re.compile(r"^(?:[0-9a-f]{40}|[0-9a-f]{64})$")
 
 REVIEW_CACHE = {}
 
@@ -49,8 +49,8 @@ def IsChange(rev):
     return rev.startswith(R_CHANGES)
 
 
-def IsId(rev):
-    return ID_RE.match(rev)
+def IsId(rev: str) -> bool:
+    return bool(ID_RE.match(rev))
 
 
 def IsTag(rev):

git_refs.py

@@ -14,6 +14,7 @@
 
 import os
 
+from git_command import git_require
 from git_command import GitCommand
 import platform_utils
 from repo_trace import Trace
@@ -41,6 +42,17 @@ class GitRefs:
         self._EnsureLoaded()
         return self._phyref
 
+    @property
+    def head(self) -> str:
+        """Return HEAD's symbolic target or detached object ID."""
+        self._EnsureLoaded()
+        return self._symref.get(HEAD) or self._phyref.get(HEAD, "")
+
+    @property
+    def is_loaded(self) -> bool:
+        """Whether a ref snapshot has already been loaded."""
+        return self._phyref is not None
+
     def get(self, name):
         try:
             return self.all[name]
@@ -87,8 +99,12 @@ class GitRefs:
             self._symref = {}
             self._mtime = {}
 
-            self._ReadRefs()
-            self._ReadSymbolicRef(HEAD)
+            root_refs_loaded = self._ReadRefs()
+            if not root_refs_loaded or (
+                HEAD not in self._phyref and HEAD not in self._symref
+            ):
+                # --include-root-refs does not report an unborn HEAD.
+                self._ReadSymbolicRef(HEAD)
 
             scan = self._symref
             attempts = 0
@@ -113,18 +129,32 @@ class GitRefs:
         """Check if a ref_id is a null object ID."""
         return ref_id and all(ch == "0" for ch in ref_id)
 
-    def _ReadRefs(self) -> None:
-        """Read all references using git for-each-ref."""
+    def _ReadRefs(self) -> bool:
+        """Read all references using git for-each-ref.
+
+        Returns:
+            Whether root refs, including HEAD when it exists, were loaded.
+        """
+        include_root_refs = git_require((2, 45, 0))
+        cmd = [
+            "for-each-ref",
+            "--format=%(objectname)%00%(refname)%00%(symref)",
+        ]
+        if include_root_refs:
+            cmd.insert(1, "--include-root-refs")
+            # Avoid caching volatile root refs such as ORIG_HEAD.  HEAD and
+            # refs/* are the only namespaces GitRefs exposes to callers.
+            cmd.extend([HEAD, "refs"])
         p = GitCommand(
             None,
-            ["for-each-ref", "--format=%(objectname)%00%(refname)%00%(symref)"],
+            cmd,
             capture_stdout=True,
             capture_stderr=True,
             bare=True,
             gitdir=self._gitdir,
         )
         if p.Wait() != 0:
-            return
+            return False
 
         for line in p.stdout.splitlines():
             ref_id, name, symref = line.split("\0")
@@ -132,6 +162,7 @@ class GitRefs:
                 self._symref[name] = symref
             elif ref_id and not self._IsNullRef(ref_id):
                 self._phyref[name] = ref_id
+        return include_root_refs
 
     def _ReadSymbolicRef(self, name: str) -> None:
         """Read a symbolic reference."""

git_status.py

@@ -0,0 +1,259 @@
+# Copyright (C) 2026 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.
+
+"""Read a worktree's state from one machine-readable git status snapshot."""
+
+from collections import OrderedDict
+import os
+from typing import Iterator, List, Optional, TYPE_CHECKING
+
+from git_command import git_require
+from git_command import GitCommand
+
+
+if TYPE_CHECKING:
+    from project import Project
+
+
+class StatusEntry:
+    """The state of one path on one side of the index."""
+
+    def __init__(
+        self,
+        path: str,
+        status: str,
+        src_path: Optional[str] = None,
+        level: Optional[str] = None,
+    ) -> None:
+        self.path = path
+        self.status = status
+        self.src_path = src_path
+        self.level = level
+
+
+class StatusSnapshot:
+    """A consistent view of worktree, index, and branch state."""
+
+    def __init__(self) -> None:
+        self.index_changes = OrderedDict()
+        self.worktree_changes = OrderedDict()
+        self.untracked = []
+        self.branch_oid = None
+        self.branch_head = None
+        self.upstream = None
+        self.ahead = 0
+        self.behind = 0
+        self.has_ahead_behind = False
+        self.stash_count = 0
+
+    @property
+    def current_branch(self) -> Optional[str]:
+        if self.branch_head in (None, "(detached)", "(unknown)"):
+            return None
+        return self.branch_head
+
+    def is_dirty(self, consider_untracked: bool = True) -> bool:
+        return bool(
+            self.index_changes
+            or self.worktree_changes
+            or (consider_untracked and self.untracked)
+        )
+
+
+def GetStatus(
+    project: "Project",
+    gitdir: str,
+    untracked_files: str = "all",
+    branch: bool = False,
+    ahead_behind: bool = False,
+    show_stash: bool = False,
+) -> StatusSnapshot:
+    """Return one machine-readable status snapshot for |project|."""
+    if not git_require((2, 11, 0)):
+        raise UnsupportedStatusError("porcelain v2 requires Git 2.11")
+    cmd = [
+        "status",
+        "--porcelain=v2",
+        "-z",
+        "--ignore-submodules=all",
+        f"--untracked-files={untracked_files}",
+    ]
+    if branch:
+        cmd.append("--branch")
+        if git_require((2, 17, 0)):
+            cmd.append(
+                "--ahead-behind" if ahead_behind else "--no-ahead-behind"
+            )
+    if git_require((2, 18, 0)):
+        # Match the existing staged diff's explicit rename detection even if
+        # status.renames is disabled in the user's config.
+        cmd.append("--renames")
+    if show_stash and git_require((2, 35, 0)):
+        cmd.append("--show-stash")
+
+    p = GitCommand(
+        project,
+        cmd,
+        bare=False,
+        gitdir=gitdir,
+        capture_stdout=True,
+        capture_stdout_bytes=True,
+        capture_stderr=True,
+        verify_command=True,
+    )
+    p.Wait()
+    return ParsePorcelainV2(p.stdout)
+
+
+def _Path(value: bytes) -> str:
+    """Decode a Git pathname without losing undecodable bytes."""
+    return os.fsdecode(value)
+
+
+def _Status(value: int) -> str:
+    """Normalize Git's unchanged markers for repo's status display."""
+    char = chr(value)
+    return "" if char == "." else char
+
+
+def _Records(output: bytes) -> Iterator[bytes]:
+    if not output:
+        return iter(())
+    if not output.endswith(b"\0"):
+        raise StatusParseError("porcelain v2 output is not NUL terminated")
+    records = output.split(b"\0")
+    if not records[-1]:
+        records.pop()
+    return iter(records)
+
+
+class StatusParseError(ValueError):
+    """Raised when machine-readable status output is malformed."""
+
+
+class UnsupportedStatusError(RuntimeError):
+    """Raised when the Git client cannot produce porcelain v2."""
+
+
+def _Fields(record: bytes, count: int) -> List[bytes]:
+    fields = record.split(b" ", count - 1)
+    if len(fields) != count:
+        raise StatusParseError(f"malformed porcelain v2 record: {record!r}")
+    return fields
+
+
+def _AddTracked(
+    status: StatusSnapshot,
+    path: str,
+    xy: bytes,
+    src_path: Optional[str] = None,
+    level: Optional[str] = None,
+) -> None:
+    index_status = _Status(xy[0])
+    worktree_status = _Status(xy[1])
+    if index_status:
+        status.index_changes[path] = StatusEntry(
+            path,
+            index_status,
+            src_path=src_path if index_status in ("R", "C") else None,
+            level=level if index_status in ("R", "C") else None,
+        )
+    if worktree_status:
+        status.worktree_changes[path] = StatusEntry(
+            path,
+            worktree_status,
+            src_path=src_path if worktree_status in ("R", "C") else None,
+            level=level if worktree_status in ("R", "C") else None,
+        )
+
+
+def ParsePorcelainV2(output: bytes) -> StatusSnapshot:
+    """Parse ``git status --porcelain=v2 -z --branch`` output."""
+    status = StatusSnapshot()
+    records = _Records(output)
+    for record in records:
+        kind = record[:1]
+        if kind == b"#":
+            try:
+                key, value = record[2:].split(b" ", 1)
+            except ValueError as e:
+                raise StatusParseError(
+                    f"malformed porcelain v2 header: {record!r}"
+                ) from e
+            if key == b"branch.oid":
+                value = value.decode("ascii")
+                status.branch_oid = None if value == "(initial)" else value
+            elif key == b"branch.head":
+                status.branch_head = _Path(value)
+            elif key == b"branch.upstream":
+                status.upstream = _Path(value)
+            elif key == b"branch.ab":
+                try:
+                    value = value.decode("ascii")
+                    ahead, behind = value.split()
+                    if ahead != "+?" and behind != "-?":
+                        status.ahead = int(ahead)
+                        status.behind = -int(behind)
+                        status.has_ahead_behind = True
+                except ValueError as e:
+                    raise StatusParseError(
+                        f"malformed porcelain v2 branch.ab record: {record!r}"
+                    ) from e
+            elif key == b"stash":
+                status.stash_count = int(value.decode("ascii"))
+            continue
+
+        if kind == b"1":
+            fields = _Fields(record, 9)
+            xy = fields[1]
+            if len(xy) != 2:
+                raise StatusParseError(f"invalid status pair: {xy!r}")
+            path = _Path(fields[8])
+            _AddTracked(status, path, xy)
+        elif kind == b"2":
+            fields = _Fields(record, 10)
+            xy = fields[1]
+            if len(xy) != 2:
+                raise StatusParseError(f"invalid status pair: {xy!r}")
+            score = fields[8][1:].lstrip(b"0") or b"0"
+            try:
+                src_path = _Path(next(records))
+            except StopIteration as e:
+                raise StatusParseError(
+                    "rename record has no source path"
+                ) from e
+            path = _Path(fields[9])
+            _AddTracked(
+                status,
+                path,
+                xy,
+                src_path=src_path,
+                level=score.decode("ascii"),
+            )
+        elif kind == b"u":
+            fields = _Fields(record, 11)
+            path = _Path(fields[10])
+            # The old diff-index/diff-files pair reported unmerged paths on
+            # both sides, regardless of porcelain's more specific XY pair.
+            status.index_changes[path] = StatusEntry(path, "U")
+            status.worktree_changes[path] = StatusEntry(path, "U")
+        elif kind == b"?":
+            status.untracked.append(_Path(record[2:]))
+        elif kind == b"!":
+            continue
+        else:
+            raise StatusParseError(
+                f"unknown porcelain v2 record type: {record!r}"
+            )
+    return status

git_superproject.py

@@ -36,7 +36,6 @@ from git_command import git_require
 from git_command import GitCommand
 from git_config import IsId
 from git_config import RepoConfig
-from git_refs import GitRefs
 import platform_utils
 
 
@@ -189,7 +188,7 @@ class Superproject:
             if netloc:
                 parts = netloc.split("-review", 1)
                 host = parts[0]
-                rev = GitRefs(self._work_git).get("HEAD")
+                rev = self._GetRef("HEAD")
                 return f"{host}/{self.name}@{rev}"
         return None
 
@@ -314,7 +313,10 @@ class Superproject:
         # 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}")
+        negotiation_ref = self.revision
+        if negotiation_ref and not negotiation_ref.startswith("refs/"):
+            negotiation_ref = f"refs/heads/{negotiation_ref}"
+        rev_commit = self._GetRef(negotiation_ref) if negotiation_ref else ""
         if rev_commit:
             cmd.extend(["--negotiation-tip", rev_commit])
 
@@ -347,6 +349,21 @@ class Superproject:
             return False
         return True
 
+    def _GetRef(self, ref: str) -> str:
+        """Resolve one local ref without loading the entire ref namespace."""
+        p = GitCommand(
+            None,
+            ["rev-parse", "--verify", "--quiet", ref],
+            gitdir=self._work_git,
+            bare=True,
+            capture_stdout=True,
+            capture_stderr=True,
+            log_as_error=False,
+        )
+        if p.Wait() == 0:
+            return p.stdout.strip()
+        return ""
+
     def _LsTree(self):
         """Gets the commit ids for all projects.
 
@@ -473,7 +490,7 @@ class Superproject:
             )
             return None
         manifest_str = self._manifest.ToXml(
-            filter_groups=self._manifest.GetManifestGroupsStr(),
+            filter_groups="all",
             omit_local=True,
         ).toxml()
         manifest_path = self._manifest_path

git_trace2_event_log_base.py

@@ -195,7 +195,13 @@ class BaseEventLog:
 
     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"
+        return (
+            "data-json"
+            if isinstance(value, str)
+            and value.startswith("[")
+            and value.endswith("]")
+            else "data"
+        )
 
     def LogDataConfigEvents(self, config, prefix):
         """Append a 'data' event for each entry in |config| to the current log.

hooks.py

@@ -12,6 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+import optparse
 import os
 import re
 import sys
@@ -68,6 +69,8 @@ class RepoHook:
         allow_all_hooks=False,
         ignore_hooks=False,
         abort_if_user_denies=False,
+        yes=False,
+        fix=False,
     ):
         """RepoHook constructor.
 
@@ -89,6 +92,8 @@ class RepoHook:
             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.
+            yes: If True, then 'Yes' is assumed for any prompts.
+            fix: If True, then 'Fix' is assumed for any fixup prompts.
         """
         self._hook_type = hook_type
         self._hooks_project = hooks_project
@@ -99,6 +104,8 @@ class RepoHook:
         self._allow_all_hooks = allow_all_hooks
         self._ignore_hooks = ignore_hooks
         self._abort_if_user_denies = abort_if_user_denies
+        self._yes = yes
+        self._fix = fix
 
         # Store the full path to the script for convenience.
         self._script_fullpath = None
@@ -374,8 +381,12 @@ class RepoHook:
             #   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
+            kwargs = {
+                **kwargs,
+                "hook_should_take_kwargs": True,
+                "fix": self._fix,
+                "yes": self._yes,
+            }
 
             # See what version of python the hook has been written against.
             data = open(self._script_fullpath).read()
@@ -497,12 +508,18 @@ class RepoHook:
                     "origin"
                 ).url,
                 "bug_url": manifest.contactinfo.bugurl,
+                "yes": getattr(opt, "yes", False),
+                "fix": getattr(opt, "fix", False),
             }
         )
         return cls(*args, **kwargs)
 
     @staticmethod
-    def AddOptionGroup(parser, name):
+    def AddOptionGroup(
+        parser: optparse.OptionParser,
+        name: str,
+        allow_fix: bool = False,
+    ) -> None:
         """Help options relating to the various hooks."""
 
         # Note that verify and no-verify are NOT opposites of each other, which
@@ -526,3 +543,10 @@ class RepoHook:
             action="store_true",
             help="Do not abort if %s hooks fail." % name,
         )
+        if allow_fix:
+            group.add_option(
+                "--fix",
+                action="store_true",
+                default=False,
+                help="Automatically apply %s fixes without prompting." % name,
+            )

main.py

@@ -104,6 +104,11 @@ elif sys.version_info < MIN_PYTHON_VERSION_SOFT:
 KEYBOARD_INTERRUPT_EXIT = 128 + signal.SIGINT
 MAX_PRINT_ERRORS = 5
 
+if hasattr(sys.stdout, "reconfigure"):
+    sys.stdout.reconfigure(errors="surrogateescape")
+if hasattr(sys.stderr, "reconfigure"):
+    sys.stderr.reconfigure(errors="surrogateescape")
+
 global_options = optparse.OptionParser(
     usage="repo [-p|--paginate|--no-pager] COMMAND [ARGS]",
     add_help_option=False,

man/repo-abandon.1

@@ -1,5 +1,5 @@
 .\" DO NOT MODIFY THIS FILE!  It was generated by help2man.
-.TH REPO "1" "July 2022" "repo abandon" "Repo Manual"
+.TH REPO "1" "June 2026" "repo abandon" "Repo Manual"
 .SH NAME
 repo \- repo abandon - manual page for repo abandon
 .SH SYNOPSIS
@@ -20,8 +20,7 @@ It is equivalent to "git branch \fB\-D\fR <branchname>".
 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)
+number of jobs to run in parallel (default: based on number of CPU cores)
 .TP
 \fB\-\-all\fR
 delete all branches in all projects

man/repo-branches.1

@@ -1,5 +1,5 @@
 .\" DO NOT MODIFY THIS FILE!  It was generated by help2man.
-.TH REPO "1" "July 2022" "repo branches" "Repo Manual"
+.TH REPO "1" "June 2026" "repo branches" "Repo Manual"
 .SH NAME
 repo \- repo branches - manual page for repo branches
 .SH SYNOPSIS
@@ -46,8 +46,7 @@ is shown, then the branch appears in all projects.
 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)
+number of jobs to run in parallel (default: based on number of CPU cores)
 .SS Logging options:
 .TP
 \fB\-v\fR, \fB\-\-verbose\fR

man/repo-checkout.1

@@ -1,5 +1,5 @@
 .\" DO NOT MODIFY THIS FILE!  It was generated by help2man.
-.TH REPO "1" "July 2022" "repo checkout" "Repo Manual"
+.TH REPO "1" "June 2026" "repo checkout" "Repo Manual"
 .SH NAME
 repo \- repo checkout - manual page for repo checkout
 .SH SYNOPSIS
@@ -15,8 +15,7 @@ Checkout a branch for development
 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)
+number of jobs to run in parallel (default: based on number of CPU cores)
 .SS Logging options:
 .TP
 \fB\-v\fR, \fB\-\-verbose\fR

man/repo-diff.1

@@ -1,5 +1,5 @@
 .\" DO NOT MODIFY THIS FILE!  It was generated by help2man.
-.TH REPO "1" "July 2022" "repo diff" "Repo Manual"
+.TH REPO "1" "June 2026" "repo diff" "Repo Manual"
 .SH NAME
 repo \- repo diff - manual page for repo diff
 .SH SYNOPSIS
@@ -19,8 +19,7 @@ to the Unix 'patch' command.
 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)
+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

man/repo-forall.1

@@ -1,5 +1,5 @@
 .\" DO NOT MODIFY THIS FILE!  It was generated by help2man.
-.TH REPO "1" "May 2026" "repo forall" "Repo Manual"
+.TH REPO "1" "June 2026" "repo forall" "Repo Manual"
 .SH NAME
 repo \- repo forall - manual page for repo forall
 .SH SYNOPSIS
@@ -17,20 +17,16 @@ repo forall \fB\-r\fR str1 [str2] ... \fB\-c\fR <command> [<arg>...]
 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)
+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
+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
+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
+execute the command only on projects matching the specified groups
 .TP
 \fB\-c\fR, \fB\-\-command\fR
 command (and arguments) to execute
@@ -39,8 +35,7 @@ command (and arguments) to execute
 abort if a command exits unsuccessfully
 .TP
 \fB\-\-ignore\-missing\fR
-silently skip & do not exit non\-zero due missing
-checkouts
+silently skip & do not exit non\-zero due missing checkouts
 .TP
 \fB\-\-interactive\fR
 force interactive usage
@@ -125,6 +120,8 @@ REPO_UPSTREAM is the name of the upstream branch as specified in the manifest.
 REPO_DEST_BRANCH is the name of the destination branch for code review, as
 specified in the manifest.
 .PP
+REPO_PROJECT_FETCH_URL is the full resolved fetch URL for the project.
+.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

man/repo-gc.1

@@ -1,5 +1,5 @@
 .\" DO NOT MODIFY THIS FILE!  It was generated by help2man.
-.TH REPO "1" "April 2025" "repo gc" "Repo Manual"
+.TH REPO "1" "June 2026" "repo gc" "Repo Manual"
 .SH NAME
 repo \- repo gc - manual page for repo gc
 .SH SYNOPSIS
@@ -21,8 +21,7 @@ do everything except actually delete
 answer yes to all safe prompts
 .TP
 \fB\-\-repack\fR
-repack all projects that use partial clone with
-filter=blob:none
+repack all projects that use partial clone with filter=blob:none
 .SS Logging options:
 .TP
 \fB\-v\fR, \fB\-\-verbose\fR

man/repo-grep.1

@@ -1,5 +1,5 @@
 .\" DO NOT MODIFY THIS FILE!  It was generated by help2man.
-.TH REPO "1" "July 2022" "repo grep" "Repo Manual"
+.TH REPO "1" "June 2026" "repo grep" "Repo Manual"
 .SH NAME
 repo \- repo grep - manual page for repo grep
 .SH SYNOPSIS
@@ -15,8 +15,7 @@ Print lines matching a pattern
 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)
+number of jobs to run in parallel (default: based on number of CPU cores)
 .SS Logging options:
 .TP
 \fB\-\-verbose\fR

man/repo-info.1

@@ -1,5 +1,5 @@
 .\" DO NOT MODIFY THIS FILE!  It was generated by help2man.
-.TH REPO "1" "May 2026" "repo info" "Repo Manual"
+.TH REPO "1" "June 2026" "repo info" "Repo Manual"
 .SH NAME
 repo \- repo info - manual page for repo info
 .SH SYNOPSIS
@@ -15,12 +15,10 @@ Get info on the manifest branch, current branch or unmerged branches
 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)
+number of jobs to run in parallel (default: based on number of CPU cores)
 .TP
 \fB\-d\fR, \fB\-\-diff\fR
-show full info and commit diff including remote
-branches
+show full info and commit diff including remote branches
 .TP
 \fB\-o\fR, \fB\-\-overview\fR
 show overview of all local commits

man/repo-init.1

@@ -1,5 +1,5 @@
 .\" DO NOT MODIFY THIS FILE!  It was generated by help2man.
-.TH REPO "1" "September 2024" "repo init" "Repo Manual"
+.TH REPO "1" "June 2026" "repo init" "Repo Manual"
 .SH NAME
 repo \- repo init - manual page for repo init
 .SH SYNOPSIS
@@ -29,36 +29,29 @@ manifest repository location
 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
+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]
+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|...]
+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
+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)
+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)
+fetch only current manifest branch from server (default)
 .TP
 \fB\-\-no\-current\-branch\fR
 fetch all manifest branches from server
@@ -71,15 +64,16 @@ 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
+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.
+checkout an archive instead of a git repository for each project. See git archive.
 .TP
 \fB\-\-worktree\fR
 use git\-worktree to manage projects
+.TP
+\fB\-\-use\-local\-gitdirs\fR
+bypass .repo/projects/ and use standard Git layout in working tree
 .SS Project checkout optimizations:
 .TP
 \fB\-\-reference\fR=\fI\,DIR\/\fR
@@ -92,33 +86,28 @@ dissociate from reference mirrors after clone
 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)
+perform partial clone (https://git\-scm.com/docs/partial\-clone)
 .TP
 \fB\-\-no\-partial\-clone\fR
-disable use of partial clone (https://gitscm.com/docs/gitrepositorylayout#_code_partialclone_code)
+disable use of partial clone (https://git\-scm.com/docs/partial\-clone)
 .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)
+exclude the specified projects (a comma\-delimited project names) from partial clone (https://git\-scm.com/docs/partial\-clone)
 .TP
 \fB\-\-clone\-filter\fR=\fI\,CLONE_FILTER\/\fR
-filter for use with \fB\-\-partial\-clone\fR [default:
-blob:none]
+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
+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)
+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)
+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

man/repo-list.1

@@ -1,5 +1,5 @@
 .\" DO NOT MODIFY THIS FILE!  It was generated by help2man.
-.TH REPO "1" "July 2022" "repo list" "Repo Manual"
+.TH REPO "1" "June 2026" "repo list" "Repo Manual"
 .SH NAME
 repo \- repo list - manual page for repo list
 .SH SYNOPSIS
@@ -17,12 +17,10 @@ repo list [\-f] \fB\-r\fR str1 [str2]...
 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
+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
+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
@@ -34,12 +32,10 @@ display only the name of the repository
 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
+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)
+display paths relative to this one (default: top of repo client checkout)
 .SS Logging options:
 .TP
 \fB\-v\fR, \fB\-\-verbose\fR

man/repo-manifest.1

@@ -1,5 +1,5 @@
 .\" DO NOT MODIFY THIS FILE!  It was generated by help2man.
-.TH REPO "1" "April 2026" "repo manifest" "Repo Manual"
+.TH REPO "1" "June 2026" "repo manifest" "Repo Manual"
 .SH NAME
 repo \- repo manifest - manual page for repo manifest
 .SH SYNOPSIS
@@ -21,14 +21,10 @@ save revisions as current HEAD
 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)
+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)
+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)
@@ -40,8 +36,7 @@ format output for humans to read
 ignore local manifests
 .TP
 \fB\-o\fR \-|NAME.xml, \fB\-\-output\-file\fR=\fI\,\-\/\fR|NAME.xml
-file to save the manifest to. (Filename prefix for
-multi\-tree.)
+file to save the manifest to. (Filename prefix for multi\-tree.)
 .SS Logging options:
 .TP
 \fB\-v\fR, \fB\-\-verbose\fR
@@ -138,6 +133,7 @@ include*)>
 .IP
 <!ELEMENT manifest\-server EMPTY>
 <!ATTLIST manifest\-server url CDATA #REQUIRED>
+<!ATTLIST manifest\-server helper CDATA #IMPLIED>
 .IP
 <!ELEMENT submanifest EMPTY>
 <!ATTLIST submanifest name           ID    #REQUIRED>
@@ -347,6 +343,11 @@ 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
+Attribute `url`: The URL of the manifest server.
+.PP
+Attribute `helper`: Optional name of a remote helper binary to execute to
+resolve proxying or authentication for the manifest server.
+.PP
 Element submanifest
 .PP
 One or more submanifest elements may be specified. Each element describes a

man/repo-prune.1

@@ -1,5 +1,5 @@
 .\" DO NOT MODIFY THIS FILE!  It was generated by help2man.
-.TH REPO "1" "July 2022" "repo prune" "Repo Manual"
+.TH REPO "1" "June 2026" "repo prune" "Repo Manual"
 .SH NAME
 repo \- repo prune - manual page for repo prune
 .SH SYNOPSIS
@@ -15,8 +15,7 @@ Prune (delete) already merged topics
 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)
+number of jobs to run in parallel (default: based on number of CPU cores)
 .SS Logging options:
 .TP
 \fB\-v\fR, \fB\-\-verbose\fR

man/repo-rebase.1

@@ -1,5 +1,5 @@
 .\" DO NOT MODIFY THIS FILE!  It was generated by help2man.
-.TH REPO "1" "July 2022" "repo rebase" "Repo Manual"
+.TH REPO "1" "June 2026" "repo rebase" "Repo Manual"
 .SH NAME
 repo \- repo rebase - manual page for repo rebase
 .SH SYNOPSIS
@@ -33,9 +33,7 @@ pass \fB\-\-whitespace\fR to git rebase
 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)
+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

man/repo-smartsync.1

@@ -1,5 +1,5 @@
 .\" DO NOT MODIFY THIS FILE!  It was generated by help2man.
-.TH REPO "1" "May 2026" "repo smartsync" "Repo Manual"
+.TH REPO "1" "September 2026" "repo smartsync" "Repo Manual"
 .SH NAME
 repo \- repo smartsync - manual page for repo smartsync
 .SH SYNOPSIS
@@ -15,16 +15,13 @@ Update working tree to the latest known good revision
 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)
+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 unless \fB\-\-no\-interleaved\fR is set
+number of network jobs to run in parallel (defaults to \fB\-\-jobs\fR or 1). Ignored unless \fB\-\-no\-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 unless \fB\-\-nointerleaved\fR is set
+number of local checkout jobs to run in parallel (defaults to \fB\-\-jobs\fR or based on number of CPU cores). Ignored unless \fB\-\-no\-interleaved\fR is set
 .TP
 \fB\-f\fR, \fB\-\-force\-broken\fR
 obsolete option (to be deleted in the future)
@@ -33,30 +30,22 @@ obsolete option (to be deleted in the future)
 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
+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
+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
+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
+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)
+use the existing manifest checkout as\-is. (do not update to the latest revision)
 .TP
 \fB\-\-interleaved\fR
 fetch and checkout projects in parallel (default)
@@ -79,6 +68,9 @@ fetch all branches from server
 \fB\-m\fR NAME.xml, \fB\-\-manifest\-name\fR=\fI\,NAME\/\fR.xml
 temporary manifest to use for this sync
 .TP
+\fB\-g\fR GROUP, \fB\-\-groups\fR=\fI\,GROUP\/\fR
+sync projects matching the specific groups.  Not persistent unlike when used on init
+.TP
 \fB\-\-clone\-bundle\fR
 enable use of \fI\,/clone.bundle\/\fP on HTTP/HTTPS
 .TP
@@ -91,19 +83,20 @@ username to authenticate with the manifest server
 \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
+\fB\-\-recurse\-submodules\fR
+sync submodules from server
+.TP
+\fB\-\-no\-recurse\-submodules\fR
+don't sync submodules from server
 .TP
 \fB\-\-use\-superproject\fR
-use the manifest superproject to sync projects;
-implies \fB\-c\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\-\-superproject\-revision\fR=\fI\,SUPERPROJECT_REVISION\/\fR
-sync to superproject revision (applies to outer
-manifest)
+sync to superproject revision (applies to outer manifest)
 .TP
 \fB\-\-tags\fR
 fetch tags
@@ -112,15 +105,13 @@ fetch tags
 don't fetch tags (default)
 .TP
 \fB\-\-optimized\-fetch\fR
-only fetch projects fixed to sha1 if revision does not
-exist locally
+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)
+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
@@ -129,8 +120,7 @@ do not delete refs that no longer exist on the remote
 run garbage collection on all synced projects
 .TP
 \fB\-\-no\-auto\-gc\fR
-do not run garbage collection on any projects
-(default)
+do not run garbage collection on any projects (default)
 .SS Logging options:
 .TP
 \fB\-v\fR, \fB\-\-verbose\fR

man/repo-start.1

@@ -1,5 +1,5 @@
 .\" DO NOT MODIFY THIS FILE!  It was generated by help2man.
-.TH REPO "1" "July 2022" "repo start" "Repo Manual"
+.TH REPO "1" "June 2026" "repo start" "Repo Manual"
 .SH NAME
 repo \- repo start - manual page for repo start
 .SH SYNOPSIS
@@ -15,8 +15,7 @@ Start a new branch for development
 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)
+number of jobs to run in parallel (default: based on number of CPU cores)
 .TP
 \fB\-\-all\fR
 begin branch in all projects

man/repo-status.1

@@ -1,5 +1,5 @@
 .\" DO NOT MODIFY THIS FILE!  It was generated by help2man.
-.TH REPO "1" "July 2022" "repo status" "Repo Manual"
+.TH REPO "1" "June 2026" "repo status" "Repo Manual"
 .SH NAME
 repo \- repo status - manual page for repo status
 .SH SYNOPSIS
@@ -15,12 +15,10 @@ Show the working tree status
 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)
+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
+include objects in working directory outside of repo projects
 .SS Logging options:
 .TP
 \fB\-v\fR, \fB\-\-verbose\fR
@@ -70,6 +68,15 @@ branch devwork
 \fB\-m\fR
 subcmds/status.py
 .PP
+If the branch is tracking an upstream branch, the number of commits ahead and/or
+behind is also shown:
+.TP
+project repo/
+branch devwork [ahead 1, behind 2]
+.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:

man/repo-sync.1

@@ -1,5 +1,5 @@
 .\" DO NOT MODIFY THIS FILE!  It was generated by help2man.
-.TH REPO "1" "May 2026" "repo sync" "Repo Manual"
+.TH REPO "1" "September 2026" "repo sync" "Repo Manual"
 .SH NAME
 repo \- repo sync - manual page for repo sync
 .SH SYNOPSIS
@@ -15,16 +15,13 @@ Update working tree to the latest revision
 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)
+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 unless \fB\-\-no\-interleaved\fR is set
+number of network jobs to run in parallel (defaults to \fB\-\-jobs\fR or 1). Ignored unless \fB\-\-no\-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 unless \fB\-\-nointerleaved\fR is set
+number of local checkout jobs to run in parallel (defaults to \fB\-\-jobs\fR or based on number of CPU cores). Ignored unless \fB\-\-no\-interleaved\fR is set
 .TP
 \fB\-f\fR, \fB\-\-force\-broken\fR
 obsolete option (to be deleted in the future)
@@ -33,30 +30,22 @@ obsolete option (to be deleted in the future)
 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
+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
+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
+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
+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)
+use the existing manifest checkout as\-is. (do not update to the latest revision)
 .TP
 \fB\-\-interleaved\fR
 fetch and checkout projects in parallel (default)
@@ -79,6 +68,9 @@ fetch all branches from server
 \fB\-m\fR NAME.xml, \fB\-\-manifest\-name\fR=\fI\,NAME\/\fR.xml
 temporary manifest to use for this sync
 .TP
+\fB\-g\fR GROUP, \fB\-\-groups\fR=\fI\,GROUP\/\fR
+sync projects matching the specific groups.  Not persistent unlike when used on init
+.TP
 \fB\-\-clone\-bundle\fR
 enable use of \fI\,/clone.bundle\/\fP on HTTP/HTTPS
 .TP
@@ -91,19 +83,20 @@ username to authenticate with the manifest server
 \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
+\fB\-\-recurse\-submodules\fR
+sync submodules from server
+.TP
+\fB\-\-no\-recurse\-submodules\fR
+don't sync submodules from server
 .TP
 \fB\-\-use\-superproject\fR
-use the manifest superproject to sync projects;
-implies \fB\-c\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\-\-superproject\-revision\fR=\fI\,SUPERPROJECT_REVISION\/\fR
-sync to superproject revision (applies to outer
-manifest)
+sync to superproject revision (applies to outer manifest)
 .TP
 \fB\-\-tags\fR
 fetch tags
@@ -112,15 +105,13 @@ fetch tags
 don't fetch tags (default)
 .TP
 \fB\-\-optimized\-fetch\fR
-only fetch projects fixed to sha1 if revision does not
-exist locally
+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)
+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
@@ -129,12 +120,10 @@ do not delete refs that no longer exist on the remote
 run garbage collection on all synced projects
 .TP
 \fB\-\-no\-auto\-gc\fR
-do not run garbage collection on any projects
-(default)
+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
+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
@@ -229,8 +218,12 @@ 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.
+The \fB\-\-recurse\-submodules\fR option enables syncing Git submodules of all projects
+from the server. The \fB\-\-no\-recurse\-submodules\fR option disables syncing Git
+submodules, even when a project has sync\-s="true" in the manifest.
+.PP
+The \fB\-\-fetch\-submodules\fR and \fB\-\-no\-fetch\-submodules\fR options are deprecated aliases
+for \fB\-\-recurse\-submodules\fR and \fB\-\-no\-recurse\-submodules\fR, respectively.
 .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.

man/repo-upload.1

@@ -1,5 +1,5 @@
 .\" DO NOT MODIFY THIS FILE!  It was generated by help2man.
-.TH REPO "1" "June 2024" "repo upload" "Repo Manual"
+.TH REPO "1" "August 2026" "repo upload" "Repo Manual"
 .SH NAME
 repo \- repo upload - manual page for repo upload
 .SH SYNOPSIS
@@ -15,8 +15,7 @@ Upload changes for code review
 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)
+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
@@ -113,6 +112,9 @@ Run the pre\-upload hook without prompting.
 .TP
 \fB\-\-ignore\-hooks\fR
 Do not abort if pre\-upload hooks fail.
+.TP
+\fB\-\-fix\fR
+Automatically apply pre\-upload fixes without prompting.
 .PP
 Run `repo help upload` to view the detailed manual.
 .SH DETAILS

man/repo-wipe.1

@@ -1,5 +1,5 @@
 .\" DO NOT MODIFY THIS FILE!  It was generated by help2man.
-.TH REPO "1" "November 2025" "repo wipe" "Repo Manual"
+.TH REPO "1" "June 2026" "repo wipe" "Repo Manual"
 .SH NAME
 repo \- repo wipe - manual page for repo wipe
 .SH SYNOPSIS
@@ -21,8 +21,7 @@ force wipe shared projects and uncommitted changes
 force wipe even if there are uncommitted changes
 .TP
 \fB\-\-force\-shared\fR
-force wipe even if the project shares an object
-directory
+force wipe even if the project shares an object directory
 .SS Logging options:
 .TP
 \fB\-v\fR, \fB\-\-verbose\fR

man/repo.1

@@ -1,5 +1,5 @@
 .\" DO NOT MODIFY THIS FILE!  It was generated by help2man.
-.TH REPO "1" "November 2025" "repo" "Repo Manual"
+.TH REPO "1" "June 2026" "repo" "Repo Manual"
 .SH NAME
 repo \- repository management tool built on top of git
 .SH SYNOPSIS
@@ -26,8 +26,7 @@ control color usage: auto, always, never
 trace git command execution (REPO_TRACE=1)
 .TP
 \fB\-\-trace\-to\-stderr\fR
-trace outputs go to stderr in addition to
-\&.repo/TRACE_FILE
+trace outputs go to stderr in addition to .repo/TRACE_FILE
 .TP
 \fB\-\-trace\-python\fR
 trace python command execution
@@ -39,8 +38,7 @@ time repo command execution
 display this version of repo
 .TP
 \fB\-\-show\-toplevel\fR
-display the path of the top\-level directory of the
-repo client checkout
+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

manifest_xml.py

@@ -651,6 +651,8 @@ https://gerrit.googlesource.com/git-repo/+/HEAD/docs/manifest-format.md
         if self._manifest_server:
             e = doc.createElement("manifest-server")
             e.setAttribute("url", self._manifest_server)
+            if self._manifest_server_helper:
+                e.setAttribute("helper", self._manifest_server_helper)
             root.appendChild(e)
             root.appendChild(doc.createTextNode(""))
 
@@ -690,9 +692,9 @@ https://gerrit.googlesource.com/git-repo/+/HEAD/docs/manifest-format.md
                 e.setAttribute("remote", remoteName)
             if peg_rev:
                 if self.IsMirror:
-                    value = p.bare_git.rev_parse(p.revisionExpr + "^0")
+                    value = p.bare_git.ResolveCommit(p.revisionExpr)
                 else:
-                    value = p.work_git.rev_parse(HEAD + "^0")
+                    value = p.work_git.ResolveCommit(HEAD)
                 e.setAttribute("revision", value)
                 if peg_rev_upstream:
                     if p.upstream:
@@ -999,6 +1001,11 @@ https://gerrit.googlesource.com/git-repo/+/HEAD/docs/manifest-format.md
         self._Load()
         return self._manifest_server
 
+    @property
+    def manifest_server_helper(self):
+        self._Load()
+        return self._manifest_server_helper
+
     @property
     def CloneBundle(self):
         clone_bundle = self.manifestProject.clone_bundle
@@ -1055,6 +1062,10 @@ https://gerrit.googlesource.com/git-repo/+/HEAD/docs/manifest-format.md
     def UseGitWorktrees(self):
         return self.manifestProject.use_worktree
 
+    @property
+    def UseLocalGitDirs(self):
+        return self.manifestProject.use_local_gitdirs
+
     @property
     def IsArchive(self):
         return self.manifestProject.archive
@@ -1153,6 +1164,7 @@ https://gerrit.googlesource.com/git-repo/+/HEAD/docs/manifest-format.md
         self._notice = None
         self.branch = None
         self._manifest_server = None
+        self._manifest_server_helper = None
 
     def Load(self):
         """Read the manifest into memory."""
@@ -1422,11 +1434,13 @@ https://gerrit.googlesource.com/git-repo/+/HEAD/docs/manifest-format.md
         for node in itertools.chain(*node_list):
             if node.nodeName == "manifest-server":
                 url = self._reqatt(node, "url")
+                helper = node.getAttribute("helper") or None
                 if self._manifest_server is not None:
                     raise ManifestParseError(
                         "duplicate manifest-server in %s" % (self.manifestFile)
                     )
                 self._manifest_server = url
+                self._manifest_server_helper = helper
 
         def recursively_add_projects(project):
             projects = self._projects.setdefault(project.name, [])
@@ -1505,9 +1519,9 @@ https://gerrit.googlesource.com/git-repo/+/HEAD/docs/manifest-format.md
                         if base_revision:
                             if p.revisionExpr != base_revision:
                                 failed_revision_changes.append(
-                                    "extend-project name %s mismatch base "
-                                    "%s vs revision %s"
-                                    % (name, base_revision, p.revisionExpr)
+                                    f"extend-project name {name}:\n  "
+                                    f"base {base_revision} vs "
+                                    f"revision {p.revisionExpr}"
                                 )
                         p.SetRevision(revision)
 
@@ -1608,9 +1622,9 @@ https://gerrit.googlesource.com/git-repo/+/HEAD/docs/manifest-format.md
                             if base_revision:
                                 if p.revisionExpr != base_revision:
                                     failed_revision_changes.append(
-                                        "remove-project name %s mismatch base "
-                                        "%s vs revision %s"
-                                        % (name, base_revision, p.revisionExpr)
+                                        f"remove-project name {name}:\n  "
+                                        f"base {base_revision} vs "
+                                        f"revision {p.revisionExpr}"
                                     )
                             del self._paths[p.relpath]
                             if not removed_project:
@@ -1622,13 +1636,9 @@ https://gerrit.googlesource.com/git-repo/+/HEAD/docs/manifest-format.md
                             if base_revision:
                                 if p.revisionExpr != base_revision:
                                     failed_revision_changes.append(
-                                        "remove-project path %s mismatch base "
-                                        "%s vs revision %s"
-                                        % (
-                                            p.relpath,
-                                            base_revision,
-                                            p.revisionExpr,
-                                        )
+                                        f"remove-project path {p.relpath}:\n  "
+                                        f"base {base_revision} vs "
+                                        f"revision {p.revisionExpr}"
                                     )
                             self._projects[projname].remove(p)
                             del self._paths[p.relpath]
@@ -1650,10 +1660,10 @@ https://gerrit.googlesource.com/git-repo/+/HEAD/docs/manifest-format.md
                     )
 
         if failed_revision_changes:
+            fail_string = "\n".join(failed_revision_changes)
             raise ManifestParseError(
-                "revision base check failed, rebase patches and update "
-                "base revs for: ",
-                failed_revision_changes,
+                f"detected base-revision mismatch, updates needed:\n"
+                f"{fail_string}",
             )
 
         # Store repo hooks project information.
@@ -2042,15 +2052,21 @@ https://gerrit.googlesource.com/git-repo/+/HEAD/docs/manifest-format.md
             else:
                 namepath = f"{name}.git"
             worktree = os.path.join(self.topdir, path).replace("\\", "/")
-            gitdir = os.path.join(self.subdir, "projects", "%s.git" % path)
-            # We allow people to mix git worktrees & non-git worktrees for now.
-            # This allows for in situ migration of repo clients.
-            if os.path.exists(gitdir) or not self.UseGitWorktrees:
-                objdir = os.path.join(self.repodir, "project-objects", namepath)
-            else:
-                use_git_worktrees = True
-                gitdir = os.path.join(self.repodir, "worktrees", namepath)
+            if self.UseLocalGitDirs:
+                gitdir = os.path.join(worktree, ".git")
                 objdir = gitdir
+            else:
+                gitdir = os.path.join(self.subdir, "projects", "%s.git" % path)
+                # We allow people to mix git worktrees & non-git worktrees for
+                # now. This allows for in situ migration of repo clients.
+                if os.path.exists(gitdir) or not self.UseGitWorktrees:
+                    objdir = os.path.join(
+                        self.repodir, "project-objects", namepath
+                    )
+                else:
+                    use_git_worktrees = True
+                    gitdir = os.path.join(self.repodir, "worktrees", namepath)
+                    objdir = gitdir
         return relpath, worktree, gitdir, objdir, use_git_worktrees
 
     def GetProjectsWithName(self, name, all_manifests=False):

release/update-manpages

@@ -23,4 +23,5 @@ import sys
 import update_manpages
 
 
-sys.exit(update_manpages.main(sys.argv[1:]))
+if __name__ == "__main__":
+    sys.exit(update_manpages.main(sys.argv[1:]))

release/update_manpages.py

@@ -76,6 +76,7 @@ def main(argv: List[str]) -> int:
     # 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! "
+    os.environ["COLUMNS"] = "10000"
 
     # "repo branch" is an alias for "repo branches".
     del subcmds.all_commands["branch"]

repo

@@ -129,7 +129,7 @@ if not REPO_REV:
 BUG_URL = "https://issues.gerritcodereview.com/issues/new?component=1370071"
 
 # increment this whenever we make important changes to this script
-VERSION = (2, 54)
+VERSION = (2, 65)
 
 # increment this if the MAINTAINER_KEYS block is modified
 KEYRING_VERSION = (2, 3)
@@ -379,6 +379,11 @@ def InitParser(parser):
         action="store_true",
         help="use git-worktree to manage projects",
     )
+    group.add_option(
+        "--use-local-gitdirs",
+        action="store_true",
+        help="bypass .repo/projects/ and use standard Git layout in working tree",
+    )
 
     # These are fundamentally different ways of structuring the checkout.
     group = parser.add_option_group("Project checkout optimizations")
@@ -400,20 +405,20 @@ def InitParser(parser):
         "--partial-clone",
         action="store_true",
         help="perform partial clone (https://git-scm.com/"
-        "docs/gitrepository-layout#_code_partialclone_code)",
+        "docs/partial-clone)",
     )
     group.add_option(
         "--no-partial-clone",
         action="store_false",
         help="disable use of partial clone (https://git-scm.com/"
-        "docs/gitrepository-layout#_code_partialclone_code)",
+        "docs/partial-clone)",
     )
     group.add_option(
         "--partial-clone-exclude",
         action="store",
         help="exclude the specified projects (a comma-delimited "
         "project names) from partial clone (https://git-scm.com"
-        "/docs/gitrepository-layout#_code_partialclone_code)",
+        "/docs/partial-clone)",
     )
     group.add_option(
         "--clone-filter",
@@ -742,6 +747,28 @@ def SetGitTrace2ParentSid(env=None):
     _setenv(KEY, value, env=env)
 
 
+def _NormalizeGpgHomePath(path: str) -> str:
+    """Convert path for GPG on Windows if running in MSYS/MinGW.
+
+    If GPG is MSYS-based (common in Git Bash/Cygwin), it expects POSIX-like paths
+    (e.g. /c/Users/... instead of C:\\Users\\...). Native Windows Python uses
+    Windows-style paths, which MSYS GPG will incorrectly treat as relative paths.
+    We use cygpath to query the active MSYS/Cygwin mount configuration and resolve
+    the correct POSIX path.
+    """
+    if platform.system() == "Windows":
+        try:
+            out = subprocess.check_output(
+                ["cygpath", "-u", path],
+                stderr=subprocess.DEVNULL,
+                universal_newlines=True,
+            )
+            return out.strip()
+        except (OSError, subprocess.CalledProcessError):
+            pass
+    return path
+
+
 def _setenv(key, value, env=None):
     """Set |key| in the OS environment |env| to |value|."""
     if env is None:
@@ -1074,7 +1101,7 @@ def verify_rev(cwd, remote_ref, rev, quiet):
             print(file=sys.stderr)
 
     env = os.environ.copy()
-    _setenv("GNUPGHOME", gpg_dir, env)
+    _setenv("GNUPGHOME", _NormalizeGpgHomePath(gpg_dir), env)
     run_git("tag", "-v", cur, cwd=cwd, env=env)
     return "%s^0" % cur
 

subcmds/abandon.py

@@ -20,7 +20,7 @@ from command import Command
 from command import DEFAULT_LOCAL_JOBS
 from error import RepoError
 from error import RepoExitError
-from git_command import git
+from git_command import IsValidBranchName
 from progress import Progress
 from repo_logging import RepoLogger
 
@@ -58,9 +58,7 @@ It is equivalent to "git branch -D <branchname>".
 
         if not opt.all:
             branches = args[0].split()
-            invalid_branches = [
-                x for x in branches if not git.check_ref_format(f"heads/{x}")
-            ]
+            invalid_branches = [x for x in branches if not IsValidBranchName(x)]
 
             if invalid_branches:
                 self.OptionParser.error(
@@ -94,7 +92,6 @@ It is equivalent to "git branch -D <branchname>".
 
     def Execute(self, opt, args):
         nb = args[0].split()
-        self.TryOverrideManifestWithSmartSync()
         err = collections.defaultdict(list)
         success = collections.defaultdict(list)
         aggregate_errors = []

subcmds/cherry_pick.py

@@ -14,6 +14,7 @@
 
 import re
 import sys
+from typing import Tuple
 
 from command import Command
 from error import GitError
@@ -43,36 +44,8 @@ change id will be added.
 
     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
-
-        sha1 = p.stdout.strip()
-
-        p = GitCommand(
-            None,
-            ["cat-file", "commit", sha1],
-            capture_stdout=True,
-            verify_command=True,
-        )
-
-        try:
-            p.Wait()
-        except GitError:
-            logger.error("error: Failed to retrieve old commit message")
-            raise
-
-        old_msg = self._StripHeader(p.stdout)
+        sha1, commit = self._ResolveReference(reference)
+        old_msg = self._StripHeader(commit)
 
         p = GitCommand(
             None,
@@ -117,6 +90,48 @@ change id will be added.
             logger.error("error: Failed to update commit message")
             raise
 
+    def _ResolveReference(self, reference: str) -> Tuple[str, str]:
+        """Resolve a commit and read it through one cat-file batch request."""
+        expression = f"{reference}^{{commit}}"
+        p = GitCommand(
+            None,
+            ["cat-file", "--batch"],
+            input=expression + "\n",
+            capture_stdout=True,
+            capture_stderr=True,
+            verify_command=True,
+        )
+        try:
+            p.Wait()
+            header, separator, output = p.stdout.partition("\n")
+            if not separator:
+                raise ValueError("missing cat-file header")
+            if header.endswith(" missing") or header.endswith(" ambiguous"):
+                raise GitError(f"commit {reference} not found")
+
+            parts = header.split(" ", 2)
+            if len(parts) != 3 or parts[1] != "commit":
+                raise ValueError(
+                    f"unexpected object type {parts[1]!r}"
+                    if len(parts) >= 2
+                    else "invalid header"
+                )
+            sha1, _object_type, _size = parts
+
+            if not output.endswith("\n"):
+                raise ValueError("truncated cat-file object")
+
+            commit = output[:-1]
+        except (GitError, ValueError) as e:
+            logger.error(
+                "error: Failed to resolve or read commit %s", reference
+            )
+            if isinstance(e, GitError):
+                raise
+            raise GitError(str(e)) from e
+
+        return sha1, commit
+
     def _IsChangeId(self, line):
         return CHANGE_ID_RE.match(line)
 

subcmds/download.py

@@ -195,7 +195,7 @@ If no project is specified try to use current directory as a project.
                 elif opt.revert:
                     project._Revert(dl.commit)
                 elif opt.ffonly:
-                    project._FastForward(dl.commit, ffonly=True)
+                    project._FastForward(dl.commit)
                 else:
                     if opt.branch:
                         project.StartBranch(opt.branch, revision=dl.commit)

subcmds/forall.py

@@ -25,7 +25,6 @@ from color import Coloring
 from command import Command
 from command import DEFAULT_LOCAL_JOBS
 from command import MirrorSafeCommand
-from error import ManifestInvalidRevisionError
 from repo_logging import RepoLogger
 
 
@@ -108,6 +107,8 @@ manifest.
 REPO_DEST_BRANCH is the name of the destination branch for code review,
 as specified in the manifest.
 
+REPO_PROJECT_FETCH_URL is the full resolved fetch URL for the project.
+
 REPO_COUNT is the total number of projects being iterated.
 
 REPO_I is the current (1-based) iteration count. Can be used in
@@ -242,13 +243,15 @@ without iterating through the remaining projects.
 
         mirror = self.manifest.IsMirror
 
-        self.TryOverrideManifestWithSmartSync()
-
         if opt.regex:
-            projects = self.FindProjects(args, all_manifests=all_trees)
+            projects = self.FindProjects(
+                args,
+                groups=opt.groups,
+                all_manifests=all_trees,
+            )
         elif opt.inverse_regex:
             projects = self.FindProjects(
-                args, inverse=True, all_manifests=all_trees
+                args, inverse=True, groups=opt.groups, all_manifests=all_trees
             )
         else:
             projects = self.GetProjects(
@@ -339,25 +342,8 @@ def DoWork(project, mirror, opt, cmd, shell, cnt, config):
             val = ""
         env[name] = val
 
-    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)
+    env.update(project.GetEnvVars(local=opt.this_manifest_only))
+    env["REPO_I"] = str(cnt + 1)
 
     if mirror:
         setenv("GIT_DIR", project.gitdir)

subcmds/info.py

@@ -18,7 +18,7 @@ import io
 import json
 import optparse
 import sys
-from typing import Any, Dict, List, NamedTuple
+from typing import Any, Dict, List, NamedTuple, Optional, Tuple
 
 from color import Coloring
 from command import DEFAULT_LOCAL_JOBS
@@ -147,8 +147,6 @@ class Info(PagedCommand):
         if not opt.this_manifest_only:
             self.manifest = self.manifest.outer_client
 
-        self.TryOverrideManifestWithSmartSync()
-
         output_format = OutputFormat[opt.format.upper()]
         if output_format == OutputFormat.JSON:
             self._ExecuteJson(opt, args)
@@ -191,20 +189,36 @@ class Info(PagedCommand):
             "superproject_revision": srev,
         }
 
-    def _getProjectData(self, project) -> Dict[str, Any]:
+    @staticmethod
+    def _GetCurrentBranch(branches: Dict[str, Any]) -> Optional[str]:
+        """Return the name of the current branch from a GetBranches mapping."""
+        return next(
+            (name for name, branch in branches.items() if branch.current), None
+        )
+
+    @classmethod
+    def _getProjectData(cls, project) -> Dict[str, Any]:
         """Gather project data as a dict."""
+        branches = project.GetBranches()
+        currentBranch = cls._GetCurrentBranch(branches)
         data = {
             "name": project.name,
             "mount_path": project.worktree,
-            "current_revision": project.GetRevisionId(),
+            "current_revision": project.GetHeadRevisionId()
+            or project.GetRevisionId(),
             "manifest_revision": project.revisionExpr,
-            "local_branches": list(project.GetBranches()),
+            "local_branches": list(branches),
         }
-        currentBranch = project.CurrentBranch
         if currentBranch:
             data["current_branch"] = currentBranch
         return data
 
+    @classmethod
+    def _ProjectDataHelper(cls, project_idx: int) -> Dict[str, Any]:
+        """Helper to get project data in parallel."""
+        project = cls.get_parallel_context()["projects"][project_idx]
+        return cls._getProjectData(project)
+
     def _ExecuteJson(self, opt, args) -> None:
         """Output info as JSON."""
         result = {}
@@ -214,7 +228,22 @@ class Info(PagedCommand):
             projs = self.GetProjects(
                 args, all_manifests=not opt.this_manifest_only
             )
-            result["projects"] = [self._getProjectData(p) for p in projs]
+            project_data = []
+
+            def _ProcessResults(_pool, _output, results):
+                project_data.extend(results)
+
+            with self.ParallelContext():
+                self.get_parallel_context()["projects"] = projs
+                self.ExecuteInParallel(
+                    opt.jobs,
+                    self._ProjectDataHelper,
+                    range(len(projs)),
+                    callback=_ProcessResults,
+                    ordered=True,
+                    chunksize=1,
+                )
+            result["projects"] = project_data
 
         json_settings = {
             # JSON style guide says Unicode characters are fully allowed.
@@ -264,6 +293,9 @@ class Info(PagedCommand):
         text = out.nofmt_printer("text")
         dimtext = out.printer("dimtext", attr="dim")
 
+        branches = project.GetBranches()
+        currentBranch = cls._GetCurrentBranch(branches)
+
         heading("Project: ")
         headtext(project.name)
         out.nl()
@@ -273,10 +305,9 @@ class Info(PagedCommand):
         out.nl()
 
         heading("Current revision: ")
-        headtext(project.GetRevisionId())
+        headtext(project.GetHeadRevisionId() or project.GetRevisionId())
         out.nl()
 
-        currentBranch = project.CurrentBranch
         if currentBranch:
             heading("Current branch: ")
             headtext(currentBranch)
@@ -286,7 +317,7 @@ class Info(PagedCommand):
         headtext(project.revisionExpr)
         out.nl()
 
-        localBranches = list(project.GetBranches().keys())
+        localBranches = list(branches)
         heading("Local Branches: ")
         redtext(str(len(localBranches)))
         if localBranches:
@@ -306,25 +337,10 @@ class Info(PagedCommand):
                 branch = branch[len(R_HEADS) :]
             logTarget = R_M + branch
 
-            bareTmp = project.bare_git._bare
-            project.bare_git._bare = False
-            localCommits = project.bare_git.rev_list(
-                "--abbrev=8",
-                "--abbrev-commit",
-                "--pretty=oneline",
-                logTarget + "..",
-                "--",
+            localCommits, originCommits = cls._GetDiffCommits(
+                project, logTarget
             )
 
-            originCommits = project.bare_git.rev_list(
-                "--abbrev=8",
-                "--abbrev-commit",
-                "--pretty=oneline",
-                ".." + logTarget,
-                "--",
-            )
-            project.bare_git._bare = bareTmp
-
             heading("Local Commits: ")
             redtext(str(len(localCommits)))
             dimtext(" (on current branch)")
@@ -354,6 +370,35 @@ class Info(PagedCommand):
 
         return buf.getvalue()
 
+    @classmethod
+    def _GetDiffCommits(
+        cls, project: Any, log_target: str
+    ) -> Tuple[List[str], List[str]]:
+        """Return local-only and remote-only commits from one history walk."""
+        git = getattr(project, "work_git", None) or getattr(
+            project, "bare_git", None
+        )
+        if git is None:
+            return [], []
+        commits = git.rev_list(
+            "--left-right",
+            "--abbrev=8",
+            "--abbrev-commit",
+            "--pretty=oneline",
+            f"HEAD...{log_target}",
+            "--",
+        )
+        if isinstance(commits, str):
+            commits = commits.splitlines()
+        local = []
+        remote = []
+        for commit in commits:
+            if commit.startswith("<"):
+                local.append(commit[1:])
+            elif commit.startswith(">"):
+                remote.append(commit[1:])
+        return local, remote
+
     def _printDiffInfo(self, opt, args):
         projs = self.GetProjects(args, all_manifests=not opt.this_manifest_only)
 
@@ -383,10 +428,18 @@ class Info(PagedCommand):
         project = cls.get_parallel_context()["projects"][project_idx]
 
         branches = []
-        br = [project.GetUploadableBranch(x) for x in project.GetBranches()]
-        br = [x for x in br if x]
+        local_branches = project.GetBranches()
+        current_branch = cls._GetCurrentBranch(local_branches)
         if opt.current_branch:
-            br = [x for x in br if x.name == project.CurrentBranch]
+            candidate_branches = (
+                [current_branch]
+                if current_branch and current_branch in local_branches
+                else []
+            )
+        else:
+            candidate_branches = local_branches
+        br = [project.GetUploadableBranch(x) for x in candidate_branches]
+        br = [x for x in br if x]
 
         for b in br:
             branches.append(
@@ -395,7 +448,7 @@ class Info(PagedCommand):
                     name=b.name,
                     commits=b.commits,
                     date=b.date,
-                    is_current=b.name == project.CurrentBranch,
+                    is_current=b.name == current_branch,
                 )
             )
         return branches

subcmds/init.py

@@ -33,6 +33,7 @@ _REPO_ALLOW_SHALLOW = os.environ.get("REPO_ALLOW_SHALLOW")
 
 class Init(InteractiveCommand, MirrorSafeCommand):
     COMMON = True
+    RESPECT_SMART_SYNC_OVERRIDE = False
     MULTI_MANIFEST_SUPPORT = True
     helpSummary = "Initialize a repo client checkout in the current directory"
     helpUsage = """
@@ -169,6 +170,7 @@ to update the working directory files.
             depth=opt.depth,
             git_event_log=self.git_event_log,
             manifest_name=opt.manifest_name,
+            use_local_gitdirs=opt.use_local_gitdirs,
         ):
             manifest_name = opt.manifest_name
             raise UpdateManifestError(

subcmds/list.py

@@ -109,7 +109,10 @@ This is similar to running: repo forall -c 'echo "$REPO_PATH : $REPO_PROJECT"'.
             )
         else:
             projects = self.FindProjects(
-                args, all_manifests=not opt.this_manifest_only
+                args,
+                groups=opt.groups,
+                missing_ok=opt.all,
+                all_manifests=not opt.this_manifest_only,
             )
 
         def _getpath(x):

subcmds/overview.py

@@ -59,10 +59,15 @@ are displayed.
         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]
+            local_branches = project.GetBranches()
+            br = []
+            for name, branch in local_branches.items():
+                uploadable = project.GetUploadableBranch(name)
+                if uploadable:
+                    uploadable.branch.current = branch.current
+                    br.append(uploadable)
             if opt.current_branch:
-                br = [x for x in br if x.name == project.CurrentBranch]
+                br = [x for x in br if x.current]
             all_branches.extend(br)
 
         if not all_branches:
@@ -97,7 +102,7 @@ are displayed.
             print(
                 "%s %-33s (%2d commit%s, %s)"
                 % (
-                    branch.name == project.CurrentBranch and "*" or " ",
+                    branch.current and "*" or " ",
                     branch.name,
                     len(commits),
                     len(commits) != 1 and "s" or " ",

subcmds/prune.py

@@ -80,7 +80,7 @@ class Prune(PagedCommand):
             print(
                 "%s %-33s "
                 % (
-                    branch.name == project.CurrentBranch and "*" or " ",
+                    branch.current and "*" or " ",
                     branch.name,
                 ),
                 end="",

subcmds/rebase.py

@@ -16,7 +16,9 @@ import sys
 
 from color import Coloring
 from command import Command
+from error import GitError
 from git_command import GitCommand
+from project import Project
 from repo_logging import RepoLogger
 
 
@@ -30,6 +32,17 @@ class RebaseColoring(Coloring):
         self.fail = self.printer("fail", fg="red")
 
 
+def _ResolveOntoManifest(project: Project) -> str:
+    """Resolve project's revisionExpr to a local tracking branch.
+
+    Falls back to the raw revisionExpr if ToLocal fails or raises GitError.
+    """
+    try:
+        return project.GetRemote().ToLocal(project.revisionExpr)
+    except GitError:
+        return project.revisionExpr
+
+
 class Rebase(Command):
     COMMON = True
     helpSummary = "Rebase local branches on upstream branch"
@@ -126,6 +139,8 @@ branch but need to incorporate new upstream changes "underneath" them.
             common_args.append("--autosquash")
         if opt.interactive:
             common_args.append("-i")
+        if opt.auto_stash:
+            common_args.append("--autostash")
 
         config = self.manifest.manifestProject.config
         out = RebaseColoring(config)
@@ -162,7 +177,7 @@ branch but need to incorporate new upstream changes "underneath" them.
             args = common_args[:]
             if opt.onto_manifest:
                 args.append("--onto")
-                args.append(project.revisionExpr)
+                args.append(_ResolveOntoManifest(project))
 
             args.append(upbranch.LocalMerge)
 
@@ -175,29 +190,10 @@ branch but need to incorporate new upstream changes "underneath" them.
             out.nl()
             out.flush()
 
-            needs_stash = False
-            if opt.auto_stash:
-                stash_args = ["update-index", "--refresh", "-q"]
-
-                if GitCommand(project, stash_args).Wait() != 0:
-                    needs_stash = True
-                    # Dirty index, requires stash...
-                    stash_args = ["stash"]
-
-                    if GitCommand(project, stash_args).Wait() != 0:
-                        ret += 1
-                        continue
-
             if GitCommand(project, args).Wait() != 0:
                 ret += 1
                 continue
 
-            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)

subcmds/start.py

@@ -18,7 +18,7 @@ from typing import NamedTuple
 from command import Command
 from command import DEFAULT_LOCAL_JOBS
 from error import RepoExitError
-from git_command import git
+from git_command import IsValidBranchName
 from git_config import IsImmutable
 from progress import Progress
 from repo_logging import RepoLogger
@@ -75,7 +75,7 @@ revision specified in the manifest.
             self.Usage()
 
         nb = args[0]
-        if not git.check_ref_format("heads/%s" % nb):
+        if not IsValidBranchName(nb):
             self.OptionParser.error("'%s' is not a valid name" % nb)
 
     @classmethod
@@ -104,7 +104,6 @@ revision specified in the manifest.
 
     def Execute(self, opt, args):
         nb = args[0]
-        self.TryOverrideManifestWithSmartSync()
         err_projects = []
         err = []
         projects = []

subcmds/status.py

@@ -54,6 +54,12 @@ project 'repo' on branch 'devwork':
   project repo/                                   branch devwork
    -m     subcmds/status.py
 
+If the branch is tracking an upstream branch, the number of commits
+ahead and/or behind is also shown:
+
+  project repo/                           branch devwork [ahead 1, behind 2]
+   -m     subcmds/status.py
+
 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:

subcmds/sync.py

@@ -23,10 +23,12 @@ import netrc
 import optparse
 import os
 from pathlib import Path
+import shutil
+import subprocess
 import sys
 import tempfile
 import time
-from typing import List, NamedTuple, Optional, Set, Tuple, Union
+from typing import Dict, List, NamedTuple, Optional, Set, Tuple, Union
 import urllib.error
 import urllib.parse
 import urllib.request
@@ -70,6 +72,7 @@ from git_refs import HEAD
 from git_refs import R_HEADS
 import git_superproject
 from hooks import RepoHook
+from manifest_xml import XmlManifest
 import platform_utils
 from progress import elapsed_str
 from progress import jobs_str
@@ -96,19 +99,27 @@ logger = RepoLogger(__file__)
 
 
 def _SafeCheckoutOrder(checkouts: List[Project]) -> List[List[Project]]:
-    """Generate a sequence of checkouts that is safe to perform. The client
-    should checkout everything from n-th index before moving to n+1.
+    """Generate a sequence of checkouts that is safe to perform.
+
+    The client should checkout everything from n-th index before moving to
+    n+1.
 
     This is only useful if manifest contains nested projects.
 
     E.g. if foo, foo/bar and foo/bar/baz are project paths, then foo needs to
     finish before foo/bar can proceed, and foo/bar needs to finish before
-    foo/bar/baz."""
-    res = [[]]
-    current = res[0]
+    foo/bar/baz.
 
-    # depth_stack contains a current stack of parent paths.
+    Discovered submodules have an additional constraint: sibling submodules in
+    the same parent repository must not be checked out in parallel because they
+    all run `git submodule init` against the same parent .git/config.
+    """
+    res = [[]]
+
+    # depth_stack contains the current stack of parent paths together with the
+    # effective checkout level assigned to each path.
     depth_stack = []
+    submodule_parent_level = {}
     # Checkouts are iterated in the hierarchical order. That way, it can easily
     # be determined if the previous checkout is parent of the current checkout.
     # We are splitting by the path separator so the final result is
@@ -119,25 +130,115 @@ def _SafeCheckoutOrder(checkouts: List[Project]) -> List[List[Project]]:
         checkout_path = Path(checkout.relpath)
         while depth_stack:
             try:
-                checkout_path.relative_to(depth_stack[-1])
+                checkout_path.relative_to(depth_stack[-1][0])
             except ValueError:
                 # Path.relative_to returns ValueError if paths are not relative.
                 # TODO(sokcevic): Switch to is_relative_to once min supported
                 # version is py3.9.
                 depth_stack.pop()
             else:
-                if len(depth_stack) >= len(res):
-                    # Another depth created.
-                    res.append([])
                 break
 
-        current = res[len(depth_stack)]
+        level = depth_stack[-1][1] + 1 if depth_stack else 0
+        parent = checkout.parent
+        if parent is not None:
+            level = max(
+                level,
+                submodule_parent_level.get(parent.worktree, level - 1) + 1,
+            )
+            submodule_parent_level[parent.worktree] = level
+        if level >= len(res):
+            res.extend([] for _ in range(level + 1 - len(res)))
+
+        current = res[level]
         current.append(checkout)
-        depth_stack.append(checkout_path)
+        depth_stack.append((checkout_path, level))
 
     return res
 
 
+def _NestedProjects(projects: List[Project]) -> List[Project]:
+    """Return the projects in |projects| living inside another one's path."""
+    return [p for level in _SafeCheckoutOrder(projects)[1:] for p in level]
+
+
+def _ParentFirstBatches(projects: List[Project]) -> List[List[Project]]:
+    """Group |projects| so that a parent is fetched before its submodules.
+
+    A discovered submodule can only be fetched at the right revision once the
+    project holding its gitlink has been fetched, so it is held back to a later
+    batch than its parent. Projects that are not discovered submodules all end
+    up in the first batch, which keeps manifests without submodules on a single
+    batch.
+    """
+    batches = collections.defaultdict(list)
+    for project in projects:
+        depth = 0
+        ancestor = project
+        while ancestor.Derived and ancestor.parent:
+            depth += 1
+            ancestor = ancestor.parent
+        batches[depth].append(project)
+    return [batches[depth] for depth in sorted(batches)]
+
+
+def _RefreshDerivedRevisions(
+    projects: List[Project],
+    submodule_revisions: Optional[Dict[Project, Dict[str, str]]] = None,
+) -> List[Project]:
+    """Re-resolve the gitlinks of the discovered submodules in |projects|.
+
+    The revision of a discovered submodule is read from its parent when the
+    manifest is loaded, so it is stale as soon as the parent gets fetched. It
+    has to be resolved again once the parent is up-to-date, and before the
+    submodule itself is fetched and checked out.
+
+    Args:
+        projects: The projects whose discovered submodules to resolve.
+        submodule_revisions: Gitlinks already read, keyed by the project
+            holding them. Passing the same dict for project sets that follow
+            the same fetches, e.g. the levels of one checkout order, keeps a
+            project from being read more than once.
+
+    Returns:
+        The submodules that their parent no longer holds a gitlink for.
+    """
+    if submodule_revisions is None:
+        submodule_revisions = {}
+
+    subprojects_by_parent = collections.defaultdict(list)
+    for project in projects:
+        if project.Derived and project.parent:
+            subprojects_by_parent[project.parent].append(project)
+
+    removed = []
+    for parent, subprojects in subprojects_by_parent.items():
+        revisions = submodule_revisions.get(parent)
+        if revisions is None:
+            revisions = parent.GetSubmoduleRevisions()
+            if revisions is None:
+                # Leave the submodules of a parent we cannot read alone.
+                continue
+            submodule_revisions[parent] = revisions
+        for subproject in subprojects:
+            rev = revisions.get(subproject.gitlink_path)
+            if rev:
+                subproject.SetRevision(rev, revisionId=rev)
+            else:
+                removed.append(subproject)
+    return removed
+
+
+def _WithoutProjects(
+    projects: List[Project], unwanted: List[Project]
+) -> List[Project]:
+    """Return |projects| without the projects in |unwanted|."""
+    if not unwanted:
+        return projects
+    dropped = set(unwanted)
+    return [p for p in projects if p not in dropped]
+
+
 def _chunksize(projects: int, jobs: int) -> int:
     """Calculate chunk size for the given number of projects and jobs."""
     return min(max(1, projects // jobs), WORKER_BATCH_SIZE)
@@ -206,7 +307,8 @@ class _SyncResult(NamedTuple):
 
     Attributes:
       project_index (int): The index of the project in the shared list.
-      relpath (str): The project's relative path from the repo client top.
+      relpath (str): The project's path relative to the tree being synced.
+          Unlike Project.relpath, it is unique across submanifests.
       remote_fetched (bool): True if the remote was actually queried.
       fetch_success (bool): True if the fetch operation was successful.
       fetch_errors (List[Exception]): The Exceptions from a failed fetch.
@@ -294,6 +396,7 @@ class TeeStringIO(io.StringIO):
 
 class Sync(Command, MirrorSafeCommand):
     COMMON = True
+    RESPECT_SMART_SYNC_OVERRIDE = False
     MULTI_MANIFEST_SUPPORT = True
     helpSummary = "Update working tree to the latest revision"
     helpUsage = """
@@ -360,8 +463,12 @@ 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.
 
-The --fetch-submodules option enables fetching Git submodules
-of a project from server.
+The --recurse-submodules option enables syncing Git submodules of all projects
+from the server. The --no-recurse-submodules option disables syncing Git
+submodules, even when a project has sync-s="true" in the manifest.
+
+The --fetch-submodules and --no-fetch-submodules options are deprecated aliases
+for --recurse-submodules and --no-recurse-submodules, respectively.
 
 The -c/--current-branch option can be used to only fetch objects that
 are on the branch specified by a project's revision.
@@ -409,6 +516,15 @@ later is required to fix a server side protocol bug.
 
     _JOBS_WARN_THRESHOLD = 100
 
+    @staticmethod
+    def _deprecated_submodules_option(option, opt_str, _value, parser):
+        enabled = opt_str == "--fetch-submodules"
+        replacement = (
+            "--recurse-submodules" if enabled else "--no-recurse-submodules"
+        )
+        logger.warning("%s is deprecated; use %s instead", opt_str, replacement)
+        setattr(parser.values, option.dest, enabled)
+
     def _Options(self, p, show_smart=True):
         p.add_option(
             "--jobs-network",
@@ -418,6 +534,8 @@ later is required to fix a server side protocol bug.
             help="number of network jobs to run in parallel (defaults to "
             "--jobs or 1). Ignored unless --no-interleaved is set",
         )
+
+        jobs_checkout_default = self._GetHelpForCpuJobCount(DEFAULT_LOCAL_JOBS)
         p.add_option(
             "--jobs-checkout",
             default=None,
@@ -425,7 +543,7 @@ later is required to fix a server side protocol bug.
             metavar="JOBS",
             help=(
                 "number of local checkout jobs to run in parallel (defaults "
-                f"to --jobs or {DEFAULT_LOCAL_JOBS}). Ignored unless "
+                f"to --jobs or {jobs_checkout_default}). Ignored unless "
                 "--no-interleaved is set"
             ),
         )
@@ -527,6 +645,13 @@ later is required to fix a server side protocol bug.
             help="temporary manifest to use for this sync",
             metavar="NAME.xml",
         )
+        p.add_option(
+            "-g",
+            "--groups",
+            help="sync projects matching the specific groups.  Not persistent "
+            "unlike when used on init",
+            metavar="GROUP",
+        )
         p.add_option(
             "--clone-bundle",
             action="store_true",
@@ -551,9 +676,29 @@ later is required to fix a server side protocol bug.
             help="password to authenticate with the manifest server",
         )
         p.add_option(
-            "--fetch-submodules",
+            "--recurse-submodules",
             action="store_true",
-            help="fetch submodules from server",
+            help="sync submodules from server",
+        )
+        p.add_option(
+            "--no-recurse-submodules",
+            dest="recurse_submodules",
+            action="store_false",
+            help="don't sync submodules from server",
+        )
+        p.add_option(
+            "--fetch-submodules",
+            dest="recurse_submodules",
+            action="callback",
+            callback=self._deprecated_submodules_option,
+            help=optparse.SUPPRESS_HELP,
+        )
+        p.add_option(
+            "--no-fetch-submodules",
+            dest="recurse_submodules",
+            action="callback",
+            callback=self._deprecated_submodules_option,
+            help=optparse.SUPPRESS_HELP,
         )
         p.add_option(
             "--use-superproject",
@@ -723,8 +868,9 @@ later is required to fix a server side protocol bug.
 
         all_projects = self.GetProjects(
             args,
+            groups=opt.groups,
             missing_ok=True,
-            submodules_ok=opt.fetch_submodules,
+            submodules_ok=opt.recurse_submodules,
             manifest=manifest,
             all_manifests=not opt.this_manifest_only,
         )
@@ -1007,6 +1153,40 @@ later is required to fix a server side protocol bug.
 
         return _FetchResult(ret, fetched)
 
+    def _FetchParentFirst(
+        self,
+        projects: List[Project],
+        opt: optparse.Values,
+        err_event: _threading.Event,
+        ssh_proxy: ssh.ProxyManager,
+        errors: List[Exception],
+    ) -> _FetchResult:
+        """Fetch |projects|, holding submodules back until their parent is done.
+
+        Args:
+            projects: Projects to fetch.
+            opt: Program options returned from optparse. See _Options().
+            err_event: Whether an error was hit while processing.
+            ssh_proxy: SSH manager for clients & masters.
+            errors: A list to accumulate errors.
+
+        Returns:
+            _FetchResult for all the batches combined.
+        """
+        success = True
+        fetched = set()
+        for batch in _ParentFirstBatches(projects):
+            batch = _WithoutProjects(batch, _RefreshDerivedRevisions(batch))
+            if not batch:
+                continue
+            batch.sort(key=self._fetch_times.Get, reverse=True)
+            result = self._Fetch(batch, opt, err_event, ssh_proxy, errors)
+            success = success and result.success
+            fetched.update(result.projects)
+            if not success and opt.fail_fast:
+                break
+        return _FetchResult(success, fetched)
+
     def _FetchMain(
         self, opt, args, all_projects, err_event, ssh_proxy, manifest, errors
     ):
@@ -1023,12 +1203,10 @@ later is required to fix a server side protocol bug.
         Returns:
             List of all projects that should be checked out.
         """
-        to_fetch = []
-        to_fetch.extend(all_projects)
-        to_fetch.sort(key=self._fetch_times.Get, reverse=True)
-
         try:
-            result = self._Fetch(to_fetch, opt, err_event, ssh_proxy, errors)
+            result = self._FetchParentFirst(
+                all_projects, opt, err_event, ssh_proxy, errors
+            )
             success = result.success
             fetched = result.projects
             if not success:
@@ -1052,8 +1230,9 @@ later is required to fix a server side protocol bug.
                 self._ReloadManifest(None, manifest)
                 all_projects = self.GetProjects(
                     args,
+                    groups=opt.groups,
                     missing_ok=True,
-                    submodules_ok=opt.fetch_submodules,
+                    submodules_ok=opt.recurse_submodules,
                     manifest=manifest,
                     all_manifests=not opt.this_manifest_only,
                 )
@@ -1070,7 +1249,9 @@ later is required to fix a server side protocol bug.
                 if previously_missing_set == missing_set:
                     break
                 previously_missing_set = missing_set
-                result = self._Fetch(missing, opt, err_event, ssh_proxy, errors)
+                result = self._FetchParentFirst(
+                    missing, opt, err_event, ssh_proxy, errors
+                )
                 success = result.success
                 new_fetched = result.projects
                 if not success:
@@ -1433,10 +1614,23 @@ later is required to fix a server side protocol bug.
         # Only check dirty or locally modified projects. These can't be
         # freshly cloned and will accumulate garbage.
         try:
-            is_dirty = project.IsDirty(consider_untracked=True)
+            status = project._GetStatusSnapshot(
+                untracked_files="normal", branch=True
+            )
+            if status is not None:
+                is_dirty = status.is_dirty(consider_untracked=True)
+                head_rev = status.branch_oid
+            else:
+                is_dirty = project.IsDirty(consider_untracked=True)
+                head_rev = project.work_git.rev_parse(HEAD)
+
+            if head_rev is None:
+                # Porcelain v2 reports an unborn branch as "(initial)".  The
+                # legacy rev-parse path failed here and skipped the bloat
+                # calculation, so preserve that behavior.
+                return None
 
             manifest_rev = project.GetRevisionId(project.bare_ref.all)
-            head_rev = project.work_git.rev_parse(HEAD)
             has_local_commits = manifest_rev != head_rev
 
             if not (is_dirty or has_local_commits):
@@ -1722,16 +1916,104 @@ later is required to fix a server side protocol bug.
 
         return True
 
-    def _SmartSyncSetup(self, opt, smart_sync_manifest_path, manifest):
-        if not manifest.manifest_server:
-            raise SmartSyncError(
-                "error: cannot smart sync: no manifest server defined in "
-                "manifest"
-            )
+    def _ResolveManifestServerTransport(self, opt, manifest):
+        """Resolves the manifest server URL and transport.
 
+        Returns:
+            Tuple[str, xmlrpc.client.Transport]: The resolved server URL and
+                transport.
+
+        Raises:
+            SmartSyncError: If resolution fails (e.g. helper missing, helper
+                error, unsupported scheme).
+        """
         manifest_server = manifest.manifest_server
-        if not opt.quiet:
-            print("Using manifest server %s" % manifest_server)
+        helper_binary = manifest.manifest_server_helper
+
+        if helper_binary:
+            if not shutil.which(helper_binary):
+                raise SmartSyncError(
+                    f"error: helper binary '{helper_binary}' declared in "
+                    "manifest was not found in your PATH."
+                )
+
+            if not opt.quiet:
+                print(f"Using remote helper {helper_binary}")
+
+            p = None
+            try:
+                p = subprocess.Popen(
+                    [helper_binary, manifest_server],
+                    stdin=subprocess.PIPE,
+                    stdout=subprocess.PIPE,
+                    stderr=subprocess.PIPE,
+                    text=True,
+                )
+                stdout, stderr = p.communicate(timeout=10)
+                output = stdout.strip()
+                stderr_content = stderr.strip() if stderr else ""
+            except subprocess.TimeoutExpired as e:
+                err_msg = f"helper {helper_binary} timed out after 10 seconds"
+                timeout_stderr = e.stderr.strip() if e.stderr else ""
+                if timeout_stderr:
+                    err_msg += f". Stderr: {timeout_stderr}"
+                raise SmartSyncError(err_msg)
+            except OSError as e:
+                raise SmartSyncError(
+                    "failed to start or communicate with helper "
+                    f"{helper_binary}: {e}"
+                )
+            finally:
+                if p and p.poll() is None:
+                    p.kill()
+                    p.wait()
+
+            if p.returncode != 0:
+                err_msg = (
+                    f"helper {helper_binary} exited with exit code "
+                    f"{p.returncode}."
+                )
+                if stderr_content:
+                    err_msg += f" Stderr: {stderr_content}"
+                raise SmartSyncError(err_msg)
+
+            try:
+                res = json.loads(output)
+                status = res.get("status")
+                msg = res.get("message")
+            except json.JSONDecodeError as e:
+                err_msg = (
+                    f"failed to parse JSON from helper {helper_binary}: {e}. "
+                    f"Output was: {output}"
+                )
+                if stderr_content:
+                    err_msg += f"\nStderr was: {stderr_content}"
+                raise SmartSyncError(err_msg)
+
+            if status != "ok":
+                err_msg = f"helper {helper_binary} returned error: {msg}"
+                if stderr_content:
+                    err_msg += f"\nStderr was: {stderr_content}"
+                raise SmartSyncError(err_msg)
+
+            proxy_url = msg
+            transport = PersistentTransport(manifest_server, proxy=proxy_url)
+            server_url = manifest_server
+            if server_url.startswith("persistent-"):
+                server_url = server_url[len("persistent-") :]
+            return server_url, transport
+
+        # Fallback path if helper isn't specified
+        scheme = urllib.parse.urlparse(manifest_server).scheme
+        if scheme not in (
+            "http",
+            "https",
+            "persistent-http",
+            "persistent-https",
+        ):
+            raise SmartSyncError(
+                f"error: unsupported manifest server scheme '{scheme}'."
+            )
 
         if "@" not in manifest_server:
             username = None
@@ -1766,20 +2048,34 @@ later is required to fix a server side protocol bug.
                 )
 
         transport = PersistentTransport(manifest_server)
-        if manifest_server.startswith("persistent-"):
-            manifest_server = manifest_server[len("persistent-") :]
+        server_url = manifest_server
+        if server_url.startswith("persistent-"):
+            server_url = server_url[len("persistent-") :]
+
+        return server_url, transport
+
+    def _SmartSyncSetup(self, opt, smart_sync_manifest_path, manifest):
+        if not manifest.manifest_server:
+            raise SmartSyncError(
+                "error: cannot smart sync: no manifest server defined in "
+                "manifest"
+            )
+
+        if not opt.quiet:
+            print("Using manifest server %s" % manifest.manifest_server)
+
+        server_url, transport = self._ResolveManifestServerTransport(
+            opt, manifest
+        )
 
         # Changes in behavior should update docs/smart-sync.md accordingly.
         try:
-            server = xmlrpc.client.Server(manifest_server, transport=transport)
+            server = xmlrpc.client.Server(server_url, transport=transport)
             if opt.smart_sync:
                 branch = self._GetBranch(manifest.manifestProject)
-
+                target = None
                 if "SYNC_TARGET" in os.environ:
                     target = os.environ["SYNC_TARGET"]
-                    [success, manifest_str] = server.GetApprovedManifest(
-                        branch, target
-                    )
                 elif (
                     "TARGET_PRODUCT" in os.environ
                     and "TARGET_BUILD_VARIANT" in os.environ
@@ -1790,9 +2086,6 @@ later is required to fix a server side protocol bug.
                         os.environ["TARGET_RELEASE"],
                         os.environ["TARGET_BUILD_VARIANT"],
                     )
-                    [success, manifest_str] = server.GetApprovedManifest(
-                        branch, target
-                    )
                 elif (
                     "TARGET_PRODUCT" in os.environ
                     and "TARGET_BUILD_VARIANT" in os.environ
@@ -1801,6 +2094,8 @@ later is required to fix a server side protocol bug.
                         os.environ["TARGET_PRODUCT"],
                         os.environ["TARGET_BUILD_VARIANT"],
                     )
+
+                if target:
                     [success, manifest_str] = server.GetApprovedManifest(
                         branch, target
                     )
@@ -1822,25 +2117,34 @@ later is required to fix a server side protocol bug.
                         aggregate_errors=[e],
                     )
                 self._ReloadManifest(manifest_name, manifest)
-            else:
-                raise SmartSyncError(
-                    "error: manifest server RPC call failed: %s" % manifest_str
-                )
+                return manifest_name
+
+            raise SmartSyncError(
+                "error: manifest server RPC call failed: %s" % manifest_str
+            )
         except (OSError, xmlrpc.client.Fault) as e:
+            if manifest.manifest_server_helper:
+                raise SmartSyncError(
+                    "error: failed to communicate with manifest server via "
+                    f"helper: {e}"
+                )
             raise SmartSyncError(
                 "error: cannot connect to manifest server %s:\n%s"
                 % (manifest.manifest_server, e),
                 aggregate_errors=[e],
             )
         except xmlrpc.client.ProtocolError as e:
+            if manifest.manifest_server_helper:
+                raise SmartSyncError(
+                    "error: failed to communicate with manifest server via "
+                    f"helper: {e}"
+                )
             raise SmartSyncError(
                 "error: cannot connect to manifest server %s:\n%d %s"
                 % (manifest.manifest_server, e.errcode, e.errmsg),
                 aggregate_errors=[e],
             )
 
-        return manifest_name
-
     def _UpdateAllManifestProjects(self, opt, mp, manifest_name, errors):
         """Fetch & update the local manifest project.
 
@@ -2189,11 +2493,13 @@ later is required to fix a server side protocol bug.
 
         all_projects = self.GetProjects(
             args,
+            groups=opt.groups,
             missing_ok=True,
-            submodules_ok=opt.fetch_submodules,
+            submodules_ok=opt.recurse_submodules,
             manifest=manifest,
             all_manifests=not opt.this_manifest_only,
         )
+        self._CheckReprojectCmdNesting(opt, args, manifest, all_projects)
 
         # Log the repo projects by existing and new.
         existing = [x for x in all_projects if x.Exists]
@@ -2257,6 +2563,46 @@ later is required to fix a server side protocol bug.
         if not opt.quiet:
             print("repo sync has finished successfully.")
 
+    def _CheckReprojectCmdNesting(
+        self,
+        opt: optparse.Values,
+        args: List[str],
+        manifest: XmlManifest,
+        all_projects: List[Project],
+    ) -> None:
+        """Fail when repo.reprojectcmd is used on a manifest nesting projects.
+
+        The command materializes a project's tree without Git, so nothing
+        keeps it from clobbering a project or submodule checked out inside
+        that tree. See docs/reproject-cmd.md.
+        """
+        if not any(p.UseReprojectCmd for p in all_projects):
+            return
+        projects = all_projects
+        if args:
+            # Nesting is a property of the manifest, not of the projects
+            # picked on the command line.
+            projects = self.GetProjects(
+                [],
+                groups=opt.groups,
+                missing_ok=True,
+                submodules_ok=opt.recurse_submodules,
+                manifest=manifest,
+                all_manifests=not opt.this_manifest_only,
+            )
+        nested = _NestedProjects(projects)
+        if not nested:
+            return
+        e = SyncError(
+            "error: repo.reprojectcmd does not support nested projects or "
+            "submodules; found:\n"
+            + "\n".join(
+                f" - {p.RelPath(local=opt.this_manifest_only)}" for p in nested
+            )
+        )
+        logger.error(e)
+        raise e
+
     def _CreateSyncProgressThread(
         self, pm: Progress, stop_event: _threading.Event
     ) -> _threading.Thread:
@@ -2586,7 +2932,7 @@ later is required to fix a server side protocol bug.
 
         return _SyncResult(
             project_index=project_index,
-            relpath=project.relpath,
+            relpath=project.RelPath(local=opt.this_manifest_only),
             fetch_success=fetch_success,
             remote_fetched=remote_fetched,
             checkout_success=checkout_success,
@@ -2734,6 +3080,10 @@ later is required to fix a server side protocol bug.
         self._interleaved_err_checkout = False
         self._interleaved_err_checkout_results = []
 
+        # Project.relpath is relative to its own (sub)manifest, so it does not
+        # tell apart projects of different manifests being synced together.
+        _RelPath = lambda p: p.RelPath(local=opt.this_manifest_only)
+
         err_event = multiprocessing.Event()
         finished_relpaths = set()
         project_list = list(all_projects)
@@ -2770,13 +3120,13 @@ later is required to fix a server side protocol bug.
                             projects_to_sync = [
                                 p
                                 for p in project_list
-                                if p.relpath not in finished_relpaths
+                                if _RelPath(p) not in finished_relpaths
                             ]
                             if not projects_to_sync:
                                 break
 
                             pending_relpaths = {
-                                p.relpath for p in projects_to_sync
+                                _RelPath(p) for p in projects_to_sync
                             }
                             if previously_pending_relpaths == pending_relpaths:
                                 stalled_projects_str = "\n".join(
@@ -2805,12 +3155,22 @@ later is required to fix a server side protocol bug.
                             # projects in one level can be processed in
                             # parallel, but we must wait for a level to complete
                             # before starting the next.
+                            submodule_revisions = {}
                             for level_projects in _SafeCheckoutOrder(
                                 projects_to_sync
                             ):
                                 if not level_projects:
                                     continue
 
+                                level_projects = _WithoutProjects(
+                                    level_projects,
+                                    _RefreshDerivedRevisions(
+                                        level_projects, submodule_revisions
+                                    ),
+                                )
+                                if not level_projects:
+                                    continue
+
                                 objdir_project_map = collections.defaultdict(
                                     list
                                 )
@@ -2852,8 +3212,9 @@ later is required to fix a server side protocol bug.
                             self._ReloadManifest(None, manifest)
                             project_list = self.GetProjects(
                                 args,
+                                groups=opt.groups,
                                 missing_ok=True,
-                                submodules_ok=opt.fetch_submodules,
+                                submodules_ok=opt.recurse_submodules,
                                 manifest=manifest,
                                 all_manifests=not opt.this_manifest_only,
                             )
@@ -3078,14 +3439,15 @@ class LocalSyncState:
 # request to request like the normal transport, the real url
 # is passed during initialization.
 class PersistentTransport(xmlrpc.client.Transport):
-    def __init__(self, orig_host):
+    def __init__(self, orig_host, proxy=None):
         super().__init__()
         self.orig_host = orig_host
+        self.proxy = proxy
 
     def request(self, host, handler, request_body, verbose=False):
         with GetUrlCookieFile(self.orig_host, not verbose) as (
             cookiefile,
-            proxy,
+            cookie_proxy,
         ):
             # Python doesn't understand cookies with the #HttpOnly_ prefix
             # Since we're only using them for HTTP, copy the file temporarily,
@@ -3111,10 +3473,11 @@ class PersistentTransport(xmlrpc.client.Transport):
             else:
                 cookiejar = cookielib.CookieJar()
 
+            active_proxy = self.proxy or cookie_proxy
             proxyhandler = urllib.request.ProxyHandler
-            if proxy:
+            if active_proxy:
                 proxyhandler = urllib.request.ProxyHandler(
-                    {"http": proxy, "https": proxy}
+                    {"http": active_proxy, "https": active_proxy}
                 )
 
             opener = urllib.request.build_opener(
@@ -3127,13 +3490,16 @@ class PersistentTransport(xmlrpc.client.Transport):
             scheme = parse_results.scheme
             if scheme == "persistent-http":
                 scheme = "http"
-            if scheme == "persistent-https":
+            elif scheme == "persistent-https":
                 # If we're proxying through persistent-https, use http. The
                 # proxy itself will do the https.
-                if proxy:
+                if active_proxy:
                     scheme = "http"
                 else:
                     scheme = "https"
+            elif scheme not in ("http", "https"):
+                if active_proxy:
+                    scheme = "http"
 
             # Parse out any authentication information using the base class.
             host, extra_headers, _ = self.get_host_info(parse_results.netloc)

subcmds/upload.py

@@ -25,7 +25,6 @@ from editor import Editor
 from error import GitError
 from error import SilentRepoExitError
 from error import UploadError
-from git_command import GitCommand
 from git_refs import R_HEADS
 import git_superproject
 from hooks import RepoHook
@@ -379,7 +378,7 @@ Gerrit Code Review:  https://www.gerritcodereview.com/
             default=True,
             help="disable verifying ssl certs (unsafe)",
         )
-        RepoHook.AddOptionGroup(p, "pre-upload")
+        RepoHook.AddOptionGroup(p, "pre-upload", allow_fix=True)
 
     def _SingleBranch(self, opt, branch, people):
         project = branch.project
@@ -436,6 +435,18 @@ Gerrit Code Review:  https://www.gerritcodereview.com/
         self._UploadAndReport(opt, [branch], people)
 
     def _MultipleBranches(self, opt, pending, people):
+        if opt.yes and (opt.current_branch or opt.branch):
+            todo = [
+                branch
+                for _, avail in pending
+                for branch in avail
+                if branch is not None
+            ]
+            if not todo:
+                _die("nothing ready for upload")
+            self._UploadAndReport(opt, todo, people)
+            return
+
         projects = {}
         branches = {}
 
@@ -649,6 +660,7 @@ Gerrit Code Review:  https://www.gerritcodereview.com/
             validate_certs=opt.validate_certs,
             push_options=push_options,
             patchset_description=opt.patchset_description,
+            git_event_log=self.git_event_log,
         )
 
         branch.uploaded = True
@@ -704,36 +716,31 @@ Gerrit Code Review:  https://www.gerritcodereview.com/
             raise UploadExitError(aggregate_errors=aggregate_errors)
 
     def _GetMergeBranch(self, project, local_branch=None):
+        """Get the merge branch name for a local branch.
+
+        Resolves the merge branch in-memory via project configuration to
+        avoid git subprocess overhead during upload.
+        """
         if local_branch is None:
-            p = GitCommand(
-                project,
-                ["rev-parse", "--abbrev-ref", "HEAD"],
-                capture_stdout=True,
-                capture_stderr=True,
-            )
-            p.Wait()
-            local_branch = p.stdout.strip()
-        p = GitCommand(
-            project,
-            ["config", "--get", "branch.%s.merge" % local_branch],
-            capture_stdout=True,
-            capture_stderr=True,
-        )
-        p.Wait()
-        merge_branch = p.stdout.strip()
-        return merge_branch
+            local_branch = project.CurrentBranch
+        if local_branch:
+            branch = project.GetBranch(local_branch)
+            if branch.merge:
+                return branch.merge
+        return ""
 
     @classmethod
     def _GatherOne(cls, opt, project_idx):
         """Figure out the upload status for |project|."""
         project = cls.get_parallel_context()["projects"][project_idx]
+        cbr = None
         if opt.current_branch:
             cbr = project.CurrentBranch
             up_branch = project.GetUploadableBranch(cbr)
             avail = [up_branch] if up_branch else None
         else:
             avail = project.GetUploadableBranches(opt.branch)
-        return (project_idx, avail)
+        return (project_idx, avail, cbr)
 
     def Execute(self, opt, args):
         projects = self.GetProjects(
@@ -743,7 +750,7 @@ Gerrit Code Review:  https://www.gerritcodereview.com/
         def _ProcessResults(_pool, _out, results):
             pending = []
             for result in results:
-                project_idx, avail = result
+                project_idx, avail, current_branch = result
                 project = projects[project_idx]
                 if avail is None:
                     logger.error(
@@ -751,7 +758,7 @@ Gerrit Code Review:  https://www.gerritcodereview.com/
                         "You might be able to fix the branch by running:\n"
                         "  git branch --set-upstream-to m/%s",
                         project.RelPath(local=opt.this_manifest_only),
-                        project.CurrentBranch,
+                        current_branch,
                         project.manifest.branch,
                     )
                 elif avail:

subcmds/version.py

@@ -14,10 +14,12 @@
 
 import platform
 import sys
+from typing import Any, Tuple
 
 from command import Command
 from command import MirrorSafeCommand
 from git_command import git
+from git_command import git_require
 from git_command import RepoSourceVersion
 from git_command import user_agent
 from git_refs import HEAD
@@ -34,6 +36,22 @@ class Version(Command, MirrorSafeCommand):
 %prog
 """
 
+    @staticmethod
+    def _RepoVersion(project: Any) -> Tuple[str, str]:
+        """Return repo's describe string and commit date."""
+        if git_require((2, 32, 0)):
+            output = project.bare_git.log(
+                "-1", "--format=%(describe)%n%cD", HEAD
+            )
+            description, commit_date = output.rstrip("\n").split("\n", 1)
+            if description:
+                return description, commit_date
+
+        return (
+            project.bare_git.describe(HEAD),
+            project.bare_git.log("-1", "--format=%cD", HEAD),
+        )
+
     def Execute(self, opt, args):
         rp = self.manifest.repoProject
         rem = rp.GetRemote()
@@ -41,11 +59,11 @@ class Version(Command, MirrorSafeCommand):
 
         # These might not be the same.  Report them both.
         src_ver = RepoSourceVersion()
-        rp_ver = rp.bare_git.describe(HEAD)
+        rp_ver, commit_date = self._RepoVersion(rp)
         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)})")
+        print(f"       ({commit_date})")
 
         if self.wrapper_path is not None:
             print(f"repo launcher version {self.wrapper_version}")

tests/test_color.py

@@ -14,6 +14,8 @@
 
 """Unittests for the color.py module."""
 
+from unittest import mock
+
 import pytest
 import utils_for_test
 
@@ -24,9 +26,14 @@ import git_config
 @pytest.fixture
 def coloring() -> color.Coloring:
     """Create a Coloring object for testing."""
+    return _make_coloring("always")
+
+
+def _make_coloring(default_state: str) -> color.Coloring:
+    """Set the default color mode and return a Coloring using test config."""
     config_fixture = utils_for_test.FIXTURES_DIR / "test.gitconfig"
     config = git_config.GitConfig(config_fixture)
-    color.SetDefaultColoring("true")
+    color.SetDefaultColoring(default_state)
     return color.Coloring(config, "status")
 
 
@@ -72,3 +79,76 @@ def test_Color_Parse_empty_entry(coloring: color.Coloring) -> None:
     assert val == "\033[2;34;47m"
     val = coloring._parse("empty", "green", "white", "bold")
     assert val == "\033[1;32;47m"
+
+
+class TestSetDefaultColoring:
+    """Tests for SetDefaultColoring."""
+
+    def test_none_leaves_default_unchanged(self) -> None:
+        color.DEFAULT = "auto"
+        color.SetDefaultColoring(None)
+        assert color.DEFAULT == "auto"
+
+    @pytest.mark.parametrize(
+        "value, expected",
+        (
+            # auto/true/yes all store their lowercase form.
+            ("auto", "auto"),
+            ("Auto", "auto"),
+            ("true", "true"),
+            ("True", "true"),
+            ("yes", "yes"),
+            ("Yes", "yes"),
+            # "always" stores as "always".
+            ("always", "always"),
+            ("Always", "always"),
+            # never/no/false store their lowercase form.
+            ("never", "never"),
+            ("no", "no"),
+            ("false", "false"),
+        ),
+    )
+    def test_maps_to_expected(self, value: str, expected: str) -> None:
+        color.SetDefaultColoring(value)
+        assert color.DEFAULT == expected
+
+    def test_unrecognised_leaves_default_unchanged(self) -> None:
+        color.DEFAULT = "auto"
+        color.SetDefaultColoring("garbage")
+        assert color.DEFAULT == "auto"
+
+
+class TestColoringInit:
+    """Tests for Coloring.__init__ color mode logic."""
+
+    @pytest.mark.parametrize(
+        "state, isatty, pager_active, expected",
+        (
+            # "always" enables color unconditionally.
+            ("always", False, False, True),
+            # "never" disables color unconditionally.
+            ("never", True, True, False),
+            # auto/true/yes enable color only on a TTY or active pager.
+            ("auto", True, False, True),
+            ("auto", False, False, False),
+            ("auto", False, True, True),
+            ("true", True, False, True),
+            ("true", False, False, False),
+            ("true", False, True, True),
+            ("yes", True, False, True),
+            ("yes", False, False, False),
+            ("yes", False, True, True),
+        ),
+    )
+    def test_color_mode(
+        self,
+        state: str,
+        isatty: bool,
+        pager_active: bool,
+        expected: bool,
+    ) -> None:
+        with mock.patch("os.isatty", return_value=isatty), mock.patch(
+            "pager.active", pager_active
+        ):
+            c = _make_coloring(state)
+        assert c.is_on is expected

tests/test_command.py

@@ -14,6 +14,10 @@
 
 """Unittests for the command.py module."""
 
+from typing import Iterable, List, Optional
+
+import pytest
+
 from command import Command
 
 
@@ -28,12 +32,15 @@ class FakeProject:
         gitdir=None,
         derived_subprojects=None,
         sync_s=False,
+        exists: bool = True,
     ):
         self.name = name
         self.relpath = relpath
+        self.worktree = f"/work/{relpath}"
+        self.manifest = None
         self.gitdir = gitdir or f"/git/{relpath}"
         self.sync_s = sync_s
-        self.Exists = True
+        self.Exists = exists
         self._derived_subprojects = derived_subprojects or []
 
     def GetDerivedSubprojects(self):
@@ -49,11 +56,59 @@ class FakeProject:
 class FakeManifest:
     """Minimal manifest double for Command.GetProjects tests."""
 
-    def __init__(self, projects):
-        self.projects = projects
+    def __init__(
+        self,
+        projects: Iterable[FakeProject],
+        *,
+        all_projects: Optional[Iterable[FakeProject]] = None,
+        effective_groups: str = "default",
+    ):
+        self.projects = list(projects)
+        self.all_projects = (
+            list(self.projects) if all_projects is None else list(all_projects)
+        )
+        self._effective_groups = effective_groups
+        self.path_prefix = ""
+
+        # all_projects may include projects owned by child manifests,
+        # so only set this manifest on its direct projects.
+        for project in self.projects:
+            self._set_project_manifest(project)
+
+    def _set_project_manifest(self, project: FakeProject) -> None:
+        project.manifest = self
+        for subproject in project.GetDerivedSubprojects():
+            self._set_project_manifest(subproject)
 
     def GetManifestGroupsStr(self):
-        return "default"
+        return self._effective_groups
+
+    def GetProjectsWithName(
+        self, name: str, all_manifests: bool = False
+    ) -> List[FakeProject]:
+        projects = self.all_projects if all_manifests else self.projects
+        return [project for project in projects if project.name == name]
+
+
+class GroupMatchingFakeProject(FakeProject):
+    """Fake project with predictable group matches for GetProjects tests.
+
+    This lets the tests check which groups GetProjects uses without
+    reimplementing Project.MatchesGroups.
+    """
+
+    def __init__(
+        self,
+        name: str,
+        relpath: str,
+        *,
+        matching_groups: Iterable[str],
+    ):
+        super().__init__(name, relpath)
+        self._matching_groups = set(matching_groups)
+
+    def MatchesGroups(self, groups: Iterable[str]) -> bool:
+        return bool(self._matching_groups.intersection(groups))
 
 
 def test_get_projects_keeps_derived_subprojects_for_repeated_repo():
@@ -86,3 +141,209 @@ def test_get_projects_keeps_derived_subprojects_for_repeated_repo():
     projects = cmd.GetProjects([])
 
     assert set(projects) == {project_a, project_b, submodule_a, submodule_b}
+
+
+@pytest.mark.parametrize(
+    "submodules_ok, sync_s, includes_submodule",
+    [
+        (None, False, False),
+        (None, True, True),
+        (True, False, True),
+        (True, True, True),
+        (False, False, False),
+        (False, True, False),
+    ],
+)
+def test_get_projects_submodule_override(
+    submodules_ok, sync_s, includes_submodule
+):
+    """The CLI override takes precedence over a project's sync-s setting."""
+    submodule = FakeProject("submodule", "project/submodule")
+    project = FakeProject(
+        "project",
+        "project",
+        derived_subprojects=[submodule],
+        sync_s=sync_s,
+    )
+    cmd = Command(manifest=FakeManifest([project]))
+
+    projects = cmd.GetProjects([], submodules_ok=submodules_ok)
+
+    assert (submodule in projects) is includes_submodule
+
+
+@pytest.mark.parametrize(
+    ("groups", "expected_relpaths"),
+    [
+        (None, ["outer", "sub/child"]),
+        ("", ["outer", "sub/child"]),
+        ("override-group", ["sub/override"]),
+    ],
+    ids=("groups-omitted", "groups-empty", "explicit-override"),
+)
+def test_get_projects_uses_groups_from_each_manifest_unless_overridden(
+    groups: Optional[str],
+    expected_relpaths: List[str],
+) -> None:
+    """Use each manifest's effective groups unless the caller overrides them."""
+    outer_project = GroupMatchingFakeProject(
+        "outer",
+        "outer",
+        matching_groups={"outer-group"},
+    )
+
+    # Both child projects also match "outer". Reusing the outer manifest's
+    # groups would therefore select both child projects.
+    child_project = GroupMatchingFakeProject(
+        "child",
+        "sub/child",
+        matching_groups={"outer-group", "child-group"},
+    )
+    override_project = GroupMatchingFakeProject(
+        "override",
+        "sub/override",
+        matching_groups={"outer-group", "override-group"},
+    )
+
+    child_manifest = FakeManifest(
+        [child_project, override_project],
+        effective_groups="child-group",
+    )
+    outer_manifest = FakeManifest(
+        [outer_project],
+        all_projects=[outer_project, *child_manifest.projects],
+        effective_groups="outer-group",
+    )
+    cmd = Command(manifest=outer_manifest)
+
+    projects = cmd.GetProjects(
+        [],
+        manifest=outer_manifest,
+        groups=groups,
+        all_manifests=True,
+    )
+
+    assert [project.relpath for project in projects] == expected_relpaths
+
+
+def test_get_projects_by_name_uses_groups_from_each_manifest() -> None:
+    """Name matches use the groups from each project's owning manifest."""
+    outer_project = GroupMatchingFakeProject(
+        "shared",
+        "outer/shared",
+        matching_groups={"outer-group"},
+    )
+    child_project = GroupMatchingFakeProject(
+        "shared",
+        "sub/shared",
+        matching_groups={"child-group"},
+    )
+
+    child_manifest = FakeManifest(
+        [child_project],
+        effective_groups="child-group",
+    )
+    outer_manifest = FakeManifest(
+        [outer_project],
+        all_projects=[outer_project, *child_manifest.projects],
+        effective_groups="outer-group",
+    )
+    cmd = Command(manifest=outer_manifest)
+
+    projects = cmd.GetProjects(
+        ["shared"],
+        manifest=outer_manifest,
+        all_manifests=True,
+    )
+
+    assert [project.relpath for project in projects] == [
+        "outer/shared",
+        "sub/shared",
+    ]
+
+
+def test_find_projects_uses_groups_from_each_manifest() -> None:
+    """Use each manifest's effective groups for regex selection."""
+    outer_project = GroupMatchingFakeProject(
+        "match-outer",
+        "outer",
+        matching_groups={"outer-group"},
+    )
+    child_project = GroupMatchingFakeProject(
+        "match-child",
+        "sub/child",
+        matching_groups={"child-group"},
+    )
+    excluded_project = GroupMatchingFakeProject(
+        "match-excluded",
+        "sub/excluded",
+        matching_groups={"other-group"},
+    )
+
+    child_manifest = FakeManifest(
+        [child_project, excluded_project],
+        effective_groups="child-group",
+    )
+    child_manifest.path_prefix = "sub"
+
+    outer_manifest = FakeManifest(
+        [outer_project],
+        all_projects=[
+            outer_project,
+            *child_manifest.projects,
+        ],
+        effective_groups="outer-group",
+    )
+    outer_manifest.outer_client = outer_manifest
+
+    cmd = Command(manifest=outer_manifest)
+
+    projects = cmd.FindProjects(["match"], all_manifests=True)
+
+    assert [project.relpath for project in projects] == [
+        "outer",
+        "sub/child",
+    ]
+
+
+def test_find_projects_uses_explicit_groups() -> None:
+    """Use explicit groups for regex selection."""
+    default_project = GroupMatchingFakeProject(
+        "default",
+        "default",
+        matching_groups={"default-group"},
+    )
+    override_project = GroupMatchingFakeProject(
+        "override",
+        "override",
+        matching_groups={"override-group"},
+    )
+    manifest = FakeManifest(
+        [default_project, override_project],
+        effective_groups="default-group",
+    )
+    cmd = Command(manifest=manifest)
+
+    projects = cmd.FindProjects(
+        ["override"],
+        groups="override-group",
+    )
+
+    assert projects == [override_project]
+
+
+def test_find_projects_allows_missing_projects() -> None:
+    """Allow regex selection to include projects without a checkout."""
+    project = FakeProject(
+        "missing",
+        "missing",
+        exists=False,
+    )
+    cmd = Command(manifest=FakeManifest([project]))
+
+    projects = cmd.FindProjects(
+        ["missing"],
+        missing_ok=True,
+    )
+
+    assert projects == [project]

tests/test_git_command.py

@@ -123,6 +123,7 @@ class GitCommandStreamLogsTest(unittest.TestCase):
     """Tests the GitCommand class stderr log streaming cases."""
 
     def setUp(self):
+        _ = git_command.user_agent.git
         self.mock_process = mock.MagicMock()
         self.mock_process.communicate.return_value = (None, None)
         self.mock_process.wait.return_value = 0
@@ -228,9 +229,162 @@ class GitCommandStreamLogsTest(unittest.TestCase):
         self.assertEqual(cmd.stderr, logs)
 
 
+class GitCommandCaptureBytesTest(unittest.TestCase):
+    """Tests the GitCommand class byte capture cases."""
+
+    def setUp(self) -> None:
+        _ = git_command.user_agent.git
+        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) -> None:
+        mock.patch.stopall()
+
+    def test_captures_stdout_as_bytes(self) -> None:
+        self.mock_process.communicate.return_value = (b"\xff\x00", b"error\r\n")
+
+        cmd = git_command.GitCommand(
+            None,
+            ["status"],
+            capture_stdout=True,
+            capture_stdout_bytes=True,
+            capture_stderr=True,
+        )
+
+        self.mock_popen.assert_called_once_with(
+            ["git", "status"],
+            cwd=None,
+            env=mock.ANY,
+            stdin=None,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+        )
+        self.assertEqual(cmd.stdout, b"\xff\x00")
+        self.assertEqual(cmd.stderr, "error\n")
+
+    def test_capture_stdout_bytes_auto_enables_capture_stdout(self) -> None:
+        self.mock_process.communicate.return_value = (b"output", b"")
+
+        cmd = git_command.GitCommand(
+            None,
+            ["status"],
+            capture_stdout_bytes=True,
+        )
+
+        self.mock_popen.assert_called_once_with(
+            ["git", "status"],
+            cwd=None,
+            env=mock.ANY,
+            stdin=None,
+            stdout=subprocess.PIPE,
+            stderr=None,
+        )
+        self.assertEqual(cmd.stdout, b"output")
+
+    def test_capture_stdout_bytes_with_merge_output_raises(self) -> None:
+        with self.assertRaises(ValueError):
+            git_command.GitCommand(
+                None,
+                ["status"],
+                capture_stdout_bytes=True,
+                merge_output=True,
+            )
+
+    def test_captures_stdout_as_bytes_encodes_str_input(self) -> None:
+        self.mock_process.communicate.return_value = (b"output", b"")
+
+        git_command.GitCommand(
+            None,
+            ["status"],
+            input="hello world",
+            capture_stdout_bytes=True,
+        )
+
+        self.mock_process.communicate.assert_called_once_with(
+            input=b"hello world"
+        )
+
+    def test_captures_stdout_as_bytes_encodes_surrogate_input(self) -> None:
+        self.mock_process.communicate.return_value = (b"output", b"")
+
+        git_command.GitCommand(
+            None,
+            ["status"],
+            input="file_\udcff.txt",
+            capture_stdout_bytes=True,
+        )
+
+        self.mock_process.communicate.assert_called_once_with(
+            input=b"file_\xff.txt"
+        )
+
+    def test_captures_stdout_as_bytes_passes_bytes_input(self) -> None:
+        self.mock_process.communicate.return_value = (b"output", b"")
+
+        git_command.GitCommand(
+            None,
+            ["status"],
+            input=b"raw_\xff.txt",
+            capture_stdout_bytes=True,
+        )
+
+        self.mock_process.communicate.assert_called_once_with(
+            input=b"raw_\xff.txt"
+        )
+
+    def test_verify_command_truncates_nul_delimited_stdout(self) -> None:
+        cmd = git_command.GitCommand(
+            None,
+            ["status"],
+            capture_stdout_bytes=True,
+        )
+        cmd.rc = 1
+        cmd.stdout = b"first_file\0second_file\0third_file"
+        cmd.stderr = "stderr"
+        with self.assertRaises(git_command.GitCommandError) as cm:
+            cmd.VerifyCommand()
+        self.assertEqual(cm.exception.git_stdout, "first_file")
+
+    def test_verify_command_decodes_bytes_stdout(self) -> None:
+        cmd = git_command.GitCommand(
+            None,
+            ["status"],
+            capture_stdout_bytes=True,
+        )
+        cmd.rc = 1
+        cmd.stdout = b"error\xff\nline2"
+        cmd.stderr = "stderr"
+        with self.assertRaises(git_command.GitCommandError) as cm:
+            cmd.VerifyCommand()
+        self.assertEqual(cm.exception.git_stdout, "error\\xff")
+
+
 class GitCallUnitTest(unittest.TestCase):
     """Tests the _GitCall class (via git_command.git)."""
 
+    def test_valid_branch_name_uses_branch_mode(self) -> None:
+        """Branch validation applies Git's branch-specific restrictions."""
+        command = mock.MagicMock()
+        command.Wait.return_value = 1
+        with mock.patch.object(
+            git_command, "GitCommand", return_value=command
+        ) as check:
+            self.assertFalse(git_command.IsValidBranchName("-topic"))
+
+        check.assert_called_once_with(
+            None,
+            ["check-ref-format", "--branch", "-topic"],
+            capture_stdout=True,
+            capture_stderr=True,
+            add_event_log=False,
+            log_as_error=False,
+        )
+
     def test_version_tuple(self):
         """Check git.version_tuple() handling."""
         ver = git_command.git.version_tuple()

tests/test_git_config.py

@@ -244,3 +244,27 @@ def test_remote_save_with_push_url_without_projectname(
     assert (
         written_config.GetString("remote.origin.pushurl") == "ssh://example.com"
     )
+
+
+@pytest.mark.parametrize(
+    "rev, expected",
+    (
+        ("a" * 40, True),
+        ("0" * 40, True),
+        ("f" * 40, True),
+        ("a" * 64, True),
+        ("0" * 64, True),
+        ("f" * 64, True),
+        ("a" * 39, False),
+        ("a" * 41, False),
+        ("a" * 63, False),
+        ("a" * 65, False),
+        ("g" * 40, False),
+        ("g" * 64, False),
+        ("refs/heads/master", False),
+        ("refs/tags/v1.0", False),
+    ),
+)
+def test_is_id(rev: str, expected: bool) -> None:
+    """Test IsId identifies both SHA-1 and SHA-256 hashes."""
+    assert git_config.IsId(rev) == expected

tests/test_git_refs.py

@@ -17,6 +17,8 @@
 import os
 from pathlib import Path
 import subprocess
+from typing import Any, List
+from unittest import mock
 
 import pytest
 import utils_for_test
@@ -24,7 +26,7 @@ import utils_for_test
 import git_refs
 
 
-def _run(repo, *args):
+def _run(repo: str, *args: str) -> str:
     return subprocess.run(
         ["git", "-C", repo, *args],
         stdout=subprocess.PIPE,
@@ -34,7 +36,7 @@ def _run(repo, *args):
     ).stdout.strip()
 
 
-def _init_repo(tmp_path, reftable=False):
+def _init_repo(tmp_path: Path, reftable: bool = False) -> str:
     repo = os.path.join(tmp_path, "repo")
     ref_format = "reftable" if reftable else "files"
     utils_for_test.init_git_tree(repo, ref_format=ref_format)
@@ -57,10 +59,154 @@ def test_reads_refs(tmp_path, reftable):
     branch = _run(repo, "symbolic-ref", "--short", "HEAD")
     head = _run(repo, "rev-parse", "HEAD")
     assert refs.symref("HEAD") == f"refs/heads/{branch}"
+    assert refs.head == f"refs/heads/{branch}"
     assert refs.get("HEAD") == head
     assert refs.get(f"refs/heads/{branch}") == head
 
 
+@pytest.mark.parametrize("reftable", [False, True])
+def test_reads_detached_head(tmp_path: Path, reftable: bool) -> None:
+    if reftable and not utils_for_test.supports_reftable():
+        pytest.skip("reftable not supported")
+
+    repo = _init_repo(tmp_path, reftable=reftable)
+    head = _run(repo, "rev-parse", "HEAD")
+    _run(repo, "checkout", "--detach", head)
+    refs = git_refs.GitRefs(os.path.join(repo, ".git"))
+
+    assert refs.symref("HEAD") == ""
+    assert refs.head == head
+    assert refs.get("HEAD") == head
+
+
+def test_reads_head_with_root_refs_in_one_command(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """Git 2.45 and newer include HEAD in the ref snapshot."""
+    head = "1" * 40
+    commands = []
+
+    class FakeGitCommand:
+        def __init__(
+            self, _project: Any, cmdv: List[str], **_kwargs: Any
+        ) -> None:
+            commands.append(cmdv)
+            self.stdout = (
+                f"{head}\0HEAD\0refs/heads/main\n"
+                f"{head}\0refs/heads/main\0\n"
+            )
+
+        def Wait(self) -> int:
+            return 0
+
+    monkeypatch.setattr(git_refs, "GitCommand", FakeGitCommand)
+    monkeypatch.setattr(git_refs, "git_require", lambda _version: True)
+    refs = git_refs.GitRefs("/nonexistent")
+    with mock.patch.object(refs, "_ReadSymbolicRef") as read_head:
+        assert refs.get("HEAD") == head
+
+    assert commands == [
+        [
+            "for-each-ref",
+            "--include-root-refs",
+            "--format=%(objectname)%00%(refname)%00%(symref)",
+            "HEAD",
+            "refs",
+        ]
+    ]
+    read_head.assert_not_called()
+
+
+def test_root_ref_snapshot_falls_back_for_unborn_head(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """An unborn HEAD still uses symbolic-ref after the ref snapshot."""
+
+    class FakeGitCommand:
+        def __init__(
+            self, _project: Any, _cmdv: List[str], **_kwargs: Any
+        ) -> None:
+            self.stdout = ""
+
+        def Wait(self) -> int:
+            return 0
+
+    monkeypatch.setattr(git_refs, "GitCommand", FakeGitCommand)
+    monkeypatch.setattr(git_refs, "git_require", lambda _version: True)
+    refs = git_refs.GitRefs("/nonexistent")
+
+    def read_head(name: str) -> None:
+        assert name == "HEAD"
+        refs._symref[name] = "refs/heads/main"
+
+    monkeypatch.setattr(refs, "_ReadSymbolicRef", read_head)
+
+    assert refs.symref("HEAD") == "refs/heads/main"
+
+
+def test_old_git_keeps_separate_head_fallback(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """Git before 2.45 uses the original for-each-ref and HEAD calls."""
+    head = "1" * 40
+    commands = []
+
+    class FakeGitCommand:
+        def __init__(
+            self, _project: Any, cmdv: List[str], **_kwargs: Any
+        ) -> None:
+            commands.append(cmdv)
+            self.stdout = f"{head}\0refs/heads/main\0\n"
+
+        def Wait(self) -> int:
+            return 0
+
+    monkeypatch.setattr(git_refs, "GitCommand", FakeGitCommand)
+    monkeypatch.setattr(git_refs, "git_require", lambda _version: False)
+    refs = git_refs.GitRefs("/nonexistent")
+
+    def read_head(name: str) -> None:
+        assert name == "HEAD"
+        refs._symref[name] = "refs/heads/main"
+
+    monkeypatch.setattr(refs, "_ReadSymbolicRef", read_head)
+
+    assert refs.get("HEAD") == head
+    assert commands == [
+        [
+            "for-each-ref",
+            "--format=%(objectname)%00%(refname)%00%(symref)",
+        ]
+    ]
+
+
+def test_for_each_ref_failure_falls_back_to_symbolic_ref(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """When for-each-ref fails, HEAD is still resolved via symbolic-ref."""
+
+    class FakeGitCommand:
+        def __init__(
+            self, _project: Any, _cmdv: List[str], **_kwargs: Any
+        ) -> None:
+            self.stdout = ""
+
+        def Wait(self) -> int:
+            return 1
+
+    monkeypatch.setattr(git_refs, "GitCommand", FakeGitCommand)
+    monkeypatch.setattr(git_refs, "git_require", lambda _version: True)
+    refs = git_refs.GitRefs("/nonexistent")
+
+    def read_head(name: str) -> None:
+        assert name == "HEAD"
+        refs._symref[name] = "refs/heads/main"
+
+    monkeypatch.setattr(refs, "_ReadSymbolicRef", read_head)
+
+    assert refs.symref("HEAD") == "refs/heads/main"
+
+
 @pytest.mark.parametrize("reftable", [False, True])
 def test_updates_when_refs_change(tmp_path, reftable):
     if reftable and not utils_for_test.supports_reftable():

tests/test_git_status.py

@@ -0,0 +1,210 @@
+# Copyright (C) 2026 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_status.py module."""
+
+import os
+from typing import Any, List
+from unittest import mock
+
+import pytest
+
+import git_status
+
+
+def test_parse_porcelain_v2_branch_and_paths() -> None:
+    output = (
+        b"# branch.oid " + b"1" * 40 + b"\0"
+        b"# branch.head topic\0"
+        b"# branch.upstream origin/main\0"
+        b"# branch.ab +2 -3\0"
+        b"# stash 1\0"
+        b"1 M. N... 100644 100644 100644 "
+        + b"1" * 40
+        + b" "
+        + b"2" * 40
+        + b" staged name\0"
+        b"1 .M N... 100644 100644 100644 "
+        + b"1" * 40
+        + b" "
+        + b"2" * 40
+        + b" worktree name\0"
+        b"2 R. N... 100644 100644 100644 "
+        + b"1" * 40
+        + b" "
+        + b"2" * 40
+        + b" R075 renamed\0old name\0"
+        b"? untracked\0"
+    )
+
+    status = git_status.ParsePorcelainV2(output)
+
+    assert status.current_branch == "topic"
+    assert status.upstream == "origin/main"
+    assert (status.ahead, status.behind, status.stash_count) == (2, 3, 1)
+    assert status.index_changes["staged name"].status == "M"
+    assert status.worktree_changes["worktree name"].status == "M"
+    renamed = status.index_changes["renamed"]
+    assert (renamed.src_path, renamed.level) == ("old name", "75")
+    assert status.untracked == ["untracked"]
+
+
+def test_parse_porcelain_v2_unmerged_and_non_utf8_path() -> None:
+    path = b"bad-\xff-name"
+    output = (
+        b"u UU N... 100644 100644 100644 100644 "
+        + b"1" * 40
+        + b" "
+        + b"2" * 40
+        + b" "
+        + b"3" * 40
+        + b" "
+        + path
+        + b"\0"
+    )
+
+    status = git_status.ParsePorcelainV2(output)
+    decoded = os.fsdecode(path)
+
+    assert status.index_changes[decoded].status == "U"
+    assert status.worktree_changes[decoded].status == "U"
+    assert os.fsencode(status.index_changes[decoded].path) == path
+
+
+def test_untracked_only_respects_consider_untracked() -> None:
+    status = git_status.ParsePorcelainV2(b"? new file\0")
+
+    assert status.is_dirty()
+    assert not status.is_dirty(consider_untracked=False)
+
+
+def test_branch_headers_preserve_non_ascii_names() -> None:
+    branch = "tópico"
+    status = git_status.ParsePorcelainV2(
+        b"# branch.oid " + b"1" * 40 + b"\0"
+        b"# branch.head " + os.fsencode(branch) + b"\0"
+    )
+
+    assert status.current_branch == branch
+
+
+def test_quick_ahead_behind_is_recorded_as_unknown() -> None:
+    status = git_status.ParsePorcelainV2(b"# branch.ab +? -?\0")
+
+    assert (status.ahead, status.behind) == (0, 0)
+    assert not status.has_ahead_behind
+
+
+def test_unknown_head_is_not_a_current_branch() -> None:
+    status = git_status.ParsePorcelainV2(b"# branch.head (unknown)\0")
+
+    assert status.current_branch is None
+
+
+def test_malformed_output_is_rejected() -> None:
+    with pytest.raises(git_status.StatusParseError):
+        git_status.ParsePorcelainV2(b"2 R. truncated\0")
+
+
+def test_malformed_branch_ab_is_rejected() -> None:
+    with pytest.raises(git_status.StatusParseError):
+        git_status.ParsePorcelainV2(b"# branch.ab not-a-valid-ab\0")
+
+
+def test_ignored_records_are_skipped() -> None:
+    status = git_status.ParsePorcelainV2(b"! ignored_file\0")
+    assert not status.is_dirty()
+    assert status.untracked == []
+
+
+def test_get_status_uses_versioned_machine_options(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    commands = []
+
+    class FakeGitCommand:
+        def __init__(
+            self, _project: Any, cmdv: List[str], **kwargs: Any
+        ) -> None:
+            commands.append((cmdv, kwargs))
+            self.stdout = b""
+
+        def Wait(self) -> int:
+            return 0
+
+    monkeypatch.setattr(git_status, "GitCommand", FakeGitCommand)
+    monkeypatch.setattr(git_status, "git_require", lambda _version: True)
+
+    git_status.GetStatus(
+        mock.sentinel.project,
+        mock.sentinel.gitdir,
+        untracked_files="no",
+        branch=True,
+        ahead_behind=True,
+        show_stash=True,
+    )
+
+    cmd, kwargs = commands[0]
+    assert cmd == [
+        "status",
+        "--porcelain=v2",
+        "-z",
+        "--ignore-submodules=all",
+        "--untracked-files=no",
+        "--branch",
+        "--ahead-behind",
+        "--renames",
+        "--show-stash",
+    ]
+    assert kwargs["capture_stdout_bytes"]
+
+
+def test_get_status_rejects_git_before_2_11(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.setattr(git_status, "git_require", lambda _version: False)
+
+    with pytest.raises(git_status.UnsupportedStatusError):
+        git_status.GetStatus(mock.sentinel.project, mock.sentinel.gitdir)
+
+
+def test_get_status_omits_stash_header_before_2_35(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    commands = []
+
+    class FakeGitCommand:
+        def __init__(
+            self, _project: Any, cmdv: List[str], **_kwargs: Any
+        ) -> None:
+            commands.append(cmdv)
+            self.stdout = b""
+
+        def Wait(self) -> int:
+            return 0
+
+    monkeypatch.setattr(git_status, "GitCommand", FakeGitCommand)
+    monkeypatch.setattr(
+        git_status,
+        "git_require",
+        lambda version: version <= (2, 34, 0),
+    )
+
+    git_status.GetStatus(
+        mock.sentinel.project,
+        mock.sentinel.gitdir,
+        show_stash=True,
+    )
+
+    assert "--show-stash" not in commands[0]

tests/test_git_superproject.py

@@ -542,14 +542,15 @@ class SuperprojectTestCase(unittest.TestCase):
             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:
+                with mock.patch.object(
+                    self._superproject, "_GetRef"
+                ) as get_ref:
                     instance = mock_git_command.return_value
                     instance.Wait.return_value = 0
-                    mock_git_refs.side_effect = ["", "1234"]
+                    get_ref.side_effect = ["", "1234"]
 
                     self.assertTrue(self._superproject._Fetch())
+                    get_ref.assert_called_with("refs/heads/main")
                     self.assertEqual(
                         # TODO: Once we require Python 3.8+,
                         #  use 'mock_git_command.call_args.args'.
@@ -572,6 +573,7 @@ class SuperprojectTestCase(unittest.TestCase):
 
                     # If branch for revision exists, set as --negotiation-tip.
                     self.assertTrue(self._superproject._Fetch())
+                    get_ref.assert_called_with("refs/heads/main")
                     self.assertEqual(
                         # TODO: Once we require Python 3.8+,
                         #  use 'mock_git_command.call_args.args'.
@@ -593,3 +595,21 @@ class SuperprojectTestCase(unittest.TestCase):
                             ],
                         ),
                     )
+
+    def test_GetRef_resolves_only_the_requested_ref(self) -> None:
+        command = mock.MagicMock(stdout="1234\n")
+        command.Wait.return_value = 0
+        with mock.patch(
+            "git_superproject.GitCommand", return_value=command
+        ) as git_command:
+            self.assertEqual("1234", self._superproject._GetRef("HEAD"))
+
+        git_command.assert_called_once_with(
+            None,
+            ["rev-parse", "--verify", "--quiet", "HEAD"],
+            gitdir=self._superproject._work_git,
+            bare=True,
+            capture_stdout=True,
+            capture_stderr=True,
+            log_as_error=False,
+        )

tests/test_git_trace2_event_log.py

@@ -33,7 +33,7 @@ import platform_utils
 
 def server_logging_thread(
     socket_path: str,
-    server_ready: threading.Condition,
+    server_ready: threading.Event,
     received_traces: List[str],
 ) -> None:
     """Helper function to receive logs over a Unix domain socket.
@@ -43,8 +43,7 @@ def server_logging_thread(
 
     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
+        server_ready: event set when the server is ready to accept connections
         received_traces: a list to which received traces will be appended (after
             decoding to a utf-8 string).
     """
@@ -53,8 +52,7 @@ def server_logging_thread(
     with socket.socket(socket.AF_UNIX, socket.SOCK_STREAM) as sock:
         sock.bind(socket_path)
         sock.listen(0)
-        with server_ready:
-            server_ready.notify()
+        server_ready.set()
         with sock.accept()[0] as conn:
             while True:
                 recved = conn.recv(4096)
@@ -315,6 +313,7 @@ def test_data_event_config(event_log: git_trace2_event_log.EventLog) -> None:
         "repo.partialclone": "false",
         "repo.syncstate.superproject.hassuperprojecttag": "true",
         "repo.syncstate.superproject.sys.argv": ["--", "sync", "protobuf"],
+        "repo.syncstate.emptykey": "",
     }
     prefix_value = "prefix"
     event_log.LogDataConfigEvents(config, prefix_value)
@@ -323,7 +322,7 @@ def test_data_event_config(event_log: git_trace2_event_log.EventLog) -> None:
         log_path = event_log.Write(path=tempdir)
         log_data = read_log(log_path)
 
-    assert len(log_data) == 5
+    assert len(log_data) == 6
     data_events = log_data[1:]
     verify_common_keys(log_data[0], expected_event_name="version")
 
@@ -403,7 +402,7 @@ def test_write_socket(event_log: git_trace2_event_log.EventLog) -> None:
     received_traces: List[str] = []
     with tempfile.TemporaryDirectory(prefix="test_server_sockets") as tempdir:
         socket_path = os.path.join(tempdir, "server.sock")
-        server_ready = threading.Condition()
+        server_ready = threading.Event()
         # Start "server" listening on Unix domain socket at socket_path.
         server_thread = threading.Thread(
             target=server_logging_thread,
@@ -411,9 +410,7 @@ def test_write_socket(event_log: git_trace2_event_log.EventLog) -> None:
         )
         try:
             server_thread.start()
-
-            with server_ready:
-                server_ready.wait(timeout=120)
+            server_ready.wait(timeout=120)
 
             event_log.StartEvent([])
             path = event_log.Write(path=f"af_unix:{socket_path}")

tests/test_hooks.py

@@ -15,6 +15,7 @@
 """Unittests for the hooks.py module."""
 
 from io import StringIO
+from pathlib import Path
 import sys
 
 import pytest
@@ -105,3 +106,98 @@ def test_post_sync_argument_validation() -> None:
 
     finally:
         sys.stderr = old_stderr
+
+
+@pytest.mark.parametrize("yes_val", (True, False))
+def test_repo_upload_yes_arg(tmp_path: Path, yes_val: bool) -> None:
+    """Test that yes is passed in kwargs during hook execution."""
+
+    class FakeProject:
+        def __init__(self, worktree: str) -> None:
+            self.worktree = worktree
+            self.enabled_repo_hooks = ["pre-upload"]
+            self.config = None
+
+    hook_file = tmp_path / "pre-upload.py"
+
+    hook_content = """
+def main(project_list, **kwargs):
+    project_list.append(kwargs.get("yes"))
+"""
+    hook_file.write_text(hook_content)
+
+    hook = hooks.RepoHook(
+        hook_type="pre-upload",
+        hooks_project=FakeProject(str(tmp_path)),
+        repo_topdir=str(tmp_path),
+        manifest_url="https://gerrit",
+        allow_all_hooks=True,
+        yes=yes_val,
+    )
+
+    project_list = []
+    res = hook.Run(project_list=project_list, worktree_list=[])
+
+    assert res is True
+    assert project_list == [yes_val]
+
+
+@pytest.mark.parametrize("fix_val", (True, False))
+def test_repo_upload_fix_arg(tmp_path: Path, fix_val: bool) -> None:
+    """Test that fix is passed in kwargs during hook execution."""
+
+    class FakeProject:
+        def __init__(self, worktree: str) -> None:
+            self.worktree = worktree
+            self.enabled_repo_hooks = ["pre-upload"]
+            self.config = None
+
+    hook_file = tmp_path / "pre-upload.py"
+
+    hook_content = """
+def main(project_list, **kwargs):
+    project_list.append(kwargs.get("fix"))
+"""
+    hook_file.write_text(hook_content)
+
+    hook = hooks.RepoHook(
+        hook_type="pre-upload",
+        hooks_project=FakeProject(str(tmp_path)),
+        repo_topdir=str(tmp_path),
+        manifest_url="https://gerrit",
+        allow_all_hooks=True,
+        fix=fix_val,
+    )
+
+    project_list = []
+    res = hook.Run(project_list=project_list, worktree_list=[])
+
+    assert res is True
+    assert project_list == [fix_val]
+
+
+def test_from_subcmd_without_fix_option() -> None:
+    """Test that FromSubcmd works when opt does not have fix attribute."""
+
+    class Remote:
+        url = "https://gerrit"
+
+    class FakeManifest:
+        repo_hooks_project = None
+        topdir = "/fake/topdir"
+
+        class manifestProject:
+            @staticmethod
+            def GetRemote(name: str) -> "Remote":
+                return Remote()
+
+        class contactinfo:
+            bugurl = "https://bugs"
+
+    class FakeOpt:
+        bypass_hooks = False
+        allow_all_hooks = False
+        ignore_hooks = False
+
+    hook = hooks.RepoHook.FromSubcmd(FakeManifest(), FakeOpt(), "post-sync")
+    assert hook._fix is False

tests/test_manifest_xml.py

@@ -819,6 +819,26 @@ class TestProjectElement:
                 str(repo_client.topdir), ".repo", "projects", "..git"
             )
 
+    def test_get_project_paths_local_gitdirs(
+        self, repo_client: RepoClient
+    ) -> None:
+        """Check GetProjectPaths with UseLocalGitDirs."""
+        manifest = repo_client.get_xml_manifest(
+            '<?xml version="1.0" encoding="UTF-8"?><manifest></manifest>'
+        )
+        manifest.manifestProject.config.SetBoolean("repo.uselocalgitdirs", True)
+
+        relpath, worktree, gitdir, objdir, use_git_worktrees = (
+            manifest.GetProjectPaths("foo", "bar", "origin")
+        )
+
+        assert os.path.normpath(gitdir) == os.path.normpath(
+            os.path.join(str(repo_client.topdir), "bar", ".git")
+        )
+        assert os.path.normpath(objdir) == os.path.normpath(
+            os.path.join(str(repo_client.topdir), "bar", ".git")
+        )
+
     def test_bad_path_name_checks(self, repo_client: RepoClient) -> None:
         """Check handling of bad path & name attributes."""
 

tests/test_release_update_manpages.py

@@ -0,0 +1,43 @@
+# Copyright (C) 2026 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.
+
+"""Tests for the release/update-manpages wrapper."""
+
+import runpy
+import sys
+from types import ModuleType
+
+import pytest
+import utils_for_test
+
+
+UPDATE_MANPAGES_SCRIPT = (
+    utils_for_test.THIS_DIR.parent / "release" / "update-manpages"
+)
+
+
+def test_wrapper_does_not_run_main_for_multiprocessing_child(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """Do not rerun main when multiprocessing re-executes the wrapper."""
+    fake_update_manpages = ModuleType("update_manpages")
+
+    # Mock this because the real module requires newer Python versions than
+    # our unittest framework does.
+    monkeypatch.setitem(sys.modules, "update_manpages", fake_update_manpages)
+
+    runpy.run_path(
+        str(UPDATE_MANPAGES_SCRIPT),
+        run_name="__mp_main__",
+    )

tests/test_subcmds_cherry_pick.py

@@ -0,0 +1,85 @@
+# Copyright (C) 2026 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 subcmds/cherry_pick.py."""
+
+from unittest import mock
+
+import pytest
+
+from error import GitError
+from git_command import GitCommand
+from subcmds import cherry_pick
+
+
+def test_resolve_reference_uses_one_typed_batch_request(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    oid = "1" * 40
+    commit = "tree " + "2" * 40 + "\n\nSubject 🚀\n\nBody\n"
+    output = oid + " commit " + str(len(commit.encode("utf-8"))) + "\n"
+    output += commit + "\n"
+    command = mock.create_autospec(GitCommand, instance=True)
+    command.stdout = output
+    command.stderr = ""
+    command.Wait.return_value = 0
+    run_git = mock.create_autospec(GitCommand, return_value=command)
+    monkeypatch.setattr(cherry_pick, "GitCommand", run_git)
+
+    resolved, contents = cherry_pick.CherryPick()._ResolveReference("topic")
+
+    assert resolved == oid
+    assert contents == commit
+    run_git.assert_called_once_with(
+        None,
+        ["cat-file", "--batch"],
+        input="topic^{commit}\n",
+        capture_stdout=True,
+        capture_stderr=True,
+        verify_command=True,
+    )
+
+
+def test_resolve_reference_rejects_missing_object(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    command = mock.create_autospec(GitCommand, instance=True)
+    command.stdout = "topic^{commit} missing\n"
+    command.stderr = ""
+    command.Wait.return_value = 0
+    monkeypatch.setattr(
+        cherry_pick,
+        "GitCommand",
+        mock.create_autospec(GitCommand, return_value=command),
+    )
+
+    with pytest.raises(GitError, match="commit topic not found"):
+        cherry_pick.CherryPick()._ResolveReference("topic")
+
+
+def test_resolve_reference_rejects_ambiguous_object(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    command = mock.create_autospec(GitCommand, instance=True)
+    command.stdout = "topic^{commit} ambiguous\n"
+    command.stderr = ""
+    command.Wait.return_value = 0
+    monkeypatch.setattr(
+        cherry_pick,
+        "GitCommand",
+        mock.create_autospec(GitCommand, return_value=command),
+    )
+
+    with pytest.raises(GitError, match="commit topic not found"):
+        cherry_pick.CherryPick()._ResolveReference("topic")

tests/test_subcmds_forall.py

@@ -19,10 +19,10 @@ import io
 from pathlib import Path
 from unittest import mock
 
+import pytest
 import utils_for_test
 
 import manifest_xml
-import project
 import subcmds
 
 
@@ -87,13 +87,16 @@ def test_forall_all_projects_called_once(tmp_path: Path) -> None:
     opts, args = cmd.OptionParser.parse_args(["-c", "echo $REPO_PROJECT"])
     opts.verbose = False
 
+    # Set revisionId directly so GetRevisionId() short-circuits without
+    # touching git.  Using mock.patch.object on the class does not work
+    # with Python 3.14+, which defaults to "forkserver" on Linux —
+    # class-level patches do not survive into forkserver worker processes.
+    for proj in manifest.projects:
+        proj.revisionId = "refs/heads/main"
+
     with contextlib.redirect_stdout(io.StringIO()) as stdout:
-        # 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)
+        # Run the forall command.
+        cmd.Execute(opts, args)
 
     output = stdout.getvalue()
     # Verify that we got every project name in the output.
@@ -104,3 +107,57 @@ def test_forall_all_projects_called_once(tmp_path: Path) -> None:
     line_count = sum(1 for x in output.splitlines() if x)
     # Verify that we didn't get more lines than expected.
     assert line_count == 8
+
+
+@pytest.mark.parametrize(
+    ("regex_option", "inverse"),
+    [
+        ("-r", False),
+        ("-i", True),
+    ],
+    ids=("regex", "inverse-regex"),
+)
+def test_forall_regex_modes_pass_groups_to_find_projects(
+    tmp_path: Path,
+    regex_option: str,
+    inverse: bool,
+) -> None:
+    """Pass --groups through in regex modes."""
+    manifest = _create_manifest_with_8_projects(tmp_path)
+
+    cmd = subcmds.forall.Forall()
+    cmd.manifest = manifest
+
+    opts, args = cmd.OptionParser.parse_args(
+        [
+            regex_option,
+            "--groups",
+            "special",
+            "project",
+            "-c",
+            "true",
+        ]
+    )
+
+    with mock.patch.object(
+        cmd,
+        "FindProjects",
+        return_value=[],
+    ) as find_projects, mock.patch.object(
+        cmd,
+        "ExecuteInParallel",
+        return_value=0,
+    ):
+        cmd.Execute(opts, args)
+
+    expected_kwargs = {
+        "groups": "special",
+        "all_manifests": True,
+    }
+    if inverse:
+        expected_kwargs["inverse"] = True
+
+    find_projects.assert_called_once_with(
+        ["project"],
+        **expected_kwargs,
+    )

tests/test_subcmds_gc.py

@@ -24,7 +24,7 @@ class GcCommand(unittest.TestCase):
     """Tests for gc command."""
 
     def setUp(self):
-        self.cmd = gc.Gc()
+        self.cmd = gc.Gc(manifest=mock.MagicMock())
         self.opt, self.args = self.cmd.OptionParser.parse_args([])
         self.opt.this_manifest_only = False
         self.opt.repack = False

tests/test_subcmds_info.py

@@ -199,3 +199,171 @@ def test_text_enables_pager() -> None:
     cmd = _get_cmd()
     opts, _ = cmd.OptionParser.parse_args([])
     assert cmd.WantPager(opts)
+
+
+def test_get_project_data_uses_head_revision() -> None:
+    """_getProjectData should use GetHeadRevisionId if available."""
+    cmd = _get_cmd()
+    project = mock.MagicMock()
+    project.name = "foo"
+    project.worktree = "/path/to/foo"
+    project.revisionExpr = "refs/heads/main"
+    project.GetBranches.return_value = {}
+
+    # GetHeadRevisionId() returns a SHA, it should be used.
+    project.GetHeadRevisionId.return_value = "head_sha_12345"
+    project.GetRevisionId.return_value = "manifest_sha_54321"
+
+    data = cmd._getProjectData(project)
+    assert data["current_revision"] == "head_sha_12345"
+    project.GetHeadRevisionId.assert_called_once()
+
+    # GetHeadRevisionId() is None, fall back to GetRevisionId().
+    project.GetHeadRevisionId.reset_mock()
+    project.GetHeadRevisionId.return_value = None
+    data = cmd._getProjectData(project)
+    assert data["current_revision"] == "manifest_sha_54321"
+
+
+def test_json_with_projects(capsys) -> None:
+    """--format=json should emit project data."""
+    cmd = _get_cmd()
+    opts, args = cmd.OptionParser.parse_args(["--format=json"])
+    opts.jobs = 1  # To avoid multiprocessing pickle issues with mocks
+
+    project = mock.MagicMock()
+    project.name = "foo"
+    project.worktree = "/path/to/foo"
+    project.revisionExpr = "refs/heads/main"
+    branch = mock.MagicMock()
+    branch.current = True
+    project.GetBranches.return_value = {"branch1": branch}
+    project.GetHeadRevisionId.return_value = "head_sha_12345"
+    project.CurrentBranch = "branch1"
+
+    cmd.GetProjects = mock.MagicMock(return_value=[project])
+
+    cmd.Execute(opts, args)
+
+    data = json.loads(capsys.readouterr().out)
+    assert "projects" in data
+    assert len(data["projects"]) == 1
+    project_data = data["projects"][0]
+    assert project_data["name"] == "foo"
+    assert project_data["mount_path"] == "/path/to/foo"
+    assert project_data["current_revision"] == "head_sha_12345"
+    assert project_data["manifest_revision"] == "refs/heads/main"
+    assert project_data["local_branches"] == ["branch1"]
+    assert project_data["current_branch"] == "branch1"
+
+
+def test_diff_commits_uses_one_left_right_walk() -> None:
+    """Local and remote commits are partitioned from one rev-list."""
+    project = mock.MagicMock()
+    project.work_git.rev_list.return_value = [
+        "<11111111 local commit",
+        ">22222222 remote commit",
+    ]
+
+    local, remote = info.Info._GetDiffCommits(project, "refs/remotes/m/main")
+
+    assert local == ["11111111 local commit"]
+    assert remote == ["22222222 remote commit"]
+    project.work_git.rev_list.assert_called_once_with(
+        "--left-right",
+        "--abbrev=8",
+        "--abbrev-commit",
+        "--pretty=oneline",
+        "HEAD...refs/remotes/m/main",
+        "--",
+    )
+
+
+def test_diff_commits_falls_back_to_bare_git_when_no_worktree() -> None:
+    """Bare or worktree-less projects fall back to bare_git for history walk."""
+    project = mock.MagicMock()
+    project.work_git = None
+    project.bare_git.rev_list.return_value = [
+        "<11111111 local commit",
+        ">22222222 remote commit",
+    ]
+
+    local, remote = info.Info._GetDiffCommits(project, "refs/remotes/m/main")
+
+    assert local == ["11111111 local commit"]
+    assert remote == ["22222222 remote commit"]
+    project.bare_git.rev_list.assert_called_once_with(
+        "--left-right",
+        "--abbrev=8",
+        "--abbrev-commit",
+        "--pretty=oneline",
+        "HEAD...refs/remotes/m/main",
+        "--",
+    )
+
+
+def test_diff_commits_empty_output() -> None:
+    """Empty rev-list output produces empty local and remote commit lists."""
+    project = mock.MagicMock()
+    project.work_git.rev_list.return_value = []
+
+    local, remote = info.Info._GetDiffCommits(project, "refs/remotes/m/main")
+
+    assert local == []
+    assert remote == []
+
+
+def test_get_current_branch() -> None:
+    """_GetCurrentBranch identifies the branch with current=True."""
+    b1 = mock.MagicMock(current=False)
+    b2 = mock.MagicMock(current=True)
+    assert info.Info._GetCurrentBranch({"b1": b1, "b2": b2}) == "b2"
+    assert info.Info._GetCurrentBranch({"b1": b1}) is None
+    assert info.Info._GetCurrentBranch({}) is None
+
+
+def test_overview_helper_current_branch_filters_before_uploadable(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """_OverviewHelper only checks uploadable state for the current branch."""
+    project = mock.MagicMock()
+    project.RelPath.return_value = "proj"
+    b1 = mock.MagicMock(current=False)
+    b2 = mock.MagicMock(current=True)
+    project.GetBranches.return_value = {"b1": b1, "b2": b2}
+    uploadable = mock.MagicMock(commits=["c1"], date="2026-09-21")
+    uploadable.name = "b2"
+    project.GetUploadableBranch.return_value = uploadable
+    monkeypatch.setattr(
+        info.Info,
+        "get_parallel_context",
+        lambda: {"projects": [project]},
+    )
+    opt = mock.MagicMock(current_branch=True, this_manifest_only=False)
+
+    result = info.Info._OverviewHelper(0, opt)
+
+    project.GetUploadableBranch.assert_called_once_with("b2")
+    assert len(result) == 1
+    assert result[0].name == "b2"
+    assert result[0].is_current is True
+
+
+def test_overview_helper_current_branch_detached_head_skips_uploadable(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """_OverviewHelper skips GetUploadableBranch when detached with -b."""
+    project = mock.MagicMock()
+    b1 = mock.MagicMock(current=False)
+    project.GetBranches.return_value = {"b1": b1}
+    monkeypatch.setattr(
+        info.Info,
+        "get_parallel_context",
+        lambda: {"projects": [project]},
+    )
+    opt = mock.MagicMock(current_branch=True, this_manifest_only=False)
+
+    result = info.Info._OverviewHelper(0, opt)
+
+    project.GetUploadableBranch.assert_not_called()
+    assert result == []

tests/test_subcmds_list.py

@@ -0,0 +1,57 @@
+# Copyright (C) 2026 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 list subcmd."""
+
+from typing import List, Optional
+from unittest import mock
+
+import pytest
+
+import subcmds
+
+
+@pytest.mark.parametrize(
+    ("extra_args", "expected_groups", "expected_missing_ok"),
+    [
+        (["--groups", "special"], "special", None),
+        (["--all"], None, True),
+    ],
+    ids=("groups", "all"),
+)
+def test_list_regex_passes_groups_and_all(
+    extra_args: List[str],
+    expected_groups: Optional[str],
+    expected_missing_ok: Optional[bool],
+) -> None:
+    """Pass --groups and --all through in regex mode."""
+    cmd = subcmds.list.List()
+
+    opts, args = cmd.OptionParser.parse_args(
+        ["--regex", *extra_args, "project"]
+    )
+
+    with mock.patch.object(
+        cmd,
+        "FindProjects",
+        return_value=[],
+    ) as find_projects:
+        cmd.Execute(opts, args)
+
+    find_projects.assert_called_once_with(
+        ["project"],
+        groups=expected_groups,
+        missing_ok=expected_missing_ok,
+        all_manifests=True,
+    )

tests/test_subcmds_rebase.py

@@ -0,0 +1,91 @@
+# Copyright (C) 2026 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/rebase.py module."""
+
+import contextlib
+import io
+from types import SimpleNamespace
+from unittest import mock
+
+from error import GitError
+from subcmds import rebase
+
+
+def test_resolve_onto_manifest_success() -> None:
+    """Test _ResolveOntoManifest when ToLocal succeeds."""
+    project = mock.MagicMock()
+    project.revisionExpr = "main"
+
+    remote = mock.MagicMock()
+    remote.ToLocal.return_value = "refs/remotes/goog/main"
+    project.GetRemote.return_value = remote
+
+    res = rebase._ResolveOntoManifest(project)
+    assert res == "refs/remotes/goog/main"
+    project.GetRemote.assert_called_once()
+    remote.ToLocal.assert_called_once_with("main")
+
+
+def test_resolve_onto_manifest_fallback() -> None:
+    """Test _ResolveOntoManifest when ToLocal raises GitError."""
+    project = mock.MagicMock()
+    project.revisionExpr = "main"
+
+    remote = mock.MagicMock()
+    remote.ToLocal.side_effect = GitError("Failed to resolve")
+    project.GetRemote.return_value = remote
+
+    res = rebase._ResolveOntoManifest(project)
+    assert res == "main"
+    project.GetRemote.assert_called_once()
+    remote.ToLocal.assert_called_once_with("main")
+
+
+def test_execute_delegates_autostash_to_rebase() -> None:
+    """--auto-stash is one rebase process, including staged-only changes."""
+    cmd = rebase.Rebase()
+    cmd.manifest = mock.MagicMock()
+    cmd.git_event_log = mock.MagicMock()
+    project = mock.MagicMock()
+    project.CurrentBranch = "topic"
+    project.RelPath.return_value = "project"
+    branch = mock.MagicMock()
+    branch.LocalMerge = "refs/remotes/origin/main"
+    project.GetBranch.return_value = branch
+    cmd.GetProjects = mock.MagicMock(return_value=[project])
+    opt = SimpleNamespace(
+        interactive=False,
+        fail_fast=False,
+        whitespace=None,
+        quiet=False,
+        force_rebase=False,
+        ff=True,
+        autosquash=False,
+        auto_stash=True,
+        onto_manifest=False,
+        this_manifest_only=False,
+    )
+    git_command = mock.MagicMock()
+    git_command.Wait.return_value = 0
+
+    with mock.patch.object(
+        rebase, "GitCommand", return_value=git_command
+    ) as run_git, contextlib.redirect_stdout(io.StringIO()):
+        assert cmd.Execute(opt, []) == 0
+
+    run_git.assert_called_once_with(
+        project,
+        ["rebase", "--autostash", "refs/remotes/origin/main"],
+    )

tests/test_subcmds_status.py

@@ -107,6 +107,18 @@ def _assert_project_header(line: str, project_path: str, branch: str) -> None:
     assert line == expected
 
 
+def _assert_project_header_with_ahead_behind(
+    line: str,
+    project_path: str,
+    branch: str,
+    ahead_behind: str,
+) -> None:
+    """Assert a status project header line includes ahead/behind info."""
+    suffix = f"branch {branch}{ahead_behind}"
+    expected = f"project {(project_path + '/ '):<40}{suffix}"
+    assert line == expected
+
+
 def _assert_orphan_block(lines: List[str], expected: List[str]) -> None:
     """Assert orphan block header and entries, independent of entry ordering."""
     assert lines
@@ -173,6 +185,96 @@ def test_status_without_orphans(
     assert lines[1] == " -m\tREADME"
 
 
+def test_status_staged_and_unstaged_same_path(
+    repo_client_checkout: Tuple[Path, manifest_xml.XmlManifest],
+) -> None:
+    """A path changed on both sides of the index renders both states."""
+    topdir, manifest = repo_client_checkout
+    project_path = next(iter(manifest.paths.keys()))
+    project_worktree = topdir / project_path
+    readme = project_worktree / "README"
+    readme.write_text("staged")
+    subprocess.check_call(["git", "add", "README"], cwd=project_worktree)
+    readme.write_text("unstaged")
+
+    with contextlib.redirect_stdout(io.StringIO()) as stdout:
+        _run_status(manifest, [])
+
+    lines = _status_lines(stdout.getvalue())
+    assert lines[1] == " Mm\tREADME"
+
+
+def test_status_forces_staged_rename_detection(
+    repo_client_checkout: Tuple[Path, manifest_xml.XmlManifest],
+) -> None:
+    """The snapshot preserves rename scores despite user status config."""
+    topdir, manifest = repo_client_checkout
+    project_path = next(iter(manifest.paths.keys()))
+    project_worktree = topdir / project_path
+    subprocess.check_call(
+        ["git", "config", "status.renames", "false"], cwd=project_worktree
+    )
+    subprocess.check_call(
+        ["git", "mv", "README", "RENAMED"], cwd=project_worktree
+    )
+
+    with contextlib.redirect_stdout(io.StringIO()) as stdout:
+        _run_status(manifest, [])
+
+    lines = _status_lines(stdout.getvalue())
+    assert lines[1] == " R-\tREADME => RENAMED (100%)"
+
+
+def test_detached_clean_status_is_suppressed(
+    repo_client_checkout: Tuple[Path, manifest_xml.XmlManifest],
+) -> None:
+    """A clean detached checkout keeps returning CLEAN without output."""
+    topdir, manifest = repo_client_checkout
+    project_path = next(iter(manifest.paths.keys()))
+    subprocess.check_call(
+        ["git", "checkout", "-q", "--detach", "HEAD"],
+        cwd=topdir / project_path,
+    )
+
+    with contextlib.redirect_stdout(io.StringIO()) as stdout:
+        _run_status(manifest, [])
+
+    assert _status_lines(stdout.getvalue()) == [
+        "nothing to commit (working directory clean)"
+    ]
+
+
+def test_status_unmerged_path_matches_legacy_display(
+    repo_client_checkout: Tuple[Path, manifest_xml.XmlManifest],
+) -> None:
+    """Porcelain-v2 unmerged records render as index U and worktree u."""
+    topdir, manifest = repo_client_checkout
+    project_path = next(iter(manifest.paths.keys()))
+    worktree = topdir / project_path
+    subprocess.check_call(
+        ["git", "checkout", "-q", "-b", "other"], cwd=worktree
+    )
+    (worktree / "README").write_text("other")
+    subprocess.check_call(["git", "commit", "-qam", "other"], cwd=worktree)
+    subprocess.check_call(["git", "checkout", "-q", "main"], cwd=worktree)
+    (worktree / "README").write_text("main")
+    subprocess.check_call(["git", "commit", "-qam", "main"], cwd=worktree)
+    merge = subprocess.run(
+        ["git", "merge", "other"],
+        cwd=worktree,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        check=False,
+    )
+    assert merge.returncode != 0
+
+    with contextlib.redirect_stdout(io.StringIO()) as stdout:
+        _run_status(manifest, [])
+
+    lines = _status_lines(stdout.getvalue())
+    assert lines[1] == " Uu\tREADME"
+
+
 def test_status_with_orphans_and_modified_file(
     repo_client_checkout: Tuple[Path, manifest_xml.XmlManifest],
 ) -> None:
@@ -218,3 +320,245 @@ def test_empty_status_after_start_shows_started_branch(
     lines = _status_lines(stdout.getvalue())
     assert len(lines) == 1
     _assert_project_header(lines[0], project_path, started_branch)
+
+
+def _setup_remote_tracking_branch(
+    manifest: manifest_xml.XmlManifest,
+    branch_name: str,
+) -> None:
+    """Create a branch tracking a remote ref, like ``repo start``.
+
+    In a real repo checkout, ``repo start`` creates a branch that
+    tracks a remote tracking ref (e.g. refs/remotes/origin/main).
+    This sets up the same config in both the worktree and the
+    project gitdir (where repo reads its config from).
+    """
+    proj = list(manifest.paths.values())[0]
+    worktree = Path(proj.worktree)
+    proj_gitdir = Path(proj.gitdir)
+
+    # Create the remote tracking ref in the worktree.
+    subprocess.check_call(
+        ["git", "update-ref", "refs/remotes/origin/main", "main"],
+        cwd=worktree,
+    )
+    # Create the new branch from main in the worktree.
+    subprocess.check_call(
+        ["git", "checkout", "-q", "-b", branch_name, "main"],
+        cwd=worktree,
+    )
+    # Write remote and branch config into the *project gitdir* config,
+    # which is where repo's Project.config reads from.
+    cfg = str(proj_gitdir / "config")
+    subprocess.check_call(
+        [
+            "git",
+            "config",
+            "-f",
+            cfg,
+            "remote.origin.url",
+            "http://localhost/fake",
+        ],
+    )
+    subprocess.check_call(
+        [
+            "git",
+            "config",
+            "-f",
+            cfg,
+            "remote.origin.fetch",
+            "+refs/heads/*:refs/remotes/origin/*",
+        ],
+    )
+    subprocess.check_call(
+        ["git", "config", "-f", cfg, f"branch.{branch_name}.remote", "origin"],
+    )
+    subprocess.check_call(
+        [
+            "git",
+            "config",
+            "-f",
+            cfg,
+            f"branch.{branch_name}.merge",
+            "refs/heads/main",
+        ],
+    )
+
+
+def test_status_branch_ahead_of_upstream(
+    repo_client_checkout: Tuple[Path, manifest_xml.XmlManifest],
+) -> None:
+    """Verify status shows [ahead N] for local commits."""
+    topdir, manifest = repo_client_checkout
+    project_path = next(iter(manifest.paths.keys()))
+    project_worktree = topdir / project_path
+
+    _setup_remote_tracking_branch(manifest, "feature")
+    subprocess.check_call(
+        ["git", "config", "status.aheadBehind", "false"],
+        cwd=project_worktree,
+    )
+    subprocess.check_call(
+        ["git", "commit", "-q", "--allow-empty", "-m", "c1"],
+        cwd=project_worktree,
+    )
+    subprocess.check_call(
+        ["git", "commit", "-q", "--allow-empty", "-m", "c2"],
+        cwd=project_worktree,
+    )
+
+    with contextlib.redirect_stdout(io.StringIO()) as stdout:
+        _run_status(manifest, [])
+
+    lines = _status_lines(stdout.getvalue())
+    assert len(lines) == 1
+    _assert_project_header_with_ahead_behind(
+        lines[0], project_path, "feature", " [ahead 2]"
+    )
+
+
+def test_status_branch_behind_upstream(
+    repo_client_checkout: Tuple[Path, manifest_xml.XmlManifest],
+) -> None:
+    """Verify status shows [behind N] when upstream is ahead."""
+    topdir, manifest = repo_client_checkout
+    project_path = next(iter(manifest.paths.keys()))
+    project_worktree = topdir / project_path
+
+    _setup_remote_tracking_branch(manifest, "feature")
+    # Advance the remote tracking ref past the feature branch.
+    subprocess.check_call(
+        ["git", "checkout", "-q", "main"], cwd=project_worktree
+    )
+    subprocess.check_call(
+        ["git", "commit", "-q", "--allow-empty", "-m", "upstream"],
+        cwd=project_worktree,
+    )
+    subprocess.check_call(
+        ["git", "update-ref", "refs/remotes/origin/main", "main"],
+        cwd=project_worktree,
+    )
+    subprocess.check_call(
+        ["git", "checkout", "-q", "feature"],
+        cwd=project_worktree,
+    )
+
+    with contextlib.redirect_stdout(io.StringIO()) as stdout:
+        _run_status(manifest, [])
+
+    lines = _status_lines(stdout.getvalue())
+    assert len(lines) == 1
+    _assert_project_header_with_ahead_behind(
+        lines[0], project_path, "feature", " [behind 1]"
+    )
+
+
+def test_status_branch_ahead_and_behind(
+    repo_client_checkout: Tuple[Path, manifest_xml.XmlManifest],
+) -> None:
+    """Verify [ahead N, behind M] when branch has diverged."""
+    topdir, manifest = repo_client_checkout
+    project_path = next(iter(manifest.paths.keys()))
+    project_worktree = topdir / project_path
+
+    _setup_remote_tracking_branch(manifest, "feature")
+    # Add a local commit on feature.
+    subprocess.check_call(
+        ["git", "commit", "-q", "--allow-empty", "-m", "local"],
+        cwd=project_worktree,
+    )
+    # Advance the remote tracking ref independently.
+    subprocess.check_call(
+        ["git", "checkout", "-q", "main"], cwd=project_worktree
+    )
+    subprocess.check_call(
+        ["git", "commit", "-q", "--allow-empty", "-m", "upstream"],
+        cwd=project_worktree,
+    )
+    subprocess.check_call(
+        ["git", "update-ref", "refs/remotes/origin/main", "main"],
+        cwd=project_worktree,
+    )
+    subprocess.check_call(
+        ["git", "checkout", "-q", "feature"],
+        cwd=project_worktree,
+    )
+
+    with contextlib.redirect_stdout(io.StringIO()) as stdout:
+        _run_status(manifest, [])
+
+    lines = _status_lines(stdout.getvalue())
+    assert len(lines) == 1
+    _assert_project_header_with_ahead_behind(
+        lines[0],
+        project_path,
+        "feature",
+        " [ahead 1, behind 1]",
+    )
+
+
+def test_status_branch_no_tracking_no_ahead_behind(
+    repo_client_checkout: Tuple[Path, manifest_xml.XmlManifest],
+) -> None:
+    """Verify no ahead/behind when branch has no upstream."""
+    topdir, manifest = repo_client_checkout
+    project_path = next(iter(manifest.paths.keys()))
+    project_worktree = topdir / project_path
+
+    subprocess.check_call(
+        [
+            "git",
+            "checkout",
+            "-q",
+            "-b",
+            "orphan-branch",
+            "--no-track",
+            "main",
+        ],
+        cwd=project_worktree,
+    )
+    subprocess.check_call(
+        ["git", "commit", "-q", "--allow-empty", "-m", "c1"],
+        cwd=project_worktree,
+    )
+
+    with contextlib.redirect_stdout(io.StringIO()) as stdout:
+        _run_status(manifest, [])
+
+    lines = _status_lines(stdout.getvalue())
+    assert len(lines) == 1
+    _assert_project_header(lines[0], project_path, "orphan-branch")
+
+
+def test_status_branch_synced_no_ahead_behind(
+    repo_client_checkout: Tuple[Path, manifest_xml.XmlManifest],
+) -> None:
+    """Verify no ahead/behind when branch is fully synced."""
+    topdir, manifest = repo_client_checkout
+    project_path = next(iter(manifest.paths.keys()))
+
+    _setup_remote_tracking_branch(manifest, "synced")
+
+    with contextlib.redirect_stdout(io.StringIO()) as stdout:
+        _run_status(manifest, [])
+
+    lines = _status_lines(stdout.getvalue())
+    assert len(lines) == 1
+    _assert_project_header(lines[0], project_path, "synced")
+
+
+def test_status_non_utf8_path(
+    repo_client_checkout: Tuple[Path, manifest_xml.XmlManifest],
+) -> None:
+    """Non-UTF-8 pathnames render without crashing."""
+    topdir, manifest = repo_client_checkout
+    project_path = next(iter(manifest.paths.keys()))
+    project_worktree = topdir / project_path
+    bad_path = project_worktree / os.fsdecode(b"bad-\xff-name")
+    bad_path.write_bytes(b"content")
+
+    with contextlib.redirect_stdout(io.StringIO()) as stdout:
+        _run_status(manifest, [])
+
+    lines = _status_lines(stdout.getvalue())
+    assert any("bad-" in line for line in lines)

tests/test_subcmds_upload.py

@@ -14,6 +14,7 @@
 
 """Unittests for the subcmds/upload.py module."""
 
+from typing import List, Optional
 from unittest import mock
 
 import pytest
@@ -63,3 +64,172 @@ def test_UploadAndReport_UnhandledError(cmd: upload.Upload) -> None:
     with mock.patch.object(cmd, "_UploadBranch", side_effect=UnexpectedError):
         with pytest.raises(UnexpectedError):
             cmd._UploadAndReport(opt, [mock.MagicMock()], _STUB_PEOPLE)
+
+
+def test_GetMergeBranch_explicit_branch(cmd: upload.Upload) -> None:
+    """Verify _GetMergeBranch reads branch.merge for explicit local_branch."""
+    mock_project = mock.MagicMock()
+    mock_branch = mock.MagicMock()
+    mock_branch.merge = "refs/heads/main"
+    mock_project.GetBranch.return_value = mock_branch
+
+    res = cmd._GetMergeBranch(mock_project, local_branch="feature")
+    assert res == "refs/heads/main"
+    mock_project.GetBranch.assert_called_once_with("feature")
+
+
+def test_GetMergeBranch_current_branch(cmd: upload.Upload) -> None:
+    """Verify _GetMergeBranch falls back to project.CurrentBranch."""
+    mock_project = mock.MagicMock()
+    mock_project.CurrentBranch = "auto-cbr"
+    mock_branch = mock.MagicMock()
+    mock_branch.merge = "refs/heads/upstream-main"
+    mock_project.GetBranch.return_value = mock_branch
+
+    res = cmd._GetMergeBranch(mock_project, local_branch=None)
+    assert res == "refs/heads/upstream-main"
+    mock_project.GetBranch.assert_called_once_with("auto-cbr")
+
+
+def test_GetMergeBranch_none_when_no_branch(cmd: upload.Upload) -> None:
+    """Verify _GetMergeBranch returns empty string when detached HEAD."""
+    mock_project = mock.MagicMock()
+    mock_project.CurrentBranch = None
+
+    res = cmd._GetMergeBranch(mock_project, local_branch=None)
+    assert res == ""
+
+
+def test_GatherOne_returns_resolved_current_branch(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """Upload error reporting reuses the branch gathered by the worker."""
+    project = mock.MagicMock()
+    project.CurrentBranch = "topic"
+    branch = mock.sentinel.branch
+    project.GetUploadableBranch.return_value = branch
+    monkeypatch.setattr(
+        upload.Upload,
+        "get_parallel_context",
+        lambda: {"projects": [project]},
+    )
+    opt = mock.MagicMock(current_branch=True)
+
+    assert upload.Upload._GatherOne(opt, 0) == (0, [branch], "topic")
+
+    project.GetUploadableBranch.assert_called_once_with("topic")
+
+
+def _create_mock_branch(
+    name: str = "main",
+    commits: Optional[List[str]] = None,
+    project_relpath: str = "project-a",
+) -> mock.MagicMock:
+    """Helper to construct a mock ReviewableBranch."""
+    branch = mock.MagicMock()
+    branch.name = name
+    branch.commits = commits if commits is not None else ["commit1"]
+
+    project = mock.MagicMock()
+    project.RelPath.return_value = project_relpath
+    branch.project = project
+    return branch
+
+
+def test_MultipleBranches_yes_with_current_branch_flag_bypasses_editor(
+    cmd: upload.Upload,
+) -> None:
+    """_MultipleBranches with --yes and -c flag bypasses editor."""
+    opt, _ = cmd.OptionParser.parse_args(["-c", "-y"])
+    branch1 = _create_mock_branch("b1", project_relpath="p1")
+    branch2 = _create_mock_branch("b2", project_relpath="p2")
+    pending = [(branch1.project, [branch1]), (branch2.project, [branch2])]
+
+    with mock.patch.object(cmd, "_UploadAndReport") as mock_upload, mock.patch(
+        "editor.Editor.EditString"
+    ) as mock_edit:
+        cmd._MultipleBranches(opt, pending, _STUB_PEOPLE)
+        mock_edit.assert_not_called()
+        mock_upload.assert_called_once_with(
+            opt, [branch1, branch2], _STUB_PEOPLE
+        )
+
+
+def test_MultipleBranches_yes_with_cbr_flag_bypasses_editor(
+    cmd: upload.Upload,
+) -> None:
+    """_MultipleBranches with --yes and --cbr flag bypasses editor."""
+    opt, _ = cmd.OptionParser.parse_args(["--cbr", "--yes"])
+    branch1 = _create_mock_branch("b1", project_relpath="p1")
+    branch2 = _create_mock_branch("b2", project_relpath="p2")
+    pending = [(branch1.project, [branch1]), (branch2.project, [branch2])]
+
+    with mock.patch.object(cmd, "_UploadAndReport") as mock_upload, mock.patch(
+        "editor.Editor.EditString"
+    ) as mock_edit:
+        cmd._MultipleBranches(opt, pending, _STUB_PEOPLE)
+        mock_edit.assert_not_called()
+        mock_upload.assert_called_once_with(
+            opt, [branch1, branch2], _STUB_PEOPLE
+        )
+
+
+def test_MultipleBranches_yes_with_branch_flag_bypasses_editor(
+    cmd: upload.Upload,
+) -> None:
+    """_MultipleBranches with --yes and --br flag bypasses editor."""
+    opt, _ = cmd.OptionParser.parse_args(["--br", "feature", "-y"])
+    branch1 = _create_mock_branch("feature", project_relpath="p1")
+    branch2 = _create_mock_branch("feature", project_relpath="p2")
+    pending = [(branch1.project, [branch1]), (branch2.project, [branch2])]
+
+    with mock.patch.object(cmd, "_UploadAndReport") as mock_upload, mock.patch(
+        "editor.Editor.EditString"
+    ) as mock_edit:
+        cmd._MultipleBranches(opt, pending, _STUB_PEOPLE)
+        mock_edit.assert_not_called()
+        mock_upload.assert_called_once_with(
+            opt, [branch1, branch2], _STUB_PEOPLE
+        )
+
+
+def test_MultipleBranches_yes_with_branch_flag_empty_pending_dies(
+    cmd: upload.Upload,
+) -> None:
+    """_MultipleBranches with --yes and empty pending branches dies."""
+    opt, _ = cmd.OptionParser.parse_args(["--br", "feature", "-y"])
+    mock_project = mock.MagicMock()
+    pending = [(mock_project, [])]
+
+    with pytest.raises(
+        upload.UploadExitError, match="nothing ready for upload"
+    ):
+        cmd._MultipleBranches(opt, pending, _STUB_PEOPLE)
+
+
+def test_MultipleBranches_yes_without_branch_or_cbr_uses_editor(
+    cmd: upload.Upload,
+) -> None:
+    """_MultipleBranches with -y but no -c/--br falls back to editor."""
+    opt, _ = cmd.OptionParser.parse_args(["-y"])
+    branch1 = _create_mock_branch("b1", project_relpath="p1")
+    branch1.date = "2026-08-26"
+    mock_remote = mock.MagicMock()
+    branch1.project.dest_branch = None
+    branch1.project.revisionExpr = "refs/heads/main"
+    branch_config = mock.MagicMock()
+    branch_config.remote = mock_remote
+    branch1.project.GetBranch.return_value = branch_config
+    pending = [(branch1.project, [branch1])]
+
+    edited_script = (
+        "project p1/:\n"
+        "  branch b1 ( 1 commit, 2026-08-26) to remote branch "
+        "refs/heads/main:\n"
+    )
+    with mock.patch.object(cmd, "_UploadAndReport") as mock_upload, mock.patch(
+        "editor.Editor.EditString", return_value=edited_script
+    ) as mock_edit:
+        cmd._MultipleBranches(opt, pending, _STUB_PEOPLE)
+        mock_edit.assert_called_once()
+        mock_upload.assert_called_once_with(opt, [branch1], _STUB_PEOPLE)

tests/test_subcmds_version.py

@@ -0,0 +1,52 @@
+# Copyright (C) 2026 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 subcmds/version.py."""
+
+from unittest import mock
+
+import pytest
+
+from subcmds import version
+
+
+def test_repo_version_uses_one_pretty_format_call(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    project = mock.MagicMock()
+    project.bare_git.log.return_value = "v2.0-1-g12345678\nTue, 25 Aug\n"
+    monkeypatch.setattr(version, "git_require", lambda _version: True)
+
+    result = version.Version._RepoVersion(project)
+
+    assert result == ("v2.0-1-g12345678", "Tue, 25 Aug")
+    project.bare_git.log.assert_called_once_with(
+        "-1", "--format=%(describe)%n%cD", "HEAD"
+    )
+    project.bare_git.describe.assert_not_called()
+
+
+def test_repo_version_keeps_old_git_fallback(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    project = mock.MagicMock()
+    project.bare_git.describe.return_value = "v2.0"
+    project.bare_git.log.return_value = "Tue, 25 Aug"
+    monkeypatch.setattr(version, "git_require", lambda _version: False)
+
+    result = version.Version._RepoVersion(project)
+
+    assert result == ("v2.0", "Tue, 25 Aug")
+    project.bare_git.describe.assert_called_once_with("HEAD")
+    project.bare_git.log.assert_called_once_with("-1", "--format=%cD", "HEAD")