SYNOPSIS

git worktree add [-f] [--detach] [--checkout] [--lock [--reason <string>]]
                   [--orphan] [(-b | -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)と呼ばれます。

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

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

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

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

COMMANDS

add <path> [<commit-ish>]

<path> にワークツリー(worktree)を作成し、 そこに <commit-ish> をチェックアウトします。 新しいワークツリーは現在のリポジトリにリンクされ、 HEAD 、 index などのワークツリーごとのファイルを除くすべてを共有します。 便宜上、 <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 も使用されていない場合、便宜上、新しいワークツリーは $(basename <path>) にちなんで名付けらたブランチ(<branch> とします)に関連付けられます。<branch> が存在しない場合、 -b <branch> が指定されたかのように、 HEAD に基づく新しいブランチが自動的に作成されます。 <branch> が存在する場合で、他の場所でチェックアウトされていない場合は、新しいワークツリーでチェックアウトされます。 存在しない場合、(--force が使用されている場合を除き、)コマンドはワークツリーの作成を拒否します。

<commit-ish> が省略され、かつ、 --detach と --orphan のいずれも使われておらず、 かつ有効なローカルブランチ(または --guess-remote が指定された場合にはリモートブランチ)が無い場合、 便宜上、 新しいワークツリーは、 --orphan がコマンドに渡されたかのように、 <branch> という名前の新しい孤立ブランチ(orphan branch)(-b も -B も使用されていない場合は、 $(basename <path>) の後)に関連付けられます。 リポジトリにリモートがあり、 --guess-remote が使用されているが、 リモートまたはローカルのブランチが存在しない場合、 コマンドは失敗(fail)し、 最初にリモートから取得するようにユーザーに通知する警告が表示されます(または -f/--force を使用してこれをオーバーライドします)。

list

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

lock

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

move

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

prune

$GIT_DIR/worktrees のワークツリー情報を刈り込みます(prune)。

remove

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

repair [<path>…]

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

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

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

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

unlock

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

OPTIONS

-f
--force

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

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

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

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

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

-d
--detach

add を使用して、新しいワークツリーで 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

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

-n
--dry-run

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

--orphan

add と共に使用して、 新しいワークツリーとインデックスを空で作り、そのワークツリーを <new-branch> という名前の新しい 孤立(orphan)/未誕生(unborn) ブランチに関連付けます。

--porcelain

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

-z

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

-q
--quiet

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

-v
--verbose

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

list と供に使用すると、ワークツリーに関する追加情報を出力します(後述)。

--expire <time>

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

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

--reason <string>

lock または add --lock と共に使用して、そのワークツリーをなぜロックしているのかの説明を記述します。

<worktree>

ワークツリーは、相対パスまたは絶対パスのいずれかで識別できます。

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

REFS

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

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

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

たとえば、 main-worktree/HEAD や main-worktree/refs/bisect/good は、それぞれメインのワークツリーの 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 ファイルはすべてのワークツリーで共有されます。 構成変数 core.bare または core.worktree が共通の構成ファイルに存在し、 extensions.worktreeConfig が無効になっている場合、それらはメインのワークツリーのみに適用されます。

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

$ git config extensions.worktreeConfig true

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

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

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

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

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

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

DETAILS

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

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

git rev-parse --git-path によるパス解決では、 パスに応じて $GIT_DIR または $GIT_COMMON_DIR のいずれかが使用されます。たとえば、リンクされた ワークツリー(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 を除くすべてのワークツリーで共有されるためです。

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

リンクされたワークツリー(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)されないようにする(これは、 エントリのワークツリーがポータブルデバイスに保存されている場合など、 状況によっては便利です)には、 git worktree lock コマンドを使用します。 このコマンドは locked という名前のファイルをエントリのディレクトリに追加します。 ファイルには、 理由(reason)がプレーンテキストで含まれています。 たとえば、リンクされたワークツリー(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)

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

  • locked :ワークツリーがロックされている場合。

  • prunable :ワークツリーが 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

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

Porcelain Format

磁器コマンドのフォーマットは、属性ごとに1行あります。 -z が指定された場合、 行は改行(newline)ではなく NUL で終了します。 属性は、 単一のスペースで区切られたラベルと値でリストされます。 ブール属性(bare や detached など)はラベルとしてのみリストされ、 値がtrueの場合にのみ存在します。 一部の属性(locked など)は、 ラベルとしてのみリストすることも、 理由が利用可能かどうかに応じて値とともにリストすることもできます。 ワークツリーの最初の属性は常に 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)は、(新しいファイル、移動されたファイル、削除されたファイル、その他の断片が散らばっていて)混乱状態にあります。 あなたはそれのいずれかを邪魔する危険を冒したくありません。 あなたは代わりに、一時的にリンクされたワークツリーを作成して緊急修正を行い、 完了したらそれを削除してから、以前のリファクタリングセッションを再開することにします。

$ 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