wt

Tiny zsh helper for switching to existing git worktrees or creating a new one from a branch name.

Requirements

• zsh
• git
• fzf (required for interactive wt picker mode; not required for wt <branch-name>)

Install

Pick one of these installation paths.

1) Clone the repo (recommended)

git clone https://github.com/RyanJamesCaldwell/wt.git ~/.config/wt
echo 'source ~/.config/wt/wt.zsh' >> ~/.zshrc
source ~/.zshrc

2) Use a zsh plugin manager

wt.plugin.zsh exists for plugin-manager compatibility and sources wt.zsh.

# zinit
zinit light RyanJamesCaldwell/wt

# antigen
antigen bundle RyanJamesCaldwell/wt

# zplug
zplug "RyanJamesCaldwell/wt"

3) Download a single file

mkdir -p ~/.config/wt
curl -fsSL https://raw.githubusercontent.com/RyanJamesCaldwell/wt/main/wt.zsh -o ~/.config/wt/wt.zsh
echo 'source ~/.config/wt/wt.zsh' >> ~/.zshrc
source ~/.zshrc

Manual source example:

# ~/.zshrc
source /absolute/path/to/wt.zsh
# or
source /absolute/path/to/wt.plugin.zsh

Do not run ./wt.zsh directly; it defines a shell function and must be sourced.

Usage

• wt
  • Opens an fzf picker of existing worktrees and cds to the selection.
  • Rows are shown under a branch / created / updated / path column header, where created and updated are compact relative ages (for example 5m, 3h, 2d, 4w, 6mo, 1y).
  • Ctrl-N: open an fzf branch-name prompt, prefilled with your configured prefix, then create/switch worktree.
  • Ctrl-D: remove selected worktree (with confirmation; main worktree is protected).
• wt <branch-name>
  • If that branch already has a worktree, switches to it.
  • Otherwise creates a new worktree at ../<repo>-worktrees/<branch-name> and switches to it.
  • Branch names with / are preserved as nested directories (for example team/feature -> ../<repo>-worktrees/team/feature).

Branch Timestamps

The picker's created and updated columns are read straight from each branch's reflog file under .git/logs/refs/heads/: the first entry is when the branch was created locally, the last entry is when the branch ref last moved (commit, merge, rebase, reset, pull). That is a single file read per worktree with no extra git processes.

If a branch has no reflog (for example when core.logAllRefUpdates is disabled), created shows - and updated falls back to the tip commit date, resolved for all branches in one git for-each-ref call.

Branch Prefix

The Ctrl-N branch prompt uses the first available prefix from:

1. WT_BRANCH_PREFIX, including an explicitly empty value.
2. The repository or global Git setting wt.branchPrefix.
3. The active GitHub CLI login from gh auth status, lowercased and followed by /.

Set a persistent prefix with Git:

git config --global wt.branchPrefix 'ryanjamescaldwell/'

Or configure it in your shell:

export WT_BRANCH_PREFIX='ryanjamescaldwell/'

Set WT_BRANCH_PREFIX='' to disable both the Git setting and the automatic GitHub CLI default.

Dotfile Copy Behavior

When wt <branch-name> creates a new worktree, it copies these files from the main worktree root if they exist and are not already present in the new path:

• .mise.toml
• .node-version
• .nvmrc
• .python-version
• .ruby-version
• .tool-versions

Sensitive files are not copied by default:

• .env
• .env.local
• .envrc
• .npmrc

Enable sensitive-file copying:

WT_COPY_SENSITIVE_DOTFILES=1

You can set that flag either before sourcing wt.zsh or later in an existing shell session, as long as it is set before running wt <branch-name>.

Or fully override the copy list:

WT_DOTFILES_TO_COPY=(.nvmrc .tool-versions .env.local)
source /absolute/path/to/wt.zsh

Tested Platforms

• macOS with zsh 5.9