git-sync-failure-diagnosis

name	git-sync-failure-diagnosis
description	Diagnose and report git synchronization failures when standard pull/fetch operations fail, particularly in automated/cron contexts where the repository may have network connectivity issues. Trigger keywords: git pull timeout, git fetch failed, sync failure, cron git error, ahead behind diverged, ls-remote diagnose.
license	MIT
metadata	{"version":"1.0.0","hermes":{"tags":["Git","Sync","Network","Timeout","Diagnosis","Automation","Cron"],"related_skills":["git-limited-history-analysis"]}}

Git Sync Failure Diagnosis

When git pull/git fetch times out or fails, especially in cron, diagnose without retrying indefinitely.

1. Local state baseline

cd <repo-path>
git status --porcelain
git rev-parse HEAD
git branch --show-current

2. Lightweight remote test

git ls-remote --heads origin 2>&1 | head -5

ls-remote is much lighter than fetch and often succeeds when fetch times out. It confirms network path, daemon health, and auth.

3. Determine commit relationship

# After getting remote SHA from ls-remote output:
git merge-base --is-ancestor <local-sha> <remote-sha> \
  && echo "local is ancestor (behind)" \
  || echo "local is NOT ancestor (ahead or diverged)"

4. Alternative fetch strategies

If standard fetch fails, constrain it:

# Aggressive timeouts + shallow
GIT_HTTP_LOW_SPEED_LIMIT=1000 GIT_HTTP_LOW_SPEED_TIME=10 \
  git fetch origin <branch> --no-tags --depth=1

# Hard timeout wrapper
timeout 90 git fetch origin --depth=1 --no-tags --no-recurse-submodules

5. Final state

git rev-parse origin/<branch>
git log --oneline <remote-sha>..HEAD 2>/dev/null \
  || echo "Cannot compare — remote commit not fetched"

Reporting

Always report: local state (branch, HEAD, working tree), remote state (URL, HEAD via ls-remote, reachability), relationship (ahead/behind/diverged/unknown), commands attempted with results, recommended next steps.

Common Patterns

Symptom	Likely Cause	Action
ls-remote works, fetch times out	Large repo / slow connection	--depth=1 shallow fetch
Both fail	Network/firewall	VPN, proxy, retry later
Local ahead	Unpushed commits	Push when connectivity restored
Remote ahead	Needs pull	pull --rebase when restored

Edge Case: Pull Timeout but Operation Succeeded

A git pull --rebase may complete server-side then the connection hangs before returning:

$ git pull --rebase
[Command timed out]

$ git status
Your branch is ahead of 'origin/master' by 4 commits.
nothing to commit, working tree clean

The rebase succeeded; only the connection died. Always verify state after a timeout before retrying:

git status
git log --oneline -3

Edge Case: Push Rejected After Successful Pull

$ git push
! [rejected] master -> master (fetch first)

Remote changed mid-operation. Pull again. If pull keeps timing out: report state, don't loop indefinitely; offer wait-and-retry vs force-push (only if appropriate).

Edge Case: File Modified but Won't Stage

If git status shows a file modified but git add -A doesn't clear it:

$ git status --short
 M "path/to/file with spaces.md"

$ git add -A
$ git status --short
 M "path/to/file with spaces.md"   # still modified

Likely causes: file moved+modified in same session, filename encoding (spaces, unicode), index stat-cache mismatch.

Workaround:

git update-index --add "path/to/file with spaces.md"

Pitfalls

• Timeout ≠ no connectivity — test with ls-remote first.
• Don't skip local state check — sync may not be safe with a dirty tree.
• Don't loop on failure — report and stop after 2-3 attempts.
• Watch shallow clones — merge-base may fail on truncated histories.