Forklift

Forklift is a local CLI/TUI for keeping long-lived forks current. It finds the fork's current upstream base, chooses the next upstream target, rebases your custom commits, runs your local checks, and writes a report with the exact files, commits, checks, and branch changes.

detect-upstream-base -> target discovery -> rebase-assistant -> local-test-runner

Install

uv tool install forklift-ai

or:

pipx install forklift-ai

The primary command is:

forklift

auto-rebase is kept as a compatibility alias.

Quick Start

Run these inside your forked repository:

forklift init
forklift doctor
forklift detect-base
forklift run

forklift init writes .auto-rebase.yaml and opens a guided setup form when the terminal is interactive. The form auto-loads local remotes, remote-tracking branches, tags, tag patterns, and likely test commands.

For later edits:

forklift config edit

What forklift run Does

1. refuse to start if the working tree has unrelated local changes
2. detect the fork's current upstream base
3. resolve the target upstream tag or branch
4. run baseline checks before rebasing
5. create a local backup branch
6. rebase your custom commits onto the target
7. run post-rebase checks
8. apply the successful rebase back to your original branch
9. show a run screen with the result and push decision
10. write artifacts and a final summary

If use_worktree: true is enabled, Forklift does the risky work in a temporary worktree first. When the post-rebase checks pass, it moves your original branch to the successful rebased HEAD and removes the temporary run branch.

The CLI prints the important result directly:

Forklift run complete
- status: healthy
- branch: test_branch
- base: v1
- target: v2
- custom commits replayed: 4
- changed files: 7
- local branch updated: yes
- backup branch: auto-rebase/backup-...

Checks
- baseline/tests: passed (0)
- post_rebase/tests: passed (0)

Next step
- remote branch updated: no
- push rebased branch: git push --force-with-lease origin test_branch

status=healthy
report=.auto-rebase/artifacts/.../summary.md

In an interactive terminal, forklift run opens a TUI that shows the local result and asks whether to push the rewritten branch. Forklift never pushes silently. A successful rebase rewrites local commit IDs, so remote updates require an explicit confirmation and use --force-with-lease.

For scripts or raw terminal output:

forklift run --plain

Configuration

The generated .auto-rebase.yaml is intentionally small enough to review:

project:
  name: forklift

auto_rebase:
  target_mode: latest_tag
  explicit_target: null
  max_iterations: 5

detect_upstream_base:
  upstream_remote: upstream
  upstream_branch: main
  tag_pattern: "v*"

local_test_runner:
  baseline_required: true
  checks:
    - name: tests
      run: "uv run --extra dev pytest -q"
      timeout_minutes: 20

forklift init overwrites an existing .auto-rebase.yaml with a clean generated file. Use forklift config edit when you want to update it later.

Artifacts

Every run writes a timestamped folder under .auto-rebase/artifacts/:

detection/      current base, base tag, custom commits, patch
target/         selected target ref and upstream diff
measurement/    baseline and post-rebase command logs
controller/     rebase logs, conflicts, repair packets, apply logs
summary.md      branch update, commits, conflicts, files, check results
replay.sh       manual reproduction script

The newest run is also linked at .auto-rebase/artifacts/latest/.

Safety

Forklift is local-first and conservative:

• refuses dirty working trees by default
• creates a backup branch before rebasing
• never pushes without explicit confirmation
• only updates the original branch after post-rebase checks pass
• keeps failed/conflicted worktrees available for inspection
• redacts common secret variables from logs and repair packets

Development

uv run --extra dev pytest
uv run --extra dev ruff check .
uv build --no-sources

Verify a built wheel through the tool-install path:

UV_TOOL_DIR=/tmp/forklift-tool \
UV_TOOL_BIN_DIR=/tmp/forklift-tool-bin \
uv tool install dist/forklift_ai-0.1.0-py3-none-any.whl

/tmp/forklift-tool-bin/forklift init