https://github.com/arielsalvo/zsh-config
My ZShell configuration
https://github.com/arielsalvo/zsh-config
zsh zsh-configuration zshell zshrc
Last synced: 10 months ago
JSON representation
My ZShell configuration
- Host: GitHub
- URL: https://github.com/arielsalvo/zsh-config
- Owner: arielsalvo
- License: mit
- Created: 2024-03-25T22:22:47.000Z (about 2 years ago)
- Default Branch: main
- Last Pushed: 2025-08-13T21:01:30.000Z (10 months ago)
- Last Synced: 2025-08-13T23:14:57.612Z (10 months ago)
- Topics: zsh, zsh-configuration, zshell, zshrc
- Language: Shell
- Homepage:
- Size: 105 KB
- Stars: 3
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Ari's ZShell configuration
## Intro and Basics
This is my own personal ZShell configuration so it matches my workflow/likes/needs.
Recommendations and PRs are appreciated but, if it doesn't improve the setup for me, you are probably better of forking and modifying it yourself.
* Based on [Zdharma-continuum:ZINIT](https://github.com/zdharma-continuum/zinit)
* Designed (sometimes over-designed) to be as modular as possible
* Portable
* MacOS
* Ubuntu
* Windows (WSL)
* Linux
## TLDR
* This repository should be cloned to `$ZDOTDIR` (preferrably: `$HOME/.config/zsh`)
* To enable the configuration, symlink `$ZDOTDIR/.zshenv` to `$HOME/.zshenv`
* $ZDOTDIR is implied from the real location of `.zshenv` (changing it is untested)
* The rest of the configuration is self-deployed during the first run
* Many packages are installed by the configuration:
* most within the ZINIT directory
* some exceptions using brew or apt
* Parts of the configuration are enabled by setting Feature Flags
## Requirements
### MacOs
* [homebrew](https://brew.sh/)
* tree
### Ubuntu
#### Linux
This configuration requires the following packages installed via package manager:
* zsh
* git
* make
* gcc
* tree
#### Windows (WSL)
This configuration requires the following packages installed via package manager:
* zsh
* git
* make
* gcc
* tree
* [Git.Git](https://winget.run/pkg/Git/Git) (in the Windows host)
## Playground
This repository can be cloned to a separate directory and the configuration tested in a docker container by using the docker-compose stack in the `_tests` directory.
## GIT Configuration
The setup of these is beyond the scope of this documentation and can be replaced by other mechanisms.
Not requiered for anonymous clones (not logged into GitHub)
### MacOS
I prefer using [1Password CLI](https://1password.com/downloads/command-line) and [GitHub CLI](https://cli.github.com/) to clone/sync the repository.
### Windows (WSL)
GIT must be already configured in the Windows host and able to connect and clone this GitHub repo.
This [article](https://learn.microsoft.com/en-us/windows/wsl/tutorials/wsl-git) can be consulted for details.
Run the following commands in the shell being installed:
```sh
git config --global credential.helper '/mnt/c/Program\ Files/Git/mingw64/bin/git-credential-manager.exe'
```
If this deployment is used to push code to the repository, these are required as well:
```sh
git config --global user.email ""
git config --global user.name ""
```
## Installation
Clone the repository:
```sh
git clone ~/.config/zsh
```
Enable the configuration:
```sh
ln -s ~/.config/zsh/.zshenv ~/.zshenv
```
## Feature Flags
### How to use
Feature flags are read from `${ZDOTDIR}/.featureflags` in the form of files that can be either empty (representing a `FLAG` or a default value for `VAR`) or contain some configuration parameter (representing a `VAR`). A feature flag with no file in this directory is interpreted as an `OFF` value for a `FLAG` or as `DEFAULT` for a `VAR`.
### Examples
#### Feature flag of type `VAR`
Selecting the default prompt:
```sh
echo -n "p10k" > ${ZDOTDIR}/.featureflags/DEFAULT_PROMPT
```
#### Feature flag of type `FLAG`
Enabling `pyenv`:
```sh
touch ~/.config/zsh/.featureflags/PYTHON
```
Keep in mind this will not install a Python interpreter (See [the Python section](Python) for instructions)
### Inventory
| Key/Filename | Type | Files | Purpose | Default | Values | Case Sensitivity |
| -- | -- | -- | -- | -- | -- | -- |
| `DEFAULT_PROMPT` | VAR | [89-prompt](zshrc.d/89-prompt.zsh) | Select the default prompt to install/use | `P10K` | ``
`P10K`
`STARSHIP`
`DEFAULT` | NO |
| `HISTORY_MANAGER` | VAR | [85-history](zshrc.d/85-history.zsh) | Select the history handler | `` | ``
`ATUIN` | NO |
| `HOOK_LOCAL` | FLAG | [09-local-pre.zsh](zshrc.d/09-local-pre.zsh)
[99-local-post.zsh](zshrc.d/99-local-post.zsh) | Enables the execution of `.zshrc.local.{pre,post}` if they exist in the home directory | OFF | `` | N/A |
| `PYTHON` | FLAG/VAR | [20-apps-05-python](zshrc.d/20-apps-05-python.zsh) | Enable installation of `python` via `asdf` and, if available, initialize `conda` | OFF | ``
`` | N/A |
| `TMUX` | FLAG | [03-tmux.zsh](zshrc.d/03-tmux.zsh) | Installs custom Oh-My-TMUX config | OFF | `` | N/A |
## Python
Once `python` has been enabled in `asdf` (See [Feature Flags](#Feature-Flags) for instructions), you can install a Python interpreter by setting the distro name in the `PYTHON` feature flag (recommended: `miniforge3-latest`).
```sh
echo -n "miniforge3-latest" > ${ZDOTDIR}/.featureflags/PYTHON
```
Open a new terminal.
The specified distro will be registered as the global Python interpreter (with `system` as fallback).
If the Python interpreter is `conda` based, the hooks will be installed, enabling environment activations.