Filtering and Traversal

LSW applies filters while walking the directory tree. The scan functions share the same broad rules, with small output-specific differences documented in Output formats.

Evaluation order

For each entry, the scanner generally:

1. Lists entries and removes names beginning with ..
2. Applies ignore names, glob patterns, and ignore regexes.
3. For directories, applies --ignore and root-level --include rules, then recurses.
4. For files, applies root-level include-directory behavior, include patterns/regexes, extension filters where supported, size filters, and date filters.

An ignored directory is pruned and none of its descendants are considered. Include-directory filtering is only applied at the scan root; nested directories remain containers for matching files.

Include versus ignore

Ignore rules are exclusions and take effect before inclusion. Include patterns and regexes are file whitelists: a file must match at least one supplied include pattern or regex. If no include rule is supplied, all non-hidden files are eligible.

--include is different: it names directories allowed directly under the scan root. When it is supplied, root-level files are skipped and only named root-level directories are traversed.

Examples:

# Keep Python files, except generated files
python lsw.py --ext .py --ignore-pattern "*.generated.py,*.pyc"

# Search only source and test roots for TypeScript files
python lsw.py --include src,test --include-pattern "*.ts"

# Use a regex whitelist for names beginning with test_
python lsw.py --include-regex "^test_.*"

Depth

Depth starts at 0 for the scan root. If --max-depth N is set, a function returns without processing entries when the current depth is greater than or equal to N. Thus --max-depth 1 lists root-level entries but does not enumerate their children.

Size and dates

Size checks use file byte counts from os.stat. Directory entries are not filtered by their aggregate size. Date checks use each file's modification timestamp. A file exactly on a minimum or maximum boundary is included.

Current edge cases

• Extension matching is case-sensitive because the supplied extension and os.path.splitext() result are compared directly.
• The text output path does not pass --ext to its tree generator, so --ext has no effect when --type txt is selected.
• The HTML analytics treemap rebuilds a filesystem tree independently and does not apply the report's filters in the same way as the visible tree. Treat it as contextual size information rather than an exact filtered export.