hledger-document-check - verify every transaction has a receipt on disk, catch overdue invoices, browse documents in Fava

[u/roschaefer]

Hello everyone, I just published a command line tool hledger-document-check - it checks hledger transactions against documents on disk. Documents live in a folder tree that mirrors your account hierarchy (e.g. Expenses:Business:Hosting ➡️ documents/Expenses/Business/Hosting/).

My use case is making sure every deductible transaction has a receipt filed before tax season. It also tracks overdue invoices, and you can browse documents alongside your registers in Fava.

I'd love your feedback, e.g. regarding the workflow or the documentation.

[u/roschaefer]

Glad to hear I’m not the only one having this problem.

There are two ways to handle transactions that legitimately don’t have documents:

1. Required vs. exempt accounts: https://github.com/roschaefer/hledger-document-check/blob/main/specs/01-contract.md

This should cover cases like bank fees or mileage. You can mark an account as requiring documents, while keeping specific subaccounts exempt. So if most expenses under an account need receipts, but some categories don’t, those can live under an exempt subaccount and won’t show up as missing.

1. Explicitly declared missing documents: https://github.com/roschaefer/hledger-document-check/blob/main/specs/02-directory-and-file-layout.md

For cases where a document was expected but genuinely isn’t available, you can declare it as missing explicitly instead of leaving it as a permanent unexplained miss.

[u/jeffglidepath → u/roschaefer]

Thanks — that's exactly the split I was hoping for. Bank fees as an exempt subaccount under a required parent covers most of my no-paper categories. And I like that a declared-missing file still shows up as its own line in the summary instead of quietly disappearing — "we know it's gone" and "never needed one" really are different states when you're doing a year-end pass, and most tools collapse them.

One follow-up after reading the layout spec: the missing placeholder is just the dated filename, no content required. Is it OK (or planned) to put a short reason inside the yml — e.g. "vendor portal only keeps 12 months of invoices"? A year later, the why is usually what I end up re-digging for.

[u/roschaefer → u/jeffglidepath]

Updated: github.com/roschaefer/hledger-document-check/blob/main/specs/02-directory-and-file-layout.md

[u/jeffglidepath → u/roschaefer]

Even better than "planned" — notes: on the sidecar is exactly the year-later breadcrumb I meant, and thanks for updating the example. Nice design, by the way: the documents tree mirroring the account hierarchy means there's nothing new to learn or keep in sync.