Debian Codegraph @

Hledger/Cli/Commands/Check.txt

raw
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