folder_rename · folder_attr · folder_sort¶

Three tools for tidying large folders. All are standalone and dependency-free; folder_rename and folder_sort preview by default and change nothing until you pass --apply.

folder_rename — bulk rename¶

folder_rename <path...> [options]      # a file, or a directory's children

Transforms act on the stem (name without extension) unless --include-ext:

Option	Effect
`--replace <find> <with>`	literal substring replace
`--regex <pat> <repl>`	regex replace (ECMAScript; `$1` in `<repl>`)
`--lower` / `--upper`	change case
`--prepend <text>` / `--append <text>`	add to front / back
`--pattern <template>`	rebuild the whole name from tokens (exclusive)

Tokens (in --pattern, and in --prepend/--append): {stem} {ext} {name} {parent} {n} {n:W} (zero-padded width) {date:FMT}.

# Sequential numbering:  000_, 001_, 002_ …   (--start sets the first number)
folder_rename ./photos --prepend "{n:03}_" --start 0 --apply

# Date stamp before the extension
folder_rename report.txt --append "_{date:%Y%m%d}" --apply

# Regex: IMG_1234.jpg -> photo-1234.jpg
folder_rename ./photos --regex "IMG_([0-9]+)" "photo-\$1" --apply

# Full template
folder_rename ./scans --pattern "{date:%Y-%m-%d}_{n:03}_{stem}.{ext}" --apply

Collisions (target exists, or two files map to one name) are skipped unless --overwrite.

folder_attr — attributes, permissions, timestamps¶

folder_attr <path...>                   # no change options = view
folder_attr <path...> [changes] [-R] [--dry-run]

Cross-platform: --mtime "now" or --mtime "YYYY-MM-DD HH:MM:SS"
Windows: --readonly|--hidden|--system|--archive <on|off>
POSIX: --chmod <octal> (e.g. 644), --owner <user>, --group <group>

-R/--recursive descends; --jobs -1 uses all cores; --dry-run previews.

folder_attr ./build -R --readonly off            # clear read-only on a tree (Windows)
folder_attr ./scripts -R --chmod 755             # make executable (POSIX)
folder_attr photo.jpg --mtime "2020-07-01 12:00:00"

folder_sort — organize into a templated tree¶

folder_sort <src...> <dest> [--by <layout> | --template "<t>"] [--move] [--apply]

Built-in layouts (--by): date → {year}/{month}/{name}, month, type (images/video/audio/documents/archives/code/other), ext, letter. Or write a --template with tokens {name}{stem}{ext}{category}{firstletter}{year}{month}{day}{date:FMT}{size}{idx}{idx:W}.

folder_sort ~/Downloads ~/Sorted --by type --apply         # copy into images/, audio/, …
folder_sort ./dump ./tree --template "{year}/{category}/{name}" --move --apply

Copies by default (--move to move); name clashes get a " (2)" suffix (--skip to skip). A CSV index of every move is written for later lookup / undo.