Skip to content

feat: restructure README, add GIT_WT_BASE and GIT_WT_COPY_ENV #8

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
kuderr merged 1 commit into from
Feb 25, 2026
Merged

feat: restructure README, add GIT_WT_BASE and GIT_WT_COPY_ENV #8

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
152 changes: 79 additions & 73 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -73,35 +73,6 @@ git wt open auth-refactor
git wt rm auth-refactor
```

### Shell Aliases

Install the optional aliases for shorter commands:

```bash
curl -fsSL https://raw.githubusercontent.com/kuderr/git-wt/main/aliases/install.sh | bash
```

Or source manually:

```bash
# Add to ~/.bashrc or ~/.zshrc
source /path/to/git-wt/aliases/git-wt.sh
```

| Alias | Equivalent | Description |
|-------|-----------|-------------|
| `wtcd <name>` | `cd $(git wt path <name>)` | cd into a worktree |
| `wto` | `cd $(git wt origin)` | cd into the origin (main) repo |
| `wtn [name]` | `git wt new` + `cd` | Create worktree and cd into it |
| `wtls` | `git wt list` | List worktrees |
| `wtla` | `git wt list-all` | List all worktrees |
| `wtrm <name>` | `git wt rm` | Remove a worktree |
| `wtopen <name>` | `git wt open` | Open worktree in editor |
| `wtclean` | `git wt clean` | Remove all worktrees |
| `wtpath <name>` | `git wt path` | Print worktree path |

Tab completion is included for bash and zsh — worktree names autocomplete for `wtcd`, `wtrm`, `wtopen`, and `wtpath`.

### Copying `.env` files

Worktrees are separate directories — your `.env` files (gitignored) won't be there.
Expand All @@ -115,35 +86,12 @@ git wt new --copy-env my-feature

This way your dev server starts immediately without missing config.

### AI session preservation

AI tools like Claude Code store sessions and settings per project path. When a worktree is deleted, that data is normally lost. Use `--copy-ai` to preserve it:

```bash
# On create: copies .claude/settings.local.json into worktree
git wt new --copy-ai my-feature

# Work in the worktree — AI tools create sessions, you approve new commands...

# On rm: archives Claude sessions, syncs settings back to origin
git wt rm my-feature
# Archived Claude sessions → .ai-sessions/my-feature/claude/
# Synced .claude/settings.local.json → origin
```

**What happens:**
- **On create**: copies `.claude/settings.local.json` (approved commands) into the worktree
- **On remove**: archives Claude Code sessions to `~/.git-wt/<repo>/.ai-sessions/<name>/`, syncs settings back to origin
- **Extensible**: add new providers via `GIT_WT_AI_PROVIDERS` (define `_ai_copy_<name>` + `_ai_save_<name>` functions in the script)

To enable this permanently:

```bash
export GIT_WT_COPY_AI=true # add to ~/.zshrc or ~/.bashrc
export GIT_WT_COPY_ENV=true # add to ~/.zshrc or ~/.bashrc
```

The provider system is extensible — see `GIT_WT_AI_PROVIDERS` to control which AI tools are managed.

### External worktrees

git-wt can see and manage worktrees created outside of `git wt` (e.g., via `git worktree add`).
Expand Down Expand Up @@ -204,29 +152,11 @@ Global flags:
|----------|---------|-------------|
| `GIT_WT_HOME` | `~/.git-wt` | Root directory for all worktrees |
| `GIT_WT_PREFIX` | `wt` | Branch name prefix |
| `GIT_WT_BASE` | _(current branch)_ | Default base branch for new worktrees |
| `GIT_WT_COPY_ENV` | `false` | Always copy `.env*` files on new |
| `GIT_WT_COPY_AI` | `false` | Always copy AI configs on new, save sessions on rm |
| `GIT_WT_AI_PROVIDERS` | `claude` | Space-separated list of AI providers to manage |

## Shell Completions

The installer sets up completions automatically. For manual setup:

**Bash:**

```bash
# Add to ~/.bashrc
source /path/to/git-wt/completions/git-wt.bash
```

**Zsh:**

```bash
# Add to ~/.zshrc (before compinit)
fpath=(~/.local/share/zsh/site-functions $fpath)
```

Completions support subcommands, flags, worktree names, and branch names.

## How It Works

```
Expand Down Expand Up @@ -273,6 +203,33 @@ git wt origin # → /Users/you/projects/myapp

This works from the main repo too (prints its own path). Useful for scripts that need to reference the original repository.

### Session preservation

AI tools like Claude Code store sessions and settings per project path. When a worktree is deleted, that data is normally lost. Use `--copy-ai` to preserve it:

```bash
# On create: copies .claude/settings.local.json into worktree
git wt new --copy-ai my-feature

# Work in the worktree — AI tools create sessions, you approve new commands...

# On rm: archives Claude sessions, syncs settings back to origin
git wt rm my-feature
# Archived Claude sessions → .ai-sessions/my-feature/claude/
# Synced .claude/settings.local.json → origin
```

**What happens:**
- **On create**: copies `.claude/settings.local.json` (approved commands) into the worktree
- **On remove**: archives Claude Code sessions to `~/.git-wt/<repo>/.ai-sessions/<name>/`, syncs settings back to origin
- **Extensible**: add new providers via `GIT_WT_AI_PROVIDERS` (define `_ai_copy_<name>` + `_ai_save_<name>` functions in the script)

To enable this permanently:

```bash
export GIT_WT_COPY_AI=true # add to ~/.zshrc or ~/.bashrc
```

### Agent Skill

git-wt ships with a [SKILL.md](skills/git-wt/SKILL.md) that teaches AI agents (Claude Code, Cursor, Windsurf, etc.) how and when to use `git wt` commands.
Expand Down Expand Up @@ -311,6 +268,55 @@ cp skill/SKILL.md .cursor/skills/git-wt/SKILL.md
| Multi-agent workflows | ✅ | ❌ | ✅ | ✅ Claude-only | ❌ |
| Install time | ~5 seconds | ~30 seconds | ~10 seconds | ~15 seconds | Built-in |

## Shell Aliases

Install the optional aliases for shorter commands:

```bash
curl -fsSL https://raw.githubusercontent.com/kuderr/git-wt/main/aliases/install.sh | bash
```

Or source manually:

```bash
# Add to ~/.bashrc or ~/.zshrc
source /path/to/git-wt/aliases/git-wt.sh
```

| Alias | Equivalent | Description |
|-------|-----------|-------------|
| `wtcd <name>` | `cd $(git wt path <name>)` | cd into a worktree |
| `wto` | `cd $(git wt origin)` | cd into the origin (main) repo |
| `wtn [name]` | `git wt new` + `cd` | Create worktree and cd into it |
| `wtls` | `git wt list` | List worktrees |
| `wtla` | `git wt list-all` | List all worktrees |
| `wtrm <name>` | `git wt rm` | Remove a worktree |
| `wtopen <name>` | `git wt open` | Open worktree in editor |
| `wtclean` | `git wt clean` | Remove all worktrees |
| `wtpath <name>` | `git wt path` | Print worktree path |

Tab completion is included for bash and zsh — worktree names autocomplete for `wtcd`, `wtrm`, `wtopen`, and `wtpath`.

## Shell Completions

The installer sets up completions automatically. For manual setup:

**Bash:**

```bash
# Add to ~/.bashrc
source /path/to/git-wt/completions/git-wt.bash
```

**Zsh:**

```bash
# Add to ~/.zshrc (before compinit)
fpath=(~/.local/share/zsh/site-functions $fpath)
```

Completions support subcommands, flags, worktree names, and branch names.

## Known Issues

- **Warp Terminal**: Tab completions for `git wt` don't work. Warp uses its own completion engine and [doesn't delegate to shell completions](https://github.com/warpdotdev/Warp/discussions/434). Completions work correctly in Terminal.app, iTerm2, Ghostty, Kitty, and other terminals that use native zsh/bash completion.
Expand Down
6 changes: 4 additions & 2 deletions bin/git-wt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,9 +13,9 @@ GIT_WT_VERSION="1.3.0"
# --- Config ---
GIT_WT_HOME="${GIT_WT_HOME:-${HOME}/.git-wt}"
WT_PREFIX="${GIT_WT_PREFIX:-wt}"
WT_BASE=""
WT_BASE="${GIT_WT_BASE:-}"
WT_NO_BRANCH=false
WT_COPY_ENV=false
WT_COPY_ENV="${GIT_WT_COPY_ENV:-false}"
WT_COPY_AI="${GIT_WT_COPY_AI:-false}"
WT_QUIET=false

Expand Down Expand Up @@ -630,6 +630,8 @@ ${BOLD}Options for new:${RESET}
${BOLD}Environment:${RESET}
GIT_WT_HOME Worktrees root (default: ~/.git-wt)
GIT_WT_PREFIX Default branch prefix (default: wt)
GIT_WT_BASE Default base branch for new worktrees (default: current branch)
GIT_WT_COPY_ENV Always copy .env* files on new (default: false)
GIT_WT_COPY_AI Always copy AI configs on new, save on rm (default: false)
GIT_WT_AI_PROVIDERS Space-separated AI providers (default: "claude")

Expand Down