Checking for errors

hledger can check your data in various ways. Here are some checks/desirable properties, with short names for convenience:

These checks are run always (with all hledger commands, eg hledger stats >/dev/null):

  • parseable - data files are well-formed and can be successfully parsed
  • autobalanced - all transactions are balanced, inferring missing amounts where necessary, and possibly converting commodities using transaction prices or automatically-inferred transaction prices
  • assertions - all balance assertions are passing (except with -I/--ignore-assertions)

These checks are run only in hledger-1.19.99's strict mode (eg hledger stats --strict):

These checks are run by special commands (for now):

  • dates - transactions are ordered by date (command: hledger check-dates)
  • leafnames - all account leaf names are unique (command: hledger check-leafnames)
  • tagfiles - all tag values containing / (a forward slash) exist as file paths (addon command: hledger-check-tagfiles.hs)
  • fancyassertions - more complex balance assertions are passing (addon command: hledger-check-fancyassertions.hs)

The addon commands are available in https://github.com/simonmichael/hledger/tree/master/bin (cf Scripting).

Todo / maybe

These are some checks we might add in future:

  • accountsactive - for each account used, if there is posting with an open: tag, it must have a corresponding posting with a close: tag, and all other postings must be chronologically between (and if on the same date, textually between) open and close postings. ("Accounts are posted to only within their declared active period.")
  • payees - all payee names used have been declared
  • pricebalanced - transactions are balanced, possibly using explicit transaction prices but not auto-inferred ones
  • fullybalanced - transactions are balanced in each commodity, without needing any conversions
  • explicitamounts - all transaction amounts have been recorded explicitly

Comparing report output

Commit some hledger report output into your version control system. Then you can detect any changes, eg:

$ hledger COMMAND > report.txt; git diff -- report.txt

Pre-commit hook

Version control systems often support a "pre-commit hook", a script which is run and required to succeed before each commit. Eg:

#!/bin/bash
set -e
hledger stats -s

Diffing

Here's another way to check for undeclared accounts, that works with older hledger versions, showing some diff tricks:

$ diff -U0 --label "Unused Accounts" --label "Undeclared Accounts" <(hledger accounts --declared) <(hledger accounts --used)