nixos/modules/programs/zsh/oh-my-zsh.md

   1 # Oh my ZSH {#module-programs-zsh-ohmyzsh}
   2
   3 [`oh-my-zsh`](https://ohmyz.sh/) is a framework to manage your [ZSH](https://www.zsh.org/)
   4 configuration including completion scripts for several CLI tools or custom
   5 prompt themes.
   6
   7 ## Basic usage {#module-programs-oh-my-zsh-usage}
   8
   9 The module uses the `oh-my-zsh` package with all available
  10 features. The initial setup using Nix expressions is fairly similar to the
  11 configuration format of `oh-my-zsh`.
  12 ```nix
  13 {
  14   programs.zsh.ohMyZsh = {
  15     enable = true;
  16     plugins = [ "git" "python" "man" ];
  17     theme = "agnoster";
  18   };
  19 }
  20 ```
  21 For a detailed explanation of these arguments please refer to the
  22 [`oh-my-zsh` docs](https://github.com/robbyrussell/oh-my-zsh/wiki).
  23
  24 The expression generates the needed configuration and writes it into your
  25 `/etc/zshrc`.
  26
  27 ## Custom additions {#module-programs-oh-my-zsh-additions}
  28
  29 Sometimes third-party or custom scripts such as a modified theme may be
  30 needed. `oh-my-zsh` provides the
  31 [`ZSH_CUSTOM`](https://github.com/robbyrussell/oh-my-zsh/wiki/Customization#overriding-internals)
  32 environment variable for this which points to a directory with additional
  33 scripts.
  34
  35 The module can do this as well:
  36 ```nix
  37 {
  38   programs.zsh.ohMyZsh.custom = "~/path/to/custom/scripts";
  39 }
  40 ```
  41
  42 ## Custom environments {#module-programs-oh-my-zsh-environments}
  43
  44 There are several extensions for `oh-my-zsh` packaged in
  45 `nixpkgs`. One of them is
  46 [nix-zsh-completions](https://github.com/spwhitt/nix-zsh-completions)
  47 which bundles completion scripts and a plugin for `oh-my-zsh`.
  48
  49 Rather than using a single mutable path for `ZSH_CUSTOM`,
  50 it's also possible to generate this path from a list of Nix packages:
  51 ```nix
  52 { pkgs, ... }:
  53 {
  54   programs.zsh.ohMyZsh.customPkgs = [
  55     pkgs.nix-zsh-completions
  56     # and even more...
  57   ];
  58 }
  59 ```
  60 Internally a single store path will be created using
  61 `buildEnv`. Please refer to the docs of
  62 [`buildEnv`](https://nixos.org/nixpkgs/manual/#sec-building-environment)
  63 for further reference.
  64
  65 *Please keep in mind that this is not compatible with
  66 `programs.zsh.ohMyZsh.custom` as it requires an immutable
  67 store path while `custom` shall remain mutable! An
  68 evaluation failure will be thrown if both `custom` and
  69 `customPkgs` are set.*
  70
  71 ## Package your own customizations {#module-programs-oh-my-zsh-packaging-customizations}
  72
  73 If third-party customizations (e.g. new themes) are supposed to be added to
  74 `oh-my-zsh` there are several pitfalls to keep in mind:
  75
  76   - To comply with the default structure of `ZSH` the entire
  77     output needs to be written to `$out/share/zsh.`
  78
  79   - Completion scripts are supposed to be stored at
  80     `$out/share/zsh/site-functions`. This directory is part of the
  81     [`fpath`](https://zsh.sourceforge.io/Doc/Release/Functions.html)
  82     and the package should be compatible with pure `ZSH`
  83     setups. The module will automatically link the contents of
  84     `site-functions` to completions directory in the proper
  85     store path.
  86
  87   - The `plugins` directory needs the structure
  88     `pluginname/pluginname.plugin.zsh` as structured in the
  89     [upstream repo.](https://github.com/robbyrussell/oh-my-zsh/tree/91b771914bc7c43dd7c7a43b586c5de2c225ceb7/plugins)
  90
  91 A derivation for `oh-my-zsh` may look like this:
  92 ```nix
  93 { stdenv, fetchFromGitHub }:
  94
  95 stdenv.mkDerivation rec {
  96   name = "exemplary-zsh-customization-${version}";
  97   version = "1.0.0";
  98   src = fetchFromGitHub {
  99     # path to the upstream repository
 100   };
 101
 102   dontBuild = true;
 103   installPhase = ''
 104     mkdir -p $out/share/zsh/site-functions
 105     cp {themes,plugins} $out/share/zsh
 106     cp completions $out/share/zsh/site-functions
 107   '';
 108 }
 109 ```