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

<!-- Do not edit this file directly, edit its companion .md instead
     and regenerate this file using nixos/doc/manual/md-to-db.sh -->
<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="module-programs-zsh-ohmyzsh">
  <title>Oh my ZSH</title>
  <para>
    <link xlink:href="https://ohmyz.sh/"><literal>oh-my-zsh</literal></link>
    is a framework to manage your
    <link xlink:href="https://www.zsh.org/">ZSH</link> configuration
    including completion scripts for several CLI tools or custom prompt
    themes.
  </para>
  <section xml:id="module-programs-oh-my-zsh-usage">
    <title>Basic usage</title>
    <para>
      The module uses the <literal>oh-my-zsh</literal> package with all
      available features. The initial setup using Nix expressions is
      fairly similar to the configuration format of
      <literal>oh-my-zsh</literal>.
    </para>
    <programlisting>
{
  programs.zsh.ohMyZsh = {
    enable = true;
    plugins = [ &quot;git&quot; &quot;python&quot; &quot;man&quot; ];
    theme = &quot;agnoster&quot;;
  };
}
</programlisting>
    <para>
      For a detailed explanation of these arguments please refer to the
      <link xlink:href="https://github.com/robbyrussell/oh-my-zsh/wiki"><literal>oh-my-zsh</literal>
      docs</link>.
    </para>
    <para>
      The expression generates the needed configuration and writes it
      into your <literal>/etc/zshrc</literal>.
    </para>
  </section>
  <section xml:id="module-programs-oh-my-zsh-additions">
    <title>Custom additions</title>
    <para>
      Sometimes third-party or custom scripts such as a modified theme
      may be needed. <literal>oh-my-zsh</literal> provides the
      <link xlink:href="https://github.com/robbyrussell/oh-my-zsh/wiki/Customization#overriding-internals"><literal>ZSH_CUSTOM</literal></link>
      environment variable for this which points to a directory with
      additional scripts.
    </para>
    <para>
      The module can do this as well:
    </para>
    <programlisting>
{
  programs.zsh.ohMyZsh.custom = &quot;~/path/to/custom/scripts&quot;;
}
</programlisting>
  </section>
  <section xml:id="module-programs-oh-my-zsh-environments">
    <title>Custom environments</title>
    <para>
      There are several extensions for <literal>oh-my-zsh</literal>
      packaged in <literal>nixpkgs</literal>. One of them is
      <link xlink:href="https://github.com/spwhitt/nix-zsh-completions">nix-zsh-completions</link>
      which bundles completion scripts and a plugin for
      <literal>oh-my-zsh</literal>.
    </para>
    <para>
      Rather than using a single mutable path for
      <literal>ZSH_CUSTOM</literal>, it’s also possible to generate this
      path from a list of Nix packages:
    </para>
    <programlisting>
{ pkgs, ... }:
{
  programs.zsh.ohMyZsh.customPkgs = [
    pkgs.nix-zsh-completions
    # and even more...
  ];
}
</programlisting>
    <para>
      Internally a single store path will be created using
      <literal>buildEnv</literal>. Please refer to the docs of
      <link xlink:href="https://nixos.org/nixpkgs/manual/#sec-building-environment"><literal>buildEnv</literal></link>
      for further reference.
    </para>
    <para>
      <emphasis>Please keep in mind that this is not compatible with
      <literal>programs.zsh.ohMyZsh.custom</literal> as it requires an
      immutable store path while <literal>custom</literal> shall remain
      mutable! An evaluation failure will be thrown if both
      <literal>custom</literal> and <literal>customPkgs</literal> are
      set.</emphasis>
    </para>
  </section>
  <section xml:id="module-programs-oh-my-zsh-packaging-customizations">
    <title>Package your own customizations</title>
    <para>
      If third-party customizations (e.g. new themes) are supposed to be
      added to <literal>oh-my-zsh</literal> there are several pitfalls
      to keep in mind:
    </para>
    <itemizedlist>
      <listitem>
        <para>
          To comply with the default structure of <literal>ZSH</literal>
          the entire output needs to be written to
          <literal>$out/share/zsh.</literal>
        </para>
      </listitem>
      <listitem>
        <para>
          Completion scripts are supposed to be stored at
          <literal>$out/share/zsh/site-functions</literal>. This
          directory is part of the
          <link xlink:href="http://zsh.sourceforge.net/Doc/Release/Functions.html"><literal>fpath</literal></link>
          and the package should be compatible with pure
          <literal>ZSH</literal> setups. The module will automatically
          link the contents of <literal>site-functions</literal> to
          completions directory in the proper store path.
        </para>
      </listitem>
      <listitem>
        <para>
          The <literal>plugins</literal> directory needs the structure
          <literal>pluginname/pluginname.plugin.zsh</literal> as
          structured in the
          <link xlink:href="https://github.com/robbyrussell/oh-my-zsh/tree/91b771914bc7c43dd7c7a43b586c5de2c225ceb7/plugins">upstream
          repo.</link>
        </para>
      </listitem>
    </itemizedlist>
    <para>
      A derivation for <literal>oh-my-zsh</literal> may look like this:
    </para>
    <programlisting>
{ stdenv, fetchFromGitHub }:

stdenv.mkDerivation rec {
  name = &quot;exemplary-zsh-customization-${version}&quot;;
  version = &quot;1.0.0&quot;;
  src = fetchFromGitHub {
    # path to the upstream repository
  };

  dontBuild = true;
  installPhase = ''
    mkdir -p $out/share/zsh/site-functions
    cp {themes,plugins} $out/share/zsh
    cp completions $out/share/zsh/site-functions
  '';
}
</programlisting>
  </section>
</chapter>