gerrit-checkout

Fetch and checkout Gerrit topic changes across a single git repository or a repo-tool workspace.

The tool understands Gerrit parent relationships and can:

• keep only top changes per repository when parent changes are already included by ancestry
• discover related parent topics that are still needed for a complete local checkout
• show a dry-run execution plan with lineage to master
• build a complete dependency graph across recursively linked topics
• safely preflight, store, and push a full affected rebase chain

Installation

pip install git+https://github.com/example/gerrit-checkout.git

For local development:

pip install -e . --force-reinstall --no-deps

Python dependency (rich) is installed by pip. git and ssh must be available on your system.

Usage

gerrit-checkout --version
gerrit-checkout --init-config [--gerrit-server SERVER]
gerrit-checkout <topic|change-number|url> [--gerrit-server SERVER] [--repo PATH] [-v] [--comments] [--plan | --html-report [PATH] | --rebase [--push] | --push]

The first positional argument accepts:

• a topic name — fetches all open changes in that topic
• a change number — fetches that specific change; if it belongs to a topic the full topic is loaded, otherwise the change is used directly as the dependency seed
• a full Gerrit URL — e.g. https://gerrit.example.com/c/example/platform/test/+/12345

Note: Change numbers are globally unique within a Gerrit server, so 12345 always refers to the same change regardless of which project it belongs to.

Options

• --gerrit-server: Gerrit server hostname (overrides config for this run only)
• --repo: Git repository or repo-tool workspace path (default: current directory)
• --init-config: Create ~/.gerrit-checkout.cfg with default values
• --version: Print the installed gerrit-checkout version and exit
• -v, --verbose: Enable verbose traceback output on failures
• --plan: Preview the checkout and rebase plans. It queries Gerrit and may fetch metadata, but does not checkout, rebase, or push.
• --html-report [PATH]: Write the preview as HTML, optionally at PATH. It does not checkout, rebase, or push.
• --rebase: Preflight the complete affected chain bottom-to-top in temporary worktrees and store validated local Git refs only if every rebase succeeds.
• --push: Validate and push previously stored refs to Gerrit. With --rebase, push only after the complete preflight succeeds.

--plan and --html-report are preview-only modes and cannot be combined with --rebase or --push. --rebase and --push are compatible and may be used together.

Compatibility note: --dry-run remains an alias for --plan. The older --rebase-check, --check-rebase, --auto-rebase, and detailed report flags remain available for compatibility.

Command effects

gerrit-checkout TOPIC
    Local working-tree changes. Fetches and checks out planned changes.

gerrit-checkout TOPIC --plan
    Preview only. Queries Gerrit and may fetch metadata, but does not checkout,
    rebase or push.

gerrit-checkout TOPIC --html-report [PATH]
    Preview only. Writes an HTML report locally but does not checkout, rebase
    or push.

gerrit-checkout TOPIC --rebase
    Local Git metadata changes. Uses temporary worktrees and creates validated
    local Git refs. Does not change the main working tree or push to Gerrit.

gerrit-checkout TOPIC --push
    Remote Gerrit changes. Validates and pushes previously stored rebases.

gerrit-checkout TOPIC --rebase --push
    Remote Gerrit changes. Preflights the complete affected chain bottom-to-top
    and pushes only when every rebase succeeds. A conflict or validation failure
    pushes nothing.

Server value precedence:

1. --gerrit-server (CLI override, current run only)
2. ~/.gerrit-checkout.cfg -> [gerrit].server

If no server is set in either place, the command exits with an error.

Note: gerrit.example.com in the config template below is a sample only. Update it to your actual Gerrit hostname.

Config file

--init-config creates this file:

[gerrit]
server = gerrit.example.com
repo_path = .

For one-step setup, run gerrit-checkout --init-config --gerrit-server YOUR_HOST.

If the config file already exists, --init-config updates it.

What It Does

For a source topic, the tool will:

1. query every open Gerrit change in the source topic
2. recursively discover open parent topics and build one complete dependency graph
3. group changes by normalized project and target branch, split them into connected components, and identify every component head
4. independently build a rebase plan containing every affected open change
5. either report the plans, checkout the repository leaves, or safely preflight the rebase chain

By default, mutations are limited to git fetch, checkout, temporary preflight worktrees, and tool-managed refs. Push happens only when --push is used.

With --comments (also available as --download-comments), each affected local repository receives a pretty-printed .gerrit-comments.json file after a successful normal checkout. Without the flag, checkout behavior is unchanged. For topic input it consolidates only changes directly in that topic; for a change number or URL it includes only that requested change. Supporting parent changes discovered for checkout are excluded. Entries are grouped by change, reviewed file, and unresolved thread. Complete conversations are retained for unresolved threads, so the file is both machine-readable and useful in an ordinary text editor. The report is replaced atomically on each checkout to avoid stale entries and invalid partial JSON. Gerrit REST authentication uses the configured Git cookie file (or ~/.gitcookies) and ~/.netrc credentials through curl.

A connected chain in one repository is represented by checking out its head. If a repository has multiple independent heads, preview modes show all of them, while normal checkout stops with a clear error because one worktree cannot represent multiple independent histories. Use separate worktrees manually for those heads.

Output

Preview plan

--plan prints a unified table that includes:

• source-topic top changes
• related-topic changes that are already covered by the source topic
• related-topic changes that still need local checkout
• a relation tree showing how each change reaches master
• stale parent issues and rebase status
• which changes would be rebased and which are blocked

Use --html-report [PATH] to write the preview to an HTML file for easier reading.

Rebase status

The rebase status view marks each change as one of:

• rebased on latest open parent
• parent already merged to master
• warning: needs rebase
• warning: parent unresolved

When stale parents are found, the tool prints a warning summary after the table.

Rebase

--rebase refreshes the target branch, builds explicit dependency components from current revision parents, and rebases every component root onto the latest branch tip when needed. It also finds every stale Gerrit parent edge and adds only the open descendants in that component. Each component is ordered bottom-to-top; independent components are rebased separately and are never stacked onto one another.

• every patch set and parent ref is fetched and checked against the revision returned during planning
• each change is replayed in a disposable Git worktree; the user's current branch, index, and files are not changed
• each child is replayed onto the newly generated commit for its parent
• Gerrit Change-Id footers are verified before and after every replay
• unresolved parents, merge commits, conflicts, and rebase failures block the operation and return a non-zero exit code
• a conflict names the failing change and every blocked descendant; no changes are pushed
• local tool-managed refs are stored only after the complete graph passes preflight

Push

--push publishes previously rebased local changes in bottom-to-top order.

• before the first push, every stored result is checked against its original Gerrit revision, its validated parent, its current Gerrit patch set, and its Change-Id
• a missing, stale, or modified local ref prevents all pushes and returns a non-zero exit code
• pushes stop immediately if Gerrit rejects any change; later descendants remain unpushed
• successfully pushed local refs and their validation metadata are cleaned up automatically

Safety and exit status

Preflight may fetch Gerrit objects and create temporary worktrees, but it never checks out or rebases in the user's working tree. Temporary worktrees are removed whether a replay succeeds or conflicts. No Gerrit push starts until every affected change has passed preflight and every stored ref has passed freshness validation.

The command exits non-zero for unresolved dependencies, conflicts, rebase failures, stale stored refs, push failures, and descendants blocked by any of those failures. A preview also exits non-zero when it reports unresolved rebase dependencies, which makes it suitable for CI validation.

Examples

# By topic name
gerrit-checkout FEATURE-1234

# Show the installed version (useful in bug reports)
gerrit-checkout --version

# By change number
gerrit-checkout 12345

# By full Gerrit URL
gerrit-checkout "https://gerrit.example.com/c/example/platform/test/+/12345"

# Preview the full checkout plan (no actual fetch/checkout)
gerrit-checkout FEATURE-1234 --plan

# Write preview output to the default HTML report location
gerrit-checkout FEATURE-1234 --html-report

# Write preview output to an explicit path
gerrit-checkout FEATURE-1234 --html-report gerrit-checkout-report.html

# Rebase stale changes locally in dependency order
gerrit-checkout FEATURE-1234 --rebase

# Push previously rebased changes
gerrit-checkout FEATURE-1234 --push

# Rebase now and push immediately after
gerrit-checkout FEATURE-1234 --rebase --push

# Use an explicit Gerrit host for one run
gerrit-checkout FEATURE-1234 --gerrit-server gerrit.example.com

# Create default config once
gerrit-checkout --init-config --gerrit-server gerrit.example.com

Requirements

• Python 3.7+
• Git
• SSH access to Gerrit

Uninstall

python3 -m pip uninstall -y gerrit-checkout && rm -f ~/.gerrit-checkout.cfg

0.5.2

The 0.5.2 release validates that every rebase candidate maps to exactly one Git commit before replay. It rejects multi-commit ranges and unsupported merge or root commits, then verifies the new parent, changed paths, commit message, and Gerrit Change-Id before storing refs or allowing a push. Rebase output now distinguishes topic changes, supporting parents, dependency chains, replayed commits, stored ref sets, and pushed changes.

0.5.4

The 0.5.4 release retains exact intermediate Gerrit parent changes in one canonical graph. Transitive chains now produce only their true checkout head, while genuinely independent histories and stale/non-current patch-set links remain explicit. Terminal and self-contained HTML previews include all direct and supporting nodes, repository paths, checkout targets, rebase order, blockers, and matching summary counts.

0.5.5

The 0.5.5 release makes every HTML report filter dropdown responsive and readable for long topics, repository names, and paths. Native checkboxes keep their intrinsic size, option text wraps without clipping, menus stay within narrow and zoomed viewports, and labelled controls preserve keyboard navigation with Escape-to-close focus restoration.

0.5.6

The 0.5.6 release fixes linked-topic planning across repositories. Gerrit topic expansion now builds the complete recursive cross-project closure before component grouping or repository filtering. Terminal and HTML reports consume the same canonical plan with matching changes, topics, projects, local paths, dependency relationships, checkout heads, rebase candidates, and skipped reasons.

0.5.7

The 0.5.7 release makes Gerrit dependency discovery easier to follow and faster across repeated queries. It prints one concise dependency-resolution status message and reuses the SSH connection for topic, revision, and change-number lookups.

0.5.8

The 0.5.8 release rebases every independent same-repository topic component onto the refreshed target branch tip without stacking unrelated changes. It fails closed when the target branch cannot be refreshed and revalidates the branch tip immediately before push so an advancing branch cannot receive stale rebases.

0.5.9

The 0.5.9 release prevents merged supporting changes from entering rebase mutation plans. Merged nodes remain visible for dependency reporting, while only their open descendants are rebased onto the refreshed target branch tip.

0.5.10

The 0.5.10 release keeps recursive topic discovery while retaining only the Git-connected component containing each exact resolved parent. Unrelated changes that merely share a discovered topic no longer inflate reports, become checkout heads, or enter rebase analysis; legitimate connected parents across multiple source repositories continue to resolve recursively.

0.5.11

The 0.5.11 release restores cross-repository changes from recursively discovered dependency topics to the checkout plan, while continuing to filter disconnected Git histories within the resolved repository. It also adds gerrit-checkout --version and documents it in command help and usage examples.

0.5.12rc1

This release candidate adds super-repo support. When manifest/default.xml is absent and .gitmodules is present, normal checkout initializes submodules recursively and maps Gerrit projects to their submodule paths. Relative submodule URLs are matched safely against fully qualified Gerrit project names, including initialized nested submodules. Preview modes remain non-mutating.

License

MIT