sync: Add CLI flag for globally disabling submodule fetch

A global setting for disabling fetching of submodules is useful
since this can currently otherwise only be done by modifying
the manifest, or by explicitly providing projects on command line.

Add this setting as --no-fetch-submodules to mirror the existing
--fetch-submodules.

Change-Id: Ic727c54f11a594aa52315751284b87138cf246bb
Reviewed-on: https://gerrit-review.googlesource.com/c/git-repo/+/607641
Commit-Queue: Josef Malmstrom <Josef.Malmstrom@arm.com>
Reviewed-by: Gavin Mak <gavinmak@google.com>
Tested-by: Josef Malmstrom <Josef.Malmstrom@arm.com>
Reviewed-by: Mike Frysinger <vapier@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 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! "
 
@@ -375,7 +380,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.
@@ -385,7 +390,9 @@ class Command:
             manifest: an XmlManifest, the manifest to use, or None for default.
             groups: a string, the manifest groups in use.
             missing_ok: a boolean, whether to allow missing projects.
-            submodules_ok: a boolean, whether to allow submodules.
+            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,6 +410,11 @@ class Command:
             all_projects_list = manifest.projects
         result = []
 
+        def should_include_submodules(project: "Project") -> bool:
+            if submodules_ok is None:
+                return project.sync_s
+            return submodules_ok
+
         if not groups:
             groups = manifest.GetManifestGroupsStr()
         groups = [x for x in re.split(r"[,\s]+", groups) if x]
@@ -410,7 +422,7 @@ class Command:
         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()
@@ -452,7 +464,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():

completion.zsh

@@ -323,6 +323,7 @@ _repo() {
         '(-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]' \
+        '--no-fetch-submodules[Do not fetch submodules]' \
         '--use-superproject[Use superproject]' \
         '--no-use-superproject[Do not use superproject]' \
         '--tags[Sync tags]' \

docs/fetch-cmd.md

@@ -0,0 +1,63 @@
+# 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.
+
+## 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/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_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,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_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.

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" "June 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 8). 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)
@@ -94,16 +83,17 @@ password to authenticate with the manifest server
 \fB\-\-fetch\-submodules\fR
 fetch submodules from server
 .TP
+\fB\-\-no\-fetch\-submodules\fR
+don't fetch 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 +102,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 +117,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" "July 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 8). 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)
@@ -94,16 +83,17 @@ password to authenticate with the manifest server
 \fB\-\-fetch\-submodules\fR
 fetch submodules from server
 .TP
+\fB\-\-no\-fetch\-submodules\fR
+don't fetch 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 +102,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 +117,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 +215,9 @@ 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\-\-fetch\-submodules\fR option enables fetching Git submodules of all projects
+from the server. The \fB\-\-no\-fetch\-submodules\fR option disables fetching Git
+submodules, even when a project has sync\-s="true" in the manifest.
 .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" "June 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

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(""))
 
@@ -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, [])
@@ -2042,15 +2056,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):

project.py

@@ -28,7 +28,7 @@ import sys
 import tarfile
 import tempfile
 import time
-from typing import List, NamedTuple, Optional
+from typing import Dict, List, NamedTuple, Optional
 import urllib.parse
 
 from color import Coloring
@@ -651,6 +651,51 @@ class Project:
             return self.relpath
         return os.path.join(self.manifest.path_prefix, self.relpath)
 
+    def GetEnvVars(self, local: bool = True) -> Dict[str, str]:
+        """Get project-context environment variables.
+
+        Args:
+            local: If True, REPO_PATH is relative to the local (sub)manifest.
+                If False, it is relative to the outermost manifest.
+
+        Returns:
+            A dictionary mapping environment variable names to their values.
+
+        Environment Variables:
+            See the Environment section in `repo help forall` or
+            `subcmds/forall.py` for details on the available variables.
+            Note that `forall.py` also documents some extra variables that are
+            specific to how the `repo forall` command iterates over projects
+            (e.g., `REPO_COUNT` and `REPO_I`).
+        """
+        env = {}
+
+        def setenv(name, val):
+            if val is None:
+                val = ""
+            env[name] = val
+
+        setenv("REPO_PROJECT", self.name)
+        setenv("REPO_OUTERPATH", self.manifest.path_prefix)
+        setenv("REPO_INNERPATH", self.relpath)
+        setenv("REPO_PATH", self.RelPath(local=local))
+        setenv("REPO_REMOTE", self.remote.name)
+        setenv("REPO_PROJECT_FETCH_URL", self.remote.url)
+
+        try:
+            lrev = "" if self.manifest.IsMirror else self.GetRevisionId()
+        except ManifestInvalidRevisionError:
+            lrev = ""
+        setenv("REPO_LREV", lrev)
+        setenv("REPO_RREV", self.revisionExpr)
+        setenv("REPO_UPSTREAM", self.upstream)
+        setenv("REPO_DEST_BRANCH", self.dest_branch)
+
+        for annotation in self.annotations:
+            setenv(f"REPO__{annotation.name}", annotation.value)
+
+        return env
+
     def SetRevision(self, revisionExpr, revisionId=None):
         """Set revisionId based on revision expression and id"""
         self.revisionExpr = revisionExpr
@@ -951,11 +996,32 @@ class Project:
             out.nl()
             return "DIRTY"
 
-        branch = self.CurrentBranch
-        if branch is None:
+        branch_name = self.CurrentBranch
+        if branch_name is None:
             out.nobranch("(*** NO BRANCH ***)")
         else:
-            out.branch("branch %s", branch)
+            branch_obj = self.GetBranch(branch_name)
+            ahead_behind = ""
+            try:
+                local_merge = branch_obj.LocalMerge
+                if local_merge:
+                    left_right = self.work_git.rev_list(
+                        "--left-right",
+                        "--count",
+                        f"{local_merge}...{R_HEADS}{branch_name}",
+                    )
+                    left, right = left_right[0].split()
+                    behind = int(left)
+                    ahead = int(right)
+                    if ahead and behind:
+                        ahead_behind = f" [ahead {ahead}, behind {behind}]"
+                    elif ahead:
+                        ahead_behind = f" [ahead {ahead}]"
+                    elif behind:
+                        ahead_behind = f" [behind {behind}]"
+            except GitError:
+                pass
+            out.branch("branch %s%s", branch_name, ahead_behind)
         out.nl()
 
         if rb:
@@ -1491,42 +1557,25 @@ class Project:
             depth = None
             clone_filter = clone_filter_for_depth
 
-        # See if we can skip the network fetch entirely.
+        custom_fetch_configured = (
+            self.manifest.manifestProject.use_local_gitdirs
+            and self.manifest.manifestProject.fetch_cmd
+            and not isinstance(self, MetaProject)
+        )
+
         remote_fetched = False
-        if not (
-            optimized_fetch
-            and IsId(self.revisionExpr)
-            and self._CheckForImmutableRevision(
-                use_superproject=use_superproject
-            )
-            and (
-                not depth
-                or os.path.exists(os.path.join(self.gitdir, "shallow"))
-            )
-        ):
+        if custom_fetch_configured:
+            # The custom fetch command is executed unconditionally on every sync
+            # because it is responsible for updating tracking refs and
+            # FETCH_HEAD.
             remote_fetched = True
             try:
-                if not self._RemoteFetch(
-                    initial=is_new,
-                    quiet=quiet,
-                    verbose=verbose,
-                    output_redir=output_redir,
-                    alt_dir=alt_dir,
-                    use_superproject=use_superproject,
-                    current_branch_only=current_branch_only,
-                    tags=tags,
-                    prune=prune,
-                    depth=depth,
-                    submodules=submodules,
-                    force_sync=force_sync,
-                    ssh_proxy=ssh_proxy,
-                    clone_filter=clone_filter,
-                    retry_fetches=retry_fetches,
-                ):
+                if not self._CustomFetch(verbose=verbose):
                     return SyncNetworkHalfResult(
                         remote_fetched,
                         SyncNetworkHalfError(
-                            f"Unable to remote fetch project {self.name}",
+                            f"Unable to fetch project {self.name} using "
+                            "fetchcmd",
                             project=self.name,
                         ),
                     )
@@ -1535,6 +1584,53 @@ class Project:
                     remote_fetched,
                     e,
                 )
+        else:
+            # See if we can skip the standard network fetch entirely.
+            has_shallow = os.path.exists(os.path.join(self.gitdir, "shallow"))
+            skip_fetch = (
+                optimized_fetch
+                and IsId(self.revisionExpr)
+                and self._CheckForImmutableRevision(
+                    use_superproject=use_superproject
+                )
+                and (
+                    has_shallow
+                    or (not depth and not self._SharingProjectHasShallow())
+                )
+            )
+
+            if not skip_fetch:
+                remote_fetched = True
+                try:
+                    if not self._RemoteFetch(
+                        initial=is_new,
+                        quiet=quiet,
+                        verbose=verbose,
+                        output_redir=output_redir,
+                        alt_dir=alt_dir,
+                        use_superproject=use_superproject,
+                        current_branch_only=current_branch_only,
+                        tags=tags,
+                        prune=prune,
+                        depth=depth,
+                        submodules=submodules,
+                        force_sync=force_sync,
+                        ssh_proxy=ssh_proxy,
+                        clone_filter=clone_filter,
+                        retry_fetches=retry_fetches,
+                    ):
+                        return SyncNetworkHalfResult(
+                            remote_fetched,
+                            SyncNetworkHalfError(
+                                f"Unable to remote fetch project {self.name}",
+                                project=self.name,
+                            ),
+                        )
+                except RepoError as e:
+                    return SyncNetworkHalfResult(
+                        remote_fetched,
+                        e,
+                    )
 
         mp = self.manifest.manifestProject
         dissociate = mp.dissociate
@@ -1575,6 +1671,8 @@ class Project:
         self._InitHooks()
 
     def _CopyAndLinkFiles(self):
+        if not self.worktree or not platform_utils.isdir(self.worktree):
+            return
         for copyfile in self.copyfiles:
             copyfile._Copy()
         for linkfile in self.linkfiles:
@@ -1599,6 +1697,18 @@ class Project:
                 f"revision {self.revisionExpr} in {self.name} not found"
             )
 
+    def GetHeadRevisionId(self) -> Optional[str]:
+        """Get the commit revision of the checked out HEAD.
+
+        Returns None if worktree is not checked out or HEAD cannot be resolved.
+        """
+        if self.work_git:
+            try:
+                return self.work_git.rev_parse("HEAD")
+            except GitError:
+                pass
+        return None
+
     def GetRevisionId(self, all_refs=None):
         if self.revisionId:
             return self.revisionId
@@ -1953,28 +2063,51 @@ class Project:
 
         Args:
             verbose: Whether to show verbose messages.
-            force: Always delete tree even if dirty.
+            force: Always delete tree even if dirty or corrupted.
 
         Returns:
             True if the worktree was completely cleaned out.
         """
-        if self.IsDirty():
+        is_dirty = False
+        is_corrupted = False
+        try:
+            is_dirty = self.IsDirty()
+        except GitError:
+            is_corrupted = True
+
+        rel_path = self.RelPath(local=False)
+
+        if is_dirty or is_corrupted:
             if force:
-                logger.warning(
-                    "warning: %s: Removing dirty project: uncommitted changes "
-                    "lost.",
-                    self.RelPath(local=False),
-                )
+                if is_corrupted:
+                    logger.warning(
+                        "warning: %s: Removing corrupted project.",
+                        rel_path,
+                    )
+                else:
+                    logger.warning(
+                        "warning: %s: Removing dirty project: "
+                        "uncommitted changes lost.",
+                        rel_path,
+                    )
             else:
-                msg = (
-                    "error: %s: Cannot remove project: uncommitted "
-                    "changes are present.\n" % self.RelPath(local=False)
-                )
-                logger.error(msg)
-                raise DeleteDirtyWorktreeError(msg, project=self.name)
+                if is_corrupted:
+                    msg = (
+                        f"error: {rel_path}: Cannot remove project: "
+                        "project is corrupted.\n"
+                    )
+                    logger.error(msg)
+                    raise DeleteWorktreeError(msg, project=self.name)
+                else:
+                    msg = (
+                        f"error: {rel_path}: Cannot remove project: "
+                        "uncommitted changes are present.\n"
+                    )
+                    logger.error(msg)
+                    raise DeleteDirtyWorktreeError(msg, project=self.name)
 
         if verbose:
-            print(f"{self.RelPath(local=False)}: Deleting obsolete checkout.")
+            print(f"{rel_path}: Deleting obsolete checkout.")
 
         # Unlock and delink from the main worktree.  We don't use git's worktree
         # remove because it will recursively delete projects -- we handle that
@@ -1982,23 +2115,33 @@ class Project:
         if self.use_git_worktrees:
             needle = os.path.realpath(self.gitdir)
             # Find the git worktree commondir under .repo/worktrees/.
-            output = self.bare_git.worktree("list", "--porcelain").splitlines()[
-                0
-            ]
-            assert output.startswith("worktree "), output
-            commondir = output[9:]
-            # Walk each of the git worktrees to see where they point.
-            configs = os.path.join(commondir, "worktrees")
-            for name in os.listdir(configs):
-                gitdir = os.path.join(configs, name, "gitdir")
-                with open(gitdir) as fp:
-                    relpath = fp.read().strip()
-                # Resolve the checkout path and see if it matches this project.
-                fullpath = os.path.realpath(
-                    os.path.join(configs, name, relpath)
+            try:
+                output = self.bare_git.worktree(
+                    "list", "--porcelain"
+                ).splitlines()[0]
+                assert output.startswith("worktree "), output
+                commondir = output[9:]
+                # Walk each of the git worktrees to see where they point.
+                configs = os.path.join(commondir, "worktrees")
+                if os.path.exists(configs):
+                    for name in os.listdir(configs):
+                        gitdir = os.path.join(configs, name, "gitdir")
+                        with open(gitdir) as fp:
+                            relpath = fp.read().strip()
+                        # Resolve the checkout path and see if it
+                        # matches this project.
+                        fullpath = os.path.realpath(
+                            os.path.join(configs, name, relpath)
+                        )
+                        if fullpath == needle:
+                            platform_utils.rmtree(os.path.join(configs, name))
+            except GitError as e:
+                logger.warning(
+                    "warning: %s: Failed to list worktrees, skipping worktree "
+                    "cleanup: %s",
+                    rel_path,
+                    e,
                 )
-                if fullpath == needle:
-                    platform_utils.rmtree(os.path.join(configs, name))
 
         # Delete the .git directory first, so we're less likely to have a
         # partially working git repository around. There shouldn't be any git
@@ -2019,7 +2162,7 @@ class Project:
                 logger.error(
                     "error: %s: Failed to delete obsolete checkout; remove "
                     "manually, then run `repo sync -l`.",
-                    self.RelPath(local=False),
+                    rel_path,
                 )
                 raise DeleteWorktreeError(aggregate_errors=[e])
 
@@ -2083,7 +2226,7 @@ class Project:
                 logger.error(
                     "%s: Failed to delete obsolete checkout.\n",
                     "       Remove manually, then run `repo sync -l`.",
-                    self.RelPath(local=False),
+                    rel_path,
                 )
                 raise DeleteWorktreeError(aggregate_errors=errors)
 
@@ -2563,6 +2706,23 @@ class Project:
             # There is no such persistent revision. We have to fetch it.
             return False
 
+    def _SharingProjectHasShallow(self) -> bool:
+        """Check if another project sharing this objdir has a "shallow" file.
+
+        If any project sharing this objdir has a shallow file in its gitdir,
+        then the shared objdir may be depth-limited, and every other project
+        sharing this objdir needs its own shallow file so that git knows
+        where history is truncated.
+        """
+        other_projects = self.manifest.GetProjectsWithName(
+            self.name, all_manifests=True
+        )
+        for proj in other_projects:
+            if proj.objdir == self.objdir and proj.gitdir != self.gitdir:
+                if os.path.exists(os.path.join(proj.gitdir, "shallow")):
+                    return True
+        return False
+
     def _FetchArchive(self, tarpath, cwd=None):
         cmd = ["archive", "-v", "-o", tarpath]
         cmd.append("--remote=%s" % self.remote.url)
@@ -2579,6 +2739,114 @@ class Project:
         )
         command.Wait()
 
+    def _CustomFetch(self, verbose=False) -> bool:
+        """Fetch using a custom command specified by repo.fetchcmd.
+
+        Populates the subshell with project-context environment variables,
+        including REPO_TREV (target revision resolved to a commit hash).
+
+        Expects the target commit to be reachable and tracking refs/FETCH_HEAD
+        to be updated upon a successful 0 exit code.
+
+        For a detailed contract, environment variables, and postconditions,
+        see docs/fetch-cmd.md.
+        """
+        # Resolve REPO_TREV (target revision resolved to a full commit hash).
+        repo_trev = None
+        if self.revisionId and IsId(self.revisionId):
+            repo_trev = self.revisionId
+
+        if not repo_trev:
+            output = self._LsRemote(self.upstream or self.revisionExpr)
+            if output:
+                lines = output.splitlines()
+                if lines:
+                    parts = lines[0].split()
+                    if parts:
+                        repo_trev = parts[0]
+
+        if not repo_trev:
+            logger.error("error: Cannot resolve REPO_TREV for %s", self.name)
+            return False
+
+        env = os.environ.copy()
+        env.update(self.GetEnvVars())
+        env["REPO_TREV"] = repo_trev
+        cmd_str = self.manifest.manifestProject.fetch_cmd
+
+        if verbose:
+            print(f"Running fetchcmd: {cmd_str} for {self.name}")
+
+        stdout = None if verbose else subprocess.PIPE
+        stderr = None if verbose else subprocess.PIPE
+        try:
+            p = subprocess.run(
+                cmd_str,
+                shell=True,
+                cwd=self.manifest.topdir,
+                env=env,
+                stdout=stdout,
+                stderr=stderr,
+                text=True,
+            )
+
+            if p.returncode != 0:
+                logger.error(
+                    "error: fetchcmd failed with exit code %d", p.returncode
+                )
+                if not verbose:
+                    logger.error("stderr: %s", p.stderr)
+                return False
+
+        except Exception as e:
+            logger.error("error: Failed to execute fetchcmd: %s", e)
+            return False
+
+        # Verify postconditions.
+        try:
+            self.bare_git.cat_file("-e", repo_trev)
+        except GitError:
+            logger.error(
+                "error: Postcondition failed: %s not found in object store",
+                repo_trev,
+            )
+            return False
+
+        try:
+            ref_name = self.GetRemote().ToLocal(self.revisionExpr)
+        except GitError as e:
+            logger.error("error: Failed to resolve tracking ref: %s", e)
+            return False
+        try:
+            resolved_ref = self.bare_git.rev_parse(ref_name)
+            if resolved_ref != repo_trev:
+                logger.error(
+                    "error: Postcondition failed: %s is %s, expected %s",
+                    ref_name,
+                    resolved_ref,
+                    repo_trev,
+                )
+                return False
+        except GitError:
+            logger.error("error: Postcondition failed: %s not found", ref_name)
+            return False
+
+        try:
+            fetch_head = self.bare_git.rev_parse("FETCH_HEAD")
+            if fetch_head != repo_trev:
+                logger.error(
+                    "error: Postcondition failed: FETCH_HEAD is %s, "
+                    "expected %s",
+                    fetch_head,
+                    repo_trev,
+                )
+                return False
+        except GitError:
+            logger.error("error: Postcondition failed: FETCH_HEAD not found")
+            return False
+
+        return True
+
     def _RemoteFetch(
         self,
         name=None,
@@ -2611,7 +2879,7 @@ class Project:
         if depth:
             current_branch_only = True
 
-        is_sha1 = bool(IsId(self.revisionExpr))
+        is_sha1 = IsId(self.revisionExpr)
 
         if current_branch_only:
             if self.revisionExpr.startswith(R_TAGS):
@@ -2622,11 +2890,14 @@ class Project:
                 tag_name = self.upstream[len(R_TAGS) :]
 
             if is_sha1 or tag_name is not None:
+                has_shallow = os.path.exists(
+                    os.path.join(self.gitdir, "shallow")
+                )
                 if self._CheckForImmutableRevision(
                     use_superproject=use_superproject
                 ) and (
-                    not depth
-                    or os.path.exists(os.path.join(self.gitdir, "shallow"))
+                    has_shallow
+                    or (not depth and not self._SharingProjectHasShallow())
                 ):
                     if verbose:
                         print(
@@ -3686,7 +3957,11 @@ class Project:
             self._MigrateOldSubmoduleDir()
 
         # If using an old layout style (a directory), migrate it.
-        if not platform_utils.islink(dotgit) and platform_utils.isdir(dotgit):
+        if (
+            not platform_utils.islink(dotgit)
+            and platform_utils.isdir(dotgit)
+            and not self.manifest.UseLocalGitDirs
+        ):
             self._MigrateOldWorkTreeGitDir(dotgit, project=self.name)
 
         init_dotgit = not os.path.lexists(dotgit)
@@ -3735,6 +4010,11 @@ class Project:
         For submodule projects, create a '.git' file using the gitfile
         mechanism, and for the rest, create a symbolic link.
         """
+        if self.manifest.UseLocalGitDirs and os.path.normpath(
+            self.gitdir
+        ) == os.path.normpath(dotgit):
+            return
+
         os.makedirs(self.worktree, exist_ok=True)
         if self.parent:
             _lwrite(
@@ -4488,6 +4768,16 @@ class ManifestProject(MetaProject):
         """Whether we use worktree."""
         return self.config.GetBoolean("repo.worktree")
 
+    @property
+    def use_local_gitdirs(self):
+        """Whether we use local gitdirs."""
+        return self.config.GetBoolean("repo.uselocalgitdirs")
+
+    @property
+    def fetch_cmd(self):
+        """The fetch command to use."""
+        return self.config.GetString("repo.fetchcmd")
+
     @property
     def clone_bundle(self):
         """Whether we use clone_bundle."""
@@ -4642,6 +4932,7 @@ class ManifestProject(MetaProject):
         this_manifest_only=False,
         outer_manifest=True,
         clone_filter_for_depth=None,
+        use_local_gitdirs=False,
     ):
         """Sync the manifest and all submanifests.
 
@@ -4872,6 +5163,41 @@ class ManifestProject(MetaProject):
                 self.use_git_worktrees = True
             logger.warning("warning: --worktree is experimental!")
 
+        if use_local_gitdirs:
+            if mirror:
+                logger.error(
+                    "fatal: --mirror and --use-local-gitdirs are incompatible"
+                )
+                return False
+
+            if worktree:
+                logger.error(
+                    "fatal: --worktree and --use-local-gitdirs are incompatible"
+                )
+                return False
+
+            if archive:
+                logger.error(
+                    "fatal: --archive and --use-local-gitdirs are incompatible"
+                )
+                return False
+
+            if not is_new and not self.use_local_gitdirs:
+                logger.error(
+                    "fatal: --use-local-gitdirs is only supported when "
+                    "initializing a new workspace."
+                )
+                return False
+
+            self.config.SetBoolean("repo.uselocalgitdirs", use_local_gitdirs)
+
+        if self.fetch_cmd and not (use_local_gitdirs or self.use_local_gitdirs):
+            logger.error(
+                "fatal: repo.fetchcmd is set but repo.uselocalgitdirs is "
+                "not enabled"
+            )
+            return False
+
         if archive:
             if is_new:
                 self.config.SetBoolean("repo.archive", archive)

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/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
@@ -339,25 +340,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

@@ -191,12 +191,14 @@ class Info(PagedCommand):
             "superproject_revision": srev,
         }
 
-    def _getProjectData(self, project) -> Dict[str, Any]:
+    @classmethod
+    def _getProjectData(cls, project) -> Dict[str, Any]:
         """Gather project data as a dict."""
         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()),
         }
@@ -205,6 +207,12 @@ class Info(PagedCommand):
             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 +222,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.
@@ -273,7 +296,7 @@ class Info(PagedCommand):
         out.nl()
 
         heading("Current revision: ")
-        headtext(project.GetRevisionId())
+        headtext(project.GetHeadRevisionId() or project.GetRevisionId())
         out.nl()
 
         currentBranch = project.CurrentBranch

subcmds/init.py

@@ -169,6 +169,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/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"
@@ -162,7 +175,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)
 

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,6 +23,8 @@ import netrc
 import optparse
 import os
 from pathlib import Path
+import shutil
+import subprocess
 import sys
 import tempfile
 import time
@@ -96,19 +98,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,21 +129,29 @@ 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
 
@@ -361,7 +379,8 @@ 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.
+of all projects from the server. The --no-fetch-submodules option disables
+fetching Git submodules, even when a project has sync-s="true" in the manifest.
 
 The -c/--current-branch option can be used to only fetch objects that
 are on the branch specified by a project's revision.
@@ -555,6 +574,12 @@ later is required to fix a server side protocol bug.
             action="store_true",
             help="fetch submodules from server",
         )
+        p.add_option(
+            "--no-fetch-submodules",
+            dest="fetch_submodules",
+            action="store_false",
+            help="don't fetch submodules from server",
+        )
         p.add_option(
             "--use-superproject",
             action="store_true",
@@ -1722,16 +1747,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 +1879,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 +1917,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 +1925,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 +1948,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.
 
@@ -3078,14 +3213,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 +3247,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 +3264,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)

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,8 @@
 
 """Unittests for the command.py module."""
 
+import pytest
+
 from command import Command
 
 
@@ -86,3 +88,32 @@ 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

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, True),
+        ("a" * 63, True),
+        ("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_trace2_event_log.py

@@ -315,6 +315,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 +324,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")
 

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_project.py

@@ -104,6 +104,28 @@ class ProjectTests(unittest.TestCase):
             "abcd00%21%21_%2b",
         )
 
+    def test_get_head_revision_id(self):
+        """Check GetHeadRevisionId behavior."""
+        with utils_for_test.TempGitTree() as tempdir:
+            proj = _create_mock_project(tempdir)
+
+            # Initially unborn HEAD should return None.
+            self.assertIsNone(proj.GetHeadRevisionId())
+
+            # Create a commit.
+            with open(os.path.join(tempdir, "readme"), "w") as fp:
+                fp.write("hello")
+            proj.work_git.add("readme")
+            proj.work_git.commit("-m", "initial commit")
+
+            # HEAD should resolve to the commit SHA.
+            commit_sha = proj.work_git.rev_parse("HEAD")
+            self.assertEqual(commit_sha, proj.GetHeadRevisionId())
+
+            # Even if worktree is detached.
+            proj.work_git.checkout("HEAD~0")
+            self.assertEqual(commit_sha, proj.GetHeadRevisionId())
+
     @unittest.skipUnless(
         utils_for_test.supports_reftable(),
         "git reftable support is required for this test",
@@ -657,6 +679,9 @@ class ManifestPropertiesFetchedCorrectly(unittest.TestCase):
             fakeproj.config.SetBoolean("repo.worktree", False)
             self.assertFalse(fakeproj.use_worktree)
 
+            fakeproj.config.SetBoolean("repo.uselocalgitdirs", False)
+            self.assertFalse(fakeproj.use_local_gitdirs)
+
             fakeproj.config.SetBoolean("repo.clonebundle", False)
             self.assertFalse(fakeproj.clone_bundle)
 
@@ -691,39 +716,137 @@ class ManifestPropertiesFetchedCorrectly(unittest.TestCase):
             fakeproj.config.SetString("manifest.platform", "auto")
             self.assertEqual(fakeproj.manifest_platform, "auto")
 
+    def test_sync_use_local_gitdirs_worktree_conflict(self):
+        """Test that --use-local-gitdirs conflicts with --worktree."""
+        with utils_for_test.TempGitTree() as tempdir:
+            fakeproj = self.setUpManifest(tempdir)
+
+            class DummyManifest:
+                is_submanifest = False
+
+                def GetDefaultGroupsStr(self, with_platform=False):
+                    return ""
+
+            fakeproj.manifest = DummyManifest()
+
+            result = fakeproj.Sync(use_local_gitdirs=True, worktree=True)
+            self.assertFalse(result)
+
+    def test_sync_use_local_gitdirs_archive_conflict(self):
+        """Test that --use-local-gitdirs conflicts with --archive."""
+        with utils_for_test.TempGitTree() as tempdir:
+            fakeproj = self.setUpManifest(tempdir)
+
+            class DummyManifest:
+                is_submanifest = False
+
+                def GetDefaultGroupsStr(self, with_platform=False):
+                    return ""
+
+            fakeproj.manifest = DummyManifest()
+
+            result = fakeproj.Sync(use_local_gitdirs=True, archive=True)
+            self.assertFalse(result)
+
+    def test_sync_use_local_gitdirs_mirror_conflict(self):
+        """Test that --use-local-gitdirs conflicts with --mirror."""
+        with utils_for_test.TempGitTree() as tempdir:
+            fakeproj = self.setUpManifest(tempdir)
+
+            class DummyManifest:
+                is_submanifest = False
+
+                def GetDefaultGroupsStr(self, with_platform=False):
+                    return ""
+
+            fakeproj.manifest = DummyManifest()
+
+            result = fakeproj.Sync(use_local_gitdirs=True, mirror=True)
+            self.assertFalse(result)
+
+    def test_delete_worktree_corrupted(self):
+        """Test DeleteWorktree gracefully handles corrupted projects."""
+        for use_git_worktrees in (False, True):
+            with self.subTest(use_git_worktrees=use_git_worktrees):
+                with utils_for_test.TempGitTree() as tempdir:
+                    proj = _create_mock_project(tempdir)
+                    os.makedirs(os.path.join(tempdir, "worktree"))
+                    os.makedirs(os.path.join(tempdir, "gitdir"))
+                    proj.worktree = os.path.join(tempdir, "worktree")
+                    proj.gitdir = os.path.join(tempdir, "gitdir")
+                    proj.use_git_worktrees = use_git_worktrees
+
+                    with mock.patch.object(
+                        proj,
+                        "IsDirty",
+                        side_effect=error.GitError("mock error"),
+                    ):
+                        with self.assertRaises(project.DeleteWorktreeError):
+                            proj.DeleteWorktree(force=False)
+
+                        self.assertTrue(proj.DeleteWorktree(force=True))
+                        self.assertFalse(os.path.exists(proj.worktree))
+                        self.assertFalse(os.path.exists(proj.gitdir))
+
+
+def _create_mock_project(
+    tempdir,
+    use_local_gitdirs=False,
+    fetch_cmd=None,
+    depth=None,
+    gitdir=None,
+    objdir=None,
+    revisionExpr="main",
+    sync_strategy=None,
+):
+    manifest = mock.MagicMock()
+    manifest.manifestProject.use_local_gitdirs = use_local_gitdirs
+    manifest.manifestProject.fetch_cmd = fetch_cmd
+    manifest.manifestProject.depth = depth
+    manifest.manifestProject.dissociate = False
+    manifest.manifestProject.clone_filter = None
+    manifest.manifestProject.config.GetBoolean.return_value = False
+    manifest.is_multimanifest = False
+    manifest.IsMirror = False
+    manifest.topdir = tempdir
+
+    remote = mock.MagicMock()
+    remote.name = "origin"
+    remote.url = "http://example.com/repo"
+
+    if gitdir is None:
+        gitdir = os.path.join(tempdir, ".git")
+    if objdir is None:
+        objdir = os.path.join(tempdir, ".git")
+
+    proj = project.Project(
+        manifest=manifest,
+        name="test-project",
+        remote=remote,
+        gitdir=gitdir,
+        objdir=objdir,
+        worktree=tempdir,
+        relpath="test-project",
+        revisionExpr=revisionExpr,
+        revisionId=None,
+        sync_strategy=sync_strategy,
+    )
+
+    proj.bare_git = mock.MagicMock()
+    proj._LsRemote = mock.MagicMock(return_value="1234abcd\trefs/heads/main\n")
+    manifest.GetProjectsWithName.return_value = [proj]
+
+    return proj
+
 
 class StatelessSyncTests(unittest.TestCase):
     """Tests for stateless sync strategy."""
 
     def _get_project(self, tempdir):
-        manifest = mock.MagicMock()
-        manifest.manifestProject.depth = None
-        manifest.manifestProject.dissociate = False
-        manifest.manifestProject.clone_filter = None
-        manifest.is_multimanifest = False
-        manifest.manifestProject.config.GetBoolean.return_value = False
-
-        remote = mock.MagicMock()
-        remote.name = "origin"
-        remote.url = "http://"
-
-        proj = project.Project(
-            manifest=manifest,
-            name="test-project",
-            remote=remote,
-            gitdir=os.path.join(tempdir, ".git"),
-            objdir=os.path.join(tempdir, ".git"),
-            worktree=tempdir,
-            relpath="test-project",
-            revisionExpr="1234abcd",
-            revisionId=None,
-            sync_strategy="stateless",
+        proj = _create_mock_project(
+            tempdir, revisionExpr="1234abcd", sync_strategy="stateless"
         )
         proj._CheckForImmutableRevision = mock.MagicMock(return_value=False)
-        proj._LsRemote = mock.MagicMock(
-            return_value="1234abcd\trefs/heads/main\n"
-        )
-        proj.bare_git = mock.MagicMock()
         proj.bare_git.rev_parse.return_value = "5678abcd"
         proj.bare_git.rev_list.return_value = ["0"]
         proj.IsDirty = mock.MagicMock(return_value=False)
@@ -843,28 +966,12 @@ class SyncOptimizationTests(unittest.TestCase):
     """Tests for sync optimization logic involving shallow clones."""
 
     def _get_project(self, tempdir, depth=None):
-        manifest = mock.MagicMock()
-        manifest.manifestProject.depth = depth
-        manifest.manifestProject.dissociate = False
-        manifest.manifestProject.clone_filter = None
-        manifest.is_multimanifest = False
-        manifest.manifestProject.config.GetBoolean.return_value = False
-        manifest.IsMirror = False
-
-        remote = mock.MagicMock()
-        remote.name = "origin"
-        remote.url = "http://"
-
-        proj = project.Project(
-            manifest=manifest,
-            name="test-project",
-            remote=remote,
+        proj = _create_mock_project(
+            tempdir,
+            depth=depth,
             gitdir=os.path.join(tempdir, "gitdir"),
             objdir=os.path.join(tempdir, "objdir"),
-            worktree=tempdir,
-            relpath="test-project",
             revisionExpr="0123456789abcdef0123456789abcdef01234567",
-            revisionId=None,
         )
         proj._CheckForImmutableRevision = mock.MagicMock(return_value=True)
         proj.DeleteWorktree = mock.MagicMock()
@@ -873,6 +980,31 @@ class SyncOptimizationTests(unittest.TestCase):
         proj._InitMRef = mock.MagicMock()
         return proj
 
+    def _create_sharing_project(self, tempdir, proj, share_objdir=True):
+        """Create another project with the same name but a different gitdir.
+
+        Args:
+            share_objdir: a boolean, if True - the new project shares the same
+                objdir, if False - the new project has a different objdir.
+        """
+        if share_objdir:
+            other_objdir = proj.objdir
+        else:
+            other_objdir = os.path.join(tempdir, "other_objdir")
+        other = project.Project(
+            manifest=proj.manifest,
+            name=proj.name,
+            remote=proj.remote,
+            gitdir=os.path.join(tempdir, "other_gitdir"),
+            objdir=other_objdir,
+            worktree=os.path.join(tempdir, "other_worktree"),
+            relpath="other-test-project",
+            revisionExpr=proj.revisionExpr,
+            revisionId=None,
+        )
+        proj.manifest.GetProjectsWithName.return_value.append(other)
+        return other
+
     def test_sync_network_half_shallow_missing_fetches(self):
         """Test Sync_NetworkHalf fetches if shallow file is missing."""
         with utils_for_test.TempGitTree() as tempdir:
@@ -907,6 +1039,72 @@ class SyncOptimizationTests(unittest.TestCase):
             self.assertTrue(res.success)
             proj._RemoteFetch.assert_not_called()
 
+    def test_sync_network_half_sharing_project_shallow_missing_fetches(
+        self,
+    ):
+        """Test Sync_NetworkHalf fetches when sharing project has shallow
+        file but this project does not."""
+        with utils_for_test.TempGitTree() as tempdir:
+            proj = self._get_project(tempdir, depth=1)
+            os.makedirs(proj.gitdir, exist_ok=True)
+            os.makedirs(proj.objdir, exist_ok=True)
+
+            other = self._create_sharing_project(tempdir, proj)
+            os.makedirs(other.gitdir, exist_ok=True)
+            with open(os.path.join(other.gitdir, "shallow"), "w") as f:
+                f.write("")
+
+            proj._RemoteFetch = mock.MagicMock(return_value=True)
+
+            res = proj.Sync_NetworkHalf(optimized_fetch=True)
+
+            self.assertTrue(res.success)
+            proj._RemoteFetch.assert_called_once()
+
+    def test_sync_network_half_different_objdir_shallow_exists_skips(self):
+        """Test Sync_NetworkHalf skips when same-name project has shallow file
+        but different objdir (like in a multi-manifest setup)."""
+        with utils_for_test.TempGitTree() as tempdir:
+            proj = self._get_project(tempdir, depth=1)
+            os.makedirs(proj.gitdir, exist_ok=True)
+            os.makedirs(proj.objdir, exist_ok=True)
+
+            other = self._create_sharing_project(
+                tempdir, proj, share_objdir=False
+            )
+            os.makedirs(other.gitdir, exist_ok=True)
+            with open(os.path.join(other.gitdir, "shallow"), "w") as f:
+                f.write("")
+
+            proj._RemoteFetch = mock.MagicMock()
+
+            res = proj.Sync_NetworkHalf(optimized_fetch=True)
+
+            self.assertTrue(res.success)
+            proj._RemoteFetch.assert_not_called()
+
+    def test_sync_network_half_sharing_project_both_shallow_skips(self):
+        """Test Sync_NetworkHalf skips when both this project and the sharing
+        project have shallow files."""
+        with utils_for_test.TempGitTree() as tempdir:
+            proj = self._get_project(tempdir, depth=1)
+            os.makedirs(proj.gitdir, exist_ok=True)
+            os.makedirs(proj.objdir, exist_ok=True)
+            with open(os.path.join(proj.gitdir, "shallow"), "w") as f:
+                f.write("")
+
+            other = self._create_sharing_project(tempdir, proj)
+            os.makedirs(other.gitdir, exist_ok=True)
+            with open(os.path.join(other.gitdir, "shallow"), "w") as f:
+                f.write("")
+
+            proj._RemoteFetch = mock.MagicMock()
+
+            res = proj.Sync_NetworkHalf(optimized_fetch=True)
+
+            self.assertTrue(res.success)
+            proj._RemoteFetch.assert_not_called()
+
     def test_remote_fetch_shallow_missing_fetches(self):
         """Test _RemoteFetch fetches if shallow file is missing."""
         with utils_for_test.TempGitTree() as tempdir:
@@ -947,3 +1145,212 @@ class SyncOptimizationTests(unittest.TestCase):
 
                 self.assertTrue(res)
                 mock_git_cmd.assert_not_called()
+
+    def test_remote_fetch_sharing_project_shallow_missing_fetches(self):
+        """Test _RemoteFetch fetches when sharing project has shallow file
+        but this project does not."""
+        with utils_for_test.TempGitTree() as tempdir:
+            proj = self._get_project(tempdir, depth=1)
+            os.makedirs(proj.gitdir, exist_ok=True)
+            os.makedirs(proj.objdir, exist_ok=True)
+
+            other = self._create_sharing_project(tempdir, proj)
+            os.makedirs(other.gitdir, exist_ok=True)
+            with open(os.path.join(other.gitdir, "shallow"), "w") as f:
+                f.write("")
+
+            with mock.patch("project.GitCommand") as mock_git_cmd:
+                mock_cmd_instance = mock.MagicMock()
+                mock_cmd_instance.Wait.return_value = 0
+                mock_git_cmd.return_value = mock_cmd_instance
+
+                res = proj._RemoteFetch(
+                    current_branch_only=True,
+                    depth=1,
+                    use_superproject=False,
+                )
+
+                self.assertTrue(res)
+                mock_git_cmd.assert_called()
+
+    def test_remote_fetch_sharing_project_both_shallow_skips(self):
+        """Test _RemoteFetch skips when both this project and the sharing
+        project have shallow files."""
+        with utils_for_test.TempGitTree() as tempdir:
+            proj = self._get_project(tempdir, depth=1)
+            os.makedirs(proj.gitdir, exist_ok=True)
+            os.makedirs(proj.objdir, exist_ok=True)
+            with open(os.path.join(proj.gitdir, "shallow"), "w") as f:
+                f.write("")
+
+            other = self._create_sharing_project(tempdir, proj)
+            os.makedirs(other.gitdir, exist_ok=True)
+            with open(os.path.join(other.gitdir, "shallow"), "w") as f:
+                f.write("")
+
+            with mock.patch("project.GitCommand") as mock_git_cmd:
+                res = proj._RemoteFetch(
+                    current_branch_only=True,
+                    depth=1,
+                    use_superproject=False,
+                )
+
+                self.assertTrue(res)
+                mock_git_cmd.assert_not_called()
+
+
+class GetEnvVarsTests(unittest.TestCase):
+    """Tests for GetEnvVars project environment variable generation."""
+
+    def _get_project(self, tempdir, revisionExpr="main"):
+        proj = _create_mock_project(tempdir, revisionExpr=revisionExpr)
+        proj.GetRevisionId = mock.MagicMock(return_value="1234abcd")
+        return proj
+
+    def test_get_env_vars_basic(self):
+        """Test that all basic environment variables are set correctly."""
+        with utils_for_test.TempGitTree() as tempdir:
+            proj = self._get_project(tempdir)
+            proj.manifest.path_prefix = "sub-manifest"
+            proj.upstream = "upstream-branch"
+            proj.dest_branch = "dest-branch"
+
+            env = proj.GetEnvVars(local=True)
+
+            self.assertEqual(env["REPO_PROJECT"], "test-project")
+            self.assertEqual(env["REPO_OUTERPATH"], "sub-manifest")
+            self.assertEqual(env["REPO_INNERPATH"], "test-project")
+            self.assertEqual(env["REPO_PATH"], "test-project")
+            self.assertEqual(env["REPO_REMOTE"], "origin")
+            self.assertEqual(env["REPO_LREV"], "1234abcd")
+            self.assertEqual(env["REPO_RREV"], "main")
+            self.assertEqual(env["REPO_UPSTREAM"], "upstream-branch")
+            self.assertEqual(env["REPO_DEST_BRANCH"], "dest-branch")
+            self.assertEqual(
+                env["REPO_PROJECT_FETCH_URL"], "http://example.com/repo"
+            )
+
+    def test_get_env_vars_non_local(self):
+        """Test environment variables generation with local=False."""
+        with utils_for_test.TempGitTree() as tempdir:
+            proj = self._get_project(tempdir)
+            proj.manifest.path_prefix = "sub-manifest"
+
+            env = proj.GetEnvVars(local=False)
+
+            # REPO_PATH should be relative to outermost manifest
+            # (sub-manifest/test-project)
+            self.assertEqual(env["REPO_PATH"], "sub-manifest/test-project")
+
+    def test_get_env_vars_mirror(self):
+        """Test environment variables generation in mirror mode."""
+        with utils_for_test.TempGitTree() as tempdir:
+            proj = self._get_project(tempdir)
+            proj.manifest.IsMirror = True
+
+            env = proj.GetEnvVars()
+
+            # In mirror mode, REPO_LREV should be empty, and GetRevisionId must
+            # not be called
+            self.assertEqual(env["REPO_LREV"], "")
+            proj.GetRevisionId.assert_not_called()
+
+    def test_get_env_vars_annotations(self):
+        """Test that project annotations are added correctly."""
+        with utils_for_test.TempGitTree() as tempdir:
+            proj = self._get_project(tempdir)
+
+            annotation1 = mock.MagicMock()
+            annotation1.name = "key1"
+            annotation1.value = "value1"
+
+            annotation2 = mock.MagicMock()
+            annotation2.name = "key2"
+            annotation2.value = "value2"
+
+            proj.annotations = [annotation1, annotation2]
+
+            env = proj.GetEnvVars()
+
+            self.assertEqual(env["REPO__key1"], "value1")
+            self.assertEqual(env["REPO__key2"], "value2")
+
+    def test_get_env_vars_invalid_revision_graceful(self):
+        """Test that invalid revision error is handled gracefully."""
+        with utils_for_test.TempGitTree() as tempdir:
+            proj = self._get_project(tempdir)
+            proj.GetRevisionId.side_effect = error.ManifestInvalidRevisionError(
+                "revision not found"
+            )
+
+            env = proj.GetEnvVars()
+
+            self.assertEqual(env["REPO_LREV"], "")
+
+
+class FetchCmdTests(unittest.TestCase):
+    """Tests for fetch_cmd feature."""
+
+    def setUpManifest(self, tempdir):
+        repodir = os.path.join(tempdir, ".repo")
+        manifest_dir = os.path.join(repodir, "manifests")
+        manifest_file = os.path.join(repodir, manifest_xml.MANIFEST_FILE_NAME)
+        os.mkdir(repodir)
+        os.mkdir(manifest_dir)
+        manifest = manifest_xml.XmlManifest(repodir, manifest_file)
+
+        return project.ManifestProject(
+            manifest, "test/manifest", os.path.join(tempdir, ".git"), tempdir
+        )
+
+    def _get_project(self, tempdir):
+        proj = _create_mock_project(
+            tempdir, use_local_gitdirs=True, fetch_cmd="echo hi"
+        )
+        proj.GetRevisionId = mock.MagicMock(return_value="1234abcd")
+        return proj
+
+    def test_fetch_cmd_execution(self):
+        """Test that fetch_cmd is executed with correct environment."""
+        with utils_for_test.TempGitTree() as tempdir:
+            proj = self._get_project(tempdir)
+
+            proj.bare_git.rev_parse.return_value = "1234abcd"
+            mock_remote = mock.MagicMock()
+            mock_remote.ToLocal.return_value = "refs/remotes/origin/main"
+            proj.GetRemote = mock.MagicMock(return_value=mock_remote)
+
+            with mock.patch("subprocess.run") as mock_run:
+                mock_run.return_value = mock.MagicMock(returncode=0, stderr="")
+                res = proj._CustomFetch()
+
+                self.assertTrue(res)
+                mock_run.assert_called_once()
+            args, kwargs = mock_run.call_args
+            self.assertEqual(args[0], "echo hi")
+            self.assertEqual(kwargs["shell"], True)
+            self.assertEqual(kwargs["cwd"], tempdir)
+            self.assertEqual(kwargs["env"]["REPO_TREV"], "1234abcd")
+            self.assertEqual(
+                kwargs["env"]["REPO_PROJECT_FETCH_URL"],
+                "http://example.com/repo",
+            )
+
+    def test_sync_fetch_cmd_requires_use_local_gitdirs(self):
+        """Test that fetch_cmd requires use_local_gitdirs."""
+        with utils_for_test.TempGitTree() as tempdir:
+            fakeproj = self.setUpManifest(tempdir)
+
+            class DummyManifest:
+                is_submanifest = False
+
+                def GetDefaultGroupsStr(self, with_platform=False):
+                    return ""
+
+            fakeproj.manifest = DummyManifest()
+
+            fakeproj.config.SetString("repo.fetchcmd", "echo hi")
+            fakeproj.config.SetBoolean("repo.uselocalgitdirs", False)
+
+            result = fakeproj.Sync(use_local_gitdirs=False)
+            self.assertFalse(result)

tests/test_subcmds_forall.py

@@ -17,12 +17,10 @@
 import contextlib
 import io
 from pathlib import Path
-from unittest import mock
 
 import utils_for_test
 
 import manifest_xml
-import project
 import subcmds
 
 
@@ -87,13 +85,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.

tests/test_subcmds_info.py

@@ -199,3 +199,57 @@ 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"
+    project.GetBranches.return_value = {"branch1": mock.MagicMock()}
+    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"

tests/test_subcmds_rebase.py

@@ -0,0 +1,50 @@
+# 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."""
+
+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")

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
@@ -218,3 +230,224 @@ 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", "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")

tests/test_subcmds_sync.py

@@ -30,6 +30,23 @@ from project import SyncNetworkHalfResult
 from subcmds import sync
 
 
+@pytest.mark.parametrize(
+    "cli_args, expected",
+    [
+        ([], None),
+        (["--fetch-submodules"], True),
+        (["--no-fetch-submodules"], False),
+    ],
+)
+def test_fetch_submodules_option(cli_args, expected):
+    """The fetch-submodules flags preserve an unset manifest-driven state."""
+    cmd = sync.Sync()
+
+    opts, _ = cmd.OptionParser.parse_args(cli_args)
+
+    assert opts.fetch_submodules is expected
+
+
 @pytest.mark.parametrize(
     "use_superproject, cli_args, result",
     [
@@ -340,6 +357,7 @@ class FakeProject:
         self.name = name or relpath
         self.objdir = objdir or relpath
         self.worktree = relpath
+        self.parent = None
 
         self.use_git_worktrees = False
         self.UseAlternates = False
@@ -397,6 +415,65 @@ class SafeCheckoutOrder(unittest.TestCase):
             ],
         )
 
+    def test_sibling_submodules_with_shared_parent_are_serialized(self):
+        parent = mock.Mock(worktree="/worktree/parent")
+        other_parent = mock.Mock(worktree="/worktree/other")
+        p_parent = FakeProject("parent")
+        p_other = FakeProject("other")
+        p_parent_sub1 = FakeProject("parent/sub1")
+        p_parent_sub1.parent = parent
+        p_parent_sub2 = FakeProject("parent/sub2")
+        p_parent_sub2.parent = parent
+        p_other_sub = FakeProject("other/sub")
+        p_other_sub.parent = other_parent
+
+        out = sync._SafeCheckoutOrder(
+            [p_parent_sub2, p_other_sub, p_parent, p_parent_sub1, p_other]
+        )
+
+        self.assertEqual(
+            out,
+            [
+                [p_other, p_parent],
+                [p_other_sub, p_parent_sub1],
+                [p_parent_sub2],
+            ],
+        )
+
+    def test_nested_submodules_respect_delayed_parent_level(self):
+        parent = mock.Mock(worktree="/worktree/parent")
+        sub1 = mock.Mock(worktree="/worktree/parent/sub1")
+        sub2 = mock.Mock(worktree="/worktree/parent/sub2")
+        p_parent = FakeProject("parent")
+        p_parent_sub1 = FakeProject("parent/sub1")
+        p_parent_sub1.parent = parent
+        p_parent_sub1_nested = FakeProject("parent/sub1/nested")
+        p_parent_sub1_nested.parent = sub1
+        p_parent_sub2 = FakeProject("parent/sub2")
+        p_parent_sub2.parent = parent
+        p_parent_sub2_nested = FakeProject("parent/sub2/nested")
+        p_parent_sub2_nested.parent = sub2
+
+        out = sync._SafeCheckoutOrder(
+            [
+                p_parent_sub2_nested,
+                p_parent_sub2,
+                p_parent_sub1_nested,
+                p_parent,
+                p_parent_sub1,
+            ]
+        )
+
+        self.assertEqual(
+            out,
+            [
+                [p_parent],
+                [p_parent_sub1],
+                [p_parent_sub1_nested, p_parent_sub2],
+                [p_parent_sub2_nested],
+            ],
+        )
+
 
 class Chunksize(unittest.TestCase):
     """Tests for _chunksize."""
@@ -1454,3 +1531,232 @@ class UpdateAllManifestProjectsTests(unittest.TestCase):
                 )
                 mock_sync_to_rev.assert_not_called()
                 mock_update_manifest.assert_called_once()
+
+
+class TestSmartSyncSetupRemoteHelper(unittest.TestCase):
+    """Tests for _SmartSyncSetup with remote helpers."""
+
+    def setUp(self):
+        self.cmd = sync.Sync()
+        self.opt = mock.MagicMock()
+        self.opt.quiet = False
+        self.opt.smart_sync = True
+        self.manifest = mock.MagicMock()
+        self.smart_sync_manifest_path = "/fake/path/to/manifest.xml"
+
+    @mock.patch("shutil.which")
+    @mock.patch("subprocess.Popen")
+    @mock.patch("xmlrpc.client.Server")
+    @mock.patch("subcmds.sync.PersistentTransport")
+    def test_smart_sync_setup_with_helper(
+        self, mock_transport_class, mock_server_class, mock_popen, mock_which
+    ):
+        """Test _SmartSyncSetup when a helper is present and succeeds."""
+        import subprocess
+
+        self.manifest.manifest_server = (
+            "persistent-https://android-smartsync.corp.google.com/"
+            "manifestserver"
+        )
+        self.manifest.manifest_server_helper = "repo-remote-sso"
+        mock_which.return_value = "/fake/bin/repo-remote-sso"
+
+        # Mock subprocess to return a JSON with status ok and proxy address
+        mock_process = mock.MagicMock()
+        mock_process.communicate.return_value = (
+            '{"status":"ok","message":"http://127.0.0.1:999"}\n',
+            "",
+        )
+        mock_process.returncode = 0
+        mock_popen.return_value = mock_process
+
+        # Mock XML-RPC server call
+        mock_server = mock.MagicMock()
+        mock_server.GetApprovedManifest.return_value = [
+            True,
+            "<manifest></manifest>",
+        ]
+        mock_server_class.return_value = mock_server
+
+        # Mock manifest project branch
+        self.cmd._GetBranch = mock.MagicMock(return_value="main")
+        self.cmd._ReloadManifest = mock.MagicMock()
+
+        # Mock open to avoid writing to disk
+        with mock.patch("builtins.open", mock.mock_open()):
+            manifest_name = self.cmd._SmartSyncSetup(
+                self.opt, self.smart_sync_manifest_path, self.manifest
+            )
+
+        # Assertions
+        mock_which.assert_called_once_with("repo-remote-sso")
+        mock_popen.assert_called_once_with(
+            ["repo-remote-sso", self.manifest.manifest_server],
+            stdin=subprocess.PIPE,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            text=True,
+        )
+
+        # Verify transport was created with the proxy returned by helper (with
+        # http:// prepended)
+        mock_transport_class.assert_called_once_with(
+            self.manifest.manifest_server, proxy="http://127.0.0.1:999"
+        )
+
+        # Verify Server was created with the same URL, with persistent- stripped
+        mock_server_class.assert_called_once_with(
+            "https://android-smartsync.corp.google.com/manifestserver",
+            transport=mock_transport_class.return_value,
+        )
+
+        self.assertEqual(manifest_name, "manifest.xml")
+
+    @mock.patch("shutil.which")
+    @mock.patch("subprocess.Popen")
+    def test_smart_sync_setup_helper_error(self, mock_popen, mock_which):
+        """Test _SmartSyncSetup when helper returns an error status."""
+        self.manifest.manifest_server = (
+            "http://android-smartsync.corp.google.com/manifestserver"
+        )
+        self.manifest.manifest_server_helper = "repo-remote-sso"
+        mock_which.return_value = "/fake/bin/repo-remote-sso"
+
+        # Mock subprocess to return a JSON with status error
+        mock_process = mock.MagicMock()
+        mock_process.communicate.return_value = (
+            '{"status":"error","message":"uplink-helper failed"}\n',
+            "",
+        )
+        mock_process.returncode = 0
+        mock_popen.return_value = mock_process
+
+        with self.assertRaises(sync.SmartSyncError) as context:
+            self.cmd._SmartSyncSetup(
+                self.opt, self.smart_sync_manifest_path, self.manifest
+            )
+
+        self.assertIn(
+            "helper repo-remote-sso returned error: uplink-helper failed",
+            str(context.exception),
+        )
+
+    @mock.patch("shutil.which")
+    def test_smart_sync_setup_missing_declared_helper(self, mock_which):
+        """Test _SmartSyncSetup when helper declared in manifest is missing."""
+        self.manifest.manifest_server = (
+            "http://android-smartsync.corp.google.com/manifestserver"
+        )
+        self.manifest.manifest_server_helper = "repo-remote-sso"
+        mock_which.return_value = None
+
+        with self.assertRaises(sync.SmartSyncError) as context:
+            self.cmd._SmartSyncSetup(
+                self.opt, self.smart_sync_manifest_path, self.manifest
+            )
+
+        self.assertIn(
+            "helper binary 'repo-remote-sso' declared in manifest was not "
+            "found",
+            str(context.exception),
+        )
+
+    @mock.patch("shutil.which")
+    @mock.patch("subprocess.Popen")
+    def test_smart_sync_setup_helper_exit_code_error(
+        self, mock_popen, mock_which
+    ):
+        """Test _SmartSyncSetup when helper exits with non-zero and stderr."""
+        self.manifest.manifest_server = (
+            "http://android-smartsync.corp.google.com/manifestserver"
+        )
+        self.manifest.manifest_server_helper = "repo-remote-sso"
+        mock_which.return_value = "/fake/bin/repo-remote-sso"
+
+        # Mock subprocess: exit code 1, stderr, and no JSON on stdout
+        mock_process = mock.MagicMock()
+        mock_process.communicate.return_value = (
+            "",
+            "internal binary error occurred\n",
+        )
+        mock_process.returncode = 1
+        mock_popen.return_value = mock_process
+
+        with self.assertRaises(sync.SmartSyncError) as context:
+            self.cmd._SmartSyncSetup(
+                self.opt, self.smart_sync_manifest_path, self.manifest
+            )
+
+        self.assertIn(
+            "helper repo-remote-sso exited with exit code 1. "
+            "Stderr: internal binary error occurred",
+            str(context.exception),
+        )
+
+    @mock.patch("shutil.which")
+    @mock.patch("subprocess.Popen")
+    def test_smart_sync_setup_helper_json_decode_error_with_stderr(
+        self, mock_popen, mock_which
+    ):
+        """Test _SmartSyncSetup when helper returns invalid JSON and stderr."""
+        self.manifest.manifest_server = (
+            "http://android-smartsync.corp.google.com/manifestserver"
+        )
+        self.manifest.manifest_server_helper = "repo-remote-sso"
+        mock_which.return_value = "/fake/bin/repo-remote-sso"
+
+        mock_process = mock.MagicMock()
+        mock_process.communicate.return_value = (
+            "not a json",
+            "some warning messages\n",
+        )
+        mock_process.returncode = 0
+        mock_popen.return_value = mock_process
+
+        with self.assertRaises(sync.SmartSyncError) as context:
+            self.cmd._SmartSyncSetup(
+                self.opt, self.smart_sync_manifest_path, self.manifest
+            )
+
+        self.assertIn(
+            "failed to parse JSON from helper repo-remote-sso",
+            str(context.exception),
+        )
+        self.assertIn(
+            "Stderr was: some warning messages",
+            str(context.exception),
+        )
+
+    @mock.patch("shutil.which")
+    @mock.patch("subprocess.Popen")
+    def test_smart_sync_setup_helper_error_with_stderr(
+        self, mock_popen, mock_which
+    ):
+        """Test _SmartSyncSetup when helper returns error status and stderr."""
+        self.manifest.manifest_server = (
+            "http://android-smartsync.corp.google.com/manifestserver"
+        )
+        self.manifest.manifest_server_helper = "repo-remote-sso"
+        mock_which.return_value = "/fake/bin/repo-remote-sso"
+
+        mock_process = mock.MagicMock()
+        mock_process.communicate.return_value = (
+            '{"status":"error","message":"uplink-helper failed"}\n',
+            "debugging logs\n",
+        )
+        mock_process.returncode = 0
+        mock_popen.return_value = mock_process
+
+        with self.assertRaises(sync.SmartSyncError) as context:
+            self.cmd._SmartSyncSetup(
+                self.opt, self.smart_sync_manifest_path, self.manifest
+            )
+
+        self.assertIn(
+            "helper repo-remote-sso returned error: uplink-helper failed",
+            str(context.exception),
+        )
+        self.assertIn(
+            "Stderr was: debugging logs",
+            str(context.exception),
+        )