slaesvuo/hledger
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

;doc:close: rewrite again; and give a better excluding technique [#2151]

Browse Source
This commit is contained in:
Simon Michael 2024-01-20 09:23:56 -10:00
parent cd72c62858
commit 785206ee94
1 changed files with 105 additions and 101 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

206
hledger/Hledger/Cli/Commands/Close.md
View File

@ -2,90 +2,104 @@
(equity) (equity)
A transaction-generating command which generates several kinds of "closing" `close` generates several kinds of "closing" and/or "opening" transactions, useful in certain situations, including
and/or "opening" transactions useful in certain situations. migrating balances to a new journal file, retaining earnings into equity, consolidating balances, or viewing lots.
It prints one or two transactions to stdout, but does not write them to the journal file; Like `print`, it prints valid journal entries.
you can append or copy them there when you are happy with the output. You can append or copy these to your journal file(s) when you are happy with how they look.
_FLAGS _FLAGS
<!-- related: --> <!-- related: -->
This command is most often used when migrating balances to a new journal file, at the start of a new financial year. `close` currently has six modes, selected by a single mode flag:
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:
1. With `--close` (or no mode flag) it prints a "closing balances" transaction ### `close --migrate`
that zeroes out all the asset and liability account balances, by default
(this requires [account types](hledger.md#account-types) to be detected or declared.).
All of the balances are transferred to a special "opening/closing balances" equity account.
Or, if it will zero out the accounts matched by query arguments you provide.
Eg you could include assets, liabilities, and equity with `hledger close type:ALE`.
The "opening/closing balances" equity account is always excluded.
2. With `--open`, it prints an opposite "opening balances" transaction that This is the most common mode.
restores the same account balances, starting from zero. It prints a "closing balances" transaction that zeroes out all asset and liability balances (by default),
<!-- This mode is similar to [Ledger's equity command](https://ledger-cli.org/doc/ledger3.html#The-equity-command). --> 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` and/or `--open-acct`).
3. With `--migrate`, it prints both the closing and opening transactions above. This is useful when migrating balances to a new journal file at the start of a new year.
This is a common way to migrate balances to a new file at year end; Essentially, you run `hledger close --migrate -e NEWYEAR`
run `hledger close --migrate -e NEWYEAR` (-e influences the transaction date) and then copy the closing transaction to the end of the old file
and add the closing transaction at the end of the old file, and the opening transaction to the start of the new file.
and the opening transaction at the start of the new file. The opening transaction sets correct starting balances in the new file when it is used alone,
Doing this means you can include past year files in your reports at any time and the closing transaction keeps balances correct when you use both old and new files together,
without disturbing asset/liability/equity balances, by cancelling out the following opening transaction and preventing buildup of duplicated opening balances.
because the closing balances transaction cancels out the following opening balances transaction. Think of the closing/opening pair as "moving the balances into the next file".
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 You can close a different set of accounts by providing a query.
just asserts the current balances, without changing them. Most people don't need to migrate equity (?)
This can be useful as documention and to guard against errors and changes. but you can include it by adding a `type:ALE` argument (except `equity:opening/closing balances`, which 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 ### `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](https://ledger-cli.org/doc/ledger3.html#The-equity-command).
### `close --assert`
This prints a "closing balances" transaction that just declares [balance assertions](#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). 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. 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 However, omitting the closing balances transaction would unbalance equity.
revenue and expense balances to `equity:retained earnings`. This is relatively harmless for personal reports, but it disturbs the accounting equation, removing a source of error detection.
This is a traditional end-of-period bookkeeping operation also called "closing the books"; So `--migrate` is generally the best way to set to set balances in new files, [for now](https://github.com/simonmichael/hledger/issues/2151).
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 --retain`
This is like `--close` with different defaults:
it prints a "retain earnings" transaction 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: In all modes, the following things can be overridden:
- the transaction descriptions can be changed with `--close-desc=DESC` and `--open-desc=DESC` - the accounts to be closed/opened, with account query arguments
- the account to transfer to and from can be changed with `--close-acct=ACCT` and `--open-acct=ACCT` - the balancing account, with `--close-acct=ACCT` and/or `--open-acct=ACCT`
- the accounts to be closed/opened can be changed with `ACCTQUERY` (account query arguments). - the transaction descriptions, with `--close-desc=DESC` and `--open-desc=DESC`
- the closing/opening dates can be changed with `-e DATE` (a report end date) - the closing/opening dates, with `-e OPENDATE`
By default just one destination/source posting will be used, with its amount left implicit. By default, the closing date is yesterday, or the journal's end date, whichever is later;
With `--x/--explicit`, the amount will be shown explicitly, and the opening date is always one day after the closing date.
You can change these by specifying a [report end date](#report-start--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 `--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 and if it involves multiple commodities, a separate posting will be generated for each of them
(similar to `print -x`). (similar to `print -x`).
With `--show-costs`, any amount costs are shown, with separate postings for each cost. With `--interleaved`, each individual transfer is shown with source and destination postings next to each other
This is currently the best way to view investment lots. (perhaps useful for troubleshooting).
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 With `--show-costs`, balances' costs are also shown, with different costs kept separate.
and destination postings next to each other. This may generate very large journal entries, if you have many currency conversions or investment transactions.
This could be useful for troubleshooting. `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`](scripts.md#hledger-move) script.)
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](#report-start--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.
### close and balance assertions ### close and balance assertions
@ -122,7 +136,9 @@ in effect splitting the multi-day transaction into two single-day transactions:
assets:bank:checking -5 assets:bank:checking -5
``` ```
### Example: retain earnings ### close examples
#### Retain earnings
<!-- XXX update --> <!-- XXX update -->
@ -133,16 +149,16 @@ appending the generated transaction to the journal:
$ hledger close --retain -f 2022.journal -p 2022 >> 2022.journal $ hledger close --retain -f 2022.journal -p 2022 >> 2022.journal
``` ```
Note 2022's income statement will now show only zeroes, 2022's income statement will now show only zeroes,
because revenues and expenses have been moved entirely to equity. because revenues and expenses have been moved entirely to equity.
To see them again, you could exclude the retain transaction: To see their end balances, you could exclude the retain transaction:
```cli ```cli
$ hledger -f 2022.journal is not:desc:'retain earnings' $ 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:
```cli ```cli
$ hledger close --migrate -f 2022.journal -p 2022 $ hledger close --migrate -f 2022.journal -p 2022
@ -159,63 +175,51 @@ $ hledger close --open -f 2022.journal -p 2022 >> 2022.journal
``` ```
--> -->
Now 2022's balance sheet will show only zeroes, indicating a balanced accounting equation. 2022's balance sheet will now show only zeroes, indicating a balanced accounting equation.
([Unless](/investments.html#a-more-correct-entry) you are using @/@@ notation - in that case, try adding --infer-equity.) ([Unless](/investments.html#a-more-correct-entry) 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: (Do we need to close equity also ? retest)
To see the end-of-year balances, you could exclude the closing transaction:
```cli ```cli
$ hledger -f 2022.journal bs not:desc:'closing balances' $ hledger -f 2022.journal bs not:desc:'closing balances'
``` ```
### Example: excluding closing/opening transactions #### Exclude opening/closing transactions
When combining many files for multi-year reports, When combining files for multi-year reports, for some reports (eg a yearly balance sheet)
the closing/opening transactions cause some noise in transaction-oriented reports like `print` and `register`. you may need to suppress all opening/closing transactions except the first.
You can exclude them as shown above, but `not:desc:...` is not ideal This is a bit awkward if you also want to be able to choose any range of year files,
as it depends on consistent descriptions; also you will want to avoid excluding but here is a way, using tags:
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:
```journal ```journal
; 2021.journal ; 2021.journal
2021-06-01 first opening balances 2021-06-01 opening balances ; start:2021
... ...
2021-12-31 closing balances ; clopen:2022 2021-12-31 closing balances ; start:2022
... ...
``` ```
```journal ```journal
; 2022.journal ; 2022.journal
2022-01-01 opening balances ; clopen:2022 2022-01-01 opening balances ; start:2022
... ...
2022-12-31 closing balances ; clopen:2023 2022-12-31 closing balances ; start:2023
... ...
``` ```
```journal ```journal
; 2023.journal ; 2023.journal
2023-01-01 opening balances ; clopen:2023 2023-01-01 opening balances ; start:2023
... ...
``` ```
Now, assuming a combined journal like: All of these will show the year-end balances correctly:
```journal
; 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:
```cli ```cli
$ hledger -f all.journal areg checking not:tag:clopen $ hledger bs -Y -f 2021.journal -f 2022.journal -f 2023.journal expr:'tag:start=2021 or not tag:start'
$ hledger bs -Y -f 2021.journal -f 2022.journal expr:'tag:start=2021 or not tag:start'
$ hledger bs -Y -f 2022.journal -f 2023.journal expr:'tag:start=2022 or not tag:start'
$ hledger bs -Y -f 2021.journal expr:'tag:start=2021 or not tag:start'
$ hledger bs -Y -f 2022.journal expr:'tag:start=2022 or not tag:start'
$ hledger bs -Y -f 2023.journal # unclosed file, no query needed
``` ```
And the year values allow more precision.
To show 2022's year-end balance sheet:
```cli
$ hledger -f all.journal bs -e2023 not:tag:clopen=2023
```