Commit messages are not titles(antirez.com)
antirez.com
Commit messages are not titles
http://antirez.com/news/90
172 comments
Whenever I see a convention like this, I think to myself, “There is another data model being serialized into text.”
Great observation, though it's not a bad thing, necessarily (assuming you were even implying that it was).
In fact, it could be a very good thing, especially if the alternative is, eg, dropdowns for type and scope, and a separate popup for editing or adding new ones, and so on.
Having the data model loosely encoded as text, and understood only by convention among humans, who can then improvise changes to that model in exceptional cases, relying on other humans to make sense of those changes even though they are "outside" the agreed-upon model, is sometimes exactly what you want.
Also, as UI for input, text is often the fastest and most efficient -- again, just what you want. Of course, you could always do string validation on the text input to enforce your model, so this can be considered an orthogonal point.
And these considerations don't even touch upon the increased complexity and maintenance costs that your tool itself (in this case, git) will incur if it takes on the burden of maintaining the data model explicitly.
In fact, it could be a very good thing, especially if the alternative is, eg, dropdowns for type and scope, and a separate popup for editing or adding new ones, and so on.
Having the data model loosely encoded as text, and understood only by convention among humans, who can then improvise changes to that model in exceptional cases, relying on other humans to make sense of those changes even though they are "outside" the agreed-upon model, is sometimes exactly what you want.
Also, as UI for input, text is often the fastest and most efficient -- again, just what you want. Of course, you could always do string validation on the text input to enforce your model, so this can be considered an orthogonal point.
And these considerations don't even touch upon the increased complexity and maintenance costs that your tool itself (in this case, git) will incur if it takes on the burden of maintaining the data model explicitly.
I agree.
The UX exists for the reader, the data model for the programmer. Sometimes, text is the best UX. For example, I love Markdown, a classic example of a data model serialized as text. I do not want a “rich editor” that speaks the data model directly.
The UX exists for the reader, the data model for the programmer. Sometimes, text is the best UX. For example, I love Markdown, a classic example of a data model serialized as text. I do not want a “rich editor” that speaks the data model directly.
Not exactly. The actual commit content is in the code difference. Code message is just some kind of human-readable abstract, or at least - a hit of what was changed.
There is a big deal of subjectivity (e.g. what is a bug, and what is a feature) but (as with any comments in the code) it is nice to see at least what was intended (e.g. someone wanted to position a misaligned button, or added it, or improved its visuals or optimized its click from O(n!) to O(1), ...).
There is a big deal of subjectivity (e.g. what is a bug, and what is a feature) but (as with any comments in the code) it is nice to see at least what was intended (e.g. someone wanted to position a misaligned button, or added it, or improved its visuals or optimized its click from O(n!) to O(1), ...).
The code message is metadata, like the commit hash, date and author. It could easily be split up into different fields.
> what is a bug, and what is a feature)
Well, for starters I wouldn't have a commit message stating that I just added a bug, though I might have one stating that I added a feature. :P
Well, for starters I wouldn't have a commit message stating that I just added a bug, though I might have one stating that I added a feature. :P
So very true. And I struggle with this. "Why should I write something out when tools could do it for me? Isn't me specifying it, then, just me being overly verbose?" But tools often don't - and may never.
I'm curious:
In any tool for any revision control system ever: in a list of commits, are the commit messages augmented with something useful beyond the basics? ("Basics" being e.g. the first 'n' characters of the human-provided commit message, a revision identifier, a timestamp, and a username.)
I'm curious:
In any tool for any revision control system ever: in a list of commits, are the commit messages augmented with something useful beyond the basics? ("Basics" being e.g. the first 'n' characters of the human-provided commit message, a revision identifier, a timestamp, and a username.)
I can vaguely remember that PVCS had a way of explicitly linking tickets to commits, TFS probably has this as well.
Github has a way of linking issues with commits. You just mention the issue in the commit e.g. 'This commit closes #1' and i believe the issue will close with that as well, but it will show up in the issue.
Jira and other ticketing systems can often read repos and look for ticket ids. In my commits at work I just mention PRJCTNAME-142 and that'll link to a ticket and aggregate in jira all the commits/pull requeusts/branches... tagged with that
Jira and other ticketing systems can often read repos and look for ticket ids. In my commits at work I just mention PRJCTNAME-142 and that'll link to a ticket and aggregate in jira all the commits/pull requeusts/branches... tagged with that
Our internal system has some integration between Jira and Github, such that if you comment a commit with the ticket number then you can see them all in the Jira ticket.
RTC works like that. You can also set up rules so that you can't even check in without linking a ticket.
that tool would have to be quite specialized though and needs to enforce test driven development... how else could it check different benchmarks?
I just see that as friction. Now a developer who is working on a new feature is reluctant to take opportunities to refactor incase their commit message doesn't match the "standard". Empower the developer and reduce friction to a minimum is my modus operandi.
Plus commit often and plan commits: with the example above the commit messages themselves are becoming a chore. Just make the message meaningful and link it to a JIRA issue or something. That's simple enough for me.
Plus commit often and plan commits: with the example above the commit messages themselves are becoming a chore. Just make the message meaningful and link it to a JIRA issue or something. That's simple enough for me.
> Now a developer who is working on a new feature is reluctant to take opportunities to refactor incase their commit message doesn't match the "standard".
Having maintained a few projects on Github, I routinely reject commits that both introduce new features and fix/refactor things. Refactoring is good, but jumping on a project and changing everything at once is a strong indicator of a lack of focus. The "fix some of everything" commits usually lack tests and documentation updates which wouldn't have been overlooked if the contributor took a step away and looked at the big picture.
Having maintained a few projects on Github, I routinely reject commits that both introduce new features and fix/refactor things. Refactoring is good, but jumping on a project and changing everything at once is a strong indicator of a lack of focus. The "fix some of everything" commits usually lack tests and documentation updates which wouldn't have been overlooked if the contributor took a step away and looked at the big picture.
Adding a new feature is the main reason you'd want to refactor something. Refactoring for its own sake is nice in theory, but ain't nobody got time for that. If you are doing real refactoring in a practical setting, it's probably a situation like adding a feature that closely parallels an existing one and now some of the stuff the old feature does can be factored out.
Refactoring is often done in order to implement a new feature, but that doesn't mean they need to be done in the same commit. A common workflow is to be implementing something, realize a refactor is needed, "git stash", refactor, commit, "git stash pop", continue feature work.
I'm a fan of creating two commits in that case:
- Refactor to prepare for Feature X - Implement Feature X
Note that these can be written in parallel, but just submitted as two separate commits (guess which side of the history editing debate I come down on :) )
- Refactor to prepare for Feature X - Implement Feature X
Note that these can be written in parallel, but just submitted as two separate commits (guess which side of the history editing debate I come down on :) )
> I just see that as friction. Now a developer who is working on a new feature is reluctant to take opportunities to refactor incase their commit message doesn't match the "standard". Empower the developer and reduce friction to a minimum is my modus operandi.
Honestly those commits should probably be split anyway. A commit should represent the smallest 'change' which is singificant.
Honestly those commits should probably be split anyway. A commit should represent the smallest 'change' which is singificant.
>Honestly those commits should probably be split anyway. A commit should represent the smallest 'change' which is singificant.
Which again may result in that refactoring never getting done. Many times I've found myself saying to myself "I must refactor this class.. But I'll just finish implementing this feature first so that I can get a clean commit with only the refactoring afterwards". Suddenly it's 5 o'clock and tomorrow I've forgotten about the refactoring need.
Which again may result in that refactoring never getting done. Many times I've found myself saying to myself "I must refactor this class.. But I'll just finish implementing this feature first so that I can get a clean commit with only the refactoring afterwards". Suddenly it's 5 o'clock and tomorrow I've forgotten about the refactoring need.
I can't imagine my workflow being all that special, but I never have to deal with this?
I just write new features, refactor if needed, fix unrelated bugs, etc. When I feel like it's commit-time, I cherry-pick changed chunks or lines to commit into single coherent commits. If I've introduced a new feature that required refactoring, I'll first pick all the chunks that belong to the refactoring and commit; then I'll commit the new feature and afterwards commit any bugfixes and other side endeavors that may have come up during the development of the new feature.
This is one of the reasons I don't like working with Subversion anymore. Committing, say, two changed lines in a file with many changes is nearly impossible. In 'git gui' it's a simple as selecting the lines, right-click, "Stage lines for commit" and pressing the commit button, and I'm back to working on whatever it was I was really working on.
I just write new features, refactor if needed, fix unrelated bugs, etc. When I feel like it's commit-time, I cherry-pick changed chunks or lines to commit into single coherent commits. If I've introduced a new feature that required refactoring, I'll first pick all the chunks that belong to the refactoring and commit; then I'll commit the new feature and afterwards commit any bugfixes and other side endeavors that may have come up during the development of the new feature.
This is one of the reasons I don't like working with Subversion anymore. Committing, say, two changed lines in a file with many changes is nearly impossible. In 'git gui' it's a simple as selecting the lines, right-click, "Stage lines for commit" and pressing the commit button, and I'm back to working on whatever it was I was really working on.
I find this method to not work too well for me because oftentimes features will have changes to the refactored code.
So I'm stuck with undoing my feature code or leaving smells of my feature in the refactored code.
Maybe I'm doing something wrong though.
So I'm stuck with undoing my feature code or leaving smells of my feature in the refactored code.
Maybe I'm doing something wrong though.
I tend to do this but with git add -p
I did this too in the past, but I've since found the convenience of 'git gui' too hard to ignore. The fact that it seamlessly runs on remote servers over X forwarding without having to install anything on the remote server really helps.
I struggle to see how this adds so much more effort?
You already know you want to refactor it so its not about forgetting to do it, and once the feature is done you'll probably have a better idea of how to refactor everything better and faster. It should actually save time in code productivity vs the extra minutes to do another commit.
You already know you want to refactor it so its not about forgetting to do it, and once the feature is done you'll probably have a better idea of how to refactor everything better and faster. It should actually save time in code productivity vs the extra minutes to do another commit.
Yeah, that's why I really hate rules like "all commits must have a user story attached". I'm not going to make a jira story for "function is poorly named", so if that's the rule then the code will fall to entropy.
For some reason the fact that "feature" is abbreviated to "feat" while "refactor" which is actually longer than "feature" is left alone irritates me - which, of course, doesn't mean anything other than to demonstrate how silly this kind of argument can be!
True, but "ref" is ambiguous since that abbreviation is usually used to mean "reference". "refac" or "refact" just don't roll off the tongue.
[deleted]
Every newspaper -- even ones that mostly use AP style -- has its own slightly different style guide. I don't think that proves style guides are pointless.
Hep, that's very good. I'm trying to do this recently, it is very hard btw unless you organize different topics beforehand, but then it is easy to escape since I often try to do something like "Submodule: ...." because later to merge just a single feature is simpler because commits are "tagged" with the name of the feature or module.
I do have problems with "(<scope>)", but I don't treat commit messages as statements defining code structure, but as hints of what I did.
(In any case, I don't use Angular-style commits for all projects. But learning about them was a small (but important) step in reducing complexity, vide http://www.johndcook.com/blog/2015/06/18/most-important-skil...)
(In any case, I don't use Angular-style commits for all projects. But learning about them was a small (but important) step in reducing complexity, vide http://www.johndcook.com/blog/2015/06/18/most-important-skil...)
One really nice side-effect is that these commits can be used to autogenerate changelogs, which is what the Angular team does.
Starting with caps or not makes a huge difference. It can easily break naive grep/awk. Other problems are typos and idiosyncratic spellings. Always spell-check your commit messages, it should be part of your git hooks.
By that logic we should also take into account all the other 1000s pieces of technology that can operate with text. In the end it all comes down to personal preference or the project guidelines.
> we should also take into account all the other 1000s pieces of technology that can operate with text
Yes, it called the Unix philosophy, good programs do it.
Yes, it called the Unix philosophy, good programs do it.
Speaking of Git commit messages, it's worth pointing out this wiki[1], written and reviewed by some long time open source contributors. It's a bit verbose, but rewarding to the patient reader.
On writing Git commit subject lines, I've come to appreciate why the imperative mood is nicer (as opposed to the and indicative mood). Some related reasoning here[2].
[1] https://wiki.openstack.org/wiki/GitCommitMessages [2] http://chris.beams.io/posts/git-commit/
On writing Git commit subject lines, I've come to appreciate why the imperative mood is nicer (as opposed to the and indicative mood). Some related reasoning here[2].
[1] https://wiki.openstack.org/wiki/GitCommitMessages [2] http://chris.beams.io/posts/git-commit/
Add comment strongly agreeing with parent
The links in the parent comment are to documents which are
prescriptive, based on hard-earned experience, and provide
well-reasoned justifications for how and why to format commit
messages, along with examples of projects which do so.
I wish the parent comment were at the top of the page, but I can
provide only a single upvote. This comment is to provide more
exposure than an upvote alone, and so that I can find it my HN
history.- http://orgmode.org/ (or Evernote, this-pad, that-pad...)
- https://en.wikipedia.org/wiki/Bookmark_%28World_Wide_Web%29
- Direct link to parent comment: https://news.ycombinator.com/item?id=9764039
- https://en.wikipedia.org/wiki/Bookmark_%28World_Wide_Web%29
- Direct link to parent comment: https://news.ycombinator.com/item?id=9764039
Does anyone actually care whether commit messages contain a period or not? If they're lower case, title case, sentence case, it's completely irrelevant
Sadly. In my view they're bikeshedding, hard.
Bikeshedding like this is useful as a team efficiency metric.
If you can't get quickly to an agreement about such a thing, or if the members of the team that didn't get their way actively rebel (or worse sabotage), you are working with a team of divas.
(note: of course developers whinge, as long as you stick with the team decisions once their are made, whinge all you want)
If you can't get quickly to an agreement about such a thing, or if the members of the team that didn't get their way actively rebel (or worse sabotage), you are working with a team of divas.
(note: of course developers whinge, as long as you stick with the team decisions once their are made, whinge all you want)
I feel like if you work in a team of divas you don't need a test like this to tell you that.
It kinda reminds me of that buzzfeed article "53 Signs Your Boyfriend Is Really Three Children In A Trenchcoat".
It kinda reminds me of that buzzfeed article "53 Signs Your Boyfriend Is Really Three Children In A Trenchcoat".
> If you can't get quickly to an agreement about such a thing ... you are working with a team of divas.
Or you're working on such a trivial problem that it should have been given to an individual, not a team.
Or you're working on such a trivial problem that it should have been given to an individual, not a team.
Well that's the point. Feed the team with a trivial problem to see how they react.
A well working team will probably do as you say - volunteer an individual to write the rule in an email and follow it from there on.
If you going to introduce changes in a team, like for example introducing Agile (the proper way) or you are starting a new project, you want to quickly gauge the team dynamic, and that's a good exercise.
A well working team will probably do as you say - volunteer an individual to write the rule in an email and follow it from there on.
If you going to introduce changes in a team, like for example introducing Agile (the proper way) or you are starting a new project, you want to quickly gauge the team dynamic, and that's a good exercise.
For those who don't know what that means https://en.wikipedia.org/wiki/Parkinson's_law_of_triviality
See also http://bikeshed.org/
(make sure to hit F5 a few times)
(make sure to hit F5 a few times)
I am glad to see your comment. I wanted to post 'Who cares?' Not about commit messages, because having nice compact descriptive messages can be useful, but mostly about the 'dot' at the end. Because seriously; 'Who cares?'
[deleted]
What is it about our industry (or perhaps just the slice of it that hangs around HN) that makes people feel the need to spout absolutist dogma about trivial shit like whether a commit message should be a sentence or not? Jesus. Sometimes a sentence is the most useful and sometimes a very short newspaper-headline-style summary is the most useful. Why must we constantly go in search of hard rules that prevent this sort of consideration? If having to shift between styles makes commit logs too hard to read for you, maybe the commit messages aren't the problem.
The only thing I care about is whether there's an empty line between the head and body of the (Git) commit message.
I don't care whether the lines are too long, whether they're nicely capitalized, whether they end with a dot. These are all things that tickle my OCD gland but I've learned to ignore them because it is ultimately useless and a waste of my time to get worked up about it. If the summary and description are good enough, I'm a happy man.
(I'm talking about reading others people's commit messages here. I try to make my own commit messages adhere to the scriptures as declared by his Holiness himself: https://gist.github.com/matthewhudson/1475276 (which, I now note, makes no mention of the length of the header line).)
I don't care whether the lines are too long, whether they're nicely capitalized, whether they end with a dot. These are all things that tickle my OCD gland but I've learned to ignore them because it is ultimately useless and a waste of my time to get worked up about it. If the summary and description are good enough, I'm a happy man.
(I'm talking about reading others people's commit messages here. I try to make my own commit messages adhere to the scriptures as declared by his Holiness himself: https://gist.github.com/matthewhudson/1475276 (which, I now note, makes no mention of the length of the header line).)
I find it a lot easier to read a commit log when it's consistent in style.
Regardless of whether commit messages are in past or present tense, have trailing period or not, properly capitalized or not -- they are all equally unreadable with all the "Merge pull request #20552 from jamesdabbs/belongs-to-polymorphic-force-reload" junk.
Yeah, that's something that I never understood. The most important information is not that this is a merge, but the intent of the branch. You can give extra detail in the extended part, but the title should not be just referencing the way in which those changes found their way to the branch, and not what they do as in the rest of commits...
I believe Github lets one add extended commit messages for merge commits. Most of us (including me) tend to ignore that and use the autogenerated one. It'd be nice if we had an easy option to automatically include the PR's description (first comment) as the merge commit's message.
`git log --no-merges` saved me a lot of headaches after switching to a pull request-based review model at work.
My main point is not about dots but the way you change the content of the first line depending on how do you look at it.
The problem is that if your repo maintainer is encouraging you to use a title as a commit message it implies a different level of information content.
commit -m "Features Aboundin: A new wave"
vs.
commit -m "Added initial project structure for new wave feature."
I'll hesitantly admit that I do, but not enough to blog about it. It's an unconscious indicator for me of inexperience with working with conventional Git, and very (very) often I have to intentionally ignore it for someone's benefit. However, that attitude is rooted in thinking about someone's teamwork abilities; good commit message etiquette, whether regarding periods, conventions on length and formatting, and squashing instead of merging seventeen of your test commits off a feature branch, or just general writing ability and effective communication, are all something I look for in a person.
I care more about merge commits, to be honest.
I care more about merge commits, to be honest.
I wouldn't call this indicator so unconscious when the triggers can be so easily enumerated. Agreed wholeheartedly.
It's not LITERALLY about the period. It's about how content that contains periods tends to be written a certain way that the author doesn't care for in commit messages.
Did you really not understand that?
Did you really not understand that?
"Please don't use uppercase for emphasis. If you want to emphasize a word or phrase, put asterisks around it and it will get italicized."
https://news.ycombinator.com/newsguidelines.html
https://news.ycombinator.com/newsguidelines.html
Considering there are people who have heart attacks based on whether a file ends with a newline or not, commit message formatting is a hugely important topic.
That's because there's some unix commandline tools that won't work right when a file does not end with a newline.
For serious. For just one example, `cat` doesn't act as expected without a trailing newline. You end up with stuff like <(echo) to space things out and it's really bogus.
Actually the ISO C99 language standard requires that every source file ends with a newline (§5.1.1.2, 2.):
"A source file that is not empty shall end in a new-line character [...]"
So if your C implementation doesn't complain about source files that don't end with a newline, you're unknowingly relying on a language extension.
"A source file that is not empty shall end in a new-line character [...]"
So if your C implementation doesn't complain about source files that don't end with a newline, you're unknowingly relying on a language extension.
lol. You'd think if "it's open source you can fix it yourself" worked as an ideology, its heartland would be Unix commandline text processing tools.
> "If it's open source you can fix it yourself, given that it is not standardised somehow, and that you have time to spare, and that you have the skills and knowhow to do it or that you possess the financial resources to hire some developers to do it for you.
FTFY.
FTFY.
Well his argument is not really the dot at the end, but rather whether the first line of the commit message is a title to the rest of it or whether it is a one-sentence synopsis of the changeset. Examples respectively:
1)
1)
Fix layout.
Replace proprietary grid layout w/ that of Bootstrap,
so that it is easier to manage and use. [...]
Substitute Bootstrap for proprietary grid.
The proprietary grid system was abandoned for Bootstrap,
as it will let us focus on the more peculiar stuff of the
UI.What? How can you not care.
Commit messages are extremely important when trying to understand the evolution of code. And the style matters a lot, not only the content. The (Linux) style is optimised both for people and tools (e.g. grep, awk).
When reviewing code I held the commit message at a much higher standard that the code itself. Nobody passes through me with a non-perfect commit. Luckily, people quickly learn and they start writing good messages without having me to force them, because they see the value.
Commit messages are extremely important when trying to understand the evolution of code. And the style matters a lot, not only the content. The (Linux) style is optimised both for people and tools (e.g. grep, awk).
When reviewing code I held the commit message at a much higher standard that the code itself. Nobody passes through me with a non-perfect commit. Luckily, people quickly learn and they start writing good messages without having me to force them, because they see the value.
Does having a dot at the end or not affect your understanding?
It does affect readability! That's the reason we have punctuation rules in human languages.
Maybe it doesn't have any effect when reviewing _one_ commit message, but when you're reading a list of hundreds, or thousands of them, it does have a huge impact.
This messages are meant to be consumed by humans, as in natural language. So it should respect the rules / conventions of that natural language.
The same way when we write code we should respect the coding style of the code base we are working on, we should respect the style conventions of the natural languages. Because of the same reasons.
Maybe it doesn't have any effect when reviewing _one_ commit message, but when you're reading a list of hundreds, or thousands of them, it does have a huge impact.
This messages are meant to be consumed by humans, as in natural language. So it should respect the rules / conventions of that natural language.
The same way when we write code we should respect the coding style of the code base we are working on, we should respect the style conventions of the natural languages. Because of the same reasons.
Also, even if it doesn't affect you, that is completely irrelevant for the project. A project should be oblivious to any one developer's preferences. Successful software projects thrive on conventions that affect the whole project. People do what's implicitly or explicitly agreed on, a person can't just ignore rules he doesn't see the value of.
People generally accept that when it's about coding conventions. Commit messages are just another convention. The rules are not arbitrary, in fact, if you read the Linux commit style guide, it will try to explain the value of the conventions.
If you still don't get it, or you disagree, too bad. Conventions are much more important that individual opinions. If you prefer spaces, you'd better start using tabs when you want to contribute to the Linux kernel.
(By you I meant, of course, some abstract person who doesn't see the value of certain rules, not kolme who I am responding to).
People generally accept that when it's about coding conventions. Commit messages are just another convention. The rules are not arbitrary, in fact, if you read the Linux commit style guide, it will try to explain the value of the conventions.
If you still don't get it, or you disagree, too bad. Conventions are much more important that individual opinions. If you prefer spaces, you'd better start using tabs when you want to contribute to the Linux kernel.
(By you I meant, of course, some abstract person who doesn't see the value of certain rules, not kolme who I am responding to).
A project can't be completely oblivious to preferences. You'll never find something that everyone agrees on. Eventually you have to pick something that's acceptable to the majority of the people working on the project and move on.
Of course in the case of projects a developer is working on solo, they're free to do whatever they want ;) When I'm working with others, I still express my own preferences, but I'm willing to go along with whatever the group consensus is because I'd rather be consistent above anything else.
Of course in the case of projects a developer is working on solo, they're free to do whatever they want ;) When I'm working with others, I still express my own preferences, but I'm willing to go along with whatever the group consensus is because I'd rather be consistent above anything else.
I've never seen a project use commit messages with periods and I've never felt like it affected readability at all. I don't think it really has anything to do with natural language style conventions. Writing a paragraph consisting of several sentences is very different from a disjoint set of statements which I have always seen separated by newlines anyway.
Its defensible to adopt an abbreviated style suitable for the context of oneliner commits in a long report. Nobody uses natural language when creating other textual reports like that - e.g. log messages, checkbook register, ships' log. They all have an encoded style unrelated to natural language.
[deleted]
A lot of the people commenting on the article seem to be pretty adamant that something like this matters. Personally, I've never been confused by a period (or lack of thereof) at the end of a commit message. And if such a time comes, I'll give serious thought to whether it's worth anyone's time to teach the team to use/not use periods or whether I'm better off investing that time to teach them something more useful.
Well, commit logs could be good complement to developer documentation, if done properly. e.g. "See <some hash range> to see how to add a new protocol to Spyne!" "See <some hash range> to see how a new statement could be added to CPython!."
But, yes, if you care this much about commit format, put structured data in commit logs using yaml or something and be done with it :)
But, yes, if you care this much about commit format, put structured data in commit logs using yaml or something and be done with it :)
Possibly if there were going to be a machine parsing them, but otherwise no.
As for me, I don't care about the style at all.
What I care is about the content. And the thing I hate the most are commit messages that explain the what, but not the why! (It's the equivalent to comments in the code that explain something obvious.) To me, this kind of commit messages express the same as if there was no commit message.
What I care is about the content. And the thing I hate the most are commit messages that explain the what, but not the why! (It's the equivalent to comments in the code that explain something obvious.) To me, this kind of commit messages express the same as if there was no commit message.
But if the commit message says what happened, then you don't need to read diffs to find out what happened. Reading an English sentence is easier than reading code diffs, and also you can read a bunch of sentences in list form (eg, git log).
I'm not saying you don't need to include the 'why', I'm saying there is value just in the 'what'.
As for code comments that just 'explain something obvious'... I have no problem with comments that simply summarise, in English, what the next few lines do. It means I can skim through a file just reading the comments, until I find the part I want to debug/modify/understand in more detail. Also, if you can sum up some code with a sentence then there's a good chance it makes sense, so it's a good quality check.
I'm not saying you don't need to include the 'why', I'm saying there is value just in the 'what'.
As for code comments that just 'explain something obvious'... I have no problem with comments that simply summarise, in English, what the next few lines do. It means I can skim through a file just reading the comments, until I find the part I want to debug/modify/understand in more detail. Also, if you can sum up some code with a sentence then there's a good chance it makes sense, so it's a good quality check.
With the 'what' of course I don't mean 'what happened', as the latter would be actually kind of the 'why' you're making the change. So with the 'what' I mean 'what is being changed', some people just write what file are changing and what they are adding to it, explaining how the code is changing in the diff, but not why the code is changing.
As for code comments, I think you're basically wrong. If you can summarize some fragment of code under a sentence, extract that piece of code into a method and name that method in the same way you were going to write that comment; otherwise comments get outdated easily. These kind of techniques are well explained in a very good book I read a while ago, it's called "Clean Code".
As for code comments, I think you're basically wrong. If you can summarize some fragment of code under a sentence, extract that piece of code into a method and name that method in the same way you were going to write that comment; otherwise comments get outdated easily. These kind of techniques are well explained in a very good book I read a while ago, it's called "Clean Code".
I have no objection to summary comments - they can guard against certain types of accidental or otherwise erroneous edits. If the code and the comment don't quite agree then suspect both of them are wrong.
Personally I think check-in comments should be a concise (but not generic like "bug fix") description of "what" with a smattering of "why" (perhaps a reference to a bug/ticket/feature/request ID). The details of "what" can be seen by looking at the diffs. Where the details of "why" go is split. Why you chose a particular method over others available? Any constants or magic numbers you think might need clarifying when someone else looks? You've done something that looks odd/unnecessary at first glance in order to work around a bug/limitation beyond your immediate control? Those things go in comments in the code. Just about everything else goes in the ticket and possibly makes its way to other documentation, there is not point cluttering the code up too much (unless your implementation documentation is all in-code and you use tools to extract it into other forms, as I've seen done before now, in whic case everything goes in there). "FIXME" and "TODO" markers can go in the code too though generally you want them gone for release (if they survive between releases then they should really be feature requests in your backlog rather than just code markers, so they can be tracked/managed/prioritised as needed.
What really grinds my gears is commits without any comment at all.
Personally I think check-in comments should be a concise (but not generic like "bug fix") description of "what" with a smattering of "why" (perhaps a reference to a bug/ticket/feature/request ID). The details of "what" can be seen by looking at the diffs. Where the details of "why" go is split. Why you chose a particular method over others available? Any constants or magic numbers you think might need clarifying when someone else looks? You've done something that looks odd/unnecessary at first glance in order to work around a bug/limitation beyond your immediate control? Those things go in comments in the code. Just about everything else goes in the ticket and possibly makes its way to other documentation, there is not point cluttering the code up too much (unless your implementation documentation is all in-code and you use tools to extract it into other forms, as I've seen done before now, in whic case everything goes in there). "FIXME" and "TODO" markers can go in the code too though generally you want them gone for release (if they survive between releases then they should really be feature requests in your backlog rather than just code markers, so they can be tracked/managed/prioritised as needed.
What really grinds my gears is commits without any comment at all.
> What really grinds my gears is commits without any comment at all.
That just shouldn't be allowed. Commits without JIRA (or whatever you use) task reference should just be automaticaly rejected.
That just shouldn't be allowed. Commits without JIRA (or whatever you use) task reference should just be automaticaly rejected.
Yeah, the legacy project I'm working on isn't that modern... And even when rules are enforced, people sometimes work around them and leave a useless commit comment. Lax documentation, sometimes deliberately lax, is a person problem unfortuntely - one better solved in ways that HR would disaprove of then via technical blocks!
Ah OK I see what I call "what" you call "why".
"otherwise comments get outdated easily" - not mine. If this is a problem, it's a problem that needs fixing, not a reason to comment less.
"extract that piece of code into a method" Sometimes, yes, but you can overdo this and end up with a fragmented codebase that is harder to follow.
This is an old debate, and there are books on either side. My preference is something approaching Knuth's literate programming.
"otherwise comments get outdated easily" - not mine. If this is a problem, it's a problem that needs fixing, not a reason to comment less.
"extract that piece of code into a method" Sometimes, yes, but you can overdo this and end up with a fragmented codebase that is harder to follow.
This is an old debate, and there are books on either side. My preference is something approaching Knuth's literate programming.
Oh god, another commit message discussion.
It's funny how the ones who contribute the least to the functionality have the most outspoken opinions on commit messages. Perhaps it's easier to be puritan when you only handle trivial code changes.
I prefer productive people with messy commit messages over pedantic people with meticolous commit messages any day.
The picky ones usually refuse to touch anything surrounding their particular feature and end up increasing code complexity with every commit, whereas the productive people massage the code into the best possible state as they go along.
It's funny how the ones who contribute the least to the functionality have the most outspoken opinions on commit messages. Perhaps it's easier to be puritan when you only handle trivial code changes.
I prefer productive people with messy commit messages over pedantic people with meticolous commit messages any day.
The picky ones usually refuse to touch anything surrounding their particular feature and end up increasing code complexity with every commit, whereas the productive people massage the code into the best possible state as they go along.
> It's funny how the ones who contribute the least to the functionality have the most outspoken opinions on commit messages. Perhaps it's easier to be puritan when you only handle trivial code changes.
According to GitHub, this guy is the author of Redis and he has made 3659 commits to the repository. Call that trivial code changes.
According to GitHub, this guy is the author of Redis and he has made 3659 commits to the repository. Call that trivial code changes.
I'm not criticizing Antirez, he seems to be on the recieving end.
I don't understand how you could possibly tolerate messy commit messages. It's as if you've never had to do a code investigation/audit ever, heaven forbid you do.
> I don't understand how you could possibly tolerate messy commit messages.
I mean, it's pretty easy. You just like, tolerate it.
I'm sure there are contexts where strict rules are important, but in my experience most of the time fussy commit message rules are put in place it's because someone has reimagined themselves as the gordon ramsey of code and the people rolling their eyes don't want to get entrenched in a political battle where they're against "professionalism", so they just deal with it, or someone with mild OCD is inflicting it on everyone else. (I know I'm being harsh and I'm writing this tongue in cheek, I don't really think that badly of people that are super fussy about these things, but I've rarely seen any actual utility come from strict commit rules).
I mean, it's pretty easy. You just like, tolerate it.
I'm sure there are contexts where strict rules are important, but in my experience most of the time fussy commit message rules are put in place it's because someone has reimagined themselves as the gordon ramsey of code and the people rolling their eyes don't want to get entrenched in a political battle where they're against "professionalism", so they just deal with it, or someone with mild OCD is inflicting it on everyone else. (I know I'm being harsh and I'm writing this tongue in cheek, I don't really think that badly of people that are super fussy about these things, but I've rarely seen any actual utility come from strict commit rules).
I don't think that's a fair statement, at least based on my own experience. When I'm investigating how code arrived at a certain state, I'm looking primarily at the code.
The commit messages are nice as indicators of intent, but I don't rely on them. The real change is in the code, not what somebody remembered to write in a summary of the change.
The commit messages are nice as indicators of intent, but I don't rely on them. The real change is in the code, not what somebody remembered to write in a summary of the change.
Investigating code deltas tells you nothing about HOW the code got there. It's there. Someone committed it. But WHY? Hence, the commit message.
"new feature. fix it. fixed. lol. WIP. COMPILES NOW"
None of these tell you how the commits came to be other than that they are already there.
"new feature. fix it. fixed. lol. WIP. COMPILES NOW"
None of these tell you how the commits came to be other than that they are already there.
Well, I don't tolerate just anything. But I much rather have "fixed fs race" than "merged a13b1z: <issue 14365><subsystem core><signoff:dave> changed fs_handle.lock to use blargh_lock_45"
Regardless of my opinion about this subject, i always find it good to see when people try to think out of the box.
Nowadays most people just follow what is the current hype:
yeah, let's do semver! And it HAS TO BE react, agile and also it must be in Git, because... yeah, because what? Did you as a developer really think why you are following a certain practice and if it is beneficial to your project at hand? Most people don't. They just do what John Doe posts on his hipster blog about Web3.0.
yeah, let's do semver! And it HAS TO BE react, agile and also it must be in Git, because... yeah, because what? Did you as a developer really think why you are following a certain practice and if it is beneficial to your project at hand? Most people don't. They just do what John Doe posts on his hipster blog about Web3.0.
If you join a team project, you have to follow the team convention. It is not necessary to put dbo. in front of table names in SQL server. Yes, you can use .PHP instead of .INC for class files. No, C# will compile just fine if you indent with four spaces or eight spaces instead of a tab.
However, when you are working in a team, you follow the convention of the team. Or change the convention so the team is on the same page.
However, when you are working in a team, you follow the convention of the team. Or change the convention so the team is on the same page.
>It is not necessary to put dbo. in front of table names in SQL server.
Depending on default schema, it definitely can have performance considerations on compilation.
Maybe some of those team conventions are actually based on real world things.
From: https://msdn.microsoft.com/en-us/library/dd283095%28v=sql.10...
SELECT * FROM Table1
Will assess the following statement first: SELECT * FROM <defaultschema>.Table1
If it cannot find the object, the server will assess the following statement: SELECT * FROM dbo.Table1.
The assessment process can be improved by using either the fully qualified name or the DEFAULT_SCHEMA option described earlier. By setting a value for DEFAULT_SCHEMA for the user, the server will check the DEFAULT_SCHEMA first, removing an unnecessary ownership checking process. This can improve performance considerably on heavily utilized systems.
Depending on default schema, it definitely can have performance considerations on compilation.
Maybe some of those team conventions are actually based on real world things.
From: https://msdn.microsoft.com/en-us/library/dd283095%28v=sql.10...
SELECT * FROM Table1
Will assess the following statement first: SELECT * FROM <defaultschema>.Table1
If it cannot find the object, the server will assess the following statement: SELECT * FROM dbo.Table1.
The assessment process can be improved by using either the fully qualified name or the DEFAULT_SCHEMA option described earlier. By setting a value for DEFAULT_SCHEMA for the user, the server will check the DEFAULT_SCHEMA first, removing an unnecessary ownership checking process. This can improve performance considerably on heavily utilized systems.
The point is not the existence of conventions but the correct and wise application of them as opposed to just "let's do what the internet blogs about!".
Critical thinking will never be out of style, no matter how much people try.
I really like bitbucket and JIRA for this in a business use case.
We use the format "JIRA-XXX commit message/title/synopsis/whatever you wish to call it" where JIRA is our project name in JIRA and XXX is the ticket number. Bitbucket then can turn that into a link to your JIRA project
All of the who/what/why is already in the JIRA ticket as more often than not there are non-coders who have input/insight around the issue. When I am looking at the commit log I see a brief summary and if I need more details I can go to JIRA and get the full history with screenshots, designs, reproducible steps, business cases, etc.
Another side effect of this is, when someone is searching in JIRA and finds a ticket they can easily see all of the commits related to that ticket. This also works with Github
The commit becomes simply the "how" "JIRA-XXX brief desc" was implemented
We use the format "JIRA-XXX commit message/title/synopsis/whatever you wish to call it" where JIRA is our project name in JIRA and XXX is the ticket number. Bitbucket then can turn that into a link to your JIRA project
All of the who/what/why is already in the JIRA ticket as more often than not there are non-coders who have input/insight around the issue. When I am looking at the commit log I see a brief summary and if I need more details I can go to JIRA and get the full history with screenshots, designs, reproducible steps, business cases, etc.
Another side effect of this is, when someone is searching in JIRA and finds a ticket they can easily see all of the commits related to that ticket. This also works with Github
The commit becomes simply the "how" "JIRA-XXX brief desc" was implemented
Way too much energy to expend on worrying about this.
I put Github issue numbers into my commits because I use Github. Anything is fine if you're consistent.
I put Github issue numbers into my commits because I use Github. Anything is fine if you're consistent.
The first comment under the post is frankly outrageous.
This is precisely the reason why the rest of the world abhors programmers and the software community. Random strangers contributing nothing to the debate but their angry and immature bile. No wonder content creators are disabling comments one after another, why wouldn't you?
This is precisely the reason why the rest of the world abhors programmers and the software community. Random strangers contributing nothing to the debate but their angry and immature bile. No wonder content creators are disabling comments one after another, why wouldn't you?
Well, programming can be picked up by just about anyone these days, so its no wonders you get people as mature as youtube commenters in the mix.
This is what differentiate professionals from amateurs.
This is what differentiate professionals from amateurs.
In a previous gig, we had a simple rule: there must be a ticket number with a certain format at the beginning of the commit message. A summary follows.
The ticket has pretty much all the info you need, so there's usually no need to write a very detailed commit message.
This essentially mandates tickets for every single commit, which might sound too process heavy for some people, but ticketing was part of our process anyway for other reasons (change management, compliance, etc).
In the rare event that a commit is not originated by a ticket, you can still cheat by writing a fake ticket number.
The ticket has pretty much all the info you need, so there's usually no need to write a very detailed commit message.
This essentially mandates tickets for every single commit, which might sound too process heavy for some people, but ticketing was part of our process anyway for other reasons (change management, compliance, etc).
In the rare event that a commit is not originated by a ticket, you can still cheat by writing a fake ticket number.
It ought to be a simple matter to start a new ticket and dump your work into it.
A la the Joel Test, your ticketing system should:
- open a new ticket on receipt of unknown email, sending back the ticket number
- treat email with a proper subject prefix as a comment on an existing ticket, adding any attached files
- easily merge two or more tickets, preserving both histories and redirecting all references to the old tickets to the new one
- maintain metadata and ACLs for metadata
- automatically re-open a ticket when a new comment or reply is received
- require a message to close a ticket
- provide summaries
- be full-text searchable
- track all history immutably
- provide a method to associate many individual reports of the same problem
A la the Joel Test, your ticketing system should:
- open a new ticket on receipt of unknown email, sending back the ticket number
- treat email with a proper subject prefix as a comment on an existing ticket, adding any attached files
- easily merge two or more tickets, preserving both histories and redirecting all references to the old tickets to the new one
- maintain metadata and ACLs for metadata
- automatically re-open a ticket when a new comment or reply is received
- require a message to close a ticket
- provide summaries
- be full-text searchable
- track all history immutably
- provide a method to associate many individual reports of the same problem
I was recently advised to use the "commit messages are subjects" style, but I get a pang of... something, every time I have to omit the full stop (I always type it out of habit and then press backspace).
I agree completely with Antirez, messages are not subjects or titles, and we should make them as succinct as possible, not force ourselves to write something that leads into a full-text piece only to omit the latter.
If it can fit in one line, make it fit, otherwise summarize the change as well as you can. Our goal should be to have to read the least amount of text to understand what the change is doing, and the hierarchy is: short commit message > long commit message > diff.
I agree completely with Antirez, messages are not subjects or titles, and we should make them as succinct as possible, not force ourselves to write something that leads into a full-text piece only to omit the latter.
If it can fit in one line, make it fit, otherwise summarize the change as well as you can. Our goal should be to have to read the least amount of text to understand what the change is doing, and the hierarchy is: short commit message > long commit message > diff.
I get a pang of... something, every time I have to omit the full stop
You know that you've read to the end of something.
In the absence of one, there's always the chance that text has been cut off
Cut off what? The suspense is killing me!
> How many emails or articles you see with just the subject or the title? Very little, I guess
I hate to go OT and "well actually", but, well actually this is more common that you'd think. I first learned about "subject only" emails back in 1998 and most places I've worked at use them to convey succinct email messages where there's no need for extraneous words in the body. It's a real time saver when you have a busy inbox.
I've also worked in places that "EOM" (or some variant of) their message subjects to be explicit that there's nothing in the body [0].
WRT to the remainder of the article, I don't have any strong feelings either way.
[0]: http://lifehacker.com/5028808/how-eom-makes-your-email-more-...
I hate to go OT and "well actually", but, well actually this is more common that you'd think. I first learned about "subject only" emails back in 1998 and most places I've worked at use them to convey succinct email messages where there's no need for extraneous words in the body. It's a real time saver when you have a busy inbox.
I've also worked in places that "EOM" (or some variant of) their message subjects to be explicit that there's nothing in the body [0].
WRT to the remainder of the article, I don't have any strong feelings either way.
[0]: http://lifehacker.com/5028808/how-eom-makes-your-email-more-...
NT
I also prefer treating them as sentences and prickle at the level of enthusiasm for no dots. In the end consistency with others is more valuable though. However, the article is entirely unconvincing to me, despite being on his side - the removal of a dot and writing succinctly are not mutually exclusive.
It always felt natural to put this dot at the end of (what antirez nicely called) commit synopsis, so AFAIR I always (or at least since I started using git and when was not forced by particular project's rules to do some other way) put it there and found advices to avoid it quite strange. The only exception (beside forgetting about full stop yet pushing to public repo, it does happen sometimes) I have is when the commit is sole version-bumping/releasing one, because then I usually go with following style
As some commenters here already wrote, it's not a grave matter, but it's good to have consistent style. It goes without saying, that having relatively short commit summary in one sentence separated with blank line from further details (if they are necessary) is far more important matter than the period or lack thereof, as it immensely eases groking commit log.
PROJECT_NAME [v]VERSION
As some commenters here already wrote, it's not a grave matter, but it's good to have consistent style. It goes without saying, that having relatively short commit summary in one sentence separated with blank line from further details (if they are necessary) is far more important matter than the period or lack thereof, as it immensely eases groking commit log.
Commit messages need to convey what will happen if you merge that commit in. Plain and simple. That's all that is needed of them.
Of course, you need to tag the ticket number (in case you are using Cloud based solutions like Github) but I am more interested in what the changes will do if I merge them in.
I think the body of the commit message is way more important than the title: http://blog.jgc.org/2013/07/write-good-commit-messages.html
Body is super important, but when you can craft a very good single line commit message, is not bad either. It is hard to find a balance but what I try to do is to reserve multi line commit messages for situations where it is appropriate to provide mode details compared to just "git show" the commit to check the actual content.
It really depends on the situation tbf; if you're looking for a commit or an overview of what happened, titles; if you're looking for details, especially important in the less legible languages and environments (C, the Linux kernel), body.
Actually TL;DR both are important.
Actually TL;DR both are important.
Is it me or the entire "Kosher Commit Messages" movement really gained traction with the widespread adoption of DVCSes?
I really cannot recall contributors obsessing that much over SVN, CVS or VSS commit messages. Now, you could change these after the fact, but still.
I really cannot recall contributors obsessing that much over SVN, CVS or VSS commit messages. Now, you could change these after the fact, but still.
We used to have a Perforce changelist guideline newsletter here.
No, I'm not kidding.
No, I'm not kidding.
From a code standpoint (excluding commit messages) DVCSes tend to do a better job at expressing high quality history. As an example you have two ways to express a merging history (merge and rebase), giving the developer more tools to accurately describe what has historically happened.
This "mentality" seems to have leaked out of the machine and into the mindsets of developers. Just like learning a functional language will alter the way you think so will learning a SCM that values history (which DVCSes typically do).
This "mentality" seems to have leaked out of the machine and into the mindsets of developers. Just like learning a functional language will alter the way you think so will learning a SCM that values history (which DVCSes typically do).
How about: if your message doesn't fit into a single sentence, the commit is too big. Split it. If it's a huge architectural change merged from another branch, describe it in a separate document referenced in the message.
It seems obvious that inside any given organisation, it makes sense to have a convention regarding the form of commit messages, so you know how to look for certain things.
However, pretending there is a one-size-fits-all rule is taking it too far.
However, pretending there is a one-size-fits-all rule is taking it too far.
I'm waiting for the 'Commit messages considered harmful' blog post.
While I commend the poster's ideals, the method only works in the glass cathedrals model of development. One in which no commit gets made without having followed the process from inception, through requirements gathering, through unpressured development, through appropriate and thorough QA/code review, and deployment. In the street market bazzar you're left with thousands of micro commits that you don't have time to sit down and create an illuminated manuscript page for each commit explaining it's small description, and it's naritive history.
We use Redmine and just put the relevant issue number and the title of the issue. If more information is needed, you can go to Redmine to check more details or how to reproduce.
I prefer the next step over: Branch is named after the ticket and a short description of what the branch does, commit messages just talk about the contents of the commit itself.
We actually don't make a branch for each ticket because we need to expose the repositories to outside and so we use Gitolite, and having to reconfigure branch permissions each time... Ain't nobody got time for that.
The 50 character limit on the first line of a commit message really bugs me. I try to stay within 50 characters but sometimes I don't care. I can't always fit what I want in 50 chars and adding a second line can be too much. This is the worst kind of thing around tooling, these types of conventions, in this case because that's how Torvald's wants kernel git commits formatted. I am not committing to anything Torvald's cares about.
The 50 character convention has nothing to do with Linus Torvalds.
I've seen a lot of posts and comments about the 50 character convention but I'm not sure I've ever seen a reason for that specific number. What is the reason for that anyway?
It appears to originate with Tim Pope: http://tbaggery.com/2008/04/19/a-note-about-git-commit-messa...
Reading between the lines, it seems that the 50 character limit is to accommodate commands like "git log --pretty=oneline" and "git rebase --interactive" on an 80 column terminal. He also recommends 72 columns for any subsequent text because git makes a left margin of 4 characters and it looks balanced if you also have a right margin of 4 characters (80 - 8 = 72).
As someone who actually uses an 80 column terminal, I appreciate this practice. Probably younger people with good eyes won't be able to understand the reasoning behind it ;-)
Reading between the lines, it seems that the 50 character limit is to accommodate commands like "git log --pretty=oneline" and "git rebase --interactive" on an 80 column terminal. He also recommends 72 columns for any subsequent text because git makes a left margin of 4 characters and it looks balanced if you also have a right margin of 4 characters (80 - 8 = 72).
As someone who actually uses an 80 column terminal, I appreciate this practice. Probably younger people with good eyes won't be able to understand the reasoning behind it ;-)
> Probably younger people with good eyes won't be able to understand the reasoning behind it ;-)
Serious question, have you tried reading glasses? You don't have to just deal with bad eyes as you age, you can wear reading glasses. This what I do now.
Serious question, have you tried reading glasses? You don't have to just deal with bad eyes as you age, you can wear reading glasses. This what I do now.
I think people tend to overthink this. The only thing I need from a commit message is what you did and why you did it. (One might be implicit from the other). If there's more than that, you might be committing too much at once. People hardly ever go over commit history unless something got fucked up, and then those are the things you're interested in. Whenever people get OCD about the form or rules I cringe.
As others have observed, these comments are used for auto-documentation, for reporting, and for merge requests. Its handy to be able to categorize them, to schedule and organize these activities.
I feel like things like "auto documentation" and "automated reporting" are code words for "things that superficially sound useful that in reality no human should ever use to make an actual decision". So in that context, well formed commit messages are very important for supporting bureaucratic nonsense. My feeling is that if you want to publish a change log, you should do that by hand while keeping the intended audience in mind, and if you want to review the performance of people, "metrics" are extremely game-able and instead the work should be considered as a whole.
You don't read release notes?
This is what I'm using now: http://seesparkbox.com/foundry/semantic_commit_messages.
chore: add Oyster build script
docs: explain hat wobble
feat: add beta sequence
fix: remove broken confirmation message
refactor: share logic between 4d3d3d3 and flarhgunnstow
style: convert tabs to spaces
test: ensure Tayne retains clothing
chore: add Oyster build script
docs: explain hat wobble
feat: add beta sequence
fix: remove broken confirmation message
refactor: share logic between 4d3d3d3 and flarhgunnstow
style: convert tabs to spaces
test: ensure Tayne retains clothing
Right. Commit messages are not titles.
Commit messages ought to consist of a title, followed by an empty line and a short(-ish) summary.
Commit messages ought to consist of a title, followed by an empty line and a short(-ish) summary.
I think the two most important rules are:
1- The first line should give a good description of the commit
2- Avoid long lines (reading truncated commit messages is painful)
Other than that I think it's all common sense/good judgment and I'm not attached to a particular writing style or kind of sentences one should make.
1- The first line should give a good description of the commit
2- Avoid long lines (reading truncated commit messages is painful)
Other than that I think it's all common sense/good judgment and I'm not attached to a particular writing style or kind of sentences one should make.
At our company we use a svn hook with Jira, so all commit messages must contain a valid Jira issue ID which contains a detailed explanation of the commit itself. So our messages are always like:
PROJ-0001
I did this.
IMO does the job and is much easier for the developers.
Commit messages are like tabs and spaces. However you write them, keep them the same across your repository.
But obviously lower case, present tense, no dot, 50 char limit, and usually starting with add/fix/refactor/update/remove is the way to go. ;)
But obviously lower case, present tense, no dot, 50 char limit, and usually starting with add/fix/refactor/update/remove is the way to go. ;)
Linus on good git comments: https://gist.github.com/matthewhudson/1475276
The first line is special for a reason, it makes shortlog clean and clear.
The first line is special for a reason, it makes shortlog clean and clear.
An option for git or magit that would automatically look at recent commits and maybe capitalize or add a period to my commit message so that it is consistent with the majority of the commits for the project would be nice.
Does something like that exist?
Does something like that exist?
I don't know if someone has already written one, but a commit-msg hook could certainly achieve this.
http://git-scm.com/docs/githooks
http://git-scm.com/docs/githooks
I perceive the condensed sentence fragment (as requested for Angular) as a conceptual gist, which is all it really is (a few words to suggest the bigger picture), not a title (each commit is identified by its hash).
I ALWAYS commit message like this:
<action>: <brief explanation>
For example like this:
"refactor: tightened for() loop in networking code"
"added: feature #134"
"removed: debug cruft"
"fixed: one-off bug in string parser"
<action>: <brief explanation>
For example like this:
"refactor: tightened for() loop in networking code"
"added: feature #134"
"removed: debug cruft"
"fixed: one-off bug in string parser"
Fuck it. From now on, all my first lines will be UTF-8 emoji.
my commits are not only titles they are milestones , I have lolcommits installed and pose for the selfie and everything.
Could be because of I am new to git
Could be because of I am new to git
Commit messages could have titles :-)
Most tools only shows first line of message. Rest of the message can contain whatever you want.
Most tools only shows first line of message. Rest of the message can contain whatever you want.
What's your blog theme?
So cool and minimalistic.
I have the following in my git config for handling these kinds of discussions:
[jlouis@lady-of-pain ~]$ cat .gitconfig | grep phk
phk = commit -a -m 'upd'Does phk mean what I think it means? It's definitely funny and I'd definitely decline all your pull requests, but in company work it really doesn't matter because most people don't look into the history anyway. So yeah, it's probably a productivity tip.
It pays eternal homage to a toy-repository by phk in which that commit message occurs. I found it more fun than `git yolo`. And easier to type as well.
The other reason I have it is that when you are first building up a piece of software, you may want to snapshot it now and then, but you don't care too much for the archeology because things are still not working. Once you reach something which seems to work, you squash everything down and cut your first release with a meaningful commit.
The other reason I have it is that when you are first building up a piece of software, you may want to snapshot it now and then, but you don't care too much for the archeology because things are still not working. Once you reach something which seems to work, you squash everything down and cut your first release with a meaningful commit.
Yeah in a feature branch it's also reasonable. `git yolo` is also nice.
When using Git's mail features -- remember, not everyone uses GitHub -- the first line of a commit is a subject line. It's good practice to just think of it that way. If you write sentences in your subject lines in e-mail, I guess, that's up to you. Don't take it from me, read the Tim Pope counterpoint, with eight extremely good reasons for concise subjects in the closing paragraph:
http://tbaggery.com/2008/04/19/a-note-about-git-commit-messa...
Strong disagree with antirez on this one. Even vim filetype gitcommit disagrees. (Try it on the "smart synopsis" example.)
http://tbaggery.com/2008/04/19/a-note-about-git-commit-messa...
Strong disagree with antirez on this one. Even vim filetype gitcommit disagrees. (Try it on the "smart synopsis" example.)
I don't see how this is a counterpoint. tpope says "This first line should be a concise summary of the changes introduced by the commit", and antirez says the first line should be a "synopsis of the meaning of the change operated by the commit"; these appear to be exactly the same thing.
But then, I don't understand the distinction the original post seems to be making between "titles or subjects" and "synopses." A good title or subject for a git commit is a synopsis of the changes in the commit, in the same way a good headline for a newspaper article is a synopsis of the article.
But then, I don't understand the distinction the original post seems to be making between "titles or subjects" and "synopses." A good title or subject for a git commit is a synopsis of the changes in the commit, in the same way a good headline for a newspaper article is a synopsis of the article.
Why is it that programmers invariably state their opinions as if they were facts.
Qualifying an argument weakens it. And makes it less concise. Note: I could have said "I think that usually qualifying an argument tends to weaken it in the eyes of the reader". Which is better in a text discussion?
How can anyone take the author's word on whether or not to put a full stop at the end of something when he puts a full stop at the end of the bullet points in his list? That's far worse usage than anything he's doing in the title/summary/smart synopsis. https://www.oxforddictionaries.com/words/bullet-points
That link you posted says you can put fullstops at the end of lists if the elements of the list are full sentences.
"And resulted into this" is a full sentence now? I guess. It's not really English though.
The whole thing is serious bikeshedding in my opinion.
The whole thing is serious bikeshedding in my opinion.
"Sentence" is a highly debated linguistic construct with no clear rules for what does or doesn't apply. You don't think that's a sentence? So what?
> <type>(<scope>): <subject>
> [...]
> feat: A new feature
> fix: A bug fix
> docs: Documentation only changes
> style: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)
> refactor: A code change that neither fixes a bug or adds a feature
> perf: A code change that improves performance
> test: Adding missing tests
> chore: Changes to the build process or auxiliary tools and libraries such as documentation generation
There is a big difference in knowing if someone added a feature, fixed something, or did some refactoring.