learning_ai_common_plat/AI.dev/SKILLS/backup-main-branch.md

Backup Main Branch Skill

Description: Smart backup of main branches across repositories with duplicate detection.

When to Use

• Before making major changes to main branch
• Before risky operations (rebases, large refactors)
• Regular safety backups
• When working with critical repositories

Prerequisites

• Git access to repositories
• Write permissions to backup branch
• Clean working directory

Quick Start

# From any repo root
/windsurf-workflow backup-main-branch

Workflow Steps

1. Check Current State

# Ensure we're on main branch
CURRENT_BRANCH=$(git branch --show-current)
if [ "$CURRENT_BRANCH" != "main" ]; then
  echo "Switching to main branch..."
  git switch main
fi

# Check if working directory is clean
if [ -n "$(git status --porcelain)" ]; then
  echo "⚠️  Working directory not clean!"
  echo "Please commit or stash changes before backup"
  exit 1
fi

2. Check if Backup Needed

# Get timestamp of last backup branch commit
BACKUP_BRANCH="backup/main-$(date +%Y-%m-%d)"
LATEST_BACKUP=$(git branch -r --sort=-committerdate | grep "origin/backup/main-" | head -1 | cut -d'/' -f2)

if [ -n "$LATEST_BACKUP" ]; then
  # Compare main with latest backup
  MAIN_COMMIT=$(git rev-parse origin/main)
  BACKUP_COMMIT=$(git rev-parse origin/$LATEST_BACKUP)

  if [ "$MAIN_COMMIT" = "$BACKUP_COMMIT" ]; then
    echo "✅ Main branch already backed up in $LATEST_BACKUP"
    echo "No backup needed"
    exit 0
  fi
fi

3. Create New Backup

# Create backup branch name with timestamp
BACKUP_BRANCH="backup/main-$(date +%Y-%m-%d-%H%M%S)"

# Create and push backup branch
echo "Creating backup branch: $BACKUP_BRANCH"
git checkout -b $BACKUP_BRANCH
git push -u origin $BACKUP_BRANCH

# Switch back to main
git checkout main

echo "✅ Backup created: $BACKUP_BRANCH"

4. Cleanup Old Backups (Optional)

# Keep only last 7 days of backups
echo "Cleaning up old backups..."
git fetch origin
for branch in $(git branch -r --sort=-committerdate | grep "origin/backup/main-" | tail -n +8); do
  BACKUP_NAME=$(echo $branch | cut -d'/' -f2)
  echo "Deleting old backup: $BACKUP_NAME"
  git push origin --delete $BACKUP_NAME
done

Full Script

Create scripts/backup-main.sh:

#!/bin/bash
# Backup main branch with smart duplicate detection

set -e  # Exit on any error

# Colors for output
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
NC='\033[0m' # No Color

echo -e "${GREEN}🔄 Starting main branch backup...${NC}"

# Function to backup a single repository
backup_repo() {
  local repo_path=$1
  local repo_name=$(basename "$repo_path")

  echo -e "\n${YELLOW}Processing repository: $repo_name${NC}"

  cd "$repo_path"

  # Ensure we're on main
  CURRENT_BRANCH=$(git branch --show-current)
  if [ "$CURRENT_BRANCH" != "main" ]; then
    echo "Switching to main branch..."
    git switch main
  fi

  # Pull latest changes
  echo "Pulling latest changes..."
  git pull origin main

  # Check if working directory is clean
  if [ -n "$(git status --porcelain)" ]; then
    echo -e "${RED}⚠️  Working directory not clean in $repo_name!${NC}"
    echo "Skipping backup for this repository"
    cd ..
    return 1
  fi

  # Check if backup is needed
  LATEST_BACKUP=$(git branch -r --sort=-committerdate 2>/dev/null | grep "origin/backup/main-" | head -1 | cut -d'/' -f2 || true)

  if [ -n "$LATEST_BACKUP" ]; then
    MAIN_COMMIT=$(git rev-parse origin/main)
    BACKUP_COMMIT=$(git rev-parse origin/$LATEST_BACKUP 2>/dev/null || true)

    if [ "$MAIN_COMMIT" = "$BACKUP_COMMIT" ]; then
      echo -e "${GREEN}✅ $repo_name: Already backed up in $LATEST_BACKUP${NC}"
      cd ..
      return 0
    fi
  fi

  # Create new backup
  BACKUP_BRANCH="backup/main-$(date +%Y-%m-%d-%H%M%S)"

  echo "Creating backup branch: $BACKUP_BRANCH"
  git checkout -b $BACKUP_BRANCH
  git push -u origin $BACKUP_BRANCH
  git checkout main

  echo -e "${GREEN}✅ $repo_name: Backup created successfully${NC}"

  # Cleanup old backups (keep last 7)
  for branch in $(git branch -r --sort=-committerdate 2>/dev/null | grep "origin/backup/main-" | tail -n +8); do
    BACKUP_NAME=$(echo $branch | cut -d'/' -f2)
    echo "Deleting old backup: $BACKUP_NAME"
    git push origin --delete $BACKUP_NAME 2>/dev/null || true
  done

  cd ..
}

# Backup all repositories
REPOS=(
  "/Users/sd9235/code/mygh/learning_ai_common_plat"
  "/Users/sd9235/code/mygh/learning_voice_ai_agent"
  "/Users/sd9235/code/mygh/learning_multimodal_memory_agents"
)

# Check which repos exist
for repo in "${REPOS[@]}"; do
  if [ -d "$repo" ]; then
    backup_repo "$repo"
  else
    echo -e "${YELLOW}Repository not found: $repo${NC}"
  fi
done

echo -e "\n${GREEN}✨ Backup process completed!${NC}"

Windsurf Workflow

Create .windsurf/workflows/backup-main-branch.md:

---
description: Smart backup of main branches with duplicate detection
---

# Backup Main Branch

Creates smart backups of main branches across all repositories.

// turbo
Run `bash scripts/backup-main.sh` from any repository root

## What it does:

1. Checks each repository for changes
2. Skips backup if main hasn't changed since last backup
3. Creates timestamped backup branch
4. Cleans up old backups (keeps 7 days)
5. Returns to main branch

## Repositories covered:

- learning_ai_common_plat
- learning_voice_ai_agent
- learning_multimodal_memory_agents

Advanced Features

Backup with Tags

# Create backup with descriptive tag
BACKUP_BRANCH="backup/main-$(date +%Y-%m-%d)-before-refactor"

Include Additional Repositories

# Add to REPOS array in script
REPOS=(
  "/Users/sd9235/code/mygh/learning_ai_common_plat"
  "/Users/sd9235/code/mygh/learning_voice_ai_agent"
  "/Users/sd9235/code/mygh/learning_multimodal_memory_agents"
  "/path/to/your/repo"  # Add new repo here
)

Custom Retention Policy

# Keep backups for 30 days instead of 7
for branch in $(git branch -r --sort=-committerdate | grep "origin/backup/main-" | tail -n +31); do
  # Delete old backup
done

Restoration

From Backup Branch

# List available backups
git branch -r | grep "backup/main-"

# Switch to specific backup
git checkout -b restore-from-backup origin/backup/main-2024-01-15-143022

# Merge changes to main if needed
git switch main
git merge restore-from-backup

Create Hotfix from Backup

# Create hotfix branch from backup
git checkout -b hotfix/critical-bug origin/backup/main-2024-01-15-143022

# Make fixes, then merge to main
git switch main
git merge hotfix/critical-bug
git push origin main

Automation

Cron Job for Daily Backups

# Add to crontab (crontab -e)
0 18 * * * cd /Users/sd9235/code/mygh/learning_ai_common_plat && bash scripts/backup-main.sh

GitHub Actions

name: Daily Backup

on:
  schedule:
    - cron: '0 18 * * *' # Daily at 6 PM
  workflow_dispatch:

jobs:
  backup:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          token: ${{ secrets.PAT }} # Personal Access Token with push permissions

      - name: Configure Git
        run: |
          git config --global user.name "Backup Bot"
          git config --global user.email "backup@example.com"          

      - name: Run Backup Script
        run: bash scripts/backup-main.sh

Best Practices

When to Backup

• Before major refactors
• Before risky operations (rebase, force push)
• Before releases
• On a regular schedule (daily/weekly)

Backup Naming

• Use descriptive names for important backups
• Include date and time in all backups
• Consider adding purpose (e.g., "-before-v2.0")

Security

• Use secure Personal Access Tokens
• Limit backup branch permissions
• Regularly review and clean old backups

Troubleshooting

Permission Denied

# Ensure PAT has correct permissions
# Settings → Developer settings → Personal access tokens → repo (full control)

Branch Already Exists

# Delete local branch if exists
git branch -D backup/main-YYYY-MM-DD-HHMMSS

# Or use different timestamp
BACKUP_BRANCH="backup/main-$(date +%Y-%m-%d-%H%M%S)-$(uuidgen | head -c 8)"

Network Issues

# Retry failed pushes
git push -u origin $BACKUP_BRANCH

# Or use retry loop
for i in {1..3}; do
  git push -u origin $BACKUP_BRANCH && break
  sleep 5
done

Notes

• Smart detection prevents unnecessary backups
• Automatic cleanup keeps repository tidy
• Multi-repo support backs up all related projects
• Safe operations always returns to main branch
• No data loss only creates branches, never deletes main

Related Skills

• Git Workflow - General Git operations
• Production Readiness - Backup before releases
• Debug Service - Backup before major changes