@gw-tools/gw 0.20.12-beta.1 → 0.20.12

package/README.md

@@ -354,27 +354,33 @@ gw add <worktree-name> [files...]
 
 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.
 
-**Branch Handling:**
-`gw add` intelligently handles different branch scenarios:
+**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.
 
-1. **Local branches**: If the branch already exists locally, it's used directly. No network access required.
+**Remote-First Fetch Approach:**
 
-2. **Remote-only branches**: If the branch exists only on remote (e.g., `origin/feat/something`), `gw add` fetches it and creates a proper local tracking branch. This ensures `git push` and `git pull` work correctly.
+The `gw add` command follows a remote-first approach when creating new branches:
 
-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.
+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
 
-**Network Behavior:**
+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
 
-- **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
+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.
+
+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.
 
 **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.
-- 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.
+- 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.
 
 **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.
@@ -1104,12 +1110,12 @@ Use `gw show-init` to:
 Sync files and directories between worktrees, preserving directory structure.
 
 ```bash
-gw sync [options] <target-worktree> [files...]
+gw sync [options] [target-worktree] [files...]
 ```
 
 #### Arguments
 
-- `<target-worktree>`: Name or full path of the target worktree
+- `[target-worktree]`: Name or full path of the target worktree. If omitted, defaults to the current worktree
 - `[files...]`: One or more files or directories to sync (paths relative to worktree root). If omitted, uses `autoCopyFiles` from `.gw/config.json`
 
 #### Options
@@ -1121,7 +1127,10 @@ gw sync [options] <target-worktree> [files...]
 #### Examples
 
 ```bash
-# Sync autoCopyFiles from config (if configured)
+# Sync autoCopyFiles to current worktree (if inside a worktree)
+gw sync
+
+# Sync autoCopyFiles from config to a specific target
 gw sync feat-branch
 
 # Sync .env file from main to feat-branch
@@ -1199,7 +1208,8 @@ The clean command:
 | `gw clean`                           | No (all worktrees) | Yes (unless --force) | Clean up all finished work          |
 | `gw clean --use-autoclean-threshold` | Yes (7+ days)      | Yes (unless --force) | Clean up old, stale worktrees       |
 | `gw clean --force`                   | No (all worktrees) | No                   | Force removal of all worktrees      |
-| `gw prune --clean`                   | No (all worktrees) | No                   | Git's native cleanup (no gw safety) |
+| `gw prune`                           | No (all worktrees) | Yes                  | Full cleanup (worktrees + branches) |
+| `gw prune --stale-only`              | N/A                | N/A                  | Git passthrough (metadata only)     |
 
 **Safety Features:**
 
@@ -1252,7 +1262,7 @@ gw list -v               # Verbose output
 
 #### remove (rm)
 
-Remove a worktree from the repository. By default, also deletes the local branch to prevent orphaned branches.
+Remove a worktree from the repository.
 
 ```bash
 gw remove <worktree>
@@ -1260,16 +1270,7 @@ gw remove <worktree>
 gw rm <worktree>
 ```
 
-**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:**
+**Protected Branches:**
 
 The following worktrees are protected and cannot be removed:
 
@@ -1280,10 +1281,9 @@ The following worktrees are protected and cannot be removed:
 **Examples:**
 
 ```bash
-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
+gw remove feat-branch           # Remove a worktree
+gw remove --force feat-branch   # Force remove even if dirty
+gw rm feat-branch               # Using alias
 ```
 
 #### move (mv)
@@ -1305,13 +1305,13 @@ gw mv feat-branch ../new-location
 
 #### prune
 
-Clean up worktree administrative data and optionally remove clean worktrees.
+Clean up worktrees and orphan branches. By default, performs full cleanup (removes clean worktrees AND deletes orphan branches).
 
-**Standard Mode** (without `--clean`):
-Wraps `git worktree prune` to clean up administrative files for deleted worktrees.
+**Default Mode (full cleanup):**
+Removes worktrees that are safe to delete (no uncommitted changes, no unpushed commits) AND deletes orphan branches (branches without associated worktrees).
 
-**Clean Mode** (with `--clean`):
-First runs `git worktree prune`, then removes ALL worktrees that have no uncommitted changes, no staged files, and no unpushed commits. This is similar to default `gw clean` behavior but with additional protections for the default branch.
+**Stale-Only Mode** (with `--stale-only`):
+Git passthrough - only cleans up administrative files for deleted worktrees. Does not remove worktrees or branches.
 
 ```bash
 gw prune [options]
@@ -1319,42 +1319,47 @@ gw prune [options]
 
 **Options:**
 
-- `--clean` - Enable clean mode (remove clean worktrees)
+- `--stale-only` - Git passthrough mode (only metadata cleanup)
+- `--no-branches` - Skip orphan branch cleanup (worktrees only)
 - `-n, --dry-run` - Preview what would be removed
 - `-f, --force` - Skip confirmation prompt
 - `-v, --verbose` - Show detailed output
 - `-h, --help` - Show help
 
-**Safety Features** (in clean mode):
+**Safety Features:**
 
 - Default branch is protected (configured in `.gw/config.json`)
 - gw_root branch is protected (bare repository root)
 - Current worktree cannot be removed
 - Bare repository is never removed
-- Confirmation prompt before removal (defaults to yes, just press Enter to confirm)
+- Branches with unpushed commits are protected
+- Confirmation prompt before removal (defaults to yes)
 
 **Examples:**
 
 ```bash
-# Standard prune (cleanup administrative data)
-gw prune
-gw prune --verbose
+# Full cleanup (default) - removes worktrees AND orphan branches
+gw prune                     # Remove clean worktrees and orphan branches
+gw prune --dry-run           # Preview what would be removed
+gw prune --force             # Skip confirmation
+gw prune --verbose           # Show detailed output
+
+# Skip branch cleanup
+gw prune --no-branches       # Only clean worktrees, keep branches
 
-# Clean mode (remove clean worktrees)
-gw prune --clean              # Remove all clean worktrees (with prompt)
-gw prune --clean --dry-run    # Preview what would be removed
-gw prune --clean --force      # Remove without confirmation
-gw prune --clean --verbose    # Show detailed output
+# Git passthrough (stale-only)
+gw prune --stale-only        # Only clean git metadata (like git worktree prune)
 ```
 
 **Comparison with `gw clean`:**
-| Feature | `gw clean` | `gw clean --use-autoclean-threshold` | `gw prune --clean` |
+| Feature | `gw clean` | `gw clean --use-autoclean-threshold` | `gw prune` |
 |---------|-----------|-------------------------------------|-------------------|
 | Age-based | No (all worktrees) | Yes (configurable threshold) | No (removes all clean) |
 | Safety checks | Yes | Yes | Yes |
 | Protects default branch | No | No | Yes |
+| Deletes orphan branches | No | No | Yes |
 | Runs `git worktree prune` | No | No | Yes |
-| Use case | Clean up finished work | Regular maintenance | Aggressive cleanup |
+| Use case | Clean up finished work | Regular maintenance | Full cleanup |
 
 #### lock
 

package/package.json

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