git-reconciler

Git Reconciler

Skill to safely sync your working branch with main/master, detecting conflicts before merging.

Process

Step 1: Check current status

git status
git branch --show-current
git status --porcelain

IMPORTANT: If there are uncommitted changes, ask the user:

• Do you want to commit first?
• Do you want to stash?
• Do you want to discard changes?

Step 2: Identify main branch

# Detectar si es main o master (local, sin network call)
git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@'

If it fails (HEAD not set):

git branch -r | grep -E "origin/(main|master)$" | head -1 | sed 's/.*origin\///'

Step 3: Fetch remote changes

git fetch origin main  # o master segun detectado

Step 4: Analyze divergence

# Commits en main que no estan en tu branch
git log HEAD..origin/main --oneline

# Commits en tu branch que no estan en main
git log origin/main..HEAD --oneline

# Ver cuanto divergieron
git rev-list --left-right --count origin/main...HEAD

The output of rev-list is: <commits_en_main> <commits_en_branch>

Interpret:

• 0 0 = Synced, there is nothing to do
• 5 0 = Main has 5 new commits, your branch is behind
• 0 3 = Your branch has 3 commits, main has no new ones (only push needed)
• 5 3 = Divergence: main has 5 new ones, your branch has 3

Step 5: Detect potential conflicts

# Archivos modificados en main desde que divergieron
git diff --name-only HEAD...origin/main

# Archivos modificados en tu branch
git diff --name-only origin/main...HEAD

Compare the lists. If there are files in common, there is a risk of conflict.

To check for conflicts without merging (Git 2.38+):

git merge-tree --write-tree HEAD origin/main

A non-zero exit code indicates conflicts. Legacy alternative:

git merge-tree $(git merge-base HEAD origin/main) HEAD origin/main

If the output contains <<<<<< or >>>>>>, there will be conflicts.

Step 6: Suggest strategy

Present to the user:

Option A: Merge (recommended for shared branches)

git merge origin/main

• Preserves full history
• Creates a merge commit
• Safer for branches with collaborators

Option B: Rebase (recommended for personal branches)

git rebase origin/main

• Linear history
• Rewrites commits (requires force push if you already pushed)
• Better for clean branches before a PR

Question:

Estrategia recomendada: [merge/rebase] porque [razon].
Cual preferis? [merge/rebase]

Step 7: Execute synchronization

If MERGE was chosen:

git merge origin/main

If REBASE was chosen:

git rebase origin/main

Step 8: Handle conflicts (if they occur)

If there are conflicts, list them:

git diff --name-only --diff-filter=U

Show the user:

Hay conflictos en los siguientes archivos:
- <archivo1>
- <archivo2>

Opciones:
1. Resolver conflictos manualmente (te guio archivo por archivo)
2. Abortar merge: git merge --abort
3. Abortar rebase: git rebase --abort

For each file with a conflict:

git diff <archivo>

Step 9: Verify result

git status
git log --oneline -5

---

Worktree Support

If the user works with worktrees (pattern .worktrees/):

Detect if we are in a worktree

git rev-parse --is-inside-work-tree
git worktree list

Special considerations for worktrees

1. The main/master is usually in the main repo, not in the worktree
2. Fetch from the worktree works the same
3. Rebase can be problematic if the worktree shares objects

Workflow for worktree:

pwd  # Verificar que estamos en .worktrees/<branch>
git fetch origin main
git merge origin/main

---

For detailed examples, read references/examples.md. For a quick command table, read references/quick-ref.md.