using-jj

jj ワークフロー

一覧表、Git での相当機能、トラブルシューティング、revset のチートシートについては、REFERENCE.md を参照してください。

スタイルガイド

1. 説明は必須です。 作業コピーを「(no description set)」のままにしないでください。
2. ブックマークは GitHub のためのものであり、あなたのためのものではありません。 匿名変更を使い、プッシュするときにのみブックマークを追加してください。
3. 手動で squash 先を指定するのではなく、absorb を使ってください。 jj に、各ハンクを適切な祖先へ振り分けさせましょう。

非対話型の分割

jj split にはファイルセットと -m の両方が必要です。

jj split -r <rev> -m "first part" path/a path/b   # rest stays in the child commit

Evolog による指定

以前のバージョン：<change-id>/0（最新）、/1（その前）。jj restore --from xyz/1 --into xyz で以前の状態に戻せます。

ワークフロー

Squash（推奨）

jj describe -m "feat: what I'm building"
jj new -m "wip"
# ... make changes ...
jj squash -m "feat: done"

Edit（スタック途中の修正）

jj edit <change-id>
# ... fix ...
jj new -m "back to work"   # descendants auto-rebased

Absorb

@ から jj absorb を実行すると、各ハンクは、その行が最後に変更された祖先へ振り分けられます。

ブックマークとプッシュ

ブックマークは自動では先へ進みません。明示的に移動してください。実際に作業内容を保持しているリビジョンを対象にしてください。 これは直前に使ったフローによって異なります。

jj bookmark set <name> -r @-    # after `jj squash`/`jj commit`: @ is a fresh empty change
jj bookmark set <name> -r @     # after `jj describe -m` alone: @ IS the work
jj git push

間違えても何も通知されません。作業内容が @ にあるときに @- をプッシュすると、前のコミットが公開されます。

レビュー済み PR の履歴を書き換えない

デフォルト（安全 — コメントのアンカーを保持します）：

jj new feature-x -m "fixup: address feedback"
# ... make changes ...
jj bookmark set feature-x -r @
jj git push

jj new feature-x（末尾に - を付けない）は、ブックマークの上に修正を積み重ねます。 feature-x- は feature-x の親を表す revset なので、レビュー済みコミットから兄弟を分岐させることになります。その後 bookmark set -r @- を実行するとブックマークが後戻りし、レビュー担当者がコメントを付けたコミットそのものが外れてしまいます。

PR の作成（jj + gh）

jj と Git を併用するリポジトリでは、git HEAD は detached 状態のため、gh pr create は「not on any branch」というエラーで失敗します。必ず --head <bookmark> を指定してください。 git の自動検出に頼らないでください。

jj bookmark set feature-x -r @-   # or -r @ — see "Bookmarks & pushing" above
jj git push
gh pr create --head feature-x --title "..." --body "..."

復旧

jj op log の後に jj op restore <id> を実行します。jj evolog -r <change-id> で、1 つの変更の履歴を確認できます。詳しくは REFERENCE.md の該当箇所を参照してください。

不変コミット

プッシュ済みコミットは immutable_heads() によって保護されています。プッシュ済みコミットに修正を取り込むには、承認されている方法である jj squash --into <id> --ignore-immutable を使ってください。ただし、レビュー済み PR では引き続き rules/pr-safety.md のルールが適用されます。

Revset

jj log -r 'trunk()..@'              # everything between main and here
jj log -r '::@ & ~::trunk()'         # my branch only
jj log -r 'mine()'                  # my commits
jj log -r 'author(substring:"trevor")'  # bare strings in author()/description() are whole-string globs; say substring: for partial