Extensible Hook System for GIT
Project description
hooks4git
Fully configurable language-agnostic git hooks.
Auto checks your code before you ship it. Works with any programmning language. If not, let me know.
Availability
Production module is available from Pypi, and development branch is also published by Travis-CI to Pypi TestServer. Both are provided as EGG packages, since there is a Post Install section which creates the hook files on your local directory. Wheel packaging is not intented to do that.
Both can be downloaded and installed via the pip command.
More information on Git Hooks
Here.
Getting started
These instructions will show you how to install and use the application.
Supported OSs
Supported OSs are Linux, MAC and Windows. However, I was not able to make it work CMD.exe (like if cmd.exe even works...). If you are using Windows, use it inside GitBash. DO NOT use it on cmd.exe
.
Installation
pip install hooks4git --user
Depending on your setup, you might want to use pip3
instead of pip
.
Please, keep in mind that --user
folder might not be on your PATH environment var. If you fix this here, it will be automatically fixed for any other python tool you might eventually install inside your user context.
In this case, a script called hooks4git
will be available all the time, to hook any project you are currently in.
By running this script, hooks will be applied. Please note you need to manually keep upgrading your system tools, like you do for others, like pip itself.
You probably added virtualenv and others with sudo. If in doubt, please take a look at source files.
Built-in Scripts
Currently, there is only one available built-in script, called check_branch_name.sh
. If you want to use, just follow the exemple on the default .ini file, on sub-section 'checkbranch'. This is the way to trigger built-in scripts, prefixing them with 'h4g/'.
On 0.1 release, I was using a '*' character for built-in scripts, but that caused so many headaches, mainly when trying to make this work inside GitBash for windows (ok, that was because I was actually trying to call a bat file ... then I just gave it up). I also tried once calling 'scripts', but it may confuse with a possible local 'scripts' folder on your project.
CLI Usage
After installation, your repo needs to be hooked for all events. Prior version used YAML for configuration management, but that caused PyYAML to be a dependency, and things went a little wrong when running it as a tool. So I choose .ini files over .json files (both have Python native parsers) because it looked less ugly.
Inside your git repository, just type:
hooks4git --init
And get all your regular non-sense-hard-to-use-and-hard-to-maintain-and-hard-to-share hook scripts updated. Then, you just need to open .hooks4git.ini file on the root of your project and configure it the way you want. This first example section is meant for Python, but you can use any tool you want, at any given git hook event.
Example section for pre-commit, for Python:
[scripts]
flake8 = flake8 --max-line-length=119 --exclude .git,build,dist,.env,.venv
nosetests = nosetests --with-coverage
[hooks.pre-commit.scripts]
check = flake8
It also could be for NodeJS:
[scripts]
eslint = eslint -f checkstyle index.js > checkstyle-result.xml
jshint = jshint *.js
[hooks.pre-commit.scripts]
check_a = eslint
check_b = jslint
Note: All scripts you add here need to be available on your PATH for execution. So you need to make all of them depedencies on your current project, no matter the language it is written with. Per default, the available hooks are only echo
commands, which will always pass!
CI Usage
When running inside CI, if you manage to have hooks4git
package available, you can force trigger a hook this way:
hooks4git -t <hook> --ci
This will run the very same set of scrips you ran on your development workstation prior to the commit. Please note that <hook>
is any valid entry on .hooks4git.ini
file, not only necessarily a git-hook. See below about "Custom Hooks".
Colors
The --ci
parameter tells hooks4git to not print in nice colors, just plain strings. But first check if your CI output handle colors or not. For instance, Bitbucket Pipelines handle it nicely, while Jenkins doesn't.
"Custom Hooks"
Hooks have those static names because they are automatically triggered by GIT. However, you can create others inside .hooks4git.ini
file. And you can trigger them using the -t
parameter.
So, if you like check_branch_name
feature, you might think running it inside CI wouldn't be a great idea. How to solve it?
[hooks.ci-develop.scripts]
check = flake8
tests = tests_with_report
As said, there is no "ci-develop" git hook. But due to internal hooks4git
mechanics, using -t
flag, hooks4git
will try to find and run that configuration.
So, it would be a matter of adding this to your CI script:
- pip install hooks4git
- hooks4git -t ci-develop
And since you were using flake8 and tests already on your commit and push hooks, you guarantee to run the same tools with the same parameters on CI, with a nice output, colored or not.
Disclaimer: This feature was never intended to exist, and happened to work by accident. Since it is kind of cool and doesn't break the law, I decided to document it.
Output
Here is a sample output for a Python configuration, with Flake8 (black and white... it has actually a full colored output if --ci parameter is not issued):
———————————————————————————————————————————————————————————————————————————————
hooks4git v0.3.x :: Pre-Commit :: hook triggered
———————————————————————————————————————————————————————————————————————————————
STEP | $ flake8 --max-line-length=119 --exclude .git,__pycache__,build,dist
OUT | None
PASS | 'flake8' step executed successfully
———————————————————————————————————————————————————————————————————————————————
STEPS| 1 were executed
TIME | Execution took 0:00:00.684762
PASS | All green! Good!
———————————————————————————————————————————————————————————————————————————————
License
This project is licensed under MIT license. See the LICENSE file for details
Authors
See list of contributors who participated in this project.
Credits
- Marco Lovato
- Collins Abitekaniza (where I forked from)
Change Log
0.3.x
- Major rework on how strings are printed out
- Added --ci parameter, so no color will be printed out (Idea from Fernando Espíndola)
- Auto create hooks folder (inside .git) if it is missing (Idea from Édouard Lopez)
0.2.x
- Support for Windows with GitBash
- Added docker scripts for quick clean machine testing environment
- Better exception handling when user configures duplicate sections by mistake
- FIXED: Changed default max line length example to 119 instead of 120
- Replaced copying code to .git/hooks with a safe bash caller
- Replaced '_' folder (or 'scripts' folder) with 'h4g' folder for internal scripts
- FIXED: Script order inside a hook definition was random
- Standard Error Output was not being handled and printed accordingly
0.1.x
- Initial release
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.