From febee2c30b1dfbdf69375bbf4d57d46ff34a6841 Mon Sep 17 00:00:00 2001 From: Alexander Barton Date: Fri, 30 Apr 2021 13:10:57 +0200 Subject: [PATCH 1/1] Greatly enhance the README.md file --- README.md | 214 +++++++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 179 insertions(+), 35 deletions(-) diff --git a/README.md b/README.md index 8e059fc..ec35845 100644 --- a/README.md +++ b/README.md @@ -1,72 +1,216 @@ -AX-ZSH: Alex' Modular ZSH Configuration -======================================= +# AX-ZSH: Alex' Modular ZSH Configuration AX-ZSH is a modular configuration system for the Z shell (ZSH). It provides sane defaults and is extendable by plugins. -Installation ------------- +## Installation 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. -When using Git it is best to directly clone the AX-ZSH repository into the -`~/.axzsh` directory and call `install.sh` from this location. +Prerequisites: -Clone repository from _GitHub_ (): +* [ZSH](https://www.zsh.org/) – obviously ;-) +* [Git](https://git-scm.com/) (optional but recommended!) - git clone https://github.com/alexbarton/ax-zsh.git ~/.axzsh +Installing AX-ZSH is a two-step process: -Then run the installer script: - - ~/.axzsh/install.sh +1. Clone or copy the source files into `~/.axzsh`, +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). -Now close and restart all your running ZSH session to activate AX-ZSH. +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? -To update AX-ZSH run `axzshctl upgrade`. +For example like this: -AX-ZSH & Local ZSH Configuration --------------------------------- +```sh +# Set new default shell +chsh -s $(command -v zsh) -Plugins are loaded when they are linked into the `$AXZSH/active_plugins/` -directory; see the _Customization_ section below for how to activate them. +# Replace running shell with a ZSH login shell +exec $(command -v zsh) -l +``` -Don't modify `~/.zprofile`, `~/.zshrc`, `~/.zlogin`, or `~/.zlogout`! These -are links to "AX-ZSH"-private files that can become overwritten when updating. +### Installation using Git -You can use the following files for local ZSH configuration: +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: -1. AX-ZSH doesn't use `~/.zshenv` in any way. So you can use this file for your - own purposes (for example, to set up some environment variables that AX-ZSH - relies on). +```sh +git clone https://github.com/alexbarton/ax-zsh.git ~/.axzsh +~/.axzsh/install.sh +``` -2. AX-ZSH reads the optional files `~/.zprofile.local`, `~/.zshrc.local`, - `~/.zlogin.local`, and `~/.zlogout.local` after its own core initialization - files when present. +### 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! + +```sh +curl -Lo ax-zsh-master.zip https://github.com/alexbarton/ax-zsh/archive/refs/heads/master.zip +unzip ax-zsh-master.zip +mv ax-zsh-master ~/.axzsh +~/.axzsh/install.sh +``` + +## Upgrade + +When you used Git to install AX-ZSH (and/or plugins), you can use the `axzshctl` +command to upgrade AX-ZSH itself and external plugins like this: + +```sh +axzshctl upgrade +``` + +## Usage + +AX-ZSH comes with a hopefully sane default configuration and can be extended +using plugins. Different types of plugins are supported: + +* Plugins shipped with AX-ZSH. +* Themes shipped with AX-ZSH. +* 3rd-party plugins: + * installed manually into `$AXZSH/custom_plugins` + * stand-alone plugins stored on GitHub + * plugins of OhMyZsh from its GitHub repository +* 3rd-party themes: + * installed manually into `$AXZSH/custom_themes` + * some stand-alone themes stored on GitHub + +### Check whether all locally available "useful" plug-ins are activated + +Most plugins can be enabled even when the commands they work with aren't +available and won't do any harm. But to keep ZSH startup times low, you should +only enable plugins that are useable on your local system and which you actually +plan to use. + +You can use the following command to let AX-ZSH scan the status of all locally +available plugins: + +```sh +axzshctl check-plugins +``` + +It will summarize the status of all enabled plugins, and suggest to enable +plugins which seem to make sense on the system and to disable enabled plugins +that seem not to be supported (for example because of missing dependencies). + +### List enabled plugins + +Run the following command to list all currently enabled plugins: + +```sh +axzshctl list-enabled +``` + +### Enable plugins + +AX-ZSH comes with a sane "core ZSH configuration", but it can show its true +strengths when enabling additional plugins for additional tools and commands +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: + +* ``: locally available plugin, either bundled with AX-ZSH itself, or + installed manually (see below). +* `/`: stand-alone GitHub repository. +* `@ohmyzsh/`: [OhMyZsh](https://ohmyz.sh/) plugin from the OhMyZsh GitHub + repository (see ). + +You can enable one or more plugins like this: -Customization -------------- +```sh +axzshctl enable-plugin [ […]] +``` -Use the `axzshctl` tool to enable, disable, and reset plugins. AXZSH -initializes an alias which points to the actual location in `~/.axzsh/bin/`. +Hint: _Tab-completion_ works for sub-commands and already locally available +plugin names! -See `axzshctl --help` for details. +Some examples: + +```sh +# Enable some plugins bundled with AX-ZSH: +axzshctl enable-plugin editor_select git ssh_autoadd + +# Enable the Powerlevel10k "theme plugin" from GitHub, see +# : +axzshctl enable-plugin romkatv/powerlevel10k + +# Enable the "fast-syntax-highlighting" plugin from GitHub, see +# : +axzshctl enable-plugin zdharma/fast-syntax-highlighting + +# Enable the Git and tmux plugins of OhMyZsh: +axzshctl enable-plugin @ohmyzsh/git @ohmyzsh/tmux +``` + +#### Custom local plugins You can link custom plugins stored in arbitrary directories using `axzshctl` by specifying the complete path name. Or you can place additional plugins into -the `~/.axzsh/custom_plugins` folder which is searched by the `axzshctl` tool +the `$AXZSH/custom_plugins` folder which is searched by the `axzshctl` tool by default. In addition you can set the `AXZSH_PLUGIN_D` variable (and `ZSH_CUSTOM` like "OhMyZsh") to specify additional plugin search directories. -Environment Variables ---------------------- +### Disable plugins + +Run the following command to disable a currently enabled plugin: + +```sh +axzshctl disable-plugin [ […]] +``` + +Hint: _Tab-completion_ works for sub-commands and plugin names! + +### Update plugin cache + +AX-ZSH uses a "plugin cache" to speedup ZSH start times. This cache is +automatically updated when using the `axzshctl` sub-commands, for example when +enabling or disabling plugins, or when upgrading the AX-ZSH installation and +all plugins. + +But you *have to* update the cache when manually installing plugins or during +development of a own local plugin after updating its code! + +Run the following command to update the AX-ZSH cache: + +```sh +axzshctl update-caches +``` + +### Other `axzshctl` sub-commands + +Please run `axzshctl --help` to get a full list of a available sub-commands: + +```sh +axzshctl --help +``` + +## AX-ZSH & local ZSH configuration + +Don't modify `~/.zprofile`, `~/.zshrc`, `~/.zlogin`, or `~/.zlogout`! These +are links to "AX-ZSH"-private files that can become overwritten when updating. + +You can use the following files for local ZSH configuration: + +1. AX-ZSH doesn't use `~/.zshenv` in any way. So you can use this file for your + own purposes (for example, to set up some environment variables that AX-ZSH + relies on). + +2. AX-ZSH reads the optional files `~/.zprofile.local`, `~/.zshrc.local`, + `~/.zlogin.local`, and `~/.zlogout.local` after its own core initialization + files when present. + +## Environment variables Expected to be already set: @@ -75,7 +219,7 @@ Expected to be already set: Validated and/or set up by core plugins: -* `AXZSH` +* `AXZSH` – AX-ZSH installation directory * `HOST` * `HOSTNAME` (same as HOST, deprecated) * `LOCAL_HOME` -- 2.39.2