;doc: update CLI usage texts
This commit is contained in:
Simon Michael
parent
c0053cb9ba
commit
ddec2cedf3
@ -31,6 +31,7 @@ balance can show..
|
||||
- or actual and planned balance changes (--budget)
|
||||
- or value of balance changes (-V)
|
||||
- or change of balance values (--valuechange)
|
||||
- or unrealised capital gain/loss (--gain)
|
||||
|
||||
..in..
|
||||
|
||||
@ -75,9 +76,9 @@ should also match their end balance at the end of the journal period
|
||||
(more on this below).
|
||||
|
||||
Accounts are sorted by declaration order if any, and then alphabetically
|
||||
by account name. For instance, using examples/sample.journal:
|
||||
by account name. For instance (using examples/sample.journal):
|
||||
|
||||
$ hledger bal
|
||||
$ hledger -f examples/sample.journal bal
|
||||
$1 assets:bank:saving
|
||||
$-2 assets:cash
|
||||
$1 expenses:food
|
||||
@ -92,7 +93,7 @@ Accounts with a zero balance (and no non-zero subaccounts, in tree mode
|
||||
- see below) are hidden by default. Use -E/--empty to show them
|
||||
(revealing assets:bank:checking here):
|
||||
|
||||
$ hledger -f examples/sample.journal bal -E
|
||||
$ hledger -f examples/sample.journal bal -E
|
||||
0 assets:bank:checking
|
||||
$1 assets:bank:saving
|
||||
$-2 assets:cash
|
||||
@ -113,7 +114,7 @@ You can show fewer accounts, a different time period, totals from
|
||||
cleared transactions only, etc. by using query arguments or options to
|
||||
limit the postings being matched. Eg:
|
||||
|
||||
$ hledger bal --cleared assets date:200806
|
||||
$ hledger -f examples/sample.journal bal --cleared assets date:200806
|
||||
$-2 assets:cash
|
||||
--------------------
|
||||
$-2
|
||||
@ -126,7 +127,7 @@ their full names visible, as in the examples above.
|
||||
With -t/--tree, the account hierarchy is shown, with subaccounts' "leaf"
|
||||
names indented below their parent:
|
||||
|
||||
$ hledger balance
|
||||
$ hledger -f examples/sample.journal balance
|
||||
$-1 assets
|
||||
$1 bank:saving
|
||||
$-2 cash
|
||||
@ -159,22 +160,29 @@ Notes:
|
||||
|
||||
Depth limiting
|
||||
|
||||
With a depth:N query, or --depth N option, or just -N, balance reports
|
||||
will show accounts only to the specified depth, hiding the deeper
|
||||
subaccounts. Account balances at the depth limit always include the
|
||||
balances from any hidden subaccounts (even in list mode). This can be
|
||||
useful for getting an overview. Eg, limiting to depth 1:
|
||||
With a depth:NUM query, or --depth NUM option, or just -NUM (eg: -3)
|
||||
balance reports will show accounts only to the specified depth, hiding
|
||||
the deeper subaccounts. This can be useful for getting an overview
|
||||
without too much detail.
|
||||
|
||||
$ hledger balance -N -1
|
||||
Account balances at the depth limit always include the balances from any
|
||||
deeper subaccounts (even in list mode). Eg, limiting to depth 1:
|
||||
|
||||
$ hledger -f examples/sample.journal balance -1
|
||||
$-1 assets
|
||||
$2 expenses
|
||||
$-2 income
|
||||
$1 liabilities
|
||||
--------------------
|
||||
0
|
||||
|
||||
You can also hide top-level account name parts, using --drop N. This can
|
||||
be useful for hiding repetitive top-level account names:
|
||||
Dropping top-level accounts
|
||||
|
||||
$ hledger bal expenses --drop 1
|
||||
You can also hide one or more top-level account name parts, using
|
||||
--drop NUM. This can be useful for hiding repetitive top-level account
|
||||
names:
|
||||
|
||||
$ hledger -f examples/sample.journal bal expenses --drop 1
|
||||
$1 food
|
||||
$1 supplies
|
||||
--------------------
|
||||
@ -187,7 +195,7 @@ With a report interval (set by the -D/--daily, -W/--weekly,
|
||||
shows a tabular report, with columns representing successive time
|
||||
periods (and a title):
|
||||
|
||||
$ hledger balance --quarterly income expenses -E
|
||||
$ hledger -f examples/sample.journal bal --quarterly income expenses -E
|
||||
Balance changes in 2008:
|
||||
|
||||
|| 2008q1 2008q2 2008q3 2008q4
|
||||
@ -306,7 +314,7 @@ Percentages
|
||||
With -%/--percent, balance reports show each account's value expressed
|
||||
as a percentage of the (column) total:
|
||||
|
||||
$ hledger bal expenses -Q -%
|
||||
$ hledger -f examples/sample.journal bal expenses -Q -%
|
||||
Balance changes in 2008:
|
||||
|
||||
|| 2008Q1 2008Q2 2008Q3 2008Q4
|
||||
@ -382,7 +390,10 @@ The basic calculation to perform for each table cell. It is one of:
|
||||
- --sum : sum the posting amounts (default)
|
||||
- --budget : like --sum but also show a goal amount
|
||||
- --valuechange : show the change in period-end historical balance
|
||||
values
|
||||
values (caused by deposits, withdrawals, and/or market price
|
||||
fluctuations)
|
||||
- --gain : show the unrealised capital gain/loss, (the current valued
|
||||
balance minus each amount's original cost)
|
||||
|
||||
Accumulation type:
|
||||
Which postings should be included in each cell's calculation. It is one
|
||||
@ -409,7 +420,7 @@ valuation commodity to use. It is one of:
|
||||
- --value=cost[,COMM] : no valuation, show amounts converted to cost
|
||||
- --value=then[,COMM] : show value at transaction dates
|
||||
- --value=end[,COMM] : show value at period end date(s) (default with
|
||||
--valuechange)
|
||||
--valuechange, --gain)
|
||||
- --value=now[,COMM] : show value at today's date
|
||||
- --value=YYYY-MM-DD[,COMM] : show value at another date
|
||||
|
||||
@ -752,7 +763,7 @@ For single-period balance reports displayed in the terminal (only), you
|
||||
can use --format FMT to customise the format and content of each line.
|
||||
Eg:
|
||||
|
||||
$ hledger balance --format "%20(account) %12(total)"
|
||||
$ hledger -f examples/sample.journal balance --format "%20(account) %12(total)"
|
||||
assets $-1
|
||||
bank:saving $1
|
||||
cash $-2
|
||||
|
||||
@ -54,14 +54,17 @@ whichever is later.
|
||||
|
||||
Unless you are running close on exactly the first day of the new period,
|
||||
you'll want to override the closing date. This is done by specifying a
|
||||
report period, where "last day of the report period" will be the closing
|
||||
date. The opening date is always the following day. So to close on
|
||||
2020-12-31 and open on 2021-01-01, any of these work
|
||||
report end date, where "last day of the report period" will be the
|
||||
closing date. The opening date is always the following day. So to close
|
||||
on (end of) 2020-12-31 and open on (start of) 2021-01-01, any of these
|
||||
will work:
|
||||
|
||||
- -p 2020
|
||||
- date:2020
|
||||
- -e 2021-01-01 (remember -e specifies an exclusive end date)
|
||||
- -e 2021
|
||||
end date argument explanation
|
||||
------------------- ------------------------------------------------
|
||||
-e 2021-01-01 end dates are exclusive
|
||||
-e 2021 equivalent, per smart dates
|
||||
-p 2020 equivalent, the period's begin date is ignored
|
||||
date:2020 equivalent query
|
||||
|
||||
Example: close asset/liability accounts for file transition
|
||||
|
||||
@ -103,17 +106,17 @@ transactions, like this:
|
||||
; 2019.journal
|
||||
2019-01-01 opening balances ; earliest opening txn, no tag here
|
||||
...
|
||||
2019-12-31 closing balances ; close:2019
|
||||
2019-12-31 closing balances ; clopen:2020
|
||||
...
|
||||
|
||||
; 2020.journal
|
||||
2020-01-01 opening balances ; open:2020
|
||||
2020-01-01 opening balances ; clopen:2020
|
||||
...
|
||||
2020-12-31 closing balances ; close:2020
|
||||
2020-12-31 closing balances ; clopen:2021
|
||||
...
|
||||
|
||||
; 2021.journal
|
||||
2021-01-01 opening balances ; open:2021
|
||||
2021-01-01 opening balances ; clopen:2021
|
||||
...
|
||||
|
||||
Now with
|
||||
@ -125,15 +128,12 @@ include 2021.journal
|
||||
|
||||
you could do eg:
|
||||
|
||||
$ hledger -f all.journal reg -H checking not:tag:'open|close'
|
||||
$ hledger -f all.journal reg -H checking not:tag:clopen
|
||||
# all years checking register, hiding non-essential opening/closing txns
|
||||
|
||||
$ hledger -f all.journal bs -p 2020 not:tag:close=2020
|
||||
$ hledger -f all.journal bs -p 2020 not:tag:clopen=2020
|
||||
# 2020 year end balances, suppressing 2020 closing txn
|
||||
|
||||
$ hledger -f 2020.journal bs not:tag:close
|
||||
# 2020 year end balances, easier case
|
||||
|
||||
close and balance assertions
|
||||
|
||||
The closing and opening transactions will include balance assertions,
|
||||
@ -171,22 +171,27 @@ single-day transactions):
|
||||
|
||||
Example: close revenue/expense accounts to retained earnings
|
||||
|
||||
Here, the opening transaction is supressed with --close, as it's
|
||||
probably not needed. Also you'll want to use a different equity account
|
||||
name:
|
||||
For this, use --close to suppress the opening transaction, as it's not
|
||||
needed. Also you'll want to change the equity account name to your
|
||||
equivalent of "equity:retained earnings".
|
||||
|
||||
$ hledger close -f 2021.journal -p 2021Q1 --close --close-acct='equity:retained earnings' revenues expenses >> 2021.journal
|
||||
# close 2021 first quarter revenues/expenses
|
||||
Closing 2021's first quarter revenues/expenses:
|
||||
|
||||
Or, operating on the default journal:
|
||||
$ hledger close -f 2021.journal --close revenues expenses -p 2021Q1 \
|
||||
--close-acct='equity:retained earnings' >> 2021.journal
|
||||
|
||||
$ hledger close -p Q1 --close --close-acct='equity:retained earnings' revenues expenses >> $LEDGER_FILE
|
||||
# close current year's first quarter revenues/expenses
|
||||
The same, using the default journal and current year:
|
||||
|
||||
Now, eg:
|
||||
$ hledger close --close revenues expenses -p Q1 \
|
||||
--close-acct='equity:retained earnings' >> $LEDGER_FILE
|
||||
|
||||
Now, the first quarter's balance sheet should show a zero (unless you
|
||||
are using @/@@ notation without equity postings):
|
||||
|
||||
$ hledger bse -p Q1
|
||||
# Q1 full balance sheet, total should be zero
|
||||
|
||||
$ hledger is -p Q1 not:'retained earnings'
|
||||
# Q1 income statement, must suppress the closing txn
|
||||
And we must suppress the closing transaction to see the first quarter's
|
||||
income statement (using the description; not:'retained earnings' won't
|
||||
work here):
|
||||
|
||||
$ hledger is -p Q1 not:desc:'closing balances'
|
||||
|
||||
@ -1,8 +1,12 @@
|
||||
help
|
||||
Show the hledger user manual in one of several formats, optionally
|
||||
positioned at a given TOPIC (if possible). TOPIC is any heading, or
|
||||
heading prefix, in the manual. Some examples: commands, print, 'auto
|
||||
postings', periodic.
|
||||
positioned at a given TOPIC (if possible).
|
||||
|
||||
TOPIC is any heading in the manual, or the start of any heading (but not
|
||||
the middle). It is case insensitive.
|
||||
|
||||
Some examples: commands, print, forecast, "auto postings",
|
||||
"commodity column".
|
||||
|
||||
_FLAGS
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user