Sorting and Statistics¶

visualize, export, and compare can annotate every file with its lines of code, size, modification time, or Git status, and can order files by any of them. The flags on this page behave the same way in all three commands.

Sorting and Display Are Separate¶

Recursivist keeps two things separate: how files are ordered and what each file is annotated with. That gives three families of flags:

Combined — --sort-by-loc, --sort-by-size, --sort-by-mtime, and --sort-by-git-status each sort files by a metric and annotate every file with it.
Display-only — --loc, --size, --mtime, and --git-status annotate files without touching the order.
Sorting-only — --sort-by-similarity reorders without annotating.

A combined flag is the quickest way to see one metric. To sort by one metric while showing others, see Combining Statistics.

Lines of Code¶

Count lines per file and total them per directory, largest first:

recursivist visualize --sort-by-loc

recursivist-demo ~ bash

📂 my-project (1262 lines)
├── 📄 README.md (124 lines)
├── 📄 setup.py (65 lines)
├── 📄 requirements.txt (18 lines)
└── 📂 src (1055 lines)
    ├── 📄 main.py (245 lines)
    ├── 📄 utils.py (157 lines)
    └── 📂 tests (653 lines)
        ├── 📄 test_main.py (412 lines)
        └── 📄 test_utils.py (241 lines)

Every line of a text file is counted, blank lines and comments included. Files are read as UTF-8, and UTF-16 files are recognized; a file that is empty, binary, or unreadable counts as 0 lines. A directory's figure is the total of the files shown beneath it, so files left out by a filter or a depth limit are not counted.

File Sizes¶

Display sizes with units (B, KB, MB, GB), largest first:

recursivist visualize --sort-by-size

recursivist-demo ~ bash

📂 my-project (57.1 KB)
├── 📄 README.md (4.2 KB)
├── 📄 setup.py (3.8 KB)
├── 📄 requirements.txt (512 B)
└── 📂 src (48.6 KB)
    ├── 📄 main.py (12.4 KB)
    ├── 📄 utils.py (8.2 KB)
    └── 📂 tests (28.0 KB)
        ├── 📄 test_main.py (18.6 KB)
        └── 📄 test_utils.py (9.4 KB)

Modification Times¶

Show when files were last modified, newest first, with recency-aware formatting (Today HH:MM, Yesterday HH:MM, a weekday and time within the last week, Mon DD earlier this year, or YYYY-MM-DD for older files). A directory shows the time of its most recently modified file:

recursivist visualize --sort-by-mtime

recursivist-demo ~ bash

📂 my-project (Today 14:30)
├── 📄 README.md (Today 10:15)
├── 📄 setup.py (Today 09:00)
├── 📄 requirements.txt (Yesterday 16:00)
└── 📂 src (Today 14:30)
    ├── 📄 main.py (Today 14:30)
    ├── 📄 utils.py (Today 09:15)
    └── 📂 tests (Today 14:25)
        ├── 📄 test_main.py (Today 14:25)
        └── 📄 test_utils.py (Yesterday 18:10)

Displaying Without Sorting¶

Use the display-only flags — --loc, --size, --mtime — to annotate files while keeping the default extension-and-name ordering:

recursivist visualize --size          # show sizes, don't reorder
recursivist visualize --loc --mtime   # show LOC and mtime, don't reorder

Display-only annotations appear in the exact order you list the flags, so --loc --mtime and --mtime --loc differ only in column order.

Combining Statistics¶

You can sort by one metric and annotate with several. Pair a single sorting flag with as many display-only flags as you like:

recursivist visualize --sort-by-loc --size --mtime

recursivist-demo ~ bash

📂 my-project (1262 lines, 57.1 KB, Today 14:30)
├── 📄 README.md (124 lines, 4.2 KB, Today 10:15)
├── 📄 setup.py (65 lines, 3.8 KB, Today 09:00)
├── 📄 requirements.txt (18 lines, 512 B, Yesterday 16:00)
└── 📂 src (1055 lines, 48.6 KB, Today 14:30)
    ├── 📄 main.py (245 lines, 12.4 KB, Today 14:30)
    ├── 📄 utils.py (157 lines, 8.2 KB, Today 09:15)
    └── 📂 tests (653 lines, 28.0 KB, Today 14:25)
        ├── 📄 test_main.py (412 lines, 18.6 KB, Today 14:25)
        └── 📄 test_utils.py (241 lines, 9.4 KB, Yesterday 18:10)

Here files are ordered by lines of code, and each is annotated with LOC, size, and modification time.

Flags are resolved by their left-to-right order on the command line:

Only the first sorting flag takes effect. A later --sort-by-* is discarded entirely — so --sort-by-loc --sort-by-size sorts by LOC and shows only LOC, not both. Use --sort-by-loc --size to sort by LOC and display size too.
The winning sort metric is annotated first; display-only annotations follow in the order given.

The CLI Reference has the complete resolution rules.

Grouping by Name Similarity¶

Instead of ordering files by extension and then name, group files with similar names next to each other:

recursivist visualize --sort-by-similarity

recursivist-demo ~ bash

📂 project
├── 📄 main.js
├── 📄 main.py
├── 📄 test_api.py
├── 📄 test_api.js
└── 📄 README.md

--sort-by-similarity is a sorting flag like the others, so it takes effect only when it comes before any other --sort-by-* flag on the command line.

Git Status¶

Inside a Git repository, annotate files with their status:

recursivist visualize --git-status

recursivist-demo ~ bash

📂 my-project
├── 📄 README.md
├── 📄 newfile.txt [U]
└── 📂 src
    ├── 📄 main.py
    └── 📄 utils.py [M]

Markers are [U] untracked, [M] modified, [A] added, and [D] deleted. Deleted files are also shown struck through, and a file deleted from disk is still listed so the change is visible, along with its directory if that is gone too. If the directory isn't inside a repository (or has no changes), no markers are added.

--git-status is display-only. To also sort by Git status (modified, added, deleted, untracked, then clean), use the combined flag:

recursivist visualize --sort-by-git-status

The Git-status marker always trails at the very end of a file's annotations, after any metric parenthetical. For example, --sort-by-loc --git-status shows main.py (245 lines) [M].

In Exports and Comparisons¶

Every flag above works with export and compare:

recursivist export --format md --sort-by-loc --size   # sort by LOC, show LOC and size
recursivist export --format json --mtime              # show mtime, keep default order
recursivist compare dir1 dir2 --sort-by-size
recursivist compare dir1 dir2 --git-status

Each export format writes the annotations in its own way; Export Formats shows them.
In compare, the legend notes which metrics and ordering are active, and Git status is read independently for each directory, so both sides are annotated correctly even when they belong to different repositories.
For a GitHub repository URL, lines of code and size apply, while the Git-status and modification-time flags are skipped. See GitHub Repositories.