/ 
Git-Hooks-2.11.0
River stage one • 5 direct dependents • 5 total dependents
/ Git::Hooks::CheckReference

NAME

Git::Hooks::CheckReference - Git::Hooks plugin for checking references

VERSION

version 2.11.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 = CheckReference

  # These users are exempt from all checks
  admin  = joe molly

  # This group is used in a ACL spec below
  groups = cms = mhelena tiago juliana

[githooks "checkreference"]

  # Deny changes on any references by default
  acl = deny  CRUD ^refs/

  # Only users in the @cms group may create, change, or delete tags
  acl = allow CRUD ^refs/tags/ by @cms

  # Users may maintain personal branches under user/<username>/
  acl = allow CRUD ^refs/heads/user/{USER}/

  # Users may only update the vetted branch names
  acl = allow U    ^refs/heads/(?:feature|release|hotfix)/

  # Users in the @cms group may create, rewrite, update, and delete the vetted
  # branch names
  acl = allow CRUD ^refs/heads/(?:feature|release|hotfix)/ by @cms

  # Reject lightweight tags
  require-annotated-tags = true

DESCRIPTION

This Git::Hooks plugin hooks itself to the hooks below to check if the names of references added to or renamed in the repository meet specified constraints. If they don't, the commit/push is aborted.

  • update

  • pre-receive

  • ref-update

  • commit-received

  • submit

To enable it you should add it to the githooks.plugin configuration option:

[githooks]
  plugin = CheckReference

NAME

CheckReference - Git::Hooks plugin for checking references

CONFIGURATION

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

It can be disabled for specific references via the githooks.ref and githooks.noref options about which you can read in the Git::Hooks documentation.

acl RULE

This multi-valued option specifies rules allowing or denying specific users to perform specific actions on specific references. (Common references are branches and tags, but an ACL may refer to any reference under the refs/ name space.) By default any user can perform any action on any reference. So, the rules are used to impose restrictions.

The acls are grokked by the Git::Repository::Plugin::GitHooks's grok_acls method. Please read its documentation for the general documentation.

A RULE takes three or four parts, like this:

(allow|deny) [CRUD]+ <refspec> (by <userspec>)?

Some parts are described below:

  • [CRUD]+

    The second part specifies which actions are being considered by a combination of letters: (C) create a reference, (R) rewrite a reference (a non fast-forward change), (U) update a reference (a fast-forward change), or (D) delete a reference. You can specify one, two, three, or the four letters.

  • <refspec>

    The third part specifies which references are being considered. In its simplest form, a refspec is a complete name starting with refs/ (e.g. refs/heads/master). These refspecs match a single file exactly.

    If the refspec starts with a caret (^) it's interpreted as a Perl regular expression, the caret being kept as part of the regexp. These refspecs match potentially many references (e.g. ^refs/heads/feature/).

    Before being interpreted as a string or as a regexp, any sub-string of it in the form {VAR} is replaced by $ENV{VAR}. This is useful, for example, to interpolate the committer's username in the refspec, in order to create reference name spaces for users.

See the "SYNOPSIS" section for some examples.

require-annotated-tags BOOL

By default one can push lightweight or annotated tags but if you want to require that only annotated tags be pushed to the repository you can set this option to true.

[DEPRECATED] deny REGEXP

This option is deprecated. Please, use an acl option like this instead:

[githooks "checkreference"]
  acl = deny C ^<REGEXP>

This directive denies references with names matching REGEXP.

[DEPRECATED] allow REGEXP

This option is deprecated. Please, use an acl option like this instead:

[githooks "checkreference"]
  acl = allow C ^<REGEXP>

This directive allows references with names matching REGEXP. Since by default all names are allowed this directive is useful only to prevent a githooks.checkreference.deny directive to deny the same name.

The checks are evaluated so that a reference is denied only if it's name matches any deny directive and none of the allow directives. So, for instance, you would apply it like this to allow only the creation of branches with names prefixed by feature/, release/, and hotfix/, denying all others.

[githooks "checkreference"]
    deny  = ^refs/heads/
    allow = ^refs/heads/(?:feature|release|hotfix)/

Note that the order of the directives is irrelevant.

REFERENCES

  • update-paranoid

    This module is inspired from the example hook which comes with the Git distribution.

AUTHOR

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

COPYRIGHT AND LICENSE

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