How to Merge Worktree Branches and Resolve Conflicts After Parallel Builds

The AI Website Cloner template manages parallel component builds by isolating each builder in a dedicated Git worktree, then merging branches sequentially with --no-ff flags while enforcing TypeScript validation gates to prevent broken code from reaching the main branch.

The JCodesMore/ai-website-cloner-template repository implements a sophisticated parallel build architecture where independent agents generate website components in isolated Git worktrees. After builders complete their tasks, you must merge these temporary branches back into the main repository using a deterministic workflow that prevents conflicts and ensures type safety. This guide covers the exact merge strategy and conflict resolution process defined in the repository's source files.

Understanding the Worktree Isolation Strategy

The repository leverages Git worktrees to eliminate filesystem conflicts during simultaneous builds. According to the README.md parallel build section, each builder agent receives its own isolated workspace where it can modify files without interfering with other running agents.

Creating Isolated Build Environments

When the pipeline initiates a parallel build, it executes:

git worktree add -b feature/header ./worktrees/header-builder

This command creates a new branch (feature/header) and a linked working directory (./worktrees/header-builder) separate from the main repository. Builders operate entirely within these sandboxes, ensuring that simultaneous modifications to shared utilities never cause race conditions or dirty working tree states.

Pre-Merge Type-Checking Gates

Before any worktree branch qualifies for merging, the builder must pass a strict validation step. As documented in README.md at lines 93-94, each worktree must successfully run:

npx tsc --noEmit

This TypeScript check acts as a hard gate—if the compiler exits with errors, the worktree branch cannot proceed to the merge phase, preventing broken type definitions from corrupting the main build.

Step-by-Step Worktree Branch Merging

Prepare the Target Branch

Begin by ensuring the main branch contains the latest upstream changes:

git checkout main
git pull origin main

This guarantees a clean base state before introducing worktree changes.

Execute Sequential Merges

The repository mandates a non-fast-forward merge strategy to preserve the history of each builder's contribution. As noted in AGENTS.md at line 60, merge each worktree branch using:

git merge --no-ff feature/header
git merge --no-ff feature/footer

# Repeat for each worktree branch

The --no-ff flag forces Git to create a merge commit even when a fast-forward is possible, maintaining a clear audit trail of which components entered the codebase at specific integration points.

Handle Cross-Component Conflicts

While worktrees isolate file changes, UI components often share utility files or design tokens. When git merge reports conflicts:

1. Open the conflicted files and identify overlapping regions
2. Preserve the component-specific changes while maintaining API compatibility
3. Re-run the type-checking gate: npx tsc --noEmit
4. Stage resolved files and complete the merge commit

This proactive resolution prevents "merge hell" scenarios where conflicting TypeScript types propagate undetected into the main branch.

Post-Merge Validation and Cleanup

Full Build Verification

After merging all worktree branches, validate the combined output using the repository's QA pipeline commands:

npm run build
npm run check

The npm run check command (defined in package.json) runs linting, type-checking, and build verification to ensure the merged components integrate correctly without visual regressions.

Remove Temporary Worktrees

Once validation passes, eliminate the temporary directories to prevent stale refs and disk space accumulation:

git worktree remove ./worktrees/header-builder
git worktree prune

The prune command cleans up the Git metadata associated with removed worktrees, keeping the repository lean.

Automation and CI Integration

The repository provides helper scripts to standardize these workflows. The scripts/sync-agent-rules.sh file regenerates platform-specific agent configurations after merges, ensuring documentation remains synchronized with the current codebase.

Additionally, the .github/workflows/ci.yml pipeline automatically runs npm run check on every pull request, acting as a final safety net that prevents merges breaking the build from entering the main branch.

Summary

• Git worktrees provide filesystem isolation for parallel builder agents, with each component receiving its own branch and working directory
• Type-checking gates (npx tsc --noEmit) must pass before any worktree branch qualifies for merging back into the main repository
• Non-fast-forward merges (--no-ff) preserve the history of each builder's contribution and create explicit integration points
• Conflict resolution requires re-running TypeScript validation after fixing overlapping changes to shared utilities
• Cleanup procedures using git worktree remove and prune prevent repository bloat and stale reference accumulation

Frequently Asked Questions

What is a Git worktree and why does the template use it for parallel builds?

A Git worktree creates a separate linked working directory for a specific branch, allowing multiple branches to exist simultaneously on disk without switching contexts. The AI Website Cloner template uses worktrees to let builder agents run concurrently—each agent checks out a component-specific branch in its own directory, preventing file locking and overwrite conflicts that would occur if all builders shared a single working tree.

How should I resolve conflicts when multiple worktrees modify shared utilities?

When merging worktree branches reveals conflicts in shared utility files, resolve them by prioritizing the component specification changes while maintaining API compatibility. After editing the conflicted files, you must re-run npx tsc --noEmit to verify the resolution doesn't introduce type errors, then stage the files and complete the merge commit before proceeding to the next worktree branch.

Why does the repository require the --no-ff flag for merges?

The --no-ff (no fast-forward) flag ensures Git creates a dedicated merge commit even when the branch history could be linearized. As implemented in the repository's workflow, this preserves the complete history of each builder agent's contribution, making it possible to identify which specific component introduced changes or regressions during the parallel build process.

What happens if type-checking fails during the merge process?

If npx tsc --noEmit exits with errors during the pre-merge verification or conflict resolution phase, the merge cannot proceed. The TypeScript compiler acts as a mandatory quality gate—branches with type errors must be fixed in their respective worktrees before attempting to merge again, ensuring the main branch never contains uncompilable code that would break the npm run build command.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}