Skip to main content
SysAdmin Shell Scripting Essentials

ls Command Reference: Options, Exit Codes, Troubleshooting

5 min read

ls lists directory contents with options for formatting, sorting, and filtering output. It is a core Unix/Linux command.

ls [OPTION]... [FILE]...
# Common usage patterns
ls -l       # long listing
ls -a       # include hidden files
ls -lh      # human-readable sizes
ls -ltr     # reverse chronological order

Options and Flags

Flag Type Default Description
-l boolean off Long format – permissions, links, owner, group, size, date
-a boolean off Show all entries including . and ..
-h boolean off Human-readable sizes (KB, MB, GB) – used with -l
-r boolean off Reverse sort order
-t boolean off Sort by modification time (newest first)
-S boolean off Sort by file size (largest first)
-X boolean off Sort alphabetically by extension
-R boolean off Recursive – list subdirectories
-F boolean off Append indicator (*/=>@|) to entries
-i boolean off Print inode number
-n boolean off Numeric UID/GID instead of names
-m boolean off Comma-separated list
-Q boolean off Quote entry names with double quotes
--color=auto string auto Color output based on file type (auto/always/never)
--author boolean off Show file author (usually same as owner)
See also  Install wget on macOS — Verified Syntax, Flags & Troubleshooting

Usage Examples

Example 1: Long listing with human-readable sizes, sorted by time

ls -lhtr /var/log/

Lists files in /var/log with details, human-readable sizes, sorted by modification time (oldest first). Useful for log rotation inspection.

Example 2: Recursive listing with hidden files and inode numbers

ls -laiR /etc/

Recursively lists all files (including hidden) in /etc with inode numbers. Good for finding duplicate inodes or auditing configuration files.

Example 3: Comma-separated list showing numeric UIDs/GIDs

ls -mn /home/

Outputs a comma-separated list of home directories with numeric owner/group IDs. Useful for scripting permission audits across NFS mounts.

Troubleshooting and Common Errors

Error Message / Symptom Root Cause Resolution
ls: invalid option -- 'z' Typo or unsupported flag ls --help | grep -i allowed – review options
ls: cannot access 'nonexist': No such file or directory Argument points to non-existent path ls -d /path 2>/dev/null || echo "Path not found"
ls: reading directory '.': Permission denied No read or execute permission on directory sudo ls -la /restricted
Output extends beyond terminal (no pager) Large directory with long listing ls -la | less
ls: unrecognized option '--sort' Using GNU coreutils flag on a non-GNU system (e.g., BSD/macOS) ls -t – use POSIX time sort instead
Output shown but no colors --color flag omitted or output is piped (GNU ls disables color by default when not a TTY) ls --color=always | cat or alias ll='ls -l --color=auto'
Very slow listing on large directories Globbing with ls *.log triggers shell expansion first; ls -l on 100k files takes seconds find . -maxdepth 1 -name '*.log' -ls – faster for large dirs
Filename with newline appears broken Default output treats newlines as line separators; -b or -Q needed ls -b – escapes backslash sequences
See also  PowerShell Create a Directory: New-Item and mkdir Syntax & Error

Related: LSS Userscript Project (Grisu118/lss-userscript)

The GitHub repository Grisu118/lss-userscript provides a userscript (enhanced-s5.user.js) for the browser game Leitstellenspiel.de. This is not a CLI command; it installs into a browser (Tampermonkey/Greasemonkey) to enhance the game UI. Development uses Nx workspace commands for building and syncing TypeScript project references. No native cloud equivalents exist for this userscript.

Development Commands (from project)

# Build a specific project
npx nx build pkg1

# Sync TypeScript project references
npx nx sync

# Check sync status
npx nx sync:check

These commands are specific to an Nx monorepo and do not apply to the ls command.

Frequently Asked Questions

What is the difference between long listing and single column output in ls?

Answer: Default ls prints entries in columns aligned to terminal width. The -l flag switches to long format with one line per entry, showing permissions, links, owner, group, size, and modification time.

Long format is human-readable for detailed inspection; column output is more compact for scanning many files. Use -C to force column output after a pipe.

ls -l /etc
ls /etc | head -5

How do I exclude hidden files from ls output?

Answer: By default, ls does not show hidden files (those starting with a dot) unless you use -a. To explicitly exclude them from a listing, simply omit -a. For more granular exclusion, use shell globbing patterns like ls -l !(.*) in extended glob mode.

In POSIX shell, ls -l * does not match hidden files. To include all non-hidden files, use ls -l without patterns.

ls -l                    # no hidden files
ls -la                   # all files including hidden
ls -l .[!.]*             # only hidden files (excluding . and ..)

How do I fix ‘ls: invalid option’ error?

Answer: The error usually means you typed a flag that does not exist. Check the options list with ls --help or the man page. Common mistakes include using --sort on BSD systems or uppercase flags incorrectly.

See also  Test-Connection PowerShell Command Reference: Syntax, Flags

For example, --sort is GNU only; use -t for time sort on POSIX. Always verify flag compatibility across systems.

ls --help | grep -E '^  -|--[a-z]'
man ls

Does the ls command work on macOS and Linux?

Answer: Yes, ls is present on both. However, macOS uses BSD ls which differs from GNU coreutils ls in some flags (e.g., --color, -h with -l, sorting options).

On macOS, -h is supported with -l (GNU and BSD), but --color=auto is not native; install coreutils via Homebrew for full GNU compatibility. Scripts should check uname or use POSIX flags only.

ls --version 2>/dev/null || echo "BSD ls"
ls -ltr /tmp

How can I list files modified in the last hour using ls?

Answer: ls has no built-in filter by modification time. Use the find command with -mmin for this purpose, then optionally pipe to ls -l for formatting.

For example, find /var/log -mmin -60 -type f -exec ls -lh {} ;. This is more efficient than parsing ls -l output.

find . -mmin -60 -type f -ls
find . -mmin -60 -type f -exec ls -lh {} ;