1App::GitHooks(3pm) User Contributed Perl Documentation App::GitHooks(3pm)
2
6 App::GitHooks - Extensible plugins system for git hooks.
7
9 Version 1.9.0
10
12 "App::GitHooks" is an extensible and easy to configure git hooks
13 framework that supports many plugins.
14 Here's an example of it in action, running the "pre-commit" hook checks
16 before the commit message can be entered:
17 Here is another example, with a Perl file that fails compilation this
19 time:
20
22 1. Install this distribution (with cpanm or your preferred CPAN
23 client):
24 cpanm App::GitHooks
26 2. Install the plugins you are interested in (with cpanm or your
28 prefered CPAN client), as "App::GitHooks" does not bundle them. See
29 the list of plugins below, but for example:
30 cpanm App::GitHooks::Plugin::BlockNOCOMMIT
32 cpanm App::GitHooks::Plugin::DetectCommitNoVerify
33 ...
34 3. Go to the git repository for which you want to set up git hooks,
36 and run:
37 githooks install
39 4. Enjoy!
41
43 App::GitHooks requires git v1.7.4.1 or above.
44
46 • applypatch-msg
47 • pre-applypatch
49 • post-applypatch
51 • pre-commit
53 • prepare-commit-msg
55 • commit-msg
57 • post-commit
59 • pre-rebase
61 • post-checkout
63 • post-merge
65 • pre-receive
67 • update
69 • post-receive
71 • post-update
73 • pre-auto-gc
75 • post-rewrite
77
79 • App::GitHooks::Plugin::BlockNOCOMMIT
80 Prevent committing code with #NOCOMMIT mentions.
82 • App::GitHooks::Plugin::BlockProductionCommits
84 Prevent commits in a production environment.
86 • App::GitHooks::Plugin::DetectCommitNoVerify
88 Find out when someone uses --no-verify and append the pre-commit
90 checks to the commit message.
91 • App::GitHooks::Plugin::ForceRegularUpdate
93 Force running a specific tool at regular intervals.
95 • App::GitHooks::Plugin::MatchBranchTicketID
97 Detect discrepancies between the ticket ID specified by the branch
99 name and the one in the commit message.
100 • App::GitHooks::Plugin::PerlCompile
102 Verify that Perl files compile without errors.
104 • App::GitHooks::Plugin::PerlCritic
106 Verify that all changes and addition to the Perl files pass
108 PerlCritic checks.
109 • App::GitHooks::Plugin::PerlInterpreter
111 Enforce a specific Perl interpreter on the first line of Perl
113 files.
114 • App::GitHooks::Plugin::PgBouncerAuthSyntax
116 Verify that the syntax of PgBouncer auth files is correct.
118 • App::GitHooks::Plugin::PrependTicketID
120 Derive a ticket ID from the branch name and prepend it to the
122 commit-message.
123 • App::GitHooks::Plugin::RequireCommitMessage
125 Require a commit message.
127 • App::GitHooks::Plugin::RequireTicketID
129 Verify that staged Ruby files compile.
131 • App::GitHooks::Plugin::ValidatePODFormat
133 Validate POD format in Perl and POD files.
135
137 • App::GitHooks::Plugin::RubyCompile
138 Verify that staged Ruby files compile.
140 • App::GitHooks::Plugin::PreventTrailingWhitespace
142 Prevent trailing whitespace from being committed.
144
146 Configuration format
147 App::GitHooks uses Config::Tiny, so the configuration should follow the
148 following format:
149 general_key_1 = value
151 general_key_2 = value
152 [section_1]
154 section_1_key 1 = value
155 The file is divided between the global configuration options at the
157 beginning of the file (such as "general_key_1" above) and plugin
158 specific configuration options which are located in distinct sections
159 (such as "section_1_key" in the "[section_1]" section).
160 Configuration file locations
162 App::GitHooks supports setting custom options by creating one of the
163 following files, which are searched in descending order of preference:
164 • A file of any name anywhere on your system, if you set the
166 environment variable "GITHOOKSRC_FORCE" to its path.
167 Note that you should normally use "GITHOOKSRC". This option is
169 provided mostly for testing purposes, when configuration options
170 for testing in a reliable manner are of the utmost importance and
171 take precedence over any repository-specific settings.
172 • A ".githooksrc" file at the root of the git repository.
174 The settings will then only apply to that repository.
176 • A file of any name anywhere on your system, if you set the
178 environment variable "GITHOOKSRC" to its path.
179 Note that ".githooksrc" files at the top of a repository or in a
181 user's home directory will take precedence over a file specified by
182 the "GITHOOKSRC" environment variable.
183 • A ".githooksrc" file in the home directory of the current user.
185 The settings will then apply to all the repositories that have
187 hooks set up. Note that if ".githooksrc" file is defined at the
188 root of a repository, that configuration file will take precedence
189 over the one defined in the home directory of the current user (as
190 it is presumably more specific). Auto-merge of options across
191 multiple ".githooksrc" files in an inheritance fashion is not
192 currently supported.
193 General configuration options
195 • project_prefixes
196 A comma-separated list of project prefixes, in case you want to use
198 this in "extract_ticket_id_from_commit" or
199 "extract_ticket_id_from_branch".
200 project_prefixes = OPS, DEV
202 • extract_ticket_id_from_commit
204 A regular expression with _one_ capturing group that will be
206 applied to the first line of a commit message to extract the ticket
207 ID referenced, if there is one.
208 extract_ticket_id_from_commit = /^($project_prefixes-\d+|--): /
210 • extract_ticket_id_from_branch
212 A regular expression with _one_ capturing group that will be
214 applied to branch names to extract a ticket ID. This allows
215 creating one branch per ticket and having the hooks check that the
216 commit messages and the branch names are in sync.
217 extract_ticket_id_from_branch = /^($project_prefixes-?\d+)/
219 • normalize_branch_ticket_id
221 A replacement expression that normalizes the ticket ID captured
223 with "extract_ticket_id_from_branch".
224 normalize_branch_ticket_id = s/^(.*?)-?(\d+)$/\U$1-$2/
226 • skip_directories
228 A regular expression to filter the directory names that should be
230 skipped when analyzing files as part of file-level checks.
231 skip_directories = /^cpan(?:-[^\/]+)?\//
233 • force_plugins
235 A comma-separated list of the plugins that must be present on the
237 system and will be executed. If any plugins from this list are
238 missing, the action will error out. If any other plugins not in
239 this list are installed on the system, they will be ignored.
240 force_plugins = App::GitHooks::Plugin::ValidatePODFormat, App::GitHooks::Plugin::RequireCommitMessage
242 • min_app_githooks_version
244 Specify the minimum version of App::GitHooks.
246 min_app_githooks_version = 1.9.0
248 Testing-specific options
250 • limit_plugins
251 Deprecated. Use "force_plugins" instead.
253 • force_interactive
255 Force the application to consider that the terminal is interactive
257 (`1`) or non-interactive (`0`) independently of whether the actual
258 STDOUT is interactive or not.
259 • force_use_colors
261 Force the output to use colors (`1`) or to not use colors (`0`)
263 independently of the ability of STDOUT to display colors.
264 • force_is_utf8
266 Allows the output to use utf-8 characters (`1`) or not (`0`),
268 independently of whether the output declares supporting utf-8.
269 • commit_msg_no_edit
271 Allows skipping the loop to edit the message when the commit
273 message checks failed.
274
276 GITHOOKS_SKIP
277 Comma separated list of hooks to skip. A warning is issued for each
278 hook that would otherwise be triggered.
279 GITHOOKS_SKIP=pre-commit,update
281 GITHOOKS_DISABLE
283 Works similarly to "GITHOOKS_SKIP", but it skips all the possible
284 hooks. Set it to a true value, e.g. 1.
285 GITHOOKS_DISABLE=1
287 GITHOOKSRC
289 Contains path to a custom configuration file, see "Configuration file
290 locations" above.
291 GITHOOKSRC_FORCE
293 Similar to "GITHOOKSRC" but with a higher priority. See "Configuration
294 file locations" above.
295
297 run()
298 Run the specified hook.
299 App::GitHooks::run(
301 name => $name,
302 arguments => \@arguments,
303 );
304 Arguments:
306 • name (mandatory)
308 The name of the git hook calling this class. See the "VALID GIT
310 HOOK NAMES" section for acceptable values.
311 • arguments (optional)
313 An arrayref of arguments passed originally to the git hook.
315 • exit (optional, default 1)
317 Indicate whether the method should exit (1) or simply return the
319 exit status without actually exiting (0).
320
322 new()
323 Create a new "App::GitHooks" object.
324 my $app = App::GitHooks->new(
326 name => $name,
327 arguments => \@arguments,
328 );
329 Arguments:
331 • name (mandatory)
333 The name of the git hook calling this class. See the "VALID GIT
335 HOOK NAMES" section for acceptable values.
336 • arguments (optional)
338 An arrayref of arguments passed originally to the git hook.
340 clone()
342 Clone the current object and override its properties with the arguments
343 specified.
344 my $cloned_app = $app->clone(
346 name => $hook_name, # optional
347 );
348 • name (optional)
350 The name of the invoking hook.
352 get_hook_plugins()
354 Return an arrayref of all the plugins installed and available for a
355 specific git hook on the current system.
356 my $plugins = $app->get_hook_plugins(
358 $hook_name
359 );
360 Arguments:
362 • $hook_name
364 The name of the git hook for which to find available plugins.
366 get_all_plugins()
368 Return a hashref of the plugins available for every git hook.
369 my $all_plugins = $self->get_all_plugins();
371 get_config()
373 Retrieve the configuration information for the current project.
374 my $config = $app->get_config();
376 force_non_interactive()
378 By default "App::GitHooks" detects whether it is running in interactive
379 mode, but this allows forcing it to run in non-interactive mode.
380 # Retrieve the current setting.
382 my $force_non_interactive = $app->force_non_interactive();
383 # Force non-interactive mode.
385 $app->force_non_interactive( 1 );
386 # Go back to the default behavior of detecting the current mode.
388 $app->force_non_interactive( 0 );
389 get_failure_character()
391 Return a character to use to indicate a failure.
392 my $failure_character = $app->get_failure_character()
394 get_success_character()
396 Return a character to use to indicate a success.
397 my $success_character = $app->get_success_character()
399 get_warning_character()
401 Return a character to use to indicate a warning.
402 my $warning_character = $app->get_warning_character()
404 get_staged_changes()
406 Return a "App::GitHooks::StagedChanges" object corresponding to the
407 changes staged in the current project.
408 my $staged_changes = $app->get_staged_changes();
410 use_colors()
412 Allows disabling the use of colors in "App::GitHooks"'s output.
413 # Retrieve the current setting.
415 my $use_colors = $app->use_colors();
416 # Disable colors in the output.
418 $app->use_colors( 0 );
419
421 get_repository()
422 Return the underlying "Git::Repository" object for the current project.
423 my $repository = $app->get_repository();
425 get_remote_name()
427 Get the name of the repository.
428 my $remote_name = $app->get_remote_name();
430 get_hook_name
432 Return the name of the git hook that called the current instance.
433 my $hook_name = $app->get_hook_name();
435 get_command_line_arguments()
437 Return the arguments passed originally to the git hook.
438 my $command_line_arguments = $app->get_command_line_arguments();
440 get_terminal()
442 Return the "App::GitHooks::Terminal" object associated with the current
443 instance.
444 my $terminal = $app->get_terminal();
446
448 wrap()
449 Format information while respecting the format width and indentation.
450 my $string = $app->wrap( $information, $indent );
452 color()
454 Print text with colors.
455 $app->color( $color, $text );
457
459 _to_camelcase()
460 Convert a dash-separated string to camelcase.
461 my $camelcase_string = App::GitHooks::_to_camelcase( $string );
463 This function is useful to convert git hook names (commit-msg) to
465 module names (CommitMsg).
466 _should_skip()
468 See the environment variables GITHOOKS_SKIP and GITHOOKS_DISABLE above.
469 This function returns the variable name that would be the reason to
470 skip the given hook, or nothing.
471 return if _should_skip( $name );
473
475 Manual installation
476 Symlink your git hooks under .git/hooks to a file with the following
477 content:
478 #!/usr/bin/perl
480 use strict;
482 use warnings;
483 use App::GitHooks;
485 App::GitHooks->run(
487 name => $0,
488 arguments => \@ARGV,
489 );
490 All you need to do then is install the plugins you are interested in!
492 This distribution also includes a "hooks/" directory that you can
494 symlink / copy to ".git/hooks/" instead , to get all the hooks set up
495 properly in one swoop.
496 Important: adjust "#!/usr/bin/perl" as needed, if that line is not a
498 valid interpreter, your git actions will fail with "error: cannot run
499 .git/hooks/[hook name]: No such file or directory".
500
502 Please report any bugs or feature requests through the web interface at
503 <https://github.com/guillaumeaubert/App-GitHooks/issues/new>. I will
504 be notified, and then you'll automatically be notified of progress on
505 your bug as I make changes.
506
508 You can find documentation for this module with the perldoc command.
509 perldoc App::GitHooks
511 You can also look for information at:
513 • GitHub's request tracker
515 <https://github.com/guillaumeaubert/App-GitHooks/issues>
517 • AnnoCPAN: Annotated CPAN documentation
519 <http://annocpan.org/dist/app-githooks>
521 • CPAN Ratings
523 <http://cpanratings.perl.org/d/app-githooks>
525 • MetaCPAN
527 <https://metacpan.org/release/App-GitHooks>
529
531 Guillaume Aubert <https://metacpan.org/author/AUBERTG>, "<aubertg at
532 cpan.org>".
533
535 Copyright 2013-2017 Guillaume Aubert.
536 This code is free software; you can redistribute it and/or modify it
538 under the same terms as Perl 5 itself.
539 This program is distributed in the hope that it will be useful, but
541 WITHOUT ANY WARRANTY; without even the implied warranty of
542 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the LICENSE
543 file for more details.
544perl v5.38.0 2023-07-20 App::GitHooks(3pm)