TreeFiles is a CLI tool for easy directory space allocation visualization.
The same C++17 sources support native Windows and Linux. Windows uses PDCurses
and the system's default file associations; Linux uses ncurses and xdg-open.
The GitHub releases page hosts
Windows x64 and Linux x64 packages for each published version. Download the
package for your platform and its .sha256 file. Packages include the executable,
this guide, the demonstration and third-party notices.
On Windows, extract treefiles-windows-x64.zip and run from PowerShell:
Get-FileHash .\treefiles-windows-x64.zip -Algorithm SHA256
Expand-Archive .\treefiles-windows-x64.zip -DestinationPath .\TreeFiles
.\TreeFiles\treefiles.exe "$env:USERPROFILE\Documents"Compare the SHA-256 result with treefiles-windows-x64.zip.sha256. The executable
requires no compiler, WSL or extra runtime DLLs. Add its directory to your own
PATH if you want to run treefiles.exe from any folder.
On Debian/Ubuntu, install the runtime libraries, verify the archive and extract it:
sudo apt-get install libncursesw6 libstdc++6 xdg-utils
sha256sum --check treefiles-linux-x64.tar.gz.sha256
mkdir -p TreeFiles
tar -xzf treefiles-linux-x64.tar.gz -C TreeFiles
./TreeFiles/treefiles ~/DocumentsThe Linux package requires glibc 2.35 or newer. For an older distribution or another architecture, build from source using the instructions below.
Clone the repository and run:
cd TreeFiles
.\scripts\build_windows.ps1 -Test
.\build\windows-debug\treefiles.exe .The first build downloads a pinned, SHA-256-verified w64devkit
toolchain into .tools/ and PDCurses 3.9 into the CMake build directory. It
requires internet access. Later builds reuse these downloads. No administrator
access or global PATH changes are required. WSL and the old MinGW compiler are
not needed. Use a PowerShell terminal in Windows Terminal or VS Code.
If Windows PowerShell blocks local scripts, allow them for the current session:
Set-ExecutionPolicy -Scope Process -ExecutionPolicy BypassTo use the compiler, CMake and GDB directly in the current PowerShell session:
.\scripts\setup_windows.ps1
cmake --build build/windows-debug
ctest --test-dir build/windows-debug --output-on-failure
gdb .\build\windows-debug\treefiles.exeFor a release build and a distributable ZIP:
.\scripts\build_windows.ps1 -Configuration Release -Test
.\scripts\package_windows.ps1The Windows executable statically links PDCurses and the C++ runtime. Users can
extract the ZIP and run treefiles.exe without installing the development tools.
On Debian/Ubuntu:
sudo apt-get update
sudo apt-get install -y g++ cmake ninja-build libncurses-dev xdg-utils
cmake -S . -B build/linux-debug -G Ninja -DCMAKE_BUILD_TYPE=Debug
cmake --build build/linux-debug --parallel
ctest --test-dir build/linux-debug --output-on-failure
./build/linux-debug/treefiles .The existing make, make test and make install commands also remain supported.
The Makefile is for Linux; use CMake or the PowerShell scripts on Windows.
treefiles [--headless] [--page-size N] [--lang en|es] [directory]
| Option | Behavior |
|---|---|
directory |
Directory to inspect; defaults to the current directory |
--page-size N / --page-size=N |
Files and directories per page, default 30 |
--lang en / --lang es |
Interface language; English is the default |
--headless |
Read events from stdin and print structured frames |
--help, -h |
Show command-line help |
--version |
Show the application version |
Pass a directory as the optional argument; the default is the current directory.
Quote paths containing spaces. Use the arrows to select, E to expand/collapse,
N/P for pagination, Space to open, Delete to delete after confirmation,
B to change colors, and Q to quit.
.\build\windows-debug\treefiles.exe "$env:USERPROFILE\Documents"
'DOWN', 'e', 'q' | .\build\windows-debug\treefiles.exe --headless .Headless mode logs opening actions without launching external applications. Confirmed deletion still removes the selected file or directory.
Use --page-size N (or --page-size=N) to configure the number of files and
directories per page. The default is 30; N must be a positive integer up to
2147483647. The limit applies independently to every directory, including
expanded subdirectories. Previous/next navigation rows do not count toward it.
This option works in both interactive and headless mode. Use --help for usage.
.\build\windows-debug\treefiles.exe --page-size 10 .
'n', 'p', 'q' | .\build\windows-debug\treefiles.exe --headless --page-size 10 ../build/linux-debug/treefiles --page-size 10 .Entries are sorted by size, largest first, and then by name. Expanding a folder shows its children in the tree. The size bar is relative to the entries displayed at that level. Pagination and scrolling are independent: a large page can still be scrolled to fit the terminal.
Displayed sizes are logical file lengths in bytes, including sparse files; they do not estimate how many storage blocks a file occupies. Files larger than 1 TiB are included in directory totals.
| Key | Action |
|---|---|
Up / k |
Move up |
Down / j |
Move down |
Right / l |
Expand a directory; advance a selected next-page row |
Left / h |
Fold a directory; from a child, select and fold its parent |
| Enter | Enter the selected directory; activates a selected page row |
| Backspace | Return to the parent directory |
O |
Type a path relative to the current root or an absolute path |
g / G |
Select the first / last row of the current tree |
E |
Toggle directory expansion or activate a pagination row |
N / P |
Next / previous page of the selected directory |
R |
Re-scan the current root and update cached sizes |
| Escape | Cancel the active scan and keep the last completed listing |
| Space | Open with the system's default application |
| Delete | Delete the selected file or directory after confirmation |
B |
Choose the bar's background and text colors |
W |
Review filesystem errors and omitted entries from the last scan |
Q |
Quit |
Scans run in a managed background worker. While one is active, TreeFiles shows
the scan root, directories and entries processed, bytes counted and elapsed
time. It keeps the previous completed listing available for selection and
scrolling; Delete is disabled until the replacement completes. Press Escape to
cancel. Pressing R or changing roots replaces the pending scan with the
latest request. Cancellation is cooperative between filesystem operations, so
a filesystem call already blocked by the operating system must return first.
All terminal drawing and key handling stay on the main thread.
TreeFiles lists symbolic links and Windows directory junctions without following
them. A link can be opened with Space or deleted without deleting its target.
If an item could not be read, directory sizes are marked partial or unavailable;
press W to review the affected paths and filesystem errors.
In the color picker, use arrows or j/k, Enter to confirm each color and Escape
to cancel. The picker starts with the current colors. In delete confirmations,
use left/right or h/l to select, Enter to confirm, or y/n to answer directly.
English is the default. Select Spanish for a session with:
.\build\windows-debug\treefiles.exe --lang es --page-size 10 .--lang=es also works. The language covers the footer, page labels, prompts,
color picker, scan status and command-line help. Headless protocol keys
such as selected_index remain stable; the language field identifies the
selected language. Unsupported language codes exit with code 2.
Confirm both colors with B to save them automatically for the next session.
Canceling the picker keeps the current configuration. Settings are per user:
| Platform | Configuration file |
|---|---|
| Windows | %LOCALAPPDATA%\TreeFiles\config.ini |
| Linux | $XDG_CONFIG_HOME/treefiles/config.ini, or ~/.config/treefiles/config.ini |
The file uses canonical English color names:
foreground=black
background=yellowSupported names are black, red, green, yellow, blue, magenta, cyan
and white. Missing or invalid fields use their defaults. Remove the file to
reset the colors. Saving uses a temporary file and replaces the old file only
after the write succeeds; a failed save reports an error.
Set TREEFILES_CONFIG to a different file for portable use or isolated tests:
$env:TREEFILES_CONFIG = "$PWD\colors.ini"
.\build\windows-debug\treefiles.exe .Pipe one event per line. Arrow events use UP, DOWN, LEFT and RIGHT;
SPACE, DELETE, ENTER, BACKSPACE and REFRESH represent those actions.
CD <path> changes to a path relative to the current root or to an absolute
path; the entire remainder of the line is treated as the literal path. Letter shortcuts work as
in the interactive interface. COLOR foreground background applies and saves
colors; B only logs the available choices in headless mode. Headless scans
remain synchronous by default. SCAN_START starts an asynchronous scan,
CANCEL_SCAN requests cancellation, and WAIT_SCAN waits for the active and
replacement scans to finish. While a scan runs, frames retain the last completed
listing and report the target and progress counters.
'COLOR white blue', 'j', 'l', 'q' |
.\build\windows-debug\treefiles.exe --headless --page-size 10 .Frames contain the current path, language, page size, pagination, selection,
scrolling, expansion, colors, entry list, scan_status, and structured
diagnostics_count/diagnostic_N records. They also include
async_scan_state, async_scan_root, scan_progress_entries,
scan_progress_directories, scan_progress_bytes, and
scan_progress_elapsed_seconds. Headless opening logs an action;
confirmed deletion still removes files. Exit codes are 0 on success, 1 when the
root cannot be listed, and 2 for invalid command-line options. Errors isolated
to a child keep accessible results and mark the scan partial.
- If Windows blocks local scripts, use the process-scoped execution policy shown above. Run the build from PowerShell in Windows Terminal or VS Code.
- If the first Windows build cannot download dependencies, check internet
access and rerun it. Downloads are checksum-verified and cached in
.tools/. - If a Linux package reports a missing ncurses library, install
libncursesw6. A glibc version error requires building from source on your distribution. - If file opening fails on Linux, install
xdg-utilsand run within a desktop session. Windows uses the registered file association. - If colors cannot be saved, check that the configuration directory is writable
or set
TREEFILES_CONFIGto a writable file.
GitHub Actions builds and tests Windows x64 and Linux x64 on pushes and pull requests. Publishing a GitHub release triggers builds of that release's tag. After both platforms pass, the workflow attaches:
treefiles-windows-x64.ziptreefiles-linux-x64.tar.gz- A SHA-256 checksum file for each package.
The workflow must be present in the release's tagged commit. A failed build prevents the upload job; rerun the failed workflow after resolving the problem.
For the first version, prepare a draft release named v0.1.0 targeting main.
Merge the feature PR and wait for both platform checks before publishing the
draft. Publishing triggers the release workflow, which verifies the package
checksums and attaches both platforms. Downloadable archives are also available
as workflow artifacts before publication.
The Linux package is built on Ubuntu 22.04 and needs glibc 2.35 or newer and
the ncurses wide-character and C++ runtimes (libncursesw6 and libstdc++6
on Ubuntu 22.04 or newer).
Both platforms include third-party notices in licenses/.
