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 が使用されている場合を除き、)コマンドはワークツリーの作成を拒否します。

If <commit-ish> is omitted, neither --detach, or --orphan is used, and there are no valid local branches (or remote branches if --guess-remote is specified) then, as a convenience, the new worktree is associated with a new unborn branch named <branch> (after $(basename <path>) if neither -b or -B is used) as if --orphan was passed to the command. In the event the repository has a remote and --guess-remote is used, but no remote or local branches exist, then the command fails with a warning reminding the user to fetch from their remote first (or override by using -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 を実行すると、指定されたすべてのパスへの接続が再確立されます。

If both the main worktree and linked worktrees have been moved or copied manually, then running repair in the main worktree and specifying the new <path> of each linked worktree will reestablish all connections in both directions.

unlock

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

OPTIONS

-f
--force

By default, add refuses to create a new worktree when <commit-ish> is a branch name and is already checked out by another worktree, or if <path> is already assigned to some worktree but is missing (for instance, if <path> was deleted manually). This option overrides these safeguards. To add a missing but locked worktree path, specify --force twice.

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

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

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

With add, create a new branch named <new-branch> starting at <commit-ish>, and check out <new-branch> into the new worktree. If <commit-ish> is omitted, it defaults to HEAD. By default, -b refuses to create a new branch if it already exists. -B overrides this safeguard, resetting <new-branch> to <commit-ish>.

-d
--detach

With add, detach HEAD in the new worktree. See "DETACHED HEAD" in git-checkout(1).

--[no-]checkout

By default, add checks out <commit-ish>, however, --no-checkout can be used to suppress checkout in order to make customizations, such as configuring sparse-checkout. See "Sparse checkout" in git-read-tree(1).

--[no-]guess-remote

With worktree add <path>, without <commit-ish>, instead of creating a new branch from HEAD, if there exists a tracking branch in exactly one remote matching the basename of <path>, base the new branch on the remote-tracking branch, and mark the remote-tracking branch as "upstream" from the new branch.

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

--[no-]track

When creating a new branch, if <commit-ish> is a branch, mark it as "upstream" from the new branch. This is the default if <commit-ish> is a remote-tracking branch. See --track in git-branch(1) for details.

--lock

Keep the worktree locked after creation. This is the equivalent of git worktree lock after git worktree add, but without a race condition.

-n
--dry-run

With prune, do not remove anything; just report what it would remove.

--orphan

With add, make the new worktree and index empty, associating the worktree with a new unborn branch named <new-branch>.

--porcelain

With list, output in an easy-to-parse format for scripts. This format will remain stable across Git versions and regardless of user configuration. It is recommended to combine this with -z. See below for details.

-z

Terminate each line with a NUL rather than a newline when --porcelain is specified with list. This makes it possible to parse the output when a worktree path contains a newline character.

-q
--quiet

With add, suppress feedback messages.

-v
--verbose

With prune, report all removals.

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

--expire <time>

With prune, only expire unused worktrees older than <time>.

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

--reason <string>

With lock or with add --lock, an explanation why the worktree is locked.

<worktree>

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

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

REFS

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

In general, all pseudo refs are per-worktree and all refs starting with refs/ are shared. Pseudo refs are ones like HEAD which are directly under $GIT_DIR instead of inside $GIT_DIR/refs. There are exceptions, however: refs inside refs/bisect, refs/worktree and refs/rewritten are not shared.

ワークツリーごとの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 ファイルで行われます。

Path resolution via git rev-parse --git-path uses either $GIT_DIR or $GIT_COMMON_DIR depending on the path. For example, in the linked worktree git rev-parse --git-path HEAD returns /path/main/.git/worktrees/test-next/HEAD (not /path/other/test-next/.git/HEAD or /path/main/.git/HEAD) while git rev-parse --git-path refs/heads/master uses $GIT_COMMON_DIR and returns /path/main/.git/refs/heads/master, since refs are shared across all worktrees, except refs/bisect, refs/worktree and refs/rewritten.

詳細については、 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