Rename With Dates

Rename Documents with Date Prefixes

Rename files in a folder by extracting the effective date from their content and giving them a clean, human-readable title.

Target format

YYYY-MM-DD - Clear descriptive title.ext

Title casing: capitalize only the first word and proper nouns (title case), like a sentence.

Examples:

• 2023-11-01 - General terms and conditions.pdf
• 2025-08-01 - Credit card fees and charges.pdf
• 2025-12-01 - Key facts statement - Term deposits.pdf
• 2024-06-15 - Rewards program earning structure.png
• 2024-03-01 - Schedule of charges.pdf

Period documents that cover a date range (statement exports, period reports) may extend the prefix to YYYY-MM-DD--YYYY-MM-DD - Title.ext — preserve that convention where a folder already uses it.

Supported file types

• PDFs: Read the first few pages (and last page if needed) to find dates and understand content. The Read tool rejects PDFs over 20MB: render their pages to images with pdftoppm -png -r 30 and view those instead
• Images / Screenshots (PNG, JPG, etc.): View the image to understand its content, then summarize it into a clear descriptive title. For screenshots, the date is often embedded in the filename (e.g., Screenshot 2026-01-12 at 11.07.33.png → date is 2026-01-12)
• Office documents: for .xlsx, read docProps/core.xml inside the zip (unzip -p file.xlsx docProps/core.xml) for dcterms:created; for Apple .numbers, the package often embeds a readable preview.jpg or preview.pdf. A stray .~lock.*# file next to a document is a LibreOffice lock: the document may be open somewhere (possibly on another synced machine); stale locks are trash candidates
• Emails exported/printed to PDF: use the email's sent date from its header, never the print/export date; derive the title from the subject and outcome of the thread
• Photo archives: a folder full of personal photos (IMG_1234.jpeg dumps) is an archive, not a document set — propose skipping it wholesale instead of dating each file. Rename a photo only when it acts as a document (appliance rating plate, meter photo, signed-form snapshot), dating it from EXIF DateTimeOriginal via exiftool
• Other documents: Read content where possible to extract dates and meaning

Workflow

1. List files in the target directory (default: current working directory, or $ARGUMENTS if provided)

2. Skip files that already follow the YYYY-MM-DD - Title.ext pattern (but offer to clean up their titles if needed). A bare date with no title (like 2023-08-17.pdf) is not compliant — read the file and add the missing title (often just Invoice or Receipt inside a provider folder, where the folder name already gives context)

3. Read each file to find the effective date and understand the content:

   • For PDFs:
     • Look for explicit "Effective from..." or "Effective date" statements — prefer these
     • Look for version dates in footers (e.g., "08/2025", "v. August 14, 2023")
     • Beware date-lookalike version codes: a code like V160701.1 reads as YYMMDD but may be template artwork — if the same code appears on documents with different effective dates, it is not a date. Reference codes (like CRN FRM021121) often embed a MMDDYY date and corroborate other evidence at month precision
     • Filenames that are bare reference codes or portal export IDs (like LICDSO202600109568.pdf or bill-3733181.pdf) are almost always invoices or receipts — open them; the code itself rarely matters to the user
     • When two files resolve to the same date and the same title, re-inspect before renaming: one is usually a different document type (like an annual statement of accounts issued the same day as the monthly invoice)
     • Look for dated headers, cover pages, or document stamps
     • Use the effective/applicability date, not the publication or copyright date
   • For images/screenshots:
     • View the image to understand what it shows
     • Extract date from the original filename if it contains one (e.g., Screenshot 2026-01-12 at ...)
     • If the image contains visible dates in its content, prefer those
     • If no date can be found, ask the user
   • Match the date precision to what the document provides: use YYYY-MM-DD for exact dates, YYYY-MM for month-only, YYYY for year-only

4. Choose a clear title:

   • Use sentence case: capitalize only the first word and proper nouns
   • Be descriptive but concise (e.g., "Credit card fees and charges", not "popularbankname_credit_card_fees_charges")
   • For screenshots: summarize what the image shows (e.g., "Rewards program earning structure", "Account balance overview")
   • Keep well-known abbreviations uppercase: KFS, FAQ, T&C
   • Remove redundant institution names if the folder context already makes it clear
   • When two documents of the same type share the same effective date but cover different product segments, disambiguate in the title (like KFS - Credit cards (Skywards, Cash+ and Live+) vs KFS - Credit cards (Private Bank, Premier and Advance))
   • Manuals and spec sheets: title as Brand Model - Doc type (like Gorenje WHT923E5XUK - Cooker hood manual); vendor doc codes often embed the publication date (Grohe …/02.19 = February 2019)

5. Present a summary table showing current name, detected date, and proposed new name

6. Rename all files after presenting the plan. On case-insensitive filesystems (macOS APFS), a case-only rename fails with "are the same file" — do it in two steps through a temporary name

7. Post-rename analysis — after renaming, scan the folder for cleanup opportunities and present a report with three sections:

   • Duplicates: Compare files with similar titles using MD5 checksums (md5 -r). Files with identical hashes are exact duplicates. Propose keeping one and trashing the others. If an undated file is an exact duplicate of an already-compliant one, do not rename it into a name collision — leave its name untouched and propose trashing it. Also compare content when hashes differ but titles match: re-downloads of the same document often differ only in PDF metadata. Printed document numbers (invoice number, receipt number, DocuSign envelope ID) are reliable fingerprints for catching these content-duplicates.

   • Superseded documents: Identify files that are older versions of the same document type (e.g., "Personal banking general T&C" from 2023 vs 2025). The newer version supersedes the older. Propose trashing the older version.

   • Expired documents: For time-bound documents (campaigns, offers, promotions) that specify a validity period (e.g., "1 November 2025 – 31 December 2025"), check if the end date has passed relative to today. Propose trashing expired ones. Do not flag standing T&Cs, KFS documents, or privacy policies — only documents with explicit campaign/offer end dates.

   • Not applicable: documents covering products or services the user does not hold (other product tiers' T&C, KFS for products never subscribed, forms for other customer segments). Ask the user to confirm their actual holdings, then propose trashing the rest — documents for held products stay, as they are the contractual record of the terms in force.

   When the user approves trashing, move the files into a dated subfolder like ~/.Trash/{folder} cleanup YYYY-MM-DD/ so the whole batch stays grouped and recoverable. Writing into ~/.Trash is typically blocked by the command sandbox — run that step outside the sandbox.

8. Verify by listing the final result with plain binaries — ls may be aliased (eza, lsd) and print nothing when piped — and run a compliance sweep: /usr/bin/find . -type f | sed 's|.*/||' | grep -Ev '^[0-9]{4}(-[0-9]{2})?(-[0-9]{2})?(--[0-9]{4}-[0-9]{2}-[0-9]{2})? - ' should return only intentionally held files

Multi-language PDF stripping

Many legal/banking documents repeat the same content translated across several languages, organized as consecutive blocks of pages (e.g., pages 1-10 in English, 11-20 in Arabic, 21-30 in Bulgarian). When detected, propose stripping to keep only English and French pages.