git-workflow

@samhvw8/git-workflow

0 forks

Updated 4/7/2026

Git workflow management with atomic commit principles. Capabilities: commit organization, branching strategies, merge/rebase workflows, PR management, history cleanup, staged change analysis, single-responsibility commits. Actions: commit, push, pull, merge, rebase, branch, stage, stash git operations. Keywords: git commit, git push, git pull, git merge, git rebase, git branch, git stash, atomic commit, commit message, conventional commits, branching strategy, GitFlow, trunk-based, PR, pull request, code review, git history, cherry-pick, squash, amend, interactive rebase, staged changes. Use when: organizing commits, creating branches, merging code, rebasing, writing commit messages, managing PRs, cleaning git history, analyzing staged changes.

Installation

$npx agent-skills-cli install @samhvw8/git-workflow

Claude Code

Cursor

Copilot

Codex

Antigravity

Details

Repositorysamhvw8/dot-claude

Pathskills/git-workflow/SKILL.md

Branchmain

Scoped Name@samhvw8/git-workflow

Usage

After installing, this skill will be available to your AI coding assistant.

Verify installation:

npx agent-skills-cli list

Skill Instructions

name: git-workflow description: "Git workflow management with atomic commit principles. Capabilities: commit organization, branching strategies, merge/rebase workflows, PR management, history cleanup, staged change analysis, single-responsibility commits. Actions: commit, push, pull, merge, rebase, branch, stage, stash git operations. Keywords: git commit, git push, git pull, git merge, git rebase, git branch, git stash, atomic commit, commit message, conventional commits, branching strategy, GitFlow, trunk-based, PR, pull request, code review, git history, cherry-pick, squash, amend, interactive rebase, staged changes. Use when: organizing commits, creating branches, merging code, rebasing, writing commit messages, managing PRs, cleaning git history, analyzing staged changes."

Git Workflow & Best Practices

Purpose

Comprehensive guide for git operations with emphasis on clean history, atomic commits, and professional workflows. Automatically analyzes staged changes and enforces single-responsibility principle.

When to Use

Activate for any git operation:

Committing changes (especially multiple files)
Creating branches
Merging or rebasing
Managing git history
Writing commit messages
Organizing staging area
Code review preparation
Repository management

Core Philosophy

Single Responsibility Rule ⭐

CRITICAL: Before committing, analyze staged changes and divide into atomic commits.

Process:

Run git status to see all staged files
Identify different concerns/features
Unstage everything: git reset HEAD
Stage files by concern, one group at a time
Commit each group with focused message
Repeat until all changes are committed

Why: Makes history reviewable, revertable, and maintainable.

Commit Organization

Analyzing Staged Changes

# Check what's staged
git status

# See file-level summary
git diff --cached --stat

# See detailed changes
git diff --cached

# Check specific file
git diff --cached path/to/file

Grouping Strategies

By Feature:

Auth system changes → one commit
Payment module → separate commit
User profile → another commit

By Layer:

Database migrations → first commit
Backend API → second commit
Frontend UI → third commit
Tests → fourth commit

By Type:

New features (feat)
Bug fixes (fix)
Refactoring (refactor)
Documentation (docs)
Performance (perf)
Tests (test)

By Dependency:

Foundation/infrastructure first
Features that depend on foundation second

Division Workflow

# 1. Analyze current state
git status
git diff --cached --stat

# 2. Unstage everything
git reset HEAD

# 3. Stage first logical group
git add file1.ts file2.ts directory/

# 4. Verify what's staged
git diff --cached --stat

# 5. Commit with focused message
git commit -m "type: concise description"

# 6. Repeat steps 3-5 for remaining groups

Example: Real Scenario

Situation: 29 files staged with mixed concerns

# Before - messy staging
$ git status
Changes to be committed:
  # Trading Styles feature (25 files)
  modified:   src/app/styles/page.tsx
  new file:   src/core/domain/models/TradingStyle.ts
  new file:   src/infrastructure/database/migrations/create_trading_styles.ts
  ...
  # History enhancements (4 files)
  modified:   src/app/history/page.tsx
  modified:   src/app/api/history/recommendations/route.ts
  ...

Solution:

# 1. Reset staging
git reset HEAD

# 2. Commit #1 - Trading Styles feature
git add \
  package.json pnpm-lock.yaml \
  src/app/styles/ \
  src/core/domain/models/TradingStyle.ts \
  src/core/ports/ITradingStyleRepository.ts \
  src/infrastructure/database/TradingStyleRepository.ts \
  src/infrastructure/database/migrations/create_trading_styles.ts

git commit -m "feat: Add trading style persona system for AI-powered analysis"

# 3. Commit #2 - History enhancements
git add \
  src/app/history/page.tsx \
  src/app/api/history/recommendations/route.ts \
  src/infrastructure/database/TimeseriesRepository.ts \
  src/components/layout/AppLayout.tsx

git commit -m "feat: Add comprehensive search and filtering to history page"

Result: Clean, focused commits that are independently reviewable and revertable.

Commit Messages

Conventional Commits Format

<type>(<scope>): <subject>

<body>

<footer>

Types

feat - New feature
fix - Bug fix
refactor - Code restructuring (no behavior change)
perf - Performance improvement
docs - Documentation only
style - Formatting, whitespace, semicolons
test - Adding/updating tests
chore - Maintenance, dependencies
build - Build system changes
ci - CI/CD configuration
revert - Revert previous commit

Subject Line Rules

Use imperative mood: "Add feature" not "Added feature"
Start with lowercase (no capital first letter)
No period at end
50 characters maximum
Be specific and descriptive

Body Guidelines

Explain WHAT and WHY, not HOW
Wrap at 72 characters
Use bullet points for multiple changes
Reference issue numbers: Fixes #123
Include breaking changes

Examples

Good:

git commit -m "$(cat <<'EOF'
feat: add trading style filtering to history page

Implemented comprehensive search and filtering:
- Multi-criteria filtering (action, type, risk, style)
- Partial symbol search with case-insensitive matching
- LEFT JOIN with trading_styles table
- Extended API with new query parameters

Fixes #456
EOF
)"

Bad:

git commit -m "Fixed stuff"
git commit -m "WIP"
git commit -m "Updated files"

Branching Strategy

Branch Naming

Format: type/description-in-kebab-case

Types:

feature/ - New features
fix/ - Bug fixes
refactor/ - Code improvements
docs/ - Documentation
test/ - Test additions
chore/ - Maintenance

Examples:

feature/trading-style-personas
fix/history-filter-bug
refactor/database-queries
docs/api-documentation

Branch Workflow

# Create and switch to new branch
git checkout -b feature/new-feature

# Work on changes
git add ...
git commit -m "..."

# Keep branch updated with main
git fetch origin
git rebase origin/main

# Push to remote
git push origin feature/new-feature

# Create pull request (via GitHub/GitLab UI)

Branch Management

# List all branches
git branch -a

# Switch branches
git checkout branch-name

# Delete local branch
git branch -d branch-name

# Delete remote branch
git push origin --delete branch-name

# Rename current branch
git branch -m new-name

Staging Operations

Selective Staging

# Stage specific files
git add file1.ts file2.ts

# Stage entire directory
git add src/features/

# Stage all changes
git add .

# Stage by file extension
git add *.ts

# Interactive staging (patch mode)
git add -p file.ts

Patch Mode Operations

When using git add -p:

y - stage this hunk
n - don't stage this hunk
s - split into smaller hunks
e - manually edit hunk
q - quit
? - help

Unstaging

# Unstage all files
git reset HEAD

# Unstage specific file
git restore --staged file.ts

# Unstage directory
git restore --staged src/features/

History Management

Viewing History

# Compact history
git log --oneline -10

# Detailed history
git log -5

# With file changes
git log --stat -3

# Specific file history
git log -- path/to/file

# Graph view
git log --oneline --graph --all

# Search commits
git log --grep="search term"

# By author
git log --author="name"

# Date range
git log --since="2 weeks ago"

Amending Commits

# Add forgotten files to last commit
git add forgotten-file.ts
git commit --amend --no-edit

# Change last commit message
git commit --amend -m "new message"

⚠️ Warning: Only amend commits that haven't been pushed!

Interactive Rebase

# Rebase last 3 commits
git rebase -i HEAD~3

# Rebase from specific commit
git rebase -i commit-hash

Options:

pick - keep commit as-is
reword - change commit message
edit - modify commit
squash - combine with previous
fixup - like squash, discard message
drop - remove commit

Squashing Commits

Before pushing:

# Squash last 3 commits
git rebase -i HEAD~3
# Mark commits as "squash" or "fixup"

Cherry-picking

# Apply specific commit to current branch
git cherry-pick commit-hash

# Cherry-pick multiple commits
git cherry-pick hash1 hash2 hash3

Merging & Rebasing

Merge vs Rebase

Merge:

Creates merge commit
Preserves complete history
Use for: integrating feature branches to main

git checkout main
git merge feature/new-feature

Rebase:

Rewrites history, linear timeline
Cleaner history
Use for: updating feature branch with main changes

git checkout feature/new-feature
git rebase main

Merge Strategies

Fast-forward (default):

git merge feature/branch

No fast-forward (always create merge commit):

git merge --no-ff feature/branch

Squash (combine all commits):

git merge --squash feature/branch
git commit -m "feat: merged feature"

Resolving Conflicts

# Check conflict status
git status

# View conflicts
git diff

# After resolving conflicts in editor
git add resolved-file.ts

# Continue rebase
git rebase --continue

# Or abort
git rebase --abort

Remote Operations

Working with Remotes

# View remotes
git remote -v

# Add remote
git remote add origin https://github.com/user/repo.git

# Update remote URL
git remote set-url origin new-url

# Fetch from remote
git fetch origin

# Pull with rebase
git pull --rebase origin main

# Push to remote
git push origin branch-name

# Force push (use carefully!)
git push --force-with-lease origin branch-name

Pull Request Workflow

# 1. Update local main
git checkout main
git pull origin main

# 2. Create feature branch
git checkout -b feature/new-feature

# 3. Make changes and commit atomically
# (following single-responsibility rule)

# 4. Keep branch updated
git fetch origin
git rebase origin/main

# 5. Push to remote
git push origin feature/new-feature

# 6. Create PR via GitHub/GitLab UI

# 7. Address review feedback
git add .
git commit -m "fix: address review comments"
git push origin feature/new-feature

# 8. After PR merged, clean up
git checkout main
git pull origin main
git branch -d feature/new-feature

Advanced Techniques

Stashing

# Stash current changes
git stash

# Stash with message
git stash save "work in progress"

# List stashes
git stash list

# Apply last stash
git stash apply

# Apply and remove stash
git stash pop

# Apply specific stash
git stash apply stash@{2}

# Drop stash
git stash drop stash@{0}

# Clear all stashes
git stash clear

Tagging

# Create lightweight tag
git tag v1.0.0

# Create annotated tag
git tag -a v1.0.0 -m "Release version 1.0.0"

# List tags
git tag

# Push tag to remote
git push origin v1.0.0

# Push all tags
git push origin --tags

# Delete tag
git tag -d v1.0.0
git push origin --delete v1.0.0

Bisect (Finding Bugs)

# Start bisect
git bisect start

# Mark current commit as bad
git bisect bad

# Mark known good commit
git bisect good commit-hash

# Git will checkout middle commit
# Test it, then mark as good or bad
git bisect good  # or git bisect bad

# Repeat until bug is found
# Reset after finding
git bisect reset

Reflog (Recovery)

# View reflog
git reflog

# Recover lost commit
git reset --hard commit-hash

# Recover deleted branch
git checkout -b recovered-branch commit-hash

Git Ignore

.gitignore Patterns

# Ignore file
secret.env

# Ignore directory
node_modules/

# Ignore by extension
*.log

# Ignore except specific file
!important.log

# Ignore in all subdirectories
**/debug.log

Common Ignores

# Dependencies
node_modules/
vendor/

# Build outputs
dist/
build/
*.exe

# Environment
.env
.env.local

# IDE
.vscode/
.idea/
*.swp

# OS
.DS_Store
Thumbs.db

# Logs
*.log
logs/

Best Practices Checklist

Before Committing

Branch Management

Commit Quality

Atomic commits (one concern per commit)
Meaningful commit messages
No WIP or "fix stuff" messages
No commented-out code in commits
No generated files (unless necessary)
No secrets or credentials

Code Review

Small, focused pull requests
Descriptive PR title and description
Reference related issues
Self-review before requesting review
Address all review comments
Keep commits clean during review

Anti-Patterns to Avoid

❌ Giant Mixed Commits

git add .
git commit -m "various changes"

Problem: Impossible to review, revert, or understand

Fix: Divide into atomic commits by concern

❌ Committing Directly to Main

git checkout main
git commit -m "quick fix"
git push

Problem: Bypasses code review, risky

Fix: Always use feature branches

❌ Force Push to Shared Branches

git push --force origin main

Problem: Destroys others' work, breaks history

Fix: Use --force-with-lease and only on your branches

❌ Large Binary Files

git add large-video.mp4
git commit -m "add video"

Problem: Bloats repository size forever

Fix: Use Git LFS or external storage

❌ Committing Secrets

git add .env
git commit -m "add config"

Problem: Security vulnerability, hard to remove

Fix: Use .gitignore, environment variables, secrets management

❌ Meaningless Messages

git commit -m "fix"
git commit -m "update"
git commit -m "wip"

Problem: History is useless for debugging

Fix: Write descriptive, specific commit messages

Quick Reference

Essential Commands

# Status and diff
git status
git diff
git diff --cached
git diff --stat

# Staging
git add file.ts
git add .
git reset HEAD
git restore --staged file.ts

# Committing
git commit -m "message"
git commit --amend

# Branching
git branch
git checkout -b branch-name
git branch -d branch-name

# History
git log --oneline -10
git log --stat
git show commit-hash

# Remote
git fetch origin
git pull --rebase
git push origin branch-name

# Stashing
git stash
git stash pop

Recovery Commands

# Undo last commit (keep changes)
git reset --soft HEAD~1

# Undo last commit (discard changes)
git reset --hard HEAD~1

# Undo changes to file
git restore file.ts

# Recover deleted branch
git reflog
git checkout -b branch-name commit-hash

Resources

Conventional Commits: https://www.conventionalcommits.org/
Git Book: https://git-scm.com/book/en/v2
Oh Shit, Git!: https://ohshitgit.com/

Status: Production-ready ✅ Line Count: ~480 (under 500-line rule) ✅ Coverage: Complete git workflow + atomic commit enforcement ✅

More by samhvw8

View all

design-principles

UI/UX design system for dashboards, admin panels, SaaS interfaces, and web apps. Stack: React, Tailwind, CSS, styled-components. Capabilities: spacing systems (4px grid), color palettes, typography hierarchy, shadows/elevation, card layouts, dark mode, component styling. Actions: design, style, beautify, fix, improve, refactor UI components. Keywords: ugly, inconsistent, cluttered, unprofessional, spacing, padding, margin, colors, fonts, shadows, cards, buttons, forms, navigation, sidebar, layout. Use when: building new UI, fixing ugly interfaces, making things look professional/modern/clean, implementing design systems, styling components, choosing colors/fonts/spacing.

github-search

Search GitHub for repos, code, and usage examples using gh CLI. Capabilities: repo discovery, code search, finding library usage patterns, issue/PR search. Actions: search, find, discover repos/code/examples. Keywords: gh, github, search repos, search code, find examples, how to use library, stars, language filter. Use when: finding repositories, searching code patterns, discovering how libraries are used, exploring open source.

3d-graphics

3D web graphics with Three.js (WebGL/WebGPU). Capabilities: scenes, cameras, geometries, materials, lights, animations, model loading (GLTF/FBX), PBR materials, shadows, post-processing (bloom, SSAO, SSR), custom shaders, instancing, LOD, physics, VR/XR. Actions: create, build, animate, render 3D scenes/models. Keywords: Three.js, WebGL, WebGPU, 3D graphics, scene, camera, geometry, material, light, animation, GLTF, FBX, OrbitControls, PBR, shadow mapping, post-processing, bloom, SSAO, shader, instancing, LOD, WebXR, VR, AR, product configurator, data visualization, architectural walkthrough, interactive 3D, canvas. Use when: creating 3D visualizations, building WebGL/WebGPU apps, loading 3D models, adding animations, implementing VR/XR, creating interactive graphics, building product configurators.

claude-ecosystem

Claude Code ecosystem expertise. Modules: CLI tool (setup, slash commands, MCP servers, hooks, plugins, CI/CD), extensibility (agents, skills, output styles creation), CLAUDE.md (project instructions, optimization). Actions: configure, troubleshoot, create, deploy, integrate, optimize Claude Code. Keywords: Claude Code, Anthropic, CLI tool, slash command, MCP server, Agent Skill, hook, plugin, CI/CD, enterprise, CLAUDE.md, agentic coding, agent, skill, output-style, SKILL.md, subagent, Task tool, project instructions, token optimization. Use when: learning Claude Code features, configuring settings, creating skills/agents/hooks, setting up MCP servers, troubleshooting issues, CI/CD integration, initializing or optimizing CLAUDE.md files.