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] [--checkout] [--lock [--reason <string>]]
  13                    [--orphan] [(-b | -B) <new-branch>] <path> [<commit-ish>]
  14 'git worktree list' [-v | --porcelain [-z]]
  15 'git worktree lock' [--reason <string>] <worktree>
  16 'git worktree move' <worktree> <new-path>
  17 'git worktree prune' [-n] [-v] [--expire <expire>]
  18 'git worktree remove' [-f] <worktree>
  19 'git worktree repair' [<path>...]
  20 'git worktree unlock' <worktree>
  21
  22 DESCRIPTION
  23 -----------
  24
  25 Manage multiple working trees attached to the same repository.
  26
  27 A git repository can support multiple working trees, allowing you to check
  28 out more than one branch at a time.  With `git worktree add` a new working
  29 tree is associated with the repository, along with additional metadata
  30 that differentiates that working tree from others in the same repository.
  31 The working tree, along with this metadata, is called a "worktree".
  32
  33 This new worktree is called a "linked worktree" as opposed to the "main
  34 worktree" prepared by linkgit:git-init[1] or linkgit:git-clone[1].
  35 A repository has one main worktree (if it's not a bare repository) and
  36 zero or more linked worktrees. When you are done with a linked worktree,
  37 remove it with `git worktree remove`.
  38
  39 In its simplest form, `git worktree add <path>` automatically creates a
  40 new branch whose name is the final component of `<path>`, which is
  41 convenient if you plan to work on a new topic. For instance, `git
  42 worktree add ../hotfix` creates new branch `hotfix` and checks it out at
  43 path `../hotfix`. To instead work on an existing branch in a new worktree,
  44 use `git worktree add <path> <branch>`. On the other hand, if you just
  45 plan to make some experimental changes or do testing without disturbing
  46 existing development, it is often convenient to create a 'throwaway'
  47 worktree not associated with any branch. For instance,
  48 `git worktree add -d <path>` creates a new worktree with a detached `HEAD`
  49 at the same commit as the current branch.
  50
  51 If a working tree is deleted without using `git worktree remove`, then
  52 its associated administrative files, which reside in the repository
  53 (see "DETAILS" below), will eventually be removed automatically (see
  54 `gc.worktreePruneExpire` in linkgit:git-config[1]), or you can run
  55 `git worktree prune` in the main or any linked worktree to clean up any
  56 stale administrative files.
  57
  58 If the working tree for a linked worktree is stored on a portable device
  59 or network share which is not always mounted, you can prevent its
  60 administrative files from being pruned by issuing the `git worktree lock`
  61 command, optionally specifying `--reason` to explain why the worktree is
  62 locked.
  63
  64 COMMANDS
  65 --------
  66 add <path> [<commit-ish>]::
  67
  68 Create a worktree at `<path>` and checkout `<commit-ish>` into it. The new worktree
  69 is linked to the current repository, sharing everything except per-worktree
  70 files such as `HEAD`, `index`, etc. As a convenience, `<commit-ish>` may
  71 be a bare "`-`", which is synonymous with `@{-1}`.
  72 +
  73 If `<commit-ish>` is a branch name (call it `<branch>`) and is not found,
  74 and neither `-b` nor `-B` nor `--detach` are used, but there does
  75 exist a tracking branch in exactly one remote (call it `<remote>`)
  76 with a matching name, treat as equivalent to:
  77 +
  78 ------------
  79 $ git worktree add --track -b <branch> <path> <remote>/<branch>
  80 ------------
  81 +
  82 If the branch exists in multiple remotes and one of them is named by
  83 the `checkout.defaultRemote` configuration variable, we'll use that
  84 one for the purposes of disambiguation, even if the `<branch>` isn't
  85 unique across all remotes. Set it to
  86 e.g. `checkout.defaultRemote=origin` to always checkout remote
  87 branches from there if `<branch>` is ambiguous but exists on the
  88 `origin` remote. See also `checkout.defaultRemote` in
  89 linkgit:git-config[1].
  90 +
  91 If `<commit-ish>` is omitted and neither `-b` nor `-B` nor `--detach` used,
  92 then, as a convenience, the new worktree is associated with a branch (call
  93 it `<branch>`) named after `$(basename <path>)`.  If `<branch>` doesn't
  94 exist, a new branch based on `HEAD` is automatically created as if
  95 `-b <branch>` was given.  If `<branch>` does exist, it will be checked out
  96 in the new worktree, if it's not checked out anywhere else, otherwise the
  97 command will refuse to create the worktree (unless `--force` is used).
  98 +
  99 If `<commit-ish>` is omitted, neither `--detach`, or `--orphan` is
 100 used, and there are no valid local branches (or remote branches if
 101 `--guess-remote` is specified) then, as a convenience, the new worktree is
 102 associated with a new orphan branch named `<branch>` (after
 103 `$(basename <path>)` if neither `-b` or `-B` is used) as if `--orphan` was
 104 passed to the command. In the event the repository has a remote and
 105 `--guess-remote` is used, but no remote or local branches exist, then the
 106 command fails with a warning reminding the user to fetch from their remote
 107 first (or override by using `-f/--force`).
 108
 109 list::
 110
 111 List details of each worktree.  The main worktree is listed first,
 112 followed by each of the linked worktrees.  The output details include
 113 whether the worktree is bare, the revision currently checked out, the
 114 branch currently checked out (or "detached HEAD" if none), "locked" if
 115 the worktree is locked, "prunable" if the worktree can be pruned by the
 116 `prune` command.
 117
 118 lock::
 119
 120 If a worktree is on a portable device or network share which is not always
 121 mounted, lock it to prevent its administrative files from being pruned
 122 automatically. This also prevents it from being moved or deleted.
 123 Optionally, specify a reason for the lock with `--reason`.
 124
 125 move::
 126
 127 Move a worktree to a new location. Note that the main worktree or linked
 128 worktrees containing submodules cannot be moved with this command. (The
 129 `git worktree repair` command, however, can reestablish the connection
 130 with linked worktrees if you move the main worktree manually.)
 131
 132 prune::
 133
 134 Prune worktree information in `$GIT_DIR/worktrees`.
 135
 136 remove::
 137
 138 Remove a worktree. Only clean worktrees (no untracked files and no
 139 modification in tracked files) can be removed. Unclean worktrees or ones
 140 with submodules can be removed with `--force`. The main worktree cannot be
 141 removed.
 142
 143 repair [<path>...]::
 144
 145 Repair worktree administrative files, if possible, if they have become
 146 corrupted or outdated due to external factors.
 147 +
 148 For instance, if the main worktree (or bare repository) is moved, linked
 149 worktrees will be unable to locate it. Running `repair` in the main
 150 worktree will reestablish the connection from linked worktrees back to the
 151 main worktree.
 152 +
 153 Similarly, if the working tree for a linked worktree is moved without
 154 using `git worktree move`, the main worktree (or bare repository) will be
 155 unable to locate it. Running `repair` within the recently-moved worktree
 156 will reestablish the connection. If multiple linked worktrees are moved,
 157 running `repair` from any worktree with each tree's new `<path>` as an
 158 argument, will reestablish the connection to all the specified paths.
 159 +
 160 If both the main worktree and linked worktrees have been moved manually,
 161 then running `repair` in the main worktree and specifying the new `<path>`
 162 of each linked worktree will reestablish all connections in both
 163 directions.
 164
 165 unlock::
 166
 167 Unlock a worktree, allowing it to be pruned, moved or deleted.
 168
 169 OPTIONS
 170 -------
 171
 172 -f::
 173 --force::
 174         By default, `add` refuses to create a new worktree when
 175         `<commit-ish>` is a branch name and is already checked out by
 176         another worktree, or if `<path>` is already assigned to some
 177         worktree but is missing (for instance, if `<path>` was deleted
 178         manually). This option overrides these safeguards. To add a missing but
 179         locked worktree path, specify `--force` twice.
 180 +
 181 `move` refuses to move a locked worktree unless `--force` is specified
 182 twice. If the destination is already assigned to some other worktree but is
 183 missing (for instance, if `<new-path>` was deleted manually), then `--force`
 184 allows the move to proceed; use `--force` twice if the destination is locked.
 185 +
 186 `remove` refuses to remove an unclean worktree unless `--force` is used.
 187 To remove a locked worktree, specify `--force` twice.
 188
 189 -b <new-branch>::
 190 -B <new-branch>::
 191         With `add`, create a new branch named `<new-branch>` starting at
 192         `<commit-ish>`, and check out `<new-branch>` into the new worktree.
 193         If `<commit-ish>` is omitted, it defaults to `HEAD`.
 194         By default, `-b` refuses to create a new branch if it already
 195         exists. `-B` overrides this safeguard, resetting `<new-branch>` to
 196         `<commit-ish>`.
 197
 198 -d::
 199 --detach::
 200         With `add`, detach `HEAD` in the new worktree. See "DETACHED HEAD"
 201         in linkgit:git-checkout[1].
 202
 203 --[no-]checkout::
 204         By default, `add` checks out `<commit-ish>`, however, `--no-checkout` can
 205         be used to suppress checkout in order to make customizations,
 206         such as configuring sparse-checkout. See "Sparse checkout"
 207         in linkgit:git-read-tree[1].
 208
 209 --[no-]guess-remote::
 210         With `worktree add <path>`, without `<commit-ish>`, instead
 211         of creating a new branch from `HEAD`, if there exists a tracking
 212         branch in exactly one remote matching the basename of `<path>`,
 213         base the new branch on the remote-tracking branch, and mark
 214         the remote-tracking branch as "upstream" from the new branch.
 215 +
 216 This can also be set up as the default behaviour by using the
 217 `worktree.guessRemote` config option.
 218
 219 --[no-]track::
 220         When creating a new branch, if `<commit-ish>` is a branch,
 221         mark it as "upstream" from the new branch.  This is the
 222         default if `<commit-ish>` is a remote-tracking branch.  See
 223         `--track` in linkgit:git-branch[1] for details.
 224
 225 --lock::
 226         Keep the worktree locked after creation. This is the
 227         equivalent of `git worktree lock` after `git worktree add`,
 228         but without a race condition.
 229
 230 -n::
 231 --dry-run::
 232         With `prune`, do not remove anything; just report what it would
 233         remove.
 234
 235 --orphan::
 236         With `add`, make the new worktree and index empty, associating
 237         the worktree with a new orphan/unborn branch named `<new-branch>`.
 238
 239 --porcelain::
 240         With `list`, output in an easy-to-parse format for scripts.
 241         This format will remain stable across Git versions and regardless of user
 242         configuration.  It is recommended to combine this with `-z`.
 243         See below for details.
 244
 245 -z::
 246         Terminate each line with a NUL rather than a newline when
 247         `--porcelain` is specified with `list`. This makes it possible
 248         to parse the output when a worktree path contains a newline
 249         character.
 250
 251 -q::
 252 --quiet::
 253         With `add`, suppress feedback messages.
 254
 255 -v::
 256 --verbose::
 257         With `prune`, report all removals.
 258 +
 259 With `list`, output additional information about worktrees (see below).
 260
 261 --expire <time>::
 262         With `prune`, only expire unused worktrees older than `<time>`.
 263 +
 264 With `list`, annotate missing worktrees as prunable if they are older than
 265 `<time>`.
 266
 267 --reason <string>::
 268         With `lock` or with `add --lock`, an explanation why the worktree
 269         is locked.
 270
 271 <worktree>::
 272         Worktrees can be identified by path, either relative or absolute.
 273 +
 274 If the last path components in the worktree's path is unique among
 275 worktrees, it can be used to identify a worktree. For example if you only
 276 have two worktrees, at `/abc/def/ghi` and `/abc/def/ggg`, then `ghi` or
 277 `def/ghi` is enough to point to the former worktree.
 278
 279 REFS
 280 ----
 281 When using multiple worktrees, some refs are shared between all worktrees,
 282 but others are specific to an individual worktree. One example is `HEAD`,
 283 which is different for each worktree. This section is about the sharing
 284 rules and how to access refs of one worktree from another.
 285
 286 In general, all pseudo refs are per-worktree and all refs starting with
 287 `refs/` are shared. Pseudo refs are ones like `HEAD` which are directly
 288 under `$GIT_DIR` instead of inside `$GIT_DIR/refs`. There are exceptions,
 289 however: refs inside `refs/bisect`, `refs/worktree` and `refs/rewritten` are
 290 not shared.
 291
 292 Refs that are per-worktree can still be accessed from another worktree via
 293 two special paths, `main-worktree` and `worktrees`. The former gives
 294 access to per-worktree refs of the main worktree, while the latter to all
 295 linked worktrees.
 296
 297 For example, `main-worktree/HEAD` or `main-worktree/refs/bisect/good`
 298 resolve to the same value as the main worktree's `HEAD` and
 299 `refs/bisect/good` respectively. Similarly, `worktrees/foo/HEAD` or
 300 `worktrees/bar/refs/bisect/bad` are the same as
 301 `$GIT_COMMON_DIR/worktrees/foo/HEAD` and
 302 `$GIT_COMMON_DIR/worktrees/bar/refs/bisect/bad`.
 303
 304 To access refs, it's best not to look inside `$GIT_DIR` directly. Instead
 305 use commands such as linkgit:git-rev-parse[1] or linkgit:git-update-ref[1]
 306 which will handle refs correctly.
 307
 308 CONFIGURATION FILE
 309 ------------------
 310 By default, the repository `config` file is shared across all worktrees.
 311 If the config variables `core.bare` or `core.worktree` are present in the
 312 common config file and `extensions.worktreeConfig` is disabled, then they
 313 will be applied to the main worktree only.
 314
 315 In order to have worktree-specific configuration, you can turn on the
 316 `worktreeConfig` extension, e.g.:
 317
 318 ------------
 319 $ git config extensions.worktreeConfig true
 320 ------------
 321
 322 In this mode, specific configuration stays in the path pointed by `git
 323 rev-parse --git-path config.worktree`. You can add or update
 324 configuration in this file with `git config --worktree`. Older Git
 325 versions will refuse to access repositories with this extension.
 326
 327 Note that in this file, the exception for `core.bare` and `core.worktree`
 328 is gone. If they exist in `$GIT_DIR/config`, you must move
 329 them to the `config.worktree` of the main worktree. You may also take this
 330 opportunity to review and move other configuration that you do not want to
 331 share to all worktrees:
 332
 333  - `core.worktree` should never be shared.
 334
 335  - `core.bare` should not be shared if the value is `core.bare=true`.
 336
 337  - `core.sparseCheckout` should not be shared, unless you are sure you
 338    always use sparse checkout for all worktrees.
 339
 340 See the documentation of `extensions.worktreeConfig` in
 341 linkgit:git-config[1] for more details.
 342
 343 DETAILS
 344 -------
 345 Each linked worktree has a private sub-directory in the repository's
 346 `$GIT_DIR/worktrees` directory.  The private sub-directory's name is usually
 347 the base name of the linked worktree's path, possibly appended with a
 348 number to make it unique.  For example, when `$GIT_DIR=/path/main/.git` the
 349 command `git worktree add /path/other/test-next next` creates the linked
 350 worktree in `/path/other/test-next` and also creates a
 351 `$GIT_DIR/worktrees/test-next` directory (or `$GIT_DIR/worktrees/test-next1`
 352 if `test-next` is already taken).
 353
 354 Within a linked worktree, `$GIT_DIR` is set to point to this private
 355 directory (e.g. `/path/main/.git/worktrees/test-next` in the example) and
 356 `$GIT_COMMON_DIR` is set to point back to the main worktree's `$GIT_DIR`
 357 (e.g. `/path/main/.git`). These settings are made in a `.git` file located at
 358 the top directory of the linked worktree.
 359
 360 Path resolution via `git rev-parse --git-path` uses either
 361 `$GIT_DIR` or `$GIT_COMMON_DIR` depending on the path. For example, in the
 362 linked worktree `git rev-parse --git-path HEAD` returns
 363 `/path/main/.git/worktrees/test-next/HEAD` (not
 364 `/path/other/test-next/.git/HEAD` or `/path/main/.git/HEAD`) while `git
 365 rev-parse --git-path refs/heads/master` uses
 366 `$GIT_COMMON_DIR` and returns `/path/main/.git/refs/heads/master`,
 367 since refs are shared across all worktrees, except `refs/bisect`,
 368 `refs/worktree` and `refs/rewritten`.
 369
 370 See linkgit:gitrepository-layout[5] for more information. The rule of
 371 thumb is do not make any assumption about whether a path belongs to
 372 `$GIT_DIR` or `$GIT_COMMON_DIR` when you need to directly access something
 373 inside `$GIT_DIR`. Use `git rev-parse --git-path` to get the final path.
 374
 375 If you manually move a linked worktree, you need to update the `gitdir` file
 376 in the entry's directory. For example, if a linked worktree is moved
 377 to `/newpath/test-next` and its `.git` file points to
 378 `/path/main/.git/worktrees/test-next`, then update
 379 `/path/main/.git/worktrees/test-next/gitdir` to reference `/newpath/test-next`
 380 instead. Better yet, run `git worktree repair` to reestablish the connection
 381 automatically.
 382
 383 To prevent a `$GIT_DIR/worktrees` entry from being pruned (which
 384 can be useful in some situations, such as when the
 385 entry's worktree is stored on a portable device), use the
 386 `git worktree lock` command, which adds a file named
 387 `locked` to the entry's directory. The file contains the reason in
 388 plain text. For example, if a linked worktree's `.git` file points
 389 to `/path/main/.git/worktrees/test-next` then a file named
 390 `/path/main/.git/worktrees/test-next/locked` will prevent the
 391 `test-next` entry from being pruned.  See
 392 linkgit:gitrepository-layout[5] for details.
 393
 394 When `extensions.worktreeConfig` is enabled, the config file
 395 `.git/worktrees/<id>/config.worktree` is read after `.git/config` is.
 396
 397 LIST OUTPUT FORMAT
 398 ------------------
 399 The `worktree list` command has two output formats. The default format shows the
 400 details on a single line with columns.  For example:
 401
 402 ------------
 403 $ git worktree list
 404 /path/to/bare-source            (bare)
 405 /path/to/linked-worktree        abcd1234 [master]
 406 /path/to/other-linked-worktree  1234abc  (detached HEAD)
 407 ------------
 408
 409 The command also shows annotations for each worktree, according to its state.
 410 These annotations are:
 411
 412  * `locked`, if the worktree is locked.
 413  * `prunable`, if the worktree can be pruned via `git worktree prune`.
 414
 415 ------------
 416 $ git worktree list
 417 /path/to/linked-worktree    abcd1234 [master]
 418 /path/to/locked-worktree    acbd5678 (brancha) locked
 419 /path/to/prunable-worktree  5678abc  (detached HEAD) prunable
 420 ------------
 421
 422 For these annotations, a reason might also be available and this can be
 423 seen using the verbose mode. The annotation is then moved to the next line
 424 indented followed by the additional information.
 425
 426 ------------
 427 $ git worktree list --verbose
 428 /path/to/linked-worktree              abcd1234 [master]
 429 /path/to/locked-worktree-no-reason    abcd5678 (detached HEAD) locked
 430 /path/to/locked-worktree-with-reason  1234abcd (brancha)
 431         locked: worktree path is mounted on a portable device
 432 /path/to/prunable-worktree            5678abc1 (detached HEAD)
 433         prunable: gitdir file points to non-existent location
 434 ------------
 435
 436 Note that the annotation is moved to the next line if the additional
 437 information is available, otherwise it stays on the same line as the
 438 worktree itself.
 439
 440 Porcelain Format
 441 ~~~~~~~~~~~~~~~~
 442 The porcelain format has a line per attribute.  If `-z` is given then the lines
 443 are terminated with NUL rather than a newline.  Attributes are listed with a
 444 label and value separated by a single space.  Boolean attributes (like `bare`
 445 and `detached`) are listed as a label only, and are present only
 446 if the value is true.  Some attributes (like `locked`) can be listed as a label
 447 only or with a value depending upon whether a reason is available.  The first
 448 attribute of a worktree is always `worktree`, an empty line indicates the
 449 end of the record.  For example:
 450
 451 ------------
 452 $ git worktree list --porcelain
 453 worktree /path/to/bare-source
 454 bare
 455
 456 worktree /path/to/linked-worktree
 457 HEAD abcd1234abcd1234abcd1234abcd1234abcd1234
 458 branch refs/heads/master
 459
 460 worktree /path/to/other-linked-worktree
 461 HEAD 1234abc1234abc1234abc1234abc1234abc1234a
 462 detached
 463
 464 worktree /path/to/linked-worktree-locked-no-reason
 465 HEAD 5678abc5678abc5678abc5678abc5678abc5678c
 466 branch refs/heads/locked-no-reason
 467 locked
 468
 469 worktree /path/to/linked-worktree-locked-with-reason
 470 HEAD 3456def3456def3456def3456def3456def3456b
 471 branch refs/heads/locked-with-reason
 472 locked reason why is locked
 473
 474 worktree /path/to/linked-worktree-prunable
 475 HEAD 1233def1234def1234def1234def1234def1234b
 476 detached
 477 prunable gitdir file points to non-existent location
 478
 479 ------------
 480
 481 Unless `-z` is used any "unusual" characters in the lock reason such as newlines
 482 are escaped and the entire reason is quoted as explained for the
 483 configuration variable `core.quotePath` (see linkgit:git-config[1]).
 484 For Example:
 485
 486 ------------
 487 $ git worktree list --porcelain
 488 ...
 489 locked "reason\nwhy is locked"
 490 ...
 491 ------------
 492
 493 EXAMPLES
 494 --------
 495 You are in the middle of a refactoring session and your boss comes in and
 496 demands that you fix something immediately. You might typically use
 497 linkgit:git-stash[1] to store your changes away temporarily, however, your
 498 working tree is in such a state of disarray (with new, moved, and removed
 499 files, and other bits and pieces strewn around) that you don't want to risk
 500 disturbing any of it. Instead, you create a temporary linked worktree to
 501 make the emergency fix, remove it when done, and then resume your earlier
 502 refactoring session.
 503
 504 ------------
 505 $ git worktree add -b emergency-fix ../temp master
 506 $ pushd ../temp
 507 # ... hack hack hack ...
 508 $ git commit -a -m 'emergency fix for boss'
 509 $ popd
 510 $ git worktree remove ../temp
 511 ------------
 512
 513 BUGS
 514 ----
 515 Multiple checkout in general is still experimental, and the support
 516 for submodules is incomplete. It is NOT recommended to make multiple
 517 checkouts of a superproject.
 518
 519 GIT
 520 ---
 521 Part of the linkgit:git[1] suite