Skip to content
Projects

ahmedelgabri/git-wt has 80 GitHub stars and 8 forks. GitHot measured 0 stars in 24 hours. Last checked 2026-11-15 15:32 UTC. Last push 2026-10-10.

How these counts are measured

Measured star growth

in 24h
0
in 7 days
Update delayed
in 15 days
Update delayed
in 1 month
Update delayed

Net star changes over overlapping periods, not daily totals. Missing measurements are left blank. Stars measure attention, not software quality.

About

A git custom command that enhances Git's native worktree functionality with interactive features, automation, and repository migration capabilities.

Developer Tools

README.md

Original
Logo

git-wt

Work on several Git branches at once, each in its own directory. No need to stash changes when switching tasks.

git-wt helps you create, switch, and remove these directories, called worktrees. Pick branches interactively or pass their names directly.

It stores Git data in .bare/, with your worktrees next to it:

my-project/
├── .bare/       # Shared Git data
├── .git         # Points to .bare
├── main/        # Main branch
└── feature/     # Feature branch

Read why this layout works.

Contents

Installation

Requires Git 2.48.0 or newer.

Homebrew

brew install ahmedelgabri/tap/git-wt

Includes shell completions for bash, zsh, and fish.

mise

mise use "github:ahmedelgabri/git-wt"

Nix flakes

Run without installing:

nix run github:ahmedelgabri/git-wt

Or add it to your flake inputs:

{
  inputs.git-wt.url = "github:ahmedelgabri/git-wt";
}

Then include inputs.git-wt.packages.${system}.default in your packages.

Manual installation

Download the archive for your platform from the latest release.

Extract it and copy git-wt to a directory in your $PATH:

tar xzf git-wt-VERSION-OS-ARCH.tar.gz
cp git-wt-VERSION-OS-ARCH/git-wt ~/.local/bin/

Replace VERSION, OS, and ARCH with the values in the archive name.

Shell completions

For manual installs, copy files from the archive's completions/ directory:

# Bash
cp completions/git-wt.bash ~/.local/share/bash-completion/completions/git-wt

# Zsh
cp completions/_git-wt ~/.local/share/zsh/site-functions/_git-wt
cp completions/_git_wt ~/.local/share/zsh/site-functions/_git_wt

# Fish
cp completions/git-wt.fish ~/.config/fish/completions/git-wt.fish

Zsh needs both files. _git-wt completes git-wt; _git_wt completes git wt.

Usage

Clone a repository

git wt clone https://github.com/user/repo.git
cd repo

This creates the .bare/ layout and a worktree for the default branch.

If setup fails after downloading, git-wt keeps the repository and prints recovery instructions.

Convert an existing repository

cd existing-repo
git wt migrate

Migration is experimental. Stop editors, builds, and other Git operations before running it.

It moves your files into a worktree and changes .git to .bare. It checks that your files and Git state survived the move.

A failed or interrupted migration restores the original layout. After a crash, run git wt migrate again to restore it.

Read the migration limits and recovery guide before converting a repository.

Create a worktree

# Choose a branch interactively
git wt add

# Use an existing remote branch
git wt add feature origin/feature

# Create a new branch and worktree
git wt add -b new-feature new-feature

add requires the .bare/ layout. It prints the new worktree's path so scripts can use it.

Run git wt add --help for more options.

Switch worktrees

cd "$(git wt switch)"

To let git wt switch change directories directly, add the matching line to your shell configuration:

# Bash: ~/.bashrc
eval "$(git-wt init bash)"

# Zsh: ~/.zshrc
eval "$(git-wt init zsh)"

# Fish: ~/.config/fish/config.fish
git-wt init fish | source

Reload your shell configuration, then use git wt switch.

This also defines a git shell function. If another tool already defines one, use --no-git-wrapper and call git-wt switch instead.

Git options before wt, such as git -C <path> wt switch, bypass the function and only print the path.

Remove worktrees

Preview removal, then remove the worktree and its local branch:

git wt remove --dry-run feature
git wt remove feature

To also delete its configured remote branch:

git wt remove feature --delete-remote

To clean up merged branches and missing worktrees:

git wt remove --sweep --dry-run
git wt remove --sweep

Keep these rules in mind:

  • Save valuable ignored files first. Removal deletes them, including ignored .env files.
  • git-wt checks for changed files and commits that no other branch or tag keeps.
  • On a terminal, discarding that work requires typing the worktree name. Without a terminal, git-wt skips it and exits 1.
  • --force discards that work without asking. With --delete-remote, it can also delete commits pushed by others that you have not fetched.
  • Cleanup filters do not accept --force. A deleted remote branch alone does not make a worktree safe to remove.

See removal safety for cleanup settings and remote deletion rules.

Check and update worktrees

# List worktrees
git wt list

# List as JSON
git wt list --json

# Show changes across worktrees
git wt status

# Check for repository problems
git wt doctor

# Fetch remotes and pull the default branch
git wt update

update uses your Git settings for pulling and pruning tags. Tag pruning can delete local-only tags if enabled.

See update settings and the JSON format for details.

Commands

Command Purpose
clone <url> Clone into the .bare/ layout
migrate Convert an existing repository
add Create a worktree
switch Pick a worktree to switch to
remove / rm Remove worktrees and branches
list / ls List worktrees, with optional JSON output
status Show changes across worktrees
doctor Check for repository problems
update / u Fetch remotes and update the default branch
init <shell> Set up automatic directory switching
agent-skill Install instructions for coding agents

lock, unlock, move, prune, and repair use the matching native git worktree commands.

Run git wt <command> --help for options.

Hooks

Run shell commands before or after creating and removing worktrees. Configure them per repository, or add --global for all repositories.

git config --add wt.afteradd 'cp ../main/compile_commands.json .'
Hook Runs in
wt.beforeadd Repository root, before creation
wt.afteradd New worktree, after creation
wt.beforeremove Worktree, before removal
wt.afterremove Repository root, after removal

Hooks receive the path in $GIT_WT_PATH and the branch name in $GIT_WT_BRANCH.

Before-hooks can stop the operation. After-hook failures report an error but do not undo completed work.

Hooks apply to add and remove, not clone or migrate. See the hook reference for environment variables and failure rules.

Coding agents

Install agent instructions for git-wt:

git wt agent-skill

This writes ~/.agents/skills/git-wt/SKILL.md. Use --dir ~/.claude/skills to choose another location, or --print to read it first.

Claude Code integration

Claude Code can use git-wt to create and remove worktrees.

Add these entries under hooks in your project or user settings.json. The commands require jq.

{
  "WorktreeCreate": [
    {
      "hooks": [
        {
          "type": "command",
          "command": "git wt add \"$(cat /dev/stdin | jq -r '.name')\""
        }
      ]
    }
  ],
  "WorktreeRemove": [
    {
      "hooks": [
        {
          "type": "command",
          "command": "echo y | git wt rm \"$(cat /dev/stdin | jq -r '.worktree_path')\""
        }
      ]
    }
  ]
}

WorktreeCreate reads the branch name from stdin and creates a worktree. WorktreeRemove reads the worktree path and confirms removal with echo y.

Removal refuses changed files and commits that no other branch or tag keeps. Do not automatically add --force when removal fails. It can discard the agent's work.

Development

nix develop          # Enter the development shell
nix fmt              # Format files
nix flake check      # Check the build and formatting
go test ./...        # Run Go tests
bats tests/          # Run end-to-end tests

See the development guide for CI and release details.

License

MIT