diff --git a/hledger-lib/.date.m4 b/hledger-lib/.date.m4 index 4e27a764744..705091ff8ff 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 4e27a764744..705091ff8ff 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 65e800cbd9b..5b37f9699f6 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.34 " "hledger User Manuals" +.TH "HLEDGER\-UI" "1" "June 2024" "hledger-ui-1.34 " "hledger User Manuals" @@ -11,6 +11,10 @@ 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.34. @@ -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 -.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 +.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 +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 0d6c1baa080..2d64ae28c20 100644 --- a/hledger-ui/hledger-ui.info +++ b/hledger-ui/hledger-ui.info @@ -15,6 +15,7 @@ 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.34. See @@ -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. - - hledger-ui provides the following options: - -'-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 -=================== +Any arguments are interpreted as a hledger query which filters the data. +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 + + 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 - -5 TIPS -****** - -* Menu: +File: hledger-ui.info, Node: WATCH MODE, Next: ENVIRONMENT, Prev: SCREENS, Up: Top -* 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: OPTIONS1861 -Ref: #options1959 -Node: General options2926 -Ref: #general-options3030 -Node: MOUSE8180 -Ref: #mouse8275 -Node: KEYS8512 -Ref: #keys8605 -Node: SCREENS13260 -Ref: #screens13358 -Node: Menu screen13994 -Ref: #menu-screen14115 -Node: Cash accounts screen14310 -Ref: #cash-accounts-screen14487 -Node: Balance sheet accounts screen14671 -Ref: #balance-sheet-accounts-screen14887 -Node: Income statement accounts screen15007 -Ref: #income-statement-accounts-screen15228 -Node: All accounts screen15392 -Ref: #all-accounts-screen15573 -Node: Register screen15755 -Ref: #register-screen15914 -Node: Transaction screen18198 -Ref: #transaction-screen18356 -Node: Error screen19773 -Ref: #error-screen19895 -Node: TIPS20139 -Ref: #tips20238 -Node: Watch mode20280 -Ref: #watch-mode20387 -Node: Debug output21846 -Ref: #debug-output21957 -Node: ENVIRONMENT22169 -Ref: #environment22279 -Node: BUGS22470 -Ref: #bugs22553 +Node: OPTIONS1870 +Ref: #options1968 +Node: MOUSE8148 +Ref: #mouse8243 +Node: KEYS8480 +Ref: #keys8573 +Node: SCREENS13228 +Ref: #screens13332 +Node: Menu screen13968 +Ref: #menu-screen14089 +Node: Cash accounts screen14284 +Ref: #cash-accounts-screen14461 +Node: Balance sheet accounts screen14645 +Ref: #balance-sheet-accounts-screen14861 +Node: Income statement accounts screen14981 +Ref: #income-statement-accounts-screen15202 +Node: All accounts screen15366 +Ref: #all-accounts-screen15547 +Node: Register screen15729 +Ref: #register-screen15888 +Node: Transaction screen18172 +Ref: #transaction-screen18330 +Node: Error screen19747 +Ref: #error-screen19869 +Node: WATCH MODE20113 +Ref: #watch-mode20230 +Node: ENVIRONMENT21689 +Ref: #environment21805 +Node: BUGS21996 +Ref: #bugs22079  End Tag Table diff --git a/hledger-ui/hledger-ui.txt b/hledger-ui/hledger-ui.txt index 46c1304183e..32861134748 100644 --- a/hledger-ui/hledger-ui.txt +++ b/hledger-ui/hledger-ui.txt @@ -7,6 +7,7 @@ NAME SYNOPSIS hledger-ui [OPTS] [QUERYARGS] + or hledger ui -- [OPTS] [QUERYARGS] DESCRIPTION @@ -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: + + 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 + + and also supports many of hledger's general options: - hledger-ui provides the following options: - - -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): - - 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.34 May 2024 HLEDGER-UI(1) +hledger-ui-1.34 June 2024 HLEDGER-UI(1) diff --git a/hledger-web/.date.m4 b/hledger-web/.date.m4 index 4e27a764744..705091ff8ff 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 671fd555b8f..6dc904b533d 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.34 " "hledger User Manuals" +.TH "HLEDGER\-WEB" "1" "June 2024" "hledger-web-1.34 " "hledger User Manuals" @@ -7,11 +7,15 @@ 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.34. See also the hledger manual for common concepts and file formats. @@ -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 hledger\-web listens only on IP address \f[CR]127.0.0.1\f[R], +which be accessed only from the local machine. .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) +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 9375bf5d499..cf3b00ba5b5 100644 --- a/hledger-web/hledger-web.info +++ b/hledger-web/hledger-web.info @@ -14,8 +14,9 @@ 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.34. See also the hledger manual for common concepts and file formats. @@ -78,54 +79,43 @@ File: hledger-web.info, Node: OPTIONS, Next: PERMISSIONS, Prev: Top, Up: Top hledger-web provides the following options: -'--serve' - - serve and log requests, don't browse or auto-exit after timeout -'--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) - - 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) +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 + + By default hledger-web listens only on IP address '127.0.0.1', which +be accessed only from the local machine. + + 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: OPTIONS2605 -Ref: #options2710 -Node: General options5614 -Ref: #general-options5719 -Node: PERMISSIONS10869 -Ref: #permissions11008 -Node: EDITING UPLOADING DOWNLOADING12220 -Ref: #editing-uploading-downloading12401 -Node: RELOADING13235 -Ref: #reloading13369 -Node: JSON API13802 -Ref: #json-api13917 -Node: DEBUG OUTPUT19405 -Ref: #debug-output19530 -Node: Debug output19557 -Ref: #debug-output-119658 -Node: ENVIRONMENT20075 -Ref: #environment20194 -Node: BUGS20311 -Ref: #bugs20395 +Node: OPTIONS2566 +Ref: #options2671 +Node: PERMISSIONS10859 +Ref: #permissions10998 +Node: EDITING UPLOADING DOWNLOADING12210 +Ref: #editing-uploading-downloading12391 +Node: RELOADING13225 +Ref: #reloading13359 +Node: JSON API13792 +Ref: #json-api13907 +Node: DEBUG OUTPUT19441 +Ref: #debug-output19566 +Node: Debug output19593 +Ref: #debug-output-119694 +Node: ENVIRONMENT20111 +Ref: #environment20230 +Node: BUGS20347 +Ref: #bugs20431  End Tag Table diff --git a/hledger-web/hledger-web.txt b/hledger-web/hledger-web.txt index fa577d26317..584a8362ba6 100644 --- a/hledger-web/hledger-web.txt +++ b/hledger-web/hledger-web.txt @@ -6,8 +6,9 @@ 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.34. See also the @@ -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 - - --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 per- - missions 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 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 + 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 + + By default hledger-web listens only on IP address 127.0.0.1, which be + accessed only from the local machine. + + 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. + + 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. 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. + hledger-web also supports many of hledger's general options: - 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.34 May 2024 HLEDGER-WEB(1) +hledger-web-1.34 June 2024 HLEDGER-WEB(1) diff --git a/hledger/.date.m4 b/hledger/.date.m4 index 4e27a764744..705091ff8ff 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 023a4520c17..f47c0505958 100644 --- a/hledger/hledger.1 +++ b/hledger/hledger.1 @@ -1,6 +1,6 @@ .\"t -.TH "HLEDGER" "1" "May 2024" "hledger-1.34 " "hledger User Manuals" +.TH "HLEDGER" "1" "June 2024" "hledger-1.34 " "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 COMMAND [OPTS] [ARGS]\f[R] +.PD 0 +.P +.PD +or .PD 0 .P .PD -\f[CR]hledger ADDONCMD \-\- [OPTS] [ARGS]\f[R] +\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 @@ -226,8 +234,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:\- @@ -328,9 +336,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: @@ -399,7 +407,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. @@ -408,19 +415,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 @@ -885,6 +897,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. @@ -1017,9 +1030,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 @@ -3410,24 +3424,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. @@ -6334,42 +6363,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. -.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. -.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]. +.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 +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 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 42d06ce0182..afaab59499a 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 @@ -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 - -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 +File: hledger.info, Node: Special characters, Next: Unicode characters, Up: Options -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. - - 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". - - 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. +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. Eg it could be "primary +is the bank's clearing date, secondary is the date the transaction was +initiated, if different". + + 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. - - 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. - - 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'. + 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. + + 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 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 INTERFACE4266 -Ref: #part-1-user-interface4405 -Node: Input4405 -Ref: #input4515 -Node: Text encoding5482 -Ref: #text-encoding5596 -Node: Data formats6162 -Ref: #data-formats6297 -Node: Standard input7886 -Ref: #standard-input8026 -Node: Multiple files8253 -Ref: #multiple-files8392 -Node: Strict mode8990 -Ref: #strict-mode9100 -Node: Commands9824 -Ref: #commands9926 -Node: Add-on commands10993 -Ref: #add-on-commands11095 -Node: Options12211 -Ref: #options12323 -Node: Command line tips17715 -Ref: #command-line-tips17845 -Node: Option repetition18104 -Ref: #option-repetition18248 -Node: Special characters18352 -Ref: #special-characters18525 -Node: Single escaping shell metacharacters18688 -Ref: #single-escaping-shell-metacharacters18929 -Node: Double escaping regular expression metacharacters19532 -Ref: #double-escaping-regular-expression-metacharacters19843 -Node: Triple escaping for add-on commands20369 -Ref: #triple-escaping-for-add-on-commands20629 -Node: Less escaping21273 -Ref: #less-escaping21427 -Node: Unicode characters21751 -Ref: #unicode-characters21926 -Node: Regular expressions23425 -Ref: #regular-expressions23598 -Node: hledger's regular expressions26694 -Ref: #hledgers-regular-expressions26853 -Node: Argument files28239 -Ref: #argument-files28375 -Node: Output28872 -Ref: #output28984 -Node: Output destination29111 -Ref: #output-destination29242 -Node: Output format29667 -Ref: #output-format29813 -Node: CSV output31410 -Ref: #csv-output31526 -Node: HTML output31629 -Ref: #html-output31767 -Node: JSON output31861 -Ref: #json-output31999 -Node: SQL output32921 -Ref: #sql-output33037 -Node: Commodity styles33772 -Ref: #commodity-styles33912 -Node: Colour34650 -Ref: #colour34768 -Node: Box-drawing35172 -Ref: #box-drawing35290 -Node: Paging35580 -Ref: #paging35694 -Node: Debug output36647 -Ref: #debug-output36753 -Node: Environment37416 -Ref: #environment37540 -Node: PART 2 DATA FORMATS38084 -Ref: #part-2-data-formats38227 -Node: Journal38227 -Ref: #journal38336 -Node: Journal cheatsheet40704 -Ref: #journal-cheatsheet40831 -Node: Comments46918 -Ref: #comments47046 -Node: Transactions47862 -Ref: #transactions47985 -Node: Dates48999 -Ref: #dates49106 -Node: Simple dates49151 -Ref: #simple-dates49267 -Node: Posting dates49767 -Ref: #posting-dates49885 -Node: Status50854 -Ref: #status50955 -Node: Code52620 -Ref: #code52723 -Node: Description52955 -Ref: #description53086 -Node: Payee and note53642 -Ref: #payee-and-note53748 -Node: Transaction comments54733 -Ref: #transaction-comments54886 -Node: Postings55249 -Ref: #postings55380 -Node: Debits and credits56412 -Ref: #debits-and-credits56559 -Node: The two space delimiter57022 -Ref: #the-two-space-delimiter57179 -Node: Account names57587 -Ref: #account-names57717 -Node: Amounts59391 -Ref: #amounts59519 -Node: Decimal marks60420 -Ref: #decimal-marks60547 -Node: Digit group marks61524 -Ref: #digit-group-marks61677 -Node: Commodity62159 -Ref: #commodity62288 -Node: Costs63276 -Ref: #costs63371 -Node: Balance assertions65528 -Ref: #balance-assertions65681 -Node: Assertions and ordering66765 -Ref: #assertions-and-ordering66954 -Node: Assertions and multiple included files67493 -Ref: #assertions-and-multiple-included-files67753 -Node: Assertions and multiple -f files68253 -Ref: #assertions-and-multiple--f-files68498 -Node: Assertions and costs68895 -Ref: #assertions-and-costs69104 -Node: Assertions and commodities69545 -Ref: #assertions-and-commodities69760 -Node: Assertions and subaccounts71204 -Ref: #assertions-and-subaccounts71430 -Node: Assertions and virtual postings71874 -Ref: #assertions-and-virtual-postings72112 -Node: Assertions and auto postings72244 -Ref: #assertions-and-auto-postings72474 -Node: Assertions and precision73119 -Ref: #assertions-and-precision73301 -Node: Posting comments73568 -Ref: #posting-comments73731 -Node: Transaction balancing74108 -Ref: #transaction-balancing74267 -Node: Tags76110 -Ref: #tags76229 -Node: Tag names77572 -Ref: #tag-names77679 -Node: Special tags78067 -Ref: #special-tags78199 -Node: Tag values79712 -Ref: #tag-values79822 -Node: Directives80694 -Ref: #directives80821 -Node: Directives and multiple files82151 -Ref: #directives-and-multiple-files82329 -Node: Directive effects83096 -Ref: #directive-effects83250 -Node: account directive86252 -Ref: #account-directive86408 -Node: Account comments87702 -Ref: #account-comments87853 -Node: Account error checking88361 -Ref: #account-error-checking88554 -Node: Account display order89743 -Ref: #account-display-order89931 -Node: Account types90941 -Ref: #account-types91082 -Node: alias directive94715 -Ref: #alias-directive94876 -Node: Basic aliases95926 -Ref: #basic-aliases96057 -Node: Regex aliases96801 -Ref: #regex-aliases96958 -Node: Combining aliases97848 -Ref: #combining-aliases98026 -Node: Aliases and multiple files99302 -Ref: #aliases-and-multiple-files99506 -Node: end aliases directive100085 -Ref: #end-aliases-directive100304 -Node: Aliases can generate bad account names100453 -Ref: #aliases-can-generate-bad-account-names100701 -Node: Aliases and account types101286 -Ref: #aliases-and-account-types101478 -Node: commodity directive102174 -Ref: #commodity-directive102348 -Node: Commodity directive syntax103761 -Ref: #commodity-directive-syntax103946 -Node: Commodity error checking105397 -Ref: #commodity-error-checking105578 -Node: decimal-mark directive105872 -Ref: #decimal-mark-directive106054 -Node: include directive106451 -Ref: #include-directive106615 -Node: P directive107527 -Ref: #p-directive107672 -Node: payee directive108561 -Ref: #payee-directive108710 -Node: tag directive109183 -Ref: #tag-directive109338 -Node: Periodic transactions109795 -Ref: #periodic-transactions109960 -Node: Periodic rule syntax111949 -Ref: #periodic-rule-syntax112127 -Node: Periodic rules and relative dates112772 -Ref: #periodic-rules-and-relative-dates113038 -Node: Two spaces between period expression and description!113549 -Ref: #two-spaces-between-period-expression-and-description113826 -Node: Auto postings114510 -Ref: #auto-postings114658 -Node: Auto postings and multiple files117488 -Ref: #auto-postings-and-multiple-files117652 -Node: Auto postings and dates118053 -Ref: #auto-postings-and-dates118301 -Node: Auto postings and transaction balancing / inferred amounts / balance assertions118476 -Ref: #auto-postings-and-transaction-balancing-inferred-amounts-balance-assertions118832 -Node: Auto posting tags119335 -Ref: #auto-posting-tags119617 -Node: Auto postings on forecast transactions only120253 -Ref: #auto-postings-on-forecast-transactions-only120499 -Node: Other syntax120746 -Ref: #other-syntax120862 -Node: Balance assignments121518 -Ref: #balance-assignments121674 -Node: Balance assignments and costs123046 -Ref: #balance-assignments-and-costs123258 -Node: Balance assignments and multiple files123468 -Ref: #balance-assignments-and-multiple-files123698 -Node: Bracketed posting dates123891 -Ref: #bracketed-posting-dates124075 -Node: D directive124589 -Ref: #d-directive124757 -Node: apply account directive126362 -Ref: #apply-account-directive126542 -Node: Y directive127229 -Ref: #y-directive127389 -Node: Secondary dates128217 -Ref: #secondary-dates128371 -Node: Star comments129185 -Ref: #star-comments129345 -Node: Valuation expressions129877 -Ref: #valuation-expressions130054 -Node: Virtual postings130176 -Ref: #virtual-postings130353 -Node: Other Ledger directives131800 -Ref: #other-ledger-directives131996 -Node: Other cost/lot notations132562 -Ref: #other-costlot-notations132735 -Node: CSV135324 -Ref: #csv135417 -Node: CSV rules cheatsheet137414 -Ref: #csv-rules-cheatsheet137543 -Node: source139341 -Ref: #source139464 -Node: separator140344 -Ref: #separator140457 -Node: skip140997 -Ref: #skip141105 -Node: date-format141649 -Ref: #date-format141770 -Node: timezone142494 -Ref: #timezone142617 -Node: newest-first143622 -Ref: #newest-first143760 -Node: intra-day-reversed144337 -Ref: #intra-day-reversed144491 -Node: decimal-mark144939 -Ref: #decimal-mark145080 -Node: fields list145419 -Ref: #fields-list145558 -Node: Field assignment147229 -Ref: #field-assignment147373 -Node: Field names148450 -Ref: #field-names148581 -Node: date field149784 -Ref: #date-field149902 -Node: date2 field149950 -Ref: #date2-field150091 -Node: status field150147 -Ref: #status-field150290 -Node: code field150339 -Ref: #code-field150484 -Node: description field150529 -Ref: #description-field150689 -Node: comment field150748 -Ref: #comment-field150903 -Node: account field151196 -Ref: #account-field151346 -Node: amount field151916 -Ref: #amount-field152065 -Node: currency field154757 -Ref: #currency-field154910 -Node: balance field155167 -Ref: #balance-field155299 -Node: if block155692 -Ref: #if-block155813 -Node: Matchers157221 -Ref: #matchers157335 -Node: What matchers match158132 -Ref: #what-matchers-match158281 -Node: Combining matchers158721 -Ref: #combining-matchers158889 -Node: Match groups159426 -Ref: #match-groups159554 -Node: if table160322 -Ref: #if-table160444 -Node: balance-type162325 -Ref: #balance-type162454 -Node: include163154 -Ref: #include163281 -Node: Working with CSV163725 -Ref: #working-with-csv163872 -Node: Rapid feedback164279 -Ref: #rapid-feedback164412 -Node: Valid CSV164864 -Ref: #valid-csv165010 -Node: File Extension165742 -Ref: #file-extension165915 -Node: Reading CSV from standard input166479 -Ref: #reading-csv-from-standard-input166703 -Node: Reading multiple CSV files166867 -Ref: #reading-multiple-csv-files167098 -Node: Reading files specified by rule167339 -Ref: #reading-files-specified-by-rule167567 -Node: Valid transactions168738 -Ref: #valid-transactions168937 -Node: Deduplicating importing169565 -Ref: #deduplicating-importing169760 -Node: Setting amounts170796 -Ref: #setting-amounts170967 -Node: Amount signs173325 -Ref: #amount-signs173495 -Node: Setting currency/commodity174392 -Ref: #setting-currencycommodity174596 -Node: Amount decimal places175770 -Ref: #amount-decimal-places175976 -Node: Referencing other fields177029 -Ref: #referencing-other-fields177242 -Node: How CSV rules are evaluated178139 -Ref: #how-csv-rules-are-evaluated178356 -Node: Well factored rules179809 -Ref: #well-factored-rules179977 -Node: CSV rules examples180301 -Ref: #csv-rules-examples180436 -Node: Bank of Ireland180501 -Ref: #bank-of-ireland180638 -Node: Coinbase182100 -Ref: #coinbase182238 -Node: Amazon183285 -Ref: #amazon183410 -Node: Paypal185129 -Ref: #paypal185237 -Node: Timeclock192881 -Ref: #timeclock192986 -Node: Timedot195162 -Ref: #timedot195285 -Node: Timedot examples198406 -Ref: #timedot-examples198512 -Node: PART 3 REPORTING CONCEPTS200683 -Ref: #part-3-reporting-concepts200847 -Node: Time periods200847 -Ref: #time-periods200981 -Node: Report start & end date201099 -Ref: #report-start-end-date201251 -Node: Smart dates202575 -Ref: #smart-dates202728 -Node: Report intervals204518 -Ref: #report-intervals204673 -Node: Date adjustment205091 -Ref: #date-adjustment205251 -Node: Period expressions206102 -Ref: #period-expressions206243 -Node: Period expressions with a report interval208007 -Ref: #period-expressions-with-a-report-interval208241 -Node: More complex report intervals208455 -Ref: #more-complex-report-intervals208700 -Node: Multiple weekday intervals210561 -Ref: #multiple-weekday-intervals210750 -Node: Depth211572 -Ref: #depth211674 -Node: Queries211970 -Ref: #queries212072 -Node: Query types213668 -Ref: #query-types213789 -Node: Combining query terms217023 -Ref: #combining-query-terms217200 -Node: Queries and command options218763 -Ref: #queries-and-command-options218968 -Node: Queries and account aliases219217 -Ref: #queries-and-account-aliases219422 -Node: Queries and valuation219542 -Ref: #queries-and-valuation219699 -Node: Pivoting219904 -Ref: #pivoting220018 -Node: Generating data221795 -Ref: #generating-data221927 -Node: Forecasting223510 -Ref: #forecasting223635 -Node: --forecast224166 -Ref: #forecast224297 -Node: Inspecting forecast transactions225267 -Ref: #inspecting-forecast-transactions225469 -Node: Forecast reports226599 -Ref: #forecast-reports226772 -Node: Forecast tags227708 -Ref: #forecast-tags227868 -Node: Forecast period in detail228328 -Ref: #forecast-period-in-detail228522 -Node: Forecast troubleshooting229416 -Ref: #forecast-troubleshooting229584 -Node: Budgeting230487 -Ref: #budgeting230610 -Node: Amount formatting231047 -Ref: #amount-formatting231189 -Node: Commodity display style231291 -Ref: #commodity-display-style231445 -Node: Rounding233132 -Ref: #rounding233287 -Node: Trailing decimal marks233737 -Ref: #trailing-decimal-marks233916 -Node: Amount parseability234670 -Ref: #amount-parseability234826 -Node: Cost reporting236251 -Ref: #cost-reporting236393 -Node: Recording costs237054 -Ref: #recording-costs237190 -Node: Reporting at cost238781 -Ref: #reporting-at-cost238956 -Node: Equity conversion postings239546 -Ref: #equity-conversion-postings239760 -Node: Inferring equity conversion postings242191 -Ref: #inferring-equity-conversion-postings242454 -Node: Combining costs and equity conversion postings243206 -Ref: #combining-costs-and-equity-conversion-postings243516 -Node: Requirements for detecting equity conversion postings244431 -Ref: #requirements-for-detecting-equity-conversion-postings244753 -Node: Infer cost and equity by default ?245953 -Ref: #infer-cost-and-equity-by-default246182 -Node: Value reporting246390 -Ref: #value-reporting246532 -Node: -V Value247271 -Ref: #v-value247403 -Node: -X Value in specified commodity247598 -Ref: #x-value-in-specified-commodity247799 -Node: Valuation date247948 -Ref: #valuation-date248125 -Node: Finding market price248908 -Ref: #finding-market-price249119 -Node: --infer-market-prices market prices from transactions250288 -Ref: #infer-market-prices-market-prices-from-transactions250570 -Node: Valuation commodity253332 -Ref: #valuation-commodity253552 -Node: --value Flexible valuation254765 -Ref: #value-flexible-valuation254964 -Node: Valuation examples256608 -Ref: #valuation-examples256808 -Node: Interaction of valuation and queries258740 -Ref: #interaction-of-valuation-and-queries258980 -Node: Effect of valuation on reports259457 -Ref: #effect-of-valuation-on-reports259660 -Node: PART 4 COMMANDS267355 -Ref: #part-4-commands267498 -Node: Help commands269571 -Ref: #help-commands269716 -Node: help269744 -Ref: #help269833 -Node: demo271202 -Ref: #demo271291 -Node: User interface commands272207 -Ref: #user-interface-commands272376 -Node: ui272401 -Ref: #ui272493 -Node: web272526 -Ref: #web272620 -Node: Data entry commands272654 -Ref: #data-entry-commands272823 -Node: add272852 -Ref: #add272946 -Node: import275337 -Ref: #import275437 -Node: Date skipping276445 -Ref: #date-skipping276568 -Node: Import testing279346 -Ref: #import-testing279509 -Node: Importing balance assignments280352 -Ref: #importing-balance-assignments280559 -Node: Import and commodity styles281208 -Ref: #import-and-commodity-styles281388 -Node: Basic report commands281617 -Ref: #basic-report-commands281791 -Node: accounts281918 -Ref: #accounts282028 -Node: codes283915 -Ref: #codes284039 -Node: commodities284903 -Ref: #commodities285043 -Node: descriptions285113 -Ref: #descriptions285255 -Node: files285546 -Ref: #files285668 -Node: notes285809 -Ref: #notes285925 -Node: payees286287 -Ref: #payees286406 -Node: prices286925 -Ref: #prices287044 -Node: stats287697 -Ref: #stats287812 -Node: tags289326 -Ref: #tags-1289426 -Node: Standard report commands290435 -Ref: #standard-report-commands290620 -Node: print290740 -Ref: #print290848 -Node: print explicitness291828 -Ref: #print-explicitness291969 -Node: print amount style292748 -Ref: #print-amount-style292916 -Node: print parseability293986 -Ref: #print-parseability294156 -Node: print other features294905 -Ref: #print-other-features295082 -Node: print output format295603 -Ref: #print-output-format295749 -Node: aregister298888 -Ref: #aregister299021 -Node: aregister and posting dates301902 -Ref: #aregister-and-posting-dates302047 -Node: register302803 -Ref: #register302941 -Node: Custom register output307972 -Ref: #custom-register-output308101 -Node: balancesheet309448 -Ref: #balancesheet309603 -Node: balancesheetequity311265 -Ref: #balancesheetequity311432 -Node: cashflow313452 -Ref: #cashflow313602 -Node: incomestatement315089 -Ref: #incomestatement315226 -Node: Advanced report commands316762 -Ref: #advanced-report-commands316940 -Node: balance316970 -Ref: #balance317078 -Node: balance features318237 -Ref: #balance-features318377 -Node: Simple balance report320287 -Ref: #simple-balance-report320472 -Node: Balance report line format322097 -Ref: #balance-report-line-format322299 -Node: Filtered balance report324457 -Ref: #filtered-balance-report324649 -Node: List or tree mode324976 -Ref: #list-or-tree-mode325144 -Node: Depth limiting326489 -Ref: #depth-limiting326655 -Node: Dropping top-level accounts327256 -Ref: #dropping-top-level-accounts327456 -Node: Showing declared accounts327766 -Ref: #showing-declared-accounts327965 -Node: Sorting by amount328496 -Ref: #sorting-by-amount328663 -Node: Percentages329333 -Ref: #percentages329492 -Node: Multi-period balance report330040 -Ref: #multi-period-balance-report330240 -Node: Balance change end balance332792 -Ref: #balance-change-end-balance333001 -Node: Balance report types334429 -Ref: #balance-report-types334610 -Node: Calculation type335108 -Ref: #calculation-type335263 -Node: Accumulation type335812 -Ref: #accumulation-type335992 -Node: Valuation type336913 -Ref: #valuation-type337101 -Node: Combining balance report types338102 -Ref: #combining-balance-report-types338296 -Node: Budget report340134 -Ref: #budget-report340296 -Node: Using the budget report342439 -Ref: #using-the-budget-report342612 -Node: Budget date surprises344715 -Ref: #budget-date-surprises344915 -Node: Selecting budget goals346079 -Ref: #selecting-budget-goals346282 -Node: Budgeting vs forecasting347027 -Ref: #budgeting-vs-forecasting347204 -Node: Balance report layout348704 -Ref: #balance-report-layout348889 -Node: Wide layout349842 -Ref: #wide-layout349977 -Node: Tall layout352247 -Ref: #tall-layout352402 -Node: Bare layout353553 -Ref: #bare-layout353708 -Node: Tidy layout355612 -Ref: #tidy-layout355747 -Node: Some useful balance reports357156 -Ref: #some-useful-balance-reports357331 -Node: roi358416 -Ref: #roi358516 -Node: Spaces and special characters in --inv and --pnl360328 -Ref: #spaces-and-special-characters-in---inv-and---pnl360566 -Node: Semantics of --inv and --pnl361054 -Ref: #semantics-of---inv-and---pnl361291 -Node: IRR and TWR explained363141 -Ref: #irr-and-twr-explained363299 -Node: Chart commands366552 -Ref: #chart-commands366710 -Node: activity366733 -Ref: #activity366822 -Node: Data generation commands367196 -Ref: #data-generation-commands367370 -Node: close367402 -Ref: #close367508 -Node: close --migrate368161 -Ref: #close---migrate368286 -Node: close --close369925 -Ref: #close---close370067 -Node: close --open370303 -Ref: #close---open370442 -Node: close --assert370552 -Ref: #close---assert370696 -Node: close --assign370917 -Ref: #close---assign371063 -Node: close --retain371589 -Ref: #close---retain371740 -Node: close customisation372485 -Ref: #close-customisation372662 -Node: close and balance assertions374129 -Ref: #close-and-balance-assertions374324 -Node: close examples375651 -Ref: #close-examples375790 -Node: Retain earnings375888 -Ref: #retain-earnings376045 -Node: Migrate balances to a new file376391 -Ref: #migrate-balances-to-a-new-file376615 -Node: More detailed close examples377743 -Ref: #more-detailed-close-examples377939 -Node: rewrite377965 -Ref: #rewrite378075 -Node: Re-write rules in a file379973 -Ref: #re-write-rules-in-a-file380134 -Node: Diff output format381283 -Ref: #diff-output-format381464 -Node: rewrite vs print --auto382556 -Ref: #rewrite-vs.-print---auto382714 -Node: Maintenance commands383270 -Ref: #maintenance-commands383441 -Node: check383479 -Ref: #check383578 -Node: Basic checks384527 -Ref: #basic-checks384645 -Node: Strict checks385480 -Ref: #strict-checks385621 -Node: Other checks386355 -Ref: #other-checks386495 -Node: Custom checks388210 -Ref: #custom-checks388330 -Node: diff388665 -Ref: #diff388775 -Node: test389817 -Ref: #test389913 -Node: PART 5 COMMON TASKS390655 -Ref: #part-5-common-tasks390814 -Node: Getting help390888 -Ref: #getting-help391037 -Node: Constructing command lines391797 -Ref: #constructing-command-lines391978 -Node: Starting a journal file392635 -Ref: #starting-a-journal-file392817 -Node: Setting LEDGER_FILE394019 -Ref: #setting-ledger_file394191 -Node: Setting opening balances395148 -Ref: #setting-opening-balances395329 -Node: Recording transactions398470 -Ref: #recording-transactions398639 -Node: Reconciling399195 -Ref: #reconciling399327 -Node: Reporting401584 -Ref: #reporting401713 -Node: Migrating to a new file405698 -Ref: #migrating-to-a-new-file405848 -Node: BUGS406147 -Ref: #bugs406241 -Node: Troubleshooting407120 -Ref: #troubleshooting407220 +Node: PART 1 USER INTERFACE4267 +Ref: #part-1-user-interface4406 +Node: Input4406 +Ref: #input4516 +Node: Text encoding5483 +Ref: #text-encoding5597 +Node: Data formats6163 +Ref: #data-formats6298 +Node: Standard input7887 +Ref: #standard-input8027 +Node: Multiple files8276 +Ref: #multiple-files8415 +Node: Strict mode9013 +Ref: #strict-mode9123 +Node: Commands9847 +Ref: #commands9949 +Node: Add-on commands11016 +Ref: #add-on-commands11118 +Node: Options12234 +Ref: #options12335 +Node: Special characters18185 +Ref: #special-characters18322 +Node: Single escaping shell metacharacters18485 +Ref: #single-escaping-shell-metacharacters18726 +Node: Double escaping regular expression metacharacters19329 +Ref: #double-escaping-regular-expression-metacharacters19640 +Node: Triple escaping for add-on commands20166 +Ref: #triple-escaping-for-add-on-commands20426 +Node: Less escaping21070 +Ref: #less-escaping21224 +Node: Unicode characters21548 +Ref: #unicode-characters21713 +Node: Regular expressions23212 +Ref: #regular-expressions23375 +Node: hledger's regular expressions26471 +Ref: #hledgers-regular-expressions26630 +Node: Argument files28016 +Ref: #argument-files28142 +Node: Output28639 +Ref: #output28741 +Node: Output destination28868 +Ref: #output-destination28999 +Node: Output format29424 +Ref: #output-format29570 +Node: CSV output31167 +Ref: #csv-output31283 +Node: HTML output31386 +Ref: #html-output31524 +Node: JSON output31618 +Ref: #json-output31756 +Node: SQL output32741 +Ref: #sql-output32857 +Node: Commodity styles33592 +Ref: #commodity-styles33732 +Node: Colour34470 +Ref: #colour34588 +Node: Box-drawing34992 +Ref: #box-drawing35110 +Node: Paging35400 +Ref: #paging35514 +Node: Debug output36467 +Ref: #debug-output36573 +Node: Environment37236 +Ref: #environment37360 +Node: PART 2 DATA FORMATS37927 +Ref: #part-2-data-formats38070 +Node: Journal38070 +Ref: #journal38179 +Node: Journal cheatsheet40547 +Ref: #journal-cheatsheet40674 +Node: Comments46761 +Ref: #comments46889 +Node: Transactions47705 +Ref: #transactions47828 +Node: Dates48842 +Ref: #dates48949 +Node: Simple dates48994 +Ref: #simple-dates49110 +Node: Posting dates49610 +Ref: #posting-dates49728 +Node: Status50697 +Ref: #status50798 +Node: Code52463 +Ref: #code52566 +Node: Description52798 +Ref: #description52929 +Node: Payee and note53485 +Ref: #payee-and-note53591 +Node: Transaction comments54576 +Ref: #transaction-comments54729 +Node: Postings55092 +Ref: #postings55223 +Node: Debits and credits56255 +Ref: #debits-and-credits56402 +Node: The two space delimiter56865 +Ref: #the-two-space-delimiter57022 +Node: Account names57430 +Ref: #account-names57560 +Node: Amounts59234 +Ref: #amounts59362 +Node: Decimal marks60263 +Ref: #decimal-marks60390 +Node: Digit group marks61367 +Ref: #digit-group-marks61520 +Node: Commodity62002 +Ref: #commodity62131 +Node: Costs63119 +Ref: #costs63214 +Node: Balance assertions65371 +Ref: #balance-assertions65524 +Node: Assertions and ordering66608 +Ref: #assertions-and-ordering66797 +Node: Assertions and multiple included files67336 +Ref: #assertions-and-multiple-included-files67596 +Node: Assertions and multiple -f files68096 +Ref: #assertions-and-multiple--f-files68341 +Node: Assertions and costs68738 +Ref: #assertions-and-costs68947 +Node: Assertions and commodities69388 +Ref: #assertions-and-commodities69603 +Node: Assertions and subaccounts71047 +Ref: #assertions-and-subaccounts71273 +Node: Assertions and virtual postings71717 +Ref: #assertions-and-virtual-postings71955 +Node: Assertions and auto postings72087 +Ref: #assertions-and-auto-postings72317 +Node: Assertions and precision72962 +Ref: #assertions-and-precision73144 +Node: Posting comments73411 +Ref: #posting-comments73574 +Node: Transaction balancing73951 +Ref: #transaction-balancing74110 +Node: Tags75953 +Ref: #tags76072 +Node: Tag names77415 +Ref: #tag-names77522 +Node: Special tags77910 +Ref: #special-tags78042 +Node: Tag values79555 +Ref: #tag-values79665 +Node: Directives80537 +Ref: #directives80664 +Node: Directives and multiple files81994 +Ref: #directives-and-multiple-files82172 +Node: Directive effects82939 +Ref: #directive-effects83093 +Node: account directive86095 +Ref: #account-directive86251 +Node: Account comments87545 +Ref: #account-comments87696 +Node: Account error checking88204 +Ref: #account-error-checking88397 +Node: Account display order89586 +Ref: #account-display-order89774 +Node: Account types90784 +Ref: #account-types90925 +Node: alias directive94558 +Ref: #alias-directive94719 +Node: Basic aliases95769 +Ref: #basic-aliases95900 +Node: Regex aliases96644 +Ref: #regex-aliases96801 +Node: Combining aliases97691 +Ref: #combining-aliases97869 +Node: Aliases and multiple files99145 +Ref: #aliases-and-multiple-files99349 +Node: end aliases directive99928 +Ref: #end-aliases-directive100147 +Node: Aliases can generate bad account names100296 +Ref: #aliases-can-generate-bad-account-names100544 +Node: Aliases and account types101129 +Ref: #aliases-and-account-types101321 +Node: commodity directive102017 +Ref: #commodity-directive102191 +Node: Commodity directive syntax103604 +Ref: #commodity-directive-syntax103789 +Node: Commodity error checking105240 +Ref: #commodity-error-checking105421 +Node: decimal-mark directive105715 +Ref: #decimal-mark-directive105897 +Node: include directive106294 +Ref: #include-directive106458 +Node: P directive107370 +Ref: #p-directive107515 +Node: payee directive108404 +Ref: #payee-directive108553 +Node: tag directive109026 +Ref: #tag-directive109181 +Node: Periodic transactions109638 +Ref: #periodic-transactions109803 +Node: Periodic rule syntax111792 +Ref: #periodic-rule-syntax111970 +Node: Periodic rules and relative dates112615 +Ref: #periodic-rules-and-relative-dates112881 +Node: Two spaces between period expression and description!113392 +Ref: #two-spaces-between-period-expression-and-description113669 +Node: Auto postings114353 +Ref: #auto-postings114501 +Node: Auto postings and multiple files117331 +Ref: #auto-postings-and-multiple-files117495 +Node: Auto postings and dates117896 +Ref: #auto-postings-and-dates118144 +Node: Auto postings and transaction balancing / inferred amounts / balance assertions118319 +Ref: #auto-postings-and-transaction-balancing-inferred-amounts-balance-assertions118675 +Node: Auto posting tags119178 +Ref: #auto-posting-tags119460 +Node: Auto postings on forecast transactions only120096 +Ref: #auto-postings-on-forecast-transactions-only120342 +Node: Other syntax120589 +Ref: #other-syntax120705 +Node: Balance assignments121361 +Ref: #balance-assignments121517 +Node: Balance assignments and costs122889 +Ref: #balance-assignments-and-costs123101 +Node: Balance assignments and multiple files123311 +Ref: #balance-assignments-and-multiple-files123541 +Node: Bracketed posting dates123734 +Ref: #bracketed-posting-dates123918 +Node: D directive124432 +Ref: #d-directive124600 +Node: apply account directive126205 +Ref: #apply-account-directive126385 +Node: Y directive127072 +Ref: #y-directive127232 +Node: Secondary dates128060 +Ref: #secondary-dates128214 +Node: Star comments129545 +Ref: #star-comments129705 +Node: Valuation expressions130237 +Ref: #valuation-expressions130414 +Node: Virtual postings130536 +Ref: #virtual-postings130713 +Node: Other Ledger directives132160 +Ref: #other-ledger-directives132356 +Node: Other cost/lot notations132922 +Ref: #other-costlot-notations133095 +Node: CSV135684 +Ref: #csv135775 +Node: CSV rules cheatsheet137772 +Ref: #csv-rules-cheatsheet137899 +Node: source139697 +Ref: #source139818 +Node: separator140698 +Ref: #separator140809 +Node: skip141349 +Ref: #skip141455 +Node: date-format141999 +Ref: #date-format142118 +Node: timezone142842 +Ref: #timezone142963 +Node: newest-first143968 +Ref: #newest-first144104 +Node: intra-day-reversed144681 +Ref: #intra-day-reversed144833 +Node: decimal-mark145281 +Ref: #decimal-mark145420 +Node: fields list145759 +Ref: #fields-list145896 +Node: Field assignment147567 +Ref: #field-assignment147709 +Node: Field names148786 +Ref: #field-names148915 +Node: date field150118 +Ref: #date-field150234 +Node: date2 field150282 +Ref: #date2-field150421 +Node: status field150477 +Ref: #status-field150618 +Node: code field150667 +Ref: #code-field150810 +Node: description field150855 +Ref: #description-field151013 +Node: comment field151072 +Ref: #comment-field151225 +Node: account field151518 +Ref: #account-field151666 +Node: amount field152236 +Ref: #amount-field152383 +Node: currency field155075 +Ref: #currency-field155226 +Node: balance field155483 +Ref: #balance-field155613 +Node: if block156006 +Ref: #if-block156125 +Node: Matchers157533 +Ref: #matchers157645 +Node: What matchers match158442 +Ref: #what-matchers-match158589 +Node: Combining matchers159029 +Ref: #combining-matchers159195 +Node: Match groups159732 +Ref: #match-groups159858 +Node: if table160626 +Ref: #if-table160746 +Node: balance-type162627 +Ref: #balance-type162754 +Node: include163454 +Ref: #include163579 +Node: Working with CSV164023 +Ref: #working-with-csv164168 +Node: Rapid feedback164575 +Ref: #rapid-feedback164706 +Node: Valid CSV165158 +Ref: #valid-csv165302 +Node: File Extension166034 +Ref: #file-extension166205 +Node: Reading CSV from standard input166769 +Ref: #reading-csv-from-standard-input166991 +Node: Reading multiple CSV files167155 +Ref: #reading-multiple-csv-files167384 +Node: Reading files specified by rule167625 +Ref: #reading-files-specified-by-rule167851 +Node: Valid transactions169022 +Ref: #valid-transactions169219 +Node: Deduplicating importing169847 +Ref: #deduplicating-importing170040 +Node: Setting amounts171076 +Ref: #setting-amounts171245 +Node: Amount signs173603 +Ref: #amount-signs173771 +Node: Setting currency/commodity174668 +Ref: #setting-currencycommodity174870 +Node: Amount decimal places176044 +Ref: #amount-decimal-places176248 +Node: Referencing other fields177301 +Ref: #referencing-other-fields177512 +Node: How CSV rules are evaluated178409 +Ref: #how-csv-rules-are-evaluated178624 +Node: Well factored rules180077 +Ref: #well-factored-rules180243 +Node: CSV rules examples180567 +Ref: #csv-rules-examples180700 +Node: Bank of Ireland180765 +Ref: #bank-of-ireland180900 +Node: Coinbase182362 +Ref: #coinbase182498 +Node: Amazon183545 +Ref: #amazon183668 +Node: Paypal185387 +Ref: #paypal185493 +Node: Timeclock193137 +Ref: #timeclock193242 +Node: Timedot195418 +Ref: #timedot195541 +Node: Timedot examples198662 +Ref: #timedot-examples198768 +Node: PART 3 REPORTING CONCEPTS200939 +Ref: #part-3-reporting-concepts201103 +Node: Time periods201103 +Ref: #time-periods201237 +Node: Report start & end date201355 +Ref: #report-start-end-date201507 +Node: Smart dates202831 +Ref: #smart-dates202984 +Node: Report intervals204774 +Ref: #report-intervals204929 +Node: Date adjustment205347 +Ref: #date-adjustment205507 +Node: Period expressions206358 +Ref: #period-expressions206499 +Node: Period expressions with a report interval208263 +Ref: #period-expressions-with-a-report-interval208497 +Node: More complex report intervals208711 +Ref: #more-complex-report-intervals208956 +Node: Multiple weekday intervals210817 +Ref: #multiple-weekday-intervals211006 +Node: Depth211828 +Ref: #depth211930 +Node: Queries212226 +Ref: #queries212328 +Node: Query types213924 +Ref: #query-types214045 +Node: Combining query terms217279 +Ref: #combining-query-terms217456 +Node: Queries and command options219019 +Ref: #queries-and-command-options219224 +Node: Queries and account aliases219473 +Ref: #queries-and-account-aliases219678 +Node: Queries and valuation219798 +Ref: #queries-and-valuation219955 +Node: Pivoting220160 +Ref: #pivoting220274 +Node: Generating data222051 +Ref: #generating-data222183 +Node: Forecasting223851 +Ref: #forecasting223976 +Node: --forecast224507 +Ref: #forecast224638 +Node: Inspecting forecast transactions225608 +Ref: #inspecting-forecast-transactions225810 +Node: Forecast reports226940 +Ref: #forecast-reports227113 +Node: Forecast tags228049 +Ref: #forecast-tags228209 +Node: Forecast period in detail228669 +Ref: #forecast-period-in-detail228863 +Node: Forecast troubleshooting229757 +Ref: #forecast-troubleshooting229925 +Node: Budgeting230828 +Ref: #budgeting230951 +Node: Amount formatting231388 +Ref: #amount-formatting231530 +Node: Commodity display style231632 +Ref: #commodity-display-style231786 +Node: Rounding233473 +Ref: #rounding233628 +Node: Trailing decimal marks234078 +Ref: #trailing-decimal-marks234257 +Node: Amount parseability235011 +Ref: #amount-parseability235167 +Node: Cost reporting236592 +Ref: #cost-reporting236734 +Node: Recording costs237395 +Ref: #recording-costs237531 +Node: Reporting at cost239122 +Ref: #reporting-at-cost239297 +Node: Equity conversion postings239887 +Ref: #equity-conversion-postings240101 +Node: Inferring equity conversion postings242532 +Ref: #inferring-equity-conversion-postings242795 +Node: Combining costs and equity conversion postings243547 +Ref: #combining-costs-and-equity-conversion-postings243857 +Node: Requirements for detecting equity conversion postings244772 +Ref: #requirements-for-detecting-equity-conversion-postings245094 +Node: Infer cost and equity by default ?246294 +Ref: #infer-cost-and-equity-by-default246523 +Node: Value reporting246731 +Ref: #value-reporting246873 +Node: -V Value247612 +Ref: #v-value247744 +Node: -X Value in specified commodity247939 +Ref: #x-value-in-specified-commodity248140 +Node: Valuation date248289 +Ref: #valuation-date248466 +Node: Finding market price249249 +Ref: #finding-market-price249460 +Node: --infer-market-prices market prices from transactions250629 +Ref: #infer-market-prices-market-prices-from-transactions250911 +Node: Valuation commodity253673 +Ref: #valuation-commodity253893 +Node: --value Flexible valuation255106 +Ref: #value-flexible-valuation255305 +Node: Valuation examples256949 +Ref: #valuation-examples257149 +Node: Interaction of valuation and queries259081 +Ref: #interaction-of-valuation-and-queries259321 +Node: Effect of valuation on reports259798 +Ref: #effect-of-valuation-on-reports260001 +Node: PART 4 COMMANDS267696 +Ref: #part-4-commands267839 +Node: Help commands269912 +Ref: #help-commands270057 +Node: help270085 +Ref: #help270174 +Node: demo271543 +Ref: #demo271632 +Node: User interface commands272548 +Ref: #user-interface-commands272717 +Node: ui272742 +Ref: #ui272834 +Node: web272867 +Ref: #web272961 +Node: Data entry commands272995 +Ref: #data-entry-commands273164 +Node: add273193 +Ref: #add273287 +Node: import275678 +Ref: #import275778 +Node: Date skipping276786 +Ref: #date-skipping276909 +Node: Import testing279687 +Ref: #import-testing279850 +Node: Importing balance assignments280693 +Ref: #importing-balance-assignments280900 +Node: Import and commodity styles281549 +Ref: #import-and-commodity-styles281729 +Node: Basic report commands281958 +Ref: #basic-report-commands282132 +Node: accounts282259 +Ref: #accounts282369 +Node: codes284256 +Ref: #codes284380 +Node: commodities285244 +Ref: #commodities285384 +Node: descriptions285454 +Ref: #descriptions285596 +Node: files285887 +Ref: #files286009 +Node: notes286150 +Ref: #notes286266 +Node: payees286628 +Ref: #payees286747 +Node: prices287266 +Ref: #prices287385 +Node: stats288038 +Ref: #stats288153 +Node: tags289667 +Ref: #tags-1289767 +Node: Standard report commands290776 +Ref: #standard-report-commands290961 +Node: print291081 +Ref: #print291189 +Node: print explicitness292169 +Ref: #print-explicitness292310 +Node: print amount style293089 +Ref: #print-amount-style293257 +Node: print parseability294327 +Ref: #print-parseability294497 +Node: print other features295246 +Ref: #print-other-features295423 +Node: print output format295944 +Ref: #print-output-format296090 +Node: aregister299229 +Ref: #aregister299362 +Node: aregister and posting dates302243 +Ref: #aregister-and-posting-dates302388 +Node: register303144 +Ref: #register303282 +Node: Custom register output308313 +Ref: #custom-register-output308442 +Node: balancesheet309789 +Ref: #balancesheet309944 +Node: balancesheetequity311606 +Ref: #balancesheetequity311773 +Node: cashflow313793 +Ref: #cashflow313943 +Node: incomestatement315430 +Ref: #incomestatement315567 +Node: Advanced report commands317103 +Ref: #advanced-report-commands317281 +Node: balance317311 +Ref: #balance317419 +Node: balance features318578 +Ref: #balance-features318718 +Node: Simple balance report320628 +Ref: #simple-balance-report320813 +Node: Balance report line format322438 +Ref: #balance-report-line-format322640 +Node: Filtered balance report324798 +Ref: #filtered-balance-report324990 +Node: List or tree mode325317 +Ref: #list-or-tree-mode325485 +Node: Depth limiting326830 +Ref: #depth-limiting326996 +Node: Dropping top-level accounts327597 +Ref: #dropping-top-level-accounts327797 +Node: Showing declared accounts328107 +Ref: #showing-declared-accounts328306 +Node: Sorting by amount328837 +Ref: #sorting-by-amount329004 +Node: Percentages329674 +Ref: #percentages329833 +Node: Multi-period balance report330381 +Ref: #multi-period-balance-report330581 +Node: Balance change end balance333133 +Ref: #balance-change-end-balance333342 +Node: Balance report types334770 +Ref: #balance-report-types334951 +Node: Calculation type335449 +Ref: #calculation-type335604 +Node: Accumulation type336153 +Ref: #accumulation-type336333 +Node: Valuation type337254 +Ref: #valuation-type337442 +Node: Combining balance report types338443 +Ref: #combining-balance-report-types338637 +Node: Budget report340475 +Ref: #budget-report340637 +Node: Using the budget report342780 +Ref: #using-the-budget-report342953 +Node: Budget date surprises345056 +Ref: #budget-date-surprises345256 +Node: Selecting budget goals346420 +Ref: #selecting-budget-goals346623 +Node: Budgeting vs forecasting347368 +Ref: #budgeting-vs-forecasting347545 +Node: Balance report layout349045 +Ref: #balance-report-layout349230 +Node: Wide layout350183 +Ref: #wide-layout350318 +Node: Tall layout352588 +Ref: #tall-layout352743 +Node: Bare layout353894 +Ref: #bare-layout354049 +Node: Tidy layout355953 +Ref: #tidy-layout356088 +Node: Some useful balance reports357497 +Ref: #some-useful-balance-reports357672 +Node: roi358757 +Ref: #roi358857 +Node: Spaces and special characters in --inv and --pnl360669 +Ref: #spaces-and-special-characters-in---inv-and---pnl360907 +Node: Semantics of --inv and --pnl361395 +Ref: #semantics-of---inv-and---pnl361632 +Node: IRR and TWR explained363482 +Ref: #irr-and-twr-explained363640 +Node: Chart commands366893 +Ref: #chart-commands367051 +Node: activity367074 +Ref: #activity367163 +Node: Data generation commands367537 +Ref: #data-generation-commands367711 +Node: close367743 +Ref: #close367849 +Node: close --migrate368502 +Ref: #close---migrate368627 +Node: close --close370266 +Ref: #close---close370408 +Node: close --open370644 +Ref: #close---open370783 +Node: close --assert370893 +Ref: #close---assert371037 +Node: close --assign371258 +Ref: #close---assign371404 +Node: close --retain371930 +Ref: #close---retain372081 +Node: close customisation372826 +Ref: #close-customisation373003 +Node: close and balance assertions374470 +Ref: #close-and-balance-assertions374665 +Node: close examples375992 +Ref: #close-examples376131 +Node: Retain earnings376229 +Ref: #retain-earnings376386 +Node: Migrate balances to a new file376732 +Ref: #migrate-balances-to-a-new-file376956 +Node: More detailed close examples378084 +Ref: #more-detailed-close-examples378280 +Node: rewrite378306 +Ref: #rewrite378416 +Node: Re-write rules in a file380314 +Ref: #re-write-rules-in-a-file380475 +Node: Diff output format381624 +Ref: #diff-output-format381805 +Node: rewrite vs print --auto382897 +Ref: #rewrite-vs.-print---auto383055 +Node: Maintenance commands383611 +Ref: #maintenance-commands383782 +Node: check383820 +Ref: #check383919 +Node: Basic checks384868 +Ref: #basic-checks384986 +Node: Strict checks385821 +Ref: #strict-checks385962 +Node: Other checks386696 +Ref: #other-checks386836 +Node: Custom checks388551 +Ref: #custom-checks388671 +Node: diff389006 +Ref: #diff389116 +Node: test390158 +Ref: #test390254 +Node: PART 5 COMMON TASKS390996 +Ref: #part-5-common-tasks391155 +Node: Getting help391229 +Ref: #getting-help391378 +Node: Constructing command lines392138 +Ref: #constructing-command-lines392319 +Node: Starting a journal file392976 +Ref: #starting-a-journal-file393158 +Node: Setting LEDGER_FILE394360 +Ref: #setting-ledger_file394532 +Node: Setting opening balances395489 +Ref: #setting-opening-balances395670 +Node: Recording transactions398811 +Ref: #recording-transactions398980 +Node: Reconciling399536 +Ref: #reconciling399668 +Node: Reporting401925 +Ref: #reporting402054 +Node: Migrating to a new file406039 +Ref: #migrating-to-a-new-file406189 +Node: BUGS406488 +Ref: #bugs406582 +Node: Troubleshooting407461 +Ref: #troubleshooting407561  End Tag Table diff --git a/hledger/hledger.txt b/hledger/hledger.txt index 09934ac3ca5..8c3eba6bb00 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 @@ -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. + + If the same option appears more than once in a command, usually the + last (right-most) wins. -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. + 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. - Option repetition - If options are repeated in a command line, hledger will generally use - the last (right-most) occurence. + 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. Eg it could be "primary + is the bank's clearing date, secondary is the date the transaction was + initiated, if different". + + 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. - 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". + o It distracts new users and supporters. - 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. + 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 Missing amounts or missing costs in transactions are inferred auto- + matically when possible. - o The balance command's --budget option uses these same periodic rules - to generate goals for the budget report. + o The --infer-equity flag infers missing conversion equity postings + from @/@@ costs. - 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 The --infer-costs flag infers missing costs from conversion equity + postings. - 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. - - 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. - - 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.34 May 2024 HLEDGER(1) +hledger-1.34 June 2024 HLEDGER(1)