From 4dba59b0a1ad94d745608efc0642f38117026a22 Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Mon, 30 Nov 2020 08:08:49 -0800 Subject: [PATCH] ;check: doc updates --- hledger/Hledger/Cli/Commands/Check.md | 96 ++++++++++++++++++--------- 1 file changed, 63 insertions(+), 33 deletions(-) diff --git a/hledger/Hledger/Cli/Commands/Check.md b/hledger/Hledger/Cli/Commands/Check.md index 820f67283..15fd06212 100644 --- a/hledger/Hledger/Cli/Commands/Check.md +++ b/hledger/Hledger/Cli/Commands/Check.md @@ -1,44 +1,74 @@ check\ -Check for various kinds of errors in your data. +Check for various kinds of errors in your data. +*experimental* _FLAGS hledger provides a number of built-in error checks to help -prevent problems in your data. Some, but not all, of these are run -automatically before all commands. You can also use this `check` -command to run any of the available tests. They are named, -and run, as follows: +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. +Use it as follows: -`hledger check` runs the basic checks, like all other commands, -but with no output unless there is a problem. These are: +- `hledger check` - runs the basic checks +- `hledger check -s` - runs the basic + strict checks +- `hledger check CHECK1 CHECK2 ..` - runs the basic + specified checks. + +Here are the checks currently available: + +### Basic checks + +These are always run by this command and other commands: + +- **parseable** - data files are well-formed and can be + [successfully parsed](hledger.html#input-files) + +- **autobalanced** - all transactions are [balanced](journal.html#postings), + inferring missing amounts where necessary, and possibly converting commodities + using [transaction prices] or automatically-inferred transaction prices + +- **assertions** - all [balance assertions] in the journal are passing. + This can be disabled with `-I`/`--ignore-assertions`. + +### Strict checks + +These are always run by this and other commands when `-s`/`--strict` is used +([strict mode]): + +- **accounts** - all account names used by transactions + [have been declared](journal.html#account-error-checking) + +- **commodities** - all commodity symbols used + [have been declared](journal.html#commodity-error-checking) + +### Other checks + +These checks can be run by specifying their names as arguments to the check command: + +- **ordereddates** - transactions are ordered by date (similar to the old `check-dates` command) + +- **uniqueleafnames** - all account leaf names are unique ((similar to the old `check-dupes` command) + +This command would run all of the checks above: +```shell +$ hledger check -s ordereddates uniqueleafnames +``` + +### Addon checks + +Some checks are not yet integrated with this command, but are available as +[addon commands] in : + +- **hledger-check-tagfiles** - all tag values containing / (a forward slash) exist as file paths + +- **hledger-check-fancyassertions** - more complex balance assertions are passing + +You could make your own similar scripts to perform custom checks; +Cookbook -> [Scripting](scripting.html) may be helpful. -- **parseable** - data files are well-formed and can be [successfully parsed](hledger.html#input-files) -- **autobalanced** - all transactions are [balanced](journal.html#postings), 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`) [transaction prices]: journal.html#transaction-prices [balance assertions]: journal.html#balance-assertions [strict mode]: hledger.html#strict-mode - -`hledger check --strict` also runs the additional "strict mode" checks, -which are: - -- **accounts** - all account names used by transactions [have been declared](journal.html#account-error-checking) -- **commodities** - all commodity symbols used [have been declared](journal.html#commodity-error-checking) - -`hledger check CHECK1 CHECK2 ...` runs all of the named checks, in turn. -This may be useful when neither the default nor strict checks are exactly -what you want, or when you want to focus on a single check of interest. -The arguments are standard lowercase names for the checks. Currently -only these checks can be run in this way: - -- **dates** - transactions are ordered by date (similar to the old `check-dates` command) -- **leafnames** - all account leaf names are unique ((similar to the old `check-dupes` command) - -See also: - -Some checks are shipped as addon scripts for now -(cf , and Cookbook -> [Scripting](scripting.html)): - -- **tagfiles** - all tag values containing / (a forward slash) exist as file paths -- **fancyassertions** - more complex balance assertions are passing +[addon]: hledger.html#addon-commands \ No newline at end of file