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

bash

# 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

bash

# 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

bash

# 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:

bash

# 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:

bash

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:

bash

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:

bash

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

Branch Workflow

bash

# 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

bash

# 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

bash

# 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

bash

# 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

bash

# 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

bash

# 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

bash

# 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:

bash

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

Cherry-picking

bash

# 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

bash

git checkout main
git merge feature/new-feature

Rebase:

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

bash

git checkout feature/new-feature
git rebase main

Merge Strategies

Fast-forward (default):

bash

git merge feature/branch

No fast-forward (always create merge commit):

bash

git merge --no-ff feature/branch

Squash (combine all commits):

bash

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

Resolving Conflicts

bash

# 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

bash

# 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

bash

# 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

bash

# 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

bash

# 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)

bash

# 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)

bash

# 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

bash

# 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

bash

# 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

Run
```
git status
```
to analyze staged files
Group changes by single responsibility
Unstage unrelated files
Stage only related files together
Review
```
git diff --cached
```
before committing
Write clear, descriptive commit message
Follow conventional commit format
Ensure code builds successfully
Run tests if applicable
Verify commit is independently reviewable

Branch Management

Use descriptive branch names
Keep branches short-lived
Rebase regularly with main
Delete merged branches
Don't commit directly to main

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

bash

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

bash

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

bash

git push --force origin main

Problem: Destroys others' work, breaks history

Fix: Use

--force-with-lease

and only on your branches

❌ Large Binary Files

bash

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

Problem: Bloats repository size forever

Fix: Use Git LFS or external storage

❌ Committing Secrets

bash

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

Problem: Security vulnerability, hard to remove

Fix: Use .gitignore, environment variables, secrets management

❌ Meaningless Messages

bash

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

bash

# 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

bash

# 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 ✅

git-workflow

NPX Install

Tags

SKILL.md Content

Git Workflow & Best Practices

Purpose

When to Use

Core Philosophy

Single Responsibility Rule ⭐

Commit Organization

Analyzing Staged Changes

Grouping Strategies

Division Workflow

Example: Real Scenario

Commit Messages

Conventional Commits Format

Types

Subject Line Rules

Body Guidelines

Examples

Branching Strategy

Branch Naming

Branch Workflow

Branch Management

Staging Operations

Selective Staging

Patch Mode Operations

Unstaging

History Management

Viewing History

Amending Commits

Interactive Rebase

Squashing Commits

Cherry-picking

Merging & Rebasing

Merge vs Rebase

Merge Strategies

Resolving Conflicts

Remote Operations

Working with Remotes

Pull Request Workflow

Advanced Techniques

Stashing

Tagging

Bisect (Finding Bugs)

Reflog (Recovery)

Git Ignore

.gitignore Patterns

Common Ignores

Best Practices Checklist

Before Committing

Branch Management

Commit Quality

Code Review

Anti-Patterns to Avoid

❌ Giant Mixed Commits

❌ Committing Directly to Main

❌ Force Push to Shared Branches

❌ Large Binary Files

❌ Committing Secrets

❌ Meaningless Messages

Quick Reference

Essential Commands

Recovery Commands

Resources