Skip to content

Latest commit

 

History

History
161 lines (120 loc) · 5.66 KB

git-hooks.md

File metadata and controls

161 lines (120 loc) · 5.66 KB
Raw

Git Hooks

This document contains some basic information regarding Git hooks in ILIAS. It describes how Git hooks can be installed/activated manually and where to find some offial Git hooks provided by the ILIAS community. Furtheremore it contains installation instructions for CaptainHook, a Git hook PHP library used by ILIAS to manage and execute a shared Git hook configuration amongst contributors.

Table of Contents

General

Git hooks are scripts that run automatically every time a particular event occurs in a Git repository and thus can be a powerful tool in the ILIAS development workflow. Check out the documentation about Git Hooks for more information.

Usage

Preconditions:

  • Git must be configured for the local project and the development environment

The Easy Way: CaptainHook - Git Hook Library

ILIAS provides a shared Git hook configuration for CaptainHook, a Git hook management library written in PHP.

It enables you to define a shared (amongst developers) Git hook configuration for actions being executed locally on your machine.

Currently, the following actions will be executed:

  • pre-commit:
    • PHP Linting
    • php-cs-fixer (dryrun only)

If you'd like to make sure all your committed files pass a PHP syntax (lint) check, and the ILIAS Coding Style was applied to all committed files, you are welcome to install CaptainHook and our shared actions.

Installation

Once you installed the composer development dependencies, go to the ILIAS main directory and execute:

libs/composer/vendor/bin/captainhook install

Executing this will create the hook script located in your .git/hooks directory, for each hook you choose to install while running the command.

Every time Git triggers a hook, CaptainHook will be executed.

If one the enabled actions (scripts) returns an exit code unequal 0 (successful program termination), your files will not be committed.

Troubleshooting
  • If you have issues with CaptainHook you can remove the created hooks in the ./git/hooks directory permanently. If you only want to temporarily deactivate a certain hook or action, disable the hook section by setting enabled to false or remove the action from the respective array in the captainhook.json configuration file. Please make sure you do not commit a changed captainhook.json file be accident.
  • If the Git hooks have been installed once, changing branches could be an issue if CaptainHook is not installed or the captainhook.json file is missing in the branch just checked out.
Additional Custom Actions

You can merge some additional custom actions with the standard actions of the captainhook.json: Create your own config-file and add actions or settings you want to merge with the default. Make sure, you have the config option includes defined to include the standard-configuration captainhook.json, e.g a file captainhook.local.json (which will be ignored in the repo):

{
  "config": {
    "includes": [
      "captainhook.json"
    ]
  },

  "pre-push": {
    "enabled": true,
    "actions": [
      {
        "action": "./CI/PHPUnit/run_tests.sh"
      }
    ]
  }
}

You must reinstall captainhook with your local config. Go to the ILIAS main directory and execute:

libs/composer/vendor/bin/captainhook install -c captainhook.local.json

The installation of the local file might respond with the following error:

In Builder.php line 55:
                                                                        
  bootstrap file not found: '/var/www/ilias/trunk/vendor/autoload.php'

In this case, you have to include the "bootstrap": "libs/composer/vendor/autoload.php" setting, similar to captainhook.json.

The Manual Way: Creating Git Hooks

Git hooks reside in the .git/hooks directory of a Git repository. To install/activate a Git hook first enter this directory.

cd .git/hooks

By default every hook has the suffix .sample. This suffix prevents them from being executed by default when a particular Git event occurs.

Removing this suffix will activate the hook.

mv pre-commit.sample pre-commit

Git hooks can be implemented by using any scripting language as long as they can be run as an executable. There can only be one script for each particular Git event.

If a script exits with a status set to 1, the actual execution of the Git event will be aborted, otherwise an exit status set to 0 will continue the Git workflow as expected.

ILIAS Git Hooks

The ILIAS community provides a bunch of Git hook scripts which can be used to optimize the development workflow and to enforce certain policies regarding the ILIAS code base.

Please be aware that these recommendations are for a development environment only, and may not be used in production environments

The Git hook scripts can be found in the git_hooks folder of the official ILIAS Developer Tools GitHub repository.