@ogpoyraz/wtx 0.7.0 → 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
@@ -87,12 +90,13 @@ If origin already has a branch with that name owned by someone else, `wtx` warns
 | `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) |
@@ -167,7 +171,7 @@ 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 for `deps --install` and `create --deps install` (`{wt}`, `{branch}`, `{main}` expanded); when unset, the detected package manager performs a real install |
+| `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>.check_prs` | `true` | Set `false` to skip all PR lookups for this repo's branches (no `gh` calls) |
@@ -214,7 +218,7 @@ 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 with the same `{wt}` / `{branch}` / `{main}` template expansion as hooks.
+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)
 
@@ -283,6 +287,23 @@ wtx prune                                          # remove worktrees whose PR m
 
 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.
+
 ---
 
 ## Terminal dashboard

package/completions/_wtx.zsh

@@ -59,7 +59,7 @@ _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]' \
@@ -68,7 +68,8 @@ _wtx() {
         '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]' \
@@ -127,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]'
@@ -197,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 pull-branch init skill terminal mcp exec rename"
+  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
@@ -92,14 +92,15 @@ _wtx_completions() {
       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
@@ -153,7 +154,7 @@ _wtx_completions() {
     cd)
       [ "$prev" = "cd" ] && COMPREPLY=($(compgen -W "$(_wtx_get_repos)" -- "$cur")) && return 0
       ;;
-    rebase|open|status|remove|sync|deps|rename)
+    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 pull-branch init skill terminal mcp exec rename
+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,7 +49,7 @@ 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"
@@ -59,6 +59,7 @@ complete -c wtx -n "not __fish_seen_subcommand_from $commands" -a "deps" -d "Man
 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"
@@ -67,10 +68,10 @@ 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 rename pull-branch" -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 pull-branch rename" -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"
@@ -90,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"
@@ -98,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"