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,

@

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>

# 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

@-

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

@

@-

jj squash  # @ → @-

With

--into

-t

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

Revision Syntax

@

x-

@-

x+

@--

@-

-

trunk()

::x

x::

x..y

x::y

<change-id>

ksrmwuon

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 @