{"id":13507791,"url":"https://github.com/qgadrian/elixir_git_hooks","last_synced_at":"2025-04-14T08:16:39.325Z","repository":{"id":31979164,"uuid":"130372941","full_name":"qgadrian/elixir_git_hooks","owner":"qgadrian","description":"🪝 Add git hooks to Elixir projects","archived":false,"fork":false,"pushed_at":"2025-03-07T12:28:08.000Z","size":292,"stargazers_count":166,"open_issues_count":2,"forks_count":17,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-04-14T08:16:29.936Z","etag":null,"topics":["elixir","elixir-lang","git-hook","git-hooks","hex","mix-tasks"],"latest_commit_sha":null,"homepage":"","language":"Elixir","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/qgadrian.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-04-20T14:26:29.000Z","updated_at":"2025-03-07T12:28:04.000Z","dependencies_parsed_at":"2024-01-12T14:40:22.471Z","dependency_job_id":"81e2b490-c3d5-447a-b246-9c25d1e5fd79","html_url":"https://github.com/qgadrian/elixir_git_hooks","commit_stats":null,"previous_names":[],"tags_count":25,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qgadrian%2Felixir_git_hooks","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qgadrian%2Felixir_git_hooks/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qgadrian%2Felixir_git_hooks/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qgadrian%2Felixir_git_hooks/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/qgadrian","download_url":"https://codeload.github.com/qgadrian/elixir_git_hooks/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248844000,"owners_count":21170499,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["elixir","elixir-lang","git-hook","git-hooks","hex","mix-tasks"],"created_at":"2024-08-01T02:00:39.247Z","updated_at":"2025-04-14T08:16:39.296Z","avatar_url":"https://github.com/qgadrian.png","language":"Elixir","readme":"[![Coverage Status](https://coveralls.io/repos/github/qgadrian/elixir_git_hooks/badge.svg?branch=master)](https://coveralls.io/github/qgadrian/elixir_git_hooks?branch=master)\n[![Hex version](https://img.shields.io/hexpm/v/git_hooks.svg \"Hex version\")](https://hex.pm/packages/git_hooks)\n[![Hex Docs](https://img.shields.io/badge/hex-docs-9768d1.svg)](https://hexdocs.pm/git_hooks)\n![CI Status](https://github.com/qgadrian/elixir_git_hooks/actions/workflows/test.yml/badge.svg)\n[![Inline docs](http://inch-ci.org/github/qgadrian/elixir_git_hooks.svg)](http://inch-ci.org/github/qgadrian/elixir_git_hooks)\n\n# GitHooks 🪝\n\n\u003c!--toc:start--\u003e\n\n- [Project description](#project-description)\n  - [Why use git hooks?](#why-use-git-hooks)\n- [Installation](#installation)\n  - [Backup current hooks](#backup-current-hooks)\n  - [Automatic installation](#automatic-installation)\n  - [Manual installation](#manual-installation)\n- [Configuration](#configuration)\n  - [Auto install](#auto-install)\n  - [Hook configuration](#hook-configuration)\n  - [Git submodules](#git-submodules)\n  - [Custom project path](#custom-project-path)\n  - [Custom mix path](#custom-mix-path)\n    - [Troubleshooting in docker containers](#troubleshooting-in-docker-containers)\n  - [Example config](#example-config)\n  - [Task types](#task-types)\n    - [Mix task](#mix-task)\n    - [Command](#command)\n    - [Executable file](#executable-file)\n    - [Elixir module](#elixir-module)\n- [Removing a hook](#removing-a-hook)\n- [Recipes](#recipes)\n  - [Running pre-commit hook only for staged files](#running-pre-commit-hook-only-for-staged-files)\n- [Execution](#execution)\n  - [Automatic execution](#automatic-execution)\n  - [Manual execution](#manual-execution)\n- [Copyright and License](#copyright-and-license)\n\u003c!--toc:end--\u003e\n\n## Project description\n\nConfigure [git hooks](https://git-scm.com/docs/githooks) in your Elixir projects.\n\n#### Why use git hooks?\n\n- Enforces code quality: Automatically run tests, formatters, linters... before every\n  commit or push to ensure code consistency.\n- Prevent errors earlier: Catch issues with `pre-commit` or `pre-push`, reducing the\n  chance of broken builds and saving minutes and time in the CI or code review.\n- Improve workflows: Automate repetitive tasks, unify command execution, ensure\n  consistent standards across the team...\n\nMain features:\n\n- **Simplicity**: Automatic or manually install the configured git hook actions.\n- **Flexibility**: You choose what to use to define the git hooks actions:\n  - Bash commands\n  - Executable files\n  - Elixir modules\n- **No limits**: Any git hook is and will be supported out of the box,\n  you can [check here the git hooks list](https://git-scm.com/docs/githooks)\n  available.\n\n## Installation\n\nAdd to dependencies:\n\n```elixir\ndef deps do\n  [\n    {:git_hooks, \"~\u003e 0.8.0\", only: [:dev], runtime: false}\n  ]\nend\n```\n\nThen install and compile the dependencies:\n\n```bash\nmix deps.get \u0026\u0026 mix deps.compile\n```\n\n### Backup current hooks\n\nThis library will backup automatically your current git hooks before\noverwriting them.\n\nThe backup files will have the file extension `.pre_git_hooks_backup`\n\n### Automatic installation\n\nThis library will install automatically the configured git hooks in your\n`config.exs` file.\n\nSee [configuration](#disable-auto-install) to disable the automatic install.\n\n### Manual installation\n\nIf you prefer **not to enforce git hooks in a project**, you can still define\nrecommended hooks and allow team members to install them manually by running:\n\n```bash\nmix git_hooks.install\n```\n\n## Configuration\n\n### Auto install\n\nTo disable the automatic install of the git hooks set the configuration key `auto_install` to\n`false`.\n\n### Hook configuration\n\nOne or more git hooks can be configured, those hooks will be the ones\n[installed](#installation) in your git project.\n\nCurrently there are supported two configuration options:\n\n- **tasks**: A list of the commands that will be executed when running a git hook. [See types of tasks](#type-of-tasks) for more info.\n- **verbose**: If true, the output of the mix tasks will be visible. This can be configured globally or per git hook.\n- **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.\n\n### Git submodules\n\nThis library supports git submodules, just add your `git_hooks` configuration to\nany of the submodules projects.\n\nSetting a custom _git hooks_ config path is also supported:\n\n```\ngit config core.hooksPath .myCustomGithooks/\n```\n\n### Custom project path\n\nThis library assumes a simple Elixir project architecture. This is, an Elixir\nproject in the root of a git repository.\n\nIf you have a different project architecture, you can specify the absolute path\nof your project using the `project_path` configuration:\n\n```elixir\n{project_path, 0} = System.cmd(\"pwd\", [])\nproject_path = String.replace(project_path, ~r/\\n/, \"/\")\n\nconfig :git_hooks,\n  hooks: [\n    pre_commit: [\n      tasks: [\n        {:cmd, \"mix format --check-formatted\"}\n      ]\n    ]\n  ],\n  project_path: project_path\n```\n\n### Custom mix path\n\nThis 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.\n\nThe following example would run the hooks on a docker container:\n\n```elixir\nconfig :git_hooks,\n  auto_install: false,\n  mix_path: \"docker-compose exec mix\",\n```\n\n##### Troubleshooting in docker containers\n\nThe `mix_path` configuration can be used to run mix hooks on a Docker container.\nIf 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](https://github.com/qgadrian/elixir_git_hooks/issues/82) as reference.\n\n### Example config\n\nIn `config/config.exs`\n\n```elixir\nuse Mix.Config\n\n# somewhere in your config file\nif Mix.env() == :dev do\n  config :git_hooks,\n    auto_install: true,\n    verbose: true,\n    branches: [\n      whitelist: [\"feature-.*\"],\n      blacklist: [\"master\"]\n    ],\n    hooks: [\n      pre_commit: [\n        tasks: [\n          {:cmd, \"mix format --check-formatted\"}\n        ]\n      ],\n      pre_push: [\n        verbose: false,\n        tasks: [\n          {:cmd, \"mix dialyzer\"},\n          {:cmd, \"mix test --color\"},\n          {:cmd, \"echo 'success!'\"}\n        ]\n      ]\n    ]\nend\n```\n\n### Task types\n\n\u003e For more information, check the [module\n\u003e documentation](https://hexdocs.pm/git_hooks) for each of the different\n\u003e supported tasks.\n\n#### Mix task\n\nThis is the preferred option to run mix tasks, as it will provide the best\nexecution feedback.\n\nJust add in your config the mix tasks you want to run. You can also set the args\nto be used by the mix task:\n\n```elixir\nconfig :git_hooks,\n  verbose: true,\n  hooks: [\n    commit_msg: [\n      tasks: [\n        {:mix_task, :test},\n        {:mix_task, :\"hex.user\", \"whoami\"},\n        {:mix_task, :format, [\"--dry-run\"]}\n      ]\n    ]\n  ]\n```\n\nBy default this library expects by default the following return values from mix tasks:\n\n```elixir\n0\n:ok\nnil\n```\n\nIf you want to support additional success return values from your mix tasks, you\ncan add them by adding the following configuration:\n\n```elixir\nconfig :git_hooks,\n  extra_success_returns: [\n    {:noop, []},\n    {:ok, []}\n  ]\n```\n\n#### Command\n\nTo run a simple command you can either declare a string or a tuple with the\ncommand you want to run. For example, having `\"mix test\"` and `{:cmd, \"mix\ntest\"}` in the hook `tasks` will be equivalent.\n\n\u003e If you want to forward the git hook arguments, add the option\n\u003e `include_hook_args: true`.\n\n```elixir\nconfig :git_hooks,\n  verbose: true,\n  hooks: [\n    commit_msg: [\n      tasks: [\n        {:cmd, \"echo 'test'\"},\n        {:cmd, \"elixir ./priv/test_task.ex\", include_hook_args: true},\n      ]\n    ]\n  ]\n```\n\n#### Executable file\n\nThe following configuration uses a script file to be run with a git hook. If you\nwant to forward the git hook arguments, add the option `include_hook_args:\ntrue`.\n\n```elixir\nconfig :git_hooks,\n  verbose: true,\n  hooks: [\n    commit_msg: [\n      tasks: [\n        {:file, \"./priv/test_script\"},\n        {:file, \"./priv/test_script_with_args\", include_hook_args: true},\n      ]\n    ]\n  ]\n```\n\nThe script file executed will receive the arguments from git, so you can use\nthem as you please.\n\n#### Elixir module\n\nIt is also possible to use Elixir modules to execute actions for a given git\nhook.\n\nJust add in your config the\n[MFA](https://hexdocs.pm/elixir/typespecs.html#built-in-types) (`{module,\nfunction}`) definition:\n\n```elixir\nconfig :git_hooks,\n  verbose: true,\n  hooks: [\n    commit_msg: [\n      tasks: [\n        {MyModule, :execute}\n      ]\n    ]\n  ]\n```\n\n## Removing a hook\n\nWhen a git hook configuration is removed, the installed hook will automatically\ndelete it.\n\nAny backup done at the moment will still be kept.\n\n## Recipes\n\nList of recipes that can be useful to setup your git hooks.\n\n### Running pre-commit hook only for staged files\n\n```elixir\n{:mix_task, \"credo\", [\"$(git diff --name-only --cached)\", \" --strict\"]}\n```\n\n## Execution\n\n### Automatic execution\n\nThe configured mix tasks will run automatically for each [git\nhook](https://git-scm.com/docs/githooks#_hooks).\n\n### Manual execution\n\nYou can also run manually any configured git hook as well.\n\nThe following example will run the pre_commit configuration:\n\n```bash\nmix git_hooks.run pre_commit\n```\n\nIt is also possible to run all the configured hooks:\n\n```bash\nmix git_hooks.run all\n```\n\n## Copyright and License\n\nCopyright © 2022-present Adrián Quintás\n\nSource code is released under [the MIT license](./LICENSE).\n","funding_links":[],"categories":["Debugging"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fqgadrian%2Felixir_git_hooks","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fqgadrian%2Felixir_git_hooks","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fqgadrian%2Felixir_git_hooks/lists"}