worktree-aid

Git worktrees are a great way to work on multiple branches or copies of a git repository but are under-appreciated by many perhaps because the interface is somewhat cumbersome to use. worktree-aid is a command line tool to make using git worktrees more convenient. It allows you to easily add, remove, and change directories for git worktrees. Users can be prompted with list of worktrees using a fuzzy finder. worktree-aid runs on Linux, macOS, and Windows (via WSL).

After following the instructions in the Installation and Setup sections below, a wt shell command/alias is available to use to manage git worktrees. There are 3 commonly used commands:

• wt add (or wt a) to add a new worktree + branch and automatically cd to it. If you don't specify a worktree name, a new unique name will be automatically created for you. If you specify an existing branch name then a new worktree will be created for that branch.

• wt cd (or wt c) to change directory to a specified worktree. You can use / as a shortcut to the top-level repository directory. If you don't specify a worktree name, then a fuzzy finder will prompt you with a list of worktrees to select from and be cd'd to.

• wt rm (or wt r or wt remove) to remove a worktree + branch. You can use . as a shortcut for the current worktree. If you don't specify a worktree name, then a fuzzy finder will prompt you with a list of worktrees to select from. The current worktree is first in the list and is the default selection to remove. If you remove the current worktree then you will be automatically cd'd to the top-level repository directory.

There are some other less commonly used options and commands available, as described in the following sections. Type wt to see an overall help/usage summary, or wt <command> -h to see specific help/usage for any individual command.

The project homepage and latest documentation is at https://github.com/bulletmark/worktree-aid.

Usage

Type wt or wt -h to view the usage summary:

usage: wt [-P PATH] [-r] [-u] [-F FUZZY] [-H HASH_LEN] [-V] [-h]
                    {add,a,rm,r,remove,cd,c,ls,l,list,init,i} ...

Command line tool to easily add, remove, and change directories for git
worktrees. Prompts user with list of worktrees using fuzzy finder.

options:
  -P, --path PATH       directory path template for newly added worktrees,
                        default = "../worktrees/{repo}/{worktree}". Can use
                        {worktree}, {repo}, {user}, and {home} placeholders.
                        Must contain {worktree} at least.
  -r, --relative        toggle absolute/relative display of worktree paths,
                        default is absolute. Can be specified on command line
                        again to toggle your default setting.
  -u, --no-user         toggle substitution of "~" for user home directory,
                        default is to substitute. Can be specified on command
                        line again to toggle your default setting.
  -F, --fuzzy FUZZY     fuzzy finder program, default = "fzf"
  -H, --hash-len HASH_LEN
                        length of git commit hash to display in list, default
                        = 7, 0 = display full hash, -1 = do not display hash
  -V, --version         show program version and exit
  -h, --help            show help message and exit

Commands:
  {add,a,rm,r,remove,cd,c,ls,l,list,init,i}
    add (a)             Add new worktree + branch.
    rm (r, remove)      Remove worktree + branch.
    cd (c)              Change worktree directory.
    ls (l, list)        List worktrees.
    init (i)            Output shell initialization code and set default
                        options.

Type wt <command> -h to see specific help/usage for any individual command:

Command add

usage: wt add [-d] [-c] [-b BASE] [-h] [worktree ...]

Add new worktree + branch.

positional arguments:
  worktree         new worktree + branch to add. A name is automatically
                   created if not specified. Can also specify an existing
                   branch name to create a new worktree for that branch.

options:
  -d, --detach     add detached worktree only, i.e. without adding a new
                   branch
  -c, --no-cd      do not change directory to new worktree after adding it
  -b, --base BASE  base commit-ish to create worktree from, default is current
                   HEAD.
  -h, --help       show help message and exit

aliases: a

Command rm

usage: wt rm [-k] [-f] [-a] [-h] [worktree ...]

Remove worktree + branch.

positional arguments:
  worktree           worktree + branch name to remove. "." is a shortcut for
                     the current worktree. If not specified then fuzzy finder
                     will prompt with a list of worktrees, with the current
                     worktree as the default selection.

options:
  -k, --keep-branch  remove worktree but keep branch
  -f, --force        force removal of worktree + branch even if untracked or
                     unmerged changes exist.
  -a, --all          remove all worktrees
  -h, --help         show help message and exit

aliases: r, remove

Command cd

usage: wt cd [-h] [worktree]

Change worktree directory.

positional arguments:
  worktree    Worktree name to change directory to. "/" is a shortcut to the
              top-level repository. If not specified then fuzzy finder will
              prompt with a list of worktrees.

options:
  -h, --help  show help message and exit

aliases: c

Command ls

usage: wt ls [-h]

List worktrees.

options:
  -h, --help  show help message and exit

aliases: l, list

Command init

usage: wt init [-h] [command]

Output shell initialization code and set default options. Should be invoked
using `source <(worktree-aid init)` in your shell `~/.bashrc` or `~/.zshrc`
initialization file to create the shell alias/function by which you invoke
this program. You can also append preferred default options to the command
name, e.g. `source <(worktree-aid init "wt -r")`.

positional arguments:
  command     alternative command name, and optional default arguments,
              default = "wt"

options:
  -h, --help  show help message and exit

aliases: i

Installation or Upgrade

Python 3.10 or later is required. Install using uv tool:

$ uv tool install worktree-aid

# To upgrade:
$ uv tool upgrade worktree-aid

# To uninstall:
$ uv tool uninstall worktree-aid

Or, on Arch Linux:

$ yay -S worktree-aid  # or your preferred AUR helper

git is required to execute all commands. You also need to install a fuzzy finder program such as fzf which is the default used by worktree-aid. See fuzzy finder installation instructions for possible alternatives.

Setup

A user who wants to use worktree-aid must add the following line to their ~/.bashrc (bash user) or ~/.zshrc (zsh user). Ensure it is added after where your PATH is set up so that the command worktree-aid can be found (or specify the full path to worktree-aid). This creates the wt wrapper command in your interactive shell session as a tiny function.

source <(worktree-aid init)

Then log out and back in again to be able to use the new wt function in your shell.

Alternative Command Name

You can use an alternative command name instead of the default wt if you prefer. To do this, simply append your desired command name as the first argument to the worktree-aid init line in your shell initialization code.

E.g, to use the command name wx rather than the default wt, use the following in your shell init line:

source <(worktree-aid init wx)

Then log out/in, and then use wx command instead of the default wt.

Default Options

You can also set default worktree-aid options by appending options in your shell init line, e.g:

source <(worktree-aid init "wt -r")

The above sets -r (for relative display of worktree directories) as default for your wt command.

The following options are sensible candidates to set as default options: -P/--path, -r/--relative, -u/--no-user, -F/--fuzzy.

Directory Path Template for new Worktree Creation

The -P/--path option allows you to specify the directory path template for newly added worktrees. It is set to a default as below but you can change this to any directory you like. It can be absolute or relative where relative paths are relative to base top-level repository directory.

• Default base directory is -P ../worktrees/{repo}/{worktree}.
• E.g. can use -P ../worktrees/{repo}/{worktree}/{repo} which is same as Zed editor creates by default.
• E.g. can use -P ../{repo}.worktrees/{worktree} which is same as VS Code editor creates by default.
• E.g. can use -P ~/worktrees/{repo}/{worktree} to create all worktrees within a subdirectory of your home directory.

The following placeholders can be used in the definition of the directory template:

• {worktree}: Substituted with the name of the worktree/branch.
• {repo}: Substituted with the base name of the repository.
• {user}: Substituted with the name of the user.
• {home}: Substituted with the home directory of the user (also can use ~ at start of a path).

Your path definition must at least contain the {worktree} placeholder.

Most likely if you want to set a custom path then you will set -P as a default option.

Note that the -P/--path setting is only relevant when adding a new worktree using the add command. All other commands query your existing worktrees so will work regardless of how or where the worktrees were created.

Display as Relative Worktree Directories

The git worktree list command displays absolute directory paths, and worktree-aid does also by default, but you may prefer to display them as relative paths which git worktree does not provide. You can enable it in worktree-aid however, by adding the -r/--relative option, e.g:

$ wt l
../worktrees/worktree-aid/development 9796714 [development]
../worktrees/worktree-aid/milestone1  bc921b8 [milestone1]
../worktrees/worktree-aid/test        e6d965a [test]
                                      f76b8e0 [main]

Most likely you will want to set -r as a default option. Note you can use the -r option again on a one-off command to temporarily toggle whatever your default -r/--relative option is set as.

Fuzzy Finder Integration

fzf is by far the most popular command line fuzzy search/finder and is the default used by worktree-aid. You can however use any other fuzzy finder such as sk, tv, or fzy, etc.

E.g. to use sk, put this in your shell init line:

source <(worktree-aid init "wt -F sk")

You can also get fancy and add preview options etc to your fuzzy finder command line. Most likely you will want to set -F as a default option.

Moving or Copying Changes to Another Worktree

This program originally included a fetch command to copy changes from one worktree to another. However fetch has been removed because it is more flexible and essentially as easy to do using ordinary git commands.

E.g. A common situation is when you have been working within your main repo and you decide to move all your tracked and untracked file changes to a new feature branch in a worktree. So just stash your changes, add the new worktree, and then pop the stash in that new worktree:

$ git stash -u
$ wt a my-feature-branch
$ git stash pop

License

GPL-3.0-or-later.