Git Mastery - Complete Git Expertise

🚨 CRITICAL GUIDELINES

Windows File Path Requirements

MANDATORY: Always Use Backslashes on Windows for File Paths

When using Edit or Write tools on Windows, you MUST use backslashes (\) in file paths, NOT forward slashes (/).

Examples:

• ❌ WRONG: D:/repos/project/file.tsx
• ✅ CORRECT: D:\repos\project\file.tsx

This applies to:

• Edit tool file_path parameter
• Write tool file_path parameter
• All file operations on Windows systems

Documentation Guidelines

NEVER create new documentation files unless explicitly requested by the user.

• Priority: Update existing README.md files rather than creating new documentation
• Repository cleanliness: Keep repository root clean - only README.md unless user requests otherwise
• Style: Documentation should be concise, direct, and professional - avoid AI-generated tone
• User preference: Only create additional .md files when user specifically asks for documentation

---

Comprehensive guide for ALL Git operations from basic to advanced, including dangerous operations with safety guardrails.

---

TL;DR QUICK REFERENCE

Safety First - Before ANY Destructive Operation:

# ALWAYS check status first
git status
git log --oneline -10

# For risky operations, create a safety branch
git branch backup-$(date +%Y%m%d-%H%M%S)

# Remember: git reflog is your safety net (90 days default)
git reflog

User Preference Check:

• ALWAYS ASK: "Would you like me to create commits automatically, or would you prefer to handle commits manually?"
• Respect user's choice throughout the session

---

Overview

This skill provides COMPLETE Git expertise for ANY Git operation, no matter how advanced, niche, or risky. It covers:

MUST use this skill for:

• ✅ ANY Git command or operation
• ✅ Repository initialization, cloning, configuration
• ✅ Branch management and strategies
• ✅ Commit workflows and best practices
• ✅ Merge strategies and conflict resolution
• ✅ Rebase operations (interactive and non-interactive)
• ✅ History rewriting (filter-repo, reset, revert)
• ✅ Recovery operations (reflog, fsck)
• ✅ Dangerous operations (force push, hard reset)
• ✅ Platform-specific workflows (GitHub, Azure DevOps, Bitbucket)
• ✅ Advanced features (submodules, worktrees, hooks)
• ✅ Performance optimization
• ✅ Cross-platform compatibility (Windows/Linux/macOS)

---

Core Principles

1. Safety Guardrails for Destructive Operations

CRITICAL: Before ANY destructive operation (reset --hard, force push, filter-repo, etc.):

1. Always warn the user explicitly
2. Explain the risks clearly
3. Ask for confirmation
4. Suggest creating a backup branch first
5. Provide recovery instructions

# Example safety pattern for dangerous operations
echo "⚠️  WARNING: This operation is DESTRUCTIVE and will:"
echo "   - Permanently delete uncommitted changes"
echo "   - Rewrite Git history"
echo "   - [specific risks for the operation]"
echo ""
echo "Safety recommendation: Creating backup branch first..."
git branch backup-before-reset-$(date +%Y%m%d-%H%M%S)
echo ""
echo "To recover if needed: git reset --hard backup-before-reset-XXXXXXXX"
echo ""
read -p "Are you SURE you want to proceed? (yes/NO): " confirm
if [[ "$confirm" != "yes" ]]; then
    echo "Operation cancelled."
    exit 1
fi

2. Commit Creation Policy

ALWAYS ASK at the start of ANY Git task: "Would you like me to:

1. Create commits automatically with appropriate messages
2. Stage changes only (you handle commits manually)
3. Just provide guidance (no automatic operations)"

Respect this choice throughout the session.

3. Platform Awareness

Git behavior and workflows differ across platforms and hosting providers:

Windows (Git Bash/PowerShell):

• Line ending handling (core.autocrlf)
• Path separators and case sensitivity
• Credential management (Windows Credential Manager)

Linux/macOS:

• Case-sensitive filesystems
• SSH key management
• Permission handling

Hosting Platforms:

• GitHub: Pull requests, GitHub Actions, GitHub CLI
• Azure DevOps: Pull requests, Azure Pipelines, policies
• Bitbucket: Pull requests, Bitbucket Pipelines, Jira integration
• GitLab: Merge requests, GitLab CI/CD

---

Basic Git Operations

Repository Initialization and Cloning

# Initialize new repository
git init
git init --initial-branch=main  # Specify default branch name

# Clone repository
git clone <url>
git clone <url> <directory>
git clone --depth 1 <url>  # Shallow clone (faster, less history)
git clone --branch <branch> <url>  # Clone specific branch
git clone --recurse-submodules <url>  # Include submodules

Configuration

# User identity (required for commits)
git config --global user.name "Your Name"
git config --global user.email "[email protected]"

# Default branch name
git config --global init.defaultBranch main

# Line ending handling (Windows)
git config --global core.autocrlf true  # Windows
git config --global core.autocrlf input  # macOS/Linux

# Editor
git config --global core.editor "code --wait"  # VS Code
git config --global core.editor "vim"

# Diff tool
git config --global diff.tool vscode
git config --global difftool.vscode.cmd 'code --wait --diff $LOCAL $REMOTE'

# Merge tool
git config --global merge.tool vscode
git config --global mergetool.vscode.cmd 'code --wait $MERGED'

# Aliases
git config --global alias.st status
git config --global alias.co checkout
git config --global alias.br branch
git config --global alias.ci commit
git config --global alias.unstage 'reset HEAD --'
git config --global alias.last 'log -1 HEAD'
git config --global alias.visual '!gitk'

# View configuration
git config --list
git config --global --list
git config --local --list
git config user.name  # Get specific value

Basic Workflow

# Check status
git status
git status -s  # Short format
git status -sb  # Short with branch info

# Add files
git add <file>
git add .  # Add all changes in current directory
git add -A  # Add all changes in repository
git add -p  # Interactive staging (patch mode)

# Remove files
git rm <file>
git rm --cached <file>  # Remove from index, keep in working directory
git rm -r <directory>

# Move/rename files
git mv <old> <new>

# Commit
git commit -m "message"
git commit -am "message"  # Add and commit tracked files
git commit --amend  # Amend last commit
git commit --amend --no-edit  # Amend without changing message
git commit --allow-empty -m "message"  # Empty commit (useful for triggers)

# View history
git log
git log --oneline
git log --graph --oneline --all --decorate
git log --stat  # Show file statistics
git log --patch  # Show diffs
git log -p -2  # Show last 2 commits with diffs
git log --since="2 weeks ago"
git log --until="2025-01-01"
git log --author="Name"
git log --grep="pattern"
git log -- <file>  # History of specific file
git log --follow <file>  # Follow renames

# Show changes
git diff  # Unstaged changes
git diff --staged  # Staged changes
git diff HEAD  # All changes since last commit
git diff <branch>  # Compare with another branch
git diff <commit1> <commit2>
git diff <commit>  # Changes since specific commit
git diff <branch1>...<branch2>  # Changes between branches