JJ Workflow (Canonical)

Policy

• •For new PRs, use jj push-new (alias for jj git push --change @-) to create the bookmark and push it.
• •Do not run jj git push directly; use jj push for updates and jj push-new for new PRs.
• •Do not pre-create bookmarks for independent PRs. For stacked PRs, create a bookmark per layer so each PR has a stable head.
• •Avoid generating multiple new bookmarks for the same PR. If a bookmark already exists, move it and run jj push.
• •Only use jj abandon after confirming with the user; it is rare and usually indicates recovery from a bad state.
• •Enforce Conventional Commits for commit messages and PR titles. Format: type(scope optional)!: subject.
  • •Allowed types: feat, fix, docs, chore, refactor, test, build, ci, perf.
  • •Scope is optional; ! marks breaking changes.
  • •If the user supplies a non-conforming title/message, propose a compliant one and confirm before committing/creating a PR.
  • •If the merge strategy is squash, the PR title becomes the commit message; keep it Conventional.

Notes

• •@ is the working-copy commit; @- is its parent.
• •jj push (alias for jj git push @-) pushes the bookmark(s) pointing at @-. If @- has no bookmarks, use jj push-new instead.
• •jj push-new (alias for jj git push --change @-) creates a new bookmark and pushes it.
• •trunk() resolves to the repository's trunk bookmark and avoids guessing main vs master; wrap it in single quotes for shell safety.
• •When a revset includes parentheses (like trunk()), single-quote it.

Workflows

Initialize / clone:

• •jj git init [DESTINATION]
• •jj git clone <SOURCE> [DESTINATION]

Create a new change from trunk:

• •jj new 'trunk()'

Decide whether the work is independent or stacked:

• •Independent work must start from trunk() to avoid accidental stacking.
• •Stacked work intentionally builds on a prior change; each stack layer gets its own bookmark and PR.
• •Use an independent PR when the change does not depend on other unmerged work.
• •Use a stack when the overall effort is too large for one PR but can be split into self-contained, mergeable chunks.
• •Stack only when later changes rely on earlier unmerged work and reviewers benefit from smaller, focused slices.

Check where I am:

• •jj status

Check commit history:

• •jj log

View diff for current change:

• •jj diff (defaults to -r @)

Show full change details:

• •jj show <rev>
• •Use jj log -p -r <rev> for patch-view history.

New commit (new PR):

• •jj commit -m "type: message" (scope optional: type(scope): message)
• •jj push-new
• •If this PR was already pushed, move the existing bookmark and use jj push instead.

Independent PR (standalone) flow:

• •jj new 'trunk()'
• •Make changes → jj commit -m "type: message"
• •jj push-new
• •Create the PR with base master (or repo trunk) so GitHub shows only this change.

Stacked PR flow (multiple dependent changes):

• •Create each change as a separate revision in a chain.
• •Create a bookmark for each layer (example names: bede/1, bede/2):
  • •jj bookmark create <bookmark> -r <rev>
• •Push each bookmark:
  • •Move bookmark if needed: jj bookmark move <bookmark> --to <rev>
  • •jj push
• •Create PRs in order, setting the base of each PR to the previous layer’s bookmark/branch.

Unwind an accidental stack (PR shows unrelated commits):

• •jj git fetch
• •Identify the intended change (bookmark or revision): jj bookmark list or jj log -r <rev>
• •Rebase just that change onto trunk:
  • •jj rebase -r <rev> -A 'trunk()' --ignore-immutable
• •Move the bookmark to the rebased change (use @- if it is the parent of the working copy):
  • •jj bookmark move <bookmark> --to @-
• •Push the updated bookmark:
  • •jj push
• •Ensure the PR base is trunk (update via gh pr edit --base <trunk-branch> if needed).

Add a commit to an existing PR/stack (reuse existing bookmark):

• •jj commit -m "type: message" (scope optional: type(scope): message)
• •jj status (identify the existing push-... bookmark for the current change)
• •If multiple push-... bookmarks are shown, ask which PR/bookmark to update.
• •jj bookmark move <bookmark-name> --to @-
• •jj push
• •If no bookmark exists yet, do not create one manually; use jj push-new.

Amend current change content:

• •jj squash (move working-copy changes into parent)

Split a change:

• •jj split

Squash/merge changes in a stack:

• •jj squash [--from <rev>] [--into <rev>]

Abandon a change:

• •jj abandon [REVSET]

Restore a file to parent state:

• •jj restore <path>
• •Restore a file from trunk:
  • •jj restore --from 'trunk()' -- <path>

Resolve conflicts:

• •jj resolve [FILESETS]...

Recover from a bad state (operation log):

• •Use when repo state is messed up (bad merges/conflicts/accidental rebase).
• •Prefer jj op log + jj op restore over manual rebases when unsure.
• •jj op log (see recent operations; each op snapshots repo state)
• •Optional preview: jj --at-op=<op-id> log
• •jj undo (undo the most recent operation)
• •jj redo (redo the most recently undone operation)
• •jj op restore <op-id> (restore repo state to a specific operation)
• •jj op revert <op-id> (revert a specific earlier operation)

Sync with trunk:

• •jj git fetch
• •jj rebase -d 'trunk()'

Rebase a stack onto trunk (move a change and all its descendants):

• •jj rebase -r <rev>:: -A 'trunk()' --ignore-immutable