jj リファレンスガイド

このコードベースで使用される一般的な jj 操作、慣例、パターンのリファレンスです。

コミットディスクリプション形式

すべてのコミットディスクリプションは、以下の形式に従った1行である必要があります:

<project-prefix>: <short description>

重要: 常に1行のコミットメッセージを使用してください。複数行の説明や箇条書きを使用しないでください。

プロジェクトプレフィックス はサブシステムを識別する説明的なフォルダパスです（例：src/auth、lib/utils、services/api）。

説明 は小文字の動詞で始まります: add、update、fix、refactor、remove など。

例

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

変更の分析

概要コマンド

# 変更の種類（modified/added/deleted）を含むファイル一覧
jj diff --summary
jj show <rev> --summary

# ファイルごとの行数変更ヒストグラム
jj diff --stat
jj diff -r <rev> --stat

# 完全な差分
jj diff
jj diff -r <rev>

サイズベースのアプローチ

• 小さな変更（≤5ファイル、≤200行）: 差分を直接読む
• 大きな変更（>5ファイルまたは>200行）: /jj-context を使用して構造化されたサマリーを取得

一般的な操作

コミットの作成（jj commit）

作業ディレクトリの変更から新しいコミットを作成します:

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

コミット後、@ は新しいコミットの上の空のワーキングコピーになります。

コミットのディスクリプション設定（jj describe）

既存のコミットのディスクリプションを設定または更新します:

# 親コミットをディスクリプション設定（最も一般的）
jj describe @- -m "<project-prefix>: <description>"

# 任意のコミットをディスクリプション設定
jj describe <rev> -m "<description>"

ブックマークの作成（jj bookmark）

ブックマークは john/<descriptive-name> 形式をケバブケースで使用します:

# 親コミット上（@ が空の場合）
jj bookmark create john/<name> -r @-

# 現在のコミット上
jj bookmark create john/<name>

# ブックマークを一覧表示
jj bookmark list

命名規則: 作業を説明する2～4単語のケバブケース名を使用します:

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

コミットの分割（jj split）

コミットをファイル単位で複数のコミットに分割します:

# 特定のファイルを新しいコミットに分割
jj split -r <rev> -m "<description>" path/to/file1 path/to/file2

# 最後のグループ: 残りをディスクリプション設定
jj describe -r @- -m "<description>"

注意: 各分割後、リビジョンIDが変わります。結果を参照するには @- を使用します。

グループ分けの提案:

• コア機能とそのテストを一緒に
• 設定/インフラストラクチャを分離
• データベースマイグレーションを分離
• リファクタリング/クリーンアップを分離

変更の統合（jj squash）

ワーキングコピーから祖先コミットへ変更を移動します。

オプションなしの場合、@ のすべての変更を親コミット（@-）に統合します:

jj squash  # @ → @-

--into（または -t）で特定のコミットへ統合します:

jj squash --into <change-id> path/to/file.py  # 特定のファイル
jj squash --into <change-id> "src/**/*.py"    # グロブパターン
jj squash --into @--                           # 祖父母コミット

ファイル単位未満のチャンク（特定のハンク、ファイル全体ではない）の場合:

1. 元の @ チェンジIDを保存: jj log -r @ --no-graph -T 'change_id'
2. 中間コミットを作成: jj new --insert-before @
3. ターゲットコミット用のハンクのみを記述
4. 統合: jj squash --into <target-change-id>
5. リベースされた @ に戻す: jj edit <rebased-@-change-id>
6. 重複したハンクを削除
7. ワーキングコピーを復元: jj new

常にチェンジID（例：ksrmwuon）を使用します。コミットIDではなく、リライト後も安定しています。

リビジョン構文

構文	意味
@	現在のワーキングコピーコミット
x-	x の親（例：@- = ワーキングコピーの親）
x+	x の子
@--	祖父母コミット（@- の次に - をもう一度）
trunk()	メインブランチ（main/master）
::x	x のすべての祖先（x を含む）
x::	x のすべての子孫（x を含む）
x..y	y の祖先で x の祖先ではないもの
x::y	x の子孫で y の祖先でもあるもの
<change-id>	チェンジIDで指定されたコミット（例：ksrmwuon）

ワーキングコピーの動作

• jj では、@（ワーキングコピー）は実際の作業の上にある空のコミットであることがよくあります
• jj log で「(empty)」を確認して @ が変更を持っているかどうかを知ることができます
• jj commit はコミットを作成し、@ を空のまま残します
• jj describe は既存のコミットを修正し、@ は変更しません