A tmux plugin to create, switch between, and clean up git worktrees without leaving your terminal.
Demo: prefix + W opens a picker — type a branch name, press Enter, and
you're in a fresh tmux window pointing at that worktree. prefix + D removes
one just as fast.
Add to ~/.tmux.conf and reload (prefix + I):
set -g @plugin 'gbrennon/tmux-worktrees'Requires fzf on your $PATH. Also needs tmux >= 2.4, git >= 2.5,
bash >= 4.0.
# Fedora | # Debian/Ubuntu | # Arch | # macOS
sudo dnf install fzf | sudo apt install fzf | sudo pacman -S fzf | brew install fzf| Keys | What it does | Details |
|---|---|---|
prefix + W |
Create or switch to worktree | docs |
prefix + D |
Remove merged/stale worktrees | docs |
prefixisCtrl-bby default. Override the keys by setting these variables in~/.tmux.confbefore the plugin line — for example:set -g @worktree-key 'T' # prefix + T to pick a worktree set -g @worktree-cleanup-key 'X' # prefix + X to clean up set -g @worktree-dir 'my-trees' # custom worktree directoryMore details: Customise the keys. You can also change the shell that opens in new windows. Or change the worktree directory.
cd ~/my-project
prefix + W
Type feat/foo -> Enter. A worktree is created (by default at .worktrees/feat-foo)
and a new tmux window wt-feat/foo opens there. Press prefix + W again to switch
between worktrees, prefix + D to clean up.
Examples use conventional branch prefixes (
feat/,fix/,chore/), but any branch name works —my-branchorbugfix/loginare equally valid.
| Topic | |
|---|---|
| Creating worktrees | Step-by-step walkthrough |
| Switching worktrees | Using the picker as a dashboard |
| Cleaning up | Removing worktrees and branches |
| Customise keys | Change W / D bindings |
| Customise shell | Launch bash, zsh, vim, emacs, etc. |
| Customise worktree dir | Use a different worktree directory |
| How it works | Under-the-hood architecture |
Run the full test suite from the project root:
bash tests/run.shRequires git >= 2.28 (for init.defaultBranch support) and bash >= 4.0.
Tests create and tear down temporary git repositories in /tmp — no project
files are touched.
MIT