In git, what are some good conventions to format multiple comments to a single commit.

Question

I was wondering how people normally separate out the multiple comments in a single commit. Stars? Commas? Separate lines? Just wondering what you find to be the best.

I'm using this now when I add comments via Emacs, but not sure I like it:

Added error messaging
Cleaned up sign-up UI
Added recaptcha

# Please enter the commit message for your changes. Lines starting
# with '#' will be ignored, and an empty message aborts the commit.
#
# Committer: Conrad Chu <[email protected]>
#
# On branch master
# Changes to be committed:
#   (use "git reset HEAD <file>..." to unstage)
#
#       modified:   app/controllers/api_controller.rb
#       modified:   app/controllers/users_controller.rb
#       modified:   app/models/user.rb
#       modified:   app/views/users/new.html.erb
#       modified:   app/views/users/show.html.erb
#       modified:   config/environment.rb
#       modified:   db/migrate/20090923001219_create_users.rb
#       modified:   db/schema.rb
#       modified:   doc/README
#       modified:   public/stylesheets/master.css
#       new file:   vendor/plugins/recaptcha/.gitignore
#       new file:   vendor/plugins/recaptcha/CHANGELOG

Answer 1

Git has very strong conventions on log messages, but the rules are simple:

1. First line is a summary of the commit
2. First line may have a scope description prefix "module:"
3. Second line is empty
4. Then follows a discussion in paragraphs, as long as it needs be

As a start you should use these conventions, as the presentation tools even rely on them (The second line being empty is important, and in many situations, you will only see the first line summary.)

With git, commits should be small so the first answer is of course, you shouldn't modify many things in one commit. You should have three commits, not one.

But, you can write a whole essay in the commit log, and there you can describe their changes in all detail (motivation, discarded designs, ideas). If the three changes truly belong together, this text will make it clear why.

I found more instructions describing the same Git Commit message conventions, with examples for which git commands depend on the particular format. (Most of it is all based on an existing convention: Patches sent by emails.)

Answer 2

Look here, http://progit.org/book/ch5-2.html, there are commit guidelines and a sample commit.

Answer 3

I have to agree with @kaizer.se. Use git's ability to stage the modifications into 3 different commits. In this way you have a clear idea of what each modification is and your commit comments will give you the why. On a merge back into your main branch (assuming you're using branches for feature mods) you can roll up these smaller commits into one merge.

Answer 4

I strive not to commit changes which require too many comments, but if there's a need for it I usually do something like this:

Multiple changes:

- done this
- fixed that
- removed other

Maybe some additional explanations.

Try to keep your commits atomic, as far as features are concerned. I stage hunks or lines of code for that when I forget to actually commit after every completed feature.