NixOS Wiki

Zsh: Difference between revisions

← Older edit
VisualWikitext
Layer-09 (talk | contribs)
169 edits
m Removed numbering
Pigs (talk | contribs)
259 edits
Reorganize page layout, add configuration options for system wide zsh usage, and make it clear when the article is talking about system configuration vs home manager
 
(8 intermediate revisions by 7 users not shown)
Line 6: Line 6:


== Installation ==
== Installation ==
See [[Command Shell]].
 
=== NixOS system installation ===
 
To install zsh for a user on a regular nixos system:
 
{{file|/etc/nixos/configuration.nix|nix|
<nowiki>
  programs.zsh.enable = true;
  users.extraUsers.myuser = {
    ...
    shell = pkgs.zsh;
  };
</nowiki>
}}
Replace <code>myuser</code> with the appropriate username.
 
See [[Command Shell]] for more information.
 
=== Home Manager ===
 
For a user-specific installation managed by [[Home Manager]], use the following configuration:
 
{{file|home.nix|nix|
<nowiki>
  home-manager.users.myuser = {
    programs.zsh.enable = true;
  };
</nowiki>
}}
 
Replace <code>myuser</code> with the appropriate username.
 
You can enable the zsh shell and manage zsh configuration and plugins with Home Manager, but to enable vendor zsh completions provided by Nixpkgs you will also want to enable the zsh shell:
 
{{file|/etc/nixos/configuration.nix|nix|
<nowiki>
  programs.zsh.enable = true;
</nowiki>
}}


== Configuration ==
== Configuration ==


==== Basic ====
=== NixOS system configuration ===
<syntaxhighlight lang="nix">
 
programs.zsh = {
The following example demonstrates how to configure zsh system-wide through the NixOS configuration:
 
{{file|/etc/nixos/configuration.nix|nix|
<nowiki>
  programs.zsh = {
    enable = true;
    enableCompletion = true;
    autosuggestions.enable = true;
    syntaxHighlighting.enable = true;
 
    shellAliases = {
      ll = "ls -l";
      edit = "sudo -e";
      update = "sudo nixos-rebuild switch";
    };
 
    histSize = 10000;
    histFile = "$HOME/.zsh_history";
    setOptions = [
      "HIST_IGNORE_ALL_DUPS"
    ];
  };
</nowiki>
}}
 
For a full list of zsh module options, refer to {{nixos:option|programs.zsh}}.
 
==== Plugins ====
 
The most straightforward way to manage Zsh plugins on NixOS is by enabling the <code>ohMyZsh</code> plugin manager, as demonstrated in the example below:
 
{{file|/etc/nixos/configuration.nix|nix|
<nowiki>
  programs.zsh = {
     enable = true;
     enable = true;
};
    ohMyZsh = {
</syntaxhighlight>
      enable = true;
      plugins = [
        "git"
        "z"
      ];
      theme = "robbyrussell";
    };
  };
</nowiki>
}}
 
Alternatively, individual Zsh plugins are available as {{nixos:package|zsh-*}} packages within Nixpkgs. When using this method, plugins must be manually sourced within the Zsh configuration file.
 
=== Home Manager ===
 
The configuration below is using [[Home Manager]], but a more limited version of it can be achieved if system-wide.


==== Advanced ====
{{file|home.nix|nix|
The configuration below is using home manager, but a more limited version of it can be achieved if system-wide.<syntaxhighlight lang="nix">
<nowiki>
programs.zsh = {
  programs.zsh = {
     enable = true;
     enable = true;
     enableCompletion = true;
     enableCompletion = true;
     autosuggestions.enable = true;
     autosuggestion.enable = true;
     syntaxHighlighting.enable = true;
     syntaxHighlighting.enable = true;


Line 35: Line 122:
     history.path = "$HOME/.zsh_history";
     history.path = "$HOME/.zsh_history";
     history.ignorePatterns = ["rm *" "pkill *" "cp *"];
     history.ignorePatterns = ["rm *" "pkill *" "cp *"];
};
  };
</syntaxhighlight>
</nowiki>
}}
 
The home manager options are defined in the following [https://nix-community.github.io/home-manager/options.xhtml#opt-programs.zsh.enable Home Manager Options Manual] or can be looked up at [https://home-manager-options.extranix.com/?query=zsh&release=master Home Manager Option Search].


== Tips and Tricks ==
The system-wide options are listed on [https://search.nixos.org/options?query=programs.zsh programs.zsh.*].


==== Where to see a list of options? ====
==== Plugins ====
The home manager options are defined in the following [https://nix-community.github.io/home-manager/options.xhtml#opt-programs.zsh.enable Home Manager Options Manual].


The system-wide options are listed on [https://mynixos.com/search?q=zsh MyNixOS].
Home manager has four ways of managing plugins: '''[http://zplug.github.io/ Zplug]''', '''[https://ohmyz.sh/ Oh-My-Zsh], [https://getantidote.github.io/ Antidote]''' and '''manually'''.


==== How to use plugins? ====
{{file|home.nix|nix|
Home manager has three ways of managing plugins: '''Zplug''', '''Oh-My-Zsh''' and '''Manual'''.<syntaxhighlight lang="nix">
<nowiki>
programs.zsh = {
programs.zsh = {
   enable = true;
   enable = true;


# With Zplug:
   zplug = {
   zplug = {
     enable = true;
     enable = true;
Line 56: Line 146:
       {
       {
         name = "romkatv/powerlevel10k";
         name = "romkatv/powerlevel10k";
         tags = [as:theme depth:1];
         tags = [ "as:theme" "depth:1" ];
       } # Installations with additional options. For the list of options, please refer to Zplug README.
       } # Installations with additional options. For the list of options, please refer to Zplug README.
     ];
     ];
   };
   };


   ohMyZsh = {
# With Oh-My-Zsh:
   oh-my-zsh = {
     enable = true;
     enable = true;
     plugins = ["git" "thefuck"];
     plugins = [
      "git"         # also requires `programs.git.enable = true;`
      "thefuck"     # also requires `programs.thefuck.enable = true;`
    ];
     theme = "robbyrussell";
     theme = "robbyrussell";
   };
   };


# With Antidote:
  antidote = {
    enable = true;
    plugins = [''
      zsh-users/zsh-autosuggestions
      ohmyzsh/ohmyzsh path:lib/git.zsh
    '']; # explanation of "path:..." and other options explained in Antidote README.
# Manual
   plugins = [
   plugins = [
     {
     {
Line 98: Line 201:
   ];
   ];
};
};
</syntaxhighlight>
</nowiki>
}}
 
An example of less verbatim approach to sourcing packaged plugins can be [https://discourse.nixos.org/t/zsh-users-how-do-you-manage-plugins/9199/8 found here] and [https://discourse.nixos.org/t/zsh-users-how-do-you-manage-plugins/9199/10 here].


== Troubleshooting ==
== Troubleshooting ==
Line 125: Line 231:
<syntaxhighlight lang="nix">
<syntaxhighlight lang="nix">
environment.shells = with pkgs; [ zsh ];
environment.shells = with pkgs; [ zsh ];
</syntaxhighlight>
==== Hide configuration for new users ====
Meaning this message:<syntaxhighlight lang="zsh">
This is the Z Shell configuration function for new users,
zsh-newuser-install.
You are seeing this message because you have no zsh startup files
(the files .zshenv, .zprofile, .zshrc, .zlogin in the directory
~).  This function can help you with a few settings that should
make your use of the shell easier.
You can:
(q)  Quit and do nothing.  The function will be run again next time.
(0)  Exit, creating the file ~/.zshrc containing just a comment.
    That will prevent this function being run again.
(1)  Continue to the main menu.
--- Type one of the keys in parentheses ---
</syntaxhighlight>You can hide this message by adding following line to the system configuration:<syntaxhighlight lang="nixos">
# Prevent the new user dialog in zsh
system.userActivationScripts.zshrc = "touch .zshrc";
</syntaxhighlight>
</syntaxhighlight>


Line 134: Line 264:
# http://zsh.sourceforge.net/FAQ/zshfaq01.html#l4
# http://zsh.sourceforge.net/FAQ/zshfaq01.html#l4
# https://nix-community.github.io/home-manager/options.xhtml#opt-programs.zsh.enable
# https://nix-community.github.io/home-manager/options.xhtml#opt-programs.zsh.enable
# https://mynixos.com/search?q=zsh
# https://search.nixos.org/options?query=programs.zsh


[[Category:Shell]]
[[Category:Shell]]
[[Category:NixOS Manual]]
[[Category:NixOS Manual]]
Retrieved from "https://wiki.nixos.org/wiki/Zsh"