JJ Topology and Source Control

VCS rules cover jj-first source-control work, remote topology, operation-log recovery, workspaces, publication safety, and file-tracking decisions.

JJ state, review lanes, publication, remote topology, and recovery.

28 rules

VCS JJToolingLocal ConventionsAsk Before Repairing JJ AliasesVCS-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.VCS JJAgent WorkflowToolingAvoid Interactive JJ in Agent WorkVCS-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.VCS JJToolingAgent WorkflowConfigure JJ PagerVCS-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.VCS JJReviewabilityVerificationConfirm Broad JJ OperationsVCS-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.VCS JJReview HandoffReleaseConfirm GitHub Remote TopologyVCS-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.VCS JJChange ShapeVerificationCreate an Operation Log Point Before ReshapingVCS-CREATE-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.VCS JJToolingSource TruthDo Not Fall Back to Git for JJ IssuesVCS-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.VCS JJVerificationReleaseDry Run Surprising PublicationVCS-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.VCS JJChange ShapeReviewabilityDuplicate for Alternative CandidatesVCS-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.VCS JJToolingSource TruthInspect Sparse StateVCS-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.VCS JJVerificationOwnershipInspect State Before MutatingVCS-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.VCS JJSource TruthToolingJJ as Source of TruthVCS-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.VCS JJChange ShapeReviewabilityJJ New for Review LanesVCS-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.VCS JJReview HandoffSource TruthMake GitHub Handoff ExplicitVCS-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.VCS JJSource TruthToolingMatch JJ Topology to Repo RoleVCS-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.VCS JJToolingVerificationName Exact JJ Mutation TargetsVCS-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.VCS JJToolingAutomationQuote Revsets and Shell SyntaxVCS-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.VCS JJVerificationSource TruthRecover with Operation LogVCS-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.VCS JJSource TruthReview HandoffRepair Remote Topology CoherentlyVCS-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.VCS JJToolingAutomationRun JJ Mutations SequentiallyVCS-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.VCS JJOwnershipSource TruthScope JJ File TrackingVCS-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.VCS JJToolingVerificationStop Repeated JJ Retries And Localize StateVCS-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.VCS JJSource TruthReview HandoffTrack Remotes ExplicitlyVCS-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.VCS JJToolingSource TruthTreat Bookmark Remote Syntax as Version SensitiveVCS-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.VCS JJSource TruthVerificationUse Evolog and Operation LogVCS-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.VCS JJAgent WorkflowReview HandoffUse Git-Formatted Diffs for AgentsVCS-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.VCS JJToolingVerificationUse Ignore Working Copy CarefullyVCS-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.VCS JJAgent WorkflowChange ShapeWorkspace Add for Second CheckoutsVCS-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.