---
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:**
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.

---

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