worktree: add can be created from any commit-ish
authorThomas Gummerer <t.gummerer@gmail.com>
Sun, 26 Nov 2017 19:43:52 +0000 (19:43 +0000)
committerJunio C Hamano <gitster@pobox.com>
Mon, 27 Nov 2017 00:48:06 +0000 (09:48 +0900)
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>
Documentation/git-worktree.txt

index b472acc..1218952 100644 (file)
@@ -9,7 +9,7 @@ git-worktree - Manage multiple working trees
 SYNOPSIS
 --------
 [verse]
-'git worktree add' [-f] [--detach] [--checkout] [--lock] [-b <new-branch>] <path> [<branch>]
+'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 prune' [-n] [-v] [--expire <expire>]
@@ -45,14 +45,14 @@ 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. `-` may also be
-specified as `<branch>`; it is synonymous with `@{-1}`.
+specified as `<commit-ish>`; it is synonymous with `@{-1}`.
 +
-If `<branch>` is omitted and neither `-b` nor `-B` nor `--detach` used,
+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.
 
@@ -84,25 +84,25 @@ OPTIONS
 
 -f::
 --force::
-       By default, `add` refuses to create a new working tree when `<branch>`
+       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. 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].