SYNOPSIS

git worktree add [-f] [--detach] [--checkout] [--lock [--reason <string>]] [-b <new-branch>] <path> [<commit-ish>]
git worktree list [-v | --porcelain [-z]]
git worktree lock [--reason <string>] <worktree>
git worktree move <worktree> <new-path>
git worktree prune [-n] [-v] [--expire <expire>]
git worktree remove [-f] <worktree>
git worktree repair [<path>…]
git worktree unlock <worktree>

DESCRIPTION

同一のリポジトリに接続されている複数の作業ツリーを管理します。

gitリポジトリは複数の作業ツリー(working tree)をサポートできるため、一度に複数のブランチをチェックアウトできます。 git worktree add を使用すると、 新しい作業ツリーがリポジトリに関連付けられ、 その作業ツリーを、同一リポジトリの他の作業ツリーと区別する、追加のメタデータを関連付けます。 作業ツリーは、このメタデータとひっくるめて worktree (ワークツリー)と呼ばれます。

この新しい worktree は、 git-init(1) または git-clone(1) によって準備された「メイン worktree」とは対照的に、「リンクされた worktree」(linked worktree)と呼ばれます。 リポジトリには、1 つの メイン worktree (ベア・リポジトリでない場合) と、0 個以上のリンクされた worktree があります。 リンクされたworktree を使い終わったら、 git worktree remove で削除します。

最も単純な形式では、 git worktree add <path> は、名前が <path> の最後のコンポーネントである新しいブランチを自動的に作成します。これは、あなたが新しいトピックで作業する場合に便利です。たとえば、 git worktree add ../hotfix は、新しいブランチ hotfix を作成し、パス ../hotfix でチェックアウトします。代わりに、既存のブランチの新しい worktree で作業するには、 git worktree add <path> <branch> を使用します。一方、既存の開発を妨げることなく実験的な変更やテストを行う場合は、ブランチに関連付けられていない「使い捨て」の worktree を作成すると便利なことがよくあります。たとえば、 git worktree add -d <path> は、現在のブランチと同じコミットで、切り離された`HEAD`(detached HEAD)を持つ新しい worktree を作成します。

git worktree remove を使用せずに作業ツリーを削除すると、リポジトリにある関連する管理ファイル(後述の「DETAILS」参照)が最終的には自動的に削除されます(git-config(1) の gc.worktreePruneExpire 参照)。 または、メインまたはリンクされた worktree で、古い管理ファイルをクリーンアップするために git worktree prune を実行できます。

リンクされた workutree の作業ツリー(working tree)が、常にマウントされている訳ではないポータブル・デバイスまたはネットワーク共有に保存されている場合、 git worktree lock コマンド(オプションで --reason を指定して worktree がなぜロックされているかを説明)を発行することで、 管理ファイルが刈り込み(prune)されるのを防ぐことができます。

COMMANDS

add <path> [<commit-ish>]

<path> に worktree を作成し、 そこに <commit-ish> をチェックアウトします。 新しい worktree は現在のリポジトリにリンクされ、 HEAD 、 index などの worktree ごとのファイルを除くすべてを共有します。 便宜上、 <commit-ish> は、 @{-1} と同義の - だけでもかまいません。

上記 <commit-ish> がブランチ名(以下 <branch> とします)で見つからず、 -b や -B や --detach のいずれも使用されていないが、名前が一致する1つのリモート(以下 <remote> とします)には追跡ブランチが存在する場合、上記は以下と同等です:

$ git worktree add --track -b <branch> <path> <remote>/<branch>

ブランチが複数のリモートに存在し、そのうちの1つが checkout.defaultRemote 設定変数によって名付けられた場合、 <branch> がすべてのリモートでユニークでなくても、曖昧さをなくすためにその1つを使用します。例えば、 checkout.defaultRemote=origin と設定すると、 <branch> があいまいで、かつ origin リモートに存在する場合、常にそこからリモートブランチをチェックアウトすることができます。git-config(1) にある checkout.defaultRemote も参照してください。

<commit-ish> が省略され、 -b も -B も --detach も使用されていない場合、便宜上、新しい worktree は $(basename <path>) にちなんで名付けらたブランチ(<branch> とします)に関連付けられます。<branch> が存在しない場合、 -b <branch> が指定されたかのように、 HEAD に基づく新しいブランチが自動的に作成されます。 <branch> が存在する場合で、他の場所でチェックアウトされていない場合は、新しい worktree でチェックアウトされます。 存在しない場合、(--force が使用されている場合を除き、)コマンドは worktree の作成を拒否します。

list

各 worktree の詳細を一覧表示します。 リストの最初はメインの worktree であり、その後にリンクされた各 worktree が続きます。 出力の詳細として、 worktree が裸(bare)かどうかや、 現在チェックアウトされているリビジョン(または、存在しない場合は「切り離された HEAD」detached HEAD)や、 現在チェックアウトされているブランチや、 worktree がロックされているなら locked が出力に含まれ、 worktree が prune コマンドでプルーニングできる場合は prunable が出力に含まれます。

lock

worktree が常にマウントされているとは限らないポータブルデバイスまたはネットワーク共有上にある場合は、 管理ファイルが自動的に刈り込み(prune)されないようにツリーをロック(lock)します。 これにより、移動や削除も防止されます。 オプションの`--reason` を使用してロック理由を記述します。

move

注意: worktree を新しい場所に移動します。このコマンドでは、 メインの worktree または、 サブモジュールを含むリンクされた worktree (linked worktree)は、移動できないことに注意してください。 (ただし、 git worktree repair コマンドを使用すると、メインの worktree を手動で移動した場合、 リンクされた worktree ごとの接続を再確立できます。)

prune

$GIT_DIR/worktrees の worktree 情報を刈り込みます(prune)。

remove

worktgree を削除します。削除できるのは、クリーンな worktree (追跡してないファイルが無く、かつ、追跡ファイルの変更が無い場合)のみです。綺麗でない(unclean) worktree または、サブモジュールのある worktree は、 --force を使用して削除できます。メインの worktree は削除できません。

repair [<path>…]

可能であれば、外部要因によって、破損または古くなった worktree 管理ファイルを修復します。

たとえば、メインの worktree (またはベア・リポジトリ)を移動すると、リンクされた worktree (linked worktree)はそれを見つけることができなくなります。 メインの worktree で repair を実行すると、リンクされた worktree からメインの worktree への接続が再確立されます。

同様に、リンクされた worktree (linked worktree)が git worktree move を使用せずに移動された場合、 メイン worktree (またはベア・リポジトリ)はそれを見つけることができません。 直近に移動した worktree 内で repair を実行すると、接続が再確立されます。 リンクされた worktree が複数移動された場合、 各 worktree の新しい <path> を引数として任意の worktree から repair を実行すると、指定されたすべてのパスへの接続が再確立されます。

メイン worktree とリンクされた worktree (linked worktree)の両方が手動で移動された場合、メイン worktree で repair を実行し、 各リンクされた worktree の新しい <path> を指定すると、両方向のすべての接続が再確立されます。

unlock

worktree のロックを解除(unlock)して、刈り込み(prune)または移動(move)または削除(delete)できるようにします。

OPTIONS

-f
--force

デフォルトでは、<commit-ish> がブランチ名であり、別の worktree によってすでにチェックアウトされている場合、 または <path> がすでに worktree に割り当てられているが欠落している場合(たとえば、 <path>`が手動で削除された場合)、 `add は新しい worktree の作成を拒否します。 このオプションは、これらの安全装置(safeguards)をオーバーライドします。 欠落しているがロックされている worktree パスを追加するには、 --force を2回指定します。

--force が2回指定されていない限り、 move はロックされた worktree の移動を拒否します。移動先がすでに他の worktree に割り当てられているが欠落している場合(たとえば、 <new-path> が手動で削除された場合)は、 --force で移動を続行できます。移動先がロックされている場合は、 --force を2回使用します。

remove は、 --force が使用されない限り、 クリーンでない(unclean)worktreeの削除を拒否します。 ロックされた(locked)worktreeを削除するには、 --force を 2 回指定します。

-b <new-branch>
-B <new-branch>

add を使用して、 <commit-ish> から開始する <new-branch> という名前の新しいブランチを作成し、 <new-branch> を新しい worktree にチェックアウトします。 <commit-ish> を省略すると、 デフォルトで HEAD になります。 デフォルトでは、 -b は、 新しいブランチがすでに存在する場合、そのブランチを作成することを拒否します。 -B はこの安全装置をオーバーライドし、 <new-branch> を <commit-ish> にリセットします。

-d
--detach

add を使用して、新しい worktree で HEAD を切り離します(detach)。 git-checkout(1) の「DETACHED HEAD」を参照してください。

--[no-]checkout

デフォルトでは、 add は <commit-ish> をチェックアウトしますが、 --no-checkout を使用して、スパースチェックアウト(suppress checkout)の構成などのカスタマイズを行うためにチェックアウトを抑制することができます。 git-read-tree(1) の「Sparse checkout」を参照してください。

--[no-]guess-remote

<commit-ish> を伴わずに worktree add <path> を使用し、 HEAD から新しいブランチを作成する代わりに、 <path> のベース名に一致する追跡ブランチが１つリモートにだけ存在する場合、新しいブランチをそのリモート追跡ブランチに基づいて作成し、そのリモート追跡ブランチを新しいブランチの「アップストリーム」としてマークします。

これは、 worktree.guessRemote 構成オプションを使用してデフォルトの動作として設定することもできます。

--[no-]track

新しいブランチを作成するときに、 <commit-ish> がブランチである場合は、新しいブランチの「アップストリーム」としてマークします。 <commit-ish> がリモート追跡ブランチの場合、これの振る舞いがデフォルトです。詳細については、 git-branch(1)の --track を参照してください。

--lock

作成後は、 worktree をロックしたままにします。 これは、 git worktree add の後に git worktree lock するのと同等ですが、競合状態(race condition)にはなりません。

-n
--dry-run

prune では、何も削除しないでください。何が削除されるかを報告するだけです。

--porcelain

list を使用すると、スクリプトの解析が容易な形式で出力されます。この形式は、Gitのバージョン間で、ユーザー構成に関係なく安定しています。 これは -z と組み合わせることをお勧めします。 詳細については、後述します。

-z

list で --porcelain が指定されている場合、改行(newline)ではなく NUL で各行を終了します。 これにより、 worktree パスに改行文字が含まれている場合、出力をパースできます。

-q
--quiet

add を使用して、フィードバックメッセージを抑制します。

-v
--verbose

prune を使用して、すべての削除を報告します。

list を使用して、worktreeに関する追加情報を出力します(後述)。

--expire <time>

prune と共に使うと、 <time> より古い未使用の worktree のみを期限切れにします。

list と共に使うと、 <time> より古い場合は、欠落している worktree に刈り込み可能(prunable)という注釈(annotate)を付けます。

--reason <string>

lock または add --lock と共に使用して、その worktree がなぜロックされているかを記述します。

<worktree>

worktree は、相対パスまたは絶対パスのいずれかで識別できます。

worktree のパスの最後のパスコンポーネントが worktree 間で一意である場合、それを使用して worktree を識別できます。 たとえば、 /abc/def/ghi と /abc/def/ggg の2つの worktree しかない場合、 これらの worktree を指すには、 ghi または def/ghi で十分です。

REFS

複数の worktree を使用する場合、一部のrefはすべての worktree 間で共有されますが、その他は個々の worktree に固有です。 その一例が HEAD で、これは worktree ごとに異なります。 このセクションでは、共有ルールと、ある worktree の ref を別の worktree からアクセスする方法について説明します。

一般に、すべての疑似ref(pseudo refs)は worktree ごとにあり、そして、 refs/ で始まるすべてのrefは共有されます。 疑似refは、 $GIT_DIR/refs 内ではなく、 $GIT_DIR の直下にある HEAD のようなものです。 ただし、例外があります。 refs/bisect 内のrefと refs/worktree は共有されません。

worktree ごとのrefには、 別の worktree から、 main-worktree と worktrees の2つの特別なパスを介してアクセスできます。 前者はメインの worktree の worktree ごとのrefを提供し、後者はすべてのリンクされた worktree へのアクセスを提供します。

たとえば、 main-worktree/HEAD や main-worktree/refs/bisect/good は、それぞれメイン worktree の HEAD や refs/bisect/good ` と同一の値に解決されます。 同様に、 `worktrees/foo/HEAD や worktrees/bar/refs/bisect/bad は、 $GIT_COMMON_DIR/worktrees/foo/HEAD や $GIT_COMMON_DIR/worktrees/bar/refs/bisect/bad と同一です。

refにアクセスするのに $GIT_DIR の内部を直接調べないことをお勧めします。代わりに、refを正しく処理する git-rev-parse(1) や git-update-ref(1) などのコマンドを使用してください。

CONFIGURATION FILE

デフォルトでは、リポジトリの config ファイルはすべての worktree で共有されます。 構成変数 core.bare または core.worktree が共通の構成ファイルに存在し、 extensions.worktreeConfig が無効になっている場合、それらはメイン worktree のみに適用されます。

worktree 固有の構成を作成するには、 worktreeConfig 拡張機能をオンにします。例:

$ git config extensions.worktreeConfig true

このモードでは、指定の構成は git rev-parse --git-path config.worktree が指すパスに残ります。 git config --worktree を使用して、このファイルの構成を追加または更新できます。古いバージョンのGitは、この拡張機能を備えたリポジトリへのアクセスを拒否します。

注意: このファイルでは、 core.bare と core.worktree が例外扱いされないことに注意してください。 それらが $GIT_DIR/config に存在する場合は、メイン worktree の config.worktree に移動する必要があります。 また、この機会に、あなたが共有したくない他の構成を確認して、すべての worktree に移動することもできます。

  • core.worktree は決して共有しないでください。

  • core.bare は、 値が core.bare=true である場合には共有されるべきではありません。

  • すべての worktree に対して常にスパース・チェックアウトを使用することが確実でない限り、 core.sparseCheckout は共有すべきではありません。

詳細については、 git-config(1) の extensions.worktreeConfig のドキュメントを参照してください。

DETAILS

各々のリンクされた workutree (linked worktree)には、 リポジトリの $ GIT_DIR/worktrees ディレクトリにプライベート・サブ・ディレクトリがあります。 プライベート・サブ・ディレクトリの名前は通常、リンクされた worktree のパスのベース名であり、 一意にするために番号が追加される場合があります。 たとえば、 $GIT_DIR=/path/main/.git の場合、 コマンド git worktree add /path/other/test-next next はリンクされた worktree を /path/other/test-next に作成し、 そしてまた $GIT_DIR/worktrees/test-next ディレクトリ(または、 test-next がすでに存在する場合、 $GIT_DIR/worktrees/test-next1 ディレクトリ)を作成します。

リンクされた worktree (linked worktree)内で、 $GIT_DIR は、このプライベート・ディレクトリを指すように設定され(例では /path/main/.git/worktrees/test-next)、 $GIT_COMMON_DIR はメイン worktree の $GIT_DIR (例では /path/main/.git )を指すように設定されます。これらの設定は、リンクされた worktree の最上位ディレクトリにある .git ファイルで行われます。

git rev-parse --git-path によるパス解決では、 パスに応じて $GIT_DIR または $GIT_COMMON_DIR のいずれかが使用されます。たとえば、リンクされた worktree (linked worktree)では、 git rev-parse --git-path HEAD は /path/main/.git/worktrees/test-next/HEAD を返します(/path/other/test-next/.git/HEAD や /path/main/.git/HEAD ではありません)。 一方、 git rev-parse --git-path refs/heads/master は $GIT_COMMON_DIR を使用し、 /path/main/.git/refs/heads/ master を返します。 refは、 refs/bisect と refs/worktree を除くすべての worktree で共有されるためです。

詳細については、 gitrepository-layout(5) を参照してください。 経験則では、 $GIT_DIR 内の何かに直接アクセスする必要がある場合、パスが $GIT_DIR または $GIT_COMMON_DIR のどちらに属するかについては何も想定していません。 git rev-parse --git-path を使用して、最終的なパスを取得してください。

リンクされた worktree (linked worktree)を手動で移動する場合は、 エントリのディレクトリにある gitdir ファイルを更新する必要があります。 たとえば、リンクされた作業ツリーが /newpath/test-next に移動され、 その .git ファイルが /path/main/.git/worktrees/test-next を指しているならば、 代わりに /path/main/.git/worktrees/test-next/gitdir を更新し /newpath/test-next を参照するようにします。 もっといいのは、 git worktree repair を実行して、接続を自動的に再確立することです。

$GIT_DIR/worktrees エントリが刈り込み(prune)されないようにする(これは、 エントリの worktree がポータブルデバイスに保存されている場合など、 状況によっては便利です)には、 git worktree lock コマンドを使用します。 このコマンドは locked という名前のファイルをエントリのディレクトリに追加します。 ファイルには、 理由(reason)がプレーンテキストで含まれています。 たとえば、リンクされた worktree (linked worktree)の .git ファイルが /path/main/.git/worktrees/test-next を指しているならば、 /path/main/.git/worktrees/test-next/locked という名前のファイルは test-next エントリが刈り込み(pruned)されるのを防ぎます。 詳細については、 gitrepository-layout(5) を参照してください。

extensions.worktreeConfig が有効になっている場合、設定ファイル .git/worktrees/<id>/config.worktree は .git/config の後に読み込まれます。

LIST OUTPUT FORMAT

worktreelist コマンドには2つの出力形式があります。デフォルトの形式では、詳細が1行に複数列で表示されます。例えば:

$ git worktree list
/path/to/bare-source            (bare)
/path/to/linked-worktree        abcd1234 [master]
/path/to/other-linked-worktree  1234abc  (detached HEAD)

このコマンドは、状態に応じて、各 worktree の注釈(annotations)も表示します。これらの注釈は以下のとおりです:

  • locked : worktree がロックされている場合。

  • prunable : worktree が git worktree prune を介して刈り込みできる場合。 

$ git worktree list
/path/to/linked-worktree    abcd1234 [master]
/path/to/locked-worktree    acbd5678 (brancha) locked
/path/to/prunable-worktree  5678abc  (detached HEAD) prunable

これらの注釈(annotations)については、理由(reason)も利用できる可能性があり、これは冗長モード(verbose mode)を使用して確認できます。そして、注釈はインデントされた次の行に移動され、その後に追加情報が続きます。

$ git worktree list --verbose
/path/to/linked-worktree              abcd1234 [master]
/path/to/locked-worktree-no-reason    abcd5678 (detached HEAD) locked
/path/to/locked-worktree-with-reason  1234abcd (brancha)
        locked: worktree path is mounted on a portable device
/path/to/prunable-worktree            5678abc1 (detached HEAD)
        prunable: gitdir file points to non-existent location

注意: 追加情報が利用可能な場合、注釈は次の行に移動されることに注意してください。そうでない場合、注釈は worktree 自体と同じ行にとどまります。

Porcelain Format

磁器コマンドのフォーマットは、属性ごとに1行あります。 -z が指定された場合、 行は改行(newline)ではなく NUL で終了します。 属性は、 単一のスペースで区切られたラベルと値でリストされます。 ブール属性(bare や detached など)はラベルとしてのみリストされ、 値がtrueの場合にのみ存在します。 一部の属性(locked など)は、 ラベルとしてのみリストすることも、 理由が利用可能かどうかに応じて値とともにリストすることもできます。 worktree の最初の属性は常に worktree であり、空行はレコードの終わりを示します。 例えば:

$ git worktree list --porcelain
worktree /path/to/bare-source
bare

worktree /path/to/linked-worktree
HEAD abcd1234abcd1234abcd1234abcd1234abcd1234
branch refs/heads/master

worktree /path/to/other-linked-worktree
HEAD 1234abc1234abc1234abc1234abc1234abc1234a
detached

worktree /path/to/linked-worktree-locked-no-reason
HEAD 5678abc5678abc5678abc5678abc5678abc5678c
branch refs/heads/locked-no-reason
locked

worktree /path/to/linked-worktree-locked-with-reason
HEAD 3456def3456def3456def3456def3456def3456b
branch refs/heads/locked-with-reason
locked reason why is locked

worktree /path/to/linked-worktree-prunable
HEAD 1233def1234def1234def1234def1234def1234b
detached
prunable gitdir file points to non-existent location

-z が使用されない限り、ロック理由での改行などの「異常な」文字はエスケープされ、 設定変数 core.quotePath で説明されているように理由全体がクォートされます(git-config(1) 参照)。 例えば:

$ git worktree list --porcelain
...
locked "reason\nwhy is locked"
...

EXAMPLES

リファクタリングセッションの真っ最中に、 上司がやって来て、 あなたに、 すぐに何かを修正するように要求します。 通常、 git-stash(1) を使用して変更を一時的に保存しますが、 作業ツリー(working tree)は、(新しいファイル、移動されたファイル、削除されたファイル、その他の断片が散らばっていて)混乱状態にあります。 あなたはそれのいずれかを邪魔する危険を冒したくありません。 あなたは代わりに、一時的にリンクされた worktree を作成して緊急修正を行い、 完了したらそれを削除してから、以前のリファクタリングセッションを再開することにします。

$ git worktree add -b emergency-fix ../temp master
$ pushd ../temp
# ... hack hack hack ...
$ git commit -a -m 'emergency fix for boss'
$ popd
$ git worktree remove ../temp

BUGS

一般的な複数チェックアウト(multiple checkout)はまだ実験段階であり、サブモジュールのサポートは不完全です。スーパープロジェクトを複数チェックアウトすることはお勧めしません。

GIT

Part of the git(1) suite