Why does git worktree add create a branch, and can I delete it?

Question

I used git worktree add to create a new worktree. I noticed that is has created a new branch in the repo with the same name as the worktree. What is this branch for

Answer 1

git worktree --help clearly mentions this as below.

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.

           If <branch> is omitted and neither -b nor -B is used, then, as a convenience, a new branch based at HEAD is created automatically,
           as if -b $(basename <path>) was specified.

       prune
           Prune working tree information in $GIT_DIR/worktrees.

Answer 2

Seems you can run in detached mode with --detach, which won't create branches. This may be useful if you don't plan to do modifications in the worktree, but just run build or run tests for example.

Source: https://stacktoheap.com/blog/2016/01/19/using-multiple-worktrees-with-git/#long-running-tasks

Answer 3

The branch is necessary because you cannot have the same branch checked out in different worktrees at the same time.

So if you do not specify a branch when adding the worktree, then git will add one automatically, based on your current branch and with the name of the worktree directory.

You may ask, why cannot I have the same branch checkout out twice? Think of what will happen to worktree A when you commit to B, if they both share the branch... the worktree A will see the commit in B as a local difference, but in reverse! just as if you did git reset --soft HEAD^... That would be quite dangerous.

BTW, that is the same reason why you cannot push to a branch of a non-bare repository that is checked out.

About your last question: can you delete the branch? Of course, that branch is in no way special. You can delete it as long as it is not checked out anywhere.

Answer 4

From Git 2.17.0, you can safely run this all-in-one command

git worktree remove <path>

Answer 5

git worktree will add a new branch if none are specified:

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.

Since Git 2.17, you can delete that branch with git worktree remove.

But, that same remove command also included:

Unclean working trees or ones with submodules can be removed with --force.
The main working tree cannot be removed.

True... except --force was not fully implemented in Git 2.17.

With Git 2.18 (Q2 2018), "git worktree remove" learned that "-f" is a shorthand for "--force" option, just like for "git worktree add".

See commit d228eea (17 Apr 2018) by Stefan Beller (stefanbeller).
Helped-by: Eric Sunshine (sunshineco).
^{(Merged by Junio C Hamano -- gitster -- in commit 90186fa, 08 May 2018)}

worktree: accept -f as short for --force for removal

Many commands support a "--force" option, frequently abbreviated as "-f".
However, "git worktree remove"'s hand-rolled OPT_BOOL forgets to recognize the short form, despite git-worktree.txt documenting "-f" as supported.
Replace OPT_BOOL with OPT__FORCE, which provides "-f" for free, and makes 'remove' consistent with 'add' option parsing (which also specifies the PARSE_OPT_NOCOMPLETE flag).

Answer 6

As the other guys answer this question, I put commands to delete the folder, delete worktree and delete branch here:

first, list all of your worktrees to double check...

$ git worktree list

then, delete the folder of the worktree

$ rm -rf path/to/worktree

after that, delete the worktree itself

$ git worktree prune

in case you have more than one worktree, the above command only prune the worktree that its path doesn't exist anymore, so don't worry!

finally, delete the branch (same branch-name as the worktree)

$ git branch -D <branch-name>