User guideGuide utilisateur

Git, hooks and CIGit, hooks et CI

Check only the changed lines, commit the fixes, refuse a bad commit with the pre-commit hook, fail a CI job.Vérifier seulement les lignes modifiées, committer les corrections, refuser un mauvais commit avec le hook pre-commit, faire échouer un job de CI.

xstyle reads git to check only what changed, and its exit status stops a commit or a CI job.

xstyle lit git pour ne vérifier que ce qui a changé, et son code de sortie arrête un commit ou un job de CI.

1. Only the changed linesSeulement les lignes modifiées

Command	Checks
`xstyle --diff`	the lines changed since `HEAD` (staged and not staged, new files included)
`xstyle --diff-ref main`	the lines changed since a branch, tag or commit
`xstyle --staged`	only the staged lines (`git diff --cached`): the mode of the pre-commit hook

With no path these modes take the changed files themselves. An issue about the whole file is kept when the file changed; --fix follows the same filter.

Commande	Vérifie
`xstyle --diff`	les lignes modifiées depuis `HEAD` (indexées ou non, nouveaux fichiers compris)
`xstyle --diff-ref main`	les lignes modifiées depuis une branche, un tag ou un commit
`xstyle --staged`	seulement les lignes indexées (`git diff --cached`) : le mode du hook pre-commit

Sans chemin, ces modes prennent les fichiers modifiés eux-mêmes. Un problème qui porte sur tout le fichier est gardé quand le fichier a changé ; --fix suit le même filtre.

2. Commit the fixesCommitter les corrections

xstyle --fix --commit                                  # fix, then commit the fixed files
xstyle --fix --commit-all --message "chore(core): ..." # fix, then commit every tracked change with them

The default message is chore(style): apply the xstyle fixes (N issues), with one line per rule. --commit only takes the files that had no change before the fixes (the others are listed and left out); --commit-all takes every tracked change too. Never with --dry-run.

xstyle --fix --commit                                  # corriger, puis committer les fichiers corrigés
xstyle --fix --commit-all --message "chore(core): ..." # corriger, puis committer toutes les modifications suivies avec

Le message par défaut est chore(style): apply the xstyle fixes (N issues), avec une ligne par règle. --commit ne prend que les fichiers qui n'avaient aucune modification avant les corrections (les autres sont listés et laissés) ; --commit-all prend aussi toutes les modifications suivies. Jamais avec --dry-run.

3. Pre-commit hookHook pre-commit

The hook of the repository (.githooks/pre-commit) runs xstyle on the staged lines at each git commit and refuses a major (or worse) issue.

git config core.hooksPath .githooks   # once per clone
git commit --no-verify                # skip it once (or XSTYLE_HOOK=0 git commit ...)
xstyle --fix --staged                 # fix what can be, then git add -u

Setting at the top of the hook	Values (default first)
`SCOPE`	`staged` (staged lines) · `files` (whole staged files) · `all` (whole project)
`FAIL_ON`	`major` · `unforgivable` · `minor` · `negligible` · `never`
`WARN_ON`	`minor` · `negligible` · `none`
`FIX`	`none` · `safe` (auto fixes of the fully staged files, added again before the check)
`MISSING`	`warn` · `fail` · `ignore` (xstyle not installed)
`OUTPUT`	`auto` (compact under Claude Code / `XSTYLE_RTK`) · `human` · `rtk`

Tip. In another repository the hook is installed by the pre-commit skill, or by the setup.sh of ai-utils (hook); a hook already there is kept and run first.

Le hook du dépôt (.githooks/pre-commit) lance xstyle sur les lignes indexées à chaque git commit et refuse un problème major (ou pire).

git config core.hooksPath .githooks   # une fois par clone
git commit --no-verify                # le sauter une fois (ou XSTYLE_HOOK=0 git commit ...)
xstyle --fix --staged                 # corriger ce qui peut l'être, puis git add -u

Réglage en haut du hook	Valeurs (défaut en premier)
`SCOPE`	`staged` (lignes indexées) · `files` (fichiers indexés entiers) · `all` (tout le projet)
`FAIL_ON`	`major` · `unforgivable` · `minor` · `negligible` · `never`
`WARN_ON`	`minor` · `negligible` · `none`
`FIX`	`none` · `safe` (corrections auto des fichiers entièrement indexés, ré-ajoutés avant la vérification)
`MISSING`	`warn` · `fail` · `ignore` (xstyle non installé)
`OUTPUT`	`auto` (compact sous Claude Code / `XSTYLE_RTK`) · `human` · `rtk`

Astuce. Dans un autre dépôt, le hook s'installe avec le skill pre-commit, ou le setup.sh de ai-utils (hook) ; un hook déjà présent est gardé et lancé en premier.

4. In a CI jobDans un job de CI

- name: Style check
  run: xstyle -r src include --fail-on major --r34 --rtk

The exit status is 0 when clean, 1 when an issue at or above --fail-on is left, 255 on an error. On a pull request, --diff-ref origin/<base> checks only its lines. The Build (CI) workflow of xstyle runs it on its own sources this way.

- name: Style check
  run: xstyle -r src include --fail-on major --r34 --rtk

Le code de sortie vaut 0 si tout est propre, 1 s'il reste un problème au niveau de --fail-on ou plus, 255 en cas d'erreur. Sur une pull request, --diff-ref origin/<base> ne vérifie que ses lignes. Le workflow Build (CI) de xstyle le lance ainsi sur ses propres sources.