LSW: List Walker

LSW (List Walker) is a Python command-line utility inspired by ls that walks a directory and produces a browsable HTML tree, a plain-text tree, or structured exports. It can filter results by name patterns, regular expressions, directory scope, file extension, size, modification date, and traversal depth.

Documentation

This repository includes a Retype documentation site. Run retype start from the repository root to preview it, or retype build to generate static files in .retype/.

• CLI reference: installation, command syntax, options, and examples.
• Graphical launcher: the optional Flet one-shot interface.
• Configuration and presets: lsw-config.json, presets, and .lswignore.
• Filtering guide: how filters combine and how directory traversal behaves.
• Output formats: HTML, TXT, CSV, JSON, JSONL, and Markdown details.
• HTML report guide: tree controls, search, grouping, analytics, and browser behavior.
• Developer reference: function map, execution flow, data contracts, and known implementation notes.
• Documentation deployment: publish the Retype site with GitHub Pages.

Documentation deployment is automated by .github/workflows/retype-pages.yml. Set the repository's GitHub Pages source to GitHub Actions.

Requirements

• Python 3.8 or newer is recommended.
• Installing the package installs Flet so the GUI is available immediately.
• On first run, LSW creates editable user defaults, presets, and .lswignore under %APPDATA%\lsw on Windows.
• HTML analytics are rendered entirely by the generated report, with no external JavaScript dependency or network connection required.

Install as a command

Install the current checkout:

py -m pip install .

After installation, use LSW from any directory:

lsw
lsw --gui

The command remains CLI-first. Running lsw does not open a window; use lsw --gui for the graphical launcher.

Quick start

From the directory containing lsw.py:

python lsw.py --path .

To open the modern desktop launcher:

lsw --gui

This writes tree_output.html and opens it in the default browser. To generate a text tree without opening a browser:

python lsw.py --path . --type txt --out tree.txt --no-browser

To export a filtered inventory:

python lsw.py --path . --type csv --ext .py,.json --ignore node_modules --out inventory.csv

Important behavior notes

• Hidden entries are skipped by the scan functions because names beginning with . are filtered out. The show_hidden config value is currently not consumed.
• --parallel, --no-parallel, and --workers are parsed, but the current execution path scans synchronously.
• The theme config value is loaded but the generated HTML starts in dark mode; the report's own theme button persists the user's browser choice in localStorage.
• .lswignore in the scanned directory takes precedence, followed by the current working directory, the file beside lsw.py, and finally the packaged default in the Python environment.
• Existing files in %APPDATA%\lsw are never overwritten by first-run initialization.
• CLI values override preset values only when the parsed CLI value is not None; argparse defaults can therefore remain in place instead of being replaced by a preset.