Git-hooks by git-hooks

git-hooks is currently at the stage of managing client-side hooks. It will support server-side hooks future.

git-hooks is a fork of icefox/git-hooks. The article “Managing Project, User, and Global git hooks” explains much of the purpose of using git-hooks.

Below, I will explain git-hooks as well as the new features in this fork.

Terminology

git-hooks: The tool created by this repo
trigger: Hook type (such as pre-commit and commit-msg)
hook: Specific hook
community hook: a commonly used hook. Also referred to as contrib hooks in the source code.

Usage

Run git hooks install to tell a git repo to use git-hooks.

Stop using git-hooks by git hooks uninstall.

List all scope of hooks by execute git hooks directly. See below for what scope is.

Scope

git-hooks tries to reduce hook copies by using symbolic links to manage them.

Take pre-commit hook as an example. When git triggers pre-commit, git-hooks routes the execution to:

githooks directory under the repo directory,
~/.githooks directory under home directory, and
the directory configured by git config --set --system hooks.global.

These three directories are called project scope, user scope, and global scope.

project scope hooks reside under repo directory. Here’s an example layout:

some-project
└── githooks
    ├── commit-msg
    │   └── check
    │   └── check2
    └── pre-commit
        └── check
        └── check2

When git triggers pre-commit, all hooks under githooks/pre-commit will be executed.

By project scope, we can add project-related hooks into version control, and separate them into multiple files.

user hooks reside in the user’s home directory under the name .githooks. It contains the same directory structure as project hooks. With user hooks, you can setup personal hooks for all your projects.

home
└── someuser
    └── .githooks
        ├── commit-msg
        │   └── check
        │   └── check2
        └── pre-commit
            └── check
            └── check2

global scope hooks is configured via hooks.global entry in git's system-wide configuration. It allows multiple users on the same machine to share hooks.

usr
└── local
    └── share
        └── githooks
            ├── commit-msg
            │   └── check
            │   └── check2
            └── pre-commit
                └── check
                └── check2

Git's system configuration is usually found in /etc/gitconfig or /usr/local/etc/gitconfig.

Use git config --system --set hooks.global to setup your global hooks directory.

[hooks]
    global = /usr/local/share/githooks

Wait a minute.... What if I want to have a hook for a particular project and particular user? It can't be added in version control, or into user scope directory.

The solution is semi scope. semi scope actually reside inside project scope,

some-project
└── githooks
    ├── .gitignore
    ├── _pre-commit
    │   └── check
    │   └── check2
    ├── commit-msg
    │   └── check
    │   └── check2
    └── pre-commit
        └── check
        └── check2

Now, when git triggers pre-commit, all hooks under githooks/pre-commit and git-hooks/_pre-commit will be executed.

In order to setup hooks as user-related, .gitignore should be written as

_*

Community Hooks

This is where git-hooks differs from icefox/git-hooks; it adds the feature of community hooks.

Let’s look at the pre-commit hook in project scope. When git triggers pre-commit, besides scanning githooks, git-hooks also read githooks.json.

For this example, the contents of githooks.json are:

{
    "pre-commit": {
        "github.com/git-hooks/contrib": [
            "bashlint",
            "jshint"
        ]
    }
}

In the JSON, hooks under the "pre-commit" field will be executed.

It’s organized as another git repository. The repository will be cloned into the ~/.githooks-contrib directory. (It will be created if it doesn't exist.)

See Community hooks for more info.

xmind