From de5dfe2d1b377c4711706d7327a61f2ff48deada Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Sun, 10 Jan 2021 15:35:48 -0800 Subject: [PATCH] ;update CLI usage texts --- hledger/Hledger/Cli/Commands/Balance.txt | 190 ++++++++++++----------- hledger/Hledger/Cli/Commands/Check.txt | 27 ++-- 2 files changed, 114 insertions(+), 103 deletions(-) diff --git a/hledger/Hledger/Cli/Commands/Balance.txt b/hledger/Hledger/Cli/Commands/Balance.txt index 40d34be7c..a45156fdd 100644 --- a/hledger/Hledger/Cli/Commands/Balance.txt +++ b/hledger/Hledger/Cli/Commands/Balance.txt @@ -29,10 +29,31 @@ html, and json. The balance command can produce several styles of report: -Classic balance report +Single-period flat balance report -This is the original balance report, as found in Ledger. It usually -looks like this: +This is the default for hledger's balance command: a flat list of all +(or with a query, matched) accounts, showing full account names. +Accounts are sorted by declaration order if any, and then by account +name. Accounts which have zero balance are not shown unless -E/--empty +is used. The reported balances' total is shown as the last line, unless +disabled by -N/--no-total. + +$ hledger bal + $1 assets:bank:saving + $-2 assets:cash + $1 expenses:food + $1 expenses:supplies + $-1 income:gifts + $-1 income:salary + $1 liabilities:debts +-------------------- + 0 + +Single-period tree-mode balance report + +With the -t/--tree flag, accounts are displayed hierarchically, showing +subaccounts as short names indented below their parent. (This is the +default style in Ledger and in older hledger versions.) $ hledger balance $-1 assets @@ -48,33 +69,26 @@ $ hledger balance -------------------- 0 -By default, accounts are displayed hierarchically, with subaccounts -indented below their parent, with accounts at each level of the tree -sorted by declaration order if declared, then by account name. +For more compact output, "boring" accounts containing a single +interesting subaccount and no balance of their own (assets:bank and +liabilities here) are elided into the following line, unless --no-elide +is used. And accounts which have zero balance and no non-zero +subaccounts are omitted, unless -E/--empty is used. -"Boring" accounts, which contain a single interesting subaccount and no -balance of their own, are elided into the following line for more -compact output. (Eg above, the "liabilities" account.) Use --no-elide to -prevent this. +Account balances in tree mode are "inclusive" - they include the +balances of any subaccounts. Eg, the assets $-1 balance here includes +the $1 from assets:bank:saving and the $-2 from assets:cash. (And it +would include balance posted to the assets account itself, if there was +any). Note this causes some repetition, and the final total (0) is the +sum of the top-level balances, not of all the balances shown. -Account balances are "inclusive" - they include the balances of any -subaccounts. +Each group of sibling accounts is sorted separately, by declaration +order and then by account name. -Accounts which have zero balance (and no non-zero subaccounts) are -omitted. Use -E/--empty to show them. +Customising single-period balance reports -A final total is displayed by default; use -N/--no-total to suppress it, -eg: - -$ hledger balance -p 2008/6 expenses --no-total - $2 expenses - $1 food - $1 supplies - -Customising the classic balance report - -You can customise the layout of classic balance reports with ---format FMT: +You can customise the layout of single-period balance reports with +--format FMT, which sets the format of each line. Eg: $ hledger balance --format "%20(account) %12(total)" assets $-1 @@ -129,28 +143,12 @@ Some example formats: - %20(total) %2(depth_spacer)%-(account) - the default format for the single-column balance report -Colour support +Depth limiting -In terminal output, when colour is enabled, the balance command shows -negative amounts in red. - -Flat mode - -To see a flat list instead of the default hierarchical display, use ---flat. In this mode, accounts (unless depth-clipped) show their full -names and "exclusive" balance, excluding any subaccount balances. In -this mode, you can also use --drop N to omit the first few account name -components. - -$ hledger balance -p 2008/6 expenses -N --flat --drop 1 - $1 food - $1 supplies - -Depth limited balance reports - -With --depth N or depth:N or just -N, balance reports show accounts only -to the specified numeric depth. This is very useful to summarise a -complex set of accounts and get an overview. +With a depth:N query, or --depth N option, or just -N, balance reports +will show accounts only to the specified depth. This is very useful to +hide low-level accounts and get an overview. Eg, limiting to depth 1 +shows the top-level accounts: $ hledger balance -N -1 $-1 assets @@ -158,8 +156,30 @@ $ hledger balance -N -1 $-2 income $1 liabilities -Flat-mode balance reports, which normally show exclusive balances, show -inclusive balances at the depth limit. +Accounts at the depth limit will include the balances of any hidden +subaccounts (even in flat mode, which normally shows exclusive +balances). + +You can also drop account name components from the start of account +names, using --drop N. This can be useful to hide unwanted top-level +detail. + +Colour support + +In terminal output, when colour is enabled, the balance command shows +negative amounts in red. + +Sorting by amount + +With -S/--sort-amount, accounts with the largest (most positive) +balances are shown first. For example, hledger bal expenses -MAS shows +your biggest averaged monthly expenses first. + +Revenues and liability balances are typically negative, however, so -S +shows these in reverse order. To work around this, you can add --invert +to flip the signs. Or, use one of the sign-flipping reports like +balancesheet or incomestatement, which also support -S. Eg: +hledger is -MAS. Percentages @@ -189,47 +209,37 @@ This flag does not work if the report contains any mixed commodity accounts. If there are mixed commodity accounts in the report be sure to use -V or -B to coerce the report into using a single commodity. -Sorting by amount +Multi-period balance report -With -S/--sort-amount, accounts with the largest (most positive) -balances are shown first. For example, hledger bal expenses -MAS shows -your biggest averaged monthly expenses first. +Multi-period balance reports are a very useful hledger feature, +activated if you provide one of the reporting interval flags, such as +-M/--monthly. They are similar to single-period balance reports, but +they show the report as a table, with columns representing one or more +successive time periods. This is the usually the preferred style of +balance report in hledger (even for a single period). -Revenues and liability balances are typically negative, however, so -S -shows these in reverse order. To work around this, you can add --invert -to flip the signs. Or, use one of the sign-flipping reports like -balancesheet or incomestatement, which also support -S. Eg: -hledger is -MAS. - -Multicolumn balance report - -Multicolumn or tabular balance reports are a very useful hledger -feature, and usually the preferred style. They share many of the above -features, but they show the report as a table, with columns representing -time periods. This mode is activated by providing a reporting interval. - -There are three types of multicolumn balance report, showing different +Multi-period balance reports come in several types, showing different information: -1. By default: each column shows the sum of postings in that period, ie - the account's change of balance in that period. This is useful eg - for a monthly income statement: +1. A balance change report: by default, each column shows the sum of + postings in that period, ie the account's change of balance in that + period. This is useful eg for a monthly income statement: - $ hledger balance --quarterly income expenses -E - Balance changes in 2008: +$ hledger balance --quarterly income expenses -E +Balance changes in 2008: - || 2008q1 2008q2 2008q3 2008q4 - ===================++================================= - expenses:food || 0 $1 0 0 - expenses:supplies || 0 $1 0 0 - income:gifts || 0 $-1 0 0 - income:salary || $-1 0 0 0 - -------------------++--------------------------------- - || $-1 $1 0 0 + || 2008q1 2008q2 2008q3 2008q4 +===================++================================= + expenses:food || 0 $1 0 0 + expenses:supplies || 0 $1 0 0 + income:gifts || 0 $-1 0 0 + income:salary || $-1 0 0 0 +-------------------++--------------------------------- + || $-1 $1 0 0 -2. With --cumulative: each column shows the ending balance for that - period, accumulating the changes across periods, starting from 0 at - the report start date: +2. A cumulative end balance report: with --cumulative, each column + shows the end balance for that period, accumulating the changes + across periods, starting from 0 at the report start date: $ hledger balance --quarterly income expenses -E --cumulative Ending balances (cumulative) in 2008: @@ -243,11 +253,12 @@ information: -------------------++------------------------------------------------- || $-1 0 0 0 -3. With --historical/-H: each column shows the actual historical ending - balance for that period, accumulating the changes across periods, - starting from the actual balance at the report start date. This is - useful eg for a multi-period balance sheet, and when you are showing - only the data after a certain start date: +3. A historical end balance report: with --historical/-H, each column + shows the actual historical end balance for that period, + accumulating the changes across periods, and including the balance + from any postings before the report start date. This is useful eg + for a multi-period balance sheet, and when you want to see balances + only after a certain date: $ hledger balance ^assets ^liabilities --quarterly --historical --begin 2008/4/1 Ending balances (historical) in 2008/04/01-2008/12/31: @@ -264,9 +275,6 @@ information: Note that --cumulative or --historical/-H disable --row-total/-T, since summing end balances generally does not make sense. -Multicolumn balance reports display accounts in flat mode by default; to -see the hierarchy, use --tree. - With a reporting interval (like --quarterly above), the report start/end dates will be adjusted if necessary so that they encompass the displayed report periods. This is so that the first and last periods will be diff --git a/hledger/Hledger/Cli/Commands/Check.txt b/hledger/Hledger/Cli/Commands/Check.txt index 1bc794d49..2436ceceb 100644 --- a/hledger/Hledger/Cli/Commands/Check.txt +++ b/hledger/Hledger/Cli/Commands/Check.txt @@ -1,16 +1,19 @@ check -Check for various kinds of errors in your data. experimental +Check for various kinds of errors in your data. _FLAGS hledger provides a number of built-in error 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. Some examples: +exit code if all is well. Specify their names (or a prefix) as +argument(s). + +Some examples: hledger check # basic checks hledger check -s # basic + strict checks -hledger check ordereddates uniqueleafnames # basic + specified checks +hledger check ordereddates payees # basic + two other checks Here are the checks currently available: @@ -32,7 +35,7 @@ commands, including check: Strict checks These additional checks are run when the -s/--strict (strict mode) flag -is used. They can also be run by specifying their names as arguments to +is used. Or, they can be run by giving their names as arguments to check: - accounts - all account names used by transactions have been declared @@ -41,8 +44,9 @@ check: Other checks -These checks can be run only by specifying their names as arguments to -check: +These checks can be run only by giving their names as arguments to +check. They are more specialised and not desirable for everyone, +therefore optional: - ordereddates - transactions are ordered by date (similar to the old check-dates command) @@ -50,12 +54,11 @@ check: - payees - all payees used by transactions have been declared - uniqueleafnames - all account leaf names are unique (similar to the - old check-dupes command) + old check-dupes command). -Add-on checks +Custom checks -These checks are not yet integrated with check, but are available as -add-on commands in +A few more checks are are available as separate add-on commands, in https://github.com/simonmichael/hledger/tree/master/bin: - hledger-check-tagfiles - all tag values containing / (a forward @@ -64,5 +67,5 @@ https://github.com/simonmichael/hledger/tree/master/bin: - hledger-check-fancyassertions - more complex balance assertions are passing -You could make your own similar scripts to perform custom checks; -Cookbook -> Scripting may be helpful. +You could make similar scripts to perform your own custom checks. See: +Cookbook -> Scripting.