NotAShelf/eh
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs: describe new configuration options

Browse source 
Signed-off-by: NotAShelf <raf@notashelf.dev>
Change-Id: I6365676d18d980b5727bc65d07cf47af6a6a6964
This commit is contained in:
raf 2026-04-23 17:43:45 +03:00
commit a53664be83
Signed by: NotAShelf
GPG key ID: 29D95B64378DB4BF
1 changed files with 90 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

90
README.md
View file

@ -27,6 +27,10 @@ of building the package. The following variables are supported:
- **Insecure packages**: Sets `NIXPKGS_ALLOW_INSECURE=1`
- **Broken packages**: Sets `NIXPKGS_ALLOW_BROKEN=1`
Auto-retry requires that `--impure` is not explicitly disabled for the relevant
command in the config file. By default retries are automatic. See
[Configuration](#configuration).
### Hash Auto-Fix
When a hash mismatch is detected in the underlying `nix build`, `eh` can
@ -55,6 +59,92 @@ nb .#myPackage # nix build .#myPackage
nu # nix flake update
```
## Configuration
`eh` reads configuration from the first `.eh.toml` found by walking up from the
current directory, falling back to `~/.config/eh/config.toml`. If no file
exists, all defaults apply and no extra flags are passed to Nix.
### Global settings
Top-level keys apply to every command unless overridden per-command:
```toml
# Explicitly enable --impure for all commands (also passes it on initial run).
impure = true
# Explicitly disable impure retries for all commands.
impure = false
```
When `impure` is absent (the default), auto-retry with `--impure` is
**automatic** — `eh` will add `--impure` and the appropriate `NIXPKGS_ALLOW_*`
variable whenever it detects an unfree, insecure, or broken package.
<!--markdownlint-disable MD013-->
| Key | Type | Default | Description |
| -------- | ---- | ------- | -------------------------------------------------------------- |
| `impure` | bool | - | `true` passes `--impure` always; `false` blocks impure retries |
<!--markdownlint-enable MD013-->
### Per-command settings
Each command can be configured independently under `[commands.<name>]`. A
per-command setting takes precedence over the global one; the global setting
applies to commands that do not have their own entry.
```toml
[commands.build]
impure = true
env = { NIXPKGS_ALLOW_UNFREE = "1" }
[commands.develop]
impure = false
[commands.develop.env]
MY_DEV_VAR = "1"
```
<!--markdownlint-disable MD013-->
| Key | Type | Default | Description |
| -------- | ----- | ------- | ------------------------------------------------------------------------------- |
| `impure` | bool | - | `true` passes `--impure` always; `false` blocks impure retries for this command |
| `env` | table | `{}` | Extra environment variables to set for the command |
<!--markdownlint-enable MD013-->
### Impure mode and unfree/insecure/broken packages
When `eh` detects that a package requires `--impure` (unfree, insecure, or
broken), it retries automatically with the appropriate `NIXPKGS_ALLOW_*`
variable and `--impure` by default.
If `impure = false` is set for the active command (or globally), the retry is
blocked and an error is shown instead:
```plaintext
! package has an unfree license but `--impure` is disabled for `build` in config
~ set `impure = true` for this command (or globally) in .eh.toml or
~/.config/eh/config.toml, or pass `--impure` manually
```
To explicitly enable `--impure` for a specific command (also adds it to the
initial run, not just retries):
```toml
[commands.build]
impure = true
```
To disable impure retries globally:
```toml
impure = false
```
## License
<!--markdownlint-disable MD059-->