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?

I have checked out an other, pre-existing branch in the second worktree. Am I free to delete the branch that git worktree add created?

Fineman

I could be wrong, but my guess is that this branch is what you are actually on while working in the worktree. – Panthia

I think I should have specified the pre-existing branch I wanted to check out when I created the worktree, instead of switching branch afterwards. Then I would have avoided creating a new branch. – Fineman

I can't really say why they did it this way, but yes, you must specify a branch for the new work-tree, so they default to having it create a branch named the same as the new work-tree. They could have had git worktree add /path/to/foo fail without a -b or -B or final argument, instead of defaulting to using foo here, but my guess is they thought it was more convenient to default to using foo here. – Busey

If you don't want to create a new branch, you can run git worktree add --detach </path/to/worktree> and you will get a detached head instead. This is what I always do. If you are planning to checkout some existing branch, you can do git worktree add </path/to/worktree> <my-branch>. – Shiri

Note: for deleting worktree-related element: git worktree --remove (for Git 2.17+, Q2 2018): see my answer here – Eluviation

Answer 1

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.

Menstrual

Thanks! I asked about the double checkout issue separately in #39666070 – Fineman

Answer 2

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>

Sypher

A worktree doesn't necessarily go with it's own branch. So it's worth to add a reservation to the recommendation to delete the branch – Scrutable

After I did the rm -rf path/to/worktree and git worktree prune then the /.git/worktree directory I had got deleted. This is expected – Rollie

Answer 3

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

git worktree remove <path>

Hawthorne

That is Sweet 🍯 – Greenwald

Answer 4

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

Rotatory

Answer 5

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.

Cyrilla

Answer 6

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

Eluviation