Differences between revisions 1 and 2
Revision 1 as of 2014-11-22 12:56:02
Size: 18838
Editor: brobecke
Comment: User Manual for proposed git-hooks.
Revision 2 as of 2014-11-22 12:56:52
Size: 18886
Editor: brobecke
Comment: new name clearer.
Deletions are marked like this. Additions are marked like this.
Line 1: Line 1:
## page was renamed from proposed/git-hooks/UG

Git Hooks Users Guide

This document provides a quick reference towards using AdaCore's "Git Hooks", which are the scripts used to manage our git repositories, when new commits get pushed. These scripts are typically responsible for pre-commit checks, and email notifications.

Enabling the hooks

The hooks have been designed to work with both bare and non-bare repositories. But typical usage will be with bare repositories.

o enable the hooks, an administrator needs to replace the "hooks" directory in your git repository by a link to the /hooks directory from a git-hooks checkout, and configure them as outlined below.

Minimum Configuration

The following config options must be set for all repositories. Updates of any kind will be rejected with an appropriate error message until minimum configuration is satisfied.

  • hooks.from-domain

  • hooks.mailinglist

See below for a description of these config options.

Configuration

Configuration File location

The hooks configuration is loaded from a file named project.config in branch refs/meta/config. This file follows the same format as the various git "config" files (Eg. $HOME/.gitconfig).

To update your repository's configuration, you will need to do the following:

  • Check the refs/meta/config branch out;

  • Modify project.config accordingly;

  • Check your change in;
  • Push the updated branch.

Configuration Options for General Use

The following config options are available for general use:

  • hooks.allow-delete-tag (default value: false):

    • By default, deleting a tag is not allowed. To allow it, set this option to true.

  • hooks.allow-non-fast-forward:

    • A coma-separated list of regular expressions matching branch names (NOT reference names; ie 'master', not 'refs/heads/master').

      By default, non-fast-forward updates are only allowed on 'topic' branches (ie branches whose name start with topic/. This option allows us to extend the list of branches where non-fast-forward updates are allowed.

  • hooks.allow-lightweight-tag (default value: false):

    • Lightweight Tags (as opposed to Annotated Tags) are really not meant to be shared, and thus the hooks will reject updates that create a new lightweight tag, unless this config option is defined to true.

  • hooks.combined-style-checking (default value: false):

    • By default, the pre-commit checks are performed on each commit individually. This ensures that none of the commits introduce some style violations. But some developers have found that this policy gets in the way more than it helps, and thus requested that the pre-commit checks be performed on the combination of all commits.

      The general recommendation is to keep commit-by-commit style checks. But to enable combined style-checking, set this config option to true.

  • hooks.disable-merge-commit-checks (default value: false):

    • If set to True, disable the precommit-check in charge of detecting [#UnintentionalMergeCommitsCheck unintentional merge commits].

      /!\ The use of this option is strongly discouraged, as it helps catching mistakes that are easily done, especially by git users who are less experimented.

  • hooks.from-domain:

    • The domain name of the email address used in the 'From:' field for all email notifications being sent (the local part of the email address - before the '@' -, is simply the user name on the host where the hooks are running).
  • hooks.mailinglist:

    • A coma-separated list of email addresses where to send all email notifications.
  • hooks.max-commit-emails (default value: 100):

    • This is mostly a safe-guard against updates with unintended consequences in terms of the number of emails being sent out. If an update is pushed such that the update would trigger a number of commit email notifications greater than the value of this config option, the hooks will reject this update.

      Typically, this happens when a developer merges a large number of changes from an external source, and then pushes it into an AdaCore repository.

  • hooks.max-email-diff-size (default value: 100,000):

    • This config option ensures that patches sent out inside commit email notifications do not exceed a certain size, clogging the mailbox of all recipients. Past a certain size, which is configured via this config option, the diff isn't likely to be useful anymore, and thus gets truncated. A small note is added at the end of the truncated diff to indicate that the truncation took place.

  • hooks.max-rh-line-length (default value: 76):

    • The maximum length for each line in the revision log. If any line exceeds that length, the commit will be rejected. Setting this variable to zero turns this check off entirely.

      Note: We used a default limit of 76 characters instead of 80, because git commands have a tendency to indent the revision history by 4 characters. Similarly, the git hooks also send emails where the revision history also gets indented by 4 characters. This limit ensures that all lines of a commit revision history fit in a standard 80-characters wide terminal.

  • hooks.no-emails:

    • A coma-separated list of regular expressions matching some reference names for which updates should not trigger any email notification.
      The example below turns off email notifications for all branches whose name start with "fsf-", as well as the "thirdparty" branch.

    no-emails = /refs/heads/fsf-.*, /refs/heads/thirdparty

  • hooks.no-precommit-check:

    • A coma-separated list of regular expressions matching some reference names for which pre-commit checks should not be enabled. /!\ Note that this disables all pre-commit checks, including the revision history checks. It is therefore recommended that this option be only used for branches developed outside of AdaCore.

      This is typically used for branches tracking external repositories.
      The example below turns pre-commit-checks off for all branches whose name start with "fsf-", as well as the "thirdparty" branch.

    no-precommit-check = /refs/heads/fsf-.*, /refs/heads/thirdparty
  • hooks. no-rh-style-checks

    • A coma-separated list of regular expressions matching some reference names for which style-checking of the revision logs should not be enabled. /!\ The use of this option is strongly discouraged for branches maintained by AdaCore.

      {i} Revision History style checks can be disabled for a specific commit by using the sequence '(no-rh-check)' in the revision history.
      The example below turns revision logs style-checking off for all branches whose name start with "fsf-", as well as the "thirdparty" branch.

    no-rh-style-checks = /refs/heads/fsf-.*, /refs/heads/thirdparty
  • hooks.style-checker (default value: cvs_check):

    • If provided, the program to call when performing style checks. It is expected that this program follow the same calling convention as cvs_check:

      • The first argument is a dummy argument mimicking an SVN path, and can be ignored;
      • The second argument is the name of the file to be checked, relative to the project's root directory (Eg: path/to/filename.adb). The style-checking program is called with the Current Working Directory (CWD) such that opening that file can be done using the given (relative) filename.

      It is recommended that, unless located in a very standard location always included in the PATH (Eg: /usr/bin), the full path to the program be specified.

  • hooks.tn-required (default value: false):

    • If set to true, the hooks verify that the revision history of all new commits contain a Ticket Number, and reject the update if it is not the case.

      This requirement can be by-passed by using the sequence '(no-tn-check)' or the word 'minor' in the revision history, in lieu of the Ticket Number.

Configuration Options for Debugging

The following config options are recognized, but are only meant to be used for debugging/testing purposes. They should not be used during normal operations.

  • hooks.bcc-file-ci (default value: true):

    • Setting this config option to false prevents the hooks from Bcc'ing file-ci@adacore.com in all emails sent. This option should never be used in any official repository, and is only meant to for testing of the git hooks outside of the testsuite.

  • hooks.debug-level (default value: 0):

    • Setting this debug option to a value higher than zero turns debugging traces on. The higher the value, the more verbose the traces.

Pre-commit Checks

Pre-commit Checks on the Revision History

The hooks verify that the revision histories of all new commits being pushed comply with the rules defined below. This step is skipped for any commit whose revision history contains the '(no-rh-check)' sequence.

Rules enforced on the revision logs:

  • Empty line after subject line

    • By convention, the first line of the revision history should always be the subject of the commit. If additional text is required, an empty line should be inserted between the subject and the rest of the revision history.

YES:
      | The subject of my commit - no other explanation required.

YES:
      | The subject of my commit
      |
      | This is what this commit does.

NO:
      | The subject of my commit
      | This is what this commit does, but an empty line is missing
      | between the subject and this description.
  • Maximum line length in revision history:

    • See [#ConfigMaxRHLineLength hooks.max-rh-line-length].

  • Unedited revision history of merge commits

    • The purpose of this rule is to prevent a merge commit which was unintentionally created to be pushed to the shared repository. This can easily happen when, for instance, forgetting the --rebase option when doing a git pull.

      It works by detecting the default text that git uses as the revision history when the merge does not trigger a merge conflict.
      When a merge was in fact intentional, the revision history of the merge commit must be manually edited to avoid the "Merge branch '[...]" line that git uses by default as the subject of the merge commit. Doing so will satisfy this pre-commit check.

      {i} Although strongly discouraged, this check can be disabled by setting the [#ConfigDisableMergeCommitChecks hooks.disable-merge-commit-checks config option] to True.

  • Merge conflict section

    • When creating a merge commit during which conflicts were discovered and had to be resolved, the default revision history created by git and proposed for edition contains a section at the end that lists the files inside which merge conflicts where found. We do not want this section in the revision history of our commits, so the hooks verify that the author of the commit remembered to delete it.
  • Missing Ticket Number

    • This check is enable only if the hooks.tn-required config option is set. For such repositories, the hooks verify that the revision history contains a Ticket Number.
      This requirement can be by-passed via the use of the word "Minor" (Eg. "Minor reformatting"), or via the sequence "(no-tn-check)". Casing is not taken into account for this rule.

Filename Collisions Pre-commit Check

On Operating Systems such as Darwin or Windows, where the File System is typically case-insensitive, having two files whose name only differ in the casing (Eg: "hello.txt" and "Hello.txt", or "dir/hello.txt" vs "DIR/hello.txt") can cause a lot of confusion. To avoid this, the hooks will reject any commit where such name collision occurs.

This check is disabled on the branches matching the hooks.no-precommit-check config value, or if a valid $HOME/.no_cvs_check file is found (see below).

Pre-commit Checks on the Differences Introduced by the Commit

This is the usual "style check" performed by the cvs_check program, maintained by the infosys team.

Note that the program verifies the entire contents of the files being modified, not just the modified parts.

Controlling the Pre-commit Checks

/!\ Despite the use of very similar names, note the fairly important difference in scope between the hooks.no-precommit-checks config option, and the no-precommit-check git attribute! (see below)

By default, the pre-commit checks are turned on for all commits of all branches. The following controls are available to tailor the hooks' behavior regarding this check:

  • The hooks.no-precommit-check config option can be used to turn pre-commit checks off entirely for a given branch. This option is typically used for branches tracking other branches from a third-party repository.

  • The $HOME/.no_cvs_check file, if less than 24 hours old and located on the machine running the hooks, will also turn all pre-commit checks off entirely.

  • Setting the hooks.combined-style-checking config option tells the hooks that the second part of the pre-commit checks (operating on the differences introduces by the commits) to only check the final result. Thus, if a user pushes an update introduces two new commits C1 and C2, it does not matter if C1 contains a style-check violation as long as the violation is corrected in C2.

    • It is important to note, however, that the pre-commit checks on the revision histories are still performed on a commit-per-commit basis. Otherwise, it would be possible to push a commit missing a Ticket Number in repositories that are configured to require one.

  • The no-precommit-check git attribute. Setting this attribute for any given file disables the pre-commit checks for this file. See git --help attributes for more info on how to set those attributes.

    • Normally, it is preferred that these attributes be maintained via a .gitattributes file which is checked in the repository. This makes everything properly tracked. But there may be situations where this is not convenient (Eg: trying to avoid a local change in a branch tracking another branch from a third-party repository). For those situations, it is possible to define the attribute in the GIT_DIR/info/default_attributes file inside the shared repository. The downside of this approach is that this file is not tracked.

Email Notifications

In general, developers are notified via email whenever a change is pushed to the repository. This section describes the policy used to determine which emails are being sent.

The Summary Email

The purpose of this email is to give a quick overview of what has changed.

Composition

The Summary Email is composed of two sections:

  1. A short description of what has changed. For instance, if a tag was created, it will explain what kind of tag was created, what the associated revision log was, and what commit it points to.
  2. Optionally, a list of commits which have been lost and/or added.

Sending Policy

The general policy is to send the Summary Email for all updates in order to inform its developers about the change. However, there are a number of situations where the email would bring little information to the Commit Emails already sent out:

  • Branch updates: If the update does not cause any commit to be lost, nor does it include commits from a branch matching the hooks.no-emails configuration, then the email is superfluous and therefore not sent.

  • Notes updates: Notes are really a special case of branch handling, where only fast-forward updates are allowed, and where the hooks.no-emails configuration is ignored. So the Summary Email is also never sent.

Filing Policy

Normally, this email is not used for filing purposes (ie, a copy is not even sent to file-ci@), as we are more interested in filing the individual commits than the summary.

However, it is interesting to file those emails in the following cases:

  • tag creation
  • tag update

In those cases, the revision log attached to those tags may contain a TN, which means this event deserves filing.

In either case, a Diff: marker is always added before the section summarizing the list of commits that were lost and/or added, making sure that this part of the email never gets filed, as the commits themselves are already getting filed.

The Commit Emails

Composition

The subject of that email is the commit's subject and its contents is roughly what the git show command would display.

Sending Policy

The Commit Email is always sent, unless the commit is found to exist in a branch matching the hooks.no-emails configuration.

Filing Policy

This email is always bcc'd to file-ci@. Note that this list must not appear in any explicit To:/Cc: header, as we want to prevent any replies from being sent there.

Retiring Old Branches

The recommended method for retiring a branch which is no longer useful is the following:

  • Create a tag referencing the tip of the branch to be retired.
    • The tag name should be retired/<branch-name> where <branch-name> is the name of the branch to be retired.

  • Push this tag to the official repository;
  • Delete the retired branch in the official repository.

By using the naming suggested for the tag, the hooks will ensure that the branch never gets accidently recreated. This would otherwise happen if a developer did not know that the branch was deleted, still had that branch locally in his repository, and tried to push his change as usual.

The use of the retired/ namespace for those tags also helps standardizing the location where those tags are created.

And the use of a tag allows everyone to determine the latest state of that branch prior to its retirement.

None: GitHooksUsersGuide (last edited 2017-12-13 13:32:25 by brobecke)

All content (C) 2008 Free Software Foundation. For terms of use, redistribution, and modification, please see the WikiLicense page.