mirror of
https://github.com/astro/deadnix.git
synced 2024-11-28 10:13:34 +03:00
136 lines
4.2 KiB
Markdown
136 lines
4.2 KiB
Markdown
# deadnix
|
|
|
|
Scan `.nix` files for dead code (unused variable bindings).
|
|
|
|
## Usage with Github Actions
|
|
|
|
See [deadnix-action](https://github.com/astro/deadnix-action)
|
|
|
|
|
|
## Usage with Nix Flakes
|
|
|
|
### Help
|
|
|
|
```console
|
|
$ nix run github:astro/deadnix -- --help
|
|
Find dead code in .nix files
|
|
|
|
Usage: deadnix [OPTIONS] [FILE_PATHS]...
|
|
|
|
Arguments:
|
|
[FILE_PATHS]... .nix files, or directories with .nix files inside [default: .]
|
|
|
|
Options:
|
|
-l, --no-lambda-arg Don't check lambda parameter arguments
|
|
-L, --no-lambda-pattern-names Don't check lambda attrset pattern names (don't break nixpkgs callPackage)
|
|
-_, --no-underscore Don't check any bindings that start with a _
|
|
-q, --quiet Don't print dead code report
|
|
-e, --edit Remove unused code and write to source file
|
|
-h, --hidden Recurse into hidden subdirectories and process hidden .*.nix files
|
|
--help
|
|
-f, --fail Exit with 1 if unused code has been found
|
|
-o, --output-format <OUTPUT_FORMAT> Output format to use [default: human-readable] [possible values: human-readable, json]
|
|
--exclude <EXCLUDES>... Files to exclude from analysis
|
|
-V, --version Print version
|
|
```
|
|
|
|
Reports contain ANSI color escape codes unless the
|
|
[`$NO_COLOR`](https://no-color.org/) environment variable is set.
|
|
|
|
The `--exclude` parameter accepts multiple paths. Separate them with
|
|
`--` to pass `[FILE_PATHS]...`.
|
|
|
|
### Scan for unused code
|
|
|
|
```console
|
|
$ nix run github:astro/deadnix example.nix
|
|
Warning: Unused declarations were found.
|
|
╭─[example.nix:1:1]
|
|
1 │unusedArgs@{ unusedArg, usedArg, ... }:
|
|
· │ ╰───── Unused lambda pattern: unusedArg
|
|
· ╰───────────────── Unused lambda pattern: unusedArgs
|
|
3 │ inherit (builtins) unused_inherit;
|
|
· ╰─────── Unused let binding: unused_inherit
|
|
5 │ unused = "fnord";
|
|
· ╰─── Unused let binding: unused
|
|
10 │ shadowed = 42;
|
|
· ╰──── Unused let binding: shadowed
|
|
11 │ _unused = unused: false;
|
|
· │ ╰─── Unused lambda argument: unused
|
|
· ╰───────────── Unused let binding: _unused
|
|
13 │ x = { unusedArg2, x ? args.y, ... }@args: used1 + x;
|
|
· ╰───── Unused lambda pattern: unusedArg2
|
|
```
|
|
|
|
|
|
### Remove unused code automatically
|
|
|
|
**Do commit** your changes into version control **before!**
|
|
|
|
```console
|
|
$ nix run github:astro/deadnix -- -eq test.nix
|
|
```
|
|
|
|
## Usage with [pre-commit](https://pre-commit.com/)
|
|
|
|
Add the following to your project's `.pre-commit-config.yaml`:
|
|
```yaml
|
|
repos:
|
|
- repo: https://github.com/astro/deadnix
|
|
rev: ID # frozen: VERSION
|
|
hooks:
|
|
- id: deadnix
|
|
#args: [--edit] # Uncomment to automatically modify files
|
|
stages: [commit]
|
|
```
|
|
|
|
Replace `ID` and `VERSION` above with the relevant version tag and
|
|
commit ID for reference, for example:
|
|
|
|
```yaml
|
|
rev: da39a3ee5e6b4b0d3255bfef95601890afd80709 # frozen: v1.2.3
|
|
```
|
|
|
|
## Behavior
|
|
|
|
### Renaming of all unused to lambda args to start with `_`
|
|
|
|
If you disfavor marking them as unused, use option
|
|
`-l`/`--no-lambda-arg`.
|
|
|
|
|
|
### nixpkgs `callPackages` with multiple imports
|
|
|
|
`callPackages` guesses the packages to inject by the names of a
|
|
packages' lambda attrset pattern names. Some packages alias these with
|
|
`@args` to pass them to another `import ...nix args`.
|
|
|
|
As the used args are only named in the imported file they will be
|
|
recognized as dead in the package source file that is imported by
|
|
`callPackage`, rendering it unable to guess the dependencies to call
|
|
the packages with.
|
|
|
|
Use option `-L`/`--no-lambda-pattern-names` in this case.
|
|
|
|
|
|
### Skipping reports for certain declarations
|
|
|
|
As of 1.1.0 deadnix supports the following pragma to skip check of
|
|
bindings in the following line:
|
|
|
|
```nix
|
|
# deadnix: skip
|
|
```
|
|
|
|
|
|
## What if the produced reports are wrong?
|
|
|
|
Please open an issue. Do not forget to include the `.nix` code that
|
|
produces incorrect results.
|
|
|
|
|
|
## Commercial Support
|
|
|
|
The author can be hired to implement the features that you wish, or to
|
|
integrate this tool into your toolchain.
|