README.md

September 2, 2026 · View on GitHub

Zsh eza

Zsh aliases and directory-listing behavior powered by eza.

Screenshot showing ll, ls, lx, and la directory-listing examples

Features

Eight eza-backed aliases for common list, long-list, and tree views.
Opinionated defaults for Git status, icons, groups, directory ordering, timestamps, and color scales.
Complete replacement or extension of the default eza arguments.
Optional automatic directory listing after cd.
Safe startup failure when eza is unavailable.
Reversible unload that restores aliases present before the plugin loaded.

Requirements

Zsh
eza available on PATH

Use the upstream eza installation guide to install the executable for your platform.

Installation

Zi

zi light z-shell/zsh-eza

To load only when eza exists and enable automatic listing after directory changes:

zstyle ':zsh-eza:config' autocd yes
zi ice has'eza'
zi light z-shell/zsh-eza

Other plugin managers

The plugin follows the Zsh Plugin Standard and can be sourced by other Zsh plugin managers.

Oh My Zsh custom plugin

git clone https://github.com/z-shell/zsh-eza \
  "${ZSH_CUSTOM:-$HOME/.oh-my-zsh/custom}/plugins/zsh-eza"

Add zsh-eza to the plugin list:

plugins=(... zsh-eza)

Zplug

zplug "z-shell/zsh-eza"

Antigen

antigen bundle z-shell/zsh-eza@main

Style Context	Style	Type	Default	Effect
`:zsh-eza:config`	`user-params`	Shell words	Unset	Replaces the complete default argument list.
`:zsh-eza:config`	`extra-params`	Shell words	Unset	Appends arguments after the selected defaults.
`:zsh-eza:config`	`autocd`	Boolean	`no`	Set to `yes` to list the new directory after `cd`.

The global parameters eza_user_params, eza_extra_params and AUTOCD were removed. Replace them with the :zsh-eza:config styles above. The parameter holding the resolved arguments is now _zsh_eza_params; it is private state, not a configuration entry point.

The default arguments are:

_zsh_eza_params=(
  '--git' '--icons' '--group' '--group-directories-first'
  '--time-style=long-iso' '--color-scale=all'
)

For example:

zstyle ':zsh-eza:config' extra-params '--classify --hyperlink=auto'
zstyle ':zsh-eza:config' autocd yes
zi light z-shell/zsh-eza

Aliases

Alias	Effective command	Purpose
`ls`	`eza ${(@)_zsh_eza_params}`	List with the configured defaults.
`l`	`eza --git-ignore ${(@)_zsh_eza_params}`	Hide Git-ignored entries.
`ll`	`eza --all --header --long ${(@)_zsh_eza_params}`	Show a detailed list including hidden entries.
`llm`	`eza --all --header --long --sort=modified ${(@)_zsh_eza_params}`	Show a detailed list sorted by modification time.
`la`	`eza -lbhHigUmuSa ${(@)_zsh_eza_params}`	Show an extended long listing.
`lx`	`eza -lbhHigUmuSa@ ${(@)_zsh_eza_params}`	Show an extended long listing with extended attributes.
`lt`	`eza --tree ${(@)_zsh_eza_params}`	Display a directory tree.
`tree`	`eza --tree ${(@)_zsh_eza_params}`	Display a directory tree.

Lifecycle and side effects

With TERM=dumb, the plugin returns successfully without defining aliases.
If eza is missing, loading returns a nonzero status without exiting the current shell.
Each load captures any existing aliases with the same names before replacement.
With autocd set to a true value, the plugin registers _zsh_eza_auto_list as a chpwd hook.
zsh-eza_plugin_unload removes the hook and plugin functions, removes plugin-owned state, and restores aliases captured by the most recent load. An alias changed after the plugin loaded is treated as user-owned and is left untouched.

Verification

The repository includes its ZUnit runner. From the repository root:

export ZSH_EZA_REPO="$PWD"
PATH="$PWD/bin:$PATH" zunit --tap --verbose tests/zsh-eza.zunit

The suite uses a fake eza executable; a system installation is not required for tests.

Documentation and support

Release model

zsh-eza is consumed directly from Git and uses trunk-based development on main. Create feature-<id>, bug-<id>, or hotfix-<id> branches from main and target pull requests back to main. Merges do not create a package release.

Contributing and license

Contributions follow the Z-Shell organization guidance. This project is distributed under the terms in LICENSE.