name: git-state-validator description: Check git repository status, detect conflicts, and validate branch state before operations. Use when verifying working directory cleanliness, checking for conflicts, or validating branch state.

Git State Validator

Instructions

When to Invoke This Skill

• Before creating new branches
• Before switching branches
• Before merging or pulling
• After conflicts occur
• When verifying clean working directory
• Before committing changes

Core Validations

1. Working Directory Status - Check for uncommitted changes
2. Branch Validation - Verify current branch and relationship to main
3. Conflict Detection - Identify merge conflicts
4. Remote Sync Status - Check if local is ahead/behind remote
5. Repository Health - Verify git repository integrity

Standard Workflows

Check Working Directory Status

1. Get Status

   git status
   

2. Parse Output

   • Clean: "nothing to commit, working tree clean"
   • Unstaged changes: Modified files not added
   • Staged changes: Files added but not committed
   • Untracked files: New files not added to git

3. Get Machine-Readable Status

   git status --porcelain
   

   Prefixes:

   • M - Modified
   • A - Added
   • D - Deleted
   • ?? - Untracked
   • UU - Merge conflict

Validate Branch State

1. Get Current Branch

   git branch --show-current
   

2. Check if on Main

   git branch --show-current | grep -E "^(main|master)$"
   

3. Get Branch List

   git branch -a
   

   • Local branches (no prefix)
   • Remote branches (remotes/origin/...)

4. Check Branch Relationship

   git merge-base --is-ancestor main HEAD
   

   Exit code 0: Current branch is based on main

Detect Conflicts

1. Check for Conflict Markers

   git diff --check
   

2. List Conflicted Files

   git diff --name-only --diff-filter=U
   

3. View Conflict Details

   git status
   

   Look for "both modified" or "both added"

4. Analyze Conflict Markers Search files for:

   <<<<<<< HEAD
   <current changes>
   =======
   <incoming changes>
   >>>>>>> branch-name
   

Check Remote Sync Status

1. Fetch Remote State (without merging)

   git fetch origin
   

2. Compare with Remote

   git status -sb
   

   Output patterns:

   • [ahead 3] - Local has 3 commits not pushed
   • [behind 2] - Remote has 2 commits not pulled
   • [ahead 1, behind 2] - Both have unpushed/unpulled commits

3. View Unpushed Commits

   git log origin/main..HEAD --oneline
   

4. View Unpulled Commits

   git log HEAD..origin/main --oneline
   

Validate Repository Health

1. Check Repository Integrity

   git fsck --full
   

2. Verify Object Database

   git count-objects -v
   

3. Check for Corrupted Objects

   git fsck --lost-found
   

Common Status Interpretations

Clean Working Directory

$ git status
On branch feat/new-feature
nothing to commit, working tree clean

Interpretation: Safe to switch branches, merge, or create new branch

Uncommitted Changes

$ git status
On branch feat/new-feature
Changes not staged for commit:
  modified:   src/main.py
  modified:   src/utils.py

Interpretation: Need to commit or stash before branch operations

Merge Conflict

$ git status
On branch feat/new-feature
You have unmerged paths.

Unmerged paths:
  both modified:   src/config.py

Interpretation: Must resolve conflicts before proceeding

Ahead of Remote

$ git status -sb
## feat/new-feature...origin/feat/new-feature [ahead 3]

Interpretation: Local has 3 commits not pushed to remote

Behind Remote

$ git status -sb
## main...origin/main [behind 5]

Interpretation: Remote has 5 commits not pulled locally

Error Scenarios

Not a Git Repository:

fatal: not a git repository (or any of the parent directories): .git

Action: Navigate to git repository or run git init

Detached HEAD State:

HEAD detached at <commit>

Action: Create branch or checkout existing branch

Corrupted Repository:

error: object file .git/objects/... is empty

Action: Try git fsck, may need to restore from backup

Examples

Example 1: Pre-branch creation validation

Context: About to create new feature branch
Action:
1. Check status: git status
2. Verify on main: git branch --show-current
3. Check for uncommitted changes: git status --porcelain
4. Verify remote sync: git status -sb
Output: "Working directory clean, on main, synced with remote - safe to create branch"

Example 2: Detect merge conflicts

Context: Pull resulted in conflicts
Action:
1. Run git status
2. Identify "both modified" files
3. List conflicted files: git diff --name-only --diff-filter=U
4. For each file, read and identify conflict markers
Output: "3 files have conflicts: src/main.py, src/utils.py, src/config.py"

Example 3: Validate before commit

Context: Ready to commit changes
Action:
1. Check branch: git branch --show-current
2. Verify not on main: Ensure branch name != main/master
3. Review changes: git status
4. View diff: git diff
Output: "On feature branch with 5 modified files - safe to commit"

Example 4: Sync status check

Context: Before pushing changes
Action:
1. Fetch remote: git fetch origin
2. Check status: git status -sb
3. If behind: Suggest pull first
4. If ahead: Confirm ready to push
Output: "Local is ahead by 2 commits - ready to push"