slaesvuo/hledger
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

;update CLI usage texts

Browse Source
This commit is contained in:
Simon Michael 2021-01-10 15:35:48 -08:00
parent 0d418fc86e
commit de5dfe2d1b
2 changed files with 114 additions and 103 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

178
hledger/Hledger/Cli/Commands/Balance.txt
View File

@ -29,10 +29,31 @@ html, and json.
The balance command can produce several styles of report: 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 This is the default for hledger's balance command: a flat list of all
looks like this: (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 $ hledger balance
$-1 assets $-1 assets
@ -48,33 +69,26 @@ $ hledger balance
-------------------- --------------------
0 0
By default, accounts are displayed hierarchically, with subaccounts For more compact output, "boring" accounts containing a single
indented below their parent, with accounts at each level of the tree interesting subaccount and no balance of their own (assets:bank and
sorted by declaration order if declared, then by account name. 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 Account balances in tree mode are "inclusive" - they include the
balance of their own, are elided into the following line for more balances of any subaccounts. Eg, the assets $-1 balance here includes
compact output. (Eg above, the "liabilities" account.) Use --no-elide to the $1 from assets:bank:saving and the $-2 from assets:cash. (And it
prevent this. 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 Each group of sibling accounts is sorted separately, by declaration
subaccounts. order and then by account name.
Accounts which have zero balance (and no non-zero subaccounts) are Customising single-period balance reports
omitted. Use -E/--empty to show them.
A final total is displayed by default; use -N/--no-total to suppress it, You can customise the layout of single-period balance reports with
eg: --format FMT, which sets the format of each line. 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:
$ hledger balance --format "%20(account) %12(total)" $ hledger balance --format "%20(account) %12(total)"
assets $-1 assets $-1
@ -129,28 +143,12 @@ Some example formats:
- %20(total) %2(depth_spacer)%-(account) - the default format for the - %20(total) %2(depth_spacer)%-(account) - the default format for the
single-column balance report single-column balance report
Colour support Depth limiting
In terminal output, when colour is enabled, the balance command shows With a depth:N query, or --depth N option, or just -N, balance reports
negative amounts in red. 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
Flat mode shows the top-level accounts:
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.
$ hledger balance -N -1 $ hledger balance -N -1
$-1 assets $-1 assets
@ -158,8 +156,30 @@ $ hledger balance -N -1
$-2 income $-2 income
$1 liabilities $1 liabilities
Flat-mode balance reports, which normally show exclusive balances, show Accounts at the depth limit will include the balances of any hidden
inclusive balances at the depth limit. 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 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 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. 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) Multi-period balance reports are a very useful hledger feature,
balances are shown first. For example, hledger bal expenses -MAS shows activated if you provide one of the reporting interval flags, such as
your biggest averaged monthly expenses first. -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 Multi-period balance reports come in several types, showing different
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
information: information:
1. By default: each column shows the sum of postings in that period, ie 1. A balance change report: by default, each column shows the sum of
the account's change of balance in that period. This is useful eg postings in that period, ie the account's change of balance in that
for a monthly income statement: period. This is useful eg for a monthly income statement:
$ hledger balance --quarterly income expenses -E $ hledger balance --quarterly income expenses -E
Balance changes in 2008: Balance changes in 2008:
|| 2008q1 2008q2 2008q3 2008q4 || 2008q1 2008q2 2008q3 2008q4
===================++================================= ===================++=================================
expenses:food || 0 $1 0 0 expenses:food || 0 $1 0 0
expenses:supplies || 0 $1 0 0 expenses:supplies || 0 $1 0 0
income:gifts || 0 $-1 0 0 income:gifts || 0 $-1 0 0
income:salary || $-1 0 0 0 income:salary || $-1 0 0 0
-------------------++--------------------------------- -------------------++---------------------------------
|| $-1 $1 0 0 || $-1 $1 0 0
2. With --cumulative: each column shows the ending balance for that 2. A cumulative end balance report: with --cumulative, each column
period, accumulating the changes across periods, starting from 0 at shows the end balance for that period, accumulating the changes
the report start date: across periods, starting from 0 at the report start date:
$ hledger balance --quarterly income expenses -E --cumulative $ hledger balance --quarterly income expenses -E --cumulative
Ending balances (cumulative) in 2008: Ending balances (cumulative) in 2008:
@ -243,11 +253,12 @@ information:
-------------------++------------------------------------------------- -------------------++-------------------------------------------------
|| $-1 0 0 0 || $-1 0 0 0
3. With --historical/-H: each column shows the actual historical ending 3. A historical end balance report: with --historical/-H, each column
balance for that period, accumulating the changes across periods, shows the actual historical end balance for that period,
starting from the actual balance at the report start date. This is accumulating the changes across periods, and including the balance
useful eg for a multi-period balance sheet, and when you are showing from any postings before the report start date. This is useful eg
only the data after a certain start date: 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 $ hledger balance ^assets ^liabilities --quarterly --historical --begin 2008/4/1
Ending balances (historical) in 2008/04/01-2008/12/31: 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 Note that --cumulative or --historical/-H disable --row-total/-T, since
summing end balances generally does not make sense. 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 With a reporting interval (like --quarterly above), the report start/end
dates will be adjusted if necessary so that they encompass the displayed 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 report periods. This is so that the first and last periods will be

27
hledger/Hledger/Cli/Commands/Check.txt
View File

@ -1,16 +1,19 @@
check check
Check for various kinds of errors in your data. experimental Check for various kinds of errors in your data.
_FLAGS _FLAGS
hledger provides a number of built-in error checks to help prevent 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 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 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 # basic checks
hledger check -s # basic + strict 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: Here are the checks currently available:
@ -32,7 +35,7 @@ commands, including check:
Strict checks Strict checks
These additional checks are run when the -s/--strict (strict mode) flag 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: check:
- accounts - all account names used by transactions have been declared - accounts - all account names used by transactions have been declared
@ -41,8 +44,9 @@ check:
Other checks Other checks
These checks can be run only by specifying their names as arguments to These checks can be run only by giving their names as arguments to
check: check. They are more specialised and not desirable for everyone,
therefore optional:
- ordereddates - transactions are ordered by date (similar to the old - ordereddates - transactions are ordered by date (similar to the old
check-dates command) check-dates command)
@ -50,12 +54,11 @@ check:
- payees - all payees used by transactions have been declared - payees - all payees used by transactions have been declared
- uniqueleafnames - all account leaf names are unique (similar to the - 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 A few more checks are are available as separate add-on commands, in
add-on commands in
https://github.com/simonmichael/hledger/tree/master/bin: https://github.com/simonmichael/hledger/tree/master/bin:
- hledger-check-tagfiles - all tag values containing / (a forward - 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 - hledger-check-fancyassertions - more complex balance assertions are
passing passing
You could make your own similar scripts to perform custom checks; You could make similar scripts to perform your own custom checks. See:
Cookbook -> Scripting may be helpful. Cookbook -> Scripting.