Maintaining Clean Git History in Teams

# Example of messy history
* fix typo
* oops
* work in progress
* more fixes
* actually fix the bug
* temp commit
* final fix

# Good: Atomic commits
git commit -m "feat(auth): add user login functionality"
git commit -m "test(auth): add login integration tests"
git commit -m "docs(auth): update authentication guide"

# Bad: Mixed changes
git commit -m "add login, fix tests, update docs, refactor utils"

# Good commit messages
feat(api): add user profile endpoint
fix(auth): resolve token expiration issue
docs: update installation instructions
refactor(db): optimize user queries
test(payment): add credit card validation tests

# Bad commit messages
fix stuff
update
work in progress
temp

# Good: Logical progression
1. feat(user): add user model
2. feat(user): add user controller
3. feat(user): add user routes
4. test(user): add user API tests
5. docs(user): add user API documentation

# Bad: Random order
1. fix typo in docs
2. add user model
3. temp commit
4. add tests
5. add controller

# 1. Create feature branch from main
git checkout main
git pull origin main
git checkout -b feature/user-authentication

# 2. Work in small, logical commits
echo "User model implementation" > user.js
git add user.js
git commit -m "feat(auth): add user model with validation"

echo "Password hashing logic" >> user.js
git add user.js
git commit -m "feat(auth): implement password hashing"

echo "Login endpoint" > auth.js
git add auth.js
git commit -m "feat(auth): add login endpoint"

# 3. Push feature branch
git push -u origin feature/user-authentication

# 4. Create pull request
gh pr create --title "Add user authentication system" \
  --body "Implements complete user authentication with login/logout"

# 5. Clean up before merge (if needed)
git rebase -i main  # Interactive rebase to clean commits

# 6. Merge with clean history
gh pr merge --squash  # or --rebase depending on team preference

# Initialize git flow
git flow init

# Start feature
git flow feature start user-dashboard

# Work with clean commits
git commit -m "feat(dashboard): add user stats component"
git commit -m "feat(dashboard): add activity timeline"
git commit -m "style(dashboard): improve responsive layout"
git commit -m "test(dashboard): add component unit tests"

# Finish feature (creates merge commit)
git flow feature finish user-dashboard

# Start release
git flow release start 1.2.0

# Prepare release
echo "1.2.0" > VERSION
git add VERSION
git commit -m "chore(release): bump version to 1.2.0"

# Update changelog
echo "## v1.2.0\n- Add user dashboard\n- Improve authentication" > CHANGELOG.md
git add CHANGELOG.md
git commit -m "docs(release): update changelog for v1.2.0"

# Finish release
git flow release finish 1.2.0

# Example: Clean up feature branch before merge
git log --oneline
# a1b2c3d feat(auth): add login endpoint
# e4f5g6h fix typo
# i7j8k9l feat(auth): add password hashing
# m1n2o3p work in progress
# q4r5s6t feat(auth): add user model

# Interactive rebase to clean up
git rebase -i HEAD~5

# In the editor:
pick q4r5s6t feat(auth): add user model
squash m1n2o3p work in progress
pick i7j8k9l feat(auth): add password hashing
pick a1b2c3d feat(auth): add login endpoint
fixup e4f5g6h fix typo

# Result: Clean, logical commits
# q4r5s6t feat(auth): add user model
# i7j8k9l feat(auth): add password hashing
# a1b2c3d feat(auth): add login endpoint

# Before squashing
git log --oneline
# abc123 fix: resolve linting errors
# def456 feat: add user validation
# ghi789 fix: handle edge case in validation
# jkl012 feat: add user registration form

# Squash validation-related commits
git rebase -i HEAD~4

# In editor:
pick jkl012 feat: add user registration form
pick def456 feat: add user validation
squash ghi789 fix: handle edge case in validation
squash abc123 fix: resolve linting errors

# Edit commit message:
# feat: add user registration with validation
#
# - Add registration form component
# - Implement comprehensive user validation
# - Handle edge cases and linting issues

# If you have a large commit that should be split
git log --oneline
# abc123 feat: add user management (too large)

# Reset to split the commit
git reset HEAD~1

# Stage and commit parts separately
git add user-model.js
git commit -m "feat(user): add user model"

git add user-controller.js
git commit -m "feat(user): add user controller"

git add user-routes.js
git commit -m "feat(user): add user routes"

git add user-tests.js
git commit -m "test(user): add user API tests"

# Preserves branch history
git checkout main
git merge feature/user-auth

# Creates merge commit:
# *   Merge branch 'feature/user-auth'
# |\
# | * feat(auth): add login tests
# | * feat(auth): add login endpoint
# | * feat(auth): add user model
# |/
# * Previous main commit

# Good for: Complex features, preserving context
# Bad for: Simple changes, linear history preference

# Combines all feature commits into one
gh pr merge --squash

# Results in:
# * feat(auth): add user authentication system
# * Previous main commit

# Good for: Simple features, clean linear history
# Bad for: Losing detailed commit history

# Replays commits on top of main
git checkout feature/user-auth
git rebase main
git checkout main
git merge feature/user-auth  # Fast-forward merge

# Results in linear history:
# * feat(auth): add login tests
# * feat(auth): add login endpoint
# * feat(auth): add user model
# * Previous main commit

# Good for: Linear history, preserving individual commits
# Bad for: Losing branch context

# Team commit message template
cat > .gitmessage << EOF
# <type>(<scope>): <subject>
#
# <body>
#
# <footer>
#
# Type: feat, fix, docs, style, refactor, test, chore
# Scope: component or file being modified
# Subject: imperative, present tense, no period
# Body: explain what and why vs. how
# Footer: breaking changes, issue references
EOF

# Configure git to use template
git config commit.template .gitmessage

# Feature branches
feature/user-authentication
feature/payment-integration
feature/admin-dashboard

# Bug fix branches
fix/login-validation-error
fix/memory-leak-in-parser
hotfix/critical-security-patch

# Maintenance branches
chore/update-dependencies
chore/improve-test-coverage
refactor/database-optimization

# Documentation branches
docs/api-documentation
docs/installation-guide
docs/contributing-guidelines

<!-- .github/pull_request_template.md -->

## Description

Brief description of changes

## Type of Change

- [ ] Bug fix (non-breaking change which fixes an issue)
- [ ] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
- [ ] Documentation update

## How Has This Been Tested?

- [ ] Unit tests
- [ ] Integration tests
- [ ] Manual testing

## Checklist

- [ ] My code follows the style guidelines
- [ ] I have performed a self-review
- [ ] I have commented my code, particularly in hard-to-understand areas
- [ ] I have made corresponding changes to the documentation
- [ ] My changes generate no new warnings
- [ ] I have added tests that prove my fix is effective or that my feature works
- [ ] New and existing unit tests pass locally
- [ ] Any dependent changes have been merged and published

## Related Issues

Closes #123
References #456

# Pre-commit hook for commit message validation
cat > .git/hooks/commit-msg << 'EOF'
#!/bin/bash

commit_regex='^(feat|fix|docs|style|refactor|test|chore)(\(.+\))?: .{1,50}'

if ! grep -qE "$commit_regex" "$1"; then
    echo "Invalid commit message format!"
    echo "Format: type(scope): description"
    echo "Example: feat(auth): add login functionality"
    exit 1
fi
EOF

chmod +x .git/hooks/commit-msg

# Install conventional-changelog
npm install -g conventional-changelog-cli

# Generate changelog
conventional-changelog -p angular -i CHANGELOG.md -s

# Add to package.json scripts
"scripts": {
  "changelog": "conventional-changelog -p angular -i CHANGELOG.md -s -r 0",
  "release": "npm run changelog && git add CHANGELOG.md && git commit -m 'docs: update changelog'"
}

# .github/workflows/history-check.yml
name: History Check

on:
  pull_request:
    branches: [main]

jobs:
  check-commits:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Check commit messages
        run: |
          # Check all commits in PR
          commits=$(git rev-list --no-merges origin/main..HEAD)

          for commit in $commits; do
            message=$(git log --format=%s -n 1 $commit)
            if ! echo "$message" | grep -qE '^(feat|fix|docs|style|refactor|test|chore)(\(.+\))?: .{1,50}'; then
              echo "❌ Invalid commit message: $message"
              echo "Commit: $commit"
              exit 1
            fi
          done

          echo "✅ All commit messages are valid"

      - name: Check for merge commits
        run: |
          merge_commits=$(git rev-list --merges origin/main..HEAD)
          if [ -n "$merge_commits" ]; then
            echo "❌ Merge commits found in feature branch"
            echo "Please rebase your branch"
            exit 1
          fi

          echo "✅ No merge commits found"

# Multiple developers working on same feature

# Developer A starts feature
git checkout -b feature/user-dashboard
git commit -m "feat(dashboard): add basic layout"
git push -u origin feature/user-dashboard

# Developer B joins
git checkout feature/user-dashboard
git pull origin feature/user-dashboard
git commit -m "feat(dashboard): add user stats widget"
git push origin feature/user-dashboard

# Developer A continues
git pull origin feature/user-dashboard  # Get B's changes
git commit -m "feat(dashboard): add activity timeline"

# Before pushing, rebase to maintain clean history
git pull --rebase origin feature/user-dashboard
git push origin feature/user-dashboard

# Final cleanup before merge
git rebase -i origin/main
# Squash related commits, fix commit messages

# Critical bug in production
git checkout main
git pull origin main
git checkout -b hotfix/critical-security-fix

# Make minimal fix
git commit -m "fix(security): patch XSS vulnerability in user input

Resolves critical security issue where user input was not properly
sanitized, allowing potential XSS attacks.

Fixes #SECURITY-123"

# Test thoroughly
npm test
npm run security-audit

# Fast-track review and merge
gh pr create --title "HOTFIX: Critical security patch" \
  --body "Critical security fix for XSS vulnerability" \
  --label "security,hotfix,priority-critical"

# Merge immediately after review
gh pr merge --squash

# Tag for tracking
git checkout main
git pull origin main
git tag v1.2.1-hotfix
git push origin v1.2.1-hotfix

# Prepare release branch
git checkout main
git pull origin main
git checkout -b release/v2.0.0

# Version bump and changelog
echo "2.0.0" > VERSION
npm run changelog
git add VERSION CHANGELOG.md
git commit -m "chore(release): prepare version 2.0.0"

# Bug fixes during release preparation
git commit -m "fix(release): resolve build issue in production"
git commit -m "docs(release): update migration guide"

# Merge back to develop
git checkout develop
git merge release/v2.0.0

# Merge to main and tag
git checkout main
git merge release/v2.0.0
git tag v2.0.0
git push origin main develop v2.0.0

# Clean up release branch
git branch -d release/v2.0.0
git push origin --delete release/v2.0.0

# Install commitizen
npm install -g commitizen cz-conventional-changelog

# Configure
echo '{ "path": "cz-conventional-changelog" }' > ~/.czrc

# Use instead of git commit
git add .
git cz

# Interactive prompts:
# ? Select the type of change: feat
# ? What is the scope of this change: auth
# ? Write a short description: add login functionality
# ? Provide a longer description: (optional)
# ? Are there any breaking changes: No
# ? Does this change affect any open issues: Yes
# ? Add issue references: Closes #123

# Install semantic-release
npm install --save-dev semantic-release

# Configure .releaserc.json
cat > .releaserc.json << EOF
{
  "branches": ["main"],
  "plugins": [
    "@semantic-release/commit-analyzer",
    "@semantic-release/release-notes-generator",
    "@semantic-release/changelog",
    "@semantic-release/npm",
    "@semantic-release/github"
  ]
}
EOF

# Add to CI/CD pipeline
# Automatically creates releases based on commit history

# Useful aliases for maintaining clean history
git config --global alias.lg "log --color --graph --pretty=format:'%Cred%h%Creset -%C(yellow)%d%Creset %s %Cgreen(%cr) %C(bold blue)<%an>%Creset' --abbrev-commit"

git config --global alias.cleanup "!git branch --merged | grep -v '\*\|main\|develop' | xargs -n 1 git branch -d"

git config --global alias.squash "!f() { git reset --soft HEAD~$1 && git commit --edit -m\"$(git log --format=%B --reverse HEAD..HEAD@{1})\"; }; f"

git config --global alias.fixup "commit --fixup"

git config --global alias.autosquash "rebase -i --autosquash"

# Usage examples
git lg                    # Pretty log
git cleanup              # Remove merged branches
git squash 3             # Squash last 3 commits
git fixup abc123         # Create fixup commit
git autosquash main      # Auto-squash fixup commits

# Clean history commands
git rebase -i HEAD~n              # Interactive rebase last n commits
git commit --amend                # Modify last commit
git reset --soft HEAD~1           # Undo last commit, keep changes
git cherry-pick abc123            # Apply specific commit
git revert abc123                 # Create commit that undoes changes

# Branch management
git checkout -b feature/name      # Create feature branch
git rebase main                   # Rebase current branch on main
git merge --no-ff feature/name    # Merge with merge commit
git merge --squash feature/name   # Squash merge

# History inspection
git log --oneline                 # Compact log
git log --graph                   # Visual branch structure
git show abc123                   # Show specific commit
git diff main..feature/name       # Compare branches

# Cleanup
git branch -d feature/name        # Delete merged branch
git remote prune origin           # Clean up remote references
git gc                            # Garbage collection