README.md

# Zsh Configuration README

This README explains the configuration of the `.zshrc` file and the plugins listed in `zsh_plugins.txt`. It also provides instructions for setting up Antidote (the Zsh plugin manager) and updating the plugins.

## Installation

Get the file from got repository:

    got clone ssh://anon@repo.vincentdelft.be/zsh
    got checkout zsh.git

    or 
    git clone ssh://anon@repo.vincentdelft.be/zsh zsh
    
    cp zsh/zshrc ~/.zshrc

## Overview of `.zshrc`

The `.zshrc` file is a configuration file for the Zsh shell, customizing the shell environment, prompt, key bindings, aliases, and plugins. Below is a breakdown of its sections and their purposes:

### Sections in `.zshrc`

1. **Colors**:
   - Enables color support in the shell using `autoload -U colors && colors` to allow colored prompts and completion highlights.

2. **Prompt & Right Prompt**:
   - Configures a custom prompt using `setopt prompt_subst` to enable dynamic prompt substitution.
   - The left prompt (`PROMPT`) shows:
     - A custom symbol (`#` for root, `$` for non-root) with the last command’s exit code.
     - The current directory (`%~`) and a connection status (`is_local` function).
   - The right prompt (`RPROMPT`) displays:
     - The current time in cyan.
     - Battery status (via `get_battery` function) with icons indicating charging state and percentage.

3. **Plugins (via Antidote)**:
   - Uses Antidote to manage plugins listed in `zsh_plugins.txt`.
   - Loads plugins with `source $HOME/.config/zsh/antidote/antidote.zsh` and `antidote load`.

4. **Completion**:
   - Initializes Zsh’s completion system with `autoload -Uz compinit && compinit`.
   - Enables case-insensitive completion using `zstyle ':completion:*' matcher-list`.
   - Colors completion items based on `LS_COLORS`.

5. **History**:
   - Configures history settings:
     - `HISTSIZE=5000`: Stores up to 5000 history entries in memory.
     - `HISTFILE=~/.zsh_history`: Saves history to a file.
     - `SAVEHIST=$HISTSIZE`: Saves all history entries to the file.
     - `HISTDUP=erase`: Removes duplicates.
     - Options like `appendhistory`, `sharehistory`, and `hist_ignore_dups` ensure efficient history management.
   - Sets `ZSH_AUTOSUGGEST_HIGHLIGHT_STYLE` for styling autosuggestion text.

6. **Key Bindings**:
   - Binds up/down arrow keys to search through command history (`history-search-backward` and `history-search-forward`).

7. **Aliases**:
   - Adds `ls --color` alias for FreeBSD systems.
   - Sets `v` as an alias for `nvim` (Neovim editor).

8. **Environment**:
   - Adds `$HOME/.local/bin` to the `PATH` for custom binaries.
   - Sets `WINIT_X11_SCALE_FACTOR=1` to adjust Alacritty terminal scaling.

9. **Functions**:
   - `get_battery`: Displays battery percentage and charging status (used in `RPROMPT`).
   - `is_local`: Customizes the prompt based on local or SSH connections.
   - `chpwd`: Updates the terminal window title to show the current directory when it changes.
   - `set_title`: Manually sets the terminal window title.
   - `ssh_title`: Updates the terminal title for SSH sessions.

10. **External Tools**:
    - Integrates `zoxide` for intelligent directory navigation with the `cd` command alias.

## Plugins in `zsh_plugins.txt`

The `zsh_plugins.txt` file lists plugins managed by Antidote. Below is an explanation of each plugin’s purpose:

- **zsh-users/zsh-syntax-highlighting**:
  - Provides real-time syntax highlighting for commands as you type.
  - Highlights valid commands in green, invalid ones in red, and other elements (e.g., paths, options) in different colors for better readability.

- **zsh-users/zsh-autosuggestions**:
  - Suggests commands based on your history as you type.
  - Suggestions appear in a faint color (configured via `ZSH_AUTOSUGGEST_HIGHLIGHT_STYLE`) and can be accepted with the right arrow key.

- **zsh-users/zsh-history-substring-search**:
  - Enables searching through command history using substrings.
  - Bound to up/down arrow keys (via `^[[A` and `^[[B`) for navigating matching history entries.

- **zsh-users/zsh-completions**:
  - Adds additional completion definitions for various commands and tools.
  - Enhances the completion system with more context-aware suggestions.

## Setting Up Antidote

Antidote is a lightweight Zsh plugin manager used to load the plugins listed in `zsh_plugins.txt`. Follow these steps to set it up:

1. **Install Antidote**:
   - Create the Antidote directory:
     ```bash
     mkdir -p $HOME/.config/zsh/antidote
     ```
   - Clone the Antidote repository:
     ```bash
     git clone --depth=1 https://github.com/mattmc3/antidote.git $HOME/.config/zsh/antidote
     ```

2. **Ensure `.zshrc` Loads Antidote**:
   - The `.zshrc` file already includes:
     ```bash
     source $HOME/.config/zsh/antidote/antidote.zsh
     antidote load $HOME/.config/zsh/zsh_plugins.txt
     ```
   - If not present, add these lines to your `.zshrc`.

3. **Create `zsh_plugins.txt`**:
   - Ensure the `zsh_plugins.txt` file exists at `$HOME/.config/zsh/zsh_plugins.txt` with the plugin list:
     ```
     zsh-users/zsh-syntax-highlighting
     zsh-users/zsh-autosuggestions
     zsh-users/zsh-history-substring-search
     zsh-users/zsh-completions
     ```

4. **Apply Changes**:
   - Source your `.zshrc` to apply the configuration:
     ```bash
     source ~/.zshrc
     ```

## Updating Plugins

To update the plugins managed by Antidote, run the following command:

```bash
antidote update
```

This command updates Antidote itself and all plugins listed in `zsh_plugins.txt` to their latest versions. After updating, source your `.zshrc` again to apply changes:

```bash
source ~/.zshrc
```

## Additional Notes

- **Dependencies**:
  - Ensure `zoxide` is installed for the `cd` alias to work (`eval "$(zoxide init --cmd cd zsh)"`).
  - On FreeBSD, `acpiconf` is used for battery status. Ensure it’s available or modify the `get_battery` function for other systems.
  - Neovim (`nvim`) is required for the `v` alias.

- **Customization**:
  - Modify `ZSH_AUTOSUGGEST_HIGHLIGHT_STYLE` to change the autosuggestion color.
  - Adjust `HISTSIZE` and `SAVEHIST` for larger or smaller history storage.
  - Customize the prompt colors or symbols in `PROMPT`, `RPROMPT`, or the `is_local` function.

- **Troubleshooting**:
  - If plugins fail to load, verify that Antidote is installed correctly and `zsh_plugins.txt` is in the right location.
  - Check for missing dependencies (e.g., `acpiconf` or `zoxide`) if functions or aliases don’t work.

This configuration provides a powerful, user-friendly Zsh environment with enhanced completion, history management, and a dynamic prompt.