# Git Merge Strategy Configuration

This guide explains how the augint-library template handles configurable merge strategies for pull requests.

## Overview

The merge strategy is configured via the `MERGE_STRATEGY` environment variable in `.env`, allowing projects to switch between different git merge approaches without modifying scripts or documentation.

## Configuration

### Setting the Strategy

In your `.env` file:
```bash
# Git merge strategy for PRs (options: squash, rebase, merge)
MERGE_STRATEGY=squash
```

### Available Options

1. **squash** (default)
   - Combines all commits into a single commit
   - Creates clean, linear history
   - Ideal for: Solo developers, clean changelogs, simple projects
   - Drawback: Poor for `git bisect` debugging

2. **rebase**
   - Preserves individual commits with linear history
   - Excellent for debugging with `git bisect`
   - Ideal for: Teams valuing granular history
   - Drawback: Can create more merge conflicts

3. **merge**
   - Creates merge commits preserving full history
   - Shows complete development timeline
   - Ideal for: Audit trails, complex projects
   - Drawback: Non-linear history can be harder to read

## Changing Strategies

To switch merge strategies:

1. Update `.env`:
   ```bash
   MERGE_STRATEGY=rebase  # Change from squash to rebase
   ```

2. Update GitHub repository settings:
   ```bash
   # Disable old strategy
   gh repo edit --disable-squash-merge

   # Enable new strategy
   gh repo edit --enable-rebase-merge
   ```

3. That's it! All scripts will automatically use the new strategy.

## How It Works

### Script Integration

The `/ai-ship` command reads the strategy:
```bash
# Load merge strategy from .env
if [ -f .env ]; then
    export $(grep MERGE_STRATEGY .env | xargs)
fi
MERGE_STRATEGY=${MERGE_STRATEGY:-squash}

# Use it for auto-merge
gh pr merge --auto --${MERGE_STRATEGY}
```

### Workflow Benefits

- **Single source of truth**: One place to configure
- **Dynamic scripts**: No hardcoded values
- **Easy transitions**: Switch strategies as team grows
- **Template-friendly**: Each project can choose its own strategy

## Best Practices

### For Solo Developers
- Start with `squash` for simplicity
- Clean history, easy reverts
- Switch to `rebase` when debugging becomes important

### For Growing Teams
- Consider `rebase` for better debugging
- Requires commit discipline
- Better `git bisect` effectiveness

### For Enterprise Teams
- Evaluate based on audit requirements
- Consider tooling integration
- May need `merge` for compliance

## Common Scenarios

### Switching from Squash to Rebase

When your project grows and debugging becomes critical:

```bash
# 1. Update .env
sed -i 's/MERGE_STRATEGY=squash/MERGE_STRATEGY=rebase/' .env

# 2. Update GitHub
gh repo edit --disable-squash-merge --enable-rebase-merge

# 3. Communicate to team
echo "Team: We're now using rebase merge. Keep commits clean!"
```

### Temporary Strategy Change

For a complex PR that needs different handling:

```bash
# Manually merge with different strategy
gh pr merge 123 --rebase  # Even if .env says squash
```

## Troubleshooting

### Scripts Using Wrong Strategy

Check that:
1. `.env` has the correct `MERGE_STRATEGY` value
2. GitHub repository has the matching merge method enabled
3. Scripts are reading from the project directory

### Auto-merge Failing

Ensure:
1. The configured strategy is enabled in GitHub settings
2. Branch is up to date (scripts now run `gh pr update-branch`)
3. All required checks are passing

## Related Documentation

- [Git Workflow Agent](../.claude/agents/git-workflow.md)
- [AI Ship Command](../.claude/commands/ai-ship.md)
- [Repository Setup](.github/REPOSITORY_SETUP.md)
