eza Deployment and Usage Guide

1. Prerequisites

Runtime Requirements:

A Unix-like system (Linux, macOS) or Windows
Terminal with color support (for full functionality)
Git (for cloning and version control)

Development Requirements (for building from source):

Rust toolchain (rustc and cargo) - version 1.70 or later recommended
C compiler (for building dependencies)
pkg-config (on Unix systems)
libgit2 development headers (for Git integration)

Optional Dependencies:

Nix package manager (for Nix-based installation)
Terminal that supports hyperlinks (for hyperlink display feature)
SELinux-enabled system (for SELinux context display)

2. Installation

Package Manager Installation (Recommended)

Linux (using package manager):

# Ubuntu/Debian
sudo apt install eza

# Fedora
sudo dnf install eza

# Arch Linux
sudo pacman -S eza

# NixOS/Nix
nix-env -iA nixos.eza

macOS:

# Homebrew
brew install eza

# MacPorts
sudo port install eza

Windows:

# Scoop
scoop install eza

# Chocolatey
choco install eza

Cargo Installation (from crates.io)

cargo install eza

Building from Source

# Clone the repository
git clone https://github.com/eza-community/eza.git
cd eza

# Build and install
cargo build --release
sudo cp target/release/eza /usr/local/bin/

# Or install directly with cargo
cargo install --path .

Nix Flake (Development/Testing)

# Run directly without installation
nix run github:eza-community/eza

# Run with arguments
nix run github:eza-community/eza -- -ol

3. Configuration

Environment Variables

# Force color output
export EXA_COLORS="reset"

# Customize colors using LS_COLORS format
export LS_COLORS="di=34:ln=35:so=32:pi=33:ex=31:bd=34;46:cd=34;43:su=30;41:sg=30;46:tw=30;42:ow=30;43"

# Enable icons
export EXA_ICON_SPACING=1

# Set time format
export TIME_STYLE="long-iso"

Theme Configuration File

eza supports a theme.yml configuration file for customizing colors and icons:

Create the configuration directory:

mkdir -p ~/.config/eza

Create ~/.config/eza/theme.yml with your customizations:

colourful: true

filekinds:
  normal: { fg: "default", bg: "none" }
  directory: { fg: "blue", bg: "none", bold: true }
  symlink: { fg: "cyan", bg: "none" }
  pipe: { fg: "yellow", bg: "none" }
  socket: { fg: "magenta", bg: "none" }
  block_device: { fg: "yellow", bg: "blue", bold: true }
  char_device: { fg: "yellow", bg: "brown", bold: true }

filenames:
  "README.md":
    icon: { glyph: "📚", style: { fg: "cyan" } }
    filename: { fg: "cyan", bold: true }
  
  "*.rs":
    icon: { glyph: "🦀", style: { fg: "red" } }
    filename: { fg: "red" }

extensions:
  "png":
    icon: { glyph: "🖼️", style: { fg: "green" } }
    filename: { fg: "green" }
  
  "zip":
    icon: { glyph: "🗜️", style: { fg: "yellow" } }
    filename: { fg: "yellow" }

Git Integration

eza automatically detects Git repositories and shows status indicators. No additional configuration is needed, but ensure Git is installed for this feature.

4. Build & Run

Development Build

# Clone the repository
git clone https://github.com/eza-community/eza.git
cd eza

# Build in debug mode (faster compilation)
cargo build

# Test the build
./target/debug/eza --version

# Run with specific options
./target/debug/eza -l --git

Production/Release Build

# Optimized build
cargo build --release

# The binary will be at:
./target/release/eza

# Install system-wide
sudo cp ./target/release/eza /usr/local/bin/

Testing Features

# Test color scale modes
eza -l --color-scale=age --color-scale-mode=gradient
eza -l --color-scale=size --color-scale-mode=fixed

# Test hyperlink support
eza --hyperlink

# Test mount point details
eza -l --mounts

# Test SELinux context (on SELinux systems)
eza -l --context

5. Deployment

Binary Distribution

Since eza is a single binary with no runtime dependencies beyond standard system libraries, deployment is straightforward:

Cross-compilation (for distributing to different platforms):

# Install cross-compilation target
rustup target add x86_64-unknown-linux-musl

# Build static binary for Linux
cargo build --release --target x86_64-unknown-linux-musl

# The binary will be at:
./target/x86_64-unknown-linux-musl/release/eza

Docker Deployment:

# Create a minimal Docker image
FROM alpine:latest
COPY target/release/eza /usr/local/bin/eza
ENTRYPOINT ["eza"]

Platform Recommendations

For end-users:

Package managers: Best for most users (apt, dnf, pacman, brew, etc.)
Cargo install: Good for Rust developers
Direct binary download: For systems without package managers

For system administrators:

Build from source: For custom patches or specific optimizations
Nix/Guix: For reproducible deployments
Configuration management: Include in Ansible, Puppet, or Chef recipes

For containerized environments:

Alpine Linux: Small image size (~5MB with eza)
Distroless: Minimal runtime containers
Build in CI/CD: Automated binary distribution

6. Troubleshooting

Common Issues and Solutions

1. Colors not displaying:

# Force color output
eza --color=always

# Check terminal color support
echo $TERM

# Test with simple command
eza --color=always | cat

2. Icons not showing:

# Enable icons explicitly
eza --icons=always

# Check if your terminal supports the icon font
# Install a Nerd Font or similar icon font

3. Git status not appearing:

# Ensure Git is installed
git --version

# Run with explicit Git flag
eza --git

# Check Git repository status
git status

4. Permission issues:

# Build without installing
cargo build --release && ./target/release/eza

# Install to user directory
cargo install --path . --root ~/.local
export PATH="$HOME/.local/bin:$PATH"

5. Theme configuration not loading:

# Check theme file location
ls ~/.config/eza/theme.yml

# Use verbose mode to see loaded configuration
eza --verbose

# Test with explicit theme path
eza --theme=~/.config/eza/theme.yml

6. SELinux context not showing:

# Check if SELinux is enabled
getenforce

# Run with context flag
eza -l --context

# May require additional permissions on some systems

7. Hyperlinks not working:

# Ensure terminal supports OSC 8
echo -e '\e]8;;https://example.com\e\\This is a link\e]8;;\e\\'

# Try different terminal emulators
# (Warp, iTerm2, Kitty, and newer versions of others support hyperlinks)

8. Build failures:

# Update Rust toolchain
rustup update

# Clear cargo cache
cargo clean

# Check dependencies
sudo apt install build-essential pkg-config libgit2-dev  # Ubuntu/Debian
sudo dnf install gcc pkgconfig libgit2-devel            # Fedora
brew install pkg-config libgit2                         # macOS

9. "The Grid Bug" or alignment issues:

# Use alternative view modes
eza -1      # One line per file
eza -l      # Long view
eza -x      # Sort across instead of down

# Set explicit terminal width
eza -w 80

For additional help, consult the Matrix room: #eza-community:gitter.im or check the GitHub issues for known problems and solutions.

How to Deploy & Use eza