# AX-ZSH: Alex' Modular ZSH Configuration
-AX-ZSH is a modular configuration system for the Z shell (ZSH).
+[AX-ZSH] is a modular configuration system for the Z shell ([ZSH]).
It provides sane defaults and is extendable by plugins.
-## Installation
+AX-ZSH integrates well with [Powerlevel10k] and other extensions, even plugins
+of [OhMyZsh], see [below](#integration-with-other-projects).
+
+The homepage of [AX-ZSH] can be found at [GitHub]:
+<https://github.com/alexbarton/ax-zsh>.
-To install AX-ZSH, either download a source archive or use Git to clone it.
-Afterwards use the `install.sh` script inside of the source directory to set
-up the `~/.axzsh` directory.
+## Installation
Prerequisites:
-* [ZSH](https://www.zsh.org/) – obviously ;-)
-* [Git](https://git-scm.com/) (optional but recommended!)
+* [ZSH] – obviously ;-)
+* [Git] (optional but recommended!)
Installing AX-ZSH is a two-step process:
-1. Clone or copy the source files into `~/.axzsh`,
+1. Clone or copy the source files into the `~/.axzsh` directory,
2. Run the `~/.axzsh/install.sh` script.
The `install.sh` script creates symbolic links for `~/.zprofile`, `~/.zshrc`,
`~/.zlogin`, and `~/.zlogout` (don't worry, already existing files are backed
up).
-Then close all running ZSH sessions and restart them to activate AX-ZSH. And
-maybe change your default shell to ZSH if you haven't already?
-
-For example like this:
-
-```sh
-# Set new default shell
-chsh -s $(command -v zsh)
-
-# Replace running shell with a ZSH login shell
-exec $(command -v zsh) -l
-```
+*Note:* The installation is per-user and only changes/installs files into the
+home directory of the current user (`~`). AX-ZSH is not meant to be installed
+globally for all users on a system at once, and you don't need to become "root"
+or any other user with elevated privileges!
### Installation using Git
-When using Git, the preferred method, it is best to directly clone the AX-ZSH
+When using [Git], the preferred method, it is best to directly clone the AX-ZSH
repository into the `~/.axzsh` directory and call `install.sh` from this
location:
### Installation without Git
-*Note:* If you do not install AX-ZSH with Git, you will not be able to upgrade
-itself afterwards with the integrated `axzsh upgrade` command!
+*Note:* If you do not install AX-ZSH with [Git], you will not be able to upgrade
+itself afterwards with the integrated `axzsh upgrade` command! Therefore this
+method is *not recommended* for normal use!
```sh
curl -Lo ax-zsh-master.zip https://github.com/alexbarton/ax-zsh/archive/refs/heads/master.zip
~/.axzsh/install.sh
```
+### Post-Installation Tasks
+
+After installing AX-ZSH, using Git or via an archive file, you should close all
+running ZSH sessions and restart them to activate AX-ZSH. And maybe you want to
+change your default shell to ZSH if you haven't already?
+
+For example like this:
+
+```sh
+# Set new default shell
+chsh -s $(command -v zsh)
+
+# Replace running shell with a ZSH login shell
+exec $(command -v zsh) -l
+```
+
## Upgrade
When you used Git to install AX-ZSH (and/or plugins), you can use the `axzshctl`
that are available on your system and you want to use.
Different types of plugins are supported (see the introduction to the section
-"_usage_" above) which are differentiated by their identifier:
+"*usage*" above) which are differentiated by their identifier:
* `<name>`: locally available plugin, either bundled with AX-ZSH itself, or
installed manually (see below).
-* `<repository>/<name>`: stand-alone GitHub repository.
-* `@ohmyzsh/<name>`: [OhMyZsh](https://ohmyz.sh/) plugin from the OhMyZsh GitHub
+* `<repository>/<name>`: stand-alone [GitHub] repository.
+* `@ohmyzsh/<name>`: [OhMyZsh] plugin from the OhMyZsh GitHub
repository (see <https://github.com/ohmyzsh/ohmyzsh/tree/master/plugins>).
You can enable one or more plugins like this:
axzshctl enable-plugin <identifier> [<identifier> […]]
```
-Hint: _Tab-completion_ works for sub-commands and already locally available
+*Hint:* *Tab-completion* works for sub-commands and already locally available
plugin names!
Some examples:
axzshctl enable-plugin romkatv/powerlevel10k
# Enable the "fast-syntax-highlighting" plugin from GitHub, see
-# <https://github.com/zdharma/fast-syntax-highlighting>:
-axzshctl enable-plugin zdharma/fast-syntax-highlighting
+# <https://github.com/zdharma-continuum/fast-syntax-highlighting>:
+axzshctl enable-plugin zdharma-continuum/fast-syntax-highlighting
# Enable the Git and tmux plugins of OhMyZsh:
axzshctl enable-plugin @ohmyzsh/git @ohmyzsh/tmux
by default.
In addition you can set the `AXZSH_PLUGIN_D` variable (and `ZSH_CUSTOM` like
-"OhMyZsh") to specify additional plugin search directories.
+[OhMyZsh]) to specify additional plugin search directories.
### Disable plugins
axzshctl disable-plugin <identifier> [<identifier> […]]
```
-Hint: _Tab-completion_ works for sub-commands and plugin names!
+*Hint:* *Tab-completion* works for sub-commands and plugin names!
### Update plugin cache
axzshctl --help
```
+## Integration with other projects
+
+### Powerlevel10k
+
+AX-ZSH supports [Powerlevel10k] out of the box, you just have to install it as a
+plugin:
+
+```sh
+axzshctl enable-plugin romkatv/powerlevel10k
+```
+
+*Hint:* Once the Powerlevel10k plugin theme is installed, you can use the
+regular `axzshctl set-theme` command to enable it, like for any other installed
+theme: `axzshctl set-theme powerlevel10k`.
+
## AX-ZSH & local ZSH configuration
Don't modify `~/.zprofile`, `~/.zshrc`, `~/.zlogin`, or `~/.zlogout`! These
* `XDG_CACHE_HOME`
* `XDG_RUNTIME_DIR`
* `ZSH_CACHE_DIR`
+
+___
+[AX-ZSH]: <https://github.com/alexbarton/ax-zsh> "AX-ZSH Homepage"
+[Git]: <https://git-scm.com/> "Git Homepage"
+[GitHub]: <https://github.com/> "GitHub Homepage"
+[OhMyZsh]: <https://ohmyz.sh/> "OhMyZsh Homepage"
+[Powerlevel10k]: <https://github.com/romkatv/powerlevel10k> "Powerlevel10k Homepage"
+[ZSH]: <https://www.zsh.org/> "ZSH Homepage"
+
+[AX-ZSH] Copyright (c) 2015-2022 Alexander Barton <alex@barton.de>
projects / ax-zsh.git / blobdiff