From 3f3672e9998ea2efd908d31da5bbe19ea6c9261e Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Sat, 1 Jun 2024 13:30:47 -1000 Subject: [PATCH] ;doc: update manuals --- hledger-lib/.date.m4 | 2 +- hledger-ui/.date.m4 | 2 +- hledger-ui/hledger-ui.1 | 83 +- hledger-ui/hledger-ui.info | 177 +-- hledger-ui/hledger-ui.txt | 303 +++-- hledger-web/.date.m4 | 2 +- hledger-web/hledger-web.1 | 115 +- hledger-web/hledger-web.info | 152 +-- hledger-web/hledger-web.txt | 105 +- hledger/.date.m4 | 2 +- hledger/hledger.1 | 175 ++- hledger/hledger.info | 2280 +++++++++++++++++----------------- hledger/hledger.txt | 275 ++-- 13 files changed, 1803 insertions(+), 1870 deletions(-) diff --git a/hledger-lib/.date.m4 b/hledger-lib/.date.m4 index 4e27a7647..705091ff8 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_}}, {{May 2024}})m4_dnl +m4_define({{_monthyear_}}, {{June 2024}})m4_dnl diff --git a/hledger-ui/.date.m4 b/hledger-ui/.date.m4 index 4e27a7647..705091ff8 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_}}, {{May 2024}})m4_dnl +m4_define({{_monthyear_}}, {{June 2024}})m4_dnl diff --git a/hledger-ui/hledger-ui.1 b/hledger-ui/hledger-ui.1 index 48645102f..7eeb19b1b 100644 --- a/hledger-ui/hledger-ui.1 +++ b/hledger-ui/hledger-ui.1 @@ -1,5 +1,5 @@ -.TH "HLEDGER\-UI" "1" "May 2024" "hledger-ui-1.33.99 " "hledger User Manuals" +.TH "HLEDGER\-UI" "1" "June 2024" "hledger-ui-1.34.99 " "hledger User Manuals" @@ -11,9 +11,13 @@ robust, friendly plain text accounting app. .PD 0 .P .PD +or +.PD 0 +.P +.PD \f[CR]hledger ui \-\- [OPTS] [QUERYARGS]\f[R] .SH DESCRIPTION -This manual is for hledger\[aq]s terminal interface, version 1.33.99. +This manual is for hledger\[aq]s terminal interface, version 1.34.99. See also the hledger manual for common concepts and file formats. .PP hledger is a robust, user\-friendly, cross\-platform set of programs for @@ -42,47 +46,27 @@ They can be revealed, along with any rule\-generated periodic transactions, by pressing the F key (or starting with \-\-forecast) to enable \[dq]forecast mode\[dq]. .SH OPTIONS -Any QUERYARGS are interpreted as a hledger search query which filters -the data. -.PP +Any arguments are interpreted as a hledger query which filters the data. hledger\-ui provides the following options: -.TP -\f[CR]\-w \-\-watch\f[R] -watch for data and date changes and reload automatically -.TP -\f[CR]\-\-theme=default|terminal|greenterm|dark\f[R] -use this custom display theme -.TP -\f[CR]\-\-menu\f[R] -start in the menu screen -.TP -\f[CR]\-\-cash\f[R] -start in the cash accounts screen -.TP -\f[CR]\-\-bs\f[R] -start in the balance sheet accounts screen -.TP -\f[CR]\-\-is\f[R] -start in the income statement accounts screen -.TP -\f[CR]\-\-all\f[R] -start in the all accounts screen -.TP -\f[CR]\-\-register=ACCTREGEX\f[R] -start in the (first) matched account\[aq]s register screen -.TP -\f[CR]\-\-change\f[R] -show period balances (changes) at startup instead of historical balances -.TP -\f[CR]\-l \-\-flat\f[R] -show accounts as a flat list (default) -.TP -\f[CR]\-t \-\-tree\f[R] -show accounts as a tree +.IP +.EX +Flags: + \-w \-\-watch watch for data and date changes and reload + automatically + \-\-theme=THEME use this custom display theme (default, + greenterm, terminal, dark) + \-\-cash start in the cash accounts screen + \-\-bs start in the balance sheet accounts screen + \-\-is start in the income statement accounts screen + \-\-all start in the all accounts screen + \-\-register=ACCTREGEX start in the (first matched) account\[aq]s register + \-\-change show period balances (changes) at startup instead + of historical balances + \-l \-\-flat show accounts as a flat list (default) + \-t \-\-tree show accounts as a tree +.EE .PP -hledger\-ui also supports many of hledger\[aq]s general options (and the -hledger manual\[aq]s command line tips also apply here): -.SS General options +and also supports many of hledger\[aq]s general options: .IP .EX General input/data transformation flags: @@ -151,7 +135,6 @@ General output/reporting flags (supported by some commands): Eg: \-c \[aq].\[aq] or \-c \[aq]1.000,00 EUR\[aq] \-\-color=YN \-\-colour Use ANSI color codes in text output? Can be \[aq]y\[aq]/\[aq]yes\[aq]/\[aq]always\[aq], \[aq]n\[aq]/\[aq]no\[aq]/\[aq]never\[aq] or \[aq]auto\[aq]. - (A NO_COLOR environment variable overrides this.) \-\-pretty[=YN] Use box\-drawing characters in text output? Can be \[aq]y\[aq]/\[aq]yes\[aq] or \[aq]n\[aq]/\[aq]no\[aq]. If YN is specified, the equals is required. @@ -160,10 +143,13 @@ General output/reporting flags (supported by some commands): General help flags: \-h \-\-help show command line help \-\-tldr show command examples with tldr - \-\-info show the hledger manual with info - \-\-man show the hledger manual with man + \-\-info show the manual with info + \-\-man show the manual with man \-\-version show version information .EE +.PP +With hledger\-ui, the \f[CR]\-\-debug\f[R] option sends debug output to +a \f[CR]hledger\-ui.log\f[R] file in the current directory. .SH MOUSE In most modern terminals, you can navigate through the screens with a mouse or touchpad: @@ -417,8 +403,7 @@ when you press g to reload. Once you have fixed the problem, press g again to reload and resume normal operation. (Or, you can press escape to cancel the reload attempt.) -.SH TIPS -.SS Watch mode +.SH WATCH MODE One of hledger\-ui\[aq]s best features is the auto\-reloading \f[CR]\-w/\-\-watch\f[R] mode. With this flag, it will update the display automatically whenever @@ -458,12 +443,6 @@ know.) .PP If you are viewing files mounted from another machine, the system clocks on both machines should be roughly in agreement. -.SS Debug output -You can add \f[CR]\-\-debug[=N]\f[R] to the command line to log debug -output. -This will be logged to the file \f[CR]hledger\-ui.log\f[R] in the -current directory. -N ranges from 1 (least output, the default) to 9 (maximum output). .SH ENVIRONMENT \f[B]COLUMNS\f[R] The screen width to use. Default: the full terminal width. diff --git a/hledger-ui/hledger-ui.info b/hledger-ui/hledger-ui.info index 5d1172872..43e4ef0ee 100644 --- a/hledger-ui/hledger-ui.info +++ b/hledger-ui/hledger-ui.info @@ -15,9 +15,10 @@ hledger-ui - terminal interface (TUI) for 'hledger', a robust, friendly plain text accounting app. 'hledger-ui [OPTS] [QUERYARGS]' +or 'hledger ui -- [OPTS] [QUERYARGS]' - This manual is for hledger's terminal interface, version 1.33.99. + This manual is for hledger's terminal interface, version 1.34.99. See also the hledger manual for common concepts and file formats. hledger is a robust, user-friendly, cross-platform set of programs @@ -49,7 +50,7 @@ enable "forecast mode". * MOUSE:: * KEYS:: * SCREENS:: -* TIPS:: +* WATCH MODE:: * ENVIRONMENT:: * BUGS:: @@ -59,58 +60,25 @@ File: hledger-ui.info, Node: OPTIONS, Next: MOUSE, Prev: Top, Up: Top 1 OPTIONS ********* -Any QUERYARGS are interpreted as a hledger search query which filters -the data. +Any arguments are interpreted as a hledger query which filters the data. +hledger-ui provides the following options: - hledger-ui provides the following options: +Flags: + -w --watch watch for data and date changes and reload + automatically + --theme=THEME use this custom display theme (default, + greenterm, terminal, dark) + --cash start in the cash accounts screen + --bs start in the balance sheet accounts screen + --is start in the income statement accounts screen + --all start in the all accounts screen + --register=ACCTREGEX start in the (first matched) account's register + --change show period balances (changes) at startup instead + of historical balances + -l --flat show accounts as a flat list (default) + -t --tree show accounts as a tree -'-w --watch' - - watch for data and date changes and reload automatically -'--theme=default|terminal|greenterm|dark' - - use this custom display theme -'--menu' - - start in the menu screen -'--cash' - - start in the cash accounts screen -'--bs' - - start in the balance sheet accounts screen -'--is' - - start in the income statement accounts screen -'--all' - - start in the all accounts screen -'--register=ACCTREGEX' - - start in the (first) matched account's register screen -'--change' - - show period balances (changes) at startup instead of historical - balances -'-l --flat' - - show accounts as a flat list (default) -'-t --tree' - - show accounts as a tree - - hledger-ui also supports many of hledger's general options (and the -hledger manual's command line tips also apply here): - -* Menu: - -* General options:: - - -File: hledger-ui.info, Node: General options, Up: OPTIONS - -1.1 General options -=================== + and also supports many of hledger's general options: General input/data transformation flags: -f --file=FILE Read data from FILE, or from stdin if -. Can be @@ -178,7 +146,6 @@ General output/reporting flags (supported by some commands): Eg: -c '.' or -c '1.000,00 EUR' --color=YN --colour Use ANSI color codes in text output? Can be 'y'/'yes'/'always', 'n'/'no'/'never' or 'auto'. - (A NO_COLOR environment variable overrides this.) --pretty[=YN] Use box-drawing characters in text output? Can be 'y'/'yes' or 'n'/'no'. If YN is specified, the equals is required. @@ -187,10 +154,13 @@ General output/reporting flags (supported by some commands): General help flags: -h --help show command line help --tldr show command examples with tldr - --info show the hledger manual with info - --man show the hledger manual with man + --info show the manual with info + --man show the manual with man --version show version information + With hledger-ui, the '--debug' option sends debug output to a +'hledger-ui.log' file in the current directory. +  File: hledger-ui.info, Node: MOUSE, Next: KEYS, Prev: OPTIONS, Up: Top @@ -309,7 +279,7 @@ amount values. Additional screen-specific keys are described below.  -File: hledger-ui.info, Node: SCREENS, Next: TIPS, Prev: KEYS, Up: Top +File: hledger-ui.info, Node: SCREENS, Next: WATCH MODE, Prev: KEYS, Up: Top 4 SCREENS ********* @@ -485,21 +455,10 @@ again to reload and resume normal operation. (Or, you can press escape to cancel the reload attempt.)  -File: hledger-ui.info, Node: TIPS, Next: ENVIRONMENT, Prev: SCREENS, Up: Top +File: hledger-ui.info, Node: WATCH MODE, Next: ENVIRONMENT, Prev: SCREENS, Up: Top -5 TIPS -****** - -* Menu: - -* Watch mode:: -* Debug output:: - - -File: hledger-ui.info, Node: Watch mode, Next: Debug output, Up: TIPS - -5.1 Watch mode -============== +5 WATCH MODE +************ One of hledger-ui's best features is the auto-reloading '-w/--watch' mode. With this flag, it will update the display automatically whenever @@ -536,17 +495,7 @@ work around, press 'g' to reload manually, or try #1617's clocks on both machines should be roughly in agreement.  -File: hledger-ui.info, Node: Debug output, Prev: Watch mode, Up: TIPS - -5.2 Debug output -================ - -You can add '--debug[=N]' to the command line to log debug output. This -will be logged to the file 'hledger-ui.log' in the current directory. N -ranges from 1 (least output, the default) to 9 (maximum output). - - -File: hledger-ui.info, Node: ENVIRONMENT, Next: BUGS, Prev: TIPS, Up: Top +File: hledger-ui.info, Node: ENVIRONMENT, Next: BUGS, Prev: WATCH MODE, Up: Top 6 ENVIRONMENT ************* @@ -581,42 +530,36 @@ above).  Tag Table: Node: Top221 -Node: OPTIONS1863 -Ref: #options1961 -Node: General options2928 -Ref: #general-options3032 -Node: MOUSE8182 -Ref: #mouse8277 -Node: KEYS8514 -Ref: #keys8607 -Node: SCREENS13262 -Ref: #screens13360 -Node: Menu screen13996 -Ref: #menu-screen14117 -Node: Cash accounts screen14312 -Ref: #cash-accounts-screen14489 -Node: Balance sheet accounts screen14673 -Ref: #balance-sheet-accounts-screen14889 -Node: Income statement accounts screen15009 -Ref: #income-statement-accounts-screen15230 -Node: All accounts screen15394 -Ref: #all-accounts-screen15575 -Node: Register screen15757 -Ref: #register-screen15916 -Node: Transaction screen18200 -Ref: #transaction-screen18358 -Node: Error screen19775 -Ref: #error-screen19897 -Node: TIPS20141 -Ref: #tips20240 -Node: Watch mode20282 -Ref: #watch-mode20389 -Node: Debug output21848 -Ref: #debug-output21959 -Node: ENVIRONMENT22171 -Ref: #environment22281 -Node: BUGS22472 -Ref: #bugs22555 +Node: OPTIONS1872 +Ref: #options1970 +Node: MOUSE8150 +Ref: #mouse8245 +Node: KEYS8482 +Ref: #keys8575 +Node: SCREENS13230 +Ref: #screens13334 +Node: Menu screen13970 +Ref: #menu-screen14091 +Node: Cash accounts screen14286 +Ref: #cash-accounts-screen14463 +Node: Balance sheet accounts screen14647 +Ref: #balance-sheet-accounts-screen14863 +Node: Income statement accounts screen14983 +Ref: #income-statement-accounts-screen15204 +Node: All accounts screen15368 +Ref: #all-accounts-screen15549 +Node: Register screen15731 +Ref: #register-screen15890 +Node: Transaction screen18174 +Ref: #transaction-screen18332 +Node: Error screen19749 +Ref: #error-screen19871 +Node: WATCH MODE20115 +Ref: #watch-mode20232 +Node: ENVIRONMENT21691 +Ref: #environment21807 +Node: BUGS21998 +Ref: #bugs22081  End Tag Table diff --git a/hledger-ui/hledger-ui.txt b/hledger-ui/hledger-ui.txt index 813f72300..e00bd1916 100644 --- a/hledger-ui/hledger-ui.txt +++ b/hledger-ui/hledger-ui.txt @@ -7,10 +7,11 @@ NAME SYNOPSIS hledger-ui [OPTS] [QUERYARGS] + or hledger ui -- [OPTS] [QUERYARGS] DESCRIPTION - This manual is for hledger's terminal interface, version 1.33.99. See + This manual is for hledger's terminal interface, version 1.34.99. See also the hledger manual for common concepts and file formats. hledger is a robust, user-friendly, cross-platform set of programs for @@ -37,44 +38,26 @@ DESCRIPTION enable "forecast mode". OPTIONS - Any QUERYARGS are interpreted as a hledger search query which filters - the data. + Any arguments are interpreted as a hledger query which filters the + data. hledger-ui provides the following options: - hledger-ui provides the following options: + Flags: + -w --watch watch for data and date changes and reload + automatically + --theme=THEME use this custom display theme (default, + greenterm, terminal, dark) + --cash start in the cash accounts screen + --bs start in the balance sheet accounts screen + --is start in the income statement accounts screen + --all start in the all accounts screen + --register=ACCTREGEX start in the (first matched) account's register + --change show period balances (changes) at startup instead + of historical balances + -l --flat show accounts as a flat list (default) + -t --tree show accounts as a tree - -w --watch - watch for data and date changes and reload automatically + and also supports many of hledger's general options: - --theme=default|terminal|greenterm|dark - use this custom display theme - - --menu start in the menu screen - - --cash start in the cash accounts screen - - --bs start in the balance sheet accounts screen - - --is start in the income statement accounts screen - - --all start in the all accounts screen - - --register=ACCTREGEX - start in the (first) matched account's register screen - - --change - show period balances (changes) at startup instead of historical - balances - - -l --flat - show accounts as a flat list (default) - - -t --tree - show accounts as a tree - - hledger-ui also supports many of hledger's general options (and the - hledger manual's command line tips also apply here): - - General options General input/data transformation flags: -f --file=FILE Read data from FILE, or from stdin if -. Can be specified more than once. If not specified, reads @@ -141,7 +124,6 @@ OPTIONS Eg: -c '.' or -c '1.000,00 EUR' --color=YN --colour Use ANSI color codes in text output? Can be 'y'/'yes'/'always', 'n'/'no'/'never' or 'auto'. - (A NO_COLOR environment variable overrides this.) --pretty[=YN] Use box-drawing characters in text output? Can be 'y'/'yes' or 'n'/'no'. If YN is specified, the equals is required. @@ -150,12 +132,15 @@ OPTIONS General help flags: -h --help show command line help --tldr show command examples with tldr - --info show the hledger manual with info - --man show the hledger manual with man + --info show the manual with info + --man show the manual with man --version show version information + With hledger-ui, the --debug option sends debug output to a + hledger-ui.log file in the current directory. + MOUSE - In most modern terminals, you can navigate through the screens with a + In most modern terminals, you can navigate through the screens with a mouse or touchpad: o Use mouse wheel or trackpad to scroll up and down @@ -167,95 +152,95 @@ MOUSE KEYS Keyboard gives more control. - ? shows a help dialog listing all keys. (Some of these also appear in - the quick help at the bottom of each screen.) Press ? again (or ES- - CAPE, or LEFT, or q) to close it. The following keys work on most + ? shows a help dialog listing all keys. (Some of these also appear in + the quick help at the bottom of each screen.) Press ? again (or ES- + CAPE, or LEFT, or q) to close it. The following keys work on most screens: - The cursor keys navigate: RIGHT or ENTER goes deeper, LEFT returns to + The cursor keys navigate: RIGHT or ENTER goes deeper, LEFT returns to the previous screen, UP/DOWN/PGUP/PGDN/HOME/END move up and down - through lists. Emacs-style (CTRL-p/CTRL-n/CTRL-f/CTRL-b) and VI-style - (k,j,l,h) movement keys are also supported. A tip: movement speed is - limited by your keyboard repeat rate, to move faster you may want to - adjust it. (If you're on a mac, the karabiner app is one way to do + through lists. Emacs-style (CTRL-p/CTRL-n/CTRL-f/CTRL-b) and VI-style + (k,j,l,h) movement keys are also supported. A tip: movement speed is + limited by your keyboard repeat rate, to move faster you may want to + adjust it. (If you're on a mac, the karabiner app is one way to do that.) - With shift pressed, the cursor keys adjust the report period, limiting - the transactions to be shown (by default, all are shown). - SHIFT-DOWN/UP steps downward and upward through these standard report + With shift pressed, the cursor keys adjust the report period, limiting + the transactions to be shown (by default, all are shown). + SHIFT-DOWN/UP steps downward and upward through these standard report period durations: year, quarter, month, week, day. Then, - SHIFT-LEFT/RIGHT moves to the previous/next period. T sets the report - period to today. With the -w/--watch option, when viewing a "current" - period (the current day, week, month, quarter, or year), the period - will move automatically to track the current date. To set a non-stan- + SHIFT-LEFT/RIGHT moves to the previous/next period. T sets the report + period to today. With the -w/--watch option, when viewing a "current" + period (the current day, week, month, quarter, or year), the period + will move automatically to track the current date. To set a non-stan- dard period, you can use / and a date: query. - (Mac users: SHIFT-DOWN/UP keys do not work by default in Terminal, as - of MacOS Monterey. You can configure them as follows: open Terminal, - press CMD-comma to open preferences, click Profiles, select your cur- + (Mac users: SHIFT-DOWN/UP keys do not work by default in Terminal, as + of MacOS Monterey. You can configure them as follows: open Terminal, + press CMD-comma to open preferences, click Profiles, select your cur- rent terminal profile on the left, click Keyboard on the right, click + - and add this for Shift-Down: \033[1;2B, click + and add this for - Shift-Up: \033[1;2A. Press the Escape key to enter the \033 part, you + and add this for Shift-Down: \033[1;2B, click + and add this for + Shift-Up: \033[1;2A. Press the Escape key to enter the \033 part, you can't type it directly.) - / lets you set a general filter query limiting the data shown, using - the same query terms as in hledger and hledger-web. While editing the - query, you can use CTRL-a/e/d/k, BS, cursor keys; press ENTER to set + / lets you set a general filter query limiting the data shown, using + the same query terms as in hledger and hledger-web. While editing the + query, you can use CTRL-a/e/d/k, BS, cursor keys; press ENTER to set it, or ESCAPEto cancel. There are also keys for quickly adjusting some - common filters like account depth and transaction status (see below). + common filters like account depth and transaction status (see below). BACKSPACE or DELETE removes all filters, showing all transactions. - As mentioned above, by default hledger-ui hides future transactions - + As mentioned above, by default hledger-ui hides future transactions - both ordinary transactions recorded in the journal, and periodic trans- - actions generated by rule. F toggles forecast mode, in which fu- + actions generated by rule. F toggles forecast mode, in which fu- ture/forecasted transactions are shown. - ESCAPE resets the UI state and jumps back to the top screen, restoring + ESCAPE resets the UI state and jumps back to the top screen, restoring the app's initial state at startup. Or, it cancels minibuffer data en- try or the help dialog. CTRL-l redraws the screen and centers the selection if possible (selec- - tions near the top won't be centered, since we don't scroll above the + tions near the top won't be centered, since we don't scroll above the top). - g reloads from the data file(s) and updates the current screen and any - previous screens. (With large files, this could cause a noticeable + g reloads from the data file(s) and updates the current screen and any + previous screens. (With large files, this could cause a noticeable pause.) - I toggles balance assertion checking. Disabling balance assertions + I toggles balance assertion checking. Disabling balance assertions temporarily can be useful for troubleshooting. - a runs command-line hledger's add command, and reloads the updated + a runs command-line hledger's add command, and reloads the updated file. This allows some basic data entry. - A is like a, but runs the hledger-iadd tool, which provides a terminal - interface. This key will be available if hledger-iadd is installed in + A is like a, but runs the hledger-iadd tool, which provides a terminal + interface. This key will be available if hledger-iadd is installed in $path. - E runs $HLEDGER_UI_EDITOR, or $EDITOR, or a default (emacsclient -a "" - -nw) on the journal file. With some editors (emacs, vi), the cursor - will be positioned at the current transaction when invoked from the - register and transaction screens, and at the error location (if possi- + E runs $HLEDGER_UI_EDITOR, or $EDITOR, or a default (emacsclient -a "" + -nw) on the journal file. With some editors (emacs, vi), the cursor + will be positioned at the current transaction when invoked from the + register and transaction screens, and at the error location (if possi- ble) when invoked from the error screen. - B toggles cost mode, showing amounts converted to their cost's commod- + B toggles cost mode, showing amounts converted to their cost's commod- ity (see hledger manual > Cost reporting. - V toggles value mode, showing amounts converted to their market value + V toggles value mode, showing amounts converted to their market value (see hledger manual > Valuation flag). More specifically, - 1. By default, the V key toggles showing end value (--value=end) on or - off. The valuation date will be the report end date if specified, + 1. By default, the V key toggles showing end value (--value=end) on or + off. The valuation date will be the report end date if specified, otherwise today. - 2. If you started hledger-ui with some other valuation (such as + 2. If you started hledger-ui with some other valuation (such as --value=then,EUR), the V key toggles that off or on. - Cost/value tips: - When showing end value, you can change the report - end date without restarting, by pressing / and adding a query like - date:..YYYY-MM-DD. - Either cost mode, or value mode, can be active, - but not both at once. Cost mode takes precedence. - There's not yet - any visual indicator that cost or value mode is active, other than the + Cost/value tips: - When showing end value, you can change the report + end date without restarting, by pressing / and adding a query like + date:..YYYY-MM-DD. - Either cost mode, or value mode, can be active, + but not both at once. Cost mode takes precedence. - There's not yet + any visual indicator that cost or value mode is active, other than the amount values. q quits the application. @@ -263,47 +248,47 @@ KEYS Additional screen-specific keys are described below. SCREENS - At startup, hledger-ui shows a menu screen by default. From here you + At startup, hledger-ui shows a menu screen by default. From here you can navigate to other screens using the cursor keys: UP/DOWN to select, - RIGHT to move to the selected screen, LEFT to return to the previous + RIGHT to move to the selected screen, LEFT to return to the previous screen. Or you can use ESC to return directly to the top menu screen. - You can also use a command line flag to specific a different startup + You can also use a command line flag to specific a different startup screen (--cs, --bs, --is, --all, or --register=ACCT). Menu screen - This is the top-most screen. From here you can navigate to several - screens listing accounts of various types. Note some of these may not + This is the top-most screen. From here you can navigate to several + screens listing accounts of various types. Note some of these may not show anything until you have configured account types. Cash accounts screen This screen shows "cash" (ie, liquid asset) accounts (like hledger bal- - ancesheet type:c). It always shows balances (historical ending bal- + ancesheet type:c). It always shows balances (historical ending bal- ances on the date shown in the title line). Balance sheet accounts screen - This screen shows asset, liability and equity accounts (like hledger + This screen shows asset, liability and equity accounts (like hledger balancesheetequity). It always shows balances. Income statement accounts screen - This screen shows revenue and expense accounts (like hledger incomes- - tatement). It always shows changes (balance changes in the period + This screen shows revenue and expense accounts (like hledger incomes- + tatement). It always shows changes (balance changes in the period shown in the title line). All accounts screen - This screen shows all accounts in your journal (unless filtered by a - query; like hledger balance). It shows balances by default; you can + This screen shows all accounts in your journal (unless filtered by a + query; like hledger balance). It shows balances by default; you can toggle showing changes with the H key. Register screen - This screen shows the transactions affecting a particular account. + This screen shows the transactions affecting a particular account. Each line represents one transaction, and shows: - o the other account(s) involved, in abbreviated form. (If there are - both real and virtual postings, it shows only the accounts affected + o the other account(s) involved, in abbreviated form. (If there are + both real and virtual postings, it shows only the accounts affected by real postings.) - o the overall change to the current account's balance; positive for an + o the overall change to the current account's balance; positive for an inflow to this account, negative for an outflow. o the running total after the transaction. With the H key you can tog- @@ -311,91 +296,90 @@ SCREENS o the period total, which is from just the transactions displayed - o or the historical total, which includes any undisplayed transac- - tions before the start of the report period (and matching the fil- - ter query if any). This will be the running historical balance - (what you would see on a bank's website, eg) if not disturbed by a + o or the historical total, which includes any undisplayed transac- + tions before the start of the report period (and matching the fil- + ter query if any). This will be the running historical balance + (what you would see on a bank's website, eg) if not disturbed by a query. - Note, this screen combines each transaction's in-period postings to a - single line item, dated with the earliest in-period transaction or - posting date (like hledger's aregister). So custom posting dates can - cause the running balance to be temporarily inaccurate. (See hledger + Note, this screen combines each transaction's in-period postings to a + single line item, dated with the earliest in-period transaction or + posting date (like hledger's aregister). So custom posting dates can + cause the running balance to be temporarily inaccurate. (See hledger manual > aregister and posting dates.) - Transactions affecting this account's subaccounts will be included in + Transactions affecting this account's subaccounts will be included in the register if the accounts screen is in tree mode, or if it's in list - mode but this account has subaccounts which are not shown due to a - depth limit. In other words, the register always shows the transac- - tions contributing to the balance shown on the accounts screen. Tree + mode but this account has subaccounts which are not shown due to a + depth limit. In other words, the register always shows the transac- + tions contributing to the balance shown on the accounts screen. Tree mode/list mode can be toggled with t here also. - U toggles filtering by unmarked status, showing or hiding unmarked + U toggles filtering by unmarked status, showing or hiding unmarked transactions. Similarly, P toggles pending transactions, and C toggles - cleared transactions. (By default, transactions with all statuses are - shown; if you activate one or two status filters, only those transac- + cleared transactions. (By default, transactions with all statuses are + shown; if you activate one or two status filters, only those transac- tions are shown; and if you activate all three, the filter is removed.) R toggles real mode, in which virtual postings are ignored. - z toggles nonzero mode, in which only transactions posting a nonzero - change are shown (hledger-ui shows zero items by default, unlike com- + z toggles nonzero mode, in which only transactions posting a nonzero + change are shown (hledger-ui shows zero items by default, unlike com- mand-line hledger). Press RIGHT to view the selected transaction in detail. Transaction screen - This screen shows a single transaction, as a general journal entry, - similar to hledger's print command and journal format (hledger_jour- + This screen shows a single transaction, as a general journal entry, + similar to hledger's print command and journal format (hledger_jour- nal(5)). - The transaction's date(s) and any cleared flag, transaction code, de- - scription, comments, along with all of its account postings are shown. - Simple transactions have two postings, but there can be more (or in + The transaction's date(s) and any cleared flag, transaction code, de- + scription, comments, along with all of its account postings are shown. + Simple transactions have two postings, but there can be more (or in certain cases, fewer). - UP and DOWN will step through all transactions listed in the previous - account register screen. In the title bar, the numbers in parentheses - show your position within that account register. They will vary de- + UP and DOWN will step through all transactions listed in the previous + account register screen. In the title bar, the numbers in parentheses + show your position within that account register. They will vary de- pending on which account register you came from (remember most transac- - tions appear in multiple account registers). The #N number preceding + tions appear in multiple account registers). The #N number preceding them is the transaction's position within the complete unfiltered jour- nal, which is a more stable id (at least until the next reload). On this screen (and the register screen), the E key will open your text - editor with the cursor positioned at the current transaction if possi- + editor with the cursor positioned at the current transaction if possi- ble. - This screen has a limitation with showing file updates: it will not - show them until you exit and re-enter it. So eg to see the effect of + This screen has a limitation with showing file updates: it will not + show them until you exit and re-enter it. So eg to see the effect of using the E key, currently you must: - press E, edit and save the file, - then exit the editor, returning to hledger-ui - press g to reload the - file (or use -w/--watch mode) - press LEFT then RIGHT to exit and + then exit the editor, returning to hledger-ui - press g to reload the + file (or use -w/--watch mode) - press LEFT then RIGHT to exit and re-enter the transaction screen. Error screen - This screen will appear if there is a problem, such as a parse error, - when you press g to reload. Once you have fixed the problem, press g + This screen will appear if there is a problem, such as a parse error, + when you press g to reload. Once you have fixed the problem, press g again to reload and resume normal operation. (Or, you can press escape to cancel the reload attempt.) -TIPS - Watch mode - One of hledger-ui's best features is the auto-reloading -w/--watch - mode. With this flag, it will update the display automatically when- +WATCH MODE + One of hledger-ui's best features is the auto-reloading -w/--watch + mode. With this flag, it will update the display automatically when- ever changes are saved to the data files. - This is very useful when reconciling. A good workflow is to have your - bank's online register open in a browser window, for reference; the - journal file open in an editor window; and hledger-ui in watch mode in + This is very useful when reconciling. A good workflow is to have your + bank's online register open in a browser window, for reference; the + journal file open in an editor window; and hledger-ui in watch mode in a terminal window, eg: $ hledger-ui --watch --register checking -C - As you mark things cleared in the editor, you can see the effect imme- - diately without having to context switch. This leaves more mental - bandwidth for your accounting. Of course you can still interact with - hledger-ui when needed, eg to toggle cleared mode, or to explore the + As you mark things cleared in the editor, you can see the effect imme- + diately without having to context switch. This leaves more mental + bandwidth for your accounting. Of course you can still interact with + hledger-ui when needed, eg to toggle cleared mode, or to explore the history. There are currently some limitations with --watch: @@ -403,32 +387,27 @@ TIPS It may not work correctly for you, depending on platform or system con- figuration. (Eg #836.) - At least on mac, there can be a slow build-up of CPU usage over time, - until the program is restarted (or, suspending and restarting with + At least on mac, there can be a slow build-up of CPU usage over time, + until the program is restarted (or, suspending and restarting with CTRL-z fg may be enough). - It will not detect file changes made by certain editors, such as Jet- - brains IDEs or gedit, or on certain less common filesystems. (To work - around, press g to reload manually, or try #1617's fs.ino- + It will not detect file changes made by certain editors, such as Jet- + brains IDEs or gedit, or on certain less common filesystems. (To work + around, press g to reload manually, or try #1617's fs.ino- tify.max_user_watches workaround and let us know.) - If you are viewing files mounted from another machine, the system + If you are viewing files mounted from another machine, the system clocks on both machines should be roughly in agreement. - Debug output - You can add --debug[=N] to the command line to log debug output. This - will be logged to the file hledger-ui.log in the current directory. N - ranges from 1 (least output, the default) to 9 (maximum output). - ENVIRONMENT COLUMNS The screen width to use. Default: the full terminal width. - LEDGER_FILE The main journal file to use when not specified with + LEDGER_FILE The main journal file to use when not specified with -f/--file. Default: $HOME/.hledger.journal. BUGS We welcome bug reports in the hledger issue tracker (shortcut: - http://bugs.hledger.org), or on the #hledger chat or hledger mail list + http://bugs.hledger.org), or on the #hledger chat or hledger mail list (https://hledger.org/support). Some known issues: @@ -440,7 +419,7 @@ BUGS The Transaction screen does not update from file changes until you exit and re-endter it (see SCREENS > Transaction above). - --watch is not yet fully robust on all platforms (see Watch mode + --watch is not yet fully robust on all platforms (see Watch mode above). @@ -461,4 +440,4 @@ LICENSE SEE ALSO hledger(1), hledger-ui(1), hledger-web(1), ledger(1) -hledger-ui-1.33.99 May 2024 HLEDGER-UI(1) +hledger-ui-1.34.99 June 2024 HLEDGER-UI(1) diff --git a/hledger-web/.date.m4 b/hledger-web/.date.m4 index 4e27a7647..705091ff8 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_}}, {{May 2024}})m4_dnl +m4_define({{_monthyear_}}, {{June 2024}})m4_dnl diff --git a/hledger-web/hledger-web.1 b/hledger-web/hledger-web.1 index 28ad73946..18c66c0f9 100644 --- a/hledger-web/hledger-web.1 +++ b/hledger-web/hledger-web.1 @@ -1,5 +1,5 @@ -.TH "HLEDGER\-WEB" "1" "May 2024" "hledger-web-1.33.99 " "hledger User Manuals" +.TH "HLEDGER\-WEB" "1" "June 2024" "hledger-web-1.34.99 " "hledger User Manuals" @@ -7,13 +7,17 @@ hledger\-web \- web interface and API for \f[CR]hledger\f[R], a robust, friendly plain text accounting app. .SH SYNOPSIS -\f[CR]hledger\-web [\-\-serve|\-\-serve\-api] [OPTS] [ARGS]\f[R] +\f[CR]hledger\-web [OPTS] [QUERY]\f[R] .PD 0 .P .PD -\f[CR]hledger web \-\- [\-\-serve|\-\-serve\-api] [OPTS] [ARGS]\f[R] +or +.PD 0 +.P +.PD +\f[CR]hledger web \-\- [OPTS] [QUERY]\f[R] .SH DESCRIPTION -This manual is for hledger\[aq]s web interface, version 1.33.99. +This manual is for hledger\[aq]s web interface, version 1.34.99. See also the hledger manual for common concepts and file formats. .PP hledger is a robust, user\-friendly, cross\-platform set of programs for @@ -61,45 +65,41 @@ In all cases hledger\-web runs as a foreground process, logging requests to stdout. .SH OPTIONS hledger\-web provides the following options: -.TP -\f[CR]\-\-serve\f[R] -serve and log requests, don\[aq]t browse or auto\-exit after timeout -.TP -\f[CR]\-\-serve\-api\f[R] -like \-\-serve, but serve only the JSON web API, not the web UI -.TP -\f[CR]\-\-allow=view|add|edit\f[R] -set the user\[aq]s access level for changing data (default: -\f[CR]add\f[R]). -It also accepts \f[CR]sandstorm\f[R] for use on that platform (reads -permissions from the \f[CR]X\-Sandstorm\-Permissions\f[R] request -header). -.TP -\f[CR]\-\-cors=ORIGIN\f[R] -allow cross\-origin requests from the specified origin; setting ORIGIN -to \[dq]*\[dq] allows requests from any origin -.TP -\f[CR]\-\-host=IPADDR\f[R] -listen on this IP address (default: 127.0.0.1) +.IP +.EX +Flags: + \-\-serve \-\-server serve and log requests, don\[aq]t browse or auto\-exit + \-\-serve\-api like \-\-serve, but serve only the JSON web API, + not the web UI + \-\-allow=view|add|edit set the user\[aq]s access level for changing data + (default: \[ga]add\[ga]). It also accepts \[ga]sandstorm\[ga] for + use on that platform (reads permissions from the + \[ga]X\-Sandstorm\-Permissions\[ga] request header). + \-\-cors=ORIGIN allow cross\-origin requests from the specified + origin; setting ORIGIN to \[dq]*\[dq] allows requests from + any origin + \-\-host=IPADDR listen on this IP address (default: 127.0.0.1) + \-\-port=PORT listen on this TCP port (default: 5000) + \-\-socket=SOCKET listen on the given unix socket instead of an IP + address and port (unix only; implies \-\-serve) + \-\-base\-url=BASEURL set the base url (default: http://IPADDR:PORT) + \-\-test run hledger\-web\[aq]s tests and exit. hspec test + runner args may follow a \-\-, eg: hledger\-web \-\-test + \-\- \-\-help +.EE .PP -By default the server listens on IP address \f[CR]127.0.0.1\f[R], which -is accessible only to requests from the local machine.. -You can use \f[CR]\-\-host\f[R] to listen on a different address -configured on the machine, eg to allow access from other machines. -The special address \f[CR]0.0.0.0\f[R] causes it to listen on all -addresses configured on the machine. -.TP -\f[CR]\-\-port=PORT\f[R] -listen on this TCP port (default: 5000) +By default hledger\-web listens only on IP address \f[CR]127.0.0.1\f[R], +which be accessed only from the local machine. +.PP +To allow access from elsewhere, use \f[CR]\-\-host\f[R] to specify an +externally accessible address configured on this machine, The special +address \f[CR]0.0.0.0\f[R] causes it to listen on all of this +machine\[aq]s addresses. .PP Similarly, you can use \f[CR]\-\-port\f[R] to listen on a TCP port other than 5000. This is useful if you want to run multiple hledger\-web instances on a machine. -.TP -\f[CR]\-\-socket=SOCKETFILE\f[R] -listen on the given unix socket instead of an IP address and port (unix -only; implies \-\-serve) .PP When \f[CR]\-\-socket\f[R] is used, hledger\-web creates and communicates via a socket file instead of a TCP port. @@ -108,9 +108,6 @@ certain use cases easier, such as running per\-user instances behind an nginx reverse proxy. (Eg: \f[CR]proxy_pass http://unix:/tmp/hledger/${remote_user}.socket;\f[R].) -.TP -\f[CR]\-\-base\-url=URL\f[R] -set the base url (default: http://IPADDR:PORT). .PP You can use \f[CR]\-\-base\-url\f[R] to change the protocol, hostname, port and path that appear in hledger\-web\[aq]s hyperlinks. @@ -119,26 +116,8 @@ The default is \f[CR]http://HOST:PORT/\f[R] using the server\[aq]s configured host address and TCP port (or \f[CR]http://HOST\f[R] if PORT is 80). Note this affects url generation but not route parsing. -.TP -\f[CR]\-\-test\f[R] -run hledger\-web\[aq]s tests and exit. -hspec test runner args may follow a \-\-, eg: hledger\-web \-\-test \-\- -\-\-help .PP -hledger\-web also supports many of hledger\[aq]s general options. -Query options and arguments may be used to set an initial filter, which -although not shown in the UI, will restrict the data shown, in addition -to any search query entered in the UI. -.PP -Note that hledger\-web shows accounts with zero balances by default, -like \f[CR]hledger\-ui\f[R] (and unlike \f[CR]hledger\f[R]). -Using the \f[CR]\-E/\-\-empty\f[R] flag at startup will hide them. -.PP -If you see accounts which appear to have a zero balance, but cannot be -hidden with \f[CR]\-E\f[R]: these have a mixed\-cost balance which looks -like zero when costs are hidden. -Currently hledger\-web does not show costs at all. -.SS General options +hledger\-web also supports many of hledger\[aq]s general options: .IP .EX General input/data transformation flags: @@ -207,7 +186,6 @@ General output/reporting flags (supported by some commands): Eg: \-c \[aq].\[aq] or \-c \[aq]1.000,00 EUR\[aq] \-\-color=YN \-\-colour Use ANSI color codes in text output? Can be \[aq]y\[aq]/\[aq]yes\[aq]/\[aq]always\[aq], \[aq]n\[aq]/\[aq]no\[aq]/\[aq]never\[aq] or \[aq]auto\[aq]. - (A NO_COLOR environment variable overrides this.) \-\-pretty[=YN] Use box\-drawing characters in text output? Can be \[aq]y\[aq]/\[aq]yes\[aq] or \[aq]n\[aq]/\[aq]no\[aq]. If YN is specified, the equals is required. @@ -216,10 +194,22 @@ General output/reporting flags (supported by some commands): General help flags: \-h \-\-help show command line help \-\-tldr show command examples with tldr - \-\-info show the hledger manual with info - \-\-man show the hledger manual with man + \-\-info show the manual with info + \-\-man show the manual with man \-\-version show version information .EE +.PP +hledger\-web shows accounts with zero balances by default (like +\f[CR]hledger\-ui\f[R], and unlike \f[CR]hledger\f[R]). +Using the \f[CR]\-E/\-\-empty\f[R] flag will reverse this behaviour. +If you see accounts which appear to have a zero balance, but cannot be +hidden with \f[CR]\-E\f[R], it\[aq]s because they have a mixed\-cost +balance, which looks like zero when costs are hidden. +(hledger\-web does not show costs.) +.PP +Reporting options and/or query arguments can be used to set an initial +query, which although not shown in the UI, will restrict the data shown +(in addition to any search query entered in the UI). .SH PERMISSIONS By default, hledger\-web allows anyone who can reach it to view the journal and to add new transactions, but not to change existing data. @@ -360,6 +350,7 @@ Most of the JSON corresponds to hledger\[aq]s data types; for details of what the fields mean, see the Hledger.Data.Json haddock docs and click on the various data types, eg Transaction. And for a higher level understanding, see the journal docs. +There is also a basic OpenAPI specification. .PP In some cases there is outer JSON corresponding to a \[dq]Report\[dq] type. diff --git a/hledger-web/hledger-web.info b/hledger-web/hledger-web.info index 9ecd10a65..964795fc9 100644 --- a/hledger-web/hledger-web.info +++ b/hledger-web/hledger-web.info @@ -14,10 +14,11 @@ hledger-web(1) hledger-web - web interface and API for 'hledger', a robust, friendly plain text accounting app. - 'hledger-web [--serve|--serve-api] [OPTS] [ARGS]' -'hledger web -- [--serve|--serve-api] [OPTS] [ARGS]' + 'hledger-web [OPTS] [QUERY]' +or +'hledger web -- [OPTS] [QUERY]' - This manual is for hledger's web interface, version 1.33.99. See + This manual is for hledger's web interface, version 1.34.99. See also the hledger manual for common concepts and file formats. hledger is a robust, user-friendly, cross-platform set of programs @@ -78,54 +79,43 @@ File: hledger-web.info, Node: OPTIONS, Next: PERMISSIONS, Prev: Top, Up: Top hledger-web provides the following options: -'--serve' +Flags: + --serve --server serve and log requests, don't browse or auto-exit + --serve-api like --serve, but serve only the JSON web API, + not the web UI + --allow=view|add|edit set the user's access level for changing data + (default: `add`). It also accepts `sandstorm` for + use on that platform (reads permissions from the + `X-Sandstorm-Permissions` request header). + --cors=ORIGIN allow cross-origin requests from the specified + origin; setting ORIGIN to "*" allows requests from + any origin + --host=IPADDR listen on this IP address (default: 127.0.0.1) + --port=PORT listen on this TCP port (default: 5000) + --socket=SOCKET listen on the given unix socket instead of an IP + address and port (unix only; implies --serve) + --base-url=BASEURL set the base url (default: http://IPADDR:PORT) + --test run hledger-web's tests and exit. hspec test + runner args may follow a --, eg: hledger-web --test + -- --help - serve and log requests, don't browse or auto-exit after timeout -'--serve-api' + By default hledger-web listens only on IP address '127.0.0.1', which +be accessed only from the local machine. - like -serve, but serve only the JSON web API, not the web UI -'--allow=view|add|edit' - - set the user's access level for changing data (default: 'add'). It - also accepts 'sandstorm' for use on that platform (reads - permissions from the 'X-Sandstorm-Permissions' request header). -'--cors=ORIGIN' - - allow cross-origin requests from the specified origin; setting - ORIGIN to "*" allows requests from any origin -'--host=IPADDR' - - listen on this IP address (default: 127.0.0.1) - - By default the server listens on IP address '127.0.0.1', which is -accessible only to requests from the local machine.. You can use -'--host' to listen on a different address configured on the machine, eg -to allow access from other machines. The special address '0.0.0.0' -causes it to listen on all addresses configured on the machine. - -'--port=PORT' - - listen on this TCP port (default: 5000) + To allow access from elsewhere, use '--host' to specify an externally +accessible address configured on this machine, The special address +'0.0.0.0' causes it to listen on all of this machine's addresses. Similarly, you can use '--port' to listen on a TCP port other than 5000. This is useful if you want to run multiple hledger-web instances on a machine. -'--socket=SOCKETFILE' - - listen on the given unix socket instead of an IP address and port - (unix only; implies -serve) - When '--socket' is used, hledger-web creates and communicates via a socket file instead of a TCP port. This can be more secure, respects unix file permissions, and makes certain use cases easier, such as running per-user instances behind an nginx reverse proxy. (Eg: 'proxy_pass http://unix:/tmp/hledger/${remote_user}.socket;'.) -'--base-url=URL' - - set the base url (default: http://IPADDR:PORT). - You can use '--base-url' to change the protocol, hostname, port and path that appear in hledger-web's hyperlinks. This is useful eg when integrating hledger-web within a larger website. The default is @@ -133,34 +123,7 @@ integrating hledger-web within a larger website. The default is port (or 'http://HOST' if PORT is 80). Note this affects url generation but not route parsing. -'--test' - - run hledger-web's tests and exit. hspec test runner args may - follow a -, eg: hledger-web -test - -help - - hledger-web also supports many of hledger's general options. Query -options and arguments may be used to set an initial filter, which -although not shown in the UI, will restrict the data shown, in addition -to any search query entered in the UI. - - Note that hledger-web shows accounts with zero balances by default, -like 'hledger-ui' (and unlike 'hledger'). Using the '-E/--empty' flag -at startup will hide them. - - If you see accounts which appear to have a zero balance, but cannot -be hidden with '-E': these have a mixed-cost balance which looks like -zero when costs are hidden. Currently hledger-web does not show costs -at all. - -* Menu: - -* General options:: - - -File: hledger-web.info, Node: General options, Up: OPTIONS - -1.1 General options -=================== + hledger-web also supports many of hledger's general options: General input/data transformation flags: -f --file=FILE Read data from FILE, or from stdin if -. Can be @@ -228,7 +191,6 @@ General output/reporting flags (supported by some commands): Eg: -c '.' or -c '1.000,00 EUR' --color=YN --colour Use ANSI color codes in text output? Can be 'y'/'yes'/'always', 'n'/'no'/'never' or 'auto'. - (A NO_COLOR environment variable overrides this.) --pretty[=YN] Use box-drawing characters in text output? Can be 'y'/'yes' or 'n'/'no'. If YN is specified, the equals is required. @@ -237,10 +199,21 @@ General output/reporting flags (supported by some commands): General help flags: -h --help show command line help --tldr show command examples with tldr - --info show the hledger manual with info - --man show the hledger manual with man + --info show the manual with info + --man show the manual with man --version show version information + hledger-web shows accounts with zero balances by default (like +'hledger-ui', and unlike 'hledger'). Using the '-E/--empty' flag will +reverse this behaviour. If you see accounts which appear to have a zero +balance, but cannot be hidden with '-E', it's because they have a +mixed-cost balance, which looks like zero when costs are hidden. +(hledger-web does not show costs.) + + Reporting options and/or query arguments can be used to set an +initial query, which although not shown in the UI, will restrict the +data shown (in addition to any search query entered in the UI). +  File: hledger-web.info, Node: PERMISSIONS, Next: EDITING UPLOADING DOWNLOADING, Prev: OPTIONS, Up: Top @@ -382,7 +355,8 @@ $ curl -s http://127.0.0.1:5000/transactions | python -m json.tool Most of the JSON corresponds to hledger's data types; for details of what the fields mean, see the Hledger.Data.Json haddock docs and click on the various data types, eg Transaction. And for a higher level -understanding, see the journal docs. +understanding, see the journal docs. There is also a basic OpenAPI +specification. In some cases there is outer JSON corresponding to a "Report" type. To understand that, go to the Hledger.Web.Handler.MiscR haddock and look @@ -548,26 +522,24 @@ http://bugs.hledger.org), or on the #hledger chat or hledger mail list  Tag Table: Node: Top223 -Node: OPTIONS2608 -Ref: #options2713 -Node: General options5617 -Ref: #general-options5722 -Node: PERMISSIONS10872 -Ref: #permissions11011 -Node: EDITING UPLOADING DOWNLOADING12223 -Ref: #editing-uploading-downloading12404 -Node: RELOADING13238 -Ref: #reloading13372 -Node: JSON API13805 -Ref: #json-api13920 -Node: DEBUG OUTPUT19408 -Ref: #debug-output19533 -Node: Debug output19560 -Ref: #debug-output-119661 -Node: ENVIRONMENT20078 -Ref: #environment20197 -Node: BUGS20314 -Ref: #bugs20398 +Node: OPTIONS2569 +Ref: #options2674 +Node: PERMISSIONS10862 +Ref: #permissions11001 +Node: EDITING UPLOADING DOWNLOADING12213 +Ref: #editing-uploading-downloading12394 +Node: RELOADING13228 +Ref: #reloading13362 +Node: JSON API13795 +Ref: #json-api13910 +Node: DEBUG OUTPUT19444 +Ref: #debug-output19569 +Node: Debug output19596 +Ref: #debug-output-119697 +Node: ENVIRONMENT20114 +Ref: #environment20233 +Node: BUGS20350 +Ref: #bugs20434  End Tag Table diff --git a/hledger-web/hledger-web.txt b/hledger-web/hledger-web.txt index 2807a42be..ad726f484 100644 --- a/hledger-web/hledger-web.txt +++ b/hledger-web/hledger-web.txt @@ -6,11 +6,12 @@ NAME plain text accounting app. SYNOPSIS - hledger-web [--serve|--serve-api] [OPTS] [ARGS] - hledger web -- [--serve|--serve-api] [OPTS] [ARGS] + hledger-web [OPTS] [QUERY] + or + hledger web -- [OPTS] [QUERY] DESCRIPTION - This manual is for hledger's web interface, version 1.33.99. See also + This manual is for hledger's web interface, version 1.34.99. See also the hledger manual for common concepts and file formats. hledger is a robust, user-friendly, cross-platform set of programs for @@ -55,50 +56,43 @@ DESCRIPTION OPTIONS hledger-web provides the following options: - --serve - serve and log requests, don't browse or auto-exit after timeout + Flags: + --serve --server serve and log requests, don't browse or auto-exit + --serve-api like --serve, but serve only the JSON web API, + not the web UI + --allow=view|add|edit set the user's access level for changing data + (default: `add`). It also accepts `sandstorm` for + use on that platform (reads permissions from the + `X-Sandstorm-Permissions` request header). + --cors=ORIGIN allow cross-origin requests from the specified + origin; setting ORIGIN to "*" allows requests from + any origin + --host=IPADDR listen on this IP address (default: 127.0.0.1) + --port=PORT listen on this TCP port (default: 5000) + --socket=SOCKET listen on the given unix socket instead of an IP + address and port (unix only; implies --serve) + --base-url=BASEURL set the base url (default: http://IPADDR:PORT) + --test run hledger-web's tests and exit. hspec test + runner args may follow a --, eg: hledger-web --test + -- --help - --serve-api - like --serve, but serve only the JSON web API, not the web UI + By default hledger-web listens only on IP address 127.0.0.1, which be + accessed only from the local machine. - --allow=view|add|edit - set the user's access level for changing data (default: add). - It also accepts sandstorm for use on that platform (reads per- - missions from the X-Sandstorm-Permissions request header). + To allow access from elsewhere, use --host to specify an externally ac- + cessible address configured on this machine, The special address + 0.0.0.0 causes it to listen on all of this machine's addresses. - --cors=ORIGIN - allow cross-origin requests from the specified origin; setting - ORIGIN to "*" allows requests from any origin - - --host=IPADDR - listen on this IP address (default: 127.0.0.1) - - By default the server listens on IP address 127.0.0.1, which is acces- - sible only to requests from the local machine.. You can use --host to - listen on a different address configured on the machine, eg to allow - access from other machines. The special address 0.0.0.0 causes it to - listen on all addresses configured on the machine. - - --port=PORT - listen on this TCP port (default: 5000) - - Similarly, you can use --port to listen on a TCP port other than 5000. - This is useful if you want to run multiple hledger-web instances on a + Similarly, you can use --port to listen on a TCP port other than 5000. + This is useful if you want to run multiple hledger-web instances on a machine. - --socket=SOCKETFILE - listen on the given unix socket instead of an IP address and - port (unix only; implies --serve) - When --socket is used, hledger-web creates and communicates via a socket file instead of a TCP port. This can be more secure, respects unix file permissions, and makes certain use cases easier, such as run- ning per-user instances behind an nginx reverse proxy. (Eg: proxy_pass http://unix:/tmp/hledger/${remote_user}.socket;.) - --base-url=URL - set the base url (default: http://IPADDR:PORT). - You can use --base-url to change the protocol, hostname, port and path that appear in hledger-web's hyperlinks. This is useful eg when inte- grating hledger-web within a larger website. The default is @@ -106,24 +100,8 @@ OPTIONS port (or http://HOST if PORT is 80). Note this affects url generation but not route parsing. - --test run hledger-web's tests and exit. hspec test runner args may - follow a --, eg: hledger-web --test -- --help + hledger-web also supports many of hledger's general options: - hledger-web also supports many of hledger's general options. Query op- - tions and arguments may be used to set an initial filter, which al- - though not shown in the UI, will restrict the data shown, in addition - to any search query entered in the UI. - - Note that hledger-web shows accounts with zero balances by default, - like hledger-ui (and unlike hledger). Using the -E/--empty flag at - startup will hide them. - - If you see accounts which appear to have a zero balance, but cannot be - hidden with -E: these have a mixed-cost balance which looks like zero - when costs are hidden. Currently hledger-web does not show costs at - all. - - General options General input/data transformation flags: -f --file=FILE Read data from FILE, or from stdin if -. Can be specified more than once. If not specified, reads @@ -190,7 +168,6 @@ OPTIONS Eg: -c '.' or -c '1.000,00 EUR' --color=YN --colour Use ANSI color codes in text output? Can be 'y'/'yes'/'always', 'n'/'no'/'never' or 'auto'. - (A NO_COLOR environment variable overrides this.) --pretty[=YN] Use box-drawing characters in text output? Can be 'y'/'yes' or 'n'/'no'. If YN is specified, the equals is required. @@ -199,10 +176,21 @@ OPTIONS General help flags: -h --help show command line help --tldr show command examples with tldr - --info show the hledger manual with info - --man show the hledger manual with man + --info show the manual with info + --man show the manual with man --version show version information + hledger-web shows accounts with zero balances by default (like + hledger-ui, and unlike hledger). Using the -E/--empty flag will re- + verse this behaviour. If you see accounts which appear to have a zero + balance, but cannot be hidden with -E, it's because they have a + mixed-cost balance, which looks like zero when costs are hidden. + (hledger-web does not show costs.) + + Reporting options and/or query arguments can be used to set an initial + query, which although not shown in the UI, will restrict the data shown + (in addition to any search query entered in the UI). + PERMISSIONS By default, hledger-web allows anyone who can reach it to view the journal and to add new transactions, but not to change existing data. @@ -327,7 +315,8 @@ JSON API Most of the JSON corresponds to hledger's data types; for details of what the fields mean, see the Hledger.Data.Json haddock docs and click on the various data types, eg Transaction. And for a higher level un- - derstanding, see the journal docs. + derstanding, see the journal docs. There is also a basic OpenAPI spec- + ification. In some cases there is outer JSON corresponding to a "Report" type. To understand that, go to the Hledger.Web.Handler.MiscR haddock and look @@ -484,4 +473,4 @@ LICENSE SEE ALSO hledger(1), hledger-ui(1), hledger-web(1), ledger(1) -hledger-web-1.33.99 May 2024 HLEDGER-WEB(1) +hledger-web-1.34.99 June 2024 HLEDGER-WEB(1) diff --git a/hledger/.date.m4 b/hledger/.date.m4 index 4e27a7647..705091ff8 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_}}, {{May 2024}})m4_dnl +m4_define({{_monthyear_}}, {{June 2024}})m4_dnl diff --git a/hledger/hledger.1 b/hledger/hledger.1 index e6c264c88..1958ca1e2 100644 --- a/hledger/hledger.1 +++ b/hledger/hledger.1 @@ -1,6 +1,6 @@ .\"t -.TH "HLEDGER" "1" "May 2024" "hledger-1.33.99 " "hledger User Manuals" +.TH "HLEDGER" "1" "June 2024" "hledger-1.34.99 " "hledger User Manuals" @@ -12,11 +12,19 @@ version). .PD 0 .P .PD -\f[CR]hledger COMMAND [OPTS] [ARGS]\f[R] +or .PD 0 .P .PD -\f[CR]hledger ADDONCMD \-\- [OPTS] [ARGS]\f[R] +\f[CR]hledger COMMAND [OPTS] [ARGS]\f[R] +.PD 0 +.P +.PD +or +.PD 0 +.P +.PD +\f[CR]hledger ADDONCMD [OPTS] \-\- [ADDONOPTS] [ADDONARGS]\f[R] .SH DESCRIPTION hledger is a robust, user\-friendly, cross\-platform set of programs for tracking money, time, or any other commodity, using double\-entry @@ -25,7 +33,7 @@ hledger is inspired by and largely compatible with ledger(1), and largely interconvertible with beancount(1). .PP This manual is for hledger\[aq]s command line interface, version -1.33.99. +1.34.99. It also describes the common options, file formats and concepts used by all hledger programs. It might accidentally teach you some bookkeeping/accounting as well! @@ -227,8 +235,8 @@ The file name \f[CR]\-\f[R] means standard input: $ cat FILE | hledger \-f\- print .EE .PP -If reading non\-journal data in this way, you\[aq]ll need to add a file -format prefix, like: +If reading non\-journal data in this way, you\[aq]ll need to write the +format as a prefix, like \f[CR]timeclock:\f[R] here: .IP .EX $ echo \[aq]i 2009/13/1 08:00:00\[aq] | hledger print \-f timeclock:\- @@ -329,9 +337,9 @@ If this causes difficulty, you can always run the add\-on directly, without using \f[CR]hledger\f[R]: \f[CR]hledger\-ui \-\-watch\f[R] or \f[CR]hledger\-web \-\-serve\f[R]. .SH Options -Run \f[CR]hledger \-h\f[R] to see general command line help, and general -options which are common to most hledger commands. -These options can be written anywhere on the command line: +Run \f[CR]hledger \-h\f[R] to see general command line help. +The following general options are common to most hledger commands. +General options can be written either before or after the command name. .IP .EX General input/data transformation flags: @@ -400,7 +408,6 @@ General output/reporting flags (supported by some commands): Eg: \-c \[aq].\[aq] or \-c \[aq]1.000,00 EUR\[aq] \-\-color=YN \-\-colour Use ANSI color codes in text output? Can be \[aq]y\[aq]/\[aq]yes\[aq]/\[aq]always\[aq], \[aq]n\[aq]/\[aq]no\[aq]/\[aq]never\[aq] or \[aq]auto\[aq]. - (A NO_COLOR environment variable overrides this.) \-\-pretty[=YN] Use box\-drawing characters in text output? Can be \[aq]y\[aq]/\[aq]yes\[aq] or \[aq]n\[aq]/\[aq]no\[aq]. If YN is specified, the equals is required. @@ -409,19 +416,24 @@ General output/reporting flags (supported by some commands): General help flags: \-h \-\-help show command line help \-\-tldr show command examples with tldr - \-\-info show the hledger manual with info - \-\-man show the hledger manual with man + \-\-info show the manual with info + \-\-man show the manual with man \-\-version show version information .EE .PP -Some reporting options can also be written as query arguments. -.SH Command line tips -Here are some details useful to know about for hledger command lines -(and elsewhere). -Feel free to skip this section until you need it. -.SS Option repetition -If options are repeated in a command line, hledger will generally use -the last (right\-most) occurence. +Usually hledger accepts any unambiguous flag prefix, eg you can write +\f[CR]\-\-tl\f[R] instead of \f[CR]\-\-tldr\f[R] or \f[CR]\-\-dry\f[R] +instead of \f[CR]\-\-dry\-run\f[R]. +.PP +If the same option appears more than once in a command, usually the last +(right\-most) wins. +.PP +With most commands, arguments are interpreted as a hledger query which +filter the data. +Some queries can be expressed either with options or with arguments. +.PP +Below are more tips for using the command line interface \- feel free to +skip these until you need them. .SS Special characters .SS Single escaping (shell metacharacters) In shell command lines, characters significant to your shell \- such as @@ -886,6 +898,7 @@ representation of hledger\[aq]s internal data types. To understand the JSON, read the Haskell type definitions, which are mostly in https://github.com/simonmichael/hledger/blob/master/hledger\-lib/Hledger/Data/Types.hs. +hledger\-web\[aq]s OpenAPI specification may also be relevant. .IP \[bu] 2 hledger represents quantities as Decimal values storing up to 255 significant digits, eg for repeating decimals. @@ -1018,9 +1031,10 @@ If not set, they will try to use the available terminal width. with \f[CR]\-f/\-\-file\f[R]. Default: \f[CR]$HOME/.hledger.journal\f[R]. .PP -\f[B]NO_COLOR\f[R] If this environment variable is set (with any value), -hledger will not use ANSI color codes in terminal output, unless -overridden by an explicit \f[CR]\-\-color/\-\-colour\f[R] option. +\f[B]NO_COLOR\f[R] If this environment variable exists (with any value, +including empty), hledger will not use ANSI color codes in terminal +output, unless overridden by an explicit +\f[CR]\-\-color=y\f[R]/\f[CR]\-\-colour=y\f[R] option. .SH PART 2: DATA FORMATS .SH Journal hledger\[aq]s usual data source is a plain text file containing journal @@ -3411,24 +3425,39 @@ when evaluating a region of the journal in your editor. A missing Y directive makes reports dependent on today\[aq]s date. .SS Secondary dates A secondary date is written after the primary date, following an equals -sign. +sign: \f[CR]DATE1=DATE2\f[R]. If the year is omitted, the primary date\[aq]s year is assumed. -When running reports, the primary (left) date is used by default, but -with the \f[CR]\-\-date2\f[R] flag (or \f[CR]\-\-aux\-date\f[R] or -\f[CR]\-\-effective\f[R]), the secondary (right) date will be used -instead. +When running reports, the primary (left side) date is used by default, +but with the \f[CR]\-\-date2\f[R] flag (\f[CR]\-\-aux\-date\f[R] +or\f[CR]\-\-effective\f[R] also work, for Ledger users), the secondary +(right side) date will be used instead. .PP -The meaning of secondary dates is up to you, but it\[aq]s best to follow -a consistent rule. -Eg \[dq]primary = the bank\[aq]s clearing date, secondary = date the -transaction was initiated, if different\[dq]. +The meaning of secondary dates is up to you. +Eg it could be \[dq]primary is the bank\[aq]s clearing date, secondary +is the date the transaction was initiated, if different\[dq]. .PP -Downsides: makes your financial data more complicated, less portable, -and less trustworthy in an audit. -Keeping the meaning of the two dates consistent requires discipline, and -you have to remember which reporting mode is appropriate for a given -report. -Posting dates are simpler and better. +In practice, this feature usually adds confusion: +.IP \[bu] 2 +You have to remember the primary and secondary dates\[aq] meaning, and +follow that consistently. +.IP \[bu] 2 +It splits your bookkeeping into two modes, and you have to remember +which mode is appropriate for a given report. +.IP \[bu] 2 +Usually your balance assertions will work with only one of these modes. +.IP \[bu] 2 +It makes your financial data more complicated, less portable, and less +clear in an audit. +.IP \[bu] 2 +It interacts with every feature, creating an ongoing cost for +implementors. +.IP \[bu] 2 +It distracts new users and supporters. +.IP \[bu] 2 +Posting dates are simpler and work better. +.PP +So secondary dates are officially deprecated in hledger, remaining only +as a Ledger compatibility aid; we recommend using posting dates instead. .SS Star comments Lines beginning with \f[CR]*\f[R] (star/asterisk) are also comment lines. @@ -6335,42 +6364,52 @@ $ hledger balance Income:Dues \-\-pivot kind:member \-2 EUR .EE .SH Generating data -hledger has several features for generating data, such as: +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: .IP \[bu] 2 -Periodic transaction rules can generate single or repeating transactions -following a template. -These are usually dated in the future, eg to help with forecasting. -They are activated by the \f[CR]\-\-forecast\f[R] option. -.IP \[bu] 2 -The balance command\[aq]s \f[CR]\-\-budget\f[R] option uses these same -periodic rules to generate goals for the budget report. -.IP \[bu] 2 -Auto posting rules can generate extra postings on certain matched -transactions. -They are always applied to forecast transactions; with the -\f[CR]\-\-auto\f[R] flag they are applied to transactions recorded in -the journal as well. +Missing amounts or missing costs in transactions are inferred +automatically when possible. .IP \[bu] 2 The \f[CR]\-\-infer\-equity\f[R] flag infers missing conversion equity postings from \[at]/\[at]\[at] costs. -And the inverse \f[CR]\-\-infer\-costs\f[R] flag infers missing -\[at]/\[at]\[at] costs from conversion equity postings. +.IP \[bu] 2 +The \f[CR]\-\-infer\-costs\f[R] flag infers missing costs from +conversion equity postings. +.IP \[bu] 2 +The \f[CR]\-\-infer\-market\-prices\f[R] flag infers \f[CR]P\f[R] price +directives from costs. +.IP \[bu] 2 +The \f[CR]\-\-auto\f[R] flag adds extra postings to transactions matched +by auto posting rules. +.IP \[bu] 2 +The \f[CR]\-\-forecast\f[R] option generates transactions from periodic +transaction rules. +.IP \[bu] 2 +The \f[CR]balance \-\-budget\f[R] report infers budget goals from +periodic transaction rules. +.IP \[bu] 2 +Commands like \f[CR]close\f[R], \f[CR]rewrite\f[R], and +\f[CR]hledger\-interest\f[R] generate transactions or postings. +.IP \[bu] 2 +CSV data is converted to transactions by applying CSV conversion rules.. +etc. .PP -Generated data of this kind is temporary, existing only at report time. -But you can see it in the output of \f[CR]hledger print\f[R], and you -can save that to your journal, in effect converting it from temporary -generated data to permanent recorded data. -This could be useful as a data entry aid. +Such generated data is temporary, existing only at report time. +You can convert it to permanent recorded data by, eg, capturing the +output of \f[CR]hledger print\f[R] and saving it in your journal file. +This can sometimes be useful as a data entry aid. .PP -If you are wondering what data is being generated and why, add the -\f[CR]\-\-verbose\-tags\f[R] flag. -In \f[CR]hledger print\f[R] output you will see extra tags like -\f[CR]generated\-transaction\f[R], \f[CR]generated\-posting\f[R], and -\f[CR]modified\f[R] on generated/modified data. -Also, even without \f[CR]\-\-verbose\-tags\f[R], generated data always -has equivalen hidden tags (with an underscore prefix), so eg you could -match generated transactions with -\f[CR]tag:_generated\-transaction\f[R]. +If you are curious what data is being generated and why, run +\f[CR]hledger print \-x \-\-verbose\-tags\f[R]. +\f[CR]\-x/\-\-explicit\f[R] shows inferred amounts and +\f[CR]\-\-verbose\-tags\f[R] adds tags like +\f[CR]generated\-transaction\f[R] (from periodic rules) and +\f[CR]generated\-posting\f[R], \f[CR]modified\f[R] (from auto posting +rules). +Similar hidden tags (with an underscore prefix) are always present, +also, so you can always match such data with queries like +\f[CR]tag:generated\f[R] or \f[CR]tag:modified\f[R]. .SH Forecasting Forecasting, or speculative future reporting, can be useful for estimating future balances, or for exploring different future scenarios. diff --git a/hledger/hledger.info b/hledger/hledger.info index f1ef34149..5e4a1cc8f 100644 --- a/hledger/hledger.info +++ b/hledger/hledger.info @@ -15,8 +15,10 @@ hledger - a robust, friendly plain text accounting app (command line version). 'hledger' +or 'hledger COMMAND [OPTS] [ARGS]' -'hledger ADDONCMD -- [OPTS] [ARGS]' +or +'hledger ADDONCMD [OPTS] -- [ADDONOPTS] [ADDONARGS]' hledger is a robust, user-friendly, cross-platform set of programs for tracking money, time, or any other commodity, using double-entry @@ -24,7 +26,7 @@ accounting and a simple, editable file format. hledger is inspired by and largely compatible with ledger(1), and largely interconvertible with beancount(1). - This manual is for hledger's command line interface, version 1.33.99. + This manual is for hledger's command line interface, version 1.34.99. It also describes the common options, file formats and concepts used by all hledger programs. It might accidentally teach you some bookkeeping/accounting as well! You don't need to know everything in @@ -87,7 +89,6 @@ file" and "Setting opening balances" sections in PART 5: COMMON TASKS. * Input:: * Commands:: * Options:: -* Command line tips:: * Output:: * Environment:: * PART 2 DATA FORMATS:: @@ -238,8 +239,8 @@ The file name '-' means standard input: $ cat FILE | hledger -f- print - If reading non-journal data in this way, you'll need to add a file -format prefix, like: + If reading non-journal data in this way, you'll need to write the +format as a prefix, like 'timeclock:' here: $ echo 'i 2009/13/1 08:00:00' | hledger print -f timeclock:- @@ -349,14 +350,14 @@ difficulty, you can always run the add-on directly, without using 'hledger': 'hledger-ui --watch' or 'hledger-web --serve'.  -File: hledger.info, Node: Options, Next: Command line tips, Prev: Commands, Up: Top +File: hledger.info, Node: Options, Next: Output, Prev: Commands, Up: Top 4 Options ********* -Run 'hledger -h' to see general command line help, and general options -which are common to most hledger commands. These options can be written -anywhere on the command line: +Run 'hledger -h' to see general command line help. The following +general options are common to most hledger commands. General options +can be written either before or after the command name. General input/data transformation flags: -f --file=FILE Read data from FILE, or from stdin if -. Can be @@ -424,7 +425,6 @@ General output/reporting flags (supported by some commands): Eg: -c '.' or -c '1.000,00 EUR' --color=YN --colour Use ANSI color codes in text output? Can be 'y'/'yes'/'always', 'n'/'no'/'never' or 'auto'. - (A NO_COLOR environment variable overrides this.) --pretty[=YN] Use box-drawing characters in text output? Can be 'y'/'yes' or 'n'/'no'. If YN is specified, the equals is required. @@ -433,42 +433,34 @@ General output/reporting flags (supported by some commands): General help flags: -h --help show command line help --tldr show command examples with tldr - --info show the hledger manual with info - --man show the hledger manual with man + --info show the manual with info + --man show the manual with man --version show version information - Some reporting options can also be written as query arguments. + Usually hledger accepts any unambiguous flag prefix, eg you can write +'--tl' instead of '--tldr' or '--dry' instead of '--dry-run'. - -File: hledger.info, Node: Command line tips, Next: Output, Prev: Options, Up: Top + If the same option appears more than once in a command, usually the +last (right-most) wins. -5 Command line tips -******************* + With most commands, arguments are interpreted as a hledger query +which filter the data. Some queries can be expressed either with +options or with arguments. -Here are some details useful to know about for hledger command lines -(and elsewhere). Feel free to skip this section until you need it. + Below are more tips for using the command line interface - feel free +to skip these until you need them. * Menu: -* Option repetition:: * Special characters:: * Unicode characters:: * Regular expressions:: * Argument files::  -File: hledger.info, Node: Option repetition, Next: Special characters, Up: Command line tips +File: hledger.info, Node: Special characters, Next: Unicode characters, Up: Options -5.1 Option repetition -===================== - -If options are repeated in a command line, hledger will generally use -the last (right-most) occurence. - - -File: hledger.info, Node: Special characters, Next: Unicode characters, Prev: Option repetition, Up: Command line tips - -5.2 Special characters +4.1 Special characters ====================== * Menu: @@ -481,7 +473,7 @@ File: hledger.info, Node: Special characters, Next: Unicode characters, Prev:  File: hledger.info, Node: Single escaping shell metacharacters, Next: Double escaping regular expression metacharacters, Up: Special characters -5.2.1 Single escaping (shell metacharacters) +4.1.1 Single escaping (shell metacharacters) -------------------------------------------- In shell command lines, characters significant to your shell - such as @@ -503,7 +495,7 @@ PowerShell treats both single and double quotes as quotes.  File: hledger.info, Node: Double escaping regular expression metacharacters, Next: Triple escaping for add-on commands, Prev: Single escaping shell metacharacters, Up: Special characters -5.2.2 Double escaping (regular expression metacharacters) +4.1.2 Double escaping (regular expression metacharacters) --------------------------------------------------------- Characters significant in regular expressions (described below) - such @@ -523,7 +515,7 @@ $ hledger balance cur:\\$  File: hledger.info, Node: Triple escaping for add-on commands, Next: Less escaping, Prev: Double escaping regular expression metacharacters, Up: Special characters -5.2.3 Triple escaping (for add-on commands) +4.1.3 Triple escaping (for add-on commands) ------------------------------------------- When you use hledger to run an external add-on command (described @@ -553,7 +545,7 @@ $ hledger-ui cur:\\$  File: hledger.info, Node: Less escaping, Prev: Triple escaping for add-on commands, Up: Special characters -5.2.4 Less escaping +4.1.4 Less escaping ------------------- Options and arguments are sometimes used in places other than the shell @@ -566,9 +558,9 @@ use one less level of escaping. Those places include: * GHCI's prompt (used by developers).  -File: hledger.info, Node: Unicode characters, Next: Regular expressions, Prev: Special characters, Up: Command line tips +File: hledger.info, Node: Unicode characters, Next: Regular expressions, Prev: Special characters, Up: Options -5.3 Unicode characters +4.2 Unicode characters ====================== hledger is expected to handle non-ascii characters correctly: @@ -606,9 +598,9 @@ hledger is expected to handle non-ascii characters correctly: terminal, and vice versa. (See eg #961).  -File: hledger.info, Node: Regular expressions, Next: Argument files, Prev: Unicode characters, Up: Command line tips +File: hledger.info, Node: Regular expressions, Next: Argument files, Prev: Unicode characters, Up: Options -5.4 Regular expressions +4.3 Regular expressions ======================= A regular expression (regexp) is a small piece of text where certain @@ -683,7 +675,7 @@ if %amount \b3\.99  File: hledger.info, Node: hledger's regular expressions, Up: Regular expressions -5.4.1 hledger's regular expressions +4.3.1 hledger's regular expressions ----------------------------------- hledger's regular expressions come from the regex-tdfa library. If @@ -717,9 +709,9 @@ they support: See Special characters.  -File: hledger.info, Node: Argument files, Prev: Regular expressions, Up: Command line tips +File: hledger.info, Node: Argument files, Prev: Regular expressions, Up: Options -5.5 Argument files +4.4 Argument files ================== You can save a set of command line options and arguments in a file, and @@ -733,9 +725,9 @@ argument. For the special characters mentioned above, use one less level of quoting than you would at the command prompt.  -File: hledger.info, Node: Output, Next: Environment, Prev: Command line tips, Up: Top +File: hledger.info, Node: Output, Next: Environment, Prev: Options, Up: Top -6 Output +5 Output ******** * Menu: @@ -751,7 +743,7 @@ File: hledger.info, Node: Output, Next: Environment, Prev: Command line tips,  File: hledger.info, Node: Output destination, Next: Output format, Up: Output -6.1 Output destination +5.1 Output destination ====================== hledger commands send their output to the terminal by default. You can @@ -769,7 +761,7 @@ $ hledger print -o - # write to stdout (the default)  File: hledger.info, Node: Output format, Next: Commodity styles, Prev: Output destination, Up: Output -6.2 Output format +5.2 Output format ================= Some commands offer other kinds of output, not just text on the @@ -816,7 +808,7 @@ $ hledger balancesheet -o foo.txt -O csv # write CSV to foo.txt  File: hledger.info, Node: CSV output, Next: HTML output, Up: Output format -6.2.1 CSV output +5.2.1 CSV output ---------------- * In CSV output, digit group marks (such as thousands separators) are @@ -825,7 +817,7 @@ File: hledger.info, Node: CSV output, Next: HTML output, Up: Output format  File: hledger.info, Node: HTML output, Next: JSON output, Prev: CSV output, Up: Output format -6.2.2 HTML output +5.2.2 HTML output ----------------- * HTML output can be styled by an optional 'hledger.css' file in the @@ -834,7 +826,7 @@ File: hledger.info, Node: HTML output, Next: JSON output, Prev: CSV output,  File: hledger.info, Node: JSON output, Next: SQL output, Prev: HTML output, Up: Output format -6.2.3 JSON output +5.2.3 JSON output ----------------- * This is not yet much used; real-world feedback is welcome. @@ -843,6 +835,7 @@ File: hledger.info, Node: JSON output, Next: SQL output, Prev: HTML output, representation of hledger's internal data types. To understand the JSON, read the Haskell type definitions, which are mostly in https://github.com/simonmichael/hledger/blob/master/hledger-lib/Hledger/Data/Types.hs. + hledger-web's OpenAPI specification may also be relevant. * hledger represents quantities as Decimal values storing up to 255 significant digits, eg for repeating decimals. Such numbers can @@ -856,7 +849,7 @@ File: hledger.info, Node: JSON output, Next: SQL output, Prev: HTML output,  File: hledger.info, Node: SQL output, Prev: JSON output, Up: Output format -6.2.4 SQL output +5.2.4 SQL output ---------------- * This is not yet much used; real-world feedback is welcome. @@ -879,7 +872,7 @@ File: hledger.info, Node: SQL output, Prev: JSON output, Up: Output format  File: hledger.info, Node: Commodity styles, Next: Colour, Prev: Output format, Up: Output -6.3 Commodity styles +5.3 Commodity styles ==================== When displaying amounts, hledger infers a standard display style for @@ -902,7 +895,7 @@ parseability (such as adding trailing decimal marks when needed).  File: hledger.info, Node: Colour, Next: Box-drawing, Prev: Commodity styles, Up: Output -6.4 Colour +5.4 Colour ========== In terminal output, some commands can produce colour when the terminal @@ -918,7 +911,7 @@ supports it:  File: hledger.info, Node: Box-drawing, Next: Paging, Prev: Colour, Up: Output -6.5 Box-drawing +5.5 Box-drawing =============== In terminal output, you can enable unicode box-drawing characters to @@ -931,7 +924,7 @@ render prettier tables:  File: hledger.info, Node: Paging, Next: Debug output, Prev: Box-drawing, Up: Output -6.6 Paging +5.6 Paging ========== When showing long output in the terminal, hledger will try to use the @@ -955,7 +948,7 @@ to disable all ANSI output (see Colour).  File: hledger.info, Node: Debug output, Prev: Paging, Up: Output -6.7 Debug output +5.7 Debug output ================ We intend hledger to be relatively easy to troubleshoot, introspect and @@ -973,7 +966,7 @@ hledger bal --debug=3 2>hledger.log  File: hledger.info, Node: Environment, Next: PART 2 DATA FORMATS, Prev: Output, Up: Top -7 Environment +6 Environment ************* These environment variables affect hledger: @@ -985,20 +978,21 @@ set, they will try to use the available terminal width. *LEDGER_FILE* The main journal file to use when not specified with '-f/--file'. Default: '$HOME/.hledger.journal'. - *NO_COLOR* If this environment variable is set (with any value), -hledger will not use ANSI color codes in terminal output, unless -overridden by an explicit '--color/--colour' option. + *NO_COLOR* If this environment variable exists (with any value, +including empty), hledger will not use ANSI color codes in terminal +output, unless overridden by an explicit '--color=y'/'--colour=y' +option.  File: hledger.info, Node: PART 2 DATA FORMATS, Next: Journal, Prev: Environment, Up: Top -8 PART 2: DATA FORMATS +7 PART 2: DATA FORMATS **********************  File: hledger.info, Node: Journal, Next: CSV, Prev: PART 2 DATA FORMATS, Up: Top -9 Journal +8 Journal ********* hledger's usual data source is a plain text file containing journal @@ -1069,7 +1063,7 @@ part.  File: hledger.info, Node: Journal cheatsheet, Next: Comments, Up: Journal -9.1 Journal cheatsheet +8.1 Journal cheatsheet ====================== # Here is the main syntax of hledger's journal format @@ -1203,7 +1197,7 @@ include other.journal ; Include another journal file here.  File: hledger.info, Node: Comments, Next: Transactions, Prev: Journal cheatsheet, Up: Journal -9.2 Comments +8.2 Comments ============ Lines in the journal will be ignored if they begin with a hash ('#') or @@ -1233,7 +1227,7 @@ comments, and Account comments below.  File: hledger.info, Node: Transactions, Next: Dates, Prev: Comments, Up: Journal -9.3 Transactions +8.3 Transactions ================ Transactions are the main unit of information in a journal file. They @@ -1262,7 +1256,7 @@ optional fields, separated by spaces:  File: hledger.info, Node: Dates, Next: Status, Prev: Transactions, Up: Journal -9.4 Dates +8.4 Dates ========= * Menu: @@ -1273,7 +1267,7 @@ File: hledger.info, Node: Dates, Next: Status, Prev: Transactions, Up: Journ  File: hledger.info, Node: Simple dates, Next: Posting dates, Up: Dates -9.4.1 Simple dates +8.4.1 Simple dates ------------------ Dates in the journal file use _simple dates_ format: 'YYYY-MM-DD' or @@ -1289,7 +1283,7 @@ dates documented in the hledger manual.)  File: hledger.info, Node: Posting dates, Prev: Simple dates, Up: Dates -9.4.2 Posting dates +8.4.2 Posting dates ------------------- You can give individual postings a different date from their parent @@ -1317,7 +1311,7 @@ a 'date:' tag with no value is not allowed.  File: hledger.info, Node: Status, Next: Code, Prev: Dates, Up: Journal -9.5 Status +8.5 Status ========== Transactions (or individual postings within a transaction) can have a @@ -1365,7 +1359,7 @@ your finances.  File: hledger.info, Node: Code, Next: Description, Prev: Status, Up: Journal -9.6 Code +8.6 Code ======== After the status mark, but before the description, you can optionally @@ -1376,7 +1370,7 @@ or reference number.  File: hledger.info, Node: Description, Next: Transaction comments, Prev: Code, Up: Journal -9.7 Description +8.7 Description =============== After the date, status mark and/or code fields, the rest of the line (or @@ -1398,7 +1392,7 @@ description with '--pivot desc'.  File: hledger.info, Node: Payee and note, Up: Description -9.7.1 Payee and note +8.7.1 Payee and note -------------------- Sometimes people want a dedicated payee/payer field that can be queried @@ -1424,7 +1418,7 @@ checkable payee name, even if it's empty.)  File: hledger.info, Node: Transaction comments, Next: Postings, Prev: Description, Up: Journal -9.8 Transaction comments +8.8 Transaction comments ======================== Text following ';', after a transaction description, and/or on indented @@ -1440,7 +1434,7 @@ tags, which are not ignored.  File: hledger.info, Node: Postings, Next: Account names, Prev: Transaction comments, Up: Journal -9.9 Postings +8.9 Postings ============ A posting is an addition of some amount to, or removal of some amount @@ -1472,7 +1466,7 @@ will infer what it should be so as to balance the transaction.  File: hledger.info, Node: Debits and credits, Next: The two space delimiter, Up: Postings -9.9.1 Debits and credits +8.9.1 Debits and credits ------------------------ The traditional accounting concepts of debit and credit of course exist @@ -1490,7 +1484,7 @@ _'credit / minus / right / longer words'_  File: hledger.info, Node: The two space delimiter, Prev: Debits and credits, Up: Postings -9.9.2 The two space delimiter +8.9.2 The two space delimiter ----------------------------- Be sure to notice the unusual separator between the account name and the @@ -1503,7 +1497,7 @@ probably need to add another space between them.  File: hledger.info, Node: Account names, Next: Amounts, Prev: Postings, Up: Journal -9.10 Account names +8.10 Account names ================== Accounts are the main way of categorising things in hledger. As in @@ -1554,7 +1548,7 @@ aliases.  File: hledger.info, Node: Amounts, Next: Balance assertions, Prev: Account names, Up: Journal -9.11 Amounts +8.11 Amounts ============ After the account name, there is usually an amount. (Remember: between @@ -1602,7 +1596,7 @@ EUR 1E3  File: hledger.info, Node: Decimal marks, Next: Digit group marks, Up: Amounts -9.11.1 Decimal marks +8.11.1 Decimal marks -------------------- A _decimal mark_ can be written as a period or a comma: @@ -1634,7 +1628,7 @@ disambiguate them - see Trailing decimal marks).  File: hledger.info, Node: Digit group marks, Next: Commodity, Prev: Decimal marks, Up: Amounts -9.11.2 Digit group marks +8.11.2 Digit group marks ------------------------ In the integer part of the amount quantity (left of the decimal mark), @@ -1652,7 +1646,7 @@ INR 9,99,99,999.00  File: hledger.info, Node: Commodity, Next: Costs, Prev: Digit group marks, Up: Amounts -9.11.3 Commodity +8.11.3 Commodity ---------------- Amounts in hledger have both a "quantity", which is a signed decimal @@ -1679,7 +1673,7 @@ style below.  File: hledger.info, Node: Costs, Prev: Commodity, Up: Amounts -9.11.4 Costs +8.11.4 Costs ------------ After a posting amount, you can note its cost (when buying) or selling @@ -1733,7 +1727,7 @@ not required to be. This can be a little confusing, see discussion at  File: hledger.info, Node: Balance assertions, Next: Posting comments, Prev: Amounts, Up: Journal -9.12 Balance assertions +8.12 Balance assertions ======================= hledger supports Ledger-style balance assertions in journal files. @@ -1772,7 +1766,7 @@ does not disable balance assignments, described below).  File: hledger.info, Node: Assertions and ordering, Next: Assertions and multiple included files, Up: Balance assertions -9.12.1 Assertions and ordering +8.12.1 Assertions and ordering ------------------------------ hledger calculates and checks an account's balance assertions in date @@ -1789,7 +1783,7 @@ updating.  File: hledger.info, Node: Assertions and multiple included files, Next: Assertions and multiple -f files, Prev: Assertions and ordering, Up: Balance assertions -9.12.2 Assertions and multiple included files +8.12.2 Assertions and multiple included files --------------------------------------------- Multiple files included with the 'include' directive are processed as if @@ -1805,7 +1799,7 @@ balance on that day, you'll need to put the assertion in the right file  File: hledger.info, Node: Assertions and multiple -f files, Next: Assertions and costs, Prev: Assertions and multiple included files, Up: Balance assertions -9.12.3 Assertions and multiple -f files +8.12.3 Assertions and multiple -f files --------------------------------------- Unlike 'include', when multiple files are specified on the command line @@ -1819,7 +1813,7 @@ problems in earlier files to disrupt valid assertions in later files.  File: hledger.info, Node: Assertions and costs, Next: Assertions and commodities, Prev: Assertions and multiple -f files, Up: Balance assertions -9.12.4 Assertions and costs +8.12.4 Assertions and costs --------------------------- Balance assertions ignore costs, and should normally be written without @@ -1837,7 +1831,7 @@ costs), and because balance _assignments_ do use costs (see below).  File: hledger.info, Node: Assertions and commodities, Next: Assertions and subaccounts, Prev: Assertions and costs, Up: Balance assertions -9.12.5 Assertions and commodities +8.12.5 Assertions and commodities --------------------------------- The balance assertions described so far are "*single commodity balance @@ -1886,7 +1880,7 @@ specified commodities and no others. It can be done by  File: hledger.info, Node: Assertions and subaccounts, Next: Assertions and virtual postings, Prev: Assertions and commodities, Up: Balance assertions -9.12.6 Assertions and subaccounts +8.12.6 Assertions and subaccounts --------------------------------- All of the balance assertions above (both '=' and '==') are @@ -1905,7 +1899,7 @@ by adding a star after the equals ('=*' or '==*'):  File: hledger.info, Node: Assertions and virtual postings, Next: Assertions and auto postings, Prev: Assertions and subaccounts, Up: Balance assertions -9.12.7 Assertions and virtual postings +8.12.7 Assertions and virtual postings -------------------------------------- Balance assertions always consider both real and virtual postings; they @@ -1914,7 +1908,7 @@ are not affected by the '--real/-R' flag or 'real:' query.  File: hledger.info, Node: Assertions and auto postings, Next: Assertions and precision, Prev: Assertions and virtual postings, Up: Balance assertions -9.12.8 Assertions and auto postings +8.12.8 Assertions and auto postings ----------------------------------- Balance assertions _are_ affected by the '--auto' flag, which generates @@ -1933,7 +1927,7 @@ these. So to avoid making fragile assertions, either:  File: hledger.info, Node: Assertions and precision, Prev: Assertions and auto postings, Up: Balance assertions -9.12.9 Assertions and precision +8.12.9 Assertions and precision ------------------------------- Balance assertions compare the exactly calculated amounts, which are not @@ -1944,7 +1938,7 @@ assertion failure messages show exact amounts.  File: hledger.info, Node: Posting comments, Next: Transaction balancing, Prev: Balance assertions, Up: Journal -9.13 Posting comments +8.13 Posting comments ===================== Text following ';', at the end of a posting line, and/or on indented @@ -1961,7 +1955,7 @@ tags, which are not ignored.  File: hledger.info, Node: Transaction balancing, Next: Tags, Prev: Posting comments, Up: Journal -9.14 Transaction balancing +8.14 Transaction balancing ========================== How exactly does hledger decide when a transaction is balanced ? The @@ -2003,7 +1997,7 @@ directives' placement might be important - see 'commodity' directive.  File: hledger.info, Node: Tags, Next: Directives, Prev: Transaction balancing, Up: Journal -9.15 Tags +8.15 Tags ========= Tags are a way to add extra labels or data fields to transactions, @@ -2045,7 +2039,7 @@ posting).  File: hledger.info, Node: Tag names, Next: Special tags, Up: Tags -9.15.1 Tag names +8.15.1 Tag names ---------------- Most non-whitespace characters are allowed in tag names. Eg '😀:' is a @@ -2064,7 +2058,7 @@ them with the check command.  File: hledger.info, Node: Special tags, Next: Tag values, Prev: Tag names, Up: Tags -9.15.2 Special tags +8.15.2 Special tags ------------------- Some tag names have special significance to hledger. There's not much @@ -2099,7 +2093,7 @@ Not displayed, but queryable:  File: hledger.info, Node: Tag values, Prev: Special tags, Up: Tags -9.15.3 Tag values +8.15.3 Tag values ----------------- Tags can have a value, which is any text after the colon up until a @@ -2127,7 +2121,7 @@ with  File: hledger.info, Node: Directives, Next: account directive, Prev: Tags, Up: Journal -9.16 Directives +8.16 Directives =============== Besides transactions, there is something else you can put in a 'journal' @@ -2167,7 +2161,7 @@ Declare market prices 'P'  File: hledger.info, Node: Directives and multiple files, Next: Directive effects, Up: Directives -9.16.1 Directives and multiple files +8.16.1 Directives and multiple files ------------------------------------ Directives vary in their scope, ie which journal entries and which input @@ -2187,7 +2181,7 @@ directives in your files.  File: hledger.info, Node: Directive effects, Prev: Directives and multiple files, Up: Directives -9.16.2 Directive effects +8.16.2 Directive effects ------------------------ Here are all hledger's directives, with their effects and scope @@ -2248,7 +2242,7 @@ directives*  File: hledger.info, Node: account directive, Next: alias directive, Prev: Directives, Up: Journal -9.17 'account' directive +8.17 'account' directive ======================== 'account' directives can be used to declare accounts (ie, the places @@ -2289,7 +2283,7 @@ account assets:bank:checking  File: hledger.info, Node: Account comments, Next: Account error checking, Up: account directive -9.17.1 Account comments +8.17.1 Account comments ----------------------- Text following *two or more spaces* and ';' at the end of an account @@ -2307,7 +2301,7 @@ account assets:bank:checking ; same-line comment, at least 2 spaces before th  File: hledger.info, Node: Account error checking, Next: Account display order, Prev: Account comments, Up: account directive -9.17.2 Account error checking +8.17.2 Account error checking ----------------------------- By default, accounts need not be declared; they come into existence when @@ -2335,7 +2329,7 @@ been declared by an account directive. Some notes:  File: hledger.info, Node: Account display order, Next: Account types, Prev: Account error checking, Up: account directive -9.17.3 Account display order +8.17.3 Account display order ---------------------------- Account directives also cause hledger to display accounts in a @@ -2377,7 +2371,7 @@ the other.  File: hledger.info, Node: Account types, Prev: Account display order, Up: account directive -9.17.4 Account types +8.17.4 Account types -------------------- hledger knows that accounts come in several types: assets, liabilities, @@ -2463,7 +2457,7 @@ account equity:conversion ; type: V  File: hledger.info, Node: alias directive, Next: commodity directive, Prev: account directive, Up: Journal -9.18 'alias' directive +8.18 'alias' directive ====================== You can define account alias rules which rewrite your account names, or @@ -2500,7 +2494,7 @@ more on this below.  File: hledger.info, Node: Basic aliases, Next: Regex aliases, Up: alias directive -9.18.1 Basic aliases +8.18.1 Basic aliases -------------------- To set an account alias, use the 'alias' directive in your journal file. @@ -2524,7 +2518,7 @@ alias checking = assets:bank:wells fargo:checking  File: hledger.info, Node: Regex aliases, Next: Combining aliases, Prev: Basic aliases, Up: alias directive -9.18.2 Regex aliases +8.18.2 Regex aliases -------------------- There is also a more powerful variant that uses a regular expression, @@ -2558,7 +2552,7 @@ of option argument), so it can contain trailing whitespace.  File: hledger.info, Node: Combining aliases, Next: Aliases and multiple files, Prev: Regex aliases, Up: alias directive -9.18.3 Combining aliases +8.18.3 Combining aliases ------------------------ You can define as many aliases as you like, using journal directives @@ -2595,7 +2589,7 @@ which aliases are being applied when.  File: hledger.info, Node: Aliases and multiple files, Next: end aliases directive, Prev: Combining aliases, Up: alias directive -9.18.4 Aliases and multiple files +8.18.4 Aliases and multiple files --------------------------------- As explained at Directives and multiple files, 'alias' directives do not @@ -2627,7 +2621,7 @@ include c.journal ; also affected  File: hledger.info, Node: end aliases directive, Next: Aliases can generate bad account names, Prev: Aliases and multiple files, Up: alias directive -9.18.5 'end aliases' directive +8.18.5 'end aliases' directive ------------------------------ You can clear (forget) all currently defined aliases (seen in the @@ -2638,7 +2632,7 @@ end aliases  File: hledger.info, Node: Aliases can generate bad account names, Next: Aliases and account types, Prev: end aliases directive, Up: alias directive -9.18.6 Aliases can generate bad account names +8.18.6 Aliases can generate bad account names --------------------------------------------- Be aware that account aliases can produce malformed account names, which @@ -2669,7 +2663,7 @@ $ hledger print --alias old="new USD" | hledger -f- print  File: hledger.info, Node: Aliases and account types, Prev: Aliases can generate bad account names, Up: alias directive -9.18.7 Aliases and account types +8.18.7 Aliases and account types -------------------------------- If an account with a type declaration (see Declaring accounts > Account @@ -2693,7 +2687,7 @@ $ hledger accounts --alias assets=bassetts type:a  File: hledger.info, Node: commodity directive, Next: decimal-mark directive, Prev: alias directive, Up: Journal -9.19 'commodity' directive +8.19 'commodity' directive ========================== The 'commodity' directive performs several functions: @@ -2735,7 +2729,7 @@ precise.  File: hledger.info, Node: Commodity directive syntax, Next: Commodity error checking, Up: commodity directive -9.19.1 Commodity directive syntax +8.19.1 Commodity directive syntax --------------------------------- A commodity directive is normally the word 'commodity' followed by a @@ -2782,7 +2776,7 @@ commodity INR  File: hledger.info, Node: Commodity error checking, Prev: Commodity directive syntax, Up: commodity directive -9.19.2 Commodity error checking +8.19.2 Commodity error checking ------------------------------- In strict mode ('-s'/'--strict') (or when you run 'hledger check @@ -2794,7 +2788,7 @@ have no commodity symbol.) It works like account error checking  File: hledger.info, Node: decimal-mark directive, Next: include directive, Prev: commodity directive, Up: Journal -9.20 'decimal-mark' directive +8.20 'decimal-mark' directive ============================= You can use a 'decimal-mark' directive - usually one per file, at the @@ -2814,7 +2808,7 @@ thousands separators).  File: hledger.info, Node: include directive, Next: P directive, Prev: decimal-mark directive, Up: Journal -9.21 'include' directive +8.21 'include' directive ======================== You can pull in the content of additional files by writing an include @@ -2845,7 +2839,7 @@ timedot:~/notes/2023*.md'.  File: hledger.info, Node: P directive, Next: payee directive, Prev: include directive, Up: Journal -9.22 'P' directive +8.22 'P' directive ================== The 'P' directive declares a market price, which is a conversion rate @@ -2875,7 +2869,7 @@ amount values in another commodity. See Value reporting.  File: hledger.info, Node: payee directive, Next: tag directive, Prev: P directive, Up: Journal -9.23 'payee' directive +8.23 'payee' directive ====================== 'payee PAYEE NAME' @@ -2898,7 +2892,7 @@ payee ""  File: hledger.info, Node: tag directive, Next: Periodic transactions, Prev: payee directive, Up: Journal -9.24 'tag' directive +8.24 'tag' directive ==================== 'tag TAGNAME' @@ -2918,7 +2912,7 @@ check your tags .  File: hledger.info, Node: Periodic transactions, Next: Auto postings, Prev: tag directive, Up: Journal -9.25 Periodic transactions +8.25 Periodic transactions ========================== The '~' directive declares a "periodic rule" which generates temporary @@ -2966,7 +2960,7 @@ this whole section, or at least the following tips:  File: hledger.info, Node: Periodic rule syntax, Next: Periodic rules and relative dates, Up: Periodic transactions -9.25.1 Periodic rule syntax +8.25.1 Periodic rule syntax --------------------------- A periodic transaction rule looks like a normal journal entry, with the @@ -2991,7 +2985,7 @@ dates).  File: hledger.info, Node: Periodic rules and relative dates, Next: Two spaces between period expression and description!, Prev: Periodic rule syntax, Up: Periodic transactions -9.25.2 Periodic rules and relative dates +8.25.2 Periodic rules and relative dates ---------------------------------------- Partial or relative dates (like '12/31', '25', 'tomorrow', 'last week', @@ -3010,7 +3004,7 @@ dates.  File: hledger.info, Node: Two spaces between period expression and description!, Prev: Periodic rules and relative dates, Up: Periodic transactions -9.25.3 Two spaces between period expression and description! +8.25.3 Two spaces between period expression and description! ------------------------------------------------------------ If the period expression is followed by a transaction description, these @@ -3035,7 +3029,7 @@ accidentally alter their meaning, as in this example:  File: hledger.info, Node: Auto postings, Next: Other syntax, Prev: Periodic transactions, Up: Journal -9.26 Auto postings +8.26 Auto postings ================== The '=' directive declares an "auto posting rule", which adds extra @@ -3125,7 +3119,7 @@ output into the journal file to make it permanent.  File: hledger.info, Node: Auto postings and multiple files, Up: Auto postings -9.26.1 Auto postings and multiple files +8.26.1 Auto postings and multiple files --------------------------------------- An auto posting rule can affect any transaction in the current file, or @@ -3142,7 +3136,7 @@ sibling files (when multiple '-f'/'--file' are used - see #1212).  File: hledger.info, Node: Auto postings and dates, Next: Auto postings and transaction balancing / inferred amounts / balance assertions, Up: Auto postings and multiple files -9.26.1.1 Auto postings and dates +8.26.1.1 Auto postings and dates ................................ A posting date (or secondary date) in the matched posting, or (taking @@ -3152,7 +3146,7 @@ used in the generated posting.  File: hledger.info, Node: Auto postings and transaction balancing / inferred amounts / balance assertions, Next: Auto posting tags, Prev: Auto postings and dates, Up: Auto postings and multiple files -9.26.1.2 Auto postings and transaction balancing / inferred +8.26.1.2 Auto postings and transaction balancing / inferred ........................................................... amounts / balance assertions Currently, auto postings are added: @@ -3172,7 +3166,7 @@ infer amounts.  File: hledger.info, Node: Auto posting tags, Next: Auto postings on forecast transactions only, Prev: Auto postings and transaction balancing / inferred amounts / balance assertions, Up: Auto postings and multiple files -9.26.1.3 Auto posting tags +8.26.1.3 Auto posting tags .......................... Automated postings will have some extra tags: @@ -3194,7 +3188,7 @@ will have these tags added:  File: hledger.info, Node: Auto postings on forecast transactions only, Prev: Auto posting tags, Up: Auto postings and multiple files -9.26.1.4 Auto postings on forecast transactions only +8.26.1.4 Auto postings on forecast transactions only .................................................... Tip: you can can make auto postings that will apply to forecast @@ -3205,7 +3199,7 @@ generating new journal entries to be saved in the journal.  File: hledger.info, Node: Other syntax, Prev: Auto postings, Up: Journal -9.27 Other syntax +8.27 Other syntax ================= hledger journal format supports quite a few other features, mainly to @@ -3232,7 +3226,7 @@ you decide if you want to use them.  File: hledger.info, Node: Balance assignments, Next: Bracketed posting dates, Up: Other syntax -9.27.1 Balance assignments +8.27.1 Balance assignments -------------------------- Ledger-style balance assignments are also supported. These are like @@ -3275,7 +3269,7 @@ trustworthy in an audit.  File: hledger.info, Node: Balance assignments and costs, Next: Balance assignments and multiple files, Up: Balance assignments -9.27.1.1 Balance assignments and costs +8.27.1.1 Balance assignments and costs ...................................... A cost in a balance assignment will cause the calculated amount to have @@ -3291,7 +3285,7 @@ $ hledger print --explicit  File: hledger.info, Node: Balance assignments and multiple files, Prev: Balance assignments and costs, Up: Balance assignments -9.27.1.2 Balance assignments and multiple files +8.27.1.2 Balance assignments and multiple files ............................................... Balance assignments handle multiple files like balance assertions. They @@ -3301,7 +3295,7 @@ but not from previous sibling or parent files.  File: hledger.info, Node: Bracketed posting dates, Next: D directive, Prev: Balance assignments, Up: Other syntax -9.27.2 Bracketed posting dates +8.27.2 Bracketed posting dates ------------------------------ For setting posting dates and secondary posting dates, Ledger's @@ -3318,7 +3312,7 @@ syntax.  File: hledger.info, Node: D directive, Next: apply account directive, Prev: Bracketed posting dates, Up: Other syntax -9.27.3 'D' directive +8.27.3 'D' directive -------------------- 'D AMOUNT' @@ -3364,7 +3358,7 @@ Ledger's 'D'.  File: hledger.info, Node: apply account directive, Next: Y directive, Prev: D directive, Up: Other syntax -9.27.4 'apply account' directive +8.27.4 'apply account' directive -------------------------------- This directive sets a default parent account, which will be prepended to @@ -3400,7 +3394,7 @@ portable, and less trustworthy in an audit.  File: hledger.info, Node: Y directive, Next: Secondary dates, Prev: apply account directive, Up: Other syntax -9.27.5 'Y' directive +8.27.5 'Y' directive -------------------- 'Y YEAR' @@ -3438,29 +3432,43 @@ date.  File: hledger.info, Node: Secondary dates, Next: Star comments, Prev: Y directive, Up: Other syntax -9.27.6 Secondary dates +8.27.6 Secondary dates ---------------------- A secondary date is written after the primary date, following an equals -sign. If the year is omitted, the primary date's year is assumed. When -running reports, the primary (left) date is used by default, but with -the '--date2' flag (or '--aux-date' or '--effective'), the secondary -(right) date will be used instead. +sign: 'DATE1=DATE2'. If the year is omitted, the primary date's year is +assumed. When running reports, the primary (left side) date is used by +default, but with the '--date2' flag ('--aux-date' or'--effective' also +work, for Ledger users), the secondary (right side) date will be used +instead. - The meaning of secondary dates is up to you, but it's best to follow -a consistent rule. Eg "primary = the bank's clearing date, secondary = -date the transaction was initiated, if different". + The meaning of secondary dates is up to you. Eg it could be "primary +is the bank's clearing date, secondary is the date the transaction was +initiated, if different". - Downsides: makes your financial data more complicated, less portable, -and less trustworthy in an audit. Keeping the meaning of the two dates -consistent requires discipline, and you have to remember which reporting -mode is appropriate for a given report. Posting dates are simpler and -better. + In practice, this feature usually adds confusion: + + * You have to remember the primary and secondary dates' meaning, and + follow that consistently. + * It splits your bookkeeping into two modes, and you have to remember + which mode is appropriate for a given report. + * Usually your balance assertions will work with only one of these + modes. + * It makes your financial data more complicated, less portable, and + less clear in an audit. + * It interacts with every feature, creating an ongoing cost for + implementors. + * It distracts new users and supporters. + * Posting dates are simpler and work better. + + So secondary dates are officially deprecated in hledger, remaining +only as a Ledger compatibility aid; we recommend using posting dates +instead.  File: hledger.info, Node: Star comments, Next: Valuation expressions, Prev: Secondary dates, Up: Other syntax -9.27.7 Star comments +8.27.7 Star comments -------------------- Lines beginning with '*' (star/asterisk) are also comment lines. This @@ -3477,7 +3485,7 @@ losing ledger mode's features.  File: hledger.info, Node: Valuation expressions, Next: Virtual postings, Prev: Star comments, Up: Other syntax -9.27.8 Valuation expressions +8.27.8 Valuation expressions ---------------------------- Ledger allows a valuation function or value to be written in double @@ -3486,7 +3494,7 @@ parentheses after an amount. hledger ignores these.  File: hledger.info, Node: Virtual postings, Next: Other Ledger directives, Prev: Valuation expressions, Up: Other syntax -9.27.9 Virtual postings +8.27.9 Virtual postings ----------------------- A posting with parentheses around the account name, like '(some:account) @@ -3518,7 +3526,7 @@ from reports with the '-R/--real' flag or a 'real:1' query.  File: hledger.info, Node: Other Ledger directives, Next: Other cost/lot notations, Prev: Virtual postings, Up: Other syntax -9.27.10 Other Ledger directives +8.27.10 Other Ledger directives ------------------------------- These other Ledger directives are currently accepted but ignored. This @@ -3549,7 +3557,7 @@ hledger/Ledger syntax comparison.  File: hledger.info, Node: Other cost/lot notations, Prev: Other Ledger directives, Up: Other syntax -9.27.11 Other cost/lot notations +8.27.11 Other cost/lot notations -------------------------------- A slight digression for Ledger and Beancount users. Ledger has a number @@ -3619,8 +3627,8 @@ but ignores it.  File: hledger.info, Node: CSV, Next: Timeclock, Prev: Journal, Up: Top -10 CSV -****** +9 CSV +***** hledger can read CSV files (Character Separated Value - usually comma, semicolon, or tab) containing dated records, automatically converting @@ -3689,8 +3697,8 @@ https://github.com/simonmichael/hledger/tree/master/examples/csv.  File: hledger.info, Node: CSV rules cheatsheet, Next: source, Up: CSV -10.1 CSV rules cheatsheet -========================= +9.1 CSV rules cheatsheet +======================== The following kinds of rule can appear in the rules file, in any order. (Blank lines and lines beginning with '#' or ';' or '*' are ignored.) @@ -3729,8 +3737,8 @@ evaluated.  File: hledger.info, Node: source, Next: separator, Prev: CSV rules cheatsheet, Up: CSV -10.2 'source' -============= +9.2 'source' +============ If you tell hledger to read a csv file with '-f foo.csv', it will look for rules in 'foo.csv.rules'. Or, you can tell it to read the rules @@ -3759,8 +3767,8 @@ source Checking1*.csv  File: hledger.info, Node: separator, Next: skip, Prev: source, Up: CSV -10.3 'separator' -================ +9.3 'separator' +=============== You can use the 'separator' rule to read other kinds of character-separated data. The argument is any single separator @@ -3784,8 +3792,8 @@ inferred automatically, and you won't need this rule.  File: hledger.info, Node: skip, Next: date-format, Prev: separator, Up: CSV -10.4 'skip' -=========== +9.4 'skip' +========== skip N @@ -3803,8 +3811,8 @@ required to be valid CSV.  File: hledger.info, Node: date-format, Next: timezone, Prev: skip, Up: CSV -10.5 'date-format' -================== +9.5 'date-format' +================= date-format DATEFMT @@ -3832,8 +3840,8 @@ date-format %-m/%-d/%Y %l:%M %p some other junk  File: hledger.info, Node: timezone, Next: newest-first, Prev: date-format, Up: CSV -10.6 'timezone' -=============== +9.6 'timezone' +============== timezone TIMEZONE @@ -3861,8 +3869,8 @@ For others, use numeric format: +HHMM or -HHMM.  File: hledger.info, Node: newest-first, Next: intra-day-reversed, Prev: timezone, Up: CSV -10.7 'newest-first' -=================== +9.7 'newest-first' +================== hledger tries to ensure that the generated transactions will be ordered chronologically, including same-day transactions. Usually it can @@ -3884,8 +3892,8 @@ newest-first  File: hledger.info, Node: intra-day-reversed, Next: decimal-mark, Prev: newest-first, Up: CSV -10.8 'intra-day-reversed' -========================= +9.8 'intra-day-reversed' +======================== If CSV records within a single day are ordered opposite to the overall record order, you can add the 'intra-day-reversed' rule to improve the @@ -3903,8 +3911,8 @@ intra-day-reversed  File: hledger.info, Node: decimal-mark, Next: fields list, Prev: intra-day-reversed, Up: CSV -10.9 'decimal-mark' -=================== +9.9 'decimal-mark' +================== decimal-mark . @@ -3921,8 +3929,8 @@ misparsed numbers.  File: hledger.info, Node: fields list, Next: Field assignment, Prev: decimal-mark, Up: CSV -10.10 'fields' list -=================== +9.10 'fields' list +================== fields FIELDNAME1, FIELDNAME2, ... @@ -3966,8 +3974,8 @@ field (and generating a balance assertion).  File: hledger.info, Node: Field assignment, Next: Field names, Prev: fields list, Up: CSV -10.11 Field assignment -====================== +9.11 Field assignment +===================== HLEDGERFIELD FIELDVALUE @@ -4000,8 +4008,8 @@ comment note: %somefield - %anotherfield, date: %1  File: hledger.info, Node: Field names, Next: if block, Prev: Field assignment, Up: CSV -10.12 Field names -================= +9.12 Field names +================ Note the two kinds of field names mentioned here, and used only in hledger CSV rules files: @@ -4049,48 +4057,48 @@ happens when you assign values to them:  File: hledger.info, Node: date field, Next: date2 field, Up: Field names -10.12.1 date field ------------------- +9.12.1 date field +----------------- Assigning to 'date' sets the transaction date.  File: hledger.info, Node: date2 field, Next: status field, Prev: date field, Up: Field names -10.12.2 date2 field -------------------- +9.12.2 date2 field +------------------ 'date2' sets the transaction's secondary date, if any.  File: hledger.info, Node: status field, Next: code field, Prev: date2 field, Up: Field names -10.12.3 status field --------------------- +9.12.3 status field +------------------- 'status' sets the transaction's status, if any.  File: hledger.info, Node: code field, Next: description field, Prev: status field, Up: Field names -10.12.4 code field ------------------- +9.12.4 code field +----------------- 'code' sets the transaction's code, if any.  File: hledger.info, Node: description field, Next: comment field, Prev: code field, Up: Field names -10.12.5 description field -------------------------- +9.12.5 description field +------------------------ 'description' sets the transaction's description, if any.  File: hledger.info, Node: comment field, Next: account field, Prev: description field, Up: Field names -10.12.6 comment field ---------------------- +9.12.6 comment field +-------------------- 'comment' sets the transaction's comment, if any. @@ -4104,8 +4112,8 @@ code. A comment starting with '\n' will begin on a new line.  File: hledger.info, Node: account field, Next: amount field, Prev: comment field, Up: Field names -10.12.7 account field ---------------------- +9.12.7 account field +-------------------- Assigning to 'accountN', where N is 1 to 99, sets the account name of the Nth posting, and causes that posting to be generated. @@ -4122,8 +4130,8 @@ or "income:unknown").  File: hledger.info, Node: amount field, Next: currency field, Prev: account field, Up: Field names -10.12.8 amount field --------------------- +9.12.8 amount field +------------------- There are several ways to set posting amounts from CSV, useful in different situations. @@ -4180,8 +4188,8 @@ different situations.  File: hledger.info, Node: currency field, Next: balance field, Prev: amount field, Up: Field names -10.12.9 currency field ----------------------- +9.12.9 currency field +--------------------- 'currency' sets a currency symbol, to be prepended to all postings' amounts. You can use this if the CSV amounts do not have a currency @@ -4193,8 +4201,8 @@ amount.  File: hledger.info, Node: balance field, Prev: currency field, Up: Field names -10.12.10 balance field ----------------------- +9.12.10 balance field +--------------------- 'balanceN' sets a balance assertion amount (or if the posting amount is left empty, a balance assignment) on posting N. @@ -4211,8 +4219,8 @@ and currency.  File: hledger.info, Node: if block, Next: Matchers, Prev: Field names, Up: CSV -10.13 'if' block -================ +9.13 'if' block +=============== Rules can be applied conditionally, depending on patterns in the CSV data. This allows flexibility; in particular, it is how you can @@ -4266,8 +4274,8 @@ if ,,,,  File: hledger.info, Node: Matchers, Next: if table, Prev: if block, Up: CSV -10.14 Matchers -============== +9.14 Matchers +============= There are two kinds: @@ -4296,8 +4304,8 @@ expressions" in the hledger manual  File: hledger.info, Node: What matchers match, Next: Combining matchers, Up: Matchers -10.14.1 What matchers match ---------------------------- +9.14.1 What matchers match +-------------------------- With record matchers, it's important to know that the record matched is not the original CSV record, but a modified one: separators will be @@ -4314,8 +4322,8 @@ the original record was:  File: hledger.info, Node: Combining matchers, Next: Match groups, Prev: What matchers match, Up: Matchers -10.14.2 Combining matchers --------------------------- +9.14.2 Combining matchers +------------------------- When an if block has multiple matchers, they are combined as follows: @@ -4332,8 +4340,8 @@ on the same line (you can't AND a negated matcher).  File: hledger.info, Node: Match groups, Prev: Combining matchers, Up: Matchers -10.14.3 Match groups --------------------- +9.14.3 Match groups +------------------- _Added in 1.32_ @@ -4360,8 +4368,8 @@ if %account1 liabilities:family:(expenses:.*)  File: hledger.info, Node: if table, Next: balance-type, Prev: Matchers, Up: CSV -10.15 'if' table -================ +9.15 'if' table +=============== "if tables" are an alternative to if blocks; they can express many matchers and field assignments in a more compact tabular format, like @@ -4421,8 +4429,8 @@ atm transaction fee,expenses:business:banking,deductible? check it  File: hledger.info, Node: balance-type, Next: include, Prev: if table, Up: CSV -10.16 'balance-type' -==================== +9.16 'balance-type' +=================== Balance assertions generated by assigning to balanceN are of the simple '=' type by default, which is a single-commodity, subaccount-excluding @@ -4444,8 +4452,8 @@ balance-type ==*  File: hledger.info, Node: include, Next: Working with CSV, Prev: balance-type, Up: CSV -10.17 'include' -=============== +9.17 'include' +============== include RULESFILE @@ -4467,8 +4475,8 @@ include categorisation.rules  File: hledger.info, Node: Working with CSV, Next: CSV rules examples, Prev: include, Up: CSV -10.18 Working with CSV -====================== +9.18 Working with CSV +===================== Some tips: @@ -4493,8 +4501,8 @@ Some tips:  File: hledger.info, Node: Rapid feedback, Next: Valid CSV, Up: Working with CSV -10.18.1 Rapid feedback ----------------------- +9.18.1 Rapid feedback +--------------------- It's a good idea to get rapid feedback while creating/troubleshooting CSV rules. Here's a good way, using entr from eradman.com/entrproject: @@ -4509,8 +4517,8 @@ output.  File: hledger.info, Node: Valid CSV, Next: File Extension, Prev: Rapid feedback, Up: Working with CSV -10.18.2 Valid CSV ------------------ +9.18.2 Valid CSV +---------------- Note that hledger will only accept valid CSV conforming to RFC 4180, and equivalent SSV and TSV formats (like RFC 4180 but with semicolon or tab @@ -4530,8 +4538,8 @@ permissive CSV parser like python's csv lib.  File: hledger.info, Node: File Extension, Next: Reading CSV from standard input, Prev: Valid CSV, Up: Working with CSV -10.18.3 File Extension ----------------------- +9.18.3 File Extension +--------------------- To help hledger choose the CSV file reader and show the right error messages (and choose the right field separator character by default), @@ -4550,8 +4558,8 @@ rule if needed.  File: hledger.info, Node: Reading CSV from standard input, Next: Reading multiple CSV files, Prev: File Extension, Up: Working with CSV -10.18.4 Reading CSV from standard input ---------------------------------------- +9.18.4 Reading CSV from standard input +-------------------------------------- You'll need the file format prefix when reading CSV from stdin also, since hledger assumes journal format by default. Eg: @@ -4561,8 +4569,8 @@ $ cat foo.dat | hledger -f ssv:- print  File: hledger.info, Node: Reading multiple CSV files, Next: Reading files specified by rule, Prev: Reading CSV from standard input, Up: Working with CSV -10.18.5 Reading multiple CSV files ----------------------------------- +9.18.5 Reading multiple CSV files +--------------------------------- If you use multiple '-f' options to read multiple CSV files at once, hledger will look for a correspondingly-named rules file for each CSV @@ -4572,8 +4580,8 @@ used for all the CSV files.  File: hledger.info, Node: Reading files specified by rule, Next: Valid transactions, Prev: Reading multiple CSV files, Up: Working with CSV -10.18.6 Reading files specified by rule ---------------------------------------- +9.18.6 Reading files specified by rule +-------------------------------------- Instead of specifying a CSV file in the command line, you can specify a rules file, as in 'hledger -f foo.csv.rules CMD'. By default this will @@ -4601,8 +4609,8 @@ most recent.  File: hledger.info, Node: Valid transactions, Next: Deduplicating importing, Prev: Reading files specified by rule, Up: Working with CSV -10.18.7 Valid transactions --------------------------- +9.18.7 Valid transactions +------------------------- After reading a CSV file, hledger post-processes and validates the generated journal entries as it would for a journal file - balancing @@ -4620,8 +4628,8 @@ $ hledger -f file.csv print | hledger -f- print  File: hledger.info, Node: Deduplicating importing, Next: Setting amounts, Prev: Valid transactions, Up: Working with CSV -10.18.8 Deduplicating, importing --------------------------------- +9.18.8 Deduplicating, importing +------------------------------- When you download a CSV file periodically, eg to get your latest bank transactions, the new file may overlap with the old one, containing some @@ -4650,8 +4658,8 @@ CSV data. See:  File: hledger.info, Node: Setting amounts, Next: Amount signs, Prev: Deduplicating importing, Up: Working with CSV -10.18.9 Setting amounts ------------------------ +9.18.9 Setting amounts +---------------------- Continuing from amount field above, here are more tips for amount-setting: @@ -4717,8 +4725,8 @@ amount-setting:  File: hledger.info, Node: Amount signs, Next: Setting currency/commodity, Prev: Setting amounts, Up: Working with CSV -10.18.10 Amount signs ---------------------- +9.18.10 Amount signs +-------------------- There is some special handling making it easier to parse and to reverse amount signs. (This only works for whole amounts, not for cost amounts @@ -4747,8 +4755,8 @@ its absolute value, ie discard its sign.  File: hledger.info, Node: Setting currency/commodity, Next: Amount decimal places, Prev: Amount signs, Up: Working with CSV -10.18.11 Setting currency/commodity ------------------------------------ +9.18.11 Setting currency/commodity +---------------------------------- If the currency/commodity symbol is included in the CSV's amount field(s): @@ -4795,8 +4803,8 @@ that would trigger the prepending effect, which we don't want here.  File: hledger.info, Node: Amount decimal places, Next: Referencing other fields, Prev: Setting currency/commodity, Up: Working with CSV -10.18.12 Amount decimal places ------------------------------- +9.18.12 Amount decimal places +----------------------------- When you are reading CSV data, eg with a command like 'hledger -f foo.csv print', hledger will infer each commodity's decimal precision @@ -4824,8 +4832,8 @@ want, add a 'commodity' directive to specify them.  File: hledger.info, Node: Referencing other fields, Next: How CSV rules are evaluated, Prev: Amount decimal places, Up: Working with CSV -10.18.13 Referencing other fields ---------------------------------- +9.18.13 Referencing other fields +-------------------------------- In field assignments, you can interpolate only CSV fields, not hledger fields. In the example below, there's both a CSV field and a hledger @@ -4861,8 +4869,8 @@ if something  File: hledger.info, Node: How CSV rules are evaluated, Next: Well factored rules, Prev: Referencing other fields, Up: Working with CSV -10.18.14 How CSV rules are evaluated ------------------------------------- +9.18.14 How CSV rules are evaluated +----------------------------------- Here's how to think of CSV rules being evaluated (if you really need to). First, @@ -4902,8 +4910,8 @@ command the user specified.  File: hledger.info, Node: Well factored rules, Prev: How CSV rules are evaluated, Up: Working with CSV -10.18.15 Well factored rules ----------------------------- +9.18.15 Well factored rules +--------------------------- Some things than can help reduce duplication and complexity in rules files: @@ -4918,8 +4926,8 @@ files:  File: hledger.info, Node: CSV rules examples, Prev: Working with CSV, Up: CSV -10.19 CSV rules examples -======================== +9.19 CSV rules examples +======================= * Menu: @@ -4931,8 +4939,8 @@ File: hledger.info, Node: CSV rules examples, Prev: Working with CSV, Up: CSV  File: hledger.info, Node: Bank of Ireland, Next: Coinbase, Up: CSV rules examples -10.19.1 Bank of Ireland ------------------------ +9.19.1 Bank of Ireland +---------------------- Here's a CSV with two amount fields (Debit and Credit), and a balance field, which we can use to add balance assertions, which is not @@ -4984,8 +4992,8 @@ imported into a journal file.  File: hledger.info, Node: Coinbase, Next: Amazon, Prev: Bank of Ireland, Up: CSV rules examples -10.19.2 Coinbase ----------------- +9.19.2 Coinbase +--------------- A simple example with some CSV from Coinbase. The spot price is recorded using cost notation. The legacy 'amount' field name @@ -5011,8 +5019,8 @@ $ hledger print -f coinbase.csv  File: hledger.info, Node: Amazon, Next: Paypal, Prev: Coinbase, Up: CSV rules examples -10.19.3 Amazon --------------- +9.19.3 Amazon +------------- Here we convert amazon.com order history, and use an if block to generate a third posting if there's a fee. (In practice you'd probably @@ -5069,8 +5077,8 @@ $ hledger -f amazon-orders.csv print  File: hledger.info, Node: Paypal, Prev: Amazon, Up: CSV rules examples -10.19.4 Paypal --------------- +9.19.4 Paypal +------------- Here's a real-world rules file for (customised) Paypal CSV, with some Paypal-specific rules, and a second rules file included: @@ -5223,7 +5231,7 @@ $ hledger -f paypal-custom.csv print  File: hledger.info, Node: Timeclock, Next: Timedot, Prev: CSV, Up: Top -11 Timeclock +10 Timeclock ************ The time logging format of timeclock.el, as read by hledger. @@ -5278,7 +5286,7 @@ $ hledger -f sample.timeclock register -p weekly --depth 1 --empty # time summa  File: hledger.info, Node: Timedot, Next: PART 3 REPORTING CONCEPTS, Prev: Timeclock, Up: Top -12 Timedot +11 Timedot ********** 'timedot' format is hledger's human-friendly time logging format. @@ -5359,7 +5367,7 @@ notes in the same file:  File: hledger.info, Node: Timedot examples, Up: Timedot -12.1 Timedot examples +11.1 Timedot examples ===================== Numbers: @@ -5466,13 +5474,13 @@ $ hledger -f a.timedot --alias '/\./=:' bal -t  File: hledger.info, Node: PART 3 REPORTING CONCEPTS, Next: Time periods, Prev: Timedot, Up: Top -13 PART 3: REPORTING CONCEPTS +12 PART 3: REPORTING CONCEPTS *****************************  File: hledger.info, Node: Time periods, Next: Depth, Prev: PART 3 REPORTING CONCEPTS, Up: Top -14 Time periods +13 Time periods *************** * Menu: @@ -5486,7 +5494,7 @@ File: hledger.info, Node: Time periods, Next: Depth, Prev: PART 3 REPORTING C  File: hledger.info, Node: Report start & end date, Next: Smart dates, Up: Time periods -14.1 Report start & end date +13.1 Report start & end date ============================ Most hledger reports will by default show the full time period @@ -5535,7 +5543,7 @@ during January 2020 (the smallest common period, with the -p overriding  File: hledger.info, Node: Smart dates, Next: Report intervals, Prev: Report start & end date, Up: Time periods -14.2 Smart dates +13.2 Smart dates ================ In hledger's user interfaces (though not in the journal file), you can @@ -5602,7 +5610,7 @@ affected by '--today'.)  File: hledger.info, Node: Report intervals, Next: Date adjustment, Prev: Smart dates, Up: Time periods -14.3 Report intervals +13.3 Report intervals ===================== A report interval can be specified so that reports like register, @@ -5624,7 +5632,7 @@ described below.  File: hledger.info, Node: Date adjustment, Next: Period expressions, Prev: Report intervals, Up: Time periods -14.4 Date adjustment +13.4 Date adjustment ==================== When there is a report interval (other than daily), report start/end @@ -5648,7 +5656,7 @@ period headings.  File: hledger.info, Node: Period expressions, Prev: Date adjustment, Up: Time periods -14.5 Period expressions +13.5 Period expressions ======================= The '-p/--period' option specifies a period expression, which is a @@ -5708,7 +5716,7 @@ date:  File: hledger.info, Node: Period expressions with a report interval, Next: More complex report intervals, Up: Period expressions -14.5.1 Period expressions with a report interval +13.5.1 Period expressions with a report interval ------------------------------------------------ A period expression can also begin with a report interval, separated @@ -5721,7 +5729,7 @@ from the start/end dates (if any) by a space or the word 'in':  File: hledger.info, Node: More complex report intervals, Next: Multiple weekday intervals, Prev: Period expressions with a report interval, Up: Period expressions -14.5.2 More complex report intervals +13.5.2 More complex report intervals ------------------------------------ Some more complex intervals can be specified within period expressions, @@ -5785,7 +5793,7 @@ $ hledger register checking -p "every 3rd day of week"  File: hledger.info, Node: Multiple weekday intervals, Prev: More complex report intervals, Up: Period expressions -14.5.3 Multiple weekday intervals +13.5.3 Multiple weekday intervals --------------------------------- This special form is also supported: @@ -5813,7 +5821,7 @@ weekendday"'  File: hledger.info, Node: Depth, Next: Queries, Prev: Time periods, Up: Top -15 Depth +14 Depth ******** With the '--depth NUM' option (short form: '-NUM'), reports will show @@ -5825,7 +5833,7 @@ equivalent.  File: hledger.info, Node: Queries, Next: Pivoting, Prev: Depth, Up: Top -16 Queries +15 Queries ********** One of hledger's strengths is being able to quickly report on a precise @@ -5891,7 +5899,7 @@ a more complex query.  File: hledger.info, Node: Query types, Next: Combining query terms, Up: Queries -16.1 Query types +15.1 Query types ================ Here are the types of query term available. Remember these can also be @@ -5983,7 +5991,7 @@ hledger-web to show the transaction register for an account.)  File: hledger.info, Node: Combining query terms, Next: Queries and command options, Prev: Query types, Up: Queries -16.2 Combining query terms +15.2 Combining query terms ========================== When given multiple space-separated query terms, most commands select @@ -6034,7 +6042,7 @@ result sets, with unclear semantics for our reports.  File: hledger.info, Node: Queries and command options, Next: Queries and account aliases, Prev: Combining query terms, Up: Queries -16.3 Queries and command options +15.3 Queries and command options ================================ Some queries can also be expressed as command-line options: 'depth:2' is @@ -6045,7 +6053,7 @@ resulting query is their intersection.  File: hledger.info, Node: Queries and account aliases, Next: Queries and valuation, Prev: Queries and command options, Up: Queries -16.4 Queries and account aliases +15.4 Queries and account aliases ================================ When account names are rewritten with '--alias' or 'alias', 'acct:' will @@ -6054,7 +6062,7 @@ match either the old or the new account name.  File: hledger.info, Node: Queries and valuation, Prev: Queries and account aliases, Up: Queries -16.5 Queries and valuation +15.5 Queries and valuation ========================== When amounts are converted to other commodities in cost or value @@ -6064,7 +6072,7 @@ amount quantity, not the new ones. (Except in hledger 1.22, #1625.)  File: hledger.info, Node: Pivoting, Next: Generating data, Prev: Queries, Up: Top -17 Pivoting +16 Pivoting *********** Normally, hledger groups and sums amounts within each account. The @@ -6125,46 +6133,48 @@ $ hledger balance Income:Dues --pivot kind:member  File: hledger.info, Node: Generating data, Next: Forecasting, Prev: Pivoting, Up: Top -18 Generating data +17 Generating data ****************** -hledger has several features for generating data, such as: - - * Periodic transaction rules can generate single or repeating - transactions following a template. These are usually dated in the - future, eg to help with forecasting. They are activated by the - '--forecast' option. - - * The balance command's '--budget' option uses these same periodic - rules to generate goals for the budget report. - - * Auto posting rules can generate extra postings on certain matched - transactions. They are always applied to forecast transactions; - with the '--auto' flag they are applied to transactions recorded in - the journal as well. +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: + * Missing amounts or missing costs in transactions are inferred + automatically when possible. * The '--infer-equity' flag infers missing conversion equity postings - from @/@@ costs. And the inverse '--infer-costs' flag infers - missing @/@@ costs from conversion equity postings. + from @/@@ costs. + * The '--infer-costs' flag infers missing costs from conversion + equity postings. + * The '--infer-market-prices' flag infers 'P' price directives from + costs. + * The '--auto' flag adds extra postings to transactions matched by + auto posting rules. + * The '--forecast' option generates transactions from periodic + transaction rules. + * The 'balance --budget' report infers budget goals from periodic + transaction rules. + * Commands like 'close', 'rewrite', and 'hledger-interest' generate + transactions or postings. + * CSV data is converted to transactions by applying CSV conversion + rules.. etc. - Generated data of this kind is temporary, existing only at report -time. But you can see it in the output of 'hledger print', and you can -save that to your journal, in effect converting it from temporary -generated data to permanent recorded data. This could be useful as a -data entry aid. + 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 +sometimes be useful as a data entry aid. - If you are wondering what data is being generated and why, add the -'--verbose-tags' flag. In 'hledger print' output you will see extra -tags like 'generated-transaction', 'generated-posting', and 'modified' -on generated/modified data. Also, even without '--verbose-tags', -generated data always has equivalen hidden tags (with an underscore -prefix), so eg you could match generated transactions with -'tag:_generated-transaction'. + 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). +Similar 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'.  File: hledger.info, Node: Forecasting, Next: Budgeting, Prev: Generating data, Up: Top -19 Forecasting +18 Forecasting ************** Forecasting, or speculative future reporting, can be useful for @@ -6187,7 +6197,7 @@ when you want to see them.  File: hledger.info, Node: --forecast, Next: Inspecting forecast transactions, Up: Forecasting -19.1 -forecast +18.1 -forecast ============== There is another way: with the '--forecast' option, hledger can generate @@ -6211,7 +6221,7 @@ that the '=' is required.  File: hledger.info, Node: Inspecting forecast transactions, Next: Forecast reports, Prev: --forecast, Up: Forecasting -19.2 Inspecting forecast transactions +18.2 Inspecting forecast transactions ===================================== 'print' is the best command for inspecting and troubleshooting forecast @@ -6255,7 +6265,7 @@ reproducible.)  File: hledger.info, Node: Forecast reports, Next: Forecast tags, Prev: Inspecting forecast transactions, Up: Forecasting -19.3 Forecast reports +18.3 Forecast reports ===================== Forecast transactions affect all reports, as you would expect. Eg: @@ -6280,7 +6290,7 @@ Balance changes in 2023-05-01..2023-09-30:  File: hledger.info, Node: Forecast tags, Next: Forecast period in detail, Prev: Forecast reports, Up: Forecasting -19.4 Forecast tags +18.4 Forecast tags ================== Forecast transactions generated by -forecast have a hidden tag, @@ -6296,7 +6306,7 @@ rule was responsible.  File: hledger.info, Node: Forecast period in detail, Next: Forecast troubleshooting, Prev: Forecast tags, Up: Forecasting -19.5 Forecast period, in detail +18.5 Forecast period, in detail =============================== Forecast start/end dates are chosen so as to do something useful by @@ -6327,7 +6337,7 @@ default in almost all situations, while also being flexible. Here are  File: hledger.info, Node: Forecast troubleshooting, Prev: Forecast period in detail, Up: Forecasting -19.6 Forecast troubleshooting +18.6 Forecast troubleshooting ============================= When -forecast is not doing what you expect, one of these tips should @@ -6355,7 +6365,7 @@ help:  File: hledger.info, Node: Budgeting, Next: Amount formatting, Prev: Forecasting, Up: Top -20 Budgeting +19 Budgeting ************ With the balance command's '--budget' report, each periodic transaction @@ -6372,7 +6382,7 @@ bal -M --budget --forecast ...'  File: hledger.info, Node: Amount formatting, Next: Cost reporting, Prev: Budgeting, Up: Top -21 Amount formatting +20 Amount formatting ******************** * Menu: @@ -6385,7 +6395,7 @@ File: hledger.info, Node: Amount formatting, Next: Cost reporting, Prev: Budg  File: hledger.info, Node: Commodity display style, Next: Rounding, Up: Amount formatting -21.1 Commodity display style +20.1 Commodity display style ============================ For the amounts in each commodity, hledger chooses a consistent display @@ -6428,7 +6438,7 @@ as decimal mark, and two decimal digits).  File: hledger.info, Node: Rounding, Next: Trailing decimal marks, Prev: Commodity display style, Up: Amount formatting -21.2 Rounding +20.2 Rounding ============= Amounts are stored internally as decimal numbers with up to 255 decimal @@ -6442,7 +6452,7 @@ decimal digits appears as "0".  File: hledger.info, Node: Trailing decimal marks, Next: Amount parseability, Prev: Rounding, Up: Amount formatting -21.3 Trailing decimal marks +20.3 Trailing decimal marks =========================== If you're wondering why your 'print' report sometimes shows trailing @@ -6476,7 +6486,7 @@ $ hledger print -c '$1,000.00' --round=soft  File: hledger.info, Node: Amount parseability, Prev: Trailing decimal marks, Up: Amount formatting -21.4 Amount parseability +20.4 Amount parseability ======================== More generally, hledger output falls into three rough categories, which @@ -6515,7 +6525,7 @@ by humans)*  File: hledger.info, Node: Cost reporting, Next: Value reporting, Prev: Amount formatting, Up: Top -22 Cost reporting +21 Cost reporting ***************** In some transactions - for example a currency conversion, or a purchase @@ -6538,7 +6548,7 @@ rate" or "selling price" if helpful.  File: hledger.info, Node: Recording costs, Next: Reporting at cost, Up: Cost reporting -22.1 Recording costs +21.1 Recording costs ==================== We'll explore several ways of recording transactions involving costs. @@ -6592,7 +6602,7 @@ sure you have none of these by using '-s' (strict mode), or by running  File: hledger.info, Node: Reporting at cost, Next: Equity conversion postings, Prev: Recording costs, Up: Cost reporting -22.2 Reporting at cost +21.2 Reporting at cost ====================== Now when you add the '-B'/'--cost' flag to reports ("B" is from Ledger's @@ -6612,7 +6622,7 @@ they will be displayed "at cost" or "at sale price".  File: hledger.info, Node: Equity conversion postings, Next: Inferring equity conversion postings, Prev: Reporting at cost, Up: Cost reporting -22.3 Equity conversion postings +21.3 Equity conversion postings =============================== There is a problem with the entries above - they are not conventional @@ -6668,7 +6678,7 @@ $ hledger bal --infer-costs -B  File: hledger.info, Node: Inferring equity conversion postings, Next: Combining costs and equity conversion postings, Prev: Equity conversion postings, Up: Cost reporting -22.4 Inferring equity conversion postings +21.4 Inferring equity conversion postings ========================================= Can we go in the other direction ? Yes, if you have transactions @@ -6694,7 +6704,7 @@ account with the 'V'/'Conversion' account type.  File: hledger.info, Node: Combining costs and equity conversion postings, Next: Requirements for detecting equity conversion postings, Prev: Inferring equity conversion postings, Up: Cost reporting -22.5 Combining costs and equity conversion postings +21.5 Combining costs and equity conversion postings =================================================== Finally, you can use both the @/@@ cost notation and equity postings at @@ -6728,7 +6738,7 @@ $ hledger print -x --infer-costs --infer-equity  File: hledger.info, Node: Requirements for detecting equity conversion postings, Next: Infer cost and equity by default ?, Prev: Combining costs and equity conversion postings, Up: Cost reporting -22.6 Requirements for detecting equity conversion postings +21.6 Requirements for detecting equity conversion postings ========================================================== '--infer-costs' has certain requirements (unlike '--infer-equity', which @@ -6759,7 +6769,7 @@ fails, hledger raises an "unbalanced transaction" error.  File: hledger.info, Node: Infer cost and equity by default ?, Prev: Requirements for detecting equity conversion postings, Up: Cost reporting -22.7 Infer cost and equity by default ? +21.7 Infer cost and equity by default ? ======================================= Should '--infer-costs' and '--infer-equity' be enabled by default ? Try @@ -6772,7 +6782,7 @@ alias h="hledger --infer-equity --infer-costs"  File: hledger.info, Node: Value reporting, Next: PART 4 COMMANDS, Prev: Cost reporting, Up: Top -23 Value reporting +22 Value reporting ****************** Instead of reporting amounts in their original commodity, hledger can @@ -6798,7 +6808,7 @@ and '-X COMMODITY' options, and often one of these is all you need:  File: hledger.info, Node: -V Value, Next: -X Value in specified commodity, Up: Value reporting -23.1 -V: Value +22.1 -V: Value ============== The '-V/--market' flag converts amounts to market value in their default @@ -6808,7 +6818,7 @@ _valuation date(s)_, if any. More on these in a minute.  File: hledger.info, Node: -X Value in specified commodity, Next: Valuation date, Prev: -V Value, Up: Value reporting -23.2 -X: Value in specified commodity +22.2 -X: Value in specified commodity ===================================== The '-X/--exchange=COMM' option is like '-V', except you tell it which @@ -6818,7 +6828,7 @@ that.  File: hledger.info, Node: Valuation date, Next: Finding market price, Prev: -X Value in specified commodity, Up: Value reporting -23.3 Valuation date +22.3 Valuation date =================== Market prices can change from day to day. hledger will use the prices @@ -6841,7 +6851,7 @@ always resets it to "end".)  File: hledger.info, Node: Finding market price, Next: --infer-market-prices market prices from transactions, Prev: Valuation date, Up: Value reporting -23.4 Finding market price +22.4 Finding market price ========================= To convert a commodity A to its market value in another commodity B, @@ -6875,7 +6885,7 @@ converted.  File: hledger.info, Node: --infer-market-prices market prices from transactions, Next: Valuation commodity, Prev: Finding market price, Up: Value reporting -23.5 -infer-market-prices: market prices from transactions +22.5 -infer-market-prices: market prices from transactions ========================================================== Normally, market value in hledger is fully controlled by, and requires, @@ -6961,7 +6971,7 @@ P 2022-01-03 B A -1.0  File: hledger.info, Node: Valuation commodity, Next: --value Flexible valuation, Prev: --infer-market-prices market prices from transactions, Up: Value reporting -23.6 Valuation commodity +22.6 Valuation commodity ======================== *When you specify a valuation commodity ('-X COMM' or '--value @@ -7000,7 +7010,7 @@ converted.  File: hledger.info, Node: --value Flexible valuation, Next: Valuation examples, Prev: Valuation commodity, Up: Value reporting -23.7 -value: Flexible valuation +22.7 -value: Flexible valuation =============================== '-V' and '-X' are special cases of the more general '--value' option: @@ -7042,7 +7052,7 @@ this commodity, deducing market prices as described above.  File: hledger.info, Node: Valuation examples, Next: Interaction of valuation and queries, Prev: --value Flexible valuation, Up: Value reporting -23.8 Valuation examples +22.8 Valuation examples ======================= Here are some quick examples of '-V': @@ -7153,7 +7163,7 @@ $ hledger -f- print --value=2000-01-15  File: hledger.info, Node: Interaction of valuation and queries, Next: Effect of valuation on reports, Prev: Valuation examples, Up: Value reporting -23.9 Interaction of valuation and queries +22.9 Interaction of valuation and queries ========================================= When matching postings based on queries in the presence of valuation, @@ -7174,7 +7184,7 @@ the following happens:  File: hledger.info, Node: Effect of valuation on reports, Prev: Interaction of valuation and queries, Up: Value reporting -23.10 Effect of valuation on reports +22.10 Effect of valuation on reports ==================================== Here is a reference for how valuation is supposed to affect each part of @@ -7322,7 +7332,7 @@ a zero starting balance.  File: hledger.info, Node: PART 4 COMMANDS, Next: Help commands, Prev: Value reporting, Up: Top -24 PART 4: COMMANDS +23 PART 4: COMMANDS ******************* Here are the standard commands, which you can list by running 'hledger'. @@ -7393,7 +7403,7 @@ If you have installed more add-on commands, they also will be listed.  File: hledger.info, Node: Help commands, Next: User interface commands, Prev: PART 4 COMMANDS, Up: Top -25 Help commands +24 Help commands **************** * Menu: @@ -7404,7 +7414,7 @@ File: hledger.info, Node: Help commands, Next: User interface commands, Prev:  File: hledger.info, Node: help, Next: demo, Up: Help commands -25.1 help +24.1 help ========= Show the hledger user manual with 'info', 'man', or a pager. With a @@ -7440,7 +7450,7 @@ $ hledger help 'time periods' -m # use man, even if info is installed  File: hledger.info, Node: demo, Prev: help, Up: Help commands -25.2 demo +24.2 demo ========= Play demos of hledger usage in the terminal, if asciinema is installed. @@ -7469,7 +7479,7 @@ $ hledger demo install -s4 # play the "install" demo at 4x speed  File: hledger.info, Node: User interface commands, Next: Data entry commands, Prev: Help commands, Up: Top -26 User interface commands +25 User interface commands ************************** * Menu: @@ -7480,7 +7490,7 @@ File: hledger.info, Node: User interface commands, Next: Data entry commands,  File: hledger.info, Node: ui, Next: web, Up: User interface commands -26.1 ui +25.1 ui ======= Runs hledger-ui (if installed). @@ -7488,7 +7498,7 @@ Runs hledger-ui (if installed).  File: hledger.info, Node: web, Prev: ui, Up: User interface commands -26.2 web +25.2 web ======== Runs hledger-web (if installed). @@ -7496,7 +7506,7 @@ Runs hledger-web (if installed).  File: hledger.info, Node: Data entry commands, Next: Basic report commands, Prev: User interface commands, Up: Top -27 Data entry commands +26 Data entry commands ********************** * Menu: @@ -7507,7 +7517,7 @@ File: hledger.info, Node: Data entry commands, Next: Basic report commands, P  File: hledger.info, Node: add, Next: import, Up: Data entry commands -27.1 add +26.1 add ======== Record new transactions with interactive prompting in the console. @@ -7571,7 +7581,7 @@ or press control-d or control-c to exit.  File: hledger.info, Node: import, Prev: add, Up: Data entry commands -27.2 import +26.2 import =========== Import new transactions from one or more data files to the main journal. @@ -7607,7 +7617,7 @@ target file (main journal) should be in journal format.  File: hledger.info, Node: Date skipping, Next: Import testing, Up: import -27.2.1 Date skipping +26.2.1 Date skipping -------------------- 'import' tries to import only the transactions which are new since the @@ -7676,7 +7686,7 @@ but it is less often used.  File: hledger.info, Node: Import testing, Next: Importing balance assignments, Prev: Date skipping, Up: import -27.2.2 Import testing +26.2.2 Import testing --------------------- With '--dry-run', the transactions that will be imported are printed to @@ -7701,7 +7711,7 @@ import.  File: hledger.info, Node: Importing balance assignments, Next: Import and commodity styles, Prev: Import testing, Up: import -27.2.3 Importing balance assignments +26.2.3 Importing balance assignments ------------------------------------ Entries added by import will have their posting amounts made explicit @@ -7720,7 +7730,7 @@ please test it and send a pull request.)  File: hledger.info, Node: Import and commodity styles, Prev: Importing balance assignments, Up: import -27.2.4 Import and commodity styles +26.2.4 Import and commodity styles ---------------------------------- Amounts in entries added by import will be formatted according to the @@ -7732,7 +7742,7 @@ directives or inferred from the journal's amounts.  File: hledger.info, Node: Basic report commands, Next: Standard report commands, Prev: Data entry commands, Up: Top -28 Basic report commands +27 Basic report commands ************************ * Menu: @@ -7751,7 +7761,7 @@ File: hledger.info, Node: Basic report commands, Next: Standard report command  File: hledger.info, Node: accounts, Next: codes, Up: Basic report commands -28.1 accounts +27.1 accounts ============= List account names. @@ -7808,7 +7818,7 @@ $ hledger check accounts  File: hledger.info, Node: codes, Next: commodities, Prev: accounts, Up: Basic report commands -28.2 codes +27.2 codes ========== List the codes seen in transactions, in the order parsed. @@ -7856,7 +7866,7 @@ $ hledger codes -E  File: hledger.info, Node: commodities, Next: descriptions, Prev: codes, Up: Basic report commands -28.3 commodities +27.3 commodities ================ List all commodity/currency symbols used or declared in the journal. @@ -7864,7 +7874,7 @@ List all commodity/currency symbols used or declared in the journal.  File: hledger.info, Node: descriptions, Next: files, Prev: commodities, Up: Basic report commands -28.4 descriptions +27.4 descriptions ================= List the unique descriptions that appear in transactions. @@ -7883,7 +7893,7 @@ Person A  File: hledger.info, Node: files, Next: notes, Prev: descriptions, Up: Basic report commands -28.5 files +27.5 files ========== List all files included in the journal. With a REGEX argument, only @@ -7892,7 +7902,7 @@ file names matching the regular expression (case sensitive) are shown.  File: hledger.info, Node: notes, Next: payees, Prev: files, Up: Basic report commands -28.6 notes +27.6 notes ========== List the unique notes that appear in transactions. @@ -7911,7 +7921,7 @@ Snacks  File: hledger.info, Node: payees, Next: prices, Prev: notes, Up: Basic report commands -28.7 payees +27.7 payees =========== List the unique payee/payer names that appear in transactions. @@ -7936,7 +7946,7 @@ Person A  File: hledger.info, Node: prices, Next: stats, Prev: payees, Up: Basic report commands -28.8 prices +27.8 prices =========== Print the market prices declared with P directives. With @@ -7957,7 +7967,7 @@ running the value report with -debug=2.  File: hledger.info, Node: stats, Next: tags, Prev: prices, Up: Basic report commands -28.9 stats +27.9 stats ========== Show journal and performance statistics. @@ -8005,7 +8015,7 @@ Runtime stats : 0.12 s elapsed, 8266 txns/s, 4 MB live, 16 MB alloc  File: hledger.info, Node: tags, Prev: stats, Up: Basic report commands -28.10 tags +27.10 tags ========== List the tags used in the journal, or their values. @@ -8035,7 +8045,7 @@ transactions also acquire tags from their postings.  File: hledger.info, Node: Standard report commands, Next: Advanced report commands, Prev: Basic report commands, Up: Top -29 Standard report commands +28 Standard report commands *************************** * Menu: @@ -8051,7 +8061,7 @@ File: hledger.info, Node: Standard report commands, Next: Advanced report comm  File: hledger.info, Node: print, Next: aregister, Up: Standard report commands -29.1 print +28.1 print ========== Show full journal entries, representing transactions. @@ -8091,7 +8101,7 @@ $ hledger print -f examples/sample.journal date:200806  File: hledger.info, Node: print explicitness, Next: print amount style, Up: print -29.1.1 print explicitness +28.1.1 print explicitness ------------------------- Normally, whether posting amounts are implicit or explicit is preserved. @@ -8112,7 +8122,7 @@ single-commodity postings, keeping the output parseable.  File: hledger.info, Node: print amount style, Next: print parseability, Prev: print explicitness, Up: print -29.1.2 print amount style +28.1.2 print amount style ------------------------- Amounts are shown right-aligned within each transaction (but not aligned @@ -8143,7 +8153,7 @@ when needed.  File: hledger.info, Node: print parseability, Next: print other features, Prev: print amount style, Up: print -29.1.3 print parseability +28.1.3 print parseability ------------------------- print's output is usually a valid hledger journal, and you can process @@ -8166,7 +8176,7 @@ unparseable:  File: hledger.info, Node: print other features, Next: print output format, Prev: print parseability, Up: print -29.1.4 print, other features +28.1.4 print, other features ---------------------------- With '-B'/'--cost', amounts with costs are shown converted to cost. @@ -8183,7 +8193,7 @@ will be shown and the program exit code will be non-zero.  File: hledger.info, Node: print output format, Prev: print other features, Up: print -29.1.5 print output format +28.1.5 print output format -------------------------- This command also supports the output destination and output format @@ -8248,7 +8258,7 @@ $ hledger print -Ocsv  File: hledger.info, Node: aregister, Next: register, Prev: print, Up: Standard report commands -29.2 aregister +28.2 aregister ============== (areg) @@ -8324,7 +8334,7 @@ in 1.32_), and 'json'.  File: hledger.info, Node: aregister and posting dates, Up: aregister -29.2.1 aregister and posting dates +28.2.1 aregister and posting dates ---------------------------------- aregister always shows one line (and date and amount) per transaction. @@ -8344,7 +8354,7 @@ inaccurate running balance.  File: hledger.info, Node: register, Next: balancesheet, Prev: aregister, Up: Standard report commands -29.3 register +28.3 register ============= (reg) @@ -8454,7 +8464,7 @@ no posting will be shown and the program exit code will be non-zero.  File: hledger.info, Node: Custom register output, Up: register -29.3.1 Custom register output +28.3.1 Custom register output ----------------------------- register uses the full terminal width by default, except on windows. @@ -8486,7 +8496,7 @@ options The output formats supported are 'txt', 'csv', 'tsv' (_Added in  File: hledger.info, Node: balancesheet, Next: balancesheetequity, Prev: register, Up: Standard report commands -29.4 balancesheet +28.4 balancesheet ================= (bs) @@ -8539,7 +8549,7 @@ options The output formats supported are 'txt', 'csv', 'tsv' (_Added in  File: hledger.info, Node: balancesheetequity, Next: cashflow, Prev: balancesheet, Up: Standard report commands -29.5 balancesheetequity +28.5 balancesheetequity ======================= (bse) @@ -8599,7 +8609,7 @@ and 'json'.  File: hledger.info, Node: cashflow, Next: incomestatement, Prev: balancesheetequity, Up: Standard report commands -29.6 cashflow +28.6 cashflow ============= (cf) @@ -8650,7 +8660,7 @@ options The output formats supported are 'txt', 'csv', 'tsv' (_Added in  File: hledger.info, Node: incomestatement, Prev: cashflow, Up: Standard report commands -29.7 incomestatement +28.7 incomestatement ==================== (is) @@ -8703,7 +8713,7 @@ options The output formats supported are 'txt', 'csv', 'tsv' (_Added in  File: hledger.info, Node: Advanced report commands, Next: Chart commands, Prev: Standard report commands, Up: Top -30 Advanced report commands +29 Advanced report commands *************************** * Menu: @@ -8714,7 +8724,7 @@ File: hledger.info, Node: Advanced report commands, Next: Chart commands, Pre  File: hledger.info, Node: balance, Next: roi, Up: Advanced report commands -30.1 balance +29.1 balance ============ (bal) @@ -8755,7 +8765,7 @@ more control, then use 'balance'.  File: hledger.info, Node: balance features, Next: Simple balance report, Up: balance -30.1.1 balance features +29.1.1 balance features ----------------------- Here's a quick overview of the 'balance' command's features, followed by @@ -8816,7 +8826,7 @@ colour-supporting terminal, negative amounts are shown in red.  File: hledger.info, Node: Simple balance report, Next: Balance report line format, Prev: balance features, Up: balance -30.1.2 Simple balance report +29.1.2 Simple balance report ---------------------------- With no arguments, 'balance' shows a list of all accounts and their @@ -8865,7 +8875,7 @@ $ hledger -f examples/sample.journal bal -E  File: hledger.info, Node: Balance report line format, Next: Filtered balance report, Prev: Simple balance report, Up: balance -30.1.3 Balance report line format +29.1.3 Balance report line format --------------------------------- For single-period balance reports displayed in the terminal (only), you @@ -8928,7 +8938,7 @@ may be needed to get pleasing results.  File: hledger.info, Node: Filtered balance report, Next: List or tree mode, Prev: Balance report line format, Up: balance -30.1.4 Filtered balance report +29.1.4 Filtered balance report ------------------------------ You can show fewer accounts, a different time period, totals from @@ -8943,7 +8953,7 @@ $ hledger -f examples/sample.journal bal --cleared assets date:200806  File: hledger.info, Node: List or tree mode, Next: Depth limiting, Prev: Filtered balance report, Up: balance -30.1.5 List or tree mode +29.1.5 List or tree mode ------------------------ By default, or with '-l/--flat', accounts are shown as a flat list with @@ -8986,7 +8996,7 @@ $ hledger -f examples/sample.journal balance  File: hledger.info, Node: Depth limiting, Next: Dropping top-level accounts, Prev: List or tree mode, Up: balance -30.1.6 Depth limiting +29.1.6 Depth limiting --------------------- With a 'depth:NUM' query, or '--depth NUM' option, or just '-NUM' (eg: @@ -9008,7 +9018,7 @@ $ hledger -f examples/sample.journal balance -1  File: hledger.info, Node: Dropping top-level accounts, Next: Showing declared accounts, Prev: Depth limiting, Up: balance -30.1.7 Dropping top-level accounts +29.1.7 Dropping top-level accounts ---------------------------------- You can also hide one or more top-level account name parts, using @@ -9024,7 +9034,7 @@ $ hledger -f examples/sample.journal bal expenses --drop 1  File: hledger.info, Node: Showing declared accounts, Next: Sorting by amount, Prev: Dropping top-level accounts, Up: balance -30.1.8 Showing declared accounts +29.1.8 Showing declared accounts -------------------------------- With '--declared', accounts which have been declared with an account @@ -9042,7 +9052,7 @@ accounts yet.  File: hledger.info, Node: Sorting by amount, Next: Percentages, Prev: Showing declared accounts, Up: balance -30.1.9 Sorting by amount +29.1.9 Sorting by amount ------------------------ With '-S/--sort-amount', accounts with the largest (most positive) @@ -9060,7 +9070,7 @@ which flip the sign automatically. Eg: 'hledger incomestatement -MAS').  File: hledger.info, Node: Percentages, Next: Multi-period balance report, Prev: Sorting by amount, Up: balance -30.1.10 Percentages +29.1.10 Percentages ------------------- With '-%/--percent', balance reports show each account's value expressed @@ -9083,7 +9093,7 @@ $ hledger bal -% cur:€  File: hledger.info, Node: Multi-period balance report, Next: Balance change end balance, Prev: Percentages, Up: balance -30.1.11 Multi-period balance report +29.1.11 Multi-period balance report ----------------------------------- With a report interval (set by the '-D/--daily', '-W/--weekly', @@ -9143,7 +9153,7 @@ viewing in the terminal. Here are some ways to handle that:  File: hledger.info, Node: Balance change end balance, Next: Balance report types, Prev: Multi-period balance report, Up: balance -30.1.12 Balance change, end balance +29.1.12 Balance change, end balance ----------------------------------- It's important to be clear on the meaning of the numbers shown in @@ -9180,7 +9190,7 @@ historical end balances:  File: hledger.info, Node: Balance report types, Next: Budget report, Prev: Balance change end balance, Up: balance -30.1.13 Balance report types +29.1.13 Balance report types ---------------------------- The balance command is quite flexible; here is the full detail on how to @@ -9203,7 +9213,7 @@ experimentation to get familiar with all the report modes.  File: hledger.info, Node: Calculation type, Next: Accumulation type, Up: Balance report types -30.1.13.1 Calculation type +29.1.13.1 Calculation type .......................... The basic calculation to perform for each table cell. It is one of: @@ -9221,7 +9231,7 @@ The basic calculation to perform for each table cell. It is one of:  File: hledger.info, Node: Accumulation type, Next: Valuation type, Prev: Calculation type, Up: Balance report types -30.1.13.2 Accumulation type +29.1.13.2 Accumulation type ........................... How amounts should accumulate across a report's subperiods/columns. @@ -9247,7 +9257,7 @@ each cell's calculation. It is one of:  File: hledger.info, Node: Valuation type, Next: Combining balance report types, Prev: Accumulation type, Up: Balance report types -30.1.13.3 Valuation type +29.1.13.3 Valuation type ........................ Which kind of value or cost conversion should be applied, if any, before @@ -9278,7 +9288,7 @@ displaying the report. It is one of:  File: hledger.info, Node: Combining balance report types, Prev: Valuation type, Up: Balance report types -30.1.13.4 Combining balance report types +29.1.13.4 Combining balance report types ........................................ Most combinations of these options should produce reasonable reports, @@ -9317,7 +9327,7 @@ Accumulation:v YYYY-MM-DD  File: hledger.info, Node: Budget report, Next: Balance report layout, Prev: Balance report types, Up: balance -30.1.14 Budget report +29.1.14 Budget report --------------------- The '--budget' report type is like a regular balance report, but with @@ -9388,7 +9398,7 @@ https://plaintextaccounting.org/Budgeting has more on this topic.  File: hledger.info, Node: Using the budget report, Next: Budget date surprises, Up: Budget report -30.1.14.1 Using the budget report +29.1.14.1 Using the budget report ................................. Historically this report has been confusing and fragile. hledger's @@ -9444,7 +9454,7 @@ troubleshooting.  File: hledger.info, Node: Budget date surprises, Next: Selecting budget goals, Prev: Using the budget report, Up: Budget report -30.1.14.2 Budget date surprises +29.1.14.2 Budget date surprises ............................... With small data, or when starting out, some of the generated budget goal @@ -9483,7 +9493,7 @@ the trick.  File: hledger.info, Node: Selecting budget goals, Next: Budgeting vs forecasting, Prev: Budget date surprises, Up: Budget report -30.1.14.3 Selecting budget goals +29.1.14.3 Selecting budget goals ................................ By default, the budget report uses all available periodic transaction @@ -9503,7 +9513,7 @@ defined in your journal.  File: hledger.info, Node: Budgeting vs forecasting, Prev: Selecting budget goals, Up: Budget report -30.1.14.4 Budgeting vs forecasting +29.1.14.4 Budgeting vs forecasting .................................. '--forecast' and '--budget' both use the periodic transaction rules in @@ -9535,7 +9545,7 @@ uses all periodic rules uses all periodic rules; or  File: hledger.info, Node: Balance report layout, Next: Some useful balance reports, Prev: Budget report, Up: balance -30.1.15 Balance report layout +29.1.15 Balance report layout ----------------------------- The '--layout' option affects how balance reports show multi-commodity @@ -9573,7 +9583,7 @@ tidy Y  File: hledger.info, Node: Wide layout, Next: Tall layout, Up: Balance report layout -30.1.15.1 Wide layout +29.1.15.1 Wide layout ..................... With many commodities, reports can be very wide: @@ -9601,7 +9611,7 @@ Balance changes in 2012-01-01..2014-12-31:  File: hledger.info, Node: Tall layout, Next: Bare layout, Prev: Wide layout, Up: Balance report layout -30.1.15.2 Tall layout +29.1.15.2 Tall layout ..................... Each commodity gets a new line (may be different in each column), and @@ -9627,7 +9637,7 @@ Balance changes in 2012-01-01..2014-12-31:  File: hledger.info, Node: Bare layout, Next: Tidy layout, Prev: Tall layout, Up: Balance report layout -30.1.15.3 Bare layout +29.1.15.3 Bare layout ..................... Commodity symbols are kept in one column, each commodity has its own @@ -9674,7 +9684,7 @@ commodity-less, usually). This can break 'hledger-bar' confusingly  File: hledger.info, Node: Tidy layout, Prev: Bare layout, Up: Balance report layout -30.1.15.4 Tidy layout +29.1.15.4 Tidy layout ..................... This produces normalised "tidy data" (see @@ -9704,7 +9714,7 @@ $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -Y -O csv --layo  File: hledger.info, Node: Some useful balance reports, Prev: Balance report layout, Up: balance -30.1.16 Some useful balance reports +29.1.16 Some useful balance reports ----------------------------------- Some frequently used 'balance' options/reports are: @@ -9744,7 +9754,7 @@ Some frequently used 'balance' options/reports are:  File: hledger.info, Node: roi, Prev: balance, Up: Advanced report commands -30.2 roi +29.2 roi ======== Shows the time-weighted (TWR) and money-weighted (IRR) rate of return on @@ -9794,7 +9804,7 @@ annual rate.  File: hledger.info, Node: Spaces and special characters in --inv and --pnl, Next: Semantics of --inv and --pnl, Up: roi -30.2.1 Spaces and special characters in '--inv' and +29.2.1 Spaces and special characters in '--inv' and --------------------------------------------------- '--pnl' Note that '--inv' and '--pnl''s argument is a query, and queries @@ -9813,7 +9823,7 @@ $ hledger roi --inv="'Assets:Test 1'" --pnl="'Equity:Unrealized Profit and Loss'  File: hledger.info, Node: Semantics of --inv and --pnl, Next: IRR and TWR explained, Prev: Spaces and special characters in --inv and --pnl, Up: roi -30.2.2 Semantics of '--inv' and '--pnl' +29.2.2 Semantics of '--inv' and '--pnl' --------------------------------------- Query supplied to '--inv' has to match all transactions that are related @@ -9867,7 +9877,7 @@ postings in the example below would be classifed as:  File: hledger.info, Node: IRR and TWR explained, Prev: Semantics of --inv and --pnl, Up: roi -30.2.3 IRR and TWR explained +29.2.3 IRR and TWR explained ---------------------------- "ROI" stands for "return on investment". Traditionally this was @@ -9936,7 +9946,7 @@ cash in-flows and out-flows.  File: hledger.info, Node: Chart commands, Next: Data generation commands, Prev: Advanced report commands, Up: Top -31 Chart commands +30 Chart commands ***************** * Menu: @@ -9946,7 +9956,7 @@ File: hledger.info, Node: Chart commands, Next: Data generation commands, Pre  File: hledger.info, Node: activity, Up: Chart commands -31.1 activity +30.1 activity ============= Show an ascii barchart of posting counts per interval. @@ -9966,7 +9976,7 @@ $ hledger activity --quarterly  File: hledger.info, Node: Data generation commands, Next: Maintenance commands, Prev: Chart commands, Up: Top -32 Data generation commands +31 Data generation commands *************************** * Menu: @@ -9977,7 +9987,7 @@ File: hledger.info, Node: Data generation commands, Next: Maintenance commands  File: hledger.info, Node: close, Next: rewrite, Up: Data generation commands -32.1 close +31.1 close ========== (equity) @@ -10006,7 +10016,7 @@ are happy with how they look.  File: hledger.info, Node: close --migrate, Next: close --close, Up: close -32.1.1 close -migrate +31.1.1 close -migrate --------------------- This is the most common mode. It prints a "closing balances" @@ -10041,7 +10051,7 @@ main file name. The other modes behave similarly.  File: hledger.info, Node: close --close, Next: close --open, Prev: close --migrate, Up: close -32.1.2 close -close +31.1.2 close -close ------------------- This prints just the closing balances transaction of '--migrate'. It is @@ -10052,7 +10062,7 @@ accounts to a different account.  File: hledger.info, Node: close --open, Next: close --assert, Prev: close --close, Up: close -32.1.3 close -open +31.1.3 close -open ------------------ This prints just the opening balances transaction of '--migrate'. It is @@ -10061,7 +10071,7 @@ similar to Ledger's equity command.  File: hledger.info, Node: close --assert, Next: close --assign, Prev: close --open, Up: close -32.1.4 close -assert +31.1.4 close -assert -------------------- This prints a "closing balances" transaction (with 'balances:' tag), @@ -10072,7 +10082,7 @@ changes.  File: hledger.info, Node: close --assign, Next: close --retain, Prev: close --assert, Up: close -32.1.5 close -assign +31.1.5 close -assign -------------------- This prints an "opening balances" transaction that restores the account @@ -10089,7 +10099,7 @@ files, for now.  File: hledger.info, Node: close --retain, Next: close customisation, Prev: close --assign, Up: close -32.1.6 close -retain +31.1.6 close -retain -------------------- This is like '--close' with different defaults: it prints a "retain @@ -10109,7 +10119,7 @@ demonstrating that the accounting equation (A-L=E) is satisfied.  File: hledger.info, Node: close customisation, Next: close and balance assertions, Prev: close --retain, Up: close -32.1.7 close customisation +31.1.7 close customisation -------------------------- In all modes, the following things can be overridden: @@ -10146,7 +10156,7 @@ hledger. (To move or dispose of lots, see the more capable  File: hledger.info, Node: close and balance assertions, Next: close examples, Prev: close customisation, Up: close -32.1.8 close and balance assertions +31.1.8 close and balance assertions ----------------------------------- 'close' adds balance assertions verifying that the accounts have been @@ -10188,7 +10198,7 @@ transactions:  File: hledger.info, Node: close examples, Prev: close and balance assertions, Up: close -32.1.9 close examples +31.1.9 close examples --------------------- * Menu: @@ -10200,7 +10210,7 @@ File: hledger.info, Node: close examples, Prev: close and balance assertions,  File: hledger.info, Node: Retain earnings, Next: Migrate balances to a new file, Up: close examples -32.1.9.1 Retain earnings +31.1.9.1 Retain earnings ........................ Record 2022's revenues/expenses as retained earnings on 2022-12-31, @@ -10216,7 +10226,7 @@ $ hledger -f 2022.journal is not:desc:'retain earnings'  File: hledger.info, Node: Migrate balances to a new file, Next: More detailed close examples, Prev: Retain earnings, Up: close examples -32.1.9.2 Migrate balances to a new file +31.1.9.2 Migrate balances to a new file ....................................... Close assets/liabilities on 2022-12-31 and re-open them on 2023-01-01: @@ -10245,7 +10255,7 @@ $ hledger bs -Y -f 2023.j # unclosed file, no query needed  File: hledger.info, Node: More detailed close examples, Prev: Migrate balances to a new file, Up: close examples -32.1.9.3 More detailed close examples +31.1.9.3 More detailed close examples ..................................... See examples/multi-year. @@ -10253,7 +10263,7 @@ See examples/multi-year.  File: hledger.info, Node: rewrite, Prev: close, Up: Data generation commands -32.2 rewrite +31.2 rewrite ============ Print all transactions, rewriting the postings of matched transactions. @@ -10306,7 +10316,7 @@ commodity.  File: hledger.info, Node: Re-write rules in a file, Next: Diff output format, Up: rewrite -32.2.1 Re-write rules in a file +31.2.1 Re-write rules in a file ------------------------------- During the run this tool will execute so called "Automated Transactions" @@ -10344,7 +10354,7 @@ postings.  File: hledger.info, Node: Diff output format, Next: rewrite vs print --auto, Prev: Re-write rules in a file, Up: rewrite -32.2.2 Diff output format +31.2.2 Diff output format ------------------------- To use this tool for batch modification of your journal files you may @@ -10385,7 +10395,7 @@ output from 'hledger print'.  File: hledger.info, Node: rewrite vs print --auto, Prev: Diff output format, Up: rewrite -32.2.3 rewrite vs. print -auto +31.2.3 rewrite vs. print -auto ------------------------------ This command predates print -auto, and currently does much the same @@ -10405,7 +10415,7 @@ thing, but with these differences:  File: hledger.info, Node: Maintenance commands, Next: PART 5 COMMON TASKS, Prev: Data generation commands, Up: Top -33 Maintenance commands +32 Maintenance commands *********************** * Menu: @@ -10417,7 +10427,7 @@ File: hledger.info, Node: Maintenance commands, Next: PART 5 COMMON TASKS, Pr  File: hledger.info, Node: check, Next: diff, Up: Maintenance commands -33.1 check +32.1 check ========== Check for various kinds of errors in your data. @@ -10449,7 +10459,7 @@ is reported).  File: hledger.info, Node: Basic checks, Next: Strict checks, Up: check -33.1.1 Basic checks +32.1.1 Basic checks ------------------- These important checks are performed by default, by almost all hledger @@ -10473,7 +10483,7 @@ commands:  File: hledger.info, Node: Strict checks, Next: Other checks, Prev: Basic checks, Up: check -33.1.2 Strict checks +32.1.2 Strict checks -------------------- These additional checks are performed by any command when the @@ -10495,7 +10505,7 @@ typos:  File: hledger.info, Node: Other checks, Next: Custom checks, Prev: Strict checks, Up: check -33.1.3 Other checks +32.1.3 Other checks ------------------- These other checks are not wanted by everyone, but can be run using the @@ -10534,7 +10544,7 @@ These other checks are not wanted by everyone, but can be run using the  File: hledger.info, Node: Custom checks, Prev: Other checks, Up: check -33.1.4 Custom checks +32.1.4 Custom checks -------------------- You can build your own custom checks with add-on command scripts. See @@ -10549,7 +10559,7 @@ also Cookbook > Scripting. Here are some examples from hledger/bin/:  File: hledger.info, Node: diff, Next: test, Prev: check, Up: Maintenance commands -33.2 diff +32.2 diff ========= Compares a particular account's transactions in two input files. It @@ -10583,7 +10593,7 @@ These transactions are in the second file only:  File: hledger.info, Node: test, Prev: diff, Up: Maintenance commands -33.3 test +32.3 test ========= Run built-in unit tests. @@ -10609,7 +10619,7 @@ $ hledger test -- -pData.Amount --color=never  File: hledger.info, Node: PART 5 COMMON TASKS, Next: Getting help, Prev: Maintenance commands, Up: Top -34 PART 5: COMMON TASKS +33 PART 5: COMMON TASKS *********************** Here are some quick examples of how to do some basic tasks with hledger. @@ -10617,7 +10627,7 @@ 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 -35 Getting help +34 Getting help *************** Here's how to list commands and view options and command docs: @@ -10640,7 +10650,7 @@ 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 -36 Constructing command lines +35 Constructing command lines ***************************** hledger has a flexible command line interface. We strive to keep it @@ -10660,7 +10670,7 @@ described in OPTIONS, here are some tips that might help:  File: hledger.info, Node: Starting a journal file, Next: Setting LEDGER_FILE, Prev: Constructing command lines, Up: Top -37 Starting a journal file +36 Starting a journal file ************************** hledger looks for your accounting data in a journal file, @@ -10699,7 +10709,7 @@ Market prices : 0 ()  File: hledger.info, Node: Setting LEDGER_FILE, Next: Setting opening balances, Prev: Starting a journal file, Up: Top -38 Setting LEDGER_FILE +37 Setting LEDGER_FILE ********************** How to set 'LEDGER_FILE' permanently depends on your setup: @@ -10735,7 +10745,7 @@ persists across a reboot, and if you need to be an Administrator):  File: hledger.info, Node: Setting opening balances, Next: Recording transactions, Prev: Setting LEDGER_FILE, Up: Top -39 Setting opening balances +38 Setting opening balances *************************** Pick a starting date for which you can look up the balances of some @@ -10818,7 +10828,7 @@ $ git commit -m 'initial balances' 2023.journal  File: hledger.info, Node: Recording transactions, Next: Reconciling, Prev: Setting opening balances, Up: Top -40 Recording transactions +39 Recording transactions ************************* As you spend or receive money, you can record these transactions using @@ -10844,7 +10854,7 @@ and hledger.org for more ideas:  File: hledger.info, Node: Reconciling, Next: Reporting, Prev: Recording transactions, Up: Top -41 Reconciling +40 Reconciling ************** Periodically you should reconcile - compare your hledger-reported @@ -10899,7 +10909,7 @@ $ git commit -m 'txns' 2023.journal  File: hledger.info, Node: Reporting, Next: Migrating to a new file, Prev: Reconciling, Up: Top -42 Reporting +41 Reporting ************ Here are some basic reports. @@ -11047,7 +11057,7 @@ $ hledger activity -W  File: hledger.info, Node: Migrating to a new file, Next: BUGS, Prev: Reporting, Up: Top -43 Migrating to a new file +42 Migrating to a new file ************************** At the end of the year, you may want to continue your journal in a new @@ -11060,7 +11070,7 @@ close command.  File: hledger.info, Node: BUGS, Prev: Migrating to a new file, Up: Top -44 BUGS +43 BUGS ******* We welcome bug reports in the hledger issue tracker (shortcut: @@ -11092,7 +11102,7 @@ Ledger.  File: hledger.info, Node: Troubleshooting, Up: BUGS -44.1 Troubleshooting +43.1 Troubleshooting ==================== Here are some common issues you might encounter when you run hledger, @@ -11149,686 +11159,682 @@ See hledger and Ledger for full details.  Tag Table: Node: Top208 -Node: PART 1 USER INTERFACE4269 -Ref: #part-1-user-interface4408 -Node: Input4408 -Ref: #input4518 -Node: Text encoding5485 -Ref: #text-encoding5599 -Node: Data formats6165 -Ref: #data-formats6300 -Node: Standard input7889 -Ref: #standard-input8029 -Node: Multiple files8256 -Ref: #multiple-files8395 -Node: Strict mode8993 -Ref: #strict-mode9103 -Node: Commands9827 -Ref: #commands9929 -Node: Add-on commands10996 -Ref: #add-on-commands11098 -Node: Options12214 -Ref: #options12326 -Node: Command line tips17718 -Ref: #command-line-tips17848 -Node: Option repetition18107 -Ref: #option-repetition18251 -Node: Special characters18355 -Ref: #special-characters18528 -Node: Single escaping shell metacharacters18691 -Ref: #single-escaping-shell-metacharacters18932 -Node: Double escaping regular expression metacharacters19535 -Ref: #double-escaping-regular-expression-metacharacters19846 -Node: Triple escaping for add-on commands20372 -Ref: #triple-escaping-for-add-on-commands20632 -Node: Less escaping21276 -Ref: #less-escaping21430 -Node: Unicode characters21754 -Ref: #unicode-characters21929 -Node: Regular expressions23428 -Ref: #regular-expressions23601 -Node: hledger's regular expressions26697 -Ref: #hledgers-regular-expressions26856 -Node: Argument files28242 -Ref: #argument-files28378 -Node: Output28875 -Ref: #output28987 -Node: Output destination29114 -Ref: #output-destination29245 -Node: Output format29670 -Ref: #output-format29816 -Node: CSV output31413 -Ref: #csv-output31529 -Node: HTML output31632 -Ref: #html-output31770 -Node: JSON output31864 -Ref: #json-output32002 -Node: SQL output32924 -Ref: #sql-output33040 -Node: Commodity styles33775 -Ref: #commodity-styles33915 -Node: Colour34653 -Ref: #colour34771 -Node: Box-drawing35175 -Ref: #box-drawing35293 -Node: Paging35583 -Ref: #paging35697 -Node: Debug output36650 -Ref: #debug-output36756 -Node: Environment37419 -Ref: #environment37543 -Node: PART 2 DATA FORMATS38087 -Ref: #part-2-data-formats38230 -Node: Journal38230 -Ref: #journal38339 -Node: Journal cheatsheet40707 -Ref: #journal-cheatsheet40834 -Node: Comments46921 -Ref: #comments47049 -Node: Transactions47865 -Ref: #transactions47988 -Node: Dates49002 -Ref: #dates49109 -Node: Simple dates49154 -Ref: #simple-dates49270 -Node: Posting dates49770 -Ref: #posting-dates49888 -Node: Status50857 -Ref: #status50958 -Node: Code52623 -Ref: #code52726 -Node: Description52958 -Ref: #description53089 -Node: Payee and note53645 -Ref: #payee-and-note53751 -Node: Transaction comments54736 -Ref: #transaction-comments54889 -Node: Postings55252 -Ref: #postings55383 -Node: Debits and credits56415 -Ref: #debits-and-credits56562 -Node: The two space delimiter57025 -Ref: #the-two-space-delimiter57182 -Node: Account names57590 -Ref: #account-names57720 -Node: Amounts59394 -Ref: #amounts59522 -Node: Decimal marks60423 -Ref: #decimal-marks60550 -Node: Digit group marks61527 -Ref: #digit-group-marks61680 -Node: Commodity62162 -Ref: #commodity62291 -Node: Costs63279 -Ref: #costs63374 -Node: Balance assertions65531 -Ref: #balance-assertions65684 -Node: Assertions and ordering66768 -Ref: #assertions-and-ordering66957 -Node: Assertions and multiple included files67496 -Ref: #assertions-and-multiple-included-files67756 -Node: Assertions and multiple -f files68256 -Ref: #assertions-and-multiple--f-files68501 -Node: Assertions and costs68898 -Ref: #assertions-and-costs69107 -Node: Assertions and commodities69548 -Ref: #assertions-and-commodities69763 -Node: Assertions and subaccounts71207 -Ref: #assertions-and-subaccounts71433 -Node: Assertions and virtual postings71877 -Ref: #assertions-and-virtual-postings72115 -Node: Assertions and auto postings72247 -Ref: #assertions-and-auto-postings72477 -Node: Assertions and precision73122 -Ref: #assertions-and-precision73304 -Node: Posting comments73571 -Ref: #posting-comments73734 -Node: Transaction balancing74111 -Ref: #transaction-balancing74270 -Node: Tags76113 -Ref: #tags76232 -Node: Tag names77575 -Ref: #tag-names77682 -Node: Special tags78070 -Ref: #special-tags78202 -Node: Tag values79715 -Ref: #tag-values79825 -Node: Directives80697 -Ref: #directives80824 -Node: Directives and multiple files82154 -Ref: #directives-and-multiple-files82332 -Node: Directive effects83099 -Ref: #directive-effects83253 -Node: account directive86255 -Ref: #account-directive86411 -Node: Account comments87705 -Ref: #account-comments87856 -Node: Account error checking88364 -Ref: #account-error-checking88557 -Node: Account display order89746 -Ref: #account-display-order89934 -Node: Account types90944 -Ref: #account-types91085 -Node: alias directive94718 -Ref: #alias-directive94879 -Node: Basic aliases95929 -Ref: #basic-aliases96060 -Node: Regex aliases96804 -Ref: #regex-aliases96961 -Node: Combining aliases97851 -Ref: #combining-aliases98029 -Node: Aliases and multiple files99305 -Ref: #aliases-and-multiple-files99509 -Node: end aliases directive100088 -Ref: #end-aliases-directive100307 -Node: Aliases can generate bad account names100456 -Ref: #aliases-can-generate-bad-account-names100704 -Node: Aliases and account types101289 -Ref: #aliases-and-account-types101481 -Node: commodity directive102177 -Ref: #commodity-directive102351 -Node: Commodity directive syntax103764 -Ref: #commodity-directive-syntax103949 -Node: Commodity error checking105400 -Ref: #commodity-error-checking105581 -Node: decimal-mark directive105875 -Ref: #decimal-mark-directive106057 -Node: include directive106454 -Ref: #include-directive106618 -Node: P directive107530 -Ref: #p-directive107675 -Node: payee directive108564 -Ref: #payee-directive108713 -Node: tag directive109186 -Ref: #tag-directive109341 -Node: Periodic transactions109798 -Ref: #periodic-transactions109963 -Node: Periodic rule syntax111952 -Ref: #periodic-rule-syntax112130 -Node: Periodic rules and relative dates112775 -Ref: #periodic-rules-and-relative-dates113041 -Node: Two spaces between period expression and description!113552 -Ref: #two-spaces-between-period-expression-and-description113829 -Node: Auto postings114513 -Ref: #auto-postings114661 -Node: Auto postings and multiple files117491 -Ref: #auto-postings-and-multiple-files117655 -Node: Auto postings and dates118056 -Ref: #auto-postings-and-dates118304 -Node: Auto postings and transaction balancing / inferred amounts / balance assertions118479 -Ref: #auto-postings-and-transaction-balancing-inferred-amounts-balance-assertions118835 -Node: Auto posting tags119338 -Ref: #auto-posting-tags119620 -Node: Auto postings on forecast transactions only120256 -Ref: #auto-postings-on-forecast-transactions-only120502 -Node: Other syntax120749 -Ref: #other-syntax120865 -Node: Balance assignments121521 -Ref: #balance-assignments121677 -Node: Balance assignments and costs123049 -Ref: #balance-assignments-and-costs123261 -Node: Balance assignments and multiple files123471 -Ref: #balance-assignments-and-multiple-files123701 -Node: Bracketed posting dates123894 -Ref: #bracketed-posting-dates124078 -Node: D directive124592 -Ref: #d-directive124760 -Node: apply account directive126365 -Ref: #apply-account-directive126545 -Node: Y directive127232 -Ref: #y-directive127392 -Node: Secondary dates128220 -Ref: #secondary-dates128374 -Node: Star comments129188 -Ref: #star-comments129348 -Node: Valuation expressions129880 -Ref: #valuation-expressions130057 -Node: Virtual postings130179 -Ref: #virtual-postings130356 -Node: Other Ledger directives131803 -Ref: #other-ledger-directives131999 -Node: Other cost/lot notations132565 -Ref: #other-costlot-notations132738 -Node: CSV135327 -Ref: #csv135420 -Node: CSV rules cheatsheet137417 -Ref: #csv-rules-cheatsheet137546 -Node: source139344 -Ref: #source139467 -Node: separator140347 -Ref: #separator140460 -Node: skip141000 -Ref: #skip141108 -Node: date-format141652 -Ref: #date-format141773 -Node: timezone142497 -Ref: #timezone142620 -Node: newest-first143625 -Ref: #newest-first143763 -Node: intra-day-reversed144340 -Ref: #intra-day-reversed144494 -Node: decimal-mark144942 -Ref: #decimal-mark145083 -Node: fields list145422 -Ref: #fields-list145561 -Node: Field assignment147232 -Ref: #field-assignment147376 -Node: Field names148453 -Ref: #field-names148584 -Node: date field149787 -Ref: #date-field149905 -Node: date2 field149953 -Ref: #date2-field150094 -Node: status field150150 -Ref: #status-field150293 -Node: code field150342 -Ref: #code-field150487 -Node: description field150532 -Ref: #description-field150692 -Node: comment field150751 -Ref: #comment-field150906 -Node: account field151199 -Ref: #account-field151349 -Node: amount field151919 -Ref: #amount-field152068 -Node: currency field154760 -Ref: #currency-field154913 -Node: balance field155170 -Ref: #balance-field155302 -Node: if block155695 -Ref: #if-block155816 -Node: Matchers157224 -Ref: #matchers157338 -Node: What matchers match158135 -Ref: #what-matchers-match158284 -Node: Combining matchers158724 -Ref: #combining-matchers158892 -Node: Match groups159429 -Ref: #match-groups159557 -Node: if table160325 -Ref: #if-table160447 -Node: balance-type162328 -Ref: #balance-type162457 -Node: include163157 -Ref: #include163284 -Node: Working with CSV163728 -Ref: #working-with-csv163875 -Node: Rapid feedback164282 -Ref: #rapid-feedback164415 -Node: Valid CSV164867 -Ref: #valid-csv165013 -Node: File Extension165745 -Ref: #file-extension165918 -Node: Reading CSV from standard input166482 -Ref: #reading-csv-from-standard-input166706 -Node: Reading multiple CSV files166870 -Ref: #reading-multiple-csv-files167101 -Node: Reading files specified by rule167342 -Ref: #reading-files-specified-by-rule167570 -Node: Valid transactions168741 -Ref: #valid-transactions168940 -Node: Deduplicating importing169568 -Ref: #deduplicating-importing169763 -Node: Setting amounts170799 -Ref: #setting-amounts170970 -Node: Amount signs173328 -Ref: #amount-signs173498 -Node: Setting currency/commodity174395 -Ref: #setting-currencycommodity174599 -Node: Amount decimal places175773 -Ref: #amount-decimal-places175979 -Node: Referencing other fields177032 -Ref: #referencing-other-fields177245 -Node: How CSV rules are evaluated178142 -Ref: #how-csv-rules-are-evaluated178359 -Node: Well factored rules179812 -Ref: #well-factored-rules179980 -Node: CSV rules examples180304 -Ref: #csv-rules-examples180439 -Node: Bank of Ireland180504 -Ref: #bank-of-ireland180641 -Node: Coinbase182103 -Ref: #coinbase182241 -Node: Amazon183288 -Ref: #amazon183413 -Node: Paypal185132 -Ref: #paypal185240 -Node: Timeclock192884 -Ref: #timeclock192989 -Node: Timedot195165 -Ref: #timedot195288 -Node: Timedot examples198409 -Ref: #timedot-examples198515 -Node: PART 3 REPORTING CONCEPTS200686 -Ref: #part-3-reporting-concepts200850 -Node: Time periods200850 -Ref: #time-periods200984 -Node: Report start & end date201102 -Ref: #report-start-end-date201254 -Node: Smart dates202578 -Ref: #smart-dates202731 -Node: Report intervals204521 -Ref: #report-intervals204676 -Node: Date adjustment205094 -Ref: #date-adjustment205254 -Node: Period expressions206105 -Ref: #period-expressions206246 -Node: Period expressions with a report interval208010 -Ref: #period-expressions-with-a-report-interval208244 -Node: More complex report intervals208458 -Ref: #more-complex-report-intervals208703 -Node: Multiple weekday intervals210564 -Ref: #multiple-weekday-intervals210753 -Node: Depth211575 -Ref: #depth211677 -Node: Queries211973 -Ref: #queries212075 -Node: Query types213671 -Ref: #query-types213792 -Node: Combining query terms217026 -Ref: #combining-query-terms217203 -Node: Queries and command options218766 -Ref: #queries-and-command-options218971 -Node: Queries and account aliases219220 -Ref: #queries-and-account-aliases219425 -Node: Queries and valuation219545 -Ref: #queries-and-valuation219702 -Node: Pivoting219907 -Ref: #pivoting220021 -Node: Generating data221798 -Ref: #generating-data221930 -Node: Forecasting223513 -Ref: #forecasting223638 -Node: --forecast224169 -Ref: #forecast224300 -Node: Inspecting forecast transactions225270 -Ref: #inspecting-forecast-transactions225472 -Node: Forecast reports226602 -Ref: #forecast-reports226775 -Node: Forecast tags227711 -Ref: #forecast-tags227871 -Node: Forecast period in detail228331 -Ref: #forecast-period-in-detail228525 -Node: Forecast troubleshooting229419 -Ref: #forecast-troubleshooting229587 -Node: Budgeting230490 -Ref: #budgeting230613 -Node: Amount formatting231050 -Ref: #amount-formatting231192 -Node: Commodity display style231294 -Ref: #commodity-display-style231448 -Node: Rounding233135 -Ref: #rounding233290 -Node: Trailing decimal marks233740 -Ref: #trailing-decimal-marks233919 -Node: Amount parseability234673 -Ref: #amount-parseability234829 -Node: Cost reporting236254 -Ref: #cost-reporting236396 -Node: Recording costs237057 -Ref: #recording-costs237193 -Node: Reporting at cost238784 -Ref: #reporting-at-cost238959 -Node: Equity conversion postings239549 -Ref: #equity-conversion-postings239763 -Node: Inferring equity conversion postings242194 -Ref: #inferring-equity-conversion-postings242457 -Node: Combining costs and equity conversion postings243209 -Ref: #combining-costs-and-equity-conversion-postings243519 -Node: Requirements for detecting equity conversion postings244434 -Ref: #requirements-for-detecting-equity-conversion-postings244756 -Node: Infer cost and equity by default ?245956 -Ref: #infer-cost-and-equity-by-default246185 -Node: Value reporting246393 -Ref: #value-reporting246535 -Node: -V Value247274 -Ref: #v-value247406 -Node: -X Value in specified commodity247601 -Ref: #x-value-in-specified-commodity247802 -Node: Valuation date247951 -Ref: #valuation-date248128 -Node: Finding market price248911 -Ref: #finding-market-price249122 -Node: --infer-market-prices market prices from transactions250291 -Ref: #infer-market-prices-market-prices-from-transactions250573 -Node: Valuation commodity253335 -Ref: #valuation-commodity253555 -Node: --value Flexible valuation254768 -Ref: #value-flexible-valuation254967 -Node: Valuation examples256611 -Ref: #valuation-examples256811 -Node: Interaction of valuation and queries258743 -Ref: #interaction-of-valuation-and-queries258983 -Node: Effect of valuation on reports259460 -Ref: #effect-of-valuation-on-reports259663 -Node: PART 4 COMMANDS267358 -Ref: #part-4-commands267501 -Node: Help commands269574 -Ref: #help-commands269719 -Node: help269747 -Ref: #help269836 -Node: demo271205 -Ref: #demo271294 -Node: User interface commands272210 -Ref: #user-interface-commands272379 -Node: ui272404 -Ref: #ui272496 -Node: web272529 -Ref: #web272623 -Node: Data entry commands272657 -Ref: #data-entry-commands272826 -Node: add272855 -Ref: #add272949 -Node: import275340 -Ref: #import275440 -Node: Date skipping276448 -Ref: #date-skipping276571 -Node: Import testing279349 -Ref: #import-testing279512 -Node: Importing balance assignments280355 -Ref: #importing-balance-assignments280562 -Node: Import and commodity styles281211 -Ref: #import-and-commodity-styles281391 -Node: Basic report commands281620 -Ref: #basic-report-commands281794 -Node: accounts281921 -Ref: #accounts282031 -Node: codes283918 -Ref: #codes284042 -Node: commodities284906 -Ref: #commodities285046 -Node: descriptions285116 -Ref: #descriptions285258 -Node: files285549 -Ref: #files285671 -Node: notes285812 -Ref: #notes285928 -Node: payees286290 -Ref: #payees286409 -Node: prices286928 -Ref: #prices287047 -Node: stats287700 -Ref: #stats287815 -Node: tags289329 -Ref: #tags-1289429 -Node: Standard report commands290438 -Ref: #standard-report-commands290623 -Node: print290743 -Ref: #print290851 -Node: print explicitness291831 -Ref: #print-explicitness291972 -Node: print amount style292751 -Ref: #print-amount-style292919 -Node: print parseability293989 -Ref: #print-parseability294159 -Node: print other features294908 -Ref: #print-other-features295085 -Node: print output format295606 -Ref: #print-output-format295752 -Node: aregister298891 -Ref: #aregister299024 -Node: aregister and posting dates301905 -Ref: #aregister-and-posting-dates302050 -Node: register302806 -Ref: #register302944 -Node: Custom register output307975 -Ref: #custom-register-output308104 -Node: balancesheet309451 -Ref: #balancesheet309606 -Node: balancesheetequity311268 -Ref: #balancesheetequity311435 -Node: cashflow313455 -Ref: #cashflow313605 -Node: incomestatement315092 -Ref: #incomestatement315229 -Node: Advanced report commands316765 -Ref: #advanced-report-commands316943 -Node: balance316973 -Ref: #balance317081 -Node: balance features318240 -Ref: #balance-features318380 -Node: Simple balance report320290 -Ref: #simple-balance-report320475 -Node: Balance report line format322100 -Ref: #balance-report-line-format322302 -Node: Filtered balance report324460 -Ref: #filtered-balance-report324652 -Node: List or tree mode324979 -Ref: #list-or-tree-mode325147 -Node: Depth limiting326492 -Ref: #depth-limiting326658 -Node: Dropping top-level accounts327259 -Ref: #dropping-top-level-accounts327459 -Node: Showing declared accounts327769 -Ref: #showing-declared-accounts327968 -Node: Sorting by amount328499 -Ref: #sorting-by-amount328666 -Node: Percentages329336 -Ref: #percentages329495 -Node: Multi-period balance report330043 -Ref: #multi-period-balance-report330243 -Node: Balance change end balance332795 -Ref: #balance-change-end-balance333004 -Node: Balance report types334432 -Ref: #balance-report-types334613 -Node: Calculation type335111 -Ref: #calculation-type335266 -Node: Accumulation type335815 -Ref: #accumulation-type335995 -Node: Valuation type336916 -Ref: #valuation-type337104 -Node: Combining balance report types338105 -Ref: #combining-balance-report-types338299 -Node: Budget report340137 -Ref: #budget-report340299 -Node: Using the budget report342442 -Ref: #using-the-budget-report342615 -Node: Budget date surprises344718 -Ref: #budget-date-surprises344918 -Node: Selecting budget goals346082 -Ref: #selecting-budget-goals346285 -Node: Budgeting vs forecasting347030 -Ref: #budgeting-vs-forecasting347207 -Node: Balance report layout348707 -Ref: #balance-report-layout348892 -Node: Wide layout349845 -Ref: #wide-layout349980 -Node: Tall layout352250 -Ref: #tall-layout352405 -Node: Bare layout353556 -Ref: #bare-layout353711 -Node: Tidy layout355615 -Ref: #tidy-layout355750 -Node: Some useful balance reports357159 -Ref: #some-useful-balance-reports357334 -Node: roi358419 -Ref: #roi358519 -Node: Spaces and special characters in --inv and --pnl360331 -Ref: #spaces-and-special-characters-in---inv-and---pnl360569 -Node: Semantics of --inv and --pnl361057 -Ref: #semantics-of---inv-and---pnl361294 -Node: IRR and TWR explained363144 -Ref: #irr-and-twr-explained363302 -Node: Chart commands366555 -Ref: #chart-commands366713 -Node: activity366736 -Ref: #activity366825 -Node: Data generation commands367199 -Ref: #data-generation-commands367373 -Node: close367405 -Ref: #close367511 -Node: close --migrate368164 -Ref: #close---migrate368289 -Node: close --close369928 -Ref: #close---close370070 -Node: close --open370306 -Ref: #close---open370445 -Node: close --assert370555 -Ref: #close---assert370699 -Node: close --assign370920 -Ref: #close---assign371066 -Node: close --retain371592 -Ref: #close---retain371743 -Node: close customisation372488 -Ref: #close-customisation372665 -Node: close and balance assertions374132 -Ref: #close-and-balance-assertions374327 -Node: close examples375654 -Ref: #close-examples375793 -Node: Retain earnings375891 -Ref: #retain-earnings376048 -Node: Migrate balances to a new file376394 -Ref: #migrate-balances-to-a-new-file376618 -Node: More detailed close examples377746 -Ref: #more-detailed-close-examples377942 -Node: rewrite377968 -Ref: #rewrite378078 -Node: Re-write rules in a file379976 -Ref: #re-write-rules-in-a-file380137 -Node: Diff output format381286 -Ref: #diff-output-format381467 -Node: rewrite vs print --auto382559 -Ref: #rewrite-vs.-print---auto382717 -Node: Maintenance commands383273 -Ref: #maintenance-commands383444 -Node: check383482 -Ref: #check383581 -Node: Basic checks384530 -Ref: #basic-checks384648 -Node: Strict checks385483 -Ref: #strict-checks385624 -Node: Other checks386358 -Ref: #other-checks386498 -Node: Custom checks388213 -Ref: #custom-checks388333 -Node: diff388668 -Ref: #diff388778 -Node: test389820 -Ref: #test389916 -Node: PART 5 COMMON TASKS390658 -Ref: #part-5-common-tasks390817 -Node: Getting help390891 -Ref: #getting-help391040 -Node: Constructing command lines391800 -Ref: #constructing-command-lines391981 -Node: Starting a journal file392638 -Ref: #starting-a-journal-file392820 -Node: Setting LEDGER_FILE394022 -Ref: #setting-ledger_file394194 -Node: Setting opening balances395151 -Ref: #setting-opening-balances395332 -Node: Recording transactions398473 -Ref: #recording-transactions398642 -Node: Reconciling399198 -Ref: #reconciling399330 -Node: Reporting401587 -Ref: #reporting401716 -Node: Migrating to a new file405701 -Ref: #migrating-to-a-new-file405851 -Node: BUGS406150 -Ref: #bugs406244 -Node: Troubleshooting407123 -Ref: #troubleshooting407223 +Node: PART 1 USER INTERFACE4270 +Ref: #part-1-user-interface4409 +Node: Input4409 +Ref: #input4519 +Node: Text encoding5486 +Ref: #text-encoding5600 +Node: Data formats6166 +Ref: #data-formats6301 +Node: Standard input7890 +Ref: #standard-input8030 +Node: Multiple files8279 +Ref: #multiple-files8418 +Node: Strict mode9016 +Ref: #strict-mode9126 +Node: Commands9850 +Ref: #commands9952 +Node: Add-on commands11019 +Ref: #add-on-commands11121 +Node: Options12237 +Ref: #options12338 +Node: Special characters18188 +Ref: #special-characters18325 +Node: Single escaping shell metacharacters18488 +Ref: #single-escaping-shell-metacharacters18729 +Node: Double escaping regular expression metacharacters19332 +Ref: #double-escaping-regular-expression-metacharacters19643 +Node: Triple escaping for add-on commands20169 +Ref: #triple-escaping-for-add-on-commands20429 +Node: Less escaping21073 +Ref: #less-escaping21227 +Node: Unicode characters21551 +Ref: #unicode-characters21716 +Node: Regular expressions23215 +Ref: #regular-expressions23378 +Node: hledger's regular expressions26474 +Ref: #hledgers-regular-expressions26633 +Node: Argument files28019 +Ref: #argument-files28145 +Node: Output28642 +Ref: #output28744 +Node: Output destination28871 +Ref: #output-destination29002 +Node: Output format29427 +Ref: #output-format29573 +Node: CSV output31170 +Ref: #csv-output31286 +Node: HTML output31389 +Ref: #html-output31527 +Node: JSON output31621 +Ref: #json-output31759 +Node: SQL output32744 +Ref: #sql-output32860 +Node: Commodity styles33595 +Ref: #commodity-styles33735 +Node: Colour34473 +Ref: #colour34591 +Node: Box-drawing34995 +Ref: #box-drawing35113 +Node: Paging35403 +Ref: #paging35517 +Node: Debug output36470 +Ref: #debug-output36576 +Node: Environment37239 +Ref: #environment37363 +Node: PART 2 DATA FORMATS37930 +Ref: #part-2-data-formats38073 +Node: Journal38073 +Ref: #journal38182 +Node: Journal cheatsheet40550 +Ref: #journal-cheatsheet40677 +Node: Comments46764 +Ref: #comments46892 +Node: Transactions47708 +Ref: #transactions47831 +Node: Dates48845 +Ref: #dates48952 +Node: Simple dates48997 +Ref: #simple-dates49113 +Node: Posting dates49613 +Ref: #posting-dates49731 +Node: Status50700 +Ref: #status50801 +Node: Code52466 +Ref: #code52569 +Node: Description52801 +Ref: #description52932 +Node: Payee and note53488 +Ref: #payee-and-note53594 +Node: Transaction comments54579 +Ref: #transaction-comments54732 +Node: Postings55095 +Ref: #postings55226 +Node: Debits and credits56258 +Ref: #debits-and-credits56405 +Node: The two space delimiter56868 +Ref: #the-two-space-delimiter57025 +Node: Account names57433 +Ref: #account-names57563 +Node: Amounts59237 +Ref: #amounts59365 +Node: Decimal marks60266 +Ref: #decimal-marks60393 +Node: Digit group marks61370 +Ref: #digit-group-marks61523 +Node: Commodity62005 +Ref: #commodity62134 +Node: Costs63122 +Ref: #costs63217 +Node: Balance assertions65374 +Ref: #balance-assertions65527 +Node: Assertions and ordering66611 +Ref: #assertions-and-ordering66800 +Node: Assertions and multiple included files67339 +Ref: #assertions-and-multiple-included-files67599 +Node: Assertions and multiple -f files68099 +Ref: #assertions-and-multiple--f-files68344 +Node: Assertions and costs68741 +Ref: #assertions-and-costs68950 +Node: Assertions and commodities69391 +Ref: #assertions-and-commodities69606 +Node: Assertions and subaccounts71050 +Ref: #assertions-and-subaccounts71276 +Node: Assertions and virtual postings71720 +Ref: #assertions-and-virtual-postings71958 +Node: Assertions and auto postings72090 +Ref: #assertions-and-auto-postings72320 +Node: Assertions and precision72965 +Ref: #assertions-and-precision73147 +Node: Posting comments73414 +Ref: #posting-comments73577 +Node: Transaction balancing73954 +Ref: #transaction-balancing74113 +Node: Tags75956 +Ref: #tags76075 +Node: Tag names77418 +Ref: #tag-names77525 +Node: Special tags77913 +Ref: #special-tags78045 +Node: Tag values79558 +Ref: #tag-values79668 +Node: Directives80540 +Ref: #directives80667 +Node: Directives and multiple files81997 +Ref: #directives-and-multiple-files82175 +Node: Directive effects82942 +Ref: #directive-effects83096 +Node: account directive86098 +Ref: #account-directive86254 +Node: Account comments87548 +Ref: #account-comments87699 +Node: Account error checking88207 +Ref: #account-error-checking88400 +Node: Account display order89589 +Ref: #account-display-order89777 +Node: Account types90787 +Ref: #account-types90928 +Node: alias directive94561 +Ref: #alias-directive94722 +Node: Basic aliases95772 +Ref: #basic-aliases95903 +Node: Regex aliases96647 +Ref: #regex-aliases96804 +Node: Combining aliases97694 +Ref: #combining-aliases97872 +Node: Aliases and multiple files99148 +Ref: #aliases-and-multiple-files99352 +Node: end aliases directive99931 +Ref: #end-aliases-directive100150 +Node: Aliases can generate bad account names100299 +Ref: #aliases-can-generate-bad-account-names100547 +Node: Aliases and account types101132 +Ref: #aliases-and-account-types101324 +Node: commodity directive102020 +Ref: #commodity-directive102194 +Node: Commodity directive syntax103607 +Ref: #commodity-directive-syntax103792 +Node: Commodity error checking105243 +Ref: #commodity-error-checking105424 +Node: decimal-mark directive105718 +Ref: #decimal-mark-directive105900 +Node: include directive106297 +Ref: #include-directive106461 +Node: P directive107373 +Ref: #p-directive107518 +Node: payee directive108407 +Ref: #payee-directive108556 +Node: tag directive109029 +Ref: #tag-directive109184 +Node: Periodic transactions109641 +Ref: #periodic-transactions109806 +Node: Periodic rule syntax111795 +Ref: #periodic-rule-syntax111973 +Node: Periodic rules and relative dates112618 +Ref: #periodic-rules-and-relative-dates112884 +Node: Two spaces between period expression and description!113395 +Ref: #two-spaces-between-period-expression-and-description113672 +Node: Auto postings114356 +Ref: #auto-postings114504 +Node: Auto postings and multiple files117334 +Ref: #auto-postings-and-multiple-files117498 +Node: Auto postings and dates117899 +Ref: #auto-postings-and-dates118147 +Node: Auto postings and transaction balancing / inferred amounts / balance assertions118322 +Ref: #auto-postings-and-transaction-balancing-inferred-amounts-balance-assertions118678 +Node: Auto posting tags119181 +Ref: #auto-posting-tags119463 +Node: Auto postings on forecast transactions only120099 +Ref: #auto-postings-on-forecast-transactions-only120345 +Node: Other syntax120592 +Ref: #other-syntax120708 +Node: Balance assignments121364 +Ref: #balance-assignments121520 +Node: Balance assignments and costs122892 +Ref: #balance-assignments-and-costs123104 +Node: Balance assignments and multiple files123314 +Ref: #balance-assignments-and-multiple-files123544 +Node: Bracketed posting dates123737 +Ref: #bracketed-posting-dates123921 +Node: D directive124435 +Ref: #d-directive124603 +Node: apply account directive126208 +Ref: #apply-account-directive126388 +Node: Y directive127075 +Ref: #y-directive127235 +Node: Secondary dates128063 +Ref: #secondary-dates128217 +Node: Star comments129548 +Ref: #star-comments129708 +Node: Valuation expressions130240 +Ref: #valuation-expressions130417 +Node: Virtual postings130539 +Ref: #virtual-postings130716 +Node: Other Ledger directives132163 +Ref: #other-ledger-directives132359 +Node: Other cost/lot notations132925 +Ref: #other-costlot-notations133098 +Node: CSV135687 +Ref: #csv135778 +Node: CSV rules cheatsheet137775 +Ref: #csv-rules-cheatsheet137902 +Node: source139700 +Ref: #source139821 +Node: separator140701 +Ref: #separator140812 +Node: skip141352 +Ref: #skip141458 +Node: date-format142002 +Ref: #date-format142121 +Node: timezone142845 +Ref: #timezone142966 +Node: newest-first143971 +Ref: #newest-first144107 +Node: intra-day-reversed144684 +Ref: #intra-day-reversed144836 +Node: decimal-mark145284 +Ref: #decimal-mark145423 +Node: fields list145762 +Ref: #fields-list145899 +Node: Field assignment147570 +Ref: #field-assignment147712 +Node: Field names148789 +Ref: #field-names148918 +Node: date field150121 +Ref: #date-field150237 +Node: date2 field150285 +Ref: #date2-field150424 +Node: status field150480 +Ref: #status-field150621 +Node: code field150670 +Ref: #code-field150813 +Node: description field150858 +Ref: #description-field151016 +Node: comment field151075 +Ref: #comment-field151228 +Node: account field151521 +Ref: #account-field151669 +Node: amount field152239 +Ref: #amount-field152386 +Node: currency field155078 +Ref: #currency-field155229 +Node: balance field155486 +Ref: #balance-field155616 +Node: if block156009 +Ref: #if-block156128 +Node: Matchers157536 +Ref: #matchers157648 +Node: What matchers match158445 +Ref: #what-matchers-match158592 +Node: Combining matchers159032 +Ref: #combining-matchers159198 +Node: Match groups159735 +Ref: #match-groups159861 +Node: if table160629 +Ref: #if-table160749 +Node: balance-type162630 +Ref: #balance-type162757 +Node: include163457 +Ref: #include163582 +Node: Working with CSV164026 +Ref: #working-with-csv164171 +Node: Rapid feedback164578 +Ref: #rapid-feedback164709 +Node: Valid CSV165161 +Ref: #valid-csv165305 +Node: File Extension166037 +Ref: #file-extension166208 +Node: Reading CSV from standard input166772 +Ref: #reading-csv-from-standard-input166994 +Node: Reading multiple CSV files167158 +Ref: #reading-multiple-csv-files167387 +Node: Reading files specified by rule167628 +Ref: #reading-files-specified-by-rule167854 +Node: Valid transactions169025 +Ref: #valid-transactions169222 +Node: Deduplicating importing169850 +Ref: #deduplicating-importing170043 +Node: Setting amounts171079 +Ref: #setting-amounts171248 +Node: Amount signs173606 +Ref: #amount-signs173774 +Node: Setting currency/commodity174671 +Ref: #setting-currencycommodity174873 +Node: Amount decimal places176047 +Ref: #amount-decimal-places176251 +Node: Referencing other fields177304 +Ref: #referencing-other-fields177515 +Node: How CSV rules are evaluated178412 +Ref: #how-csv-rules-are-evaluated178627 +Node: Well factored rules180080 +Ref: #well-factored-rules180246 +Node: CSV rules examples180570 +Ref: #csv-rules-examples180703 +Node: Bank of Ireland180768 +Ref: #bank-of-ireland180903 +Node: Coinbase182365 +Ref: #coinbase182501 +Node: Amazon183548 +Ref: #amazon183671 +Node: Paypal185390 +Ref: #paypal185496 +Node: Timeclock193140 +Ref: #timeclock193245 +Node: Timedot195421 +Ref: #timedot195544 +Node: Timedot examples198665 +Ref: #timedot-examples198771 +Node: PART 3 REPORTING CONCEPTS200942 +Ref: #part-3-reporting-concepts201106 +Node: Time periods201106 +Ref: #time-periods201240 +Node: Report start & end date201358 +Ref: #report-start-end-date201510 +Node: Smart dates202834 +Ref: #smart-dates202987 +Node: Report intervals204777 +Ref: #report-intervals204932 +Node: Date adjustment205350 +Ref: #date-adjustment205510 +Node: Period expressions206361 +Ref: #period-expressions206502 +Node: Period expressions with a report interval208266 +Ref: #period-expressions-with-a-report-interval208500 +Node: More complex report intervals208714 +Ref: #more-complex-report-intervals208959 +Node: Multiple weekday intervals210820 +Ref: #multiple-weekday-intervals211009 +Node: Depth211831 +Ref: #depth211933 +Node: Queries212229 +Ref: #queries212331 +Node: Query types213927 +Ref: #query-types214048 +Node: Combining query terms217282 +Ref: #combining-query-terms217459 +Node: Queries and command options219022 +Ref: #queries-and-command-options219227 +Node: Queries and account aliases219476 +Ref: #queries-and-account-aliases219681 +Node: Queries and valuation219801 +Ref: #queries-and-valuation219958 +Node: Pivoting220163 +Ref: #pivoting220277 +Node: Generating data222054 +Ref: #generating-data222186 +Node: Forecasting223854 +Ref: #forecasting223979 +Node: --forecast224510 +Ref: #forecast224641 +Node: Inspecting forecast transactions225611 +Ref: #inspecting-forecast-transactions225813 +Node: Forecast reports226943 +Ref: #forecast-reports227116 +Node: Forecast tags228052 +Ref: #forecast-tags228212 +Node: Forecast period in detail228672 +Ref: #forecast-period-in-detail228866 +Node: Forecast troubleshooting229760 +Ref: #forecast-troubleshooting229928 +Node: Budgeting230831 +Ref: #budgeting230954 +Node: Amount formatting231391 +Ref: #amount-formatting231533 +Node: Commodity display style231635 +Ref: #commodity-display-style231789 +Node: Rounding233476 +Ref: #rounding233631 +Node: Trailing decimal marks234081 +Ref: #trailing-decimal-marks234260 +Node: Amount parseability235014 +Ref: #amount-parseability235170 +Node: Cost reporting236595 +Ref: #cost-reporting236737 +Node: Recording costs237398 +Ref: #recording-costs237534 +Node: Reporting at cost239125 +Ref: #reporting-at-cost239300 +Node: Equity conversion postings239890 +Ref: #equity-conversion-postings240104 +Node: Inferring equity conversion postings242535 +Ref: #inferring-equity-conversion-postings242798 +Node: Combining costs and equity conversion postings243550 +Ref: #combining-costs-and-equity-conversion-postings243860 +Node: Requirements for detecting equity conversion postings244775 +Ref: #requirements-for-detecting-equity-conversion-postings245097 +Node: Infer cost and equity by default ?246297 +Ref: #infer-cost-and-equity-by-default246526 +Node: Value reporting246734 +Ref: #value-reporting246876 +Node: -V Value247615 +Ref: #v-value247747 +Node: -X Value in specified commodity247942 +Ref: #x-value-in-specified-commodity248143 +Node: Valuation date248292 +Ref: #valuation-date248469 +Node: Finding market price249252 +Ref: #finding-market-price249463 +Node: --infer-market-prices market prices from transactions250632 +Ref: #infer-market-prices-market-prices-from-transactions250914 +Node: Valuation commodity253676 +Ref: #valuation-commodity253896 +Node: --value Flexible valuation255109 +Ref: #value-flexible-valuation255308 +Node: Valuation examples256952 +Ref: #valuation-examples257152 +Node: Interaction of valuation and queries259084 +Ref: #interaction-of-valuation-and-queries259324 +Node: Effect of valuation on reports259801 +Ref: #effect-of-valuation-on-reports260004 +Node: PART 4 COMMANDS267699 +Ref: #part-4-commands267842 +Node: Help commands269915 +Ref: #help-commands270060 +Node: help270088 +Ref: #help270177 +Node: demo271546 +Ref: #demo271635 +Node: User interface commands272551 +Ref: #user-interface-commands272720 +Node: ui272745 +Ref: #ui272837 +Node: web272870 +Ref: #web272964 +Node: Data entry commands272998 +Ref: #data-entry-commands273167 +Node: add273196 +Ref: #add273290 +Node: import275681 +Ref: #import275781 +Node: Date skipping276789 +Ref: #date-skipping276912 +Node: Import testing279690 +Ref: #import-testing279853 +Node: Importing balance assignments280696 +Ref: #importing-balance-assignments280903 +Node: Import and commodity styles281552 +Ref: #import-and-commodity-styles281732 +Node: Basic report commands281961 +Ref: #basic-report-commands282135 +Node: accounts282262 +Ref: #accounts282372 +Node: codes284259 +Ref: #codes284383 +Node: commodities285247 +Ref: #commodities285387 +Node: descriptions285457 +Ref: #descriptions285599 +Node: files285890 +Ref: #files286012 +Node: notes286153 +Ref: #notes286269 +Node: payees286631 +Ref: #payees286750 +Node: prices287269 +Ref: #prices287388 +Node: stats288041 +Ref: #stats288156 +Node: tags289670 +Ref: #tags-1289770 +Node: Standard report commands290779 +Ref: #standard-report-commands290964 +Node: print291084 +Ref: #print291192 +Node: print explicitness292172 +Ref: #print-explicitness292313 +Node: print amount style293092 +Ref: #print-amount-style293260 +Node: print parseability294330 +Ref: #print-parseability294500 +Node: print other features295249 +Ref: #print-other-features295426 +Node: print output format295947 +Ref: #print-output-format296093 +Node: aregister299232 +Ref: #aregister299365 +Node: aregister and posting dates302246 +Ref: #aregister-and-posting-dates302391 +Node: register303147 +Ref: #register303285 +Node: Custom register output308316 +Ref: #custom-register-output308445 +Node: balancesheet309792 +Ref: #balancesheet309947 +Node: balancesheetequity311609 +Ref: #balancesheetequity311776 +Node: cashflow313796 +Ref: #cashflow313946 +Node: incomestatement315433 +Ref: #incomestatement315570 +Node: Advanced report commands317106 +Ref: #advanced-report-commands317284 +Node: balance317314 +Ref: #balance317422 +Node: balance features318581 +Ref: #balance-features318721 +Node: Simple balance report320631 +Ref: #simple-balance-report320816 +Node: Balance report line format322441 +Ref: #balance-report-line-format322643 +Node: Filtered balance report324801 +Ref: #filtered-balance-report324993 +Node: List or tree mode325320 +Ref: #list-or-tree-mode325488 +Node: Depth limiting326833 +Ref: #depth-limiting326999 +Node: Dropping top-level accounts327600 +Ref: #dropping-top-level-accounts327800 +Node: Showing declared accounts328110 +Ref: #showing-declared-accounts328309 +Node: Sorting by amount328840 +Ref: #sorting-by-amount329007 +Node: Percentages329677 +Ref: #percentages329836 +Node: Multi-period balance report330384 +Ref: #multi-period-balance-report330584 +Node: Balance change end balance333136 +Ref: #balance-change-end-balance333345 +Node: Balance report types334773 +Ref: #balance-report-types334954 +Node: Calculation type335452 +Ref: #calculation-type335607 +Node: Accumulation type336156 +Ref: #accumulation-type336336 +Node: Valuation type337257 +Ref: #valuation-type337445 +Node: Combining balance report types338446 +Ref: #combining-balance-report-types338640 +Node: Budget report340478 +Ref: #budget-report340640 +Node: Using the budget report342783 +Ref: #using-the-budget-report342956 +Node: Budget date surprises345059 +Ref: #budget-date-surprises345259 +Node: Selecting budget goals346423 +Ref: #selecting-budget-goals346626 +Node: Budgeting vs forecasting347371 +Ref: #budgeting-vs-forecasting347548 +Node: Balance report layout349048 +Ref: #balance-report-layout349233 +Node: Wide layout350186 +Ref: #wide-layout350321 +Node: Tall layout352591 +Ref: #tall-layout352746 +Node: Bare layout353897 +Ref: #bare-layout354052 +Node: Tidy layout355956 +Ref: #tidy-layout356091 +Node: Some useful balance reports357500 +Ref: #some-useful-balance-reports357675 +Node: roi358760 +Ref: #roi358860 +Node: Spaces and special characters in --inv and --pnl360672 +Ref: #spaces-and-special-characters-in---inv-and---pnl360910 +Node: Semantics of --inv and --pnl361398 +Ref: #semantics-of---inv-and---pnl361635 +Node: IRR and TWR explained363485 +Ref: #irr-and-twr-explained363643 +Node: Chart commands366896 +Ref: #chart-commands367054 +Node: activity367077 +Ref: #activity367166 +Node: Data generation commands367540 +Ref: #data-generation-commands367714 +Node: close367746 +Ref: #close367852 +Node: close --migrate368505 +Ref: #close---migrate368630 +Node: close --close370269 +Ref: #close---close370411 +Node: close --open370647 +Ref: #close---open370786 +Node: close --assert370896 +Ref: #close---assert371040 +Node: close --assign371261 +Ref: #close---assign371407 +Node: close --retain371933 +Ref: #close---retain372084 +Node: close customisation372829 +Ref: #close-customisation373006 +Node: close and balance assertions374473 +Ref: #close-and-balance-assertions374668 +Node: close examples375995 +Ref: #close-examples376134 +Node: Retain earnings376232 +Ref: #retain-earnings376389 +Node: Migrate balances to a new file376735 +Ref: #migrate-balances-to-a-new-file376959 +Node: More detailed close examples378087 +Ref: #more-detailed-close-examples378283 +Node: rewrite378309 +Ref: #rewrite378419 +Node: Re-write rules in a file380317 +Ref: #re-write-rules-in-a-file380478 +Node: Diff output format381627 +Ref: #diff-output-format381808 +Node: rewrite vs print --auto382900 +Ref: #rewrite-vs.-print---auto383058 +Node: Maintenance commands383614 +Ref: #maintenance-commands383785 +Node: check383823 +Ref: #check383922 +Node: Basic checks384871 +Ref: #basic-checks384989 +Node: Strict checks385824 +Ref: #strict-checks385965 +Node: Other checks386699 +Ref: #other-checks386839 +Node: Custom checks388554 +Ref: #custom-checks388674 +Node: diff389009 +Ref: #diff389119 +Node: test390161 +Ref: #test390257 +Node: PART 5 COMMON TASKS390999 +Ref: #part-5-common-tasks391158 +Node: Getting help391232 +Ref: #getting-help391381 +Node: Constructing command lines392141 +Ref: #constructing-command-lines392322 +Node: Starting a journal file392979 +Ref: #starting-a-journal-file393161 +Node: Setting LEDGER_FILE394363 +Ref: #setting-ledger_file394535 +Node: Setting opening balances395492 +Ref: #setting-opening-balances395673 +Node: Recording transactions398814 +Ref: #recording-transactions398983 +Node: Reconciling399539 +Ref: #reconciling399671 +Node: Reporting401928 +Ref: #reporting402057 +Node: Migrating to a new file406042 +Ref: #migrating-to-a-new-file406192 +Node: BUGS406491 +Ref: #bugs406585 +Node: Troubleshooting407464 +Ref: #troubleshooting407564  End Tag Table diff --git a/hledger/hledger.txt b/hledger/hledger.txt index 1b121a564..351618a8a 100644 --- a/hledger/hledger.txt +++ b/hledger/hledger.txt @@ -7,8 +7,10 @@ NAME SYNOPSIS hledger - hledger COMMAND [OPTS] [ARGS] - hledger ADDONCMD -- [OPTS] [ARGS] + or + hledger COMMAND [OPTS] [ARGS] + or + hledger ADDONCMD [OPTS] -- [ADDONOPTS] [ADDONARGS] DESCRIPTION hledger is a robust, user-friendly, cross-platform set of programs for @@ -17,7 +19,7 @@ DESCRIPTION and largely compatible with ledger(1), and largely interconvertible with beancount(1). - This manual is for hledger's command line interface, version 1.33.99. + This manual is for hledger's command line interface, version 1.34.99. It also describes the common options, file formats and concepts used by all hledger programs. It might accidentally teach you some bookkeep- ing/accounting as well! You don't need to know everything in here to @@ -149,29 +151,29 @@ Input $ cat FILE | hledger -f- print - If reading non-journal data in this way, you'll need to add a file for- - mat prefix, like: + If reading non-journal data in this way, you'll need to write the for- + mat as a prefix, like timeclock: here: $ echo 'i 2009/13/1 08:00:00' | hledger print -f timeclock:- Multiple files - You can specify multiple -f options, to read multiple files as one big + You can specify multiple -f options, to read multiple files as one big journal. When doing this, note that certain features (described below) will be affected: - o Balance assertions will not see the effect of transactions in previ- - ous files. (Usually this doesn't matter as each file will set the + o Balance assertions will not see the effect of transactions in previ- + ous files. (Usually this doesn't matter as each file will set the corresponding opening balances.) o Some directives will not affect previous or subsequent files. - If needed, you can work around these by using a single parent file + If needed, you can work around these by using a single parent file which includes the others, or concatenating the files into one, eg: cat a.journal b.journal | hledger -f- CMD. Strict mode hledger checks input files for valid data. By default, the most impor- - tant errors are detected, while still accepting easy journal files + tant errors are detected, while still accepting easy journal files without a lot of declarations: o Are the input files parseable, with valid syntax ? @@ -182,7 +184,7 @@ Input With the -s/--strict flag, additional checks are performed: - o Are all accounts posted to, declared with an account directive ? + o Are all accounts posted to, declared with an account directive ? (Account error checking) o Are all commodities declared with a commodity directive ? (Commodity @@ -190,13 +192,13 @@ Input o Are all commodity conversions declared explicitly ? - You can use the check command to run individual checks -- the ones + You can use the check command to run individual checks -- the ones listed above and some more. Commands - hledger provides various subcommands for getting things done. Most of - these commands do not change the journal file; they just read it and - output a report. A few commands assist with adding data and file man- + hledger provides various subcommands for getting things done. Most of + these commands do not change the journal file; they just read it and + output a report. A few commands assist with adding data and file man- agement. To show the commands list, run hledger with no arguments. The commands @@ -204,44 +206,44 @@ Commands To use a particular command, run hledger CMD [CMDOPTS] [CMDARGS], - o CMD is the full command name, or its standard abbreviation shown in + o CMD is the full command name, or its standard abbreviation shown in the commands list, or any unambiguous prefix of the name. - o CMDOPTS are command-specific options, if any. Command-specific op- + o CMDOPTS are command-specific options, if any. Command-specific op- tions must be written after the command name. Eg: hledger print -x. - o CMDARGS are additional arguments to the command, if any. Most - hledger commands accept arguments representing a query, to limit the + o CMDARGS are additional arguments to the command, if any. Most + hledger commands accept arguments representing a query, to limit the data in some way. Eg: hledger reg assets:checking. To list a command's options, arguments, and documentation in the termi- nal, run hledger CMD -h. Eg: hledger bal -h. Add-on commands - In addition to the built-in commands, you can install add-on commands: - programs or scripts named "hledger-SOMETHING", which will also appear - in hledger's commands list. If you used the hledger-install script, - you will have several add-ons installed already. Some more can be - found in hledger's bin/ directory, documented at + In addition to the built-in commands, you can install add-on commands: + programs or scripts named "hledger-SOMETHING", which will also appear + in hledger's commands list. If you used the hledger-install script, + you will have several add-ons installed already. Some more can be + found in hledger's bin/ directory, documented at https://hledger.org/scripts.html. More precisely, add-on commands are programs or scripts in your shell's PATH, whose name starts with "hledger-" and ends with no extension or a - recognised extension (".bat", ".com", ".exe", ".hs", ".js", ".lhs", - ".lua", ".php", ".pl", ".py", ".rb", ".rkt", or ".sh"), and (on unix + recognised extension (".bat", ".com", ".exe", ".hs", ".js", ".lhs", + ".lua", ".php", ".pl", ".py", ".rb", ".rkt", or ".sh"), and (on unix and mac) which has executable permission for the current user. You can run add-on commands using hledger, much like built-in commands: hledger ADDONCMD [-- ADDONCMDOPTS] [ADDONCMDARGS]. But note the double - hyphen argument, required before add-on-specific options. Eg: hledger - ui -- --watch or hledger web -- --serve. If this causes difficulty, + hyphen argument, required before add-on-specific options. Eg: hledger + ui -- --watch or hledger web -- --serve. If this causes difficulty, you can always run the add-on directly, without using hledger: hledger-ui --watch or hledger-web --serve. Options - Run hledger -h to see general command line help, and general options - which are common to most hledger commands. These options can be writ- - ten anywhere on the command line: + Run hledger -h to see general command line help. The following general + options are common to most hledger commands. General options can be + written either before or after the command name. General input/data transformation flags: -f --file=FILE Read data from FILE, or from stdin if -. Can be @@ -309,7 +311,6 @@ Options Eg: -c '.' or -c '1.000,00 EUR' --color=YN --colour Use ANSI color codes in text output? Can be 'y'/'yes'/'always', 'n'/'no'/'never' or 'auto'. - (A NO_COLOR environment variable overrides this.) --pretty[=YN] Use box-drawing characters in text output? Can be 'y'/'yes' or 'n'/'no'. If YN is specified, the equals is required. @@ -318,19 +319,22 @@ Options General help flags: -h --help show command line help --tldr show command examples with tldr - --info show the hledger manual with info - --man show the hledger manual with man + --info show the manual with info + --man show the manual with man --version show version information - Some reporting options can also be written as query arguments. + Usually hledger accepts any unambiguous flag prefix, eg you can write + --tl instead of --tldr or --dry instead of --dry-run. -Command line tips - Here are some details useful to know about for hledger command lines - (and elsewhere). Feel free to skip this section until you need it. + If the same option appears more than once in a command, usually the + last (right-most) wins. - Option repetition - If options are repeated in a command line, hledger will generally use - the last (right-most) occurence. + With most commands, arguments are interpreted as a hledger query which + filter the data. Some queries can be expressed either with options or + with arguments. + + Below are more tips for using the command line interface - feel free to + skip these until you need them. Special characters Single escaping (shell metacharacters) @@ -616,78 +620,79 @@ Output sentation of hledger's internal data types. To understand the JSON, read the Haskell type definitions, which are mostly in https://github.com/simonmichael/hledger/blob/mas- - ter/hledger-lib/Hledger/Data/Types.hs. + ter/hledger-lib/Hledger/Data/Types.hs. hledger-web's OpenAPI speci- + fication may also be relevant. - o hledger represents quantities as Decimal values storing up to 255 - significant digits, eg for repeating decimals. Such numbers can + o hledger represents quantities as Decimal values storing up to 255 + significant digits, eg for repeating decimals. Such numbers can arise in practice (from automatically-calculated transaction prices), - and would break most JSON consumers. So in JSON, we show quantities + and would break most JSON consumers. So in JSON, we show quantities as simple Numbers with at most 10 decimal places. We don't limit the - number of integer digits, but that part is under your control. We - hope this approach will not cause problems in practice; if you find + number of integer digits, but that part is under your control. We + hope this approach will not cause problems in practice; if you find otherwise, please let us know. (Cf #1195) SQL output o This is not yet much used; real-world feedback is welcome. - o SQL output is expected to work at least with SQLite, MySQL and Post- + o SQL output is expected to work at least with SQLite, MySQL and Post- gres. - o For SQLite, it will be more useful if you modify the generated id + o For SQLite, it will be 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' | ... - o SQL output is structured with the expectations that statements will - be executed in the empty database. If you already have tables cre- - ated via SQL output of hledger, you would probably want to either + o SQL output is structured with the expectations that statements will + be executed in the empty database. If you already have tables cre- + ated via SQL output of hledger, you would probably want to either clear tables of existing data (via delete or truncate SQL statements) or drop tables completely as otherwise your postings will be duped. 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 repeated to set the display style for multiple commodi- - ties/currencies. Its argument is as described in the commodity direc- + ties/currencies. Its argument is as described in the commodity direc- tive. - In some cases hledger will adjust number formatting to improve their + In some cases hledger will adjust number formatting to improve their parseability (such as adding trailing decimal marks when needed). Colour - In terminal output, some commands can produce colour when the terminal + In terminal output, some commands can produce colour when the terminal supports it: - o if the --color/--colour option is given a value of yes or always (or + o if the --color/--colour option is given a value of yes or always (or no or never), colour will (or will not) be used; - o otherwise, if the NO_COLOR environment variable is set, colour will + o otherwise, if the NO_COLOR environment variable is set, colour will not be used; - o otherwise, colour will be used if the output (terminal or file) sup- + o otherwise, colour will be used if the output (terminal or file) sup- ports it. Box-drawing - In terminal output, you can enable unicode box-drawing characters to + In terminal output, you can enable unicode box-drawing characters to render prettier tables: - o if the --pretty option is given a value of yes or always (or no or + o if the --pretty option is given a value of yes or always (or no or never), unicode characters will (or will not) be used; o otherwise, unicode characters will not be used. Paging - When showing long output in the terminal, hledger will try to use the - pager specified by the PAGER environment variable, or less, or more. - (A pager is a helper program that shows one page at a time rather than + When showing long output in the terminal, hledger will try to use the + pager specified by the PAGER environment variable, or less, or more. + (A pager is a helper program that shows one page at a time rather than scrolling everything off screen). Currently it does this only for help output, not for reports; specifically, @@ -697,23 +702,23 @@ Output o when viewing manuals with hledger help or hledger --man. - Note the pager is expected to handle ANSI codes, which hledger uses eg + Note the pager is expected to handle ANSI codes, which hledger uses eg for bold emphasis. For the common pager less (and its more compatibil- - ity mode), we add R to the LESS and MORE environment variables to make - this work. If you use a different pager, you might need to configure + ity mode), we add R to the LESS and MORE environment variables to make + this work. If you use a different pager, you might need to configure it similarly, to avoid seeing junk on screen (let us know). Otherwise, - you can set the NO_COLOR environment variable to 1 to disable all ANSI + you can set the NO_COLOR environment variable to 1 to disable all ANSI output (see Colour). Debug output We intend hledger to be relatively easy to troubleshoot, introspect and - develop. You can add --debug[=N] to any hledger command line to see - additional debug output. N ranges from 1 (least output, the default) - to 9 (maximum output). Typically you would start with 1 and increase - until you are seeing enough. Debug output goes to stderr, and is not + develop. You can add --debug[=N] to any hledger command line to see + additional debug output. N ranges from 1 (least output, the default) + to 9 (maximum output). Typically you would start with 1 and increase + until you are seeing enough. Debug output goes to stderr, and is not affected by -o/--output-file (unless you redirect stderr to stdout, eg: - 2>&1). It will be interleaved with normal output, which can help re- - veal when parts of the code are evaluated. To capture debug output in + 2>&1). It will be interleaved with normal output, which can help re- + veal when parts of the code are evaluated. To capture debug output in a log file instead, you can usually redirect stderr, eg: hledger bal --debug=3 2>hledger.log @@ -721,16 +726,16 @@ Output Environment These environment variables affect hledger: - COLUMNS This is normally set by your terminal; some hledger commands - (register) will format their output to this width. If not set, they + COLUMNS This is normally set by your terminal; some hledger commands + (register) will format their output to this width. If not set, they will try to use the available terminal width. - LEDGER_FILE The main journal file to use when not specified with + LEDGER_FILE The main journal file to use when not specified with -f/--file. Default: $HOME/.hledger.journal. - NO_COLOR If this environment variable is set (with any value), hledger - will not use ANSI color codes in terminal output, unless overridden by - an explicit --color/--colour option. + NO_COLOR If this environment variable exists (with any value, including + empty), hledger will not use ANSI color codes in terminal output, un- + less overridden by an explicit --color=y/--colour=y option. PART 2: DATA FORMATS Journal @@ -2670,20 +2675,40 @@ Journal Secondary dates A secondary date is written after the primary date, following an equals - sign. If the year is omitted, the primary date's year is assumed. - When running reports, the primary (left) date is used by default, but - with the --date2 flag (or --aux-date or --effective), the secondary - (right) date will be used instead. + sign: DATE1=DATE2. If the year is omitted, the primary date's year is + assumed. When running reports, the primary (left side) date is used by + default, but with the --date2 flag (--aux-date or--effective also work, + for Ledger users), the secondary (right side) date will be used in- + stead. - The meaning of secondary dates is up to you, but it's best to follow a - consistent rule. Eg "primary = the bank's clearing date, secondary = - date the transaction was initiated, if different". + The meaning of secondary dates is up to you. Eg it could be "primary + is the bank's clearing date, secondary is the date the transaction was + initiated, if different". - Downsides: makes your financial data more complicated, less portable, - and less trustworthy in an audit. Keeping the meaning of the two dates - consistent requires discipline, and you have to remember which report- - ing mode is appropriate for a given report. Posting dates are simpler - and better. + In practice, this feature usually adds confusion: + + o You have to remember the primary and secondary dates' meaning, and + follow that consistently. + + o It splits your bookkeeping into two modes, and you have to remember + which mode is appropriate for a given report. + + o Usually your balance assertions will work with only one of these + modes. + + o It makes your financial data more complicated, less portable, and + less clear in an audit. + + o It interacts with every feature, creating an ongoing cost for imple- + mentors. + + o It distracts new users and supporters. + + o Posting dates are simpler and work better. + + So secondary dates are officially deprecated in hledger, remaining only + as a Ledger compatibility aid; we recommend using posting dates in- + stead. Star comments Lines beginning with * (star/asterisk) are also comment lines. This @@ -4899,37 +4924,47 @@ Pivoting -2 EUR Generating data - hledger has several features for generating data, such as: + 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 Periodic transaction rules can generate single or repeating transac- - tions following a template. These are usually dated in the future, - eg to help with forecasting. They are activated by the --forecast - option. - - o The balance command's --budget option uses these same periodic rules - to generate goals for the budget report. - - o Auto posting rules can generate extra postings on certain matched - transactions. They are always applied to forecast transactions; with - the --auto flag they are applied to transactions recorded in the - journal as well. + o Missing amounts or missing costs in transactions are inferred auto- + matically when possible. o The --infer-equity flag infers missing conversion equity postings - from @/@@ costs. And the inverse --infer-costs flag infers missing - @/@@ costs from conversion equity postings. + from @/@@ costs. - Generated data of this kind is temporary, existing only at report time. - But you can see it in the output of hledger print, and you can save - that to your journal, in effect converting it from temporary generated - data to permanent recorded data. This could be useful as a data entry - aid. + o The --infer-costs flag infers missing costs from conversion equity + postings. - If you are wondering what data is being generated and why, add the - --verbose-tags flag. In hledger print output you will see extra tags - like generated-transaction, generated-posting, and modified on gener- - ated/modified data. Also, even without --verbose-tags, generated data - always has equivalen hidden tags (with an underscore prefix), so eg you - could match generated transactions with tag:_generated-transaction. + o The --infer-market-prices flag infers P price directives from costs. + + o The --auto flag adds extra postings to transactions matched by auto + posting rules. + + o The --forecast option generates transactions from periodic transac- + tion rules. + + o The balance --budget report infers budget goals from periodic trans- + action rules. + + o Commands like close, rewrite, and hledger-interest generate transac- + tions or postings. + + 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- + 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 + 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 + tag:modified. Forecasting Forecasting, or speculative future reporting, can be useful for esti- @@ -9112,4 +9147,4 @@ LICENSE SEE ALSO hledger(1), hledger-ui(1), hledger-web(1), ledger(1) -hledger-1.33.99 May 2024 HLEDGER(1) +hledger-1.34.99 June 2024 HLEDGER(1)