| :linkattrs: |
| = commit-msg Hook |
| |
| |
| == 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 |
| |
| |
| * link:user-changeid.html[Change-Id Lines] |
| * link:http://www.kernel.org/pub/software/scm/git/docs/git-commit.html[git-commit(1),role=external,window=_blank] |
| * link:http://www.kernel.org/pub/software/scm/git/docs/githooks.html[githooks(5),role=external,window=_blank] |
| |
| == 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. |
| |
| GERRIT |
| ------ |
| Part of link:index.html[Gerrit Code Review] |
| |
| SEARCHBOX |
| --------- |
