What Good Commit Hygiene Actually Looks Like for Portfolio Projects

TL;DR

Your commit history is visible on GitHub and reviewers do look at it.
"Initial commit" and "fixed bug" tell a reviewer nothing about how you think.
Good commit messages follow a consistent format and describe the intent behind the change.
Conventional Commits is a widely used standard that's worth learning and using.
A messy git history can be cleaned up before you add a project to your resume.
Branch strategy matters even on solo projects.

When a hiring manager or senior engineer looks at your GitHub portfolio, they're not just reading your code. They're reading how you work. And one of the clearest signals about how you work is your commit history.

Most portfolio projects fail this test immediately. A log full of "initial commit," "updates," "final version," and "ok actually final version" communicates that you treat git as a save button rather than a collaboration tool. That's a signal, and not a good one.

What a reviewer actually sees

Here's what the git log on a typical portfolio project looks like:

abc1234 initial commit
def5678 fixed stuff
ghi9012 added feature
jkl3456 more changes
mno6789 done

And here's what a project with thoughtful commit history looks like:

abc1234 feat: add user authentication with bcrypt and session tokens
def5678 fix: correct redirect loop on failed login attempt
ghi9012 feat: implement post creation with basic markdown rendering
jkl3456 refactor: extract post validation into a dedicated service object
mno6789 test: add unit tests for post validation edge cases
pqr2345 docs: update README with setup instructions and env vars

The second log tells a story. You can see what was built in what order, what went wrong and got fixed, and that the developer treats testing and documentation as part of the work rather than afterthoughts.

That kind of history signals professional habits. It shows you've worked, or have tried to work, the way engineers work on real teams.

The Conventional Commits format

The second example uses Conventional Commits, a widely adopted standard for commit message formatting. It's worth knowing.

The basic format is:

<type>: <short description>

Common types: - feat: A new feature - fix: A bug fix - refactor: Code changes that don't add features or fix bugs (restructuring, renaming, cleanup) - test: Adding or modifying tests - docs: Documentation only changes - style: Formatting, whitespace, no code logic changes - chore: Build process, dependency updates, or other maintenance tasks - perf: Changes that improve performance

Examples: - feat: add pagination to the posts index page - fix: prevent duplicate email registration - refactor: move authentication logic from controller to concern - test: add integration tests for checkout flow - docs: add API endpoint documentation to README

The short description should: - Use imperative mood: "add" not "added," "fix" not "fixed." Think of it as completing the sentence "this commit will..." - Be 50-72 characters maximum. If it's longer, you're describing too much. - Start with a lowercase letter after the colon (by convention). - Not end with a period.

For larger changes, you can add a body after a blank line:

feat: add rate limiting to the API authentication endpoint

Implements token bucket rate limiting using Redis. Limits unauthenticated
requests to 10 per minute and authenticated requests to 100 per minute.
Adds appropriate 429 response with Retry-After header.

The body is optional for small changes but useful when the "why" isn't obvious from the "what."

How to actually write commits while you work

The commit message starts before you type git commit. It starts when you decide what you're going to work on next.

Good commits come from small, focused units of work. If you've been working for two hours and touched eight different files across three unrelated areas, writing a good commit message is hard because you've done three different things at once.

The practice that leads to good commits is committing frequently and intentionally.

Before you start working, decide what one thing you're going to do. Build the login form. Fix the N+1 query. Extract the email service class. Then do that thing, and commit it.

This doesn't mean every tiny change gets its own commit. It means your commits reflect logical units of work rather than time passed.

Branch strategy for solo projects

Many solo portfolio projects are built entirely on main. That works, but branching is worth practicing because it signals you know how teams operate.

A simple approach for a solo project:

Keep main as the stable, deployable branch.
Create a branch for each feature or significant change: feature/user-auth, feature/post-search, fix/session-timeout.
Merge the branch back to main when the work is complete and working.

You don't need to create pull requests against yourself (though you can, and some people do as practice). The point is to show a history where features were developed in isolation and integrated deliberately.

On GitHub, the branch history is visible. Reviewers can see that you worked on feature/payment-integration as a discrete unit of work. That's a positive signal.

Squashing versus preserving history

When you're working on a feature branch, your in-progress commits might look like:

wip: start building the search form
wip: fix search query
wip: actually fix it
fix: search now works but broke pagination
wip: pagination fix attempt

That's normal. That's how work actually happens.

Before you merge to main, you have a choice: squash those commits into a single clean commit, or keep the messy history.

Squashing produces a single commit on main that summarizes the whole feature. The main branch history stays clean and readable. The cost is that you lose the intermediate history.

Keeping the history preserves the whole story of how the feature was built. On team projects, this is sometimes valuable for debugging. On a solo portfolio project, it may just show your "wip" habit.

For portfolio projects, a clean main branch that reflects finished, intentional commits is better than a transparent history of in-progress WIPs. Squash your in-progress commits before merging.

To squash interactively with git:

git rebase -i HEAD~5

This opens an editor showing your last five commits. Change pick to squash (or s) on the commits you want to fold into the previous one. Edit the resulting commit message to describe the complete change.

How to clean up a messy git history before adding a project to your resume

If you have a project with a messy commit history that you want to present well, you have options.

Option 1: Soft reset and recommit

If the project is entirely solo and hasn't been published anywhere that others depend on, you can do a soft reset to the beginning and recommit with better messages. This is essentially rewriting history from scratch.

git reset --soft $(git rev-list --max-parents=0 HEAD)
git commit -m "feat: initial project setup"

This collapses all your commits into one. It loses the full history but presents a clean starting point. From there, you can continue with good habits going forward.

This approach is only appropriate for personal projects. Never rewrite history on shared repositories.

Option 2: Interactive rebase to consolidate and rename

If you want to preserve some of the history but clean it up:

git rebase -i --root

This opens all your commits for editing. You can: - Rename commits (reword) to give them proper conventional commit messages. - Squash adjacent commits about the same thing. - Drop commits that are just noise.

This takes more time but produces a cleaner, honest history rather than a completely fresh one.

Option 3: Start a new repo

For a project that's a complete mess, it's sometimes worth creating a new repository, copying in your code, and making your first commit clean. You lose the git history but start fresh with a professional presentation.

If you do this, make sure the new repo doesn't just have one "initial commit" with everything in it. Take the time to break your project into logical commit chunks, even retroactively.

What to check before linking a project on your resume

Before you add a project to your resume or portfolio audit checklist, check these:

Open git log --oneline on the project. Does it tell a coherent story?
Are there commits that are embarrassing, incoherent, or just "fixed stuff"?
Is there at least one commit that demonstrates each of the main features?
Are the commit types varied? (feat, fix, refactor, test, docs)
Is the main branch clean and deployable?

If the log has five or fewer commits for a project you describe as having "authentication, a REST API, search functionality, and user dashboards," that's a mismatch. Either the project is simpler than it sounds, or your commits are doing too much.

A note on commit frequency over project lifetime

Some reviewers will look at when commits were made, not just what they say. A project where all commits happened on one weekend, then nothing for three months, tells a different story than a project with steady commits over several weeks.

This isn't about gaming the system. It's about how you actually build things. Projects that you develop incrementally over time, adding features, fixing things you noticed, improving based on feedback, naturally produce richer histories.

If you're building portfolio projects specifically for a job search, treat them as ongoing work. Add features. Fix things. Respond to issues you notice. The git history will reflect that.

Commit hygiene as a habit, not a cleanup task

The goal isn't to clean up your commits right before an interview. The goal is to develop the habit of committing intentionally so your projects always tell a coherent story.

This matters beyond the portfolio. On real teams, clear commit messages are how engineers communicate with their future selves and their colleagues. "Why was this changed?" is a question your commit message should be able to answer.

For more on building a GitHub presence that actually helps your job search, see our full GitHub guide. And once your commit history is clean, make sure your README can explain the project to someone who's never seen it.

If you want a structured review of your portfolio projects before you start applying, the portfolio audit guide walks through exactly what reviewers check.