@junheep/gwt 0.3.0 → 0.5.0

package/README.md

@@ -29,9 +29,11 @@ gwt shell install zsh
 ```
 
 The installer shows the line it will add to `~/.zshrc` and asks for
-confirmation. The integration also provides Zsh completion for commands,
-options, worktrees, and Git refs. It only changes directories; it does not load
-environment variables or run project hooks.
+confirmation. The integration also provides Zsh completion, which lists one
+row per worktree and completes worktree IDs as well as the branch names it
+shows. It also automatically loads assigned ports and configured environment
+variables when Zsh enters a managed worktree. Previous values are restored
+when Zsh leaves it. Normal environment synchronization produces no output.
 
 ## Coding agents
 
@@ -56,14 +58,10 @@ the installed skill is identical:
 `--project` writes into the primary worktree so the skill can be committed for
 the team.
 
-The skill covers what `gwt --help` does not: that gwt is preferred over native
-`git worktree`, that project hooks need `gwt trust`, that a failed setup is
-retried rather than recreated, that ports come from `gwt info`, and that
-removal is destructive. It points at `gwt <command> --help` for command
-details instead of repeating them, so it does not go stale as gwt changes.
-Reinstall after upgrading to pick up a revised skill; an unchanged file is
-reported as already installed, and a modified one is replaced only after
-confirmation.
+The skill covers what the help does not: when to prefer gwt over native
+`git worktree`, which commands are destructive, and the traps worth knowing. It
+points at `gwt <command> --help` for command details rather than repeating
+them. Reinstall after upgrading gwt to pick up a revised skill.
 
 ## Configuration
 
@@ -90,6 +88,9 @@ Repositories without a remote use their canonical path.
         "WEB_PORT",
         "SERVER_PORT"
       ],
+      "env": {
+        "NEXT_PUBLIC_API_ENDPOINT": "http://127.0.0.1:${SERVER_PORT}"
+      },
       "postCreate": "hooks/worktree-setup",
       "preRemove": "hooks/worktree-cleanup"
     }
@@ -121,6 +122,9 @@ The project file contains the configuration fields directly:
     "WEB_PORT",
     "SERVER_PORT"
   ],
+  "env": {
+    "NEXT_PUBLIC_API_ENDPOINT": "http://127.0.0.1:${SERVER_PORT}"
+  },
   "postCreate": "./scripts/worktree-setup",
   "preRemove": "./scripts/worktree-cleanup"
 }
@@ -145,6 +149,10 @@ current commit as their base and run no setup actions.
   overwriting an existing destination.
 - `ports`: Environment variable names assigned stable ports in the range
   20000–39999.
+- `env`: Environment variables loaded alongside assigned ports. Values are
+  literal strings with optional `${PORT_NAME}` references to names declared in
+  `ports`. Shell expressions and references to arbitrary process variables are
+  not evaluated.
 - `postCreate`: Executable run after files and ports are prepared.
 - `preRemove`: Executable run before removal.
 
@@ -170,6 +178,7 @@ GWT_PATH
 GWT_PRIMARY_PATH
 GWT_BRANCH
 <each name declared in ports>
+<each name declared in env>
 ```
 
 Example `postCreate` hook:
@@ -187,25 +196,30 @@ Hook paths in user config are resolved relative to the directory containing
 worktree. Both run with the target worktree as their working directory, and
 their standard output and errors are streamed directly to the terminal.
 
-Hooks in user config are trusted because the user added them directly. Hooks
-from a committed `.gwt.json` require explicit trust because they execute
-repository code:
+User configuration is trusted because the user added it directly. Ports and
+environment variables from a committed `.gwt.json` require explicit trust
+because they automatically change the shell; repository hooks require the same
+approval because they execute code:
 
 ```sh
 gwt trust
 ```
 
-Approval is invalidated when `.gwt.json` or either hook changes.
+Approval is invalidated when `.gwt.json` or either hook changes. `gwt remove`
+asks for approval only when `preRemove` is configured, because removal applies
+nothing else from the configuration.
 
 ## Commands
 
 ```sh
-gwt new [branch] [--base <ref>] [--no-hooks]
-gwt setup [id|branch|path] [--no-hooks]
+gwt new [branch] [--base <ref>] [--no-hooks] [--background]
+gwt setup [id|branch|path] [--no-hooks] [--background]
 gwt list
-gwt switch [primary|id|branch|path]
+gwt ls
+gwt switch [primary|id|branch|path] [--create]
 gwt info [primary|id|branch|path]
 gwt remove [id|branch|path] [--keep-branch|--discard] [--yes] [--no-hooks]
+gwt prune [--dry-run] [--yes]
 gwt trust [--revoke]
 gwt config create [--project]
 gwt config show
@@ -213,26 +227,25 @@ gwt shell install zsh [--dry-run] [--yes]
 gwt skill install <claude|codex> [--project] [--dry-run] [--yes]
 ```
 
-Run `gwt --help` for the command overview, or `gwt <command> --help` for
-behavior, options, and practical examples. Nested commands such as
-`gwt config create --help` have their own help as well.
-
-`gwt new` creates `scratch/<id>` when no branch is provided. The immutable ID,
-assigned ports, and setup status are stored under the repository's common Git
-directory at `.git/gwt/worktrees/`.
-
-Setup failures retain the worktree and record the failure. Retry with
-`gwt setup <id>` or remove it explicitly.
-
-Run `gwt switch` without a target to open the interactive picker. Use the
-arrow keys, `j`/`k`, or Ctrl-n/Ctrl-p to move; press `/` to filter by branch,
-ID, or path. Enter switches to the selected worktree. Escape leaves filter
-mode or cancels the picker. `primary` is a reserved ID for the repository's
-primary worktree, so `gwt switch primary` returns to it from any linked
-worktree.
-
-`gwt remove` refuses dirty worktrees and first tries to delete the branch with
-`git branch -d`. If Git rejects safe deletion, an interactive terminal asks
-whether to force-delete the branch; non-interactive use keeps it and prints a
-command for deleting it later. `--discard --yes` explicitly allows dirty
-worktree removal and forced branch deletion.
+Run `gwt --help` for the overview, or `gwt <command> --help` for arguments,
+options, behavior, and examples. Nested commands such as `gwt config create
+--help` have their own help.
+
+What the listing does not show:
+
+- **Branches.** `gwt new` without an argument creates `scratch/<id>`. With one,
+  it reuses an existing local branch, or creates a branch tracking the remote
+  when the name exists on exactly one remote; `--base` always means "new
+  branch". `gwt switch <branch>` offers to create a worktree for a branch that
+  has none, and `--create` skips the question when running non-interactively.
+- **Background setup.** `--background` detaches `postCreate` and returns once
+  files are copied and ports assigned, logging to `.git/gwt/logs/<id>.log`.
+  `gwt list` reports the worktree as `running`, or `interrupted` if the process
+  disappears.
+- **Cleanup.** `gwt remove` also deletes the `scratch/<id>` branch a worktree
+  moved off, but only when the branch it moved to already contains those
+  commits. `gwt prune` clears records left by worktrees removed outside gwt,
+  including their scratch branches; it reports what it found and asks first.
+- **State.** IDs, assigned ports, and setup status live in
+  `.git/gwt/worktrees/`. `gwt info` prints a worktree's ports and environment
+  exactly as the shell integration loads them.