Zsh eza

Zsh aliases and directory-listing behavior powered by eza.

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

Configuration

Set configuration before loading the plugin using standard zstyle contexts.

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.

Important

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

• Z-Shell plugin gallery
• Zsh Plugin Standard
• Report an issue

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.