Jj Workflow

Jujutsu (jj) Daily Workflow

jj is the preferred VCS. Git is acceptable when needed for interop.

Commit Style

Commit messages are full short sentences, not conventional commits:

jj commit -m "Fix some stuff about that"
jj commit -m "Update the firewall rules for the new subnet"
jj commit -m "Add missing netpol for vaultwarden"

Not fix: add foo — just plain sentences. One commit per logical fix. No body, no trailers.

Init

# New repo (colocated with git for GitHub/GitLab interop)
jj git init --colocate

# Clone an existing repo
jj git clone git@github.com:org/repo.git ~/Source/Repos/github.com/org/repo
# or
gh repo clone org/repo ~/Source/Repos/github.com/org/repo
cd ~/Source/Repos/github.com/org/repo

Clone pattern follows XDG: ~/Source/Repos///

Daily Workflow

# Check status
jj status

# See recent log
jj log -n 20

# See what changed in working copy
jj diff

# Commit everything in working copy
jj commit -m "Describe what changed"

# Commit only specific files
jj commit -m "Fix the thing" -- path/to/file1 path/to/file2

# Amend the last commit (auto-squash into @)
jj commit --amend -m "Better description"

Branching & Bookmarks

# Create a bookmark (branch) for a change
jj bookmark create fix-thing -r @-
# or shorthand
jj bookmark c fix-thing -r @-

# List bookmarks
jj bookmark list

# Push a bookmark to remote
jj git push --bookmark fix-thing
# Push all bookmarks
jj git push --all

# Track a remote bookmark
jj bookmark track fix-thing@origin

# Delete a bookmark
jj bookmark delete fix-thing

Stacking Changes

jj doesn't need explicit stacks — just build on top of the working copy parent:

# Make first change
jj commit -m "Add feature A"

# Make second change (automatically on top of feature A)
jj commit -m "Add feature B"

# Go back to an earlier commit and make a sibling change
jj edit   # or jj new 
# ... make changes ...
jj commit -m "Fix edge case in feature A"

Use jj split to split one change into two:

jj split 

Rebasing

# Rebase current change onto main
jj rebase -d main

# Rebase a range
jj rebase -s  -d 

# Rebase all descendants of a commit
jj rebase -r  -d 

Conflict Resolution

# jj marks conflicts; edit the files and resolve them
jj resolve  # interactive conflict resolver

# Or manually fix files, then:
jj squash  # fold resolution into the conflicted commit

# See conflicted files
jj status

Undo / Backtrack

# Undo the last operation (safe — jj keeps everything)
jj undo

# Abandon a commit (removes it from the graph)
jj abandon 

# Restore a previous state
jj restore  -- 

Git Interop

# Fetch from remote
jj git fetch

# Push to remote
jj git push

# Create a bookmark from a GitHub PR
jj bookmark create pr-123 -r 
jj git fetch
jj bookmark track pr-123@origin

# Pull (note: jj doesn't have a native pull — fetch + rebase)
jj git fetch
jj rebase -d main@origin

New Work (Start Fresh)

# Start a new empty change on top of @
jj new

# Start from a specific revision
jj new main
jj new 

# Describe the working commit
jj describe -m "What I'm about to do"

Squashing

# Squash changes from @- into @
jj squash  # interactive
jj squash --from @- --to @  # explicit

# Squash everything since main into one commit
jj squash --from main

Log & Inspection

# Compact log with bookmarks
jj log -T 'commit_id.short() ++ " " ++ description.first_line() ++ " " ++
  bookmarks'

# Full diff of a commit
jj show 

# Show changes between two revs
jj diff --from main --to @

# See which changes are not on main
jj log -r 'main..@'

Access Control (Repository Rules)

For repos with .jj/repos ACL config:

# Check repo-level permissions
jj config list repo

Common Pitfalls

1. jj git push fails with "No matching bookmarks": Create the bookmark

first with jj bookmark create -r @-, then push with jj git push --bookmark .

1. Conflicts on rebase: Expected when stacking changes. Resolve with

jj resolve or manually edit then jj squash.

1. Detached HEAD: If jj show @ has no commit_id, use jj new to create a

new commit before working.

1. Accidental abandon: Use jj undo immediately. jj keeps everything until

the git gc equivalent runs.

1. Commit scope: jj commit commits everything in the working copy. To

commit selectively, use jj commit -- or split first.

1. GitHub rejects push with GH013 (verified signatures required): If

jj git push fails because commits lack verified signatures, either upload the GPG key to GitHub or switch to SSH commit signing: jj config set --repo signing.backend ssh and jj config set --repo signing.key ~/.ssh/id_ed25519.pub. Then rebase to re-sign existing commits. See github-auth skill for full SSH signing setup.

See Also

• references/ghstack-integration.md — how jj interacts with ghstack for

stacked PRs

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: shikanime-labs
• Source: shikanime-labs/skills
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.