JosiahSiegel/git-master

Git Mastery - Complete Git Expertise

Comprehensive Git skill covering basic to advanced operations, with mandatory safety guardrails for destructive commands and platform-specific workflows.

Critical Guidelines

Windows File Path Requirements

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

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

Applies to: Edit/Write file_path parameters and all file operations.

Documentation Guidelines

NEVER create new documentation files unless explicitly requested by the user. Prefer updating existing README.md files. Keep documentation concise, direct, and professional.

TL;DR 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 at 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.

When to Use This Skill

Activate for ANY Git command or operation including:

• 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, GitLab)
• Advanced features (submodules, worktrees, hooks)
• Performance optimization, large files (LFS)
• Cross-platform compatibility (Windows/Linux/macOS)

Key indicators: user mentions Git, GitHub, GitLab, Bitbucket, Azure DevOps, version control, commit/push/pull/merge/rebase, branch management, history modification, or recovery scenarios.

Core Principles

1. Safety Guardrails for Destructive Operations

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

See references/dangerous-operations.md for full safety protocols and confirmation scripts.

2. Commit Creation Policy

ALWAYS ask the user preference at the start of any Git task (automatic / stage-only / guidance-only). Respect this choice throughout.

3. Platform Awareness

Git behavior differs across platforms and hosting providers:

• Windows (Git Bash/PowerShell): Line endings (core.autocrlf), path separators, case sensitivity, Windows Credential Manager
• Linux/macOS: Case-sensitive filesystems, SSH key management, permissions
• Hosting platforms: GitHub (PRs, Actions, gh CLI), Azure DevOps (PRs, Pipelines, policies), Bitbucket (PRs, Pipelines, Jira), GitLab (MRs, CI/CD)

See references/platform-workflows.md for hosting-specific commands and references/cross-platform.md for Windows/Linux/macOS handling.

Reference Map

This SKILL.md is a lean orchestrator. Detailed command catalogs and procedures live in references/:

| Reference | Contents | |-----------|----------| | references/basic-operations.md | Init, clone, config, basic workflow, branches, remotes, fetch/pull/push (non-destructive) | | references/merging-rebasing.md | Merge strategies, conflict resolution, rebase (interactive/onto/autosquash), cherry-pick | | references/advanced-commands.md | Stash (incl. Git 2.51+ import/export), revert, reflog, bisect, clean, worktrees, submodules, tags | | references/dangerous-operations.md | Reset (hard/soft/mixed), force push, filter-repo, amend pushed commits, safety protocols | | references/platform-workflows.md | GitHub, Azure DevOps, Bitbucket, GitLab CLIs and CI/CD templates | | references/performance-large-files.md | GC, repack, fsck, LFS, shallow clones, large-file discovery | | references/hooks-and-security.md | Client/server hooks, credential management, SSH, GPG, secret prevention, conventional commits | | references/troubleshooting-recovery.md | Common problems, recovery scenarios, emergency commands | | references/cross-platform.md | Line endings, case sensitivity, Git Bash/MINGW path conversion, shell detection |

Quick Command Index

| Task | Reference | |------|-----------| | git init, git clone, git add, git commit, git log, git diff | basic-operations | | git branch, git switch, git remote, git fetch, git pull, git push | basic-operations | | git merge, conflict markers, git rebase -i, git cherry-pick | merging-rebasing | | git stash, git revert, git reflog, git bisect, git clean, git worktree, git submodule, git tag | advanced-commands | | git reset --hard, git push --force[-with-lease], git filter-repo, amend pushed | dangerous-operations | | gh pr, az repos pr, bb pr, glab mr, CI/CD YAML | platform-workflows | | git gc, git repack, git lfs, shallow clone | performance-large-files | | .git/hooks/*, conventional commits, SSH/GPG/secrets | hooks-and-security | | Detached HEAD, recover branch/file/commit, corrupted repo | troubleshooting-recovery | | core.autocrlf, core.ignorecase, MSYS_NO_PATHCONV, cygpath, $MSYSTEM | cross-platform |

Success Criteria

A Git workflow using this skill should:

1. ALWAYS ask user preference for automatic commits vs manual
2. ALWAYS warn before destructive operations
3. ALWAYS create backup branches before risky operations
4. ALWAYS explain recovery procedures
5. Use appropriate branch strategy for the project
6. Write meaningful commit messages
7. Keep commit history clean and linear
8. Never commit secrets or large binary files
9. Test code before committing
10. Know how to recover from any mistake

Closing Note

Combined with the reference files and safety guardrails, this skill provides the knowledge to handle ANY Git operation safely and effectively. Always load the appropriate reference before executing a category of commands.