pyrox.dev
1# Fish {#sec-fish}
2
3Fish is a "smart and user-friendly command line shell" with support for plugins.
4
5
6## Vendor Fish scripts {#sec-fish-vendor}
7
8Any package may ship its own Fish completions, configuration snippets, and
9functions. Those should be installed to
10`$out/share/fish/vendor_{completions,conf,functions}.d` respectively.
11
12When the `programs.fish.enable` and
13`programs.fish.vendor.{completions,config,functions}.enable` options from the
14NixOS Fish module are set to true, those paths are symlinked in the current
15system environment and are automatically loaded by Fish.
16
17
18## Packaging Fish plugins {#sec-fish-plugins-pkg}
19
20While packages providing standalone executables belong to the top level,
21packages which have the sole purpose of extending Fish belong to the
22`fishPlugins` scope and should be registered in
23`pkgs/shells/fish/plugins/default.nix`.
24
25The `buildFishPlugin` utility function can be used to automatically copy Fish
26scripts from `$src/{completions,conf,conf.d,functions}` to the standard vendor
27installation paths. It also sets up the test environment so that the optional
28`checkPhase` is executed in a Fish shell with other already packaged plugins
29and package-local Fish functions specified in `checkPlugins` and
30`checkFunctionDirs` respectively.
31
32See `pkgs/shells/fish/plugins/pure.nix` for an example of Fish plugin package
33using `buildFishPlugin` and running unit tests with the `fishtape` test runner.
34
35
36## Fish wrapper {#sec-fish-wrapper}
37
38The `wrapFish` package is a wrapper around Fish which can be used to create
39Fish shells initialized with some plugins as well as completions, configuration
40snippets and functions sourced from the given paths. This provides a convenient
41way to test Fish plugins and scripts without having to alter the environment.
42
43```nix
44wrapFish {
45 pluginPkgs = with fishPlugins; [
46 pure
47 foreign-env
48 ];
49 completionDirs = [ ];
50 functionDirs = [ ];
51 confDirs = [ "/path/to/some/fish/init/dir/" ];
52}
53```