Git Version Control Best Practices: Commit Discipline, Rebase Workflows, and Repository Security

Why Git Discipline Matters — And Why Most Teams Learn It the Hard Way

Let me tell you about the worst git history I have ever seen. It was a payments service at a Series B fintech. The project had been running for four years. The main branch had 3,400 commits. Roughly 800 of them were "fix", "wip", "asdf", "temp fix again", "ok now for real", and one memorable entry that just said "ugh". The team could not confidently answer a question that should take thirty seconds: when was this behaviour introduced and why?

That is what poor git discipline costs you in practice. Not cleanliness for its own sake — the actual ability to debug production incidents, roll back specific changes safely, understand why a decision was made six months ago, and onboard a new engineer without spending a week explaining which commits actually matter.

Git is not just a backup tool. It is the most complete record of how your software evolved — every decision, every bug, every deliberate trade-off. The teams I have worked with that treat it that way are consistently faster at debugging, safer with deployments, and more effective at code review. The ones that treat it as a "save button" accumulate an archaeology problem that compounds every sprint.

Commit Message Best Practices — Writing for the Engineer Who Debugs This at 2am

When you write a commit message, you are not writing for yourself today. You are writing for yourself eight months from now, for your teammate doing a code review, for the on-call engineer tracing a production issue at 2am who has never seen this part of the codebase.

The single most important rule: the commit message should explain the why, not the what. The diff already shows what changed. The message needs to explain why it changed — what problem this solved, what decision was made, what constraint led to this approach.

None of those tell you anything a diff reader could not figure out in ten seconds. Now compare:

The second set reads like a changelog. Six months from now, a new engineer reading this history understands not just what happened but why, what the trade-off was, and what ticket to reference for more context. That is worth the extra two minutes it takes to write.

The anatomy of a good commit message

Commit message structure
# Subject line — 50 chars or less, imperative mood, no period
feat(auth): add refresh token rotation on every use

# Blank line separating subject from body (required)

# Body — wrap at 72 chars, explain WHY not WHAT
# Use multiple paragraphs for complex changes
Rotating the refresh token on every use prevents replay attacks
where a stolen token can be reused indefinitely. The old token
is invalidated immediately when a new one is issued.

# Footer — reference issues, breaking changes, co-authors
Closes #923
BREAKING CHANGE: clients must store and send the new refresh token
returned in each /auth/refresh response

Conventional Commits — The Standard That Actually Stuck

I resisted Conventional Commits for two years. It felt like ceremony — a format requirement layered on top of what I was already doing. Then I set up automated changelog generation and semantic versioning for a library project, and the format stopped feeling like overhead and started feeling like a decision that pays dividends continuously.

The specification is simple. Every commit message starts with a type:

Conventional Commits — type reference
feat     → new feature (triggers minor version bump)
fix      → bug fix (triggers patch version bump)
docs     → documentation only
style    → formatting, whitespace (no logic change)
refactor → code change that is neither a fix nor a feature
test     → adding or correcting tests
chore    → maintenance: dependency updates, build changes
ci       → CI/CD configuration
perf     → performance improvement
revert   → reverting a previous commit

# Scope (optional) — what part of the codebase
feat(auth): ...
fix(payments): ...
refactor(user-service): ...

# Breaking change — append ! or add BREAKING CHANGE in footer
feat(api)!: change response format for /users endpoint
# → triggers MAJOR version bump in semantic versioning

What this unlocks in practice: release-please and semantic-release read your commit history and automatically determine the next version number, generate a changelog, and create a GitHub release. Zero manual work. The changelog is accurate because it is generated from commits that actually describe what changed. This is not theoretical — I run this on three active projects right now.

Creating Focused Commits — One Logical Change Per Commit

The other half of commit discipline is scope. A commit should represent one logical change — not one file, not one hour of work, not one feature branch. One logical change. If you cannot describe what a commit does in a single sentence without using "and", it probably should be two commits.

The practical tool for creating focused commits when you have been working in chunks: git add -p. It lets you stage individual hunks of changes rather than entire files, so you can commit "refactor the validation logic" separately from "add the new endpoint" even if you wrote both in the same coding session.

Shell · stage specific changes, not whole files
# Interactive patch staging — choose which hunks to stage
git add -p

# Stage a specific file section
git add -p src/PaymentService.java

# Review exactly what you are about to commit
git diff --staged

# Amend the last commit if you forgot something small
# Only if not yet pushed to shared branch
git commit --amend --no-edit

Branching Strategies — Choosing One and Actually Following It

The branching strategy debate — GitFlow vs GitHub Flow vs trunk-based development — generates more heat than it deserves. The right answer is almost always: whatever your team will actually follow consistently. An imperfect strategy followed religiously beats a perfect one followed inconsistently every time.

That said, my honest opinion after seeing all three in production:

Trunk-based development (what I use)

Everyone commits to main frequently — ideally multiple times per day — using short-lived feature branches or feature flags for in-progress work. No long-lived branches. No merge conflicts that accumulate for two weeks. Requires strong CI and feature flags but produces the cleanest history and the fastest feedback loops.

GitHub Flow (sensible default)

One protected main branch. Feature branches created for each piece of work, merged via PR. Simple, clean, works for most teams. The only problem: undisciplined teams let feature branches live for three weeks and then have a merge conflict nightmare.

GitFlow (use sparingly)

Develop → feature branches → release branches → main → hotfix branches. Was designed for software with scheduled releases and multiple supported versions. If you are doing continuous deployment, GitFlow is overhead, not value. I have helped three teams migrate away from GitFlow to GitHub Flow and each one said they wished they had done it sooner.

Naming branches consistently matters more than you think. When a repository has branches named priya-work, new-feature-v2-final, test123, and john-payment-thing, nobody knows what is active versus abandoned. Agree on a pattern and enforce it:

Branch naming conventions — agree on one, use it always
feat/JIRA-123-user-authentication
fix/JIRA-456-null-payment-handler
chore/update-spring-boot-3.3
hotfix/critical-payment-timeout
docs/api-authentication-guide
refactor/extract-token-validation

Rebase vs Merge — The One Distinction That Actually Matters

The rebase vs merge discussion is often presented as a philosophical debate about history purity. I prefer to think about it as a practical question: who is going to read this history, and what do they need to understand from it?

Merge preserves the complete truth of what happened — this branch was created from commit X, developed over three days, and merged at commit Y. You can see exactly when branches diverged and came back together. The history is accurate but can become a dense graph when many branches are active simultaneously.

Rebase rewrites the feature branch commits as if they were written on top of the current main — giving you a linear history that reads like a clean narrative, but one that technically rewrites what happened. The original branch structure disappears.

Shell · the workflow I actually use daily
# Update your feature branch with main changes — rebase, not merge
git checkout feat/JIRA-123-auth
git fetch origin
git rebase origin/main   # replay your commits on top of latest main

# If conflicts arise during rebase:
git status               # see which files conflict
# resolve conflicts in editor
git add resolved-file.java
git rebase --continue    # continue the rebase

# Or abandon the rebase if things get complicated
git rebase --abort       # safely returns to pre-rebase state

Interactive Rebase — Your Commit History Time Machine

Interactive rebase is the feature that separates developers who think about their commit history from those who do not. It lets you rewrite the last N commits — squash them together, reorder them, edit their messages, or drop them entirely — before sharing your work.

I use it every single time before opening a PR. My working commits during development look like: "wip checkpoint", "try different approach", "fix typo in previous", "ok actually working now". Before review, I use interactive rebase to turn those into 2–3 clean, logical commits that actually tell a coherent story.

Shell · interactive rebase — clean up last 5 commits before PR
git rebase -i HEAD~5

# Git opens your editor with this:
pick a1b2c3d feat: add payment processor integration
pick b2c3d4e wip checkpoint
pick c3d4e5f fix typo in previous commit
pick d4e5f6g try different approach to error handling
pick e5f6g7h ok actually working now

# Change to:
pick a1b2c3d feat: add payment processor integration
squash b2c3d4e wip checkpoint
squash c3d4e5f fix typo in previous commit
reword d4e5f6g fix(payments): handle timeout with exponential backoff
drop e5f6g7h ok actually working now

# Commands available:
# pick   = use commit as-is
# reword = use commit, but edit the message
# squash = merge into previous commit, combine messages
# fixup  = merge into previous commit, discard this message
# drop   = remove commit entirely
# reorder lines to reorder commits

Pull Request Best Practices — Making Review Actually Useful

A pull request is not a code dump with a "please review" label. It is a request for a conversation — and the quality of that conversation depends almost entirely on how well you set it up for the reviewer.

Writing a PR description that does not waste reviewer time

Every PR description should answer three questions before the reviewer looks at a single line of code:

1. What does this change? — One or two sentences, plain English
2. Why was this change needed? — Link to the ticket, explain the problem being solved
3. How should I test or verify this? — Steps to reproduce the old behaviour, steps to verify the new behaviour

Markdown · PR description template I use on every team
## What this PR does
Adds idempotency key support to all payment API calls to prevent
duplicate charges on client retry. Resolves #1847.

## Why
We had 3 incidents in Q4 where network timeouts on the client side
caused retried requests to create duplicate charges. Gateway logs
showed the original request was processing while the retry arrived.

## How to test
1. Run PaymentIntegrationTest — all 23 tests should pass
2. Use the sandbox environment to simulate a timeout:
   `SIMULATE_TIMEOUT=true ./gradlew test --tests PaymentTimeoutTest`
3. Check gateway logs for idempotency key in request headers

## Screenshots / Evidence
[Link to sandbox test run showing no duplicate charge]

## Checklist
- [x] Unit tests added for idempotency logic
- [x] Integration test covers timeout scenario
- [x] CHANGELOG updated
- [ ] Docs updated (N/A — internal change)

PR size — the rule nobody enforces until it is too late

A PR with 500+ lines of changes gets rubber-stamped. Not because reviewers are lazy — because the human brain cannot hold the context of 500 lines simultaneously and still spot subtle logic errors. Small PRs get better reviews. I aim for under 300 lines. If a change is larger, I break it into a chain of PRs that each build on the last.

Git Recovery — Undoing Mistakes Without Making Them Worse

Everyone breaks something in git eventually. The skill is knowing how to recover without panicking and making it worse. Here is the toolkit I reach for in each situation:

Shell · recovery toolkit — from least to most drastic
# Undo the last commit but keep the changes staged
git reset --soft HEAD~1

# Undo the last commit and unstage changes (files unchanged)
git reset HEAD~1

# Undo the last commit and discard all changes (DESTRUCTIVE)
git reset --hard HEAD~1
# ⚠ Only on commits not yet pushed to shared branch

# Safely undo a commit on a shared branch — creates a new commit
git revert abc123        # reverts that specific commit
git revert HEAD~3..HEAD  # reverts last 3 commits

# Recover a file deleted by mistake
git checkout HEAD -- path/to/file.java

# Find a commit you accidentally dropped
git reflog               # shows every HEAD movement — commits do not disappear
git checkout abc123      # go back to any point in reflog

# Stash work in progress before switching branches
git stash push -m "wip: payment timeout handling"
git stash list
git stash pop            # apply most recent stash

# Recover a stash after accidentally dropping it
git fsck --unreachable | grep commit | cut -d ' ' -f3 | xargs git stash drop

Repository Security — The Part Most Teams Skip Until Something Goes Wrong

Repository security is the part of git practice that teams do not think about until a credential leaks into a public repo or a disgruntled ex-employee pushes to main. By then the conversation has moved from "best practice" to "incident response".

The security surface area for a git repository is larger than most teams realise: commit history (which is permanent and often public), branch permissions (which control who can merge to main), deploy keys (which give CI access to production), and the contents of configuration files that get committed accidentally.

Here is what I verify on every repository I am responsible for:

• Branch protection on main: require PR reviews, require status checks to pass, disallow force pushes, require signed commits
• Secret scanning enabled: GitHub Advanced Security or a third-party tool that alerts on credential patterns in commits
• CODEOWNERS file: ensures domain experts review changes to critical paths
• Deploy key rotation: CI/CD credentials rotated quarterly, stored in a secrets manager not hardcoded in pipeline YAML
• Repository access audit: quarterly review of who has write or admin access — people leave teams but their access often stays

Secret Detection and Credential Management — Stop the Leak Before It Happens

Secrets committed to git are a top-three cause of security incidents for software companies. The pattern is always the same: a developer adds a real API key or database password to a configuration file during local development, forgets to remove it, commits it, and pushes. If the repository is public — or ever becomes public — the secret is compromised within seconds. Automated scanners index GitHub for leaked credentials continuously.

Shell · install and configure Gitleaks pre-commit hook
# Install gitleaks
brew install gitleaks          # macOS
# or download binary from github.com/gitleaks/gitleaks

# Scan current repo for secrets (before pushing)
gitleaks detect --source . --verbose

# Scan git history (finds secrets in old commits too)
gitleaks detect --source . --log-opts="--all"

# Add as pre-commit hook — runs automatically before every commit
cat > .git/hooks/pre-commit << 'EOF'
#!/bin/sh
gitleaks protect --staged --verbose
if [ $? -ne 0 ]; then
  echo "❌ Gitleaks found potential secrets. Commit blocked."
  exit 1
fi
EOF
chmod +x .git/hooks/pre-commit

Shell · if a secret was already committed — the full recovery process
# Step 1: IMMEDIATELY rotate the secret — it is compromised regardless
# Changing git history does not uncompromise a secret that was pushed.

# Step 2: Remove the file from ALL of git history
pip install git-filter-repo
git filter-repo --path config/secrets.properties --invert-paths

# Step 3: Force-push all branches
git push origin --force --all
git push origin --force --tags

# Step 4: Ask all collaborators to re-clone the repository
# Their local copies still have the old history

# Step 5: Add to .gitignore immediately
echo "config/secrets.properties" >> .gitignore
echo "application-prod.yml" >> .gitignore

Branch Protection and CODEOWNERS — Making the Right Thing the Default

Branch protection and CODEOWNERS are the git configuration changes with the highest impact-to-effort ratio I know of. Thirty minutes of setup that prevents classes of mistakes indefinitely.

Branch protection rules — what to enable on main

GitHub · branch protection settings via API or UI
# Via GitHub CLI
gh api repos/{owner}/{repo}/branches/main/protection \
  --method PUT \
  --field required_status_checks='{"strict":true,"contexts":["ci/tests","ci/security"]}' \
  --field enforce_admins=true \
  --field required_pull_request_reviews='{"required_approving_review_count":2}' \
  --field restrictions=null

# What each setting does:
# required_status_checks: CI must pass before merge is allowed
# enforce_admins: rules apply to admins too (important — without this,
#   admins can bypass rules and "just quickly push to main")
# required_approving_review_count: 2 reviewers required
# allow_force_pushes: false (protect history)
# allow_deletions: false (protect branch from deletion)

CODEOWNERS — automatic review assignment for critical paths

.github/CODEOWNERS · example for a microservices repo
# Default owner for everything not matched below
*                           @engineering-leads

# Payment service — any change requires payments team review
/src/main/java/payments/    @payments-team

# Security-sensitive configuration
/src/main/resources/security/  @security-team @payments-team
*.jks                           @security-team
**/SecurityConfig.java          @security-team

# CI/CD pipeline changes — require platform team sign-off
/.github/workflows/             @platform-team
/Dockerfile                     @platform-team
/docker-compose*.yml            @platform-team

# Database migrations — irreversible, require DBA review
/src/main/resources/db/migration/  @dba-team @backend-leads

# Docs — no approval required beyond the author
/docs/                          @documentation

The CODEOWNERS file becomes particularly valuable as teams grow. Before it, a new engineer could modify the payment processing logic in a PR reviewed only by another new engineer who happened to be online. After it, that same PR automatically requests the payments team — who know that a particular edge case matters and would have been missed otherwise.

Git Configuration for Developers — The Setup Most People Never Do

Most developers use the default git configuration they got when they first installed git. There are a handful of settings that significantly improve the daily experience — none of them are obvious from the documentation.

Shell · ~/.gitconfig — my personal configuration with explanations
[user]
  name = Priya Singh
  email = priya@company.com
  signingkey = YOUR_GPG_KEY_ID  # sign commits for verified status on GitHub

[core]
  editor = code --wait          # VS Code as git editor (or vim, nano)
  autocrlf = input              # Unix line endings on macOS/Linux
  pager = delta                 # prettier diffs (install: brew install git-delta)

[commit]
  gpgsign = true                # sign all commits — shows "Verified" on GitHub

[pull]
  rebase = true                 # git pull does rebase not merge by default

[push]
  default = current             # push current branch to same name on remote
  autoSetupRemote = true        # auto-create remote branch on first push

[rebase]
  autoStash = true              # auto-stash uncommitted changes before rebase

[diff]
  algorithm = histogram         # better diff algorithm — fewer false conflicts

[merge]
  conflictstyle = zdiff3        # shows common ancestor in conflict markers

[alias]
  # Shortcuts I use dozens of times per day
  st = status -sb
  lg = log --oneline --graph --decorate --all
  last = log -1 HEAD --stat
  undo = reset HEAD~1 --mixed
  fixup = commit --fixup
  branches = branch -a --sort=-committerdate  # most recently used first

  # Show what changed in the last commit
  show-last = diff HEAD~1..HEAD

Git Workflow for a Real Development Team — What Actually Happens Monday to Friday

Describing git theory is easy. Describing what the daily workflow actually looks like for a team of eight engineers building a microservices platform — that is what makes the practices real.

Here is the actual workflow my current team uses, Monday to Friday:

Shell · the daily git workflow — start of day
# Morning: sync with main before starting new work
git checkout main
git pull --rebase origin main   # rebase preserves clean history

# Create a branch for the day's work
git checkout -b feat/JIRA-892-add-audit-logging

# Work in small increments — commit frequently, clean up before PR
git add -p                      # stage specific changes, not whole files
git commit -m "wip: initial audit logger structure"

# Keep branch current as main moves (at least once per day)
git fetch origin
git rebase origin/main

# End of day — push work-in-progress, even if not ready for review
git push origin feat/JIRA-892-add-audit-logging
# This backs up your work and signals to teammates what is in progress

Shell · before opening a PR — the cleanup ritual
# 1. Rebase onto latest main one final time
git fetch origin
git rebase origin/main

# 2. Review your commits — are they logical and clean?
git log --oneline origin/main..HEAD

# 3. Interactive rebase to clean up
git rebase -i origin/main

# 4. Run full test suite locally before pushing
./gradlew test

# 5. Push and open PR
git push --force-with-lease origin feat/JIRA-892-add-audit-logging
# --force-with-lease is safer than --force:
# it fails if someone else pushed to your branch since your last pull

Git Best Practices Checklist — Before Every PR, Every Week, Every Quarter

• Commit messages explain why, not just what — the diff already shows what Every commit
• Using Conventional Commits format: type(scope): description Every commit
• Each commit is a single logical change — can be described in one sentence without "and" Every commit
• Ran git rebase -i to clean up WIP commits before opening PR Before PR
• PR description answers: what, why, and how to test Before PR
• PR is under 300 lines of change — or broken into a chain if larger Before PR
• Feature branch rebased onto latest main before PR opened Before PR
• All CI checks passing — tests, SAST, dependency scan Before PR
• Gitleaks or similar secret scanner installed as pre-commit hook Repo setup
• Branch protection enabled on main: required reviews, required CI, no force push Repo setup
• CODEOWNERS file in place for security-sensitive and payment-related paths Repo setup
• Commit signing configured: gpgsign = true in gitconfig Developer setup
• .gitignore covers: application-prod.yml, *.env, *.jks, *.p12 Repo setup
• Quarterly access review: who has write/admin access to production repos Quarterly
• Deploy keys and CI tokens rotated: review expiry dates Quarterly
• Repository secret scanning enabled (GitHub Advanced Security or equivalent) Always on

---

Frequently Asked Questions

Useful Git Resources

The git documentation is excellent but dense. Here is what I actually recommend to engineers who want to go deeper:

• LearnHubly Git Cheatsheet — every command in this article, searchable and copy-ready. The one tab I keep open when working.
• GitHub API Playground — inspect pull requests, repository metadata, and branch protection settings directly in the browser using the GitHub REST API.
• conventionalcommits.org — the full Conventional Commits specification with examples.
• Pro Git book (free) — chapters 3 (branching), 7 (advanced tools), and 10 (internals) are worth reading end-to-end.
• Gitleaks — secret detection tool with pre-commit hook support.
• git-filter-repo — the correct tool for removing files from git history (preferred over the deprecated git filter-branch).