# 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

Submit issues

If you spotted something weird in application behavior or want to propose a feature you are welcome.

Write code

Fork the project, write your code — whether it should be a bugfix or a feature implementation — and make a pull request.

Spread the word

If you have tips and tricks or any other words in mind that might be of interest to others, publish them.

fslint Next »