48 lines
2.1 KiB
Markdown
48 lines
2.1 KiB
Markdown
# Gotchas
|
|
|
|
Short list of jj behaviors that regularly surprise agents.
|
|
|
|
**Tested with jj 0.41.0**
|
|
|
|
## 1. Working Copy Is a Commit
|
|
|
|
`@` is always a commit, not a staging area. `jj new` starts a different change; it does not finish the current one.
|
|
|
|
## 2. Most jj Commands Snapshot the Working Copy
|
|
|
|
Running `jj st`, `jj log`, and many other commands can record filesystem changes into the working-copy commit. If you intentionally need a stale view, use `--ignore-working-copy`.
|
|
|
|
## 3. Change IDs and Commit IDs Are Different
|
|
|
|
Change IDs are stable across rewrites. Commit IDs change whenever content or metadata changes. Prefer change IDs when handing work to another agent.
|
|
|
|
## 4. `jj undo` Is the First Recovery Tool
|
|
|
|
Do not manually reverse a bad `rebase`, `squash`, or `abandon` before trying `jj undo`. Use `references/RECOVERY.md` for deeper recovery.
|
|
|
|
## 5. Pager Output Is Not a Good Agent Default
|
|
|
|
Use the compact commands in `references/TEMPLATES.md`. Those commands intentionally use `jj --no-pager ...`.
|
|
|
|
## 6. Co-located Repos Still Forbid Git Mutations
|
|
|
|
`git log`, `git show`, `git diff`, `git blame`, `git grep`, and `git status` are fine. `git commit`, `git add`, `git rebase`, `git push`, and similar mutations can corrupt jj state.
|
|
|
|
## 7. `jj workspace forget` Does Not Delete Files
|
|
|
|
It only unregisters the workspace. Delete the directory separately if cleanup is intended.
|
|
|
|
## 8. Stale Workspaces Are Normal in Parallel Work
|
|
|
|
If another workspace rewrites your base, use `jj workspace update-stale`. Verify the result with `jj st` instead of improvising a manual repair.
|
|
|
|
## 9. Bare `jj resolve` Is Interactive
|
|
|
|
For agent-safe conflict handling, use `jj resolve --tool :ours`, `jj resolve --tool :theirs`, or edit conflict markers directly.
|
|
|
|
## 10. Default Output Is Often Too Large
|
|
|
|
Prefer compact templates, targeted revsets, and narrow filesets before reaching for full `jj log -p` or `jj show`.
|
|
|
|
When behavior feels surprising, stop and check `references/NEW_CHANGE.md`, `references/TEMPLATES.md`, `references/WORKSPACES.md`, or `references/RECOVERY.md` before inventing a git-style workaround.
|