Post cover image provided via xkcd
Git commits are one of the most underrated features of Git. Pause for a moment and think;
When was the last ...
For further actions, you may consider blocking this person and/or reporting abuse
I saw something a co-worker does and I really liked it.
It is as simple as addind the Jira issue number and the short name of the person that did the commit.
Like "841-RickM-bug fixed bug blah blah"
Reading commits from the develop and master branch is pure joy this way. Like, everything makes sense.
Why would you add the user's name? That only takes up room in the short version of the commit message, and you can see their name in the log anyway.
Isn't the author already recorded as part of the commit anyway?
We use BitBucket and Jira and when you add the issue number to the commit it links it in Jira too so you can go directly to the commit in BitBucket. Pretty cool stuff!
Adding the username and / or trello/jira id/hash to your git branch is also pretty helpful in a team environment.
Eg, instead of 'new-bug-fix' ... you can write 'jlyons-idea1234-new-bug-fix'
Cool, that also works like a charm, especially for short commits. On larger ones, you might need to add multiple lines ;)
or split up the long commit into several short ones :)
Of course! Just keep making sure that you can easily navigate through the commit history.
Great article Paul!
I see you value a more fully featured, descriptive commit message. I've worked with a few developers who really push for short, punchy commit messages of <40 characters. I guess the logic is that it will be quick and easy to scan in future but in my opinion, often times you just can't convey what you need to convey in that short of a message.
Another thing I would say is it's important to know when to put something in a commit message and when to put it in project documentation. Sometimes I'll find myself writing something in the commit message and I'll read it back and realise it's much better suited to go in the README.md or similar.
Ideally you'd do both: a concise commit subject that summarises the whole change, and a commit body that explains the why of your change. The body is something people will rarely read, but they'll really appreciate it when it answers their questions (they've likely come to your commit message to clarify something).
eg. this commit.
Excellent article, Paul!
Writing a meaningful git commit message is a good practice because it not only helps in debugging issues later (especially if it's been caused by one's own git commit) but also is one form of effective documentation that can be referred by anyone (e.g: new team-members) to get up-to speed on a project.
While I'm sure there are numerous articles on the internet towards this, here's one I found to add more detail
My commit message workflow
Shreyas Minocha ・ Jun 22 '18 ・ 4 min read
Thanks for the comment and the reference, Vinay!
Nice post, Paul! I've been trying to work out for a while how to introduce developers to using Git in its full capacity, but it's a bit of a chicken and egg problem:
Without writing good commit messages, there's no reason to look at blame/history, since it doesn't have anything to offer
If you're not looking at the history, there's no reason to write good commit messages, and there's no reason to use rebasing to keep a clean history (eg. squashing extraneous "fix" commits)
Without a clean history, tools like
git bisectbecome more pain than it's worth to use, so you don't work with the historyIt's surprising that developers, who generally thrive on learning how things work, don't progress quickly past the "Git is Ctrl-S for code" stage:
Thanks for your response Stephen, I know exactly what you mean. I indulge to the same "fast git commit" thing many times. Unfortunately, developers don't like to adhere to a new way of doing a certain thing "just because" someone told them.
If they see value in it, then they will do it.
So, if they stumble upon a situation where they want to rollback to a certain commit and spend hours finding it, then they will cahnge their minds.
So, the only way of getting them to use a new git style is actually to ask them for baby, incremental steps.
For example, they could try adding the issue tracker id in their commit messages, for a month.
Then, they could also tag the major commits so that there is a way to rollback to a previous version, easily.
These incremental small changes will result in them not complaining about drastically changing their way of work.
Really nice article, thanks a lot Paul!
I would have put the issue tracker id on the first line (ideally at the beginning) to easily find commits related to a specific feature/issue, it's usually the starting point of investigations.
I really like the commit type, I'll try to use it in my own commits, but I disagree with the "test" type. Tests should be added in the commit containing the feature/fix code because if you put tests code in a commit before feature code, a
git bisectcan stop between both commits and lead to broken unit tests. And if you put tests code after the feature code, you can forgot to revert the tests when you need to revert the feature, which will break tests too.The more complex step when doing small and smart commits is to encourage the rest of the team to do the same. This methodology takes time and developers don't often see the real advantage to do it (we don't need to
git bisectevery day). I think the best argument is about Pull Requests: with small and specific commits, rather than reading the whole change which is sometimes really hard, reading commit by commit and skipping the less interesting ones leads to more valuable code reviews. My Pull Requests are often paired with a long description linking to the important commit to read.Very nice article Paul.
I agree that commit message is essential. On first glance, it tells us a lot about commit itself, and it should be made neatly. Fortunately, nowadays most of IDE has excellent support for git. I prefer to look directly into the code and later search for the particular commit. So I omit the stage of looking through commit messages at all. I don't think that my way is the best one, but it helps in case of the mess in commit messages.
I think that more important than meaningful commit message is proper commit body. I mean, devs should avoid committing all changes in one commit and split at every available place. Creation of a commit cost as a little time but can save a lot of time in future, especially when we would like to revert some evil commit from our branch. It'd be much more difficult if we have multiple functionalities changed in one commit. This is a real nightmare!
So,
Cheers
Thanks for your response, Rafal! Totally agree with you on this.
Code readability is much more important than commit messages, and should be first priority ;)
I believe there's at least one more thing missing from the Udacity's commit style guide. There are situations when you improve some existing code by adding a new behavior. (e.g. automatically check a checkbox when a date field is set).
Therefore, I'd probably add "Improve" there too, as some things don't fall into fixing, adding a new feature or refactoring code category
Nice addition, Jakob!
Personally I (definitely not alone in this) found this guide compelling and informative, and I try to follow the Imperative Title, Explanatory Details pattern.
I'm all for good, structured commit messages, but do not see the point of the commit type. It leaves even fewer characters for a meaningful title, and creates friction by being one more thing to think about.
Well, of course it can be omitted if you think that it does not improve commit readability, but it sure is a helpful way of filtering out the commits of a certain type.
I think all of this could be omitted when you've just started a new project and at the early stages. The reasoning is simple: you need small, atomic and well-commented commits to find regressions (mostly), admire the history and to make merges/rebases easier. This is not needed when there's not much code and you only write the most basic subsystems. Actually, I'd argue that making verbose and small commits that early is counterproductive as it distracts from the flow. It might be wrong for big teams and huge tasks but I'm sure it applies to pet and medium-sized projects. My own projects usually start with a big "Initial commit" and a set of huge commits after that, mostly described as "WIP" or so.
Of course, when the groundwork is set the commits should become smaller and more feature/bugfix oriented. It can also be used as a good rule of thumb telling you the project has probably become an MVP or an alpha and is ready to be shown to somebody.
exactly this is something I overlooked ... and this style is truly great to follow ..thanx
The best way to enforce self/team discipline is to automate commit process. I can’t recommend enough github.com/brigade/overcommit
The source xkcd comic used in the cover image is Git Commit.
Would have loved to see more examples, including examples for the body.
What type of commit should I choose when changing styles in css?