working-with-jj

JJ (Jujutsu) バージョン管理ヘルパー

基本原則

• チェンジ ID（不変）vs コミット ID（編集時に変化するコンテンツベースのハッシュ）
• 操作ログ - すべての操作を元に戻せます（段階的: 複数回の jj undo でさらに前に戻り、jj redo でそれを打ち消します）
• ステージングエリアなし - 作業コピーは自動的にスナップショットされます
• コンフリクトはブロックしない - 後で解決できます
• コミットは軽量 - 自由に編集できます
• デフォルトでコロケート - Git リポジトリは .jj と .git の両方を持ちます（v0.34 以降）
• 3 つの DSL:
  • revsets: リビジョンを横断して選択します - リビジョン（チェンジ）ID は単純ですが完全に有効なシングルトン revset です
  • filesets: リポジトリ内のファイルを横断して選択します - 通常のファイルパスは単純ですが完全に有効なシングルトン fileset です
  • templates: どの情報をログに記録し、どのように表示するかを選択します
  • 多くの jj コマンドは、これらの DSL のいずれかを使用した式を想定しており、何を表示・操作するかを選択します

必須コマンド

jj log -r <revset> [-p]               # View history (--patch/-p: include diffs, --count: just count)
jj log -r <revset> -G                 # -G is short for --no-graph
jj show -r <rev>                      # Show revision details (description + diff)
jj evolog -r <rev> [-p]               # View a revision's evolution
jj new [-A] <base>                    # Create revision and edit it (-A: insert between <base> and its children rather than just on top of base)
jj new --no-edit <base>               # Create without switching
jj edit <rev>                         # Switch to editing revision
jj desc -r <rev> -m "text"            # Set description
jj metaedit -r <rev> -m "text"        # Modify metadata (author, timestamps, description)

jj diff                               # Changes in @
jj diff -r <revset>                   # Changes in revset (need to be contiguous)
jj diff -f <rev1> -t <rev2>           # Differences between two states
jj file show -r <rev> <fileset>       # Show file contents at revision (without switching)
jj file show -r <rev> **/*.md -T '"=== " ++ path ++ " ===\n"'  # Multiple files with path headers
jj restore <fileset>                    # Discard changes to files
jj restore --from <commit-id> <fileset> # Restore from another revision/commit

jj split -r <rev> <paths> -m "text"   # Split into two revisions
jj absorb                             # Auto-squash changes into ancestor commits

jj rebase -s <src> -o <dest>          # Rebase with descendants onto <dest>
jj rebase -r <rev> -o <dest>          # Rebase single revision onto <dest>
# NOTE: -d/--destination is deprecated, use -o/--onto instead

jj file annotate <path>               # Blame: who changed each line
jj bisect run -- <cmd>                # Binary search for bug-introducing commit

追加コマンド

jj undo                               # Undo last operation (progressive - repeat to go further back)
jj redo                               # Redo undone operation
jj sign -r <rev>                      # Cryptographically sign commit
jj unsign -r <rev>                    # Remove signature
jj revert -r <rev>                    # Create commit that reverts changes (replaces old jj backout)
jj tag set <name> -r <rev>            # Create/update local tag
jj tag delete <name>                  # Delete local tag
jj git colocation enable              # Convert to colocated repo
jj git colocation disable             # Convert to non-colocated

Revset クイックリファレンス

@, @-, @--                            # Working copy, parent(s), grandparent(s)
::@                                   # Ancestors
@::                                   # Descendants
mine()                                # Your changes
conflicted()                          # Has conflicts (renamed from conflict() in v0.33)
visible()                             # Visible revisions (built-in alias)
hidden()                              # Hidden revisions (built-in alias)
description(substring-i:"text")       # Match description (partial, case-insensitive)
subject(substring:"text")             # Match first line only
signed()                              # Cryptographically signed commits
A | B, A & B, A ~ B                   # Union, intersection, difference
change_id(prefix)                     # Explicit change ID prefix lookup
parents(x, 2)                         # Parents with depth
exactly(x, 3)                         # Assert exactly N revisions

包括的な revset パターンについては references/revsets.md を参照してください。

よくある落とし穴

1. --revisions ではなく -r を使用する

jj log -r xyz          # ✅
jj log --revisions xyz # ❌

2. 並列ブランチには --no-edit を使用する

jj new parent -m "A"; jj new -m "B"                             # ❌ B is child of A!
jj new --no-edit parent -m "A"; jj new --no-edit parent -m "B"  # ✅ Both children of parent

3. シェルでは revset を引用する

jj log -r 'description(substring:"[todo]")'    # ✅

4. -d/--destination ではなく -o/--onto を使用する（v0.36 以降）

jj rebase -s xyz -o main   # ✅ New syntax
jj rebase -s xyz -d main   # ⚠️ Deprecated (still works but warns)

5. シンボル式がより厳格になりました（v0.32 以降）

revset シンボルは複数のリビジョンに解決されなくなりました:

jj log -r abc              # ❌ Error if 'abc' matches multiple change IDs
jj log -r 'change_id(abc)' # ✅ Explicitly query by prefix
jj log -r 'bookmarks(abc)' # ✅ For bookmark name patterns

6. fileset では glob パターンがデフォルトです（v0.36 以降）

jj diff 'src/*.rs'         # Matches glob pattern by default
jj diff 'cwd:"src/*.rs"'   # Use cwd: prefix for literal path with special chars

スクリプト

ヘルパースクリプトは scripts/ にあります。PATH に追加するか、直接呼び出してください。

スクリプト	目的
jj-show-desc [REV]	完全な説明のみを出力する
jj-desc-transform <REV> <CMD...>	説明をコマンドにパイプする
jj-batch-desc <SED_FILE> <REV...>	説明をバッチ変換する
jj-checkpoint [NAME]	危険な操作の前に操作 ID を記録する

リカバリ

jj op log              # Find operation before problem
jj op restore <op-id>  # Restore the WHOLE repository (history included) to that state

リファレンス

• jj 実行ファイルは自己文書化されています:
  • jj help -k bookmarks を実行 - JJ ブックマーク、Git ブランチとの関係、および Git リモートからそれらを push/fetch する方法
  • jj help -k revsets を実行 - Revset DSL の構文とパターン
  • jj help -k filesets を実行 - ファイルパス選択 DSL、つまり特定のファイルのみを操作するように jj コマンドに指示する方法
  • jj help -k templates を実行 - テンプレート言語とカスタム出力
  • すべての jj サブコマンドには、かなり詳細な --help ページがあります
• references/command-syntax.md - コマンドフラグの詳細
• references/batch-operations.md - リビジョン説明に対する複雑なバッチ変換