From 13baabb88030aef75d412dde14fe77900d301240 Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Fri, 26 Jan 2024 22:49:21 -1000 Subject: [PATCH] ;doc: update command help --- hledger/Hledger/Cli/Commands/Aregister.txt | 3 +- hledger/Hledger/Cli/Commands/Balance.txt | 6 +- hledger/Hledger/Cli/Commands/Balancesheet.txt | 3 +- hledger/Hledger/Cli/Commands/Cashflow.txt | 3 +- hledger/Hledger/Cli/Commands/Close.txt | 281 +++++++++--------- .../Hledger/Cli/Commands/Incomestatement.txt | 3 +- hledger/Hledger/Cli/Commands/Print.txt | 9 +- hledger/Hledger/Cli/Commands/Register.txt | 3 +- 8 files changed, 155 insertions(+), 156 deletions(-) diff --git a/hledger/Hledger/Cli/Commands/Aregister.txt b/hledger/Hledger/Cli/Commands/Aregister.txt index c172e72f9..8ee68b384 100644 --- a/hledger/Hledger/Cli/Commands/Aregister.txt +++ b/hledger/Hledger/Cli/Commands/Aregister.txt @@ -61,7 +61,8 @@ ensure perfect alignment, at the cost of more time and memory, use the --align-all flag. This command also supports the output destination and output format -options. The output formats supported are txt, csv, tsv, and json. +options. The output formats supported are txt, csv, tsv (Added in 1.32), +and json. aregister and posting dates diff --git a/hledger/Hledger/Cli/Commands/Balance.txt b/hledger/Hledger/Cli/Commands/Balance.txt index 28b8a548b..1e01a6f12 100644 --- a/hledger/Hledger/Cli/Commands/Balance.txt +++ b/hledger/Hledger/Cli/Commands/Balance.txt @@ -66,9 +66,9 @@ balance can show.. - commodities displayed on the same line or multiple lines (--layout) This command supports the output destination and output format options, -with output formats txt, csv, tsv, json, and (multi-period reports -only:) html. In txt output in a colour-supporting terminal, negative -amounts are shown in red. +with output formats txt, csv, tsv (Added in 1.32), json, and +(multi-period reports only:) html. In txt output in a colour-supporting +terminal, negative amounts are shown in red. The --related/-r flag shows the balance of the other postings in the transactions of the postings which would normally be shown. diff --git a/hledger/Hledger/Cli/Commands/Balancesheet.txt b/hledger/Hledger/Cli/Commands/Balancesheet.txt index 051687f05..3cc36e8cd 100644 --- a/hledger/Hledger/Cli/Commands/Balancesheet.txt +++ b/hledger/Hledger/Cli/Commands/Balancesheet.txt @@ -41,4 +41,5 @@ It is similar to hledger balance -H assets liabilities, but with smarter account detection, and liabilities displayed with their sign flipped. This command also supports the output destination and output format -options The output formats supported are txt, csv, tsv, html, and json. +options The output formats supported are txt, csv, tsv (Added in 1.32), +html, and json. diff --git a/hledger/Hledger/Cli/Commands/Cashflow.txt b/hledger/Hledger/Cli/Commands/Cashflow.txt index 08d3b3ae3..d59f0a2b3 100644 --- a/hledger/Hledger/Cli/Commands/Cashflow.txt +++ b/hledger/Hledger/Cli/Commands/Cashflow.txt @@ -47,4 +47,5 @@ hledger balance assets not:fixed not:investment not:receivable, but with smarter account detection. This command also supports the output destination and output format -options The output formats supported are txt, csv, tsv, html, and json. +options The output formats supported are txt, csv, tsv (Added in 1.32), +html, and json. diff --git a/hledger/Hledger/Cli/Commands/Close.txt b/hledger/Hledger/Cli/Commands/Close.txt index 4207242c1..36378939c 100644 --- a/hledger/Hledger/Cli/Commands/Close.txt +++ b/hledger/Hledger/Cli/Commands/Close.txt @@ -2,125 +2,150 @@ close (equity) -A transaction-generating command which generates several kinds of -"closing" and/or "opening" transactions useful in certain situations. It -prints one or two transactions to stdout, but does not write them to the -journal file; you can append or copy them there when you are happy with -the output. +close generates several kinds of "closing" and/or "opening" +transactions, useful in certain situations, including migrating balances +to a new journal file, retaining earnings into equity, consolidating +balances, or viewing lots. Like print, it prints valid journal entries. +You can append or copy these to your journal file(s) when you are happy +with how they look. _FLAGS -This command is most often used when migrating balances to a new journal -file, at the start of a new financial year. It can also be used to -"retain earnings" (transfer revenues and expenses to equity), or as a -sort of generic mover of balances from any group of accounts to some -other account. So it currently has six modes, selected by a mode flag. -Use only one of these flags at a time: +close currently has six modes, selected by a single mode flag: -1. With --close (or no mode flag) it prints a "closing balances" - transaction that zeroes out all the asset, liability, and equity - account balances, by default (this requires inferred or declared - account types). Or, it will zero out the accounts matched by any - ACCTQUERY arguments you provide. All of the balances are transferred - to a special "opening/closing balances" equity account. +close --migrate -2. With --open, it prints an opposite "opening balances" transaction - that restores the same account balances, starting from zero. This - mode is similar to Ledger's equity command. +This is the most common mode. It prints a "closing balances" transaction +that zeroes out all asset and liability balances (by default), and an +opposite "opening balances" transaction that restores them again. The +balancing account will be equity:opening/closing balances (or another +specified by --close-acct or --open-acct). -3. With --migrate, it prints both the closing and opening transactions - above. This is a common way to migrate balances to a new file at - year end; run hledger close --migrate -e NEWYEAR (-e influences the - transaction date) and add the closing transaction at the end of the - old file, and the opening transaction at the start of the new file. - Doing this means you can include past year files in your reports at - any time without disturbing asset/liability/equity balances, because - the closing balances transaction cancels out the following opening - balances transaction. You will sometimes need to exclude these - transactions from reports, eg to see an end of year balance sheet; a - not:opening/closing query argument should do. You should probably - also use this query when close-ing, to exclude the "opening/closing - balances" account which might otherwise cause problems. Or you can - just migrate assets and liabilities: hledger close type:AL. Most - people don't need to migrate equity. And revenues and expenses - usually should not be migrated. +This is useful when migrating balances to a new journal file at the +start of a new year. Essentially, you run +hledger close --migrate=NEWYEAR -e NEWYEAR and then copy the closing +transaction to the end of the old file and the opening transaction to +the start of the new file. The opening transaction sets correct starting +balances in the new file when it is used alone, and the closing +transaction keeps balances correct when you use both old and new files +together, by cancelling out the following opening transaction and +preventing buildup of duplicated opening balances. Think of the +closing/opening pair as "moving the balances into the next file". -4. With --assert it prints a "closing balances" transaction that just - asserts the current balances, without changing them. This can be - useful as documention and to guard against errors and changes. +You can close a different set of accounts by providing a query. Eg if +you want to include equity, you can add assets liabilities equity or +type:ALE arguments. (The balancing account is always excluded.) Revenues +and expenses usually are not migrated to a new file directly; see +--retain below. -5. With --assign it prints an "opening balances" transaction that - restores the account balances using balance assignments. Balance - assignments work regardless of any previous balance, so a preceding - closing balances transaction is not needed. This is an alternative - to --close and --open: at year end, - hledger close --assert -e NEWYEAR in the old file (optional, but - useful for error checking), and hledger close --assign -e NEWYEAR in - the new file. This might be more convenient, eg if you are often - doing cleanups or fixes which would break closing/opening - transactions. +The generated transactions will have a start: tag, with its value set to +--migrate's NEW argument if any, for easier matching or exclusion. When +NEW is not specified, it will be inferred if possible by incrementing a +number (eg a year number) within the default journal's main file name. +The other modes behave similarly. -6. With --retain, it prints a "retain earnings" transaction that - transfers revenue and expense balances to equity:retained earnings. - This is a traditional end-of-period bookkeeping operation also - called "closing the books"; in personal accounting you probably will - not need this but it could be useful if you want to see the - accounting equation (A=L+E) balanced. +close --close + +This prints just the closing balances transaction of --migrate. It is +the default behaviour if you specify no mode flag. Using the +customisation options below, you can move balances from any set of +accounts to a different account. + +close --open + +This prints just the opening balances transaction of --migrate. It is +similar to Ledger's equity command. + +close --assert + +This prints a "closing balances" transaction (with balances: tag), that +just declares balance assertions for the current balances without +changing them. It could be useful as documention and to guard against +changes. + +close --assign + +This prints an "opening balances" transaction that restores the account +balances using balance assignments. Balance assignments work regardless +of any previous balance, so a preceding closing balances transaction is +not needed. + +However, omitting the closing balances transaction would unbalance +equity. This is relatively harmless for personal reports, but it +disturbs the accounting equation, removing a source of error detection. +So --migrate is generally the best way to set to set balances in new +files, for now. + +close --retain + +This is like --close with different defaults: it prints a "retain +earnings" transaction (with retain: tag), that transfers revenue and +expense balances to equity:retained earnings. + +This is a different kind of closing, called "retaining earnings" or +"closing the books"; it is traditionally performed by businesses at the +end of each accounting period, to consolidate revenues and expenses into +the main equity balance. ("Revenues" and "expenses" are actually equity +by another name, kept separate temporarily for reporting purposes.) + +In personal accounting you generally don't need to do this, unless you +want the balancesheetequity report to show a zero total, demonstrating +that the accounting equation (A-L=E) is satisfied. + +close customisation In all modes, the following things can be overridden: -- the transaction descriptions can be changed with --close-desc=DESC - and --open-desc=DESC -- the account to transfer to and from can be changed with - --close-acct=ACCT and --open-acct=ACCT -- the accounts to be closed/opened can be changed with ACCTQUERY - (account query arguments). -- the closing/opening dates can be changed with -e DATE (a report end - date) +- the accounts to be closed/opened, with account query arguments +- the balancing account, with --close-acct=ACCT and/or + --open-acct=ACCT +- the transaction descriptions, with --close-desc=DESC and + --open-desc=DESC +- the transaction's tag value, with a --MODE=NEW option argument +- the closing/opening dates, with -e OPENDATE -By default just one destination/source posting will be used, with its -amount left implicit. With --x/--explicit, the amount will be shown -explicitly, and if it involves multiple commodities, a separate posting -will be generated for each of them (similar to print -x). +By default, the closing date is yesterday, or the journal's end date, +whichever is later; and the opening date is always one day after the +closing date. You can change these by specifying a report end date; the +closing date will be the last day of the report period. Eg -e 2024 means +"close on 2023-12-31, open on 2024-01-01". -With --show-costs, any amount costs are shown, with separate postings -for each cost. This is currently the best way to view investment lots. -If you have many currency conversion or investment transactions, it can -generate very large journal entries. +With --x/--explicit, the balancing amount will be shown explicitly, and +if it involves multiple commodities, a separate posting will be +generated for each of them (similar to print -x). With --interleaved, each individual transfer is shown with source and -destination postings next to each other. This could be useful for -troubleshooting. +destination postings next to each other (perhaps useful for +troubleshooting). -The default closing date is yesterday, or the journal's end date, -whichever is later. You can change this by specifying a report end date -with -e. The last day of the report period will be the closing date, eg --e 2024 means "close on 2023-12-31". The opening date is always the day -after the closing date. +With --show-costs, balances' costs are also shown, with different costs +kept separate. This may generate very large journal entries, if you have +many currency conversions or investment transactions. close --show-costs +is currently the best way to view investment lots with hledger. (To move +or dispose of lots, see the more capable hledger-move script.) close and balance assertions -Balance assertions will be generated, verifying that the accounts have -been reset to zero (and then restored to their previous balances, if -there is an opening transaction). +close adds balance assertions verifying that the accounts have been +reset to zero in a closing transaction or restored to their previous +balances in an opening transaction. These provide useful error checking, +but you can ignore them temporarily with -I, or remove them if you +prefer. -These provide useful error checking, but you can ignore them temporarily -with -I, or remove them if you prefer. +When running close you should probably avoid using -C, -R, status: +(filtering by status or realness) or --auto (generating postings), since +the generated balance assertions would then require these. -You probably should avoid filtering transactions by status or realness -(-C, -R, status:), or generating postings (--auto), with this command, -since the balance assertions would depend on these. - -Note custom posting dates spanning the file boundary will disrupt the -balance assertions: +Transactions with multiple dates (eg posting dates) spanning the file +boundary also can disrupt the balance assertions: 2023-12-30 a purchase made in december, cleared in january expenses:food 5 assets:bank:checking -5 ; date: 2023-01-02 -To solve that you can transfer the money to and from a temporary -account, in effect splitting the multi-day transaction into two -single-day transactions: +To solve this you can transfer the money to and from a temporary +account, splitting the multi-day transaction into two single-day +transactions: ; in 2022.journal: 2022-12-30 a purchase made in december, cleared in january @@ -132,76 +157,44 @@ single-day transactions: equity:pending 5 = 0 assets:bank:checking -5 -Example: retain earnings +close examples + +Retain earnings Record 2022's revenues/expenses as retained earnings on 2022-12-31, appending the generated transaction to the journal: $ hledger close --retain -f 2022.journal -p 2022 >> 2022.journal -Note 2022's income statement will now show only zeroes, because revenues -and expenses have been moved entirely to equity. To see them again, you -could exclude the retain transaction: +After this, to see 2022's revenues and expenses you must exclude the +retain earnings transaction: $ hledger -f 2022.journal is not:desc:'retain earnings' -Example: migrate balances to a new file +Migrate balances to a new file -Close assets/liabilities/equity on 2022-12-31 and re-open them on -2023-01-01: +Close assets/liabilities on 2022-12-31 and re-open them on 2023-01-01: $ hledger close --migrate -f 2022.journal -p 2022 # copy/paste the closing transaction to the end of 2022.journal # copy/paste the opening transaction to the start of 2023.journal -Now 2022's balance sheet will show only zeroes, indicating a balanced -accounting equation. (Unless you are using @/@@ notation - in that case, -try adding --infer-equity.) To see the end-of-year balances again, you -could exclude the closing transaction: +After this, to see 2022's end-of-year balances you must exclude the +closing balances transaction: $ hledger -f 2022.journal bs not:desc:'closing balances' -Example: excluding closing/opening transactions +For more flexibility, it helps to tag closing and opening transactions +with eg start:NEWYEAR, then you can ensure correct balances by excluding +all opening/closing transactions except the first, like so: -When combining many files for multi-year reports, the closing/opening -transactions cause some noise in transaction-oriented reports like print -and register. You can exclude them as shown above, but not:desc:... is -not ideal as it depends on consistent descriptions; also you will want -to avoid excluding the very first opening transaction, which could be -awkward. Here is one alternative, using tags: +$ hledger bs -Y -f 2021.j -f 2022.j -f 2023.j expr:'tag:start=2021 or not tag:start' +$ hledger bs -Y -f 2021.j -f 2022.j expr:'tag:start=2021 or not tag:start' +$ hledger bs -Y -f 2022.j -f 2023.j expr:'tag:start=2022 or not tag:start' +$ hledger bs -Y -f 2021.j expr:'tag:start=2021 or not tag:start' +$ hledger bs -Y -f 2022.j expr:'tag:start=2022 or not tag:start' +$ hledger bs -Y -f 2023.j # unclosed file, no query needed -Add clopen: tags to all opening/closing balances transactions except the -first, like this: +More detailed close examples -; 2021.journal -2021-06-01 first opening balances -... -2021-12-31 closing balances ; clopen:2022 -... - -; 2022.journal -2022-01-01 opening balances ; clopen:2022 -... -2022-12-31 closing balances ; clopen:2023 -... - -; 2023.journal -2023-01-01 opening balances ; clopen:2023 -... - -Now, assuming a combined journal like: - -; all.journal -include 2021.journal -include 2022.journal -include 2023.journal - -The clopen: tag can exclude all but the first opening transaction. To -show a clean multi-year checking register: - -$ hledger -f all.journal areg checking not:tag:clopen - -And the year values allow more precision. To show 2022's year-end -balance sheet: - -$ hledger -f all.journal bs -e2023 not:tag:clopen=2023 +See examples/multi-year. diff --git a/hledger/Hledger/Cli/Commands/Incomestatement.txt b/hledger/Hledger/Cli/Commands/Incomestatement.txt index 32534573d..bfcdd1d26 100644 --- a/hledger/Hledger/Cli/Commands/Incomestatement.txt +++ b/hledger/Hledger/Cli/Commands/Incomestatement.txt @@ -43,4 +43,5 @@ smarter account detection, and revenues/income displayed with their sign flipped. This command also supports the output destination and output format -options The output formats supported are txt, csv, tsv, html, and json. +options The output formats supported are txt, csv, tsv (Added in 1.32), +html, and json. diff --git a/hledger/Hledger/Cli/Commands/Print.txt b/hledger/Hledger/Cli/Commands/Print.txt index 03ba9ea88..d0e94d7c6 100644 --- a/hledger/Hledger/Cli/Commands/Print.txt +++ b/hledger/Hledger/Cli/Commands/Print.txt @@ -55,8 +55,9 @@ their symbol placement, decimal mark, and digit group marks will be made consistent. By default, decimal digits are shown as they are written in the journal. -With the --round option, print will try increasingly hard to display -decimal digits according to the commodity display styles: +With the --round (Added in 1.32) option, print will try increasingly +hard to display decimal digits according to the commodity display +styles: - --round=none show amounts with original precisions (default) - --round=soft add/remove decimal zeros in amounts (except costs) @@ -105,8 +106,8 @@ shown and the program exit code will be non-zero. print output format This command also supports the output destination and output format -options The output formats supported are txt, beancount, csv, tsv, json -and sql. +options The output formats supported are txt, beancount (Added in 1.32), +csv, tsv (Added in 1.32), json and sql. The beancount format tries to produce Beancount-compatible output, as follows: diff --git a/hledger/Hledger/Cli/Commands/Register.txt b/hledger/Hledger/Cli/Commands/Register.txt index c42a9deb9..0137e1825 100644 --- a/hledger/Hledger/Cli/Commands/Register.txt +++ b/hledger/Hledger/Cli/Commands/Register.txt @@ -125,4 +125,5 @@ $ hledger reg -w 100,40 # set overall width 100, description width 40 $ hledger reg -w $COLUMNS,40 # use terminal width, & description width 40 This command also supports the output destination and output format -options The output formats supported are txt, csv, tsv, and json. +options The output formats supported are txt, csv, tsv (Added in 1.32), +and json.