From ddec2cedf331fef7efa214cfbde9e02610119c6d Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Thu, 9 Sep 2021 14:44:09 -1000 Subject: [PATCH] ;doc: update CLI usage texts --- hledger/Hledger/Cli/Commands/Balance.txt | 49 +++++++++++-------- hledger/Hledger/Cli/Commands/Close.txt | 61 +++++++++++++----------- hledger/Hledger/Cli/Commands/Help.txt | 10 ++-- 3 files changed, 70 insertions(+), 50 deletions(-) diff --git a/hledger/Hledger/Cli/Commands/Balance.txt b/hledger/Hledger/Cli/Commands/Balance.txt index 309b5736d..f3d8df65a 100644 --- a/hledger/Hledger/Cli/Commands/Balance.txt +++ b/hledger/Hledger/Cli/Commands/Balance.txt @@ -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 diff --git a/hledger/Hledger/Cli/Commands/Close.txt b/hledger/Hledger/Cli/Commands/Close.txt index bb2896a86..1026be860 100644 --- a/hledger/Hledger/Cli/Commands/Close.txt +++ b/hledger/Hledger/Cli/Commands/Close.txt @@ -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' diff --git a/hledger/Hledger/Cli/Commands/Help.txt b/hledger/Hledger/Cli/Commands/Help.txt index 3dc35b120..3b13378ae 100644 --- a/hledger/Hledger/Cli/Commands/Help.txt +++ b/hledger/Hledger/Cli/Commands/Help.txt @@ -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