GitHooks 🪝

• Project description
  • Why use git hooks?
• Installation
  • Backup current hooks
  • Automatic installation
  • Manual installation
• Configuration
  • Auto install
  • Hook configuration
  • Git submodules
  • Custom project path
  • Custom mix path
    • Troubleshooting in docker containers
  • Example config
  • Task types
    • Mix task
    • Command
    • Executable file
    • Elixir module
• Removing a hook
• Recipes
  • Running pre-commit hook only for staged files
• Execution
  • Automatic execution
  • Manual execution
• Copyright and License

Project description

Configure git hooks in your Elixir projects.

Why use git hooks?

• Enforces code quality: Automatically run tests, formatters, linters... before every commit or push to ensure code consistency.
• Prevent errors earlier: Catch issues with pre-commit or pre-push, reducing the chance of broken builds and saving minutes and time in the CI or code review.
• Improve workflows: Automate repetitive tasks, unify command execution, ensure consistent standards across the team...

Main features:

• Simplicity: Automatic or manually install the configured git hook actions.
• Flexibility: You choose what to use to define the git hooks actions:
  • Bash commands
  • Executable files
  • Elixir modules
• No limits: Any git hook is and will be supported out of the box, you can check here the git hooks list available.

Installation

Add to dependencies:

def deps do
  [
    {:git_hooks, "~> 0.8.0", only: [:dev], runtime: false}
  ]
end

Then install and compile the dependencies:

mix deps.get && mix deps.compile

Backup current hooks

This library will backup automatically your current git hooks before overwriting them.

The backup files will have the file extension .pre_git_hooks_backup

Automatic installation

This library will install automatically the configured git hooks in your config.exs file.

See configuration to disable the automatic install.

Manual installation

If you prefer not to enforce git hooks in a project, you can still define recommended hooks and allow team members to install them manually by running:

mix git_hooks.install

Configuration

Auto install

To disable the automatic install of the git hooks set the configuration key auto_install to false.

Hook configuration

One or more git hooks can be configured, those hooks will be the ones installed in your git project.

Currently there are supported two configuration options:

• tasks: A list of the commands that will be executed when running a git hook. See types of tasks for more info.
• verbose: If true, the output of the mix tasks will be visible. This can be configured globally or per git hook.
• branches: Allow or forbid the hook configuration to run (or not) in certain branches using whitelist or blacklist configuration (see example below). You can use regular expressions to match a branch name.

Git submodules

This library supports git submodules, just add your git_hooks configuration to any of the submodules projects.

Setting a custom git hooks config path is also supported:

git config core.hooksPath .myCustomGithooks/

Custom project path

This library assumes a simple Elixir project architecture. This is, an Elixir project in the root of a git repository.

If you have a different project architecture, you can specify the absolute path of your project using the project_path configuration:

{project_path, 0} = System.cmd("pwd", [])
project_path = String.replace(project_path, ~r/\n/, "/")

config :git_hooks,
  hooks: [
    pre_commit: [
      tasks: [
        {:cmd, "mix format --check-formatted"}
      ]
    ]
  ],
  project_path: project_path

Custom mix path

This library expects elixir to be installed in your system and the mix binary to be available. If you want to provide a specific path to run the mix executable, it can be done using the mix_path configuration.

The following example would run the hooks on a docker container:

config :git_hooks,
  auto_install: false,
  mix_path: "docker-compose exec mix",

Troubleshooting in docker containers

The mix_path configuration can be used to run mix hooks on a Docker container. If you have a TTY error running mix in a Docker container use docker exec --tty $(docker-compose ps -q web) mix as the mix_path. See this issue as reference.

Example config

In config/config.exs

use Mix.Config

# somewhere in your config file
if Mix.env() == :dev do
  config :git_hooks,
    auto_install: true,
    verbose: true,
    branches: [
      whitelist: ["feature-.*"],
      blacklist: ["master"]
    ],
    hooks: [
      pre_commit: [
        tasks: [
          {:cmd, "mix format --check-formatted"}
        ]
      ],
      pre_push: [
        verbose: false,
        tasks: [
          {:cmd, "mix dialyzer"},
          {:cmd, "mix test --color"},
          {:cmd, "echo 'success!'"}
        ]
      ]
    ]
end

Task types

For more information, check the module documentation for each of the different supported tasks.

Mix task

This is the preferred option to run mix tasks, as it will provide the best execution feedback.

Just add in your config the mix tasks you want to run. You can also set the args to be used by the mix task:

config :git_hooks,
  verbose: true,
  hooks: [
    commit_msg: [
      tasks: [
        {:mix_task, :test},
        {:mix_task, :format, ["--dry-run"]}
      ]
    ]
  ]

By default this library expects by default the following return values from mix tasks:

0
:ok
nil

If you want to support additional success return values from your mix tasks, you can add them by adding the following configuration:

config :git_hooks,
  extra_success_returns: [
    {:noop, []},
    {:ok, []}
  ]

Command

To run a simple command you can either declare a string or a tuple with the command you want to run. For example, having "mix test" and {:cmd, "mix test"} in the hook tasks will be equivalent.

If you want to forward the git hook arguments, add the option include_hook_args: true.

config :git_hooks,
  verbose: true,
  hooks: [
    commit_msg: [
      tasks: [
        {:cmd, "echo 'test'"},
        {:cmd, "elixir ./priv/test_task.ex", include_hook_args: true},
      ]
    ]
  ]

Executable file

The following configuration uses a script file to be run with a git hook. If you want to forward the git hook arguments, add the option include_hook_args: true.

config :git_hooks,
  verbose: true,
  hooks: [
    commit_msg: [
      tasks: [
        {:file, "./priv/test_script"},
        {:file, "./priv/test_script_with_args", include_hook_args: true},
      ]
    ]
  ]

The script file executed will receive the arguments from git, so you can use them as you please.

Elixir module

It is also possible to use Elixir modules to execute actions for a given git hook.

Just add in your config the MFA ({module, function, arity}) definition:

config :git_hooks,
  verbose: true,
  hooks: [
    commit_msg: [
      tasks: [
        {MyModule, :execute, 2}
      ]
    ]
  ]

To check how many args you function should expect check the git documentation to know which parameters are being sent on each hook.

Removing a hook

When a git hook configuration is removed, the installed hook will automatically delete it.

Any backup done at the moment will still be kept.

Recipes

List of recipes that can be useful to setup your git hooks.

Running pre-commit hook only for staged files

{:mix_task, "credo", ["$(git diff --name-only --cached)", " --strict"]}

Execution

Automatic execution

The configured mix tasks will run automatically for each git hook.

Manual execution

You can also run manually any configured git hook as well.

The following example will run the pre_commit configuration:

mix git_hooks.run pre_commit

It is also possible to run all the configured hooks:

mix git_hooks.run all

Copyright and License

Copyright © 2022-present Adrián Quintás

Source code is released under the MIT license.