git-state-validator

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

```bash

git status

```

1. 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

1. Get Machine-Readable Status

```bash

git status --porcelain

```

Prefixes:

- M - Modified

- A - Added

- D - Deleted

- ?? - Untracked

- UU - Merge conflict

#### Validate Branch State

1. Get Current Branch

```bash

git branch --show-current

```

1. Check if on Main

```bash

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

```

1. Get Branch List

```bash

git branch -a

```

- Local branches (no prefix)

- Remote branches (remotes/origin/...)

1. Check Branch Relationship

```bash

git merge-base --is-ancestor main HEAD

```

Exit code 0: Current branch is based on main

#### Detect Conflicts

1. Check for Conflict Markers

```bash

git diff --check

```

1. List Conflicted Files

```bash

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

```

1. View Conflict Details

```bash

git status

```

Look for "both modified" or "both added"

1. Analyze Conflict Markers

Search files for:

```

<<<<<<< HEAD

=======

>>>>>>> branch-name

```

#### Check Remote Sync Status

1. Fetch Remote State (without merging)

```bash

git fetch origin

```

1. Compare with Remote

```bash

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

1. View Unpushed Commits

```bash

git log origin/main..HEAD --oneline

```

1. View Unpulled Commits

```bash

git log HEAD..origin/main --oneline

```

#### Validate Repository Health

1. Check Repository Integrity

```bash

git fsck --full

```

1. Verify Object Database

```bash

git count-objects -v

```

1. Check for Corrupted Objects

```bash

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

```

Interpretation: Local has 3 commits not pushed to remote

#### Behind Remote

```

$ git status -sb

```

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

```

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

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"

```