|
| 1 | +# hk |
| 2 | + |
| 3 | +Git hooks and code quality checks for the yadm dotfiles repo. |
| 4 | + |
| 5 | +## Configuration |
| 6 | + |
| 7 | +**Main config**: `~/hk.pkl` (requires hk v1.44.1+ for yadm bare-repo support) |
| 8 | + |
| 9 | +hk is installed globally via `hk install --global`, using Git 2.54+ config-based hooks. It runs as a |
| 10 | +silent no-op in repos without an `hk.pkl`. |
| 11 | + |
| 12 | +### yadm-specific settings |
| 13 | + |
| 14 | +Two settings in `hk.pkl` are needed to make hk work cleanly in the yadm context |
| 15 | +(`GIT_WORK_TREE=$HOME`): |
| 16 | + |
| 17 | +- **`env { ["HK_STASH_UNTRACKED"] = "false" }`** — prevents hk from running |
| 18 | + `git status --untracked-files=all` which would scan the entire home directory (~45s). |
| 19 | + See [jdx/hk#860](https://github.com/jdx/hk/discussions/860). |
| 20 | +- **`stash = "none"`** on pre-commit and fix hooks — avoids a recursive hook invocation. |
| 21 | + `hk install --global` registers a hook on every git operation, so the internal `git stash push` |
| 22 | + hk runs during pre-commit would re-trigger hk and cause an infinite loop. Downside: if you have |
| 23 | + unstaged changes, auto-fixers may modify them alongside staged content. |
| 24 | + |
| 25 | +## Running Hooks Manually |
| 26 | + |
| 27 | +```bash |
| 28 | +# Run all checks (all files) |
| 29 | +yadm enter hk check --all |
| 30 | + |
| 31 | +# Run all fixers (all files) |
| 32 | +yadm enter hk fix --all |
| 33 | + |
| 34 | +# Via mise tasks |
| 35 | +mise run dotfiles:lint |
| 36 | +mise run dotfiles:fix |
| 37 | + |
| 38 | +# Dry-run: see what would run and why |
| 39 | +yadm enter hk check --plan |
| 40 | +``` |
| 41 | + |
| 42 | +## Configured Steps |
| 43 | + |
| 44 | +| Step | Purpose | |
| 45 | +| ------------------------------- | ---------------------------------------------- | |
| 46 | +| trailing-whitespace | Remove trailing whitespace | |
| 47 | +| newlines | Ensure files end with a newline | |
| 48 | +| check-merge-conflict | Detect leftover conflict markers | |
| 49 | +| typos | Spell checking for source code | |
| 50 | +| gitleaks | Secret detection | |
| 51 | +| yamllint | YAML linting | |
| 52 | +| editorconfig-checker | EditorConfig conformance | |
| 53 | +| shellcheck | Shell script linting (bash/sh only) | |
| 54 | +| shfmt | Shell script formatting | |
| 55 | +| zsh-syntax-check | Zsh syntax validation (`zsh -n`) | |
| 56 | +| stylua | Lua formatting (top-level .lua only) | |
| 57 | +| prettier | JSON/Markdown/YAML formatting | |
| 58 | +| standardrb | Ruby linting/formatting | |
| 59 | +| check-json | JSON parse validation | |
| 60 | +| check-executables-have-shebangs | Executables must have shebangs | |
| 61 | +| check-added-large-files | Block files over 500KB | |
| 62 | +| no-yadm-alt-symlinks | Reject staged yadm alt symlinks | |
| 63 | +| mise-fmt | Mise config formatting | |
| 64 | +| renovate-config-validator | Renovate config validation | |
| 65 | +| commitlint | Conventional commit messages (commit-msg hook) | |
| 66 | + |
| 67 | +## CI Integration |
| 68 | + |
| 69 | +The `hk-check` job in `.github/workflows/ci.yml` runs `hk check --all` via `jdx/mise-action`, |
| 70 | +which installs all tools from the Linux mise config. Steps skipped in CI: |
| 71 | + |
| 72 | +- `standardrb` — requires Ruby gems not in CI |
| 73 | +- `renovate-config-validator` — requires npm:renovate |
| 74 | +- `no-yadm-alt-symlinks` — requires yadm |
| 75 | + |
| 76 | +The separate `luacheck` job lints `.config/nvim/**/*.lua` since hk's global exclude |
| 77 | +hides `.config/` from scanning. |
| 78 | + |
| 79 | +## Bypassing Hooks |
| 80 | + |
| 81 | +```bash |
| 82 | +HK=0 yadm commit -m "wip" # skip all hk hooks |
| 83 | +HK_SKIP_STEPS=typos yadm commit -m "" # skip a specific step |
| 84 | +``` |
| 85 | + |
| 86 | +## Debugging |
| 87 | + |
| 88 | +```bash |
| 89 | +yadm enter hk check -v # verbose output |
| 90 | +yadm enter hk check --plan # show what would run |
| 91 | +yadm enter hk check --step stylua # single step |
| 92 | +``` |
| 93 | + |
| 94 | +## Adding New Steps |
| 95 | + |
| 96 | +Edit `~/hk.pkl`. Add to the `fast_steps` mapping — it is shared across `pre-commit`, `fix`, and |
| 97 | +`check` hooks. Run `yadm enter hk validate` to verify syntax. |
| 98 | + |
| 99 | +## Version Management |
| 100 | + |
| 101 | +hk version is managed by mise (`hk = "latest"` in `~/.config/mise/conf.d/global.toml`). |
| 102 | +When upgrading, bump the `amends` and `import` URLs in `~/hk.pkl` to match the new version. |
| 103 | + |
| 104 | +Check current version: `hk --version` |
0 commit comments