Guide

lsgo is a colourful ls replacement, written in Go with zero external dependencies — standard library only, by design. It colours files by type and extension, understands symlinks and Git status, and can display its listing as a grid, a single column, a detailed table, or a tree.

• Installation
• Usage & Flags
• View Modes & Sorting
• Colours & Theming

Project Goal

ls replacements are common, but most of them lean on a handful of third-party crates or packages for terminal width detection, colour parsing, or extended attributes. lsgo was built in an environment with no module proxy access, so every one of those pieces is hand-rolled against the Go standard library instead. The result is a single binary with no go.sum to audit, and that constraint turned out to be worth keeping even where it wasn't strictly necessary.

Features

• Four view modes: grid (default), one-per-line, long table, and tree — freely combinable, with predictable last-flag-wins precedence when more than one is given
• Colours files by type and extension out of the box, fully overridable via the standard LS_COLORS environment variable
• Optional Nerd Font icon glyphs next to each filename
• Git-aware: a per-file status column (--git), a per-directory repo status column (--git-repos/--git-repos-no-status), and the option to hide anything your repository already ignores (--git-ignore)
• Natural-order, case-insensitive name sorting by default (file9 before file10, apps before Documents), with size, extension, timestamp, type, and no-op sort fields available via --sort, plus --group-directories-first/--group-directories-last
• A detailed long view with per-column opt-outs, extended attribute listing, binary/decimal size prefixes, configurable timestamp fields and styles (including relative), and numeric or named user/group columns
• Filtering beyond dotfiles: --only-dirs/--only-files, --no-symlinks/--show-symlinks, and glob-based ignores
• Symlink dereferencing (-X), absolute paths (--absolute), recursive directory sizes (--total-size), SELinux context and mount-point columns (-Z/-M, Linux), and reading a file list from stdin (--stdin)

Quick Start

Go path install:

go install github.com/jc21/lsgo@latest

or build from source with the Go toolchain:

go build -o lsgo .

This produces a single lsgo binary with no runtime dependencies. See Installation for other ways to get it onto your PATH.

Once installed, run it with no arguments to list the current directory as a grid:

lsgo

Add -l for a detailed table, -T for a tree, or -1 for one entry per line:

lsgo -l
lsgo -T
lsgo -1

Run lsgo --help at any time for the full, authoritative flag reference.

Contributing

Pull requests are welcome. go test ./..., go vet ./..., and gofmt -l . should all be clean before you open one — see the project's CLAUDE.md for a tour of the codebase's architecture and the reasoning behind its more deliberate design decisions.

Getting Support

Found a bug, or have a feature request? Open an issue on GitHub.