/ 
Git-Hooks-3.6.0
River stage one • 5 direct dependents • 5 total dependents
/ Git::Hooks::PrepareLog

NAME

Git::Hooks::PrepareLog - Git::Hooks plugin to prepare commit messages before being edited

VERSION

version 3.6.0

SYNOPSIS

As a Git::Hooks plugin you don't use this Perl module directly. Instead, you may configure it in a Git configuration file like this:

[githooks]

  # Enable the plugin
  plugin = PrepareLog

[githooks "preparelog"]

  # Grok issue names from the part of the branch name matching this regular
  # expression, which matches Jira issue IDs.
  issue-branch-regex = [A-Z]+-\\d+

  # The grokked issue ID should be inserted as a message trailer, keyed by
  # "Jira".
  issue-place = key Jira

DESCRIPTION

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.

The prepare-commit-msg is invoked in every commit, but the plugin does not change the message if it's the result of an amend or a merge 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 some 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:

[githooks]
  plugin = PrepareLog

NAME

Git::Hooks::PrepareLog - Git::Hooks plugin to prepare commit log messages before being edited

CONFIGURATION

The plugin is configured by the following git options under the githooks.preparelog subsection.

issue-branch-regex REGEX

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 PRJ-123 and 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.

issue-place SPEC

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: %T and %I. The %T code is replaced by the original title, if any. And the %I code 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:

%I: %T

Prefix the issue ID, separating it by a colon and a space.

%T (%I)

Suffix the issue ID, enclosing it in parenthesis.

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 Jira as the key. Other generic common choices are Issue and Bug. In this case, your issue ID will appear at the end of the log message, something like this:

Jira: PRJ-123

The key is always capitalized, so that in this case it will be Jira even if you specified Jira or jira in 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-place option, which was implemented in that Git version. If you're using an older Git an error message will tell you that.

REFERENCES

AUTHOR

Gustavo L. de M. Chaves <gnustavo@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2023 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.