Initial commit

skills/git-jj/references/jj_bookmarks.md

@@ -0,0 +1,81 @@
+# JJ Bookmarks Reference
+
+Source: https://docs.jj-vcs.dev/latest/bookmarks/
+
+## Core Concepts
+
+- **Named pointer** to a revision - similar to Git branch but NO "current branch" concept
+- **Auto-moves** when target is rewritten (`jj rebase`, `jj squash`, `jj describe`)
+- **Auto-deletes** when commit is abandoned
+- Usable anywhere a revision is expected: `jj new main`, `jj rebase -r feature -d main`
+- In colocated repos, bookmarks map directly to Git branches
+
+## Commands
+
+| Action | Command |
+|--------|---------|
+| List local | `jj bookmark list` |
+| List all (local + remote) | `jj bookmark list --all` |
+| Create at @ | `jj bookmark create <name>` |
+| Point to revision | `jj bookmark set <name> -r <rev>` |
+| Delete | `jj bookmark delete <name>` |
+| Rename | `jj bookmark rename <old> <new>` |
+| Track remote | `jj bookmark track <name>@<remote>` |
+| Untrack remote | `jj bookmark untrack <name>@<remote>` |
+| Push single | `jj git push -b <name>` |
+| Push all | `jj git push --all` |
+
+Alias: `jj b` for `jj bookmark` (e.g., `jj b c` for create, `jj b d` for delete)
+
+## Remote & Tracking
+
+- Address remote: `<bookmark>@<remote>` (e.g., `main@origin`)
+- Can track same-name bookmarks on multiple remotes
+- Auto-tracked on: clone (default remote), first push of local bookmark
+- Enable auto-track fetched: `git.auto-local-bookmark = true`
+
+## Status Indicators
+
+| Suffix | Meaning |
+|--------|---------|
+| `*` | Local differs from remote (needs push) |
+| `??` | Conflicted (multiple targets) |
+| `@<remote>` | Remote snapshot reference |
+
+## Conflict Resolution
+
+When bookmark becomes conflicted (divergent updates):
+```bash
+jj log -r 'all:<bookmark>'              # Inspect divergent commits
+jj new 'all:<bookmark>'                 # Merge path: create merge commit
+jj rebase -r <sideA> -d <sideB>         # Rebase path
+jj bookmark set <name> -r <resolved>    # Finalize
+```
+
+## Safe Push Pattern
+
+1. `jj git fetch` - sync remote state
+2. `jj status` - check for conflicts (look for `??` markers)
+3. `jj git push -b <name>` - push single bookmark
+
+Push safety checks (force-with-lease equivalent):
+- Remote position matches last known
+- Local bookmark not conflicted
+- Remote bookmark tracked (or use `--allow-new`)
+
+## Revset with Bookmarks
+
+```bash
+jj new <bookmark>           # New commit on top
+<bookmark>::                # Ancestors
+::<bookmark>                # Descendants
+heads(all:<bookmark>)       # All heads involving bookmark
+```
+
+## Git Comparison
+
+| Git | JJ |
+|-----|-----|
+| Branch HEAD moves on commit | Bookmark only moves on rewrite |
+| Single upstream per branch | Can track multiple remotes |
+| Force push risk | Built-in force-with-lease protection |