From bde97b8f28eebf5547cf3b1203ff545f98223140 Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Thu, 9 Jan 2025 21:05:10 -1000 Subject: [PATCH] ;doc: update command docs --- hledger/Hledger/Cli/Commands/Close.md | 18 ++- hledger/Hledger/Cli/Commands/Close.txt | 172 +++++++++++++------------ 2 files changed, 99 insertions(+), 91 deletions(-) diff --git a/hledger/Hledger/Cli/Commands/Close.md b/hledger/Hledger/Cli/Commands/Close.md index 8e9a51a11..f1ba8ade1 100644 --- a/hledger/Hledger/Cli/Commands/Close.md +++ b/hledger/Hledger/Cli/Commands/Close.md @@ -9,16 +9,14 @@ You can copy these into your journal file(s) when you are happy with how they lo ```flags Flags: - --close[=NEW] (default) show a closing transaction - --open[=NEW] show an opening transaction - --clopen[=NEW] show closing and opening transactions, for Asset - and Liability accounts by default, tagged for easy - matching. The tag's default value can be overridden - by providing NEW. - --assign[=NEW] show opening balance assignments - --assert[=NEW] show closing balance assertions - --retain[=NEW] show a retain earnings transaction, for Revenue - and Expense accounts by default + --clopen[=TAGVAL] show closing and opening balances transactions, + for AL accounts by default + --close[=TAGVAL] show just a closing balances transaction + --open[=TAGVAL] show just an opening balances transaction + --assert[=TAGVAL] show a balance assertions transaction + --assign[=TAGVAL] show a balance assignments transaction + --retain[=TAGVAL] show a retain earnings transaction, for RX + accounts by default -x --explicit show all amounts explicitly --show-costs show amounts with different costs separately --interleaved show source and destination postings together diff --git a/hledger/Hledger/Cli/Commands/Close.txt b/hledger/Hledger/Cli/Commands/Close.txt index 390389eaf..2f009d4d6 100644 --- a/hledger/Hledger/Cli/Commands/Close.txt +++ b/hledger/Hledger/Cli/Commands/Close.txt @@ -2,24 +2,21 @@ close (equity) -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. +close prints several kinds of "closing" and/or "opening" transactions, +useful in various situations: migrating balances to a new journal file, +retaining earnings into equity, consolidating balances, viewing lot +costs.. Like print, it prints valid journal entries. You can copy these +into your journal file(s) when you are happy with how they look. Flags: - --migrate[=NEW] show closing and opening transactions, for Asset - and Liability accounts by default, tagged for easy - matching. The tag's default value can be overridden - by providing NEW. - --close[=NEW] (default) show a closing transaction - --open[=NEW] show an opening transaction - --assign[=NEW] show opening balance assignments - --assert[=NEW] show closing balance assertions - --retain[=NEW] show a retain earnings transaction, for Revenue - and Expense accounts by default + --clopen[=TAGVAL] show closing and opening balances transactions, + for AL accounts by default + --close[=TAGVAL] show just a closing balances transaction + --open[=TAGVAL] show just an opening balances transaction + --assert[=TAGVAL] show a balance assertions transaction + --assign[=TAGVAL] show a balance assignments transaction + --retain[=TAGVAL] show a retain earnings transaction, for RX + accounts by default -x --explicit show all amounts explicitly --show-costs show amounts with different costs separately --interleaved show source and destination postings together @@ -39,86 +36,99 @@ Flags: all - also round cost amounts to precision (can unbalance transactions) -close currently has six modes, selected by a single mode flag: +close has six modes, selected by choosing one of the mode flags (--close +is the default). They all do much the same operation, but with different +defaults, useful in different situations. -close --migrate +close --clopen -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). +This is useful if migrating balances to a new journal file at the start +of a new year. It prints a "closing balances" transaction that zeroes +out account balances (Asset and Liability accounts, by default), and an +opposite "opening balances" transaction that restores them again. +Typically, you would run -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". +hledger close --clopen -e NEWYEAR >> $LEDGER_FILE -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. +and then move the opening transaction from the old file to the new file +(and probably also update your LEDGER_FILE environment variable). -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. +Why might you do this ? If your reports are fast, you may not need it. +But at some point you will probably want to partition your data by time, +for performance or data integrity or regulatory reasons. A new file or +set of files per year is common. Then, having each file/fileset +"bookended" with opening and closing balance transactions will allow you +to freely pick and choose which files to read - just the current year, +any past year, any sequence of years, or all of them - while showing +correct account balances in each case. The earliest opening balances +transaction sets correct starting balances, and any later +closing/opening pairs will harmlessly cancel each other out. + +The balances will be transferred to and from an equity account: +equity:opening/closing balances by default, You can override this by +declaring an account with type V/Conversion, or by using --close-acct +and/or --open-acct. + +You can select a different set of accounts to close/open by providing an +account query. Eg to add Equity accounts, provide arguments like +assets liabilities equity or type:ALE. When migrating to a new file, +you'll usually want to bring along the AL or ALE accounts, but not the +RX accounts (Revenue, Expense). + +The generated transactions will have a clopen: tag. If the main +journal's file name contains a number (eg a year number), the tag's +value will be that file name with the number incremented. Or you can +choose the tag value yourself, by using --clopen=TAGVAL. 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. +This prints just the closing balances transaction of --clopen. It is the +default if you don't specify a mode. + +More customisation options are described below. Among other things, you +can use close --close to generate a transaction moving the balances from +any set of accounts, to a different account. (If you need to move just a +portion of the balance, see hledger-move.) close --open -This prints just the opening balances transaction of --migrate. It is -similar to Ledger's equity command. +This prints just the opening balances transaction of --clopen. (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. +This prints a transaction that asserts the account balances as they are +on the end date (and adds an assert: tag). 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. +This prints a transaction that assigns the account balances as they are +on the end date (and adds an "assign:" tag). Unlike balance assertions, +assignments will post changes to balances as needed to reach the +specified amounts. -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. +This is another way to set starting balances when migrating to a new +file, and it will set them correctly even in the presence of earlier +files which do not have a closing balances transaction. However, it can +hide errors, and disturb the accounting equation, so --clopen is usually +recommended. 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 like --close, but with different defaults: it prints a +transaction that transfers Revenue and Expense balances to +equity:retained earnings (and adds a retain: tag). -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.) +This is called "retaining earnings", or "closing the books". Revenues +and expenses correspond to changes in equity. They are initially kept +separate for reporting purposes, but traditionally at the end of each +accounting period, businesses consolidate them into equity, -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. +In personal accounting, there's not much reason to do this, and most +people don't. One reason to do it is to help the balancesheetequity +report show a zero total, demonstrating that the accounting equation +(A-L=E) is satisfied. close customisation @@ -207,7 +217,7 @@ Migrate balances to a new file Close assets/liabilities on 2022-12-31 and re-open them on 2023-01-01: -$ hledger close --migrate -f 2022.journal -p 2022 +$ hledger close --clopen -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 @@ -217,14 +227,14 @@ closing balances transaction: $ hledger -f 2022.journal bs not:desc:'closing balances' 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: +with eg clopen:NEWYEAR, then you can ensure correct balances by +excluding all opening/closing transactions except the first, like so: -$ 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 2021.j -f 2022.j -f 2023.j expr:'tag:clopen=2021 or not tag:clopen' +$ hledger bs -Y -f 2021.j -f 2022.j expr:'tag:clopen=2021 or not tag:clopen' +$ hledger bs -Y -f 2022.j -f 2023.j expr:'tag:clopen=2022 or not tag:clopen' +$ hledger bs -Y -f 2021.j expr:'tag:clopen=2021 or not tag:clopen' +$ hledger bs -Y -f 2022.j expr:'tag:clopen=2022 or not tag:clopen' $ hledger bs -Y -f 2023.j # unclosed file, no query needed More detailed close examples