jj Reference Guide

Reference for common jj operations, conventions, and patterns used in this codebase.

Commit Description Format

All commit descriptions MUST be a single line following this format:

<project-prefix>: <short description>

IMPORTANT: Always use a one-line commit message. Never use multi-line descriptions or bullet points.

Project prefix is the descriptive folder path identifying the subsystem (e.g., src/auth, lib/utils, services/api).

Description starts with a lowercase verb: add, update, fix, refactor, remove, etc.

Examples

src/auth: add JWT token refresh logic
lib/utils: fix date parsing for ISO formats
services/api: add rate limiting middleware
db/migrations: add users table
docs: update installation instructions
tests/integration: add checkout flow tests

Analyzing Changes

Overview Commands

# Files changed with change type (modified/added/deleted)
jj diff --summary
jj show <rev> --summary

# Lines changed per file histogram
jj diff --stat
jj diff -r <rev> --stat

# Full diff
jj diff
jj diff -r <rev>

Size-Based Approach

• Small changes (≤5 files, ≤200 lines): read the diff directly
• Large changes (>5 files or >200 lines): use /jj-context to get a structured summary

Common Operations

Creating a Commit (jj commit)

Creates a new commit from working copy changes:

jj commit -m "<project-prefix>: <description>"

After committing, @ becomes an empty working copy on top of the new commit.

Describing a Commit (jj describe)

Sets or updates the description of an existing commit:

# Describe parent commit (most common)
jj describe @- -m "<project-prefix>: <description>"

# Describe any commit
jj describe <rev> -m "<description>"

Creating a Bookmark (jj bookmark)

Bookmarks use john/<descriptive-name> format with kebab-case:

# On parent commit (if @ is empty)
jj bookmark create john/<name> -r @-

# On current commit
jj bookmark create john/<name>

# List bookmarks
jj bookmark list

Naming: Use 2-4 word kebab-case names describing the work:

• john/s3-inventory-download
• john/fix-auth-refresh
• john/refactor-poller-config

Splitting a Commit (jj split)

Splits a commit into multiple commits by file:

# Split specific files into a new commit
jj split -r <rev> -m "<description>" path/to/file1 path/to/file2

# Last group: just describe the remainder
jj describe -r @- -m "<description>"

Note: After each split, the revision ID changes. Use @- to refer to the result.

Grouping suggestions:

• Core feature + its tests together
• Configuration/infrastructure separate
• Database migrations separate
• Refactoring/cleanup separate

Squashing Changes (jj squash)

Moves changes from working copy into ancestor commits.

Without options, squashes all changes from @ into its parent (@-):

jj squash  # @ → @-

With --into (or -t), squash into a specific commit:

jj squash --into <change-id> path/to/file.py  # specific files
jj squash --into <change-id> "src/**/*.py"    # glob pattern
jj squash --into @--                           # grandparent

For sub-file chunks (specific hunks, not whole files):

1. Save original @ change ID: jj log -r @ --no-graph -T 'change_id'
2. Create intermediate: jj new --insert-before @
3. Write only the hunks for target commit
4. Squash: jj squash --into <target-change-id>
5. Return to rebased @: jj edit <rebased-@-change-id>
6. Remove duplicated hunks
7. Restore working copy: jj new

Always use change IDs (e.g., ksrmwuon) not commit IDs - they're stable across rewrites.

Revision Syntax

Working Copy Behavior

• In jj, @ (working copy) is often an empty commit on top of your actual work
• Check jj log for "(empty)" to know if @ has changes
• jj commit creates commit and leaves @ empty
• jj describe modifies existing commit, doesn't change @