| 1 |
check |
| 2 |
|
| 3 |
Check for various kinds of errors in your data. |
| 4 |
|
| 5 |
Flags: |
| 6 |
no command-specific flags |
| 7 |
|
| 8 |
hledger provides a number of built-in correctness checks to help |
| 9 |
validate your data and prevent errors. Some are run automatically, some |
| 10 |
when you enable --strict mode; or you can run any of them on demand by |
| 11 |
providing them as arguments to the check command. check produces no |
| 12 |
output and a zero exit code if all is well. Eg: |
| 13 |
|
| 14 |
hledger check # run basic checks |
| 15 |
hledger check -s # run basic and strict checks |
| 16 |
hledger check ordereddates payees # run basic checks and two others |
| 17 |
|
| 18 |
If you are an Emacs user, you can also configure flycheck-hledger to run |
| 19 |
these checks, providing instant feedback as you edit the journal. |
| 20 |
|
| 21 |
Here are the checks currently available. They are generally checked in |
| 22 |
the order they are shown here, and only the first failure will be |
| 23 |
reported. |
| 24 |
|
| 25 |
Basic checks |
| 26 |
|
| 27 |
These important checks are performed by default, by almost all hledger |
| 28 |
commands: |
| 29 |
|
| 30 |
- parseable - data files are in a supported format, with no syntax |
| 31 |
errors and no invalid include directives. This ensures that all files |
| 32 |
exist and are readable. |
| 33 |
|
| 34 |
- autobalanced - all transactions are balanced, after automatically |
| 35 |
inferring missing amounts and conversion rates and then converting |
| 36 |
amounts to cost. This ensures that each transaction's journal entry is |
| 37 |
well formed. |
| 38 |
|
| 39 |
- assertions - all balance assertions in the journal are passing. |
| 40 |
Balance assertions are a strong defense against errors, catching many |
| 41 |
problems. This check is on by default, but if it gets in your way, you |
| 42 |
can disable it temporarily with -I/--ignore-assertions, or as a |
| 43 |
default by adding that flag to your config file. (Then use -s/--strict |
| 44 |
or hledger check assertions when you want to enable it). |
| 45 |
|
| 46 |
Strict checks |
| 47 |
|
| 48 |
When the -s/--strict flag is used (AKA strict mode), all commands will |
| 49 |
perform the following additional checks (and assertions, above). These |
| 50 |
provide extra error-catching power to help you keep your data clean and |
| 51 |
correct: |
| 52 |
|
| 53 |
- balanced - like autobalanced, but implicit conversions between |
| 54 |
commodities are not allowed; all conversion transactions must use cost |
| 55 |
notation or equity postings. This prevents wrong conversions caused by |
| 56 |
typos. |
| 57 |
|
| 58 |
- commodities - all commodity symbols used must be declared. This guards |
| 59 |
against mistyping or omitting commodity symbols. |
| 60 |
|
| 61 |
- accounts - all account names used must be declared. This prevents the |
| 62 |
use of mis-spelled or outdated account names. |
| 63 |
|
| 64 |
Other checks |
| 65 |
|
| 66 |
These are not wanted by everyone, but can be run using the check |
| 67 |
command: |
| 68 |
|
| 69 |
- tags - all tags used must be declared. This prevents mis-spelled tag |
| 70 |
names. Note hledger fairly often finds unintended tags in comments. |
| 71 |
|
| 72 |
- payees - all payees used in transactions must be declared. This will |
| 73 |
force you to declare any new payee name before using it. Most people |
| 74 |
will probably find this a bit too strict. |
| 75 |
|
| 76 |
- ordereddates - within each file, transactions must be ordered by date. |
| 77 |
This is a simple and effective error catcher. It's not included in |
| 78 |
strict mode, but you can add it by running |
| 79 |
hledger check -s ordereddates. If enabled, this check is performed |
| 80 |
before balance assertions. |
| 81 |
|
| 82 |
- recentassertions - all accounts with balance assertions must have one |
| 83 |
that's within the 7 days before their latest posting. This will |
| 84 |
encourage adding balance assertions for your active asset/liability |
| 85 |
accounts, which in turn should encourage you to reconcile regularly |
| 86 |
with those real world balances - another strong defense against |
| 87 |
errors. (hledger close --assert >>$LEDGER_FILE is a convenient way to |
| 88 |
add new balance assertions. Later these become quite redundant, and |
| 89 |
you might choose to remove them to reduce clutter.) |
| 90 |
|
| 91 |
- uniqueleafnames - no two accounts may have the same last account name |
| 92 |
part (eg the checking in assets:bank:checking). This ensures each |
| 93 |
account can be matched by a unique short name, easier to remember and |
| 94 |
to type. |
| 95 |
|
| 96 |
Custom checks |
| 97 |
|
| 98 |
You can build your own custom checks with add-on command scripts. See |
| 99 |
also Cookbook > Scripting. Here are some examples from hledger/bin/: |
| 100 |
|
| 101 |
- hledger-check-tagfiles - all tag values containing / exist as file |
| 102 |
paths |
| 103 |
|
| 104 |
- hledger-check-fancyassertions - more complex balance assertions are |
| 105 |
passing |