tree: 9eb96be5dc5a910e0513c9ceaa663c6fce695e6e [search]
  1. src/
  2. BUILD.bazel
  3. BUILD.gn
  4. OWNERS
  5. README.md
tools/revert/README.md

fx revert

fx revert is a host tool that orchestrates pure reverts of submitted Gerrit changes across Fuchsia repositories (e.g. fuchsia.git and vendor/google).

It generates authentic Gerrit server-side reverts via Gerrit's REST API, ensuring that Rubber Stamper (rubber-stamper@appspot.gserviceaccount.com) automatically recognizes the reverts and approves them with Bot-Commit +1 / Code-Review +2.


Features

  • Mechanical Single-CL Reverts: Reverts a single merged Gerrit change via Gerrit's /revert REST endpoint. The change must be MERGED; its Depends-on footers are reported but related changes are not reverted automatically.
  • Rubber Stamper & Auto-Submit Integration: Adds Rubber Stamper as a reviewer and optionally applies Fuchsia-Auto-Submit +1 for hands-off tree unblocking.
  • Structured Commit Messages: Properly formats standard Gerrit revert metadata including Reason for revert:, Failure Link:, and Bug: references.

Installation & Setup

//tools/revert:install is part of the //tools group. If your build does not include it, add it explicitly:

fx set ... --with-host //tools/revert:install

To build only the tool and its unit tests:

fx build --host //tools/revert:install //tools/revert:tests

Repository Impact & Requirements

fx revert operates entirely through Gerrit's REST API (gob-curl or plain curl). It does not read or modify any local Git repository:

  • Checkout freshness and branch: You do not need an up-to-date checkout, and you do not need to be on origin/main. A checkout that lags behind origin has no effect on the result, because the change metadata and the revert itself come directly from Gerrit.
  • Working tree, branches, and local commits: The tool is completely unaffected by uncommitted or staged edits, local branches, a detached HEAD, or local commits, and never touches any of them.
  • Gerrit credentials: Gerrit requests are authenticated with gob-curl when it is installed. Otherwise fx revert prints a warning and falls back to plain curl with ~/.netrc and ~/.gitcookies; requests to internal hosts or authenticated endpoints may fail without valid cookies.
  • Repository state after running: Your local repositories are 100% unchanged. Revert CLs are created only on Gerrit; to work on one locally, fetch it from Gerrit like any other CL.

Usage

1. Dry Run (Preview Plan)

Always preview the revert plan before executing. Running without --upload only prints the plan (dry-run mode is the default):

fx revert <gerrit_url> --dry-run

Example:

fx revert https://fuchsia-review.googlesource.com/c/fuchsia/+/1783117 \
  -m "Reverting suspect CL due to builder failure of core.arm64-debug" \
  -f "go/bbid/8672361213915190673" \
  -b "12345" \
  --dry-run

2. Execute a Pure Revert via REST API

Upload the revert to Gerrit with Rubber Stamper reviewer:

fx revert <gerrit_url> \
  -m "<reason>" \
  -f "<failure_link>" \
  -b "<bug_id>" \
  --upload

The full plan summary is always printed before any Gerrit API calls are made.

3. Auto-Submit (+1)

To automatically set Fuchsia-Auto-Submit +1 on the created revert CL:

fx revert <gerrit_url> \
  -m "Reverting broken build" \
  -f "go/bbid/..." \
  --upload \
  --auto-submit

Options & Arguments

  • <gerrit_url>: Positional (Required). Full Gerrit URL to the change (e.g. https://fuchsia-review.googlesource.com/c/fuchsia/+/123456).
  • -m, --reason: Custom reason for the revert in the commit message.
  • -f, --failure-link: Link to builder failure, log, or test failure (e.g. go/bbid/... or https://ci.chromium.org/...).
  • -b, --bug: Associated Buganizer issue tracker ID (e.g. 12345 or b/12345).
  • --upload: Create and upload the revert CL via Gerrit REST API with Rubber Stamper reviewer. Without this flag, the tool runs in dry-run mode.
  • --dry-run: Preview the planned revert without executing API calls.
  • --auto-submit: Apply Fuchsia-Auto-Submit +1 vote to the created revert CL (default: off).
  • -h, --help: Display usage and help information.

Running Unit Tests

Run unit tests via fx test:

fx test //tools/revert:tests --host