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

imp:close: --migrate -> --clopen; more doc rewrites

Browse Source
This commit is contained in:
Simon Michael 2025-01-09 21:04:12 -10:00
parent 2588e31466
commit 6868ab06a4
3 changed files with 95 additions and 83 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

34
hledger/Hledger/Cli/Commands/Close.hs
View File

@ -33,18 +33,15 @@ defretainacct = "equity:retained earnings"
closemode = hledgerCommandMode
$(embedFileRelative "Hledger/Cli/Commands/Close.txt")
[flagOpt "" ["migrate"] (\s opts -> Right $ setopt "migrate" s opts) "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."
)
,flagOpt "" ["close"] (\s opts -> Right $ setopt "close" s opts) "NEW" "(default) show a closing transaction"
,flagOpt "" ["open"] (\s opts -> Right $ setopt "open" s opts) "NEW" "show an opening transaction"
,flagOpt "" ["assign"] (\s opts -> Right $ setopt "assign" s opts) "NEW" "show opening balance assignments"
,flagOpt "" ["assert"] (\s opts -> Right $ setopt "assert" s opts) "NEW" "show closing balance assertions"
,flagOpt "" ["retain"] (\s opts -> Right $ setopt "retain" s opts) "NEW" "show a retain earnings transaction, for Revenue and Expense accounts by default"
,flagNone ["explicit","x"] (setboolopt "explicit") "show all amounts explicitly"
,flagNone ["show-costs"] (setboolopt "show-costs") "show amounts with different costs separately"
,flagNone ["interleaved"] (setboolopt "interleaved") "show source and destination postings together"
[flagOpt "" ["clopen"] (\s opts -> Right $ setopt "clopen" s opts) "TAGVAL" "show closing and opening balances transactions, for AL accounts by default"
,flagOpt "" ["close"] (\s opts -> Right $ setopt "close" s opts) "TAGVAL" "show just a closing balances transaction"
,flagOpt "" ["open"] (\s opts -> Right $ setopt "open" s opts) "TAGVAL" "show just an opening balances transaction"
,flagOpt "" ["assert"] (\s opts -> Right $ setopt "assert" s opts) "TAGVAL" "show a balance assertions transaction"
,flagOpt "" ["assign"] (\s opts -> Right $ setopt "assign" s opts) "TAGVAL" "show a balance assignments transaction"
,flagOpt "" ["retain"] (\s opts -> Right $ setopt "retain" s opts) "TAGVAL" "show a retain earnings transaction, for RX accounts by default"
,flagNone ["explicit","x"] (setboolopt "explicit") "show all amounts explicitly"
,flagNone ["show-costs"] (setboolopt "show-costs") "show amounts with different costs separately"
,flagNone ["interleaved"] (setboolopt "interleaved") "show source and destination postings together"
,flagReq ["assertion-type"] (\s opts -> Right $ setopt "assertion-type" s opts) "TYPE" "=, ==, =* or ==*"
,flagReq ["close-desc"] (\s opts -> Right $ setopt "close-desc" s opts) "DESC" "set closing transaction's description"
,flagReq ["close-acct"] (\s opts -> Right $ setopt "close-acct" s opts) "ACCT" "set closing transaction's destination account"
@ -57,17 +54,18 @@ closemode = hledgerCommandMode
++ -- keep supporting old flag names for compatibility
[flagNone ["closing"] (setboolopt "close") "old spelling of --close"
,flagNone ["opening"] (setboolopt "open") "old spelling of --open"
,flagNone ["migrate"] (setboolopt "clopen") "old spelling of --clopen"
,flagReq ["close-to"] (\s opts -> Right $ setopt "close-acct" s opts) "ACCT" "old spelling of --close-acct"
,flagReq ["open-from"] (\s opts -> Right $ setopt "open-acct" s opts) "ACCT" "old spelling of --open-acct"
]
)
([], Just $ argsFlag "[--migrate|--close|--open|--assign|--assert|--retain] [ACCTQUERY]")
([], Just $ argsFlag "[--close|--open|--clopen|--assign|--assert|--retain] [ACCTQUERY]")
-- | The close command's mode (subcommand).
-- The code depends on these spellings.
data CloseMode = Migrate | Close | Open | Assign | Assert | Retain deriving (Eq,Show,Read)
data CloseMode = Clopen | Close | Open | Assign | Assert | Retain deriving (Eq,Show,Read)
-- | Pick the rightmost flag spelled like a CloseMode (--migrate, --close, --open, etc), or default to Close.
-- | Pick the rightmost flag spelled like a CloseMode (--clopen, --close, --open, etc), or default to Close.
closeModeFromRawOpts :: RawOpts -> CloseMode
closeModeFromRawOpts rawopts = lastDef Close $ collectopts (\(name,_) -> readMay (capitalise name)) rawopts
@ -147,7 +145,7 @@ close CliOpts{rawopts_=rawopts, reportspec_=rspec0} j = do
-- the closing (balance-asserting or balance-zeroing) transaction
mclosetxn
| mode_ `notElem` [Migrate, Close, Assert, Retain] = Nothing
| mode_ `notElem` [Clopen, Close, Assert, Retain] = Nothing
| otherwise = Just nulltransaction{
tdate=closedate, tdescription=closedesc, tcomment=comment, tpostings=closeps
}
@ -162,7 +160,7 @@ close CliOpts{rawopts_=rawopts, reportspec_=rspec0} j = do
-- XXX some duplication
| mode_ == Assert =
[ posting{
paccount = a
paccount = a
,pamount = mixedAmount $ precise b{aquantity=0, acost=Nothing}
-- after each commodity's last posting, assert 0 balance (#1035)
-- balance assertion amounts are unpriced (#824)
@ -210,7 +208,7 @@ close CliOpts{rawopts_=rawopts, reportspec_=rspec0} j = do
-- the opening (balance-assigning or balance-unzeroing) transaction
mopentxn
| mode_ `notElem` [Migrate, Open, Assign] = Nothing
| mode_ `notElem` [Clopen, Open, Assign] = Nothing
| otherwise = Just nulltransaction{
tdate=opendate, tdescription=opendesc, tcomment=comment, tpostings=openps
}

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

@ -2,19 +2,19 @@
(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.
`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 append or copy these to your journal file(s) when you are happy with how they look.
You can copy these into your journal file(s) when you are happy with how they look.
```flags
Flags:
--migrate[=NEW] show closing and opening transactions, for Asset
--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.
--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
@ -39,45 +39,59 @@ Flags:
(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),
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.
The balancing account will be `equity:opening/closing balances` (or another specified by `--close-acct` or `--open-acct`).
Typically, you would run
```
hledger close --clopen -e NEWYEAR >> $LEDGER_FILE
```
and then move the opening transaction from the old file to the new file
(and probably also update your LEDGER_FILE environment variable).
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".
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.
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`](hledger.md#account-types) arguments.
(The balancing account is always excluded.)
Revenues and expenses usually are not migrated to a new file directly; see `--retain` below.
The balances will be transferred to and from `equity:opening/closing balances` by default.
You can override this by using `--close-acct` and/or `--open-acct`.
The generated transactions will have a `clopen:` 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.
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](https://hledger.org/scripts.html#hledger-move).)
### 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).
This prints just the opening balances transaction of `--clopen`.
(It is similar to [Ledger's equity command](https://ledger-cli.org/doc/ledger3.html#The-equity-command).)
### close --assert
@ -92,21 +106,21 @@ Unlike balance assertions, assignments will post changes to balances as needed t
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 `--migrate` is usually recommended [for now](https://github.com/simonmichael/hledger/issues/2151).
so `--clopen` is usually [recommended](https://github.com/simonmichael/hledger/issues/2151).
### close --retain
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 like `--close`, but it closes Revenue and Expense account balances by default.
They will be transferred to `equity:retained earnings`, or another account specified with `--close-acct`.
Revenues and expenses correspond to changes in equity.
They are categorised separately for reporting purposes,
but traditionally at the end of each accounting period, businesses consolidate them into equity,
This is called "retaining earnings", or "closing the books".
Revenues and expenses are actually part of equity, kept separate temporarily for clarity;
once they have been seen and noted, at the end of each accounting period,
businesses normally consolidate them into equity,
In personal accounting, there's not much benefit from this, and most people don't do it.
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.
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
@ -196,7 +210,7 @@ $ hledger -f 2022.journal is not:desc:'retain earnings'
Close assets/liabilities on 2022-12-31 and re-open them on 2023-01-01:
```cli
$ 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
```

44
hledger/test/close.test
View File

@ -20,7 +20,7 @@
# ** 1. By default, closes ALE accounts, on the last day of the report period.
$ hledger close -f- -e 2017
2016-12-31 closing balances ; start:
2016-12-31 closing balances ; clopen:
assets:bank $-80 = $0
assets:cash $-10 = $0
liabilities $-25 = $0
@ -30,7 +30,7 @@ $ hledger close -f- -e 2017
# ** 2. With --close, likewise.
$ hledger close -f- -e 2017 --close
2016-12-31 closing balances ; start:
2016-12-31 closing balances ; clopen:
assets:bank $-80 = $0
assets:cash $-10 = $0
liabilities $-25 = $0
@ -46,15 +46,15 @@ $ hledger close -f- -e 2017 --retain
>=0
# ** 4. With --migrate, opens and closes ALE.
$ hledger close -f- -p 2016 --migrate
2016-12-31 closing balances ; start:
# ** 4. With --clopen, opens and closes ALE.
$ hledger close -f- -p 2016 --clopen
2016-12-31 closing balances ; clopen:
assets:bank $-80 = $0
assets:cash $-10 = $0
liabilities $-25 = $0
equity:opening/closing balances
2017-01-01 opening balances ; start:
2017-01-01 opening balances ; clopen:
assets:bank $80 = $80
assets:cash $10 = $10
liabilities $25 = $25
@ -64,7 +64,7 @@ $ hledger close -f- -p 2016 --migrate
# ** 5. With --open, opens ALE.
$ hledger close -f- -p 2016 --open
2017-01-01 opening balances ; start:
2017-01-01 opening balances ; clopen:
assets:bank $80 = $80
assets:cash $10 = $10
liabilities $25 = $25
@ -74,7 +74,7 @@ $ hledger close -f- -p 2016 --open
# ** 6. -x makes all amounts explicit.
$ hledger close -f- -p 2016 -x
2016-12-31 closing balances ; start:
2016-12-31 closing balances ; clopen:
assets:bank $-80 = $0
assets:cash $-10 = $0
liabilities $-25 = $0
@ -90,7 +90,7 @@ $ hledger close -f- -p 2016 -x
equity
$ hledger -f- close assets -p 2019 -x
2019-12-31 closing balances ; start:
2019-12-31 closing balances ; clopen:
assets -2A = 0A
equity:opening/closing balances 2A
@ -100,7 +100,7 @@ $ hledger -f- close assets -p 2019 -x
# Only the last posting in each commodity gets a balance assertion (#1035).
# Balance assertion amounts do not have a price.
$ hledger -f- close assets -p 2019 --show-costs -x
2019-12-31 closing balances ; start:
2019-12-31 closing balances ; clopen:
assets -1A @ 1B
assets -1A @ 1C = 0A
equity:opening/closing balances 1A @ 1B
@ -119,7 +119,7 @@ $ hledger -f- close assets -p 2019 --show-costs -x
(assets) 1A @ 2B
$ hledger -f- close assets -p 2019 -x
2019-12-31 closing balances ; start:
2019-12-31 closing balances ; clopen:
assets -2A = 0A
equity:opening/closing balances 2A
@ -127,7 +127,7 @@ $ hledger -f- close assets -p 2019 -x
# ** 10. The same with costs preserved.
$ hledger -f- close assets -p 2019 --show-costs -x
2019-12-31 closing balances ; start:
2019-12-31 closing balances ; clopen:
assets -1A @ 1B
assets -1A @ 2B = 0A
equity:opening/closing balances 1A @ 1B
@ -160,7 +160,7 @@ $ hledger -f- close assets -p 2019 --show-costs -x
liabilities:employer
$ hledger -f- close -p 2016 assets liabilities --show-costs -x
2016-12-31 closing balances ; start:
2016-12-31 closing balances ; clopen:
assets:bank -5,733.00 EUR = 0.00 EUR
liabilities:employer $-10,000.00
liabilities:employer $5,000.00 @ 0.93 EUR
@ -177,7 +177,7 @@ $ hledger -f- close -p 2016 assets liabilities --show-costs -x
# (And balances with the same cost are not necessarily combined into
# a single posting. Eg the 5734 EUR above is 5733 EUR and 1 EUR below.)
$ hledger -f- close -p 2016 assets liabilities --interleaved --show-costs -x
2016-12-31 closing balances ; start:
2016-12-31 closing balances ; clopen:
assets:bank -5,733.00 EUR = 0.00 EUR
equity:opening/closing balances 5,733.00 EUR
liabilities:employer $-10,000.00
@ -206,7 +206,7 @@ commodity AAA 0.00000000
expenses:banking $0.1280810
$ hledger -f- close -p 2019 assets --show-costs -x
2019-12-31 closing balances ; start:
2019-12-31 closing balances ; clopen:
assets:aaa AAA -510 = AAA 0
assets:usd $-49.50
assets:usd $49.3900010 @ AAA 10.3528243 = $0.0000000
@ -218,7 +218,7 @@ $ hledger -f- close -p 2019 assets --show-costs -x
# ** 14. The same, without costs and with --interleaved.
$ hledger -f- close -p 2019 assets --interleaved -x
2019-12-31 closing balances ; start:
2019-12-31 closing balances ; clopen:
assets:aaa AAA -510 = AAA 0
equity:opening/closing balances AAA 510
assets:usd $-0.1099990 = $0.0000000
@ -245,12 +245,12 @@ commodity $1,000.00
2000-01-01
(assets:a) $1,000 @@ $1,000
$ hledger -f- close --migrate --show-costs -e 2001
2000-12-31 closing balances ; start:
$ hledger -f- close --clopen --show-costs -e 2001
2000-12-31 closing balances ; clopen:
assets:a $-1,000. @@ $1,000. = $0
equity:opening/closing balances
2001-01-01 opening balances ; start:
2001-01-01 opening balances ; clopen:
assets:a $1,000. @@ $1,000. = $1,000.
equity:opening/closing balances
@ -264,12 +264,12 @@ $ hledger -f- close --assert --show-costs -e 2001
>=
# ** 19. close supports --round, like print.
$ hledger -f- close --migrate -e 2001 --round=hard -c '$1.0'
2000-12-31 closing balances ; start:
$ hledger -f- close --clopen -e 2001 --round=hard -c '$1.0'
2000-12-31 closing balances ; clopen:
assets:a $-1000.0 = $0.0
equity:opening/closing balances
2001-01-01 opening balances ; start:
2001-01-01 opening balances ; clopen:
assets:a $1000.0 = $1000.0
equity:opening/closing balances