# git-hooks Git hooks owned by the workspace: a typed configuration of named steps per hook, the runner behind `hf hooks run` and `hf push`, and the stubs Git starts. ## Configuration The hooks live in `hooks.config.ts` at the workspace root, declared with [`defineHooks`](https://www.hyperfrontend.dev/docs/libraries/workspace/git-hooks/#api-defineHooks). Each of `pre-commit`, `commit-msg` and `pre-push` is a list of named steps that run in order, and the first step that fails ends the hook. A fourth list, named push, holds the steps `hf push` runs before it pushes. ```ts import { defineHooks } from '@hyperfrontend/workspace/git-hooks' export default defineHooks({ 'pre-commit': [ { name: 'format', run: ['hf', 'format', '--write'], stageFixed: true, }, ], 'commit-msg': [ { name: 'message', run: ['cl'], passArgs: true, failText: 'Write a conventional commit message.', }, ], 'pre-push': [ { name: 'version-check', run: ['hf', 'affected', '-t', 'version-check'], failText: 'Push with npx hf push.', }, { name: 'checks', run: ['hf', 'affected', '-t', 'typecheck,lint', '-t', 'test'], env: { CI: '1' }, }, ], push: [ { name: 'version', run: ['hf', 'run', 'workspace:version:all'], }, ], }) ``` | Field of a [`HookStep`](https://www.hyperfrontend.dev/docs/libraries/workspace/git-hooks/#api-HookStep) | What it sets | | -------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | | [`name`](https://www.hyperfrontend.dev/docs/libraries/workspace/git-hooks/#api-HookStep-prop-name) | What the step is listed, skipped and selected by | | [`run`](https://www.hyperfrontend.dev/docs/libraries/workspace/git-hooks/#api-HookStep-prop-run) | The program and its arguments, started without a shell from the workspace root | | [`env`](https://www.hyperfrontend.dev/docs/libraries/workspace/git-hooks/#api-HookStep) | Variables set for the step, over the environment the hook runs in | | [`failText`](https://www.hyperfrontend.dev/docs/libraries/workspace/git-hooks/#api-HookStep-prop-failText) | What is printed when the step fails | | [`stageFixed`](https://www.hyperfrontend.dev/docs/libraries/workspace/git-hooks/#api-HookStep-prop-stageFixed) | Stage again the files that were fully staged before the step and that it changed | | [`passArgs`](https://www.hyperfrontend.dev/docs/libraries/workspace/git-hooks/#api-HookStep-prop-passArgs) | Append the arguments Git gave the hook, such as the message file of `commit-msg` | A step is an argument array, so nothing is quoted and no variable is written in front of a command. `hf` starts this command line again the way it was started and `node` is the running Node.js. Any other program is found on the search path with the workspace's `node_modules/.bin` first; on Windows it starts through the command shim a package manager writes for it. [`stageFixed`](https://www.hyperfrontend.dev/docs/libraries/workspace/git-hooks/#api-HookStep-prop-stageFixed) never stashes and never touches unstaged content: a file that was only partly staged is left exactly as it was staged. ## Installing ```bash npx hf generate hooks ``` The generator writes one POSIX `sh` stub per hook that has steps into the repository's hooks directory, each starting `hf hooks run ` with the arguments Git gave. It rewrites its own stubs, takes the place of Lefthook's, removes the stubs of hooks that no longer have steps, and refuses to replace a hook file somebody else wrote unless given `--force`. A workspace without a configuration gets a first one. Installing the package runs nothing. A repository that wants its hooks installed on every install says so in its own root manifest: ```json { "scripts": { "prepare": "hf generate hooks" } } ``` That is safe in a deploy build: where the CI variable is set or there is no repository, the generator writes nothing and succeeds. It also writes nothing, and says why, where the workspace is not the root of its repository or Git reads the hooks from a directory outside the workspace, as it does in a linked working tree. ## Skipping A clone that does not want a step names it in an untracked `hooks.local.config.ts` beside the configuration, declared with [`defineLocalHooks`](https://www.hyperfrontend.dev/docs/libraries/workspace/git-hooks/#api-defineLocalHooks): ```ts import { defineLocalHooks } from '@hyperfrontend/workspace/git-hooks' export default defineLocalHooks({ skip: ['checks', 'pre-commit:format'] }) ``` A name skips the step in every hook that has one; `:` skips it in that hook alone. For one invocation, the variable HF_HOOKS_SKIP takes the same names separated by commas, and HF_HOOKS set to 0 skips every step: ```bash HF_HOOKS_SKIP=checks git push ``` A skip is never silent. The hook ends on one line per step, and a skipped step is listed with what skipped it; a name that matches no step is reported too. ```text pre-push ✓ version-check 2.1s - checks skipped by hooks.local.config.ts ``` ## Rehearsing and pushing `hf hooks run ` is what a stub starts, and by hand it rehearses the hook without committing or pushing. `--only` and `--skip` select steps by name: ```bash npx hf hooks run pre-push npx hf hooks run pre-push --only=version-check ``` `hf push` runs the push steps and then `git push` with the arguments it was given. Git resolves what a push sends before the pre-push hook runs, so a commit made inside that hook is left behind; a step that commits, such as a version bump, belongs among the push steps, where its commit is part of what the push carries and of what the pre-push hook then checks. ```bash npx hf push --set-upstream origin feature ``` ## Building on the parts The commands are built from exported parts. [`loadHooks`](https://www.hyperfrontend.dev/docs/libraries/workspace/git-hooks/#api-loadHooks) reads both files, [`skipReason`](https://www.hyperfrontend.dev/docs/libraries/workspace/git-hooks/#api-skipReason) says what skips a step, and [`runHook`](https://www.hyperfrontend.dev/docs/libraries/workspace/git-hooks/#api-runHook) runs steps through a host you supply: ```ts import { loadHooks, runHook, skipReason } from '@hyperfrontend/workspace/git-hooks' import { createTerminal } from '@hyperfrontend/workspace/progress' const { config, local } = await loadHooks(process.cwd()) const sources = { env: process.env, local, only: [], skip: [] } const code = await runHook( { hook: 'pre-push', steps: config['pre-push'] ?? [], args: [], skipOf: (step) => skipReason('pre-push', step, sources), }, { start: async (step) => (step.name === 'checks' ? 0 : 1), now: () => performance.now(), terminal: createTerminal(process.stderr, process.env), fullyStaged: () => [], restage: () => [], } ) ``` ## API Reference ### Functions #### checkHooks ```typescript function checkHooks(value: unknown): HooksConfig ``` Reads a value as a hooks configuration. **Parameters** | Name | Type | Description | | --- | --- | --- | | `value` | `unknown` | What `hooks.config.ts` exports | **Returns** `HooksConfig`: The configuration **Example: Reading what a configuration file exports** ```typescript import { checkHooks } from '@hyperfrontend/workspace/git-hooks' checkHooks({ 'pre-push': [{ name: 'lint', run: ['hf', 'affected', '-t', 'lint'] }] }) // => the same object checkHooks({ 'post-merge': [] }) // throws: post-merge is not a hook this configures; the hooks are pre-commit, commit-msg, pre-push, push ``` #### checkLocalHooks ```typescript function checkLocalHooks(value: unknown): LocalHooksConfig ``` Reads a value as one clone's preferences. **Parameters** | Name | Type | Description | | --- | --- | --- | | `value` | `unknown` | What `hooks.local.config.ts` exports | **Returns** `LocalHooksConfig`: The preferences **Example: Reading what a local file exports** ```typescript import { checkLocalHooks } from '@hyperfrontend/workspace/git-hooks' checkLocalHooks({ skip: ['pipeline', 'pre-commit:format'] }) // => the same object checkLocalHooks({ skip: 'pipeline' }) // throws: skip takes a list of step names ``` #### defineHooks ```typescript function defineHooks(config: HooksConfig): HooksConfig ``` Declares the hooks of a workspace, in `hooks.config.ts` at its root. Each hook is a list of named steps that run in order; the first that fails ends the hook. **Parameters** | Name | Type | Description | | --- | --- | --- | | `config` | `HooksConfig` | The steps of each hook | **Returns** `HooksConfig`: The configuration, checked **Example: Formatting what is committed and checking what is pushed** ```typescript import { defineHooks } from '@hyperfrontend/workspace/git-hooks' export default defineHooks({ 'pre-commit': [{ name: 'format', run: ['hf', 'format', '--write'], stageFixed: true }], 'pre-push': [ { name: 'checks', run: ['hf', 'affected', '-t', 'typecheck,lint', '-t', 'test'], failText: 'A check failed. Each task wrote its log under .hf/logs.', }, ], }) ``` #### defineLocalHooks ```typescript function defineLocalHooks(config: LocalHooksConfig): LocalHooksConfig ``` Declares what one clone changes about the workspace's hooks, in an untracked `hooks.local.config.ts` beside the configuration. **Parameters** | Name | Type | Description | | --- | --- | --- | | `config` | `LocalHooksConfig` | The steps this clone does not run | **Returns** `LocalHooksConfig`: The preferences, checked **Example: A clone that leaves the long step to the pull request** ```typescript import { defineLocalHooks } from '@hyperfrontend/workspace/git-hooks' export default defineLocalHooks({ skip: ['pipeline'] }) ``` #### fullyStaged ```typescript function fullyStaged(git: Git): string[] ``` The files whose staged content is all there is to them: staged, and with no unstaged change. **Parameters** | Name | Type | Description | | --- | --- | --- | | `git` | `Git` | Runs git in the workspace | **Returns** `string[]`: The paths, relative to the directory git runs in **Example: Before a formatter runs** ```typescript import { fullyStaged, gitIn } from '@hyperfrontend/workspace/git-hooks' fullyStaged(gitIn(process.cwd())) // => ['src/a.ts'] when src/b.ts is staged too but was edited since ``` #### gitIn ```typescript function gitIn(cwd: string): Git ``` Git, run from a directory. **Parameters** | Name | Type | Description | | --- | --- | --- | | `cwd` | `string` | The directory, absolute | **Returns** `Git`: Runs git there **Example: Asking the repository of the working directory** ```typescript import { gitIn } from '@hyperfrontend/workspace/git-hooks' gitIn(process.cwd())(['rev-parse', '--show-prefix']) // => '\n' at the root of a working tree ``` #### launchOf ```typescript function launchOf(run: unknown, started: StartedAs, platform: Platform): Launch ``` How to start what a step runs. **Parameters** | Name | Type | Description | | --- | --- | --- | | `run` | `unknown` | The program and its arguments, as the step writes them | | `started` | `StartedAs` | The running process | | `platform` | `Platform` | `win32` or another platform name | **Returns** `Launch`: The executable, its arguments and whether a shell starts it **Example: The command line itself, and a package's executable** ```typescript import { launchOf } from '@hyperfrontend/workspace/git-hooks' launchOf(['hf', 'format', '--write'], process, process.platform) // => { file: '/usr/bin/node', args: ['/repo/node_modules/@hyperfrontend/workspace/bin/hf.mjs', 'format', '--write'], shell: false } launchOf(['cl', '.git/COMMIT_EDITMSG'], process, 'linux') // => { file: 'cl', args: ['.git/COMMIT_EDITMSG'], shell: false } ``` #### loadHooks ```typescript function loadHooks(root: string): Promise ``` Loads the hooks of a workspace. **Parameters** | Name | Type | Description | | --- | --- | --- | | `root` | `string` | The workspace root, absolute | **Returns** `Promise`: The configuration, and the local preferences when the clone has any **Example: Listing the steps a push runs here** ```typescript import { loadHooks } from '@hyperfrontend/workspace/git-hooks' const { config, local } = await loadHooks(process.cwd()) const skipped = local.skip ?? [] (config['pre-push'] ?? []).filter((step) => !skipped.includes(step.name)).map((step) => step.name) // => ['binary-budget', 'audit', 'version-check'] in a clone whose local file skips 'pipeline' ``` #### namesOf ```typescript function namesOf(value: string): string[] ``` The names a comma-separated value holds. **Parameters** | Name | Type | Description | | --- | --- | --- | | `value` | `string` | The value of a flag or a variable, if any | **Returns** `string[]`: The names, none for an absent or empty value **Example: Reading the steps one push skips** ```typescript import { namesOf } from '@hyperfrontend/workspace/git-hooks' namesOf('pipeline, audit') // => ['pipeline', 'audit'] namesOf(undefined) // => [] ``` #### planStubs ```typescript function planStubs(existing: ReadonlyMap, configured: unknown): StubPlan ``` What installing the stubs of the configured hooks does to a hooks directory. **Parameters** | Name | Type | Description | | --- | --- | --- | | `existing` | `ReadonlyMap` | The content of each file in the directory, by name | | `configured` | `unknown` | The hooks that have steps | **Returns** `StubPlan`: The stubs to write, the files to remove, and the configured hooks somebody else's file occupies **Example: A clone that Lefthook set up, with a hook of the committer's own** ```typescript import { planStubs } from '@hyperfrontend/workspace/git-hooks' planStubs( new Map([ ['pre-commit', '#!/bin/sh\ncall_lefthook run "pre-commit" "$@"\n'], ['post-commit', '#!/bin/sh\ncall_lefthook run "post-commit" "$@"\n'], ['pre-push', '#!/bin/sh\ngit lfs pre-push "$@"\n'], ]), ['pre-commit', 'pre-push'] ) // => { write: ['pre-commit'], remove: ['post-commit'], foreign: ['pre-push'] } ``` #### restage ```typescript function restage(git: Git, before: unknown): string[] ``` Stages again the files a step changed, among those that were fully staged before it. **Parameters** | Name | Type | Description | | --- | --- | --- | | `git` | `Git` | Runs git in the workspace | | `before` | `unknown` | The files that were fully staged before the step | **Returns** `string[]`: The files staged again **Example: After a formatter ran** ```typescript import { fullyStaged, gitIn, restage } from '@hyperfrontend/workspace/git-hooks' const git = gitIn(process.cwd()) const before = fullyStaged(git) // ... the formatter rewrites src/a.ts restage(git, before) // => ['src/a.ts'], staged with the formatter's changes ``` #### runHook ```typescript function runHook(run: HookRun, host: HookHost): Promise ``` Runs the steps of a hook in order and reports them. **Parameters** | Name | Type | Description | | --- | --- | --- | | `run` | `HookRun` | The hook, its steps, Git's arguments and which steps are skipped | | `host` | `HookHost` | How steps run and where the report is written | **Returns** `Promise`: The exit code: 0 when every step that ran succeeded, 1 otherwise **Example: A push whose audit fails before the long step starts** ```typescript import { createTerminal } from '@hyperfrontend/workspace/progress' import { runHook } from '@hyperfrontend/workspace/git-hooks' const code = await runHook( { hook: 'pre-push', steps: [ { name: 'audit', run: ['hf', 'run-many', '-t', 'audit', '--all'], failText: 'The audit failed.' }, { name: 'pipeline', run: ['hf', 'affected', '-t', 'test'] }, ], args: ['origin', 'git@example.com:acme/repo.git'], skipOf: () => null, }, { start: async (step) => (step.name === 'audit' ? 1 : 0), now: () => performance.now(), terminal: createTerminal(process.stderr, process.env), fullyStaged: () => [], restage: () => [], } ) // => 1, after the lines: // pre-push // ✗ audit 0s // · pipeline not run // The audit failed. ``` #### runHooksCommand ```typescript function runHooksCommand(argv: unknown, session: HooksSession): Promise ``` Runs `hooks run `: the steps of a hook, in order, as the stub of that hook starts them. **Parameters** | Name | Type | Description | | --- | --- | --- | | `argv` | `unknown` | The arguments after `hooks` | | `session` | `HooksSession` | The workspace root and the stream written to | **Returns** `Promise`: The exit code: 0 when every step that ran succeeded, 1 otherwise **Example: Rehearsing a push without the long step** ```typescript import { runHooksCommand } from '@hyperfrontend/workspace/git-hooks' const code = await runHooksCommand(['run', 'pre-push', '--skip=pipeline'], { root: process.cwd(), sink: process.stderr }) // => 0 when the other steps of pre-push succeeded; the list says pipeline was skipped by --skip ``` #### runPushCommand ```typescript function runPushCommand(argv: unknown, session: HooksSession): Promise ``` Runs `push`: the configuration's `push` steps, then `git push` with the arguments given. The pre-push hook then runs as on any push, on the commits the push carries. Asked for help, it prints its usage and runs nothing. **Parameters** | Name | Type | Description | | --- | --- | --- | | `argv` | `unknown` | The arguments after `push`, passed to `git push` | | `session` | `HooksSession` | The workspace root and the stream written to | **Returns** `Promise`: The exit code of the first step that failed, else of `git push` **Example: Pushing a branch for the first time** ```typescript import { runPushCommand } from '@hyperfrontend/workspace/git-hooks' const code = await runPushCommand(['--set-upstream', 'origin', 'feature'], { root: process.cwd(), sink: process.stderr }) // => 0 once the push steps succeeded and git pushed ``` #### skipReason ```typescript function skipReason(hook: HookName, step: string, sources: SkipSources): string ``` Why a step is skipped, if it is. **Parameters** | Name | Type | Description | | --- | --- | --- | | `hook` | `HookName` | The hook the step belongs to | | `step` | `string` | The step's name | | `sources` | `SkipSources` | The flags, the environment and the local file | **Returns** `string`: What skipped the step, or null when it runs **Example: A step this clone's local file names** ```typescript import { skipReason } from '@hyperfrontend/workspace/git-hooks' const sources = { env: process.env, local: { skip: ['pipeline'] }, only: [], skip: [] } skipReason('pre-push', 'pipeline', sources) // => 'hooks.local.config.ts' skipReason('pre-push', 'audit', sources) // => null ``` #### stepNames ```typescript function stepNames(config: HooksConfig): ReadonlySet ``` The names of every step a configuration holds, plain and qualified by hook. **Parameters** | Name | Type | Description | | --- | --- | --- | | `config` | `HooksConfig` | The hooks | **Returns** `ReadonlySet`: Each step as `` and as `:` **Example: Telling a skip that names nothing from one that names a step** ```typescript import { stepNames } from '@hyperfrontend/workspace/git-hooks' stepNames({ 'pre-push': [{ name: 'audit', run: ['hf', 'run-many', '-t', 'audit', '--all'] }] }).has('pre-push:audit') // => true ``` #### stubEntry ```typescript function stubEntry(root: string, from: string): string ``` The entry module a stub starts: the `hf` executable of the package this module belongs to, as a path from the workspace root where the package lies inside it. **Parameters** | Name | Type | Description | | --- | --- | --- | | `root` | `string` | The workspace root, absolute | | `from` | `string` | A directory of the package, absolute | **Returns** `string`: The entry module, workspace-relative where it can be, POSIX **Example: The executable of the installed package** ```typescript import { stubEntry } from '@hyperfrontend/workspace/git-hooks' stubEntry('/repo', '/repo/node_modules/@hyperfrontend/workspace/git-hooks') // => 'node_modules/@hyperfrontend/workspace/bin/hf.mjs' ``` #### stubOf ```typescript function stubOf(hook: "pre-commit" | "commit-msg" | "pre-push", entry: string): string ``` The stub of a hook. **Parameters** | Name | Type | Description | | --- | --- | --- | | `hook` | `"pre-commit" \| "commit-msg" \| "pre-push"` | Which hook the stub starts | | `entry` | `string` | The command line's entry module, relative to the workspace root or absolute, POSIX | **Returns** `string`: The file's content **Example: The stub Git runs before a commit** ```typescript import { stubOf } from '@hyperfrontend/workspace/git-hooks' stubOf('pre-commit', 'node_modules/@hyperfrontend/workspace/bin/hf.mjs') // => '#!/bin/sh\n# hf-hooks: ...\nexec node "node_modules/@hyperfrontend/workspace/bin/hf.mjs" hooks run pre-commit "$@"\n' ``` #### stubOrigin ```typescript function stubOrigin(content: string): StubOrigin ``` Who wrote a stub. **Parameters** | Name | Type | Description | | --- | --- | --- | | `content` | `string` | The file's content | **Returns** `StubOrigin`: This package, Lefthook, or somebody else **Example: Telling a stub that may be replaced from one that may not** ```typescript import { stubOf, stubOrigin } from '@hyperfrontend/workspace/git-hooks' stubOrigin(stubOf('pre-push', 'node_modules/@hyperfrontend/workspace/bin/hf.mjs')) // => 'own' stubOrigin('#!/bin/sh\ncall_lefthook run "pre-push" "$@"\n') // => 'lefthook' stubOrigin('#!/bin/sh\ngit lfs pre-push "$@"\n') // => 'foreign' ``` #### stubPlace ```typescript function stubPlace(root: string, env: Readonly>, git: Git): StubPlace ``` Where the stubs of a workspace go. None is written under `CI` or outside a repository, quietly, because the installing command also runs from the `prepare` script of deploy builds; none is written, with the reason, where the workspace is not the root of its repository or Git reads the repository's hooks from a directory outside the workspace. **Parameters** | Name | Type | Description | | --- | --- | --- | | `root` | `string` | The workspace root, absolute | | `env` | `Readonly>` | The environment | | `git` | `Git` | Runs git in the workspace | **Returns** `StubPlace`: The hooks directory, or why there is none to write to **Example: A clone, and a deploy build of the same repository** ```typescript import { gitIn, stubPlace } from '@hyperfrontend/workspace/git-hooks' stubPlace(process.cwd(), {}, gitIn(process.cwd())) // => { directory: '.git/hooks', reason: null } stubPlace(process.cwd(), { CI: 'true' }, gitIn(process.cwd())) // => { directory: null, reason: null } ``` #### unknownSkips ```typescript function unknownSkips(config: HooksConfig, sources: SkipSources): string[] ``` The names that were meant to select or skip a step and match none, so a misspelt skip is said rather than silently ignored. **Parameters** | Name | Type | Description | | --- | --- | --- | | `config` | `HooksConfig` | The hooks | | `sources` | `SkipSources` | The flags, the environment and the local file | **Returns** `string[]`: One line per source that names a step no hook has **Example: A skip that names nothing** ```typescript import { unknownSkips } from '@hyperfrontend/workspace/git-hooks' const config = { 'pre-push': [{ name: 'pipeline', run: ['hf', 'affected', '-t', 'test'] }] } unknownSkips(config, { env: { HF_HOOKS_SKIP: 'pipline' }, local: {}, only: [], skip: [] }) // => ['HF_HOOKS_SKIP names no step: pipline'] ``` ### Interfaces #### HookHost What the runner is given to run steps and say how they ended. **Properties** | Name | Type | Description | | --- | --- | --- | | `readonly start` | `(step: HookStep, args: unknown) => Promise` | Starts a step with its arguments and settles on its exit code. | | `readonly now` | `() => number` | The time, in milliseconds. | | `readonly terminal` | `Terminal` | Where the lines are written. | | `readonly fullyStaged` | `() => string[]` | The files that are fully staged. | | `readonly restage` | `(before: unknown) => unknown` | Stages again the files a step changed, among those given. | #### HookRun A hook to run. **Properties** | Name | Type | Description | | --- | --- | --- | | `readonly hook` | `HookName` | The hook, as the step list is headed. | | `readonly steps` | `unknown` | Its steps, in order. | | `readonly args` | `unknown` | The arguments Git gave the hook. | | `readonly skipOf` | `(step: string) => string` | Why a step is skipped, or null when it runs. | #### HooksSession Where a command of the hooks runs and writes. **Properties** | Name | Type | Description | | --- | --- | --- | | `readonly root` | `string` | The workspace root, absolute. | | `readonly sink` | `ProgressSink` | The stream the step list goes to. | #### HookStep One step of a hook. **Properties** | Name | Type | Description | | --- | --- | --- | | `readonly name` | `string` | The name the step is listed, skipped and selected by: letters, digits, `.`, `_` and `-`. | | `readonly run` | `unknown` | The program and its arguments, started without a shell from the workspace root. `hf` is this command line and `node` the running Node.js; any other program is found on the search path, the workspace's `node_modules/.bin` first. | | `readonly env?` | `Readonly>` | Variables set for the step, over the environment the hook runs in. | | `readonly failText?` | `string` | What is printed when the step fails. | | `readonly stageFixed?` | `boolean` | Whether the files that were fully staged before the step, and that it changed, are staged again after it. | | `readonly passArgs?` | `boolean` | Whether the arguments Git gave the hook follow the step's own. | #### Launch A program ready to be spawned. **Properties** | Name | Type | Description | | --- | --- | --- | | `readonly file` | `string` | The executable, or on Windows the whole command line of a shim. | | `readonly args` | `unknown` | Its arguments. | | `readonly shell` | `boolean` | Whether it starts through the platform shell, which only a Windows shim needs. | #### LoadedHooks A workspace's hooks and what this clone changes about them. **Properties** | Name | Type | Description | | --- | --- | --- | | `readonly config` | `HooksConfig` | The steps of each hook. | | `readonly local` | `LocalHooksConfig` | This clone's preferences; none where it keeps no local file. | #### LocalHooksConfig What one clone changes about the workspace's hooks. **Properties** | Name | Type | Description | | --- | --- | --- | | `readonly skip?` | `unknown` | The steps this clone does not run: a step's name, or `:` for the step of one hook. | #### SkipSources Everything that can keep a step from running. **Properties** | Name | Type | Description | | --- | --- | --- | | `readonly env` | `Readonly>` | The environment the hook runs in. | | `readonly local` | `LocalHooksConfig` | This clone's preferences. | | `readonly only` | `unknown` | The steps `--only` names; none runs every step. | | `readonly skip` | `unknown` | The steps `--skip` names. | #### StubPlace Where stubs go, or why none is written. **Properties** | Name | Type | Description | | --- | --- | --- | | `readonly directory` | `string` | The hooks directory, workspace-relative and POSIX; null when no stub is written. | | `readonly reason` | `string` | Why no stub is written, when that is worth saying; null where staying quiet is the point. | #### StubPlan What installing does to the hooks directory. **Properties** | Name | Type | Description | | --- | --- | --- | | `readonly write` | `unknown` | The hooks whose stub is written. | | `readonly remove` | `unknown` | The files removed: this package's and Lefthook's stubs of hooks no longer configured. | | `readonly foreign` | `unknown` | The configured hooks whose file somebody else wrote. | ### Types #### Git Runs git with arguments and, when given, standard input; answers what it printed. ```typescript type Git = (args: unknown, input?: string) => string ``` #### GitHook One of the Git hooks. ```typescript type GitHook = indexedAccess ``` #### HookName A list of steps a configuration names: a Git hook, or the steps `hf push` runs first. ```typescript type HookName = GitHook | unknown ``` #### HooksConfig A workspace's hooks: the steps of each, in the order they run. ```typescript type HooksConfig = mapped ``` #### StubOrigin One of the origins. ```typescript type StubOrigin = indexedAccess ``` ### Variables #### GIT_HOOKS The Git hooks a workspace configures, in the order a commit and a push reach them. ```typescript const GIT_HOOKS: unknown ``` **Value** `...` #### HOOKS_CONFIG The file holding a workspace's hooks, at its root. ```typescript const HOOKS_CONFIG: "hooks.config.ts" ``` **Value** `'hooks.config.ts'` #### HOOKS_USAGE What the command line expects. ```typescript const HOOKS_USAGE: "usage: hf hooks run [--only=] [--skip=] [arguments of the hook ...]" ``` **Value** `'usage: hf hooks run [--only=] [--skip=] [arguments of the hook ...]'` #### HOOKS_VARIABLE The variable that switches every hook off when it holds `0`. ```typescript const HOOKS_VARIABLE: "HF_HOOKS" ``` **Value** `'HF_HOOKS'` #### LOCAL_HOOKS_CONFIG The file holding one clone's preferences, at the workspace root and never tracked. ```typescript const LOCAL_HOOKS_CONFIG: "hooks.local.config.ts" ``` **Value** `'hooks.local.config.ts'` #### PUSH_STEPS The name the steps of `hf push` go by: they run before the push, outside any Git hook. ```typescript const PUSH_STEPS: "push" ``` **Value** `'push'` #### PUSH_USAGE What the command line expects. ```typescript const PUSH_USAGE: "usage: hf push [arguments of git push ...]" ``` **Value** `'usage: hf push [arguments of git push ...]'` #### SKIP_VARIABLE The variable naming the steps one invocation skips, separated by commas. ```typescript const SKIP_VARIABLE: "HF_HOOKS_SKIP" ``` **Value** `'HF_HOOKS_SKIP'` #### STUB_MARKER The comment that marks a stub as this package's own. ```typescript const STUB_MARKER: "# hf-hooks:" ``` **Value** `'# hf-hooks:'` #### StubOrigin Who wrote a stub. ```typescript const StubOrigin: Readonly<{ Foreign: "foreign"; Lefthook: "lefthook"; Own: "own" }> ``` **Value** `...` --- Canonical page: https://www.hyperfrontend.dev/docs/libraries/workspace/git-hooks/ This file: https://www.hyperfrontend.dev/docs/libraries/workspace/git-hooks.md Documentation index: https://www.hyperfrontend.dev/llms.txt