gerrit-checkout 0.5.3__tar.gz

gerrit_checkout-0.5.3/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

gerrit_checkout-0.5.3/PKG-INFO

@@ -0,0 +1,259 @@
+Metadata-Version: 2.4
+Name: gerrit-checkout
+Version: 0.5.3
+Summary: Fetch and checkout Gerrit changes by topic
+Home-page: https://github.com/example/gerrit-checkout
+Author: Tharindu Piyasekara
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Environment :: Console
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: rich>=10.0.0
+Dynamic: author
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# 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
+
+```bash
+pip install git+https://github.com/example/gerrit-checkout.git
+```
+
+For local development:
+
+```bash
+pip install -e . --force-reinstall --no-deps
+```
+
+Python dependency (`rich`) is installed by pip. `git` and `ssh` must be available on your system.
+
+## Usage
+
+```bash
+gerrit-checkout --init-config [--gerrit-server SERVER]
+gerrit-checkout <topic|change-number|url> [--gerrit-server SERVER] [--repo PATH] [-v] [--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
+- `-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
+
+```text
+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:
+
+```ini
+[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.
+
+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` builds explicit dependency components from current revision parents. It finds every stale parent edge and adds only the open descendants in that component. Each component is ordered bottom-to-top; independent components 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
+
+```bash
+# By topic name
+gerrit-checkout FEATURE-1234
+
+# 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
+
+```bash
+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.
+
+## License
+
+MIT

gerrit_checkout-0.5.3/README.md

@@ -0,0 +1,229 @@
+# 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
+
+```bash
+pip install git+https://github.com/example/gerrit-checkout.git
+```
+
+For local development:
+
+```bash
+pip install -e . --force-reinstall --no-deps
+```
+
+Python dependency (`rich`) is installed by pip. `git` and `ssh` must be available on your system.
+
+## Usage
+
+```bash
+gerrit-checkout --init-config [--gerrit-server SERVER]
+gerrit-checkout <topic|change-number|url> [--gerrit-server SERVER] [--repo PATH] [-v] [--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
+- `-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
+
+```text
+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:
+
+```ini
+[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.
+
+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` builds explicit dependency components from current revision parents. It finds every stale parent edge and adds only the open descendants in that component. Each component is ordered bottom-to-top; independent components 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
+
+```bash
+# By topic name
+gerrit-checkout FEATURE-1234
+
+# 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
+
+```bash
+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.
+
+## License
+
+MIT

gerrit_checkout-0.5.3/gerrit_checkout/__init__.py

@@ -0,0 +1,5 @@
+"""Gerrit Checkout - Fetch and checkout Gerrit changes by topic."""
+
+__version__ = "0.5.3"
+__author__ = "Tharindu Piyasekara"
+__email__ = ""