---
name: git-cl
trigger: always_on
---

# Git CL Conventions

These rules ensure correct usage of the Chromium-specific `git cl` tool in V8.

## Git Command Usage (git cl)

- **Always Format**: Run `git cl format` before creating a commit or uploading a
  CL.
- **Uploading to Gerrit**:
  - **Wrap Commit Message**: Ensure commit message descriptions are strictly
    wrapped at 78 characters.
  - **Always use `-t` and/or `--commit-description`** for `git cl upload`
    instead of the deprecated `-m` flag, to avoid interactive editors.
  - **Ensure Non-Interactive Behavior**: When committing, amending, or uploading
    (e.g., `git cl upload`), prefix the command with `EDITOR=cat` (e.g.,
    `EDITOR=cat git cl upload`) if there is a risk of an editor opening.
  - **Upload Script**: All uploads MUST be performed using
    `agents/scripts/upload_cl.sh <new|cur> <check|nocheck> [patchset_message]`.
    This script helps to manage the upload.
  - **Initial Upload**: For a new CL without an existing issue association,
    execute `agents/scripts/upload_cl.sh new check`.
  - **Subsequent Uploads**: For updating an existing patchset, run
    `agents/scripts/upload_cl.sh cur check "Brief patchset description"`.
  - **Checks**: The "check" flag runs all mjsunit tests. When no code was
    updated, or tests were already successfully ran, "nocheck" can be passed.
  - **Updating Description**: If the changes in a new patchset make the existing
    CL description **out-of-date** or inaccurate, you **MUST** explicitly update
    it by passing `--commit-description="New cohesive description content"`.
    **⚠️ CRITICAL SAFETY CONSTRAINT**: Before passing `--commit-description` or
    updating it on a subsequent upload, you must first inspect the live remote
    description on Gerrit (using either `git cl desc -d` or the
    `gerrit_get_change_details` MCP tool) to verify whether the user has
    manually edited it. If manual user edits or refinements are detected, you
    must carefully evaluate them: preserve any human-authored background
    context, rationale, or formatting, while surgically updating only the
    outdated technical statements resulting from the new patchset.
  - Verify `git diff` is not empty before uploading.
- **Safeguards & Code Quality**:
  - **Mandatory Reproducer Rule**: Before running `git cl upload`, you MUST
    verify that the diff contains a valid, working regression test (typically
    under `test/mjsunit/` or its component-specific subfolders like `compiler/`,
    `turboshaft/`, `maglev/`, etc.). Uploading code-modifying CLs without an
    accompanying regression test is strictly forbidden (unless explicitly waived
    by the user or if it's a process-only/documentation change).
  - **No Trailing Whitespace**: NEVER add trailing whitespace in any file you
    create or modify.
  - **Always Test Before Upload**: Always run tests (using `release` or
    `optdebug` mode, avoiding `debug` mode due to performance) before uploading.
  - **ALWAYS keep CLs separate**: If you are working on more than one task at
    the same time always use `agents/scripts/create_worktree.sh <task_id>` to
    create an isolated workspace for each independent task or CL. Worktrees are
    created at `REPOSITORY_ROOT/worktrees/`. NEVER upload a CL from a workspace
    containing unrelated modifications. Always verify that the diff relative to
    upstream contains ONLY the intended changes before uploading.
  - **Consult user on external changes**: When `git cl upload` detects external
    changes on Gerrit and prompts to fetch them or override, the agent MUST stop
    and ask the user for guidance, unless explicitly instructed otherwise.
  - **Verify Isolation Strategy**: Before performing any CL operations, ensure
    you have consulted the user regarding the isolation strategy as defined in
    the `v8-workflow` skill (e.g., branch vs. worktree).
  - **Preserve Issue Number**: Preserve the issue number when reusing a CL
    instead of running `git cl issue 0`.
  - **Verify Issue Description**: Before uploading, run `git cl status` to
    verify the Issue Description matches your task.
  - **Review Modified Files**: Review the modified files (`git show --stat`) or
    run `git diff --name-only origin/main..HEAD` to ensure no unrelated files
    are included. If you see commits or files that are not part of your specific
    task, reset your branch to `origin/main` and cherry-pick only your intended
    commits instead of uploading.
  - **Verify Alignment**: Verify alignment of the subsystem/context in
    `git cl status` before proceeding, and consult the user if it seems
    mismatched.
  - **Process-Only CLs**: For CLs intended to contain ONLY process/documentation
    changes, verify that no code files (e.g., `.cc`, `.h`, `.js`, `.py`) are
    modified using `git diff --name-only origin/main`.
- **Proactive Alert Handling**: Always run `git cl status` after uploading. If
  you identify failing checks or try jobs, proactively suggest addressing these
  alerts to the user.
- **Post-Upload**: Provide the `chromium-review.googlesource.com` link to the
  user.
- **Retrieving and Addressing Comments**:
  - Use this rule when asked about retrieving, addressing, reviewing, or fixing
    comments on the current CL.
  - If a CL number is specified, check first that it matches the current
    associated CL ID (find with `git cl issue`).
  - If there is no associated CL, ask the user whether you should associate it
    first with `git cl issue <cl_number>`.
  - Once associated (or if using current), fetch comments using
    `git cl comments`.
  - Note: If you have access to a dedicated tool for reviewing comments (e.g., a
    Gerrit MCP tool), prefer using that instead of `git cl comments`.

## Stacked CL Workflow

When working on a chain of dependent changes (stacked CLs):

- **Upstream Configuration**: Set the upstream of a child branch to its parent
  branch (e.g., `git branch --set-upstream-to=parent-branch`). The base branch
  at the bottom of the stack tracks `origin/main`.
- **Rebasing**: When the parent branch changes, rebase the child branch on top
  of the updated parent.
- **Unique Change-Ids**: Ensure each CL in the stack has a unique `Change-Id`.
  Make sure to remove `Change-Id` from commit messages of new CLs.

## Helpful Commands

- Use `git cl patch <CL_NUMBER>` to fetch and checkout the latest patchset of a
  CL.
- Use `git cl land` to land the CL after approval.
- Use `git cl desc -d` to view the CL description.
- Use `git cl desc -n` to write a new CL description.
