project: Skip superproject upstream check for MetaProjects

The superproject-gated upstream check in _CheckForImmutableRevision
only applies to user projects listed in the manifest. MetaProjects
(ManifestProject and RepoProject) never participate in a superproject
relationship, so evaluating git_superproject.UseSuperproject(...,
self.manifest) for them serves no purpose and, worse, calls the
manifest.superproject property which forces a manifest load.

During repo init, ManifestProject._ConfigureDependencies calls
self.Sync_NetworkHalf before manifest.xml has been linked into
.repo/. That reaches _CheckForImmutableRevision, which triggered the
manifest load and failed with:

  ManifestParseError: .../.repo/manifest.xml: [Errno 2] No such file
  or directory

breaking fresh repo init with SHA-based --manifest-branch combined
with --manifest-upstream-branch.

Factor the "should we consult the superproject for upstream?"
decision into a small overridable hook, _UseSuperprojectForUpstream.
Project's default delegates to git_superproject.UseSuperproject;
MetaProject overrides it to return False, localizing the
MetaProject-specific behavior to MetaProject.

Test verifies that calling _CheckForImmutableRevision on a
ManifestProject whose manifest.xml is not yet on disk returns False
without raising and does not create the file.

Change-Id: I22059109243d914036c06c6fe0081a5aba05da89
Reviewed-on: https://gerrit-review.googlesource.com/c/git-repo/+/574201
Reviewed-by: Gavin Mak <gavinmak@google.com>
Commit-Queue: Ajay Gupta <ajagup@qti.qualcomm.com>
Tested-by: Ajay Gupta <ajagup@qti.qualcomm.com>
Reviewed-by: Mike Frysinger <vapier@google.com>
Reviewed-by: Nasser Grainawi <nasser.grainawi@oss.qualcomm.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)
 
@@ -2531,11 +2674,12 @@ class Project:
             # throws an error.
             revs = [f"{self.revisionExpr}^0"]
             upstream_rev = None
+            use_superproject_for_upstream = self.upstream and (
+                self._UseSuperprojectForUpstream(use_superproject)
+            )
 
             # Only check upstream when using superproject.
-            if self.upstream and git_superproject.UseSuperproject(
-                use_superproject, self.manifest
-            ):
+            if use_superproject_for_upstream:
                 upstream_rev = self.GetRemote().ToLocal(self.upstream)
                 revs.append(upstream_rev)
 
@@ -2549,9 +2693,7 @@ class Project:
 
             # Only verify upstream relationship for superproject scenarios
             # without affecting plain usage.
-            if self.upstream and git_superproject.UseSuperproject(
-                use_superproject, self.manifest
-            ):
+            if use_superproject_for_upstream:
                 self.bare_git.merge_base(
                     "--is-ancestor",
                     self.revisionExpr,
@@ -2563,6 +2705,33 @@ 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 _UseSuperprojectForUpstream(
+        self, use_superproject: Optional[bool] = None
+    ) -> bool:
+        """Whether to include upstream in the immutability check.
+
+        The upstream ancestry check is only meaningful for projects
+        that participate in a superproject relationship.
+        """
+        return git_superproject.UseSuperproject(use_superproject, self.manifest)
+
     def _FetchArchive(self, tarpath, cwd=None):
         cmd = ["archive", "-v", "-o", tarpath]
         cmd.append("--remote=%s" % self.remote.url)
@@ -2579,6 +2748,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 +2888,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 +2899,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 +3966,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 +4019,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(
@@ -4397,6 +4686,15 @@ class MetaProject(Project):
                     self.revisionExpr = base
                     self.revisionId = None
 
+    def _UseSuperprojectForUpstream(
+        self, use_superproject: Optional[bool] = None
+    ) -> bool:
+        # MetaProjects (the manifest repo and repo itself) never
+        # participate in a superproject relationship. Returning False
+        # here also avoids loading the manifest during `repo init`,
+        # before manifest.xml has been linked into .repo/.
+        return False
+
     @property
     def HasChanges(self):
         """Has the remote received new commits not yet checked out?"""
@@ -4488,6 +4786,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 +4950,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 +5181,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,162 @@ class ManifestPropertiesFetchedCorrectly(unittest.TestCase):
             fakeproj.config.SetString("manifest.platform", "auto")
             self.assertEqual(fakeproj.manifest_platform, "auto")
 
+    def test_check_immutable_revision_metaproject_skips_manifest_load(self):
+        """MetaProjects must not parse manifest.xml during immutable check.
+
+        During `repo init` the manifestProject's own Sync_NetworkHalf runs
+        before manifest.xml has been linked into .repo/, so
+        _CheckForImmutableRevision must not touch it.
+        """
+
+        with utils_for_test.TempGitTree() as tempdir:
+            fakeproj = self.setUpManifest(tempdir)
+            manifest_path = os.path.join(
+                tempdir, ".repo", manifest_xml.MANIFEST_FILE_NAME
+            )
+            self.assertFalse(os.path.exists(manifest_path))
+
+            fakeproj.revisionExpr = "deadbeefdeadbeefdeadbeefdeadbeefdeadbeef"
+            fakeproj.upstream = "refs/heads/main"
+
+            # Must return False without raising ManifestParseError, and
+            # must leave the absent manifest.xml untouched.
+            self.assertFalse(
+                fakeproj._CheckForImmutableRevision(use_superproject=None)
+            )
+            self.assertFalse(os.path.exists(manifest_path))
+
+    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 +991,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 +1005,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 +1064,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 +1170,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),
+        )