Documentation/git-worktree.txt

   1 git-worktree(1)
   2 ===============
   3
   4 NAME
   5 ----
   6 git-worktree - Manage multiple worktrees
   7
   8
   9 SYNOPSIS
  10 --------
  11 [verse]
  12 'git worktree prune' [-n] [-v] [--expire <expire>]
  13
  14 DESCRIPTION
  15 -----------
  16
  17 Manage multiple worktrees attached to the same repository. These are
  18 created by the command `git checkout --to`.
  19
  20 A git repository can support multiple working trees, allowing you to check
  21 out more than one branch at a time.  With `git checkout --to` a new working
  22 tree is associated with the repository.  This new working tree is called a
  23 "linked working tree" as opposed to the "main working tree" prepared by "git
  24 init" or "git clone".  A repository has one main working tree (if it's not a
  25 bare repository) and zero or more linked working trees.
  26
  27 When you are done with a linked working tree you can simply delete it.
  28 The working tree's administrative files in the repository (see
  29 "DETAILS" below) will eventually be removed automatically (see
  30 `gc.pruneworktreesexpire` in linkgit::git-config[1]), or you can run
  31 `git worktree prune` in the main or any linked working tree to
  32 clean up any stale administrative files.
  33
  34 If you move a linked working directory to another file system, or
  35 within a file system that does not support hard links, you need to run
  36 at least one git command inside the linked working directory
  37 (e.g. `git status`) in order to update its administrative files in the
  38 repository so that they do not get automatically pruned.
  39
  40 If a linked working tree is stored on a portable device or network share
  41 which is not always mounted, you can prevent its administrative files from
  42 being pruned by creating a file named 'lock' alongside the other
  43 administrative files, optionally containing a plain text reason that
  44 pruning should be suppressed. See section "DETAILS" for more information.
  45
  46 COMMANDS
  47 --------
  48 prune::
  49
  50 Prune working tree information in $GIT_DIR/worktrees.
  51
  52 OPTIONS
  53 -------
  54
  55 -n::
  56 --dry-run::
  57         With `prune`, do not remove anything; just report what it would
  58         remove.
  59
  60 -v::
  61 --verbose::
  62         With `prune`, report all removals.
  63
  64 --expire <time>::
  65         With `prune`, only expire unused worktrees older than <time>.
  66
  67 DETAILS
  68 -------
  69 Each linked working tree has a private sub-directory in the repository's
  70 $GIT_DIR/worktrees directory.  The private sub-directory's name is usually
  71 the base name of the linked working tree's path, possibly appended with a
  72 number to make it unique.  For example, when `$GIT_DIR=/path/main/.git` the
  73 command `git checkout --to /path/other/test-next next` creates the linked
  74 working tree in `/path/other/test-next` and also creates a
  75 `$GIT_DIR/worktrees/test-next` directory (or `$GIT_DIR/worktrees/test-next1`
  76 if `test-next` is already taken).
  77
  78 Within a linked working tree, $GIT_DIR is set to point to this private
  79 directory (e.g. `/path/main/.git/worktrees/test-next` in the example) and
  80 $GIT_COMMON_DIR is set to point back to the main working tree's $GIT_DIR
  81 (e.g. `/path/main/.git`). These settings are made in a `.git` file located at
  82 the top directory of the linked working tree.
  83
  84 Path resolution via `git rev-parse --git-path` uses either
  85 $GIT_DIR or $GIT_COMMON_DIR depending on the path. For example, in the
  86 linked working tree `git rev-parse --git-path HEAD` returns
  87 `/path/main/.git/worktrees/test-next/HEAD` (not
  88 `/path/other/test-next/.git/HEAD` or `/path/main/.git/HEAD`) while `git
  89 rev-parse --git-path refs/heads/master` uses
  90 $GIT_COMMON_DIR and returns `/path/main/.git/refs/heads/master`,
  91 since refs are shared across all working trees.
  92
  93 See linkgit:gitrepository-layout[5] for more information. The rule of
  94 thumb is do not make any assumption about whether a path belongs to
  95 $GIT_DIR or $GIT_COMMON_DIR when you need to directly access something
  96 inside $GIT_DIR. Use `git rev-parse --git-path` to get the final path.
  97
  98 To prevent a $GIT_DIR/worktrees entry from from being pruned (which
  99 can be useful in some situations, such as when the
 100 entry's working tree is stored on a portable device), add a file named
 101 'locked' to the entry's directory. The file contains the reason in
 102 plain text. For example, if a linked working tree's `.git` file points
 103 to `/path/main/.git/worktrees/test-next` then a file named
 104 `/path/main/.git/worktrees/test-next/locked` will prevent the
 105 `test-next` entry from being pruned.  See
 106 linkgit:gitrepository-layout[5] for details.
 107
 108 EXAMPLES
 109 --------
 110 You are in the middle of a refactoring session and your boss comes in and
 111 demands that you fix something immediately. You might typically use
 112 linkgit:git-stash[1] to store your changes away temporarily, however, your
 113 worktree is in such a state of disarray (with new, moved, and removed files,
 114 and other bits and pieces strewn around) that you don't want to risk
 115 disturbing any of it. Instead, you create a temporary linked worktree to
 116 make the emergency fix, remove it when done, and then resume your earlier
 117 refactoring session.
 118
 119 ------------
 120 $ git branch emergency-fix master
 121 $ git checkout --to ../temp emergency-fix
 122 $ pushd ../temp
 123 # ... hack hack hack ...
 124 $ git commit -a -m 'emergency fix for boss'
 125 $ popd
 126 $ rm -rf ../temp
 127 $ git worktree prune
 128 ------------
 129
 130 BUGS
 131 ----
 132 Multiple checkout support for submodules is incomplete. It is NOT
 133 recommended to make multiple checkouts of a superproject.
 134
 135 git-worktree could provide more automation for tasks currently
 136 performed manually or via other commands, such as:
 137
 138 - `add` to create a new linked worktree
 139 - `remove` to remove a linked worktree and its administrative files (and
 140   warn if the worktree is dirty)
 141 - `mv` to move or rename a worktree and update its administrative files
 142 - `list` to list linked worktrees
 143 - `lock` to prevent automatic pruning of administrative files (for instance,
 144   for a worktree on a portable device)
 145
 146 SEE ALSO
 147 --------
 148
 149 linkgit:git-checkout[1]
 150
 151 GIT
 152 ---
 153 Part of the linkgit:git[1] suite