> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qlty.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Git Hooks

Qlty can be integrated into git using git hooks to ensure:

1. code is formatted before committing (pre-commit hook)
2. code meets quality standards before pushes (pre-push hook)

## Installation

Installation is easiest using the Qlty CLI.

1. First [Install Qlty](https://docs.qlty.sh/cli/quickstart.md).
2. Run:

```sh lines theme={"system"}
qlty githooks install
```

See the [hook files](https://github.com/qltysh/qlty/tree/main/qlty-cli/src/commands/githooks) to understand what will be installed or to perform manual installation.

## Pre-commit

The Git pre-commit hook runs `qlty fmt` on the files staged for the commit.

## Pre-push

The Git pre-push hook will ensure that files are auto-formatted before pushing.

If there are files that are formatted incorrectly, it will format them and generate a new commit.

Due to the way Git works, when this occurs, you will need to run `git push` again.

> [!NOTE]
>
> You can always run `git push --no-verify` to skip the pre-push hook.

## Keeping slow plugins out of git hooks

Each hook tells Qlty which trigger is running. The pre-commit hook runs `qlty fmt --trigger pre-commit`, and the pre-push hook runs `qlty check --trigger pre-push`. A plugin runs on a trigger when its `triggers` list includes that trigger, or when it has no `triggers` list. See [Triggers](https://docs.qlty.sh/cli/qlty-toml.md#triggers) for the trigger each context uses.

There are two ways to keep a slow plugin out of your hooks:

* **Limit the plugin's triggers** in `qlty.toml`. This works with the installed hooks, with your own hook scripts, and with [global hooks](#global-hooks).
* **Skip the plugin** with `--skip` in a hook script for one repository.

Pick one per plugin, not both.

### Limit the plugin's triggers

In `qlty.toml`, give the plugin a `triggers` list without `pre-commit` or `pre-push`:

```toml .qlty/qlty.toml lines theme={"system"}
[[plugin]]
name = "brakeman"
triggers = ["manual"]
```

With the hooks from `qlty githooks install`, that's all you need, because they pass `--trigger` for you. The plugin still runs when you run `qlty check` yourself and in Qlty Cloud analysis. To keep it running in the Qlty VS Code extension too, add `ide` to the list.

> [!WARNING]
>
> Keep `manual` in the list. Qlty Cloud analysis runs plugins with the `manual` trigger, so a plugin without `manual` stops running there.

If you write your own hook script, pass `--trigger` with the hook's name, as the installed hooks do, so `triggers` settings apply:

```sh .git/hooks/pre-push lines theme={"system"}
#!/bin/sh
qlty check \
	--trigger pre-push \
	--upstream-from-pre-push \
	--no-formatters \
	--skip-errored-plugins
```

### Skip the plugin in one repository's hook

In a hook script for a single repository, you can add `--skip` with the plugin's name:

```sh .git/hooks/pre-push lines theme={"system"}
#!/bin/sh
qlty check \
	--trigger pre-push \
	--upstream-from-pre-push \
	--no-formatters \
	--skip-errored-plugins \
	--skip brakeman
```

`--skip` fails with `Plugin not found` when the plugin wouldn't run anyway: it isn't enabled, it's disabled, its `triggers` leave out the hook's trigger, or it has `skip_upstream = true` and the hook is pre-push. So don't use `--skip` in a hook that runs in more than one repository. Use `triggers` instead. See [`check`](https://docs.qlty.sh/cli/commands/check) and [`fmt`](https://docs.qlty.sh/cli/commands/fmt) for the `--trigger` and `--skip` flags.

## Global hooks

A global hook runs in every repository on your machine. Git uses global hooks when `core.hooksPath` is set in your global Git config, for example with `git config --global core.hooksPath ~/.git-hooks`.

To run Qlty from a global hook:

* Call `qlty check` from your global hook script. When `core.hooksPath` is set, Git ignores each repository's `.git/hooks` directory, so hooks from `qlty githooks install` don't run.
* Pass `--trigger pre-push` so `triggers` settings apply.
* Keep slow plugins out with `triggers` in each repository's `qlty.toml`, not `--skip`. `--skip` fails in every repository that doesn't enable the plugin.
* Skip repositories where Qlty isn't set up. There, `qlty check` exits with an error and blocks the push.

```sh ~/.git-hooks/pre-push lines theme={"system"}
#!/bin/sh
[ -f .qlty/qlty.toml ] || exit 0
qlty check \
	--trigger pre-push \
	--upstream-from-pre-push \
	--no-formatters \
	--skip-errored-plugins
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.