Git Merge Strategies — The 'Wrong' Strategy Caused Silent Data Loss

Most developers never think about merge strategies. Git's default 'ort' strategy handles 99% of merges automatically. But when it gets the 1% wrong, the results are silent and catastrophic: files that disappear without a conflict, renamed code that's treated as deleted and recreated, and merge commits that look clean but contain wrong code. The incident that triggered this guide: a team lost 40 renamed files because the default strategy didn't detect the renames. This guide covers when to override the default, the strategy options Git provides, and how to prevent silent merge corruption.

Why Merge Strategies Matter in Production

In production Git workflows, merge strategy selection directly impacts code stability, history clarity, and rollback safety. A naive git merge can produce conflicts that break builds or introduce subtle bugs. Git offers multiple strategies—recursive, ours, theirs, and octopus—each designed for specific scenarios. Understanding when to use each prevents common failures like unintended overwrites, merge commit pollution, or broken multi-branch integrations. This article dissects each strategy with production-grade examples, focusing on real failure modes and best practices.

#!/bin/bash
# Check current merge strategy configuration
git config --get merge.ff || echo "No ff config"
git config --get merge.strategy || echo "No strategy config"

Recursive Strategy: The Workhorse

The recursive strategy is Git's default for non-fast-forward merges. It performs a three-way merge using the common ancestor and two branch tips. When conflicts occur, it recursively merges the common ancestors to find a better base. This strategy handles criss-cross merge histories well. In production, recursive is safe for most feature branch merges, but it can produce complex conflict markers when multiple developers modify the same files. Use git merge -s recursive explicitly only when you need to set options like patience or diff-algorithm.

#!/bin/bash
# Simulate a recursive merge with conflict
git init recursive-demo
cd recursive-demo
echo "initial" > file.txt
git add file.txt && git commit -m "initial"
git checkout -b feature
echo "feature change" >> file.txt
git add file.txt && git commit -m "feature"
git checkout main
echo "main change" >> file.txt
git add file.txt && git commit -m "main"
# Merge using recursive strategy
git merge -s recursive feature 2>&1 || echo "Conflict expected"

Ours Strategy: Keep Your Version

The ours strategy resolves conflicts by automatically choosing the current branch's version. It does not look at the other branch's changes—it simply ignores them for conflicting files. This is useful when you want to merge a branch but discard its changes entirely, e.g., merging a hotfix branch that was already applied differently. However, it can be dangerous: if the other branch has important changes in non-conflicting files, those are still merged. Use git merge -s ours sparingly and only when you are certain the incoming changes are unwanted.

#!/bin/bash
# Demonstrate ours strategy
git init ours-demo
cd ours-demo
echo "main version" > conflict.txt
git add conflict.txt && git commit -m "main"
git checkout -b feature
echo "feature version" > conflict.txt
git add conflict.txt && git commit -m "feature"
git checkout main
git merge -s ours feature
echo "After ours merge:"
cat conflict.txt

Theirs Strategy: Accept Incoming Changes

The theirs strategy is the inverse of ours: it automatically resolves conflicts by taking the other branch's version. This is useful when you want to overwrite your branch with upstream changes, e.g., syncing a long-lived feature branch with main. However, it can silently discard your branch's changes. In production, theirs is often used in automated merge scripts where you trust the incoming branch. Be cautious: it can introduce regressions if the other branch has untested changes.

#!/bin/bash
# Demonstrate theirs strategy
git init theirs-demo
cd theirs-demo
echo "main version" > conflict.txt
git add conflict.txt && git commit -m "main"
git checkout -b feature
echo "feature version" > conflict.txt
git add conflict.txt && git commit -m "feature"
git checkout main
git merge -X theirs feature 2>&1 || true
echo "After theirs merge:"
cat conflict.txt

Octopus Strategy: Multi-Branch Merges

The octopus strategy merges more than two branches at once. It is designed for cases where you want to combine several topic branches into a single merge commit. Octopus works best when there are no conflicts—it refuses to proceed if conflicts exist. In production, octopus is rarely used because it creates complex history and is hard to debug. It can be useful for merging multiple hotfixes that are known to be conflict-free. Use git merge -s octopus only when you are certain of no conflicts.

#!/bin/bash
# Demonstrate octopus merge
git init octopus-demo
cd octopus-demo
echo "base" > file.txt
git add file.txt && git commit -m "base"
git checkout -b feature1
echo "feature1" >> file.txt
git add file.txt && git commit -m "f1"
git checkout main
git checkout -b feature2
echo "feature2" >> file.txt
git add file.txt && git commit -m "f2"
git checkout main
git merge -s octopus feature1 feature2 2>&1 || echo "Octopus failed due to conflicts"

Recursive Options: Patience, Histogram, and More

The recursive strategy supports options that change conflict resolution behavior. patience uses a patience diff algorithm that produces cleaner diffs for code with many repeated lines. histogram is similar but often faster. diff-algorithm=patience can reduce false conflicts in refactored code. In production, these options help when recursive merges produce messy conflicts. Use git merge -s recursive -X patience to enable. However, they are not silver bullets—complex conflicts still require manual resolution.

#!/bin/bash
# Compare default vs patience merge
git init options-demo
cd options-demo
echo -e "function a() {\n  return 1;\n}\nfunction b() {\n  return 2;\n}" > code.js
git add code.js && git commit -m "base"
git checkout -b refactor
# Simulate refactor that reorders functions
cat > code.js << 'EOF'
function b() {
  return 2;
}
function a() {
  return 1;
}
EOF
git add code.js && git commit -m "refactor"
git checkout main
echo -e "function a() {\n  return 10;\n}\nfunction b() {\n  return 2;\n}" > code.js
git add code.js && git commit -m "main change"
echo "Default recursive merge:"
git merge -s recursive refactor 2>&1 || true
git merge --abort 2>/dev/null
echo "Patience merge:"
git merge -s recursive -X patience refactor 2>&1 || true

Subtree Strategy: Merging Subprojects

The subtree strategy is a variant of recursive that merges one repository into a subdirectory of another. It is useful for managing dependencies or shared libraries within a monorepo. Unlike submodules, subtree merges keep the history of the merged project. In production, subtree merges can become complex if the upstream project changes frequently. Use git merge -s subtree with caution—it can lead to large merge commits and history bloat.

#!/bin/bash
# Demonstrate subtree merge
git init main-repo
cd main-repo
echo "main project" > README.md
git add README.md && git commit -m "initial"
git remote add lib ../lib-repo 2>/dev/null || true
git fetch lib 2>/dev/null || true
git merge -s subtree --prefix=lib/ lib/main 2>&1 || echo "Subtree merge requires a valid remote"

Choosing the Right Strategy for Your Workflow

Selecting a merge strategy depends on your team's workflow and history structure. For feature branches, recursive is standard. Use ours or theirs for specific override scenarios. Octopus is for rare multi-branch merges. Subtree is for vendoring. In production, prefer explicit strategy selection over defaults when the default behavior is not ideal. Document your strategy choices in your contributing guidelines. Avoid using ours or theirs in automated merges without review—they can silently introduce bugs.

#!/bin/bash
# Decision helper
echo "Select strategy:"
echo "1) Recursive (default)"
echo "2) Ours (keep current)"
echo "3) Theirs (accept incoming)"
echo "4) Octopus (multi-branch)"
read -p "Enter choice: " choice
case $choice in
  1) echo "git merge -s recursive" ;;
  2) echo "git merge -s ours" ;;
  3) echo "git merge -s recursive -X theirs" ;;
  4) echo "git merge -s octopus branch1 branch2" ;;
  *) echo "Invalid" ;;
esac

Common Pitfalls and How to Avoid Them

Common pitfalls include: using ours when you meant theirs, forgetting to abort a failed octopus merge, and relying on recursive options to fix all conflicts. In production, a bad merge can cause silent data corruption. Always verify merge results with git diff and run tests. Use git merge --no-commit to review changes before committing. For automated merges, add a CI step that checks for conflict markers. Avoid merging large branches—break them into smaller, more frequent merges.

#!/bin/bash
# Safe merge workflow
git merge --no-commit --no-ff feature
if git diff --check | grep -q 'conflict'; then
  echo "Conflicts detected, aborting"
  git merge --abort
  exit 1
fi
git commit -m "Merge feature after review"

Advanced: Custom Merge Drivers

For complex scenarios, you can define custom merge drivers in .gitattributes. These allow you to specify how certain files are merged, e.g., always take one side for generated files. Custom drivers can call external scripts. In production, they are useful for lock files, compiled assets, or configuration files that should never be merged automatically. However, they add complexity and must be maintained. Use sparingly and document thoroughly.

#!/bin/bash
# Setup custom merge driver for package-lock.json
git config merge.ours.driver "keep-ours.sh %O %A %B"
echo "package-lock.json merge=ours" >> .gitattributes
cat > keep-ours.sh << 'EOF'
#!/bin/bash
# Always keep our version
cp $2 $1
exit 0
EOF
chmod +x keep-ours.sh

Testing Merge Strategies in CI/CD

In CI/CD, merge strategies can be tested by simulating merges in a temporary branch. Use git merge --no-commit to test for conflicts without creating a merge commit. If conflicts occur, the pipeline can fail early. For automated merges, prefer recursive with -X theirs for trusted branches, but always run a full test suite. In production, we use a merge validation step that checks for conflict markers and runs linting before allowing the merge.

jobs:
  merge-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
        with:
          fetch-depth: 0
      - name: Test merge
        run: |
          git checkout main
          git merge --no-commit --no-ff ${{ github.head_ref }} || true
          if git diff --check | grep -q 'conflict'; then
            echo "Merge conflicts detected"
            exit 1
          fi
          git merge --abort

Summary: Production Best Practices

In production, prefer recursive for most merges. Use ours or theirs only when you explicitly want to discard or accept changes. Avoid octopus unless you are certain of no conflicts. Document your strategy choices and train your team. Always review merge diffs and run tests. Use custom drivers sparingly. Remember: no strategy replaces good communication and small, frequent merges. The goal is a clean, traceable history that supports quick rollbacks.

#!/bin/bash
# Production merge checklist
echo "1. Choose strategy based on scenario"
echo "2. Use --no-commit to review"
echo "3. Run full test suite"
echo "4. Verify with git diff"
echo "5. Commit with descriptive message"