From 8a5be241b03c9899973c11be7713c4a41a5f1eef Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Mon, 3 Nov 2025 06:35:05 -1000 Subject: [PATCH] ;doc: update embedded manuals --- hledger-lib/.date.m4 | 2 +- hledger-ui/.date.m4 | 2 +- hledger-ui/hledger-ui.1 | 2 +- hledger-ui/hledger-ui.txt | 2 +- hledger-web/.date.m4 | 2 +- hledger-web/hledger-web.1 | 2 +- hledger-web/hledger-web.txt | 2 +- hledger/.date.m4 | 2 +- hledger/hledger.1 | 245 ++-- hledger/hledger.info | 1126 ++++++++++-------- hledger/hledger.txt | 2184 ++++++++++++++++++----------------- 11 files changed, 1927 insertions(+), 1644 deletions(-) diff --git a/hledger-lib/.date.m4 b/hledger-lib/.date.m4 index 29cdeb0d5..c366e46f4 100644 --- a/hledger-lib/.date.m4 +++ b/hledger-lib/.date.m4 @@ -1,2 +1,2 @@ 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 diff --git a/hledger-ui/.date.m4 b/hledger-ui/.date.m4 index 29cdeb0d5..c366e46f4 100644 --- a/hledger-ui/.date.m4 +++ b/hledger-ui/.date.m4 @@ -1,2 +1,2 @@ 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 diff --git a/hledger-ui/hledger-ui.1 b/hledger-ui/hledger-ui.1 index 974e3cecf..8f8db4257 100644 --- a/hledger-ui/hledger-ui.1 +++ b/hledger-ui/hledger-ui.1 @@ -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" diff --git a/hledger-ui/hledger-ui.txt b/hledger-ui/hledger-ui.txt index adc551948..bd9f2dc35 100644 --- a/hledger-ui/hledger-ui.txt +++ b/hledger-ui/hledger-ui.txt @@ -460,4 +460,4 @@ LICENSE SEE ALSO 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) diff --git a/hledger-web/.date.m4 b/hledger-web/.date.m4 index 29cdeb0d5..c366e46f4 100644 --- a/hledger-web/.date.m4 +++ b/hledger-web/.date.m4 @@ -1,2 +1,2 @@ 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 diff --git a/hledger-web/hledger-web.1 b/hledger-web/hledger-web.1 index 332183b4b..e8c240aeb 100644 --- a/hledger-web/hledger-web.1 +++ b/hledger-web/hledger-web.1 @@ -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" diff --git a/hledger-web/hledger-web.txt b/hledger-web/hledger-web.txt index 3dbd6baa2..aaa843186 100644 --- a/hledger-web/hledger-web.txt +++ b/hledger-web/hledger-web.txt @@ -480,4 +480,4 @@ LICENSE SEE ALSO 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) diff --git a/hledger/.date.m4 b/hledger/.date.m4 index 29cdeb0d5..c366e46f4 100644 --- a/hledger/.date.m4 +++ b/hledger/.date.m4 @@ -1,2 +1,2 @@ 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 diff --git a/hledger/hledger.1 b/hledger/hledger.1 index 8a0d85354..a7f99b9d8 100644 --- a/hledger/hledger.1 +++ b/hledger/hledger.1 @@ -1,6 +1,6 @@ .\"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. .SS Argument files 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. -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 -An argument file\[aq]s format is more restrictive than the command line. -Each line should contain just one option or argument. -Don\[aq]t use spaces except inside quotes; write \f[CR]=\f[R] or nothing -between a flag and its argument. -If you use quotes, they must enclose the whole line. -For the special characters mentioned above, use one less level of -quoting than you would at the command line. +For example: +.IP +.EX +# cash.args + +assets:cash +assets:charles schwab:sweep +cur:\[rs]$ +\-c=$1. +.EE +.IP +.EX +$ hledger bal \[at]cash.args +.EE .SS Config files With hledger 1.40+, you can save extra command line options and 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 commodities/currencies. 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 In some cases hledger will adjust number formatting to improve their parseability (such as adding trailing decimal marks when needed). @@ -3028,7 +3052,7 @@ You can list accounts and their types, for troubleshooting: .RS 2 .IP .EX -$ hledger accounts \-\-types [ACCTPAT] [type:TYPECODES] [\-DEPTH] +$ hledger accounts \-\-types [ACCTPAT] [type:TYPECODES] [\-DEPTH] [\-\-locations] .EE .RE .IP \[bu] 2 @@ -3322,6 +3346,12 @@ important. Or, keep your decimal marks unambiguous and your entries well balanced and precise. .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) .SS Commodity directive syntax 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} .TE .SH Depth -With the \f[CR]\-\-depth NUM\f[R] option (short form: \f[CR]\-NUM\f[R]), -reports will show accounts only to the specified depth, hiding deeper -subaccounts. +With the \f[CR]\-\-depth NUM\f[R] option (short form, usually preferred: +\f[CR]\-NUM\f[R]), reports will show accounts only to the specified +depth, hiding deeper subaccounts. 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. So all of these are equivalent: \f[CR]depth:2\f[R], \f[CR]\-\-depth=2\f[R], \f[CR]\-2\f[R]. .PP -In place of a single number which limits the depth for all accounts, you -can also provide depth limits for specific accounts, by providing a -\f[CR]REGEX=DEPTH\f[R] argument instead of just a \f[CR]DEPTH\f[R] -\f[I](since 1.41)\f[R]. +You can also provide custom depths for specific accounts, by providing a +\f[CR]REGEX=NUM\f[R] argument instead of just \f[CR]NUM\f[R] \f[I](since +1.41)\f[R]. For example, \f[CR]\-\-depth assets=2\f[R] (or \f[CR]depth:assets=2\f[R]) will collapse accounts matching the regular 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] would not be affected. .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. -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 -Specific depth options and a general depth option can be combined. -Eg \f[CR]\-\-depth assets=3 \-\-depth expenses=2 \-\-depth 1\f[R] would +Or a command may contain a combination of general and custom depth +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 containing \[dq]expenses\[dq] to depth 2, and all other accounts to 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 -If an account is matched by more than one regular expression depth -argument, the most specific (deepest) match will be used. -For example, with \f[CR]\-\-depth assets=1 \-\-depth savings=2\f[R], -\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). +Note currently, to override a custom depth option +\f[CR]\-\-depth REGEX=NUM\f[R] with a later option, the later option +must use the same REGEX. .SH Queries Many hledger commands accept query arguments, which restrict their scope and let you report on a precise subset of your data. @@ -12216,9 +12255,21 @@ Flags: .EE .PP \f[CR]close\f[R] has six modes, selected by choosing one of the mode -flags (\f[CR]\-\-close\f[R] is the default). -They all do much the same operation, but with different defaults, useful -in different situations. +flags: \f[CR]\-\-clopen\f[R], \f[CR]\-\-close\f[R] (default), +\f[CR]\-\-open\f[R], \f[CR]\-\-assert\f[R], \f[CR]\-\-assign\f[R], or +\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 This is useful if migrating balances to a new journal file at the start of a new year. @@ -12263,13 +12314,6 @@ AL or ALE accounts, but not the RX accounts (Revenue, Expense). .PP Assertions will be added indicating and checking the new balances of the 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 This prints just the closing balances transaction of \f[CR]\-\-clopen\f[R]. @@ -12321,16 +12365,16 @@ In all modes, the following things can be overridden: .IP \[bu] 2 the accounts to be closed/opened, with account query arguments .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 \f[CR]\-\-open\-acct=ACCT\f[R] .IP \[bu] 2 the transaction descriptions, with \f[CR]\-\-close\-desc=DESC\f[R] and \f[CR]\-\-open\-desc=DESC\f[R] .IP \[bu] 2 -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] +the transactions\[aq] \f[CR]clopen\f[R] tag value, with a +\f[CR]TAGVAL\f[R] argument for the mode flag (see above). .PP 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 @@ -12665,8 +12709,6 @@ This prevents wrong conversions caused by typos. .IP \[bu] 2 \f[B]commodities\f[R] \- all commodity symbols used must be declared. This guards against mistyping or omitting commodity symbols. -Declaring commodities also sets their precision for display and -transaction balancing. .IP \[bu] 2 \f[B]accounts\f[R] \- all account names used must be declared. This prevents the use of mis\-spelled or outdated account names. @@ -12850,7 +12892,7 @@ $ hledger test \-\- \-h # show tasty\[aq]s options .PP .SH PART 5: COMMON TASKS 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: .IP .EX @@ -12873,7 +12915,7 @@ To view manuals and introductory docs on the web, visit https://hledger.org. Chat and mail list support and discussion archives can be found at https://hledger.org/support. -.SH Constructing command lines +.SS Constructing command lines 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 described in OPTIONS, here are some tips that might @@ -12892,7 +12934,7 @@ metacharacters from the shell .IP \[bu] 2 to see how a misbehaving command line is being parsed, add \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, \f[CR]$HOME/.hledger.journal\f[R] by default: .IP @@ -12930,48 +12972,97 @@ Accounts : 0 (depth 0) Commodities : 0 () Market prices : 0 () .EE -.SH Setting LEDGER_FILE -How to set \f[CR]LEDGER_FILE\f[R] permanently depends on your setup: -.PP -On unix and mac, running these commands in the terminal will work for -many people; adapt as needed: +.SS Setting LEDGER_FILE +.SS 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: .IP .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 .EE .PP -When correctly configured, in a new terminal window -\f[CR]env | grep LEDGER_FILE\f[R] will show your file, and so will +When correctly configured: +.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]. +.SS Set LEDGER_FILE on mac +In a terminal window, follow the unix procedure above. .PP -On mac, this additional step might be helpful for GUI applications (like -Emacs started from the dock): add an entry to -\f[CR]\[ti]/.MacOSX/environment.plist\f[R] like +Also, this optional step may be helpful for GUI applications: +.IP "1." 3 +Add an entry to \f[CR]\[ti]/.MacOSX/environment.plist\f[R] like +.RS 4 .IP .EX { - \[dq]LEDGER_FILE\[dq] : \[dq]\[ti]/finance/2023.journal\[dq] + \[dq]LEDGER_FILE\[dq] : \[dq]\[ti]/finance/my.journal\[dq] } .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 -and then run \f[CR]killall Dock\f[R] in a terminal window (or restart -the machine). +When correctly configured for GUI applications: +.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 -On Windows, see https://www.java.com/en/download/help/path.html, or try -running these commands in a powershell window (let us know if it -persists across a reboot, and if you need to be an Administrator): -.IP -.EX -> CD -> MKDIR finance -> SETX LEDGER_FILE \[dq]C:\[rs]Users\[rs]USERNAME\[rs]finance\[rs]2023.journal\[dq] -.EE +Or at the command line, you can do it this way: +.IP "1." 3 +In a powershell window, run +\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] +.IP "2." 3 +And open a new powershell window. +(Existing windows won\[aq]t see the change.) .PP -When correctly configured, in a new terminal window -\f[CR]$env:LEDGER_FILE\f[R] will show the file path, and so will +Warning, doing this from the Windows command line can be tricky; other +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]. -.SH Setting opening balances +.SS Setting opening balances Pick a starting date for which you can look up the balances of some real\-world assets (bank accounts, wallet..) and liabilities (credit cards..). @@ -13060,7 +13151,7 @@ Eg: .EX $ git commit \-m \[aq]initial balances\[aq] 2023.journal .EE -.SH Recording transactions +.SS Recording transactions 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 hledger\-iadd or hledger\-web add\-ons, or by using the import command @@ -13082,7 +13173,7 @@ hledger.org for more ideas: income:salary assets:bank:checking $1000 .EE -.SH Reconciling +.SS Reconciling Periodically you should reconcile \- compare your hledger\-reported balances against external sources of truth, like bank statements or your bank\[aq]s website \- to be sure that your ledger accurately represents @@ -13143,7 +13234,7 @@ commit: .EX $ git commit \-m \[aq]txns\[aq] 2023.journal .EE -.SH Reporting +.SS Reporting Here are some basic reports. .PP Show all transactions: @@ -13301,7 +13392,7 @@ $ hledger activity \-W 2023\-01\-06 **** 2023\-01\-13 **** .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 file, so that old transactions don\[aq]t slow down or clutter your reports, and to help ensure the integrity of your accounting history. diff --git a/hledger/hledger.info b/hledger/hledger.info index 0381bc38a..54944609b 100644 --- a/hledger/hledger.info +++ b/hledger/hledger.info @@ -118,15 +118,6 @@ file" and "Setting opening balances" sections in PART 5: COMMON TASKS. * Data generation commands:: * Maintenance commands:: * PART 5 COMMON TASKS:: -* Getting help:: -* Constructing command lines:: -* Starting a journal file:: -* Setting LEDGER_FILE:: -* Setting opening balances:: -* Recording transactions:: -* Reconciling:: -* Reporting:: -* Migrating to a new file:: * BUGS::  @@ -773,15 +764,28 @@ File: hledger.info, Node: Argument files, Next: Config files, Prev: Regular e ================== 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: -'hledger bal @foo.args'. +then use them by writing '@FILE.args' as a hledger command argument. +The '.args' file extension is conventional, but not required. In an +argument file, - An argument file's format is more restrictive than the command line. -Each line should contain just one option or argument. Don't use spaces -except inside quotes; write '=' or nothing between a flag and its -argument. If you use quotes, they must enclose the whole line. For the -special characters mentioned above, use one less level of quoting than -you would at the command line. + * Each line can contain one argument, flag, or option. + * Blank lines or lines beginning with '#' are ignored. + * An option's flag and value should be joined by '='. + * An option value or an argument may contain spaces. Don't use + single or double quotes. + * 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  File: hledger.info, Node: Config files, Next: Shell completions, Prev: Argument files, Up: Options @@ -1266,7 +1270,8 @@ $ hledger print -c '$1.000,0' This option can be repeated to set the display style for multiple commodities/currencies. Its argument is as described in the commodity -directive. +directive. 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 parseability (such as adding trailing decimal marks when needed). @@ -2866,7 +2871,7 @@ incomestatement reports, and querying by type:. * You can list accounts and their types, for troubleshooting: - $ hledger accounts --types [ACCTPAT] [type:TYPECODES] [-DEPTH] + $ hledger accounts --types [ACCTPAT] [type:TYPECODES] [-DEPTH] [--locations] * It's a good idea to declare at least one account for each account type. Having some types declared and some inferred can disrupt @@ -3166,6 +3171,12 @@ commodity directives in a top-level parent file might be important. Or, keep your decimal marks unambiguous and your entries well balanced and precise. + 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) * Menu: @@ -6561,33 +6572,49 @@ File: hledger.info, Node: Depth, Next: Queries, Prev: Time periods, Up: Top 14 Depth ******** -With the '--depth NUM' option (short form: '-NUM'), reports will show -accounts only to the specified depth, hiding deeper subaccounts. Use -this when you want a summary with less detail. This flag has the same -effect as a 'depth:' query argument. So all of these are equivalent: -'depth:2', '--depth=2', '-2'. +With the '--depth NUM' option (short form, usually preferred: '-NUM'), +reports will show accounts only to the specified depth, hiding deeper +subaccounts. Use this when you want a summary with less detail. This +flag has the same effect as a 'depth:' query argument. So all of these +are equivalent: 'depth:2', '--depth=2', '-2'. - In place of a single number which limits the depth for all accounts, -you can also provide depth limits for specific accounts, by providing a -'REGEX=DEPTH' argument instead of just a 'DEPTH' _(since 1.41)_. For -example, '--depth assets=2' (or 'depth:assets=2') will collapse accounts -matching the regular expression "assets" to depth 2. So + You can also provide custom depths for specific accounts, by +providing a 'REGEX=NUM' argument instead of just 'NUM' _(since 1.41)_. +For example, '--depth assets=2' (or 'depth:assets=2') will collapse +accounts matching the regular expression "assets" to depth 2. So 'assets:bank:savings' would be collapsed to 'assets:bank', but 'liabilities:bank:credit card' would not be affected. - (If REGEX contains spaces or other special characters, enclose it in -quotes in the usual way. Eg: '--depth 'credit card=2'') + If REGEX contains spaces or other special characters, enclose it in +quotes in the usual way. Eg: '--depth 'credit card=2'' - Specific depth options and a general depth option can be combined. -Eg '--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. +* Menu: - If an account is matched by more than one regular expression depth -argument, the most specific (deepest) match will be used. For example, -with '--depth assets=1 --depth savings=2', 'assets:bank:savings' will be -collapsed to depth 2, not depth 1 (because "savings" matches a deeper -part of it than "assets" does). +* Combining depth options:: + + +File: hledger.info, Node: Combining depth options, Up: Depth + +14.1 Combining depth options +============================ + +If a command line contains multiple general depth options, the last one +wins. (Useful for overriding a depth specified by scripts.) + + Or a command may contain a combination of general and custom depth +options. In this case, the most specifically (deepest) matching option +wins. Some examples: + + * '--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. + + * '--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.  File: hledger.info, Node: Queries, Next: Pivoting, Prev: Depth, Up: Top @@ -11846,9 +11873,18 @@ Flags: all - also round cost amounts to precision (can unbalance transactions) - 'close' has six modes, selected by choosing one of the mode flags -('--close' is the default). They all do much the same operation, but -with different defaults, useful in different situations. + 'close' has six modes, selected by choosing one of the mode flags: +'--clopen', '--close' (default), '--open', '--assert', '--assign', or +'--retain'. They are all doing the same kind of operation, but with +different defaults 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'. * Menu: @@ -11903,11 +11939,6 @@ the RX accounts (Revenue, Expense). Assertions will be added indicating and checking the new balances of the closed/opened accounts. - The generated transactions will have a 'clopen:' tag. If the main -journal'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'. -  File: hledger.info, Node: close --close, Next: close --open, Prev: close --clopen, Up: close @@ -11987,12 +12018,13 @@ File: hledger.info, Node: close customisation, Next: close and balance asserti In all modes, the following things can be overridden: * the accounts to be closed/opened, with account query arguments + * the closing/opening dates, with '-e OPENDATE' * the balancing account, with '--close-acct=ACCT' and/or '--open-acct=ACCT' * the transaction descriptions, with '--close-desc=DESC' and '--open-desc=DESC' - * the transaction's tag value, with a '--MODE=NEW' option argument - * the closing/opening dates, with '-e OPENDATE' + * the transactions' 'clopen' tag value, with a 'TAGVAL' argument for + the mode flag (see above). 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 @@ -12373,9 +12405,7 @@ also always enables the 'assertions' check. This prevents wrong conversions caused by typos. * *commodities* - all commodity symbols used must be declared. This - guards against mistyping or omitting commodity symbols. Declaring - commodities also sets their precision for display and transaction - balancing. + guards against mistyping or omitting commodity symbols. * *accounts* - all account names used must be declared. This prevents the use of mis-spelled or outdated account names. @@ -12569,18 +12599,30 @@ $ hledger test balance # run tests with "balance" in their name $ hledger test -- -h # show tasty's options  -File: hledger.info, Node: PART 5 COMMON TASKS, Next: Getting help, Prev: Maintenance commands, Up: Top +File: hledger.info, Node: PART 5 COMMON TASKS, Next: BUGS, Prev: Maintenance commands, Up: Top 33 PART 5: COMMON TASKS *********************** Here are some quick examples of how to do some basic tasks with hledger. - -File: hledger.info, Node: Getting help, Next: Constructing command lines, Prev: PART 5 COMMON TASKS, Up: Top +* Menu: -34 Getting help -*************** +* Getting help:: +* Constructing command lines:: +* Starting a journal file:: +* Setting LEDGER_FILE:: +* Setting opening balances:: +* Recording transactions:: +* Reconciling:: +* Reporting:: +* Migrating to a new file:: + + +File: hledger.info, Node: Getting help, Next: Constructing command lines, Up: PART 5 COMMON TASKS + +33.1 Getting help +================= Here's how to list commands and view options and command docs: @@ -12600,10 +12642,10 @@ https://hledger.org. Chat and mail list support and discussion archives can be found at https://hledger.org/support.  -File: hledger.info, Node: Constructing command lines, Next: Starting a journal file, Prev: Getting help, Up: Top +File: hledger.info, Node: Constructing command lines, Next: Starting a journal file, Prev: Getting help, Up: PART 5 COMMON TASKS -35 Constructing command lines -***************************** +33.2 Constructing command lines +=============================== 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 @@ -12620,10 +12662,10 @@ described in OPTIONS, here are some tips that might help: '--debug=2'.  -File: hledger.info, Node: Starting a journal file, Next: Setting LEDGER_FILE, Prev: Constructing command lines, Up: Top +File: hledger.info, Node: Starting a journal file, Next: Setting LEDGER_FILE, Prev: Constructing command lines, Up: PART 5 COMMON TASKS -36 Starting a journal file -************************** +33.3 Starting a journal file +============================ hledger looks for your accounting data in a journal file, '$HOME/.hledger.journal' by default: @@ -12659,49 +12701,111 @@ Commodities : 0 () Market prices : 0 ()  -File: hledger.info, Node: Setting LEDGER_FILE, Next: Setting opening balances, Prev: Starting a journal file, Up: Top +File: hledger.info, Node: Setting LEDGER_FILE, Next: Setting opening balances, Prev: Starting a journal file, Up: PART 5 COMMON TASKS -37 Setting LEDGER_FILE -********************** +33.4 Setting LEDGER_FILE +======================== -How to set 'LEDGER_FILE' permanently depends on your setup: +* Menu: - On unix and mac, running these commands in the terminal will work for -many people; adapt as needed: - -$ echo 'export LEDGER_FILE=~/finance/2023.journal' >> ~/.profile -$ source ~/.profile - - When correctly configured, in a new terminal window 'env | grep -LEDGER_FILE' will show your file, and so will 'hledger files'. - - On mac, this additional step might be helpful for GUI applications -(like Emacs started from the dock): add an entry to -'~/.MacOSX/environment.plist' like - -{ - "LEDGER_FILE" : "~/finance/2023.journal" -} - - and then run 'killall Dock' in a terminal window (or restart the -machine). - - On Windows, see https://www.java.com/en/download/help/path.html, or -try running these commands in a powershell window (let us know if it -persists across a reboot, and if you need to be an Administrator): - -> CD -> MKDIR finance -> SETX LEDGER_FILE "C:\Users\USERNAME\finance\2023.journal" - - When correctly configured, in a new terminal window -'$env:LEDGER_FILE' will show the file path, and so will 'hledger files'. +* Set LEDGER_FILE on unix:: +* Set LEDGER_FILE on mac:: +* Set LEDGER_FILE on Windows::  -File: hledger.info, Node: Setting opening balances, Next: Recording transactions, Prev: Setting LEDGER_FILE, Up: Top +File: hledger.info, Node: Set LEDGER_FILE on unix, Next: Set LEDGER_FILE on mac, Up: Setting LEDGER_FILE -38 Setting opening balances -*************************** +33.4.1 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: + +$ echo 'export LEDGER_FILE=~/finance/my.journal' >> ~/.profile +$ source ~/.profile + + When correctly configured: + + * 'env | grep LEDGER_FILE' will show your new setting + * and so should 'hledger setup' and (once the file exists) 'hledger + files'. + + +File: hledger.info, Node: Set LEDGER_FILE on mac, Next: Set LEDGER_FILE on Windows, Prev: Set LEDGER_FILE on unix, Up: Setting LEDGER_FILE + +33.4.2 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/my.journal" + } + + 2. Run 'killall Dock' in a terminal window (or restart the machine), + to complete the change. + + When correctly configured for GUI applications: + + * apps started from the dock or a spotlight search, such as a GUI + Emacs, will be aware of the new LEDGER_FILE setting. + + +File: hledger.info, Node: Set LEDGER_FILE on Windows, Prev: Set LEDGER_FILE on mac, Up: Setting LEDGER_FILE + +33.4.3 Set LEDGER_FILE on Windows +--------------------------------- + +Using the gui is easiest: + + 1. In task bar, search for 'environment variables', and choose "Edit + environment 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]::SetEnvironmentVariable("LEDGER_FILE", + "C:\User\USERNAME\finance\my.journal", + [System.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: + + * may not affect the current window + * may not be persistent + * may not work unless you are an administrator + * may limit values to 1024 characters + * may break dynamic references to other variables + * may require a new-enough version of powershell + * or may be intended for the older command window. + * If you still have trouble, see eg Setting Windows PowerShell + environment variables or Adding path permanently to windows using + powershell doesn't appear to work. + + When correctly configured: + + * in a new powershell window, '$env:LEDGER_FILE' will show your new + setting + * and so should 'hledger setup' and (once the file exists) 'hledger + files'. + + +File: hledger.info, Node: Setting opening balances, Next: Recording transactions, Prev: Setting LEDGER_FILE, Up: PART 5 COMMON TASKS + +33.5 Setting opening balances +============================= Pick a starting date for which you can look up the balances of some real-world assets (bank accounts, wallet..) and liabilities (credit @@ -12781,10 +12885,10 @@ the journal. Eg: $ git commit -m 'initial balances' 2023.journal  -File: hledger.info, Node: Recording transactions, Next: Reconciling, Prev: Setting opening balances, Up: Top +File: hledger.info, Node: Recording transactions, Next: Reconciling, Prev: Setting opening balances, Up: PART 5 COMMON TASKS -39 Recording transactions -************************* +33.6 Recording transactions +=========================== 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 @@ -12807,10 +12911,10 @@ and hledger.org for more ideas: assets:bank:checking $1000  -File: hledger.info, Node: Reconciling, Next: Reporting, Prev: Recording transactions, Up: Top +File: hledger.info, Node: Reconciling, Next: Reporting, Prev: Recording transactions, Up: PART 5 COMMON TASKS -40 Reconciling -************** +33.7 Reconciling +================ Periodically you should reconcile - compare your hledger-reported balances against external sources of truth, like bank statements or your @@ -12862,10 +12966,10 @@ commit: $ git commit -m 'txns' 2023.journal  -File: hledger.info, Node: Reporting, Next: Migrating to a new file, Prev: Reconciling, Up: Top +File: hledger.info, Node: Reporting, Next: Migrating to a new file, Prev: Reconciling, Up: PART 5 COMMON TASKS -41 Reporting -************ +33.8 Reporting +============== Here are some basic reports. @@ -13010,10 +13114,10 @@ $ hledger activity -W 2023-01-13 ****  -File: hledger.info, Node: Migrating to a new file, Next: BUGS, Prev: Reporting, Up: Top +File: hledger.info, Node: Migrating to a new file, Prev: Reporting, Up: PART 5 COMMON TASKS -42 Migrating to a new file -************************** +33.9 Migrating to a new file +============================ 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, @@ -13023,9 +13127,9 @@ close command. If using version control, don't forget to 'git add' the new file.  -File: hledger.info, Node: BUGS, Prev: Migrating to a new file, Up: Top +File: hledger.info, Node: BUGS, Prev: PART 5 COMMON TASKS, Up: Top -43 BUGS +34 BUGS ******* We welcome bug reports in the hledger issue tracker @@ -13054,7 +13158,7 @@ Ledger.  File: hledger.info, Node: Troubleshooting, Up: BUGS -43.1 Troubleshooting +34.1 Troubleshooting ==================== Here are some common issues you might encounter when you run hledger, @@ -13092,399 +13196,403 @@ See hledger and Ledger for full details.  Tag Table: Node: Top208 -Node: PART 1 USER INTERFACE4307 -Node: Input4446 -Node: Text encoding5538 -Node: Data formats6287 -Node: Standard input8021 -Node: Multiple files8410 -Node: Strict mode9147 -Node: Commands9981 -Node: Add-on commands11263 -Node: Options12314 -Node: Special characters19464 -Node: Escaping shell special characters20454 -Node: Escaping regular expression special characters21813 -Node: Escaping in other situations23328 -Node: Unicode characters24476 -Node: Regular expressions25897 -Node: hledger's regular expressions29156 -Node: Argument files30797 -Node: Config files31500 -Node: Shell completions34769 -Node: Output35258 -Node: Output destination35449 -Node: Output format36007 -Node: Text output37793 -Node: Box-drawing characters38772 -Node: Colour39272 -Node: Paging39858 -Node: HTML output41377 -Node: CSV / TSV output41795 -Node: FODS output42049 -Node: Beancount output42853 -Node: Beancount account names44354 -Node: Beancount commodity names44895 -Node: Beancount virtual postings45542 -Node: Beancount metadata45858 -Node: Beancount costs46638 -Node: Beancount operating currency47054 -Node: SQL output47504 -Node: JSON output48295 -Node: Commodity styles49112 -Node: Debug output49999 -Node: Environment50831 -Node: PART 2 DATA FORMATS51488 -Node: Journal51631 -Node: Journal cheatsheet54096 -Node: Comments60347 -Node: Transactions61291 -Node: Dates62428 -Node: Simple dates62580 -Node: Posting dates63196 -Node: Status64369 -Node: Code66135 -Node: Description66470 -Node: Payee and note67157 -Node: Transaction comments68248 -Node: Postings68764 -Node: Debits and credits70080 -Node: Account names70639 -Node: Two space delimiter71596 -Node: Account hierarchy73001 -Node: Other account name features73884 -Node: Amounts74302 -Node: Decimal marks75331 -Node: Digit group marks76435 -Node: Commodity77070 -Node: Costs78187 -Node: Balance assertions80439 -Node: Assertions and ordering81687 -Node: Assertions and multiple files82406 -Node: Assertions and costs83574 -Node: Assertions and commodities84221 -Node: Assertions and subaccounts85880 -Node: Assertions and status86540 -Node: Assertions and virtual postings86960 -Node: Assertions and auto postings87325 -Node: Assertions and precision88200 -Node: Assertions and hledger add88684 -Node: Posting comments89432 -Node: Transaction balancing89972 -Node: Tags92180 -Node: Tag propagation93699 -Node: Displaying tags95198 -Node: When to use tags ?95591 -Node: Tag names96255 -Node: Directives98236 -Node: Directives and multiple files99693 -Node: Directive effects100638 -Node: account directive103794 -Node: Account comments105244 -Node: Account error checking105903 -Node: Account display order107440 -Node: Account types108638 -Node: alias directive111899 -Node: Basic aliases113110 -Node: Regex aliases113985 -Node: Combining aliases115032 -Node: Aliases and multiple files116486 -Node: end aliases directive117269 -Node: Aliases can generate bad account names117637 -Node: Aliases and account types118470 -Node: commodity directive119362 -Node: Commodity directive syntax120949 -Node: Commodity error checking122598 -Node: decimal-mark directive123073 -Node: include directive123652 -Node: P directive125870 -Node: payee directive126904 -Node: tag directive127526 -Node: Periodic transactions128138 -Node: Periodic rule syntax130292 -Node: Periodic rules and relative dates131115 -Node: Two spaces between period expression and description!131892 -Node: Auto postings132853 -Node: Auto postings and multiple files136139 -Node: Auto postings and dates136544 -Node: Auto postings and transaction balancing / inferred amounts / balance assertions136985 -Node: Auto posting tags137831 -Node: Auto postings on forecast transactions only138726 -Node: Other syntax139196 -Node: Balance assignments139968 -Node: Balance assignments and costs141496 -Node: Balance assignments and multiple files141918 -Node: Bracketed posting dates142341 -Node: D directive143039 -Node: apply account directive144812 -Node: Y directive145679 -Node: Secondary dates146667 -Node: Star comments148152 -Node: Valuation expressions148844 -Node: Virtual postings149143 -Node: Other Ledger directives150767 -Node: Other cost/lot notations151529 -Node: CSV154370 -Node: CSV rules cheatsheet156536 -Node: source158635 -Node: Data cleaning / generating commands160034 -Node: archive161896 -Node: encoding162824 -Node: separator163867 -Node: skip164520 -Node: date-format165170 -Node: timezone166115 -Node: newest-first167241 -Node: intra-day-reversed167954 -Node: decimal-mark168556 -Node: fields list169036 -Node: Field assignment170844 -Node: Field names172063 -Node: date field173395 -Node: date2 field173559 -Node: status field173754 -Node: code field173944 -Node: description field174132 -Node: comment field174349 -Node: account field174906 -Node: amount field175624 -Node: currency field178463 -Node: balance field178871 -Node: if block179394 -Node: Matchers180921 -Node: Multiple matchers182911 -Node: Match groups183719 -Node: if table184612 -Node: balance-type186675 -Node: include187502 -Node: Working with CSV188071 -Node: Rapid feedback188623 -Node: Valid CSV189206 -Node: File Extension190082 -Node: Reading CSV from standard input190817 -Node: Reading multiple CSV files191203 -Node: Reading files specified by rule191679 -Node: Valid transactions193076 -Node: Deduplicating importing193901 -Node: Setting amounts195130 -Node: Amount signs197657 -Node: Setting currency/commodity198722 -Node: Amount decimal places200098 -Node: Referencing other fields201355 -Node: How CSV rules are evaluated202463 -Node: Well factored rules205180 -Node: CSV rules examples205670 -Node: Bank of Ireland205868 -Node: Coinbase207465 -Node: Amazon208648 -Node: Paypal210490 -Node: Timeclock218240 -Node: Timedot222293 -Node: Timedot examples225770 -Node: PART 3 REPORTING CONCEPTS228047 -Node: Time periods228211 -Node: Report start & end date228484 -Node: Smart dates229960 -Node: Report intervals232083 -Node: Date adjustments232657 -Node: Start date adjustment232877 -Node: End date adjustment233780 -Node: Period headings234561 -Node: Period expressions235494 -Node: Period expressions with a report interval237399 -Node: More complex report intervals237847 -Node: Multiple weekday intervals239963 -Node: Depth240974 -Node: Queries242554 -Node: Query types245226 -Node: acct query245601 -Node: amt query245912 -Node: code query246609 -Node: cur query246804 -Node: desc query247410 -Node: date query247593 -Node: date2 query247989 -Node: depth query248280 -Node: note query248616 -Node: payee query248882 -Node: real query249163 -Node: status query249368 -Node: type query249608 -Node: tag query250141 -Node: Negative queries250770 -Node: not query250952 -Node: Space-separated queries251239 -Node: Boolean queries251927 -Node: expr query253245 -Node: any query253925 -Node: all query254378 -Node: Queries and command options254960 -Node: Queries and account aliases255408 -Node: Queries and valuation255733 -Node: Pivoting256095 -Node: Generating data258378 -Node: Forecasting260178 -Node: --forecast260834 -Node: Inspecting forecast transactions261935 -Node: Forecast reports263268 -Node: Forecast tags264377 -Node: Forecast period in detail264997 -Node: Forecast troubleshooting266085 -Node: Budgeting267156 -Node: Amount formatting267716 -Node: Commodity display style267960 -Node: Rounding269801 -Node: Trailing decimal marks270406 -Node: Amount parseability271339 -Node: Cost reporting272948 -Node: Recording costs273779 -Node: Reporting at cost275506 -Node: Equity conversion postings276271 -Node: Inferring equity conversion postings278916 -Node: Combining costs and equity conversion postings280058 -Node: Requirements for detecting equity conversion postings281283 -Node: Infer cost and equity by default ?282805 -Node: Value reporting283242 -Node: -V Value284178 -Node: -X Value in specified commodity284505 -Node: Valuation date284855 -Node: Finding market price285688 -Node: --infer-market-prices market prices from transactions287068 -Node: Valuation commodity290112 -Node: --value Flexible valuation291545 -Node: Valuation examples293388 -Node: Interaction of valuation and queries295532 -Node: Effect of valuation on reports296249 -Node: PART 4 COMMANDS304099 -Node: Help commands306888 -Node: commands307074 -Node: demo307282 -Node: help308375 -Node: User interface commands310080 -Node: repl310291 -Node: Examples312555 -Node: run313113 -Node: Examples 2315528 -Node: ui316552 -Node: web316689 -Node: Data entry commands316817 -Node: add317078 -Node: add and balance assertions319652 -Node: add and balance assignments320376 -Node: import320937 -Node: Import dry run322016 -Node: Overlap detection322964 -Node: First import325850 -Node: Importing balance assignments327045 -Node: Import and commodity styles328100 -Node: Import archiving328534 -Node: Import special cases329359 -Node: Deduplication329577 -Node: Varying file name330068 -Node: Multiple versions330452 -Node: Basic report commands331559 -Node: accounts331860 -Node: codes334372 -Node: commodities335394 -Node: descriptions336402 -Node: files336862 -Node: notes337159 -Node: payees337671 -Node: prices338828 -Node: stats339720 -Node: tags341461 -Node: Standard report commands343285 -Node: print343590 -Node: print amount explicitness346321 -Node: print alignment347259 -Node: print amount style347573 -Node: print parseability348803 -Node: print other features349907 -Node: print output format350869 -Node: aregister354154 -Node: aregister and posting dates358609 -Node: register359510 -Node: Custom register output366750 -Node: balancesheet367935 -Node: balancesheetequity372900 -Node: cashflow378235 -Node: incomestatement383048 -Node: Advanced report commands387897 -Node: balance388105 -Node: balance features393526 -Node: Simple balance report395629 -Node: Balance report line format397439 -Node: Filtered balance report399799 -Node: List or tree mode400318 -Node: Depth limiting401831 -Node: Dropping top-level accounts402598 -Node: Showing declared accounts403108 -Node: Sorting by amount403838 -Node: Percentages404692 -Node: Multi-period balance report405399 -Node: Balance change end balance408151 -Node: Balance report modes409788 -Node: Calculation mode410467 -Node: Accumulation mode411171 -Node: Valuation mode412272 -Node: Combining balance report modes413616 -Node: Budget report415646 -Node: Using the budget report417946 -Node: Budget date surprises420222 -Node: Selecting budget goals421586 -Node: Budgeting vs forecasting422534 -Node: Balance report layout424211 -Node: Wide layout425416 -Node: Tall layout427821 -Node: Bare layout429127 -Node: Tidy layout431191 -Node: Balance report output432735 -Node: Some useful balance reports433509 -Node: roi434769 -Node: Spaces and special characters in --inv and --pnl437016 -Node: Semantics of --inv and --pnl437742 -Node: IRR and TWR explained439829 -Node: Chart commands443240 -Node: activity443421 -Node: Data generation commands443918 -Node: close444124 -Node: close --clopen446687 -Node: close --close448861 -Node: close --open449385 -Node: close --assert449635 -Node: close --assign449962 -Node: close --retain450641 -Node: close customisation451498 -Node: close and balance assertions453142 -Node: close examples454664 -Node: Retain earnings454901 -Node: Migrate balances to a new file455404 -Node: More detailed close examples456766 -Node: rewrite456988 -Node: Re-write rules in a file459548 -Node: Diff output format460849 -Node: rewrite vs print --auto462119 -Node: Maintenance commands462833 -Node: check463052 -Node: Basic checks464134 -Node: Strict checks465155 -Node: Other checks466092 -Node: Custom checks467844 -Node: diff468299 -Node: setup469507 -Node: test472374 -Node: PART 5 COMMON TASKS473277 -Node: Getting help473510 -Node: Constructing command lines474419 -Node: Starting a journal file475264 -Node: Setting LEDGER_FILE476648 -Node: Setting opening balances477906 -Node: Recording transactions481228 -Node: Reconciling481953 -Node: Reporting484342 -Node: Migrating to a new file488456 -Node: BUGS488905 -Node: Troubleshooting489735 +Node: PART 1 USER INTERFACE4093 +Node: Input4232 +Node: Text encoding5324 +Node: Data formats6073 +Node: Standard input7807 +Node: Multiple files8196 +Node: Strict mode8933 +Node: Commands9767 +Node: Add-on commands11049 +Node: Options12100 +Node: Special characters19250 +Node: Escaping shell special characters20240 +Node: Escaping regular expression special characters21599 +Node: Escaping in other situations23114 +Node: Unicode characters24262 +Node: Regular expressions25683 +Node: hledger's regular expressions28942 +Node: Argument files30583 +Node: Config files31480 +Node: Shell completions34749 +Node: Output35238 +Node: Output destination35429 +Node: Output format35987 +Node: Text output37773 +Node: Box-drawing characters38752 +Node: Colour39252 +Node: Paging39838 +Node: HTML output41357 +Node: CSV / TSV output41775 +Node: FODS output42029 +Node: Beancount output42833 +Node: Beancount account names44334 +Node: Beancount commodity names44875 +Node: Beancount virtual postings45522 +Node: Beancount metadata45838 +Node: Beancount costs46618 +Node: Beancount operating currency47034 +Node: SQL output47484 +Node: JSON output48275 +Node: Commodity styles49092 +Node: Debug output50102 +Node: Environment50934 +Node: PART 2 DATA FORMATS51591 +Node: Journal51734 +Node: Journal cheatsheet54199 +Node: Comments60450 +Node: Transactions61394 +Node: Dates62531 +Node: Simple dates62683 +Node: Posting dates63299 +Node: Status64472 +Node: Code66238 +Node: Description66573 +Node: Payee and note67260 +Node: Transaction comments68351 +Node: Postings68867 +Node: Debits and credits70183 +Node: Account names70742 +Node: Two space delimiter71699 +Node: Account hierarchy73104 +Node: Other account name features73987 +Node: Amounts74405 +Node: Decimal marks75434 +Node: Digit group marks76538 +Node: Commodity77173 +Node: Costs78290 +Node: Balance assertions80542 +Node: Assertions and ordering81790 +Node: Assertions and multiple files82509 +Node: Assertions and costs83677 +Node: Assertions and commodities84324 +Node: Assertions and subaccounts85983 +Node: Assertions and status86643 +Node: Assertions and virtual postings87063 +Node: Assertions and auto postings87428 +Node: Assertions and precision88303 +Node: Assertions and hledger add88787 +Node: Posting comments89535 +Node: Transaction balancing90075 +Node: Tags92283 +Node: Tag propagation93802 +Node: Displaying tags95301 +Node: When to use tags ?95694 +Node: Tag names96358 +Node: Directives98339 +Node: Directives and multiple files99796 +Node: Directive effects100741 +Node: account directive103897 +Node: Account comments105347 +Node: Account error checking106006 +Node: Account display order107543 +Node: Account types108741 +Node: alias directive112016 +Node: Basic aliases113227 +Node: Regex aliases114102 +Node: Combining aliases115149 +Node: Aliases and multiple files116603 +Node: end aliases directive117386 +Node: Aliases can generate bad account names117754 +Node: Aliases and account types118587 +Node: commodity directive119479 +Node: Commodity directive syntax121272 +Node: Commodity error checking122921 +Node: decimal-mark directive123396 +Node: include directive123975 +Node: P directive126193 +Node: payee directive127227 +Node: tag directive127849 +Node: Periodic transactions128461 +Node: Periodic rule syntax130615 +Node: Periodic rules and relative dates131438 +Node: Two spaces between period expression and description!132215 +Node: Auto postings133176 +Node: Auto postings and multiple files136462 +Node: Auto postings and dates136867 +Node: Auto postings and transaction balancing / inferred amounts / balance assertions137308 +Node: Auto posting tags138154 +Node: Auto postings on forecast transactions only139049 +Node: Other syntax139519 +Node: Balance assignments140291 +Node: Balance assignments and costs141819 +Node: Balance assignments and multiple files142241 +Node: Bracketed posting dates142664 +Node: D directive143362 +Node: apply account directive145135 +Node: Y directive146002 +Node: Secondary dates146990 +Node: Star comments148475 +Node: Valuation expressions149167 +Node: Virtual postings149466 +Node: Other Ledger directives151090 +Node: Other cost/lot notations151852 +Node: CSV154693 +Node: CSV rules cheatsheet156859 +Node: source158958 +Node: Data cleaning / generating commands160357 +Node: archive162219 +Node: encoding163147 +Node: separator164190 +Node: skip164843 +Node: date-format165493 +Node: timezone166438 +Node: newest-first167564 +Node: intra-day-reversed168277 +Node: decimal-mark168879 +Node: fields list169359 +Node: Field assignment171167 +Node: Field names172386 +Node: date field173718 +Node: date2 field173882 +Node: status field174077 +Node: code field174267 +Node: description field174455 +Node: comment field174672 +Node: account field175229 +Node: amount field175947 +Node: currency field178786 +Node: balance field179194 +Node: if block179717 +Node: Matchers181244 +Node: Multiple matchers183234 +Node: Match groups184042 +Node: if table184935 +Node: balance-type186998 +Node: include187825 +Node: Working with CSV188394 +Node: Rapid feedback188946 +Node: Valid CSV189529 +Node: File Extension190405 +Node: Reading CSV from standard input191140 +Node: Reading multiple CSV files191526 +Node: Reading files specified by rule192002 +Node: Valid transactions193399 +Node: Deduplicating importing194224 +Node: Setting amounts195453 +Node: Amount signs197980 +Node: Setting currency/commodity199045 +Node: Amount decimal places200421 +Node: Referencing other fields201678 +Node: How CSV rules are evaluated202786 +Node: Well factored rules205503 +Node: CSV rules examples205993 +Node: Bank of Ireland206191 +Node: Coinbase207788 +Node: Amazon208971 +Node: Paypal210813 +Node: Timeclock218563 +Node: Timedot222616 +Node: Timedot examples226093 +Node: PART 3 REPORTING CONCEPTS228370 +Node: Time periods228534 +Node: Report start & end date228807 +Node: Smart dates230283 +Node: Report intervals232406 +Node: Date adjustments232980 +Node: Start date adjustment233200 +Node: End date adjustment234103 +Node: Period headings234884 +Node: Period expressions235817 +Node: Period expressions with a report interval237722 +Node: More complex report intervals238170 +Node: Multiple weekday intervals240286 +Node: Depth241297 +Node: Combining depth options242283 +Node: Queries243233 +Node: Query types245905 +Node: acct query246280 +Node: amt query246591 +Node: code query247288 +Node: cur query247483 +Node: desc query248089 +Node: date query248272 +Node: date2 query248668 +Node: depth query248959 +Node: note query249295 +Node: payee query249561 +Node: real query249842 +Node: status query250047 +Node: type query250287 +Node: tag query250820 +Node: Negative queries251449 +Node: not query251631 +Node: Space-separated queries251918 +Node: Boolean queries252606 +Node: expr query253924 +Node: any query254604 +Node: all query255057 +Node: Queries and command options255639 +Node: Queries and account aliases256087 +Node: Queries and valuation256412 +Node: Pivoting256774 +Node: Generating data259057 +Node: Forecasting260857 +Node: --forecast261513 +Node: Inspecting forecast transactions262614 +Node: Forecast reports263947 +Node: Forecast tags265056 +Node: Forecast period in detail265676 +Node: Forecast troubleshooting266764 +Node: Budgeting267835 +Node: Amount formatting268395 +Node: Commodity display style268639 +Node: Rounding270480 +Node: Trailing decimal marks271085 +Node: Amount parseability272018 +Node: Cost reporting273627 +Node: Recording costs274458 +Node: Reporting at cost276185 +Node: Equity conversion postings276950 +Node: Inferring equity conversion postings279595 +Node: Combining costs and equity conversion postings280737 +Node: Requirements for detecting equity conversion postings281962 +Node: Infer cost and equity by default ?283484 +Node: Value reporting283921 +Node: -V Value284857 +Node: -X Value in specified commodity285184 +Node: Valuation date285534 +Node: Finding market price286367 +Node: --infer-market-prices market prices from transactions287747 +Node: Valuation commodity290791 +Node: --value Flexible valuation292224 +Node: Valuation examples294067 +Node: Interaction of valuation and queries296211 +Node: Effect of valuation on reports296928 +Node: PART 4 COMMANDS304778 +Node: Help commands307567 +Node: commands307753 +Node: demo307961 +Node: help309054 +Node: User interface commands310759 +Node: repl310970 +Node: Examples313234 +Node: run313792 +Node: Examples 2316207 +Node: ui317231 +Node: web317368 +Node: Data entry commands317496 +Node: add317757 +Node: add and balance assertions320331 +Node: add and balance assignments321055 +Node: import321616 +Node: Import dry run322695 +Node: Overlap detection323643 +Node: First import326529 +Node: Importing balance assignments327724 +Node: Import and commodity styles328779 +Node: Import archiving329213 +Node: Import special cases330038 +Node: Deduplication330256 +Node: Varying file name330747 +Node: Multiple versions331131 +Node: Basic report commands332238 +Node: accounts332539 +Node: codes335051 +Node: commodities336073 +Node: descriptions337081 +Node: files337541 +Node: notes337838 +Node: payees338350 +Node: prices339507 +Node: stats340399 +Node: tags342140 +Node: Standard report commands343964 +Node: print344269 +Node: print amount explicitness347000 +Node: print alignment347938 +Node: print amount style348252 +Node: print parseability349482 +Node: print other features350586 +Node: print output format351548 +Node: aregister354833 +Node: aregister and posting dates359288 +Node: register360189 +Node: Custom register output367429 +Node: balancesheet368614 +Node: balancesheetequity373579 +Node: cashflow378914 +Node: incomestatement383727 +Node: Advanced report commands388576 +Node: balance388784 +Node: balance features394205 +Node: Simple balance report396308 +Node: Balance report line format398118 +Node: Filtered balance report400478 +Node: List or tree mode400997 +Node: Depth limiting402510 +Node: Dropping top-level accounts403277 +Node: Showing declared accounts403787 +Node: Sorting by amount404517 +Node: Percentages405371 +Node: Multi-period balance report406078 +Node: Balance change end balance408830 +Node: Balance report modes410467 +Node: Calculation mode411146 +Node: Accumulation mode411850 +Node: Valuation mode412951 +Node: Combining balance report modes414295 +Node: Budget report416325 +Node: Using the budget report418625 +Node: Budget date surprises420901 +Node: Selecting budget goals422265 +Node: Budgeting vs forecasting423213 +Node: Balance report layout424890 +Node: Wide layout426095 +Node: Tall layout428500 +Node: Bare layout429806 +Node: Tidy layout431870 +Node: Balance report output433414 +Node: Some useful balance reports434188 +Node: roi435448 +Node: Spaces and special characters in --inv and --pnl437695 +Node: Semantics of --inv and --pnl438421 +Node: IRR and TWR explained440508 +Node: Chart commands443919 +Node: activity444100 +Node: Data generation commands444597 +Node: close444803 +Node: close --clopen447868 +Node: close --close449764 +Node: close --open450288 +Node: close --assert450538 +Node: close --assign450865 +Node: close --retain451544 +Node: close customisation452401 +Node: close and balance assertions454079 +Node: close examples455601 +Node: Retain earnings455838 +Node: Migrate balances to a new file456341 +Node: More detailed close examples457703 +Node: rewrite457925 +Node: Re-write rules in a file460485 +Node: Diff output format461786 +Node: rewrite vs print --auto463056 +Node: Maintenance commands463770 +Node: check463989 +Node: Basic checks465071 +Node: Strict checks466092 +Node: Other checks466931 +Node: Custom checks468683 +Node: diff469138 +Node: setup470346 +Node: test473213 +Node: PART 5 COMMON TASKS474116 +Node: Getting help474565 +Node: Constructing command lines475466 +Node: Starting a journal file476331 +Node: Setting LEDGER_FILE477735 +Node: Set LEDGER_FILE on unix478023 +Node: Set LEDGER_FILE on mac478568 +Node: Set LEDGER_FILE on Windows479296 +Node: Setting opening balances481019 +Node: Recording transactions484361 +Node: Reconciling485106 +Node: Reporting487515 +Node: Migrating to a new file491649 +Node: BUGS492105 +Node: Troubleshooting492931  End Tag Table diff --git a/hledger/hledger.txt b/hledger/hledger.txt index 43672db4c..b92e6d122 100644 --- a/hledger/hledger.txt +++ b/hledger/hledger.txt @@ -605,19 +605,36 @@ Options Argument files 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: - hledger bal @foo.args. + then use them by writing @FILE.args as a hledger command argument. The + .args file extension is conventional, but not required. In an argument + file, - An argument file's format is more restrictive than the command line. - 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- - ment. If you use quotes, they must enclose the whole line. For the - special characters mentioned above, use one less level of quoting than - you would at the command line. + o Each line can contain one argument, flag, or option. + + o Blank lines or lines beginning with # are ignored. + + o An option's flag and value should be joined by =. + + 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 - With hledger 1.40+, you can save extra command line options and argu- - ments in a more featureful hledger config file. Here's a small exam- + With hledger 1.40+, you can save extra command line options and argu- + ments in a more featureful hledger config file. Here's a small exam- ple: # General options are listed first, and used with hledger commands that support them. @@ -627,47 +644,47 @@ Options [print] --explicit --infer-costs - To use a config file, specify it with the --conf option. Its options - will be inserted near the start of your command line, so you can over- + To use a config file, specify it with the --conf option. Its options + will be inserted near the start of your command line, so you can over- ride them with command line options if needed. - Or, you can set up an automatic config file that is used whenever you - run hledger, by creating hledger.conf in the current directory or - above, or .hledger.conf in your home directory (~/.hledger.conf), or - hledger.conf in your XDG config directory (~/.con- + Or, you can set up an automatic config file that is used whenever you + run hledger, by creating hledger.conf in the current directory or + above, or .hledger.conf in your home directory (~/.hledger.conf), or + hledger.conf in your XDG config directory (~/.con- fig/hledger/hledger.conf). - Here is another example config you could start with: + Here is another example config you could start with: https://github.com/simonmichael/hledger/blob/master/hledger.conf.sample - You can put not only options, but also arguments in a config file. If - the first word in a config file's top (general) section does not begin - with a dash (eg: print), it is treated as the command argument (over- + You can put not only options, but also arguments in a config file. If + the first word in a config file's top (general) section does not begin + with a dash (eg: print), it is treated as the command argument (over- riding any argument on the command line). - On unix machines, you can add a shebang line at the top of a config - file, set executable permission on the file, and use it like a script. + On unix machines, you can add a shebang line at the top of a config + file, set executable permission on the file, and use it like a script. Eg (the -S is needed on some operating systems): #!/usr/bin/env -S hledger --conf You can ignore config files by adding the -n/--no-conf flag to the com- mand line. This is useful when using hledger in scripts, or when trou- - bleshooting. When both --conf and --no-conf options are used, the + bleshooting. When both --conf and --no-conf options are used, the right-most wins. - To inspect the processing of config files, use --debug or --debug=8. - Or, run the setup command, which will display any active config files. + To inspect the processing of config files, use --debug or --debug=8. + Or, run the setup command, which will display any active config files. (setup is not affected by config files itself, unlike other commands.) Warning! - There aren't many hledger features that need a warning, but this is + There aren't many hledger features that need a warning, but this is one! - Automatic config files, while convenient, also make hledger less pre- - dictable and dependable. It's easy to make a config file that changes - a report's behaviour, or breaks your hledger-using scripts/applica- + Automatic config files, while convenient, also make hledger less pre- + dictable and dependable. It's easy to make a config file that changes + a report's behaviour, or breaks your hledger-using scripts/applica- tions, in ways that will surprise you later. If you don't want this, @@ -677,31 +694,31 @@ Options 2. Also be alert to downloaded directories which may contain a hledger.conf file. - 3. Also if you are sharing scripts or examples or support, consider + 3. Also if you are sharing scripts or examples or support, consider that others may have a hledger.conf file. Conversely, once you decide to use this feature, try to remember: - 1. Whenever a hledger command does not work as expected, try it again + 1. Whenever a hledger command does not work as expected, try it again with -n (--no-conf) to see if a config file was to blame. - 2. Whenever you call hledger from a script, consider whether that call + 2. Whenever you call hledger from a script, consider whether that call should use -n or not. - 3. Be conservative about what you put in your config file; try to con- + 3. Be conservative about what you put in your config file; try to con- sider the effect on all your reports. - 4. To troubleshoot the effect of config files, run with --debug or + 4. To troubleshoot the effect of config files, run with --debug or --debug 8. The config file feature was added in hledger 1.40. Shell completions - If you use the bash or zsh shells, you can optionally set up con- - text-sensitive autocompletion for hledger command lines. Try pressing - hledger (should list all hledger commands) or hledger - reg acct: (should list your top-level account names). If - completions aren't working, or for more details, see Install > Shell + If you use the bash or zsh shells, you can optionally set up con- + text-sensitive autocompletion for hledger command lines. Try pressing + hledger (should list all hledger commands) or hledger + reg acct: (should list your top-level account names). If + completions aren't working, or for more details, see Install > Shell completions. Output @@ -711,15 +728,15 @@ Output $ hledger print > foo.txt - Some commands (print, register, stats, the balance commands) also pro- - vide the -o/--output-file option, which does the same thing without + Some commands (print, register, stats, the balance commands) also pro- + vide the -o/--output-file option, which does the same thing without needing the shell. Eg: $ hledger print -o foo.txt $ hledger print -o - # write to stdout (the default) Output format - Some commands offer other kinds of output, not just text on the termi- + Some commands offer other kinds of output, not just text on the termi- nal. Here are those commands and the formats currently supported: command txt html csv/tsv fods beancount sql json @@ -733,14 +750,14 @@ Output print Y Y Y Y Y Y Y register Y Y Y Y Y - You can also see which output formats a command supports by running + You can also see which output formats a command supports by running hledger CMD -h and looking for the -O/--output-format=FMT option, You can select the output format by using that option: $ hledger print -O csv # print CSV to standard output - or by choosing a suitable filename extension with the -o/--out- + or by choosing a suitable filename extension with the -o/--out- put-file=FILE.FMT option: $ hledger balancesheet -o foo.csv # write CSV to foo.csv @@ -758,95 +775,95 @@ Output unicode or wide characters, you'll need a terminal and font that render those correctly. (This can be challenging on MS Windows.) - Some reports (register, aregister) will normally use the full window - width. If this isn't working or you want to override it, you can use + Some reports (register, aregister) will normally use the full window + width. If this isn't working or you want to override it, you can use the -w/--width option. - Balance reports (balance, balancesheet, incomestatement...) use what- + Balance reports (balance, balancesheet, incomestatement...) use what- ever width they need. Multi-period multi-currency reports can often be - wider than the window. Besides using a pager, helpful techniques for - this situation include --layout=bare, -V, cur:, --transpose, --tree, + wider than the window. Besides using a pager, helpful techniques for + this situation include --layout=bare, -V, cur:, --transpose, --tree, --depth, --drop, switching to html output, etc. Box-drawing characters - hledger draws simple table borders by default, to minimise the risk of - display problems caused by a terminal/font not supporting box-drawing + hledger draws simple table borders by default, to minimise the risk of + display problems caused by a terminal/font not supporting box-drawing characters. - But your terminal and font probably do support them, so we recommend - using the --pretty flag to show prettier tables in the terminal. This + But your terminal and font probably do support them, so we recommend + using the --pretty flag to show prettier tables in the terminal. This is a good flag to add to your hledger config file. Colour hledger tries to automatically detect ANSI colour and text styling sup- - port and use it when appropriate. (Currently, it is used rather mini- - mally: some reports show negative numbers in red, and help output uses + port and use it when appropriate. (Currently, it is used rather mini- + mally: some reports show negative numbers in red, and help output uses bold text for emphasis.) - You can override this by setting the NO_COLOR environment variable to - disable it, or by using the --color/--colour option, perhaps in your + You can override this by setting the NO_COLOR environment variable to + disable it, or by using the --color/--colour option, perhaps in your config file, with a y/yes or n/no value to force it on or off. Paging - In unix-like environments, when displaying large output (in any output + In unix-like environments, when displaying large output (in any output format) in the terminal, hledger tries to use a pager when appropriate. - (You can disable this with the --pager=no option, perhaps in your con- + (You can disable this with the --pager=no option, perhaps in your con- fig file.) - The pager shows one page of text at a time, and lets you scroll around - to see more. While it is active, usually SPACE shows the next page, h - shows help, and q quits. The home/end/page up/page down/cursor keys, + The pager shows one page of text at a time, and lets you scroll around + to see more. While it is active, usually SPACE shows the next page, h + shows help, and q quits. The home/end/page up/page down/cursor keys, and mouse scrolling, may also work. hledger will use the pager specified by the PAGER environment variable, - otherwise less if available, otherwise more if available. (With one - exception: hledger help -p TOPIC will always use less, so that it can + otherwise less if available, otherwise more if available. (With one + exception: hledger help -p TOPIC will always use less, so that it can scroll to the topic.) - The pager is expected to display hledger's ANSI colour and text - styling. If you see junk characters, you might need to configure your - pager to handle ANSI codes. Or you could disable colour as described + The pager is expected to display hledger's ANSI colour and text + styling. If you see junk characters, you might need to configure your + pager to handle ANSI codes. Or you could disable colour as described above. If you are using the less pager, hledger automatically appends a number - of options to the LESS variable to enable ANSI colour and a number of - other conveniences. (At the time of writing: --chop-long-lines + of options to the LESS variable to enable ANSI colour and a number of + other conveniences. (At the time of writing: --chop-long-lines --hilite-unread --ignore-case --no-init --quit-at-eof - --quit-if-one-screen --RAW-CONTROL-CHARS --shift=8 + --quit-if-one-screen --RAW-CONTROL-CHARS --shift=8 --squeeze-blank-lines --use-backslash ). If these don't work well, you can set your preferred options in the HLEDGER_LESS variable, which will be used instead. HTML output - HTML output can be styled by an optional hledger.css file in the same + HTML output can be styled by an optional hledger.css file in the same directory. - HTML output will be a HTML fragment, not a complete HTML document. - Like other hledger output, for non-ascii characters it will use the + HTML output will be a HTML fragment, not a complete HTML document. + Like other hledger output, for non-ascii characters it will use the system locale's text encoding (see Text encoding). CSV / TSV output - In CSV or TSV output, digit group marks (such as thousands separators) + In CSV or TSV output, digit group marks (such as thousands separators) are disabled automatically. FODS output - FODS is the OpenDocument Spreadsheet format as plain XML, as accepted - by LibreOffice and OpenOffice. If you use their spreadsheet applica- + FODS is the OpenDocument Spreadsheet format as plain XML, as accepted + by LibreOffice and OpenOffice. If you use their spreadsheet applica- tions, this is better than CSV because it works across locales (decimal point vs. decimal comma, character encoding stored in XML header, thus - no problems with umlauts), it supports fixed header rows and columns, - cell types (string vs. number vs. date), separation of number and + no problems with umlauts), it supports fixed header rows and columns, + cell types (string vs. number vs. date), separation of number and currency (currency is displayed but the cell type is still a number ac- cessible for computation), styles (bold), borders. Btw. you can still - extract CSV from FODS/ODS using various utilities like libreoffice + extract CSV from FODS/ODS using various utilities like libreoffice --headless or ods2csv. Beancount output - This is Beancount's journal format. You can use this to export your + This is Beancount's journal format. You can use this to export your hledger data to Beancount, eg to use the Fava web app. - hledger will try to adjust your data to suit Beancount, automatically. - Be cautious and check the conversion until you are confident it is + hledger will try to adjust your data to suit Beancount, automatically. + Be cautious and check the conversion until you are confident it is good. If you plan to export to Beancount often, you may want to follow its conventions, for a cleaner conversion: @@ -858,34 +875,34 @@ Output o avoid virtual postings, balance assignments, and secondary dates. - There is one big adjustment you must handle yourself: for Beancount, - the top level account names must be Assets, Liabilities, Equity, In- + There is one big adjustment you must handle yourself: for Beancount, + the top level account names must be Assets, Liabilities, Equity, In- come, and/or Expenses. You can use account aliases to rewrite your ac- - count names temporarily, if needed, as in this hledger2beancount.conf + count names temporarily, if needed, as in this hledger2beancount.conf config file. 2024-12-20: Some more things not yet handled for you: - o P directives are not converted automatically - convert those your- + o P directives are not converted automatically - convert those your- self. - o Balance assignments are not converted (Beancount doesn't support + o Balance assignments are not converted (Beancount doesn't support them) - replace those with explicit amounts. Beancount account names - Aside from the top-level names, hledger will adjust your account names - to make valid Beancount account names, by capitalising each part, re- - placing spaces with -, replacing other unsupported characters with - C, prepending A to account name parts which don't begin with - a letter or digit, and appending :A to account names which have only + Aside from the top-level names, hledger will adjust your account names + to make valid Beancount account names, by capitalising each part, re- + placing spaces with -, replacing other unsupported characters with + C, prepending A to account name parts which don't begin with + a letter or digit, and appending :A to account names which have only one part. Beancount commodity names - hledger will adjust your commodity names to make valid Beancount com- + hledger will adjust your commodity names to make valid Beancount com- modity/currency names, which must be 2-24 uppercase letters, digits, or - ', ., _, -, beginning with a letter and ending with a letter or digit. + ', ., _, -, beginning with a letter and ending with a letter or digit. hledger will convert known currency symbols to ISO 4217 currency codes, - capitalise letters, replace spaces with -, replace other unsupported + capitalise letters, replace spaces with -, replace other unsupported characters with C, and prepend or append C if needed. Beancount virtual postings @@ -893,42 +910,42 @@ Output omitted from beancount output. Beancount metadata - hledger tags will be converted to Beancount metadata (except for tags + hledger tags will be converted to Beancount metadata (except for tags whose name begins with _). Metadata names will be adjusted to be Bean- count-compatible: beginning with a lowercase letter, at least two char- - acters long, and with unsupported characters encoded. Metadata values + acters long, and with unsupported characters encoded. Metadata values will use Beancount's string type. - In hledger, objects can have the same tag repeated with multiple val- + In hledger, objects can have the same tag repeated with multiple val- ues. Eg an assets:cash account might have both type:Asset and - type:Cash tags. For Beancount these will be combined into one, with + type:Cash tags. For Beancount these will be combined into one, with the values combined, comma separated. Eg: type: "Asset, Cash". Beancount costs - Beancount doesn't allow redundant costs and conversion postings as - hledger does. If you have any of these, the conversion postings will - be omitted. Currently we support at most one cost + conversion post- + Beancount doesn't allow redundant costs and conversion postings as + hledger does. If you have any of these, the conversion postings will + be omitted. Currently we support at most one cost + conversion post- ings group per transaction. Beancount operating currency - Declaring an operating currency (or several) improves Beancount and - Fava reports. Currently hledger will declare each currency used in - cost amounts as an operating currency. If needed, replace these with + Declaring an operating currency (or several) improves Beancount and + Fava reports. Currently hledger will declare each currency used in + cost amounts as an operating currency. If needed, replace these with your own declaration, like option "operating_currency" "USD" SQL output - SQL output is expected to work at least with SQLite, MySQL and Post- + SQL output is expected to work at least with SQLite, MySQL and Post- gres. - The SQL statements are expected to be executed in the empty database. + The SQL statements are expected to be executed in the empty database. If you already have tables created via SQL output of hledger, you would - probably want to either clear data from these (via delete or truncate - SQL statements) or drop the tables completely before import; otherwise + probably want to either clear data from these (via delete or truncate + SQL statements) or drop the tables completely before import; otherwise your postings would be duplicated. - For SQLite, it is more useful if you modify the generated id field to + For SQLite, it is more useful if you modify the generated id field to be a PRIMARY KEY. Eg: $ hledger print -O sql | sed 's/id serial/id INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL/g' | ... @@ -936,35 +953,36 @@ Output This is not yet much used; feedback is welcome. JSON output - Our JSON is rather large and verbose, since it is a faithful represen- - tation of hledger's internal data types. To understand its structure, - read the Haskell type definitions, which are mostly in + Our JSON is rather large and verbose, since it is a faithful represen- + tation of hledger's internal data types. To understand its structure, + read the Haskell type definitions, which are mostly in https://github.com/simonmichael/hledger/blob/mas- - ter/hledger-lib/Hledger/Data/Types.hs. hledger-web's OpenAPI specifi- + ter/hledger-lib/Hledger/Data/Types.hs. hledger-web's OpenAPI specifi- cation may also be relevant. - hledger stores numbers with sometimes up to 255 significant digits. - This is too many digits for most JSON consumers, so in JSON output we + hledger stores numbers with sometimes up to 255 significant digits. + This is too many digits for most JSON consumers, so in JSON output we round numbers to at most 10 decimal places. (We don't limit the number - of integer digits.) If you find this causing problems, please let us + of integer digits.) If you find this causing problems, please let us know. Related: #1195 This is not yet much used; feedback is welcome. Commodity styles - When displaying amounts, hledger infers a standard display style for + When displaying amounts, hledger infers a standard display style for each commodity/currency, as described below in Commodity display style. If needed, this can be overridden by a -c/--commodity-style option (ex- cept for cost amounts and amounts displayed by the print command, which - are always displayed with all decimal digits). For example, the fol- + are always displayed with all decimal digits). For example, the fol- lowing will force dollar amounts to be displayed as shown: $ hledger print -c '$1.000,0' - 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- - 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 parseability (such as adding trailing decimal marks when needed). @@ -2235,7 +2253,7 @@ Journal 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 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- 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) Commodity directive syntax @@ -5272,57 +5296,64 @@ Time periods day" Depth - With the --depth NUM option (short form: -NUM), reports will show ac- - counts only to the specified depth, hiding deeper subaccounts. Use - this when you want a summary with less detail. This flag has the same - effect as a depth: query argument. So all of these are equivalent: - depth:2, --depth=2, -2. + With the --depth NUM option (short form, usually preferred: -NUM), re- + ports will show accounts only to the specified depth, hiding deeper + subaccounts. Use this when you want a summary with less detail. This + flag has the same effect as a depth: query argument. So all of these + are equivalent: depth:2, --depth=2, -2. - In place of a single number which limits the depth for all accounts, - you can also provide depth limits for specific accounts, by providing a - REGEX=DEPTH argument instead of just a DEPTH (since 1.41). For exam- - ple, --depth assets=2 (or depth:assets=2) will collapse accounts match- - ing the regular expression "assets" to depth 2. So assets:bank:savings + You can also provide custom depths for specific accounts, by providing + a REGEX=NUM argument instead of just NUM (since 1.41). For example, + --depth assets=2 (or depth:assets=2) will collapse accounts matching + the regular expression "assets" to depth 2. So assets:bank:savings would be collapsed to assets:bank, but liabilities:bank:credit card would not be affected. - (If REGEX contains spaces or other special characters, enclose it in - quotes in the usual way. Eg: --depth 'credit card=2') + If REGEX contains spaces or other special characters, enclose it in + quotes in the usual way. Eg: --depth 'credit card=2' - Specific depth options and a general depth option can be combined. Eg - --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. + Combining depth options + If a command line contains multiple general depth options, the last one + wins. (Useful for overriding a depth specified by scripts.) - If an account is matched by more than one regular expression depth ar- - gument, the most specific (deepest) match will be used. For example, - with --depth assets=1 --depth savings=2, assets:bank:savings will be - collapsed to depth 2, not depth 1 (because "savings" matches a deeper - part of it than "assets" does). + Or a command may contain a combination of general and custom depth op- + tions. In this case, the most specifically (deepest) matching option + wins. Some examples: + + 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 - Many hledger commands accept query arguments, which restrict their - scope and let you report on a precise subset of your data. Here's a + Many hledger commands accept query arguments, which restrict their + scope and let you report on a precise subset of your data. Here's a quick overview of hledger's queries: - o By default, a query argument is treated as a case-insensitive sub- + o By default, a query argument is treated as a case-insensitive sub- string pattern for matching account names. Eg: dining groceries car:fuel - o Patterns containing spaces or other special characters must be en- + o Patterns containing spaces or other special characters must be en- closed in single or double quotes: 'personal care' - o Patterns are actually regular expressions, so you can add regexp - metacharacters for more precision (or you may need to backslash-es- + o Patterns are actually regular expressions, so you can add regexp + metacharacters for more precision (or you may need to backslash-es- cape certain characters; see "Regular expressions" above): '^expenses\b' 'food$' 'fuel|repair' 'accounts (payable|receivable)' - o To match something other than the account name, you can add a query + o To match something other than the account name, you can add a query type prefix, such as: date:202312- @@ -5331,28 +5362,28 @@ Queries cur:USD cur:\\$ amt:'>0' - acct:groceries (but acct: is the default, so we usually don't bother + acct:groceries (but acct: is the default, so we usually don't bother writing it) o To negate a query, add a not: prefix: not:status:'*' not:desc:'opening|closing' not:cur:USD - o Multiple query terms can be combined, as space-separated queries Eg: - hledger print date:2022 desc:amazon desc:amzn (show transactions + o Multiple query terms can be combined, as space-separated queries Eg: + hledger print date:2022 desc:amazon desc:amzn (show transactions dated in 2022 whose description contains "amazon" or "amzn"). - o Or more flexibly as boolean queries. Eg: hledger print + o Or more flexibly as boolean queries. Eg: hledger print expr:'date:2022 and (desc:amazon or desc:amzn) and not date:202210' - All hledger commands use the same query language, but different com- - mands may interpret the query in different ways. We haven't described - the commands yet (that's coming in PART 4: COMMANDS below) but here's + All hledger commands use the same query language, but different com- + mands may interpret the query in different ways. We haven't described + the commands yet (that's coming in PART 4: COMMANDS below) but here's the gist of it: - o Transaction-oriented commands (print, aregister, close, import, de- + o Transaction-oriented commands (print, aregister, close, import, de- scriptions..) try to match transactions (including the transaction's postings). - o Posting-oriented commands (register, balance, balancesheet, incomes- + o Posting-oriented commands (register, balance, balancesheet, incomes- tatement, accounts..) try to match postings. Postings inherit their transaction's attributes for querying purposes, so transaction fields like date or description can still be referenced in a posting query. @@ -5365,20 +5396,20 @@ Queries acct: query acct:REGEX, or just REGEX - Match account names containing this case insensitive regular expres- + Match account names containing this case insensitive regular expres- sion. - This is the default query type, so we usually don't bother writing the + This is the default query type, so we usually don't bother writing the "acct:" prefix. amt: query amt:N, amt:'N', amt:'>=N' - Match postings with a single-commodity amount equal to, less than, or - greater than N. (Postings with multi-commodity amounts are not tested - and will always match.) amt: needs quotes to hide the less + Match postings with a single-commodity amount equal to, less than, or + greater than N. (Postings with multi-commodity amounts are not tested + and will always match.) amt: needs quotes to hide the less than/greater than sign from the command line shell. - The comparison has two modes: if N is preceded by a + or - sign (or is - 0), the two signed numbers are compared. Otherwise, the absolute mag- + The comparison has two modes: if N is preceded by a + or - sign (or is + 0), the two signed numbers are compared. Otherwise, the absolute mag- nitudes are compared, ignoring sign. Keep in mind that amt: matches posting amounts, not account balances. @@ -5391,10 +5422,10 @@ Queries cur:REGEX Match postings or transactions including any amounts whose cur- rency/commodity symbol is fully matched by REGEX. (Contrary to - hledger's usual infix matching. To do infix matching, write + hledger's usual infix matching. To do infix matching, write .*REGEX.*.) Note, to match special characters which are regex-signifi- - cant, you need to escape them with \. And for characters which are - significant to your shell you will usually need one more level of es- + cant, you need to escape them with \. And for characters which are + significant to your shell you will usually need one more level of es- caping. Eg to match the dollar sign: cur:\\$ or cur:'\$' desc: query @@ -5403,19 +5434,19 @@ Queries date: query date:PERIODEXPR - Match dates (or with the --date2 flag, secondary dates) within the + Match dates (or with the --date2 flag, secondary dates) within the specified period. PERIODEXPR is a period expression with no report in- terval. Examples: date:2016, date:thismonth, date:2/1-2/15, date:2021-07-27..nextquarter. date2: query date2:PERIODEXPR - If you use secondary dates: this matches secondary dates within the + If you use secondary dates: this matches secondary dates within the specified period. It is not affected by the --date2 flag. depth: query depth:[REGEXP=]N - Match (or display, depending on command) accounts at or above this + Match (or display, depending on command) accounts at or above this depth, optionally only for accounts matching a provided regular expres- sion. See Depth for detailed rules. @@ -5426,7 +5457,7 @@ Queries payee: query payee:REGEX - Match transaction payee/payer names (the part of the description left + Match transaction payee/payer names (the part of the description left of |, or the whole description if there's no |). real: query @@ -5439,18 +5470,18 @@ Queries type: query type:TYPECODES - Match by account type (see Declaring accounts > Account types). TYPE- - CODES is one or more of the single-letter account type codes ALERXCV, + Match by account type (see Declaring accounts > Account types). TYPE- + CODES is one or more of the single-letter account type codes ALERXCV, case insensitive. Note type:A and type:E will also match their respec- - tive subtypes C (Cash) and V (Conversion). Certain kinds of account - alias can disrupt account types, see Rewriting accounts > Aliases and + tive subtypes C (Cash) and V (Conversion). Certain kinds of account + alias can disrupt account types, see Rewriting accounts > Aliases and account types. tag: query tag:NAMEREGEX[=VALREGEX] Match by tag name, and optionally also by tag value. Note: - o Both regular expressions do infix matching. If you need a complete + o Both regular expressions do infix matching. If you need a complete match, use ^ and $. Eg: tag:'^fullname$', tag:'^fullname$=^fullvalue$ @@ -5468,11 +5499,11 @@ Queries not:QUERY You can prepend not: to a query to negate the match. Eg: not:equity, not:desc:apple - (Also, a trick: not:not:... can sometimes solve query problems conve- + (Also, a trick: not:not:... can sometimes solve query problems conve- niently.) Space-separated queries - When given multiple space-separated query terms, most commands select + When given multiple space-separated query terms, most commands select things which match: o any of the description terms AND @@ -5496,84 +5527,84 @@ Queries Boolean queries You can write more complicated "boolean" query expressions, enclosed in quotes and prefixed with expr:. These can combine subqueries with NOT, - AND, OR operators (case insensitive), and parentheses for grouping. + AND, OR operators (case insensitive), and parentheses for grouping. Eg, to show transactions involving both cash and expense accounts: hledger print expr:'cash AND expenses' - The prefix and enclosing quotes are required, so don't write hledger + The prefix and enclosing quotes are required, so don't write hledger print cash AND expenses. That would be a space-separated query showing - transactions involving accounts with any of "cash", "and", "expenses" + transactions involving accounts with any of "cash", "and", "expenses" in their names. - You can write space-separated queries inside a boolean query, and they - will combine as described above, but it might be confusing and best - avoided. Eg these are equivalent, showing transactions involving cash + You can write space-separated queries inside a boolean query, and they + will combine as described above, but it might be confusing and best + avoided. Eg these are equivalent, showing transactions involving cash or expenses accounts: hledger print expr:'cash expenses' hledger print cash expenses - There is a restriction with date: queries: they may not be used inside + There is a restriction with date: queries: they may not be used inside OR expressions. - Actually, there are three types of boolean query: expr: for general + Actually, there are three types of boolean query: expr: for general use, and any: and all: variants which can be useful with print. expr: query expr:'QUERYEXPR' - For example, expr:'date:lastmonth AND NOT (food OR rent)' means "match - things which are dated in the last month and do not have food or rent + For example, expr:'date:lastmonth AND NOT (food OR rent)' means "match + things which are dated in the last month and do not have food or rent in the account name". - When using expr: with transaction-oriented commands like print, post- - ing-oriented query terms like acct: and amt: are considered to match + When using expr: with transaction-oriented commands like print, post- + ing-oriented query terms like acct: and amt: are considered to match the transaction if they match any of its postings. - So, hledger print expr:'cash and amt:>0' means "show transactions with + So, hledger print expr:'cash and amt:>0' means "show transactions with (at least one posting involving a cash account) and (at least one post- ing with a positive amount)". any: query any:'QUERYEXPR' - Like expr:, but when used with transaction-oriented commands like - print, it matches the transaction only if a posting can be matched by + Like expr:, but when used with transaction-oriented commands like + print, it matches the transaction only if a posting can be matched by all of QUERYEXPR. - So, hledger print any:'cash and amt:>0' means "show transactions where + So, hledger print any:'cash and amt:>0' means "show transactions where at least one posting posts a positive amount to a cash account". all: query all:'QUERYEXPR' - Like expr:, but when used with transaction-oriented commands like - print, it matches the transaction only if all postings are matched by + Like expr:, but when used with transaction-oriented commands like + print, it matches the transaction only if all postings are matched by all of QUERYEXPR (and there is at least one posting). - So, hledger print all:'cash and amt:0' means "show transactions where + So, hledger print all:'cash and amt:0' means "show transactions where all postings involve a cash account and have a zero amount". Or, hledger print all:'cash or checking' means "show transactions which touch only cash and/or checking accounts". Queries and command options - Some queries can also be expressed as command-line options: depth:2 is + Some queries can also be expressed as command-line options: depth:2 is equivalent to --depth 2, date:2023 is equivalent to -p 2023, etc. When - you mix command options and query arguments, generally the resulting + you mix command options and query arguments, generally the resulting query is their intersection. Queries and account aliases - When account names are rewritten with --alias or alias, acct: will + When account names are rewritten with --alias or alias, acct: will match either the old or the new account name. Queries and valuation - When amounts are converted to other commodities in cost or value re- - ports, cur: and amt: match the old commodity symbol and the old amount + When amounts are converted to other commodities in cost or value re- + ports, cur: and amt: match the old commodity symbol and the old amount quantity, not the new ones. (Except in hledger 1.22, #1625.) Pivoting - Normally, hledger groups amounts and displays their totals by account - (name). With --pivot PIVOTEXPR, some other field's (or multiple - fields') value is used as a synthetic account name, causing different + Normally, hledger groups amounts and displays their totals by account + (name). With --pivot PIVOTEXPR, some other field's (or multiple + fields') value is used as a synthetic account name, causing different grouping and display. PIVOTEXPR can be - o any of these standard transaction or posting fields (their value is - substituted): status, code, desc, payee, note, acct, comm/cur, amt, + o any of these standard transaction or posting fields (their value is + substituted): status, code, desc, payee, note, acct, comm/cur, amt, cost o or a tag name @@ -5588,7 +5619,7 @@ Pivoting o When pivoting a posting that has multiple values for a tag, the tag's first value will be used as the pivoted value. - o When a posting has multiple commodities, the pivoted value of + o When a posting has multiple commodities, the pivoted value of "comm"/"cur" will be "". Also when an unrecognised tag name or field is provided, its pivoted value will be "". (If this causes confusing output, consider excluding those postings from the report.) @@ -5622,7 +5653,7 @@ Pivoting -------------------- -2 EUR - Another way (the acct: query matches against the pivoted "account + Another way (the acct: query matches against the pivoted "account name"): $ hledger balance --pivot member acct:. @@ -5638,78 +5669,78 @@ Pivoting -2 EUR Generating data - hledger can enrich the data provided to it, or generate new data, in a + hledger can enrich the data provided to it, or generate new data, in a number of ways. Mostly, this is done only if you request it: - o Missing amounts or missing costs in transactions are inferred auto- + o Missing amounts or missing costs in transactions are inferred auto- matically when possible. - o The --infer-equity flag infers missing conversion equity postings + o The --infer-equity flag infers missing conversion equity postings from @/@@ costs. - o The --infer-costs flag infers missing costs from conversion equity + o The --infer-costs flag infers missing costs from conversion equity postings. o The --infer-market-prices flag infers P price directives from costs. - o The --auto flag adds extra postings to transactions matched by auto + o The --auto flag adds extra postings to transactions matched by auto posting rules. - o The --forecast option generates transactions from periodic transac- + o The --forecast option generates transactions from periodic transac- tion rules. - o The balance --budget report infers budget goals from periodic trans- + o The balance --budget report infers budget goals from periodic trans- action rules. - o Commands like close, rewrite, and hledger-interest generate transac- + o Commands like close, rewrite, and hledger-interest generate transac- tions or postings. - o CSV data is converted to transactions by applying CSV conversion + o CSV data is converted to transactions by applying CSV conversion rules.. etc. - Such generated data is temporary, existing only at report time. You - can convert it to permanent recorded data by, eg, capturing the output - of hledger print and saving it in your journal file. This can some- + Such generated data is temporary, existing only at report time. You + can convert it to permanent recorded data by, eg, capturing the output + of hledger print and saving it in your journal file. This can some- times be useful as a data entry aid. - If you are curious what data is being generated and why, run hledger - print -x --verbose-tags. -x/--explicit shows inferred amounts and - --verbose-tags adds tags like generated-transaction (from periodic + If you are curious what data is being generated and why, run hledger + print -x --verbose-tags. -x/--explicit shows inferred amounts and + --verbose-tags adds tags like generated-transaction (from periodic rules) and generated-posting, modified (from auto posting rules). Sim- - ilar hidden tags (with an underscore prefix) are always present, also, - so you can always match such data with queries like tag:generated or + ilar hidden tags (with an underscore prefix) are always present, also, + so you can always match such data with queries like tag:generated or tag:modified. Forecasting - Forecasting, or speculative future reporting, can be useful for esti- + Forecasting, or speculative future reporting, can be useful for esti- mating future balances, or for exploring different future scenarios. The simplest and most flexible way to do it with hledger is to manually record a bunch of future-dated transactions. You could keep these in a - separate future.journal and include that with -f only when you want to + separate future.journal and include that with -f only when you want to see them. --forecast - There is another way: with the --forecast option, hledger can generate - temporary "forecast transactions" for reporting purposes, according to - periodic transaction rules defined in the journal. Each rule can gen- - erate multiple recurring transactions, so by changing one rule you can + There is another way: with the --forecast option, hledger can generate + temporary "forecast transactions" for reporting purposes, according to + periodic transaction rules defined in the journal. Each rule can gen- + erate multiple recurring transactions, so by changing one rule you can change many forecasted transactions. - Forecast transactions usually start after ordinary transactions end. + Forecast transactions usually start after ordinary transactions end. By default, they begin after your latest-dated ordinary transaction, or - today, whichever is later, and they end six months from today. (The + today, whichever is later, and they end six months from today. (The exact rules are a little more complicated, and are given below.) This is the "forecast period", which need not be the same as the report - period. You can override it - eg to forecast farther into the future, + period. You can override it - eg to forecast farther into the future, or to force forecast transactions to overlap your ordinary transactions - - by giving the --forecast option a period expression argument, like - --forecast=..2099 or --forecast=2023-02-15... Note that the = is re- + - by giving the --forecast option a period expression argument, like + --forecast=..2099 or --forecast=2023-02-15... Note that the = is re- quired. Inspecting forecast transactions - print is the best command for inspecting and troubleshooting forecast + print is the best command for inspecting and troubleshooting forecast transactions. Eg: ~ monthly from 2022-12-20 rent @@ -5743,7 +5774,7 @@ Forecasting expenses:rent $1000 Here there are no ordinary transactions, so the forecasted transactions - begin on the first occurrence after today's date. (You won't normally + begin on the first occurrence after today's date. (You won't normally use --today; it's just to make these examples reproducible.) Forecast reports @@ -5767,19 +5798,19 @@ Forecasting || $1000 $1000 $1000 $1000 $1000 Forecast tags - Forecast transactions generated by --forecast have a hidden tag, _gen- - erated-transaction. So if you ever need to match forecast transac- + Forecast transactions generated by --forecast have a hidden tag, _gen- + erated-transaction. So if you ever need to match forecast transac- tions, you could use tag:_generated-transaction (or just tag:generated) in a query. - For troubleshooting, you can add the --verbose-tags flag. Then, visi- + For troubleshooting, you can add the --verbose-tags flag. Then, visi- ble generated-transaction tags will be added also, so you can view them - with the print command. Their value indicates which periodic rule was + with the print command. Their value indicates which periodic rule was responsible. Forecast period, in detail Forecast start/end dates are chosen so as to do something useful by de- - fault in almost all situations, while also being flexible. Here are + fault in almost all situations, while also being flexible. Here are (with luck) the exact rules, to help with troubleshooting: The forecast period starts on: @@ -5811,7 +5842,7 @@ Forecasting o otherwise: 180 days (~6 months) from today. Forecast troubleshooting - When --forecast is not doing what you expect, one of these tips should + When --forecast is not doing what you expect, one of these tips should help: o Remember to use the --forecast option. @@ -5821,22 +5852,22 @@ Forecasting o Test with print --forecast. - o Check for typos or too-restrictive start/end dates in your periodic + o Check for typos or too-restrictive start/end dates in your periodic transaction rule. - o Leave at least 2 spaces between the rule's period expression and de- + o Leave at least 2 spaces between the rule's period expression and de- scription fields. - o Check for future-dated ordinary transactions suppressing forecasted + o Check for future-dated ordinary transactions suppressing forecasted transactions. o Try setting explicit report start and/or end dates with -b, -e, -p or date: - o Try adding the -E flag to encourage display of empty periods/zero + o Try adding the -E flag to encourage display of empty periods/zero transactions. - o Try setting explicit forecast start and/or end dates with --fore- + o Try setting explicit forecast start and/or end dates with --fore- cast=START..END o Consult Forecast period, in detail, above. @@ -5844,13 +5875,13 @@ Forecasting o Check inside the engine: add --debug=2 (eg). Budgeting - With the balance command's --budget report, each periodic transaction - rule generates recurring budget goals in specified accounts, and goals - and actual performance can be compared. See the balance command's doc + With the balance command's --budget report, each periodic transaction + rule generates recurring budget goals in specified accounts, and goals + and actual performance can be compared. See the balance command's doc below. - You can generate budget goals and forecast transactions at the same - time, from the same or different periodic transaction rules: hledger + You can generate budget goals and forecast transactions at the same + time, from the same or different periodic transaction rules: hledger bal -M --budget --forecast ... See also: Budgeting and Forecasting. @@ -5858,17 +5889,17 @@ Budgeting Amount formatting Commodity display style For the amounts in each commodity, hledger chooses a consistent display - style (symbol placement, decimal mark and digit group marks, number of + style (symbol placement, decimal mark and digit group marks, number of decimal digits) to use in most reports. This is inferred as follows: - First, if there's a D directive declaring a default commodity, that - commodity symbol and amount format is applied to all no-symbol amounts + First, if there's a D directive declaring a default commodity, that + commodity symbol and amount format is applied to all no-symbol amounts in the journal. - Then each commodity's display style is determined from its commodity - directive. We recommend always declaring commodities with commodity + Then each commodity's display style is determined from its commodity + directive. We recommend always declaring commodities with commodity directives, since they help ensure consistent display styles and preci- - sions, and bring other benefits such as error checking for commodity + sions, and bring other benefits such as error checking for commodity symbols. Here's an example: # Set display styles (and decimal marks, for parsing, if there is no decimal-mark directive) @@ -5878,9 +5909,9 @@ Amount formatting commodity INR 9,99,99,999.00 commodity 1 000 000.9455 - But for convenience, if a commodity directive is not present, hledger - infers a commodity's display styles from its amounts as they are writ- - ten in the journal (excluding cost amounts and amounts in periodic + But for convenience, if a commodity directive is not present, hledger + infers a commodity's display styles from its amounts as they are writ- + ten in the journal (excluding cost amounts and amounts in periodic transaction rules or auto posting rules). It uses o the symbol placement and decimal mark of the first amount seen @@ -5889,7 +5920,7 @@ Amount formatting o and the maximum number of decimal digits seen across all amounts. - And as fallback if no applicable amounts are found, it would use a de- + And as fallback if no applicable amounts are found, it would use a de- fault style, like $1000.00 (symbol on the left with no space, period as decimal mark, and two decimal digits). @@ -5898,16 +5929,16 @@ Amount formatting Rounding Amounts are stored internally as decimal numbers with up to 255 decimal - places. They are displayed with their original journal precisions by - print and print-like reports, and rounded to their display precision + places. They are displayed with their original journal precisions by + print and print-like reports, and rounded to their display precision (the number of decimal digits specified by the commodity display style) - by other reports. When rounding, hledger uses banker's rounding (it + by other reports. When rounding, hledger uses banker's rounding (it rounds to the nearest even digit). So eg 0.5 displayed with zero deci- mal digits appears as "0". Trailing decimal marks If you're wondering why your print report sometimes shows trailing dec- - imal marks, with no decimal digits; it does this when showing amounts + imal marks, with no decimal digits; it does this when showing amounts that have digit group marks but no decimal digits, to disambiguate them and allow them to be re-parsed reliably (see Decimal marks). Eg: @@ -5921,7 +5952,7 @@ Amount formatting (a) $1,000. If this is a problem (eg when exporting to Ledger), you can avoid it by - disabling digit group marks, eg with -c/--commodity (for each affected + disabling digit group marks, eg with -c/--commodity (for each affected commodity): $ hledger print -c '$1000.00' @@ -5938,19 +5969,19 @@ Amount formatting More generally, hledger output falls into three rough categories, which format amounts a little bit differently to suit different consumers: - 1. "hledger-readable output" - should be readable by hledger (and by + 1. "hledger-readable output" - should be readable by hledger (and by humans) - o This is produced by reports that show full journal entries: print, + o This is produced by reports that show full journal entries: print, import, close, rewrite etc. - o It shows amounts with their original journal precisions, which may + o It shows amounts with their original journal precisions, which may not be consistent from one amount to the next. - o It adds a trailing decimal mark when needed to avoid showing ambigu- + o It adds a trailing decimal mark when needed to avoid showing ambigu- ous amounts. - o It can be parsed reliably (by hledger and ledger2beancount at least, + o It can be parsed reliably (by hledger and ledger2beancount at least, but perhaps not by Ledger..) 2. "human-readable output" - usually for humans @@ -5962,13 +5993,13 @@ Amount formatting o It shows ambiguous amounts unmodified. - o It can be parsed reliably in the context of a known report (when you + o It can be parsed reliably in the context of a known report (when you know decimals are consistently not being shown, you can assume a sin- gle mark is a digit group mark). 3. "machine-readable output" - usually for other software - o This is produced by all reports when an output format like csv, tsv, + o This is produced by all reports when an output format like csv, tsv, json, or sql is selected. o It shows amounts as 1 or 2 do, but without digit group marks. @@ -5978,17 +6009,17 @@ Amount formatting Cost reporting In some transactions - for example a currency conversion, or a purchase - or sale of stock - one commodity is exchanged for another. In these - transactions there is a conversion rate, also called the cost (when - buying) or selling price (when selling). (In hledger docs we just say - "cost" generically for convenience.) With the -B/--cost flag, hledger + or sale of stock - one commodity is exchanged for another. In these + transactions there is a conversion rate, also called the cost (when + buying) or selling price (when selling). (In hledger docs we just say + "cost" generically for convenience.) With the -B/--cost flag, hledger can show amounts "at cost", converted to the cost's commodity. Recording costs - We'll explore several ways of recording transactions involving costs. + We'll explore several ways of recording transactions involving costs. These are also summarised at hledger Cookbook > Cost notation. - Costs can be recorded explicitly in the journal, using the @ UNITCOST + Costs can be recorded explicitly in the journal, using the @ UNITCOST or @@ TOTALCOST notation described in Journal > Costs: Variant 1 @@ -6003,11 +6034,11 @@ Cost reporting assets:dollars $-135 assets:euros 100 @@ $135 ; $135 total cost - Typically, writing the unit cost (variant 1) is preferable; it can be + Typically, writing the unit cost (variant 1) is preferable; it can be more effort, requiring more attention to decimal digits; but it reveals the per-unit cost basis, and makes stock sales easier. - Costs can also be left implicit, and hledger will infer the cost that + Costs can also be left implicit, and hledger will infer the cost that is consistent with a balanced transaction: Variant 3 @@ -6016,49 +6047,49 @@ Cost reporting assets:dollars $-135 assets:euros 100 - Here, hledger will attach a @@ 100 cost to the first amount (you can - see it with hledger print -x). This form looks convenient, but there + Here, hledger will attach a @@ 100 cost to the first amount (you can + see it with hledger print -x). This form looks convenient, but there are downsides: - o It sacrifices some error checking. For example, if you accidentally + o It sacrifices some error checking. For example, if you accidentally wrote 10 instead of 100, hledger would not be able to detect the mis- take. - o It is sensitive to the order of postings - if they were reversed, a + o It is sensitive to the order of postings - if they were reversed, a different entry would be inferred and reports would be different. o The per-unit cost basis is not easy to read. - So generally this kind of entry is not recommended. You can make sure + So generally this kind of entry is not recommended. You can make sure you have none of these by using -s (strict mode), or by running hledger check balanced. Reporting at cost - Now when you add the -B/--cost flag to reports ("B" is from Ledger's - -B/--basis/--cost flag), any amounts which have been annotated with - costs will be converted to their cost's commodity (in the report out- + Now when you add the -B/--cost flag to reports ("B" is from Ledger's + -B/--basis/--cost flag), any amounts which have been annotated with + costs will be converted to their cost's commodity (in the report out- put). Ie they will be displayed "at cost" or "at sale price". Some things to note: - o Costs are attached to specific posting amounts in specific transac- - tions, and once recorded they do not change. This contrasts with + o Costs are attached to specific posting amounts in specific transac- + tions, and once recorded they do not change. This contrasts with market prices, which are ambient and fluctuating. - o Conversion to cost is performed before conversion to market value + o Conversion to cost is performed before conversion to market value (described below). Equity conversion postings - There is a problem with the entries above - they are not conventional - Double Entry Bookkeeping (DEB) notation, and because of the "magical" - transformation of one commodity into another, they cause an imbalance + There is a problem with the entries above - they are not conventional + Double Entry Bookkeeping (DEB) notation, and because of the "magical" + transformation of one commodity into another, they cause an imbalance in the Accounting Equation. This shows up as a non-zero grand total in balance reports like hledger bse. - For most hledger users, this doesn't matter in practice and can safely + For most hledger users, this doesn't matter in practice and can safely be ignored ! But if you'd like to learn more, keep reading. - Conventional DEB uses an extra pair of equity postings to balance the + Conventional DEB uses an extra pair of equity postings to balance the transaction. Of course you can do this in hledger as well: Variant 4 @@ -6069,10 +6100,10 @@ Cost reporting equity:conversion $135 equity:conversion -100 - Now the transaction is perfectly balanced according to standard DEB, + Now the transaction is perfectly balanced according to standard DEB, and hledger bse's total will not be disrupted. - And, hledger can still infer the cost for cost reporting, but it's not + And, hledger can still infer the cost for cost reporting, but it's not done by default - you must add the --infer-costs flag like so: $ hledger print --infer-costs @@ -6094,14 +6125,14 @@ Cost reporting o Instead of -B you must remember to type -B --infer-costs. - o --infer-costs works only where hledger can identify the two eq- - uity:conversion postings and match them up with the two non-equity - postings. So writing the journal entry in a particular format be- + o --infer-costs works only where hledger can identify the two eq- + uity:conversion postings and match them up with the two non-equity + postings. So writing the journal entry in a particular format be- comes more important. More on this below. Inferring equity conversion postings Can we go in the other direction ? Yes, if you have transactions writ- - ten with the @/@@ cost notation, hledger can infer the missing equity + ten with the @/@@ cost notation, hledger can infer the missing equity postings, if you add the --infer-equity flag. Eg: 2022-01-01 @@ -6115,18 +6146,18 @@ Cost reporting equity:conversion:$-: -100 equity:conversion:$-:$ $135.00 - The equity account names will be "equity:conversion:A-B:A" and "eq- - uity:conversion:A-B:B" where A is the alphabetically first commodity + The equity account names will be "equity:conversion:A-B:A" and "eq- + uity:conversion:A-B:B" where A is the alphabetically first commodity symbol. You can customise the "equity:conversion" part by declaring an account with the V/Conversion account type. - Note you will need to add account declarations for these to your jour- + Note you will need to add account declarations for these to your jour- nal, if you use check accounts or check --strict. Combining costs and equity conversion postings Finally, you can use both the @/@@ cost notation and equity postings at - the same time. This in theory gives the best of all worlds - preserv- - ing the accounting equation, revealing the per-unit cost basis, and + the same time. This in theory gives the best of all worlds - preserv- + ing the accounting equation, revealing the per-unit cost basis, and providing more flexibility in how you write the entry: Variant 5 @@ -6137,15 +6168,15 @@ Cost reporting equity:conversion -100 assets:euros 100 @ $1.35 - All the other variants above can (usually) be rewritten to this final + All the other variants above can (usually) be rewritten to this final form with: $ hledger print -x --infer-costs --infer-equity Downsides: - o The precise format of the journal entry becomes more important. If - hledger can't detect and match up the cost and equity postings, it + o The precise format of the journal entry becomes more important. If + hledger can't detect and match up the cost and equity postings, it will give a transaction balancing error. o The add command does not yet accept this kind of entry (#2056). @@ -6153,34 +6184,34 @@ Cost reporting o This is the most verbose form. Requirements for detecting equity conversion postings - --infer-costs has certain requirements (unlike --infer-equity, which + --infer-costs has certain requirements (unlike --infer-equity, which always works). It will infer costs only in transactions with: - o Two non-equity postings, in different commodities. Their order is + o Two non-equity postings, in different commodities. Their order is significant: the cost will be added to the first of them. - o Two postings to equity conversion accounts, next to one another, + o Two postings to equity conversion accounts, next to one another, which balance the two non-equity postings. This balancing is checked - to the same precision (number of decimal places) used in the conver- + to the same precision (number of decimal places) used in the conver- sion posting's amount. Equity conversion accounts are: o any accounts declared with account type V/Conversion, or their sub- accounts - o otherwise, accounts named equity:conversion, equity:trade, or eq- + o otherwise, accounts named equity:conversion, equity:trade, or eq- uity:trading, or their subaccounts. - And multiple such four-posting groups can coexist within a single - transaction. When --infer-costs fails, it does not infer a cost in - that transaction, and does not raise an error (ie, it infers costs + And multiple such four-posting groups can coexist within a single + transaction. When --infer-costs fails, it does not infer a cost in + that transaction, and does not raise an error (ie, it infers costs where it can). - Reading variant 5 journal entries, combining cost notation and equity - postings, has all the same requirements. When reading such an entry + Reading variant 5 journal entries, combining cost notation and equity + postings, has all the same requirements. When reading such an entry fails, hledger raises an "unbalanced transaction" error. Infer cost and equity by default ? - Should --infer-costs and --infer-equity be enabled by default ? Try + Should --infer-costs and --infer-equity be enabled by default ? Try using them always, eg with a shell alias: alias h="hledger --infer-equity --infer-costs" @@ -6188,102 +6219,102 @@ Cost reporting and let us know what problems you find. Value reporting - hledger can also show amounts "at market value", converted to some - other commodity using the market price or conversion rate on a certain + hledger can also show amounts "at market value", converted to some + other commodity using the market price or conversion rate on a certain date. - This is controlled by the --value=TYPE[,COMMODITY] option. We also - provide simpler -V and -X COMMODITY aliases for this, which are often + This is controlled by the --value=TYPE[,COMMODITY] option. We also + provide simpler -V and -X COMMODITY aliases for this, which are often sufficient. The market prices are declared with a special P directive, and/or they can be inferred from the costs recorded in transactions, by using the --infer-market-prices flag. -V: Value - The -V/--market flag converts amounts to market value in their default + The -V/--market flag converts amounts to market value in their default valuation commodity, using the market prices in effect on the valuation date(s), if any. More on these in a minute. -X: Value in specified commodity The -X/--exchange=COMM option is like -V, except you tell it which cur- - rency you want to convert to, and it tries to convert everything to + rency you want to convert to, and it tries to convert everything to that. Valuation date - Market prices can change from day to day. hledger will use the prices - on a particular valuation date (or on more than one date). By default + Market prices can change from day to day. hledger will use the prices + on a particular valuation date (or on more than one date). By default hledger uses "end" dates for valuation. More specifically: - o For single period reports (including normal print and register re- + o For single period reports (including normal print and register re- ports): o If an explicit report end date is specified, that is used. - o Otherwise the latest transaction date or non-future P directive + o Otherwise the latest transaction date or non-future P directive date is used. o For multiperiod reports, each period is valued on its last day. - This can be customised with the --value option described below, which + This can be customised with the --value option described below, which can select either "then", "end", "now", or "custom" dates. Finding market price - To convert a commodity A to its market value in another commodity B, - hledger looks for a suitable market price (exchange rate) as follows, + To convert a commodity A to its market value in another commodity B, + hledger looks for a suitable market price (exchange rate) as follows, in this order of preference: - 1. A declared market price or inferred market price: A's latest market + 1. A declared market price or inferred market price: A's latest market price in B on or before the valuation date as declared by a P direc- tive, or (with the --infer-market-prices flag) inferred from costs. 2. A reverse market price: the inverse of a declared or inferred market price from B to A. - 3. A forward chain of market prices: a synthetic price formed by com- + 3. A forward chain of market prices: a synthetic price formed by com- bining the shortest chain of "forward" (only 1 above) market prices, leading from A to B. - 4. Any chain of market prices: a chain of any market prices, including - both forward and reverse prices (1 and 2 above), leading from A to + 4. Any chain of market prices: a chain of any market prices, including + both forward and reverse prices (1 and 2 above), leading from A to B. - There is a limit to the length of these price chains; if hledger - reaches that length without finding a complete chain or exhausting all - possibilities, it will give up (with a "gave up" message visible in + There is a limit to the length of these price chains; if hledger + reaches that length without finding a complete chain or exhausting all + possibilities, it will give up (with a "gave up" message visible in --debug=2 output). That limit is currently 1000. - Amounts for which no suitable market price can be found, are not con- + Amounts for which no suitable market price can be found, are not con- verted. --infer-market-prices: market prices from transactions Normally, market value in hledger is fully controlled by, and requires, P directives in your journal. Since adding and updating those can be a - chore, and since transactions usually take place at close to market - value, why not use the recorded costs as additional market prices (as - Ledger does) ? Adding the --infer-market-prices flag to -V, -X or + chore, and since transactions usually take place at close to market + value, why not use the recorded costs as additional market prices (as + Ledger does) ? Adding the --infer-market-prices flag to -V, -X or --value enables this. - So for example, hledger bs -V --infer-market-prices will get market - prices both from P directives and from transactions. If both occur on + So for example, hledger bs -V --infer-market-prices will get market + prices both from P directives and from transactions. If both occur on the same day, the P directive takes precedence. There is a downside: value reports can sometimes be affected in confus- - ing/undesired ways by your journal entries. If this happens to you, - read all of this Value reporting section carefully, and try adding + ing/undesired ways by your journal entries. If this happens to you, + read all of this Value reporting section carefully, and try adding --debug or --debug=2 to troubleshoot. --infer-market-prices can infer market prices from: o multicommodity transactions with explicit prices (@/@@) - o multicommodity transactions with implicit prices (no @, two commodi- - ties, unbalanced). (With these, the order of postings matters. + o multicommodity transactions with implicit prices (no @, two commodi- + ties, unbalanced). (With these, the order of postings matters. hledger print -x can be useful for troubleshooting.) o multicommodity transactions with equity postings, if cost is inferred with --infer-costs. - There is a limitation (bug) currently: when a valuation commodity is - not specified, prices inferred with --infer-market-prices do not help + There is a limitation (bug) currently: when a valuation commodity is + not specified, prices inferred with --infer-market-prices do not help select a default valuation commodity, as P prices would. So conversion might not happen because no valuation commodity was detected (--debug=2 will show this). To be safe, specify the valuation commmodity, eg: @@ -6293,8 +6324,8 @@ Value reporting o --value=then,EUR --infer-market-prices, not --value=then --infer-mar- ket-prices - Signed costs and market prices can be confusing. For reference, here - is the current behaviour, since hledger 1.25. (If you think it should + Signed costs and market prices can be confusing. For reference, here + is the current behaviour, since hledger 1.25. (If you think it should work differently, see #1870.) 2022-01-01 Positive Unit prices @@ -6324,7 +6355,7 @@ Value reporting b B -1 @@ A -1 All of the transactions above are considered balanced (and on each day, - the two transactions are considered equivalent). Here are the market + the two transactions are considered equivalent). Here are the market prices inferred for B: $ hledger -f- --infer-market-prices prices @@ -6337,34 +6368,34 @@ Value reporting Valuation commodity When you specify a valuation commodity (-X COMM or --value TYPE,COMM): - hledger will convert all amounts to COMM, wherever it can find a suit- + hledger will convert all amounts to COMM, wherever it can find a suit- able market price (including by reversing or chaining prices). - When you leave the valuation commodity unspecified (-V or --value + When you leave the valuation commodity unspecified (-V or --value TYPE): - For each commodity A, hledger picks a default valuation commodity as + For each commodity A, hledger picks a default valuation commodity as follows, in this order of preference: 1. The price commodity from the latest P-declared market price for A on or before valuation date. 2. The price commodity from the latest P-declared market price for A on - any date. (Allows conversion to proceed when there are inferred + any date. (Allows conversion to proceed when there are inferred prices before the valuation date.) - 3. If there are no P directives at all (any commodity or date) and the - --infer-market-prices flag is used: the price commodity from the + 3. If there are no P directives at all (any commodity or date) and the + --infer-market-prices flag is used: the price commodity from the latest transaction-inferred price for A on or before valuation date. This means: - o If you have P directives, they determine which commodities -V will + o If you have P directives, they determine which commodities -V will convert, and to what. - o If you have no P directives, and use the --infer-market-prices flag, + o If you have no P directives, and use the --infer-market-prices flag, costs determine it. - Amounts for which no valuation commodity can be found are not con- + Amounts for which no valuation commodity can be found are not con- verted. --value: Flexible valuation @@ -6381,26 +6412,26 @@ Value reporting The TYPE part selects cost or value and valuation date: --value=then - Convert amounts to their value in the default valuation commod- + Convert amounts to their value in the default valuation commod- ity, using market prices on each posting's date. --value=end - Convert amounts to their value in the default valuation commod- - ity, using market prices on the last day of the report period - (or if unspecified, the journal's end date); or in multiperiod + Convert amounts to their value in the default valuation commod- + ity, using market prices on the last day of the report period + (or if unspecified, the journal's end date); or in multiperiod reports, market prices on the last day of each subperiod. --value=now - Convert amounts to their value in the default valuation commod- - ity using current market prices (as of when report is gener- + Convert amounts to their value in the default valuation commod- + ity using current market prices (as of when report is gener- ated). --value=YYYY-MM-DD - Convert amounts to their value in the default valuation commod- + Convert amounts to their value in the default valuation commod- ity using market prices on this date. To select a different valuation commodity, add the optional ,COMM part: - a comma, then the target commodity's symbol. Eg: --value=now,EUR. + a comma, then the target commodity's symbol. Eg: --value=now,EUR. hledger will do its best to convert amounts to this commodity, deducing market prices as described above. @@ -6428,13 +6459,13 @@ Value reporting $ hledger -f t.j bal -N euros -V -e 2016/11/4 $110.00 assets:euros - What are they worth after 2016/12/21 ? (no report end date specified, + What are they worth after 2016/12/21 ? (no report end date specified, defaults to today) $ hledger -f t.j bal -N euros -V $103.00 assets:euros - Here are some examples showing the effect of --value, as seen with + Here are some examples showing the effect of --value, as seen with print: P 2000-01-01 A 1 B @@ -6472,7 +6503,7 @@ Value reporting 2000-02-01 (a) 2 B - With no report period specified, the latest transaction date or price + With no report period specified, the latest transaction date or price date is used as valuation date (2000-04-01): $ hledger -f- print --value=end @@ -6510,7 +6541,7 @@ Value reporting (a) 1 B Interaction of valuation and queries - When matching postings based on queries in the presence of valuation, + When matching postings based on queries in the presence of valuation, the following happens: 1. The query is separated into two parts: @@ -6524,14 +6555,14 @@ Value reporting 3. Valuation is applied to the postings. - 4. The postings are matched to the other parts of the query based on + 4. The postings are matched to the other parts of the query based on post-valued amounts. Related: #1625 Effect of valuation on reports - Here is a reference for how valuation is supposed to affect each part - of hledger's reports. It may be useful when troubleshooting. If you + Here is a reference for how valuation is supposed to affect each part + of hledger's reports. It may be useful when troubleshooting. If you find problems, please report them, ideally with a reproducible example. Related: #329, #1083. @@ -6539,29 +6570,29 @@ Value reporting cost calculated using price(s) recorded in the transaction(s). - value market value using available market price declarations, or the + value market value using available market price declarations, or the unchanged amount if no conversion rate can be found. report start - the first day of the report period specified with -b or -p or + the first day of the report period specified with -b or -p or date:, otherwise today. report or journal start - the first day of the report period specified with -b or -p or - date:, otherwise the earliest transaction date in the journal, + the first day of the report period specified with -b or -p or + date:, otherwise the earliest transaction date in the journal, otherwise today. report end - the last day of the report period specified with -e or -p or + the last day of the report period specified with -e or -p or date:, otherwise today. report or journal end - the last day of the report period specified with -e or -p or - date:, otherwise the latest transaction date in the journal, + the last day of the report period specified with -e or -p or + date:, otherwise the latest transaction date in the journal, otherwise today. report interval - a flag (-D/-W/-M/-Q/-Y) or period expression that activates the + a flag (-D/-W/-M/-Q/-Y) or period expression that activates the report's multi-period mode (whether showing one or many subperi- ods). @@ -6569,8 +6600,8 @@ Value reporting type --value=now -------------------------------------------------------------------------------------------- print - posting cost value at re- value at posting value at re- value at - amounts port end or date port or DATE/today + posting cost value at re- value at posting value at re- value at + amounts port end or date port or DATE/today today journal end balance unchanged unchanged unchanged unchanged unchanged asser- @@ -6586,7 +6617,7 @@ Value reporting (-H) with port or posting was made port or report journal journal interval start start - posting cost value at re- value at posting value at re- value at + posting cost value at re- value at posting value at re- value at amounts port or date port or DATE/today journal end journal end summary summarised value at pe- sum of postings value at pe- value at @@ -6602,8 +6633,8 @@ Value reporting balance (bs, bse, cf, is) - balance sums of value at re- value at posting value at re- value at - changes costs port end or date port or DATE/today of + balance sums of value at re- value at posting value at re- value at + changes costs port end or date port or DATE/today of today of journal end sums of post- sums of of sums of ings postings postings @@ -6611,7 +6642,7 @@ Value reporting amounts changes changes changes ances changes (--bud- get) - grand to- sum of dis- sum of dis- sum of displayed sum of dis- sum of dis- + grand to- sum of dis- sum of dis- sum of displayed sum of dis- sum of dis- tal played val- played val- valued played val- played values ues ues ues @@ -6637,7 +6668,7 @@ Value reporting end bal- sums of same as sums of values of period end value at ances costs of --value=end postings from be- balances, DATE/today of (bal -H, postings fore period start valued at sums of post- - is --H, from before to period end at period ends ings + is --H, from before to period end at period ends ings bs, cf) report start respective post- to period ing dates end @@ -6646,10 +6677,10 @@ Value reporting (--bud- balances balances ances balances get) row to- sums, aver- sums, aver- sums, averages of sums, aver- sums, aver- - tals, row ages of dis- ages of dis- displayed values ages of dis- ages of dis- + tals, row ages of dis- ages of dis- displayed values ages of dis- ages of dis- averages played val- played val- played val- played values (-T, -A) ues ues ues - column sums of dis- sums of dis- sums of displayed sums of dis- sums of dis- + column sums of dis- sums of dis- sums of displayed sums of dis- sums of dis- totals played val- played val- values played val- played values ues ues ues grand to- sum, average sum, average sum, average of sum, average sum, average @@ -6666,10 +6697,10 @@ PART 4: COMMANDS hledger. If you have installed more add-on commands, they also will be listed. - In the following command docs, each command's specific options are + In the following command docs, each command's specific options are shown. Most commands also support the general options described above, though some of them might have no effect. (Usually if there's a sensi- - ble way for a general option to affect a command, it will.) You can + ble way for a general option to affect a command, it will.) You can list all of a command's options by running hledger CMD -h. Help commands @@ -6724,7 +6755,7 @@ PART 4: COMMANDS o aregister (areg) - show transactions in a particular account - o register (reg) - show postings in one or more accounts & running to- + o register (reg) - show postings in one or more accounts & running to- tal o balancesheet (bs) - show assets, liabilities and net worth @@ -6777,16 +6808,16 @@ Help commands -s --speed=SPEED playback speed (1 is original speed, .5 is half, 2 is double, etc (default: 2)) - Run this command with no argument to list the demos. To play a demo, + Run this command with no argument to list the demos. To play a demo, write its number or a prefix or substring of its title. Tips: Make your terminal window large enough to see the demo clearly. - Use the -s/--speed SPEED option to set your preferred playback speed, + Use the -s/--speed SPEED option to set your preferred playback speed, eg -s4 to play at 4x original speed or -s.5 to play at half speed. The default speed is 2x. - During playback, several keys are available: SPACE to pause/unpause, . + During playback, several keys are available: SPACE to pause/unpause, . to step forward (while paused), CTRL-c quit. Examples: @@ -6798,7 +6829,7 @@ Help commands This command is experimental: there aren't many useful demos yet. help - Show the hledger user manual with info, man, or a pager. With a (case + Show the hledger user manual with info, man, or a pager. With a (case insensitive) TOPIC argument, try to open it at that section heading. Flags: @@ -6807,23 +6838,23 @@ Help commands -p show the manual with $PAGER or less (less is always used if TOPIC is specified) - This command shows the hledger manual built in to your hledger exe- - cutable. It can be useful when offline, or when you prefer the termi- + This command shows the hledger manual built in to your hledger exe- + cutable. It can be useful when offline, or when you prefer the termi- nal to a web browser, or when the appropriate hledger manual or viewers are not installed properly on your system. - By default it chooses the best viewer found in $PATH, trying in this - order: info, man, $PAGER, less, more, stdout. (If a TOPIC is speci- - fied, $PAGER and more are not tried.) You can force the use of info, - man, or a pager with the -i, -m, or -p flags. If no viewer can be - found, or if running non-interactively, it just prints the manual to + By default it chooses the best viewer found in $PATH, trying in this + order: info, man, $PAGER, less, more, stdout. (If a TOPIC is speci- + fied, $PAGER and more are not tried.) You can force the use of info, + man, or a pager with the -i, -m, or -p flags. If no viewer can be + found, or if running non-interactively, it just prints the manual to stdout. - When using info, TOPIC can match either the full heading or a prefix. + When using info, TOPIC can match either the full heading or a prefix. If your info --version is < 6, you'll need to upgrade it, eg with 'brew install texinfo' on mac. - When using man or less, TOPIC must match the full heading. For a pre- + When using man or less, TOPIC must match the full heading. For a pre- fix match, you can write 'TOPIC.*'. Examples @@ -6835,7 +6866,7 @@ Help commands User interface commands repl - Start an interactive prompt, where you can run any of hledger's com- + Start an interactive prompt, where you can run any of hledger's com- mands. Data files are parsed just once, so the commands run faster. Flags: @@ -6843,21 +6874,21 @@ User interface commands This command is experimental and could change in the future. - hledger repl starts a read-eval-print loop (REPL) where you can enter - commands interactively. As with the run command, each input file (or + hledger repl starts a read-eval-print loop (REPL) where you can enter + commands interactively. As with the run command, each input file (or each input file/input options combination) is parsed just once, so com- - mands will run more quickly than if you ran them individually at the + mands will run more quickly than if you ran them individually at the command line. Also like run, the input file(s) specified for the repl command will be - the default input for all interactive commands. You can override this - temporarily by specifying an -f option in particular commands. But - note that commands will not see any changes made to input files (eg by + the default input for all interactive commands. You can override this + temporarily by specifying an -f option in particular commands. But + note that commands will not see any changes made to input files (eg by add) until you exit and restart the REPL. The command syntax is the same as with run: - o enter one hledger command at a time, without the usual hledger first + o enter one hledger command at a time, without the usual hledger first word o empty lines and comment text from # to end of line are ignored @@ -6866,7 +6897,7 @@ User interface commands o type exit or quit or control-D to exit the REPL. - While it is running, the REPL remembers your command history, and you + While it is running, the REPL remembers your command history, and you can navigate in the usual ways: o Keypad or Emacs navigation keys to edit the current command line @@ -6877,9 +6908,9 @@ User interface commands o TAB to complete file paths. - Generally repl command lines should feel much like the normal hledger - CLI, but you may find differences. repl is a little stricter; eg it - requires full command names or official abbreviations (as seen in the + Generally repl command lines should feel much like the normal hledger + CLI, but you may find differences. repl is a little stricter; eg it + requires full command names or official abbreviations (as seen in the commands list). The commands and help commands, and the command help flags (CMD --tldr, @@ -6888,7 +6919,7 @@ User interface commands You can type control-C to cancel a long-running command (but only once; typing it a second time will exit the REPL). - And in most shells you can type control-Z to temporarily exit to the + And in most shells you can type control-Z to temporarily exit to the shell (and then fg to return to the REPL). Examples @@ -6918,8 +6949,8 @@ User interface commands ... run - Run a sequence of hledger commands, provided as files or command line - arguments. Data files are parsed just once, so the commands run + Run a sequence of hledger commands, provided as files or command line + arguments. Data files are parsed just once, so the commands run faster. Flags: @@ -6929,52 +6960,52 @@ User interface commands You can use run in three ways: - o hledger run -- CMD1 -- CMD2 -- CMD3 - read commands from the command + o hledger run -- CMD1 -- CMD2 -- CMD3 - read commands from the command line, separated by -- - o hledger run SCRIPTFILE1 SCRIPTFILE2 - read commands from one or more + o hledger run SCRIPTFILE1 SCRIPTFILE2 - read commands from one or more files o cat SCRIPTFILE1 | hledger run - read commands from standard input. run first loads the input file(s) specified by LEDGER_FILE or by -f op- tions, in the usual way. Then it runs each command in turn, each using - the same input data. But if you want a particular command to use dif- - ferent input, you can specify an -f option within that command. This + the same input data. But if you want a particular command to use dif- + ferent input, you can specify an -f option within that command. This will override (not add to) the default input, just for that command. Each input file (more precisely, each combination of input file and in- - put options) is parsed only once. This means that commands will not - see any changes made to these files, until the next run. But the com- - mands will run more quickly than if run individually (typically about + put options) is parsed only once. This means that commands will not + see any changes made to these files, until the next run. But the com- + mands will run more quickly than if run individually (typically about twice as fast). Command scripts, whether in a file or written on the command line, have a simple syntax: - o each line may contain a single hledger command and its arguments, + o each line may contain a single hledger command and its arguments, without the usual hledger first word o empty lines are ignored o text from # to end of line is a comment, and ignored - o you can use single or double quotes to quote arguments when needed, + o you can use single or double quotes to quote arguments when needed, as on the command line - o these extra commands are available: echo TEXT prints some text, and + o these extra commands are available: echo TEXT prints some text, and exit or quit ends the run. - On unix systems you can use #!/usr/bin/env hledger run in the first - line of a command file to make it a runnable script. If that gives an + On unix systems you can use #!/usr/bin/env hledger run in the first + line of a command file to make it a runnable script. If that gives an error, use #!/usr/bin/env -S hledger run. It's ok to use the run command recursively within a command script. - You may find some differences in behaviour between run command lines - and normal hledger command lines. run is a little stricter; eg it re- - quires full command names or official abbreviations (as seen in the - commands list), and command options must be written after the command + You may find some differences in behaviour between run command lines + and normal hledger command lines. run is a little stricter; eg it re- + quires full command names or official abbreviations (as seen in the + commands list), and command options must be written after the command name. Examples @@ -6982,8 +7013,8 @@ User interface commands hledger -f some.journal run -- balance assets --depth 2 -- balance liabilities -f /some/other.journal --depth 3 --transpose -- stats - This would load some.journal, run balance assets --depth 2 on it, then - run balance liabilities --depth 3 --transpose on /some/other.journal, + This would load some.journal, run balance assets --depth 2 on it, then + run balance liabilities --depth 3 --transpose on /some/other.journal, and finally run stats on some.journal Run commands from standard input: @@ -7025,30 +7056,30 @@ Data entry commands Flags: --no-new-accounts don't allow creating new accounts - Many hledger users edit their journals directly with a text editor, or - generate them from CSV. For more interactive data entry, there is the - add command, which prompts interactively on the console for new trans- - actions, and appends them to the main journal file (which should be in - journal format). Existing transactions are not changed. This is one - of the few hledger commands that writes to the journal file (see also + Many hledger users edit their journals directly with a text editor, or + generate them from CSV. For more interactive data entry, there is the + add command, which prompts interactively on the console for new trans- + actions, and appends them to the main journal file (which should be in + journal format). Existing transactions are not changed. This is one + of the few hledger commands that writes to the journal file (see also import). To use it, just run hledger add and follow the prompts. You can add as - many transactions as you like; when you are finished, enter . or press + many transactions as you like; when you are finished, enter . or press control-d or control-c to exit. Features: - o add tries to provide useful defaults, using the most similar (by de- - scription) recent transaction (filtered by the query, if any) as a + o add tries to provide useful defaults, using the most similar (by de- + scription) recent transaction (filtered by the query, if any) as a template. o You can also set the initial defaults with command line arguments. o Readline-style edit keys can be used during data entry. - o The tab key will auto-complete whenever possible - accounts, pay- - ees/descriptions, dates (yesterday, today, tomorrow). If the input + o The tab key will auto-complete whenever possible - accounts, pay- + ees/descriptions, dates (yesterday, today, tomorrow). If the input area is empty, it will insert the default value. o A parenthesised transaction code may be entered following a date. @@ -7057,18 +7088,18 @@ Data entry commands o If you make a mistake, enter < at any prompt to go one step backward. - o Input prompts are displayed in a different colour when the terminal + o Input prompts are displayed in a different colour when the terminal supports it. Notes: o If you enter a number with no commodity symbol, and you have declared - a default commodity with a D directive, you might expect add to add - this symbol for you. It does not do this; we assume that if you are - using a D directive you prefer not to see the commodity symbol re- + a default commodity with a D directive, you might expect add to add + this symbol for you. It does not do this; we assume that if you are + using a D directive you prefer not to see the commodity symbol re- peated on amounts in the journal. - o add creates entries in journal format; it won't work with timeclock + o add creates entries in journal format; it won't work with timeclock or timedot files. Examples: @@ -7089,44 +7120,44 @@ Data entry commands There is a detailed tutorial at https://hledger.org/add.html. add and balance assertions - Since hledger 1.43, whenever you enter a posting amount, add will - re-check all balance assertions in the journal, and if any of them + Since hledger 1.43, whenever you enter a posting amount, add will + re-check all balance assertions in the journal, and if any of them fail, it will report the problem and ask for the amount again. - You can also add a new balance assertion, following the amount as in + You can also add a new balance assertion, following the amount as in journal format. - The new transaction's date, and the new posting's posting date if any - (entered in a comment following the amount), will influence assertion + The new transaction's date, and the new posting's posting date if any + (entered in a comment following the amount), will influence assertion checking. - You can use -I/--ignore-assertions to disable assertion checking tem- + You can use -I/--ignore-assertions to disable assertion checking tem- porarily. add and balance assignments - Balance assignments are not recalculated during a hledger add session. + Balance assignments are not recalculated during a hledger add session. When add runs, it sees the journal with all balance assignments already - processed and converted to assertions. So if you add a new posting + processed and converted to assertions. So if you add a new posting which is dated earlier than a balance assignment, it will break the as- sertion and be rejected. You can make it work by using hledger add -I. import - Import new transactions from one or more data files to the main jour- + Import new transactions from one or more data files to the main jour- nal. Flags: --catchup just mark all transactions as already imported --dry-run just show the transactions to be imported - This command detects new transactions in one or more data files speci- + This command detects new transactions in one or more data files speci- fied as arguments, and appends them to the main journal. - You can import from any input file format hledger supports, but + You can import from any input file format hledger supports, but CSV/SSV/TSV files, downloaded from financial institutions, are the most common import source. - The import destination is the default journal file, or another speci- - fied in the usual way with $LEDGER_FILE or -f/--file. It should be in + The import destination is the default journal file, or another speci- + fied in the usual way with $LEDGER_FILE or -f/--file. It should be in journal format. Examples: @@ -7136,44 +7167,44 @@ Data entry commands $ hledger import *.csv Import dry run - It's useful to preview the import by running first with --dry-run, to + It's useful to preview the import by running first with --dry-run, to sanity check the range of dates being imported, and to check the effect of your conversion rules if converting from CSV. Eg: $ hledger import bank.csv --dry-run The dry run output is valid journal format, so hledger can re-parse it. - If the output is large, you could show just the uncategorised transac- + If the output is large, you could show just the uncategorised transac- tions like so: $ hledger import --dry-run bank.csv | hledger -f- -I print unknown - You could also run this repeatedly to see the effect of edits to your + You could also run this repeatedly to see the effect of edits to your conversion rules: $ watchexec -- "hledger import --dry-run bank.csv | hledger -f- -I print unknown" - Once the conversion and dates look good enough to import to your jour- + Once the conversion and dates look good enough to import to your jour- nal, perhaps with some manual fixups to follow, you would do the actual import: $ hledger import bank.csv Overlap detection - Reading CSV files is built in to hledger, and not specific to import; - so you could also import by doing hledger -f bank.csv print + Reading CSV files is built in to hledger, and not specific to import; + so you could also import by doing hledger -f bank.csv print >>$LEDGER_FILE. - But import is easier and provides some advantages. The main one is - that it avoids re-importing transactions it has seen on previous runs. + But import is easier and provides some advantages. The main one is + that it avoids re-importing transactions it has seen on previous runs. This means you don't have to worry about overlapping data in successive - downloads of your bank CSV; just download and import as often as you + downloads of your bank CSV; just download and import as often as you like, and only the new transactions will be imported each time. - We don't call this "deduplication", as it's generally not possible to - reliably detect duplicates in bank CSV. Instead, import remembers the - latest date processed previously in each CSV file (saving it in a hid- - den file), and skips any records prior to that date. This works well + We don't call this "deduplication", as it's generally not possible to + reliably detect duplicates in bank CSV. Instead, import remembers the + latest date processed previously in each CSV file (saving it in a hid- + den file), and skips any records prior to that date. This works well for most real-world CSV, where: 1. the data file name is stable (does not change) across imports @@ -7184,114 +7215,114 @@ Data entry commands 4. the newest items have the newest dates - (Occasional violations of 2-4 are often harmless; you can reduce the + (Occasional violations of 2-4 are often harmless; you can reduce the chance of disruption by downloading and importing more often.) - Overlap detection is automatic, and shouldn't require much attention - from you, except perhaps at first import (see below). But here's how + Overlap detection is automatic, and shouldn't require much attention + from you, except perhaps at first import (see below). But here's how it works: o For each FILE being imported from: - 1. hledger reads a file named .latest.FILE file in the same direc- - tory, if any. This file contains the latest record date previ- - ously imported from FILE, in YYYY-MM-DD format. If multiple - records with that date were imported, the date is repeated on N + 1. hledger reads a file named .latest.FILE file in the same direc- + tory, if any. This file contains the latest record date previ- + ously imported from FILE, in YYYY-MM-DD format. If multiple + records with that date were imported, the date is repeated on N lines. - 2. hledger reads records from FILE. If a latest date was found in - step 1, any records before that date, and the first N records on + 2. hledger reads records from FILE. If a latest date was found in + step 1, any records before that date, and the first N records on that date, are skipped. - o After a successful import from all FILEs, without error and without + o After a successful import from all FILEs, without error and without --dry-run, hledger updates each FILE's .latest.FILE for next time. If this goes wrong, it's relatively easy to repair: - o You'll notice it before import when you preview with import + o You'll notice it before import when you preview with import --dry-run. - o Or after import when you try to reconcile your hledger account bal- + o Or after import when you try to reconcile your hledger account bal- ances with your bank. - o hledger print -f FILE.csv will show all recently downloaded transac- + o hledger print -f FILE.csv will show all recently downloaded transac- tions. Compare these with your journal. Copy/paste if needed. o Update your conversion rules and print again, if needed. - o You can manually update or remove the .latest file, or use import + o You can manually update or remove the .latest file, or use import --catchup FILE. - o Download and import more often, eg twice a week, at least while you - are learning. It's easier to review and troubleshoot when there are + o Download and import more often, eg twice a week, at least while you + are learning. It's easier to review and troubleshoot when there are fewer transactions. First import - The first time you import from a file, when no corresponding .latest + The first time you import from a file, when no corresponding .latest file has been created yet, all of the records will be imported. - But perhaps you have been entering the data manually, so you know that + But perhaps you have been entering the data manually, so you know that all of these transactions are already recorded in the journal. In this - case you can run hledger import --catchup once. This will create a - .latest file containing the latest CSV record date, so that none of + case you can run hledger import --catchup once. This will create a + .latest file containing the latest CSV record date, so that none of those records will be re-imported. - Or, if you know that some but not all of the transactions are in the - journal, you can create the .latest file yourself. Eg, let's say you - previously recorded foobank transactions up to 2024-10-31 in the jour- - nal. Then in the directory where you'll be saving foobank.csv, you + Or, if you know that some but not all of the transactions are in the + journal, you can create the .latest file yourself. Eg, let's say you + previously recorded foobank transactions up to 2024-10-31 in the jour- + nal. Then in the directory where you'll be saving foobank.csv, you would create a .latest.foobank.csv file containing 2024-10-31 - Or if you had three foobank transactions recorded with that date, you + Or if you had three foobank transactions recorded with that date, you would repeat the date that many times: 2024-10-31 2024-10-31 2024-10-31 - Then hledger import foobank.csv [--dry-run] will import only the newer + Then hledger import foobank.csv [--dry-run] will import only the newer records. Importing balance assignments - Journal entries added by import will have all posting amounts made ex- + Journal entries added by import will have all posting amounts made ex- plicit (like print -x). - This means that any balance assignments in the imported entries would - need to be evaluated. But this generally isn't possible, as the main + This means that any balance assignments in the imported entries would + need to be evaluated. But this generally isn't possible, as the main file's account balances are not visible during import. So try to avoid generating balance assignments with your CSV rules, or importing from a - journal that contains balance assignments. (Balance assignments are + journal that contains balance assignments. (Balance assignments are best avoided anyway.) - But if you must use them, eg because your CSV includes only balances: - you can import with print, which leaves implicit amounts implicit. + But if you must use them, eg because your CSV includes only balances: + you can import with print, which leaves implicit amounts implicit. (print can also do overlap detection like import, with the --new flag): $ hledger print --new -f bank.csv >> $LEDGER_FILE - (If you think import should preserve implicit balances, please test + (If you think import should preserve implicit balances, please test that and send a pull request.) Import and commodity styles - Amounts in entries added by import will be formatted according to the - journal's canonical commodity styles, as declared by commodity direc- + Amounts in entries added by import will be formatted according to the + journal's canonical commodity styles, as declared by commodity direc- tives or inferred from the journal's amounts. Related: CSV > Amount decimal places. Import archiving - When importing from a CSV rules file (hledger import bank.rules), you - can use the archive rule to enable automatic archiving of the data - file. After a successful import, the data file (specified by source) - will be moved to an archive folder (data/, next to the rules file, - auto-created), and renamed similar to the rules file, with a date. - This can be useful for troubleshooting, detecting variations in your + When importing from a CSV rules file (hledger import bank.rules), you + can use the archive rule to enable automatic archiving of the data + file. After a successful import, the data file (specified by source) + will be moved to an archive folder (data/, next to the rules file, + auto-created), and renamed similar to the rules file, with a date. + This can be useful for troubleshooting, detecting variations in your banks' CSV data, regenerating entries with improved rules, etc. The archive rule also causes import to handle source glob patterns dif- - ferently: when there are multiple matched files, it will pick the old- + ferently: when there are multiple matched files, it will pick the old- est, not the newest. Import special cases @@ -7299,33 +7330,33 @@ Data entry commands Here are two kinds of "deduplication" which import does not handle (and should not, because these can happen legitimately in financial data): - o Two or more of the new CSV records are identical, and generate iden- + o Two or more of the new CSV records are identical, and generate iden- tical new journal entries. - o A new CSV record generates a journal entry identical to one(s) al- + o A new CSV record generates a journal entry identical to one(s) al- ready in the journal. Varying file name If you have a download whose file name varies, you could rename it to a - fixed name after each download. Or you could use a CSV source rule + fixed name after each download. Or you could use a CSV source rule with a suitable glob pattern, and import from the .rules file. Multiple versions Say you download bank.csv, import it, but forget to delete it from your downloads folder. The next time you download it, your web browser will - save it as (eg) bank (2).csv. The source rule's glob patterns are for - just this situation: instead of specifying source bank.csv, specify - source bank*.csv. Then hledger -f bank.rules CMD or hledger import - bank.rules will automatically pick the newest matched file (bank + save it as (eg) bank (2).csv. The source rule's glob patterns are for + just this situation: instead of specifying source bank.csv, specify + source bank*.csv. Then hledger -f bank.rules CMD or hledger import + bank.rules will automatically pick the newest matched file (bank (2).csv). Alternately, what if you download, but forget to import or delete, then - download again ? Now each of bank.csv and bank (2).csv might contain - data that's not in the other, and not in your journal. In this case, - it's best to import each of them in turn, oldest first (otherwise, + download again ? Now each of bank.csv and bank (2).csv might contain + data that's not in the other, and not in your journal. In this case, + it's best to import each of them in turn, oldest first (otherwise, overlap detection could cause new records to be skipped). Enabling im- - port archiving ensures this. Then hledger import bank.rules; hledger - import bank.rules will import and archive first bank.csv, then bank + port archiving ensures this. Then hledger import bank.rules; hledger + import bank.rules will import and archive first bank.csv, then bank (2).csv. Basic report commands @@ -7347,31 +7378,31 @@ Basic report commands -t --tree list/tree mode: show accounts as a tree --drop=N flat mode: omit N leading account name parts - This command lists account names - all of them by default, or just the + This command lists account names - all of them by default, or just the ones which have been used in transactions (-u/--used), or declared with - account directives (-d/--declared), or used but not declared (--unde- - clared), or declared but not used (--unused), or just the first one - matched by a pattern (--find, returning a non-zero exit code if it + account directives (-d/--declared), or used but not declared (--unde- + clared), or declared but not used (--unused), or just the first one + matched by a pattern (--find, returning a non-zero exit code if it fails). - You can add query arguments to select a subset of transactions or ac- + You can add query arguments to select a subset of transactions or ac- counts. - With --directives, it shows valid account directives which could be - pasted into a journal file. This is useful together with --undeclared - when updating your account declarations to satisfy hledger check ac- + With --directives, it shows valid account directives which could be + pasted into a journal file. This is useful together with --undeclared + when updating your account declarations to satisfy hledger check ac- counts. - With --locations, it also shows the file and line number of each ac- - count's declaration, if any, and the account's overall declaration or- + With --locations, it also shows the file and line number of each ac- + count's declaration, if any, and the account's overall declaration or- der; these may be useful when troubleshooting account display order. - With --types, it also shows each account's type, if it's known. (See + With --types, it also shows each account's type, if it's known. (See Declaring accounts > Account types.) - It shows a flat list by default. With --tree, it uses indentation to - show the account hierarchy. In flat mode you can add --drop N to omit - the first few account name components. Account names can be + It shows a flat list by default. With --tree, it uses indentation to + show the account hierarchy. In flat mode you can add --drop N to omit + the first few account name components. Account names can be depth-clipped with depth:N or --depth N or -N. Examples: @@ -7395,13 +7426,13 @@ Basic report commands Flags: no command-specific flags - This command prints the value of each transaction's code field, in the - order transactions were parsed. The transaction code is an optional - value written in parentheses between the date and description, often + This command prints the value of each transaction's code field, in the + order transactions were parsed. The transaction code is an optional + value written in parentheses between the date and description, often used to store a cheque number, order number or similar. Transactions aren't required to have a code, and missing or empty codes - will not be shown by default. With the -E/--empty flag, they will be + will not be shown by default. With the -E/--empty flag, they will be printed as blank lines. You can add a query to select a subset of transactions. @@ -7447,9 +7478,9 @@ Basic report commands argument (a case-insensitive infix regexp) This command lists commodity symbols/names - all of them by default, or - just the ones which have been used in transactions or P directives, or - declared with commodity directives, or used but not declared, or de- - clared but not used, or just the first one matched by a pattern (with + just the ones which have been used in transactions or P directives, or + declared with commodity directives, or used but not declared, or de- + clared but not used, or just the first one matched by a pattern (with --find, returning a non-zero exit code if it fails). You can add cur: query arguments to further limit the commodities. @@ -7461,7 +7492,7 @@ Basic report commands no command-specific flags This command lists the unique descriptions that appear in transactions, - in alphabetic order. You can add a query to select a subset of trans- + in alphabetic order. You can add a query to select a subset of trans- actions. Example: @@ -7472,7 +7503,7 @@ Basic report commands Person A files - List all files included in the journal. With a REGEX argument, only + List all files included in the journal. With a REGEX argument, only file names matching the regular expression (case sensitive) are shown. Flags: @@ -7485,8 +7516,8 @@ Basic report commands no command-specific flags This command lists the unique notes that appear in transactions, in al- - phabetic order. You can add a query to select a subset of transac- - tions. The note is the part of the transaction description after a | + phabetic order. You can add a query to select a subset of transac- + tions. The note is the part of the transaction description after a | character (or if there is no |, the whole description). Example: @@ -7506,16 +7537,16 @@ Basic report commands --find list the first payee matched by the first argument (a case-insensitive infix regexp) - This command lists unique payee/payer names - all of them by default, - or just the ones which have been used in transaction descriptions, or - declared with payee directives, or used but not declared, or declared - but not used, or just the first one matched by a pattern (with --find, + This command lists unique payee/payer names - all of them by default, + or just the ones which have been used in transaction descriptions, or + declared with payee directives, or used but not declared, or declared + but not used, or just the first one matched by a pattern (with --find, returning a non-zero exit code if it fails). - The payee/payer name is the part of the transaction description before + The payee/payer name is the part of the transaction description before a | character (or if there is no |, the whole description). - You can add query arguments to select a subset of transactions or pay- + You can add query arguments to select a subset of transactions or pay- ees. Example: @@ -7526,8 +7557,8 @@ Basic report commands Person A prices - Print the market prices declared with P directives. With --infer-mar- - ket-prices, also show any additional prices inferred from costs. With + Print the market prices declared with P directives. With --infer-mar- + ket-prices, also show any additional prices inferred from costs. With --show-reverse, also show additional prices inferred by reversing known prices. @@ -7535,14 +7566,14 @@ Basic report commands --show-reverse also show the prices inferred by reversing known prices - Price amounts are always displayed with their full precision, except + Price amounts are always displayed with their full precision, except for reverse prices which are limited to 8 decimal digits. Prices can be filtered by a date:, cur: or amt: query. Generally if you run this command with --infer-market-prices --show-re- - verse, it will show the same prices used internally to calculate value - reports. But if in doubt, you can inspect those directly by running + verse, it will show the same prices used internally to calculate value + reports. But if in doubt, you can inspect those directly by running the value report with --debug=2. stats @@ -7553,10 +7584,10 @@ Basic report commands -o --output-file=FILE write output to FILE. The stats command shows summary information for the whole journal, or a - matched part of it. With a reporting interval, it shows a report for + matched part of it. With a reporting interval, it shows a report for each report period. - The default output is fairly impersonal, though it reveals the main + The default output is fairly impersonal, though it reveals the main file name. With -v/--verbose, more details are shown, like file paths, included files, and commodity names. @@ -7568,8 +7599,8 @@ Basic report commands o live: the peak memory in use by the program to do its work - o alloc: the peak memory allocation from the OS as seen by GHC. Mea- - suring this externally, eg with GNU time, is more accurate; usually + o alloc: the peak memory allocation from the OS as seen by GHC. Mea- + suring this externally, eg with GNU time, is more accurate; usually that will be a larger number; sometimes (with swapping?) smaller. The stats command's run time is similar to that of a balance report. @@ -7590,7 +7621,7 @@ Basic report commands Market prices : 1000 Runtime stats : 0.12 s elapsed, 8266 txns/s, 4 MB live, 16 MB alloc - This command supports the -o/--output-file option (but not -O/--out- + This command supports the -o/--output-file option (but not -O/--out- put-format). tags @@ -7608,26 +7639,26 @@ Basic report commands including duplicates This command lists tag names - all of them by default, or just the ones - which have been used on transactions/postings/accounts, or declared - with tag directives, or used but not declared, or declared but not - used, or just the first one matched by a pattern (with --find, return- + which have been used on transactions/postings/accounts, or declared + with tag directives, or used but not declared, or declared but not + used, or just the first one matched by a pattern (with --find, return- ing a non-zero exit code if it fails). - Note this command's non-standard first argument: it is a case-insensi- - tive infix regular expression for matching tag names, which limits the - tags shown. Any additional arguments are standard query arguments, + Note this command's non-standard first argument: it is a case-insensi- + tive infix regular expression for matching tag names, which limits the + tags shown. Any additional arguments are standard query arguments, which limit the transactions, postings, or accounts providing tags. With --values, the tags' unique non-empty values are listed instead. With -E/--empty, blank/empty values are also shown. - With --parsed, tags or values are shown in the order they were parsed, - with duplicates included. (Except, tags from account declarations are + With --parsed, tags or values are shown in the order they were parsed, + with duplicates included. (Except, tags from account declarations are always shown first.) - Remember that accounts also acquire tags from their parents; postings - also acquire tags from their account and transaction; and transactions + Remember that accounts also acquire tags from their parents; postings + also acquire tags from their account and transaction; and transactions also acquire tags from their postings. Standard report commands @@ -7663,9 +7694,9 @@ Standard report commands The print command displays full journal entries (transactions) from the journal file, sorted by date (or with --date2, by secondary date). - Directives and inter-transaction comments are not shown, currently. + Directives and inter-transaction comments are not shown, currently. This means the print command is somewhat lossy, and if you are using it - to reformat/regenerate your journal you should take care to also copy + to reformat/regenerate your journal you should take care to also copy over the directives and inter-transaction comments. Eg: @@ -7685,33 +7716,33 @@ Standard report commands assets:cash $-2 print amount explicitness - Normally, whether posting amounts are implicit or explicit is pre- + Normally, whether posting amounts are implicit or explicit is pre- served. For example, when an amount is omitted in the journal, it will - not appear in the output. Similarly, if a conversion cost is implied + not appear in the output. Similarly, if a conversion cost is implied but not written, it will not appear in the output. - You can use the -x/--explicit flag to force explicit display of all - amounts and costs. This can be useful for troubleshooting or for mak- - ing your journal more readable and robust against data entry errors. + You can use the -x/--explicit flag to force explicit display of all + amounts and costs. This can be useful for troubleshooting or for mak- + ing your journal more readable and robust against data entry errors. -x is also implied by using any of -B,-V,-X,--value. - The -x/--explicit flag will cause any postings with a multi-commodity - amount (which can arise when a multi-commodity transaction has an im- - plicit amount) to be split into multiple single-commodity postings, + The -x/--explicit flag will cause any postings with a multi-commodity + amount (which can arise when a multi-commodity transaction has an im- + plicit amount) to be split into multiple single-commodity postings, keeping the output parseable. print alignment - Amounts are shown right-aligned within each transaction (but not - aligned across all transactions; you can achieve that with ledger-mode + Amounts are shown right-aligned within each transaction (but not + aligned across all transactions; you can achieve that with ledger-mode in Emacs). print amount style - Amounts will be displayed mostly in their commodity's display style, - with standardised symbol placement, decimal mark, and digit group - marks. This does not apply to their decimal digits; print normally + Amounts will be displayed mostly in their commodity's display style, + with standardised symbol placement, decimal mark, and digit group + marks. This does not apply to their decimal digits; print normally shows the same decimal digits that are recorded in each journal entry. - You can override the decimal precisions with print's special --round + You can override the decimal precisions with print's special --round option (since 1.32). --round tries to show amounts with their commodi- ties' standard decimal precisions, increasingly strongly: @@ -7719,7 +7750,7 @@ Standard report commands o --round=soft add/remove decimal zeros in amounts (except costs) - o --round=hard round amounts (except costs), possibly hiding signifi- + o --round=hard round amounts (except costs), possibly hiding signifi- cant digits o --round=all round all amounts and costs @@ -7727,21 +7758,21 @@ Standard report commands soft is good for non-lossy cleanup, displaying more consistent decimals where possible, without making entries unbalanced. - hard or all can be good for stronger cleanup, when decimal rounding is - wanted. Note rounding can produce unbalanced journal entries, perhaps + hard or all can be good for stronger cleanup, when decimal rounding is + wanted. Note rounding can produce unbalanced journal entries, perhaps requiring manual fixup. print parseability - Normally, print's output is a valid hledger journal, which you can - "pipe" to a second hledger command for further processing. This is - sometimes convenient for achieving certain kinds of query (though less + Normally, print's output is a valid hledger journal, which you can + "pipe" to a second hledger command for further processing. This is + sometimes convenient for achieving certain kinds of query (though less needed now that queries have become more powerful): # Show running total of food expenses paid from cash. # -f- reads from stdin. -I/--ignore-assertions is sometimes needed. $ hledger print assets:cash | hledger -f- -I reg expenses:food - But here are some things which can cause print's output to become un- + But here are some things which can cause print's output to become un- parseable: o --round (see above) can disrupt transaction balancing. @@ -7749,56 +7780,56 @@ Standard report commands o Account aliases or pivoting can disrupt account names, balance asser- tions, or balance assignments. - o Value reporting also can disrupt balance assertions or balance as- + o Value reporting also can disrupt balance assertions or balance as- signments. o Auto postings can generate too many amountless postings. - o --infer-costs or --infer-equity can generate too-complex redundant + o --infer-costs or --infer-equity can generate too-complex redundant costs. print, other features With -B/--cost, amounts with costs are shown converted to cost. - With --invert, posting amounts are shown with their sign flipped. It - could be useful if you have accidentally recorded some transactions + With --invert, posting amounts are shown with their sign flipped. It + could be useful if you have accidentally recorded some transactions with the wrong signs. With --new, print shows only transactions it has not seen on a previous - run. This uses the same deduplication system as the import command. + run. This uses the same deduplication system as the import command. (See import's docs for details.) With -m DESC/--match=DESC, print shows one recent transaction whose de- - scription is most similar to DESC. DESC should contain at least two - characters. If there is no similar-enough match, no transaction will + scription is most similar to DESC. DESC should contain at least two + characters. If there is no similar-enough match, no transaction will be shown and the program exit code will be non-zero. - With --locations, print adds the source file and line number to every + With --locations, print adds the source file and line number to every transaction, as a tag. print output format This command also supports the output destination and output format op- - tions The output formats supported are txt, beancount (Added in 1.32), + 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 + The beancount format tries to produce Beancount-compatible output, as follows: - o Transaction and postings with unmarked status are converted to + o Transaction and postings with unmarked status are converted to cleared (*) status. - o Transactions' payee and note are backslash-escaped and dou- + o Transactions' payee and note are backslash-escaped and dou- ble-quote-escaped and wrapped in double quotes. o Transaction tags are copied to Beancount #tag format. - o Commodity symbols are converted to upper case, and a small number of - currency symbols like $ are converted to the corresponding currency + o Commodity symbols are converted to upper case, and a small number of + currency symbols like $ are converted to the corresponding currency names. o Account name parts are capitalised and unsupported characters are re- placed with -. If an account name part does not begin with a letter, - or if the first part is not Assets, Liabilities, Equity, Income, or + or if the first part is not Assets, Liabilities, Equity, Income, or Expenses, an error is raised. (Use --alias options to bring your ac- counts into compliance.) @@ -7831,26 +7862,26 @@ Standard report commands "5","2008/12/31","","*","","pay off","","liabilities:debts","1","$","","1","","" "5","2008/12/31","","*","","pay off","","assets:bank:checking","-1","$","1","","","" - o There is one CSV record per posting, with the parent transaction's + o There is one CSV record per posting, with the parent transaction's fields repeated. o The "txnidx" (transaction index) field shows which postings belong to - the same transaction. (This number might change if transactions are - reordered within the file, files are parsed/included in a different + the same transaction. (This number might change if transactions are + reordered within the file, files are parsed/included in a different order, etc.) - o The amount is separated into "commodity" (the symbol) and "amount" + o The amount is separated into "commodity" (the symbol) and "amount" (numeric quantity) fields. o The numeric amount is repeated in either the "credit" or "debit" col- - umn, for convenience. (Those names are not accurate in the account- - ing sense; it just puts negative amounts under credit and zero or + umn, for convenience. (Those names are not accurate in the account- + ing sense; it just puts negative amounts under credit and zero or greater amounts under debit.) aregister (areg) - Show the transactions and running balances in one account, with each + Show the transactions and running balances in one account, with each transaction on one line. Flags: @@ -7874,63 +7905,63 @@ Standard report commands one of the above formats selects that format. aregister shows the overall transactions affecting a particular account - (and any subaccounts). Each report line represents one transaction in - this account. Transactions before the report start date are included - in the running balance (--historical mode is the default). You can + (and any subaccounts). Each report line represents one transaction in + this account. Transactions before the report start date are included + in the running balance (--historical mode is the default). You can suppress this behaviour using the --cumulative option. - This is a more "real world", bank-like view than the register command - (which shows individual postings, possibly from multiple accounts, not + This is a more "real world", bank-like view than the register command + (which shows individual postings, possibly from multiple accounts, not necessarily in historical mode). As a quick rule of thumb: - use areg- ister for reviewing and reconciling real-world asset/liability accounts - use register for reviewing detailed revenues/expenses. - Note this command's non-standard, and required, first argument; it - specifies the account whose register will be shown. You can write the - account's name, or (to save typing) a case-insensitive infix regular - expression matching the name, which selects the alphabetically first - matched account. (For example, if you have assets:personal checking - and assets:business checking, hledger areg checking would select as- + Note this command's non-standard, and required, first argument; it + specifies the account whose register will be shown. You can write the + account's name, or (to save typing) a case-insensitive infix regular + expression matching the name, which selects the alphabetically first + matched account. (For example, if you have assets:personal checking + and assets:business checking, hledger areg checking would select as- sets:business checking.) - Transactions involving subaccounts of this account will also be shown. - aregister ignores depth limits, so its final total will always match a + Transactions involving subaccounts of this account will also be shown. + aregister ignores depth limits, so its final total will always match a historical balance report with similar arguments. Any additional arguments are standard query arguments, which will limit - the transactions shown. Note some queries will disturb the running - balance, causing it to be different from the account's real-world run- + the transactions shown. Note some queries will disturb the running + balance, causing it to be different from the account's real-world run- ning balance. - An example: this shows the transactions and historical running balance + An example: this shows the transactions and historical running balance during july, in the first account whose name contains "checking": $ hledger areg checking date:jul Each aregister line item shows: - o the transaction's date (or the relevant posting's date if different, + o the transaction's date (or the relevant posting's date if different, see below) - o the names of all the other account(s) involved in this transaction + o the names of all the other account(s) involved in this transaction (probably abbreviated) o the total change to this account's balance from this transaction o the account's historical running balance after this transaction. - Transactions making a net change of zero are not shown by default; add + Transactions making a net change of zero are not shown by default; add the -E/--empty flag to show them. - For performance reasons, column widths are chosen based on the first - 1000 lines; this means unusually wide values in later lines can cause - visual discontinuities as column widths are adjusted. If you want to - ensure perfect alignment, at the cost of more time and memory, use the + For performance reasons, column widths are chosen based on the first + 1000 lines; this means unusually wide values in later lines can cause + visual discontinuities as column widths are adjusted. If you want to + ensure perfect alignment, at the cost of more time and memory, use the --align-all flag. - By default, aregister shows a heading above the data. However, when - reporting in a language different from English, it is easier to omit - this heading and prepend your own one. For this purpose, use the + By default, aregister shows a heading above the data. However, when + reporting in a language different from English, it is easier to omit + this heading and prepend your own one. For this purpose, use the --heading=no option. This command also supports the output destination and output format op- @@ -7938,13 +7969,13 @@ Standard report commands html, fods (Added in 1.41) and json. aregister and posting dates - aregister always shows one line (and date and amount) per transaction. - But sometimes transactions have postings with different dates. Also, - not all of a transaction's postings may be within the report period. + aregister always shows one line (and date and amount) per transaction. + But sometimes transactions have postings with different dates. Also, + not all of a transaction's postings may be within the report period. To resolve this, aregister shows the earliest of the transaction's date and posting dates that is in-period, and the sum of the in-period post- - ings. In other words it will show a combined line item with just the - earliest date, and the running balance will (temporarily, until the + ings. In other words it will show a combined line item with just the + earliest date, and the running balance will (temporarily, until the transaction's last posting) be inaccurate. Use register -H if you need to see the individual postings. @@ -7984,14 +8015,14 @@ Standard report commands one of the above formats selects that format. The register command displays matched postings, across all accounts, in - date order, with their running total or running historical balance. - (See also the aregister command, which shows matched transactions in a + date order, with their running total or running historical balance. + (See also the aregister command, which shows matched transactions in a specific account.) register normally shows line per posting, but note that multi-commodity amounts will occupy multiple lines (one line per commodity). - It is typically used with a query selecting a particular account, to + It is typically used with a query selecting a particular account, to see that account's activity: $ hledger register checking @@ -8002,14 +8033,14 @@ Standard report commands With --date2, it shows and sorts by secondary date instead. - For performance reasons, column widths are chosen based on the first - 1000 lines; this means unusually wide values in later lines can cause - visual discontinuities as column widths are adjusted. If you want to - ensure perfect alignment, at the cost of more time and memory, use the + For performance reasons, column widths are chosen based on the first + 1000 lines; this means unusually wide values in later lines can cause + visual discontinuities as column widths are adjusted. If you want to + ensure perfect alignment, at the cost of more time and memory, use the --align-all flag. - The --historical/-H flag adds the balance from any undisplayed prior - postings to the running total. This is useful when you want to see + The --historical/-H flag adds the balance from any undisplayed prior + postings to the running total. This is useful when you want to see only recent activity, with a historically accurate running balance: $ hledger register checking -b 2008/6 --historical @@ -8019,25 +8050,25 @@ Standard report commands The --depth option limits the amount of sub-account detail displayed. - The --average/-A flag shows the running average posting amount instead + The --average/-A flag shows the running average posting amount instead of the running total (so, the final number displayed is the average for - the whole report period). This flag implies --empty (see below). It - is affected by --historical. It works best when showing just one ac- + the whole report period). This flag implies --empty (see below). It + is affected by --historical. It works best when showing just one ac- count and one commodity. - The --related/-r flag shows the other postings in the transactions of + The --related/-r flag shows the other postings in the transactions of the postings which would normally be shown. - The --invert flag negates all amounts. For example, it can be used on + The --invert flag negates all amounts. For example, it can be used on an income account where amounts are normally displayed as negative num- - bers. It's also useful to show postings on the checking account to- + bers. It's also useful to show postings on the checking account to- gether with the related account: - The --sort=FIELDS flag sorts by the fields given, which can be any of + The --sort=FIELDS flag sorts by the fields given, which can be any of account, amount, absamount, date, or desc/description, optionally sepa- - rated by commas. For example, --sort account,amount will group all + rated by commas. For example, --sort account,amount will group all transactions in each account, sorted by transaction amount. Each field - can be negated by a preceding -, so --sort -amount will show transac- + can be negated by a preceding -, so --sort -amount will show transac- tions ordered from smallest amount to largest amount. $ hledger register --related --invert assets:checking @@ -8049,7 +8080,7 @@ Standard report commands 2008/01 income:salary $-1 $-1 2008/06 income:gifts $-1 $-2 - Periods with no activity, and summary postings with a zero amount, are + Periods with no activity, and summary postings with a zero amount, are not shown by default; use the --empty/-E flag to see them: $ hledger register --monthly income -E @@ -8066,7 +8097,7 @@ Standard report commands 2008/11 0 $-2 2008/12 0 $-2 - Often, you'll want to see just one line per interval. The --depth op- + Often, you'll want to see just one line per interval. The --depth op- tion helps with this, causing subaccounts to be aggregated: $ hledger register --monthly assets --depth 1 @@ -8074,21 +8105,21 @@ Standard report commands 2008/06 assets $-1 0 2008/12 assets $-1 $-1 - Note when using report intervals, if you specify start/end dates these - will be adjusted outward if necessary to contain a whole number of in- - tervals. This ensures that the first and last intervals are full + Note when using report intervals, if you specify start/end dates these + will be adjusted outward if necessary to contain a whole number of in- + tervals. This ensures that the first and last intervals are full length and comparable to the others in the report. - With -m DESC/--match=DESC, register does a fuzzy search for one recent + With -m DESC/--match=DESC, register does a fuzzy search for one recent posting whose description is most similar to DESC. DESC should contain at least two characters. If there is no similar-enough match, no post- ing will be shown and the program exit code will be non-zero. Custom register output - register normally uses the full terminal width (or 80 columns if it + register normally uses the full terminal width (or 80 columns if it can't detect that). You can override this with the --width/-w option. - The description and account columns normally share the space equally + The description and account columns normally share the space equally (about half of (width - 40) each). You can adjust this by adding a de- scription width as part of --width's argument, comma-separated: --width W,D . Here's a diagram (won't display correctly in --help): @@ -8104,14 +8135,14 @@ Standard report commands $ hledger reg -w 100,40 # set overall width 100, description width 40 This command also supports the output destination and output format op- - tions The output formats supported are txt, csv, tsv (Added in 1.32), + tions The output formats supported are txt, csv, tsv (Added in 1.32), and json. balancesheet (bs) - Show the end balances in asset and liability accounts. Amounts are - shown with normal positive sign, as in conventional financial state- + Show the end balances in asset and liability accounts. Amounts are + shown with normal positive sign, as in conventional financial state- ments. Flags: @@ -8162,13 +8193,13 @@ Standard report commands -o --output-file=FILE write output to FILE. A file extension matching one of the above formats selects that format. - This command displays a balance sheet, showing historical ending bal- + This command displays a balance sheet, showing historical ending bal- ances of asset and liability accounts. (To see equity as well, use the balancesheetequity command.) Accounts declared with the Asset, Cash or Liability type are shown (see - account types). Or if no such accounts are declared, it shows - top-level accounts named asset or liability (case insensitive, plurals + account types). Or if no such accounts are declared, it shows + top-level accounts named asset or liability (case insensitive, plurals allowed) and their subaccounts. Example: @@ -8194,20 +8225,20 @@ Standard report commands Net: || 0 This command is a higher-level variant of the balance command, and sup- - ports many of that command's features, such as multi-period reports. - It is similar to hledger balance -H assets liabilities, but with - smarter account detection, and liabilities displayed with their sign + ports many of that command's features, such as multi-period reports. + It is similar to hledger balance -H assets liabilities, but with + smarter account detection, and liabilities displayed with their sign flipped. This command also supports the output destination and output format op- - tions The output formats supported are txt, csv, tsv (Added in 1.32), + tions The output formats supported are txt, csv, tsv (Added in 1.32), html, and json. balancesheetequity (bse) - This command displays a balance sheet, showing historical ending bal- - ances of asset, liability and equity accounts. Amounts are shown with + This command displays a balance sheet, showing historical ending bal- + ances of asset, liability and equity accounts. Amounts are shown with normal positive sign, as in conventional financial statements. Flags: @@ -8258,9 +8289,9 @@ Standard report commands -o --output-file=FILE write output to FILE. A file extension matching one of the above formats selects that format. - This report shows accounts declared with the Asset, Cash, Liability or - Equity type (see account types). Or if no such accounts are declared, - it shows top-level accounts named asset, liability or equity (case in- + This report shows accounts declared with the Asset, Cash, Liability or + Equity type (see account types). Or if no such accounts are declared, + it shows top-level accounts named asset, liability or equity (case in- sensitive, plurals allowed) and their subaccounts. Example: @@ -8291,14 +8322,14 @@ Standard report commands Net: || 0 This command is a higher-level variant of the balance command, and sup- - ports many of that command's features, such as multi-period reports. + ports many of that command's features, such as multi-period reports. It is similar to hledger balance -H assets liabilities equity, but with - smarter account detection, and liabilities/equity displayed with their + smarter account detection, and liabilities/equity displayed with their sign flipped. This report is the easiest way to see if the accounting equation (A+L+E - = 0) is satisfied (after you have done a close --retain to merge rev- - enues and expenses with equity, and perhaps added --infer-equity to + = 0) is satisfied (after you have done a close --retain to merge rev- + enues and expenses with equity, and perhaps added --infer-equity to balance your commodity conversions). This command also supports the output destination and output format op- @@ -8307,9 +8338,9 @@ Standard report commands cashflow (cf) - This command displays a (simple) cashflow statement, showing the in- - flows and outflows affecting "cash" (ie, liquid, easily convertible) - assets. Amounts are shown with normal positive sign, as in conven- + This command displays a (simple) cashflow statement, showing the in- + flows and outflows affecting "cash" (ie, liquid, easily convertible) + assets. Amounts are shown with normal positive sign, as in conven- tional financial statements. Flags: @@ -8361,10 +8392,10 @@ Standard report commands -o --output-file=FILE write output to FILE. A file extension matching one of the above formats selects that format. - This report shows accounts declared with the Cash type (see account + This report shows accounts declared with the Cash type (see account types). Or if no such accounts are declared, it shows accounts - o under a top-level account named asset (case insensitive, plural al- + o under a top-level account named asset (case insensitive, plural al- lowed) o whose name contains some variation of cash, bank, checking or saving. @@ -8391,19 +8422,19 @@ Standard report commands || $-1 This command is a higher-level variant of the balance command, and sup- - ports many of that command's features, such as multi-period reports. - It is similar to hledger balance assets not:fixed not:investment + ports many of that command's features, such as multi-period reports. + It is similar to hledger balance assets not:fixed not:investment 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 (Added in 1.32), + tions The output formats supported are txt, csv, tsv (Added in 1.32), html, and json. incomestatement (is) - Show revenue inflows and expense outflows during the report period. - Amounts are shown with normal positive sign, as in conventional finan- + Show revenue inflows and expense outflows during the report period. + Amounts are shown with normal positive sign, as in conventional finan- cial statements. Flags: @@ -8455,12 +8486,12 @@ Standard report commands -o --output-file=FILE write output to FILE. A file extension matching one of the above formats selects that format. - This command displays an income statement, showing revenues and ex- + This command displays an income statement, showing revenues and ex- penses during one or more periods. - It shows accounts declared with the Revenue or Expense type (see ac- - count types). Or if no such accounts are declared, it shows top-level - accounts named revenue or income or expense (case insensitive, plurals + It shows accounts declared with the Revenue or Expense type (see ac- + count types). Or if no such accounts are declared, it shows top-level + accounts named revenue or income or expense (case insensitive, plurals allowed) and their subaccounts. Example: @@ -8487,20 +8518,20 @@ Standard report commands Net: || 0 This command is a higher-level variant of the balance command, and sup- - ports many of that command's features, such as multi-period reports. + ports many of that command's features, such as multi-period reports. It is similar to hledger balance '(revenues|income)' expenses, but with - smarter account detection, and revenues/income displayed with their + smarter account detection, and revenues/income displayed with their sign flipped. This command also supports the output destination and output format op- - tions The output formats supported are txt, csv, tsv (Added in 1.32), + tions The output formats supported are txt, csv, tsv (Added in 1.32), html, and json. Advanced report commands balance (bal) - A flexible, general purpose "summing" report that shows accounts with + A flexible, general purpose "summing" report that shows accounts with some kind of numeric data. This can be balance changes per period, end balances, budget performance, unrealised capital gains, etc. @@ -8567,19 +8598,19 @@ Advanced report commands -o --output-file=FILE write output to FILE. A file extension matching one of the above formats selects that format. - balance is one of hledger's oldest and most versatile commands, for - listing account balances, balance changes, values, value changes and + balance is one of hledger's oldest and most versatile commands, for + listing account balances, balance changes, values, value changes and more, during one time period or many. Generally it shows a table, with rows representing accounts, and columns representing periods. Note there are some variants of the balance command with convenient de- - faults, which are simpler to use: balancesheet, balancesheetequity, - cashflow and incomestatement. When you need more control, then use + faults, which are simpler to use: balancesheet, balancesheetequity, + cashflow and incomestatement. When you need more control, then use balance. balance features - Here's a quick overview of the balance command's features, followed by - more detailed descriptions and examples. Many of these work with the + Here's a quick overview of the balance command's features, followed by + more detailed descriptions and examples. Many of these work with the other balance-like commands as well (bs, cf, is..). balance can show.. @@ -8634,7 +8665,7 @@ Advanced report commands ..with.. - o totals (-T), averages (-A), percentages (-%), inverted sign (--in- + o totals (-T), averages (-A), percentages (-%), inverted sign (--in- vert) o rows and columns swapped (--transpose) @@ -8647,20 +8678,20 @@ Advanced report commands This command supports the output destination and output format options, with output formats txt, csv, tsv (Added in 1.32), json, and (multi-pe- - riod reports only:) html, fods (Added in 1.40). In txt output in a + riod reports only:) html, fods (Added in 1.40). In txt output in a colour-supporting terminal, negative amounts are shown in red. Simple balance report - With no arguments, balance shows a list of all accounts and their - change of balance - ie, the sum of posting amounts, both inflows and - outflows - during the entire period of the journal. ("Simple" here - means just one column of numbers, covering a single period. You can + With no arguments, balance shows a list of all accounts and their + change of balance - ie, the sum of posting amounts, both inflows and + outflows - during the entire period of the journal. ("Simple" here + means just one column of numbers, covering a single period. You can also have multi-period reports, described later.) - For real-world accounts, these numbers will normally be their end bal- + For real-world accounts, these numbers will normally be their end bal- ance at the end of the journal period; more on this below. - Accounts are sorted by declaration order if any, and then alphabeti- + Accounts are sorted by declaration order if any, and then alphabeti- cally by account name. For instance (using examples/sample.journal): $ hledger -f examples/sample.journal bal @@ -8675,7 +8706,7 @@ Advanced report commands 0 Accounts with a zero balance (and no non-zero subaccounts, in tree mode - - see below) are hidden by default. Use -E/--empty to show them (re- + - see below) are hidden by default. Use -E/--empty to show them (re- vealing assets:bank:checking here): $ hledger -f examples/sample.journal bal -E @@ -8690,12 +8721,12 @@ Advanced report commands -------------------- 0 - The total of the amounts displayed is shown as the last line, unless + The total of the amounts displayed is shown as the last line, unless -N/--no-total is used. Balance report line format For single-period balance reports displayed in the terminal (only), you - can use --format FMT to customise the format and content of each line. + can use --format FMT to customise the format and content of each line. Eg: $ hledger -f examples/sample.journal balance --format "%20(account) %12(total)" @@ -8712,7 +8743,7 @@ Advanced report commands --------------------------------- 0 - The FMT format string specifies the formatting applied to each ac- + The FMT format string specifies the formatting applied to each ac- count/balance pair. It may contain any suitable text, with data fields interpolated like so: @@ -8724,14 +8755,14 @@ Advanced report commands o FIELDNAME must be enclosed in parentheses, and can be one of: - o depth_spacer - a number of spaces equal to the account's depth, or + o depth_spacer - a number of spaces equal to the account's depth, or if MIN is specified, MIN * depth spaces. o account - the account's name o total - the account's balance/posted total, right justified - Also, FMT can begin with an optional prefix to control how multi-com- + Also, FMT can begin with an optional prefix to control how multi-com- modity amounts are rendered: o %_ - render on multiple lines, bottom-aligned (the default) @@ -8741,25 +8772,25 @@ Advanced report commands o %, - render on one line, comma-separated There are some quirks. Eg in one-line mode, %(depth_spacer) has no ef- - fect, instead %(account) has indentation built in. Experimentation + fect, instead %(account) has indentation built in. Experimentation may be needed to get pleasing results. Some example formats: o %(total) - the account's total - o %-20.20(account) - the account's name, left justified, padded to 20 + o %-20.20(account) - the account's name, left justified, padded to 20 characters and clipped at 20 characters - o %,%-50(account) %25(total) - account name padded to 50 characters, - total padded to 20 characters, with multiple commodities rendered on + o %,%-50(account) %25(total) - account name padded to 50 characters, + total padded to 20 characters, with multiple commodities rendered on one line - o %20(total) %2(depth_spacer)%-(account) - the default format for the + o %20(total) %2(depth_spacer)%-(account) - the default format for the single-column balance report Filtered balance report - You can show fewer accounts, a different time period, totals from + You can show fewer accounts, a different time period, totals from cleared transactions only, etc. by using query arguments or options to limit the postings being matched. Eg: @@ -8769,10 +8800,10 @@ Advanced report commands $-2 List or tree mode - By default, or with -l/--flat, accounts are shown as a flat list with + By default, or with -l/--flat, accounts are shown as a flat list with their full names visible, as in the examples above. - With -t/--tree, the account hierarchy is shown, with subaccounts' + With -t/--tree, the account hierarchy is shown, with subaccounts' "leaf" names indented below their parent: $ hledger -f examples/sample.journal balance @@ -8792,26 +8823,26 @@ Advanced report commands Notes: o "Boring" accounts are combined with their subaccount for more compact - output, unless --no-elide is used. Boring accounts have no balance - of their own and just one subaccount (eg assets:bank and liabilities + output, unless --no-elide is used. Boring accounts have no balance + of their own and just one subaccount (eg assets:bank and liabilities above). - o All balances shown are "inclusive", ie including the balances from - all subaccounts. Note this means some repetition in the output, + o All balances shown are "inclusive", ie including the balances from + all subaccounts. Note this means some repetition in the output, which requires explanation when sharing reports with non-plaintextac- - counting-users. A tree mode report's final total is the sum of the + counting-users. A tree mode report's final total is the sum of the top-level balances shown, not of all the balances shown. - o Each group of sibling accounts (ie, under a common parent) is sorted + o Each group of sibling accounts (ie, under a common parent) is sorted separately. Depth limiting - With a depth:NUM query, or --depth NUM option, or just -NUM (eg: -3) - balance reports will show accounts only to the specified depth, hiding - the deeper subaccounts. This can be useful for getting an overview + With a depth:NUM query, or --depth NUM option, or just -NUM (eg: -3) + balance reports will show accounts only to the specified depth, hiding + the deeper subaccounts. This can be useful for getting an overview without too much detail. - Account balances at the depth limit always include the balances from + Account balances at the depth limit always include the balances from any deeper subaccounts (even in list mode). Eg, limiting to depth 1: $ hledger -f examples/sample.journal balance -1 @@ -8823,7 +8854,7 @@ Advanced report commands 0 Dropping top-level accounts - You can also hide one or more top-level account name parts, using + You can also hide one or more top-level account name parts, using --drop NUM. This can be useful for hiding repetitive top-level account names: @@ -8834,54 +8865,54 @@ Advanced report commands $2 Showing declared accounts - With --declared, accounts which have been declared with an account di- - rective will be included in the balance report, even if they have no + With --declared, accounts which have been declared with an account di- + rective will be included in the balance report, even if they have no transactions. (Since they will have a zero balance, you will also need -E/--empty to see them.) - More precisely, leaf declared accounts (with no subaccounts) will be + More precisely, leaf declared accounts (with no subaccounts) will be included, since those are usually the more useful in reports. - The idea of this is to be able to see a useful "complete" balance re- + The idea of this is to be able to see a useful "complete" balance re- port, even when you don't have transactions in all of your declared ac- counts yet. Sorting by amount - With -S/--sort-amount, accounts with the largest (most positive) bal- - ances are shown first. Eg: hledger bal expenses -MAS shows your - biggest averaged monthly expenses first. When more than one commodity - is present, they will be sorted by the alphabetically earliest commod- - ity first, and then by subsequent commodities (if an amount is missing + With -S/--sort-amount, accounts with the largest (most positive) bal- + ances are shown first. Eg: hledger bal expenses -MAS shows your + biggest averaged monthly expenses first. When more than one commodity + is present, they will be sorted by the alphabetically earliest commod- + ity first, and then by subsequent commodities (if an amount is missing a commodity, it is treated as 0). - Revenues and liability balances are typically negative, however, so -S - shows these in reverse order. To work around this, you can add --in- - vert to flip the signs. Or you could use one of the higher-level bal- + Revenues and liability balances are typically negative, however, so -S + shows these in reverse order. To work around this, you can add --in- + vert to flip the signs. Or you could use one of the higher-level bal- ance reports (bs, is..), which flip the sign automatically (eg: hledger is -MAS). Percentages - With -%/--percent, balance reports show each account's value expressed + With -%/--percent, balance reports show each account's value expressed as a percentage of the (column) total. Note it is not useful to calculate percentages if the amounts in a col- - umn have mixed signs. In this case, make a separate report for each + umn have mixed signs. In this case, make a separate report for each sign, eg: $ hledger bal -% amt:`>0` $ hledger bal -% amt:`<0` - Similarly, if the amounts in a column have mixed commodities, convert - them to one commodity with -B, -V, -X or --value, or make a separate + Similarly, if the amounts in a column have mixed commodities, convert + them to one commodity with -B, -V, -X or --value, or make a separate report for each commodity: $ hledger bal -% cur:\\$ $ hledger bal -% cur: Multi-period balance report - With a report interval (set by the -D/--daily, -W/--weekly, - -M/--monthly, -Q/--quarterly, -Y/--yearly, or -p/--period flag), bal- - ance shows a tabular report, with columns representing successive time + With a report interval (set by the -D/--daily, -W/--weekly, + -M/--monthly, -Q/--quarterly, -Y/--yearly, or -p/--period flag), bal- + ance shows a tabular report, with columns representing successive time periods (and a title): $ hledger -f examples/sample.journal bal --quarterly income expenses -E @@ -8902,24 +8933,24 @@ Advanced report commands encompass the displayed subperiods (so that the first and last subpe- riods have the same duration as the others). - o Leading and trailing periods (columns) containing all zeroes are not + o Leading and trailing periods (columns) containing all zeroes are not shown, unless -E/--empty is used. - o Accounts (rows) containing all zeroes are not shown, unless + o Accounts (rows) containing all zeroes are not shown, unless -E/--empty is used. - o Amounts with many commodities are shown in abbreviated form, unless + o Amounts with many commodities are shown in abbreviated form, unless --no-elide is used. - o Average and/or total columns can be added with the -A/--average and + o Average and/or total columns can be added with the -A/--average and -T/--row-total flags. o The --transpose flag can be used to exchange rows and columns. - o The --pivot FIELD option causes a different transaction field to be + o The --pivot FIELD option causes a different transaction field to be used as "account name". See PIVOTING. - o The --summary-only flag (--summary also works) hides all but the To- + o The --summary-only flag (--summary also works) hides all but the To- tal and Average columns (those should be enabled with --row-total and -A/--average). @@ -8938,57 +8969,57 @@ Advanced report commands o Reduce the terminal's font size - o View with a pager like less, eg: hledger bal -D --color=yes | less + o View with a pager like less, eg: hledger bal -D --color=yes | less -RS - o Output as CSV and use a CSV viewer like visidata (hledger bal -D -O - csv | vd -f csv), Emacs' csv-mode (M-x csv-mode, C-c C-a), or a + o Output as CSV and use a CSV viewer like visidata (hledger bal -D -O + csv | vd -f csv), Emacs' csv-mode (M-x csv-mode, C-c C-a), or a spreadsheet (hledger bal -D -o a.csv && open a.csv) - o Output as HTML and view with a browser: hledger bal -D -o a.html && + o Output as HTML and view with a browser: hledger bal -D -o a.html && open a.html Balance change, end balance - It's important to be clear on the meaning of the numbers shown in bal- + It's important to be clear on the meaning of the numbers shown in bal- ance reports. Here is some terminology we use: - A balance change is the net amount added to, or removed from, an ac- + A balance change is the net amount added to, or removed from, an ac- count during some period. - An end balance is the amount accumulated in an account as of some date - (and some time, but hledger doesn't store that; assume end of day in + An end balance is the amount accumulated in an account as of some date + (and some time, but hledger doesn't store that; assume end of day in your timezone). It is the sum of previous balance changes. - We call it a historical end balance if it includes all balance changes + We call it a historical end balance if it includes all balance changes since the account was created. For a real world account, this means it - will match the "historical record", eg the balances reported in your + will match the "historical record", eg the balances reported in your bank statements or bank web UI. (If they are correct!) - In general, balance changes are what you want to see when reviewing + In general, balance changes are what you want to see when reviewing revenues and expenses, and historical end balances are what you want to see when reviewing or reconciling asset, liability and equity accounts. - balance shows balance changes by default. To see accurate historical + balance shows balance changes by default. To see accurate historical end balances: - 1. Initialise account starting balances with an "opening balances" - transaction (a transfer from equity to the account), unless the + 1. Initialise account starting balances with an "opening balances" + transaction (a transfer from equity to the account), unless the journal covers the account's full lifetime. 2. Include all of of the account's prior postings in the report, by not - specifying a report start date, or by using the -H/--historical + specifying a report start date, or by using the -H/--historical flag. (-H causes report start date to be ignored when summing post- ings.) Balance report modes - The balance command is quite flexible; here is the full detail on how - to control what it reports. If the following seems complicated, don't - worry - this is for advanced reporting, and it does take time and ex- + The balance command is quite flexible; here is the full detail on how + to control what it reports. If the following seems complicated, don't + worry - this is for advanced reporting, and it does take time and ex- perimentation to get familiar with all the report modes. There are three important option groups: - hledger balance [CALCULATIONMODE] [ACCUMULATIONMODE] [VALUATIONMODE] + hledger balance [CALCULATIONMODE] [ACCUMULATIONMODE] [VALUATIONMODE] ... Calculation mode @@ -9000,35 +9031,35 @@ Advanced report commands each account/period) o --valuechange : show the change in period-end historical balance val- - ues (caused by deposits, withdrawals, and/or market price fluctua- + ues (caused by deposits, withdrawals, and/or market price fluctua- tions) - o --gain : show the unrealised capital gain/loss, (the current valued + o --gain : show the unrealised capital gain/loss, (the current valued balance minus each amount's original cost) o --count : show the count of postings Accumulation mode - How amounts should accumulate across a report's subperiods/columns. - Another way to say it: which time period's postings should contribute + How amounts should accumulate across a report's subperiods/columns. + Another way to say it: which time period's postings should contribute to each cell's calculation. It is one of: - o --change : calculate with postings from column start to column end, - ie "just this column". Typically used to see revenues/expenses. + o --change : calculate with postings from column start to column end, + ie "just this column". Typically used to see revenues/expenses. (default for balance, cashflow, incomestatement) - o --cumulative : calculate with postings from report start to column - end, ie "previous columns plus this column". Typically used to show + o --cumulative : calculate with postings from report start to column + end, ie "previous columns plus this column". Typically used to show changes accumulated since the report's start date. Not often used. - o --historical/-H : calculate with postings from journal start to col- - umn end, ie "all postings from before report start date until this - column's end". Typically used to see historical end balances of as- - sets/liabilities/equity. (default for balancesheet, balancesheete- + o --historical/-H : calculate with postings from journal start to col- + umn end, ie "all postings from before report start date until this + column's end". Typically used to see historical end balances of as- + sets/liabilities/equity. (default for balancesheet, balancesheete- quity) Valuation mode - Which kind of value or cost conversion should be applied, if any, be- + Which kind of value or cost conversion should be applied, if any, be- fore displaying the report. See Cost reporting and Value reporting for more about conversions. @@ -9036,19 +9067,19 @@ Advanced report commands o no conversion : don't convert to cost or value (default) - o --value=cost[,COMM] : convert amounts to cost (then optionally to + o --value=cost[,COMM] : convert amounts to cost (then optionally to some other commodity) - o --value=then[,COMM] : convert amounts to market value on transaction + o --value=then[,COMM] : convert amounts to market value on transaction dates - o --value=end[,COMM] : convert amounts to market value on period end + o --value=end[,COMM] : convert amounts to market value on period end date(s) (default with --valuechange, --gain) o --value=now[,COMM] : convert amounts to market value on today's date - o --value=YYYY-MM-DD[,COMM] : convert amounts to market value on an- + o --value=YYYY-MM-DD[,COMM] : convert amounts to market value on an- other date or with the legacy -B/-V/-X options, which are equivalent and easier to @@ -9061,17 +9092,17 @@ Advanced report commands o -X COMM/--exchange COMM : like --value=end,COMM Note that --value can also convert to cost, as a convenience; but actu- - ally --cost and --value are independent options, and could be used to- + ally --cost and --value are independent options, and could be used to- gether. Combining balance report modes Most combinations of these modes should produce reasonable reports, but - if you find any that seem wrong or misleading, let us know. The fol- + if you find any that seem wrong or misleading, let us know. The fol- lowing restrictions are applied: o --valuechange implies --value=end - o --valuechange makes --change the default when used with the bal- + o --valuechange makes --change the default when used with the bal- ancesheet/balancesheetequity commands o --cumulative or --historical disables --row-total/-T @@ -9084,18 +9115,18 @@ Advanced report commands Accumu- /now lation:v ----------------------------------------------------------------------------------- - --change change in period sum of post- period-end DATE-value of - ing-date market value of change change in pe- + --change change in period sum of post- period-end DATE-value of + ing-date market value of change change in pe- values in period in period riod - --cumu- change from re- sum of post- period-end DATE-value of - lative port start to ing-date market value of change change from + --cumu- change from re- sum of post- period-end DATE-value of + lative port start to ing-date market value of change change from period end values from re- from report report start port start to pe- start to period to period end riod end end - --his- change from sum of post- period-end DATE-value of + --his- change from sum of post- period-end DATE-value of torical journal start to ing-date market value of change change from /-H period end (his- values from jour- from journal journal start - torical end bal- nal start to pe- start to period to period end + torical end bal- nal start to pe- start to period to period end ance) riod end end Budget report @@ -9106,11 +9137,11 @@ Advanced report commands o Accounts which don't have budget goals are hidden by default. - This is useful for comparing planned and actual income, expenses, time + This is useful for comparing planned and actual income, expenses, time usage, etc. - Periodic transaction rules are used to define budget goals. For exam- - ple, here's a periodic rule defining monthly goals for bus travel and + Periodic transaction rules are used to define budget goals. For exam- + ple, here's a periodic rule defining monthly goals for bus travel and food expenses: ;; Budget @@ -9152,66 +9183,66 @@ Advanced report commands || 0 [ 0% of $430] 0 [ 0% of $430] This is "goal-based budgeting"; you define goals for accounts and peri- - ods, often recurring, and hledger shows performance relative to the - goals. This contrasts with "envelope budgeting", which is more de- - tailed and strict - useful when cash is tight, but also quite a bit - more work. https://plaintextaccounting.org/Budgeting has more on this + ods, often recurring, and hledger shows performance relative to the + goals. This contrasts with "envelope budgeting", which is more de- + tailed and strict - useful when cash is tight, but also quite a bit + more work. https://plaintextaccounting.org/Budgeting has more on this topic. Using the budget report - Historically this report has been confusing and fragile. hledger's - version should be relatively robust and intuitive, but you may still - find surprises. Here are more notes to help with learning and trou- + Historically this report has been confusing and fragile. hledger's + version should be relatively robust and intuitive, but you may still + find surprises. Here are more notes to help with learning and trou- bleshooting. - o In the above example, expenses:bus and expenses:food are shown be- + o In the above example, expenses:bus and expenses:food are shown be- cause they have budget goals during the report period. - o Their parent expenses is also shown, with budget goals aggregated + o Their parent expenses is also shown, with budget goals aggregated from the children. - o The subaccounts expenses:food:groceries and expenses:food:dining are - not shown since they have no budget goal of their own, but they con- + o The subaccounts expenses:food:groceries and expenses:food:dining are + not shown since they have no budget goal of their own, but they con- tribute to expenses:food's actual amount. - o Unbudgeted accounts expenses:movies and expenses:gifts are also not + o Unbudgeted accounts expenses:movies and expenses:gifts are also not shown, but they contribute to expenses's actual amount. - o The other unbudgeted accounts income and assets:bank:checking are + o The other unbudgeted accounts income and assets:bank:checking are grouped as . - o --depth or depth: can be used to limit report depth in the usual way + o --depth or depth: can be used to limit report depth in the usual way (but will not reveal unbudgeted subaccounts). o Amounts are always inclusive of subaccounts (even in -l/--list mode). o Numbers displayed in a --budget report will not always agree with the - totals, because of hidden unbudgeted accounts; this is normal. + totals, because of hidden unbudgeted accounts; this is normal. -E/--empty can be used to reveal the hidden accounts. o In the periodic rules used for setting budget goals, unbalanced post- ings are convenient. - o You can filter budget reports with the usual queries, eg to focus on - particular accounts. It's common to restrict them to just expenses. - (The account is occasionally hard to exclude; this is + o You can filter budget reports with the usual queries, eg to focus on + particular accounts. It's common to restrict them to just expenses. + (The account is occasionally hard to exclude; this is because of date surprises, discussed below.) - o When you have multiple currencies, you may want to convert them to - one (-X COMM --infer-market-prices) and/or show just one at a time - (cur:COMM). If you do need to show multiple currencies at once, + o When you have multiple currencies, you may want to convert them to + one (-X COMM --infer-market-prices) and/or show just one at a time + (cur:COMM). If you do need to show multiple currencies at once, --layout bare can be helpful. - o You can "roll over" amounts (actual and budgeted) to the next period + o You can "roll over" amounts (actual and budgeted) to the next period with --cumulative. See also: https://hledger.org/budgeting.html. Budget date surprises - With small data, or when starting out, some of the generated budget - goal transaction dates might fall outside the report periods. Eg with - the following journal and report, the first period appears to have no - expenses:food budget. (Also the account should be ex- + With small data, or when starting out, some of the generated budget + goal transaction dates might fall outside the report periods. Eg with + the following journal and report, the first period appears to have no + expenses:food budget. (Also the account should be ex- cluded by the expenses query, but isn't.): ~ monthly in 2020 @@ -9231,64 +9262,64 @@ Advanced report commands ---------------++-------------------- || $400 [80% of $500] - In this case, the budget goal transactions are generated on first days - of of month (this can be seen with hledger print --forecast tag:gener- - ated expenses). Whereas the report period defaults to just the 15th - day of january (this can be seen from the report table's column head- + In this case, the budget goal transactions are generated on first days + of of month (this can be seen with hledger print --forecast tag:gener- + ated expenses). Whereas the report period defaults to just the 15th + day of january (this can be seen from the report table's column head- ings). - To fix this kind of thing, be more explicit about the report period - (and/or the periodic rules' dates). In this case, adding -b 2020 does + To fix this kind of thing, be more explicit about the report period + (and/or the periodic rules' dates). In this case, adding -b 2020 does the trick. Selecting budget goals - By default, the budget report uses all available periodic transaction - rules to generate goals. This includes rules with a different report - interval from your report. Eg if you have daily, weekly and monthly - periodic rules, all of these will contribute to the goals in a monthly + By default, the budget report uses all available periodic transaction + rules to generate goals. This includes rules with a different report + interval from your report. Eg if you have daily, weekly and monthly + periodic rules, all of these will contribute to the goals in a monthly budget report. - You can select a subset of periodic rules by providing an argument to - the --budget flag. --budget=DESCPAT will match all periodic rules + You can select a subset of periodic rules by providing an argument to + the --budget flag. --budget=DESCPAT will match all periodic rules whose description contains DESCPAT, a case-insensitive substring (not a - regular expression or query). This means you can give your periodic - rules descriptions (remember that two spaces are needed between period - expression and description), and then select from multiple budgets de- + regular expression or query). This means you can give your periodic + rules descriptions (remember that two spaces are needed between period + expression and description), and then select from multiple budgets de- fined in your journal. Budgeting vs forecasting - --forecast and --budget both use the periodic transaction rules in the - journal to generate temporary transactions for reporting purposes. - However they are separate features - though you can use both at the + --forecast and --budget both use the periodic transaction rules in the + journal to generate temporary transactions for reporting purposes. + However they are separate features - though you can use both at the same time if you want. Here are some differences between them: --forecast --budget -------------------------------------------------------------------------- - is a general option; it enables fore- is a balance command option; it - casting with all reports selects the balance report's + is a general option; it enables fore- is a balance command option; it + casting with all reports selects the balance report's budget mode - generates visible transactions which generates invisible transactions + generates visible transactions which generates invisible transactions appear in reports which produce goal amounts - generates forecast transactions from generates budget goal transac- - after the last regular transaction, to tions throughout the report pe- - the end of the report period; or with riod, optionally restricted by - an argument --forecast=PERIODEXPR gen- periods specified in the peri- - erates them throughout the specified odic transaction rules - period, both optionally restricted by - periods specified in the periodic + generates forecast transactions from generates budget goal transac- + after the last regular transaction, to tions throughout the report pe- + the end of the report period; or with riod, optionally restricted by + an argument --forecast=PERIODEXPR gen- periods specified in the peri- + erates them throughout the specified odic transaction rules + period, both optionally restricted by + periods specified in the periodic transaction rules uses all periodic rules uses all periodic rules; or with an argument --budget=DESCPAT - uses just the rules matched by + uses just the rules matched by DESCPAT Balance report layout The --layout option affects how balance and the other balance-like com- - mands show multi-commodity amounts and commodity symbols. It can im- + mands show multi-commodity amounts and commodity symbols. It can im- prove readability, for humans and/or machines (other software). It has four possible values: - o --layout=wide[,WIDTH]: commodities are shown on a single line, op- + o --layout=wide[,WIDTH]: commodities are shown on a single line, op- tionally elided to WIDTH o --layout=tall: each commodity is shown on a separate line @@ -9296,11 +9327,11 @@ Advanced report commands o --layout=bare: commodity symbols are in their own column, amounts are bare numbers - o --layout=tidy: data is normalised to easily-consumed "tidy" form, - with one row per data value. (This one is currently supported only + o --layout=tidy: data is normalised to easily-consumed "tidy" form, + with one row per data value. (This one is currently supported only by the balance command.) - Here are the --layout modes supported by each output format Only CSV + Here are the --layout modes supported by each output format Only CSV output supports all of them: - txt csv html json sql @@ -9336,7 +9367,7 @@ Advanced report commands || 10.00 ITOT, 337.18 USD, 2 more.. 70.00 GLD, 18.00 ITOT, 3 more.. -11.00 ITOT, 3 more.. 70.00 GLD, 17.00 ITOT, 3 more.. Tall layout - Each commodity gets a new line (may be different in each column), and + Each commodity gets a new line (may be different in each column), and account names are repeated: $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=tall @@ -9357,7 +9388,7 @@ Advanced report commands || 18.00 VHT 294.00 VHT Bare layout - Commodity symbols are kept in one column, each commodity has its own + Commodity symbols are kept in one column, each commodity has its own row, amounts are bare numbers, account names are repeated: $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=bare @@ -9393,15 +9424,15 @@ Advanced report commands "Total:","VEA","36.00" "Total:","VHT","294.00" - Bare layout will sometimes display an extra row for the no-symbol com- - modity, because of zero amounts (hledger treats zeroes as commod- + Bare layout will sometimes display an extra row for the no-symbol com- + modity, because of zero amounts (hledger treats zeroes as commod- ity-less, usually). This can break hledger-bar confusingly (workaround: add a cur: query to exclude the no-symbol row). Tidy layout This produces normalised "tidy data" (see https://cran.r-project.org/web/packages/tidyr/vignettes/tidy-data.html) - where every variable has its own column and each row represents a sin- + where every variable has its own column and each row represents a sin- gle data point. This is the easiest kind of data for other software to consume: @@ -9424,40 +9455,40 @@ Advanced report commands "Assets:US:ETrade","2014","2014-01-01","2014-12-31","VHT","170.00" Balance report output - As noted in Output format, if you choose HTML output (by using -O html + As noted in Output format, if you choose HTML output (by using -O html or -o somefile.html), you can create a hledger.css file in the same di- rectory to customise the report's appearance. The HTML and FODS output formats can generate hyperlinks to a - hledger-web register view for each account and period. E.g. if your + hledger-web register view for each account and period. E.g. if your hledger-web server is reachable at http://localhost:5000 then you might - run the balance command with the extra option --base-url=http://local- - host:5000. You can also produce relative links, like + run the balance command with the extra option --base-url=http://local- + host:5000. You can also produce relative links, like --base-url="some/path" or --base-url="".) Some useful balance reports Some frequently used balance options/reports are: o bal -M revenues expenses - Show revenues/expenses in each month. Also available as the incomes- + Show revenues/expenses in each month. Also available as the incomes- tatement command. o bal -M -H assets liabilities - Show historical asset/liability balances at each month end. Also + Show historical asset/liability balances at each month end. Also available as the balancesheet command. o bal -M -H assets liabilities equity - Show historical asset/liability/equity balances at each month end. + Show historical asset/liability/equity balances at each month end. Also available as the balancesheetequity command. o bal -M assets not:receivable - Show changes to liquid assets in each month. Also available as the + Show changes to liquid assets in each month. Also available as the cashflow command. Also: o bal -M expenses -2 -SA - Show monthly expenses summarised to depth 2 and sorted by average + Show monthly expenses summarised to depth 2 and sorted by average amount. o bal -M --budget expenses @@ -9471,7 +9502,7 @@ Advanced report commands Show top gainers [or losers] last week roi - Shows the time-weighted (TWR) and money-weighted (IRR) rate of return + Shows the time-weighted (TWR) and money-weighted (IRR) rate of return on your investments. Flags: @@ -9481,38 +9512,38 @@ Advanced report commands --profit-loss=QUERY --pnl query to select profit-and-loss or appreciation/valuation transactions - At a minimum, you need to supply a query (which could be just an ac- - count name) to select your investment(s) with --inv, and another query + At a minimum, you need to supply a query (which could be just an ac- + count name) to select your investment(s) with --inv, and another query to identify your profit and loss transactions with --pnl. - If you do not record changes in the value of your investment manually, - or do not require computation of time-weighted return (TWR), --pnl + If you do not record changes in the value of your investment manually, + or do not require computation of time-weighted return (TWR), --pnl could be an empty query (--pnl "" or --pnl STR where STR does not match any of your accounts). - This command will compute and display the internalized rate of return - (IRR, also known as money-weighted rate of return) and time-weighted - rate of return (TWR) for your investments for the time period re- - quested. IRR is always annualized due to the way it is computed, but - TWR is reported both as a rate over the chosen reporting period and as + This command will compute and display the internalized rate of return + (IRR, also known as money-weighted rate of return) and time-weighted + rate of return (TWR) for your investments for the time period re- + quested. IRR is always annualized due to the way it is computed, but + TWR is reported both as a rate over the chosen reporting period and as an annual rate. - Price directives will be taken into account if you supply appropriate + Price directives will be taken into account if you supply appropriate --cost or --value flags (see VALUATION). Note, in some cases this report can fail, for these reasons: - o Error (NotBracketed): No solution for Internal Rate of Return (IRR). - Possible causes: IRR is huge (>1000000%), balance of investment be- + o Error (NotBracketed): No solution for Internal Rate of Return (IRR). + Possible causes: IRR is huge (>1000000%), balance of investment be- comes negative at some point in time. - o Error (SearchFailed): Failed to find solution for Internal Rate of + o Error (SearchFailed): Failed to find solution for Internal Rate of Return (IRR). Either search does not converge to a solution, or con- verges too slowly. Examples: - o Using roi to compute total return of investment in stocks: + o Using roi to compute total return of investment in stocks: https://github.com/simonmichael/hledger/blob/master/examples/invest- ing/roi-unrealised.ledger @@ -9522,28 +9553,28 @@ Advanced report commands Note that --inv and --pnl's argument is a query, and queries could have several space-separated terms (see QUERIES). - To indicate that all search terms form single command-line argument, + To indicate that all search terms form single command-line argument, you will need to put them in quotes (see Special characters): $ hledger roi --inv 'term1 term2 term3 ...' - If any query terms contain spaces themselves, you will need an extra + If any query terms contain spaces themselves, you will need an extra level of nested quoting, eg: $ hledger roi --inv="'Assets:Test 1'" --pnl="'Equity:Unrealized Profit and Loss'" Semantics of --inv and --pnl - Query supplied to --inv has to match all transactions that are related + Query supplied to --inv has to match all transactions that are related to your investment. Transactions not matching --inv will be ignored. In these transactions, ROI will conside postings that match --inv to be - "investment postings" and other postings (not matching --inv) will be - sorted into two categories: "cash flow" and "profit and loss", as ROI - needs to know which part of the investment value is your contributions + "investment postings" and other postings (not matching --inv) will be + sorted into two categories: "cash flow" and "profit and loss", as ROI + needs to know which part of the investment value is your contributions and which is due to the return on investment. o "Cash flow" is depositing or withdrawing money, buying or selling as- - sets, or otherwise converting between your investment commodity and + sets, or otherwise converting between your investment commodity and any other commodity. Example: 2019-01-01 Investing in Snake Oil @@ -9560,12 +9591,12 @@ Advanced report commands investment:snake oil = $57 equity:unrealized profit or loss - All non-investment postings are assumed to be "cash flow", unless they - match --pnl query. Changes in value of your investment due to "profit - and loss" postings will be considered as part of your investment re- + All non-investment postings are assumed to be "cash flow", unless they + match --pnl query. Changes in value of your investment due to "profit + and loss" postings will be considered as part of your investment re- turn. - Example: if you use --inv snake --pnl equity:unrealized, then postings + Example: if you use --inv snake --pnl equity:unrealized, then postings in the example below would be classifed as: 2019-01-01 Snake Oil #1 @@ -9582,58 +9613,58 @@ Advanced report commands snake oil $50 ; investment posting IRR and TWR explained - "ROI" stands for "return on investment". Traditionally this was com- - puted as a difference between current value of investment and its ini- + "ROI" stands for "return on investment". Traditionally this was com- + puted as a difference between current value of investment and its ini- tial value, expressed in percentage of the initial value. However, this approach is only practical in simple cases, where invest- - ments receives no in-flows or out-flows of money, and where rate of + ments receives no in-flows or out-flows of money, and where rate of growth is fixed over time. For more complex scenarios you need differ- - ent ways to compute rate of return, and this command implements two of + ent ways to compute rate of return, and this command implements two of them: IRR and TWR. - Internal rate of return, or "IRR" (also called "money-weighted rate of - return") takes into account effects of in-flows and out-flows, and the - time between them. Investment at a particular fixed interest rate is - going to give you more interest than the same amount invested at the - same interest rate, but made later in time. If you are withdrawing - from your investment, your future gains would be smaller (in absolute - numbers), and will be a smaller percentage of your initial investment, + Internal rate of return, or "IRR" (also called "money-weighted rate of + return") takes into account effects of in-flows and out-flows, and the + time between them. Investment at a particular fixed interest rate is + going to give you more interest than the same amount invested at the + same interest rate, but made later in time. If you are withdrawing + from your investment, your future gains would be smaller (in absolute + numbers), and will be a smaller percentage of your initial investment, so your IRR will be smaller. And if you are adding to your investment, you will receive bigger absolute gains, which will be a bigger percent- age of your initial investment, so your IRR will be larger. - As mentioned before, in-flows and out-flows would be any cash that you + As mentioned before, in-flows and out-flows would be any cash that you personally put in or withdraw, and for the "roi" command, these are the - postings that match the query in the--inv argument and NOT match the + postings that match the query in the--inv argument and NOT match the query in the--pnl argument. - If you manually record changes in the value of your investment as - transactions that balance them against "profit and loss" (or "unreal- - ized gains") account or use price directives, then in order for IRR to - compute the precise effect of your in-flows and out-flows on the rate - of return, you will need to record the value of your investement on or + If you manually record changes in the value of your investment as + transactions that balance them against "profit and loss" (or "unreal- + ized gains") account or use price directives, then in order for IRR to + compute the precise effect of your in-flows and out-flows on the rate + of return, you will need to record the value of your investement on or close to the days when in- or out-flows occur. - In technical terms, IRR uses the same approach as computation of net + In technical terms, IRR uses the same approach as computation of net present value, and tries to find a discount rate that makes net present value of all the cash flows of your investment to add up to zero. This - could be hard to wrap your head around, especially if you haven't done + could be hard to wrap your head around, especially if you haven't done discounted cash flow analysis before. Implementation of IRR in hledger should produce results that match the =XIRR formula in Excel. - Second way to compute rate of return that roi command implements is - called "time-weighted rate of return" or "TWR". Like IRR, it will ac- - count for the effect of your in-flows and out-flows, but unlike IRR it - will try to compute the true rate of return of the underlying asset, - compensating for the effect that deposits and withdrawas have on the + Second way to compute rate of return that roi command implements is + called "time-weighted rate of return" or "TWR". Like IRR, it will ac- + count for the effect of your in-flows and out-flows, but unlike IRR it + will try to compute the true rate of return of the underlying asset, + compensating for the effect that deposits and withdrawas have on the apparent rate of growth of your investment. - TWR represents your investment as an imaginary "unit fund" where - in-flows/ out-flows lead to buying or selling "units" of your invest- - ment and changes in its value change the value of "investment unit". - Change in "unit price" over the reporting period gives you rate of re- - turn of your investment, and make TWR less sensitive than IRR to the + TWR represents your investment as an imaginary "unit fund" where + in-flows/ out-flows lead to buying or selling "units" of your invest- + ment and changes in its value change the value of "investment unit". + Change in "unit price" over the reporting period gives you rate of re- + turn of your investment, and make TWR less sensitive than IRR to the effects of cash in-flows and out-flows. References: @@ -9646,7 +9677,7 @@ Advanced report commands o IRR vs TWR - o Examples of computing IRR and TWR and discussion of the limitations + o Examples of computing IRR and TWR and discussion of the limitations of both metrics Chart commands @@ -9656,8 +9687,8 @@ Chart commands Flags: no command-specific flags - The activity command displays an ascii histogram showing transaction - counts by day, week, month or other reporting interval (by day is the + The activity command displays an ascii histogram showing transaction + counts by day, week, month or other reporting interval (by day is the default). With query arguments, it counts only matched transactions. Examples: @@ -9672,10 +9703,10 @@ Data generation commands close (equity) - close prints several kinds of "closing" and/or "opening" transactions, + close prints several kinds of "closing" and/or "opening" transactions, useful in various situations: migrating balances to a new journal file, - retaining earnings into equity, consolidating balances, viewing lot - costs.. Like print, it prints valid journal entries. You can copy + retaining earnings into equity, consolidating balances, viewing lot + costs.. Like print, it prints valid journal entries. You can copy these into your journal file(s) when you are happy with how they look. Flags: @@ -9706,9 +9737,18 @@ Data generation commands all - also round cost amounts to precision (can unbalance transactions) - close has six modes, selected by choosing one of the mode flags - (--close is the default). They all do much the same operation, but - with different defaults, useful in different situations. + close has six modes, selected by choosing one of the mode flags: + --clopen, --close (default), --open, --assert, --assign, or --retain. + 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 This is useful if migrating balances to a new journal file at the start @@ -9746,22 +9786,17 @@ Data generation commands Assertions will be added indicating and checking the new balances of 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 - 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. - More customisation options are described below. Among other things, + More customisation options are described below. Among other things, you can use close --close to generate a transaction moving the balances from any set of accounts, to a different account. (If you need to move just a portion of the balance, see hledger-move.) close --open - This prints just the opening balances transaction of --clopen. (It is + This prints just the opening balances transaction of --clopen. (It is similar to Ledger's equity command.) close --assert @@ -9771,29 +9806,29 @@ Data generation commands close --assign This prints a transaction that assigns the account balances as they are - on the end date (and adds an "assign:" tag). Unlike balance asser- + on the end date (and adds an "assign:" tag). Unlike balance asser- tions, assignments will post changes to balances as needed to reach the specified amounts. - This is another way to set starting balances when migrating to a new - file, and it will set them correctly even in the presence of earlier - files which do not have a closing balances transaction. However, it - can hide errors, and disturb the accounting equation, so --clopen is + This is another way to set starting balances when migrating to a new + file, and it will set them correctly even in the presence of earlier + files which do not have a closing balances transaction. However, it + can hide errors, and disturb the accounting equation, so --clopen is usually recommended. close --retain - This is like --close, but it closes Revenue and Expense account bal- - ances by default. They will be transferred to equity:retained earn- + This is like --close, but it closes Revenue and Expense account bal- + ances by default. They will be transferred to equity:retained earn- ings, or another account specified with --close-acct. - Revenues and expenses correspond to changes in equity. They are cate- + Revenues and expenses correspond to changes in equity. They are cate- gorised separately for reporting purposes, but traditionally at the end - of each accounting period, businesses consolidate them into equity, + of each accounting period, businesses consolidate them into equity, This is called "retaining earnings", or "closing the books". - In personal accounting, there's not much reason to do this, and most - people don't. (One reason to do it is to help the balancesheetequity - report show a zero total, demonstrating that the accounting equation + In personal accounting, there's not much reason to do this, and most + people don't. (One reason to do it is to help the balancesheetequity + report show a zero total, demonstrating that the accounting equation (A-L=E) is satisfied.) close customisation @@ -9801,14 +9836,15 @@ Data generation commands 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 transaction descriptions, with --close-desc=DESC and + o the transaction descriptions, with --close-desc=DESC and --open-desc=DESC - o the transaction's tag value, with a --MODE=NEW option argument - - o the closing/opening dates, with -e OPENDATE + o the transactions' clopen tag value, with a TAGVAL argument for the + mode flag (see above). 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 @@ -10094,9 +10130,7 @@ Maintenance commands wrong conversions caused by typos. o commodities - all commodity symbols used must be declared. This - guards against mistyping or omitting commodity symbols. Declaring - commodities also sets their precision for display and transaction - balancing. + guards against mistyping or omitting commodity symbols. o accounts - all account names used must be declared. This prevents 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 hledger. -Getting help + Getting help Here's how to list commands and view options and command docs: $ hledger # show available commands @@ -10284,7 +10318,7 @@ Getting help https://hledger.org. Chat and mail list support and discussion 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 simple and ergonomic, but if you run into one of the sharp edges de- 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. -Starting a journal file + Starting a journal file hledger looks for your accounting data in a journal file, $HOME/.hledger.journal by default: @@ -10336,41 +10370,91 @@ Starting a journal file Commodities : 0 () Market prices : 0 () -Setting LEDGER_FILE - How to set LEDGER_FILE permanently depends on your setup: + Setting LEDGER_FILE + 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 - many people; adapt as needed: - - $ echo 'export LEDGER_FILE=~/finance/2023.journal' >> ~/.profile + $ echo 'export LEDGER_FILE=~/finance/my.journal' >> ~/.profile $ source ~/.profile - When correctly configured, in a new terminal window env | grep - LEDGER_FILE will show your file, and so will hledger files. + When correctly configured: - On mac, this additional step might be helpful for GUI applications - (like Emacs started from the dock): add an entry to ~/.MacOSX/environ- - ment.plist like + o env | grep LEDGER_FILE will show your new setting - { - "LEDGER_FILE" : "~/finance/2023.journal" - } + o and so should hledger setup and (once the file exists) hledger files. - and then run killall Dock in a terminal window (or restart the ma- - chine). + Set LEDGER_FILE on mac + In a terminal window, follow the unix procedure above. - On Windows, see https://www.java.com/en/download/help/path.html, or try - 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): + Also, this optional step may be helpful for GUI applications: - > CD - > MKDIR finance - > SETX LEDGER_FILE "C:\Users\USERNAME\finance\2023.journal" + 1. Add an entry to ~/.MacOSX/environment.plist like - When correctly configured, in a new terminal window $env:LEDGER_FILE - will show the file path, and so will hledger files. + { + "LEDGER_FILE" : "~/finance/my.journal" + } -Setting opening balances + 2. Run killall Dock in a terminal window (or restart the machine), to + complete the change. + + When correctly configured for GUI applications: + + o apps started from the dock or a spotlight search, such as a GUI + Emacs, will be aware of the new LEDGER_FILE setting. + + Set LEDGER_FILE on Windows + Using the gui is easiest: + + 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 real-world assets (bank accounts, wallet..) and liabilities (credit cards..). @@ -10448,7 +10532,7 @@ Setting opening balances $ git commit -m 'initial balances' 2023.journal -Recording transactions + Recording transactions 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 hledger-iadd or hledger-web add-ons, or by using the import command to @@ -10469,7 +10553,7 @@ Recording transactions income:salary assets:bank:checking $1000 -Reconciling + Reconciling Periodically you should reconcile - compare your hledger-reported bal- ances against external sources of truth, like bank statements or your bank's website - to be sure that your ledger accurately represents the @@ -10519,7 +10603,7 @@ Reconciling $ git commit -m 'txns' 2023.journal -Reporting + Reporting Here are some basic reports. Show all transactions: @@ -10662,7 +10746,7 @@ Reporting 2023-01-06 **** 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 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 @@ -10739,4 +10823,4 @@ LICENSE SEE ALSO 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)