X-Git-Url: https://arthur.barton.de/gitweb/?p=ax-zsh.git;a=blobdiff_plain;f=README.md;h=3ddbd0cb9287f4bae4d42f278a3b7e5943c8a11c;hp=d79f82f4dd53304cff41e5c5e82dfac108978f6d;hb=HEAD;hpb=a13574b2cae5945d2b0c5f1dbc85171e5c9bee9d diff --git a/README.md b/README.md index d79f82f..63bcfee 100644 --- a/README.md +++ b/README.md @@ -1,76 +1,242 @@ -AX-ZSH: Alex' Modular ZSH Configuration -======================================= +# 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. +AX-ZSH integrates well with [Powerlevel10k] and other extensions, even plugins +of [OhMyZsh], see [below](#integration-with-other-projects). -Installation ------------- +The homepage of [AX-ZSH] can be found at [GitHub]: +. -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 -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_ (https://github.com/alexbarton/ax-zsh): +* [ZSH] – obviously ;-) +* [Git] (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 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). -Now close and restart all your running ZSH session to activate AX-ZSH. +*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! -To update AX-ZSH run `axzshctl upgrade`. +### Installation using Git +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: -AX-ZSH & Local ZSH Configuration --------------------------------- +```sh +git clone https://github.com/alexbarton/ax-zsh.git ~/.axzsh +~/.axzsh/install.sh +``` -Plugins are loaded when they are linked into the `$AXZSH/active_plugins/` -directory; see the _Customization_ section below for how to activate them. +### Installation without Git -Don't modify `~/.zprofile`, `~/.zshrc`, `~/.zlogin`, or `~/.zlogout`! These -are links to "AX-ZSH"-private files that can become overwritten when updating. +*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! -You can use the following files for local ZSH configuration: +```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 +``` -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). +### Post-Installation Tasks -2. AX-ZSH reads the optional files `~/.zprofile.local`, `~/.zshrc.local`, - `~/.zlogin.local`, and `~/.zlogout.local` after its own core initialization - files when present. +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` +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] plugin from the OhMyZsh GitHub + repository (see ). + +You can enable one or more plugins like this: + +```sh +axzshctl enable-plugin [ […]] +``` + +*Hint:* *Tab-completion* works for sub-commands and already locally available +plugin names! + +Some examples: +```sh +# Enable some plugins bundled with AX-ZSH: +axzshctl enable-plugin editor_select git ssh_autoadd -Customization -------------- +# Enable the Powerlevel10k "theme plugin" from GitHub, see +# : +axzshctl enable-plugin romkatv/powerlevel10k -Use the `axzshctl` tool to enable, disable, and reset plugins. AXZSH -initializes an alias which points to the actual location in `~/.axzsh/bin/`. +# Enable the "fast-syntax-highlighting" plugin from GitHub, see +# : +axzshctl enable-plugin zdharma-continuum/fast-syntax-highlighting -See `axzshctl --help` for details. +# 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. +[OhMyZsh]) to specify additional plugin search directories. + +### 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 +``` -Environment Variables ---------------------- +### Other `axzshctl` sub-commands + +Please run `axzshctl --help` to get a full list of a available sub-commands: + +```sh +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 +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: @@ -79,13 +245,24 @@ 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` * `PS1` * `SHORT_HOST` * `TERM` -* `XDG_RUNTIME_DIR` +* `TMPDIR` (set and always ends with a "/") * `XDG_CACHE_HOME` +* `XDG_RUNTIME_DIR` * `ZSH_CACHE_DIR` + +___ +[AX-ZSH]: "AX-ZSH Homepage" +[Git]: "Git Homepage" +[GitHub]: "GitHub Homepage" +[OhMyZsh]: "OhMyZsh Homepage" +[Powerlevel10k]: "Powerlevel10k Homepage" +[ZSH]: "ZSH Homepage" + +[AX-ZSH] Copyright (c) 2015-2022 Alexander Barton