How to get the most value out of your git repository
As a beginner programmer, you can be surprised to see that people care so much about what goes into the git repository. Or worst, you can be wholly unaware & do your thing full of:
* fix the bug * another attempt * another attempt 2 * another attempt 2 * finally!
while being judged on it from behind. I check repo history whenever there is a job applicant, and they share a GitHub profile or some example work. My main question is - do they already know to keep the repository neat, or it's something we will have to work on when they join the team.
Why so much fuss?
There is a big difference between a git repository of a mature project and a repository created by an inexperienced developer. In a mature project, you can:
- find a reason to be of a given line while doing
- write a changelog or release notes based on the git history alone
- revert some changes if necessary, with only the conflicts that couldn't be avoided
- get the idea of what was merged by just seeing the
Those uses case appear days or weeks after you merged the changes. If history is a mess, you won't get much of it anyway. As a beginner programmer working on a small project, you won't see much value on your own. Most likely, you will need someone more experienced to point it out to you.
Focus your commit on one thing alone
Good commit does one thing alone. It's tempting to mix different changes, for example:
- update coding style
- implement a change
- implement an unrelated change that happens to be in the same file
Doing this makes two things more complicated than necessary:
- writing short & accurate commit message 2 reverting only one of those changes
Write meaningful commit messages
Think about the reader of your commit message. Even if you work alone, in a few months:
- you can forget everything around the change
- you can have a colleague in the team
Write a short commit message that quickly summarizes what's inside. If you did an excellent job following the previous advice, this should be pretty easy.
Reference ticket or issue
Reference ticket from the commit message if you have an issue tracking system set up for the project (for example, Jira). In this way, whoever will want to understand your changes better will have something to follow. If your project has no such system yet, you can consider setting up some. Both GitHub & GitLab have some available.
Keep your commit messages consistent
When you scan or search through the git log, any inconsistency gets annoying pretty quickly. If some commits are capitalized differently than the rest - they get your attention for the wrong reason. If sometimes the verbs are in the past tense - your search should include both versions. If you want to make a changelog or release info - the inconsistencies will need to be edited before sending it out, and it's just simpler to do it on the commit time.
How to do all of that?
You want to commit locally as often as you see fit. Luckily, you don't have to write a perfect commit message in the first go. Write the commit messages for your work in progress so you can understand at the spot, and later edit them to get the final version. It's best to learn
git rebase, as it's the most flexible method for editing your commits. It can be not very easy at first but knowing it's a good investment in the long term.
As a more straightforward tool, when you have only one commit & want to rephrase the message, you could do it with
git commit --amend.
All that is a step up from the basic pull-commit-push workflow you learn first. Resources I recommend for learning more:
I hope I convinced you to put some effort into creating a meaning full commits. Now, good luck learning how to do it!
Did you find this article valuable?
Support Marcin Wosinek by becoming a sponsor. Any amount is appreciated!