@gw-tools/gw 0.20.12 → 0.20.14

package/README.md

@@ -22,7 +22,7 @@ A command-line tool for managing git worktrees, built with Deno.
     - [Example Configuration](#example-configuration)
     - [Configuration Options](#configuration-options)
   - [Commands](#commands)
-    - [add](#add)
+    - [checkout (add, co)](#checkout)
       - [Arguments](#arguments)
       - [Options](#options)
       - [Examples](#examples)
@@ -32,10 +32,6 @@ A command-line tool for managing git worktrees, built with Deno.
       - [Arguments](#arguments-1)
       - [Examples](#examples-1)
       - [How It Works](#how-it-works)
-    - [checkout](#checkout)
-      - [Arguments](#arguments-2)
-      - [Examples](#examples-2)
-      - [How It Works](#how-it-works-1)
     - [pr](#pr)
       - [Arguments](#arguments-3)
       - [Options](#options-1)
@@ -124,7 +120,7 @@ gw cd feat/new-feature
 
 ```bash
 # Configure gw in an existing repository
-gw init --auto-copy-files .env,secrets/ --post-add "pnpm install"
+gw init --auto-copy-files .env,secrets/ --post-checkout "pnpm install"
 
 # Create worktrees - files are copied automatically, dependencies installed
 gw add feat/another-feature
@@ -165,7 +161,7 @@ Once installed, your AI agent can:
 
 ## Initial Setup: Secrets in the Default Branch
 
-**Important:** Before using `gw add` with auto-copy, ensure your secrets and environment files exist in your `defaultBranch` worktree (typically `main`). This worktree is the **source** from which files are copied to new worktrees.
+**Important:** Before using `gw checkout` with auto-copy, ensure your secrets and environment files exist in your `defaultBranch` worktree (typically `main`). This worktree is the **source** from which files are copied to new worktrees.
 
 ### First-Time Setup Flow
 
@@ -203,7 +199,7 @@ gw add feat/new-feature
 # Clone with configuration in one command
 gw init git@github.com:user/repo.git \
   --auto-copy-files .env,secrets/ \
-  --post-add "pnpm install"
+  --post-checkout "pnpm install"
 
 # Then set up secrets in main worktree as shown above
 cd repo.git/main
@@ -213,7 +209,7 @@ cp .env.example .env
 
 ### Why This Matters
 
-- **`gw add`** copies files **from** your `defaultBranch` worktree **to** the new worktree
+- **`gw checkout`** copies files **from** your `defaultBranch` worktree **to** the new worktree
 - **`gw sync`** also uses `defaultBranch` as the source (unless `--from` is specified)
 - **Auto-clean** will **never** remove the `defaultBranch` worktree, ensuring your source files are always available
 - If secrets don't exist in `defaultBranch`, they won't be copied to new worktrees
@@ -313,7 +309,7 @@ gw init --root /path/to/your/repo.git
   // Auto-copy these files when creating new worktrees
   "autoCopyFiles": [".env", "components/agents/.env", "components/ui/.vercel/"],
   "hooks": {
-    "add": {
+    "checkout": {
       "pre": ["echo 'Creating worktree: {worktree}'"],
       "post": ["pnpm install", "echo 'Setup complete!'"],
     },
@@ -333,57 +329,67 @@ gw init --root /path/to/your/repo.git
 
 - **root**: Absolute path to the git repository root (automatically detected or manually set with `gw init`)
 - **defaultBranch**: Default source worktree name (optional, defaults to "main")
-- **autoCopyFiles**: Array of file/directory paths to automatically copy when creating worktrees with `gw add` (optional, only set via `gw init --auto-copy-files`)
-- **hooks**: Command hooks configuration (optional, set via `gw init --pre-add` and `--post-add`)
-  - **hooks.add.pre**: Array of commands to run before creating a worktree
-  - **hooks.add.post**: Array of commands to run after creating a worktree
+- **autoCopyFiles**: Array of file/directory paths to automatically copy when creating worktrees with `gw checkout` (optional, only set via `gw init --auto-copy-files`)
+- **hooks**: Command hooks configuration (optional, set via `gw init --pre-checkout` and `--post-checkout`)
+  - **hooks.checkout.pre**: Array of commands to run before creating a worktree
+  - **hooks.checkout.post**: Array of commands to run after creating a worktree
 - **cleanThreshold**: Number of days before worktrees are considered stale for `gw clean` (optional, defaults to 7, set via `gw init --clean-threshold`)
-- **autoClean**: Prompt to remove stale worktrees when running `gw add` or `gw list` (optional, defaults to false, set via `gw init --auto-clean`)
+- **autoClean**: Prompt to remove stale worktrees when running `gw checkout` or `gw list` (optional, defaults to false, set via `gw init --auto-clean`)
 - **updateStrategy**: Default strategy for `gw update` command: "merge" or "rebase" (optional, defaults to "merge", set via `gw init --update-strategy`)
 - **lastAutoCleanTime**: Internal timestamp tracking last auto-cleanup run (managed automatically, do not edit manually)
 
 ## Commands
 
-### add
+### checkout
+
+Create a new git worktree, switch to an existing branch, or navigate to a worktree where a branch is checked out. This is the primary command for working with branches in a worktree workflow.
 
-Create a new git worktree with optional automatic file copying.
+**Aliases:** `co`, `add` (for backwards compatibility)
 
 ```bash
-gw add <worktree-name> [files...]
+gw checkout <branch-name> [files...]
+# or use aliases
+gw co <branch-name>
+gw add <branch-name>  # backwards-compatible alias
 ```
 
-This command wraps `git worktree add` and optionally copies files to the new worktree. If `autoCopyFiles` is configured, those files are automatically copied. You can override this by specifying files as arguments.
+This unified command handles all branch operations in a worktree workflow:
+
+1. **Branch exists locally, not checked out:** Creates a worktree for it
+2. **Branch is checked out in another worktree:** Navigates to that worktree
+3. **Branch exists on remote only:** Prompts to create a worktree for it
+4. **Branch doesn't exist:** Creates a new branch from the default branch and a worktree for it
+5. **Already on the branch:** Shows "Already on branch" message
+
+If `autoCopyFiles` is configured, those files are automatically copied when creating new worktrees. You can override this by specifying files as arguments.
 
 **Branch Creation Behavior:**
-When creating a new worktree without specifying an existing branch, `gw add` automatically fetches the latest version of your default branch (e.g., `main`) from the remote (e.g., `origin/main`) to ensure your new branch is based on the most recent code. You can override this with the `--from <branch>` option to create a branch from a different source branch instead.
+When creating a new worktree without specifying an existing branch, `gw checkout` automatically fetches the latest version of your default branch (e.g., `main`) from the remote (e.g., `origin/main`) to ensure your new branch is based on the most recent code. You can override this with the `--from <branch>` option to create a branch from a different source branch instead.
 
-**Remote-First Fetch Approach:**
+**Branch Handling:**
+`gw checkout` intelligently handles different branch scenarios:
 
-The `gw add` command follows a remote-first approach when creating new branches:
+1. **Local branches**: If the branch already exists locally, it's used directly. No network access required.
 
-1. **What happens**: When you create a new branch (e.g., `gw add feat/new-feature`), the command:
-   - Fetches the latest version of the source branch from the remote (e.g., `origin/main`)
-   - Creates your new branch from the fresh remote ref (e.g., `origin/main`)
-   - Sets up tracking to `origin/feat/new-feature` for easy pushing
+2. **Remote-only branches**: If the branch exists only on remote (e.g., `origin/feat/something`), `gw checkout` fetches it and creates a proper local tracking branch. This ensures `git push` and `git pull` work correctly.
 
-2. **Why it matters**: This ensures your new branch starts from the latest remote code, not from a potentially outdated local branch. This prevents:
-   - Merge conflicts from missing recent changes
-   - Building features on old code
-   - Divergent histories that are hard to reconcile
+3. **New branches**: If the branch doesn't exist anywhere, it's created from the source branch (defaultBranch or `--from` branch) after fetching the latest from remote.
 
-3. **Network failure handling**:
-   - **With `--from <branch>`**: Requires successful remote fetch. If the fetch fails (network issues, branch doesn't exist on remote, authentication problems), the command exits with a detailed error message and troubleshooting steps. This ensures you're working with fresh code when you explicitly specify a source.
-   - **Without `--from` (default branch)**: Warns about fetch failures but allows creation using the local branch as a fallback. This supports offline development or when no remote is configured.
+**Network Behavior:**
 
-4. **Offline development**: When working offline or when remote fetch fails for the default branch, the command falls back to using the local branch with a clear warning. This allows you to continue working without network access while being aware that your start point may not be current.
+- **New branches without `--from`**: Fetches defaultBranch from remote, falls back to local if fetch fails (offline support)
+- **New branches with `--from`**: Requires successful remote fetch, exits on failure (ensures fresh code)
+- **Local branches**: Used directly without network access
+- **Remote-only branches**: Fetches and creates local tracking branch, uses cached remote ref if fetch fails
 
 **Network Failure Handling:**
 
 - When using `--from` with an explicit branch, the command requires a successful fetch from the remote to ensure you're working with the latest code. If the fetch fails (network issues, branch doesn't exist on remote, authentication problems), the command will exit with a detailed error message and suggestions for resolution.
-- When no `--from` is specified (using default branch) or when no remote is configured, the command will warn about fetch failures but allow creation using the local branch.
+- For local branches, no network is required.
+- For remote-only branches or new branches without `--from`, fetch failures trigger a warning but allow creation using local/cached refs.
 
 **Upstream Tracking:**
-When `gw add` creates a new branch, it automatically configures the branch to track `origin/<branch-name>` (e.g., `origin/feat/my-feature`). This means `git push` will push to the correct remote branch without needing to specify `-u origin <branch>` on first push.
+When `gw checkout` creates a new branch, it automatically configures the branch to track `origin/<branch-name>` (e.g., `origin/feat/my-feature`). This means `git push` will push to the correct remote branch without needing to specify `-u origin <branch>` on first push.
 
 **Git Ref Conflict Detection:**
 The command automatically detects and prevents Git ref naming conflicts. For example, you cannot have both a branch named `test` and `test/foo` because Git stores branches as files in `.git/refs/heads/`, and `test` cannot be both a file and a directory. If a conflict is detected, you'll receive a helpful error message with suggestions for resolving it.
@@ -396,7 +402,7 @@ If you try to add a worktree that already exists, the command will prompt you to
 
 #### Arguments
 
-- `<worktree-name>`: Name or path for the new worktree
+- `<branch-name>`: Branch name to checkout or create
 - `[files...]`: Optional files to copy (overrides `autoCopyFiles` config)
 
 #### Options
@@ -416,35 +422,46 @@ All `git worktree add` options are supported:
 #### Examples
 
 ```bash
-# Create worktree (auto-copies files if autoCopyFiles is configured)
+# Create worktree for new branch (auto-copies files if autoCopyFiles is configured)
 # Automatically navigates to new worktree
-gw add feat/new-feature
+gw checkout feat/new-feature
+gw co feat/new-feature  # Using alias
+
+# Navigate to worktree where main is already checked out
+gw checkout main
+# Output: Branch main is checked out in another worktree:
+#   /path/to/repo/main
+#
+# Navigating there...
 
 # Create worktree without navigating to it
-gw add feat/new-feature --no-cd
+gw checkout feat/new-feature --no-cd
 
 # Create worktree from a different branch instead of defaultBranch
-gw add feat/new-feature --from develop
+gw checkout feat/new-feature --from develop
 
 # Create child feature branch from parent feature branch
-gw add feat/child-feature --from feat/parent-feature
+gw checkout feat/child-feature --from feat/parent-feature
 
 # Create worktree with new branch
-gw add feat/new-feature -b my-branch
+gw checkout feat/new-feature -b my-branch
 
 # Create worktree and copy specific files (overrides config)
-gw add feat/new-feature .env secrets/
+gw checkout feat/new-feature .env secrets/
 
 # Force create even if branch exists elsewhere
-gw add feat/bugfix -f
+gw checkout feat/bugfix -f
 
-# If worktree already exists, prompts to navigate to it
-gw add feat/existing-branch
-# Output: Worktree feat/existing-branch already exists at:
-#   /path/to/repo/feat/existing-branch
+# Create worktree for remote branch (prompts)
+gw checkout remote-feature
+# Output: Branch remote-feature exists on remote but not locally.
 #
-# Navigate to it? [Y/n]:
-# (Press Enter to navigate, or 'n' to cancel)
+# Create a new worktree for it? [Y/n]:
+# (If yes, creates the worktree)
+
+# Already on the branch
+gw checkout current-branch
+# Output: Already on 'current-branch'
 ```
 
 #### Auto-Copy Configuration
@@ -465,21 +482,21 @@ This creates:
 }
 ```
 
-Now every time you run `gw add`, these files will be automatically copied from your default source worktree (usually `main`) to the new worktree.
+Now every time you run `gw checkout`, these files will be automatically copied from your default source worktree (usually `main`) to the new worktree.
 
 #### Hooks
 
-You can configure pre-add and post-add hooks to run commands before and after worktree creation. This is useful for:
+You can configure pre-checkout and post-checkout hooks to run commands before and after worktree creation. This is useful for:
 
-- **Pre-add hooks**: Running validation scripts, checking prerequisites
-- **Post-add hooks**: Installing dependencies, setting up the environment
+- **Pre-checkout hooks**: Running validation scripts, checking prerequisites
+- **Post-checkout hooks**: Installing dependencies, setting up the environment
 
 ```bash
-# Configure a post-add hook to install dependencies
-gw init --post-add "pnpm install"
+# Configure a post-checkout hook to install dependencies
+gw init --post-checkout "pnpm install"
 
 # Configure multiple hooks
-gw init --pre-add "echo 'Creating: {worktree}'" --post-add "pnpm install" --post-add "echo 'Done!'"
+gw init --pre-checkout "echo 'Creating: {worktree}'" --post-checkout "pnpm install" --post-checkout "echo 'Done!'"
 ```
 
 **Hook Variables:**
@@ -493,17 +510,17 @@ Hooks support variable substitution:
 
 **Hook Behavior:**
 
-- **Pre-add hooks** run before the worktree is created (in the git root directory). If any pre-add hook fails, the worktree creation is aborted.
-- **Post-add hooks** run after the worktree is created and files are copied (in the new worktree directory). If a post-add hook fails, a warning is shown but the worktree creation is considered successful.
+- **Pre-checkout hooks** run before the worktree is created (in the git root directory). If any pre-checkout hook fails, the worktree creation is aborted.
+- **Post-checkout hooks** run after the worktree is created and files are copied (in the new worktree directory). If a post-checkout hook fails, a warning is shown but the worktree creation is considered successful.
 
 **Example: Auto-install dependencies**
 
 ```bash
 # One-time setup
-gw init --auto-copy-files .env --post-add "pnpm install"
+gw init --auto-copy-files .env --post-checkout "pnpm install"
 
 # Now when you create a worktree:
-gw add feat/new-feature
+gw checkout feat/new-feature
 # 1. Creates the worktree
 # 2. Copies .env file
 # 3. Runs pnpm install in the new worktree
@@ -547,79 +564,6 @@ The `cd` command integrates with your shell through an automatically installed f
 
 **Note**: Shell integration is automatically installed when you install via npm. If needed, you can manually install or remove it using `gw install-shell`.
 
-### checkout
-
-Smart git checkout wrapper that provides an intuitive experience for working with worktrees. The command automatically handles scenarios that would normally cause errors with standard `git checkout`.
-
-```bash
-gw checkout <branch>
-# or use the alias
-gw co <branch>
-```
-
-When you're working with worktrees, you cannot checkout the same branch in multiple worktrees. The `gw checkout` command solves this by detecting when a branch is already checked out elsewhere and navigating you to that worktree instead of showing an error.
-
-#### Arguments
-
-- `<branch>`: Branch name to checkout
-
-#### Examples
-
-```bash
-# Checkout a local branch (if not checked out elsewhere)
-gw checkout feature-x
-gw co feature-x  # Using alias
-
-# Navigate to worktree where main is already checked out
-gw checkout main
-# Output: Branch main is checked out in another worktree:
-#   /path/to/repo/main
-#
-# Navigating there...
-
-# Create worktree for remote branch (prompts)
-gw checkout remote-feature
-# Output: Branch remote-feature exists on remote but not locally.
-#
-# Create a new worktree for it? [Y/n]:
-# (If yes, runs: gw add remote-feature)
-
-# Already on the branch
-gw checkout current-branch
-# Output: Already on 'current-branch'
-```
-
-#### How It Works
-
-The `checkout` command intelligently handles four scenarios:
-
-1. **Branch exists locally and isn't checked out anywhere:**
-   - Performs standard `git checkout <branch>` in the current worktree
-
-2. **Branch is already checked out in another worktree:**
-   - Automatically navigates to that worktree (like `gw cd`)
-   - Shows you where the branch is located
-
-3. **Branch exists on remote but not locally:**
-   - Prompts you to create a new worktree for it
-   - If you confirm, runs `gw add <branch>` which:
-     - Creates the worktree
-     - Copies auto-copy files
-     - Navigates to the new worktree
-
-4. **Branch doesn't exist anywhere:**
-   - Shows a helpful error message
-   - Suggests using `gw add <branch>` to create a new branch
-
-**Why use this instead of `git checkout`?**
-
-- **No more confusing errors:** Instead of "fatal: 'main' is already checked out at '/path/to/main'", it just takes you there
-- **Reduces mental overhead:** You don't need to remember which branches are where
-- **Teaches worktree workflows:** The messages guide you toward the right action
-- **Educational:** Prompts explain what's happening and suggest alternatives
-
-**Use case:** When updating your feature branch with latest changes, you might instinctively try `git checkout main && git pull`. With worktrees, this fails because main is checked out elsewhere. Instead, use `gw update` to update your current branch with main, or use `gw checkout main` to navigate to the main worktree.
-
 ### pr
 
 Check out a pull request into a new worktree. This command fetches a PR's branch and creates a worktree for it in one step, making it easy to review, test, or contribute to pull requests.
@@ -676,8 +620,8 @@ gw pr 42 --no-cd
 3. **Checks for existing worktree**: If the branch is already checked out, offers to navigate there
 4. **Fetches PR branch**: Uses `git fetch origin pull/<number>/head:<branch>` pattern which works for both same-repo and fork PRs
 5. **Creates worktree**: Creates a new worktree with the PR's branch
-6. **Copies files**: Auto-copies files from `autoCopyFiles` config (same as `gw add`)
-7. **Runs hooks**: Executes pre-add and post-add hooks (same as `gw add`)
+6. **Copies files**: Auto-copies files from `autoCopyFiles` config (same as `gw checkout`)
+7. **Runs hooks**: Executes pre-checkout and post-checkout hooks (same as `gw checkout`)
 8. **Navigates**: Automatically navigates to the new worktree
 
 **Fork Handling:**
@@ -786,7 +730,7 @@ Shell integration provides:
 
 - **Navigation support**: `gw cd <worktree>` navigates directly to worktrees
 - **Real-time streaming**: Command output streams as it's generated (no buffering)
-- **Auto-navigation**: Automatically navigate after `gw add` and `gw remove` operations
+- **Auto-navigation**: Automatically navigate after `gw checkout` and `gw remove` operations
 - **Multi-alias support**: Install for different command names (e.g., `gw-dev` for development)
 
 ```bash
@@ -884,11 +828,11 @@ gw init [repository-url] [directory] [options]
 - `-i, --interactive`: Interactively prompt for configuration options
 - `--root <path>`: Specify the git repository root path (optional, auto-detects if not provided)
 - `--default-source <name>`: Set the default source worktree (default: "main")
-- `--auto-copy-files <files>`: Comma-separated list of files to auto-copy when creating worktrees with `gw add`
-- `--pre-add <command>`: Command to run before `gw add` creates a worktree (can be specified multiple times)
-- `--post-add <command>`: Command to run after `gw add` creates a worktree (can be specified multiple times)
+- `--auto-copy-files <files>`: Comma-separated list of files to auto-copy when creating worktrees with `gw checkout`
+- `--pre-checkout <command>`: Command to run before `gw checkout` creates a worktree (can be specified multiple times)
+- `--post-checkout <command>`: Command to run after `gw checkout` creates a worktree (can be specified multiple times)
 - `--clean-threshold <days>`: Number of days before worktrees are considered stale for `gw clean` (default: 7)
-- `--auto-clean`: Enable automatic cleanup of stale worktrees (runs on `gw add` and `gw list` with 24-hour cooldown)
+- `--auto-clean`: Enable automatic cleanup of stale worktrees (runs on `gw checkout` and `gw list` with 24-hour cooldown)
 - `--update-strategy <strategy>`: Set default update strategy: 'merge' or 'rebase' (default: merge)
 - `-h, --help`: Show help message
 
@@ -901,7 +845,7 @@ Clone a repository and automatically set it up with gw configuration. **This is
 gw init git@github.com:user/repo.git --interactive
 # Prompts for:
 # - Auto-copy files (.env, secrets/, etc.)
-# - Pre-add and post-add hooks (pnpm install, etc.)
+# - Pre-checkout and post-checkout hooks (pnpm install, etc.)
 # - Clean threshold
 # - Update strategy
 # Then automatically creates the main worktree and navigates to the repo
@@ -909,7 +853,7 @@ gw init git@github.com:user/repo.git --interactive
 # Clone with configuration in one command (non-interactive)
 gw init git@github.com:user/repo.git \
   --auto-copy-files .env,secrets/ \
-  --post-add "pnpm install"
+  --post-checkout "pnpm install"
 
 # Clone into specific directory
 gw init git@github.com:user/repo.git my-project --interactive
@@ -934,7 +878,7 @@ gw init git@github.com:user/repo.git
 
 - No need to manually run `git clone --bare` or `git worktree add`
 - Configuration is set up immediately
-- Ready to use `gw add` right away
+- Ready to use `gw checkout` right away
 
 **Notes:**
 
@@ -958,13 +902,13 @@ gw init
 gw init --auto-copy-files .env,secrets/
 
 # Initialize with post-add hook to install dependencies
-gw init --post-add "pnpm install"
+gw init --post-checkout "pnpm install"
 
 # Initialize with pre-add validation hook
-gw init --pre-add "echo 'Creating worktree: {worktree}'"
+gw init --pre-checkout "echo 'Creating worktree: {worktree}'"
 
 # Initialize with multiple hooks
-gw init --pre-add "echo 'Starting...'" --post-add "pnpm install" --post-add "echo 'Done!'"
+gw init --pre-checkout "echo 'Starting...'" --post-checkout "pnpm install" --post-checkout "echo 'Done!'"
 
 # Initialize with custom default source
 gw init --default-source master
@@ -979,7 +923,7 @@ gw init --clean-threshold 14
 gw init --update-strategy rebase
 
 # Full configuration example
-gw init --auto-copy-files .env,secrets/ --post-add "pnpm install" --clean-threshold 14 --update-strategy merge
+gw init --auto-copy-files .env,secrets/ --post-checkout "pnpm install" --clean-threshold 14 --update-strategy merge
 
 # Show help
 gw init --help
@@ -1006,12 +950,12 @@ gw init --auto-clean
 gw init --auto-clean --clean-threshold 14
 
 # Enable with other options
-gw init --auto-clean --auto-copy-files .env --post-add "pnpm install"
+gw init --auto-clean --auto-copy-files .env --post-checkout "pnpm install"
 ```
 
 **How it works:**
 
-- Prompts after `gw add` and `gw list` commands when stale worktrees are detected
+- Prompts after `gw checkout` and `gw list` commands when stale worktrees are detected
 - Only prompts once per 24 hours (cooldown)
 - **Never removes the `defaultBranch` worktree** - it's protected as the source for file syncing
 - Checks for worktrees older than `cleanThreshold` with:
@@ -1081,7 +1025,7 @@ If your `.gw/config.json` contains:
   "defaultBranch": "main",
   "autoCopyFiles": [".env", "secrets/"],
   "hooks": {
-    "add": {
+    "checkout": {
       "post": ["pnpm install"]
     }
   },
@@ -1093,7 +1037,7 @@ If your `.gw/config.json` contains:
 Then `gw show-init` will output:
 
 ```bash
-gw init --root /Users/username/Workspace/repo.git --auto-copy-files .env,secrets/ --post-add 'pnpm install' --update-strategy rebase
+gw init --root /Users/username/Workspace/repo.git --auto-copy-files .env,secrets/ --post-checkout 'pnpm install' --update-strategy rebase
 ```
 
 #### When to Use
@@ -1262,7 +1206,7 @@ gw list -v               # Verbose output
 
 #### remove (rm)
 
-Remove a worktree from the repository.
+Remove a worktree from the repository. By default, also deletes the local branch to prevent orphaned branches.
 
 ```bash
 gw remove <worktree>
@@ -1270,7 +1214,16 @@ gw remove <worktree>
 gw rm <worktree>
 ```
 
-**Protected Branches:**
+**Branch Cleanup:**
+
+By default, `gw remove` deletes the local branch after removing the worktree:
+
+- Uses safe delete (`git branch -d`) which warns if branch has unmerged commits
+- Use `--preserve-branch` to keep the local branch
+- Use `--force` to force delete unmerged branches
+- Protected branches (main, master, defaultBranch, gw_root) are never deleted
+
+**Protected Worktrees:**
 
 The following worktrees are protected and cannot be removed:
 
@@ -1281,9 +1234,10 @@ The following worktrees are protected and cannot be removed:
 **Examples:**
 
 ```bash
-gw remove feat-branch           # Remove a worktree
-gw remove --force feat-branch   # Force remove even if dirty
-gw rm feat-branch               # Using alias
+gw remove feat-branch                    # Remove worktree AND delete local branch
+gw remove feat-branch --preserve-branch  # Remove worktree but KEEP local branch
+gw remove --force feat-branch            # Force remove worktree and force delete branch
+gw rm feat-branch                        # Using alias
 ```
 
 #### move (mv)
@@ -1444,7 +1398,7 @@ gw cd feat/new-feature
 ```bash
 # One-time setup: Configure auto-copy files and hooks
 gw init --auto-copy-files .env,components/agents/.env,components/ui/.vercel/ \
-  --post-add "pnpm install"
+  --post-checkout "pnpm install"
 
 # From within any worktree of your repository
 # Create a new worktree with auto-copy and hooks
@@ -1667,7 +1621,7 @@ packages/gw-tool/
 │   ├── main.ts              # CLI entry point and command dispatcher
 │   ├── index.ts             # Public API exports
 │   ├── commands/            # Command implementations
-│   │   ├── add.ts           # Add command (create worktree with auto-copy)
+│   │   ├── checkout.ts      # Checkout command (create worktree, switch branches, navigate)
 │   │   ├── copy.ts          # Sync command (sync files between worktrees)
 │   │   ├── init.ts          # Init command
 │   │   ├── root.ts          # Root command
@@ -1702,7 +1656,7 @@ packages/gw-tool/
 
 There are two types of commands you can add:
 
-#### Custom Commands (like `add`, `copy`)
+#### Custom Commands (like `checkout`, `sync`)
 
 For commands with custom logic, follow the pattern used by existing commands:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gw-tools/gw",
-  "version": "0.20.12",
+  "version": "0.20.14",
   "description": "A command-line tool for managing git worktrees - copy files between worktrees with ease",
   "keywords": [
     "git",