fix: worktree merge command support

Author: lucatume

README.md

@@ -520,6 +520,33 @@ Or use the `--stack` flag from anywhere:
 slic --stack=/path/to/worktree run wpunit
 ```
 
+#### Merging a Worktree
+
+When you're done working on a feature branch, merge it back and clean up:
+
+```bash
+# From the base stack directory (not the worktree directory)
+slic worktree merge fix/issue-123
+```
+
+**Important:** This command must be run from the base stack directory, not from within the worktree directory being merged. The worktree directory will be removed by git during the merge process.
+
+The merge command will:
+1. Checkout the base branch in the target repository
+2. Merge the worktree branch into the base branch
+3. Remove the git worktree directory
+4. Delete the local worktree branch
+5. Stop Docker containers
+6. Unregister the slic stack
+
+Use `-y` or `--yes` to skip confirmation prompts:
+
+```bash
+slic worktree merge fix/issue-123 -y
+```
+
+If the merge encounters conflicts, the command will stop and provide instructions for manual resolution.
+
 #### Removing a Worktree
 
 To remove a worktree and clean up its slic stack:

slic.md

@@ -175,6 +175,74 @@ As an example, if I wanted to dump the current database contents to the `tests/_
 slic cli db export /plugins/the-events/calendar/tests/_data/dump.sql
 ```
 
+## Git Worktree Support
+
+The stack supports git worktrees with dedicated slic stacks, allowing you to work on multiple branches simultaneously with isolated environments.
+
+### Creating a worktree
+
+Create a new worktree for a feature branch:
+
+```bash
+slic worktree add fix/issue-123
+```
+
+This will:
+- Create a git worktree in a sibling directory
+- Set up a dedicated slic stack for the worktree
+- Allow you to run tests and develop in isolation
+
+### Listing worktrees
+
+View all worktrees and their associated stacks:
+
+```bash
+slic worktree list
+```
+
+### Merging a worktree
+
+When you're done working on a feature branch, merge it back and clean up:
+
+```bash
+# From the base stack directory (not the worktree directory)
+slic worktree merge fix/issue-123
+```
+
+**Important:** This command must be run from the base stack directory, not from within the worktree directory being merged. The worktree directory will be removed by git during the merge process.
+
+The merge command will:
+1. Checkout the base branch in the target repository
+2. Merge the worktree branch into the base branch
+3. Remove the git worktree directory
+4. Delete the local worktree branch
+5. Stop Docker containers
+6. Unregister the slic stack
+
+Use `-y` or `--yes` to skip confirmation prompts:
+
+```bash
+slic worktree merge fix/issue-123 -y
+```
+
+If the merge encounters conflicts, the command will stop and provide instructions for manual resolution.
+
+### Removing a worktree without merging
+
+To remove a worktree without merging its changes:
+
+```bash
+slic worktree remove fix/issue-123
+```
+
+### Synchronizing worktrees
+
+Clean up stale entries when worktrees have been manually removed:
+
+```bash
+slic worktree sync
+```
+
 ## How the stack works, an overview
 
 The stack services are defined by the `slic-stack.yml` file.

src/commands/worktree.php

@@ -1,35 +1,108 @@
 <?php
+/**
+ * Handles the `worktree` command and its subcommands.
+ */
+
 namespace StellarWP\Slic;
 
 // Load worktree utility functions
 require_once __DIR__ . '/../worktree-utils.php';
 
+if ( $is_help ) {
+	$help = <<< HELP
+	SUMMARY:
+
+		Manage git worktrees with dedicated slic stacks.
+
+	USAGE:
+
+		<yellow>{$cli_name} worktree <subcommand> [<args>]</yellow>
+
+	SUBCOMMANDS:
+
+		<light_cyan>add <branch> [-y|--yes]</light_cyan>
+		Create a new git worktree for the specified branch with a dedicated slic stack.
+
+		<light_cyan>list</light_cyan>
+		List all worktrees and their associated slic stacks.
+
+		<light_cyan>merge <branch> [-y|--yes]</light_cyan>
+		Merge worktree branch into base branch and remove the worktree stack.
+		Must be run from the base stack directory, not from within the worktree.
+
+		<light_cyan>remove <branch> [-y|--yes]</light_cyan>
+		Remove a worktree and its associated slic stack.
+
+		<light_cyan>sync</light_cyan>
+		Synchronize git worktrees with slic registry, removing stale entries.
+
+	OPTIONS:
+
+		<light_cyan>-y, --yes</light_cyan>
+		Skip confirmation prompt and proceed immediately. Useful for non-interactive
+		environments like CI pipelines and automation scripts.
+
+	EXAMPLES:
+
+		<light_cyan>{$cli_name} worktree add fix/issue-123</light_cyan>
+		Create a worktree for branch 'fix/issue-123' with a dedicated stack.
+
+		<light_cyan>{$cli_name} worktree add feature/new-feature -y</light_cyan>
+		Create a worktree without confirmation prompt.
+
+		<light_cyan>{$cli_name} worktree list</light_cyan>
+		Show all worktrees and their stacks.
+
+		<light_cyan>{$cli_name} worktree remove fix/issue-123</light_cyan>
+		Remove the worktree for branch 'fix/issue-123' and its stack.
+
+		<light_cyan>{$cli_name} worktree merge fix/issue-123</light_cyan>
+		Merge branch 'fix/issue-123' into base branch and clean up (from base stack directory).
+
+		<light_cyan>{$cli_name} worktree merge fix/issue-123 -y</light_cyan>
+		Merge without confirmation prompt.
+
+		<light_cyan>{$cli_name} worktree sync</light_cyan>
+		Synchronize worktrees with slic registry.
+
+	NOTE:
+
+		slic provides minimal git worktree integration. Use 'git worktree' directly
+		for advanced operations.
+	HELP;
+
+	echo colorize( $help );
+	return;
+}
+
 $worktree_subcommands = [
 	'add' => 'Create a new git worktree with dedicated stack',
 	'list' => 'List worktrees and their stacks',
+	'merge' => 'Merge worktree branch and remove stack',
 	'remove' => 'Remove a worktree and its stack',
 	'sync' => 'Synchronize git worktrees with slic registry',
 ];
 
 // Parse subcommand from args
 $sub_args = args( [ 'subcommand' ], $args( '...' ), 0 );
-$subcommand = $sub_args( 'subcommand', false );
+$wt_subcommand = $sub_args( 'subcommand', false );
 
-if (empty($subcommand)) {
+if (empty($wt_subcommand)) {
 	echo "Git Worktree Support for slic\n\n";
 	echo "Available commands:\n";
 	foreach ($worktree_subcommands as $cmd => $desc) {
 		echo "  slic worktree $cmd - $desc\n";
 	}
 	echo "\nNote: slic provides minimal git worktree integration.\n";
 	echo "Use 'git worktree' directly for advanced operations.\n";
+	echo "\nRun 'slic worktree help' for more information.\n";
 	exit(0);
 }
 
-$subcommand_file = __DIR__ . '/worktree/' . $subcommand . '.php';
+$subcommand_file = __DIR__ . '/worktree/' . $wt_subcommand . '.php';
 
 if (!file_exists($subcommand_file)) {
-	echo "Unknown worktree command: $subcommand\n";
+	echo "Unknown worktree command: $wt_subcommand\n";
 	echo "Run 'slic worktree' to see available commands.\n";
 	exit(1);
 }

src/commands/worktree/add.php

@@ -150,6 +150,9 @@
     }
 }
 
+// Get the base branch before creating the worktree
+$base_branch = trim(shell_exec("git -C " . escapeshellarg($target_full_path) . " rev-parse --abbrev-ref HEAD 2>/dev/null"));
+
 // Execute git worktree add (only if needed)
 if ($should_create_worktree) {
     echo "\nCreating git worktree...\n";
@@ -192,6 +195,7 @@
     'stack_id' => $worktree_stack_id,
     'is_worktree' => true,
     'base_stack_id' => $base_stack_id,
+    'base_branch' => $base_branch,
     'worktree_target' => $target,
     'worktree_dir' => $worktree_dir,
     'worktree_branch' => $branch,