gwt - Git Worktree CLI

Manage git worktrees so you can work on multiple branches simultaneously without stashing or switching. Each branch gets its own directory.

Directory Structure

~/projects/
  my-repo/                      # Main repository (run gwt init here)
  my-repo-worktrees/            # Created automatically by gwt
    feature/auth/               # Worktree for feature/auth branch
    bugfix/fix-123/             # Worktree for bugfix/fix-123 branch

Worktrees are sibling directories to the main repo, with -worktrees suffix.

Quick Reference

bash
1gwt init                          # One-time setup (run inside the repo)
2gwt init --local                  # Store config next to repo instead of globally
3gwt add <branch>                  # Create worktree for a branch
4gwt list                          # List worktrees with PR status
5gwt list --local                  # List worktrees without remote PR info
6gwt remove <branch>              # Remove worktree (interactive confirmation)
7gwt remove <branch> --force      # Remove worktree (no confirmation, use for automation)
8gwt remove                        # Remove current worktree
9gwt auth github                   # Check GitHub auth status
10gwt auth bitbucket-cloud setup    # Set up Bitbucket Cloud auth
11gwt auth bitbucket-cloud test     # Test Bitbucket Cloud connection
12gwt completions install           # Install shell tab completions

Best Practices for AI Agents

1. Always use --force with gwt remove - The default remove flow is interactive and requires stdin confirmation
2. Run gwt commands from the main repo or any worktree - gwt auto-discovers the project from the current directory
3. Use gwt list --local for fast status - Skips remote PR API calls when you only need local worktrees
4. After gwt add, cd into the worktree - The new worktree is at <repo>-worktrees/<branch-name>/
5. Branch names with slashes are supported - Use names like feature/my-feature or bugfix/issue-42
6. gwt init is one-time per repo - Run once inside the main repository; auto-detects provider and default branch
7. Protected branches - main, master, dev, develop cannot be deleted by gwt remove

Commands

gwt init

Initialize gwt for an existing git repository. Must be run from inside a repo with a remote origin.

• Detects provider (GitHub, Bitbucket Cloud, Bitbucket Data Center) from remote URL
• Detects the default branch from the remote
• Derives worktrees path as <repo-name>-worktrees/ sibling directory
• Saves config globally by default

Options:

• --local - Save config as git-worktree-config.jsonc in the parent directory instead of ~/.config/git-worktree-cli/projects/

bash
1cd ~/projects/my-app
2gwt init
3# Config saved to ~/.config/git-worktree-cli/projects/github_owner_my-app.jsonc
4
5gwt init --local
6# Config saved to ./git-worktree-config.jsonc

gwt add <branch>

Create a new worktree for a branch.

• Fetches from origin first to get latest remote state
• If branch exists locally: checks out the existing local branch
• If branch exists on remote only: checks out the remote branch
• If branch is new: creates it from origin/<main-branch>
• Runs postAdd hooks after creating the worktree

Arguments:

• <branch> (required) - Branch name, supports slashes like feature/name

bash
1gwt add feature/user-auth
2# Creates ~/projects/my-app-worktrees/feature/user-auth/
3
4cd ../my-app-worktrees/feature/user-auth

gwt list

List all worktrees with optional PR status.

• Shows all local worktrees with branch names
• With auth configured: shows PR URL, status (open/draft/merged/closed), and title
• Shows open PRs that have no local worktree
• Works from main repo or any worktree directory

Options:

• --local / -l - Skip remote PR info (faster, works offline)

Example output:

Local Worktrees:

main

feature/user-auth
  https://github.com/owner/repo/pull/42 (open)
  Add user authentication

Open Pull Requests (no local worktree):

bugfix/fix-login
  https://github.com/owner/repo/pull/43 (open)
  Fix login redirect bug

gwt remove [branch] [--force]

Remove a worktree and delete its branch.

• Without branch name: removes the worktree for the current directory
• Removes the worktree directory and the git branch
• Protected branches (main, master, dev, develop) are preserved
• Handles orphaned worktrees (stale git references)
• Runs preRemove hooks before removal and postRemove hooks after

Arguments:

• [branch] (optional) - Branch name, defaults to current worktree

Options:

• --force / -f - Skip all confirmation prompts. Required for non-interactive use.

bash
1gwt remove feature/user-auth --force

gwt auth <provider>

Set up authentication for PR status in gwt list.

Providers:

• github - Uses the gh CLI. Run gh auth login to authenticate
• bitbucket-cloud - Uses app passwords. Run gwt auth bitbucket-cloud setup for instructions
• bitbucket-data-center - Uses personal access tokens. Run gwt auth bitbucket-data-center setup for instructions

Subcommands:

• setup - Show setup instructions
• test - Test the authentication connection

bash
1gwt auth github                       # Check GitHub auth status
2gwt auth bitbucket-cloud setup        # Show Bitbucket Cloud setup instructions
3gwt auth bitbucket-data-center test   # Test Bitbucket DC connection

gwt completions

Manage shell tab completions.

• Without subcommand: checks if completions are installed
• install [shell] - Install completions (auto-detects shell if not specified)
• generate <shell> - Output completion script to stdout
• Supported shells: bash, zsh, fish, powershell, elvish

bash
1gwt completions                # Check installation status
2gwt completions install        # Auto-install for detected shell
3gwt completions generate zsh   # Output zsh completions to stdout

Configuration

Config file: git-worktree-config.jsonc (JSONC format, supports comments)

Global location: ~/.config/git-worktree-cli/projects/<provider_owner_repo>.jsonc Local location: ./git-worktree-config.jsonc (created with gwt init --local)

Local config takes priority over global config.

jsonc
1{
2  "repositoryUrl": "git@github.com:owner/repo.git",
3  "mainBranch": "main",
4  "createdAt": "2025-01-01T00:00:00Z",
5  "sourceControl": "github",
6  "projectPath": "/home/user/projects/repo",
7  "worktreesPath": "/home/user/projects/repo-worktrees",
8  "hooks": {
9    "postAdd": ["npm install", "npm run init"],
10    "preRemove": ["echo Cleaning up ${branchName}"],
11    "postRemove": ["echo Removed ${worktreePath}"]
12  }
13}

Fields:

• repositoryUrl - Remote origin URL
• mainBranch - Default branch name (used as base for new branches)
• sourceControl - Provider: github, bitbucket-cloud, or bitbucket-data-center
• projectPath - Absolute path to the main repository
• worktreesPath - Absolute path to the worktrees directory
• hooks - Commands to run on worktree operations (optional)

Hooks

Hooks run shell commands at specific points in worktree operations.

Available variables:

• ${branchName} - The branch name
• ${worktreePath} - Absolute path to the worktree directory

Hooks continue executing even if one fails.

Typical Workflow

bash
1# 1. One-time setup
2cd ~/projects/my-app
3gwt init
4
5# 2. Start working on a feature
6gwt add feature/new-dashboard
7cd ../my-app-worktrees/feature/new-dashboard
8
9# 3. Handle an urgent bug (no need to stash)
10gwt add hotfix/fix-crash
11cd ../../my-app-worktrees/hotfix/fix-crash
12# fix the bug, commit, push
13
14# 4. Check all work
15gwt list
16
17# 5. Clean up finished branches
18gwt remove hotfix/fix-crash --force

Prerequisites

• Git 2.5+ (for worktree support)
• gh CLI (for GitHub PR integration, optional)