feat: add automatic stashing to sync command to protect all local files

Previously, running 'arbor sync' could result in untracked and ignored files
being deleted when they conflicted with files in the upstream branch. This was
particularly problematic for files like .env.testing and modified copies of
tracked files like phpunit.parallel.xml.

This commit adds automatic stashing of ALL changes (tracked modifications,
untracked files, and ignored files) before sync operations, then automatically
restores them after a successful sync.

Changes:
- Add git stash utilities (StashAll, PopStash, HasStash, HasChanges)
- Integrate auto-stashing into sync command (enabled by default)
- Add --no-auto-stash flag to opt out
- Add sync.auto_stash config option
- Handle stash conflicts gracefully with helpful error messages
- Preserve stash on sync failure with recovery instructions
- Add comprehensive tests for stash operations
- Update documentation with auto-stash details

Benefits:
- No more lost untracked/ignored files during sync
- No manual stashing required
- Safe by default, with opt-out available
- Clear error messages when conflicts occur

Author: michaeldyrynda

README.md

@@ -122,8 +122,17 @@ See [AGENTS.md](./AGENTS.md) for development guide.
 
 Synchronizes the current worktree branch with an upstream branch by fetching the latest changes and rebasing or merging.
 
+**Auto-Stashing (Default):**
+
+By default, `arbor sync` automatically stashes **all** changes before syncing, including:
+- Tracked modifications
+- Untracked files
+- Ignored files (like `.env`, `.env.testing`)
+
+This ensures your local changes are preserved even if they conflict with files in the upstream branch. After a successful sync, the stashed changes are automatically restored.
+
 ```bash
-# Sync with default settings (upstream: main, strategy: rebase)
+# Sync with default settings (upstream: main, strategy: rebase, auto-stash: on)
 arbor sync
 
 # Sync with a specific upstream branch
@@ -138,6 +147,9 @@ arbor sync -s merge
 arbor sync --remote upstream
 arbor sync -r upstream
 
+# Disable auto-stashing (not recommended)
+arbor sync --no-auto-stash
+
 # Skip all confirmations
 arbor sync --yes
 arbor sync -y
@@ -158,18 +170,20 @@ sync:
   upstream: main
   strategy: rebase
   remote: origin
+  auto_stash: true  # Default: true, set to false to disable
 ```
 
 The command resolves settings in this order:
-1. CLI flags (`--upstream`, `--strategy`, `--remote`)
+1. CLI flags (`--upstream`, `--strategy`, `--remote`, `--no-auto-stash`)
 2. Project config (`arbor.yaml`)
 3. Project `default_branch`
 4. Interactive selection (if in interactive mode)
 
 **Notes:**
 - Must be run from within a worktree (not project root)
 - Fails if worktree is on detached HEAD
-- Warns if worktree has uncommitted changes
+- Auto-stashes all changes by default (can be disabled with `--no-auto-stash`)
+- If stash pop fails due to conflicts, the stash is preserved and instructions are provided
 - Detects and blocks if rebase or merge is already in progress
 - Provides guidance when conflicts occur
 

internal/cli/sync.go

@@ -17,8 +17,13 @@ var syncCmd = &cobra.Command{
 fetching the latest changes and rebasing or merging.
 
 The command will:
-1. Fetch updates from the remote
-2. Rebase (default) or merge the current branch with upstream changes
+1. Auto-stash all changes (tracked, untracked, and ignored files) by default
+2. Fetch updates from the remote
+3. Rebase (default) or merge the current branch with upstream changes
+4. Restore stashed changes after successful sync
+
+Auto-stashing can be disabled with --no-auto-stash flag or by setting
+sync.auto_stash: false in arbor.yaml.
 
 Configuration can be set via flags, project config (arbor.yaml), or interactively.`,
 	RunE: func(cmd *cobra.Command, args []string) error {
@@ -40,6 +45,7 @@ Configuration can be set via flags, project config (arbor.yaml), or interactivel
 		remoteFlag := mustGetString(cmd, "remote")
 		saveFlag := mustGetBool(cmd, "save")
 		yesFlag := mustGetBool(cmd, "yes")
+		noAutoStashFlag := mustGetBool(cmd, "no-auto-stash")
 
 		// Get current branch
 		currentBranch, err := git.GetCurrentBranch(pc.CWD)
@@ -64,17 +70,48 @@ Configuration can be set via flags, project config (arbor.yaml), or interactivel
 			return fmt.Errorf("merge in progress - resolve conflicts, stage changes, and commit, or run 'git merge --abort' to cancel")
 		}
 
-		// Check for dirty worktree
-		isDirty, err := git.IsWorktreeDirty(pc.CWD)
+		// Determine if auto-stash should be used
+		// Priority: CLI flag > config > default (true)
+		autoStash := true
+		if noAutoStashFlag {
+			autoStash = false
+		} else if pc.Config.Sync.AutoStash != nil {
+			autoStash = *pc.Config.Sync.AutoStash
+		}
+
+		// Check for any changes (tracked, untracked, ignored)
+		hasChanges, err := git.HasChanges(pc.CWD)
 		if err != nil {
-			return fmt.Errorf("checking worktree status: %w", err)
+			return fmt.Errorf("checking for changes: %w", err)
 		}
-		if isDirty {
+
+		// Track whether we created a stash so we can pop it later
+		var stashCreated bool
+
+		if hasChanges && autoStash {
 			if !quiet {
-				ui.PrintInfo("Warning: worktree has uncommitted changes")
+				ui.PrintInfo("Auto-stashing all changes (tracked, untracked, and ignored files)...")
+			}
+
+			if !dryRun {
+				if err := git.StashAll(pc.CWD, "arbor sync auto-stash"); err != nil {
+					return fmt.Errorf("failed to stash changes: %w", err)
+				}
+				stashCreated = true
+				if !quiet {
+					ui.PrintSuccess("Changes stashed successfully")
+				}
+			} else {
+				ui.PrintInfo("[DRY RUN] Would stash all changes")
+			}
+		} else if hasChanges && !autoStash {
+			// Auto-stash disabled but there are changes - warn the user
+			if !quiet {
+				ui.PrintWarning("Warning: worktree has changes (auto-stash is disabled)")
+				ui.PrintInfo("Untracked files that conflict with upstream may be lost")
 			}
 			if !yesFlag && ui.IsInteractive() {
-				confirmed, err := ui.Confirm("Continue with uncommitted changes?")
+				confirmed, err := ui.Confirm("Continue without stashing changes?")
 				if err != nil {
 					return err
 				}
@@ -204,13 +241,45 @@ Configuration can be set via flags, project config (arbor.yaml), or interactivel
 		}
 
 		if syncErr != nil {
+			// Leave stash intact on sync failure
+			if stashCreated && !quiet {
+				ui.PrintInfo("\nYour changes are preserved in the stash.")
+				ui.PrintInfo("After fixing the issue, run 'git stash pop' to restore them.")
+			}
 			return syncErr
 		}
 
 		if !quiet {
 			ui.PrintSuccess(fmt.Sprintf("Successfully synced with %s/%s using %s", remote, upstream, strategy))
 		}
 
+		// Pop the stash after successful sync
+		if stashCreated && !dryRun {
+			if verbose && !quiet {
+				ui.PrintInfo("Restoring stashed changes...")
+			}
+
+			popErr := git.PopStash(pc.CWD)
+			if popErr != nil {
+				// Check if it's a conflict error
+				if _, isConflict := popErr.(*git.StashConflictError); isConflict {
+					ui.PrintWarning("\nWarning: Could not automatically restore stashed changes due to conflicts")
+					ui.PrintInfo("\nYour changes have been safely preserved in the stash.")
+					ui.PrintInfo("To restore them, resolve conflicts and run:")
+					ui.PrintInfo("  git stash pop")
+					ui.PrintInfo("\nTo discard the stash:")
+					ui.PrintInfo("  git stash drop")
+				} else {
+					ui.PrintWarning(fmt.Sprintf("\nWarning: Failed to restore stashed changes: %v", popErr))
+					ui.PrintInfo("Your changes are still in the stash. Run 'git stash pop' to restore them manually.")
+				}
+			} else {
+				if !quiet {
+					ui.PrintSuccess("Stashed changes restored successfully")
+				}
+			}
+		}
+
 		// Save config if requested
 		shouldSave := saveFlag
 		if !saveFlag && shouldPrompt {
@@ -250,4 +319,5 @@ func init() {
 	syncCmd.Flags().StringP("remote", "r", "", "Remote name to fetch from (default: origin)")
 	syncCmd.Flags().Bool("save", false, "Persist sync settings to arbor.yaml")
 	syncCmd.Flags().BoolP("yes", "y", false, "Skip confirmations and run with chosen values")
+	syncCmd.Flags().Bool("no-auto-stash", false, "Disable automatic stashing of all changes before sync")
 }

internal/config/config.go

@@ -46,9 +46,10 @@ type Config struct {
 
 // SyncConfig represents sync configuration for the sync command
 type SyncConfig struct {
-	Upstream string `mapstructure:"upstream"`
-	Strategy string `mapstructure:"strategy"`
-	Remote   string `mapstructure:"remote"`
+	Upstream  string `mapstructure:"upstream"`
+	Strategy  string `mapstructure:"strategy"`
+	Remote    string `mapstructure:"remote"`
+	AutoStash *bool  `mapstructure:"auto_stash"` // Pointer to distinguish between unset and false
 }
 
 // PreFlight defines checks that run before scaffold execution.
@@ -374,7 +375,7 @@ func SaveProject(path string, config *Config) error {
 	}
 
 	// Update sync config if any values are set
-	if config.Sync.Upstream != "" || config.Sync.Strategy != "" || config.Sync.Remote != "" {
+	if config.Sync.Upstream != "" || config.Sync.Strategy != "" || config.Sync.Remote != "" || config.Sync.AutoStash != nil {
 		syncValues := make(map[string]interface{})
 		if config.Sync.Upstream != "" {
 			syncValues["upstream"] = config.Sync.Upstream
@@ -385,7 +386,10 @@ func SaveProject(path string, config *Config) error {
 		if config.Sync.Remote != "" {
 			syncValues["remote"] = config.Sync.Remote
 		}
-		setNestedValue("sync", syncValues, []string{"upstream", "strategy", "remote"})
+		if config.Sync.AutoStash != nil {
+			syncValues["auto_stash"] = *config.Sync.AutoStash
+		}
+		setNestedValue("sync", syncValues, []string{"upstream", "strategy", "remote", "auto_stash"})
 	}
 
 	content, err := yaml.Marshal(doc)

internal/git/stash.go

@@ -0,0 +1,71 @@
+package git
+
+import (
+	"fmt"
+	"os/exec"
+	"strings"
+)
+
+// StashAll creates a stash including untracked and ignored files
+// This captures tracked modifications, untracked files, and ignored files
+func StashAll(worktreePath string, message string) error {
+	cmd := exec.Command("git", "-C", worktreePath, "stash", "push", "--include-untracked", "--all", "-m", message)
+	output, err := cmd.CombinedOutput()
+	if err != nil {
+		outputStr := string(output)
+		// Check if the error is because there's nothing to stash
+		if strings.Contains(outputStr, "No local changes to save") {
+			return nil // Not an error, just nothing to stash
+		}
+		return fmt.Errorf("git stash failed: %w\n%s", err, outputStr)
+	}
+	return nil
+}
+
+// PopStash pops the most recent stash
+// Returns an error if there are conflicts or if the pop fails
+func PopStash(worktreePath string) error {
+	cmd := exec.Command("git", "-C", worktreePath, "stash", "pop")
+	output, err := cmd.CombinedOutput()
+	if err != nil {
+		outputStr := string(output)
+		// Check if it's a conflict error
+		if strings.Contains(outputStr, "CONFLICT") || strings.Contains(outputStr, "conflict") {
+			return &StashConflictError{Output: outputStr}
+		}
+		return fmt.Errorf("git stash pop failed: %w\n%s", err, outputStr)
+	}
+	return nil
+}
+
+// HasStash checks if there are any stashes in the repository
+func HasStash(worktreePath string) (bool, error) {
+	cmd := exec.Command("git", "-C", worktreePath, "stash", "list")
+	output, err := cmd.Output()
+	if err != nil {
+		return false, fmt.Errorf("checking stash list: %w", err)
+	}
+	return len(strings.TrimSpace(string(output))) > 0, nil
+}
+
+// HasChanges checks if there are any changes that would be captured by stash
+// This includes tracked modifications, untracked files, and ignored files
+func HasChanges(worktreePath string) (bool, error) {
+	// Check for any files in working tree (tracked, untracked, ignored)
+	// Using --ignored to also check ignored files
+	cmd := exec.Command("git", "-C", worktreePath, "status", "--porcelain", "--ignored")
+	output, err := cmd.Output()
+	if err != nil {
+		return false, fmt.Errorf("checking for changes: %w", err)
+	}
+	return len(strings.TrimSpace(string(output))) > 0, nil
+}
+
+// StashConflictError represents a stash pop that failed due to conflicts
+type StashConflictError struct {
+	Output string
+}
+
+func (e *StashConflictError) Error() string {
+	return fmt.Sprintf("stash pop has conflicts:\n%s\n\nResolve the conflicts, stage the changes with 'git add', then run 'git stash drop' to remove the stash, or run 'git reset --hard && git stash pop' to try again", e.Output)
+}