1 # AX-ZSH: Alex' Modular ZSH Configuration
3 [AX-ZSH] is a modular configuration system for the Z shell ([ZSH]).
4 It provides sane defaults and is extendable by plugins.
6 AX-ZSH integrates well with [Powerlevel10k] and other extensions, even plugins
7 of [OhMyZsh], see [below](#integration-with-other-projects).
9 The homepage of [AX-ZSH] can be found at [GitHub]:
10 <https://github.com/alexbarton/ax-zsh>.
16 * [ZSH] – obviously ;-)
17 * [Git] (optional but recommended!)
19 Installing AX-ZSH is a two-step process:
21 1. Clone or copy the source files into the `~/.axzsh` directory,
22 2. Run the `~/.axzsh/install.sh` script.
24 The `install.sh` script creates symbolic links for `~/.zprofile`, `~/.zshrc`,
25 `~/.zlogin`, and `~/.zlogout` (don't worry, already existing files are backed
28 *Note:* The installation is per-user and only changes/installs files into the
29 home directory of the current user (`~`). AX-ZSH is not meant to be installed
30 globally for all users on a system at once, and you don't need to become "root"
31 or any other user with elevated privileges!
33 ### Installation using Git
35 When using [Git], the preferred method, it is best to directly clone the AX-ZSH
36 repository into the `~/.axzsh` directory and call `install.sh` from this
40 git clone https://github.com/alexbarton/ax-zsh.git ~/.axzsh
44 ### Installation without Git
46 *Note:* If you do not install AX-ZSH with [Git], you will not be able to upgrade
47 itself afterwards with the integrated `axzsh upgrade` command! Therefore this
48 method is *not recommended* for normal use!
51 curl -Lo ax-zsh-master.zip https://github.com/alexbarton/ax-zsh/archive/refs/heads/master.zip
52 unzip ax-zsh-master.zip
53 mv ax-zsh-master ~/.axzsh
57 ### Post-Installation Tasks
59 After installing AX-ZSH, using Git or via an archive file, you should close all
60 running ZSH sessions and restart them to activate AX-ZSH. And maybe you want to
61 change your default shell to ZSH if you haven't already?
63 For example like this:
66 # Set new default shell
67 chsh -s $(command -v zsh)
69 # Replace running shell with a ZSH login shell
70 exec $(command -v zsh) -l
75 When you used Git to install AX-ZSH (and/or plugins), you can use the `axzshctl`
76 command to upgrade AX-ZSH itself and external plugins like this:
84 AX-ZSH comes with a hopefully sane default configuration and can be extended
85 using plugins. Different types of plugins are supported:
87 * Plugins shipped with AX-ZSH.
88 * Themes shipped with AX-ZSH.
90 * installed manually into `$AXZSH/custom_plugins`
91 * stand-alone plugins stored on GitHub
92 * plugins of OhMyZsh from its GitHub repository
94 * installed manually into `$AXZSH/custom_themes`
95 * some stand-alone themes stored on GitHub
97 ### Check whether all locally available "useful" plug-ins are activated
99 Most plugins can be enabled even when the commands they work with aren't
100 available and won't do any harm. But to keep ZSH startup times low, you should
101 only enable plugins that are useable on your local system and which you actually
104 You can use the following command to let AX-ZSH scan the status of all locally
108 axzshctl check-plugins
111 It will summarize the status of all enabled plugins, and suggest to enable
112 plugins which seem to make sense on the system and to disable enabled plugins
113 that seem not to be supported (for example because of missing dependencies).
115 ### List enabled plugins
117 Run the following command to list all currently enabled plugins:
120 axzshctl list-enabled
125 AX-ZSH comes with a sane "core ZSH configuration", but it can show its true
126 strengths when enabling additional plugins for additional tools and commands
127 that are available on your system and you want to use.
129 Different types of plugins are supported (see the introduction to the section
130 "*usage*" above) which are differentiated by their identifier:
132 * `<name>`: locally available plugin, either bundled with AX-ZSH itself, or
133 installed manually (see below).
134 * `<repository>/<name>`: stand-alone [GitHub] repository.
135 * `@ohmyzsh/<name>`: [OhMyZsh] plugin from the OhMyZsh GitHub
136 repository (see <https://github.com/ohmyzsh/ohmyzsh/tree/master/plugins>).
138 You can enable one or more plugins like this:
141 axzshctl enable-plugin <identifier> [<identifier> […]]
144 *Hint:* *Tab-completion* works for sub-commands and already locally available
150 # Enable some plugins bundled with AX-ZSH:
151 axzshctl enable-plugin editor_select git ssh_autoadd
153 # Enable the Powerlevel10k "theme plugin" from GitHub, see
154 # <https://github.com/romkatv/powerlevel10k>:
155 axzshctl enable-plugin romkatv/powerlevel10k
157 # Enable the "fast-syntax-highlighting" plugin from GitHub, see
158 # <https://github.com/zdharma-continuum/fast-syntax-highlighting>:
159 axzshctl enable-plugin zdharma-continuum/fast-syntax-highlighting
161 # Enable the Git and tmux plugins of OhMyZsh:
162 axzshctl enable-plugin @ohmyzsh/git @ohmyzsh/tmux
165 #### Custom local plugins
167 You can link custom plugins stored in arbitrary directories using `axzshctl`
168 by specifying the complete path name. Or you can place additional plugins into
169 the `$AXZSH/custom_plugins` folder which is searched by the `axzshctl` tool
172 In addition you can set the `AXZSH_PLUGIN_D` variable (and `ZSH_CUSTOM` like
173 [OhMyZsh]) to specify additional plugin search directories.
177 Run the following command to disable a currently enabled plugin:
180 axzshctl disable-plugin <identifier> [<identifier> […]]
183 *Hint:* *Tab-completion* works for sub-commands and plugin names!
185 ### Update plugin cache
187 AX-ZSH uses a "plugin cache" to speedup ZSH start times. This cache is
188 automatically updated when using the `axzshctl` sub-commands, for example when
189 enabling or disabling plugins, or when upgrading the AX-ZSH installation and
192 But you *have to* update the cache when manually installing plugins or during
193 development of a own local plugin after updating its code!
195 Run the following command to update the AX-ZSH cache:
198 axzshctl update-caches
201 ### Other `axzshctl` sub-commands
203 Please run `axzshctl --help` to get a full list of a available sub-commands:
209 ## Integration with other projects
213 AX-ZSH supports [Powerlevel10k] out of the box, you just have to install it as a
217 axzshctl enable-plugin romkatv/powerlevel10k
220 *Hint:* Once the Powerlevel10k plugin theme is installed, you can use the
221 regular `axzshctl set-theme` command to enable it, like for any other installed
222 theme: `axzshctl set-theme powerlevel10k`.
224 ## AX-ZSH & local ZSH configuration
226 Don't modify `~/.zprofile`, `~/.zshrc`, `~/.zlogin`, or `~/.zlogout`! These
227 are links to "AX-ZSH"-private files that can become overwritten when updating.
229 You can use the following files for local ZSH configuration:
231 1. AX-ZSH doesn't use `~/.zshenv` in any way. So you can use this file for your
232 own purposes (for example, to set up some environment variables that AX-ZSH
235 2. AX-ZSH reads the optional files `~/.zprofile.local`, `~/.zshrc.local`,
236 `~/.zlogin.local`, and `~/.zlogout.local` after its own core initialization
239 ## Environment variables
241 Expected to be already set:
246 Validated and/or set up by core plugins:
248 * `AXZSH` – AX-ZSH installation directory
250 * `HOSTNAME` (same as HOST, deprecated)
255 * `TMPDIR` (set and always ends with a "/")
261 [AX-ZSH]: <https://github.com/alexbarton/ax-zsh> "AX-ZSH Homepage"
262 [Git]: <https://git-scm.com/> "Git Homepage"
263 [GitHub]: <https://github.com/> "GitHub Homepage"
264 [OhMyZsh]: <https://ohmyz.sh/> "OhMyZsh Homepage"
265 [Powerlevel10k]: <https://github.com/romkatv/powerlevel10k> "Powerlevel10k Homepage"
266 [ZSH]: <https://www.zsh.org/> "ZSH Homepage"
268 [AX-ZSH] Copyright (c) 2015-2022 Alexander Barton <alex@barton.de>