lsd (LSDeluxe)

LSD can be installed via various package managers, from source using Cargo, or by downloading precompiled binaries.

Prerequisites

• Icons: To display icons, you must have a patched font like Nerd Fonts or Font Awesome installed and configured in your terminal.
• Source Installation: Requires a working Rust toolchain.

### Installing from source
With Rust's package manager cargo, you can install lsd via:
```sh
cargo install lsd

To enable Nerd Fonts for the URxvt terminal emulator, add the following line to your .Xresources file, replacing Hack Nerd Font with your specific installed Nerd Font name.

URxvt*font:    xft:Hack Nerd Font:style=Regular:size=11

Use the command corresponding to your operating system or distribution:

The lsd command provides an enhanced directory listing experience with colors and icons. You can list the current directory, a specific path, or use flags to modify the output format.

Basic Usage

• List current directory: lsd
• List a specific directory: lsd /path/to/dir
• List all entries (including hidden files): lsd -a or lsd --all
• List in long format (extended metadata): lsd -l or lsd --long
• Combine flags (e.g., long format including hidden files): lsd -la

You can customize icons using Nerd Font glyphs or Unicode emojis. lsd supports three types of icon overrides in icons.yaml:

• name: Matches specific file or directory names (e.g., .cargo).
• extension: Matches file extensions (e.g., rs).
• filetype: Matches general categories (e.g., dir, executable, symlink-file).

Custom icons are merged with the default set provided in the source.

name:
  .trash: 
  .cargo: 
  .emacs.d: 
  a.out: 
extension:
  go: 
  hs: 
  rs: 🦀
filetype:
  dir: 📂
  file: 📄
  pipe: 📩
  socket: 󰆨
  executable: 
  symlink-dir: 
  symlink-file: 
  device-char: 
  device-block: 󰜫
  special: 

To use lsd instead of the standard ls command, add an alias to your shell configuration file (e.g., ~/.bashrc, ~/.zshrc).

Basic replacement:

alias ls='lsd'

Useful productivity aliases:

alias l='lsd -l'
alias la='lsd -a'
alias lla='lsd -la'
alias lt='lsd --tree'

LSD's color settings are determined by two main components: when (how to use colors) and theme (which color scheme to use). These settings can be configured via CLI flags, the configuration file, or environment variables.

Color Usage (ColorOption)

Controls when colors are displayed in the output:

• always: Always use color.
• auto: Use color automatically (default behavior).
• never: Never use color.

Note: Enabling --classic mode (via CLI or config) forces the color option to never.

Theme Selection (ThemeOption)

Controls the color scheme applied:

• default: Use the built-in default theme.
• custom: Use a custom YAML theme file.
• no-color: Disable colors entirely.
• <path>: Provide a path to a custom legacy theme file.

Note: If classic mode is enabled in the configuration, the theme is automatically set to NoColor.

You can prevent lsd from displaying certain files or directories by using glob patterns. These patterns can be specified via the CLI or in your configuration file.

Precedence

If patterns are defined in multiple places, lsd follows this order of precedence:

1. CLI arguments (--ignore-glob)
2. Configuration file (ignore-globs)
3. Default value (an empty set, meaning nothing is ignored)

Usage

• CLI: Pass one or more patterns using the --ignore-glob flag.
• Config: In your configuration file, provide an array of strings under the ignore-globs key.

# CLI Example
lsd --ignore-glob ".git" --ignore-glob "node_modules"

# Configuration Example (YAML/JSON style)
ignore-globs: [ ".git", "node_modules" ]

The permission display format is determined by a hierarchy of settings:

1. CLI Flags: If --classic is passed, the format is set to rwx. Otherwise, the value provided to --permission takes precedence.
2. Configuration File: If the configuration file has classic = true, the format is set to rwx. Otherwise, the value of the permission key is used.
3. Defaults:
   • On non-Windows systems: rwx is the default.
   • On Windows systems: attributes is the default.