Git Best Practices for Teams

1. Use the Conventional Commits Format

Conventional Commits provide a standardized format that makes it easy to understand what a commit does at a glance and enables automated changelog generation.

<type>(<scope>): <subject>

[optional body]

[optional footer]

2. Write Meaningful Subject Lines

The first line of your commit message should be clear, concise, and written in imperative mood (as if giving a command).

3. Keep Commits Atomic and Focused

Each commit should represent a single logical change. Avoid mixing multiple unrelated changes in one commit.

• One commit = one purpose (bug fix, feature, refactor, etc.)
• If you use "and" in your commit message, it's probably too big
• Each commit should pass tests and not break the build
• Use git add -p to stage parts of files selectively

Git Flow (Traditional)

Best for teams with scheduled releases and long-lived release branches. Common in enterprise environments.

GitHub Flow (Simplified)

Lightweight branching strategy perfect for continuous deployment and fast-moving teams.

Trunk-Based Development (Modern)

Developers work in short-lived branches (or directly on main) and merge frequently. Requires strong CI/CD and feature flags.

1. Keep PRs Small and Focused

Large PRs are hard to review and take longer to merge. Aim for PRs under 400 lines of code.

2. Write Descriptive PR Titles and Descriptions

Your PR description should answer: What changed? Why? How was it tested?

## What changed
- Added JWT authentication
- Implemented refresh token rotation

## Why
- Security requirement for compliance
- Users complained about frequent logouts

## How tested
- Added 15 unit tests
- Manual testing in staging
- Load tested with 10K users

## Screenshots
[Attach if UI changed]

3. Self-Review Before Requesting Reviews

Go through your own diff line-by-line before hitting "Request Review." Catch obvious mistakes first.

• Remove console.log() and debug code
• Run linters and formatters locally
• Verify all tests pass

Starting a New Feature

# Update your local main branch
git checkout main
git pull origin main

# Create and switch to a new feature branch
git checkout -b feature/user-authentication

# Work on your changes...
git add .
git commit -m "feat(auth): implement JWT authentication"

# Push your branch to remote
git push -u origin feature/user-authentication

# Open a pull request on GitHub/GitLab

Keeping Your Branch Up to Date

# Option 1: Merge (preserves history)
git checkout main
git pull origin main
git checkout feature/your-feature
git merge main

# Option 2: Rebase (cleaner history)
git checkout main
git pull origin main
git checkout feature/your-feature
git rebase main

# If conflicts occur, resolve them, then:
git add .
git rebase --continue

# Force push after rebase (only if needed)
git push --force-with-lease

Fixing Mistakes

# Undo last commit (keep changes)
git reset --soft HEAD~1

# Amend last commit message
git commit --amend -m "New message"

# Discard local changes
git checkout -- filename.txt

# Undo a merge
git merge --abort

# Undo a rebase
git rebase --abort

1. Never Push Directly to Main/Master

Always use pull requests, even for small changes. This ensures code review and maintains a clean history.

2. Don't Rewrite Public History

Avoid force pushing to shared branches. Only rebase or amend commits on your own feature branches.

3. Delete Merged Branches

Clean up merged branches to keep your repository organized. Most Git hosting platforms can do this automatically.

4. Use Branch Protection Rules

Enable branch protection on main to require:

• Pull request reviews before merging
• Status checks to pass (tests, linting)
• Up-to-date branches before merging