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.

⛔ MANDATORY Gate Before Commit

Ask yourself: "If I need to revert ONLY ONE of these changes tomorrow, can I?"

•NO → You have multiple concerns → MUST split into separate commits
•YES → Proceed with single commit

Common trap: "All files are related to the same feature request" is NOT a valid reason to bundle. Each independently revertable change = separate commit.

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

code

<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

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

❌ "Related" Bundling

bash

# Multiple features bundled because "they're all for the same task"
git add src/components/Form.tsx src/components/PDFExport.tsx src/types/ src/config/
git commit -m "feat: add form and PDF export with new field types"

Problem: "Related to same request" ≠ "Same commit". Cannot revert PDF without losing Form.

Test: Can you revert just ONE of these features independently? No? Split it.

Fix:

bash

git add src/config/ src/types/
git commit -m "feat: add field mapping configuration"

git add src/components/Form.tsx
git commit -m "feat: add editable form component"

git add src/components/PDFExport.tsx
git commit -m "feat: add PDF export with bank-style layout"

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