List worktrees

Time to read:	Activity duration:
5 minutes	5 minutes

Overview

git worktree list

The list subcommand for git worktree will display all the worktrees that you have created for your local clone.

Result will show:

• the filesystem folder location.
• the SHA of the HEAD in this worktree;
• the branch name attached to this worktree.

Activity goal

In this activity you will learn how to check the available worktrees in an existing repository, so you can manage them.

Setup activity

Call the helper script to create the wt_list activity:

Command

./scripts/create-playground.sh wt_list

Result

[INFO] Starting activity builder for 'wt_list'
[INFO] Created activity folder: /Users/sylvain/dev/lab/git-tutorials/playgrounds/wt_list
Cloning into 'nanorpm_main'...
remote: Enumerating objects: 252, done.
remote: Total 252 (delta 0), reused 0 (delta 0), pack-reused 252 (from 1)
Receiving objects: 100% (252/252), 497.60 KiB | 2.11 MiB/s, done.
Resolving deltas: 100% (147/147), done.
[Step] Cloned repository https://gitlab.com/sgamel-projects/nanorpn.git
Already on 'main'
Your branch is up to date with 'origin/main'.
branch 'dev/coverage-improv' set up to track 'origin/dev/coverage-improv'.
Switched to a new branch 'dev/coverage-improv'
Switched to branch 'main'
Your branch is up to date with 'origin/main'.
[INFO] Successfully built activity 'wt_list' in /Users/sylvain/dev/lab/git-tutorials/playgrounds/wt_list
[INFO] You can now navigate to /Users/sylvain/dev/lab/git-tutorials/playgrounds/wt_list to work on the activity.

cd /Users/sylvain/dev/lab/git-tutorials/playgrounds/wt_list

The activity playground folder contains three sub-folders, each associated to a branch:

Worktree path	Git branch	Comment
nanorpm_main	main	default branch
nanorpm_cov	dev/coverage-improv	created from remote repository
nanorpm_feat	feature-a	local branch

Check list of worktrees

Your current working directory should now be the playgrounds/wt_list/nanorpm_main folder.

cd playgrounds/wt_list/nanorpm_main

Check the list of branches in this local repository:

Command

git branch -l

Result

  dev/coverage-improv
  feature-a
* main

Obviously you can check the list of folder in parent directory, but you cannot know if these are worktree or not.

So, how can we list the available worktrees and their information?

Command

git worktree list

Result

/Users/sylvain/dev/lab/git-tutorials/playgrounds/wt_list/nanorpm_main  4188ec5 [main]
/Users/sylvain/dev/lab/git-tutorials/playgrounds/wt_list/nanorpm_cov   6705405 [dev/coverage-improv]
/Users/sylvain/dev/lab/git-tutorials/playgrounds/wt_list/nanorpm_feat  4188ec5 [feature-a]

Note that result display a table with three columns:

1. path of the worktree;
2. SHA of the HEAD in this worktree;
3. the name of the branch bound to the worktree.

At this point, if you followed both add activity and this one, you know how to create new worktree and view the existing ones in your local clone.

Note

In this example we've stored each worktree in the same parent directory. This is not a mandatory behavior, it just makes easier to find worktrees.

It's time to learn to clean thing up by removing worktrees that you no longer use.

Missing worktree

There's always a chance to break something. What if you delete a worktree by mistake?

Just experiment with this scenario. First delete the folder nanorpm_feat:

rm -rf ../nanorpm_feat/

And try to check again the list of worktrees:

Command

git worktree list

Result

/Users/sylvain/dev/lab/git-tutorials/playgrounds/wt_list/nanorpm_main  4188ec5 [main]
/Users/sylvain/dev/lab/git-tutorials/playgrounds/wt_list/nanorpm_cov   6705405 [dev/coverage-improv]
/Users/sylvain/dev/lab/git-tutorials/playgrounds/wt_list/nanorpm_feat  4188ec5 [feature-a] prunable

You will certainly spot the difference for the nanorpm_featworktree. Now, the description end with prunable annotation.

This is the indication that this worktree can be purged as it's no longer necessary. This can occur when folder was deleted, the scenario we just tested, or this worktree is no longer referenced by an existing branch (for example the branch was deleted).

Prunable worktree can be deleted with specific Git worktree sub-command. The next section will show you how to remove a worktree.