worktree: add -b/-B options

diff --git a/Documentation/git-worktree.txt b/Documentation/git-worktree.txt
index 6afff1ed0c6cebf51a8819dd6b888ac28b2948cf..f44cd78784b9e23e861a7b342a9cfa5cbf6033c4 100644 (file)
--- a/Documentation/git-worktree.txt
+++ b/Documentation/git-worktree.txt
@@ -9,13 +9,13 @@ git-worktree - Manage multiple worktrees
 SYNOPSIS
 --------
 [verse]
+'git worktree add' [-f] [--detach] [-b <new-branch>] <path> <branch>
 'git worktree prune' [-n] [-v] [--expire <expire>]
 
 DESCRIPTION
 -----------
 
-Manage multiple worktrees attached to the same repository. These are
-created by the command `git checkout --to`.
+Manage multiple worktrees attached to the same repository.
 
 A git repository can support multiple working trees, allowing you to check
 out more than one branch at a time.  With `git checkout --to` a new working
@@ -45,6 +45,12 @@ pruning should be suppressed. See section "DETAILS" for more information.
 
 COMMANDS
 --------
+add <path> <branch>::
+
+Create `<path>` and checkout `<branch>` into it. The new working directory
+is linked to the current repository, sharing everything except working
+directory specific files such as HEAD, index, etc.
+
 prune::
 
 Prune working tree information in $GIT_DIR/worktrees.
@@ -52,6 +58,24 @@ Prune working tree information in $GIT_DIR/worktrees.
 OPTIONS
 -------
 
+-f::
+--force::
+       By default, `add` refuses to create a new worktree when `<branch>`
+       is already checked out by another worktree. 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 worktree.
+       By default, `-b` refuses to create a new branch if it already
+       exists. `-B` overrides this safeguard, resetting `<new-branch>` to
+       `<branch>`.
+
+--detach::
+       With `add`, detach HEAD in the new worktree. See "DETACHED HEAD" in
+       linkgit:git-checkout[1].
+
 -n::
 --dry-run::
        With `prune`, do not remove anything; just report what it would
@@ -117,8 +141,7 @@ make the emergency fix, remove it when done, and then resume your earlier
 refactoring session.
 
 ------------
-$ git branch emergency-fix master
-$ git checkout --to ../temp emergency-fix
+$ git worktree add -b emergency-fix ../temp master
 $ pushd ../temp
 # ... hack hack hack ...
 $ git commit -a -m 'emergency fix for boss'
@@ -133,9 +156,8 @@ Multiple checkout 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 or via other commands, such as:
+performed manually, such as:
 
-- `add` to create a new linked worktree
 - `remove` to remove a linked worktree and its administrative files (and
   warn if the worktree is dirty)
 - `mv` to move or rename a worktree and update its administrative files
@@ -143,11 +165,6 @@ performed manually or via other commands, such as:
 - `lock` to prevent automatic pruning of administrative files (for instance,
   for a worktree on a portable device)
 
-SEE ALSO
---------
-
-linkgit:git-checkout[1]
-
 GIT
 ---
 Part of the linkgit:git[1] suite