Skip to main content

​
Overview

Git worktrees enable parallel development by creating separate working directories for different branches within the same repository. In Maestro, worktrees are integrated with the Auto Run and batch processing system to allow safe concurrent work without file conflicts.
Git worktrees create isolated workspace directories for different branches, allowing you to run Auto Run on multiple branches simultaneously without conflicts.

​
Prerequisites

1

Install GitHub CLI

Worktree features require the GitHub CLI for branch management and PR creation.
# macOS
brew install gh

# Windows
winget install GitHub.cli

# Linux
sudo apt install gh
2

Authenticate GitHub CLI

Run authentication to enable PR creation features:
gh auth login

​
Configuration

Worktrees are configured in the Batch Runner modal when setting up an Auto Run:

​
Basic Setup

  1. Enable Worktree - Toggle the worktree checkbox
  2. Worktree Directory - Choose a base directory where worktrees will be created
  3. Branch Name - Specify the branch name for this worktree
  4. Computed Path - Review the full path: baseDir/branchName
// Worktree configuration state
worktreeEnabled: boolean
worktreeBaseDir: string        // User-selected base directory  
computedWorktreePath: string   // baseDir + branchName (read-only)
branchName: string
createPROnCompletion: boolean
prTargetBranch: string

​
Validation States

Maestro validates worktree configuration before starting:
✅ Existing worktree on same branch - continues work✅ New worktree location - creates fresh worktree

​
Pull Request Creation

When GitHub CLI is authenticated, you can enable automatic PR creation: 
createPROnCompletion: true
prTargetBranch: 'main'  // Dropdown of available branches
1

Auto Run Completes

Batch processing finishes successfully
2

Changes Committed

All Auto Run changes are committed to the worktree branch
3

Branch Pushed

Worktree branch is pushed to remote
4

PR Created

GitHub PR is created targeting the specified branch

​
Benefits

​
Parallel Development

Run Auto Run on multiple branches simultaneously:
  • Main branch: Production documentation
  • Feature branch: New feature docs via worktree
  • No file conflicts between the two

​
Safe Experimentation

Worktrees provide isolation: 
# Original repo remains untouched
~/projects/my-app/

# Worktree for Auto Run
~/worktrees/docs-update/  # Separate directory, same repo

​
Automated Workflow

Complete workflow from changes to PR:
  1. Configure worktree and branch
  2. Run batch Auto Run
  3. Review generated changes
  4. Automatic commit, push, and PR creation

​
SSH Remote Support

Worktrees work with SSH remote sessions:
For remote sessions, enter the path on the remote server. The Browse button is disabled for SSH remotes.
// Remote session configuration
sshRemoteId: string

// Path on remote server
worktreeBaseDir: '/home/user/worktrees'

​
Example Workflow

1

Open Batch Runner

Select documents for Auto Run batch processing
2

Enable Worktree

✓ Enable Worktree
Directory: /Users/you/worktrees
Branch: feature/update-docs
Computed: /Users/you/worktrees/feature/update-docs
3

Configure PR

✓ Create PR on completion
Target: main
4

Run Batch

Auto Run processes all documents in the worktree
5

Review PR

PR is automatically created with all changes

Build docs developers (and LLMs) love

Get started for freeTalk to us