onevcat-jj

jj（Jujutsu）— エージェントのワークフロー向けバージョン管理

jjはGitと共存するバージョン管理ツールです。ローカルではjjを使用しますが、リモートは引き続き標準のGitです。GitHubや共同作業者からは、通常のgitコミットやブランチとして見えます。

このスキルでは、特にエージェントを活用した開発ワークフローで、jjを正しく慣例に沿って使う方法を説明します。

基本的な考え方

jjの中心となるのはブランチではなく、変更です。Gitとの主な違いは次のとおりです。

• ステージングエリアはありません。 ファイルの変更は自動的に現在の変更に含まれます。git addはありません。
• stashはありません。 jj newを実行して新しい作業を始めるだけです。以前の変更はそのまま残ります。
• detached HEADはありません。 jj editで任意の変更に移動して作業を続けられ、子孫の変更は自動的にリベースされます。
• ブランチはブックマークと呼ばれ、リモートにプッシュするときにのみ必要です。

作業コピーそのものが変更です。ファイルを変更するたびに、現在の変更として即座に追跡されます。

jjリポジトリの検出

バージョン管理操作を行う前に、リポジトリでjjが使われているか確認します。

# If .jj/ exists, use jj commands — not git commands
test -d .jj && echo "jj repo"

リポジトリに.jj/と.git/の両方がある場合（併置モード）、ローカル操作には常にjjコマンドを優先してください。

セットアップ

既存のGitリポジトリでjjを初期化するには（併置モード — .git/と.jj/を並存させます）：

jj git init --colocate

初期化後、jjがリモートブランチを認識できるよう、リモートブックマークを追跡する必要がある場合があります。

jj bookmark track master@origin        # Track a specific remote branch

必要な場合は、通常jjがその旨を知らせます。

基本コマンド

状態の確認

jj log                    # Show change graph + status (replaces git log + git status)
jj diff                   # Show diff of current change vs parent
jj diff -r <change>       # Show diff of a specific change

jj logの出力では、現在の変更が@で示され、短い変更ID（例：kxryzmsp）が表示されます。変更IDはリベース後も変わらないため、参照として自由に使えます。一意に判別できる限り、一意なプレフィックス（例：kxryzmspの代わりにkx）も使えます。

変更の作業

jj describe -m "feat: add auth module"   # Set/update description of current change
jj describe -r <change> -m "new msg"     # Update description of any change
jj new                                    # Finish current change, start a new empty one
jj new <change>                           # Start new work branching from a specific change
jj commit -m "feat: ..."                  # Shorthand: describe current + start new (equivalent to describe + new)
jj edit <change>                          # Jump to an existing change and continue editing it
jj abandon                                # Discard the current change entirely
jj abandon <change>                       # Discard a specific change

jj newは、次のタスクに取りかかるための主要なコマンドです。 現在の変更を確定し、新しい作業領域を用意します。addもcommitの儀式も必要ありません。

**jj abandon**は変更を完全に破棄します。その変更の修正内容は親に取り込まれます。空の変更を整理したり、不要な作業を破棄したり、変更の連鎖から変更を取り除いたりする際に使います。

jj editは安全です。 対象の変更が不変（すでにリモートにプッシュ済み）の場合、jjはエラーを表示して拒否します。自分で確認する必要はありません。

jj editの後にファイルを変更すると、その変更がその場で修正されます。子孫の変更はすべて自動的にリベースされるため、祖先を編集した後に手動でリベースする必要はありません。

履歴の再構成

jj split                                 # Interactively split current change into two (or more)
jj split -r <change>                     # Split a specific change
jj rebase -s <source> -d <destination>   # Move a change (and its descendants) to a new parent
jj rebase -d <destination>               # Rebase current branch onto destination
jj undo                                  # Undo the last jj operation (any operation)
jj op log                                # View operation-level history
jj op restore <operation-id>             # Restore repo to any previous operation state

ファイルセットを指定せずに実行した場合、jj splitはデフォルトで対話型エディターを開きます。最初の変更に含めるファイルやハンクを選択すると、残りは自動的に2つ目の変更になります。さらに分割するには、これを繰り返します。

jj undoは、リベース、分割、説明の追加など、直前の操作を種類を問わず取り消します。常に安全に使えます。jjでは、何かが完全に失われることはありません。

リモートとのやり取り（Gitブリッジ）

jj git fetch                             # Fetch from remote (like git fetch)
jj rebase -d master                      # Rebase current work onto latest master
jj bookmark track master@origin          # Track a remote branch (needed after init or for new remotes)
jj bookmark create my-feature -r @       # Create a bookmark (= git branch) pointing at current change
jj bookmark create my-feature -r <chg>   # Create a bookmark pointing at a specific change
jj bookmark set my-feature -r <change>   # Move an existing bookmark to a different change
jj git push                              # Push all changed bookmarks to remote
jj git push --bookmark my-feature        # Push only a specific bookmark
jj git push --deleted                    # Push bookmark deletions to remote (after jj abandon)

リモートのGitブランチは、フェッチ時にjjのブックマークへ自動的にマッピングされます。jj logに表示されるmaster（またはmain）は、ブックマーク経由で参照されるリモートブランチそのものです。

jj git init --colocateの後や、新しいリモートブランチが現れたときは、jjに追跡させるためjj bookmark track <name>@<remote>が必要な場合があります。必要な場合はjjが知らせます。

プッシュのワークフロー：

1. 作業を完了します（変更の説明を記述します）
2. jj bookmark create <name> -r <change> — Gitのブランチ名を付けます
3. jj git push — リモートにプッシュします（1つだけプッシュする場合は--bookmark <name>を指定します）

プッシュ済みの変更を破棄した後のクリーンアップ： リモートにプッシュ済みのブックマークがある変更に対してjj abandonを実行すると、そのブックマークはローカルで削除されます。その削除をリモートに同期するには、jj git push --deletedを使います。

並列ワークスペース

jj workspace add ../workspace-name       # Create a parallel workspace (like git worktree)

各ワークスペースには専用のディレクトリが割り当てられますが、基盤となるリポジトリストアは共有されます。複数のエージェントが同じベースからそれぞれ別のワークスペースで同時に作業し、jj new <change1> <change2> ...で結果をマージできます。

エージェントのワークフローパターン

これらのパターンでは、エージェントを活用した開発におけるjjの強みを活用します。

パターン 1：次のタスクを開始する

jj new を実行して、すぐに作業を始めます。事前に追加、コミット、プッシュ、ブランチ作成をする必要はありません。前の変更は自動的に保持されます。

jj new
jj describe -m "feat: implement avatar upload"
# start working...

パターン 2：中断して再開する

作業中に緊急タスクに対応するには、次のようにします。

jj new master            # Branch off master for the urgent fix
# ... do the fix ...
jj describe -m "fix: critical auth bug"
jj edit <previous-change> # Jump back to where you were
# ... resume previous work ...

スタッシュもブランチの切り替えも不要で、復元する状態もありません。

パターン 3：後から分割する

大きな変更を作成した後で、論理的なまとまりに分割します。

jj split                 # Interactive: pick files/hunks for first change, rest goes to second
jj split                 # Split again if needed

分割に失敗した場合は、jj undo で元に戻して、もう一度試してください。

パターン 4：骨組みを使った計画（複雑なタスクにおすすめ）

空の変更を計画として作成し、順番に内容を追加します。

jj commit -m "refactor: extract auth module"
jj commit -m "feat: add token refresh logic"
jj commit -m "test: update auth tests"
jj commit -m "docs: update API documentation"

次に、順番に作業を進めます。

jj edit <first-change>   # Jump to first skeleton change
# ... implement ...
jj edit <next-change>    # Jump to next (previous work auto-rebases descendants)
# ... implement ...

各変更の説明は、コミットメッセージと受け入れ条件の両方の役割を果たします。次に進む前に、実装が説明に合致していることを確認してください。

説明フィールドでは、git のコミットメッセージと同じ形式を使用します。1 行目がタイトルで、その後に空行を入れ、続けて本文を記述します。-m を使って、本文に詳細な仕様やプロンプトを記述できます。

パターン 5：元に戻して復旧する

jj undo                  # Undo last operation, no questions asked
jj op log                # See full operation history if you need to go further back
jj op restore <op-id>    # Jump to any point in operation history

変更を手動で元に戻そうとするより、jj undo を使うことをおすすめします。常に正しく、安全に操作できます。

よくある間違いとその回避方法

• jj リポジトリで git add、git commit、git stash、git checkout を使わないでください。 代わりに jj の同等のコマンドを使います。
• 特別な理由がない限り、不変の（公開済みの）変更に対して jj edit を実行しないでください。 jj がブロックします。公開済みの履歴を修正する必要がある場合は、jj new <change> を使って後続の変更を作成してください。
• ローカルだけの作業にブックマークを作成しないでください。 ブックマークが必要なのはリモートへのプッシュ時だけです。ローカルの作業は Change ID で追跡されます。
• 変更が「失われる」心配はありません。 jj の操作ログがすべてを保持します。間違いから復旧するには、jj undo または jj op restore を使ってください。

クイックリファレンス

タスク	jj コマンド
既存の git リポジトリで初期化する	jj git init --colocate
状況を確認する	jj log
現在の変更を説明する	jj describe -m "..."
次のタスクを開始する	jj new
特定の変更から分岐する	jj new <change>
古い変更を編集する	jj edit <change>
変更を破棄する	jj abandon / jj abandon <change>
変更を分割する	jj split
何でも元に戻す	jj undo
リモートからフェッチする	jj git fetch
リモートブランチを追跡する	jj bookmark track <name>@<remote>
master にリベースする	jj rebase -d master
プッシュ用のブックマークを作成する	jj bookmark create <name> -r @
既存のブックマークを移動する	jj bookmark set <name> -r <change>
リモートにプッシュする	jj git push
特定のブックマークをプッシュする	jj git push --bookmark <name>
ブックマークの削除をプッシュする	jj git push --deleted
複数の変更をマージする	jj new <chg1> <chg2> ...
並列ワークスペース	jj workspace add <path>

このスキルの範囲外

このスキルでは、最も一般的な操作を扱います。ここで扱っていない高度な使い方については、次を参照してください。

jj help                  # List all commands
jj help <command>        # Detailed help for a specific command
jj help -k <keyword>     # Search help by keyword

jj には、revset、テンプレート、カスタムエイリアス、コンフリクト解決など、豊富な機能があります。jj help で調べ、状況に応じて活用できます。公式ドキュメントは https://jj-vcs.github.io/jj/ にあります。