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

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

@ -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

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

@ -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.