fslint — file system lint

fslint checks filenames in a directory against configurable naming conventions and reports violations. It ships with companion fixer scripts that rename device-specific filenames into a consistent YYYY-MM-DD originalname.ext format.

Requirements

• Python 3.12+

Installation

pip install fslint

Quick Start

Check every entry in the current folder for a valid date prefix:

fslint --dateprefix .

Only check files (skip folders):

fslint --isfile --dateprefix .

Only check .jpg files:

fslint --isext jpg --dateprefix .

Combine filters:

fslint --isfile --isext mp4 --pattern 'VID_*' --dateprefix ./videos/

Options

Option	Description
--dateprefix	Require a date prefix like 2026, 2026-04, or 2026-04-01
--isfolder	Apply filters only to folders
--isfile	Apply filters only to files (skips folders)
--isext EXT	Only check files with the given extension (e.g., jpg, mp4, md). Case-insensitive; leading dot is optional.
--pattern GLOB	Require filenames to match a glob pattern (e.g., IMG_*, [0-9]*)

Filters are cumulative — an entry must pass all active filters to be included in validation. If a filter excludes an entry, it is silently ignored.

Date Prefix Rules

The date prefix must be one of:

• YYYY (e.g., 2026-report)
• YYYY-MM (e.g., 2026-04-notes)
• YYYY-MM-DD (e.g., 2026-04-01-meeting)

Partial or malformed dates are rejected:

• 2026-9 — single-digit month
• 2026-Jan-14 — alpha month name
• 2026-04- — trailing dash with no day

Fixer Scripts

Fixer scripts live in src/fslint/ and rename files from device-specific formats into a consistent YYYY-MM-DD originalname.ext convention. Each script runs in dry-run mode by default; pass --execute to apply changes.

Script	Matches	Example
fix_iphone.py	iPhone photos/videos (IMG_YYYYMMDDHHMMSS)	IMG_20260628143022.HEIC → 2026-06-28 IMG_20260628143022.HEIC
fix_android_video.py	Android camera videos (VID_YYYYMMDD_HHMMSSmmm or YYYY-MM-DD-HHMMSSmmm)	VID_20241204_133122319.mp4 → 2024-12-04 VID_20241204_133122319.mp4
fix_android_photo.py	Android photos (IMG_YYYYMMDD_HHMMSSmmm_AE)	IMG_20260626_180649578_AE.jpg → 2026-06-26 IMG_20260626_180649578_AE.jpg
fix_android_live.py	Android live/motion photos (lv_0_YYYYMMDDHHMMSS)	lv_0_20260628103849.mp4 → 2026-06-28 lv_0_20260628103849.mp4
fix_android_screenshot.py	Android screenshots (Screenshot_YYYYMMDD-HHMMSS.AppName or without app suffix)	Screenshot_20260625-192203.Instagram.png → 2026-06-25 Screenshot_20260625-192203.Instagram.png
fix_linux_screenshot.py	Linux desktop screenshots (Screenshot from YYYY-MM-DD HH-MM-SS)	Screenshot from 2025-11-22 23-59-49.png → 2025-11-22 Screenshot from 2025-11-22 23-59-49.png
fix_mobizen.py	Mobizen screen recordings (mobizen_YYYYMMDD_HHMMSS)	mobizen_20241204_202058.mp4 → 2024-12-04 mobizen_20241204_202058.mp4
fix_snapchat.py	Snapchat videos (Snapchat-NUMBER) — no date info available	Reports found files; cannot auto-rename without metadata
fix_eu_ddmmyy.py	DDMMYY six-digit prefix (European style, folders or files)	100926 Bad → 2026-09-10 Bad
fix_taiji_yymmdd.py	YYMMDD six-digit prefix (folders or files)	260910 Bad → 2026-09-10 Bad
fix_usa_mmddyy.py	MMDDYY six-digit prefix (US style, folders or files)	091026 Bad → 2026-09-10 Bad
fix_kodak_scans.py	Kodak scanner folders (MM D YY)	09 5 02 → 2002-09-05

All fixers preserve the original filename and prepend an ISO date so files sort chronologically and pass fslint --dateprefix.

Exit Codes

• 0 — no violations found
• 1 — one or more violations reported

Get Involved