Documentation/git-worktree.txt

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