commit f60e9eac857bbc020c6f4c263f558c6ded8965f8 · pyrox.dev/nixpkgs

+109

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

···

       1
       1
       +
       # Oh my ZSH {#module-programs-zsh-ohmyzsh}

     

       2
       2
       +
       

     

       3
       3
       +
       [`oh-my-zsh`](https://ohmyz.sh/) is a framework to manage your [ZSH](https://www.zsh.org/)

     

       4
       4
       +
       configuration including completion scripts for several CLI tools or custom

     

       5
       5
       +
       prompt themes.

     

       6
       6
       +
       

     

       7
       7
       +
       ## Basic usage {#module-programs-oh-my-zsh-usage}

     

       8
       8
       +
       

     

       9
       9
       +
       The module uses the `oh-my-zsh` package with all available

     

       10
       10
       +
       features. The initial setup using Nix expressions is fairly similar to the

     

       11
       11
       +
       configuration format of `oh-my-zsh`.

     

       12
       12
       +
       ```

     

       13
       13
       +
       {

     

       14
       14
       +
         programs.zsh.ohMyZsh = {

     

       15
       15
       +
           enable = true;

     

       16
       16
       +
           plugins = [ "git" "python" "man" ];

     

       17
       17
       +
           theme = "agnoster";

     

       18
       18
       +
         };

     

       19
       19
       +
       }

     

       20
       20
       +
       ```

     

       21
       21
       +
       For a detailed explanation of these arguments please refer to the

     

       22
       22
       +
       [`oh-my-zsh` docs](https://github.com/robbyrussell/oh-my-zsh/wiki).

     

       23
       23
       +
       

     

       24
       24
       +
       The expression generates the needed configuration and writes it into your

     

       25
       25
       +
       `/etc/zshrc`.

     

       26
       26
       +
       

     

       27
       27
       +
       ## Custom additions {#module-programs-oh-my-zsh-additions}

     

       28
       28
       +
       

     

       29
       29
       +
       Sometimes third-party or custom scripts such as a modified theme may be

     

       30
       30
       +
       needed. `oh-my-zsh` provides the

     

       31
       31
       +
       [`ZSH_CUSTOM`](https://github.com/robbyrussell/oh-my-zsh/wiki/Customization#overriding-internals)

     

       32
       32
       +
       environment variable for this which points to a directory with additional

     

       33
       33
       +
       scripts.

     

       34
       34
       +
       

     

       35
       35
       +
       The module can do this as well:

     

       36
       36
       +
       ```

     

       37
       37
       +
       {

     

       38
       38
       +
         programs.zsh.ohMyZsh.custom = "~/path/to/custom/scripts";

     

       39
       39
       +
       }

     

       40
       40
       +
       ```

     

       41
       41
       +
       

     

       42
       42
       +
       ## Custom environments {#module-programs-oh-my-zsh-environments}

     

       43
       43
       +
       

     

       44
       44
       +
       There are several extensions for `oh-my-zsh` packaged in

     

       45
       45
       +
       `nixpkgs`. One of them is

     

       46
       46
       +
       [nix-zsh-completions](https://github.com/spwhitt/nix-zsh-completions)

     

       47
       47
       +
       which bundles completion scripts and a plugin for `oh-my-zsh`.

     

       48
       48
       +
       

     

       49
       49
       +
       Rather than using a single mutable path for `ZSH_CUSTOM`,

     

       50
       50
       +
       it's also possible to generate this path from a list of Nix packages:

     

       51
       51
       +
       ```

     

       52
       52
       +
       { pkgs, ... }:

     

       53
       53
       +
       {

     

       54
       54
       +
         programs.zsh.ohMyZsh.customPkgs = [

     

       55
       55
       +
           pkgs.nix-zsh-completions

     

       56
       56
       +
           # and even more...

     

       57
       57
       +
         ];

     

       58
       58
       +
       }

     

       59
       59
       +
       ```

     

       60
       60
       +
       Internally a single store path will be created using

     

       61
       61
       +
       `buildEnv`. Please refer to the docs of

     

       62
       62
       +
       [`buildEnv`](https://nixos.org/nixpkgs/manual/#sec-building-environment)

     

       63
       63
       +
       for further reference.

     

       64
       64
       +
       

     

       65
       65
       +
       *Please keep in mind that this is not compatible with

     

       66
       66
       +
       `programs.zsh.ohMyZsh.custom` as it requires an immutable

     

       67
       67
       +
       store path while `custom` shall remain mutable! An

     

       68
       68
       +
       evaluation failure will be thrown if both `custom` and

     

       69
       69
       +
       `customPkgs` are set.*

     

       70
       70
       +
       

     

       71
       71
       +
       ## Package your own customizations {#module-programs-oh-my-zsh-packaging-customizations}

     

       72
       72
       +
       

     

       73
       73
       +
       If third-party customizations (e.g. new themes) are supposed to be added to

     

       74
       74
       +
       `oh-my-zsh` there are several pitfalls to keep in mind:

     

       75
       75
       +
       

     

       76
       76
       +
         - To comply with the default structure of `ZSH` the entire

     

       77
       77
       +
           output needs to be written to `$out/share/zsh.`

     

       78
       78
       +
       

     

       79
       79
       +
         - Completion scripts are supposed to be stored at

     

       80
       80
       +
           `$out/share/zsh/site-functions`. This directory is part of the

     

       81
       81
       +
           [`fpath`](http://zsh.sourceforge.net/Doc/Release/Functions.html)

     

       82
       82
       +
           and the package should be compatible with pure `ZSH`

     

       83
       83
       +
           setups. The module will automatically link the contents of

     

       84
       84
       +
           `site-functions` to completions directory in the proper

     

       85
       85
       +
           store path.

     

       86
       86
       +
       

     

       87
       87
       +
         - The `plugins` directory needs the structure

     

       88
       88
       +
           `pluginname/pluginname.plugin.zsh` as structured in the

     

       89
       89
       +
           [upstream repo.](https://github.com/robbyrussell/oh-my-zsh/tree/91b771914bc7c43dd7c7a43b586c5de2c225ceb7/plugins)

     

       90
       90
       +
       

     

       91
       91
       +
       A derivation for `oh-my-zsh` may look like this:

     

       92
       92
       +
       ```

     

       93
       93
       +
       { stdenv, fetchFromGitHub }:

     

       94
       94
       +
       

     

       95
       95
       +
       stdenv.mkDerivation rec {

     

       96
       96
       +
         name = "exemplary-zsh-customization-${version}";

     

       97
       97
       +
         version = "1.0.0";

     

       98
       98
       +
         src = fetchFromGitHub {

     

       99
       99
       +
           # path to the upstream repository

     

       100
       100
       +
         };

     

       101
       101
       +
       

     

       102
       102
       +
         dontBuild = true;

     

       103
       103
       +
         installPhase = ''

     

       104
       104
       +
           mkdir -p $out/share/zsh/site-functions

     

       105
       105
       +
           cp {themes,plugins} $out/share/zsh

     

       106
       106
       +
           cp completions $out/share/zsh/site-functions

     

       107
       107
       +
         '';

     

       108
       108
       +
       }

     

       109
       109
       +
       ```

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

···

       142
       142
        
       

     

       143
       143
        
           };

     

       144
       144
        
       

     

       145
       145
       +
           # Don't edit the docbook xml directly, edit the md and generate it:

     

       146
       146
       +
           # `pandoc oh-my-zsh.md -t docbook --top-level-division=chapter --extract-media=media -f markdown-smart --lua-filter ../../../../doc/build-aux/pandoc-filters/myst-reader/roles.lua --lua-filter ../../../../doc/build-aux/pandoc-filters/docbook-writer/rst-roles.lua > oh-my-zsh.xml`

     

       145
       147
        
           meta.doc = ./oh-my-zsh.xml;

     

       146
       148
        
         }

+112 -115

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

···

       1
       1
       -
       <chapter xmlns="http://docbook.org/ns/docbook"

     

       2
       2
       -
                xmlns:xlink="http://www.w3.org/1999/xlink"

     

       3
       3
       -
                xmlns:xi="http://www.w3.org/2001/XInclude"

     

       4
       4
       -
                version="5.0"

     

       5
       5
       -
                xml:id="module-programs-zsh-ohmyzsh">

     

       6
       6
       -
        <title>Oh my ZSH</title>

     

       7
       7
       -
        <para>

     

       8
       8
       -
         <link xlink:href="https://ohmyz.sh/"><literal>oh-my-zsh</literal></link> is a

     

       9
       9
       -
         framework to manage your <link xlink:href="https://www.zsh.org/">ZSH</link>

     

       10
       10
       -
         configuration including completion scripts for several CLI tools or custom

     

       11
       11
       -
         prompt themes.

     

       12
       12
       -
        </para>

     

       13
       13
       -
        <section xml:id="module-programs-oh-my-zsh-usage">

     

       14
       14
       -
         <title>Basic usage</title>

     

       15
       15
       -
       

     

       1
       1
       +
       <chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="module-programs-zsh-ohmyzsh">

     

       2
       2
       +
         <title>Oh my ZSH</title>

     

       16
       3
        
         <para>

     

       17
       17
       -
          The module uses the <literal>oh-my-zsh</literal> package with all available

     

       18
       18
       -
          features. The initial setup using Nix expressions is fairly similar to the

     

       19
       19
       -
          configuration format of <literal>oh-my-zsh</literal>.

     

       20
       20
       -
       <programlisting>

     

       4
       4
       +
           <link xlink:href="https://ohmyz.sh/"><literal>oh-my-zsh</literal></link>

     

       5
       5
       +
           is a framework to manage your

     

       6
       6
       +
           <link xlink:href="https://www.zsh.org/">ZSH</link> configuration

     

       7
       7
       +
           including completion scripts for several CLI tools or custom prompt

     

       8
       8
       +
           themes.

     

       9
       9
       +
         </para>

     

       10
       10
       +
         <section xml:id="module-programs-oh-my-zsh-usage">

     

       11
       11
       +
           <title>Basic usage</title>

     

       12
       12
       +
           <para>

     

       13
       13
       +
             The module uses the <literal>oh-my-zsh</literal> package with all

     

       14
       14
       +
             available features. The initial setup using Nix expressions is

     

       15
       15
       +
             fairly similar to the configuration format of

     

       16
       16
       +
             <literal>oh-my-zsh</literal>.

     

       17
       17
       +
           </para>

     

       18
       18
       +
           <programlisting>

     

       21
       19
        
       {

     

       22
       20
        
         programs.zsh.ohMyZsh = {

     

       23
       21
        
           enable = true;

     

       24
       24
       -
           plugins = [ "git" "python" "man" ];

     

       25
       25
       -
           theme = "agnoster";

     

       22
       22
       +
           plugins = [ &quot;git&quot; &quot;python&quot; &quot;man&quot; ];

     

       23
       23
       +
           theme = &quot;agnoster&quot;;

     

       26
       24
        
         };

     

       27
       25
        
       }

     

       28
       26
        
       </programlisting>

     

       29
       29
       -
          For a detailed explanation of these arguments please refer to the

     

       30
       30
       -
          <link xlink:href="https://github.com/robbyrussell/oh-my-zsh/wiki"><literal>oh-my-zsh</literal>

     

       31
       31
       -
          docs</link>.

     

       32
       32
       -
         </para>

     

       33
       33
       -
       

     

       34
       34
       -
         <para>

     

       35
       35
       -
          The expression generates the needed configuration and writes it into your

     

       36
       36
       -
          <literal>/etc/zshrc</literal>.

     

       37
       37
       -
         </para>

     

       38
       38
       -
        </section>

     

       39
       39
       -
        <section xml:id="module-programs-oh-my-zsh-additions">

     

       40
       40
       -
         <title>Custom additions</title>

     

       41
       41
       -
       

     

       42
       42
       -
         <para>

     

       43
       43
       -
          Sometimes third-party or custom scripts such as a modified theme may be

     

       44
       44
       -
          needed. <literal>oh-my-zsh</literal> provides the

     

       45
       45
       -
          <link xlink:href="https://github.com/robbyrussell/oh-my-zsh/wiki/Customization#overriding-internals"><literal>ZSH_CUSTOM</literal></link>

     

       46
       46
       -
          environment variable for this which points to a directory with additional

     

       47
       47
       -
          scripts.

     

       48
       48
       -
         </para>

     

       49
       49
       -
       

     

       50
       50
       -
         <para>

     

       51
       51
       -
          The module can do this as well:

     

       52
       52
       -
       <programlisting>

     

       27
       27
       +
           <para>

     

       28
       28
       +
             For a detailed explanation of these arguments please refer to the

     

       29
       29
       +
             <link xlink:href="https://github.com/robbyrussell/oh-my-zsh/wiki"><literal>oh-my-zsh</literal>

     

       30
       30
       +
             docs</link>.

     

       31
       31
       +
           </para>

     

       32
       32
       +
           <para>

     

       33
       33
       +
             The expression generates the needed configuration and writes it

     

       34
       34
       +
             into your <literal>/etc/zshrc</literal>.

     

       35
       35
       +
           </para>

     

       36
       36
       +
         </section>

     

       37
       37
       +
         <section xml:id="module-programs-oh-my-zsh-additions">

     

       38
       38
       +
           <title>Custom additions</title>

     

       39
       39
       +
           <para>

     

       40
       40
       +
             Sometimes third-party or custom scripts such as a modified theme

     

       41
       41
       +
             may be needed. <literal>oh-my-zsh</literal> provides the

     

       42
       42
       +
             <link xlink:href="https://github.com/robbyrussell/oh-my-zsh/wiki/Customization#overriding-internals"><literal>ZSH_CUSTOM</literal></link>

     

       43
       43
       +
             environment variable for this which points to a directory with

     

       44
       44
       +
             additional scripts.

     

       45
       45
       +
           </para>

     

       46
       46
       +
           <para>

     

       47
       47
       +
             The module can do this as well:

     

       48
       48
       +
           </para>

     

       49
       49
       +
           <programlisting>

     

       53
       50
        
       {

     

       54
       54
       -
         programs.zsh.ohMyZsh.custom = "~/path/to/custom/scripts";

     

       51
       51
       +
         programs.zsh.ohMyZsh.custom = &quot;~/path/to/custom/scripts&quot;;

     

       55
       52
        
       }

     

       56
       53
        
       </programlisting>

     

       57
       57
       -
         </para>

     

       58
       58
       -
        </section>

     

       59
       59
       -
        <section xml:id="module-programs-oh-my-zsh-environments">

     

       60
       60
       -
         <title>Custom environments</title>

     

       61
       61
       -
       

     

       62
       62
       -
         <para>

     

       63
       63
       -
          There are several extensions for <literal>oh-my-zsh</literal> packaged in

     

       64
       64
       -
          <literal>nixpkgs</literal>. One of them is

     

       65
       65
       -
          <link xlink:href="https://github.com/spwhitt/nix-zsh-completions">nix-zsh-completions</link>

     

       66
       66
       -
          which bundles completion scripts and a plugin for

     

       67
       67
       -
          <literal>oh-my-zsh</literal>.

     

       68
       68
       -
         </para>

     

       69
       69
       -
       

     

       70
       70
       -
         <para>

     

       71
       71
       -
          Rather than using a single mutable path for <literal>ZSH_CUSTOM</literal>,

     

       72
       72
       -
          it's also possible to generate this path from a list of Nix packages:

     

       73
       73
       -
       <programlisting>

     

       54
       54
       +
         </section>

     

       55
       55
       +
         <section xml:id="module-programs-oh-my-zsh-environments">

     

       56
       56
       +
           <title>Custom environments</title>

     

       57
       57
       +
           <para>

     

       58
       58
       +
             There are several extensions for <literal>oh-my-zsh</literal>

     

       59
       59
       +
             packaged in <literal>nixpkgs</literal>. One of them is

     

       60
       60
       +
             <link xlink:href="https://github.com/spwhitt/nix-zsh-completions">nix-zsh-completions</link>

     

       61
       61
       +
             which bundles completion scripts and a plugin for

     

       62
       62
       +
             <literal>oh-my-zsh</literal>.

     

       63
       63
       +
           </para>

     

       64
       64
       +
           <para>

     

       65
       65
       +
             Rather than using a single mutable path for

     

       66
       66
       +
             <literal>ZSH_CUSTOM</literal>, it's also possible to generate this

     

       67
       67
       +
             path from a list of Nix packages:

     

       68
       68
       +
           </para>

     

       69
       69
       +
           <programlisting>

     

       74
       70
        
       { pkgs, ... }:

     

       75
       71
        
       {

     

       76
       72
        
         programs.zsh.ohMyZsh.customPkgs = [

     
···

       79
       75
        
         ];

     

       80
       76
        
       }

     

       81
       77
        
       </programlisting>

     

       82
       82
       -
          Internally a single store path will be created using

     

       83
       83
       -
          <literal>buildEnv</literal>. Please refer to the docs of

     

       84
       84
       -
          <link xlink:href="https://nixos.org/nixpkgs/manual/#sec-building-environment"><literal>buildEnv</literal></link>

     

       85
       85
       -
          for further reference.

     

       86
       86
       -
         </para>

     

       87
       87
       -
       

     

       88
       88
       -
         <para>

     

       89
       89
       -
          <emphasis>Please keep in mind that this is not compatible with

     

       90
       90
       -
          <literal>programs.zsh.ohMyZsh.custom</literal> as it requires an immutable

     

       91
       91
       -
          store path while <literal>custom</literal> shall remain mutable! An

     

       92
       92
       -
          evaluation failure will be thrown if both <literal>custom</literal> and

     

       93
       93
       -
          <literal>customPkgs</literal> are set.</emphasis>

     

       94
       94
       -
         </para>

     

       95
       95
       -
        </section>

     

       96
       96
       -
        <section xml:id="module-programs-oh-my-zsh-packaging-customizations">

     

       97
       97
       -
         <title>Package your own customizations</title>

     

       98
       98
       -
       

     

       99
       99
       -
         <para>

     

       100
       100
       -
          If third-party customizations (e.g. new themes) are supposed to be added to

     

       101
       101
       -
          <literal>oh-my-zsh</literal> there are several pitfalls to keep in mind:

     

       102
       102
       -
         </para>

     

       103
       103
       -
       

     

       104
       104
       -
         <itemizedlist>

     

       105
       105
       -
          <listitem>

     

       78
       78
       +
           <para>

     

       79
       79
       +
             Internally a single store path will be created using

     

       80
       80
       +
             <literal>buildEnv</literal>. Please refer to the docs of

     

       81
       81
       +
             <link xlink:href="https://nixos.org/nixpkgs/manual/#sec-building-environment"><literal>buildEnv</literal></link>

     

       82
       82
       +
             for further reference.

     

       83
       83
       +
           </para>

     

       106
       84
        
           <para>

     

       107
       107
       -
            To comply with the default structure of <literal>ZSH</literal> the entire

     

       108
       108
       -
            output needs to be written to <literal>$out/share/zsh.</literal>

     

       85
       85
       +
             <emphasis>Please keep in mind that this is not compatible with

     

       86
       86
       +
             <literal>programs.zsh.ohMyZsh.custom</literal> as it requires an

     

       87
       87
       +
             immutable store path while <literal>custom</literal> shall remain

     

       88
       88
       +
             mutable! An evaluation failure will be thrown if both

     

       89
       89
       +
             <literal>custom</literal> and <literal>customPkgs</literal> are

     

       90
       90
       +
             set.</emphasis>

     

       109
       91
        
           </para>

     

       110
       110
       -
          </listitem>

     

       111
       111
       -
          <listitem>

     

       92
       92
       +
         </section>

     

       93
       93
       +
         <section xml:id="module-programs-oh-my-zsh-packaging-customizations">

     

       94
       94
       +
           <title>Package your own customizations</title>

     

       112
       95
        
           <para>

     

       113
       113
       -
            Completion scripts are supposed to be stored at

     

       114
       114
       -
            <literal>$out/share/zsh/site-functions</literal>. This directory is part

     

       115
       115
       -
            of the

     

       116
       116
       -
            <link xlink:href="http://zsh.sourceforge.net/Doc/Release/Functions.html"><literal>fpath</literal></link>

     

       117
       117
       -
            and the package should be compatible with pure <literal>ZSH</literal>

     

       118
       118
       -
            setups. The module will automatically link the contents of

     

       119
       119
       -
            <literal>site-functions</literal> to completions directory in the proper

     

       120
       120
       -
            store path.

     

       96
       96
       +
             If third-party customizations (e.g. new themes) are supposed to be

     

       97
       97
       +
             added to <literal>oh-my-zsh</literal> there are several pitfalls

     

       98
       98
       +
             to keep in mind:

     

       121
       99
        
           </para>

     

       122
       122
       -
          </listitem>

     

       123
       123
       -
          <listitem>

     

       100
       100
       +
           <itemizedlist>

     

       101
       101
       +
             <listitem>

     

       102
       102
       +
               <para>

     

       103
       103
       +
                 To comply with the default structure of <literal>ZSH</literal>

     

       104
       104
       +
                 the entire output needs to be written to

     

       105
       105
       +
                 <literal>$out/share/zsh.</literal>

     

       106
       106
       +
               </para>

     

       107
       107
       +
             </listitem>

     

       108
       108
       +
             <listitem>

     

       109
       109
       +
               <para>

     

       110
       110
       +
                 Completion scripts are supposed to be stored at

     

       111
       111
       +
                 <literal>$out/share/zsh/site-functions</literal>. This

     

       112
       112
       +
                 directory is part of the

     

       113
       113
       +
                 <link xlink:href="http://zsh.sourceforge.net/Doc/Release/Functions.html"><literal>fpath</literal></link>

     

       114
       114
       +
                 and the package should be compatible with pure

     

       115
       115
       +
                 <literal>ZSH</literal> setups. The module will automatically

     

       116
       116
       +
                 link the contents of <literal>site-functions</literal> to

     

       117
       117
       +
                 completions directory in the proper store path.

     

       118
       118
       +
               </para>

     

       119
       119
       +
             </listitem>

     

       120
       120
       +
             <listitem>

     

       121
       121
       +
               <para>

     

       122
       122
       +
                 The <literal>plugins</literal> directory needs the structure

     

       123
       123
       +
                 <literal>pluginname/pluginname.plugin.zsh</literal> as

     

       124
       124
       +
                 structured in the

     

       125
       125
       +
                 <link xlink:href="https://github.com/robbyrussell/oh-my-zsh/tree/91b771914bc7c43dd7c7a43b586c5de2c225ceb7/plugins">upstream

     

       126
       126
       +
                 repo.</link>

     

       127
       127
       +
               </para>

     

       128
       128
       +
             </listitem>

     

       129
       129
       +
           </itemizedlist>

     

       124
       130
        
           <para>

     

       125
       125
       -
            The <literal>plugins</literal> directory needs the structure

     

       126
       126
       -
            <literal>pluginname/pluginname.plugin.zsh</literal> as structured in the

     

       127
       127
       -
            <link xlink:href="https://github.com/robbyrussell/oh-my-zsh/tree/91b771914bc7c43dd7c7a43b586c5de2c225ceb7/plugins">upstream

     

       128
       128
       -
            repo.</link>

     

       131
       131
       +
             A derivation for <literal>oh-my-zsh</literal> may look like this:

     

       129
       132
        
           </para>

     

       130
       130
       -
          </listitem>

     

       131
       131
       -
         </itemizedlist>

     

       132
       132
       -
       

     

       133
       133
       -
         <para>

     

       134
       134
       -
          A derivation for <literal>oh-my-zsh</literal> may look like this:

     

       135
       135
       -
       <programlisting>

     

       133
       133
       +
           <programlisting>

     

       136
       134
        
       { stdenv, fetchFromGitHub }:

     

       137
       135
        
       

     

       138
       136
        
       stdenv.mkDerivation rec {

     

       139
       139
       -
         name = "exemplary-zsh-customization-${version}";

     

       140
       140
       -
         version = "1.0.0";

     

       137
       137
       +
         name = &quot;exemplary-zsh-customization-${version}&quot;;

     

       138
       138
       +
         version = &quot;1.0.0&quot;;

     

       141
       139
        
         src = fetchFromGitHub {

     

       142
       140
        
           # path to the upstream repository

     

       143
       141
        
         };

     
···

       150
       148
        
         '';

     

       151
       149
        
       }

     

       152
       150
        
       </programlisting>

     

       153
       153
       -
         </para>

     

       154
       154
       -
        </section>

     

       151
       151
       +
         </section>

     

       155
       152
        
       </chapter>