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