@gw-tools/gw 0.12.11 → 0.12.15

package/README.md

@@ -25,24 +25,28 @@ A command-line tool for managing git worktrees, built with Deno.
       - [Arguments](#arguments-1)
       - [Examples](#examples-1)
       - [How It Works](#how-it-works)
-    - [install-shell](#install-shell)
+    - [pull](#pull)
       - [Options](#options-1)
       - [Examples](#examples-2)
-    - [root](#root)
-      - [Examples](#examples-3)
       - [How It Works](#how-it-works-1)
-    - [init](#init)
+    - [install-shell](#install-shell)
       - [Options](#options-2)
+      - [Examples](#examples-3)
+    - [root](#root)
       - [Examples](#examples-4)
+      - [How It Works](#how-it-works-2)
+    - [init](#init)
+      - [Options](#options-3)
+      - [Examples](#examples-5)
       - [When to Use](#when-to-use)
     - [sync](#sync)
       - [Arguments](#arguments-2)
-      - [Options](#options-3)
-      - [Examples](#examples-5)
-    - [clean](#clean)
       - [Options](#options-4)
       - [Examples](#examples-6)
-      - [How It Works](#how-it-works-2)
+    - [clean](#clean)
+      - [Options](#options-5)
+      - [Examples](#examples-7)
+      - [How It Works](#how-it-works-3)
     - [Git Worktree Proxy Commands](#git-worktree-proxy-commands)
       - [list (ls)](#list-ls)
       - [remove (rm)](#remove-rm)
@@ -174,7 +178,9 @@ gw init --root /path/to/your/repo.git
       "post": ["pnpm install", "echo 'Setup complete!'"]
     }
   },
-  "cleanThreshold": 7
+  "cleanThreshold": 7,
+  "autoClean": true,
+  "lastAutoCleanTime": 1706371200000
 }
 ```
 
@@ -189,6 +195,8 @@ gw init --root /path/to/your/repo.git
   - **hooks.add.pre**: Array of commands to run before creating a worktree
   - **hooks.add.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**: Automatically remove stale worktrees when running `gw add` or `gw list` (optional, defaults to false, set via `gw init --auto-clean`)
+- **lastAutoCleanTime**: Internal timestamp tracking last auto-cleanup run (managed automatically, do not edit manually)
 
 ## Commands
 
@@ -205,6 +213,12 @@ This command wraps `git worktree add` and optionally copies files to the new wor
 **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. If the remote is unavailable (no network or no remote configured), it gracefully falls back to using the local branch with a warning message.
 
+**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.
+
+**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.
+
 #### Arguments
 
 - `<worktree-name>`: Name or path for the new worktree
@@ -332,6 +346,67 @@ 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`.
 
+### pull
+
+Merge the latest version of the default branch (or specified branch) into your current worktree. This is useful when you want to update your feature branch with the latest changes from main without having to switch worktrees.
+
+```bash
+gw pull [options]
+```
+
+When working in a worktree, you cannot easily checkout main to pull the latest changes because main is typically checked out in another worktree. The `gw pull` command solves this by fetching the latest version of the default branch and merging it into your current branch.
+
+#### Options
+
+- `--from <branch>`: Merge from specified branch instead of defaultBranch (e.g., `--from develop`)
+- `--remote <name>`: Specify remote name (default: "origin")
+- `-f, --force`: Skip uncommitted changes check (not recommended)
+- `-n, --dry-run`: Preview what would happen without executing
+- `-h, --help`: Show help message
+
+#### Examples
+
+```bash
+# Merge latest default branch (typically main)
+gw pull
+
+# Merge from a specific branch
+gw pull --from develop
+
+# Preview what would happen
+gw pull --dry-run
+
+# Force pull even with uncommitted changes (not recommended)
+gw pull --force
+
+# Use a different remote
+gw pull --remote upstream
+```
+
+#### How It Works
+
+1. Fetches the latest version of the target branch from remote (e.g., `origin/main`)
+2. Merges it into your current worktree's active branch
+3. Creates merge commit if histories have diverged
+
+**Safety checks:**
+- Blocks if you have uncommitted changes (use `--force` to override)
+- Blocks if you're in a detached HEAD state
+- Handles merge conflicts gracefully with clear guidance
+
+**Merge strategy:** Allows merge commits (not fast-forward only), so it works even if you have local commits.
+
+**Configuration:**
+
+The default branch is read from `.gw/config.json`:
+```json
+{
+  "defaultBranch": "main"
+}
+```
+
+If not configured, defaults to "main".
+
 ### install-shell
 
 Install or remove shell integration for the `gw cd` command. This is automatically run during `npm install`, but can be run manually if needed.
@@ -421,6 +496,7 @@ gw init [options]
 - `--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)
 - `--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)
 - `-h, --help`: Show help message
 
 #### Examples
@@ -465,6 +541,33 @@ Hooks support variable substitution:
 - `{gitRoot}` - The git repository root path
 - `{branch}` - The branch name
 
+#### Auto-Cleanup Configuration
+
+Enable automatic removal of stale worktrees to keep your repository clean:
+
+```bash
+# Enable auto-cleanup with default 7-day threshold
+gw init --auto-clean
+
+# Enable with custom threshold (14 days)
+gw init --auto-clean --clean-threshold 14
+
+# Enable with other options
+gw init --auto-clean --auto-copy-files .env --post-add "pnpm install"
+```
+
+**How it works:**
+- Runs automatically on `gw add` and `gw list` commands
+- Only runs once per 24 hours (cooldown)
+- Removes worktrees older than `cleanThreshold` with:
+  - No uncommitted changes
+  - No staged files
+  - No unpushed commits
+- Shows brief message only when worktrees are removed: `🧹 Auto-cleanup: Removed 2 stale worktrees`
+- Never interrupts or fails the main command
+
+This is an opt-in feature. Use `gw clean` for manual, interactive cleanup with more control.
+
 #### When to Use
 
 Use `gw init` to:
@@ -524,6 +627,8 @@ gw sync /full/path/to/repo/feat-branch .env
 
 Remove stale worktrees that are older than a configured threshold. By default, only removes worktrees with no uncommitted changes and no unpushed commits.
 
+**Note:** For automatic cleanup, see `gw init --auto-clean`. The `clean` command provides interactive, manual cleanup with detailed output and confirmation prompts.
+
 ```bash
 gw clean [options]
 ```
@@ -713,6 +818,9 @@ gw add feat-new-feature
 # Navigate to your new worktree
 gw cd feat-new-feature
 
+# Keep your feature branch updated with latest changes from main
+gw pull
+
 # Alternative: Create worktree and copy specific files
 gw add feat-bugfix .env custom-config.json
 

package/package.json

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