From 92766546ebebaae46a0eaac28cc81805661dc627 Mon Sep 17 00:00:00 2001 From: kuderr Date: Wed, 25 Feb 2026 16:09:31 +0300 Subject: [PATCH] feat: restructure README, add GIT_WT_BASE and GIT_WT_COPY_ENV env vars MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - README: move Shell Aliases to bottom, consolidate AI blocks into one section - README: keep Quick Start clean — only basic usage + .env + external worktrees - Add GIT_WT_BASE env var to always fork from a specific branch (e.g. main) - Add GIT_WT_COPY_ENV env var to always copy .env files on new Co-Authored-By: Claude Opus 4.6 --- README.md | 152 ++++++++++++++++++++++++++++------------------------- bin/git-wt | 6 ++- 2 files changed, 83 insertions(+), 75 deletions(-) diff --git a/README.md b/README.md index 03809b8..638d5cf 100644 --- a/README.md +++ b/README.md @@ -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 ` | `cd $(git wt path )` | 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 ` | `git wt rm` | Remove a worktree | -| `wtopen ` | `git wt open` | Open worktree in editor | -| `wtclean` | `git wt clean` | Remove all worktrees | -| `wtpath ` | `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. @@ -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//.ai-sessions//`, syncs settings back to origin -- **Extensible**: add new providers via `GIT_WT_AI_PROVIDERS` (define `_ai_copy_` + `_ai_save_` 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`). @@ -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 ``` @@ -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//.ai-sessions//`, syncs settings back to origin +- **Extensible**: add new providers via `GIT_WT_AI_PROVIDERS` (define `_ai_copy_` + `_ai_save_` 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. @@ -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 ` | `cd $(git wt path )` | 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 ` | `git wt rm` | Remove a worktree | +| `wtopen ` | `git wt open` | Open worktree in editor | +| `wtclean` | `git wt clean` | Remove all worktrees | +| `wtpath ` | `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. diff --git a/bin/git-wt b/bin/git-wt index 4aa1281..409ed29 100755 --- a/bin/git-wt +++ b/bin/git-wt @@ -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 @@ -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")