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.

Public package: lsw-directory-walker on PyPI.

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.
• Installation: install the public PyPI package and use the lsw command.
• Graphical launcher: the Flet one-shot interface included with the package.
• 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.
• Release guide: publish future versions to PyPI.

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

Future releases can be prepared with .\scripts\release.ps1, which bumps the version, runs checks, builds the package, pushes the release commit, and creates the GitHub Release that triggers PyPI publishing.

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 public package:

py -m pip install lsw-directory-walker

For development, install the current checkout with 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.