From 50441dae046a7a60779f3259fd0a99de5e712491 Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Sat, 6 Jan 2024 18:26:53 -1000 Subject: [PATCH] ;doc:close: improvements --- hledger/Hledger/Cli/Commands/Close.md | 57 +++++++++++++++------------ 1 file changed, 32 insertions(+), 25 deletions(-) diff --git a/hledger/Hledger/Cli/Commands/Close.md b/hledger/Hledger/Cli/Commands/Close.md index 6ee167765..1b10a178d 100644 --- a/hledger/Hledger/Cli/Commands/Close.md +++ b/hledger/Hledger/Cli/Commands/Close.md @@ -4,50 +4,57 @@ 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 automatically. +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. *(experimental)* _FLAGS + + This command is most often used when migrating balances to a new journal file, at the start of a new financial year. There are a few -ways to do that, we're not sure which is best, and this command has -other uses as well; so it currently has six modes, selected by a mode -flag. Use only one of these flags at a time: +ways to do that, we're not sure which is best, and this command is +also a sort of general "balance mover"; so it currently has six modes, +selected by a mode flag. Use only one of these flags at a time: 1. With `--close` (or no mode flag) it prints a "closing balances" transaction -that zeroes out all the ALE (asset, liability, equity) accounts, by default -(this requires inferred or declared [account types](hledger.md#account-types)); -or, the accounts matched by ACCTQUERY arguments you provide. -The balances are transferred to an equity account. +that zeroes out all the asset, liability, and equity account balances, by default +(this requires inferred or declared [account types](hledger.md#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. 2. With `--open`, it prints an opposite "opening balances" transaction that "unzeros" the same accounts, restoring their balances from zero. (This mode is similar to Ledger's equity command.) -3. With `--migrate`, it prints both the `--close` and the `--open` transactions. +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` (or `hledger close --close` and `hleddger close --open`) -and add the closing transaction at the end of the old file, +run `hledger close --migrate -e NEWYEAR` and add the closing transaction at the end of the old file, and the opening transaction at the start of the new file. -This allows you to use the new file by itself, or together with previous file(s), -and still get correct balances either way, -because the matching closing/opening transactions will cancel each other out. -(You will need to exclude them sometimes, eg to see an end of year balance sheet; -`not:opening/closing` often works.) +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](https://www.reddit.com/r/plaintextaccounting/comments/18zxlbn/hledger_year_closing/). +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. 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. 5. With `--assign` it prints an "opening balances" transaction that -restores the account balances by using balance assignments, -which always succeed and do need to be preceded by a closing transaction. -This is an alternative to `--close` and `--open`: at year end -you can `--assert` in the old file and `--assign` in the new file; -(or skip the `--assert` and just do the `--assign`). -This sacrifices some error checking, but could be convenient if you are -often doing cleanups or fixes which break your closing/opening transactions. +restores the account balances using [balance assignments](#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. 6. With `--retain`, it prints a "retain earnings" transaction that transfers RX (revenue and expense) balances to `equity:retained earnings`. @@ -55,10 +62,10 @@ This is a traditional end-of-period bookkeeping operation also called "closing t 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. -In all modes, the defaults can be overridden: +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/from can be changed with `--close-acct=ACCT` and `--open-acct=ACCT` +- 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)