doc/packages/fish.section.md

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