From 4abb8ffc2efe320fd25bb69b17465d51d34cac8a Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Thu, 2 May 2024 19:59:00 -1000 Subject: [PATCH] ;doc: check: expand check descriptions --- hledger/Hledger/Cli/Commands/Check.md | 96 ++++++++++++++------------- 1 file changed, 49 insertions(+), 47 deletions(-) diff --git a/hledger/Hledger/Cli/Commands/Check.md b/hledger/Hledger/Cli/Commands/Check.md index eeb13e968..4a890ea66 100644 --- a/hledger/Hledger/Cli/Commands/Check.md +++ b/hledger/Hledger/Cli/Commands/Check.md @@ -4,76 +4,90 @@ Check for various kinds of errors in your data. _FLAGS -hledger provides a number of built-in correctness checks to help -prevent problems in your data. -Some of these are run automatically; or, -you can use this `check` command to run them on demand, -with no output and a zero exit code if all is well. -Specify their names (or a prefix) as argument(s). - -Some examples: +hledger provides a number of built-in correctness checks to help validate your data and prevent errors. +Some are run automatically, some when you enable `--strict` mode; +or you can run any of them on demand with this `check` command. +`check` produces no output and a zero exit code if all is well. +Eg: ```cli -hledger check # basic checks -hledger check -s # basic + strict checks -hledger check ordereddates payees # basic + two other checks +hledger check # run basic checks +hledger check -s # run basic and strict checks +hledger check ordereddates payees # run basic checks and two others ``` If you are an Emacs user, you can also configure flycheck-hledger to run these checks, providing instant feedback as you edit the journal. Here are the checks currently available. -They are performed in the order they are shown here. -(Eg, an `ordereddates` failure takes precedence over an `assertions` failure). +Generally, they are performed in the order they are shown here (and only the first failure is reported). -### Default checks +### Basic checks -These checks are always performed, by (almost) all hledger commands: +These important checks are performed by default, by almost all hledger commands: - **parseable** - data files are in a supported [format](#data-formats), - with no syntax errors and no invalid include directives + with no syntax errors and no invalid include directives. + This ensures that all files exist and are readable. - **autobalanced** - all transactions are [balanced](#postings), after inferring missing amounts and conversion [costs] where possible, - and then converting to cost + and then converting to cost. + This ensures that each individual transaction is well formed. - **assertions** - all [balance assertions] in the journal are passing. - (This check can be disabled with `-I`/`--ignore-assertions`.) + Balance assertions are like canaries in your journal, they catch many problems. + This check can sometimes get in the way, eg when you are troubleshooting bookkeeping errors, + or parsing a journal fragment, so it can be disabled temporarily with `-I`/`--ignore-assertions`. ### Strict checks -These additional checks are run when the `-s`/`--strict` ([strict mode]) -flag is used with any command; or, -when they are given as arguments to the `check` command: +These additional checks are performed by any command when the `-s`/`--strict` flag is used (AKA [strict mode]). +They provide extra error-catching power when you are serious about keeping your data clean and free of typos: -- **balanced** - like `autobalanced`, but conversion costs will not be - inferred, and must be written explicitly +- **balanced** - like `autobalanced`, but in [conversion transactions](#recording-costs), + costs must be written explicitly. This ensures some redundancy in the entry, guarding against typos. -- **commodities** - all commodity symbols used - [have been declared](#commodity-error-checking) +- **commodities** - all commodity symbols used [must be declared](#commodity-error-checking). + This guards against forgetting or mistyping commodity symbols. -- **accounts** - all account names used - [have been declared](#account-error-checking) +- **accounts** - all account names used [must be declared](#account-error-checking). + This prevents the use of mistyped or outdated account names. ### Other checks -These checks can be run by giving their names as arguments to `check`: +These other checks are not wanted by everyone, but can be run using the `check` command: -- **ordereddates** - within each file, transactions are ordered by date +- **ordereddates** - within each file, transactions are ordered by date. + This is a simple and effective error catcher, and you should use it. + Alas! not everyone wants it. If you do, use `hledger check -s ordereddates`. -- **payees** - all payees used by transactions [have been declared](#payee-directive) +- **payees** - all payees used by transactions [must be declared](#payee-directive). + This will force you to always use known/declared payee names. + For most people this is a bit too restrictive. -- **tags** - all tags used by transactions [have been declared](#tag-directive) +- **tags** - all tags used by transactions [must be declared](#tag-directive). + This prevents mistyped tag names. -- **recentassertions** - all accounts with balance assertions have a - balance assertion within 7 days of their latest posting +- **recentassertions** - all accounts with balance assertions must have + a balance assertion within the last 7 days before their latest posting. + This encourages you to add balance assertions fairly regularly for + your active asset/liability accounts, which in turn should encourage + you to check and reconcile with their real world balances fairly regularly. + [`close --assert`](#close---assert) can be helpful. + (The older balance assertions become redundant; you can remove them + periodically, or leave them in place, perhaps commented, as documentation.) -- **uniqueleafnames** - all account leaf names are unique +- **uniqueleafnames** - no two accounts may have the same leaf name. + The leaf name is the last colon-separated part of an account name, eg + `checking` in `assets:bank:checking`. + This encourages you to keep those unique, effectively giving each account + a short name which is easier to remember and to type in reporting commands. ### Custom checks You can build your own custom checks with [add-on command scripts]. -(See also [Cookbook > Scripting](scripting.html).) +See also [Cookbook > Scripting](scripting.html). Here are some examples from [hledger/bin/](https://github.com/simonmichael/hledger/tree/master/bin): - **hledger-check-tagfiles** - all tag values containing / (a forward slash) exist as file paths @@ -81,18 +95,6 @@ Here are some examples from [hledger/bin/](https://github.com/simonmichael/hledg - **hledger-check-fancyassertions** - more complex balance assertions are passing -### More about specific checks - -`hledger check recentassertions` will complain if any balance-asserted account -has postings more than 7 days after its latest balance assertion. -This aims to prevent the situation where you are regularly updating your journal, -but forgetting to check your balances against the real world, -then one day must dig back through months of data to find an error. -It assumes that adding a balance assertion requires/reminds you to check the real-world balance. -(That may not be true if you auto-generate balance assertions from bank data; -in that case, I recommend to import transactions uncleared, -and when you manually review and clear them, also check the latest assertion against the real-world balance.) - [add-on command scripts]: #add-on-commands [balance assertions]: #balance-assertions [strict mode]: #strict-mode