GoogleGit

blob: e1021865e348b7757e0fd0e7148781068fd8ba98 [file] [log] [blame]
  1. = commit-msg Hook
  2. == NAME
  3. commit-msg - Edit commit messages to insert a `Change-Id` tag.
  4. == DESCRIPTION
  5. A Git hook automatically invoked by `git commit`, and most other
  6. commit creation tools such as `git citool` or `git gui`. The Gerrit
  7. Code Review supplied implementation of this hook is a short shell
  8. script which automatically inserts a globally unique `Change-Id` tag
  9. in the footer of a commit message. When present, Gerrit uses this
  10. tag to track commits across cherry-picks and rebases.
  11. After the hook has been installed in the user's local Git repository
  12. for a project, the hook will modify a commit message such as:
  13. ----
  14. Improve foo widget by attaching a bar.
  15. We want a bar, because it improves the foo by providing more
  16. wizbangery to the dowhatimeanery.
  17. Signed-off-by: A. U. Thor <author@example.com>
  18. ----
  19. by inserting a new `Change-Id: ` line in the footer:
  20. ----
  21. Improve foo widget by attaching a bar.
  22. We want a bar, because it improves the foo by providing more
  23. wizbangery to the dowhatimeanery.
  24. Change-Id: Ic8aaa0728a43936cd4c6e1ed590e01ba8f0fbf5b
  25. Signed-off-by: A. U. Thor <author@example.com>
  26. ----
  27. The hook implementation is reasonably intelligent at inserting the
  28. `Change-Id` line before any `Signed-off-by` or `Acked-by` lines placed
  29. at the end of the commit message by the author, but if no such
  30. lines are present then it will just insert a blank line, and add
  31. the `Change-Id` at the bottom of the message.
  32. If a `Change-Id` line is already present in the message footer, the
  33. script will do nothing, leaving the existing `Change-Id` unmodified.
  34. This permits amending an existing commit, or allows the user to
  35. insert the Change-Id manually after copying it from an existing
  36. change viewed on the web.
  37. The `Change-Id` will not be added if `gerrit.createChangeId` is set
  38. to `false` in the git config.
  39. == OBTAINING
  40. To obtain the `commit-msg` script use `scp`, `wget` or `curl` to download
  41. it to your local system from your Gerrit server.
  42. You can use either of the below commands:
  43. ====
  44. $ scp -p -P 29418 <your username>@<your Gerrit review server>:hooks/commit-msg <local path to your git>/.git/hooks/
  45. $ curl -Lo <local path to your git>/.git/hooks/commit-msg <your Gerrit http URL>/tools/hooks/commit-msg
  46. ====
  47. A specific example of this might look something like this:
  48. .Example
  49. ====
  50. $ scp -p -P 29418 john.doe@review.example.com:hooks/commit-msg ~/duhproject/.git/hooks/
  51. $ curl -Lo ~/duhproject/.git/hooks/commit-msg http://review.example.com/tools/hooks/commit-msg
  52. ====
  53. Make sure the hook file is executable:
  54. ====
  55. $ chmod u+x ~/duhproject/.git/hooks/commit-msg
  56. ====
  57. == SEE ALSO
  58. * link:user-changeid.html[Change-Id Lines]
  59. * link:http://www.kernel.org/pub/software/scm/git/docs/git-commit.html[git-commit(1)]
  60. * link:http://www.kernel.org/pub/software/scm/git/docs/githooks.html[githooks(5)]
  61. == IMPLEMENTATION
  62. The hook generates unique `Change-Id` lines by creating a virtual
  63. commit object within the local Git repository, and obtaining the
  64. SHA-1 hash from it. Like any other Git commit, the following
  65. properties are included in the computation:
  66. * SHA-1 of the tree being committed
  67. * SHA-1 of the parent commit
  68. * Name, email address, timestamp of the author
  69. * Name, email address, timestamp of the committer
  70. * Proposed commit message (before `Change-Id` was inserted)
  71. Because the names of the tree and parent commit, as well as the
  72. committer timestamp are included in the hash computation, the output
  73. `Change-Id` is sufficiently unique.
  74. GERRIT
  75. ------
  76. Part of link:index.html[Gerrit Code Review]
  77. SEARCHBOX
  78. ---------