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 ## Installation
  10
  11 To install AX-ZSH, either download a source archive or use [Git] to clone it.
  12 Afterwards use the `install.sh` script inside of the source directory to set
  13 up the `~/.axzsh` directory.
  14
  15 The homepage of [AX-ZSH] can be found at [GitHub]:
  16 <https://github.com/alexbarton/ax-zsh>.
  17
  18 Prerequisites:
  19
  20 * [ZSH] – obviously ;-)
  21 * [Git] (optional but recommended!)
  22
  23 Installing AX-ZSH is a two-step process:
  24
  25 1. Clone or copy the source files into `~/.axzsh`,
  26 2. Run the `~/.axzsh/install.sh` script.
  27
  28 The `install.sh` script creates symbolic links for `~/.zprofile`, `~/.zshrc`,
  29 `~/.zlogin`, and `~/.zlogout` (don't worry, already existing files are backed
  30 up).
  31
  32 Then close all running ZSH sessions and restart them to activate AX-ZSH. And
  33 maybe change your default shell to ZSH if you haven't already?
  34
  35 For example like this:
  36
  37 ```sh
  38 # Set new default shell
  39 chsh -s $(command -v zsh)
  40
  41 # Replace running shell with a ZSH login shell
  42 exec $(command -v zsh) -l
  43 ```
  44
  45 ### Installation using Git
  46
  47 When using [Git], the preferred method, it is best to directly clone the AX-ZSH
  48 repository into the `~/.axzsh` directory and call `install.sh` from this
  49 location:
  50
  51 ```sh
  52 git clone https://github.com/alexbarton/ax-zsh.git ~/.axzsh
  53 ~/.axzsh/install.sh
  54 ```
  55
  56 ### Installation without Git
  57
  58 *Note:* If you do not install AX-ZSH with [Git], you will not be able to upgrade
  59 itself afterwards with the integrated `axzsh upgrade` command! Therefore this
  60 method is _not recommended_ for normal use!
  61
  62 ```sh
  63 curl -Lo ax-zsh-master.zip https://github.com/alexbarton/ax-zsh/archive/refs/heads/master.zip
  64 unzip ax-zsh-master.zip
  65 mv ax-zsh-master ~/.axzsh
  66 ~/.axzsh/install.sh
  67 ```
  68
  69 ## Upgrade
  70
  71 When you used Git to install AX-ZSH (and/or plugins), you can use the `axzshctl`
  72 command to upgrade AX-ZSH itself and external plugins like this:
  73
  74 ```sh
  75 axzshctl upgrade
  76 ```
  77
  78 ## Usage
  79
  80 AX-ZSH comes with a hopefully sane default configuration and can be extended
  81 using plugins. Different types of plugins are supported:
  82
  83 * Plugins shipped with AX-ZSH.
  84 * Themes shipped with AX-ZSH.
  85 * 3rd-party plugins:
  86   * installed manually into `$AXZSH/custom_plugins`
  87   * stand-alone plugins stored on GitHub
  88   * plugins of OhMyZsh from its GitHub repository
  89 * 3rd-party themes:
  90   * installed manually into `$AXZSH/custom_themes`
  91   * some stand-alone themes stored on GitHub
  92
  93 ### Check whether all locally available "useful" plug-ins are activated
  94
  95 Most plugins can be enabled even when the commands they work with aren't
  96 available and won't do any harm. But to keep ZSH startup times low, you should
  97 only enable plugins that are useable on your local system and which you actually
  98 plan to use.
  99
 100 You can use the following command to let AX-ZSH scan the status of all locally
 101 available plugins:
 102
 103 ```sh
 104 axzshctl check-plugins
 105 ```
 106
 107 It will summarize the status of all enabled plugins, and suggest to enable
 108 plugins which seem to make sense on the system and to disable enabled plugins
 109 that seem not to be supported (for example because of missing dependencies).
 110
 111 ### List enabled plugins
 112
 113 Run the following command to list all currently enabled plugins:
 114
 115 ```sh
 116 axzshctl list-enabled
 117 ```
 118
 119 ### Enable plugins
 120
 121 AX-ZSH comes with a sane "core ZSH configuration", but it can show its true
 122 strengths when enabling additional plugins for additional tools and commands
 123 that are available on your system and you want to use.
 124
 125 Different types of plugins are supported (see the introduction to the section
 126 "_usage_" above) which are differentiated by their identifier:
 127
 128 * `<name>`: locally available plugin, either bundled with AX-ZSH itself, or
 129   installed manually (see below).
 130 * `<repository>/<name>`: stand-alone [GitHub] repository.
 131 * `@ohmyzsh/<name>`: [OhMyZsh] plugin from the OhMyZsh GitHub
 132   repository (see <https://github.com/ohmyzsh/ohmyzsh/tree/master/plugins>).
 133
 134 You can enable one or more plugins like this:
 135
 136 ```sh
 137 axzshctl enable-plugin <identifier> [<identifier> […]]
 138 ```
 139
 140 *Hint:* _Tab-completion_ works for sub-commands and already locally available
 141 plugin names!
 142
 143 Some examples:
 144
 145 ```sh
 146 # Enable some plugins bundled with AX-ZSH:
 147 axzshctl enable-plugin editor_select git ssh_autoadd
 148
 149 # Enable the Powerlevel10k "theme plugin" from GitHub, see
 150 # <https://github.com/romkatv/powerlevel10k>:
 151 axzshctl enable-plugin romkatv/powerlevel10k
 152
 153 # Enable the "fast-syntax-highlighting" plugin from GitHub, see
 154 # <https://github.com/zdharma-continuum/fast-syntax-highlighting>:
 155 axzshctl enable-plugin zdharma-continuum/fast-syntax-highlighting
 156
 157 # Enable the Git and tmux plugins of OhMyZsh:
 158 axzshctl enable-plugin @ohmyzsh/git @ohmyzsh/tmux
 159 ```
 160
 161 #### Custom local plugins
 162
 163 You can link custom plugins stored in arbitrary directories using `axzshctl`
 164 by specifying the complete path name. Or you can place additional plugins into
 165 the `$AXZSH/custom_plugins` folder which is searched by the `axzshctl` tool
 166 by default.
 167
 168 In addition you can set the `AXZSH_PLUGIN_D` variable (and `ZSH_CUSTOM` like
 169 [OhMyZsh]) to specify additional plugin search directories.
 170
 171 ### Disable plugins
 172
 173 Run the following command to disable a currently enabled plugin:
 174
 175 ```sh
 176 axzshctl disable-plugin <identifier> [<identifier> […]]
 177 ```
 178
 179 *Hint:* _Tab-completion_ works for sub-commands and plugin names!
 180
 181 ### Update plugin cache
 182
 183 AX-ZSH uses a "plugin cache" to speedup ZSH start times. This cache is
 184 automatically updated when using the `axzshctl` sub-commands, for example when
 185 enabling or disabling plugins, or when  upgrading the AX-ZSH installation and
 186 all plugins.
 187
 188 But you *have to* update the cache when manually installing plugins or during
 189 development of a own local plugin after updating its code!
 190
 191 Run the following command to update the AX-ZSH cache:
 192
 193 ```sh
 194 axzshctl update-caches
 195 ```
 196
 197 ### Other `axzshctl` sub-commands
 198
 199 Please run `axzshctl --help` to get a full list of a available sub-commands:
 200
 201 ```sh
 202 axzshctl --help
 203 ```
 204
 205 ## Integration with other projects
 206
 207 ### Powerlevel10k
 208
 209 AX-ZSH supports [Powerlevel10k] out of the box, you just have to install it as a
 210 plugin:
 211
 212 ```sh
 213 axzshctl enable-plugin romkatv/powerlevel10k
 214 ```
 215
 216 *Hint:* Once the Powerlevel10k plugin theme is installed, you can use the
 217 regular `axzshctl set-theme` command to enable it, like for any other installed
 218 theme: `axzshctl set-theme powerlevel10k`.
 219
 220 ## AX-ZSH & local ZSH configuration
 221
 222 Don't modify `~/.zprofile`, `~/.zshrc`, `~/.zlogin`, or `~/.zlogout`! These
 223 are links to "AX-ZSH"-private files that can become overwritten when updating.
 224
 225 You can use the following files for local ZSH configuration:
 226
 227 1. AX-ZSH doesn't use `~/.zshenv` in any way. So you can use this file for your
 228    own purposes (for example, to set up some environment variables that AX-ZSH
 229    relies on).
 230
 231 2. AX-ZSH reads the optional files `~/.zprofile.local`, `~/.zshrc.local`,
 232    `~/.zlogin.local`, and `~/.zlogout.local` after its own core initialization
 233    files when present.
 234
 235 ## Environment variables
 236
 237 Expected to be already set:
 238
 239 * `HOME`
 240 * `LOGNAME`
 241
 242 Validated and/or set up by core plugins:
 243
 244 * `AXZSH` – AX-ZSH installation directory
 245 * `HOST`
 246 * `HOSTNAME` (same as HOST, deprecated)
 247 * `LOCAL_HOME`
 248 * `PS1`
 249 * `SHORT_HOST`
 250 * `TERM`
 251 * `TMPDIR` (set and always ends with a "/")
 252 * `XDG_CACHE_HOME`
 253 * `XDG_RUNTIME_DIR`
 254 * `ZSH_CACHE_DIR`
 255
 256 ___
 257 [AX-ZSH]: <https://github.com/alexbarton/ax-zsh> "AX-ZSH Homepage"
 258 [Git]: <https://git-scm.com/> "Git Homepage"
 259 [GitHub]: <https://github.com/> "GitHub Homepage"
 260 [OhMyZsh]: <https://ohmyz.sh/> "OhMyZsh Homepage"
 261 [Powerlevel10k]: <https://github.com/romkatv/powerlevel10k> "Powerlevel10k Homepage"
 262 [ZSH]: <https://www.zsh.org/> "ZSH Homepage"
 263
 264 [AX-ZSH] Copyright (c) 2015-2021 Alexander Barton <alex@barton.de>