@ogpoyraz/wtx 0.6.1 → 0.8.0

package/README.md

@@ -59,13 +59,16 @@ Run any command without a config and `wtx` walks you through setup: it scans com
 # create a worktree (deps + sync_files handled automatically)
 wtx create ogp/my-feature --repo my-frontend
 
+# create a dependent worktree from another branch
+wtx create ogp/my-ui --repo my-frontend --base ogp/my-api
+
 # hand it to a coding agent
 wtx create ogp/my-feature --repo my-frontend --agent claude --prompt "add OAuth login"
 
 # list everything across all repos
 wtx ls
 
-# rebase onto main when origin moves
+# rebase onto the recorded base (main for independent branches)
 wtx rebase ogp/my-feature
 
 # remove when merged — refuses dirty worktrees unless forced
@@ -80,17 +83,20 @@ If origin already has a branch with that name owned by someone else, `wtx` warns
 
 | Command | Args | Flags | Description |
 |---|---|---|---|
-| `create` | `<branch>` | `--repo`, `--base`, `--open`, `--ide`, `--track`, `--local`, `--agent <name>`, `--prompt <text>` | Create worktree(s), sync files, prepare deps, optionally spawn an agent |
+| `create` | `<branch>` | `--repo`, `--base`, `--open`, `--ide`, `--track`, `--local`, `--agent <name>`, `--prompt <text>`, `--deps <strategy>` | Create worktree(s), sync files, prepare deps, optionally spawn an agent |
 | `pull` | `<pr-link>` | `--repo` | Fetch a GitHub PR and create its worktree |
+| `pull-branch` | `[branch]` | `--repo` | Fast-forward pull a worktree's branch (auto-detects repo from cwd) |
 | `remove` | `<branch>` | `--repo`, `--force`, `--yes` | Remove worktree(s), clean empty dirs |
+| `rename` | `<old-branch> <new-branch>` | `--repo` | Rename the branch and move the checkout to the matching new directory |
 | `prune` | | `--repo`, `--force`, `--yes` | Remove worktrees whose PR has merged |
 | `open` | `<branch>` | `--repo`, `--ide` | Open worktree in IDE |
-| `rebase` | `<branch>` | `--repo` | Fetch base remote main, rebase worktree onto it |
+| `rebase` | `<branch>` | `--repo`, `--onto <ref>` | Rebase worktree onto its recorded base, or an explicit ref |
 | `fetch` | | `--repo` | Fetch main for each repo |
 | `sync` | `<branch>` | `--repo` | Re-copy sync files, run post-sync hooks |
-| `deps` | `[branch]` | `--repo`, `--install`, `--symlink`, `--json` | Inspect or switch dependency strategy |
+| `deps` | `[branch]` | `--repo`, `--install`, `--symlink`, `--json` | Inspect or switch dependency strategy; omit the branch and `--install` runs in the main checkout |
 | `ls` | | `--repo`, `--pr`, `--json` | List all worktrees with clean/dirty state |
-| `status` | `<branch>` | `--repo`, `--json` | Ahead/behind, dirty files, rebase state, deps strategy |
+| `status` | `<branch>` | `--repo`, `--base <ref>`, `--json` | Ahead/behind against base, dirty files, rebase state, deps strategy |
+| `stack` | `<branch>` | `--repo`, `--json` | Show recorded parent and descendant branches |
 | `prs` | | `--repo`, `--json`, `--all` | Pull request status across worktrees |
 | `exec` | `<branch> <command...>` | `--repo` | Run a command inside a worktree (`WTX_PORT` injected) |
 | `terminal` | | | Interactive worktree dashboard (requires Bun) |
@@ -139,6 +145,12 @@ Config lives at `~/.config/wtx/config.json`.
     },
     "my-go-service": {
       "main_branch": "main"
+    },
+    "forked-lib": {
+      "check_prs": true,
+      "forge_provider": "github",
+      "pr_lookup_repo": "upstream-owner/lib",
+      "install_script": "pnpm install --frozen-lockfile"
     }
   }
 }
@@ -159,10 +171,22 @@ Config lives at `~/.config/wtx/config.json`.
 | `repos.<name>.fetch_main_on_create` | `true` | Fetch before creating so branches start fresh |
 | `repos.<name>.sync_files` | `[]` | Files copied from main checkout on create and sync |
 | `repos.<name>.post_create` / `post_sync` | `[]` | Hook commands; failures fail the command with a rerun hint |
+| `repos.<name>.install_script` | `null` | Command run inside a worktree (or the main checkout via `wtx deps --install`) for dependency installs (`{wt}`, `{branch}`, `{main}` expanded); when unset, the detected package manager performs a real install |
 | `repos.<name>.deps.manager` | `"auto"` | Force a manager: `npm` `bun` `pnpm` `yarn` `go` `python` `cargo` |
 | `repos.<name>.deps.strategy` | `"auto"` | `auto` `link` `symlink` `install` `off` — see below |
-| `repos.<name>.pr` | `true` | Skip PR lookups for this repo |
-| `repos.<name>.forge` / `pr_repo` | `"auto"` / `null` | GitHub Enterprise and fork workflows |
+| `repos.<name>.check_prs` | `true` | Set `false` to skip all PR lookups for this repo's branches (no `gh` calls) |
+| `repos.<name>.forge_provider` | `"auto"` | `"auto"` enables GitHub only when the origin remote is github.com; `"github"` forces GitHub even for other hosts (GitHub Enterprise) |
+| `repos.<name>.pr_lookup_repo` | `null` | `owner/repo` override for where PRs are looked up — use when origin points at a fork or mirror |
+
+#### PR lookup keys explained
+
+PR visibility (`wtx prs`, the TUI badges, ownership tags, `prune`) is read-only via the `gh` CLI. Three per-repo keys tune it:
+
+- **`check_prs`** — master switch. `false` disables every `gh` query for this repo; everything else keeps working.
+- **`forge_provider`** — which forge hosts the project. `"auto"` only activates GitHub when your origin remote is `github.com`; set `"github"` to force it for GitHub Enterprise or custom domains.
+- **`pr_lookup_repo`** — where to look PRs up, as `owner/repo`. Normally derived from origin; override when origin points at your fork but PRs live in the upstream repo.
+
+Legacy configs using `pr`, `forge`, and `pr_repo` keep working — they are migrated automatically on load and rewritten in place on the next config save.
 
 ### Template variables
 
@@ -194,6 +218,8 @@ Hooks also receive `WTX_PORT` as an environment variable, as does `wtx exec`. Po
 | `install` | Always a real install in the worktree |
 | `off` | Leave dependencies alone |
 
+Per-repo `install_script` overrides the install command entirely — useful for non-standard setups (`pnpm install --frozen-lockfile`, bootstrap scripts, codegen steps). It runs inside the worktree (or the main checkout when installing via `wtx deps --install` with no branch) with the same `{wt}` / `{branch}` / `{main}` template expansion as hooks.
+
 ### Safe linking (the `auto` default)
 
 When manifests match main, wtx creates a **real** `node_modules` directory in the worktree containing per-package symlinks into main's tree (scoped packages traversed, `.bin` linked). Package-manager operations inside the worktree replace links, never main's files — an `npm install` in one branch cannot damage another checkout. If replacing an existing directory fails mid-way, the original is restored rather than left missing.
@@ -259,7 +285,24 @@ wtx pull https://github.com/OGPoyraz/wtx/pull/11   # PR → worktree in one comm
 wtx prune                                          # remove worktrees whose PR merged
 ```
 
-Lookups degrade gracefully: if `gh` is missing or unauthenticated you get a warning and everything else keeps working. Fork workflows are covered by `forge` / `pr_repo`.
+Lookups degrade gracefully: if `gh` is missing or unauthenticated you get a warning and everything else keeps working. Fork workflows are covered by `check_prs` / `forge_provider` / `pr_lookup_repo`.
+
+### Stacked branches
+
+Worktrees remain sibling directories on disk, while their branches can form a dependency stack:
+
+```bash
+wtx create feat/api
+wtx create feat/ui --base feat/api
+
+# Open the PRs with these bases:
+# feat/api -> main
+# feat/ui  -> feat/api
+```
+
+`--base` accepts a normal Git ref and uses committed history only; uncommitted files in the parent worktree are not copied. The default remains the configured main branch. `wtx stack feat/ui` shows the recorded local relationship, and `wtx rebase feat/ui` rebases onto the recorded parent instead of flattening the stack onto main. After the parent merges, retarget the child PR to main before rebasing it onto main.
+
+Stack metadata is stored under the repository's common Git directory and is not committed to the project. If a parent branch moves, `wtx status <child>` and the terminal dashboard mark the base as moved. Removing a parent with recorded children is refused unless `--force` is supplied.
 
 ---
 
@@ -272,7 +315,10 @@ Lookups degrade gracefully: if `gh` is missing or unauthenticated you get a warn
 | `/` | Fuzzy-filter entries by branch, repo, PR, owner |
 | `Space` | Multi-select for batch operations |
 | `R` / `D` / `s` | Batch rebase / remove / sync selection |
-| `n` | Create worktree |
+| `p` | Pull latest changes for selected branch(es) |
+| `i` | Install dependencies in selected worktree(s) |
+| `n` | Create worktree — pick a dependency strategy (auto / install / symlink) |
+| `m` | Rename worktree (branch + directory move) |
 | `b` | Rebase selected |
 | `a` | Spawn coding agent in selected worktree |
 | `H` | Action history (recent actions across CLI and dashboard) |
@@ -280,7 +326,9 @@ Lookups degrade gracefully: if `gh` is missing or unauthenticated you get a warn
 | `c` | Edit configuration |
 | `?` / `q` | Help / quit |
 
-Actions run in the background — navigation never locks. Progress shows inline: `fetching` next to the repo header, `deleting` / `rebasing` / `syncing` next to the branch (dimmed while busy), and a new worktree appears immediately as a `(creating)` row. One operation runs per repo at a time; conflicting actions are rejected with a toast until it finishes. On failure a log modal opens with the captured output; press any key to dismiss. Destructive ones confirm first.
+Actions run in the background — navigation never locks. Progress shows inline: `fetching`, `pulling`, `installing deps`, `renaming`, etc. next to the repo or branch being worked on, and a new worktree appears immediately as a `(creating)` row. Repositories render alphabetically and stay sorted across create/delete operations. While data loads, repos appear immediately with a `refreshing…` indicator. One operation runs per repo at a time; conflicting actions are rejected with a toast until it finishes. On failure a log modal opens with the captured output; press any key to dismiss. Destructive ones confirm first.
+
+If a rebase hits conflicts, the worktree is restored: the in-progress rebase is aborted automatically, the branch stays on its pre-rebase commits, and a "Rebase failed — manual merge needed" log explains what happened.
 
 ---
 

package/completions/_wtx.zsh

@@ -59,14 +59,17 @@ _wtx() {
         'remove[Remove worktrees]' \
         'prune[Remove worktrees with merged PRs]' \
         'open[Open worktree in IDE]' \
-        'rebase[Fetch and rebase vs main]' \
+         'rebase[Fetch and rebase onto recorded base]' \
         'pull[Fetch a PR and create its worktree]' \
+        'pull-branch[Fast-forward pull a worktree branch]' \
+        'rename[Rename branch and move worktree directory]' \
         'fetch[Fetch origin main]' \
         'sync[Re-copy sync files and run post_sync]' \
         'deps[Manage node_modules strategy]' \
         'ls[List worktrees with status]' \
         'cd[Change directory to worktree]' \
-        'status[Show worktree status]' \
+         'status[Show worktree status]' \
+         'stack[Show recorded branch stack]' \
         'prs[Show pull request status across worktrees]' \
         'init[Output shell integration code]' \
         'skill[Manage AI agent skills]' \
@@ -125,6 +128,7 @@ _wtx() {
           _arguments \
             ':branch:_wtx_branches' \
             '--repo[Target specific repo(s)]:repo:_wtx_repos' \
+            '--onto[Override recorded base]:ref:' \
             {-q,--quiet}'[Suppress output]' \
             '--verbose[Show git commands]' \
             '--dry-run[Show what would happen]'
@@ -137,6 +141,23 @@ _wtx() {
             '--verbose[Show git commands]' \
             '--dry-run[Show what would happen]'
           ;;
+        pull-branch)
+          _arguments \
+            '::branch:_wtx_branches' \
+            {-r,--repo}'[Target specific repo(s)]:repo:_wtx_repos' \
+            {-q,--quiet}'[Suppress output]' \
+            '--verbose[Show git commands]' \
+            '--dry-run[Show what would happen]'
+          ;;
+        rename)
+          _arguments \
+            ':old-branch:_wtx_branches' \
+            ':new-branch:' \
+            {-r,--repo}'[Target specific repo(s)]:repo:_wtx_repos' \
+            {-q,--quiet}'[Suppress output]' \
+            '--verbose[Show git commands]' \
+            '--dry-run[Show what would happen]'
+          ;;
         fetch)
           _arguments \
             '--repo[Target specific repo(s)]:repo:_wtx_repos' \
@@ -178,6 +199,16 @@ _wtx() {
             ':branch:_wtx_branches'
           ;;
         status)
+          _arguments \
+            ':branch:_wtx_branches' \
+            {-r,--repo}'[Target specific repo(s)]:repo:_wtx_repos' \
+            '--base[Override recorded base]:ref:' \
+            '--json[Output machine-readable JSON]' \
+            {-q,--quiet}'[Suppress output]' \
+            '--verbose[Show git commands]' \
+            '--dry-run[Show what would happen]'
+          ;;
+        stack)
           _arguments \
             ':branch:_wtx_branches' \
             {-r,--repo}'[Target specific repo(s)]:repo:_wtx_repos' \

package/completions/wtx.bash

@@ -43,7 +43,7 @@ _wtx_completions() {
     cword=$COMP_CWORD
   }
 
-  local subcommands="config create remove prune open rebase fetch sync deps ls cd status prs pull init skill terminal mcp exec"
+  local subcommands="config create remove prune open rebase fetch sync deps ls cd status prs pull pull-branch init skill terminal mcp exec rename stack"
   local config_subcommands="init show set add-repo remove-repo"
   local skill_subcommands="show path list"
   local skill_names="opencode cursor claude"
@@ -80,7 +80,7 @@ _wtx_completions() {
     return 0
   fi
 
-  if [ "$prev" = "--base" ]; then
+  if [ "$prev" = "--base" ] || [ "$prev" = "--onto" ]; then
     COMPREPLY=($(compgen -W "main master develop dev" -- "$cur"))
     return 0
   fi
@@ -88,17 +88,19 @@ _wtx_completions() {
   if [[ "$cur" == -* ]]; then
     local flags=""
     case "$subcommand" in
-      create)  flags="-r --repo --base --open --ide --track --agent --prompt -q --quiet --verbose --dry-run --help" ;;
+      create)  flags="-r --repo --base --open --ide --track --agent --prompt --deps -q --quiet --verbose --dry-run --help" ;;
       remove)  flags="-f --force -y --yes -r --repo -q --quiet --verbose --dry-run --help" ;;
       prune)   flags="-f --force -y --yes -r --repo -q --quiet --verbose --dry-run --help" ;;
       open)    flags="-r --repo --ide -q --quiet --verbose --dry-run --help" ;;
-      rebase)  flags="--repo -q --quiet --verbose --dry-run --help" ;;
+      rebase)  flags="--repo --onto -q --quiet --verbose --dry-run --help" ;;
+      rename)  flags="-r --repo -q --quiet --verbose --dry-run --help" ;;
       fetch)   flags="--repo -q --quiet --verbose --dry-run --help" ;;
       sync)    flags="--repo -q --quiet --verbose --dry-run --help" ;;
       deps)    flags="-r --repo --install --symlink --json -q --quiet --verbose --dry-run --help" ;;
       pull)    flags="-r --repo -q --quiet --verbose --dry-run --help" ;;
       ls)      flags="-r --repo --pr --json -q --quiet --verbose --dry-run --help" ;;
-      status)  flags="-r --repo --json -q --quiet --verbose --dry-run --help" ;;
+      status)  flags="-r --repo --base --json -q --quiet --verbose --dry-run --help" ;;
+      stack)   flags="-r --repo --json -q --quiet --verbose --dry-run --help" ;;
       prs)     flags="-r --repo --json --all -q --quiet --verbose --dry-run --help" ;;
       config)
         case "$subsubcommand" in
@@ -152,7 +154,7 @@ _wtx_completions() {
     cd)
       [ "$prev" = "cd" ] && COMPREPLY=($(compgen -W "$(_wtx_get_repos)" -- "$cur")) && return 0
       ;;
-    rebase|open|status|remove|sync|deps)
+    rebase|open|status|remove|sync|deps|rename|stack)
       [ "$prev" = "$subcommand" ] && COMPREPLY=($(compgen -W "$(_wtx_get_branches)" -- "$cur")) && return 0
       ;;
   esac

package/completions/wtx.fish

@@ -41,7 +41,7 @@ complete -c wtx -l dry-run -d "Show what would happen"
 complete -c wtx -s h -l help -d "Display help for command"
 
 # Subcommands
-set -l commands config create remove prune open rebase fetch sync deps ls cd status prs pull init skill terminal mcp exec
+set -l commands config create remove prune open rebase fetch sync deps ls cd status prs pull pull-branch init skill terminal mcp exec rename stack
 
 # Setup completions for commands
 complete -c wtx -n "not __fish_seen_subcommand_from $commands" -a "config" -d "Manage configuration"
@@ -49,14 +49,17 @@ complete -c wtx -n "not __fish_seen_subcommand_from $commands" -a "create" -d "C
 complete -c wtx -n "not __fish_seen_subcommand_from $commands" -a "remove" -d "Remove worktrees"
 complete -c wtx -n "not __fish_seen_subcommand_from $commands" -a "prune" -d "Remove worktrees with merged PRs"
 complete -c wtx -n "not __fish_seen_subcommand_from $commands" -a "open" -d "Open worktree in IDE"
-complete -c wtx -n "not __fish_seen_subcommand_from $commands" -a "rebase" -d "Fetch and rebase vs main"
+complete -c wtx -n "not __fish_seen_subcommand_from $commands" -a "rebase" -d "Fetch and rebase onto recorded base"
 complete -c wtx -n "not __fish_seen_subcommand_from $commands" -a "pull" -d "Fetch a PR and create its worktree"
+complete -c wtx -n "not __fish_seen_subcommand_from $commands" -a "pull-branch" -d "Fast-forward pull a worktree branch"
+complete -c wtx -n "not __fish_seen_subcommand_from $commands" -a "rename" -d "Rename branch and move worktree directory"
 complete -c wtx -n "not __fish_seen_subcommand_from $commands" -a "fetch" -d "Fetch origin main"
 complete -c wtx -n "not __fish_seen_subcommand_from $commands" -a "sync" -d "Re-copy sync files and run post_sync"
 complete -c wtx -n "not __fish_seen_subcommand_from $commands" -a "deps" -d "Manage node_modules strategy"
 complete -c wtx -n "not __fish_seen_subcommand_from $commands" -a "ls" -d "List worktrees with status"
 complete -c wtx -n "not __fish_seen_subcommand_from $commands" -a "cd" -d "Change directory to worktree"
 complete -c wtx -n "not __fish_seen_subcommand_from $commands" -a "status" -d "Show worktree status"
+complete -c wtx -n "not __fish_seen_subcommand_from $commands" -a "stack" -d "Show recorded branch stack"
 complete -c wtx -n "not __fish_seen_subcommand_from $commands" -a "prs" -d "Show pull request status across worktrees"
 complete -c wtx -n "not __fish_seen_subcommand_from $commands" -a "init" -d "Output shell integration code"
 complete -c wtx -n "not __fish_seen_subcommand_from $commands" -a "skill" -d "Manage AI agent skills"
@@ -65,14 +68,15 @@ complete -c wtx -n "not __fish_seen_subcommand_from $commands" -a "mcp" -d "Run
 complete -c wtx -n "not __fish_seen_subcommand_from $commands" -a "exec" -d "Execute commands across worktrees"
 
 # Dynamically complete branch arguments
-complete -c wtx -n "__fish_seen_subcommand_from create open rebase sync deps status remove" -a "(_wtx_get_branches)"
+complete -c wtx -n "__fish_seen_subcommand_from create open rebase sync deps status remove rename pull-branch stack" -a "(_wtx_get_branches)"
 
 # Flags
-complete -c wtx -n "__fish_seen_subcommand_from create remove prune open rebase fetch sync deps ls status prs pull" -s r -l repo -xa "(_wtx_get_repos)" -d "Target specific repo(s)"
+complete -c wtx -n "__fish_seen_subcommand_from create remove prune open rebase fetch sync deps ls status stack prs pull pull-branch rename" -s r -l repo -xa "(_wtx_get_repos)" -d "Target specific repo(s)"
 
 # create flags
 complete -c wtx -n "__fish_seen_subcommand_from create" -l base -xa "main master develop dev" -d "Base ref"
 complete -c wtx -n "__fish_seen_subcommand_from create" -s o -l open -d "Open worktree in IDE after creation"
+complete -c wtx -n "__fish_seen_subcommand_from create" -l deps -xa "auto link symlink install off" -d "Dependency strategy"
 complete -c wtx -n "__fish_seen_subcommand_from create open" -l ide -xa "cursor code vscode code-insiders vscodium idea webstorm zed vim nvim emacs" -d "IDE to open with"
 complete -c wtx -n "__fish_seen_subcommand_from create" -l track -d "Track remote branch even if it belongs to someone else"
 complete -c wtx -n "__fish_seen_subcommand_from create" -l agent -d "AI agent to delegate work to"
@@ -87,7 +91,7 @@ complete -c wtx -n "__fish_seen_subcommand_from deps" -l install -d "Switch to i
 complete -c wtx -n "__fish_seen_subcommand_from deps" -l symlink -d "Switch to symlinked node_modules"
 
 # json flag
-complete -c wtx -n "__fish_seen_subcommand_from ls status prs deps" -l json -d "Output machine-readable JSON"
+complete -c wtx -n "__fish_seen_subcommand_from ls status stack prs deps" -l json -d "Output machine-readable JSON"
 
 # ls flags
 complete -c wtx -n "__fish_seen_subcommand_from ls" -l pr -d "Include pull request status column"
@@ -95,6 +99,10 @@ complete -c wtx -n "__fish_seen_subcommand_from ls" -l pr -d "Include pull reque
 # prs flags
 complete -c wtx -n "__fish_seen_subcommand_from prs" -l all -d "Include drafts and closed/merged PRs"
 
+# stack-aware flags
+complete -c wtx -n "__fish_seen_subcommand_from rebase" -l onto -xa "main master develop dev" -d "Override recorded base"
+complete -c wtx -n "__fish_seen_subcommand_from status" -l base -xa "main master develop dev" -d "Override recorded base"
+
 # config subcommands
 set -l config_commands init show set add-repo remove-repo
 complete -c wtx -n "__fish_seen_subcommand_from config; and not __fish_seen_subcommand_from $config_commands" -a "init" -d "Initialize configuration"