pyrox.dev
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/)
4configuration including completion scripts for several CLI tools or custom
5prompt themes.
6
7## Basic usage {#module-programs-oh-my-zsh-usage}
8
9The module uses the `oh-my-zsh` package with all available
10features. The initial setup using Nix expressions is fairly similar to the
11configuration format of `oh-my-zsh`.
12```
13{
14 programs.zsh.ohMyZsh = {
15 enable = true;
16 plugins = [ "git" "python" "man" ];
17 theme = "agnoster";
18 };
19}
20```
21For a detailed explanation of these arguments please refer to the
22[`oh-my-zsh` docs](https://github.com/robbyrussell/oh-my-zsh/wiki).
23
24The expression generates the needed configuration and writes it into your
25`/etc/zshrc`.
26
27## Custom additions {#module-programs-oh-my-zsh-additions}
28
29Sometimes third-party or custom scripts such as a modified theme may be
30needed. `oh-my-zsh` provides the
31[`ZSH_CUSTOM`](https://github.com/robbyrussell/oh-my-zsh/wiki/Customization#overriding-internals)
32environment variable for this which points to a directory with additional
33scripts.
34
35The module can do this as well:
36```
37{
38 programs.zsh.ohMyZsh.custom = "~/path/to/custom/scripts";
39}
40```
41
42## Custom environments {#module-programs-oh-my-zsh-environments}
43
44There 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)
47which bundles completion scripts and a plugin for `oh-my-zsh`.
48
49Rather than using a single mutable path for `ZSH_CUSTOM`,
50it's also possible to generate this path from a list of Nix packages:
51```
52{ pkgs, ... }:
53{
54 programs.zsh.ohMyZsh.customPkgs = [
55 pkgs.nix-zsh-completions
56 # and even more...
57 ];
58}
59```
60Internally 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)
63for further reference.
64
65*Please keep in mind that this is not compatible with
66`programs.zsh.ohMyZsh.custom` as it requires an immutable
67store path while `custom` shall remain mutable! An
68evaluation 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
73If 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
91A derivation for `oh-my-zsh` may look like this:
92```
93{ stdenv, fetchFromGitHub }:
94
95stdenv.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```