Skip to main content
List provides three sorting modes to organize files in different ways. The SortOption enum defines how files are ordered when displaying directory contents.

​
Overview

Sorting is controlled by the sortBy field in DisplayOptions. By default, files are sorted alphabetically by name, but you can also sort by modification time or file size. Source: Sources/SwiftListCore/Configuration/SortOption.swift:13-22

​
Sort Options

​
Sort by Name (Default)

Sorts files alphabetically by filename using localized comparison. This is the default behavior. Enum value: SortOption.name CLI usage: Default behavior (no flag needed) 
$ sls
Documents  Downloads  README.md  package.json  src  tests
Implementation: Uses localizedCompare for natural sorting order (e.g., “file2.txt” comes before “file10.txt”). Source: Sources/SwiftListCore/Utilities/FileManagerHelper.swift:224-227

​
Sort by Time

Sorts files by modification time, with the most recently modified files appearing first. Enum value: SortOption.time CLI flag: -t 
$ sls -t
README.md  src  package.json  Downloads  Documents  tests
Use cases:
  • Finding recently modified files
  • Tracking recent work
  • Identifying stale files
Implementation: Compares contentModificationDate resource values. Files without modification dates are treated as having Date.distantPast. Source: Sources/SwiftListCore/Utilities/FileManagerHelper.swift:228-233

​
Sort by Size

Sorts files by size, with the largest files appearing first. Enum value: SortOption.size CLI flag: -S 
$ sls -S
Downloads  Documents  README.md  package.json  src  tests
Use cases:
  • Finding large files consuming disk space
  • Identifying files for cleanup
  • Understanding storage usage patterns
Implementation: Compares fileSize resource values. Files without size information are treated as 0 bytes. Source: Sources/SwiftListCore/Utilities/FileManagerHelper.swift:234-238

​
Combining Sort with Other Options

Sorting works seamlessly with all other display options:

​
Sort with Recursion

# Show all files recursively, sorted by time
$ sls -Rt

# Recurse with depth limit, sorted by size
$ sls -RS --depth 2
Each directory level is sorted independently using the specified sort option.

​
Sort with Long Format

# Long format sorted by size with human-readable output
$ sls -lSh

# Long format sorted by time
$ sls -lt
Combining sort with -l makes it easy to verify the sort order visually.

​
Sort with Filters

# Show all files (including hidden) sorted by time
$ sls -at

# Show one per line, sorted by size
$ sls -1S

​
Sort Implementation Details

The sorting algorithm is applied in FileManagerHelper.contents() after retrieving directory contents: 
let sortedContents = contents.sorted { url1, url2 in
    switch options.sortBy {
    case .name:
        return url1.lastPathComponent.localizedCompare(url2.lastPathComponent)
            == .orderedAscending
    case .time:
        let date1 = try? url1.resourceValues(forKeys: [.contentModificationDateKey])
            .contentModificationDate
        let date2 = try? url2.resourceValues(forKeys: [.contentModificationDateKey])
            .contentModificationDate
        return (date1 ?? Date.distantPast) > (date2 ?? Date.distantPast)
    case .size:
        let size1 = try? url1.resourceValues(forKeys: [.fileSizeKey]).fileSize
        let size2 = try? url2.resourceValues(forKeys: [.fileSizeKey]).fileSize
        return (size1 ?? 0) > (size2 ?? 0)
    }
}
Source: Sources/SwiftListCore/Utilities/FileManagerHelper.swift:222-239

​
Performance Considerations

  • Name sorting is the fastest, as it only uses filenames already in memory
  • Time sorting requires reading modification date metadata for each file
  • Size sorting requires reading size metadata for each file
For large directories, name sorting will be noticeably faster than time or size sorting.

​
Tips

Combine -l (long format) with -t or -S to see the values being sorted by:
sls -lt  # See modification dates
sls -lS  # See file sizes
Use -h (human-readable) with -S to easily understand file sizes:
sls -lSh  # Shows "2.3 MB" instead of "2,345,678 bytes"
When sorting by time or size, files without the requested metadata (e.g., files where metadata can’t be read) are treated as having:
  • Time: Date.distantPast (sorted to the end)
  • Size: 0 bytes (sorted to the end)

Build docs developers (and LLMs) love

Get started for freeTalk to us