Adopt script-helpers in a repository#
The steps to bring a repository onto script-helpers: the library, the git hooks, the scanners and the test entry points. Each step stands alone; stop after any of them.
1. Add the library#
Vendor it as a git submodule at scripts/script-helpers, on the production
branch:
git submodule add -b production https://github.com/nikolareljin/script-helpers.git scripts/script-helpers
git submodule update --init --recursive
git commit -m "chore: vendor script-helpers"
Your scripts then load it with:
Later updates: git submodule update --remote scripts/script-helpers, then
commit the new pointer. See Installation,
Usage and the API index for the modules.
2. Install the git hooks#
From the repository root:
bash scripts/script-helpers/scripts/setup-hooks.sh
bash scripts/script-helpers/scripts/setup-hooks.sh --status # what is installed
On Windows, run the commands in this guide from Git Bash. From PowerShell,
setup-hooks.ps1 finds Git Bash and runs setup-hooks.sh with the same
arguments:
powershell -NoProfile -ExecutionPolicy Bypass -File scripts\script-helpers\scripts\setup-hooks.ps1 --status
Scripts check out with LF whatever core.autocrlf says. If bash reports
$'\r': command not found or set: pipefail: invalid option name, the
checkout still has CRLF files from before .gitattributes applied. With no
local changes in it, rewrite them from scripts/script-helpers:
Hooks the repository already had (a team's, another tool's, .git/hooks)
keep running, after ours. --uninstall puts the previous setup back. To cover
every repository on the machine instead, use --global.
Installing here opts this repository in: it is always checked. With
--global, the checks apply only to the repositories you own; setup records
your GitHub account through gh. To count an organisation as yours too:
The repository-name check reads a list of your private repositories. Build it
once, with gh signed in, before the first push; without it a push is
refused as "could not check":
Details: Git hooks.
3. What a push then checks#
| Group | Checks | On a finding |
|---|---|---|
| security | private repository names (public repositories), credentials (gitleaks), personal identifiers and PII | refused |
| hygiene | conflict markers, large or secret-looking files, release CHANGELOG and VERSION, AI trailers in commit messages (repositories you own) | refused |
| lint | syntax and lint of the changed files, with the tools installed | refused |
| static analysis | foxguard on the changed files | warning only |
The checks read what the push sends; the repository-name check also reads the tracked files. A normal push takes a few seconds. Exceptions and limits: Settings and exceptions.
4. The scanners#
gitleaks and foxguard are pinned releases, checked against their SHA-256.
Setup offers both; a push installs a missing one, except in CI or with
SCRIPT_HELPERS_NO_AUTO_INSTALL=1. To install them now:
Without gitleaks a push is refused: the credential scan cannot run. Without foxguard the push goes on with a warning. foxguard findings can be written to a JSON report:
bash scripts/script-helpers/scripts/foxguard_report.sh --base origin/main --output foxguard-report.json
5. Tests#
Tests do not run on push by default. Run them with:
make test # when the repository has a test target
./dev test # with the shared ./dev entry point
bash scripts/script-helpers/scripts/run_repo_tests.sh # neither: detects the stack
./dev comes from scripts/install_dev_cli.sh:
A repository whose tests run nowhere else (no CI test job) can run its quick tests on every push:
The push is then refused when a test fails, or when no tests are found.
6. Check the result#
Every script and its options: Command reference.