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,11 +41,23 @@ 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 {
-			return errors.New("rebase --continue failed; resolve conflicts first")
+		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 fmt.Errorf("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

@@ -173,7 +173,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/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
 				}

e2e/helpers_test.go

@@ -285,3 +285,64 @@ func (e *TestEnv) AssertAncestor(ancestor, descendant string) {
 		e.t.Errorf("expected %q to be ancestor of %q", ancestor, descendant)
 	}
 }
+
+// CreateWorktree creates a linked worktree for the given branch at the given path.
+func (e *TestEnv) CreateWorktree(branch, wtPath string) {
+	e.t.Helper()
+	cmd := exec.Command("git", "worktree", "add", wtPath, branch)
+	cmd.Dir = e.WorkDir
+	cmd.Env = append(os.Environ(), "GIT_EDITOR=cat")
+	var stderr bytes.Buffer
+	cmd.Stderr = &stderr
+	if err := cmd.Run(); err != nil {
+		e.t.Fatalf("git worktree add %s %s failed: %v\nstderr: %s", wtPath, branch, err, stderr.String())
+	}
+}
+
+// GitInWorktree executes a git command in a worktree directory.
+func (e *TestEnv) GitInWorktree(wtPath string, args ...string) string {
+	e.t.Helper()
+
+	var stdout, stderr bytes.Buffer
+	cmd := exec.Command("git", args...)
+	cmd.Dir = wtPath
+	cmd.Stdout = &stdout
+	cmd.Stderr = &stderr
+	cmd.Env = append(os.Environ(), "GIT_EDITOR=cat")
+
+	if err := cmd.Run(); err != nil {
+		e.t.Fatalf("git (worktree %s) %s failed: %v\nstderr: %s", wtPath, strings.Join(args, " "), err, stderr.String())
+	}
+
+	return strings.TrimSpace(stdout.String())
+}
+
+// RunInDir executes gh-stack in a specific directory (e.g. a worktree).
+func (e *TestEnv) RunInDir(dir string, args ...string) *Result {
+	e.t.Helper()
+
+	var stdout, stderr bytes.Buffer
+	cmd := exec.Command(e.BinaryPath, args...)
+	cmd.Dir = dir
+	cmd.Stdout = &stdout
+	cmd.Stderr = &stderr
+	cmd.Env = append(os.Environ(), "GIT_EDITOR=cat")
+
+	err := cmd.Run()
+
+	result := &Result{
+		Stdout:   stdout.String(),
+		Stderr:   stderr.String(),
+		ExitCode: 0,
+	}
+
+	if err != nil {
+		if exitErr, ok := err.(*exec.ExitError); ok {
+			result.ExitCode = exitErr.ExitCode()
+		} else {
+			e.t.Fatalf("failed to run command in %s: %v", dir, err)
+		}
+	}
+
+	return result
+}