# hooks Installs the Git hooks a workspace configures into the clone: one POSIX `sh` stub per hook that has steps in `hooks.config.ts`, written into the repository's hooks directory and starting `hf hooks run `. A workspace without a configuration gets a first one, with a format step before a commit and the affected checks before a push, and `.gitignore` gains the line that keeps a clone's `hooks.local.config.ts` out of the repository. ```bash npx hf generate hooks ``` | Option | What it sets | | -------------- | ------------------------------------------------------------------ | | `--force` | Replace a hook file that neither this generator nor Lefthook wrote | | `--skipFormat` | Leave the first configuration unformatted | Running it again is how a change to the configured hooks reaches the clone: it rewrites its own stubs, takes the place of Lefthook's, and removes the stubs of hooks that no longer have steps. A repository installs its hooks on every install by naming the generator in the prepare script of its root manifest; where the CI variable is set or there is no repository it writes nothing and succeeds, so the script is harmless in a deploy build. It 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. The steps, the skips and the commands are described under [`/git-hooks`](https://www.hyperfrontend.dev/docs/libraries/workspace/git-hooks.md). ## API Reference ### Functions #### hooksGenerator ```typescript function hooksGenerator(tree: Tree, options: HooksGeneratorOptions, env: Readonly>): Promise ``` Installs the hooks of the workspace into the clone: a POSIX `sh` stub per configured hook in the repository's hooks directory, each starting `hf hooks run `. A workspace without a `hooks.config.ts` gets a first one. It writes nothing and succeeds where `CI` is set or there is no repository, so a root `prepare` script may run it in every install; it says why and writes nothing where the workspace is not the root of its repository or Git reads the hooks from a directory outside it. **Parameters** | Name | Type | Description | | --- | --- | --- | | `tree` | `Tree` | The tree, rooted at the workspace | | `options` | `HooksGeneratorOptions` | Whether to replace a foreign hook file, and whether to format (default: `{}`) | | `env` | `Readonly>` | The environment, this process's unless another is given (default: `process.env`) | **Returns** `Promise`: Resolves when the stubs are written **Example: Installing the hooks of a clone** ```bash npx hf generate hooks ``` **Example: On every install of the repository, from its root manifest** ```json { "scripts": { "prepare": "hf generate hooks" } } ``` #### stubDirectory ```typescript function stubDirectory(tree: Tree, env: Readonly>): string ``` The hooks directory the stubs of a tree's workspace go to, saying why when there is one reason worth saying and no directory. **Parameters** | Name | Type | Description | | --- | --- | --- | | `tree` | `Tree` | The tree, rooted at the workspace | | `env` | `Readonly>` | The environment | **Returns** `string`: The directory, relative to the tree's root, or null when no stub is to be written **Example: Writing stubs only where a clone can take them** ```typescript import { DEFAULT_HOOKS, stubDirectory, writeStubs } from '@hyperfrontend/workspace/generators/hooks' const directory = stubDirectory(tree, process.env) // => '.git/hooks' in a clone, null in a deploy build if (directory !== null) writeStubs(tree, { directory, hooks: DEFAULT_HOOKS, force: false }) ``` #### writeHooksSetup ```typescript function writeHooksSetup(tree: Tree): void ``` Writes what a workspace's hooks start from: the first configuration, unless the workspace has one, and the line that keeps a clone's local file out of the repository. **Parameters** | Name | Type | Description | | --- | --- | --- | | `tree` | `Tree` | The tree, rooted at the workspace | **Example: Giving a workspace of your own generator its hooks** ```typescript import { writeHooksSetup } from '@hyperfrontend/workspace/generators/hooks' writeHooksSetup(tree) // writes hooks.config.ts when missing, and adds hooks.local.config.ts to .gitignore ``` #### writeStubs ```typescript function writeStubs(tree: Tree, request: StubRequest): void ``` Writes the stub of every configured hook into a hooks directory, removes this package's and Lefthook's stubs of hooks no longer configured, and leaves every other file alone. **Parameters** | Name | Type | Description | | --- | --- | --- | | `tree` | `Tree` | The tree, rooted at the workspace | | `request` | `StubRequest` | The directory, the hooks and whether to replace a foreign file | **Example: Installing two hooks into the repository of the tree** ```typescript import { writeStubs } from '@hyperfrontend/workspace/generators/hooks' writeStubs(tree, { directory: '.git/hooks', hooks: ['pre-commit', 'pre-push'], force: false }) ``` ### Interfaces #### HooksGeneratorOptions What the `hooks` generator takes. **Properties** | Name | Type | Description | | --- | --- | --- | | `force?` | `boolean` | Replace a hook file that neither this generator nor Lefthook wrote | | `skipFormat?` | `boolean` | Skip formatting the configuration written | #### StubRequest The stubs to install and where. **Properties** | Name | Type | Description | | --- | --- | --- | | `readonly directory` | `string` | The hooks directory, relative to the tree's root, POSIX. | | `readonly hooks` | `unknown` | The hooks that have steps. | | `readonly force` | `boolean` | Whether a file somebody else wrote is replaced. | ### Variables #### DEFAULT_HOOKS The hooks the first configuration gives steps. ```typescript const DEFAULT_HOOKS: unknown ``` **Value** `...` --- Canonical page: https://www.hyperfrontend.dev/docs/libraries/workspace/generators/hooks/ This file: https://www.hyperfrontend.dev/docs/libraries/workspace/generators/hooks.md Documentation index: https://www.hyperfrontend.dev/llms.txt