Step-by-Step Implementation Plan

Git Repository Management Toolkit

Version: 1.0
Date: February 2, 2026
Estimated Total Time: 4-6 hours

Overview

This plan provides detailed, actionable steps to implement the git repository management toolkit. Tasks are organized by priority and include time estimates, commands, and verification steps.

Phase 0: Immediate Quick Wins (Today)

Time Required: 20-30 minutes
Impact: Reduces dirty repos from 24 to ~15

Step 0.1: Setup Scripts

# Create a directory for the tools
mkdir -p ~/bin/git-tools
cd ~/bin/git-tools

# Copy or download the scripts
# (Assuming files are downloaded to ~/Downloads)
cp ~/Downloads/git_status.py .
cp ~/Downloads/git_cleanup.sh .
cp ~/Downloads/quick_push.sh .

# Make executable
chmod +x git_status.py git_cleanup.sh quick_push.sh

# Add to PATH (optional)
echo 'export PATH="$HOME/bin/git-tools:$PATH"' >> ~/.zshrc
source ~/.zshrc

Verify:

./git_status.py --help
./git_cleanup.sh --help

Step 0.2: Push Unpushed Commits

# Preview what will be pushed
./git_cleanup.sh --dry-run --push

# Execute push
./quick_push.sh

Expected output:

═══════════════════════════════════════════
  Quick Push: Coditect Submodules
═══════════════════════════════════════════

Pushing coditect-core-final-exam-example (+1)... OK
Pushing coditect-task-orchestrator (+1)... OK
...

═══════════════════════════════════════════
  Results: 9 pushed, 0 failed
═══════════════════════════════════════════

Verify:

python3 git_status.py --root ~/PROJECTS/coditect-rollout-master --format simple
# Should show fewer "ahead" repos

Step 0.3: Fix Diverged PROJECTS Repo

cd ~/PROJECTS

# Check current state
git status
git log --oneline -5
git log --oneline origin/main -5

# Fetch latest from remote
git fetch origin

# Option A: Rebase (recommended for small changes)
git rebase origin/main

# Option B: Merge (safer, creates merge commit)
# git merge origin/main -m "Merge remote changes"

# Push resolved state
git push origin main

Verify:

git status
# Should show: "Your branch is up to date with 'origin/main'"

Step 0.4: Fix Noisy Home Directory

cd ~

# View current gitignore
cat .gitignore 2>/dev/null || echo "(no .gitignore)"

# Add ignore patterns
cat >> .gitignore << 'EOF'

# === Added by git-tools setup ===
# Ignore directories that shouldn't be tracked
PROJECTS/
Library/
Applications/
Desktop/
Documents/
Downloads/
Movies/
Music/
Pictures/
Public/
.Trash/
.cache/
.npm/
.local/
.config/

# Ignore common noise
*.log
*.tmp
.DS_Store
EOF

# Commit the change
git add .gitignore
git commit -m "chore: Update gitignore to exclude system directories"
git push

Verify:

git status
# Untracked count should drop significantly
python3 ~/bin/git-tools/git_status.py --root ~ --format simple | grep halcasteel

Step 0.5: Generate Baseline Report

# Create reports directory
mkdir -p ~/git-reports

# Generate comprehensive report
python3 ~/bin/git-tools/git_status.py \
    --root ~/ \
    --format all \
    --output-dir ~/git-reports

# View summary
cat ~/git-reports/git-status-2026-02-02.md | head -50

Verify:

ls -la ~/git-reports/
# Should show: .json, .md, .txt files

Phase 1: Automation Setup (This Week)

Time Required: 2-3 hours
Impact: Automated daily monitoring

Step 1.1: Create Daily Report Script

cat > ~/bin/git-tools/git_daily_report.sh << 'EOF'
#!/bin/bash
#
# git_daily_report.sh - Daily git status report with notifications
#

set -euo pipefail

TOOLS_DIR="$HOME/bin/git-tools"
REPORTS_DIR="$HOME/git-reports"
TODAY=$(date +%Y-%m-%d)

# Ensure directories exist
mkdir -p "$REPORTS_DIR"

# Generate report
python3 "$TOOLS_DIR/git_status.py" \
    --root "$HOME" \
    --format markdown \
    --stale-days 14 \
    > "$REPORTS_DIR/git-status-$TODAY.md"

# Extract metrics for notification
TOTAL=$(grep "Total Repositories" "$REPORTS_DIR/git-status-$TODAY.md" | grep -oE '[0-9]+' || echo "0")
DIRTY=$(grep "Dirty" "$REPORTS_DIR/git-status-$TODAY.md" | grep -oE '[0-9]+' | head -1 || echo "0")
STALE=$(grep "Stale" "$REPORTS_DIR/git-status-$TODAY.md" | grep -oE '[0-9]+' | head -1 || echo "0")

# macOS notification
if command -v osascript &> /dev/null; then
    if [ "$DIRTY" -gt 5 ]; then
        osascript -e "display notification \"$DIRTY dirty, $STALE stale out of $TOTAL repos\" with title \"Git Status Alert\" subtitle \"Review needed\""
    fi
fi

# Log
echo "[$TODAY] Report generated: $TOTAL repos, $DIRTY dirty, $STALE stale"
EOF

chmod +x ~/bin/git-tools/git_daily_report.sh

Test:

~/bin/git-tools/git_daily_report.sh
cat ~/git-reports/git-status-$(date +%Y-%m-%d).md | head -20

Step 1.2: Setup macOS LaunchAgent

# Create LaunchAgent
cat > ~/Library/LaunchAgents/com.coditect.git-status.plist << 'EOF'
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.coditect.git-status</string>
    
    <key>ProgramArguments</key>
    <array>
        <string>/bin/bash</string>
        <string>-c</string>
        <string>$HOME/bin/git-tools/git_daily_report.sh >> $HOME/git-reports/daily.log 2>&1</string>
    </array>
    
    <key>StartCalendarInterval</key>
    <dict>
        <key>Hour</key>
        <integer>9</integer>
        <key>Minute</key>
        <integer>0</integer>
    </dict>
    
    <key>StandardOutPath</key>
    <string>/tmp/git-status-stdout.log</string>
    
    <key>StandardErrorPath</key>
    <string>/tmp/git-status-stderr.log</string>
    
    <key>RunAtLoad</key>
    <false/>
</dict>
</plist>
EOF

# Load the agent
launchctl load ~/Library/LaunchAgents/com.coditect.git-status.plist

# Verify
launchctl list | grep coditect

Test manually:

launchctl start com.coditect.git-status
sleep 5
cat /tmp/git-status-stdout.log
cat ~/git-reports/daily.log

Step 1.3: Create Submodule Sync Script

cat > ~/bin/git-tools/submodule_sync.sh << 'EOF'
#!/bin/bash
#
# submodule_sync.sh - Recursive submodule operations for coditect-rollout-master
#

set -euo pipefail

ROLLOUT_MASTER="$HOME/PROJECTS/coditect-rollout-master"

GREEN='\033[0;32m'
YELLOW='\033[1;33m'
RED='\033[0;31m'
NC='\033[0m'

usage() {
    echo "Usage: $0 <command>"
    echo ""
    echo "Commands:"
    echo "  status    Show status of all submodules"
    echo "  pull      Fetch and merge all submodules"
    echo "  push      Push all submodules (bottom-up)"
    echo "  sync      Full sync: pull then push"
    exit 1
}

show_status() {
    echo "=== Submodule Status ==="
    cd "$ROLLOUT_MASTER"
    git submodule foreach --recursive 'echo "$(basename $(pwd)): $(git status -s | wc -l | tr -d " ") changes"'
}

pull_all() {
    echo "=== Pulling all submodules ==="
    cd "$ROLLOUT_MASTER"
    git submodule update --init --recursive
    git submodule foreach --recursive 'git fetch origin && git pull origin $(git rev-parse --abbrev-ref HEAD) || true'
    echo -e "${GREEN}Pull complete${NC}"
}

push_all() {
    echo "=== Pushing all submodules (bottom-up) ==="
    cd "$ROLLOUT_MASTER"
    
    # Push submodules first (deepest first)
    git submodule foreach --recursive '
        branch=$(git rev-parse --abbrev-ref HEAD)
        ahead=$(git rev-list --count HEAD@{upstream}..HEAD 2>/dev/null || echo "0")
        if [ "$ahead" -gt 0 ]; then
            echo "Pushing $(basename $(pwd)) (+$ahead)..."
            git push origin $branch
        fi
    '
    
    # Then push parent
    branch=$(git rev-parse --abbrev-ref HEAD)
    ahead=$(git rev-list --count HEAD@{upstream}..HEAD 2>/dev/null || echo "0")
    if [ "$ahead" -gt 0 ]; then
        echo "Pushing rollout-master (+$ahead)..."
        git push origin $branch
    fi
    
    echo -e "${GREEN}Push complete${NC}"
}

case "${1:-}" in
    status) show_status ;;
    pull)   pull_all ;;
    push)   push_all ;;
    sync)   pull_all && push_all ;;
    *)      usage ;;
esac
EOF

chmod +x ~/bin/git-tools/submodule_sync.sh

Test:

~/bin/git-tools/submodule_sync.sh status
~/bin/git-tools/submodule_sync.sh pull
~/bin/git-tools/submodule_sync.sh push

Step 1.4: Create .gitignore Templates

mkdir -p ~/bin/git-tools/templates

# Home directory template
cat > ~/bin/git-tools/templates/gitignore-home.txt << 'EOF'
# === Home Directory .gitignore ===
# For dotfiles repos that track home directory

# Exclude large/noisy directories
PROJECTS/
Library/
Applications/
Desktop/
Documents/
Downloads/
Movies/
Music/
Pictures/
Public/
.Trash/

# Exclude caches and state
.cache/
.npm/
.local/
.config/
.vscode/
.idea/

# Exclude logs and temp files
*.log
*.tmp
.DS_Store
Thumbs.db

# Exclude credentials (NEVER commit these)
.ssh/id_*
.ssh/known_hosts
.aws/credentials
.netrc
*.pem
*.key
EOF

# Projects directory template
cat > ~/bin/git-tools/templates/gitignore-projects.txt << 'EOF'
# === Projects Directory .gitignore ===
# For parent directories containing multiple repos

# Ignore all subdirectories (they're their own repos)
*/

# Keep only top-level files
!.gitignore
!README.md
!.gitattributes
EOF

# Coditect standard template
cat > ~/bin/git-tools/templates/gitignore-coditect.txt << 'EOF'
# === Coditect Standard .gitignore ===

# Dependencies
node_modules/
venv/
.venv/
__pycache__/
*.pyc

# Build outputs
dist/
build/
*.egg-info/
.next/
out/

# IDE
.vscode/
.idea/
*.swp
*.swo

# Environment
.env
.env.local
.env.*.local

# Logs
logs/
*.log
npm-debug.log*

# OS
.DS_Store
Thumbs.db

# Testing
coverage/
.coverage
.pytest_cache/

# Coditect specific
.claude/cache/
.coditect/tmp/
session-logs/
EOF

echo "Templates created in ~/bin/git-tools/templates/"
ls -la ~/bin/git-tools/templates/

Phase 2: Verification & Maintenance

Time Required: 30 minutes
Schedule: Weekly

Step 2.1: Weekly Review Checklist

# Create weekly review script
cat > ~/bin/git-tools/weekly_review.sh << 'EOF'
#!/bin/bash
#
# weekly_review.sh - Weekly git portfolio review
#

echo "=== Git Portfolio Weekly Review ==="
echo "Date: $(date)"
echo ""

# Generate fresh report
python3 ~/bin/git-tools/git_status.py \
    --root ~/ \
    --format markdown \
    --stale-days 7 \
    > /tmp/weekly-review.md

# Show summary
echo "=== Summary ==="
head -30 /tmp/weekly-review.md

echo ""
echo "=== Action Items ==="

# Dirty repos
dirty=$(grep -c "⚠️" /tmp/weekly-review.md || echo "0")
echo "- Dirty repos: $dirty"

# Stale repos
stale=$(grep -c "🕐" /tmp/weekly-review.md || echo "0")
echo "- Stale repos (>7 days): $stale"

# Unpushed
unpushed=$(grep -E "^\| .+ \| .+ \| \+[0-9]+ \|" /tmp/weekly-review.md | wc -l | tr -d ' ')
echo "- Repos with unpushed commits: $unpushed"

echo ""
echo "Full report: /tmp/weekly-review.md"
echo "Open with: open /tmp/weekly-review.md"
EOF

chmod +x ~/bin/git-tools/weekly_review.sh

Step 2.2: Add Calendar Reminder

# Create calendar event (requires calendar access)
# Alternative: Set a recurring reminder manually

echo "ACTION: Add recurring calendar event:"
echo "  Title: Git Portfolio Weekly Review"
echo "  When: Every Monday at 9:30 AM"
echo "  Notes: Run ~/bin/git-tools/weekly_review.sh"

Verification Checklist

Phase 0 Complete ✓

Scripts installed and executable
All unpushed commits pushed
PROJECTS repo divergence resolved
Home directory .gitignore updated
Baseline report generated

Phase 1 Complete ✓

Daily report script working
LaunchAgent loaded and tested
Submodule sync script working
.gitignore templates created

Phase 2 Complete ✓

Weekly review script working
Calendar reminder set
First weekly review completed

Troubleshooting

LaunchAgent not running

# Check if loaded
launchctl list | grep coditect

# Reload
launchctl unload ~/Library/LaunchAgents/com.coditect.git-status.plist
launchctl load ~/Library/LaunchAgents/com.coditect.git-status.plist

# Check logs
cat /tmp/git-status-stderr.log

Submodule sync fails

# Reset submodules
cd ~/PROJECTS/coditect-rollout-master
git submodule deinit --all -f
git submodule update --init --recursive

Permission denied on push

# Check SSH agent
ssh-add -l

# Add key if missing
ssh-add ~/.ssh/id_ed25519

# Test connection
ssh -T git@github.com

Next Steps

After completing all phases:

Monitor — Review daily reports for 1 week
Adjust — Tune stale threshold based on workflow
Expand — Add HTML dashboard (Phase 2 enhancement)
Integrate — Consider MCP server for agent access

Time Investment Summary

Phase	Tasks	Time	Cumulative
Phase 0	Quick wins	30 min	30 min
Phase 1.1	Daily report script	30 min	1 hr
Phase 1.2	LaunchAgent setup	30 min	1.5 hr
Phase 1.3	Submodule sync	45 min	2.25 hr
Phase 1.4	Templates	15 min	2.5 hr
Phase 2	Verification	30 min	3 hr

Total: ~3 hours for full implementation

For detailed script documentation, see GIT_SCRIPTS_README.md
For future enhancements, see GIT_ENHANCEMENT_PLAN.md

Git Repository Management Toolkit​

Overview​

Phase 0: Immediate Quick Wins (Today)​

Step 0.1: Setup Scripts​

Step 0.2: Push Unpushed Commits​

Step 0.3: Fix Diverged PROJECTS Repo​

Step 0.4: Fix Noisy Home Directory​

Step 0.5: Generate Baseline Report​

Phase 1: Automation Setup (This Week)​

Step 1.1: Create Daily Report Script​

Step 1.2: Setup macOS LaunchAgent​

Step 1.3: Create Submodule Sync Script​

Step 1.4: Create .gitignore Templates​

Phase 2: Verification & Maintenance​

Step 2.1: Weekly Review Checklist​

Step 2.2: Add Calendar Reminder​

Verification Checklist​

Phase 0 Complete ✓​

Phase 1 Complete ✓​

Phase 2 Complete ✓​

Troubleshooting​

LaunchAgent not running​

Submodule sync fails​

Permission denied on push​

Next Steps​

Time Investment Summary​

Git Repository Management Toolkit

Overview

Phase 0: Immediate Quick Wins (Today)

Step 0.1: Setup Scripts

Step 0.2: Push Unpushed Commits

Step 0.3: Fix Diverged PROJECTS Repo

Step 0.4: Fix Noisy Home Directory

Step 0.5: Generate Baseline Report

Phase 1: Automation Setup (This Week)

Step 1.1: Create Daily Report Script

Step 1.2: Setup macOS LaunchAgent

Step 1.3: Create Submodule Sync Script

Step 1.4: Create .gitignore Templates

Phase 2: Verification & Maintenance

Step 2.1: Weekly Review Checklist

Step 2.2: Add Calendar Reminder

Verification Checklist

Phase 0 Complete ✓

Phase 1 Complete ✓

Phase 2 Complete ✓

Troubleshooting

LaunchAgent not running

Submodule sync fails

Permission denied on push

Next Steps

Time Investment Summary