Skip to main content
A pre-push hook is a command that runs automatically before Git sends your changes to a shared repository. The Iris Code hook runs your gate at that point, so a failed check can stop the push while the code is still on your machine. You choose the thresholds it must meet.
The git pre-push hook requires Iris Code Pro.

Installing

Run Iris Code: Install Git Hook from the command palette. Iris Code writes the pre-push hook file and makes it executable so Git can run it. When Iris Code starts in a Git repository with a Pro licence, it also offers to install the hook for you. Choosing Not now is remembered for that workspace for 30 days. Closing the question without choosing only skips it until the editor next starts.

Husky and custom hook paths

Git normally looks for hooks in .git/hooks, but a project can point it somewhere else with the core.hooksPath setting. Iris Code follows that setting, so the check goes into the file Git will actually run. Husky is a popular tool for managing Git hooks. In a Husky project the Iris Code check goes in .husky/pre-push, which is the file Husky intends you to edit, and any script already there is kept. Husky v9 sets core.hooksPath to .husky/_ and generates its own helper files there. Iris Code leaves those alone, because Husky regenerates them on install and an edit to them would be lost. With any other core.hooksPath, the check goes in the pre-push file in that directory. The sidebar’s hook badge watches whichever file Git will run, so it stays accurate whatever the layout.

What happens on push

The hook finds your project root and runs iris check with the command-line tool bundled with Iris Code. If any file fails, the push is stopped and you see a list like the one above. Otherwise the push goes ahead.

Configuring the threshold

The threshold is the minimum health score a file must reach. Set it with minHealthScore in .irisconfig.json. It defaults to 70.
On an established codebase, a fixed minimum can block a large share of the project from the first day, which usually ends with the hook being uninstalled.

Judging only what a push changes

gateScope decides how much of the code the hook judges. With "changes", Iris Code checks only the files a push changes, and compares each one with its version in the commit the remote already has. Code you did not touch never blocks a push. A changed file blocks the push only if the push made it worse:
  • its score ends below minHealthScore and lower than it was before;
  • it newly breaks a limit such as gateMaxComplexity or gateMaxFileLength, or was already over the limit and got worse;
  • the push adds secrets, security smells, naming violations or duplicate blocks beyond the configured limit. Ones that were already in the file do not count.
A new file has to meet the normal limits. iris init and the editor’s config generator write "changes" for new setups. A config without the key keeps "all", which judges every file on every push, as before. Switching an existing project to "changes" narrows what the gate checks, so verification integrity reports it as rules-loosened, as it does for a lowered minHealthScore. This stops a coding agent narrowing the gate to get its own change through. If you are making the switch yourself, the push that carries it is blocked once; add a line with a reason to that commit’s message:
When Iris Code cannot find the earlier commit, for example on the first push of a branch with no upstream, it judges every file and says why in the hook output. The build hook compares the working tree with the branch’s upstream in the same way.

Comparing with a locked baseline

gateBaselineMode is the older way to avoid blocking existing code. Each existing file is judged against its own score at the time you locked a baseline, a saved snapshot of scores. The rule becomes “do not make this worse” rather than “fix everything first”. New files still have to reach minHealthScore.
An existing pre-push hook is left in place. Iris Code adds its own block between # >>> iris-hook-start <<< and # >>> iris-hook-end <<< markers, so anything already in the file keeps running.

Analytics tracking

Each time the hook runs, the result is recorded as a pass or fail in your account Analytics, so you can see how often it stops a push without reading terminal history. See iriscode.co/account/analytics.

Uninstalling

Run Iris Code: Uninstall Git Hook. Only the Iris Code block between the markers is removed. If nothing else is left in the file apart from its first #! line, the hook file is deleted. If the hook file has no Iris Code block, Iris Code says so and changes nothing.

A damaged hook block

The Iris Code block starts and ends with a marker line. If the file has a start marker without its end, an end without its start, or two blocks, Iris Code cannot tell where its own lines stop. In that case install and uninstall both stop and name the file, and nothing in it is changed. Remove or repair the Iris Code lines by hand, then run the command again. The editor, iris hook git and the JetBrains plugin all follow this rule.

Verification integrity

The hook also checks whether a push makes your tests or rules weaker, for example by deleting or skipping a test or lowering a threshold. This step is Free and runs even when the score check is not available to you. Installing the hook itself still needs Pro. It compares what you are pushing with what the remote branch already has, rather than comparing your uncommitted files with your last commit:
  • For a new branch, which has nothing on the remote yet, it compares with the point where your branch split off from the branch it tracks.
  • Pushing a branch deletion is not checked.
Removed or switched-off tests and loosened rules stop the push by default. To accept a deliberate change, add an Iris-Allow line with a reason to a commit message in the push. Hooks that earlier versions of Iris Code installed already pass Git’s push details to this check, so it runs without changing the hook file. Reinstall the hook after updating to 1.40.0 or later if you also want warnings shown when a push passes. See verification integrity.