Git Workspace Review

Git Workspace Review

Table of Contents

1. Usage 2. Required Progress Tracking

Verification

Run git status after review to verify workspace state matches expectations.

Testing

Run pytest plugins/sanctum/tests/test_git_workspace_review.py to validate review workflow.

Usage

Use this skill before workflows that depend on repository state, such as commit message generation, PR preparation, or release notes. Run it once per session or whenever staged changes are modified.

Required Progress Tracking

1. git-review:repo-confirmed 2. git-review:status-overview 3. git-review:code-quality-check 4. git-review:diff-stat 5. git-review:diff-details

Mark each item as complete as you finish the corresponding step.

Step 1: Confirm Repository (repo-confirmed)

Run pwd to confirm you are in the correct repository directory. Execute git status -sb to view the current branch and short status, then capture the branch name and upstream information.

Step 2: Review Status Overview (status-overview)

Analyze the git status -sb output for staged and unstaged changes. Stage or unstage files so that subsequent workflows operate on the intended diff.

Step 3: Check Code Quality (code-quality-check)

Run make format && make lint to validate code quality before committing. Fix any errors immediately. Do not bypass pre-commit hooks with --no-verify. This check identifies issues early and avoids late-stage pipeline failures.

Step 4: Review Diff Statistics (diff-stat)

Run git diff --cached --stat for staged changes (or git diff --stat for unstaged work). Note the number of files modified and identify hotspots with large insertion or deletion counts.

When sem is available (see leyline:sem-integration), also run sem diff --format plain --staged to display an entity-level summary alongside the stat output. This shows which functions, classes, and methods changed rather than just line counts.

Step 5: Review Detailed Diff (diff-details)

Run git diff --cached to examine the actual changes. For unstaged work, use git diff. Identify key themes, such as Makefile adjustments or new skill additions, to provide context for downstream summaries.

Exit Criteria

Complete all progress tracking items. You should have a clear understanding of modified files and areas, and the correct work should be staged. Subsequent workflows can then rely on this context without re-executing git commands.

Supporting Modules

• Git commands reference - diff, status, branch operations for sanctum workflows

Troubleshooting

If pre-commit hooks block a commit, resolve the reported issues instead of using --no-verify. Run make format to fix styling errors automatically and use make lint to isolate logical failures. If merge conflicts occur, use git merge --abort to return to a clean state before retrying.

Git Commands for Sanctum Workflows

Repository Confirmation

Verify Working Directory

pwd

validates you are in the correct repository before running git operations.

Check Branch and Status

git status -sb

Shows current branch, upstream tracking, and short status in one line.

Diff Commands

Staged Changes Statistics

git diff --cached --stat

Shows file-by-file statistics for staged changes (insertions/deletions).

Staged Changes Details

git diff --cached

Full diff of staged changes for review before commit.

Unstaged Changes Statistics

git diff --stat

File-by-file statistics for unstaged working directory changes.

Unstaged Changes Details

git diff

Full diff of unstaged working directory changes.

Branch Comparison Statistics

git diff --stat origin/main...HEAD

Shows statistics for all commits in current branch since diverging from main.

Branch Comparison Details

git diff origin/main...HEAD

Full diff of all changes in current branch compared to main.

Status Parsing Patterns

Extract Branch Name

From git status -sb output, the first line shows:

## branch-name...origin/branch-name [ahead N, behind M]

Parse the branch name from the ## line.

Identify Staged vs Unstaged

• Lines starting with M (M-space): staged modification
• Lines starting with M (space-M): unstaged modification
• Lines starting with A (A-space): staged new file
• Lines starting with ??: untracked file

Count Changes

Use --stat output to count affected files:

 file1.md | 10 +++++++---
 file2.py | 5 +++++
 2 files changed, 12 insertions(+), 3 deletions(-)

Branch Operations

Get Merge Base

git merge-base origin/main HEAD

Finds the common ancestor commit for comparison.

List Recent Commits

git log --oneline -10

Shows last 10 commits in compact format.

Show Commit Details

git show <commit-hash>

Displays commit message and diff for a specific commit.

Best Practices

Always Run in Sequence

1. pwd - Confirm location 2. git status -sb - Check branch/status 3. git diff --cached --stat - Review staged stats 4. git diff --cached - Review staged details

Use Limits

• Always limit git log output (e.g., -10, -20)
• Use --stat before full diffs to understand scope
• For large diffs, consider git diff --cached -- <specific-file>

Error Handling

• Check if git status shows "Not a git repository"
• Verify upstream tracking exists before comparing to origin
• Handle empty diffs (no staged changes) gracefully