path: root/Documentation
diff options
authorThomas Gummerer <>2018-04-24 21:56:35 (GMT)
committerJunio C Hamano <>2018-04-30 00:06:34 (GMT)
commitf60a7b763fe070161b332d3878f81a7f09ab6e44 (patch)
tree0359d260102a9bfd21292a4bf3a7fe6eb83d0377 /Documentation
parent6427f87186e53d9d4319d43e4efbe46bb93b7440 (diff)
worktree: teach "add" to check out existing branches
Currently 'git worktree add <path>' creates a new branch named after the basename of the path by default. If a branch with that name already exists, the command refuses to do anything, unless the '--force' option is given. However we can do a little better than that, and check the branch out if it is not checked out anywhere else. This will help users who just want to check an existing branch out into a new worktree, and save a few keystrokes. As the current behaviour is to simply 'die()' when a branch with the name of the basename of the path already exists, there are no backwards compatibility worries here. We will still 'die()' if the branch is checked out in another worktree, unless the --force flag is passed. Helped-by: Eric Sunshine <> Signed-off-by: Thomas Gummerer <> Reviewed-by: Eric Sunshine <> Signed-off-by: Junio C Hamano <>
Diffstat (limited to 'Documentation')
1 files changed, 7 insertions, 2 deletions
diff --git a/Documentation/git-worktree.txt b/Documentation/git-worktree.txt
index 41585f5..5d54f36 100644
--- a/Documentation/git-worktree.txt
+++ b/Documentation/git-worktree.txt
@@ -61,8 +61,13 @@ $ 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.
+then, as a convenience, the new worktree is associated with a branch
+(call it `<branch>`) named after `$(basename <path>)`. If `<branch>`
+doesn't exist, a new branch based on HEAD is automatically created as
+if `-b <branch>` was given. If `<branch>` does exist, it will be
+checked out in the new worktree, if it's not checked out anywhere
+else, otherwise the command will refuse to create the worktree (unless
+`--force` is used).