1App::GitHooks(3)      User Contributed Perl Documentation     App::GitHooks(3)
2
3
4

NAME

6       App::GitHooks - Extensible plugins system for git hooks.
7

VERSION

9       Version 1.9.0
10

DESCRIPTION

12       "App::GitHooks" is an extensible and easy to configure git hooks
13       framework that supports many plugins.
14
15       Here's an example of it in action, running the "pre-commit" hook checks
16       before the commit message can be entered:
17
18       Here is another example, with a Perl file that fails compilation this
19       time:
20

SYNOPSIS

22       1.  Install this distribution (with cpanm or your preferred CPAN
23           client):
24
25                   cpanm App::GitHooks
26
27       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
31                   cpanm App::GitHooks::Plugin::BlockNOCOMMIT
32                   cpanm App::GitHooks::Plugin::DetectCommitNoVerify
33                   ...
34
35       3.  Go to the git repository for which you want to set up git hooks,
36           and run:
37
38                   githooks install
39
40       4.  Enjoy!
41

GIT REQUIREMENTS

43       App::GitHooks requires git v1.7.4.1 or above.
44

VALID GIT HOOK NAMES

46       •   applypatch-msg
47
48       •   pre-applypatch
49
50       •   post-applypatch
51
52       •   pre-commit
53
54       •   prepare-commit-msg
55
56       •   commit-msg
57
58       •   post-commit
59
60       •   pre-rebase
61
62       •   post-checkout
63
64       •   post-merge
65
66       •   pre-receive
67
68       •   update
69
70       •   post-receive
71
72       •   post-update
73
74       •   pre-auto-gc
75
76       •   post-rewrite
77

OFFICIALLY SUPPORTED PLUGINS

79       •   App::GitHooks::Plugin::BlockNOCOMMIT
80
81           Prevent committing code with #NOCOMMIT mentions.
82
83       •   App::GitHooks::Plugin::BlockProductionCommits
84
85           Prevent commits in a production environment.
86
87       •   App::GitHooks::Plugin::DetectCommitNoVerify
88
89           Find out when someone uses --no-verify and append the pre-commit
90           checks to the commit message.
91
92       •   App::GitHooks::Plugin::ForceRegularUpdate
93
94           Force running a specific tool at regular intervals.
95
96       •   App::GitHooks::Plugin::MatchBranchTicketID
97
98           Detect discrepancies between the ticket ID specified by the branch
99           name and the one in the commit message.
100
101       •   App::GitHooks::Plugin::PerlCompile
102
103           Verify that Perl files compile without errors.
104
105       •   App::GitHooks::Plugin::PerlCritic
106
107           Verify that all changes and addition to the Perl files pass
108           PerlCritic checks.
109
110       •   App::GitHooks::Plugin::PerlInterpreter
111
112           Enforce a specific Perl interpreter on the first line of Perl
113           files.
114
115       •   App::GitHooks::Plugin::PgBouncerAuthSyntax
116
117           Verify that the syntax of PgBouncer auth files is correct.
118
119       •   App::GitHooks::Plugin::PrependTicketID
120
121           Derive a ticket ID from the branch name and prepend it to the
122           commit-message.
123
124       •   App::GitHooks::Plugin::RequireCommitMessage
125
126           Require a commit message.
127
128       •   App::GitHooks::Plugin::RequireTicketID
129
130           Verify that staged Ruby files compile.
131
132       •   App::GitHooks::Plugin::ValidatePODFormat
133
134           Validate POD format in Perl and POD files.
135

CONTRIBUTED PLUGINS

137       •   App::GitHooks::Plugin::RubyCompile
138
139           Verify that staged Ruby files compile.
140
141       •   App::GitHooks::Plugin::PreventTrailingWhitespace
142
143           Prevent trailing whitespace from being committed.
144

CONFIGURATION OPTIONS

146   Configuration format
147       App::GitHooks uses Config::Tiny, so the configuration should follow the
148       following format:
149
150               general_key_1 = value
151               general_key_2 = value
152
153               [section_1]
154               section_1_key 1 = value
155
156       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
161   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
165       •   A file of any name anywhere on your system, if you set the
166           environment variable "GITHOOKSRC_FORCE" to its path.
167
168           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
173       •   A ".githooksrc" file at the root of the git repository.
174
175           The settings will then only apply to that repository.
176
177       •   A file of any name anywhere on your system, if you set the
178           environment variable "GITHOOKSRC" to its path.
179
180           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
184       •   A ".githooksrc" file in the home directory of the current user.
185
186           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
194   General configuration options
195       •   project_prefixes
196
197           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
201                   project_prefixes = OPS, DEV
202
203       •   extract_ticket_id_from_commit
204
205           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
209                   extract_ticket_id_from_commit = /^($project_prefixes-\d+|--): /
210
211       •   extract_ticket_id_from_branch
212
213           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
218                   extract_ticket_id_from_branch = /^($project_prefixes-?\d+)/
219
220       •   normalize_branch_ticket_id
221
222           A replacement expression that normalizes the ticket ID captured
223           with "extract_ticket_id_from_branch".
224
225                   normalize_branch_ticket_id = s/^(.*?)-?(\d+)$/\U$1-$2/
226
227       •   skip_directories
228
229           A regular expression to filter the directory names that should be
230           skipped when analyzing files as part of file-level checks.
231
232                   skip_directories = /^cpan(?:-[^\/]+)?\//
233
234       •   force_plugins
235
236           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
241                   force_plugins = App::GitHooks::Plugin::ValidatePODFormat, App::GitHooks::Plugin::RequireCommitMessage
242
243       •   min_app_githooks_version
244
245           Specify the minimum version of App::GitHooks.
246
247                   min_app_githooks_version = 1.9.0
248
249   Testing-specific options
250       •   limit_plugins
251
252           Deprecated. Use "force_plugins" instead.
253
254       •   force_interactive
255
256           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
260       •   force_use_colors
261
262           Force the output to use colors (`1`) or to not use colors (`0`)
263           independently of the ability of STDOUT to display colors.
264
265       •   force_is_utf8
266
267           Allows the output to use utf-8 characters (`1`) or not (`0`),
268           independently of whether the output declares supporting utf-8.
269
270       •   commit_msg_no_edit
271
272           Allows skipping the loop to edit the message when the commit
273           message checks failed.
274

ENVIRONMENT VARIABLES

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
280               GITHOOKS_SKIP=pre-commit,update
281
282   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
286               GITHOOKS_DISABLE=1
287
288   GITHOOKSRC
289       Contains path to a custom configuration file, see "Configuration file
290       locations" above.
291
292   GITHOOKSRC_FORCE
293       Similar to "GITHOOKSRC" but with a higher priority. See "Configuration
294       file locations" above.
295

FUNCTIONS

297   run()
298       Run the specified hook.
299
300               App::GitHooks::run(
301                       name      => $name,
302                       arguments => \@arguments,
303               );
304
305       Arguments:
306
307       •   name (mandatory)
308
309           The name of the git hook calling this class. See the "VALID GIT
310           HOOK NAMES" section for acceptable values.
311
312       •   arguments (optional)
313
314           An arrayref of arguments passed originally to the git hook.
315
316       •   exit (optional, default 1)
317
318           Indicate whether the method should exit (1) or simply return the
319           exit status without actually exiting (0).
320

METHODS

322   new()
323       Create a new "App::GitHooks" object.
324
325               my $app = App::GitHooks->new(
326                       name      => $name,
327                       arguments => \@arguments,
328               );
329
330       Arguments:
331
332       •   name (mandatory)
333
334           The name of the git hook calling this class. See the "VALID GIT
335           HOOK NAMES" section for acceptable values.
336
337       •   arguments (optional)
338
339           An arrayref of arguments passed originally to the git hook.
340
341   clone()
342       Clone the current object and override its properties with the arguments
343       specified.
344
345               my $cloned_app = $app->clone(
346                       name => $hook_name, # optional
347               );
348
349       •   name (optional)
350
351           The name of the invoking hook.
352
353   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
357               my $plugins = $app->get_hook_plugins(
358                       $hook_name
359               );
360
361       Arguments:
362
363       •   $hook_name
364
365           The name of the git hook for which to find available plugins.
366
367   get_all_plugins()
368       Return a hashref of the plugins available for every git hook.
369
370               my $all_plugins = $self->get_all_plugins();
371
372   get_config()
373       Retrieve the configuration information for the current project.
374
375               my $config = $app->get_config();
376
377   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
381               # Retrieve the current setting.
382               my $force_non_interactive = $app->force_non_interactive();
383
384               # Force non-interactive mode.
385               $app->force_non_interactive( 1 );
386
387               # Go back to the default behavior of detecting the current mode.
388               $app->force_non_interactive( 0 );
389
390   get_failure_character()
391       Return a character to use to indicate a failure.
392
393               my $failure_character = $app->get_failure_character()
394
395   get_success_character()
396       Return a character to use to indicate a success.
397
398               my $success_character = $app->get_success_character()
399
400   get_warning_character()
401       Return a character to use to indicate a warning.
402
403               my $warning_character = $app->get_warning_character()
404
405   get_staged_changes()
406       Return a "App::GitHooks::StagedChanges" object corresponding to the
407       changes staged in the current project.
408
409               my $staged_changes = $app->get_staged_changes();
410
411   use_colors()
412       Allows disabling the use of colors in "App::GitHooks"'s output.
413
414               # Retrieve the current setting.
415               my $use_colors = $app->use_colors();
416
417               # Disable colors in the output.
418               $app->use_colors( 0 );
419

ACCESSORS

421   get_repository()
422       Return the underlying "Git::Repository" object for the current project.
423
424               my $repository = $app->get_repository();
425
426   get_remote_name()
427       Get the name of the repository.
428
429               my $remote_name = $app->get_remote_name();
430
431   get_hook_name
432       Return the name of the git hook that called the current instance.
433
434               my $hook_name = $app->get_hook_name();
435
436   get_command_line_arguments()
437       Return the arguments passed originally to the git hook.
438
439               my $command_line_arguments = $app->get_command_line_arguments();
440
441   get_terminal()
442       Return the "App::GitHooks::Terminal" object associated with the current
443       instance.
444
445               my $terminal = $app->get_terminal();
446

DISPLAY METHODS

448   wrap()
449       Format information while respecting the format width and indentation.
450
451               my $string = $app->wrap( $information, $indent );
452
453   color()
454       Print text with colors.
455
456               $app->color( $color, $text );
457

PRIVATE FUNCTIONS

459   _to_camelcase()
460       Convert a dash-separated string to camelcase.
461
462               my $camelcase_string = App::GitHooks::_to_camelcase( $string );
463
464       This function is useful to convert git hook names (commit-msg) to
465       module names (CommitMsg).
466
467   _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
472               return if _should_skip( $name );
473

NOTES

475   Manual installation
476       Symlink your git hooks under .git/hooks to a file with the following
477       content:
478
479               #!/usr/bin/perl
480
481               use strict;
482               use warnings;
483
484               use App::GitHooks;
485
486               App::GitHooks->run(
487                               name      => $0,
488                               arguments => \@ARGV,
489               );
490
491       All you need to do then is install the plugins you are interested in!
492
493       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
497       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

BUGS

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

SUPPORT

508       You can find documentation for this module with the perldoc command.
509
510               perldoc App::GitHooks
511
512       You can also look for information at:
513
514       •   GitHub's request tracker
515
516           <https://github.com/guillaumeaubert/App-GitHooks/issues>
517
518       •   AnnoCPAN: Annotated CPAN documentation
519
520           <http://annocpan.org/dist/app-githooks>
521
522       •   CPAN Ratings
523
524           <http://cpanratings.perl.org/d/app-githooks>
525
526       •   MetaCPAN
527
528           <https://metacpan.org/release/App-GitHooks>
529

AUTHOR

531       Guillaume Aubert <https://metacpan.org/author/AUBERTG>, "<aubertg at
532       cpan.org>".
533
535       Copyright 2013-2017 Guillaume Aubert.
536
537       This code is free software; you can redistribute it and/or modify it
538       under the same terms as Perl 5 itself.
539
540       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.
544
545
546
547perl v5.34.0                      2022-01-20                  App::GitHooks(3)
Impressum