git_remote_sync

Git Remote Sync Rule

Purpose

Ensures agents always pull and merge remote changes before pushing, maintaining repository synchronization and preventing push rejections.

Trigger Patterns

When any of the following occur, agents MUST pull and merge before pushing:

• Push is rejected with "non-fast-forward" or "diverged branches" error
• git status shows "Your branch and 'origin/main' have diverged"
• git status shows "Your branch is behind 'origin/main'"
• Remote changes detected during commit workflow
• Push command is about to execute
• Any git operation that would modify remote state

Agent Actions

Step 1: Detect Remote Changes

Before pushing or when push fails:

1. Check if remote is ahead:

   git fetch origin
   LOCAL=$(git rev-parse @)
   REMOTE=$(git rev-parse @{u} 2>/dev/null || echo "")
   
   if [ -z "$REMOTE" ]; then
     # No upstream set - proceed with push
     exit 0
   fi
   
   BASE=$(git merge-base @ @{u})
   
   if [ "$LOCAL" = "$REMOTE" ]; then
     # Already in sync
     exit 0
   elif [ "$REMOTE" = "$BASE" ]; then
     # Local is ahead - safe to push
     exit 0
   elif [ "$LOCAL" = "$BASE" ] || [ "$LOCAL" != "$REMOTE" ] && [ "$REMOTE" != "$BASE" ]; then
     # Remote is ahead or branches have diverged - MUST pull and merge
     PULL_NEEDED=true
   fi
   

2. If push was rejected, check error message:

   # If push fails with "non-fast-forward" or "diverged"
   # Immediately proceed to pull and merge workflow
   

Step 2: Pull and Merge

If remote changes detected:

1. Pull with merge strategy:

   CURRENT_BRANCH=$(git branch --show-current)
   git pull origin "$CURRENT_BRANCH" --no-rebase --no-edit
   

2. Handle merge conflicts:

   • If conflicts occur, resolve them immediately
   • Stage resolved files: git add <resolved-files>
   • Complete merge: git commit --no-edit (or with merge message if needed)
   • DO NOT abort merge unless user explicitly requests