README.md

   1 # AX-ZSH: Alex' Modular ZSH Configuration
   2
   3 [AX-ZSH] is a modular configuration system for the Z shell ([ZSH]).
   4 It provides sane defaults and is extendable by plugins.
   5
   6 AX-ZSH integrates well with [Powerlevel10k] and other extensions, even plugins
   7 of [OhMyZsh], see [below](#integration-with-other-projects).
   8
   9 The homepage of [AX-ZSH] can be found at [GitHub]:
  10 <https://github.com/alexbarton/ax-zsh>.
  11
  12 ## Installation
  13
  14 Prerequisites:
  15
  16 * [ZSH] – obviously ;-)
  17 * [Git] (optional but recommended!)
  18
  19 Installing AX-ZSH is a two-step process:
  20
  21 1. Clone or copy the source files into the `~/.axzsh` directory,
  22 2. Run the `~/.axzsh/install.sh` script.
  23
  24 The `install.sh` script creates symbolic links for `~/.zprofile`, `~/.zshrc`,
  25 `~/.zlogin`, and `~/.zlogout` (don't worry, already existing files are backed
  26 up).
  27
  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!
  32
  33 ### Installation using Git
  34
  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
  37 location:
  38
  39 ```sh
  40 git clone https://github.com/alexbarton/ax-zsh.git ~/.axzsh
  41 ~/.axzsh/install.sh
  42 ```
  43
  44 ### Installation without Git
  45
  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!
  49
  50 ```sh
  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
  54 ~/.axzsh/install.sh
  55 ```
  56
  57 ### Post-Installation Tasks
  58
  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?
  62
  63 For example like this:
  64
  65 ```sh
  66 # Set new default shell
  67 chsh -s $(command -v zsh)
  68
  69 # Replace running shell with a ZSH login shell
  70 exec $(command -v zsh) -l
  71 ```
  72
  73 ## Upgrade
  74
  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:
  77
  78 ```sh
  79 axzshctl upgrade
  80 ```
  81
  82 ## Usage
  83
  84 AX-ZSH comes with a hopefully sane default configuration and can be extended
  85 using plugins. Different types of plugins are supported:
  86
  87 * Plugins shipped with AX-ZSH.
  88 * Themes shipped with AX-ZSH.
  89 * 3rd-party plugins:
  90   * installed manually into `$AXZSH/custom_plugins`
  91   * stand-alone plugins stored on GitHub
  92   * plugins of OhMyZsh from its GitHub repository
  93 * 3rd-party themes:
  94   * installed manually into `$AXZSH/custom_themes`
  95   * some stand-alone themes stored on GitHub
  96
  97 ### Check whether all locally available "useful" plug-ins are activated
  98
  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
 102 plan to use.
 103
 104 You can use the following command to let AX-ZSH scan the status of all locally
 105 available plugins:
 106
 107 ```sh
 108 axzshctl check-plugins
 109 ```
 110
 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).
 114
 115 ### List enabled plugins
 116
 117 Run the following command to list all currently enabled plugins:
 118
 119 ```sh
 120 axzshctl list-enabled
 121 ```
 122
 123 ### Enable plugins
 124
 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.
 128
 129 Different types of plugins are supported (see the introduction to the section
 130 "*usage*" above) which are differentiated by their identifier:
 131
 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>).
 137
 138 You can enable one or more plugins like this:
 139
 140 ```sh
 141 axzshctl enable-plugin <identifier> [<identifier> […]]
 142 ```
 143
 144 *Hint:* *Tab-completion* works for sub-commands and already locally available
 145 plugin names!
 146
 147 Some examples:
 148
 149 ```sh
 150 # Enable some plugins bundled with AX-ZSH:
 151 axzshctl enable-plugin editor_select git ssh_autoadd
 152
 153 # Enable the Powerlevel10k "theme plugin" from GitHub, see
 154 # <https://github.com/romkatv/powerlevel10k>:
 155 axzshctl enable-plugin romkatv/powerlevel10k
 156
 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
 160
 161 # Enable the Git and tmux plugins of OhMyZsh:
 162 axzshctl enable-plugin @ohmyzsh/git @ohmyzsh/tmux
 163 ```
 164
 165 #### Custom local plugins
 166
 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
 170 by default.
 171
 172 In addition you can set the `AXZSH_PLUGIN_D` variable (and `ZSH_CUSTOM` like
 173 [OhMyZsh]) to specify additional plugin search directories.
 174
 175 ### Disable plugins
 176
 177 Run the following command to disable a currently enabled plugin:
 178
 179 ```sh
 180 axzshctl disable-plugin <identifier> [<identifier> […]]
 181 ```
 182
 183 *Hint:* *Tab-completion* works for sub-commands and plugin names!
 184
 185 ### Update plugin cache
 186
 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
 190 all plugins.
 191
 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!
 194
 195 Run the following command to update the AX-ZSH cache:
 196
 197 ```sh
 198 axzshctl update-caches
 199 ```
 200
 201 ### Other `axzshctl` sub-commands
 202
 203 Please run `axzshctl --help` to get a full list of a available sub-commands:
 204
 205 ```sh
 206 axzshctl --help
 207 ```
 208
 209 ## Integration with other projects
 210
 211 ### Powerlevel10k
 212
 213 AX-ZSH supports [Powerlevel10k] out of the box, you just have to install it as a
 214 plugin:
 215
 216 ```sh
 217 axzshctl enable-plugin romkatv/powerlevel10k
 218 ```
 219
 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`.
 223
 224 ## AX-ZSH & local ZSH configuration
 225
 226 Don't modify `~/.zprofile`, `~/.zshrc`, `~/.zlogin`, or `~/.zlogout`! These
 227 are links to "AX-ZSH"-private files that can become overwritten when updating.
 228
 229 You can use the following files for local ZSH configuration:
 230
 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
 233    relies on).
 234
 235 2. AX-ZSH reads the optional files `~/.zprofile.local`, `~/.zshrc.local`,
 236    `~/.zlogin.local`, and `~/.zlogout.local` after its own core initialization
 237    files when present.
 238
 239 ## Environment variables
 240
 241 Expected to be already set:
 242
 243 * `HOME`
 244 * `LOGNAME`
 245
 246 Validated and/or set up by core plugins:
 247
 248 * `AXZSH` – AX-ZSH installation directory
 249 * `HOST`
 250 * `HOSTNAME` (same as HOST, deprecated)
 251 * `LOCAL_HOME`
 252 * `PS1`
 253 * `SHORT_HOST`
 254 * `TERM`
 255 * `TMPDIR` (set and always ends with a "/")
 256 * `XDG_CACHE_HOME`
 257 * `XDG_RUNTIME_DIR`
 258 * `ZSH_CACHE_DIR`
 259
 260 ___
 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"
 267
 268 [AX-ZSH] Copyright (c) 2015-2022 Alexander Barton <alex@barton.de>