hls(1) User Manual & Feature Guide

By default, hls ignores files and directories that begin with a period (.). Passing -a forces hls to reveal all entries in the directory, including the current directory (.) and parent directory (..) pointers.

$ hls -a
.               .bashrc         .git            Makefile        src
..              .config         .gitignore      README.md

Transforms the multi-column layout into a detailed, vertical list displaying POSIX file modes, link counts, owners, groups, logical sizes, and modification timestamps.

$ hls -l
drwxr-xr-x  4 bill users     128 Oct 19 14:00 src
-rw-r--r--  1 bill users    1048 Oct 19 14:05 Makefile
lrwxr-xr-x  1 bill users       8 Oct 19 14:10 current_build -> src/main

When used alongside the -l or -s flags, -H scales raw byte sizes into human-readable binary suffixes (Base 1024: K, M, G, T, P) for immediate comprehension.

$ hls -l -H
-rw-r--r-- 1 bill users 1.0K Oct 19 14:05 Makefile
-rw-r--r-- 1 bill users 2.4M Oct 19 14:12 target_binary
-rw-r--r-- 1 bill users 4.0G Oct 19 14:15 large_database.img

Appends a single classification character to the end of filenames to visually indicate the file type.

⚬ / indicates a Directory. ⚬ * indicates an Executable regular file. ⚬ @ indicates a Symbolic Link. ⚬ | indicates a FIFO (named pipe). ⚬ = indicates a Socket.

$ hls -F
Makefile      server.sock=  src/          target_binary*

Functions identically to the -l flag, but bypasses the operating system’s /etc/passwd and /etc/group resolution, displaying the raw numeric User ID (UID) and Group ID (GID). This is highly useful for inspecting tarball extractions or network mounts where local usernames do not map correctly.

$ hls -n
-rw-r--r-- 1 1000 1000 1.0K Oct 19 14:05 Makefile

Sorts the directory contents by their modification timestamp (mtime), placing the most recently modified files at the top of the output.

$ hls -l -t
-rw-r--r-- 1 bill users 2.4M Oct 19 14:12 target_binary
-rw-r--r-- 1 bill users 1.0K Oct 19 14:05 Makefile
drwxr-xr-x 4 bill users  128 Oct 18 09:30 src

Sorts the directory contents by their apparent logical size (st_size) in descending order, placing the largest files at the top.

$ hls -l -H -S
-rw-r--r-- 1 bill users 4.0G Oct 19 14:15 large_database.img
-rw-r--r-- 1 bill users 2.4M Oct 19 14:12 target_binary
-rw-r--r-- 1 bill users 1.0K Oct 19 14:05 Makefile

Inverts the current sorting algorithm. By default, it reverses the standard alphabetical sort. When combined with -t, it places the oldest files at the top. When combined with -S, it places the smallest files at the top.

$ hls -l -H -S -r
-rw-r--r-- 1 bill users 1.0K Oct 19 14:05 Makefile
-rw-r--r-- 1 bill users 2.4M Oct 19 14:12 target_binary
-rw-r--r-- 1 bill users 4.0G Oct 19 14:15 large_database.img

Descends into subdirectories and lists their contents sequentially.

$ hls -R
.:
Makefile  src

./src:
main.c    utils.c   utils.h

The -G flag polls the active Git repository and prepends standard two-character Git status badges to your file output. It automatically crawls upward to find the .git root, meaning it works from any nested subdirectory within your project without needing a separate git status execution.

⚬ Green Badges (M =, =A =, =D =): Changes staged for commit. ⚬ Yellow Badges ( M=, ??): Unstaged modifications or untracked files.

$ hls -G
M  hls.c
?? test.log
Makefile

The -T flag replaces external utilities by rendering the directory hierarchy using UTF-8 box-drawing characters. Because this is built natively into hls, it composes perfectly with all other flags (like -l or -G). If it detects a circular symbolic link that points back to a parent directory, it safely halts traversal for that branch to prevent infinite recursive loops.

$ hls -T -F
.
├── src/
│   ├── main.c
│   └── utils.h
└── build.sh*

File extensions can be missing or falsified. The -M flag forces hls to open regular files and inspect their first 32 bytes to determine the actual content type. Calling -M automatically enables long-format listing (-l) to provide space for the content description.

$ hls -M
-rwxr-xr-x 1 bill users 14336 Oct 19 14:00 build_tool (ELF binary)
-rw-r--r-- 1 bill users 22016 Oct 19 14:00 archive.bak (ZIP archive)
-rw-r--r-- 1 bill users    12 Oct 19 14:00 raw_data (raw binary)

Modern operating systems store metadata out-of-band, such as macOS quarantine bits or Linux security contexts. The -@ flag exposes this hidden data. Files with extended attributes will feature an @ symbol appended to their permission block, and hls will enumerate the specific attribute namespaces indented beneath the file.

$ hls -l -@
-rwxr-xr-x@ 1 bill users 12288 Oct 19 14:00 downloaded_script.sh
@ com.apple.quarantine
@ com.apple.metadata:kMDItemWhereFroms

Standard long listings display logical file sizes, which can be misleading on modern filesystems supporting sparse files. The -s flag measures actual block allocation (st_blocks * 512). If the physical footprint is less than the logical size, hls displays a sparse efficiency ratio. Otherwise, it shows the physical blocks allocated to the file on disk.

$ hls -l -s -H
-rw-r--r-- 1 bill users 10.0G [0% sparse] Oct 19 14:00 virtual_machine.img
-rw-r--r-- 1 bill users   14K [16K blk]   Oct 19 14:00 normal_file.txt

Prints a rapid, concise syntax overview and exits immediately.

$ hls -h
Usage: ./hls [-aFlrRnStHM@Gs] [-h] [-m] [file ...]
Modern systems programmer's directory browser and APUE reference tool.
Execute './hls -m' for the comprehensive manual page or -h for usage summary.

Generates the full, system-style manual page to stdout. hls automatically detects when stdout is piped to an external tool (like less) and strips ANSI formatting codes to ensure perfectly clean pager viewing.

$ hls -m | less