samhvw8 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 statusto 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 featurefix- Bug fixrefactor- Code restructuring (no behavior change)perf- Performance improvementdocs- Documentation onlystyle- Formatting, whitespace, semicolonstest- Adding/updating testschore- Maintenance, dependenciesbuild- Build system changesci- CI/CD configurationrevert- 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 featuresfix/- Bug fixesrefactor/- Code improvementsdocs/- Documentationtest/- Test additionschore/- 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 hunkn- don't stage this hunks- split into smaller hunkse- manually edit hunkq- 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-isreword- change commit messageedit- modify commitsquash- combine with previousfixup- like squash, discard messagedrop- 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
- Run
git statusto analyze staged files - Group changes by single responsibility
- Unstage unrelated files
- Stage only related files together
- Review
git diff --cachedbefore 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
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 ✅