| # Fuchsia Git Staging & Commit Hooks: Architecture & Reference Guide | |
| ## 1. Overview & Current Architecture | |
| Fuchsia developer workflows span multiple Git repositories (`//`, `//vendor/*`, `//integration`) | |
| coordinated by Jiri. Ensuring that code committed locally meets platform formatting, documentation, | |
| and commit message standards is essential to preventing presubmit and CQ cycle failures. | |
| The Git staging and hook subsystem runs pre-commit and commit-msg checks without clobbering | |
| unstaged edits: | |
| - **Index Partitioning**: Distinguishes fully staged files from partially staged files to prevent | |
| corrupting unstaged hunks during formatting. | |
| - **Stash Isolation ($S^2 \to S$ diff apply)**: Uses the diff between the index commit ($S^2$) and | |
| stash worktree ($S$) to temporarily isolate staged edits without triggering false 3-way merge | |
| conflicts against `HEAD`. | |
| - **Automatic Formatting**: `fx format-code` formats fully staged files with automatic re-staging | |
| (`git add`). Partially staged files are evaluated strictly in read-only check mode under stash | |
| isolation. | |
| - **Static Analysis & Code Linting**: `fx lint` runs as a single read-only check pass on staged | |
| files for every commit after `fx format-code`, validating compliance with platform linters (GN | |
| format, fidl-lint, clippy, mdlint, etc.). Partially staged files are checked under stash | |
| isolation. `clang_tidy` and `python_format` (`ALWAYS_SKIPPED_LINTERS`) are skipped on all commits: | |
| `clang_tidy` takes ~10-20s per C++ file, does not emit auto-fixes in shac, and only emits non-blocking | |
| warnings, while `python_format` takes ~1.1s per Python file and already runs during the preceding | |
| `fx format-code` pass. Human commits also skip `check_licenses` (`HUMAN_SKIPPED_LINTERS`) because | |
| it can take over a minute when triggered; agents run `check_licenses` so automated changes are | |
| CQ-clean before upload. | |
| - **Commit Message Style Verification**: Validates subject line length ($\le 50$ chars recommended, | |
| $> 65$ warned), 72-character body line wrapping, and mandatory footers (`Bug:`, `Test:`, | |
| `Change-Id:`) via `scripts/shac/commit_msg_checker.py`. | |
| - **Jiri Hook Delegation**: Jiri (via `//integration`) distributes a hook dispatcher | |
| (`hook-dispatcher.sh`) and root hook wrappers (`pre-commit`, `commit-msg`). `fx agents setup` | |
| drops scripts into `.git/hooks/<hook_name>.d/` without modifying the root wrappers. | |
| --- | |
| ## 2. Running Multiple Hooks & Worktree Support | |
| ### 2.1 Problem Statement | |
| In Git worktrees (`git worktree add`), `.git` is a file pointing to the main repository, causing | |
| relative path lookups (`.git/hooks/...`) to fail. Furthermore, developers or other tools may have | |
| custom scripts they wish to run during `pre-commit` or `commit-msg` phases. Overwriting these | |
| scripts leads to broken workflows. | |
| ### 2.2 Directory-Based Hooks (`<hook>.d/`) | |
| Jiri (via `//integration`) natively distributes the universal dispatcher (`hook-dispatcher.sh`) and | |
| root hook wrappers (`pre-commit`, `commit-msg`). | |
| ``` | |
| .git/hooks/pre-commit (Jiri Distributed Wrapper) | |
| │ | |
| └──► .git/hooks/pre-commit.d/ | |
| ├── 05-author-check.sh (Upstream Googler email check) | |
| ├── 10-unstage-submodules.sh (Submodule reset check) | |
| ├── 20-fuchsia-agent.sh (Automated formatting & staging isolation) | |
| └── 50-team-tool.sh (Modular team/user scripts) | |
| ``` | |
| ### 2.3 How Hook Dispatch Works | |
| The dispatcher is handled natively by Jiri executing directory-based multi-hooks (`<hook_name>.d/*`) | |
| in lexical order. Check `//integration/git-hooks/hook-dispatcher.sh` for the dispatcher | |
| implementation. | |
| ### 2.4 Install and Uninstall Behavior | |
| 1. **Installation (`fx agents setup`)**: | |
| - Resolves hooks directory via `git rev-parse --git-path hooks` (ensuring compatibility with Git | |
| worktrees and subdirectories). | |
| - `install_git_hooks` creates `.git/hooks/<hook_name>.d/` and writes or updates | |
| `20-fuchsia-agent.sh`. | |
| - It does NOT touch or overwrite `.git/hooks/<hook_name>`. | |
| 2. **Uninstallation / Reset (`fx agents setup --no-git-hooks` or `fx agents setup --reset`)**: | |
| - Uses `uninstall_git_hooks` to delete only `.git/hooks/<hook_name>.d/20-fuchsia-agent.sh`. | |
| - Leaves the `.git/hooks/<hook_name>` wrappers and `<hook_name>.d/` directory intact. | |
| - Any user or team scripts in `<hook_name>.d/` continue executing without disruption. | |
| - You can inspect the status with `fx agents setup --status` (`get_git_hooks_status`). | |
| --- | |
| ## 3. Subsystem Layers | |
| The Git staging and hook subsystem is split into three layers: | |
| - **Layer 1: Generic Staging Helpers (`lib/git_staging/`)**: | |
| - Standalone Git index partitioning, stash isolation (`StashGuard`), and pipeline execution. | |
| - Runs standard Git commands (`git diff`, `git apply`, `git status`) with no Fuchsia-specific | |
| dependencies. | |
| - **Layer 2: Platform Hook Adapters (`lib/githooks/`)**: | |
| - Fuchsia-specific adapters bridging the staging engine with platform tools (`fx format-code`, | |
| `commit_msg_checker.py`). | |
| - Terminal reporters (`ConsoleReporter`) and the hook CLI dispatcher (`runner.py`). | |
| - **Layer 3: Installer & Setup (`commands/setup.py`, `lib/githooks/installer.py`)**: | |
| - Discovers checkout repositories across `//` and `//vendor/*`. | |
| - Idempotently installs and uninstalls `20-fuchsia-agent.sh` within `.git/hooks/<hook_name>.d/`. | |
| For the complete repository and test file layout, see | |
| [`tools/agents/DEVELOPMENT.md#directory-layout`](../DEVELOPMENT.md#directory-layout). | |
| ### 3.1 Standalone Hook Execution | |
| The `20-fuchsia-agent.sh` hook fragment exports `PYTHONPATH="$FUCHSIA_DIR/tools:$PYTHONPATH"` and | |
| executes `$FUCHSIA_DIR/scripts/fuchsia-vendored-python`. This allows hooks to run during | |
| `git commit` without depending on Ninja/GN build artifacts or an active build directory. | |
| --- | |
| ## 4. Console Output & Terminal Formatting | |
| ### 4.1 Terminal Output & Fallbacks | |
| `ConsoleReporter` formats messages based on terminal capabilities: | |
| - Uses UTF-8 symbols (`🧹`, `⚠️`, `❌`) on UTF-8 interactive terminals. | |
| - Falls back to ASCII tags (`[FIXED]`, `[WARN]`, `[ERROR]`) on non-UTF-8 terminals or plain | |
| consoles. Clean commits run silently. | |
| ### 4.2 Example Output | |
| #### Partial-Staging Formatting Conflict | |
| ``` | |
| ❌ Formatting issues in partially staged files. Auto-fix skipped to prevent stash conflicts. | |
| Offending files: | |
| - src/sys/pkg/lib/fuchsia-pkg/src/meta.rs | |
| Or fix directly: | |
| fx format-code --files=src/sys/pkg/lib/fuchsia-pkg/src/meta.rs | |
| ``` | |
| --- | |
| ## 5. Data Structures & Interfaces | |
| ### 5.1 Typed Data Models | |
| The subsystem uses frozen dataclasses and typed callables for pipeline state: | |
| - **[`ActionContext`](../lib/git_staging/engine.py)**: Generic execution context passed to staged | |
| pipelines (`repo_root`, `check_only`). | |
| - **[`HookContext`](../lib/githooks/adapters.py)**: Specializes `ActionContext` for Fuchsia hooks | |
| with `is_agent` flag and `ConsoleReporter`. | |
| - **[`PipelineResult`](../lib/git_staging/engine.py)**: Immutable result of pipeline actions, | |
| tracking success, `restaged_files`, `partial_conflicts`, and errors. | |
| - **[`StagedPartition`](../lib/git_staging/engine.py)**: Immutable partitioning of staged files into | |
| `fully_staged` and `partially_staged` frozensets. | |
| - **[`HookAction`](../lib/githooks/adapters.py)**: Specification of an action in the hook pipeline, | |
| defining name, mutate capability, formattable extensions filter, and failure remediation | |
| callbacks. | |
| - **[`HookOperationResult`](../lib/githooks/installer.py) & | |
| [`HookStatusResult`](../lib/githooks/installer.py)**: Structured summaries of multi-repo hook | |
| installation and status queries. | |
| See [`tools/agents/lib/git_staging/engine.py`](../lib/git_staging/engine.py) and | |
| [`tools/agents/lib/githooks/adapters.py`](../lib/githooks/adapters.py) for the complete | |
| implementations. | |
| ### 5.2 Stash Isolation (`StashGuard`) | |
| The [`StashGuard`](../lib/git_staging/engine.py) context manager handles temporary stash isolation: | |
| - **Isolation (`__enter__`)**: Detects unstaged working tree modifications via | |
| `git status --porcelain` and pushes them to a temporary stash with | |
| `git stash push --keep-index -q -m git-staging-isolation`. | |
| - **Restoration (`__exit__`)**: Captures the binary stash diff between the index commit and stash | |
| commit ($S^2 \to S$) via `git diff --no-color --binary <stash>^2 <stash>`, reapplies it via | |
| `git apply --binary --allow-empty`, and safely drops the stash commit on successful restoration. | |
| - **Unstaged Deletion Handling**: `git stash push --keep-index` omits unstaged deletions of newly | |
| added index files from the stash diff. `StashGuard` explicitly tracks and restores these deletions | |
| (`_unstaged_deleted_files`) to prevent phantom files or index corruption. | |
| - **Exception Chaining**: All Git failures during diff or apply chain the underlying exception | |
| (`raise GitError(...) from exc`) to preserve tracebacks. | |
| See [`tools/agents/lib/git_staging/engine.py`](../lib/git_staging/engine.py) for the complete | |
| implementation. | |
| ### 5.3 Exception Handling | |
| - `GitError(RuntimeError)`: Core exception raised on Git command failures, repository resolution | |
| issues, or stash isolation errors. Ensures clean error wrapping across CLI entrypoints and | |
| runners. | |
| --- | |
| ## 6. Bypasses & Agent Execution | |
| ### 6.1 Bypassing Hooks | |
| Hooks can be bypassed using standard Git flags, environment variables, or `fx agents setup` (see | |
| [`tools/agents/README.md#git-hooks-integration`](../README.md#git-hooks-integration)): | |
| 1. **Native Git Per-Commit Bypass**: | |
| - `git commit -n` or `git commit --no-verify` (standard Git flag, skips `pre-commit` and | |
| `commit-msg` natively). | |
| 2. **Environment Variable Bypass (Scripts / CI)**: | |
| - `FUCHSIA_SKIP_HOOKS=1 git commit ...` (immediately exits 0 from the hook runner). | |
| 3. **Configuration Options**: | |
| - `fx agents setup` (or `fx agents setup --git-hooks`) installs | |
| `.git/hooks/<hook_name>.d/20-fuchsia-agent.sh`. | |
| - `fx agents setup --status`: Displays current configuration and reports Git hook configuration | |
| across all checkout repositories. | |
| - `--git-hooks` / `--no-git-hooks`: CLI flags for `fx agents setup` controlling Git hook | |
| management across checkout repositories (default: `--git-hooks`). Passing `--no-git-hooks` | |
| configures agent permissions and profiles while skipping hook installation and actively | |
| uninstalling any existing `20-fuchsia-agent.sh` hooks across checkout repositories. | |
| - `fx agents setup --reset` removes `20-fuchsia-agent.sh` while leaving dispatcher and user | |
| scripts intact. | |
| - `fx agents setup --reset --no-git-hooks`: Resets Fuchsia-managed rules and configuration while | |
| preserving existing Git hooks intact (skips hook uninstallation). | |
| ### 6.2 Interactive Rebase | |
| - **Automated Rebase Replay**: Git does not run `pre-commit` or `commit-msg` hooks when | |
| automatically applying commits during a rebase. | |
| - **Explicit Commits & Amends**: When a developer stops during an interactive rebase | |
| (`git rebase -i`) to edit, amend (`git commit --amend`), or insert a commit, Git executes the | |
| hooks normally. The staging engine ensures newly amended or inserted commits are cleanly formatted | |
| and verified without false merge conflicts or unintended hook bypasses. | |
| ### 6.3 Setup Configuration vs. Runtime Agent Detection | |
| Running `fx agents setup` configures the checkout, but hooks only apply agent-specific behavior when | |
| an agent is actually executing: | |
| - The presence of `~/.local/share/Fuchsia/agents/setup/state.json` indicates that `fx agents setup` | |
| configured the developer checkout, but does **not** mean an automated AI agent is executing a | |
| given commit. | |
| - Developers routinely perform manual `git commit` commands in repositories configured with | |
| `fx agents setup`. These interactive human commits receive human-oriented UX (`ConsoleReporter`, | |
| advisory warnings, colored summaries). | |
| #### How Agents Are Detected | |
| Runtime AI agent execution is detected dynamically at commit time using canonical environment | |
| variables: | |
| - **Agent Environment Detection**: Query `is_invoked_by_agent()`, which checks the canonical agent | |
| environment variables defined in `AGENT_ENV_VARS` (`ANTIGRAVITY_AGENT`, | |
| `ANTIGRAVITY_CONVERSATION_ID`, `GEMINI_CLI`, `ANTIGRAVITY_EDITOR_APP_ROOT`, `CLAUDECODE`, | |
| `CLAUDE_CODE_SESSION_ID`, `FFX_AGENT_SESSION_ID`). | |
| When active runtime agent execution is detected: | |
| - **Auto-Formatting**: Formats fully staged files in-place and re-stages them automatically. | |
| - **Strict Validation**: Runs `commit_msg_checker.py --strict` so non-compliant messages are | |
| rejected before reaching CQ. | |
| --- | |
| ## 7. Failure Policies & Performance | |
| ### 7.1 Failure Policies (Fail-Open vs. Fail-Closed) | |
| | Failure Mode | Policy | Action | Rationale | | |
| | ----------------------------------------------- | ----------------------------------------------------------- | ------------------------------------------------------- | ------------------------------------------------------------------------------------ | | |
| | **Missing Tool / Python Environment** | **Fail-Open** | Print warning to stderr; exit 0. | Never block commits due to environment setup issues. | | |
| | **Stash Restoration Failure** | **Fail-Closed** | Print recovery command; exit 1. | Prevent silent data loss or corrupted working trees. | | |
| | **Code Syntax / Formatter Error** | **Fail-Closed** | Print formatter error; exit 1. | Catch broken code before creating commits. | | |
| | **Partially Staged Formatting Error** | **Fail-Closed** | Print remediation hint; exit 1. | Avoid committing unformatted code or corrupting unstaged hunks. | | |
| | **Code Linting / Static Analysis (`fx lint`)** | **Fail-Closed** | Reject commit on lint findings (`fx format-code` formats files first). | Keep lint violations out of the tree; `FUCHSIA_SKIP_HOOKS=1` remains the escape hatch. | | |
| | **Commit Message Warnings** | **Fail-Open** (Human)<br>**Fail-Closed** (Agent) | Advisory warning for humans; error for agents. | Warn human developers without blocking commits; block commits from automated agents. | | |
| ### 7.2 Performance Optimizations | |
| - **Fast-Path Filter**: Skip invoking `fx format-code` and `fx lint` entirely if the staged partition contains | |
| zero formattable files. Supported extensions match | |
| [`DEFAULT_FORMATTABLE_EXTENSIONS`](../lib/githooks/adapters.py) (`.py`, `.md`, `.c`, `.cc`, | |
| `.cpp`, `.h`, `.hh`, `.hpp`, `.rs`, `.go`, `.fidl`, `.gn`, `.gni`, `.json`, `.json5`, `.cml`, | |
| `.proto`, `.ts`). | |
| - **Binary Handling**: `git diff --binary` and `git apply --binary` preserve binary content without | |
| corruption, while staged path filtering targets source file extensions directly. | |
| - **Commit Latency Target**: P50 commit overhead $< 600\text{ms}$; P90 $< 1,200\text{ms}$. | |
| --- | |
| ## 8. Troubleshooting & Manual Testing | |
| ### 8.1 Partially Staged Formatting Conflicts | |
| When a file contains both staged and unstaged hunks, mutating formatters cannot safely rewrite the | |
| file on disk without corrupting the unstaged hunks. If formatting issues are detected in partially | |
| staged files, the commit is blocked with instructions on how to fix it. | |
| Developers have three standard remediation paths: | |
| 1. **Stage remaining changes**: If the unstaged changes are ready, stage the whole file: | |
| ```bash | |
| git add <file> && git commit | |
| ``` | |
| 2. **Discard unstaged changes**: If the unstaged changes were accidental: | |
| ```bash | |
| git checkout -- <file> && git commit | |
| ``` | |
| 3. **Format and stage directly**: | |
| ```bash | |
| fx format-code --files=<file> && git add <file> && git commit | |
| ``` | |
| ### 8.2 Stash Restoration Recovery | |
| In the rare event that working tree restoration encounters an unexpected conflict or failure (e.g. | |
| external process modification during commit), `StashGuard` aborts and leaves the temporary stash at | |
| `stash@{0}`. The developer can inspect and recover the working tree using: | |
| ```bash | |
| git stash list | |
| git stash apply stash@{0} | |
| ``` | |
| ### 8.3 Manual & Direct CLI Testing | |
| Hooks can be tested directly without creating a Git commit: | |
| ```bash | |
| # Run pre-commit hook checks on current index: | |
| $FUCHSIA_DIR/scripts/fuchsia-vendored-python tools/agents/lib/githooks/runner.py pre-commit | |
| # Test commit-msg hook with a sample message file: | |
| $FUCHSIA_DIR/scripts/fuchsia-vendored-python tools/agents/lib/githooks/runner.py commit-msg path/to/COMMIT_EDITMSG | |
| # Simulate AI agent invocation: | |
| ANTIGRAVITY_AGENT=1 $FUCHSIA_DIR/scripts/fuchsia-vendored-python tools/agents/lib/githooks/runner.py pre-commit | |
| ``` |