colorls: a Ruby replacement for ls with icons and git status

What colorls adds to a plain ls

The README describes colorls as "a Ruby script that colorizes the `ls` output with color and icons." That is the whole proposition. It does not replace the filesystem listing logic with anything exotic; it takes the same directory entries and renders them with a colour scheme plus glyphs from a Nerd Font. The intended audience is people who live in a terminal and want the listing to carry more information at a glance: which entries are directories, which are files, and what kind of file each one is.

The flags go past decoration. `--tree` prints a tree view of the directory with a specified depth, default 3. `--gs` (or `--git-status`) shows git status for each entry, which turns the listing into a quick check of what is modified in a repository. `--report` prints a brief count of files and folders shown. `--sd` groups directories first, `--sf` puts files first, and `-t` sorts by modification time, newest first. If you only wanted colour, `ls --color` would do; colorls is for the combination of icons, tree output and repository state in one command.

How the gem is put together and where the icons come from

The repository layout is a standard Ruby gem: `exe/` holds the executable, `lib/` the implementation, `man/` the man pages, and `spec/` and `test/` the tests. The README states that man pages have been added, so `man colorls` is the reference for flags rather than the README alone.

The dependency that matters is not in the code. Icons are glyphs from a Nerd Font, and the README is explicit that you must download and install one so "you can see the library icons." Without that font, the glyphs do not render as symbols; you get whatever your terminal substitutes. The README uses Hack Nerd Font in its instructions and gives per-terminal setup notes: for the stock macOS terminal, enable the font at Terminal > Preferences > Profiles > Text > Font; for iTerm2, set it under Profiles > Text > Non-ASCII font; for HyperJS, add `"Hack Nerd Font"` to `fontFamily` in `~/.hyper.js`. Two colour schemes ship as flags, `--light` and `--dark`, with dark as the default.

The rendering pipeline is therefore: Ruby reads the directory, the gem maps entries to colours and glyphs, and the terminal font supplies the glyph shapes. The last step is outside the gem's control, which is why the installation instructions spend as much space on fonts as on Ruby.

Installing colorls and listing a directory

The README's installation order is Ruby first, Nerd Font second, gem third. It asks for Ruby preferably version 2.6 or newer, installed via a version manager such as rbenv. Then install the gem itself:

gem install colorls

After that, enable tab completion for flags by adding one line to `~/.bashrc` or `~/.zshrc`:

source $(dirname $(gem which colorls))/tab_complete.sh

The README adds a note to restart your terminal after this step. If you use rbenv and hit a load error when using `lc`, the README suggests running `rbenv rehash` and `rehash`.

With the gem and font in place, the first real use is the command itself. Run it in a directory you know well so you can tell whether the icons are rendering or whether your terminal is substituting boxes:

colorls --tree --gs

That asks for a tree view with git status per entry, which exercises the tree renderer and the git integration in one go. If the output shows glyphs you do not recognise, the font is the first thing to check, not the gem. For the full flag list, `--help` prints a help menu and `man colorls` documents the options.

Where colorls stops being the right tool

The font requirement is the sharpest limitation. On a remote server you reach over SSH, the glyphs are produced by the remote process but drawn by your local terminal, so a correctly installed colorls on the server can still look broken if the local font lacks the glyphs. On a machine where you cannot install fonts, colorls is the wrong choice and `ls --color` is the right one.

The Ruby dependency is the second constraint. colorls is a gem, so it needs a Ruby runtime. That is fine on a development laptop and awkward on a minimal container or a system where you do not want a language runtime just to list files.

Third, the release history is uneven. The most recent release listed is v1.5.0 from 2024-07-12, preceded by v1.4.6 in 2022 and v1.4.5 earlier in 2022. The repository itself saw a push on 2026-07-27, so work happens between releases, but anyone who pins to tagged versions is installing something from 2024. That is not a defect in the tool, but it is a fact to weigh if your policy is to track recent releases.

Finally, the README documents the flags but not the failure modes. There is no section on what happens when a directory is unreadable, when git status is requested outside a repository, or how the tool behaves on very large trees. Those are the cases to test yourself before making it your default `ls`.

colorls against the alternatives people search for

The most common comparison is with `exa` and its successor `eza`, which are compiled binaries rather than Ruby gems. The difference in approach matters: a compiled binary has no Ruby runtime requirement, so it installs on a machine without Ruby, and it does not depend on a gem ecosystem for updates. colorls instead rides on RubyGems, which means `gem install colorls` and `gem update` are your whole lifecycle, and the tab completion script comes from the installed gem path.

Both approaches still depend on a Nerd Font for icons, so that cost is shared and is not a reason to pick one over the other. Where colorls differs is in what it prints by default and in the flag set: `--report` for counts, `--tree=[DEPTH]` for tree output, `--gs` for git status, and the `--sd`/`--sf` pair for ordering. If your workflow is already Ruby-centric and you want the listing to show repository state, colorls fits without adding a second toolchain. If you want a single static binary you can drop onto any machine, a compiled alternative is the better fit, and colorls is the wrong tool.

Updating, uninstalling and the MIT licence

Because colorls is a gem, the upgrade path is the gem tooling rather than a package manager. The README has an Updating section and an Uninstallation section in its table of contents, which is where the exact commands live; the repository also carries a `RELEASE_POLICY.md` at the top level, so the project states a release policy rather than leaving cadence implicit. The practical cost of upgrading is that a new release can change colour mappings or icon assignments, and since the README points to custom configurations for tweaking colours, any local colour overrides are the thing to re-check after an update.

The licence is MIT, per the repository. MIT is permissive: it allows use, modification and redistribution provided the copyright notice and permission notice are included. This is not legal advice, and the full terms are in `LICENSE.md` in the repository; read that file rather than a summary if the distinction matters to your organisation. There is no separate commercial tier or licence key mentioned anywhere in the repository, so there is nothing to purchase or activate.

Editorial conclusion

Adopt colorls if you already run Ruby and a Nerd Font terminal, and you want tree view, git status and directory-first sorting from one command you can alias over ls. Skip it if you cannot install a Nerd Font, if you need a listing tool on a machine without Ruby, or if you want a maintained release cadence: the last push to the repository was on 2026-07-27, but the most recent release is v1.5.0 from 2024-07-12, so the gap between tagged releases is wide. Before adopting, run gem install colorls in your actual shell, confirm the icons render in your terminal font, and check whether the last release predates any flag you need.

Frequently asked questions

Official sources

1. athityakumar/colorls on GitHub
2. Issues
3. License: MIT
4. README
5. Releases