worktree: add can be created from any commit-ish
Currently 'git worktree add' is documented to take an optional <branch> argument, which is checked out in the new worktree. However it is more generally possible to use a commit-ish as the optional argument, and check that out into the new worktree. Document that this is a possibility, as new users of git worktree add might find it helpful. Reported-by: Randall S. Becker <rsbecker@nexbridge.com> Signed-off-by: Thomas Gummerer <t.gummerer@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Thomas Gummerer committed
Nov 26, 2017 at 19:43 UTC
c4738aedc0aee085e25e20b6c32b9c4680f265d1
1 file changed
+10
-10
Documentation/git-worktree.txt
+10
-10
@@ -9,7 +9,7 @@ git-worktree - Manage multiple working trees
9
SYNOPSIS
10
--------
11
[verse]
12
-'git worktree add' [-f] [--detach] [--checkout] [--lock] [-b <new-branch>] <path> [<branch>]
12
+'git worktree add' [-f] [--detach] [--checkout] [--lock] [-b <new-branch>] <path> [<commit-ish>]
13
'git worktree list' [--porcelain]
14
'git worktree lock' [--reason <string>] <worktree>
15
'git worktree prune' [-n] [-v] [--expire <expire>]
@@ -45,14 +45,14 @@ specifying `--reason` to explain why the working tree is locked.
45
46
COMMANDS
47
--------
48
-add <path> [<branch>]::
48
+add <path> [<commit-ish>]::
49
50
-Create `<path>` and checkout `<branch>` into it. The new working directory
50
+Create `<path>` and checkout `<commit-ish>` into it. The new working directory
51
is linked to the current repository, sharing everything except working
52
directory specific files such as HEAD, index, etc. `-` may also be
53
-specified as `<branch>`; it is synonymous with `@{-1}`.
53
+specified as `<commit-ish>`; it is synonymous with `@{-1}`.
54
+
55
-If `<branch>` is omitted and neither `-b` nor `-B` nor `--detach` used,
55
+If `<commit-ish>` is omitted and neither `-b` nor `-B` nor `--detach` used,
56
then, as a convenience, a new branch based at HEAD is created automatically,
57
as if `-b $(basename <path>)` was specified.
58
@@ -84,25 +84,25 @@ OPTIONS
84
85
-f::
86
--force::
87
- By default, `add` refuses to create a new working tree when `<branch>`
87
+ By default, `add` refuses to create a new working tree when `<commit-ish>` is a branch name and
88
is already checked out by another working tree. This option overrides
89
that safeguard.
90
91
-b <new-branch>::
92
-B <new-branch>::
93
With `add`, create a new branch named `<new-branch>` starting at
94
- `<branch>`, and check out `<new-branch>` into the new working tree.
95
- If `<branch>` is omitted, it defaults to HEAD.
94
+ `<commit-ish>`, and check out `<new-branch>` into the new working tree.
95
+ If `<commit-ish>` is omitted, it defaults to HEAD.
96
By default, `-b` refuses to create a new branch if it already
97
exists. `-B` overrides this safeguard, resetting `<new-branch>` to
98
- `<branch>`.
98
+ `<commit-ish>`.
99
100
--detach::
101
With `add`, detach HEAD in the new working tree. See "DETACHED HEAD"
102
in linkgit:git-checkout[1].
103
104
--[no-]checkout::
105
- By default, `add` checks out `<branch>`, however, `--no-checkout` can
105
+ By default, `add` checks out `<commit-ish>`, however, `--no-checkout` can
106
be used to suppress checkout in order to make customizations,
107
such as configuring sparse-checkout. See "Sparse checkout"
108
in linkgit:git-read-tree[1].