feat: add --worktrees flag for restack and sync

When a stack branch is checked out in a linked git worktree,
`git checkout` fails, blocking `restack` and `sync`. The new
`--worktrees` flag detects linked worktrees up front and rebases
those branches directly in their worktree directories instead.

- Add `ListWorktrees`, `RebaseHere`, `RebaseOntoHere`, and
  `GetResolvedGitDir` to `internal/git`
- Fix `IsRebaseInProgress` to use resolved git dir (works in
  linked worktrees where `.git` is a file, not a directory)
- Persist worktree map in `CascadeState` so `continue`/`abort`
  operate on the correct worktree after conflicts
- Wrap worktree-related failures with actionable error messages
- Add unit tests, E2E tests, and README documentation

Closes #33

Author: boneskull

README.md

@@ -296,10 +296,11 @@ If a rebase conflict occurs, resolve it and run `gh stack continue`.
 
 #### restack Flags
 
-| Flag        | Description                                   |
-| ----------- | --------------------------------------------- |
-| `--only`    | Only restack current branch, not descendants  |
-| `--dry-run` | Show what would be done                       |
+| Flag          | Description                                              |
+| ------------- | -------------------------------------------------------- |
+| `--only`      | Only restack current branch, not descendants             |
+| `--dry-run`   | Show what would be done                                  |
+| `--worktrees` | Rebase branches checked out in linked worktrees in-place |
 
 ### continue
 
@@ -321,10 +322,11 @@ This is the command to run when upstream changes have occurred (e.g., a PR in yo
 
 #### sync Flags
 
-| Flag           | Description             |
-| -------------- | ----------------------- |
-| `--no-restack` | Skip restacking branches |
-| `--dry-run`    | Show what would be done |
+| Flag           | Description                                              |
+| -------------- | -------------------------------------------------------- |
+| `--no-restack` | Skip restacking branches                                 |
+| `--dry-run`    | Show what would be done                                  |
+| `--worktrees`  | Rebase branches checked out in linked worktrees in-place |
 
 ### undo
 
@@ -349,6 +351,26 @@ Snapshots are stored in `.git/stack-undo/` and archived to `.git/stack-undo/done
 | `--force`   | Skip confirmation prompt                     |
 | `--dry-run` | Show what would be restored without doing it |
 
+## Working with Git Worktrees
+
+If you use [git worktrees](https://git-scm.com/docs/git-worktree) to check out multiple stack branches simultaneously, `git checkout` will refuse to switch to a branch that's already checked out in another worktree. This means `restack` and `sync` will fail when they try to check out those branches.
+
+The `--worktrees` flag solves this. When set, **gh-stack** detects linked worktrees up front and rebases those branches directly in their worktree directories instead of checking them out:
+
+```bash
+# Restack with worktree-aware rebasing
+gh stack restack --worktrees
+
+# Sync with worktree-aware rebasing
+gh stack sync --worktrees
+```
+
+If a rebase conflict occurs in a worktree branch, **gh-stack** will tell you which worktree directory to resolve it in. After resolving, run `gh stack continue` from the main repository as usual—**gh-stack** remembers which worktree the conflict lives in.
+
+> [!NOTE]
+>
+> The `--worktrees` flag is opt-in. Without it, **gh-stack** behaves exactly as before. If none of your stack branches are checked out in linked worktrees, the flag is a harmless no-op.
+
 ## How It Works
 
 **gh-stack** stores metadata in your local `.git/config`:

cmd/abort.go

@@ -39,10 +39,22 @@ func runAbort(cmd *cobra.Command, args []string) error {
 		return errors.New("no operation in progress")
 	}
 
+	// Determine the correct git instance for rebase operations.
+	// If the conflicting branch is in a linked worktree, operate there.
+	rebaseGit := g
+	wtPath := ""
+	if p, ok := st.Worktrees[st.Current]; ok && p != "" {
+		wtPath = p
+		rebaseGit = git.New(wtPath)
+	}
+
 	// Abort rebase if in progress
-	if g.IsRebaseInProgress() {
+	if rebaseGit.IsRebaseInProgress() {
 		fmt.Println("Aborting rebase...")
-		if err := g.RebaseAbort(); err != nil {
+		if err := rebaseGit.RebaseAbort(); err != nil {
+			if wtPath != "" {
+				return fmt.Errorf("failed to abort rebase in worktree at %s for branch %s: %w", wtPath, st.Current, err)
+			}
 			return fmt.Errorf("failed to abort rebase: %w", err)
 		}
 	}

cmd/cascade.go

@@ -27,13 +27,15 @@ var cascadeCmd = &cobra.Command{
 }
 
 var (
-	cascadeOnlyFlag   bool
-	cascadeDryRunFlag bool
+	cascadeOnlyFlag      bool
+	cascadeDryRunFlag    bool
+	cascadeWorktreesFlag bool
 )
 
 func init() {
 	cascadeCmd.Flags().BoolVar(&cascadeOnlyFlag, "only", false, "only restack current branch, not descendants")
 	cascadeCmd.Flags().BoolVar(&cascadeDryRunFlag, "dry-run", false, "show what would be done")
+	cascadeCmd.Flags().BoolVar(&cascadeWorktreesFlag, "worktrees", false, "rebase branches checked out in linked worktrees in-place")
 	rootCmd.AddCommand(cascadeCmd)
 }
 
@@ -91,7 +93,17 @@ func runCascade(cmd *cobra.Command, args []string) error {
 		}
 	}
 
-	err = doCascadeWithState(g, cfg, branches, cascadeDryRunFlag, state.OperationCascade, false, false, false, nil, stashRef, s)
+	// Build worktree map if --worktrees flag is set
+	var worktrees map[string]string
+	if cascadeWorktreesFlag {
+		var wtErr error
+		worktrees, wtErr = g.ListWorktrees()
+		if wtErr != nil {
+			return fmt.Errorf("failed to list worktrees: %w", wtErr)
+		}
+	}
+
+	err = doCascadeWithState(g, cfg, branches, cascadeDryRunFlag, state.OperationCascade, false, false, false, nil, stashRef, worktrees, s)
 
 	// Restore auto-stashed changes after operation (unless conflict, which saves stash in state)
 	if stashRef != "" && !errors.Is(err, ErrConflict) {
@@ -107,7 +119,9 @@ func runCascade(cmd *cobra.Command, args []string) error {
 // doCascadeWithState performs cascade and saves state with the given operation type.
 // allBranches is the complete list of branches for submit operations (used for push/PR after continue).
 // stashRef is the commit hash of auto-stashed changes (if any), persisted to state on conflict.
-func doCascadeWithState(g *git.Git, cfg *config.Config, branches []*tree.Node, dryRun bool, operation string, updateOnly, web, pushOnly bool, allBranches []string, stashRef string, s *style.Style) error {
+// worktrees maps branch names to linked worktree paths. When non-nil, branches in
+// the map are rebased directly in their worktree directory instead of being checked out.
+func doCascadeWithState(g *git.Git, cfg *config.Config, branches []*tree.Node, dryRun bool, operation string, updateOnly, web, pushOnly bool, allBranches []string, stashRef string, worktrees map[string]string, s *style.Style) error {
 	originalBranch, err := g.CurrentBranch()
 	if err != nil {
 		return err
@@ -153,22 +167,44 @@ func doCascadeWithState(g *git.Git, cfg *config.Config, branches []*tree.Node, d
 			}
 		}
 
+		// Determine if this branch lives in a linked worktree
+		wtPath := ""
+		if worktrees != nil {
+			wtPath = worktrees[b.Name]
+		}
+
 		if useOnto {
 			fmt.Printf("Restacking %s onto %s %s...\n", s.Branch(b.Name), s.Branch(parent), s.Muted("(using fork point)"))
 		} else {
 			fmt.Printf("Restacking %s onto %s...\n", s.Branch(b.Name), s.Branch(parent))
 		}
 
-		// Checkout and rebase
-		if err := g.Checkout(b.Name); err != nil {
-			return err
-		}
-
 		var rebaseErr error
-		if useOnto {
-			rebaseErr = g.RebaseOnto(parent, storedForkPoint, b.Name)
+		if wtPath != "" {
+			// Branch is checked out in a linked worktree -- rebase there directly
+			fmt.Printf("  %s\n", s.Muted(fmt.Sprintf("Using worktree at %s for %s", wtPath, b.Name)))
+			gitWt := git.New(wtPath)
+			if useOnto {
+				rebaseErr = gitWt.RebaseOntoHere(parent, storedForkPoint)
+			} else {
+				rebaseErr = gitWt.RebaseHere(parent)
+			}
+			// If git failed for a non-conflict reason (e.g. worktree dir was removed),
+			// wrap the error with context so the user knows which worktree we tried.
+			if rebaseErr != nil && !gitWt.IsRebaseInProgress() {
+				return fmt.Errorf("rebase of %s in worktree at %s failed (was the worktree removed or moved?): %w", b.Name, wtPath, rebaseErr)
+			}
 		} else {
-			rebaseErr = g.Rebase(parent)
+			// Normal flow: checkout + rebase in the main repo
+			if err := g.Checkout(b.Name); err != nil {
+				return err
+			}
+
+			if useOnto {
+				rebaseErr = g.RebaseOnto(parent, storedForkPoint, b.Name)
+			} else {
+				rebaseErr = g.Rebase(parent)
+			}
 		}
 
 		if rebaseErr != nil {
@@ -188,10 +224,14 @@ func doCascadeWithState(g *git.Git, cfg *config.Config, branches []*tree.Node, d
 				PushOnly:     pushOnly,
 				Branches:     allBranches,
 				StashRef:     stashRef,
+				Worktrees:    worktrees,
 			}
 			_ = state.Save(g.GetGitDir(), st) //nolint:errcheck // best effort - user can recover manually
 
 			fmt.Printf("\n%s %s\n", s.FailureIcon(), s.Error("CONFLICT: Resolve conflicts and run 'gh stack continue', or 'gh stack abort' to cancel."))
+			if wtPath != "" {
+				fmt.Printf("Resolve conflicts in worktree: %s\n", wtPath)
+			}
 			fmt.Printf("Remaining branches: %v\n", remaining)
 			if stashRef != "" {
 				fmt.Println(s.Muted("Note: Your uncommitted changes are stashed and will be restored when you continue or abort."))

cmd/continue.go

@@ -41,10 +41,22 @@ func runContinue(cmd *cobra.Command, args []string) error {
 		return errors.New("no operation in progress")
 	}
 
+	// Determine the correct git instance for rebase operations.
+	// If the conflicting branch is in a linked worktree, operate there.
+	rebaseGit := g
+	wtPath := ""
+	if p, ok := st.Worktrees[st.Current]; ok && p != "" {
+		wtPath = p
+		rebaseGit = git.New(wtPath)
+	}
+
 	// Complete the in-progress rebase
-	if g.IsRebaseInProgress() {
+	if rebaseGit.IsRebaseInProgress() {
 		fmt.Println("Continuing rebase...")
-		if rebaseErr := g.RebaseContinue(); rebaseErr != nil {
+		if rebaseErr := rebaseGit.RebaseContinue(); rebaseErr != nil {
+			if wtPath != "" {
+				return fmt.Errorf("rebase --continue failed in worktree at %s for branch %s; resolve conflicts there first", wtPath, st.Current)
+			}
 			return errors.New("rebase --continue failed; resolve conflicts first")
 		}
 	}
@@ -74,7 +86,7 @@ func runContinue(cmd *cobra.Command, args []string) error {
 		// Remove state file before continuing (will be recreated if conflict)
 		_ = state.Remove(g.GetGitDir()) //nolint:errcheck // cleanup
 
-		if cascadeErr := doCascadeWithState(g, cfg, branches, false, st.Operation, st.UpdateOnly, st.Web, st.PushOnly, st.Branches, st.StashRef, s); cascadeErr != nil {
+		if cascadeErr := doCascadeWithState(g, cfg, branches, false, st.Operation, st.UpdateOnly, st.Web, st.PushOnly, st.Branches, st.StashRef, st.Worktrees, s); cascadeErr != nil {
 			// Stash handling is done by doCascadeWithState (conflict saves in state, errors restore)
 			if !errors.Is(cascadeErr, ErrConflict) && st.StashRef != "" {
 				fmt.Println("Restoring auto-stashed changes...")

cmd/submit.go

@@ -70,7 +70,7 @@ func runSubmit(cmd *cobra.Command, args []string) error {
 		return errors.New("--push-only and --web cannot be used together: --push-only skips all PR operations")
 	}
 	if submitFromFlag != "" && submitCurrentOnlyFlag {
-		return fmt.Errorf("--from and --current-only cannot be used together")
+		return errors.New("--from and --current-only cannot be used together")
 	}
 
 	cwd, err := os.Getwd()
@@ -126,19 +126,20 @@ func runSubmit(cmd *cobra.Command, args []string) error {
 	} else {
 		// Determine the starting node for branch collection
 		var startNode *tree.Node
-		if submitFromFlag == "HEAD" {
+		switch {
+		case submitFromFlag == "HEAD":
 			// --from without value: resolve to current branch (old behavior)
 			startNode = tree.FindNode(root, currentBranch)
 			if startNode == nil {
 				return fmt.Errorf("branch %q is not tracked in the stack\n\nTo add it, run:\n  gh stack adopt %s    # to stack on %s\n  gh stack adopt -p <parent>    # to stack on a different branch", currentBranch, trunk, trunk)
 			}
-		} else if submitFromFlag != "" && submitFromFlag != trunk {
+		case submitFromFlag != "" && submitFromFlag != trunk:
 			// --from=<branch>: use specified branch
 			startNode = tree.FindNode(root, submitFromFlag)
 			if startNode == nil {
 				return fmt.Errorf("branch %q is not tracked in the stack", submitFromFlag)
 			}
-		} else {
+		default:
 			// Default (no --from, or --from=<trunk>): entire stack
 			startNode = root
 		}
@@ -173,7 +174,7 @@ func runSubmit(cmd *cobra.Command, args []string) error {
 
 	// Phase 1: Restack
 	fmt.Println(s.Bold("=== Phase 1: Restack ==="))
-	if cascadeErr := doCascadeWithState(g, cfg, branches, submitDryRunFlag, state.OperationSubmit, submitUpdateOnlyFlag, submitWebFlag, submitPushOnlyFlag, branchNames, stashRef, s); cascadeErr != nil {
+	if cascadeErr := doCascadeWithState(g, cfg, branches, submitDryRunFlag, state.OperationSubmit, submitUpdateOnlyFlag, submitWebFlag, submitPushOnlyFlag, branchNames, stashRef, nil, s); cascadeErr != nil {
 		// Stash is saved in state for conflicts; restore on other errors
 		if !errors.Is(cascadeErr, ErrConflict) && stashRef != "" {
 			fmt.Println("Restoring auto-stashed changes...")

cmd/submit_internal_test.go

@@ -7,6 +7,7 @@
 package cmd
 
 import (
+	"errors"
 	"fmt"
 	"testing"
 )
@@ -285,22 +286,22 @@ func TestIsBaseBranchInvalidError(t *testing.T) {
 		},
 		{
 			name: "unrelated error",
-			err:  fmt.Errorf("network timeout"),
+			err:  errors.New("network timeout"),
 			want: false,
 		},
 		{
 			name: "exact GitHub 422 error",
-			err:  fmt.Errorf("failed to create PR: HTTP 422: Validation Failed (https://api.github.com/repos/owner/repo/pulls)\nPullRequest.base is invalid"),
+			err:  errors.New("failed to create PR: HTTP 422: Validation Failed (https://api.github.com/repos/owner/repo/pulls)\nPullRequest.base is invalid"),
 			want: true,
 		},
 		{
 			name: "short form",
-			err:  fmt.Errorf("base is invalid"),
+			err:  errors.New("base is invalid"),
 			want: true,
 		},
 		{
 			name: "wrapped error",
-			err:  fmt.Errorf("something went wrong: %w", fmt.Errorf("PullRequest.base is invalid")),
+			err:  fmt.Errorf("something went wrong: %w", errors.New("PullRequest.base is invalid")),
 			want: true,
 		},
 	}

cmd/sync.go

@@ -27,11 +27,13 @@ var syncCmd = &cobra.Command{
 var (
 	syncNoCascadeFlag bool
 	syncDryRunFlag    bool
+	syncWorktreesFlag bool
 )
 
 func init() {
 	syncCmd.Flags().BoolVar(&syncNoCascadeFlag, "no-restack", false, "skip restacking branches")
 	syncCmd.Flags().BoolVar(&syncDryRunFlag, "dry-run", false, "show what would be done")
+	syncCmd.Flags().BoolVar(&syncWorktreesFlag, "worktrees", false, "rebase branches checked out in linked worktrees in-place")
 	rootCmd.AddCommand(syncCmd)
 }
 
@@ -348,11 +350,21 @@ func runSync(cmd *cobra.Command, args []string) error {
 			return err
 		}
 
+		// Build worktree map if --worktrees flag is set
+		var worktrees map[string]string
+		if syncWorktreesFlag {
+			var wtErr error
+			worktrees, wtErr = g.ListWorktrees()
+			if wtErr != nil {
+				return fmt.Errorf("failed to list worktrees: %w", wtErr)
+			}
+		}
+
 		// Cascade from trunk's children
 		for _, child := range root.Children {
 			allBranches := []*tree.Node{child}
 			allBranches = append(allBranches, tree.GetDescendants(child)...)
-			if err := doCascadeWithState(g, cfg, allBranches, syncDryRunFlag, state.OperationCascade, false, false, false, nil, stashRef, s); err != nil {
+			if err := doCascadeWithState(g, cfg, allBranches, syncDryRunFlag, state.OperationCascade, false, false, false, nil, stashRef, worktrees, s); err != nil {
 				if errors.Is(err, ErrConflict) {
 					hitConflict = true
 				}