worktree-cd

Jump between Git worktrees by directory name, with native Zsh tab completion.

$ cwt <TAB>
factory-usb-serial  phoenix  phoenix-v1.10.5
$ cwt factory-usb-serial

Features

• Resolves worktrees registered to the current Git repository.
• Completes worktree directory names when you press Tab after cwt.
• Accepts either a worktree directory name or its full path.
• Handles paths containing spaces.
• Has no runtime dependencies beyond Git and Zsh.

Requirements

• Git with worktree support
• Zsh
• Oh My Zsh

Installation

Clone the repository into the Oh My Zsh custom plugins directory:

git clone https://github.com/pyang2045/worktree-cd.git \
  "${ZSH_CUSTOM:-$HOME/.oh-my-zsh/custom}/plugins/worktree-cd"

Add worktree-cd to the existing plugin list in ~/.zshrc:

plugins=(git worktree-cd)

Keep any other plugins already present in that list, then reload Zsh:

exec zsh

Usage

Run cwt from any worktree belonging to the repository you want to navigate.

Command	Description
cwt <name>	Enter a worktree by its directory name
cwt <full-path>	Enter a worktree by its absolute path
cwt --list	List the current repository's worktrees
cwt --help	Show command usage
cwt + Tab	Complete registered worktree names

For example, given these worktrees:

$ git worktree list
/Users/me/src/project                 abc1234 [main]
/Users/me/src/project-feature-login   def5678 [feature/login]

Enter the feature worktree with:

cwt project-feature-login

The lookup uses the worktree directory name, not its branch name. In this example, project-feature-login is valid and feature/login is not.

Updating

git -C "${ZSH_CUSTOM:-$HOME/.oh-my-zsh/custom}/plugins/worktree-cd" pull --ff-only
exec zsh

Troubleshooting

If cwt is not found, confirm that worktree-cd appears in the plugins=(...) line before Oh My Zsh is sourced, then start a new shell with exec zsh.

If no worktrees are listed, first enter one of the repository's worktrees. cwt intentionally scopes its results to the current repository.

Uninstalling

Remove worktree-cd from plugins=(...) in ~/.zshrc, then delete its plugin directory:

rm -rf "${ZSH_CUSTOM:-$HOME/.oh-my-zsh/custom}/plugins/worktree-cd"
exec zsh

Development

Validate the plugin and run its functional test with:

zsh -n worktree-cd.plugin.zsh
zsh test/plugin_test.zsh

License

MIT