NAME
Git::Hooks::CheckJira - Git::Hooks plugin which requires citation of JIRA issues in commit messages.
VERSION
version 0.030
DESCRIPTION
This Git::Hooks plugin can act as any of the below hooks to guarantee that every commit message cites at least one valid JIRA issue key in its log message, so that you can be certain that every change has a proper change request (a.k.a. ticket) open.
commit-msg
-
This hook is invoked during the commit, to check if the commit message cites valid JIRA issues.
update
-
This hook is invoked multiple times in the remote repository during
git push
, once per branch being updated, to check if the commit message cites valid JIRA issues. pre-receive
-
This hook is invoked once in the remote repository during
git push
, to check if the commit message cites valid JIRA issues.
It requires that any Git commits affecting all or some branches must make reference to valid JIRA issues in the commit log message. JIRA issues are cited by their keys which, by default, consist of a sequence of uppercase letters separated by an hyphen from a sequence of digits. E.g., CDS-123
, RT-1
, and GIT-97
.
To enable it you should define the appropriate Git configuration option:
git config --add githooks.commit-msg CheckJira
git config --add githooks.update CheckJira
git config --add githooks.pre-receive CheckJira
NAME
CheckJira - Git::Hooks plugin which requires citation of JIRA issues in commit messages.
CONFIGURATION
The plugin is configured by the following git options.
CheckJira.ref REFSPEC
By default, the message of every commit is checked. If you want to have them checked only for some refs (usually some branch under refs/heads/), you may specify them with one or more instances of this option.
The refs can be specified as a complete ref name (e.g. "refs/heads/master") or by a regular expression starting with a caret (^
), which is kept as part of the regexp (e.g. "^refs/heads/(master|fix)").
CheckJira.userenv STRING
This variable is deprecated. Please, use the githooks.userenv
variable, which is defined in the Git::Hooks module. Please, see its documentation to understand it.
CheckJira.admin USERSPEC
This variable is deprecated. Please, use the githooks.admin
variable, which is defined in the Git::Hooks module. Please, see its documentation to understand it.
CheckJira.jiraurl URL
This option specifies the JIRA server HTTP URL, used to construct the JIRA::Client
object which is used to interact with your JIRA server. Please, see the JIRA::Client documentation to know about them.
CheckJira.jirauser USERNAME
This option specifies the JIRA server username, used to construct the JIRA::Client
object.
CheckJira.jirapass PASSWORD
This option specifies the JIRA server password, used to construct the JIRA::Client
object.
CheckJira.matchkey REGEXP
By default, JIRA keys are matched with the regex /\b[A-Z][A-Z]+-\d+\b/
, meaning, a sequence of two or more capital letters, followed by an hyphen, followed by a sequence of digits. If you customized your JIRA project keys (https://confluence.atlassian.com/display/JIRA/Configuring+Project+Keys), you may need to customize how this hook is going to match them. Set this option to a suitable regex to match a complete JIRA issue key.
CheckJira.matchlog REGEXP
By default, JIRA keys are looked for in all of the commit message. However, this can lead to some false positives, since the default issue pattern can match other things besides JIRA issue keys. You may use this option to restrict the places inside the commit message where the keys are going to be looked for.
For example, set it to \[([^]]+)\]
to require that JIRA keys be cited inside the first pair of brackets found in the message.
CheckJira.project STRING
By default, the committer can reference any JIRA issue in the commit log. You can restrict the allowed keys to a set of JIRA projects by specifying a JIRA project key to this option. You can enable more than one project by specifying more than one value to this option.
CheckJira.require [01]
By default, the log must reference at least one JIRA issue. You can make the reference optional by setting this option to 0.
CheckJira.unresolved [01]
By default, every issue referenced must be unresolved, i.e., it must not have a resolution. You can relax this requirement by setting this option to 0.
CheckJira.by-assignee [01]
By default, the committer can reference any valid JIRA issue. Setting this value 1 requires that the user doing the push/commit (as specified by the userenv
configuration variable) be the current issue's assignee.
CheckJira.check-code CODESPEC
If the above checks aren't enough you can use this option to define a custom code to check your commits. The code may be specified directly as the option's value or you may specify it indirectly via the filename of a script. If the option's value starts with "file:", the remaining is treated as the script filename, which is executed by a do command. Otherwise, the option's value is executed directly by an eval. Either way, the code must end with the definition of a routine, which will be called once for each commit with the following arguments:
- GIT
-
The Git repository object used to grok information about the commit.
- COMMITID
-
The SHA-1 id of the Git commit. It is undef in the
commit-msg
hook, because there is no commit yet. - JIRA
-
The JIRA::Client object used to talk to the JIRA server.
- ISSUES...
-
The remaining arguments are RemoteIssue objects representing the issues being cited by the commit's message.
The subroutine must simply return with no value to indicate success and must die to indicate failure.
EXPORTS
This module exports two routines that can be used directly without using all of Git::Hooks infrastructure.
check_affected_refs GIT
This is the routine used to implement the update
and the pre-receive
hooks. It needs a Git::More
object.
check_message_file GIT, MSGFILE
This is the routine used to implement the commit-msg
hook. It needs a Git::More
object and the name of a file containing the commit message.
SEE ALSO
Git::More
JIRA::Client
REFERENCES
This script is heavily inspired (and sometimes derived) from Joyjit Nath's git-jira-hook (https://github.com/joyjit/git-jira-hook).
AUTHOR
Gustavo L. de M. Chaves <gnustavo@cpan.org>
COPYRIGHT AND LICENSE
This software is copyright (c) 2012 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.