git-state-validator

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.

⭐2stars🔀0forks📁View on GitHub🕐Updated Nov 25, 2025

When & Why to Use This Skill

The Git State Validator is a specialized Claude skill designed to automate the verification of Git repository health and status. It streamlines the development workflow by detecting merge conflicts, validating branch relationships, and ensuring a clean working directory before critical operations like merging, switching branches, or pushing code. By providing machine-readable status interpretations and health checks, it helps developers and AI agents prevent common version control errors and maintain repository integrity.

Use Cases

  • Pre-operation Safety Check: Automatically verify if the working directory is clean and identify uncommitted changes before switching branches or creating new ones to prevent data loss.
  • Conflict Detection and Resolution: Rapidly identify files with merge conflicts and locate specific conflict markers (<<<<<<< HEAD) after pull or merge operations to facilitate faster resolution.
  • Remote Synchronization Audit: Compare local and remote branch states to determine if the repository is ahead or behind the origin, ensuring the developer is working on the most up-to-date code before pushing.
  • Branch Integrity Validation: Confirm that the current feature branch is correctly based on the main branch and perform deep repository health checks (git fsck) to detect corrupted objects or broken links.
namegit-state-validator
descriptionCheck 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"