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