README.md

   1 AX-ZSH: Alex' Modular ZSH Configuration
   2 =======================================
   3
   4 AX-ZSH is a modular configuration system for the Z shell (ZSH).
   5 It provides sane defaults and is extendable by plugins.
   6
   7
   8 Installation
   9 ------------
  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 When using Git it is best to directly clone the AX-ZSH repository into the
  16 `~/.axzsh` directory and call `install.sh` from this location.
  17
  18 Clone repository from _GitHub_ (https://github.com/alexbarton/ax-zsh):
  19
  20     $ git clone https://github.com/alexbarton/ax-zsh.git ~/.axzsh
  21
  22 Then run the installer script:
  23
  24     $ ~/.axzsh/install.sh
  25
  26 The `install.sh` script creates symbolic links for `~/.zprofile`, `~/.zshrc`,
  27 `~/.zlogin`, and `~/.zlogout` (don't worry, already existing files are backed
  28 up).
  29
  30 Now close and restart all your running ZSH session to activate AX-ZSH.
  31
  32 To update AX-ZSH run `axzshctl upgrade`.
  33
  34
  35 AX-ZSH & Local ZSH Configuration
  36 --------------------------------
  37
  38 Plugins are loaded when they are linked into the `$AXZSH/active_plugins/`
  39 directory; see the _Customization_ section below for how to activate them.
  40
  41 Don't modify `~/.zprofile`, `~/.zshrc`, `~/.zlogin`, or `~/.zlogout`! These
  42 are links to "AX-ZSH"-private files that can become overwritten when updating.
  43
  44 You can use the following files for local ZSH configuration:
  45
  46 1. AX-ZSH doesn't use `~/.zshenv` in any way. So you can use this file for your
  47    own purposes (for example, to set up some environment variables that AX-ZSH
  48    relays on).
  49
  50 2. AX-ZSH reads the optional files `~/.zprofile.local`, `~/.zshrc.local`,
  51    `~/.zlogin.local`, and `~/.zlogout.local` after its own core initialization
  52    files when present.
  53
  54
  55 Customization
  56 -------------
  57
  58 Use the `axzshctl` tool to enable, disable, and reset plugins. AXZSH
  59 initializes an alias which points to the actual location in `~/.axzsh/bin/`.
  60
  61 See `axzshctl --help` for details.
  62
  63 You can link custom plugins stored in arbitrary directories using `axzshctl`
  64 by specifying the complete path name. Or you can place additional plugins into
  65 the `~/.axzsh/custom_plugins` folder which is searched by the `axzshctl` tool
  66 by default.
  67
  68 In addition you can set the `AXZSH_PLUGIN_D` variable (and `ZSH_CUSTOM` like
  69 "OhMyZsh") to specify additional plugin search directories.
  70
  71
  72 Environment Variables
  73 ---------------------
  74
  75 Expected to be already set:
  76
  77 * `HOME`
  78 * `LOGNAME`
  79
  80 Validated and/or set up by core plugins:
  81
  82 * `AXZSH`
  83 * `HOST`
  84 * `HOSTNAME` (same as HOST, deprecated)
  85 * `LOCAL_HOME`
  86 * `PS1`
  87 * `SHORT_HOST`
  88 * `TERM`
  89 * `XDG_CACHE_HOME`
  90 * `ZSH_CACHE_DIR`