GIT History Matters ✌
Having a nice, clean git history is important for many reasons :
- Help understand how a developer proceded to implement a solution and help in code reviews
- Leave clean traces about code snippets and implementations that can be used as examples or starting points in the future
- Helping in cherry-picks, rollbacks and every thing related to versionning
- Understand the evolution of the code
- Quickly detect regressions by making simple compares
To do so we should be more careful about the way we archive our code.
Commit Frequency ⏰ :
It’s up to every developer to judge how often he should commit, but it’s a good practice to try to commit as soon as a unit of work is done.
Commit or Stash 🤔 ?
We should not commit unfinished or bad code when trying to test a different solution or when changing to a different branch.
Rather than committing things like “To be Done later” , “Work in progress” .. and so on, we should use stashing.
https://git-scm.com/docs/git-stash
Commit content 📖 :
Avoid committing too many things at the same time. Try to commit “units” of coherent code.
Commits should be as isolated as it can be.
Examples of “unit of work” :
- Refactoring
- Adding/modifying a service
- Fixing things
- Adding scripts
- Renaming / moving files
When you need to select some lines from a file a leave others use interactice staging : https://git-scm.com/book/en/v2/Git-Tools-Interactive-Staging . This way you may be precise of what to put in your current commit and what to leave for the next ones.
Amend and Squash 🔧 ?
When you need to add some content to your last commit use Amend rather than making a new commit. You may need to force push for that purpose.
https://git-scm.com/docs/git-commit#_options - (search amend)
You can useSquashto simplify your commits or to regroup two commits that are strongly tied to eachother. This action can be done at the end of your developements and before the code review.
https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History (search squash)
Commit messages 📝 :
The commit message should have a structure that answers these three questions :
- What does this commit do ? [mandatory]
=> a general description (with verb in present tense) - What are the details of this commit ? [optionnal]
=> Details (with verbs in past tense) - For what task ? [highly recommended]
=> The related user story (using # in the beginning or in the end)
A good practise is to include the backlog work item id with a hashtag # at the beginning or the end of the commit (personnaly I like to prefix with it)
Example :
Persist
FooinStuff
- Added logs
- Modified XXXX
- fixed unit test YYYY
#11223
The details section of a commit is not mandatory, while the description and the tasks should be.
Avoid commits like :
- Fix Bug
- Test 2
- Screw this ****
- bla bla bla
Make it searchable 🔍 :
Keep in mind that you may want to look for your commits in some time for whatever reason, so keep it “searchable”. By this we mean that some other developer may want to Search for a specific commit from time to time with some key words. Please , help this guy (It might even be the future you! ).
Example :
“Fix timeout issue by introducing a retry mechanism”
Is better than :
“Fix timeout issue”
As we can search in the future for this “retry mechanism” to use it or generalize it.
Master & Hotfix — commits 🚒 :
When there is no task id to link, we should add a suffix to our commits
- For hotfixes we can add “SUPPORT _ commit text”
- The other cases are to be defined.
Tag while you can 📌 :
Tags are very useful for post production follow up. Tag your commits while you can with meaningful versions / text.
Some might say 😏 :
Hey I never looked to git history before, why should I care ?
Well, you should start to care, because it’s important to know what happened in order to handle what’s next. Git history, if done right, can save you from a lot of trouble and complete your understanding of the solution, especially when nobody is there to tell you the story.
Hey, commits are my private things ! Since I’m going to use a squash-merge to master afterwards
Yes, commits can be a “private matter”, but code reviews are not. And since commit messages come with the code reviews, they should be taken into consideration as for the rest. If you’re working in your own repository, then do whatever suits you. But when you work in a public/shared one, you should try your best to bring the clearest code and documentation, thus git history, to your colleagues.
What other people said about git history 📜 :
https://gist.github.com/turbo/efb8d57c145e00dc38907f9526b60f17
Git Cheat sheet & Graphical tools 💻 :
For those fond of shell and black screens :
For those who want to chill :
Respectful IDE like Rider and Visual Studio are also providing some great integrated tools (you can even create your pull request from them, or even pick only some line to commit in a changed file) :
