7850deedf7fc57f17060dab6e5b89bd49ee74ce6
   1git-worktree(1)
   2===============
   3
   4NAME
   5----
   6git-worktree - Manage multiple working trees
   7
   8
   9SYNOPSIS
  10--------
  11[verse]
  12'git worktree add' [-f] [--detach] [--checkout] [-b <new-branch>] <path> [<branch>]
  13'git worktree list' [--porcelain]
  14'git worktree lock' [--reason <string>] <worktree>
  15'git worktree prune' [-n] [-v] [--expire <expire>]
  16'git worktree unlock' <worktree>
  17
  18DESCRIPTION
  19-----------
  20
  21Manage multiple working trees attached to the same repository.
  22
  23A git repository can support multiple working trees, allowing you to check
  24out more than one branch at a time.  With `git worktree add` a new working
  25tree is associated with the repository.  This new working tree is called a
  26"linked working tree" as opposed to the "main working tree" prepared by "git
  27init" or "git clone".  A repository has one main working tree (if it's not a
  28bare repository) and zero or more linked working trees.
  29
  30When you are done with a linked working tree you can simply delete it.
  31The working tree's administrative files in the repository (see
  32"DETAILS" below) will eventually be removed automatically (see
  33`gc.worktreePruneExpire` in linkgit:git-config[1]), or you can run
  34`git worktree prune` in the main or any linked working tree to
  35clean up any stale administrative files.
  36
  37If you move a linked working tree, you need to manually update the
  38administrative files so that they do not get pruned automatically. See
  39section "DETAILS" for more information.
  40
  41If a linked working tree is stored on a portable device or network share
  42which is not always mounted, you can prevent its administrative files from
  43being pruned by issuing the `git worktree lock` command, optionally
  44specifying `--reason` to explain why the working tree is locked.
  45
  46COMMANDS
  47--------
  48add <path> [<branch>]::
  49
  50Create `<path>` and checkout `<branch>` into it. The new working directory
  51is linked to the current repository, sharing everything except working
  52directory specific files such as HEAD, index, etc.
  53+
  54If `<branch>` is omitted and neither `-b` nor `-B` nor `--detached` used,
  55then, as a convenience, a new branch based at HEAD is created automatically,
  56as if `-b $(basename <path>)` was specified.
  57
  58list::
  59
  60List details of each worktree.  The main worktree is listed first, followed by
  61each of the linked worktrees.  The output details include if the worktree is
  62bare, the revision currently checked out, and the branch currently checked out
  63(or 'detached HEAD' if none).
  64
  65lock::
  66
  67If a working tree is on a portable device or network share which
  68is not always mounted, lock it to prevent its administrative
  69files from being pruned automatically. This also prevents it from
  70being moved or deleted. Optionally, specify a reason for the lock
  71with `--reason`.
  72
  73prune::
  74
  75Prune working tree information in $GIT_DIR/worktrees.
  76
  77unlock::
  78
  79Unlock a working tree, allowing it to be pruned, moved or deleted.
  80
  81OPTIONS
  82-------
  83
  84-f::
  85--force::
  86        By default, `add` refuses to create a new working tree when `<branch>`
  87        is already checked out by another working tree. This option overrides
  88        that safeguard.
  89
  90-b <new-branch>::
  91-B <new-branch>::
  92        With `add`, create a new branch named `<new-branch>` starting at
  93        `<branch>`, and check out `<new-branch>` into the new working tree.
  94        If `<branch>` is omitted, it defaults to HEAD.
  95        By default, `-b` refuses to create a new branch if it already
  96        exists. `-B` overrides this safeguard, resetting `<new-branch>` to
  97        `<branch>`.
  98
  99--detach::
 100        With `add`, detach HEAD in the new working tree. See "DETACHED HEAD"
 101        in linkgit:git-checkout[1].
 102
 103--[no-]checkout::
 104        By default, `add` checks out `<branch>`, however, `--no-checkout` can
 105        be used to suppress checkout in order to make customizations,
 106        such as configuring sparse-checkout. See "Sparse checkout"
 107        in linkgit:git-read-tree[1].
 108
 109-n::
 110--dry-run::
 111        With `prune`, do not remove anything; just report what it would
 112        remove.
 113
 114--porcelain::
 115        With `list`, output in an easy-to-parse format for scripts.
 116        This format will remain stable across Git versions and regardless of user
 117        configuration.  See below for details.
 118
 119-v::
 120--verbose::
 121        With `prune`, report all removals.
 122
 123--expire <time>::
 124        With `prune`, only expire unused working trees older than <time>.
 125
 126--reason <string>::
 127        With `lock`, an explanation why the working tree is locked.
 128
 129<worktree>::
 130        Working trees can be identified by path, either relative or
 131        absolute.
 132+
 133If the last path components in the working tree's path is unique among
 134working trees, it can be used to identify worktrees. For example if
 135you only have to working trees at "/abc/def/ghi" and "/abc/def/ggg",
 136then "ghi" or "def/ghi" is enough to point to the former working tree.
 137
 138DETAILS
 139-------
 140Each linked working tree has a private sub-directory in the repository's
 141$GIT_DIR/worktrees directory.  The private sub-directory's name is usually
 142the base name of the linked working tree's path, possibly appended with a
 143number to make it unique.  For example, when `$GIT_DIR=/path/main/.git` the
 144command `git worktree add /path/other/test-next next` creates the linked
 145working tree in `/path/other/test-next` and also creates a
 146`$GIT_DIR/worktrees/test-next` directory (or `$GIT_DIR/worktrees/test-next1`
 147if `test-next` is already taken).
 148
 149Within a linked working tree, $GIT_DIR is set to point to this private
 150directory (e.g. `/path/main/.git/worktrees/test-next` in the example) and
 151$GIT_COMMON_DIR is set to point back to the main working tree's $GIT_DIR
 152(e.g. `/path/main/.git`). These settings are made in a `.git` file located at
 153the top directory of the linked working tree.
 154
 155Path resolution via `git rev-parse --git-path` uses either
 156$GIT_DIR or $GIT_COMMON_DIR depending on the path. For example, in the
 157linked working tree `git rev-parse --git-path HEAD` returns
 158`/path/main/.git/worktrees/test-next/HEAD` (not
 159`/path/other/test-next/.git/HEAD` or `/path/main/.git/HEAD`) while `git
 160rev-parse --git-path refs/heads/master` uses
 161$GIT_COMMON_DIR and returns `/path/main/.git/refs/heads/master`,
 162since refs are shared across all working trees.
 163
 164See linkgit:gitrepository-layout[5] for more information. The rule of
 165thumb is do not make any assumption about whether a path belongs to
 166$GIT_DIR or $GIT_COMMON_DIR when you need to directly access something
 167inside $GIT_DIR. Use `git rev-parse --git-path` to get the final path.
 168
 169If you move a linked working tree, you need to update the 'gitdir' file
 170in the entry's directory. For example, if a linked working tree is moved
 171to `/newpath/test-next` and its `.git` file points to
 172`/path/main/.git/worktrees/test-next`, then update
 173`/path/main/.git/worktrees/test-next/gitdir` to reference `/newpath/test-next`
 174instead.
 175
 176To prevent a $GIT_DIR/worktrees entry from being pruned (which
 177can be useful in some situations, such as when the
 178entry's working tree is stored on a portable device), use the
 179`git worktree lock` command, which adds a file named
 180'locked' to the entry's directory. The file contains the reason in
 181plain text. For example, if a linked working tree's `.git` file points
 182to `/path/main/.git/worktrees/test-next` then a file named
 183`/path/main/.git/worktrees/test-next/locked` will prevent the
 184`test-next` entry from being pruned.  See
 185linkgit:gitrepository-layout[5] for details.
 186
 187LIST OUTPUT FORMAT
 188------------------
 189The worktree list command has two output formats.  The default format shows the
 190details on a single line with columns.  For example:
 191
 192------------
 193S git worktree list
 194/path/to/bare-source            (bare)
 195/path/to/linked-worktree        abcd1234 [master]
 196/path/to/other-linked-worktree  1234abc  (detached HEAD)
 197------------
 198
 199Porcelain Format
 200~~~~~~~~~~~~~~~~
 201The porcelain format has a line per attribute.  Attributes are listed with a
 202label and value separated by a single space.  Boolean attributes (like 'bare'
 203and 'detached') are listed as a label only, and are only present if and only
 204if the value is true.  An empty line indicates the end of a worktree.  For
 205example:
 206
 207------------
 208S git worktree list --porcelain
 209worktree /path/to/bare-source
 210bare
 211
 212worktree /path/to/linked-worktree
 213HEAD abcd1234abcd1234abcd1234abcd1234abcd1234
 214branch refs/heads/master
 215
 216worktree /path/to/other-linked-worktree
 217HEAD 1234abc1234abc1234abc1234abc1234abc1234a
 218detached
 219
 220------------
 221
 222EXAMPLES
 223--------
 224You are in the middle of a refactoring session and your boss comes in and
 225demands that you fix something immediately. You might typically use
 226linkgit:git-stash[1] to store your changes away temporarily, however, your
 227working tree is in such a state of disarray (with new, moved, and removed
 228files, and other bits and pieces strewn around) that you don't want to risk
 229disturbing any of it. Instead, you create a temporary linked working tree to
 230make the emergency fix, remove it when done, and then resume your earlier
 231refactoring session.
 232
 233------------
 234$ git worktree add -b emergency-fix ../temp master
 235$ pushd ../temp
 236# ... hack hack hack ...
 237$ git commit -a -m 'emergency fix for boss'
 238$ popd
 239$ rm -rf ../temp
 240$ git worktree prune
 241------------
 242
 243BUGS
 244----
 245Multiple checkout in general is still experimental, and the support
 246for submodules is incomplete. It is NOT recommended to make multiple
 247checkouts of a superproject.
 248
 249git-worktree could provide more automation for tasks currently
 250performed manually, such as:
 251
 252- `remove` to remove a linked working tree and its administrative files (and
 253  warn if the working tree is dirty)
 254- `mv` to move or rename a working tree and update its administrative files
 255
 256GIT
 257---
 258Part of the linkgit:git[1] suite