A PowerShell automation tool that syncs receipt files into a formatted Excel workbook. Metadata is encoded directly in receipt filenames -- no manual data entry.

Receipt files are named with embedded metadata:

yyMMdd Vendor $Amount [Method [Account]].ext

yyMMdd is a .NET ParseExact format string: yy = 2-digit year, MM = month, dd = day.

Method and Account are optional. If omitted, the row is written to the workbook with both fields blank and flagged Method missing so the user can fill them in.

The Account field is the last 4 digits of the card or account number. Two special tokens are also accepted:

Cash receipts carry no account number.

Examples:

260301 Landlord $1200.00 Checking 7890.pdf
260305 CVS $12.00 Cash.pdf
260310 Sunoco $5.27 Card 3621.pdf
260315 Amazon $34.99 Card xxxx.pdf
260320 Costco $67.50 Card ----.pdf
260325 Employer -$2500.00 Savings 7890.pdf
260328 Vendor $5.00.pdf

Running a .bat launcher triggers the PowerShell script, which parses every receipt in the target month folder and writes a formatted table into a per-year workbook (e.g. 2026.xlsx) -- one sheet per month (e.g. 2603 for March 2026).

• Windows 10/11
• PowerShell 5.0+
• Microsoft Excel 2016+

1. Double-click Setup.bat -- it will:
   • Check that PowerShell 5.0+ and Excel are installed
   • Prompt for RECEIPTS_ROOT and WORKBOOKS_ROOT (defaults to RECEIPTS_ROOT), then create Config.ini (skipped if Config.ini already exists)
   • Create the RECEIPTS_ROOT and WORKBOOKS_ROOT folders if they do not exist (prompts for confirmation)
   • Copy Config\Templates\Accounts.template.xlsx to Config\Accounts.xlsx (skipped if already present)
   • Create Run Sync Receipts.lnk, Run Sync Month Receipts.lnk, Run Sync Year Receipts.lnk, and Run Sync All Receipts.lnk shortcuts in RECEIPTS_ROOT
2. Open Config\Accounts.xlsx and replace the example rows with your own accounts
3. Copy Config\Templates\Categories.template.json to Config\Categories.json and edit to customise your categories (skipped if already present)
4. Copy Config\Templates\Methods.template.json to Config\Methods.json and edit to customise the accepted payment method tokens (skipped if already present)
5. For the first run, use the Run Sync All Receipts.lnk shortcut in RECEIPTS_ROOT to sync all existing receipts across all years into workbooks
6. After the initial sync, use Run Sync Receipts.lnk for day-to-day syncing of the current month. Use the month and year launchers when correcting past entries.

Setup.bat is safe to re-run -- it skips steps that are already complete.

The script files and the data are kept in separate locations. RECEIPTS_ROOT is set in Config\Config.ini.

Script files (e.g. C:\Scripts\Sync-Receipts\):
    Setup.bat                <- one-time setup launcher
    Config\
        Config.ini               <- gitignored; sets RECEIPTS_ROOT
        Accounts.xlsx            <- gitignored; your personal accounts
        Categories.json          <- gitignored; your personal categories
        Methods.json             <- gitignored; your personal method tokens
        SensitivePatterns.json   <- gitignored; your sensitive data patterns (created by Setup.bat)
        Templates\
            Config.template.ini             <- generic template committed to git
            Accounts.template.xlsx          <- default accounts template; committed to git
            Categories.template.json        <- default categories template; committed to git
            Methods.template.json           <- default method tokens template; committed to git
            SensitivePatterns.template.json <- default sensitive data patterns; committed to git
    Scripts\
        Initialize-SyncReceipts.ps1
        Sync-Receipts.ps1
        New-AccountsTemplate.ps1     <- regenerates Config\Templates\Accounts.template.xlsx after schema changes
        Install-GitHooks.ps1         <- copies Scripts\hooks\ into .git\hooks\
    Launchers\
        Run-SyncReceipts.bat
        Run-SyncMonthReceipts.bat
        Run-SyncYearReceipts.bat
        Run-SyncAllReceipts.bat
    Kill-Excel.bat           <- force-closes hung EXCEL.EXE processes (gitignored)

RECEIPTS_ROOT (e.g. \\Server\Share\Receipts\):
    2026.xlsx                <- created automatically on first sync for that year
    2025.xlsx
    2026\
        2603 - March\
            260301 Vendor $10.00 Card 3621.pdf
            ...
        2602 - February\
            ...
    2025\
        ...

Per-year workbooks (e.g. 2026.xlsx) are written to WORKBOOKS_ROOT when set in Config\Config.ini, defaulting to RECEIPTS_ROOT if WORKBOOKS_ROOT is not configured.

Launchers\Run-SyncReceipts.bat is the standard day-to-day launcher. The other launchers are for initial setup and correcting past entries.

To force-close a crashed Excel instance holding the file locked, run the Sync: Current month (KillExcel) VS Code task, or add -KillExcel to the PowerShell command inside Launchers\Run-SyncReceipts.bat.

A dedicated Excel workbook at Config\Accounts.xlsx (gitignored). Copy from Config\Templates\Accounts.template.xlsx and fill in your accounts. The script reads Last 4 (column A) and Method (column B) for validation and disambiguation; all other columns are for human reference only.

Notes:

• The same Last 4 may appear on multiple rows when the same number is used for different methods (e.g. a bank account number shared across Checking and Check). Set Method on each row to disambiguate.
• Cash: no entry needed in Accounts.xlsx -- Cash receipts carry no account number in the filename.
• Inactive accounts are flagged Account inactive in the workbook rather than Account not in Accounts.xlsx.

If Accounts.xlsx is absent, account validation is skipped.

Written and maintained automatically by the script on every run; hidden in the tab bar. Category and subcategory data is sourced from Config\Categories.json (gitignored). Copy from Config\Templates\Categories.template.json to get started.

Created or overwritten on each run. Contains a 9-column table:

GNU General Public License v3.0 -- see LICENSE.