# Git hooks

> **Warning:** This product is in Beta stage and we may release breaking changes. The documentation here matches the release version listed in the table of contents.

`sonar integrate git` installs a Git hook that scans your code for secrets at commit or push time. The hook calls `sonar analyze secrets` automatically—no extra tooling required.

## Prerequisites

* [The SonarQube CLI is installed and authenticated](/sonarqube-cli/quickstart-guide.md).
* A Git repository (for project-scoped installs).

## Choose pre-commit or pre-push

The CLI supports two hook types. Both stop a secret from leaving your machine, but at different moments:

| Hook         | Fires when…          | What it scans                     | Trade-off                                                                                  |
| ------------ | -------------------- | --------------------------------- | ------------------------------------------------------------------------------------------ |
| `pre-commit` | You run `git commit` | Staged files                      | Catches secrets the earliest. Runs on every commit, which is slower for big change sets.   |
| `pre-push`   | You run `git push`   | Files changed in unpushed commits | Catches secrets just before they leave your machine. Lets you `git commit` freely locally. |

For most teams, `pre-commit` is the right default—it catches secrets before they enter local history. Choose `pre-push` if your developers commit constantly and want a single batched check before sharing.

## Install

### Per repository (default)

```bash
# Pre-commit (default)
sonar integrate git

# Or explicitly:
sonar integrate git --hook pre-commit
sonar integrate git --hook pre-push
```

You can install both hooks in the same repo. Run the command twice with different `--hook` values.

### Globally for every repository

```bash
sonar integrate git --global
```

Globally-installed hooks live in `~/.sonar/sonarqube-cli/hooks/`. The CLI sets `git config --global core.hooksPath` to that directory so every Git repo on your machine uses them, unless a repo has its own hooks path.

### Non-interactive install (for provisioning)

```bash
sonar integrate git --hook pre-commit --global --non-interactive
```

In non-interactive mode the CLI does not prompt; it fails fast on conflicts. Combine with `--force` to overwrite a pre-existing hook (see below).

## How the CLI handles existing hooks

When you install per-repo, the CLI looks at your project's hook setup in this order:

1. **Husky** (`.husky/` directory): the CLI registers via Husky.
2. **pre-commit framework** (`.pre-commit-config.yaml`): the CLI adds itself as a pre-commit framework hook.
3. **Plain Git hooks** (`.git/hooks/`): the CLI writes a hook script directly.

If a hook already exists in the target location and was **not** installed by `sonar integrate git`, the command refuses to overwrite it. Pass `--force` to overwrite:

```bash
sonar integrate git --force
```

This is safe to do when you want SonarQube secrets scanning to chain with an existing hook script — a marker comment identifies the hook, so subsequent `sonar integrate git` runs recognize and update it without `--force`.

## Verify the hook

1. Create a file with a fake-looking but secret-shaped value:

   ```javascript
   // secrets.js
   const API_KEY = "sqp_1aa323ae0689cd4a1abd062a2ad0a224ae8a1d13";
   ```
2. Stage and try to commit:

   ```bash
   git add secrets.js
   git commit -m "Test"
   ```
3. The commit should be blocked and the secret reported.

Delete the test file once confirmed.

## Bypass the hook

If you need to skip the hook for a single commit — for example, while running a script that the hook would interfere with — use Git's built-in `--no-verify` flag:

```bash
git commit --no-verify
```

> **Warning:** Use `--no-verify` sparingly. The whole point of the hook is to catch secrets before they enter your history. Prefer fixing the offending file over bypassing the check.

## Uninstall

To remove the hook:

* **Per-repo (plain Git hooks):** delete the file in `.git/hooks/pre-commit` (or `pre-push`). The CLI marks its hooks with a comment so you can identify them.
* **Per-repo (Husky / pre-commit framework):** remove the SonarQube entry from your Husky scripts or `.pre-commit-config.yaml`.
* **Globally:** unset the global hooks path with `git config --global --unset core.hooksPath` and delete the directory at `~/.sonar/sonarqube-cli/hooks/`.

See [Uninstalling](/sonarqube-cli/administration/uninstall.md) for the full removal procedure.

## Related pages <a href="#related-pages" id="related-pages"></a>

* [Secrets scanning](/sonarqube-cli/analysis/secrets-scanning.md)
* [Claude Code](/sonarqube-cli/integrations/claude-code.md)
* [GitHub Copilot](/sonarqube-cli/integrations/github-copilot.md)
* [Exit codes](/sonarqube-cli/using-sonarqube-cli/exit-codes.md)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.sonarsource.com/sonarqube-cli/integrations/git-hooks.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.