Git conventions

Commits

• Each commit should be a single logical change. Don't make several logical changes in one commit. For example, if a patch fixes a bug and optimizes the performance of a feature, split it into two separate commits.

  Tip: Use git add -p to interactively stage specific portions of the modified files.

• Don't split a single logical change into several commits. For example, the implementation of a feature and the corresponding tests should be in the same commit.

• Commit early and often. Small, self-contained commits are easier to understand and revert when something goes wrong.

• Commits should be ordered logically. For example, if commit X depends on changes done in commit Y, then commit Y should come before commit X.

Note: While working alone on a local branch that has not yet been pushed, it's fine to use commits as temporary snapshots of your work. However, it still holds true that you should apply all of the above before pushing it.

Messages

• Use the editor, not the terminal, when writing a commit message:

  # good
  $ git commit
  
  # bad
  $ git commit -m "Quick fix"

  Committing from the terminal encourages a mindset of having to fit everything in a single line which usually results in non-informative, ambiguous commit messages.

• The summary line (ie. the first line of the message) should be descriptive yet succinct. Ideally, it should be no longer than 50 characters. It should be capitalized and written in imperative present tense. It should not end with a period since it is effectively the commit title:

  # good - imperative present tense, capitalized, fewer than 50 characters
  Mark huge records as obsolete when clearing hinting faults
  
  # bad
  fixed ActiveModel::Errors deprecation messages failing when AR was used outside of Rails.

• After that should come a blank line followed by a more thorough description. It should be wrapped to 72 characters and explain why the change is needed, how it addresses the issue and what side-effects it might have.

  It should also provide any pointers to related resources (eg. link to the corresponding issue in a bug tracker):

  Short (50 chars or fewer) summary of changes
  
  More detailed explanatory text, if necessary. Wrap it to
  72 characters. In some contexts, the first
  line is treated as the subject of an email and the rest of
  the text as the body.  The blank line separating the
  summary from the body is critical (unless you omit the body
  entirely); tools like rebase can get confused if you run
  the two together.
  
  Further paragraphs come after blank lines.
  
  - Bullet points are okay, too
  
  - Use a hyphen or an asterisk for the bullet,
    followed by a single space, with blank lines in
    between
  
  Source http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html
  

  Ultimately, when writing a commit message, think about what you would need to know if you run across the commit in a year from now.

• If a commit A depends on commit B, the dependency should be stated in the message of commit A. Use the SHA1 when referring to commits.

  Similarly, if commit A solves a bug introduced by commit B, it should also be stated in the message of commit A.

  Misc

• Test before you push. Do not push half-done work.

• Use annotated tags for marking releases or other important points in the history. Prefer lightweight tags for personal use, such as to bookmark commits for future reference.

Selectively taken from agis-/git-style-guide.