LSPlus - an 'ls' clone written in Rust

LSPlus is a functional Unix ls clone written in Rust. I built it as a Rust learning project, so some code may still show beginner decisions.

• Compatibility
• Nerd Fonts
• Installation
  • Download a Binary
  • Using Cargo
  • Using "cargo-binstall"
  • From Source
• Usage
  • Fuzzy Time
  • Icons
  • Compatibility Mode
  • Configuration File
  • Aliases
• Development
• Future Plans

Compatibility

LSPlus supports Unix-like systems: Linux, macOS, and similar platforms. Windows support is on the roadmap.

Nerd Fonts

To display the folder and file icons, you need to first install a 'Nerd Font' for your terminal. You can find a great selection of Nerd Fonts from the Nerd Fonts website

My personal favourite is MesoLG Nerd Font, but there are many others to choose from. You will also need to set up your terminal to use that font.

If you DO NOT want to install a Nerd Font, pass the --no-icons switch to the program (or no_icons=true in the config file).

Installation

Download a Binary

Download the latest Linux or macOS archive from the release page. Unpack it, move lsp into a directory on your PATH, and make it executable if needed.

These binaries are auto-generated for each release.

Using Cargo

If you have rust installed, you can install the latest release of this package, using the following command:

cargo install lsplus

This will install the lsp binary into your ~/.cargo/bin directory. Make sure that this directory is in your PATH environment variable so that you can run the lsp command from anywhere. See the binstall section below for a quicker way to install using cargo.

Using "cargo-binstall"

If you have cargo-binstall installed, you can install lsplus more quickly and easily using:

cargo binstall lsplus

This will install the latest binary into your cargo bin folder without needing compilation.

From Source

You can also install the package from the GitHub repository by running the following command:

cargo install --git https://github.com/seapagan/lsplus.git

Usage

Run this command in your terminal to list files in the current directory:

lsp <options> <path | file>

Options and paths are optional. With no path, lsp lists the current directory. With no options, it uses defaults similar to ls.

Currently, only a sub-set of the standard ls options are supported. These are:

• -a / --all - Show hidden files
• -A / --almost-all - Show hidden files, but don't show . and ..
• -p / --slash-dirs - Append a '/' to directories
• --file-type - Append type indicators except * for executables
• -F / --classify - Append type indicators, including * for executables
• --no-indicators - Disable file type indicators
• -l / --long - Show long format listing
• --permissions <MODE> - Select long-format permission display: symbolic, octal, both, or none
• -h / --human-readable - Human readable file sizes using powers of 1024
• --si - Human readable file sizes using powers of 1000
• -D / --sort-dirs - Sort directories first
• -I / --gitignore - Dim entries matched by Git ignore rules
• -N / --no-color - Disable colored and styled output
• --no-permission-colors - Disable long-format file type character and permission colors
• --no-time-gradient - Use the fixed long-format timestamp color
• --no-size-colors - Disable long-format large-size colors
• --no-icons - don't show file or folder icons
• -V / --version - Print version information and exit
• -Z / --fuzzy-time - Show fuzzy time for file modification times

You can combine the short options together, e.g. -laph will show a long format listing with hidden files, append a '/' to directories, and show human-readable file sizes.

Use the --help option to see the full list of options.

The indicator characters are:

• / for directories
• @ for symlinks
• | for FIFOs
• = for sockets
• * for executables, but only with -F / --classify

In long format, native mode omits the symlink @ marker because name -> target and the symlink styling already make the type clear. This also matches GNU ls, which does not append @ to symlink names in long format.

When -I is enabled, lsp checks the same ignore sources Git normally uses: merged .gitignore files in the worktree, .git/info/exclude, and the configured global Git excludes file.

Styled output is enabled automatically when writing to a terminal. Captured, piped, and redirected output is plain by default. You can also disable styled output explicitly with --no-color, no_color = true in the config file, or the NO_COLOR environment variable.

Long-format output shows symbolic permissions by default. Use --permissions octal to replace them with octal permission bits, --permissions both to add octal bits after the symbolic field, or --permissions none to omit permission fields.

Long-format output colors permission bits, timestamp freshness, and large file sizes by default. You can adjust those accents independently with --no-permission-colors, --no-time-gradient, --no-size-colors, or the matching permission_colors = false, time_gradient = false, and size_colors = false config options.

Timestamp colors adapt to terminal color capability. Truecolor terminals use a smooth age gradient and 256-color terminals use a stepped fallback to distinguish files newer than a day, week, month, and year. Basic ANSI terminals use named yellow styling. Disabling time_gradient keeps normal timestamps on the original fixed timestamp color. Future-dated timestamps stay red to make clock-skewed files stand out.

Fuzzy Time

The -Z option will show a fuzzy time for file modification times. This will show the time in a human-readable format, e.g. '2 hours ago', 'yesterday', etc.

Icons

lsp shows icons for folders, files, and links. The current mappings cover common names and extensions. Open an issue or PR if you want another icon.

You can disable the icons by using the --no-icons option.

Compatibility Mode

lsp has two CLI modes:

• native - the default lsplus command-line interface
• gnu - a GNU ls compatibility mode intended for aliases and scripts

You can enable GNU compatibility mode in either of these ways:

compat_mode = "gnu"

or:

LSP_COMPAT_MODE=gnu lsp

The LSP_COMPAT_MODE environment variable takes precedence over the config file.

At the moment, compatibility mode only changes the CLI surface and help output. It does not yet implement the missing GNU meanings for the conflicting short flags -D, -I, -N, and -Z; those flags are reserved in gnu mode and will error until their GNU behavior is implemented.

The current lsplus features behind those four native short flags are still available in gnu mode through their long forms only:

• --group-directories-first (replaces the original --sort-dirs)
• --gitignore
• --no-color
• --fuzzy-time

GNU indicator options are also available in gnu mode:

• -p / --indicator-style=slash
• --file-type / --indicator-style=file-type
• -F / --indicator-style=classify
• --indicator-style=none

Configuration File

Put options in the config file to apply them to each run instead of passing them on the command line. See the relevant section on the website for full details.

Aliases

The lsp command can be aliased to ls by adding the following line to your .bashrc, .zshrc or similar file:

alias ls='lsp'

If you want that alias to behave more like GNU ls, enable gnu compatibility mode in your config file or set LSP_COMPAT_MODE=gnu in your shell environment.

You will need to restart your shell or source your configuration file for the alias to take effect.

The example below shows an alias for ls that uses many of the current options:

alias ls='lsp -laph'

This will show a long format listing with hidden files, append a '/' to directories, and show human readable file sizes, as in the image above.

Development

This repo uses husky-rs to manage local Git hooks for contributors. After cloning the repo, run:

cargo test

That installs the versioned hooks from .husky/ for this checkout. The hooks currently run:

• cargo fmt --check
• cargo clippy --all-targets --all-features -- -D warnings
• cargo test on pre-push

cargo-make and cargo-deny are separate Cargo subcommands, so contributors who want the full local tooling workflow should install them explicitly. They are used for the repo's preferred task aliases such as cargo make test, cargo make test-html, cargo make audit, and cargo make deny. Install them with:

cargo install cargo-make
cargo install cargo-deny

Future Plans

See TODO for planned work.