diff options
Diffstat (limited to 'Documentation/git-worktree.txt')
| -rw-r--r-- | Documentation/git-worktree.txt | 129 |
1 files changed, 94 insertions, 35 deletions
diff --git a/Documentation/git-worktree.txt b/Documentation/git-worktree.txt index c62234538b..e7eb24ab85 100644 --- a/Documentation/git-worktree.txt +++ b/Documentation/git-worktree.txt @@ -9,9 +9,13 @@ git-worktree - Manage multiple working trees SYNOPSIS -------- [verse] -'git worktree add' [-f] [--detach] [--checkout] [-b <new-branch>] <path> [<branch>] -'git worktree prune' [-n] [-v] [--expire <expire>] +'git worktree add' [-f] [--detach] [--checkout] [--lock] [-b <new-branch>] <path> [<commit-ish>] 'git worktree list' [--porcelain] +'git worktree lock' [--reason <string>] <worktree> +'git worktree move' <worktree> <new-path> +'git worktree prune' [-n] [-v] [--expire <expire>] +'git worktree remove' [--force] <worktree> +'git worktree unlock' <worktree> DESCRIPTION ----------- @@ -32,32 +36,33 @@ The working tree's administrative files in the repository (see `git worktree prune` in the main or any linked working tree to clean up any stale administrative files. -If you move a linked working tree, you need to manually update the -administrative files so that they do not get pruned automatically. See -section "DETAILS" for more information. - If a linked working tree is stored on a portable device or network share which is not always mounted, you can prevent its administrative files from -being pruned by creating a file named 'locked' alongside the other -administrative files, optionally containing a plain text reason that -pruning should be suppressed. See section "DETAILS" for more information. +being pruned by issuing the `git worktree lock` command, optionally +specifying `--reason` to explain why the working tree is locked. COMMANDS -------- -add <path> [<branch>]:: +add <path> [<commit-ish>]:: -Create `<path>` and checkout `<branch>` into it. The new working directory +Create `<path>` and checkout `<commit-ish>` into it. The new working directory is linked to the current repository, sharing everything except working -directory specific files such as HEAD, index, etc. +directory specific files such as HEAD, index, etc. `-` may also be +specified as `<commit-ish>`; it is synonymous with `@{-1}`. ++ +If <commit-ish> is a branch name (call it `<branch>`) and is not found, +and neither `-b` nor `-B` nor `--detach` are used, but there does +exist a tracking branch in exactly one remote (call it `<remote>`) +with a matching name, treat as equivalent to: + -If `<branch>` is omitted and neither `-b` nor `-B` nor `--detached` used, +------------ +$ git worktree add --track -b <branch> <path> <remote>/<branch> +------------ ++ +If `<commit-ish>` is omitted and neither `-b` nor `-B` nor `--detach` used, then, as a convenience, a new branch based at HEAD is created automatically, as if `-b $(basename <path>)` was specified. -prune:: - -Prune working tree information in $GIT_DIR/worktrees. - list:: List details of each worktree. The main worktree is listed first, followed by @@ -65,34 +70,84 @@ each of the linked worktrees. The output details include if the worktree is bare, the revision currently checked out, and the branch currently checked out (or 'detached HEAD' if none). +lock:: + +If a working tree is on a portable device or network share which +is not always mounted, lock it to prevent its administrative +files from being pruned automatically. This also prevents it from +being moved or deleted. Optionally, specify a reason for the lock +with `--reason`. + +move:: + +Move a working tree to a new location. Note that the main working tree +or linked working trees containing submodules cannot be moved. + +prune:: + +Prune working tree information in $GIT_DIR/worktrees. + +remove:: + +Remove a working tree. Only clean working trees (no untracked files +and no modification in tracked files) can be removed. Unclean working +trees or ones with submodules can be removed with `--force`. The main +working tree cannot be removed. + +unlock:: + +Unlock a working tree, allowing it to be pruned, moved or deleted. + OPTIONS ------- -f:: --force:: - By default, `add` refuses to create a new working tree when `<branch>` - is already checked out by another working tree. This option overrides - that safeguard. + By default, `add` refuses to create a new working tree when + `<commit-ish>` is a branch name and is already checked out by + another working tree and `remove` refuses to remove an unclean + working tree. This option overrides that safeguard. -b <new-branch>:: -B <new-branch>:: With `add`, create a new branch named `<new-branch>` starting at - `<branch>`, and check out `<new-branch>` into the new working tree. - If `<branch>` is omitted, it defaults to HEAD. + `<commit-ish>`, and check out `<new-branch>` into the new working tree. + 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 - `<branch>`. + `<commit-ish>`. --detach:: With `add`, detach HEAD in the new working tree. See "DETACHED HEAD" in linkgit:git-checkout[1]. --[no-]checkout:: - By default, `add` checks out `<branch>`, however, `--no-checkout` can + 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 linkgit: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. ++ +This can also be set up as the default behaviour by using the +`worktree.guessRemote` config option. + +--[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 linkgit:git-branch[1] for details. + +--lock:: + Keep the working tree locked after creation. This is the + equivalent of `git worktree lock` after `git worktree add`, + but without race condition. + -n:: --dry-run:: With `prune`, do not remove anything; just report what it would @@ -110,6 +165,18 @@ OPTIONS --expire <time>:: With `prune`, only expire unused working trees older than <time>. +--reason <string>:: + With `lock`, an explanation why the working tree is locked. + +<worktree>:: + Working trees can be identified by path, either relative or + absolute. ++ +If the last path components in the working tree's path is unique among +working trees, it can be used to identify worktrees. For example if +you only have two working trees, at "/abc/def/ghi" and "/abc/def/ggg", +then "ghi" or "def/ghi" is enough to point to the former working tree. + DETAILS ------- Each linked working tree has a private sub-directory in the repository's @@ -141,7 +208,7 @@ thumb is do not make any assumption about whether a path belongs to $GIT_DIR or $GIT_COMMON_DIR when you need to directly access something inside $GIT_DIR. Use `git rev-parse --git-path` to get the final path. -If you move a linked working tree, you need to update the 'gitdir' file +If you manually move a linked working tree, you need to update the 'gitdir' file in the entry's directory. For example, if a linked working tree is moved to `/newpath/test-next` and its `.git` file points to `/path/main/.git/worktrees/test-next`, then update @@ -150,7 +217,8 @@ instead. To prevent a $GIT_DIR/worktrees entry from being pruned (which can be useful in some situations, such as when the -entry's working tree is stored on a portable device), add a file named +entry's working tree is stored on a portable device), use the +`git worktree lock` command, which adds a file named 'locked' to the entry's directory. The file contains the reason in plain text. For example, if a linked working tree's `.git` file points to `/path/main/.git/worktrees/test-next` then a file named @@ -220,15 +288,6 @@ Multiple checkout in general is still experimental, and the support for submodules is incomplete. It is NOT recommended to make multiple checkouts of a superproject. -git-worktree could provide more automation for tasks currently -performed manually, such as: - -- `remove` to remove a linked working tree and its administrative files (and - warn if the working tree is dirty) -- `mv` to move or rename a working tree and update its administrative files -- `lock` to prevent automatic pruning of administrative files (for instance, - for a working tree on a portable device) - GIT --- Part of the linkgit:git[1] suite |