Git add a worktree from existing remote branch

TL;DR: you probably wanted git worktree add ../north north

First, a reminder (or information for others coming across this question): git worktree add wants to create a new work-tree and, at the same time, make sure that this new work-tree is using a different branch name from every other work-tree. This is because, while each added work-tree has its own index and HEAD, the HEAD files wind up sharing the underlying branch pointers in the shared repository. Having two different work-trees with independent index objects but the same underlying branch leads to some tricky problems for users to deal with. Rather than trying to figure out how to deal with these—by either educating programmers or providing tools to deal with the problems—git worktree simply forbids the situation entirely.

Hence, it's pretty typical to want to create a new branch name when creating a new work-tree. By definition, a new branch name is automatically different from every existing branch name:

$ git checkout -b newbranch
Switched to a new branch 'newbranch'
$ git checkout -b newbranch
fatal: A branch named 'newbranch' already exists.

This seems pretty natural: no one is ever surprised by this.

You're running git worktree add in a way that is just like git checkout -b, except that the checkout occurs in the new added work-tree. But you already have a branch named north.

If this existing north branch is not useful, you can delete it. Now you don't have a local branch named north and you can create a new one.

If this existing north branch is useful, don't delete it! If it's already checked out in some existing work-tree, move to that work-tree and work on it there. If it's not checked out in some existing work-tree, you can make a new work-tree that does have it checked out; you just need to avoid using the -b flag (and the corresponding branch name):

git worktree add ../north north

Note that when you're creating a new branch, you do not have to repeat yourself:

git worktree add -b newbranch ../path

will create a new work-tree in ../path, and use git checkout -b newbranch to populate it. You only need the branch name when:

1. you're not using -b, and
2. the path argument does not end in the name of the branch.

For instance, if you want to check out the existing branch zorg in a new work-tree in path ../zorg, you can just run:

git worktree add ../zorg

Here, since there is neither a -b zorg nor a final argument, Git figures out the branch name by using the last part of ../zorg, which is of course just zorg, so this tries to check out the existing branch zorg into the new work-tree.

For this problem, worktree add does need a --checkout switch to do so:

$ git worktree add --checkout ../north north
$ git worktree add --checkout ../razavi razavi

In addition of "guessing the remote branch", as I explain in my other answer, Git 2.18 (Q2 2018) will offer a new feature:
"git worktree add" learned to check out an existing branch.

See commit f60a7b7, commit 6427f87, commit 2c27002, commit d861d34 (24 Apr 2018) by Thomas Gummerer (tgummerer).
Helped-by: Eric Sunshine (sunshineco).
^{(Merged by Junio C Hamano -- gitster -- in commit 10174da, 23 May 2018)}

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.

The documentation now states:

$ 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, 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).

Git 2.30 (Q1 2021) fixes the formulation of an error message with two placeholders in "git worktree add"^(man) subcommand.

See commit b86339b (20 Nov 2020) by Matheus Tavares (matheustavares).
^{(Merged by Junio C Hamano -- gitster -- in commit f73ee0c, 30 Nov 2020)}

worktree: fix order of arguments in error message

^{Signed-off-by: Matheus Tavares
Reviewed-by: Eric Sunshine}

git worktree add^(man) (without --force) errors out when given a path that is already registered as a worktree and the path is missing on disk.
But the cmd and path strings are switched on the error message.
Let's fix that.

This is about the error messages:

<path> is a missing but locked worktree
use '<cmd> -f -f' to override, or 'unlock' and 'prune' or 'remove' to clear

Or:

<path> is a missing but already registered worktree
use '<cmd> -f' to override, or 'unlock' and 'prune' or 'remove' to clear

From the comments:

It doesn't work! I try git worktree add ../north north, and as I said it gives me an error fatal:

'north' is already checked out at 'C:/Source/nis'

That error message should be clearer now (Q1 2022).

With Git 2.35 (Q1 2022), "git worktree add"^(man) showed "Preparing worktree" message to the standard output stream, but when it failed, the message from die() went to the standard error stream.
Depending on the order the stdio streams are flushed at the program end, this resulted in confusing output.
It has been corrected by sending all the chatty messages to the standard error stream.

See commit b502524, commit da8fb6b (02 Dec 2021) by Eric Sunshine (sunshineco).
^{(Merged by Junio C Hamano -- gitster -- in commit 986eb34, 15 Dec 2021)}

worktree: send "chatty" messages to stderr

^{Reported-by: Baruch Burstein
Signed-off-by: Eric Sunshine}

The order in which the stdout and stderr streams are flushed is not guaranteed to be the same across platforms or libc implementations.
This lack of determinism can lead to anomalous and potentially confusing output if normal (stdout) output is flushed after error (stderr) output.
For instance, the following output which clearly indicates a failure due to a fatal error:

% git worktree add ../foo bar
Preparing worktree (checking out 'bar')
fatal: 'bar' is already checked out at '.../wherever'

has been reported on Microsoft Windows to appear as:

% git worktree add ../foo bar
fatal: 'bar' is already checked out at '.../wherever'
Preparing worktree (checking out 'bar')

which may confuse the reader into thinking that the command somehow recovered and ran to completion despite the error.

This problem crops up because the "chatty" status message "Preparing worktree" is sent to stdout, whereas the "fatal" error message is sent to stderr.

A common practice in Git is for "chatty" messages to be sent to stderr.
Therefore, a more appropriate fix is to adjust git-worktree to conform to that practice by sending its chatty messages to stderr rather than stdout as is currently the case.

There may be concern that relocating messages from stdout to stderr could break existing tooling, however, these messages are already internationalized, thus are unstable.
And, indeed, the "Preparing worktree" message has already been the subject of somewhat significant changes in 2c27002 ("worktree: improve message when creating a new worktree", 2018-04-24, Git v2.18.0-rc0 -- merge listed in batch #6).
Moreover, there is existing precedent, such as 68b939b ("clone: send diagnostic messages to stderr", 2013-09-18, Git v1.8.5-rc0 -- merge) which likewise relocated "chatty" messages from stdout to stderr for git-clone.

In addition of git worktree add --checkout, Git 2.16 (Q1 2018) will propose another alternative:

The way "git worktree add" determines what branch to create from where and checkout in the new worktree has been updated a bit.

See commit e92445a, commit 71d6682 (29 Nov 2017), and commit 4e85333, commit e284e89, commit c4738ae, commit 7c85a87 (26 Nov 2017) by Thomas Gummerer (tgummerer).
^{(Merged by Junio C Hamano -- gitster -- in commit 66d3f19, 19 Dec 2017)}

add worktree.guessRemote config option

Some users might want to have the --guess-remote option introduced in the previous commit on by default, so they don't have to type it out every time they create a new worktree.

Add a config option worktree.guessRemote that allows users to configure the default behaviour for themselves.

The documentation for git config now reads:

worktree.guessRemote::

With add, if no branch argument, and neither of -b nor -B nor --detach are given, the command defaults to creating a new branch from HEAD.
If worktree.guessRemote is set to true, worktree add tries to find a remote-tracking branch whose name uniquely matches the new branch name.

• If such a branch exists, it is checked out and set as "upstream" for the new branch.
• If no such match can be found, it falls back to creating a new branch from the current HEAD.

Actually, Git 2.21 (Q1 2019) clarifies the documentation for this option, which jumped right in with "With add", without explaining that add is a sub-command of "git worktree".

See commit b4583d5 (23 Dec 2018) by Eric Sunshine (sunshineco).
^{(Merged by Eric Sunshine -- sunshineco -- in commit b4583d5, 28 Dec 2018)}

The documentation now reads:

worktree.guessRemote:

If no branch is specified and neither -b nor -B nor --detach is used, then git worktree add defaults to creating a new branch from HEAD.