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