NAME

commit-msg - Edit commit messages to insert a Change-Id tag.

DESCRIPTION

A Git hook automatically invoked by git commit, and most other commit creation tools such as git citool or git gui. The Gerrit Code Review supplied implementation of this hook is a short shell script which automatically inserts a globally unique Change-Id tag in the footer of a commit message. When present, Gerrit uses this tag to track commits across cherry-picks and rebases.

After the hook has been installed in the user’s local Git repository for a project, the hook will modify a commit message such as:

Improve foo widget by attaching a bar.

We want a bar, because it improves the foo by providing more
wizbangery to the dowhatimeanery.

Signed-off-by: A. U. Thor <author@example.com>

by inserting a new `Change-Id: ` line in the footer:

Improve foo widget by attaching a bar.

We want a bar, because it improves the foo by providing more
wizbangery to the dowhatimeanery.

Change-Id: Ic8aaa0728a43936cd4c6e1ed590e01ba8f0fbf5b
Signed-off-by: A. U. Thor <author@example.com>

The hook implementation is reasonably intelligent at inserting the Change-Id line before any Signed-off-by or Acked-by lines placed at the end of the commit message by the author, but if no such lines are present then it will just insert a blank line, and add the Change-Id at the bottom of the message.

If a Change-Id line is already present in the message footer, the script will do nothing, leaving the existing Change-Id unmodified. This permits amending an existing commit, or allows the user to insert the Change-Id manually after copying it from an existing change viewed on the web.

The Change-Id will not be added if gerrit.createChangeId is set to false in the git config.

If gerrit.reviewUrl is set to the base URL of the Gerrit server that changes are uploaded to (e.g. https://gerrit-review.googlesource.com/) in the git config, then instead of adding a Change-Id trailer, a Link trailer will be inserted that will look like this:

Improve foo widget by attaching a bar.

We want a bar, because it improves the foo by providing more
wizbangery to the dowhatimeanery.

Link: https://gerrit-review.googlesource.com/id/Ic8aaa0728a43936cd4c6e1ed590e01ba8f0fbf5b
Signed-off-by: A. U. Thor <author@example.com>

This link will become a valid link to the review page once the change is uploaded to the Gerrit server. Newer versions of the Gerrit server will read the change identifier out of the appropriate Link trailer and treat it in the same way as the change identifier in a Change-Id trailer.

OBTAINING

To obtain the commit-msg script use scp, wget or curl to download it to your local system from your Gerrit server.

You can use either of the below commands:

$ scp -p -P 29418 <your username>@<your Gerrit review server>:hooks/commit-msg <local path to your git>/.git/hooks/

$ curl -Lo <local path to your git>/.git/hooks/commit-msg <your Gerrit http URL>/tools/hooks/commit-msg

A specific example of this might look something like this:

$ scp -p -P 29418 john.doe@review.example.com:hooks/commit-msg ~/duhproject/.git/hooks/

$ curl -Lo ~/duhproject/.git/hooks/commit-msg http://review.example.com/tools/hooks/commit-msg

Make sure the hook file is executable:

$ chmod u+x ~/duhproject/.git/hooks/commit-msg

SEE ALSO

IMPLEMENTATION

The hook generates unique Change-Id lines by creating a virtual commit object within the local Git repository, and obtaining the SHA-1 hash from it. Like any other Git commit, the following properties are included in the computation:

  • SHA-1 of the tree being committed

  • SHA-1 of the parent commit

  • Name, email address, timestamp of the author

  • Name, email address, timestamp of the committer

  • Proposed commit message (before Change-Id was inserted)

Because the names of the tree and parent commit, as well as the committer timestamp are included in the hash computation, the output Change-Id is sufficiently unique.

Part of Gerrit Code Review