jj

Jujutsu（jj）バージョン管理

Jujutsu は、変更可能なコミット、自動変更追跡、すべての操作を取り消せる操作ログを備えた Git 互換の VCS です。

対象バージョン：jj 0.36+

トピック

必要なこと	詳細
jj と Git の関係を理解する、または jj リポジトリで raw git を使う	git-compatibility.md
revset、fileset、またはテンプレート式を書く	revsets.md
push、pull、ブックマークの管理、または GitHub の操作	bookmarks.md
分割、リベース、スカッシュ、または競合の解決	conflicts.md
独立した作業コピーでエージェントを並行実行する	parallel-agents.md
jj の設定、エイリアスの設定、または差分のカスタマイズ	config-reference.md

基本的な考え方

作業コピーはコミットです。 ステージング領域はありません。jj コマンドを実行すると、ファイルの変更はすべて @ に自動的にスナップショットされます。「ステージ → コミット」の代わりに、コードを書いて説明を付けるだけです。

変更 ID は安定しています。コミット ID は安定していません。 各コミットには 2 つの識別子があります。

• 変更 ID — 書き換え後も安定しています。文字 k–z（例：tqpwlqmp）です。こちらを優先してください。
• コミット ID — コンテンツハッシュで、書き換えるたびに変わります。16 進数です。コロケートされたリポジトリでは、Git のコミット ID です。

履歴は変更可能です。 コミットは自由に書き換えられます。子孫のコミットは自動的にリベースされます。古いバージョンは操作ログに残ります。

ブックマークはブランチではありません。 新しいコミットを作成しても、ブックマークは自動的に進みません。書き換えには追従しますが、push の前に明示的に設定する必要があります。 → 詳細：bookmarks.md

競合が作業を妨げることはありません。 jj では、競合したファイルを含むコミットを作成できます。都合のよいときに競合マーカーを直接編集して解決し、その後 jj st で確認してください。 → 詳細：conflicts.md

エージェントのルール

自動エージェントとして操作する場合、以下は必ず守ってください。

1. メッセージには必ず -m を使ってください。 エディターを開くコマンドは実行しないでください。-m が必要なコマンド：jj new、jj describe、jj commit、jj squash。
2. 対話型コマンドは使わないでください。 jj split（ファイルパスなし）、jj squash -i、jj resolve はすべて停止します。ファイルパス引数を使うか、jj restore のワークフローを使ってください。
3. 変更後は確認してください。 squash、abandon、rebase、restore、または破壊的な操作の後には jj st を実行してください。
4. コミット ID ではなく、変更 ID を使ってください。 変更 ID は書き換え後も維持されます。
5. revset は引用符で囲んでください。 必ずシングルクォートを使います：jj log -r 'mine() & ::@'。

エージェント固有の設定

# agent-jj-config.toml
[user]
name = "Agent"
email = "[email protected]"

[ui]
editor = "TRIED_TO_RUN_AN_INTERACTIVE_EDITOR"
diff-formatter = ":git"
paginate = "never"

次のように起動します：JJ_CONFIG=/path/to/agent-jj-config.toml <agent-harness> → 詳細：config-reference.md

基本的なワークフロー

日々のサイクル：説明 → コードを書く → new → 繰り返す。

jj describe -m "feat: add user validation"
# make changes — auto-tracked, no `add` needed
jj st && jj diff
jj new -m "feat: add error handling"

履歴の整理

jj squash -m "feat: final clean message"   # fold working copy into parent
jj absorb                                   # auto-distribute hunks to right ancestor
jj abandon @                               # drop a failed experiment

→ 詳細：command-gotchas.md

非線形の作業

新しい作業が現在のチェーンに依存しない場合は、trunk から分岐します。

# Create sibling from trunk (doesn't move @)
jj new trunk() --no-edit -m "fix: correct timezone handling"
jj edit <bugfix-change-id>
# ... fix the bug ...

# Return to original work
jj log -r 'heads(trunk()..)'
jj edit <feature-change-id>

エージェントのルール： 新しいコミットを作成する前に、現在のチェーンに依存するかどうかを判断してください。依存しない場合は trunk から分岐し、分岐したことをユーザーに知らせてください。

変更の push

jj bookmark set feat -r @
jj git push -b feat

ブックマークは push の前に設定する必要があります。自動的には進みません。 → 詳細：bookmarks.md

主要なコマンド

タスク	コマンド
状態を確認する	jj st
差分／ログを表示する	jj diff / jj log
現在のコミットを説明する	jj describe -m "message"
新しい作業を開始する	jj new -m "task description"
古いコミットを編集する	jj edit <change-id>
親にスカッシュする	jj squash
変更を自動で振り分ける	jj absorb
コミットを破棄する	jj abandon <change-id>
直前の操作を元に戻す	jj undo
操作履歴を表示する	jj op log
以前の状態に復元する	jj op restore <op-id>
ブックマークを作成／移動する	jj bookmark create <n> -r @ / jj bookmark set <n> -r @
プッシュ／フェッチする	jj git push -b <bookmark> / jj git fetch

Git の翻訳については、Git から jj への対応表を参照してください。

復元

jj undo                      # undo last op; repeatable
jj op log                    # full operation history
jj op restore <op-id>        # jump to any past state
jj evolog -r <change-id>     # see how a change evolved

jj リポジトリの検出

.jj/ ディレクトリがあれば jj リポジトリです。.jj/ と .git/ の両方がある場合は、併置されたリポジトリです。常に jj コマンドを使用してください。併置されたリポジトリでは、Git の「detached HEAD」は通常の状態です。実際の状態を確認するには jj log を使用してください。

よくある間違い

間違い	修正方法
コマンドで -m を省略する	常に -m を指定してください。エディターがエージェントを停止させます
ファイルパスを指定せずに jj split を使用する	パスを指定するか、jj restore ワークフローを使用してください
プッシュ前にブックマークを設定し忘れる	まず jj bookmark set <name> -r @ を実行してください
変更 ID ではなくコミット ID を使用する	変更 ID（k〜z の文字）は書き換え後も維持されます
revset 式を引用符で囲まない	必ずシングルクォートで囲んでください：'mine() & ::@'
:: と .. 演算子を混同する	:: = 祖先パス、.. = 範囲（revsets.md を参照）
ワークスペースをサブディレクトリとして作成する	子ディレクトリではなく、兄弟ディレクトリにする必要があります

リファレンス一覧

Git 相互運用：

• references/git-to-jj.md — Git から jj へのコマンド対応表
• references/git-experts.md — jj が Git を改善する理由
• references/git-compatibility.md — Git 相互運用と併置されたリポジトリ

コマンド：

• references/command-gotchas.md — フラグの意味、引用符、非推奨フラグ

Revset とテンプレート：

• references/revsets.md — revset 言語の完全な仕様
• references/filesets.md — fileset 言語の完全な仕様
• references/templates.md — テンプレート言語の完全な仕様

共有：

• references/bookmarks.md — ブックマークの完全なリファレンス
• references/github.md — GitHub／GitLab ワークフローの詳細

履歴：

• references/conflicts.md — 競合の処理とマーカー形式
• references/divergence.md — 発散した変更のガイド

設定：

• references/config-reference.md — 設定の完全なリファレンス

ワークスペース：

• references/parallel-agents.md — エージェントを並行してセットアップするガイド