diff --git a/hledger/Hledger/Cli/Commands/Close.txt b/hledger/Hledger/Cli/Commands/Close.txt index 7a6a85005..b00af1749 100644 --- a/hledger/Hledger/Cli/Commands/Close.txt +++ b/hledger/Hledger/Cli/Commands/Close.txt @@ -1,46 +1,68 @@ close -close [--retain | --migrate | --open] [QUERY] +(equity) -By default: prints a transaction that zeroes out ("closes") all -accounts, transferring their balances to an equity account. Query -arguments can be added to override the accounts selection. Three other -modes are supported: +Generate transactions which transfer account balances to and/or from +another account (typically equity). This can be useful for migrating +balances to a new journal file, or for merging earnings into equity at +end of accounting period. ---retain: prints a transaction closing revenue and expense balances. -This is traditionally done by businesses at the end of each accounting -period; it is less necessary in personal and computer-based accounting, -but it can help balance the accounting equation A=L+E. +By default, it prints a transaction that zeroes out ALE accounts (asset, +liability, equity accounts; this requires account types to be +configured); or if ACCTQUERY is provided, the accounts matched by that. ---migrate: prints a transaction to close asset, liability and most -equity balances, and another transaction to re-open them. This can be -useful when starting a new file (for performance or data protection). -Adding the closing transaction to the old file allows old and new files -to be combined. - ---open: as above, but prints just the opening transaction. This can be -useful for starting a new file, leaving the old file unchanged. Similar -to Ledger's equity command. +(experimental) _FLAGS -You can change the equity account name with --close-acct ACCT. It -defaults to equity:retained earnings with --retain, or -equity:opening/closing balances otherwise. +This command has four main modes, corresponding to the most common use +cases: -You can change the transaction description(s) with --close-desc 'DESC' -and --open-desc 'DESC'. It defaults to retain earnings with --retain, or -closing balances and opening balances otherwise. +1. With --close (default), it prints a "closing balances" transaction + that zeroes out ALE (asset, liability, equity) accounts by default + (this requires account types to be inferred or declared); or, the + accounts matched by the provided ACCTQUERY arguments. -Just one posting to the equity account will be used by default, with an -implicit amount. +2. With --open, it prints an opposite "opening balances" transaction + that restores those balances from zero. This is similar to Ledger's + equity command. -With --x/--explicit the amount will be shown explicitly, and if it -involves multiple commodities, a separate posting will be generated for -each commodity. +3. With --migrate, it prints both the closing and opening transactions. + This is the preferred way to migrate balances to a new file: run + hledger close --migrate, add the closing transaction at the end of + the old file, and add the opening transaction at the start of the + new file. The matching closing/opening transactions cancel each + other out, preserving correct balances during multi-file reporting.1 -With --interleaved, each equity posting is shown next to the -corresponding source/destination posting. +4. With --retain, it prints a "retain earnings" transaction that + transfers RX (revenue and expense) balances to + equity:retained earnings. Businesses traditionally do this at the + end of each accounting period; it is less necessary with + computer-based accounting, but it could still be useful if you want + to see the accounting equation (A=L+E) satisfied. + +In all modes, the defaults can be overridden: + +- the transaction descriptions can be changed with --close-desc=DESC + and --open-desc=DESC +- the account to transfer to/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). + +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). + +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 --interleaved, each individual transfer is shown with source and +destination postings next to each other. This could be 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; @@ -48,13 +70,6 @@ whichever is later. You can change this by specifying a report end date; period will be the closing date; eg -e 2022 means "close on 2022-12-31". The opening date is always the day after the closing date. -close and costs - -With --show-costs, any amount costs are shown, with separate postings -for each cost. (This currently the best way to view investment assets, -showing lots and cost bases.) If you have many currency conversion or -investment transactions, it can generate very large journal entries. - close and balance assertions Balance assertions will be generated, verifying that the accounts have @@ -96,8 +111,9 @@ appending the generated transaction to the journal: $ hledger close --retain -f 2022.journal -p 2022 >> 2022.journal -Now 2022's income statement will show only zeroes. To see it again, -exclude the retain transaction. Eg: +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: $ hledger -f 2022.journal is not:desc:'retain earnings' @@ -112,19 +128,21 @@ $ hledger close --migrate -f 2022.journal -p 2022 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 it again, exclude the closing -transaction. Eg: +try adding --infer-equity.) To see the end-of-year balances again, you +could exclude the closing transaction: $ hledger -f 2022.journal bs not:desc:'closing balances' Example: excluding closing/opening transactions When combining many files for multi-year reports, the closing/opening -transactions cause some noise in reports like print and register. You -can exclude them as shown above, but not:desc:... could be fragile, and -also you will need to avoid excluding the very first opening -transaction, which can be awkward. Here is a way to do it, using tags: -add clopen: tags to all opening/closing balances transactions except the +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: + +Add clopen: tags to all opening/closing balances transactions except the first, like this: ; 2021.journal