5

I'm still not totally clear about the way git commit messages are supposed to be written.

I know the basic rules, but this one confused me. In my practice project, I created a login system and a user signup, but had not yet implemented secure password storage in the database. They were still being stored Sony style in plain text. I wanted to make a note of that in the commit message, but I found myself in a bizarre quandary about how to phrase that in the imperative.

Any thoughts?

I do think, personally, that this should be included in the commit message, even though it is a statement of what isn't included in the commit, because it represents important info for anyone wishing to use the code that may not be obvious by glancing at the changes.

user3888177
  • 85
  • 1
  • 8
  • 1
    Hello, and welcome to Stack Overflow. This question seems [primarily opinion-based](http://stackoverflow.com/help/closed-questions) and is therefore not a good fit for the site. There are many blog posts on google about this topic, perhaps you could look at those for guidance. – flaviut Dec 24 '14 at 23:12
  • Okay, thank you for the guidance. Should I delete the question? – user3888177 Dec 24 '14 at 23:14
  • 2
    I don't think this is fundamentally opinion based. But it is really about English grammar and/or expression (in a specific context), so I think it is off topic. – Stephen C Dec 25 '14 at 00:04
  • @flaviut, you may not be familiar with the technical area in question but this is not opinion based, or if it is, it's seeking best practice expert opinion informed by knowledge and experience that can establish an effective convention for practitioners. Using the imperative voice in commit messages in general is opinion based but practiced very widely and is good advice to new comers to the field. This is a good question that I've often had myself and I expect to be educated by the responses from knowledgeable people. – NeilG Apr 21 '23 at 05:17
  • @user3888177, please do not delete. This is a useful question that will help both newbies and experienced practitioners. I think SO pays some admins if they have more deleted questions or something. There seems to be an incentive or commission because lots of proposed deletions are for good questions with great answers. – NeilG Apr 21 '23 at 05:18

4 Answers4

10

One good article on commit message is How to Write a Git Commit Message.

Its rule n° 5 indeed recommends using imperative mood.

The imperative can sound a little rude; that's why we don't often use it. But it's perfect for git commit subject lines.
One reason for this is that git itself uses the imperative whenever it creates a commit on your behalf.

In the case of your topic, a simple "Doesn't add xxx" is enough to complete the first part of your commit (the "positive statement", in imperative).

VonC
  • 1,262,500
  • 529
  • 4,410
  • 5,250
  • Ahh, that makes sense. Also answers the question of whether or not to continue using the imperative in the body text of the commit message. – user3888177 Dec 24 '14 at 23:20
  • 4
    For people who are grammatically aware: "doesn't add xxx" is not imperative. It is merely a statement of (a negative) fact. The imperative would be "don't add xxx". – Stephen C Dec 24 '14 at 23:49
  • 1
    @StephenC I agree: my point was that you don't need to use imperative for the negative part, only for the positive part. – VonC Dec 25 '14 at 00:01
  • @VonC You answered the question that I had meant to ask – user3888177 Dec 25 '14 at 01:09
  • `git itself uses the imperative` is an extremely poor argument. So if git was doing it wrong for whatever reason, everyone else has to do do it wrong as well? As Bertrand Russell once said "*Even if everyone agrees, everyone can be wrong.*" I'm missing a real argument here, why imperative is better than alternatives. – Mecki Jan 17 '21 at 14:52
  • @Mecki I agree. This is not an argument in itself, simply the illustration of a possible choice/guideline, which has been followed now for many years, and has not been seriously challenged in the Git mailing list (example: https://public-inbox.org/git/CAAM6cWenBUL6rNva+KmwnPhUwzGZeFs53=N8yOkyyTXOmXC2jw@mail.gmail.com/T/#u) – VonC Jan 17 '21 at 22:27
  • Thank you @StephenC, I wish you'd provided the accepted answer. – NeilG Apr 21 '23 at 05:20
  • It's funny that Betram Russell claims that quote for himself @mecki, as it originally came from the Bible. The truth is not a democracy. – NeilG Apr 21 '23 at 05:21
5

I assume that you are trying to decide whether 

 Don't add hashing      #1

or 

 Didn't add hashing     #2a
 Doesn't add hashing    #2b

is imperative. This is really an English grammar question. But to answer it, we first need to turn the contractions back into their full forms:

 Do not add hashing        #1
 (It) did not add hashing  #2a
 (It) does not add hashing #2b

The first of these is an instruction or command ... telling people not to add hashing. That is imperative.

The second two are simple statements of fact about the commit. They are saying that the commit does not or did not add hashing. This is not a direction or a command to anyone, therefore it is not imperative. (Either "does not" or "did not" is correct. It depends on whether you interpret the message in time-frame of the person writing it or the person reading it.)

By that analysis, the #1 and #2 forms would clearly mean very different things in a commit message. It is far more important that your commit messages should say what you actually mean, than that they should conform to some stylistic rules or conventions.

However ...

I'm still not totally clear about the way git commit messages are supposed to be written.

There is no single definitive authority on that topic. My recommendation would be not to sweat tears over it. Do what feels right to you. If people complain, ask them to explain in detail what you have done wrong, and try to learn. (Bear in mind that some people are never satisfied.)

Stephen C
  • 698,415
  • 94
  • 811
  • 1,216
  • Good analysis, more detailed than my answer. +1 – VonC Dec 25 '14 at 00:32
  • 1
    For what it's worth, this was not an english grammar question, it was a git conventions question. I am aware that 'don't add' is the appropriate imperative form, however it is painfully obvious that this sounds absurd in a commit message. The question was meant to discover exactly how tolerant the style guidelines for commit messages were. You have answered both, though, and quite well. – user3888177 Dec 25 '14 at 01:06
  • @user3888177 - Thanks. I just updated my answer to say that it is more important to say what you actually mean, than any style conventions. But that also applies to "sounds absurd". If what you have written sounds absurd to you, and yet it best expresses what >>you<< want to say, then ... perhaps ... it is not absurd. – Stephen C Dec 25 '14 at 10:53
  • I think this is the best answer because the recommended text doesn't include apostrophes. Single apostrophes can sometimes put a spanner in the works and I don't like to see them hanging around. – NeilG Apr 21 '23 at 05:22
  • @NeilG - I didn't mean that when I wrote the answer. My de-apostrophization (is that a word?) was solely for the purposes of analyzing what the different versions mean ... literally. (But I'm not disagreeing with your sentiment. Incorrect use of apostrophes is annoying and can be misleading.) – Stephen C Apr 21 '23 at 05:59
  • Thanks @StephenC but even correctly used apostrophes can be destructive if the text containing them passes through some filter that treats apostrophes as special. For instance if you're view a `git` log with a syntax checker that has some default interpretation the apostrophe can start a string which never ends and messes up your syntax highlighting. That's just a minor example but the effects could be quite horrible. I just try to stay away from apostrophes in comments and documentation in general. – NeilG Apr 22 '23 at 06:13
  • That's also an interesting point. But my take is that if a script is broken by "inconvenient" characters in git commit messages, then the script is broken. Ditto for a syntax highlighting tool that is (apparently) not fully aware of the syntax of the document you are viewing. – Stephen C Apr 22 '23 at 10:14
3

A commit message tells us what is getting added to the source code through the given commit. The commit message is representing a change-set which will get applied on the code.

The guidelines given by many experts for example this article which mention having a summary line then a blank line and then description to the commit message.

The rule of imperative mood to be followed is only for the first summary line of the commit message. This summary line of the commit message shall only mention what change will be done if this commit is applied to the code. That is logical to be written as a imperative sentence.

The additional things to be mentioned can always be part of the description of the commit message, and you can write a paragraph or two there mentioning anything including what is not implemented. Git commit is written for documenting what change will be added by that git commit. Other architectural decisions and information are better suited in other documentation like architectural decision register, product roadmap, product development wiki. If the other information is still needed in the commit message, it shall be added to the description of the message.

Tushar Joshi
  • 2,206
  • 21
  • 20
0

A commit message should not contain notes of things that have not been achieved in the current changeset. Instead, it should either;

  • briefly summarise the changes themselves (e.g. Created login system), or;
  • describe the task that prompted the changes in the first place (e.g. Allow users to login)
Mathew
  • 8,203
  • 6
  • 37
  • 59
  • A reference to some "official" guidelines would be nice. Otherwise, make this answer a comment. – jub0bs Dec 24 '14 at 23:10
  • 1
    I should have clarified - the initial commit summarization would be the positive statement "Add user login". But the proceeding paragraph which details the changes is also written in the imperative (as far as I know). It is in this portion that I encountered the difficulty with wording. – user3888177 Dec 24 '14 at 23:17
  • You could also use words with negative meaning, such as `exclude`: `Exclude user login`. In a commit often approach you can break down your commits into smaller ones if that helps. – NeilG Apr 21 '23 at 05:23