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

;doc: update embedded manuals

Browse Source
This commit is contained in:
Simon Michael 2025-11-03 06:35:05 -10:00
parent 652df1a28d
commit 8a5be241b0
11 changed files with 1927 additions and 1644 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
hledger-lib/.date.m4
View File

@ -1,2 +1,2 @@
m4_dnl Date to show in man pages. Updated by "Shake manuals" m4_dnl Date to show in man pages. Updated by "Shake manuals"
m4_define({{_monthyear_}}, {{October 2025}})m4_dnl m4_define({{_monthyear_}}, {{November 2025}})m4_dnl

2
hledger-ui/.date.m4
View File

@ -1,2 +1,2 @@
m4_dnl Date to show in man pages. Updated by "Shake manuals" m4_dnl Date to show in man pages. Updated by "Shake manuals"
m4_define({{_monthyear_}}, {{October 2025}})m4_dnl m4_define({{_monthyear_}}, {{November 2025}})m4_dnl

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

@ -1,5 +1,5 @@
.TH "HLEDGER\-UI" "1" "October 2025" "hledger-ui-1.50.99 " "hledger User Manuals" .TH "HLEDGER\-UI" "1" "November 2025" "hledger-ui-1.50.99 " "hledger User Manuals"

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

@ -460,4 +460,4 @@ LICENSE
SEE ALSO SEE ALSO
hledger(1), hledger-ui(1), hledger-web(1), ledger(1) hledger(1), hledger-ui(1), hledger-web(1), ledger(1)
hledger-ui-1.50.99 October 2025 HLEDGER-UI(1) hledger-ui-1.50.99 November 2025 HLEDGER-UI(1)

2
hledger-web/.date.m4
View File

@ -1,2 +1,2 @@
m4_dnl Date to show in man pages. Updated by "Shake manuals" m4_dnl Date to show in man pages. Updated by "Shake manuals"
m4_define({{_monthyear_}}, {{October 2025}})m4_dnl m4_define({{_monthyear_}}, {{November 2025}})m4_dnl

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

@ -1,5 +1,5 @@
.TH "HLEDGER\-WEB" "1" "October 2025" "hledger-web-1.50.99 " "hledger User Manuals" .TH "HLEDGER\-WEB" "1" "November 2025" "hledger-web-1.50.99 " "hledger User Manuals"

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

@ -480,4 +480,4 @@ LICENSE
SEE ALSO SEE ALSO
hledger(1), hledger-ui(1), hledger-web(1), ledger(1) hledger(1), hledger-ui(1), hledger-web(1), ledger(1)
hledger-web-1.50.99 October 2025 HLEDGER-WEB(1) hledger-web-1.50.99 November 2025 HLEDGER-WEB(1)

2
hledger/.date.m4
View File

@ -1,2 +1,2 @@
m4_dnl Date to show in man pages. Updated by "Shake manuals" m4_dnl Date to show in man pages. Updated by "Shake manuals"
m4_define({{_monthyear_}}, {{October 2025}})m4_dnl m4_define({{_monthyear_}}, {{November 2025}})m4_dnl

245
hledger/hledger.1
View File

@ -1,6 +1,6 @@
.\"t .\"t
.TH "HLEDGER" "1" "October 2025" "hledger-1.50.99 " "hledger User Manuals" .TH "HLEDGER" "1" "November 2025" "hledger-1.50.99 " "hledger User Manuals"
@ -779,17 +779,39 @@ special meaning to the shell and so must be escaped at least once more.
See Special characters. See Special characters.
.SS Argument files .SS Argument files
You can save a set of command line options and arguments in a file, and You can save a set of command line options and arguments in a file, and
then reuse them by writing \f[CR]\[at]FILENAME\f[R] as a command line then use them by writing \f[CR]\[at]FILE.args\f[R] as a hledger command
argument. argument.
Eg: \f[CR]hledger bal \[at]foo.args\f[R]. The \f[CR].args\f[R] file extension is conventional, but not required.
In an argument file,
.IP \[bu] 2
Each line can contain one argument, flag, or option.
.IP \[bu] 2
Blank lines or lines beginning with \f[CR]#\f[R] are ignored.
.IP \[bu] 2
An option\[aq]s flag and value should be joined by \f[CR]=\f[R].
.IP \[bu] 2
An option value or an argument may contain spaces.
Don\[aq]t use single or double quotes.
.IP \[bu] 2
And generally, use one less level of quoting/escaping than at the
command line.
Eg \f[CR]cur:\[rs]$\f[R], not \f[CR]cur:\[rs]\[rs]$\f[R] as on the
command line.
.PP .PP
An argument file\[aq]s format is more restrictive than the command line. For example:
Each line should contain just one option or argument. .IP
Don\[aq]t use spaces except inside quotes; write \f[CR]=\f[R] or nothing .EX
between a flag and its argument. # cash.args
If you use quotes, they must enclose the whole line.
For the special characters mentioned above, use one less level of assets:cash
quoting than you would at the command line. assets:charles schwab:sweep
cur:\[rs]$
\-c=$1.
.EE
.IP
.EX
$ hledger bal \[at]cash.args
.EE
.SS Config files .SS Config files
With hledger 1.40+, you can save extra command line options and With hledger 1.40+, you can save extra command line options and
arguments in a more featureful hledger config file. arguments in a more featureful hledger config file.
@ -1313,6 +1335,8 @@ $ hledger print \-c \[aq]$1.000,0\[aq]
This option can be repeated to set the display style for multiple This option can be repeated to set the display style for multiple
commodities/currencies. commodities/currencies.
Its argument is as described in the commodity directive. Its argument is as described in the commodity directive.
Note that omitting the commodity symbol will set the display style for
just the no\-symbol commodity, not all commodities.
.PP .PP
In some cases hledger will adjust number formatting to improve their In some cases hledger will adjust number formatting to improve their
parseability (such as adding trailing decimal marks when needed). parseability (such as adding trailing decimal marks when needed).
@ -3028,7 +3052,7 @@ You can list accounts and their types, for troubleshooting:
.RS 2 .RS 2
.IP .IP
.EX .EX
$ hledger accounts \-\-types [ACCTPAT] [type:TYPECODES] [\-DEPTH] $ hledger accounts \-\-types [ACCTPAT] [type:TYPECODES] [\-DEPTH] [\-\-locations]
.EE .EE
.RE .RE
.IP \[bu] 2 .IP \[bu] 2
@ -3322,6 +3346,12 @@ important.
Or, keep your decimal marks unambiguous and your entries well balanced Or, keep your decimal marks unambiguous and your entries well balanced
and precise. and precise.
.PP .PP
Omitting the commodity symbol will set the display style for just the
no\-symbol commodity, not all commodities.
.PP
Commodity styles can be overridden by the
\f[CR]\-c/\-\-commodity\-style\f[R] command line option.
.PP
(Related: #793) (Related: #793)
.SS Commodity directive syntax .SS Commodity directive syntax
A commodity directive is normally the word \f[CR]commodity\f[R] followed A commodity directive is normally the word \f[CR]commodity\f[R] followed
@ -6791,18 +6821,17 @@ dates will be Sat, Sun; periods will be Sat, Sun\-Fri
T} T}
.TE .TE
.SH Depth .SH Depth
With the \f[CR]\-\-depth NUM\f[R] option (short form: \f[CR]\-NUM\f[R]), With the \f[CR]\-\-depth NUM\f[R] option (short form, usually preferred:
reports will show accounts only to the specified depth, hiding deeper \f[CR]\-NUM\f[R]), reports will show accounts only to the specified
subaccounts. depth, hiding deeper subaccounts.
Use this when you want a summary with less detail. Use this when you want a summary with less detail.
This flag has the same effect as a \f[CR]depth:\f[R] query argument. This flag has the same effect as a \f[CR]depth:\f[R] query argument.
So all of these are equivalent: \f[CR]depth:2\f[R], So all of these are equivalent: \f[CR]depth:2\f[R],
\f[CR]\-\-depth=2\f[R], \f[CR]\-2\f[R]. \f[CR]\-\-depth=2\f[R], \f[CR]\-2\f[R].
.PP .PP
In place of a single number which limits the depth for all accounts, you You can also provide custom depths for specific accounts, by providing a
can also provide depth limits for specific accounts, by providing a \f[CR]REGEX=NUM\f[R] argument instead of just \f[CR]NUM\f[R] \f[I](since
\f[CR]REGEX=DEPTH\f[R] argument instead of just a \f[CR]DEPTH\f[R] 1.41)\f[R].
\f[I](since 1.41)\f[R].
For example, \f[CR]\-\-depth assets=2\f[R] (or For example, \f[CR]\-\-depth assets=2\f[R] (or
\f[CR]depth:assets=2\f[R]) will collapse accounts matching the regular \f[CR]depth:assets=2\f[R]) will collapse accounts matching the regular
expression \[dq]assets\[dq] to depth 2. expression \[dq]assets\[dq] to depth 2.
@ -6810,22 +6839,32 @@ So \f[CR]assets:bank:savings\f[R] would be collapsed to
\f[CR]assets:bank\f[R], but \f[CR]liabilities:bank:credit card\f[R] \f[CR]assets:bank\f[R], but \f[CR]liabilities:bank:credit card\f[R]
would not be affected. would not be affected.
.PP .PP
(If REGEX contains spaces or other special characters, enclose it in If REGEX contains spaces or other special characters, enclose it in
quotes in the usual way. quotes in the usual way.
Eg: \f[CR]\-\-depth \[aq]credit card=2\[aq]\f[R]) Eg: \f[CR]\-\-depth \[aq]credit card=2\[aq]\f[R]
.SS Combining depth options
If a command line contains multiple general depth options, the last one
wins.
(Useful for overriding a depth specified by scripts.)
.PP .PP
Specific depth options and a general depth option can be combined. Or a command may contain a combination of general and custom depth
Eg \f[CR]\-\-depth assets=3 \-\-depth expenses=2 \-\-depth 1\f[R] would options.
In this case, the most specifically (deepest) matching option wins.
Some examples:
.IP \[bu] 2
\f[CR]\-\-depth assets=3 \-\-depth expenses=2 \-\-depth 1\f[R] would
collapse accounts containing \[dq]assets\[dq] to depth 3, accounts collapse accounts containing \[dq]assets\[dq] to depth 3, accounts
containing \[dq]expenses\[dq] to depth 2, and all other accounts to containing \[dq]expenses\[dq] to depth 2, and all other accounts to
depth 1. depth 1.
.IP \[bu] 2
\f[CR]\-\-depth assets=1 \-\-depth savings=2\f[R] would collapse
\f[CR]assets:bank:savings\f[R] to depth 2 (not depth 1; because
\[dq]savings\[dq] matches a deeper part of the account name than
\[dq]assets\[dq]).
.PP .PP
If an account is matched by more than one regular expression depth Note currently, to override a custom depth option
argument, the most specific (deepest) match will be used. \f[CR]\-\-depth REGEX=NUM\f[R] with a later option, the later option
For example, with \f[CR]\-\-depth assets=1 \-\-depth savings=2\f[R], must use the same REGEX.
\f[CR]assets:bank:savings\f[R] will be collapsed to depth 2, not depth 1
(because \[dq]savings\[dq] matches a deeper part of it than
\[dq]assets\[dq] does).
.SH Queries .SH Queries
Many hledger commands accept query arguments, which restrict their scope Many hledger commands accept query arguments, which restrict their scope
and let you report on a precise subset of your data. and let you report on a precise subset of your data.
@ -12216,9 +12255,21 @@ Flags:
.EE .EE
.PP .PP
\f[CR]close\f[R] has six modes, selected by choosing one of the mode \f[CR]close\f[R] has six modes, selected by choosing one of the mode
flags (\f[CR]\-\-close\f[R] is the default). flags: \f[CR]\-\-clopen\f[R], \f[CR]\-\-close\f[R] (default),
They all do much the same operation, but with different defaults, useful \f[CR]\-\-open\f[R], \f[CR]\-\-assert\f[R], \f[CR]\-\-assign\f[R], or
in different situations. \f[CR]\-\-retain\f[R].
They are all doing the same kind of operation, but with different
defaults for different situations.
.PP
The journal entries generated by \f[CR]close\f[R] will have a
\f[CR]clopen:\f[R] tag, which is helpful when you want to exclude them
from reports.
If the main journal file name contains a number, the tag\[aq]s value
will be that base file name with the number incremented.
Eg if the journal file is 2025.journal, the tag will be
\f[CR]clopen:2026\f[R].
Or you can set the tag value by providing an argument to the mode flag.
Eg \f[CR]\-\-close=foo\f[R] or \f[CR]\-\-clopen=2025\-main\f[R].
.SS close \-\-clopen .SS close \-\-clopen
This is useful if migrating balances to a new journal file at the start This is useful if migrating balances to a new journal file at the start
of a new year. of a new year.
@ -12263,13 +12314,6 @@ AL or ALE accounts, but not the RX accounts (Revenue, Expense).
.PP .PP
Assertions will be added indicating and checking the new balances of the Assertions will be added indicating and checking the new balances of the
closed/opened accounts. closed/opened accounts.
.PP
The generated transactions will have a \f[CR]clopen:\f[R] tag.
If the main journal\[aq]s base file name contains a number (eg a year
number), the tag\[aq]s value will be that base file name with the number
incremented.
Or you can choose the tag value yourself, by using
\f[CR]\-\-clopen=TAGVAL\f[R].
.SS close \-\-close .SS close \-\-close
This prints just the closing balances transaction of This prints just the closing balances transaction of
\f[CR]\-\-clopen\f[R]. \f[CR]\-\-clopen\f[R].
@ -12321,16 +12365,16 @@ In all modes, the following things can be overridden:
.IP \[bu] 2 .IP \[bu] 2
the accounts to be closed/opened, with account query arguments the accounts to be closed/opened, with account query arguments
.IP \[bu] 2 .IP \[bu] 2
the closing/opening dates, with \f[CR]\-e OPENDATE\f[R]
.IP \[bu] 2
the balancing account, with \f[CR]\-\-close\-acct=ACCT\f[R] and/or the balancing account, with \f[CR]\-\-close\-acct=ACCT\f[R] and/or
\f[CR]\-\-open\-acct=ACCT\f[R] \f[CR]\-\-open\-acct=ACCT\f[R]
.IP \[bu] 2 .IP \[bu] 2
the transaction descriptions, with \f[CR]\-\-close\-desc=DESC\f[R] and the transaction descriptions, with \f[CR]\-\-close\-desc=DESC\f[R] and
\f[CR]\-\-open\-desc=DESC\f[R] \f[CR]\-\-open\-desc=DESC\f[R]
.IP \[bu] 2 .IP \[bu] 2
the transaction\[aq]s tag value, with a \f[CR]\-\-MODE=NEW\f[R] option the transactions\[aq] \f[CR]clopen\f[R] tag value, with a
argument \f[CR]TAGVAL\f[R] argument for the mode flag (see above).
.IP \[bu] 2
the closing/opening dates, with \f[CR]\-e OPENDATE\f[R]
.PP .PP
By default, the closing date is yesterday, or the journal\[aq]s end 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 date, whichever is later; and the opening date is always one day after
@ -12665,8 +12709,6 @@ This prevents wrong conversions caused by typos.
.IP \[bu] 2 .IP \[bu] 2
\f[B]commodities\f[R] \- all commodity symbols used must be declared. \f[B]commodities\f[R] \- all commodity symbols used must be declared.
This guards against mistyping or omitting commodity symbols. This guards against mistyping or omitting commodity symbols.
Declaring commodities also sets their precision for display and
transaction balancing.
.IP \[bu] 2 .IP \[bu] 2
\f[B]accounts\f[R] \- all account names used must be declared. \f[B]accounts\f[R] \- all account names used must be declared.
This prevents the use of mis\-spelled or outdated account names. This prevents the use of mis\-spelled or outdated account names.
@ -12850,7 +12892,7 @@ $ hledger test \-\- \-h # show tasty\[aq]s options
.PP .PP
.SH PART 5: COMMON TASKS .SH PART 5: COMMON TASKS
Here are some quick examples of how to do some basic tasks with hledger. Here are some quick examples of how to do some basic tasks with hledger.
.SH Getting help .SS Getting help
Here\[aq]s how to list commands and view options and command docs: Here\[aq]s how to list commands and view options and command docs:
.IP .IP
.EX .EX
@ -12873,7 +12915,7 @@ To view manuals and introductory docs on the web, visit
https://hledger.org. https://hledger.org.
Chat and mail list support and discussion archives can be found at Chat and mail list support and discussion archives can be found at
https://hledger.org/support. https://hledger.org/support.
.SH Constructing command lines .SS Constructing command lines
hledger has a flexible command line interface. hledger has a flexible command line interface.
We strive to keep it simple and ergonomic, but if you run into one of We strive to keep it simple and ergonomic, but if you run into one of
the sharp edges described in OPTIONS, here are some tips that might the sharp edges described in OPTIONS, here are some tips that might
@ -12892,7 +12934,7 @@ metacharacters from the shell
.IP \[bu] 2 .IP \[bu] 2
to see how a misbehaving command line is being parsed, add to see how a misbehaving command line is being parsed, add
\f[CR]\-\-debug=2\f[R]. \f[CR]\-\-debug=2\f[R].
.SH Starting a journal file .SS Starting a journal file
hledger looks for your accounting data in a journal file, hledger looks for your accounting data in a journal file,
\f[CR]$HOME/.hledger.journal\f[R] by default: \f[CR]$HOME/.hledger.journal\f[R] by default:
.IP .IP
@ -12930,48 +12972,97 @@ Accounts : 0 (depth 0)
Commodities : 0 () Commodities : 0 ()
Market prices : 0 () Market prices : 0 ()
.EE .EE
.SH Setting LEDGER_FILE .SS Setting LEDGER_FILE
How to set \f[CR]LEDGER_FILE\f[R] permanently depends on your setup: .SS Set LEDGER_FILE on unix
.PP It depends on your shell, but running these commands in the terminal
On unix and mac, running these commands in the terminal will work for will work for many people; adapt if needed:
many people; adapt as needed:
.IP .IP
.EX .EX
$ echo \[aq]export LEDGER_FILE=\[ti]/finance/2023.journal\[aq] >> \[ti]/.profile $ echo \[aq]export LEDGER_FILE=\[ti]/finance/my.journal\[aq] >> \[ti]/.profile
$ source \[ti]/.profile $ source \[ti]/.profile
.EE .EE
.PP .PP
When correctly configured, in a new terminal window When correctly configured:
\f[CR]env | grep LEDGER_FILE\f[R] will show your file, and so will .IP \[bu] 2
\f[CR]env | grep LEDGER_FILE\f[R] will show your new setting
.IP \[bu] 2
and so should \f[CR]hledger setup\f[R] and (once the file exists)
\f[CR]hledger files\f[R]. \f[CR]hledger files\f[R].
.SS Set LEDGER_FILE on mac
In a terminal window, follow the unix procedure above.
.PP .PP
On mac, this additional step might be helpful for GUI applications (like Also, this optional step may be helpful for GUI applications:
Emacs started from the dock): add an entry to .IP "1." 3
\f[CR]\[ti]/.MacOSX/environment.plist\f[R] like Add an entry to \f[CR]\[ti]/.MacOSX/environment.plist\f[R] like
.RS 4
.IP .IP
.EX .EX
{ {
\[dq]LEDGER_FILE\[dq] : \[dq]\[ti]/finance/2023.journal\[dq] \[dq]LEDGER_FILE\[dq] : \[dq]\[ti]/finance/my.journal\[dq]
} }
.EE .EE
.RE
.IP "2." 3
Run \f[CR]killall Dock\f[R] in a terminal window (or restart the
machine), to complete the change.
.PP .PP
and then run \f[CR]killall Dock\f[R] in a terminal window (or restart When correctly configured for GUI applications:
the machine). .IP \[bu] 2
apps started from the dock or a spotlight search, such as a GUI Emacs,
will be aware of the new LEDGER_FILE setting.
.SS Set LEDGER_FILE on Windows
Using the gui is easiest:
.IP "1." 3
In task bar, search for \f[CR]environment variables\f[R], and choose
\[dq]Edit environment variables for your account\[dq].
.IP "2." 3
Create or change a \f[CR]LEDGER_FILE\f[R] setting in the User variables
pane.
A typical value would be
\f[CR]C:\[rs]Users\[rs]USERNAME\[rs]finance\[rs]my.journal\f[R].
.IP "3." 3
Click OK to complete the change.
.IP "4." 3
And open a new powershell window.
(Existing windows won\[aq]t see the change.)
.PP .PP
On Windows, see https://www.java.com/en/download/help/path.html, or try Or at the command line, you can do it this way:
running these commands in a powershell window (let us know if it .IP "1." 3
persists across a reboot, and if you need to be an Administrator): In a powershell window, run
.IP \f[CR][Environment]::SetEnvironmentVariable(\[dq]LEDGER_FILE\[dq], \[dq]C:\[rs]User\[rs]USERNAME\[rs]finance\[rs]my.journal\[dq], [System.EnvironmentVariableTarget]::User)\f[R]
.EX .IP "2." 3
> CD And open a new powershell window.
> MKDIR finance (Existing windows won\[aq]t see the change.)
> SETX LEDGER_FILE \[dq]C:\[rs]Users\[rs]USERNAME\[rs]finance\[rs]2023.journal\[dq]
.EE
.PP .PP
When correctly configured, in a new terminal window Warning, doing this from the Windows command line can be tricky; other
\f[CR]$env:LEDGER_FILE\f[R] will show the file path, and so will methods you may find online:
.IP \[bu] 2
may not affect the current window
.IP \[bu] 2
may not be persistent
.IP \[bu] 2
may not work unless you are an administrator
.IP \[bu] 2
may limit values to 1024 characters
.IP \[bu] 2
may break dynamic references to other variables
.IP \[bu] 2
may require a new\-enough version of powershell
.IP \[bu] 2
or may be intended for the older command window.
.IP \[bu] 2
If you still have trouble, see eg Setting Windows PowerShell environment
variables or Adding path permanently to windows using powershell
doesn\[aq]t appear to work.
.PP
When correctly configured:
.IP \[bu] 2
in a new powershell window, \f[CR]$env:LEDGER_FILE\f[R] will show your
new setting
.IP \[bu] 2
and so should \f[CR]hledger setup\f[R] and (once the file exists)
\f[CR]hledger files\f[R]. \f[CR]hledger files\f[R].
.SH Setting opening balances .SS Setting opening balances
Pick a starting date for which you can look up the balances of some Pick a starting date for which you can look up the balances of some
real\-world assets (bank accounts, wallet..) real\-world assets (bank accounts, wallet..)
and liabilities (credit cards..). and liabilities (credit cards..).
@ -13060,7 +13151,7 @@ Eg:
.EX .EX
$ git commit \-m \[aq]initial balances\[aq] 2023.journal $ git commit \-m \[aq]initial balances\[aq] 2023.journal
.EE .EE
.SH Recording transactions .SS Recording transactions
As you spend or receive money, you can record these transactions using As you spend or receive money, you can record these transactions using
one of the methods above (text editor, hledger add) or by using the one of the methods above (text editor, hledger add) or by using the
hledger\-iadd or hledger\-web add\-ons, or by using the import command hledger\-iadd or hledger\-web add\-ons, or by using the import command
@ -13082,7 +13173,7 @@ hledger.org for more ideas:
income:salary income:salary
assets:bank:checking $1000 assets:bank:checking $1000
.EE .EE
.SH Reconciling .SS Reconciling
Periodically you should reconcile \- compare your hledger\-reported Periodically you should reconcile \- compare your hledger\-reported
balances against external sources of truth, like bank statements or your balances against external sources of truth, like bank statements or your
bank\[aq]s website \- to be sure that your ledger accurately represents bank\[aq]s website \- to be sure that your ledger accurately represents
@ -13143,7 +13234,7 @@ commit:
.EX .EX
$ git commit \-m \[aq]txns\[aq] 2023.journal $ git commit \-m \[aq]txns\[aq] 2023.journal
.EE .EE
.SH Reporting .SS Reporting
Here are some basic reports. Here are some basic reports.
.PP .PP
Show all transactions: Show all transactions:
@ -13301,7 +13392,7 @@ $ hledger activity \-W
2023\-01\-06 **** 2023\-01\-06 ****
2023\-01\-13 **** 2023\-01\-13 ****
.EE .EE
.SH Migrating to a new file .SS Migrating to a new file
At the end of the year, you may want to continue your journal in a new At the end of the year, you may want to continue your journal in a new
file, so that old transactions don\[aq]t slow down or clutter your file, so that old transactions don\[aq]t slow down or clutter your
reports, and to help ensure the integrity of your accounting history. reports, and to help ensure the integrity of your accounting history.

1126
hledger/hledger.info
View File

File diff suppressed because it is too large Load Diff

236
hledger/hledger.txt
View File

@ -605,15 +605,32 @@ Options
Argument files Argument files
You can save a set of command line options and arguments in a file, and You can save a set of command line options and arguments in a file, and
then reuse them by writing @FILENAME as a command line argument. Eg: then use them by writing @FILE.args as a hledger command argument. The
hledger bal @foo.args. .args file extension is conventional, but not required. In an argument
file,
An argument file's format is more restrictive than the command line. o Each line can contain one argument, flag, or option.
Each line should contain just one option or argument. Don't use spaces
except inside quotes; write = or nothing between a flag and its argu- o Blank lines or lines beginning with # are ignored.
ment. If you use quotes, they must enclose the whole line. For the
special characters mentioned above, use one less level of quoting than o An option's flag and value should be joined by =.
you would at the command line.
o An option value or an argument may contain spaces. Don't use single
or double quotes.
o And generally, use one less level of quoting/escaping than at the
command line. Eg cur:\$, not cur:\\$ as on the command line.
For example:
# cash.args
assets:cash
assets:charles schwab:sweep
cur:\$
-c=$1.
$ hledger bal @cash.args
Config files Config files
With hledger 1.40+, you can save extra command line options and argu- With hledger 1.40+, you can save extra command line options and argu-
@ -964,7 +981,8 @@ Output
This option can be repeated to set the display style for multiple com- This option can be repeated to set the display style for multiple com-
modities/currencies. Its argument is as described in the commodity di- modities/currencies. Its argument is as described in the commodity di-
rective. rective. Note that omitting the commodity symbol will set the display
style for just the no-symbol commodity, not all commodities.
In some cases hledger will adjust number formatting to improve their In some cases hledger will adjust number formatting to improve their
parseability (such as adding trailing decimal marks when needed). parseability (such as adding trailing decimal marks when needed).
@ -2235,7 +2253,7 @@ Journal
o You can list accounts and their types, for troubleshooting: o You can list accounts and their types, for troubleshooting:
$ hledger accounts --types [ACCTPAT] [type:TYPECODES] [-DEPTH] $ hledger accounts --types [ACCTPAT] [type:TYPECODES] [-DEPTH] [--locations]
o It's a good idea to declare at least one account for each account o It's a good idea to declare at least one account for each account
type. Having some types declared and some inferred can disrupt cer- type. Having some types declared and some inferred can disrupt cer-
@ -2486,6 +2504,12 @@ Journal
your decimal marks unambiguous and your entries well balanced and pre- your decimal marks unambiguous and your entries well balanced and pre-
cise. cise.
Omitting the commodity symbol will set the display style for just the
no-symbol commodity, not all commodities.
Commodity styles can be overridden by the -c/--commodity-style command
line option.
(Related: #793) (Related: #793)
Commodity directive syntax Commodity directive syntax
@ -5272,33 +5296,40 @@ Time periods
day" day"
Depth Depth
With the --depth NUM option (short form: -NUM), reports will show ac- With the --depth NUM option (short form, usually preferred: -NUM), re-
counts only to the specified depth, hiding deeper subaccounts. Use ports will show accounts only to the specified depth, hiding deeper
this when you want a summary with less detail. This flag has the same subaccounts. Use this when you want a summary with less detail. This
effect as a depth: query argument. So all of these are equivalent: flag has the same effect as a depth: query argument. So all of these
depth:2, --depth=2, -2. are equivalent: depth:2, --depth=2, -2.
In place of a single number which limits the depth for all accounts, You can also provide custom depths for specific accounts, by providing
you can also provide depth limits for specific accounts, by providing a a REGEX=NUM argument instead of just NUM (since 1.41). For example,
REGEX=DEPTH argument instead of just a DEPTH (since 1.41). For exam- --depth assets=2 (or depth:assets=2) will collapse accounts matching
ple, --depth assets=2 (or depth:assets=2) will collapse accounts match- the regular expression "assets" to depth 2. So assets:bank:savings
ing the regular expression "assets" to depth 2. So assets:bank:savings
would be collapsed to assets:bank, but liabilities:bank:credit card would be collapsed to assets:bank, but liabilities:bank:credit card
would not be affected. would not be affected.
(If REGEX contains spaces or other special characters, enclose it in If REGEX contains spaces or other special characters, enclose it in
quotes in the usual way. Eg: --depth 'credit card=2') quotes in the usual way. Eg: --depth 'credit card=2'
Specific depth options and a general depth option can be combined. Eg Combining depth options
--depth assets=3 --depth expenses=2 --depth 1 would collapse accounts If a command line contains multiple general depth options, the last one
containing "assets" to depth 3, accounts containing "expenses" to depth wins. (Useful for overriding a depth specified by scripts.)
2, and all other accounts to depth 1.
If an account is matched by more than one regular expression depth ar- Or a command may contain a combination of general and custom depth op-
gument, the most specific (deepest) match will be used. For example, tions. In this case, the most specifically (deepest) matching option
with --depth assets=1 --depth savings=2, assets:bank:savings will be wins. Some examples:
collapsed to depth 2, not depth 1 (because "savings" matches a deeper
part of it than "assets" does). o --depth assets=3 --depth expenses=2 --depth 1 would collapse accounts
containing "assets" to depth 3, accounts containing "expenses" to
depth 2, and all other accounts to depth 1.
o --depth assets=1 --depth savings=2 would collapse assets:bank:savings
to depth 2 (not depth 1; because "savings" matches a deeper part of
the account name than "assets").
Note currently, to override a custom depth option --depth REGEX=NUM
with a later option, the later option must use the same REGEX.
Queries Queries
Many hledger commands accept query arguments, which restrict their Many hledger commands accept query arguments, which restrict their
@ -9706,9 +9737,18 @@ Data generation commands
all - also round cost amounts to precision all - also round cost amounts to precision
(can unbalance transactions) (can unbalance transactions)
close has six modes, selected by choosing one of the mode flags close has six modes, selected by choosing one of the mode flags:
(--close is the default). They all do much the same operation, but --clopen, --close (default), --open, --assert, --assign, or --retain.
with different defaults, useful in different situations. They are all doing the same kind of operation, but with different de-
faults for different situations.
The journal entries generated by close will have a clopen: tag, which
is helpful when you want to exclude them from reports. If the main
journal file name contains a number, the tag's value will be that base
file name with the number incremented. Eg if the journal file is
2025.journal, the tag will be clopen:2026. Or you can set the tag
value by providing an argument to the mode flag. Eg --close=foo or
--clopen=2025-main.
close --clopen close --clopen
This is useful if migrating balances to a new journal file at the start This is useful if migrating balances to a new journal file at the start
@ -9746,11 +9786,6 @@ Data generation commands
Assertions will be added indicating and checking the new balances of Assertions will be added indicating and checking the new balances of
the closed/opened accounts. the closed/opened accounts.
The generated transactions will have a clopen: tag. If the main jour-
nal's base file name contains a number (eg a year number), the tag's
value will be that base file name with the number incremented. Or you
can choose the tag value yourself, by using --clopen=TAGVAL.
close --close close --close
This prints just the closing balances transaction of --clopen. It is This prints just the closing balances transaction of --clopen. It is
the default if you don't specify a mode. the default if you don't specify a mode.
@ -9801,14 +9836,15 @@ Data generation commands
o the accounts to be closed/opened, with account query arguments o the accounts to be closed/opened, with account query arguments
o the closing/opening dates, with -e OPENDATE
o the balancing account, with --close-acct=ACCT and/or --open-acct=ACCT o the balancing account, with --close-acct=ACCT and/or --open-acct=ACCT
o the transaction descriptions, with --close-desc=DESC and o the transaction descriptions, with --close-desc=DESC and
--open-desc=DESC --open-desc=DESC
o the transaction's tag value, with a --MODE=NEW option argument o the transactions' clopen tag value, with a TAGVAL argument for the
mode flag (see above).
o the closing/opening dates, with -e OPENDATE
By default, the closing date is yesterday, or the journal's end date, 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 whichever is later; and the opening date is always one day after the
@ -10094,9 +10130,7 @@ Maintenance commands
wrong conversions caused by typos. wrong conversions caused by typos.
o commodities - all commodity symbols used must be declared. This o commodities - all commodity symbols used must be declared. This
guards against mistyping or omitting commodity symbols. Declaring guards against mistyping or omitting commodity symbols.
commodities also sets their precision for display and transaction
balancing.
o accounts - all account names used must be declared. This prevents o accounts - all account names used must be declared. This prevents
the use of mis-spelled or outdated account names. the use of mis-spelled or outdated account names.
@ -10266,7 +10300,7 @@ PART 5: COMMON TASKS
Here are some quick examples of how to do some basic tasks with Here are some quick examples of how to do some basic tasks with
hledger. hledger.
Getting help Getting help
Here's how to list commands and view options and command docs: Here's how to list commands and view options and command docs:
$ hledger # show available commands $ hledger # show available commands
@ -10284,7 +10318,7 @@ Getting help
https://hledger.org. Chat and mail list support and discussion https://hledger.org. Chat and mail list support and discussion
archives can be found at https://hledger.org/support. archives can be found at https://hledger.org/support.
Constructing command lines Constructing command lines
hledger has a flexible command line interface. We strive to keep it hledger has a flexible command line interface. We strive to keep it
simple and ergonomic, but if you run into one of the sharp edges de- simple and ergonomic, but if you run into one of the sharp edges de-
scribed in OPTIONS, here are some tips that might help: scribed in OPTIONS, here are some tips that might help:
@ -10302,7 +10336,7 @@ Constructing command lines
o to see how a misbehaving command line is being parsed, add --debug=2. o to see how a misbehaving command line is being parsed, add --debug=2.
Starting a journal file Starting a journal file
hledger looks for your accounting data in a journal file, hledger looks for your accounting data in a journal file,
$HOME/.hledger.journal by default: $HOME/.hledger.journal by default:
@ -10336,41 +10370,91 @@ Starting a journal file
Commodities : 0 () Commodities : 0 ()
Market prices : 0 () Market prices : 0 ()
Setting LEDGER_FILE Setting LEDGER_FILE
How to set LEDGER_FILE permanently depends on your setup: Set LEDGER_FILE on unix
It depends on your shell, but running these commands in the terminal
will work for many people; adapt if needed:
On unix and mac, running these commands in the terminal will work for $ echo 'export LEDGER_FILE=~/finance/my.journal' >> ~/.profile
many people; adapt as needed:
$ echo 'export LEDGER_FILE=~/finance/2023.journal' >> ~/.profile
$ source ~/.profile $ source ~/.profile
When correctly configured, in a new terminal window env | grep When correctly configured:
LEDGER_FILE will show your file, and so will hledger files.
On mac, this additional step might be helpful for GUI applications o env | grep LEDGER_FILE will show your new setting
(like Emacs started from the dock): add an entry to ~/.MacOSX/environ-
ment.plist like o and so should hledger setup and (once the file exists) hledger files.
Set LEDGER_FILE on mac
In a terminal window, follow the unix procedure above.
Also, this optional step may be helpful for GUI applications:
1. Add an entry to ~/.MacOSX/environment.plist like
{ {
"LEDGER_FILE" : "~/finance/2023.journal" "LEDGER_FILE" : "~/finance/my.journal"
} }
and then run killall Dock in a terminal window (or restart the ma- 2. Run killall Dock in a terminal window (or restart the machine), to
chine). complete the change.
On Windows, see https://www.java.com/en/download/help/path.html, or try When correctly configured for GUI applications:
running these commands in a powershell window (let us know if it per-
sists across a reboot, and if you need to be an Administrator):
> CD o apps started from the dock or a spotlight search, such as a GUI
> MKDIR finance Emacs, will be aware of the new LEDGER_FILE setting.
> SETX LEDGER_FILE "C:\Users\USERNAME\finance\2023.journal"
When correctly configured, in a new terminal window $env:LEDGER_FILE Set LEDGER_FILE on Windows
will show the file path, and so will hledger files. Using the gui is easiest:
Setting opening balances 1. In task bar, search for environment variables, and choose "Edit en-
vironment variables for your account".
2. Create or change a LEDGER_FILE setting in the User variables pane.
A typical value would be C:\Users\USERNAME\finance\my.journal.
3. Click OK to complete the change.
4. And open a new powershell window. (Existing windows won't see the
change.)
Or at the command line, you can do it this way:
1. In a powershell window, run [Environment]::SetEnvironmentVari-
able("LEDGER_FILE", "C:\User\USERNAME\finance\my.journal", [Sys-
tem.EnvironmentVariableTarget]::User)
2. And open a new powershell window. (Existing windows won't see the
change.)
Warning, doing this from the Windows command line can be tricky; other
methods you may find online:
o may not affect the current window
o may not be persistent
o may not work unless you are an administrator
o may limit values to 1024 characters
o may break dynamic references to other variables
o may require a new-enough version of powershell
o or may be intended for the older command window.
o If you still have trouble, see eg Setting Windows PowerShell environ-
ment variables or Adding path permanently to windows using powershell
doesn't appear to work.
When correctly configured:
o in a new powershell window, $env:LEDGER_FILE will show your new set-
ting
o and so should hledger setup and (once the file exists) hledger files.
Setting opening balances
Pick a starting date for which you can look up the balances of some Pick a starting date for which you can look up the balances of some
real-world assets (bank accounts, wallet..) and liabilities (credit real-world assets (bank accounts, wallet..) and liabilities (credit
cards..). cards..).
@ -10448,7 +10532,7 @@ Setting opening balances
$ git commit -m 'initial balances' 2023.journal $ git commit -m 'initial balances' 2023.journal
Recording transactions Recording transactions
As you spend or receive money, you can record these transactions using As you spend or receive money, you can record these transactions using
one of the methods above (text editor, hledger add) or by using the one of the methods above (text editor, hledger add) or by using the
hledger-iadd or hledger-web add-ons, or by using the import command to hledger-iadd or hledger-web add-ons, or by using the import command to
@ -10469,7 +10553,7 @@ Recording transactions
income:salary income:salary
assets:bank:checking $1000 assets:bank:checking $1000
Reconciling Reconciling
Periodically you should reconcile - compare your hledger-reported bal- Periodically you should reconcile - compare your hledger-reported bal-
ances against external sources of truth, like bank statements or your ances against external sources of truth, like bank statements or your
bank's website - to be sure that your ledger accurately represents the bank's website - to be sure that your ledger accurately represents the
@ -10519,7 +10603,7 @@ Reconciling
$ git commit -m 'txns' 2023.journal $ git commit -m 'txns' 2023.journal
Reporting Reporting
Here are some basic reports. Here are some basic reports.
Show all transactions: Show all transactions:
@ -10662,7 +10746,7 @@ Reporting
2023-01-06 **** 2023-01-06 ****
2023-01-13 **** 2023-01-13 ****
Migrating to a new file Migrating to a new file
At the end of the year, you may want to continue your journal in a new At the end of the year, you may want to continue your journal in a new
file, so that old transactions don't slow down or clutter your reports, file, so that old transactions don't slow down or clutter your reports,
and to help ensure the integrity of your accounting history. See the and to help ensure the integrity of your accounting history. See the
@ -10739,4 +10823,4 @@ LICENSE
SEE ALSO SEE ALSO
hledger(1), hledger-ui(1), hledger-web(1), ledger(1) hledger(1), hledger-ui(1), hledger-web(1), ledger(1)
hledger-1.50.99 October 2025 HLEDGER(1) hledger-1.50.99 November 2025 HLEDGER(1)