Feat(multi-store users): Deploy theme changes across multiple stores without manual conflict resolution

[lmcrean]

Unique store settings are preserved via configured Git merge drivers.

Problem

Fixes #3509

When working with themes across multiple stores, developers encounter merge conflicts in config/settings_data.json and other configuration files because each store has different settings (store names, payment configs, branding, regional preferences, app configurations).

Problematic workflow (before this fix):

# Work on theme improvements in dev branch
git checkout dev
git commit -m "Add new product grid layout to be used across our stores"

# Deploy to first store - conflicts with Shopify's auto-pushed settings
git checkout red-tie-store
git merge dev  # Conflict! Shopify modified store settings

# Manually resolve conflicts, commit
# Results in conflicts requiring manual resolution:
# <<<<<<< HEAD
# {"store_name": "Red Tie Clothing", "announcement_text": "SALE: 50% off winter coats!"}
# =======
# {"store_name": "Dev Store", "announcement_text": "Test announcement"}
# >>>>>>> dev

# Deploy to second store
git checkout blue-dress-store
git merge dev  # Another conflict! Different store settings. Same time-consuming process again

# Deploy to third store
git checkout green-shoes-store
git merge dev # Another conflict! Manually resolve the SAME type of conflicts again. This is getting painful...

# Repeat for every store... Yellow Store, Purple Store, etc.

Users are forced into the complex separate-branch approach because Shopify's GitHub integration pushes store-specific customizations (made by store admins) back to branches, making a unified single-branch workflow impossible. The result: developers must manually resolve the same settings conflicts repeatedly across multiple stores.

These conflicts require manual resolution every time, which is time-consuming and error-prone.

Solution

Custom Git merge drivers that automatically preserve the current branch's settings during merges:

• Custom Merge Driver: Preserves current branch settings for JSON config files
• Selective Application: Only affects settings files, code files merge normally
• Universal: Works for multiple stores, environments, or any branching strategy
• Git-Native: Uses Git's built-in merge driver system

Usage

# Setup (one time required to avoid merge conflicts)
shopify theme git-setup --multi-environment
git add .gitattributes && git commit -m "Add Git merge config" # preserves branch-specific files during merges 
# e.g. red-tie-store keeps it's store name, branding...

# Verify setup:
shopify theme git-setup --status

# Multi-store workflow (Same commands as before)
git checkout main
git commit -m "Add new product grid layout"

git checkout red-tie-store
git merge main  # No conflicts. Red Store settings automatically preserved

git checkout blue-dress-store
git merge main  # No conflicts. Blue Store settings automatically preserved

git checkout green-shoes-store
git merge main  # No conflicts. Green Store settings automatically preserved

# New layout efficiently pushed across all stores

Note: This solution makes the separate-branch approach work smoothly. While users ideally want a single branch for all stores, our solution makes the current multi-branch reality much more manageable by eliminating manual conflict resolution.

Implementation

New Commands:

• shopify theme git-setup --multi-environment - Configure merge strategies
• shopify theme git-setup --status - Check configuration
• shopify theme git-setup --reset - Remove configuration
• shopify theme git-merge-preserve - Internal merge driver

Files:

• git-setup.ts - CLI command for setup
• git-merge-preserve.ts - Git merge driver
• git-config.ts - Git configuration management
• theme-merge.ts - Custom merge logic

Testing

✅ 53 comprehensive tests covering all functionality
✅ Build, lint, and type checking pass
✅ Manual testing with real Git repositories validates merge preservation

Benefits

• Eliminates manual conflict resolution for store settings files
• Preserves store-specific settings automatically during merges
• Enables confident theme deployment without fear of breaking store configurations
• Backwards compatible - only activates when configured
• Git-native solution using standard merge driver functionality

Future Considerations

• Support for additional file types (deployment configs, robots.txt, store policies)
• Store-specific validation rules and deployment workflows
• Integration with multi-store theme management pipelines

[lmcrean]

it's ready @isaacroldan @amcaplan @gonzaloriestra -- any chance of a review please?