Clone wiki

petsc / writing-commit-messages


ComponentName: one-line explanation of commit

After a blank line, write a more detailed explanation of the commit.
Many tools do not auto-wrap this part, so wrap paragraph text at a
reasonable length. Commit messages are meant for other people to read,
possibly months or years later, so describe the rationale for the change
in a manner that will make sense later.

If any interfaces have changed, the commit should fix occurrences in
PETSc itself and the message should state its impact on users.

If this affects any known issues, include "fix #ISSUENUMBER" or
"see #ISSUENUM" in the message (without quotes). Bitbucket will create
a link to the issue as well as a link from the issue to this commit,
notifying anyone that was watching the issue. Feel free to link to
mailing list discussions or [petsc-maint #NUMBER].

Formatted tags in commit messages:

We have defined several standard tags you should use; this makes it easy
to search for specific types of contributions. Multiple tags may be used
in the same commit message.

* If other people contributed significantly to a commit, perhaps by
reporting bugs or by writing an initial version of the patch,
acknowledge them using tags at the end of the commit message.

Reported-by: Helpful User <>
Based-on-patch-by: Original Idea <>
Thanks-to: Incremental Improver <>

* If work is done for a particular well defined funding 
source or project you should label the commit with one 
or more of the tags

Funded-by: My funding source
Project: My project name
Time: n hours

Some possible values for Funded-by:
* P-ECP - preliminary work on the Exascale Computing Project
* IDEAS - work on interoperability/bug fixes with Hypre, SuperLU, Trilinos
* PETSc-ODEs - work funded by Emil, Lois, Barry's base ASCRC program 
* PETSc-hierarchical - work funded by the base ASCR program in hierarchical solvers

Commit message template

In order to remember tags for commit messages you can create
a file ~/git/.gitmessage containing the tags. Then on each commit 
git automatically includes these in the editor. Just remember to 
always delete the ones you do not use. For example I have


Searching git on commit messages

Once you have started using tags it is possible to search the
commit history for all contributions for a single project etc.

* Get summary of all commits Funded by a particular source
  git log --all --grep='Funded-by: P-ECP’ --reverse [-stat or -shortstat]

* Get the number of insertions 
 git log --all --grep='Funded-by: P-ECP' --reverse --shortstat | grep changed | cut -f5 -d" " | awk '{total += $NF} END { print total }'

* Get the number of deletions
 git log --all --grep='Funded-by: P-ECP' --reverse --shortstat | grep changed | cut -f7 -d" " | awk '{total += $NF} END { print total }'

* Get time
 git log --all --grep='Funded-by: P-ECP' | grep Time: | cut -f2 -d":" | sed s/hours//g | sed s/hour//g |awk '{total += $NF} END { print total }'

Merge commits

Do not use -m 'useless merge statement' when performing a merge. Instead, let git merge set up a commit message in your editor. It will look something like this:

Merge branch 'master' into yourname/your-feature


(perhaps without a Conflicts section if there are no conflicts). In your editor, add a short description of why you are merging. The final commit can look something like this:

Merge branch 'master' into yourname/your-feature

Obtain symbol visibility (PETSC_INTERN), SNESSetConvergenceHistory()
bug fix, and SNESConvergedDefault() interface change.


It should either be to obtain a specific feature or because some major changes affect you. See the Merging section of the Developer Instructions for more on when to use merges. When merging to an integration branch, a short summary of the purpose of the topic branch is useful.

Further reading