git-operations

name	git-operations
description	Use when pushing, pulling, or merging changes. Handles retries, conflicts, and error recovery.

SKILL: Git Operations

Purpose: Safe push/pull/merge operations with retry logic and error handling Target: All git operations

---

Quick Start

When to Use This Skill

• Pushing changes to remote
• Pulling latest changes
• Merging branches
• Resolving merge conflicts

Quick Reference

# Push with retry (3 attempts, 2s delay)
git_push_with_retry() {
  local branch="${1:-$(git rev-parse --abbrev-ref HEAD)}"
  for attempt in {1..3}; do
    git push origin "$branch" 2>&1 && return 0
    echo "Retry $attempt/3..." && sleep 2
  done
  return 1
}

# Pull with fast-forward only
git pull --ff-only || echo "Manual merge required"

---

Core Operations

Push with Retry

Purpose: Handle transient network failures with exponential backoff (3 attempts, 2s/4s/8s delay)

git_push_with_retry() {
  local remote="${1:-origin}"
  local branch="${2:-$(git rev-parse --abbrev-ref HEAD)}"
  local max_attempts=3
  local wait_times=(2 4 8)  # Exponential backoff

  echo "🔄 Pushing to $remote/$branch..."

  for attempt in $(seq 1 $max_attempts); do
    # Attempt push
    if git push "$remote" "$branch" 2>&1; then
      echo "✓ Push successful"
      return 0
    fi

    local exit_code=$?
    local error_output="$(git push "$remote" "$branch" 2>&1 || true)"

    # Classify error
    if echo "$error_output" | grep -qiE "non-fast-forward|rejected|protected"; then
      echo "❌ Push rejected (non-fast-forward or protected branch)"
      echo "   Run: git pull --rebase && git push"
      return 1
    elif echo "$error_output" | grep -qiE "authentication|permission|credentials"; then
      echo "❌ Authentication error"
      echo "   Check git credentials: git config --list | grep credential"
      return 1
    fi

    # Retry for network/transient errors
    if [ $attempt -lt $max_attempts ]; then
      local wait_time=${wait_times[$((attempt-1))]}
      echo "⚠️  Push failed (attempt $attempt/$max_attempts), retrying in ${wait_time}s..."
      sleep "$wait_time"
    else
      echo "❌ Push failed after $max_attempts attempts"
      return 1
    fi
  done

  return 1
}

Error Classification:

• Non-retryable (return 1): non-fast-forward, rejected, protected branch, authentication
• Retryable (continue loop): network errors, connection timeout, transient failures
• No remote (handled by caller): Remote doesn't exist

Retry Strategy:

• Max attempts: 3
• Wait times: 2s, 4s, 8s (exponential backoff)
• Exit on non-retryable errors immediately

Pull with Safety Checks

Purpose: Avoid destructive merges, ensure clean working tree

git_pull_safe() {
  # Check for uncommitted changes
  git diff-index --quiet HEAD -- || { echo "Uncommitted changes" >&2; return 1; }

  # Fast-forward only
  git pull --ff-only || { echo "Manual merge required" >&2; return 1; }
}

Merge with Verification

Purpose: Safe branch merging with conflict detection

git_merge_safe() {
  local source="$1"
  local target="${2:-$(git rev-parse --abbrev-ref HEAD)}"

  git checkout "$target" || return 1
  if git merge "$source" --no-ff --no-edit; then
    echo "✓ Merged $source into $target"
  else
    echo "⚠️  Conflicts in:" && git diff --name-only --diff-filter=U
    echo "Resolve, then: git add <files> && git commit"
    return 1
  fi
}

---

Error Handling & Recovery

Common Errors

Error	Cause	Solution
Failed to connect	Network issue	Retry with git_push_with_retry
rejected (non-fast-forward)	Remote has new commits	Pull first, then push
conflict	Branches diverged	Manual merge required
uncommitted changes	Dirty working tree	Commit or stash first

Conflict Resolution

# After merge conflict
git status  # List conflicted files
vim conflicted-file.ts  # Resolve markers
git add conflicted-file.ts
git commit

# Abort operations
git merge --abort  # Abort merge
git rebase --abort  # Abort rebase
git reset --hard HEAD  # Reset to safe state

Error Recovery Pattern

git_operation_with_fallback() {
  eval "$1" && return 0
  case "$(git status 2>&1)" in
    *connection*) return 2 ;;  # Retryable
    *conflict*) return 3 ;;    # Needs intervention
    *) return 1 ;;             # Fatal
  esac
}

---

Related Skills

• using-git-worktrees: Parallel development in isolated workspaces
• git-master: Comprehensive git workflow mastery

---

Version: claude-pilot 4.2.0