Skip to main content
List provides visual cues to help you quickly identify different file types through color-coding and emoji icons. These features enhance readability and make it easier to scan directory listings.

​
Overview

List uses two visual systems:
  • Colors: ANSI terminal color codes that colorize file names based on type
  • Icons: Emoji icons that appear before file names
Both features are opt-in and can be used independently or together. Sources:
  • Sources/SwiftListCore/Utilities/TerminalColors.swift
  • Sources/SwiftListCore/Models/FileRepresentation.swift
  • Sources/SwiftListCore/Utilities/FileManagerHelper.swift:32-59

​
Color System

Enable colors with the --color flag: 
$ sls --color

​
Color Mappings

List uses the following ANSI color scheme:
File TypeColorANSI CodeUse Case
DirectoriesBlue\u{001B}[0;34mFolders and directory paths
Symbolic LinksYellow\u{001B}[0;33mLinks pointing to other files/dirs
ExecutablesRed\u{001B}[0;31mFiles with executable permissions
Regular FilesWhite\u{001B}[0;37mAll other files
Source: Sources/SwiftListCore/Utilities/TerminalColors.swift:14-28
Colors are rendered using ANSI escape codes and will appear correctly in most modern terminals. The reset code \u{001B}[0;0m is automatically appended after each file name to restore default colors.

​
Color Examples

$ sls --color
# Output shows:
# Documents    (blue - directory)
# README.md    (white - regular file)
# build.sh     (red - executable)
# config-link  (yellow - symbolic link)

​
Icon System

Enable icons with the --icons flag: 
$ sls --icons

​
Icon Mappings

List uses emoji icons to represent file types:
File TypeIconDescription
Directories📁Folders containing other files
Regular Files📄Standard files (text, data, etc.)
Symbolic Links🔗Links pointing to other files/directories
Executables⚙️Files with executable permissions
Source: Sources/SwiftListCore/Utilities/FileManagerHelper.swift:40-58

​
Icon Examples

$ sls --icons
📁 Documents  📄 README.md  ⚙️ build.sh  🔗 config-link

​
Combining Colors and Icons

For maximum visual clarity, use both colors and icons together: 
$ sls --color --icons
This provides both color coding and icon prefixes: 
📁 Documents       # Blue text with folder icon
📄 README.md       # White text with file icon
⚙️ build.sh        # Red text with executable icon
🔗 config-link     # Yellow text with link icon

​
Combined with Long Format

$ sls -l --color --icons
Provides the most detailed and visually rich output: 
📁 493 user staff 3  96 bytes   2026-03-01 09:15 Documents
📄 493 user staff 1  2.3 KB     2026-03-01 10:30 README.md
⚙️ 493 user staff 1  512 bytes  2026-02-28 14:20 build.sh
🔗 493 user staff 1  64 bytes   2026-02-27 11:45 config-link -> /etc/config

​
File Type Detection

List determines file types using the following logic (in order):
  1. Directories: Detected via URL.hasDirectoryPath
    • Icon: 📁
    • Color: Blue
  2. Symbolic Links: Detected via file attribute .type == .typeSymbolicLink
    • Icon: 🔗
    • Color: Yellow
    • Shows destination path with -> separator
  3. Executables: Detected via FileManager.isExecutableFile(atPath:)
    • Icon: ⚙️
    • Color: Red
    • Must have executable permissions
  4. Regular Files: Everything else
    • Icon: 📄
    • Color: White
Source: Sources/SwiftListCore/Utilities/FileManagerHelper.swift:37-59
Symbolic links are checked before executables. This means a symbolic link to an executable file will be displayed as a link (🔗, yellow) rather than an executable (⚙️, red).

​
Programmatic Usage

When using List as a Swift library: 
import SwiftListCore

// Enable colors only
let options = DisplayOptions(
    color: true
)

// Enable icons only
let options = DisplayOptions(
    icons: true
)

// Enable both
let options = DisplayOptions(
    color: true,
    icons: true,
    long: true
)

let listing = try FileManagerHelper.contents(with: options)
print(listing)

​
Direct File Type Detection

You can also use the file type detection directly: 
import SwiftListCore
import Foundation

let url = URL(fileURLWithPath: "/path/to/file")
let attributes = try FileManager.default.attributesOfItem(atPath: url.path)

let representation = FileManagerHelper.determineType(
    of: url,
    attributes: attributes
)

print("Icon: \(representation.icon)")
print("Color: \(representation.color)")
if let dest = representation.destination {
    print("Link destination: \(dest)")
}
Source: Sources/SwiftListCore/Utilities/FileManagerHelper.swift:32-59 Symbolic links receive special treatment:
  • The link itself is displayed (not the target)
  • The destination path is shown after ->
  • The link’s icon and color are used (not the target’s)
$ sls -l --color --icons
🔗 493 user staff 1  64 bytes 2026-02-27 11:45 config-link -> /etc/config
Even if the target is a directory or executable, the link displays as a link. Source: Sources/SwiftListCore/Utilities/FileManagerHelper.swift:45-51

​
Terminal Compatibility

Color Support: Colors work in any terminal that supports ANSI escape codes. This includes:
  • macOS Terminal.app
  • iTerm2
  • Most Linux terminals (GNOME Terminal, Konsole, etc.)
  • Windows Terminal
  • VS Code integrated terminal
Icon Support: Icons require a terminal with Unicode/emoji support and a font that includes emoji glyphs. Most modern terminals support this by default.

​
Tips

Use --color and --icons together with -l for the most informative output:
sls -l --color --icons
If you frequently want colors and icons, consider creating a shell alias:
alias sls='sls --color --icons'
Combine visual options with sorting to organize files by importance:
sls -lS --color --icons  # Largest files first
sls -lt --color --icons  # Most recent first

Build docs developers (and LLMs) love

Get started for freeTalk to us