@shivanshshrivas/gwit 0.1.3 → 0.2.1

package/README.md

@@ -1,6 +1,12 @@
-# gwit
-
-Fully isolated git worktrees, in one command.
+# gwit
+
+[![npm version](https://img.shields.io/npm/v/%40shivanshshrivas%2Fgwit)](https://www.npmjs.com/package/@shivanshshrivas/gwit)
+[![npm downloads](https://img.shields.io/npm/dm/%40shivanshshrivas%2Fgwit)](https://www.npmjs.com/package/@shivanshshrivas/gwit)
+[![CI](https://github.com/shivanshshrivas/gwit/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/shivanshshrivas/gwit/actions/workflows/ci.yml)
+[![Node >=20](https://img.shields.io/badge/node-%3E%3D20-339933)](https://nodejs.org/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-yellow.svg)](./LICENSE)
+
+Fully isolated git worktrees, in one command.
 
 gwit wraps `git worktree` to turn a fresh checkout into a fully working environment - gitignored files copied, unique port assigned, per-worktree env vars injected, and setup scripts run automatically.
 
@@ -26,9 +32,16 @@ gwit -b fix/login-page        # create a new branch from HEAD
 
 # Day-to-day
 gwit list                     # show all active worktrees
+gwit status                   # see ahead/behind, dirty state, PR info
 gwit sync feature/auth        # re-copy files after .env changes
+gwit sync --back feature/auth # three-way merge .gwitinclude files back to main
 gwit open feature/auth        # re-open editor for an existing worktree
+
+# Merge and clean up
+gwit merge feature/auth       # merge branch back into main
 gwit remove feature/auth      # run cleanup hooks and remove worktree
+gwit sweep                    # bulk-remove all merged worktrees
+gwit rename old/name new/name # rename a worktree branch
 ```
 
 ## How it works
@@ -102,13 +115,26 @@ gwit remove feature/auth --force   # skip uncommitted-changes check
 
 ### `gwit sync [branch]`
 
-Re-copy `.gwitinclude` files into an existing worktree. Use this when your `.env` gains a new key, certs rotate, or `node_modules` is updated.
+By default, re-copy `.gwitinclude` files from main into an existing worktree.  
+With `--back`, sync in the reverse direction using snapshot-aware three-way merge.
 
 ```sh
 gwit sync feature/auth   # sync a specific branch
 gwit sync                # auto-detect from current directory (when inside a worktree)
+gwit sync --back feature/auth  # three-way merge worktree -> main
+gwit sync --back               # auto-detect branch, then merge back
 ```
 
+`--back` compares three versions of each snapshot-tracked file:
+
+1. **base** - file content captured when the worktree was created
+2. **main** - current file in the main worktree
+3. **worktree** - current file in the linked worktree
+
+If both sides changed different text regions, gwit applies a clean merge.  
+If both sides changed the same region, gwit writes git-style conflict markers  
+(`<<<<<<<`, `=======`, `>>>>>>>`). Binary conflicts are skipped with a warning.
+
 ### `gwit open <branch>`
 
 Re-open the editor for an existing worktree. Useful when the editor window was closed.
@@ -118,6 +144,62 @@ gwit open feature/auth
 gwit open feature/auth --editor cursor
 ```
 
+### `gwit merge <branch>`
+
+Merge a worktree branch back into the target branch. Combines git-tracked changes (via real git merge) with gitignored files (via reverse `.gwitinclude` sync) in a single command.
+
+```sh
+gwit merge feature/auth               # standard merge into default branch
+gwit merge feature/auth --into dev    # merge into a specific branch
+gwit merge feature/auth --squash      # squash all commits into one
+gwit merge feature/auth --rebase      # rebase onto target, then fast-forward
+gwit merge feature/auth --no-ff       # force a merge commit
+gwit merge feature/auth --cleanup     # remove worktree after successful merge
+gwit merge feature/auth --no-sync-back  # skip reverse .gwitinclude copy
+```
+
+What it does, in order:
+
+1. Validates the worktree exists in the registry
+2. Resolves the target branch (default: repo's default branch)
+3. Three-way syncs `.gwitinclude` files back to main (falls back to direct copy if no snapshot; unless `--no-sync-back`)
+4. Checks out the target branch in the main worktree
+5. Merges the feature branch using the chosen strategy
+6. Optionally removes the worktree (`--cleanup`)
+
+If the merge fails with conflicts, gwit exits with a helpful message so you can resolve manually.
+
+### `gwit status`
+
+Show detailed status of all active gwit worktrees.
+
+```sh
+gwit status          # rich table output
+gwit status --json   # machine-readable JSON
+```
+
+Displays per-worktree: branch, path, port, ahead/behind counts, dirty-file count, and PR info (if [`gh` CLI](https://cli.github.com) is installed).
+
+### `gwit sweep`
+
+Bulk-remove worktrees whose branches are fully merged into the default branch or whose GitHub PRs are merged/closed.
+
+```sh
+gwit sweep             # interactive confirmation
+gwit sweep --dry-run   # show what would be removed
+gwit sweep --force     # skip confirmation
+```
+
+Runs cleanup hooks for each removed worktree, just like `gwit remove`.
+
+### `gwit rename <old-branch> <new-branch>`
+
+Rename a worktree's git branch, move the directory (if the slug changes), and update the registry atomically.
+
+```sh
+gwit rename feature/auth feature/authentication
+```
+
 ### `gwit config`
 
 Show or update global configuration stored in `~/.gwitrc`.
@@ -145,15 +227,19 @@ gwit config set basePort 4000      # starting port for auto-assignment
 
 ### `.gwitinclude`
 
-List of gitignored files and directories to copy into every new worktree. One entry per line, comments with `#` ignored.
+List of gitignored files and directories to copy into every new worktree. One entry per line, comments with `#` ignored. Supports glob patterns via [minimatch](https://github.com/isaacs/minimatch).
 
 ```
 # .gwitinclude - files to copy into each new worktree
 .env
 .env.local
 certs/
+*.pem
+secrets/**
 ```
 
+Glob patterns (`*`, `?`, `[...]`, `**`) are expanded against the set of gitignored files in the repo. Literal entries are copied directly.
+
 Only gitignored files are eligible to copy. Tracked files are silently skipped - gwit is an allowlist for files that must be present but cannot be committed.
 
 ### `.gwitcommand`