= Zsh Configuration for Alpine Linux :proj-name: alpine-zsh-config :gh-name: jirutka/{proj-name} // Enable kbd:[] macro :experimental: :osc133-spec-url: https://gitlab.freedesktop.org/Per_Bothner/specifications/blob/master/proposals/semantic-prompts.md
ifdef::env-github[] image:https://github.com/{gh-name}/workflows/CI/badge.svg[Binaries Workflow, link=https://github.com/{gh-name}/actions?query=workflow%3A%22CI%22] endif::env-github[]
The aim of this project is to provide a sensible default (system-wide) https://www.zsh.org/[Zsh] configuration that will meet the basic needs and expectations of most users. In other words, make Zsh easy to use right out of the box, without having to configure it, while not getting in the way of individual user customization.
== Features
- XDG-based locations for Zsh data and cache files. ^link:zshrc.d/10-base-dirs.zsh[10-base-dirs.zsh]^
- Some basic aliases that most people expect. ^link:zshrc.d/50-aliases.zsh[50-aliases.zsh]^
- Command not found handler for apk-tools. ^link:zshrc.d/50-command-not-found.zsh[50-command-not-found.zsh]^
- Reasonable history defaults. ^link:zshrc.d/50-history.zsh[50-history.zsh]^
- Global <<Key Bindings,key bindings>> consistent with
/etc/inputrc(and thus with ash, bash and any other program using readline). ^link:zshrc.d/50-key-bindings.zsh[50-key-bindings.zsh]^ - Miscellaneous useful options. ^link:zshrc.d/50-misc.zsh[50-misc.zsh]^
- Support for {osc133-spec-url}[OSC 133 Semantic Prompt] footnote:[OSC 133 allows terminal features such as jumping to the previous/next prompt in the scrollback or opening the output of the last command in a pager. It is supported e.g. in Kitty, WezTerm, iTerm2.]. ^link:zshrc.d/50-semantic-prompt.zsh[50-semantic-prompt.zsh]^
- Integration with the system clipboard – copies the kill (cut) buffer to the system clipboard on each change (e.g. on kbd:[Ctrl + Insert], kbd:[Ctrl + W], …). ^link:zshrc.d/70-clipboard.zsh[70-clipboard.zsh]^
- Initialization of the completion system with reasonable defaults and caching. ^link:zshrc.d/70-completion.zsh[70-completion.zsh]^
TIP: If you as a user want to disable some of these features, define variable zshrc_blacklist with an array of the script names (without .zsh suffix) in your $ZDOTDIR/.zshenv footnote:zshenv[$ZDOTDIR/.zshenv is by default ~/.config/zsh/.zshenv, or ~/.zshenv if ~/.zshrc exists.], for example: zshrc_blacklist=(50-command-not-found 70-completion).
=== Key Bindings
List of key bindings defined in the emacs, viins, and vicmd keymaps.
- kbd:[Home] – move cursor to the beginning of a line
- kbd:[End] – move cursor to the end of a line
- kbd:[Delete] – delete the next character
- kbd:[Page Up] – move cursor up a line, or if already at the top line, move to the previous event in the history
- kbd:[Page Down] – move cursor down a line, or if already at the bottom line, move to the next event in the history
- kbd:[Up Arrow] – move cursor up a line, or if already at the top line, fuzzy search backward in the history for a line beginning with a whole line prefix up to the cursor position
- kbd:[Down Arrow] – move cursor down a line, or if already at the bottom line, fuzzy search forward in the history for a line beginning with a whole line prefix up to the cursor position
- kbd:[Shift + Tab] – perform menu completion, or if a menu completion is already in progress, move to the previous completion
- kbd:[Ctrl + Insert] – copy the area from cursor to the mark to the kill buffer and clipboard (if available)
- kbd:[Ctrl + Delete] – delete (and copy) the next word
- kbd:[Ctrl + Left Arrow] – move cursor to the beginning of the previous word
- kbd:[Ctrl + Right Arrow] – move cursor to the beginning of the next word
== Configuration Variables
Users can define the following configuration variables in their $ZDOTDIR/.zshenvfootnote:zshenv[] to override the default settings.
|=== | Variable Name | Default Value | Description
| ZSH_CACHE_DIR
| $XDG_CACHE_HOME/zsh or $HOME/.cache/zsh
| Path to a directory where to store cache files (e.g. completion cache). If it doesn’t exist, it will be created.
| ZSH_DATA_DIR
| $XDG_DATA_HOME/zsh or $HOME/.local/share/zsh
| Path to a directory where to store persistent data files (e.g. Zsh history). If it doesn’t exist, it will be created.
| ZSH_COMPDUMP
| $ZSH_CACHE_DIR/zcompdump
| Path to the Zsh completion dump file.
| HISTFILE
| $ZSH_DATA_DIR/history or $ZDOTDIR/.zsh_history or $HOME/.zsh_history
| Path to the Zsh history file. If ${ZDOTDIR:-$HOME}/.zsh_history exists, it will be preferred.
| ZSH_CUTBUFFER_CLIPBOARD
| "primary"
| The system clipboard to synchronize the kill (cut) buffer with; either "primary" (selection), or "clipboard" (regular clipboard).
| osc52_supported_terms
| ('alacritty' 'foot' 'xterm-kitty')
| An array of $TERM values that identify terminals with OSC 52 support (access to system clipboard). This is just a shortcut to skip dynamic detection using tty-copy --test for known terminals.
|===
== Requirements
- https://pkgs.alpinelinux.org/packages?name=zsh[zsh] >=5.8.1-r1
- https://pkgs.alpinelinux.org/packages?name=wl-clipboard[wl-clipboard], https://pkgs.alpinelinux.org/packages?name=xclip[xclip] or https://pkgs.alpinelinux.org/packages?name=tty-copy[tty-copy] for integration with the system clipboard (optional)
== Installation
Install package https://pkgs.alpinelinux.org/packages?name={proj-name}[{proj-name}] on Alpine Linux Edge, v3.16 or later:
[source, sh, subs="+attributes"] apk add {proj-name}
== License
This project is licensed under http://opensource.org/licenses/MIT/[MIT License]. For the full text of the license, see the link:LICENSE[LICENSE] file.