jujutsu

Jujutsu for Agents

Core Concepts

Working copy is a commit. Every file edit auto-snapshots into @. No staging area.

Change IDs persist. Always reference Change IDs (e.g., zsowkzkt), not commit hashes. IDs survive rebases.

Conflicts don't halt. jj records conflicts in commits; fix them later.

Quick Reference

Workflow Patterns

Basic Loop

# 1. Edit files (auto-snapshots)
# 2. Name the work
jj describe -m "feat: add feature"
# 3. Seal and continue
jj new

Edit Mid-Stack

# Find and jump to target
jj edit <change_id>
# Make edits (auto-snapshots)
# Return to tip
jj edit <tip_id>
# Verify no conflicts
jj log -r '::@' --template 'change_id " " conflict "\n"'

Post-Merge Sync (after GitHub merges)

jj has no git pull --rebase equivalent. After a PR is merged on GitHub:

# 1. Fetch the merged commit
jj git fetch

# 2. Rebase remaining work onto new main
jj rebase -s <oldest-unmerged-change-id> -d main

Important: Always use gh pr merge --rebase (not --squash). With rebase-merge, jj recognizes the commit is on main. Squash-merge creates a new hash, leaving orphaned "zombie" commits.

Forbidden Commands

• jj split — requires TUI, use construction method
• jj resolve — requires TUI, parse and rewrite conflict markers manually

Quality Gates

This project uses jj fix for auto-formatting and custom aliases for verification.

Philosophy

• Category A (formatters): Run jj fix anytime — auto-applies ruff, prettier, buf format
• Category B (verifiers): Run jj secure-push before pushing — runs all linters, type checkers, tests

Commands

Workflow Integration

# While coding: format often
jj fix

# Before pushing: verify everything
jj secure-push --bookmark my-feature

# Quick sanity check (no tests)
jj quality

What Runs

jj fix: ruff-format, ruff-fix (isort/pyupgrade), prettier, buf format

jj secure-push: buf lint → pyright → eslint → prettier check → angular build → pytest → vitest → playwright → e2e → generated code check → push

Detailed Protocols

See references/workflows.md for:

• State verification protocols
• Non-interactive splitting techniques
• Post-merge sync workflow
• Conflict resolution steps
• Safety and recovery operations

See references/divergent-changes.md for:

• Identifying divergent changes (multiple commits with same change ID)
• Resolution strategies: abandon, give new ID, squash, or ignore
• Common causes and prevention