2020-10-13 20:50:27 +00:00
< div align = "center" >
2021-08-12 15:18:56 +00:00
2023-07-29 12:09:05 +00:00
# eza
2014-05-22 12:55:11 +00:00
2023-07-29 12:09:05 +00:00
eza is a modern replacement for _ls_ .
2014-06-28 11:20:50 +00:00
2020-10-13 20:50:27 +00:00
**README Sections:** [Options ](#options ) — [Installation ](#installation ) — [Development ](#development )
2018-10-21 11:56:09 +00:00
2023-07-30 05:06:24 +00:00
[![Unit tests ](https://github.com/cafkafk/eza/actions/workflows/unit-tests.yml/badge.svg )](https://github.com/cafkafk/eza/actions/workflows/unit-tests.yml)
2020-10-13 20:50:27 +00:00
< / div >
2014-05-22 12:55:11 +00:00
2015-11-23 19:48:30 +00:00
![Screenshots of exa ](screenshots.png )
2014-06-28 11:20:50 +00:00
2020-10-13 20:50:27 +00:00
---
2023-07-29 12:09:05 +00:00
**eza** is a modern replacement for the venerable file-listing command-line program `ls` that ships with Unix and Linux operating systems, giving it more features and better defaults.
2020-10-13 20:50:27 +00:00
It uses colours to distinguish file types and metadata.
It knows about symlinks, extended attributes, and Git.
And it’ s **small** , **fast** , and just **one single binary** .
2023-07-29 12:09:05 +00:00
By deliberately making some decisions differently, eza attempts to be a more featureful, more user-friendly version of `ls` .
2020-10-13 20:50:27 +00:00
For more information, see [exa’ s website ](https://the.exa.website/ ).
2014-12-12 15:15:35 +00:00
2023-07-29 16:44:32 +00:00
---
< a id = "try-it" >
< h1 > Try it!< / h1 >
< / a >
2023-07-29 16:48:45 +00:00
### Nix ❄️
2023-07-29 16:44:32 +00:00
If you already have Nix setup with flake support, you can try out eza with the `nix run` command:
nix run github:cafkafk/eza
2023-07-29 16:46:44 +00:00
Nix will build eza and run it.
2023-07-29 16:45:30 +00:00
If you want to pass arguments this way, use e.g. `nix run github:cafkafk/eza -- -ol` .
2023-07-29 16:44:32 +00:00
< a id = "installation" >
< h1 > Installation< / h1 >
< / a >
eza is available for macOS and Linux.
### Cargo
If you already have a Rust environment set up, you can use the `cargo install` command:
cargo install eza
Cargo will build the `eza` binary and place it in `$HOME/.cargo` .
To build without Git support, run `cargo install --no-default-features eza` is also available, if the requisite dependencies are not installed.
2020-10-13 20:50:27 +00:00
---
2014-06-28 11:20:50 +00:00
2020-10-13 20:50:27 +00:00
< a id = "options" >
< h1 > Command-line options< / h1 >
< / a >
2015-11-19 13:21:49 +00:00
2023-07-29 12:09:05 +00:00
eza’ s options are almost, but not quite, entirely unlike `ls` ’ s.
2020-10-13 20:50:27 +00:00
### Display options
2015-11-19 13:21:49 +00:00
- **-1**, ** --oneline**: display one entry per line
2017-05-06 22:00:45 +00:00
- **-G**, ** --grid**: display entries as a grid (default)
2015-11-19 13:21:49 +00:00
- **-l**, ** --long**: display extended details and attributes
- **-R**, ** --recurse**: recurse into directories
2017-05-06 22:00:45 +00:00
- **-T**, ** --tree**: recurse into directories as a tree
- **-x**, ** --across**: sort the grid across, rather than downwards
2019-11-12 00:18:51 +00:00
- **-F**, ** --classify**: display type indicator by file names
2017-05-06 22:00:45 +00:00
- **--colo[u]r**: when to use terminal colours
- **--colo[u]r-scale**: highlight levels of file sizes distinctly
2019-11-12 00:18:51 +00:00
- **--icons**: display icons
2021-02-27 20:48:00 +00:00
- **--no-icons**: don't display icons (always overrides --icons)
2023-04-12 04:51:06 +00:00
- **--hyperlink**: display entries as hyperlinks
2015-05-07 15:53:20 +00:00
2020-10-13 20:50:27 +00:00
### Filtering options
2015-05-07 15:53:20 +00:00
2017-06-29 12:24:55 +00:00
- **-a**, ** --all**: show hidden and 'dot' files
2017-05-06 22:00:45 +00:00
- **-d**, ** --list-dirs**: list directories like regular files
- **-L**, ** --level=(depth)**: limit the depth of recursion
- **-r**, ** --reverse**: reverse the sort order
- **-s**, ** --sort=(field)**: which field to sort by
2015-11-19 13:21:49 +00:00
- **--group-directories-first**: list directories before other files
2018-10-26 23:41:27 +00:00
- **-D**, ** --only-dirs**: list only directories
2017-09-27 12:46:36 +00:00
- **--git-ignore**: ignore files mentioned in `.gitignore`
2016-10-30 14:47:38 +00:00
- **-I**, ** --ignore-glob=(globs)**: glob patterns (pipe-separated) of files to ignore
2015-05-07 15:53:20 +00:00
2017-06-29 12:24:55 +00:00
Pass the `--all` option twice to also show the `.` and `..` directories.
2020-10-13 20:50:27 +00:00
### Long view options
2015-05-07 15:53:20 +00:00
2020-10-13 20:50:27 +00:00
These options are available when running with `--long` (`-l`):
2015-05-07 15:53:20 +00:00
2017-05-06 22:00:45 +00:00
- **-b**, ** --binary**: list file sizes with binary prefixes
- **-B**, ** --bytes**: list file sizes in bytes, without any prefixes
2020-10-13 20:50:27 +00:00
- **-g**, ** --group**: list each file’ s group
2017-05-06 22:00:45 +00:00
- **-h**, ** --header**: add a header row to each column
2020-10-13 20:50:27 +00:00
- **-H**, ** --links**: list each file’ s number of hard links
- **-i**, ** --inode**: list each file’ s inode number
2017-05-06 22:00:45 +00:00
- **-m**, ** --modified**: use the modified timestamp field
2020-10-13 20:50:27 +00:00
- **-S**, ** --blocks**: list each file’ s number of file system blocks
2017-05-06 22:00:45 +00:00
- **-t**, ** --time=(field)**: which timestamp field to use
- **-u**, ** --accessed**: use the accessed timestamp field
- **-U**, ** --created**: use the created timestamp field
2021-04-25 13:00:58 +00:00
- **-Z**, ** --context**: list each file’ s security context
2020-10-13 20:50:27 +00:00
- **-@**, ** --extended**: list each file’ s extended attributes and sizes
2019-11-12 00:18:51 +00:00
- **--changed**: use the changed timestamp field
2020-10-13 20:50:27 +00:00
- **--git**: list each file’ s Git status, if tracked or ignored
2017-07-05 23:52:27 +00:00
- **--time-style**: how to format timestamps
2019-08-29 12:34:30 +00:00
- **--no-permissions**: suppress the permissions field
2023-02-23 22:57:54 +00:00
- **-o**, ** --octal-permissions**: list each file's permission in octal format
2019-08-29 12:34:30 +00:00
- **--no-filesize**: suppress the filesize field
- **--no-user**: suppress the user field
- **--no-time**: suppress the time field
2017-05-06 22:00:45 +00:00
2020-10-13 20:50:27 +00:00
Some of the options accept parameters:
2017-05-06 22:00:45 +00:00
- Valid ** --color** options are **always** , **automatic** , and **never** .
2018-12-17 04:46:50 +00:00
- Valid sort fields are **accessed** , **changed** , **created** , **extension** , **Extension** , **inode** , **modified** , **name** , **Name** , **size** , **type** , and **none** . Fields starting with a capital letter sort uppercase before lowercase. The modified field has the aliases **date** , **time** , and **newest** , while its reverse has the aliases **age** and **oldest** .
- Valid time fields are **modified** , **changed** , **accessed** , and **created** .
2022-04-30 12:38:45 +00:00
- Valid time styles are **default** , **iso** , **long-iso** , **full-iso** , and **relative** .
2014-06-28 11:20:50 +00:00
2014-12-12 15:15:35 +00:00
2020-10-13 20:50:27 +00:00
---
< a id = "development" >
< h1 > Development
2023-03-01 03:41:51 +00:00
< a href = "https://blog.rust-lang.org/2022/08/11/Rust-1.63.0.html" >
< img src = "https://img.shields.io/badge/rustc-1.63.0+-lightgray.svg" alt = "Rust 1.63.0+" / >
2020-10-13 20:50:27 +00:00
< / a >
< a href = "https://github.com/ogham/exa/blob/master/LICENCE" >
< img src = "https://img.shields.io/badge/licence-MIT-green" alt = "MIT Licence" / >
< / a >
< / h1 > < / a >
2023-07-29 12:09:05 +00:00
eza is written in [Rust ](https://www.rust-lang.org/ ).
2021-08-12 14:46:37 +00:00
You will need rustc version 1.56.1 or higher.
2020-10-13 20:50:27 +00:00
The recommended way to install Rust for development is from the [official download page ](https://www.rust-lang.org/tools/install ), using rustup.
2023-07-29 12:09:05 +00:00
Once Rust is installed, you can compile eza with Cargo:
2020-10-13 20:50:27 +00:00
2022-01-14 23:25:27 +00:00
cargo build
cargo test
2020-10-13 20:50:27 +00:00
2020-10-14 21:20:37 +00:00
- The [just ](https://github.com/casey/just ) command runner can be used to run some helpful development commands, in a manner similar to `make` .
2022-04-01 13:26:51 +00:00
Run `just --list` to get an overview of what’ s available.
2020-10-13 20:50:27 +00:00
2020-10-14 21:20:37 +00:00
- If you are compiling a copy for yourself, be sure to run `cargo build --release` or `just build-release` to benefit from release-mode optimisations.
Copy the resulting binary, which will be in the `target/release` directory, into a folder in your `$PATH` .
`/usr/local/bin` is usually a good choice.
- To compile and install the manual pages, you will need [pandoc ](https://pandoc.org/ ).
The `just man` command will compile the Markdown into manual pages, which it will place in the `target/man` directory.
To use them, copy them into a directory that `man` will read.
`/usr/local/share/man` is usually a good choice.
2023-07-29 12:09:05 +00:00
- eza depends on [libgit2 ](https://github.com/rust-lang/git2-rs ) for certain features.
2020-10-13 20:50:27 +00:00
If you’ re unable to compile libgit2, you can opt out of Git support by running `cargo build --no-default-features` .
2020-10-14 21:20:37 +00:00
- If you intend to compile for musl, you will need to use the flag `vendored-openssl` if you want to get the Git feature working.
2020-10-13 20:50:27 +00:00
The full command is `cargo build --release --target=x86_64-unknown-linux-musl --features vendored-openssl,git` .
For more information, see the [Building from Source page ](https://the.exa.website/install/source ).
2023-07-29 17:01:08 +00:00
### Developing on Nix (experimental) ❄️
If you have a working Nix installation with flake support, you can use nix to manage your dev environment.
nix develop
The Nix Flake has a few features:
- Run `nix flake check` to run `treefmt` on the repo.
- Run `nix build` and manually test `./results/bin/eza -- <arguments>` for easy debugging.
- Run `nix build .#test` to run `cargo test` via the flake.
- Run `nix build .#clippy` to lint with clippy (still work in progress).
2020-10-13 20:50:27 +00:00
### Testing with Vagrant
2016-10-07 18:31:03 +00:00
2023-07-29 12:09:05 +00:00
eza uses [Vagrant][] to configure virtual machines for testing.
2016-10-07 18:31:03 +00:00
2023-07-29 12:09:05 +00:00
Programs such as eza that are basically interfaces to the system are [notoriously difficult to test][testing].
2020-10-13 20:50:27 +00:00
Although the internal components have unit tests, it’ s impossible to do a complete end-to-end test without mandating the current user’ s name, the time zone, the locale, and directory structure to test.
(And yes, these tests are worth doing. I have missed an edge case on many an occasion.)
2016-10-07 18:31:03 +00:00
2023-07-29 12:09:05 +00:00
The initial attempt to solve the problem was just to create a directory of “awkward” test cases, run eza on it, and make sure it produced the correct output.
2020-10-13 20:50:27 +00:00
But even this output would change if, say, the user’ s locale formats dates in a different way.
These can be mocked inside the code, but at the cost of making that code more complicated to read and understand.
2016-10-07 18:31:03 +00:00
2020-10-13 20:50:27 +00:00
An alternative solution is to fake *everything* : create a virtual machine with a known state and run the tests on *that* .
This is what Vagrant does.
Although it takes a while to download and set up, it gives everyone the same development environment to test for any obvious regressions.
2016-10-07 18:31:03 +00:00
2019-05-28 21:30:18 +00:00
[Vagrant]: https://www.vagrantup.com/
2016-10-07 18:31:03 +00:00
[testing]: https://eev.ee/blog/2016/08/22/testing-for-people-who-hate-testing/#troublesome-cases
First, initialise the VM:
host$ vagrant up
2023-07-29 12:09:05 +00:00
The first command downloads the virtual machine image, and then runs our provisioning script, which installs Rust and eza’ s build-time dependencies, configures the environment, and generates some awkward files and folders to use as test cases.
2020-10-13 20:50:27 +00:00
Once this is done, you can SSH in, and build and test:
2016-10-07 18:31:03 +00:00
host$ vagrant ssh
vm$ cd /vagrant
vm$ cargo build
vm$ ./xtests/run
All the tests passed!
2020-10-13 20:50:27 +00:00
Of course, the drawback of having a standard development environment is that you stop noticing bugs that occur outside of it.
2023-07-29 12:09:05 +00:00
For this reason, Vagrant isn’ t a *necessary* development step — it’ s there if you’ d like to use it, but eza still gets used and tested on other platforms.
2020-10-13 20:50:27 +00:00
It can still be built and compiled on any target triple that it supports, VM or no VM, with `cargo build` and `cargo test` .
2023-07-29 12:09:05 +00:00