CommitHooks

Commit Hooks Isetbio Style

Historical note: this page dates from ISETBio's 2014-era layout (hardcoded Matlab paths, a utility/unit test/ directory and unitTest.m function that no longer exist). Current testing runs through isetbioUnitTest and the other runners in validate/; see Validation. Whether a maintained pre-commit hook exists today has not been verified - treat the setup steps below as a historical reference, not a supported procedure, until reviewed.

Introduction

Git pre-commit hooks could enable an auto unit test for every git commit command. All the unit test information is printed if 'git commit' is called in a command window. If commit is issued by Github software GUI, the auto unit test will also be run, but no output information is visible.

Setup Step-by-Step

In this section, we will introduce how to setup the pre-commit hooks for ISETBIO. This could take you around 10 minutes. Now let's begin.

Initialize Git Repository

At this stage, we assume that you have already got git (version 1.8.2 or later) running on your machine. If not, you could download it from here. In a command window (terminal), change current working directory to ISETBIO root folder and initialize (or re-initialize) git there. For example:

# Init git folder
$ cd ~/isetbio
$ git init

Create Pre-commit Hooks

In command window (terminal), change current working directory to hooks in .git folder of ISETBIO (e.g. ~/isetbio/.git/hooks). In hooks folder, you could see a bunch of example hooks. Create a new file called pre-commit (with no extension) in this folder and copy the following lines to it.

# pre-commit.sh
echo Start pre-commit testing...
git stash -q --keep-index
./.git/hooks/run_tests.sh
RESULT=$?
git stash pop -q
[ $RESULT -ne 0 ] && exit 1
exit 0

Set Path for Shell Commands

In isetbio/.git/hooks, create a file called run_tests.sh (this is called by pre-commit). Copy and paste the following lines to the file

# Setup alias
matlab="/Applications/MATLAB_R2014a.app/bin/matlab"

# Run unit test in matlab
cmd="cd ../../utility/unit\ test/; unitTest;"
"$matlab" -nodesktop -nosplash -nodisplay -r "$cmd"
if [ "$?" == "0" ];
then
    echo Unit test passed!
    exit 0
else
    echo Unit Test Failed
    exit 1
fi

You should change the first line to the path to your local matlab executable. Also, remember to make this file executable. You could achieve this by

$chmod u+x run_tests.sh

Adding more unit test modules

To add more testing functions, you could create a Matlab function with no output argument. Then add the function name into the try-catch structure in unitTest.m

Notes

• Only tested on mac: This instruction is only tested on mac. It should also work on Linux machine. However, Windows machines might need some more hacks
• Bypass the pre-commit hook: To avoid the auto unit test in some situation, you could use

$ git commit --no-verify

• GUI vs Command Window: Pre-commit hook will be triggered by both Github GUI or terminal commands. The difference is that in terminal, you could see the test process and error message if encountered.