SYNOPSIS

git worktree add [-f] [--detach] [--checkout] [--lock [--reason <string>]] [-b <new-branch>] <path> [<commit-ish>]
git worktree list [--porcelain]
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リポジトリは複数の作業ツリーをサポートできるため、一度に複数のブランチをチェックアウトできます。git worktree add を使用すると、新しい作業ツリーがリポジトリに関連付けられます。この新しい作業ツリーは、git-init(1) または git-clone(1) によって作成された「メイン作業ツリー」(main working tree)とは対照的に、「リンクされた作業ツリー」(linked working tree)と呼ばれます。リポジトリには、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 を使用せずに作業ツリーを削除すると、リポジトリにある関連する管理ファイル(後述の「DETAILS」参照)が最終的には自動的に削除されます(git-config(1) の gc.worktreePruneExpire 参照)。または、メインまたはリンクされた作業ツリーで、古い管理ファイルをクリーンアップするために git worktree prune を実行できます。

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

COMMANDS

add <path> [<commit-ish>]

<path> を作成し、それに <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` が使用されている場合を除く)。

list

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

lock

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

move

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

prune

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

remove

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

repair [<path>…]

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

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

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

メイン作業ツリーとリンクされた作業ツリーの両方が手動で移動された場合、メイン作業ツリーで 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回使用します。

--force が使用されていない限り、 remove は汚れた作業ツリー(unclean working tree)の削除を拒否します。ロックされた作業ツリーを削除するには、--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 では、何も削除しないでください。何が削除されるかを報告するだけです。

--porcelain

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

-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はすべての作業ツリー間で共有される場合があり、一部のrefはローカルです。 一例として、作業ツリーごとに異なる HEAD があります。このセクションでは、共有ルールと、ある作業ツリーのrefに別の作業ツリーからアクセスする方法について説明します。

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

作業ツリーごとのrefには、別の作業ツリーから、 main-worktree と worktrees の2つの特別なパスを介してアクセスできます。 main-worktree はメインの作業ツリーから作業ごとのツリーrefへのアクセスを提供し、 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 が構成ファイルにすでに存在する場合、それらはメインの作業ツリーにのみ適用されます。

作業ツリーに固有の構成を作成するには、 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 は決して共有しないでください

  • すべての作業ツリーに常にスパースチェックアウト(sparse checkout)を使用することが確実でない限りは、作業ツリーごとに core.sparseCheckout をお勧めします。

DETAILS

リンクされた各作業ツリーには、リポジトリの $ 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 ディレクトリ)を作成します。

リンクされた作業ツリー内で、 $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 のいずれかが使用されます。たとえば、リンクされた作業ツリーでは、 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 を使用して、最終的なパスを取得してください。

リンクされた作業ツリーを手動で移動する場合は、エントリのディレクトリにある 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)がプレーンテキストで含まれています。たとえば、リンクされた作業ツリーの .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: working tree 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行あります。 属性は、単一のスペースで区切られたラベルと値でリストされます。ブール属性(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

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

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

EXAMPLES

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

$ 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