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

;doc: update manuals

Browse Source
This commit is contained in:
Simon Michael 2024-01-26 22:49:07 -10:00
parent 015943b93d
commit 32ef1e3dd9
9 changed files with 2598 additions and 2423 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
hledger-ui/hledger-ui.1
View File

@ -113,9 +113,6 @@ Field separator to expect when reading CSV (default: \[aq],\[aq])
\f[CR]\-\-alias=OLD=NEW\f[R]
rename accounts named OLD to NEW
.TP
\f[CR]\-\-anon\f[R]
anonymize accounts and payees
.TP
\f[CR]\-\-pivot FIELDNAME\f[R]
use some other field or tag for the account name
.TP

71
hledger-ui/hledger-ui.info
View File

@ -148,9 +148,6 @@ File: hledger-ui.info, Node: General input options, Next: General reporting op
'--alias=OLD=NEW'
rename accounts named OLD to NEW
'--anon'
anonymize accounts and payees
'--pivot FIELDNAME'
use some other field or tag for the account name
@ -680,40 +677,40 @@ Node: General help options2951
Ref: #general-help-options3100
Node: General input options3382
Ref: #general-input-options3567
Node: General reporting options4269
Ref: #general-reporting-options4433
Node: MOUSE7823
Ref: #mouse7918
Node: KEYS8155
Ref: #keys8248
Node: SCREENS12903
Ref: #screens13001
Node: Menu13581
Ref: #menu13674
Node: Cash accounts13869
Ref: #cash-accounts14011
Node: Balance sheet accounts14195
Ref: #balance-sheet-accounts14376
Node: Income statement accounts14496
Ref: #income-statement-accounts14682
Node: All accounts14846
Ref: #all-accounts14992
Node: Register15174
Ref: #register15298
Node: Transaction17582
Ref: #transaction17705
Node: Error19122
Ref: #error19216
Node: TIPS19460
Ref: #tips19559
Node: Watch mode19601
Ref: #watch-mode19708
Node: Debug output21167
Ref: #debug-output21278
Node: ENVIRONMENT21490
Ref: #environment21600
Node: BUGS21791
Ref: #bugs21874
Node: General reporting options4224
Ref: #general-reporting-options4388
Node: MOUSE7778
Ref: #mouse7873
Node: KEYS8110
Ref: #keys8203
Node: SCREENS12858
Ref: #screens12956
Node: Menu13536
Ref: #menu13629
Node: Cash accounts13824
Ref: #cash-accounts13966
Node: Balance sheet accounts14150
Ref: #balance-sheet-accounts14331
Node: Income statement accounts14451
Ref: #income-statement-accounts14637
Node: All accounts14801
Ref: #all-accounts14947
Node: Register15129
Ref: #register15253
Node: Transaction17537
Ref: #transaction17660
Node: Error19077
Ref: #error19171
Node: TIPS19415
Ref: #tips19514
Node: Watch mode19556
Ref: #watch-mode19663
Node: Debug output21122
Ref: #debug-output21233
Node: ENVIRONMENT21445
Ref: #environment21555
Node: BUGS21746
Ref: #bugs21829

End Tag Table

2
hledger-ui/hledger-ui.txt
View File

@ -102,8 +102,6 @@ OPTIONS
--alias=OLD=NEW
rename accounts named OLD to NEW
--anon anonymize accounts and payees
--pivot FIELDNAME
use some other field or tag for the account name

3
hledger-web/hledger-web.1
View File

@ -160,9 +160,6 @@ Field separator to expect when reading CSV (default: \[aq],\[aq])
\f[CR]\-\-alias=OLD=NEW\f[R]
rename accounts named OLD to NEW
.TP
\f[CR]\-\-anon\f[R]
anonymize accounts and payees
.TP
\f[CR]\-\-pivot FIELDNAME\f[R]
use some other field or tag for the account name
.TP

39
hledger-web/hledger-web.info
View File

@ -189,9 +189,6 @@ File: hledger-web.info, Node: General input options, Next: General reporting o
'--alias=OLD=NEW'
rename accounts named OLD to NEW
'--anon'
anonymize accounts and payees
'--pivot FIELDNAME'
use some other field or tag for the account name
@ -638,24 +635,24 @@ Node: General help options5257
Ref: #general-help-options5407
Node: General input options5689
Ref: #general-input-options5875
Node: General reporting options6577
Ref: #general-reporting-options6742
Node: PERMISSIONS10132
Ref: #permissions10271
Node: EDITING UPLOADING DOWNLOADING11483
Ref: #editing-uploading-downloading11664
Node: RELOADING12498
Ref: #reloading12632
Node: JSON API13065
Ref: #json-api13180
Node: DEBUG OUTPUT18668
Ref: #debug-output18793
Node: Debug output18820
Ref: #debug-output-118921
Node: ENVIRONMENT19338
Ref: #environment19457
Node: BUGS19574
Ref: #bugs19658
Node: General reporting options6532
Ref: #general-reporting-options6697
Node: PERMISSIONS10087
Ref: #permissions10226
Node: EDITING UPLOADING DOWNLOADING11438
Ref: #editing-uploading-downloading11619
Node: RELOADING12453
Ref: #reloading12587
Node: JSON API13020
Ref: #json-api13135
Node: DEBUG OUTPUT18623
Ref: #debug-output18748
Node: Debug output18775
Ref: #debug-output-118876
Node: ENVIRONMENT19293
Ref: #environment19412
Node: BUGS19529
Ref: #bugs19613

End Tag Table

2
hledger-web/hledger-web.txt
View File

@ -142,8 +142,6 @@ OPTIONS
--alias=OLD=NEW
rename accounts named OLD to NEW
--anon anonymize accounts and payees
--pivot FIELDNAME
use some other field or tag for the account name

437
hledger/hledger.1
View File

@ -343,9 +343,6 @@ Field separator to expect when reading CSV (default: \[aq],\[aq])
\f[CR]\-\-alias=OLD=NEW\f[R]
rename accounts named OLD to NEW
.TP
\f[CR]\-\-anon\f[R]
anonymize accounts and payees
.TP
\f[CR]\-\-pivot FIELDNAME\f[R]
use some other field or tag for the account name
.TP
@ -992,6 +989,11 @@ $ hledger print \-c \[aq]$1.000,0\[aq]
This option can repeated to set the display style for multiple
commodities/currencies.
Its argument is as described in the commodity directive.
.PP
hledger will occasionally make some additional adjustments to number
formatting, eg adding a trailing decimal mark to disambiguate numbers
with digit group marks; for details, see Amount formatting,
parseability.
.SS Colour
In terminal output, some commands can produce colour when the terminal
supports it:
@ -1667,6 +1669,11 @@ reports.
When rounding, hledger uses banker\[aq]s rounding (it rounds to the
nearest even digit).
So eg 0.5 displayed with zero decimal digits appears as \[dq]0\[dq].
.SS Number format
hledger will occasionally make some additional adjustments to number
formatting, eg adding a trailing decimal mark to disambiguate numbers
with digit group marks; for details, see Amount formatting,
parseability.
.PP
.SS Costs
After a posting amount, you can note its cost (when buying) or selling
@ -2018,8 +2025,11 @@ by a full colon, in a transaction or posting or account directive\[aq]s
comment.
(This is an exception to the usual rule that things in comments are
ignored.)
Eg, here four different tags are recorded: one on the checking account,
two on the transaction, and one on the expenses posting:
You can write multiple tags separated by comma, and/or you can add more
comment lines and write more tags there.
.PP
Here five different tags are recorded: one on the checking account, two
on the transaction, and two on the expenses posting:
.IP
.EX
account assets:checking ; accounttag:
@ -2027,18 +2037,58 @@ account assets:checking ; accounttag:
2017/1/16 bought groceries ; transactiontag\-1:
; transactiontag\-2:
assets:checking $\-1
expenses:food $1 ; postingtag:
expenses:food $1 ; postingtag:, another\-posting\-tag:
.EE
.PP
Postings also inherit tags from their transaction and their account.
And transactions also acquire tags from their postings (and
postings\[aq] accounts).
So in the example above, the expenses posting effectively has all four
tags (by inheriting from account and transaction), and the transaction
also has all four tags (by acquiring from the expenses posting).
.PP
You can list tag names with \f[CR]hledger tags [NAMEREGEX]\f[R], or
match by tag name with a \f[CR]tag:NAMEREGEX\f[R] query.
.SS Tag inheritance
Postings also inherit tags from their transaction and their account.
And transactions also acquire tags from their postings (and
postings\[aq] accounts).
So in the example above, the expenses posting effectively has all five
tags (by inheriting from the account and transaction), and the
transaction also has all five tags (by acquiring from the expenses
posting).
.SS Tag names
Tag names are currently not very clearly specified; any sequence of
non\-whitespace characters followed by a colon may work.
.PP
The following tag names are generated by hledger or have special
significance to hledger, so you may want to avoid using them yourself:
.IP \[bu] 2
\f[CR]balances\f[R] \-\- a balance assertions transaction generated by
close
.IP \[bu] 2
\f[CR]retain\f[R] \-\- a retain earnings transaction generated by close
.IP \[bu] 2
\f[CR]start\f[R] \-\- a opening balances, closing balances or balance
assignment transaction generated by close
.IP \[bu] 2
\f[CR]generated\-transaction\f[R] \-\- a transaction generated by
\-\-forecast
.IP \[bu] 2
\f[CR]generated\-posting\f[R] \-\- a posting generated by \-\-auto
.IP \[bu] 2
\f[CR]modified\f[R] \-\- a transaction which has had postings added by
\-\-auto
.IP \[bu] 2
\f[CR]type\f[R] \-\- declares an account\[aq]s type in an account
declaration
.IP \[bu] 2
\f[CR]t\f[R] \-\- stores the (user defined, single letter) type of a 15m
unit of time parsed from timedot format
.PP
Some additional tag names with an underscore prefix are used internally
and not displayed in reports (but can be matched by queries):
.IP \[bu] 2
\f[CR]_generated\-transaction\f[R]
.IP \[bu] 2
\f[CR]_generated\-posting\f[R]
.IP \[bu] 2
\f[CR]_modified\f[R]
.IP \[bu] 2
\f[CR]_conversion\-matched\f[R]
.SS Tag values
Tags can have a value, which is any text after the colon up until a
comma or end of line (with surrounding whitespace removed).
@ -4206,12 +4256,14 @@ By default they are OR\[aq]d (any one of them can match)
When a matcher is preceded by ampersand (\f[CR]&\f[R]) it will be
AND\[aq]ed with the previous matcher (both of them must match)
.IP \[bu] 2
When a matcher is preceded by an exclamation mark (\f[CR]!\f[R]), the
matcher is negated (it may not match).
\f[I]Added in 1.32\f[R] When a matcher is preceded by an exclamation
mark (\f[CR]!\f[R]), the matcher is negated (it may not match).
.PP
Currently there is a limitation: you can\[aq]t use both \f[CR]&\f[R] and
\f[CR]!\f[R] on the same line (you can\[aq]t AND a negated matcher).
.SS Match groups
\f[I]Added in 1.32\f[R]
.PP
Matchers can define match groups: parenthesised portions of the regular
expression which are available for reference in field assignments.
Groups are enclosed in regular parentheses (\f[CR](\f[R] and
@ -5195,7 +5247,7 @@ one or more dots (period characters), each representing 0.25.
These are the dots in \[dq]timedot\[dq].
Spaces are ignored and can be used for grouping/alignment.
.IP \[bu] 2
one or more letters.
\f[I]Added in 1.32\f[R] one or more letters.
These are like dots but they also generate a tag \f[CR]t:\f[R] (short
for \[dq]type\[dq]) with the letter as its value, and a separate posting
for each of the values.
@ -7876,7 +7928,7 @@ memory, use the \f[CR]\-\-align\-all\f[R] flag.
This command also supports the output destination and output format
options.
The output formats supported are \f[CR]txt\f[R], \f[CR]csv\f[R],
\f[CR]tsv\f[R], and \f[CR]json\f[R].
\f[CR]tsv\f[R] (\f[I]Added in 1.32\f[R]), and \f[CR]json\f[R].
.SS aregister and posting dates
aregister always shows one line (and date and amount) per transaction.
But sometimes transactions have postings with different dates.
@ -7981,8 +8033,9 @@ commodities displayed on the same line or multiple lines
(\f[CR]\-\-layout\f[R])
.PP
This command supports the output destination and output format options,
with output formats \f[CR]txt\f[R], \f[CR]csv\f[R], \f[CR]tsv\f[R],
\f[CR]json\f[R], and (multi\-period reports only:) \f[CR]html\f[R].
with output formats \f[CR]txt\f[R], \f[CR]csv\f[R], \f[CR]tsv\f[R]
(\f[I]Added in 1.32\f[R]), \f[CR]json\f[R], and (multi\-period reports
only:) \f[CR]html\f[R].
In \f[CR]txt\f[R] output in a colour\-supporting terminal, negative
amounts are shown in red.
.PP
@ -9041,7 +9094,8 @@ sign flipped.
.PP
This command also supports the output destination and output format
options The output formats supported are \f[CR]txt\f[R], \f[CR]csv\f[R],
\f[CR]tsv\f[R], \f[CR]html\f[R], and \f[CR]json\f[R].
\f[CR]tsv\f[R] (\f[I]Added in 1.32\f[R]), \f[CR]html\f[R], and
\f[CR]json\f[R].
.SS balancesheetequity
(bse)
.PP
@ -9149,7 +9203,8 @@ but with smarter account detection.
.PP
This command also supports the output destination and output format
options The output formats supported are \f[CR]txt\f[R], \f[CR]csv\f[R],
\f[CR]tsv\f[R], \f[CR]html\f[R], and \f[CR]json\f[R].
\f[CR]tsv\f[R] (\f[I]Added in 1.32\f[R]), \f[CR]html\f[R], and
\f[CR]json\f[R].
.SS check
Check for various kinds of errors in your data.
.PP
@ -9245,133 +9300,150 @@ against the real\-world balance.)
.SS close
(equity)
.PP
A transaction\-generating command which generates several kinds of
\[dq]closing\[dq] and/or \[dq]opening\[dq] transactions useful in
certain situations.
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.
\f[CR]close\f[R] generates several kinds of \[dq]closing\[dq] and/or
\[dq]opening\[dq] transactions, useful in certain situations, including
migrating balances to a new journal file, retaining earnings into
equity, consolidating balances, or viewing lots.
Like \f[CR]print\f[R], it prints valid journal entries.
You can append or copy these to your journal file(s) when you are happy
with how they look.
.PP
This command is most often used when migrating balances to a new journal
file, at the start of a new financial year.
It can also be used to \[dq]retain earnings\[dq] (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:
.IP "1." 3
With \f[CR]\-\-close\f[R] (or no mode flag) it prints a \[dq]closing
balances\[dq] transaction that zeroes out all the asset, liability, and
equity account balances, by default (this requires inferred or declared
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 \[dq]opening/closing
balances\[dq] equity account.
.IP "2." 3
With \f[CR]\-\-open\f[R], it prints an opposite \[dq]opening
balances\[dq] transaction that restores the same account balances,
starting from zero.
This mode is similar to Ledger\[aq]s equity command.
.IP "3." 3
With \f[CR]\-\-migrate\f[R], 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
\f[CR]hledger close \-\-migrate \-e NEWYEAR\f[R] (\-e influences the
transaction date) and add the closing transaction at the end of the old
file, and the opening transaction at the start of the new file.
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 \f[CR]not:opening/closing\f[R]
query argument should do.
You should probably also use this query when \f[CR]close\f[R]\-ing, to
exclude the \[dq]opening/closing balances\[dq] account which might
otherwise cause problems.
Or you can just migrate assets and liabilities:
\f[CR]hledger close type:AL\f[R].
Most people don\[aq]t need to migrate equity.
And revenues and expenses usually should not be migrated.
.IP "4." 3
With \f[CR]\-\-assert\f[R] it prints a \[dq]closing balances\[dq]
transaction that just asserts the current balances, without changing
them.
This can be useful as documention and to guard against errors and
changes.
.IP "5." 3
With \f[CR]\-\-assign\f[R] it prints an \[dq]opening balances\[dq]
transaction that restores the account balances using balance
assignments.
\f[CR]close\f[R] currently has six modes, selected by a single mode
flag:
.SS close \-\-migrate
This is the most common mode.
It prints a \[dq]closing balances\[dq] transaction that zeroes out all
asset and liability balances (by default), and an opposite \[dq]opening
balances\[dq] transaction that restores them again.
The balancing account will be \f[CR]equity:opening/closing balances\f[R]
(or another specified by \f[CR]\-\-close\-acct\f[R] or
\f[CR]\-\-open\-acct\f[R]).
.PP
This is useful when migrating balances to a new journal file at the
start of a new year.
Essentially, you run
\f[CR]hledger close \-\-migrate=NEWYEAR \-e NEWYEAR\f[R] 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 \[dq]moving the balances into the
next file\[dq].
.PP
You can close a different set of accounts by providing a query.
Eg if you want to include equity, you can add
\f[CR]assets liabilities equity\f[R] or \f[CR]type:ALE\f[R] arguments.
(The balancing account is always excluded.)
Revenues and expenses usually are not migrated to a new file directly;
see \f[CR]\-\-retain\f[R] below.
.PP
The generated transactions will have a \f[CR]start:\f[R] tag, with its
value set to \f[CR]\-\-migrate\f[R]\[aq]s \f[CR]NEW\f[R] argument if
any, for easier matching or exclusion.
When \f[CR]NEW\f[R] is not specified, it will be inferred if possible by
incrementing a number (eg a year number) within the default
journal\[aq]s main file name.
The other modes behave similarly.
.SS close \-\-close
This prints just the closing balances transaction of
\f[CR]\-\-migrate\f[R].
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.
.SS close \-\-open
This prints just the opening balances transaction of
\f[CR]\-\-migrate\f[R].
It is similar to Ledger\[aq]s equity command.
.SS close \-\-assert
This prints a \[dq]closing balances\[dq] transaction (with
\f[CR]balances:\f[R] tag), that just declares balance assertions for the
current balances without changing them.
It could be useful as documention and to guard against changes.
.SS close \-\-assign
This prints an \[dq]opening balances\[dq] 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 is an alternative to \f[CR]\-\-close\f[R] and \f[CR]\-\-open\f[R]:
at year end, \f[CR]hledger close \-\-assert \-e NEWYEAR\f[R] in the old
file (optional, but useful for error checking), and
\f[CR]hledger close \-\-assign \-e NEWYEAR\f[R] in the new file.
This might be more convenient, eg if you are often doing cleanups or
fixes which would break closing/opening transactions.
.IP "6." 3
With \f[CR]\-\-retain\f[R], it prints a \[dq]retain earnings\[dq]
transaction that transfers revenue and expense balances to
\f[CR]equity:retained earnings\f[R].
This is a traditional end\-of\-period bookkeeping operation also called
\[dq]closing the books\[dq]; 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.
.PP
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 \f[CR]\-\-migrate\f[R] is generally the best way to set to set
balances in new files, for now.
.SS close \-\-retain
This is like \f[CR]\-\-close\f[R] with different defaults: it prints a
\[dq]retain earnings\[dq] transaction (with \f[CR]retain:\f[R] tag),
that transfers revenue and expense balances to
\f[CR]equity:retained earnings\f[R].
.PP
This is a different kind of closing, called \[dq]retaining earnings\[dq]
or \[dq]closing the books\[dq]; it is traditionally performed by
businesses at the end of each accounting period, to consolidate revenues
and expenses into the main equity balance.
(\[dq]Revenues\[dq] and \[dq]expenses\[dq] are actually equity by
another name, kept separate temporarily for reporting purposes.)
.PP
In personal accounting you generally don\[aq]t need to do this, unless
you want the \f[CR]balancesheetequity\f[R] report to show a zero total,
demonstrating that the accounting equation (A\-L=E) is satisfied.
.SS close customisation
In all modes, the following things can be overridden:
.IP \[bu] 2
the transaction descriptions can be changed with
\f[CR]\-\-close\-desc=DESC\f[R] and \f[CR]\-\-open\-desc=DESC\f[R]
the accounts to be closed/opened, with account query arguments
.IP \[bu] 2
the account to transfer to and from can be changed with
\f[CR]\-\-close\-acct=ACCT\f[R] and \f[CR]\-\-open\-acct=ACCT\f[R]
the balancing account, with \f[CR]\-\-close\-acct=ACCT\f[R] and/or
\f[CR]\-\-open\-acct=ACCT\f[R]
.IP \[bu] 2
the accounts to be closed/opened can be changed with
\f[CR]ACCTQUERY\f[R] (account query arguments).
the transaction descriptions, with \f[CR]\-\-close\-desc=DESC\f[R] and
\f[CR]\-\-open\-desc=DESC\f[R]
.IP \[bu] 2
the closing/opening dates can be changed with \f[CR]\-e DATE\f[R] (a
report end date)
the transaction\[aq]s tag value, with a \f[CR]\-\-MODE=NEW\f[R] option
argument
.IP \[bu] 2
the closing/opening dates, with \f[CR]\-e OPENDATE\f[R]
.PP
By default just one destination/source posting will be used, with its
amount left implicit.
With \f[CR]\-\-x/\-\-explicit\f[R], the amount will be shown explicitly,
and if it involves multiple commodities, a separate posting will be
generated for each of them (similar to \f[CR]print \-x\f[R]).
By default, the closing date is yesterday, or the journal\[aq]s end
date, whichever is later; and the opening date is always one day after
the closing date.
You can change these by specifying a report end date; the closing date
will be the last day of the report period.
Eg \f[CR]\-e 2024\f[R] means \[dq]close on 2023\-12\-31, open on
2024\-01\-01\[dq].
.PP
With \f[CR]\-\-show\-costs\f[R], 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 \f[CR]\-\-x/\-\-explicit\f[R], the balancing amount will be shown
explicitly, and if it involves multiple commodities, a separate posting
will be generated for each of them (similar to \f[CR]print \-x\f[R]).
.PP
With \f[CR]\-\-interleaved\f[R], each individual transfer is shown with
source and destination postings next to each other.
This could be useful for troubleshooting.
source and destination postings next to each other (perhaps useful for
troubleshooting).
.PP
The default closing date is yesterday, or the journal\[aq]s end date,
whichever is later.
You can change this by specifying a report end date with \f[CR]\-e\f[R].
The last day of the report period will be the closing date, eg
\f[CR]\-e 2024\f[R] means \[dq]close on 2023\-12\-31\[dq].
The opening date is always the day after the closing date.
With \f[CR]\-\-show\-costs\f[R], balances\[aq] costs are also shown,
with different costs kept separate.
This may generate very large journal entries, if you have many currency
conversions or investment transactions.
\f[CR]close \-\-show\-costs\f[R] is currently the best way to view
investment lots with hledger.
(To move or dispose of lots, see the more capable
\f[CR]hledger\-move\f[R] script.)
.SS close and balance assertions
Balance assertions will be generated, verifying that the accounts have
been reset to zero (and then restored to their previous balances, if
there is an opening transaction).
.PP
\f[CR]close\f[R] adds balance assertions verifying that the accounts
have been reset to zero in a closing transaction or restored to their
previous balances in an opening transaction.
These provide useful error checking, but you can ignore them temporarily
with \f[CR]\-I\f[R], or remove them if you prefer.
.PP
You probably should avoid filtering transactions by status or realness
(\f[CR]\-C\f[R], \f[CR]\-R\f[R], \f[CR]status:\f[R]), or generating
postings (\f[CR]\-\-auto\f[R]), with this command, since the balance
assertions would depend on these.
When running \f[CR]close\f[R] you should probably avoid using
\f[CR]\-C\f[R], \f[CR]\-R\f[R], \f[CR]status:\f[R] (filtering by status
or realness) or \f[CR]\-\-auto\f[R] (generating postings), since the
generated balance assertions would then require these.
.PP
Note custom posting dates spanning the file boundary will disrupt the
balance assertions:
Transactions with multiple dates (eg posting dates) spanning the file
boundary also can disrupt the balance assertions:
.IP
.EX
2023\-12\-30 a purchase made in december, cleared in january
@ -9379,9 +9451,9 @@ balance assertions:
assets:bank:checking \-5 ; date: 2023\-01\-02
.EE
.PP
To solve that you can transfer the money to and from a temporary
account, in effect splitting the multi\-day transaction into two
single\-day transactions:
To solve this you can transfer the money to and from a temporary
account, splitting the multi\-day transaction into two single\-day
transactions:
.IP
.EX
; in 2022.journal:
@ -9394,7 +9466,8 @@ single\-day transactions:
equity:pending 5 = 0
assets:bank:checking \-5
.EE
.SS Example: retain earnings
.SS close examples
.SS Retain earnings
Record 2022\[aq]s revenues/expenses as retained earnings on
2022\-12\-31, appending the generated transaction to the journal:
.IP
@ -9402,15 +9475,14 @@ Record 2022\[aq]s revenues/expenses as retained earnings on
$ hledger close \-\-retain \-f 2022.journal \-p 2022 >> 2022.journal
.EE
.PP
Note 2022\[aq]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:
After this, to see 2022\[aq]s revenues and expenses you must exclude the
retain earnings transaction:
.IP
.EX
$ hledger \-f 2022.journal is not:desc:\[aq]retain earnings\[aq]
.EE
.SS Example: migrate balances to a new file
Close assets/liabilities/equity on 2022\-12\-31 and re\-open them on
.SS Migrate balances to a new file
Close assets/liabilities on 2022\-12\-31 and re\-open them on
2023\-01\-01:
.IP
.EX
@ -9419,74 +9491,27 @@ $ hledger close \-\-migrate \-f 2022.journal \-p 2022
# copy/paste the opening transaction to the start of 2023.journal
.EE
.PP
Now 2022\[aq]s balance sheet will show only zeroes, indicating a
balanced accounting equation.
(Unless you are using \[at]/\[at]\[at] notation \- in that case, try
adding \-\-infer\-equity.)
To see the end\-of\-year balances again, you could exclude the closing
transaction:
After this, to see 2022\[aq]s end\-of\-year balances you must exclude
the closing balances transaction:
.IP
.EX
$ hledger \-f 2022.journal bs not:desc:\[aq]closing balances\[aq]
.EE
.SS Example: excluding closing/opening transactions
When combining many files for multi\-year reports, the closing/opening
transactions cause some noise in transaction\-oriented reports like
\f[CR]print\f[R] and \f[CR]register\f[R].
You can exclude them as shown above, but \f[CR]not:desc:...\f[R] 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:
.PP
Add \f[CR]clopen:\f[R] tags to all opening/closing balances transactions
except the first, like this:
For more flexibility, it helps to tag closing and opening transactions
with eg \f[CR]start:NEWYEAR\f[R], then you can ensure correct balances
by excluding all opening/closing transactions except the first, like so:
.IP
.EX
; 2021.journal
2021\-06\-01 first opening balances
\&...
2021\-12\-31 closing balances ; clopen:2022
\&...
.EE
.IP
.EX
; 2022.journal
2022\-01\-01 opening balances ; clopen:2022
\&...
2022\-12\-31 closing balances ; clopen:2023
\&...
.EE
.IP
.EX
; 2023.journal
2023\-01\-01 opening balances ; clopen:2023
\&...
.EE
.PP
Now, assuming a combined journal like:
.IP
.EX
; all.journal
include 2021.journal
include 2022.journal
include 2023.journal
.EE
.PP
The \f[CR]clopen:\f[R] tag can exclude all but the first opening
transaction.
To show a clean multi\-year checking register:
.IP
.EX
$ hledger \-f all.journal areg checking not:tag:clopen
.EE
.PP
And the year values allow more precision.
To show 2022\[aq]s year\-end balance sheet:
.IP
.EX
$ hledger \-f all.journal bs \-e2023 not:tag:clopen=2023
$ hledger bs \-Y \-f 2021.j \-f 2022.j \-f 2023.j expr:\[aq]tag:start=2021 or not tag:start\[aq]
$ hledger bs \-Y \-f 2021.j \-f 2022.j expr:\[aq]tag:start=2021 or not tag:start\[aq]
$ hledger bs \-Y \-f 2022.j \-f 2023.j expr:\[aq]tag:start=2022 or not tag:start\[aq]
$ hledger bs \-Y \-f 2021.j expr:\[aq]tag:start=2021 or not tag:start\[aq]
$ hledger bs \-Y \-f 2022.j expr:\[aq]tag:start=2022 or not tag:start\[aq]
$ hledger bs \-Y \-f 2023.j # unclosed file, no query needed
.EE
.SS More detailed close examples
See examples/multi\-year.
.SS codes
List the codes seen in transactions, in the order parsed.
.PP
@ -9816,7 +9841,8 @@ sign flipped.
.PP
This command also supports the output destination and output format
options The output formats supported are \f[CR]txt\f[R], \f[CR]csv\f[R],
\f[CR]tsv\f[R], \f[CR]html\f[R], and \f[CR]json\f[R].
\f[CR]tsv\f[R] (\f[I]Added in 1.32\f[R]), \f[CR]html\f[R], and
\f[CR]json\f[R].
.SS notes
List the unique notes that appear in transactions.
.PP
@ -9928,9 +9954,9 @@ their symbol placement, decimal mark, and digit group marks will be made
consistent.
By default, decimal digits are shown as they are written in the journal.
.PP
With the \f[CR]\-\-round\f[R] option, \f[CR]print\f[R] will try
increasingly hard to display decimal digits according to the commodity
display styles:
With the \f[CR]\-\-round\f[R] (\f[I]Added in 1.32\f[R]) option,
\f[CR]print\f[R] will try increasingly hard to display decimal digits
according to the commodity display styles:
.IP \[bu] 2
\f[CR]\-\-round=none\f[R] show amounts with original precisions
(default)
@ -9988,8 +10014,9 @@ the program exit code will be non\-zero.
.SS print output format
This command also supports the output destination and output format
options The output formats supported are \f[CR]txt\f[R],
\f[CR]beancount\f[R], \f[CR]csv\f[R], \f[CR]tsv\f[R], \f[CR]json\f[R]
and \f[CR]sql\f[R].
\f[CR]beancount\f[R] (\f[I]Added in 1.32\f[R]), \f[CR]csv\f[R],
\f[CR]tsv\f[R] (\f[I]Added in 1.32\f[R]), \f[CR]json\f[R] and
\f[CR]sql\f[R].
.PP
The \f[CR]beancount\f[R] format tries to produce Beancount\-compatible
output, as follows:
@ -10211,7 +10238,7 @@ $ hledger reg \-w $COLUMNS,40 # use terminal width, & description width 40
.PP
This command also supports the output destination and output format
options The output formats supported are \f[CR]txt\f[R], \f[CR]csv\f[R],
\f[CR]tsv\f[R], and \f[CR]json\f[R].
\f[CR]tsv\f[R] (\f[I]Added in 1.32\f[R]), and \f[CR]json\f[R].
.SS rewrite
Print all transactions, rewriting the postings of matched transactions.
For now the only rewrite available is adding new postings, like print

1815
hledger/hledger.info
View File

File diff suppressed because it is too large Load Diff

393
hledger/hledger.txt
View File

@ -251,8 +251,6 @@ Options
--alias=OLD=NEW
rename accounts named OLD to NEW
--anon anonymize accounts and payees
--pivot FIELDNAME
use some other field or tag for the account name
@ -713,6 +711,11 @@ Output
ties/currencies. Its argument is as described in the commodity direc-
tive.
hledger will occasionally make some additional adjustments to number
formatting, eg adding a trailing decimal mark to disambiguate numbers
with digit group marks; for details, see Amount formatting, parseabil-
ity.
Colour
In terminal output, some commands can produce colour when the terminal
supports it:
@ -1284,6 +1287,12 @@ Journal
rounds to the nearest even digit). So eg 0.5 displayed with zero deci-
mal digits appears as "0".
Number format
hledger will occasionally make some additional adjustments to number
formatting, eg adding a trailing decimal mark to disambiguate numbers
with digit group marks; for details, see Amount formatting, parseabil-
ity.
Costs
After a posting amount, you can note its cost (when buying) or selling
price (when selling) in another commodity, by writing either @ UNIT-
@ -1581,27 +1590,66 @@ Journal
They are written as a word (optionally hyphenated) immediately followed
by a full colon, in a transaction or posting or account directive's
comment. (This is an exception to the usual rule that things in com-
ments are ignored.) Eg, here four different tags are recorded: one on
the checking account, two on the transaction, and one on the expenses
posting:
ments are ignored.) You can write multiple tags separated by comma,
and/or you can add more comment lines and write more tags there.
Here five different tags are recorded: one on the checking account, two
on the transaction, and two on the expenses posting:
account assets:checking ; accounttag:
2017/1/16 bought groceries ; transactiontag-1:
; transactiontag-2:
assets:checking $-1
expenses:food $1 ; postingtag:
Postings also inherit tags from their transaction and their account.
And transactions also acquire tags from their postings (and postings'
accounts). So in the example above, the expenses posting effectively
has all four tags (by inheriting from account and transaction), and the
transaction also has all four tags (by acquiring from the expenses
posting).
expenses:food $1 ; postingtag:, another-posting-tag:
You can list tag names with hledger tags [NAMEREGEX], or match by tag
name with a tag:NAMEREGEX query.
Tag inheritance
Postings also inherit tags from their transaction and their account.
And transactions also acquire tags from their postings (and postings'
accounts). So in the example above, the expenses posting effectively
has all five tags (by inheriting from the account and transaction), and
the transaction also has all five tags (by acquiring from the expenses
posting).
Tag names
Tag names are currently not very clearly specified; any sequence of
non-whitespace characters followed by a colon may work.
The following tag names are generated by hledger or have special sig-
nificance to hledger, so you may want to avoid using them yourself:
o balances -- a balance assertions transaction generated by close
o retain -- a retain earnings transaction generated by close
o start -- a opening balances, closing balances or balance assignment
transaction generated by close
o generated-transaction -- a transaction generated by --forecast
o generated-posting -- a posting generated by --auto
o modified -- a transaction which has had postings added by --auto
o type -- declares an account's type in an account declaration
o t -- stores the (user defined, single letter) type of a 15m unit of
time parsed from timedot format
Some additional tag names with an underscore prefix are used internally
and not displayed in reports (but can be matched by queries):
o _generated-transaction
o _generated-posting
o _modified
o _conversion-matched
Tag values
Tags can have a value, which is any text after the colon up until a
comma or end of line (with surrounding whitespace removed). Note this
@ -3303,13 +3351,15 @@ CSV
o When a matcher is preceded by ampersand (&) it will be AND'ed with
the previous matcher (both of them must match)
o When a matcher is preceded by an exclamation mark (!), the matcher is
negated (it may not match).
o Added in 1.32 When a matcher is preceded by an exclamation mark (!),
the matcher is negated (it may not match).
Currently there is a limitation: you can't use both & and ! on the same
line (you can't AND a negated matcher).
Match groups
Added in 1.32
Matchers can define match groups: parenthesised portions of the regular
expression which are available for reference in field assignments.
Groups are enclosed in regular parentheses (( and )) and can be nested.
@ -4125,10 +4175,11 @@ Timedot
These are the dots in "timedot". Spaces are ignored and can be
used for grouping/alignment.
o one or more letters. These are like dots but they also generate a
tag t: (short for "type") with the letter as its value, and a sepa-
rate posting for each of the values. This provides a second dimen-
sion of categorisation, viewable in reports with --pivot t.
o Added in 1.32 one or more letters. These are like dots but they
also generate a tag t: (short for "type") with the letter as its
value, and a separate posting for each of the values. This pro-
vides a second dimension of categorisation, viewable in reports
with --pivot t.
o An optional comment following a semicolon (a hledger-style posting
comment).
@ -6044,7 +6095,8 @@ PART 4: COMMANDS
--align-all flag.
This command also supports the output destination and output format op-
tions. The output formats supported are txt, csv, tsv, and json.
tions. The output formats supported are txt, csv, tsv (Added in 1.32),
and json.
aregister and posting dates
aregister always shows one line (and date and amount) per transaction.
@ -6143,9 +6195,9 @@ PART 4: COMMANDS
o commodities displayed on the same line or multiple lines (--layout)
This command supports the output destination and output format options,
with output formats txt, csv, tsv, json, and (multi-period reports
only:) html. In txt output in a colour-supporting terminal, negative
amounts are shown in red.
with output formats txt, csv, tsv (Added in 1.32), json, and (multi-pe-
riod reports only:) html. In txt output in a colour-supporting termi-
nal, negative amounts are shown in red.
The --related/-r flag shows the balance of the other postings in the
transactions of the postings which would normally be shown.
@ -6986,7 +7038,8 @@ PART 4: COMMANDS
flipped.
This command also supports the output destination and output format op-
tions The output formats supported are txt, csv, tsv, html, and json.
tions The output formats supported are txt, csv, tsv (Added in 1.32),
html, and json.
balancesheetequity
(bse)
@ -7080,7 +7133,8 @@ PART 4: COMMANDS
not:receivable, but with smarter account detection.
This command also supports the output destination and output format op-
tions The output formats supported are txt, csv, tsv, html, and json.
tions The output formats supported are txt, csv, tsv (Added in 1.32),
html, and json.
check
Check for various kinds of errors in your data.
@ -7172,124 +7226,145 @@ PART 4: COMMANDS
close
(equity)
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 file; you can append or copy them there when you are happy
with the output.
close generates several kinds of "closing" and/or "opening" transac-
tions, useful in certain situations, including migrating balances to a
new journal file, retaining earnings into equity, consolidating bal-
ances, 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.
This command is most often used when migrating balances to a new jour-
nal file, at the start of a new financial year. 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:
close currently has six modes, selected by a single mode flag:
1. With --close (or no mode flag) it prints a "closing balances" trans-
action that zeroes out all the asset, liability, and equity account
balances, by default (this requires inferred or declared 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.
close --migrate
This is the most common mode. It prints a "closing balances" transac-
tion 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 an-
other specified by --close-acct or --open-acct).
2. With --open, it prints an opposite "opening balances" transaction
that restores the same account balances, starting from zero. This
mode is similar to Ledger's equity command.
This is useful when migrating balances to a new journal file at the
start of a new year. Essentially, you run hledger close --mi-
grate=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 bal-
ances correct when you use both old and new files together, by can-
celling 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".
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 -e NEWYEAR (-e influences the
transaction date) and add the closing transaction at the end of the
old file, and the opening transaction at the start of the new file.
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. Or you can
just migrate assets and liabilities: hledger close type:AL. Most
people don't need to migrate equity. And revenues and expenses usu-
ally should not be migrated.
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.) Rev-
enues and expenses usually are not migrated to a new file directly; see
--retain below.
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.
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 incre-
menting a number (eg a year number) within the default journal's main
file name. The other modes behave similarly.
5. With --assign it prints an "opening balances" transaction that re-
stores the account balances using balance assignments. Balance as-
signments 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.
close --close
This prints just the closing balances transaction of --migrate. It is
the default behaviour if you specify no mode flag. Using the customi-
sation options below, you can move balances from any set of accounts to
a different account.
6. With --retain, it prints a "retain earnings" transaction that trans-
fers revenue and expense balances to equity:retained earnings. This
is a traditional end-of-period bookkeeping operation also called
"closing the books"; 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 --open
This prints just the opening balances transaction of --migrate. 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.
close --assign
This prints an "opening balances" transaction that restores the account
balances using balance assignments. Balance assignments work regard-
less of any previous balance, so a preceding closing balances transac-
tion is not needed.
However, omitting the closing balances transaction would unbalance eq-
uity. This is relatively harmless for personal reports, but it dis-
turbs 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.
close --retain
This is like --close with different defaults: it prints a "retain earn-
ings" transaction (with retain: tag), that transfers revenue and ex-
pense 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 pur-
poses.)
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:
o the transaction descriptions can be changed with --close-desc=DESC
and --open-desc=DESC
o the accounts to be closed/opened, with account query arguments
o the account to transfer to and from can be changed with
--close-acct=ACCT and --open-acct=ACCT
o the balancing account, with --close-acct=ACCT and/or --open-acct=ACCT
o the accounts to be closed/opened can be changed with ACCTQUERY (ac-
count query arguments).
o the transaction descriptions, with --close-desc=DESC and
--open-desc=DESC
o the closing/opening dates can be changed with -e DATE (a report end
date)
o the transaction's tag value, with a --MODE=NEW option argument
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).
o the closing/opening dates, with -e OPENDATE
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.
By default, the closing date is yesterday, or the journal's end date,
whichever is later; and the opening date is always one day after the
closing date. You can change these by specifying a report 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 gener-
ated for each of them (similar to print -x).
With --interleaved, each individual transfer is shown with source and
destination postings next to each other. This could be useful for
troubleshooting.
destination postings next to each other (perhaps useful for trou-
bleshooting).
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 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 al-
ways the day after the closing date.
With --show-costs, balances' costs are also shown, with different costs
kept separate. This may generate very large journal entries, if you
have many currency conversions or investment transactions. 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 script.)
close and balance assertions
Balance assertions will be generated, verifying that the accounts have
been reset to zero (and then restored to their previous balances, if
there is an opening transaction).
close adds balance assertions verifying that the accounts have been re-
set to zero in a closing transaction or restored to their previous bal-
ances in an opening transaction. These provide useful error checking,
but you can ignore them temporarily with -I, or remove them if you pre-
fer.
These provide useful error checking, but you can ignore them temporar-
ily with -I, or remove them if you prefer.
When running close you should probably avoid using -C, -R, status:
(filtering by status or realness) or --auto (generating postings),
since the generated balance assertions would then require these.
You probably should avoid filtering transactions by status or realness
(-C, -R, status:), or generating postings (--auto), with this command,
since the balance assertions would depend on these.
Note custom posting dates spanning the file boundary will disrupt the
balance assertions:
Transactions with multiple dates (eg posting dates) spanning the file
boundary also can disrupt the balance assertions:
2023-12-30 a purchase made in december, cleared in january
expenses:food 5
assets:bank:checking -5 ; date: 2023-01-02
To solve that you can transfer the money to and from a temporary ac-
count, in effect splitting the multi-day transaction into two sin-
gle-day transactions:
To solve this you can transfer the money to and from a temporary ac-
count, splitting the multi-day transaction into two single-day transac-
tions:
; in 2022.journal:
2022-12-30 a purchase made in december, cleared in january
@ -7301,76 +7376,43 @@ PART 4: COMMANDS
equity:pending 5 = 0
assets:bank:checking -5
Example: retain earnings
close examples
Retain earnings
Record 2022's revenues/expenses as retained earnings on 2022-12-31, ap-
pending the generated transaction to the journal:
$ hledger close --retain -f 2022.journal -p 2022 >> 2022.journal
Note 2022's income statement will now show only zeroes, because rev-
enues and expenses have been moved entirely to equity. To see them
again, you could exclude the retain transaction:
After this, to see 2022's revenues and expenses you must exclude the
retain earnings transaction:
$ hledger -f 2022.journal is not:desc:'retain earnings'
Example: migrate balances to a new file
Close assets/liabilities/equity on 2022-12-31 and re-open them on
2023-01-01:
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
# copy/paste the closing transaction to the end of 2022.journal
# copy/paste the opening transaction to the start of 2023.journal
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 the end-of-year balances
again, you could exclude the closing transaction:
After this, to see 2022's end-of-year balances you must exclude the
closing balances 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 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 transac-
tion, which could be awkward. Here is one alternative, using tags:
For more flexibility, it helps to tag closing and opening transactions
with eg start:NEWYEAR, then you can ensure correct balances by exclud-
ing all opening/closing transactions except the first, like so:
Add clopen: tags to all opening/closing balances transactions except
the first, like this:
$ 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 2023.j # unclosed file, no query needed
; 2021.journal
2021-06-01 first opening balances
...
2021-12-31 closing balances ; clopen:2022
...
; 2022.journal
2022-01-01 opening balances ; clopen:2022
...
2022-12-31 closing balances ; clopen:2023
...
; 2023.journal
2023-01-01 opening balances ; clopen:2023
...
Now, assuming a combined journal like:
; 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:
$ hledger -f all.journal areg checking not:tag:clopen
And the year values allow more precision. To show 2022's year-end bal-
ance sheet:
$ hledger -f all.journal bs -e2023 not:tag:clopen=2023
More detailed close examples
See examples/multi-year.
codes
List the codes seen in transactions, in the order parsed.
@ -7662,7 +7704,8 @@ PART 4: COMMANDS
sign flipped.
This command also supports the output destination and output format op-
tions The output formats supported are txt, csv, tsv, html, and json.
tions The output formats supported are txt, csv, tsv (Added in 1.32),
html, and json.
notes
List the unique notes that appear in transactions.
@ -7767,8 +7810,9 @@ PART 4: COMMANDS
made consistent. By default, decimal digits are shown as they are
written in the journal.
With the --round option, print will try increasingly hard to display
decimal digits according to the commodity display styles:
With the --round (Added in 1.32) option, print will try increasingly
hard to display decimal digits according to the commodity display
styles:
o --round=none show amounts with original precisions (default)
@ -7819,8 +7863,8 @@ PART 4: COMMANDS
print output format
This command also supports the output destination and output format op-
tions The output formats supported are txt, beancount, csv, tsv, json
and sql.
tions The output formats supported are txt, beancount (Added in 1.32),
csv, tsv (Added in 1.32), json and sql.
The beancount format tries to produce Beancount-compatible output, as
follows:
@ -8011,7 +8055,8 @@ PART 4: COMMANDS
$ hledger reg -w $COLUMNS,40 # use terminal width, & description width 40
This command also supports the output destination and output format op-
tions The output formats supported are txt, csv, tsv, and json.
tions The output formats supported are txt, csv, tsv (Added in 1.32),
and json.
rewrite
Print all transactions, rewriting the postings of matched transactions.