VCS JJ
Jujutsu working-copy, change, workspace, bookmark, remote, and recovery practice.
39 items in this guidance cluster.
Tagged guidance
Guide item
Agent workflow rules
Isolate workspaces by taskPut separable or parallel agent work in its own workspace or source-control lane. Isolation keeps diffs, validation, and ownership clear when multiple changes are in flight.Preserve human workInspect and protect unrelated local edits before changing files. Preserving human work keeps the task diff focused and avoids destroying unfinished or intentional changes.
Change shape rules
Preserve unowned workTreat nearby edits from users, agents, generators, or earlier changes as outside your ownership unless the task says otherwise. Adapting around them protects parallel work and context.Use one purpose per changeShape each change around one review question and one reason for existing. Related tests, docs, and generated files can travel with it when they support that same purpose.
VCS rules
Ask before repairing JJ aliasesAsk before changing jj aliases when they disagree with the observed repository topology. Aliases encode workflow policy, so silent repairs can alter future user commands.Avoid interactive JJ in agent workUse noninteractive jj commands with explicit messages, targets, and files in agent work. Interactive editors, prompts, merge tools, and pagers can hang unattended sessions.Configure JJ pagerScope pager control with --no-pager, JJ_PAGER=cat, or session configuration. Direct output keeps source-control evidence visible without changing the users global pager.Confirm broad JJ operationsConfirm jj operations that abandon, rebase, squash, split, restore, publish, or go broad. Confirmation protects unrelated work when a command can reshape history or public state.Confirm GitHub remote topologyInspect origin, upstream, push remote, PR base, and PR head before publication. Fork and owned-repo layouts differ, so defaults can push or target the wrong repository.Create an operation log point before reshapingCreate a recent jj operation boundary before risky stack reshaping. Recovery is easier when there is a known point before rebases, splits, squashes, or repairs.Do not fall back to Git for JJ issuesDiagnose jj locks, pager issues, and state problems through jj before switching tools. Git bypasses jj change-graph semantics, so use it only for transport after jj state is coherent.Dry run surprising publicationUse dry-run for ambiguous or surprising remote publication, not every routine push. Extra verification pays off when remotes, bookmarks, force-like updates, or PR bases are unclear.Duplicate for alternative candidatesUse jj duplicate when two plausible fixes or refactors need independent validation. Separate candidate changes preserve comparison and recovery without mutating the only option.Inspect sparse stateCheck sparse checkout state before treating a missing path as absent from history. Sparse patterns can hide files, so inspection prevents recreating or editing the wrong path.Inspect state before mutatingInspect working-copy, stack, bookmark, conflict, and unowned state before mutation. Current state keeps edits scoped and avoids rewriting work the agent did not inspect.JJ as source of truthUse jj for local workflow in repositories with .jj state. This preserves descriptions, stack shape, operation-log recovery, and bookmark semantics.JJ new for review lanesStart unrelated review units with jj new before edits accumulate. Separate changes keep review atomic while leaving later squash or absorb decisions easy.Make GitHub handoff explicitName bookmark, remote, base, head, and repo when handing coherent jj state to GitHub. Explicit publication avoids host-tool inference mistakes in forks, stacks, and multi-remote repos.Match JJ topology to repo roleAlign fetch remotes, push remotes, tracked bookmarks, aliases, and PR bases to repo role. Owned, maintainer, and fork-only workflows need different topology assumptions.Name exact JJ mutation targetsSpecify revisions, filesets, bookmarks, and destinations for mutating jj commands. Explicit targets make intent reviewable and prevent defaults from acting on surprising state.Quote revsets and shell syntaxQuote jj revsets, bookmark syntax, and other shell-sensitive command fragments. Shell metacharacters can alter commands, so examples should prefer simple safe quoting.Recover with operation logUse jj operation-log recovery before destructive cleanup habits. The operation log preserves recoverable graph states, but inspect the target before restoring.Repair remote topology coherentlyRepair fetch, push, tracking, trunk alias, PR base, and PR head assumptions together. Remote topology is coupled, so partial fixes can leave publication commands half-correct.Run JJ mutations sequentiallyDo not overlap jj commands that write repo, working-copy, bookmark, or config state. Sequential mutations avoid locks, stale reads, and confusing operation order.Scope JJ file trackingPass intended paths to jj file track and jj file untrack. Scoped tracking keeps local-only, generated, or unrelated files out of publication state.Stop repeated JJ retries and localize stateStop repeating a failing jj command after a transient retry and inspect relevant state. Diagnosis beats command spam when locks, sparse paths, bookmarks, or remotes disagree.Track remotes explicitlySet explicit remote tracking when the same bookmark name exists on multiple remotes. This prevents fetch, rebase, and publication ambiguity in fork and upstream workflows.Treat bookmark remote syntax as version sensitiveVerify bookmark@remote and remote-bookmark syntax against the installed jj version. Durable guidance should avoid assuming one spelling works across commands and releases.Use evolog and operation logUse jj evolog for a changes evolution and jj op log for repository operations. Picking the right log distinguishes rewrite history from workspace, bookmark, and import events.Use Git-formatted diffs for agentsPrefer jj diff --git when agents or patch-oriented tools need diff text. Git patch format preserves hunks and paths in a shape those consumers can parse reliably.Use ignore working copy carefullyUse --ignore-working-copy only for understood lock-safe inspection or metadata work. It may read stale file state, so do not use it to bypass normal synchronization before edits.Workspace add for second checkoutsUse jj workspace add only when a task needs another filesystem checkout. Ordinary review separation should use jj new; workspaces fit clean validation or parallelism.
Pattern items
Commit messages for historyCommit messages become future debugging and review aids, not just publication labels. Write them to explain the reason and effect of the change, with enough context to survive outside the original conversation.Isolate agent workspacesShared worktrees make it easy for agent edits, generated files, or validation steps to collide with unrelated work. Use isolated workspaces when concurrent tasks or uncertain changes need clear ownership and cleanup.Preserve unowned workShared working copies may contain edits from another person or an earlier task. Check state before editing, work around unrelated changes, and stop for direction when unowned work blocks the current change.