- COPYRIGHT AND LICENSE
Git::Hooks::PrepareLog - Git::Hooks plugin to prepare commit messages before being edited
Git::Hooks plugin you don't use this Perl module directly. Instead, you may configure it in a Git configuration file like this:
[githooks] plugin = PrepareLog [githooks "preparelog"] issue-branch-regex = [A-Z]+-\\d+ issue-place = key Jira
The first section enables the plugin.
The second section makes the message include an issue ID grokked by the current branch name. If the current branch matches the
issue-branch-regex option it's name will be used as the issue ID. In this case, it matches a JIRA ID. The
issue-place option specifies that the JIRA ID should be inserted as a message trailer, keyed by "JIRA". For example:
This Git::Hooks plugin hooks itself to the
prepare-commit-msg. It's invoked during a Git commit in order to prepare the commit log message before invoking the editor. It should be used to pre-format or to insert automatic information in the message before the user is given a chance to edit it. If you want to check problems in the message you should use the Git::Hooks::CheckLog plugin instead.
prepare-commit-msg is invoked in every commit, but the plugin only changes the message if it's a new commit and not if it's the result of an amend, a merge, or if the message is provided via the
-m or the
-F options, because it assumes that preexisting messages shouldn't be re-prepared. Hence, the plugin simply skips these types of commits.
Even though it's not intended to "check" the message it's possible that the plugin encounters a few problems. In these situations it will abort the commit with a suitable message.
To enable the plugin you should add it to the githooks.plugin configuration option:
git config --add githooks.plugin PrepareLog
Git::Hooks::PrepareLog - Git::Hooks plugin to prepare commit log messages before being edited
The plugin is configured by the following git options.
This option enables the issue inserting feature, which inserts an issue ID (aka bug-id) in the message, making the commit refer to the project issue which required the change made by the commit. It's very common, in large or enterprise projects, to require that every commit cites at least one issue in the project's issue management system. In fact, the Git::Hooks::CheckJira plugin is used to require the citation of JIRA issues in commit messages.
It's cumbersome for the developer to have to insert issue IDs for every commit message. In order to make it automatic, as a developer, you enable this plugin and configures this option to match the syntax of your issue IDs. Then, when you start to work on a new issue, you should create a local branch named after the issue ID and let this plugin insert it into your commit messages for you.
If you're using JIRA, for example, the issue IDs are strings like
HD-1000. In this case, you can configure it like this:
[githooks "preparelog"] issue-branch-regex = [A-Z]+-\\d+
The regex provided does not need to match the whole current branch name, only a word inside it.
If your issue ID is very simple, such as a number, you can capture it with a group in the regex. Like this:
[githooks "preparelog"] issue-branch-regex = issue-(\\d+)
In this case you should name your branches as
issue-NNN and the plugin will understand that the issue ID is just what matched the first group in the regex.
If your branch does not match the regex, the plugin will not prepare the log message.
This options specifies where in the log message the issue ID should be inserted. For now there are two possibilities which you may specify with SPECs like this:
- title FORMAT
This makes the issue ID be inserted in the log message's title, i.e., in its first line. The FORMAT specifies how the title should be changed in order to incorporate the issue ID. It's a string which should contain two format codes:
%Tcode is replaced by the original title, if any. And the
%Icode is replaced by the issue ID.
The default value of this option is
title [%I] %T, which makes the issue ID be prefixed to the title, enclosed in brackets.
Other common formats are these:
- trailer KEY
Inserting the issue ID in the title makes it stand out, but it can make the title very wide and distract from its main purpose which is to tell succinctly what the commit does. In fact, if you are using Git::Hooks::CheckLog plugin to limit the log message title's width the insertion of issue IDs in it can make you overflow that limit often.
You can insert the issue ID as a trailer to the log message instead, in order to solve these problems. You must simply choose a KEY for the trailer. If you're using JIRA you can use
Jiraas the key. Other generic common choices are
Bug. In this case, your issue ID will appear at the end of the log message, something like this:
The key is always capitalized, so that in this case it will be
Jiraeven if you specified
jirain the format.
Note that this format only works with Git 2.7.0 and later, because we rely on the git interpret-trailers command with the
--in-placeoption, which was implemented in that Git version. If you're using an older Git an error message will tell you that.
Git command used to insert trailers in the commit log messages.
Gustavo L. de M. Chaves <email@example.com>
This software is copyright (c) 2018 by CPqD <www.cpqd.com.br>.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.