git-workflow

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:

1. Run git status to see all staged files
2. Identify different concerns/features
3. Unstage everything: git reset HEAD
4. Stage files by concern, one group at a time
5. Commit each group with focused message
6. 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

# 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

• Run git status to analyze staged files
• ⛔ GATE: "Can I revert ONLY ONE change independently?" If NO → split commits
• 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

git add .
git commit -m "various changes"

Problem: Impossible to review, revert, or understand

Fix: Divide into atomic commits by concern

❌ "Related" Bundling

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

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

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 ✅