diff --git a/hledger-lib/.date.m4 b/hledger-lib/.date.m4 index 705091ff8ff..c5f4680a426 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_}}, {{June 2024}})m4_dnl +m4_define({{_monthyear_}}, {{September 2024}})m4_dnl diff --git a/hledger-ui/.date.m4 b/hledger-ui/.date.m4 index 705091ff8ff..c5f4680a426 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_}}, {{June 2024}})m4_dnl +m4_define({{_monthyear_}}, {{September 2024}})m4_dnl diff --git a/hledger-ui/hledger-ui.1 b/hledger-ui/hledger-ui.1 index 67303deff49..d745fdac22c 100644 --- a/hledger-ui/hledger-ui.1 +++ b/hledger-ui/hledger-ui.1 @@ -1,5 +1,5 @@ -.TH "HLEDGER\-UI" "1" "June 2024" "hledger-ui-1.34.99 " "hledger User Manuals" +.TH "HLEDGER\-UI" "1" "September 2024" "hledger-ui-1.40 " "hledger User Manuals" @@ -17,7 +17,7 @@ or .PD \f[CR]hledger ui \-\- [OPTS] [QUERYARGS]\f[R] .SH DESCRIPTION -This manual is for hledger\[aq]s terminal interface, version 1.34.99. +This manual is for hledger\[aq]s terminal interface, version 1.40. See also the hledger manual for common concepts and file formats. .PP hledger is a robust, user\-friendly, cross\-platform set of programs for @@ -178,31 +178,10 @@ Emacs\-style (\f[CR]CTRL\-p\f[R]/\f[CR]CTRL\-n\f[R]/\f[CR]CTRL\-f\f[R]/\f[CR]CTRL\-b\f[R]) and VI\-style (\f[CR]k\f[R],\f[CR]j\f[R],\f[CR]l\f[R],\f[CR]h\f[R]) movement keys are also supported. -A tip: movement speed is limited by your keyboard repeat rate, to move +.PP +(Tip: movement speed is limited by your keyboard repeat rate, to move faster you may want to adjust it. -(If you\[aq]re on a mac, the karabiner app is one way to do that.) -.PP -With shift pressed, the cursor keys adjust the report period, limiting -the transactions to be shown (by default, all are shown). -\f[CR]SHIFT\-DOWN/UP\f[R] steps downward and upward through these -standard report period durations: year, quarter, month, week, day. -Then, \f[CR]SHIFT\-LEFT/RIGHT\f[R] moves to the previous/next period. -\f[CR]T\f[R] sets the report period to today. -With the \f[CR]\-w/\-\-watch\f[R] option, when viewing a -\[dq]current\[dq] period (the current day, week, month, quarter, or -year), the period will move automatically to track the current date. -To set a non\-standard period, you can use \f[CR]/\f[R] and a -\f[CR]date:\f[R] query. -.PP -(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 current terminal profile -on the left, click Keyboard on the right, click + and add this for -Shift\-Down: \f[CR]\[rs]033[1;2B\f[R], click + and add this for -Shift\-Up: \f[CR]\[rs]033[1;2A\f[R]. -Press the Escape key to enter the \f[CR]\[rs]033\f[R] part, you -can\[aq]t type it directly.) +On a mac, the Karabiner app is one way to do that.) .PP \f[CR]/\f[R] lets you set a general filter query limiting the data shown, using the same query terms as in hledger and hledger\-web. @@ -219,6 +198,31 @@ transactions generated by rule. \f[CR]F\f[R] toggles forecast mode, in which future/forecasted transactions are shown. .PP +Pressing \f[CR]SHIFT\-DOWN\f[R] narrows the report period, and pressing +\f[CR]SHIFT\-UP\f[R] expands it again. +When narrowed, the current report period is displayed in the header +line, pressing \f[CR]SHIFT\-LEFT\f[R] or \f[CR]SHIFT\-RIGHT\f[R] moves +to the previous or next period, and pressing \f[CR]T\f[R] sets the +period to \[dq]today\[dq]. +If you are using \f[CR]\-w/\-\-watch\f[R] and viewing a narrowed period +containing today, the view will follow any changes in system date +(moving to the period containing the new date). +.PP +You can also specify a non\-standard period with \f[CR]/\f[R] and a +\f[CR]date:\f[R] query; in this case, the period is not movable with the +arrow keys. +.PP +(Tip: arrow keys with Shift do not work out of the box in all terminal +software. +Eg in Apple\[aq]s Terminal, the SHIFT\-DOWN and SHIFT\-UP keys must be +configured as follows: in Terminal\[aq]s preferences, click Profiles, +select your current profile on the left, click Keyboard on the right, +click + and add this for SHIFT\-DOWN: \f[CR]\[rs]033[1;2B\f[R], click + +and add this for SHIFT\-UP: \f[CR]\[rs]033[1;2A\f[R]. +\ In other terminals (Windows Terminal ?) +you might need to configure SHIFT\-RIGHT and SHIFT\-LEFT to emit +\f[CR]\[rs]033[1;2C\f[R] and \f[CR]\[rs]033[1;2D\f[R] respectively.) +.PP \f[CR]ESCAPE\f[R] resets the UI state and jumps back to the top screen, restoring the app\[aq]s initial state at startup. Or, it cancels minibuffer data entry or the help dialog. diff --git a/hledger-ui/hledger-ui.info b/hledger-ui/hledger-ui.info index 3e6c15f3ff8..461b85a57e8 100644 --- a/hledger-ui/hledger-ui.info +++ b/hledger-ui/hledger-ui.info @@ -18,8 +18,8 @@ plain text accounting app. or 'hledger ui -- [OPTS] [QUERYARGS]' - This manual is for hledger's terminal interface, version 1.34.99. -See also the hledger manual for common concepts and file formats. + This manual is for hledger's terminal interface, version 1.40. See +also the hledger manual for common concepts and file formats. hledger is a robust, user-friendly, cross-platform set of programs for tracking money, time, or any other commodity, using double-entry @@ -192,27 +192,11 @@ most screens: 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 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 -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-standard 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 current -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 can't -type it directly.) +movement keys are also supported. + + (Tip: movement speed is limited by your keyboard repeat rate, to move +faster you may want to adjust it. On a mac, the Karabiner app is one +way to do that.) '/' lets you set a general filter query limiting the data shown, using the same query terms as in hledger and hledger-web. While editing @@ -227,6 +211,26 @@ both ordinary transactions recorded in the journal, and periodic transactions generated by rule. 'F' toggles forecast mode, in which future/forecasted transactions are shown. + Pressing 'SHIFT-DOWN' narrows the report period, and pressing +'SHIFT-UP' expands it again. When narrowed, the current report period +is displayed in the header line, pressing 'SHIFT-LEFT' or 'SHIFT-RIGHT' +moves to the previous or next period, and pressing 'T' sets the period +to "today". If you are using '-w/--watch' and viewing a narrowed period +containing today, the view will follow any changes in system date +(moving to the period containing the new date). + + You can also specify a non-standard period with '/' and a 'date:' +query; in this case, the period is not movable with the arrow keys. + + (Tip: arrow keys with Shift do not work out of the box in all +terminal software. Eg in Apple's Terminal, the SHIFT-DOWN and SHIFT-UP +keys must be configured as follows: in Terminal's preferences, click +Profiles, select your current 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'. In other terminals (Windows Terminal ?) +you might need to configure SHIFT-RIGHT and SHIFT-LEFT to emit +'\033[1;2C' and '\033[1;2D' respectively.) + '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 entry or the help dialog. @@ -531,36 +535,36 @@ above).  Tag Table: Node: Top221 -Node: OPTIONS1872 -Ref: #options1970 -Node: MOUSE8236 -Ref: #mouse8331 -Node: KEYS8568 -Ref: #keys8661 -Node: SCREENS13316 -Ref: #screens13420 -Node: Menu screen14056 -Ref: #menu-screen14177 -Node: Cash accounts screen14372 -Ref: #cash-accounts-screen14549 -Node: Balance sheet accounts screen14733 -Ref: #balance-sheet-accounts-screen14949 -Node: Income statement accounts screen15069 -Ref: #income-statement-accounts-screen15290 -Node: All accounts screen15454 -Ref: #all-accounts-screen15635 -Node: Register screen15817 -Ref: #register-screen15976 -Node: Transaction screen18260 -Ref: #transaction-screen18418 -Node: Error screen19835 -Ref: #error-screen19957 -Node: WATCH MODE20201 -Ref: #watch-mode20318 -Node: ENVIRONMENT21777 -Ref: #environment21893 -Node: BUGS22084 -Ref: #bugs22167 +Node: OPTIONS1870 +Ref: #options1968 +Node: MOUSE8234 +Ref: #mouse8329 +Node: KEYS8566 +Ref: #keys8659 +Node: SCREENS13394 +Ref: #screens13498 +Node: Menu screen14134 +Ref: #menu-screen14255 +Node: Cash accounts screen14450 +Ref: #cash-accounts-screen14627 +Node: Balance sheet accounts screen14811 +Ref: #balance-sheet-accounts-screen15027 +Node: Income statement accounts screen15147 +Ref: #income-statement-accounts-screen15368 +Node: All accounts screen15532 +Ref: #all-accounts-screen15713 +Node: Register screen15895 +Ref: #register-screen16054 +Node: Transaction screen18338 +Ref: #transaction-screen18496 +Node: Error screen19913 +Ref: #error-screen20035 +Node: WATCH MODE20279 +Ref: #watch-mode20396 +Node: ENVIRONMENT21855 +Ref: #environment21971 +Node: BUGS22162 +Ref: #bugs22245  End Tag Table diff --git a/hledger-ui/hledger-ui.txt b/hledger-ui/hledger-ui.txt index 3ce51447726..8345f491283 100644 --- a/hledger-ui/hledger-ui.txt +++ b/hledger-ui/hledger-ui.txt @@ -11,7 +11,7 @@ SYNOPSIS hledger ui -- [OPTS] [QUERYARGS] DESCRIPTION - This manual is for hledger's terminal interface, version 1.34.99. See + This manual is for hledger's terminal interface, version 1.40. See also the hledger manual for common concepts and file formats. hledger is a robust, user-friendly, cross-platform set of programs for @@ -161,28 +161,11 @@ KEYS 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 - 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 - 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- - 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- - 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 - can't type it directly.) + (k,j,l,h) movement keys are also supported. + + (Tip: movement speed is limited by your keyboard repeat rate, to move + faster you may want to adjust it. On a mac, the Karabiner app is one + way to do that.) / 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 @@ -196,52 +179,72 @@ KEYS 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 + Pressing SHIFT-DOWN narrows the report period, and pressing SHIFT-UP + expands it again. When narrowed, the current report period is dis- + played in the header line, pressing SHIFT-LEFT or SHIFT-RIGHT moves to + the previous or next period, and pressing T sets the period to "today". + If you are using -w/--watch and viewing a narrowed period containing + today, the view will follow any changes in system date (moving to the + period containing the new date). + + You can also specify a non-standard period with / and a date: query; in + this case, the period is not movable with the arrow keys. + + (Tip: arrow keys with Shift do not work out of the box in all terminal + software. Eg in Apple's Terminal, the SHIFT-DOWN and SHIFT-UP keys + must be configured as follows: in Terminal's preferences, click Pro- + files, select your current 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. In other terminals (Windows Terminal ?) + you might need to configure SHIFT-RIGHT and SHIFT-LEFT to emit + \033[1;2C and \033[1;2D respectively.) + + 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. @@ -249,47 +252,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- @@ -297,90 +300,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.) 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- + 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: @@ -388,27 +391,27 @@ WATCH MODE 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. 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: @@ -420,7 +423,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). @@ -441,4 +444,4 @@ LICENSE SEE ALSO hledger(1), hledger-ui(1), hledger-web(1), ledger(1) -hledger-ui-1.34.99 June 2024 HLEDGER-UI(1) +hledger-ui-1.40 September 2024 HLEDGER-UI(1) diff --git a/hledger-web/.date.m4 b/hledger-web/.date.m4 index 705091ff8ff..c5f4680a426 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_}}, {{June 2024}})m4_dnl +m4_define({{_monthyear_}}, {{September 2024}})m4_dnl diff --git a/hledger-web/hledger-web.1 b/hledger-web/hledger-web.1 index 99bc2592f9a..336631ccd74 100644 --- a/hledger-web/hledger-web.1 +++ b/hledger-web/hledger-web.1 @@ -1,5 +1,5 @@ -.TH "HLEDGER\-WEB" "1" "June 2024" "hledger-web-1.34.99 " "hledger User Manuals" +.TH "HLEDGER\-WEB" "1" "September 2024" "hledger-web-1.40 " "hledger User Manuals" @@ -17,7 +17,7 @@ or .PD \f[CR]hledger web \-\- [OPTS] [QUERY]\f[R] .SH DESCRIPTION -This manual is for hledger\[aq]s web interface, version 1.34.99. +This manual is for hledger\[aq]s web interface, version 1.40. See also the hledger manual for common concepts and file formats. .PP hledger is a robust, user\-friendly, cross\-platform set of programs for diff --git a/hledger-web/hledger-web.info b/hledger-web/hledger-web.info index 35d1bef976c..c70a7ce04b0 100644 --- a/hledger-web/hledger-web.info +++ b/hledger-web/hledger-web.info @@ -18,8 +18,8 @@ plain text accounting app. or 'hledger web -- [OPTS] [QUERY]' - This manual is for hledger's web interface, version 1.34.99. See -also the hledger manual for common concepts and file formats. + This manual is for hledger's web interface, version 1.40. See also +the hledger manual for common concepts and file formats. hledger is a robust, user-friendly, cross-platform set of programs for tracking money, time, or any other commodity, using double-entry @@ -523,24 +523,24 @@ http://bugs.hledger.org), or on the #hledger chat or hledger mail list  Tag Table: Node: Top223 -Node: OPTIONS2569 -Ref: #options2674 -Node: PERMISSIONS10948 -Ref: #permissions11087 -Node: EDITING UPLOADING DOWNLOADING12299 -Ref: #editing-uploading-downloading12480 -Node: RELOADING13314 -Ref: #reloading13448 -Node: JSON API13881 -Ref: #json-api13996 -Node: DEBUG OUTPUT19530 -Ref: #debug-output19655 -Node: Debug output19682 -Ref: #debug-output-119783 -Node: ENVIRONMENT20200 -Ref: #environment20319 -Node: BUGS20436 -Ref: #bugs20520 +Node: OPTIONS2566 +Ref: #options2671 +Node: PERMISSIONS10945 +Ref: #permissions11084 +Node: EDITING UPLOADING DOWNLOADING12296 +Ref: #editing-uploading-downloading12477 +Node: RELOADING13311 +Ref: #reloading13445 +Node: JSON API13878 +Ref: #json-api13993 +Node: DEBUG OUTPUT19527 +Ref: #debug-output19652 +Node: Debug output19679 +Ref: #debug-output-119780 +Node: ENVIRONMENT20197 +Ref: #environment20316 +Node: BUGS20433 +Ref: #bugs20517  End Tag Table diff --git a/hledger-web/hledger-web.txt b/hledger-web/hledger-web.txt index 5354c322c5f..af1f5d55c57 100644 --- a/hledger-web/hledger-web.txt +++ b/hledger-web/hledger-web.txt @@ -11,41 +11,41 @@ SYNOPSIS hledger web -- [OPTS] [QUERY] DESCRIPTION - This manual is for hledger's web interface, version 1.34.99. See also - the hledger manual for common concepts and file formats. + This manual is for hledger's web interface, version 1.40. See also the + hledger manual for common concepts and file formats. - hledger is a robust, user-friendly, cross-platform set of programs for - tracking money, time, or any other commodity, using double-entry ac- - counting and a simple, editable file format. hledger is inspired by - and largely compatible with ledger(1), and largely interconvertible + hledger is a robust, user-friendly, cross-platform set of programs for + tracking money, time, or any other commodity, using double-entry ac- + counting and a simple, editable file format. hledger is inspired by + and largely compatible with ledger(1), and largely interconvertible with beancount(1). - hledger-web is a simple web application for browsing and adding trans- - actions. It provides a more user-friendly UI than the hledger CLI or - hledger-ui TUI, showing more at once (accounts, the current account + hledger-web is a simple web application for browsing and adding trans- + actions. It provides a more user-friendly UI than the hledger CLI or + hledger-ui TUI, showing more at once (accounts, the current account register, balance charts) and allowing history-aware data entry, inter- active searching, and bookmarking. - hledger-web also lets you share a journal with multiple users, or even - the public web. There is no access control, so if you need that you - should put it behind a suitable web proxy. As a small protection - against data loss when running an unprotected instance, it writes a + hledger-web also lets you share a journal with multiple users, or even + the public web. There is no access control, so if you need that you + should put it behind a suitable web proxy. As a small protection + against data loss when running an unprotected instance, it writes a numbered backup of the main journal file (only) on every edit. - Like hledger, it reads from (and appends to) a journal file specified - by the LEDGER_FILE environment variable (defaulting to - $HOME/.hledger.journal); or you can specify files with -f options. It - can also read timeclock files, timedot files, or any CSV/SSV/TSV file + Like hledger, it reads from (and appends to) a journal file specified + by the LEDGER_FILE environment variable (defaulting to + $HOME/.hledger.journal); or you can specify files with -f options. It + can also read timeclock files, timedot files, or any CSV/SSV/TSV file with a date field. (See hledger(1) -> Input for details.) hledger-web can be run in three modes: o Transient mode (the default): your default web browser will be opened - to show the app if possible, and the app exits automatically after - two minutes of inactivity (no requests received and no open browser + to show the app if possible, and the app exits automatically after + two minutes of inactivity (no requests received and no open browser windows viewing it). - o With --serve: the app runs without stopping, and without opening a + o With --serve: the app runs without stopping, and without opening a browser. o With --serve-api: only the JSON API is served. @@ -76,28 +76,28 @@ OPTIONS 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 + 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 + 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 + 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. - When --socket is used, hledger-web creates and communicates via a - socket file instead of a TCP port. This can be more secure, respects + 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;.) - 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 - http://HOST:PORT/ using the server's configured host address and TCP - port (or http://HOST if PORT is 80). Note this affects url generation + 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 + http://HOST:PORT/ using the server's configured host address and TCP + port (or http://HOST if PORT is 80). Note this affects url generation but not route parsing. hledger-web also supports many of hledger's general options: @@ -181,25 +181,25 @@ OPTIONS --version show version information --debug=[1-9] show this much debug output (default: 1) - 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 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 + 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 + 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. You can restrict who can reach it by - o setting the IP address it listens on (see --host above). By default - it listens on 127.0.0.1, accessible to all users on the local ma- + o setting the IP address it listens on (see --host above). By default + it listens on 127.0.0.1, accessible to all users on the local ma- chine. o putting it behind an authenticating proxy, using eg apache or nginx @@ -209,44 +209,44 @@ PERMISSIONS You can restrict what the users who reach it can do, by o using the --capabilities=CAP[,CAP..] flag when you start it, enabling - one or more of the following capabilities. The default value is + one or more of the following capabilities. The default value is view,add: o view - allows viewing the journal file and all included files o add - allows adding new transactions to the main journal file - o manage - allows editing, uploading or downloading the main or in- + o manage - allows editing, uploading or downloading the main or in- cluded files - o using the --capabilities-header=HTTPHEADER flag to specify a HTTP - header from which it will read capabilities to enable. hledger-web - on Sandstorm uses the X-Sandstorm-Permissions header to integrate + o using the --capabilities-header=HTTPHEADER flag to specify a HTTP + header from which it will read capabilities to enable. hledger-web + on Sandstorm uses the X-Sandstorm-Permissions header to integrate with Sandstorm's permissions. This is disabled by default. EDITING, UPLOADING, DOWNLOADING - If you enable the manage capability mentioned above, you'll see a new - "spanner" button to the right of the search form. Clicking this will - let you edit, upload, or download the journal file or any files it in- + If you enable the manage capability mentioned above, you'll see a new + "spanner" button to the right of the search form. Clicking this will + let you edit, upload, or download the journal file or any files it in- cludes. - Note, unlike any other hledger command, in this mode you (or any visi- + Note, unlike any other hledger command, in this mode you (or any visi- tor) can alter or wipe the data files. - Normally whenever a file is changed in this way, hledger-web saves a - numbered backup (assuming file permissions allow it, the disk is not - full, etc.) hledger-web is not aware of version control systems, cur- - rently; if you use one, you'll have to arrange to commit the changes + Normally whenever a file is changed in this way, hledger-web saves a + numbered backup (assuming file permissions allow it, the disk is not + full, etc.) hledger-web is not aware of version control systems, cur- + rently; if you use one, you'll have to arrange to commit the changes yourself (eg with a cron job or a file watcher like entr). - Changes which would leave the journal file(s) unparseable or non-valid - (eg with failing balance assertions) are prevented. (Probably. This + Changes which would leave the journal file(s) unparseable or non-valid + (eg with failing balance assertions) are prevented. (Probably. This needs re-testing.) RELOADING hledger-web detects changes made to the files by other means (eg if you - edit it directly, outside of hledger-web), and it will show the new - data when you reload the page or navigate to a new page. If a change + edit it directly, outside of hledger-web), and it will show the new + data when you reload the page or navigate to a new page. If a change makes a file unparseable, hledger-web will display an error message un- til the file has been fixed. @@ -254,8 +254,8 @@ RELOADING that both machine clocks are roughly in step.) JSON API - In addition to the web UI, hledger-web also serves a JSON API that can - be used to get data or add new transactions. If you want the JSON API + In addition to the web UI, hledger-web also serves a JSON API that can + be used to get data or add new transactions. If you want the JSON API only, you can use the --serve-api flag. Eg: $ hledger-web -f examples/sample.journal --serve-api @@ -272,7 +272,7 @@ JSON API /accounttransactions/ACCOUNTNAME Eg, all account names in the journal (similar to the accounts command). - (hledger-web's JSON does not include newlines, here we use python to + (hledger-web's JSON does not include newlines, here we use python to prettify it): $ curl -s http://127.0.0.1:5000/accountnames | python -m json.tool @@ -313,26 +313,26 @@ JSON API "aprice": null, ... - 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- + 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. 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 - at the source for the appropriate handler to see what it returns. Eg + understand that, go to the Hledger.Web.Handler.MiscR haddock and look + at the source for the appropriate handler to see what it returns. Eg for /accounttransactions it's getAccounttransactionsR, returning a "ac- - countTransactionsReport ...". Looking up the haddock for that we can - see that /accounttransactions returns an AccountTransactionsReport, - which consists of a report title and a list of AccountTransactionsRe- + countTransactionsReport ...". Looking up the haddock for that we can + see that /accounttransactions returns an AccountTransactionsReport, + which consists of a report title and a list of AccountTransactionsRe- portItem (etc). - You can add a new transaction to the journal with a PUT request to - /add, if hledger-web was started with the add capability (enabled by + You can add a new transaction to the journal with a PUT request to + /add, if hledger-web was started with the add capability (enabled by default). The payload must be the full, exact JSON representation of a - hledger transaction (partial data won't do). You can get sample JSON - from hledger-web's /transactions or /accounttransactions, or you can + hledger transaction (partial data won't do). You can get sample JSON + from hledger-web's /transactions or /accounttransactions, or you can export it with hledger-lib, eg like so: .../hledger$ stack ghci hledger-lib @@ -428,28 +428,28 @@ JSON API "tstatus": "Unmarked" } - And here's how to test adding it with curl. This should add a new en- + And here's how to test adding it with curl. This should add a new en- try to your journal: $ curl http://127.0.0.1:5000/add -X PUT -H 'Content-Type: application/json' --data-binary @txn.json DEBUG OUTPUT Debug output - You can add --debug[=N] to the command line to log debug output. N + You can add --debug[=N] to the command line to log debug output. N ranges from 1 (least output, the default) to 9 (maximum output). Typi- - cally you would start with 1 and increase until you are seeing enough. - Debug output goes to stderr, interleaved with the requests logged on + cally you would start with 1 and increase until you are seeing enough. + Debug output goes to stderr, interleaved with the requests logged on stdout. To capture debug output in a log file instead, you can usually redirect stderr, eg: hledger-web --debug=3 2>hledger-web.log. ENVIRONMENT - 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: @@ -474,4 +474,4 @@ LICENSE SEE ALSO hledger(1), hledger-ui(1), hledger-web(1), ledger(1) -hledger-web-1.34.99 June 2024 HLEDGER-WEB(1) +hledger-web-1.40 September 2024 HLEDGER-WEB(1) diff --git a/hledger/.date.m4 b/hledger/.date.m4 index 705091ff8ff..c5f4680a426 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_}}, {{June 2024}})m4_dnl +m4_define({{_monthyear_}}, {{September 2024}})m4_dnl diff --git a/hledger/hledger.1 b/hledger/hledger.1 index 67b929faa78..ffa5653bd50 100644 --- a/hledger/hledger.1 +++ b/hledger/hledger.1 @@ -1,6 +1,6 @@ .\"t -.TH "HLEDGER" "1" "June 2024" "hledger-1.34.99 " "hledger User Manuals" +.TH "HLEDGER" "1" "September 2024" "hledger-1.40 " "hledger User Manuals" @@ -32,8 +32,7 @@ accounting and a simple, editable file format. hledger is inspired by and largely compatible with ledger(1), and largely interconvertible with beancount(1). .PP -This manual is for hledger\[aq]s command line interface, version -1.34.99. +This manual is for hledger\[aq]s command line interface, version 1.40. It also describes the common options, file formats and concepts used by all hledger programs. It might accidentally teach you some bookkeeping/accounting as well! @@ -112,7 +111,7 @@ hledger reads one or more data files, each time you run it. You can specify a file with \f[CR]\-f\f[R], like so .IP .EX -$ hledger \-f FILE print +$ hledger \-f FILE [\-f FILE2 ...] print .EE .PP Files are most often in hledger\[aq]s journal format, with the @@ -738,7 +737,7 @@ can override them if needed. The config file can contain general options (which will be used with all commands that support them), and command\-specific options (or arguments). -hledger.conf.sample is an example, which you can install as +hledger.conf.sample is an example, which you can install as, eg, \f[CR]./hledger.conf\f[R] or \f[CR]$HOME/.hledger.conf\f[R]. .PP To be precise, hledger looks for \f[CR]hledger.conf\f[R] in the current @@ -754,9 +753,13 @@ You can inspect the finding and processing of config files with .PP If you want to run hledger without a config file, to ensure standard defaults and behaviour, use the \f[CR]\-n/\-\-no\-conf\f[R] flag. -This is useful when troubleshooting problems or sharing examples. +This is recommended when using hledger in scripts, and when +troubleshooting problems. .PP -\f[I](Added in 1.40; experimental)\f[R] +When both \f[CR]\-\-conf\f[R] and \f[CR]\-\-no\-conf\f[R] options are +used, the last (right\-most) wins. +.PP +\f[I](in master, experimental)\f[R] .SH Output .SS Output destination hledger commands send their output to the terminal by default. @@ -783,7 +786,7 @@ Here are those commands and the formats currently supported: .PP .TS tab(@); -lw(16.1n) lw(14.5n) lw(14.5n) lw(16.1n) lw(4.8n) lw(4.0n). +lw(13.6n) lw(12.2n) lw(12.2n) lw(12.2n) lw(12.2n) lw(4.1n) lw(3.4n). T{ \- T}@T{ @@ -793,6 +796,8 @@ csv/tsv T}@T{ html T}@T{ +fods +T}@T{ json T}@T{ sql @@ -807,6 +812,7 @@ Y T}@T{ Y T}@T{ +T}@T{ Y T}@T{ T} @@ -817,7 +823,9 @@ Y \f[I]1\f[R] T}@T{ Y \f[I]1\f[R] T}@T{ -Y \f[I]1,2\f[R] +Y \f[I]1\f[R] +T}@T{ +Y \f[I]1\f[R] T}@T{ Y T}@T{ @@ -831,6 +839,7 @@ Y \f[I]1\f[R] T}@T{ Y \f[I]1\f[R] T}@T{ +T}@T{ Y T}@T{ T} @@ -843,6 +852,7 @@ Y \f[I]1\f[R] T}@T{ Y \f[I]1\f[R] T}@T{ +T}@T{ Y T}@T{ T} @@ -855,6 +865,7 @@ Y \f[I]1\f[R] T}@T{ Y \f[I]1\f[R] T}@T{ +T}@T{ Y T}@T{ T} @@ -867,6 +878,7 @@ Y \f[I]1\f[R] T}@T{ Y \f[I]1\f[R] T}@T{ +T}@T{ Y T}@T{ T} @@ -878,6 +890,7 @@ T}@T{ Y T}@T{ T}@T{ +T}@T{ Y T}@T{ Y @@ -890,6 +903,7 @@ T}@T{ Y T}@T{ T}@T{ +T}@T{ Y T}@T{ T} @@ -897,9 +911,6 @@ T} .IP \[bu] 2 \f[I]1 Also affected by the balance commands\[aq] \f[CI]\-\-layout\f[I] option.\f[R] -.IP \[bu] 2 -\f[I]2 \f[CI]balance\f[I] does not support html output without a report -interval or with \f[CI]\-\-budget\f[I].\f[R] .PP The output format is selected by the \f[CR]\-O/\-\-output\-format=FMT\f[R] option: @@ -1104,7 +1115,7 @@ the add or web or import commands to create and update it. .PP Many users, though, edit the journal file with a text editor, and track changes with a version control system such as git. -Editor addons such as ledger\-mode or hledger\-mode for Emacs, +Editor add\-ons such as ledger\-mode or hledger\-mode for Emacs, vim\-ledger for Vim, and hledger\-vscode for Visual Studio Code, make this easier, adding colour, formatting, tab completion, and useful commands. @@ -5329,11 +5340,17 @@ $ hledger \-f sample.timeclock register \-p weekly \-\-depth 1 \-\-empty # time .PP To generate time logs, ie to clock in and clock out, you could: .IP \[bu] 2 -use emacs and the built\-in timeclock.el, or the extended -timeclock\-x.el and perhaps the extras in ledgerutils.el +use these shell aliases at the command line: +.RS 2 +.IP +.EX +alias ti=\[aq]echo i \[ga]date \[dq]+%Y\-%m\-%d %H:%M:%S\[dq]\[ga] $* >>$TIMELOG\[aq] +alias to=\[aq]echo o \[ga]date \[dq]+%Y\-%m\-%d %H:%M:%S\[dq]\[ga] >>$TIMELOG\[aq] +.EE +.RE .IP \[bu] 2 -at the command line, use these bash aliases: -\f[CR]cli alias ti=\[dq]echo i \[ga]date \[aq]+%Y\-%m\-%d %H:%M:%S\[aq]\[ga] \[rs]$* >>$TIMELOG\[dq] alias to=\[dq]echo o \[ga]date \[aq]+%Y\-%m\-%d %H:%M:%S\[aq]\[ga] >>$TIMELOG\[dq]\f[R] +or Emacs\[aq]s built\-in timeclock.el, or the extended timeclock\-x.el, +and perhaps the extras in ledgerutils.el .IP \[bu] 2 or use the old \f[CR]ti\f[R] and \f[CR]to\f[R] scripts in the ledger 2.x repository. @@ -5687,26 +5704,62 @@ flags: .PP More complex intervals can be specified using \f[CR]\-p/\-\-period\f[R], described below. -.SS Date adjustment -When there is a report interval (other than daily), report start/end -dates which have been inferred, eg from the journal, are automatically -adjusted to natural period boundaries. -This is convenient for producing simple periodic reports. -More precisely: -.IP \[bu] 2 -an inferred start date will be adjusted earlier if needed to fall on a -natural period boundary -.IP \[bu] 2 -an inferred end date will be adjusted later if needed to make the last -period the same length as the others. -.PP -By contrast, start/end dates which have been specified explicitly, with -\f[CR]\-b\f[R], \f[CR]\-e\f[R], \f[CR]\-p\f[R] or \f[CR]date:\f[R], will -not be adjusted (since hledger 1.29). -This makes it possible to specify non\-standard report periods, but it -also means that if you are specifying a start date, you should pick one -that\[aq]s on a period boundary if you want to see simple report period -headings. +.SS Date adjustments +.SS Start date adjustment +If you let hledger infer a report\[aq]s start date, it will adjust the +date to the previous natural boundary of the report interval, for +convenient periodic reports. +(If you don\[aq]t want that, specify a start date.) +.PP +For example, if the journal\[aq]s first transaction is on january 10th, +.IP \[bu] 2 +\f[CR]hledger register\f[R] (no report interval) will start the report +on january 10th. +.IP \[bu] 2 +\f[CR]hledger register \-\-monthly\f[R] will start the report on the +previous month boundary, january 1st. +.IP \[bu] 2 +\f[CR]hledger register \-\-monthly \-\-begin 1/5\f[R] will start the +report on january 5th [1]. +.PP +Also if you are generating transactions or budget goals with periodic +transaction rules, their start date may be adjusted in a similar way (in +certain situations). +.SS End date adjustment +A report\[aq]s end date is always adjusted to include a whole number of +intervals, so that the last subperiod has the same length as the others. +.PP +For example, if the journal\[aq]s last transaction is on february 20th, +.IP \[bu] 2 +\f[CR]hledger register\f[R] will end the report on february 20th. +.IP \[bu] 2 +\f[CR]hledger register \-\-monthly\f[R] will end the report at the end +of february. +.IP \[bu] 2 +\f[CR]hledger register \-\-monthly \-\-end 2/14\f[R] also will end the +report at the end of february. +.IP \[bu] 2 +\f[CR]hledger register \-\-monthly \-\-begin 1/5 \-\-end 2/14\f[R] will +end the report on march 4th [1]. +.PP +[1] Since hledger 1.29. +.SS Period headings +With non\-standard subperiods, hledger will show +\[dq]STARTDATE..ENDDATE\[dq] headings. +With standard subperiods (ie, starting on a natural interval boundary), +you\[aq]ll see more compact headings, which are usually preferable. +(Though month names will be in english, currently.) +.PP +So if you are specifying a start date and you want compact headings: +choose a start of year for yearly reports, a start of quarter for +quarterly reports, a start of month for monthly reports, etc. +(Remember, you can write eg \f[CR]\-b 2024\f[R] or \f[CR]1/1\f[R] as a +shortcut for a start of year, or \f[CR]2024\-04\f[R] or +\f[CR]202404\f[R] or \f[CR]Apr\f[R] for a start of month or quarter.) +.PP +For weekly reports, choose a date that\[aq]s a Monday. +(You can try different dates until you see the short headings, or write +eg \f[CR]\-b \[aq]3 weeks ago\[aq]\f[R].) .SS Period expressions The \f[CR]\-p/\-\-period\f[R] option specifies a period expression, which is a compact way of expressing a start date, end date, and/or @@ -5873,7 +5926,7 @@ adjusted to each month\[aq]s last day) .IP \[bu] 2 \f[CR]every Nth WEEKDAYNAME [of month]\f[R] .PP -Yearly on a custom day: +Yearly on a custom month and day: .IP \[bu] 2 \f[CR]every MM/DD [of year]\f[R] (month number and day of month number) .IP \[bu] 2 @@ -6519,7 +6572,7 @@ $ hledger print \-\-forecast \-\-today=2023/4/21 .EE .PP Here there are no ordinary transactions, so the forecasted transactions -begin on the first occurence after today\[aq]s date. +begin on the first occurrence after today\[aq]s date. (You won\[aq]t normally use \f[CR]\-\-today\f[R]; it\[aq]s just to make these examples reproducible.) .SS Forecast reports @@ -7755,7 +7808,6 @@ T} \f[CR]\-\-cumulative\f[R] is omitted to save space, it works like \f[CR]\-H\f[R] but with a zero starting balance. .SH PART 4: COMMANDS -\ .PP Here are the standard commands, which you can list by running \f[CR]hledger\f[R]. @@ -7967,9 +8019,6 @@ payees/descriptions, dates (\f[CR]yesterday\f[R], \f[CR]today\f[R], \f[CR]tomorrow\f[R]). If the input area is empty, it will insert the default value. .IP \[bu] 2 -If the journal defines a default commodity, it will be added to any bare -numbers entered. -.IP \[bu] 2 A parenthesised transaction code may be entered following a date. .IP \[bu] 2 Comments and tags may be entered following a description or amount. @@ -9450,7 +9499,7 @@ Flags: \[aq]bare\[aq] : commodity symbols in one column \[aq]tidy\[aq] : every attribute in its own column \-O \-\-output\-format=FMT select the output format. Supported formats: - txt, html, csv, tsv, json. + txt, html, csv, tsv, json, fods. \-o \-\-output\-file=FILE write output to FILE. A file extension matching one of the above formats selects that format. .EE @@ -9543,7 +9592,7 @@ commodities displayed on the same line or multiple lines This command supports the output destination and output format options, with output formats \f[CR]txt\f[R], \f[CR]csv\f[R], \f[CR]tsv\f[R] (\f[I]Added in 1.32\f[R]), \f[CR]json\f[R], and (multi\-period reports -only:) \f[CR]html\f[R]. +only:) \f[CR]html\f[R], \f[CR]fods\f[R] (\f[I]Added in 1.40\f[R]). In \f[CR]txt\f[R] output in a colour\-supporting terminal, negative amounts are shown in red. .SS Simple balance report diff --git a/hledger/hledger.info b/hledger/hledger.info index 0223610a860..bf8c6ff452d 100644 --- a/hledger/hledger.info +++ b/hledger/hledger.info @@ -26,7 +26,7 @@ accounting and a simple, editable file format. hledger is inspired by and largely compatible with ledger(1), and largely interconvertible with beancount(1). - This manual is for hledger's command line interface, version 1.34.99. + This manual is for hledger's command line interface, version 1.40. It also describes the common options, file formats and concepts used by all hledger programs. It might accidentally teach you some bookkeeping/accounting as well! You don't need to know everything in @@ -146,7 +146,7 @@ File: hledger.info, Node: Input, Next: Commands, Prev: PART 1 USER INTERFACE, hledger reads one or more data files, each time you run it. You can specify a file with '-f', like so -$ hledger -f FILE print +$ hledger -f FILE [-f FILE2 ...] print Files are most often in hledger's journal format, with the '.journal' file extension ('.hledger' or '.j' also work); these files describe @@ -750,7 +750,7 @@ config file. These will be inserted early in the command line, so your later options can override them if needed. The config file can contain general options (which will be used with all commands that support them), and command-specific options (or arguments). hledger.conf.sample -is an example, which you can install as './hledger.conf' or +is an example, which you can install as, eg, './hledger.conf' or '$HOME/.hledger.conf'. To be precise, hledger looks for 'hledger.conf' in the current @@ -763,10 +763,14 @@ config file by using the '--conf' option, or by adding a 'hledger config files with '--debug' or '--debug=8'. If you want to run hledger without a config file, to ensure standard -defaults and behaviour, use the '-n/--no-conf' flag. This is useful -when troubleshooting problems or sharing examples. +defaults and behaviour, use the '-n/--no-conf' flag. This is +recommended when using hledger in scripts, and when troubleshooting +problems. - _(Added in 1.40; experimental)_ + When both '--conf' and '--no-conf' options are used, the last +(right-most) wins. + + _(in master, experimental)_  File: hledger.info, Node: Output, Next: Environment, Prev: Options, Up: Top @@ -811,20 +815,18 @@ File: hledger.info, Node: Output format, Next: Commodity styles, Prev: Output Some commands offer other kinds of output, not just text on the terminal. Here are those commands and the formats currently supported: -- txt csv/tsv html json sql -------------------------------------------------------------------------------- -aregister Y Y Y Y -balance Y _1_ Y _1_ Y _1,2_ Y -balancesheet Y _1_ Y _1_ Y _1_ Y -balancesheetequityY _1_ Y _1_ Y _1_ Y -cashflow Y _1_ Y _1_ Y _1_ Y -incomestatement Y _1_ Y _1_ Y _1_ Y -print Y Y Y Y -register Y Y Y +- txt csv/tsv html fods json sql +----------------------------------------------------------------------------- +aregister Y Y Y Y +balance Y _1_ Y _1_ Y _1_ Y _1_ Y +balancesheet Y _1_ Y _1_ Y _1_ Y +balancesheetequityY _1_ Y _1_ Y _1_ Y +cashflow Y _1_ Y _1_ Y _1_ Y +incomestatementY _1_ Y _1_ Y _1_ Y +print Y Y Y Y +register Y Y Y * _1 Also affected by the balance commands' '--layout' option._ - * _2 'balance' does not support html output without a report interval - or with '--budget'._ The output format is selected by the '-O/--output-format=FMT' option: @@ -1061,7 +1063,7 @@ of one app against the other. use the add or web or import commands to create and update it. Many users, though, edit the journal file with a text editor, and -track changes with a version control system such as git. Editor addons +track changes with a version control system such as git. Editor add-ons such as ledger-mode or hledger-mode for Emacs, vim-ledger for Vim, and hledger-vscode for Visual Studio Code, make this easier, adding colour, formatting, tab completion, and useful commands. See Editor @@ -5313,12 +5315,13 @@ $ hledger -f sample.timeclock register -p weekly --depth 1 --empty # time summa To generate time logs, ie to clock in and clock out, you could: - * use emacs and the built-in timeclock.el, or the extended - timeclock-x.el and perhaps the extras in ledgerutils.el + * use these shell aliases at the command line: - * at the command line, use these bash aliases: 'cli alias ti="echo i - `date '+%Y-%m-%d %H:%M:%S'` \$* >>$TIMELOG" alias to="echo o `date - '+%Y-%m-%d %H:%M:%S'` >>$TIMELOG"' + alias ti='echo i `date "+%Y-%m-%d %H:%M:%S"` $* >>$TIMELOG' + alias to='echo o `date "+%Y-%m-%d %H:%M:%S"` >>$TIMELOG' + + * or Emacs's built-in timeclock.el, or the extended timeclock-x.el, + and perhaps the extras in ledgerutils.el * or use the old 'ti' and 'to' scripts in the ledger 2.x repository. These rely on a "timeclock" executable which I think is just the @@ -5529,7 +5532,8 @@ File: hledger.info, Node: Time periods, Next: Depth, Prev: PART 3 REPORTING C * Report start & end date:: * Smart dates:: * Report intervals:: -* Date adjustment:: +* Date adjustments:: +* Period headings:: * Period expressions::  @@ -5649,7 +5653,7 @@ override that. (Except for periodic transaction rules, which are not affected by '--today'.)  -File: hledger.info, Node: Report intervals, Next: Date adjustment, Prev: Smart dates, Up: Time periods +File: hledger.info, Node: Report intervals, Next: Date adjustments, Prev: Smart dates, Up: Time periods 13.3 Report intervals ===================== @@ -5671,33 +5675,86 @@ flags: described below.  -File: hledger.info, Node: Date adjustment, Next: Period expressions, Prev: Report intervals, Up: Time periods +File: hledger.info, Node: Date adjustments, Next: Period headings, Prev: Report intervals, Up: Time periods -13.4 Date adjustment -==================== +13.4 Date adjustments +===================== + +* Menu: + +* Start date adjustment:: +* End date adjustment:: + + +File: hledger.info, Node: Start date adjustment, Next: End date adjustment, Up: Date adjustments + +13.4.1 Start date adjustment +---------------------------- + +If you let hledger infer a report's start date, it will adjust the date +to the previous natural boundary of the report interval, for convenient +periodic reports. (If you don't want that, specify a start date.) + + For example, if the journal's first transaction is on january 10th, -When there is a report interval (other than daily), report start/end -dates which have been inferred, eg from the journal, are automatically -adjusted to natural period boundaries. This is convenient for producing -simple periodic reports. More precisely: + * 'hledger register' (no report interval) will start the report on + january 10th. + * 'hledger register --monthly' will start the report on the previous + month boundary, january 1st. + * 'hledger register --monthly --begin 1/5' will start the report on + january 5th [1]. - * an inferred start date will be adjusted earlier if needed to fall - on a natural period boundary + Also if you are generating transactions or budget goals with periodic +transaction rules, their start date may be adjusted in a similar way (in +certain situations). - * an inferred end date will be adjusted later if needed to make the - last period the same length as the others. + +File: hledger.info, Node: End date adjustment, Prev: Start date adjustment, Up: Date adjustments + +13.4.2 End date adjustment +-------------------------- + +A report's end date is always adjusted to include a whole number of +intervals, so that the last subperiod has the same length as the others. + + For example, if the journal's last transaction is on february 20th, + + * 'hledger register' will end the report on february 20th. + * 'hledger register --monthly' will end the report at the end of + february. + * 'hledger register --monthly --end 2/14' also will end the report at + the end of february. + * 'hledger register --monthly --begin 1/5 --end 2/14' will end the + report on march 4th [1]. + + [1] Since hledger 1.29. - By contrast, start/end dates which have been specified explicitly, -with '-b', '-e', '-p' or 'date:', will not be adjusted (since hledger -1.29). This makes it possible to specify non-standard report periods, -but it also means that if you are specifying a start date, you should -pick one that's on a period boundary if you want to see simple report -period headings. + +File: hledger.info, Node: Period headings, Next: Period expressions, Prev: Date adjustments, Up: Time periods + +13.5 Period headings +==================== + +With non-standard subperiods, hledger will show "STARTDATE..ENDDATE" +headings. With standard subperiods (ie, starting on a natural interval +boundary), you'll see more compact headings, which are usually +preferable. (Though month names will be in english, currently.) + + So if you are specifying a start date and you want compact headings: +choose a start of year for yearly reports, a start of quarter for +quarterly reports, a start of month for monthly reports, etc. +(Remember, you can write eg '-b 2024' or '1/1' as a shortcut for a start +of year, or '2024-04' or '202404' or 'Apr' for a start of month or +quarter.) + + For weekly reports, choose a date that's a Monday. (You can try +different dates until you see the short headings, or write eg '-b '3 +weeks ago''.)  -File: hledger.info, Node: Period expressions, Prev: Date adjustment, Up: Time periods +File: hledger.info, Node: Period expressions, Prev: Period headings, Up: Time periods -13.5 Period expressions +13.6 Period expressions ======================= The '-p/--period' option specifies a period expression, which is a @@ -5757,7 +5814,7 @@ date:  File: hledger.info, Node: Period expressions with a report interval, Next: More complex report intervals, Up: Period expressions -13.5.1 Period expressions with a report interval +13.6.1 Period expressions with a report interval ------------------------------------------------ A period expression can also begin with a report interval, separated @@ -5770,7 +5827,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 -13.5.2 More complex report intervals +13.6.2 More complex report intervals ------------------------------------ Some more complex intervals can be specified within period expressions, @@ -5795,7 +5852,7 @@ such as: month's last day) * 'every Nth WEEKDAYNAME [of month]' - Yearly on a custom day: + Yearly on a custom month and day: * 'every MM/DD [of year]' (month number and day of month number) * 'every MONTHNAME DDth [of year]' (full or three-letter english @@ -5834,7 +5891,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 -13.5.3 Multiple weekday intervals +13.6.3 Multiple weekday intervals --------------------------------- This special form is also supported: @@ -6299,7 +6356,7 @@ $ hledger print --forecast --today=2023/4/21 expenses:rent $1000 Here there are no ordinary transactions, so the forecasted -transactions begin on the first occurence after today's date. (You +transactions begin on the first occurrence after today's date. (You won't normally use '--today'; it's just to make these examples reproducible.) @@ -7598,8 +7655,6 @@ or press control-d or control-c to exit. * The tab key will auto-complete whenever possible - accounts, payees/descriptions, dates ('yesterday', 'today', 'tomorrow'). If the input area is empty, it will insert the default value. - * If the journal defines a default commodity, it will be added to any - bare numbers entered. * A parenthesised transaction code may be entered following a date. * Comments and tags may be entered following a description or amount. * If you make a mistake, enter '<' at any prompt to go one step @@ -9124,7 +9179,7 @@ Flags: 'bare' : commodity symbols in one column 'tidy' : every attribute in its own column -O --output-format=FMT select the output format. Supported formats: - txt, html, csv, tsv, json. + txt, html, csv, tsv, json, fods. -o --output-file=FILE write output to FILE. A file extension matching one of the above formats selects that format. @@ -9215,8 +9270,9 @@ higher-level commands as well. This command supports the output destination and output format options, with output formats 'txt', 'csv', 'tsv' (_Added in 1.32_), -'json', and (multi-period reports only:) 'html'. In 'txt' output in a -colour-supporting terminal, negative amounts are shown in red. +'json', and (multi-period reports only:) 'html', 'fods' (_Added in +1.40_). In 'txt' output in a 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 @@ -11615,684 +11671,690 @@ See hledger and Ledger for full details.  Tag Table: Node: Top208 -Node: PART 1 USER INTERFACE4363 -Ref: #part-1-user-interface4502 -Node: Input4502 -Ref: #input4612 -Node: Text encoding5579 -Ref: #text-encoding5693 -Node: Data formats6259 -Ref: #data-formats6394 -Node: Standard input7983 -Ref: #standard-input8123 -Node: Multiple files8372 -Ref: #multiple-files8511 -Node: Strict mode9109 -Ref: #strict-mode9219 -Node: Commands9943 -Ref: #commands10045 -Node: Add-on commands11112 -Ref: #add-on-commands11214 -Node: Options12330 -Ref: #options12431 -Node: Special characters18725 -Ref: #special-characters18862 -Node: Single escaping shell metacharacters19025 -Ref: #single-escaping-shell-metacharacters19266 -Node: Double escaping regular expression metacharacters19869 -Ref: #double-escaping-regular-expression-metacharacters20180 -Node: Triple escaping for add-on commands20706 -Ref: #triple-escaping-for-add-on-commands20966 -Node: Less escaping21610 -Ref: #less-escaping21764 -Node: Unicode characters22088 -Ref: #unicode-characters22253 -Node: Regular expressions23752 -Ref: #regular-expressions23915 -Node: hledger's regular expressions27011 -Ref: #hledgers-regular-expressions27170 -Node: Argument files28556 -Ref: #argument-files28703 -Node: Config files29209 -Ref: #config-files29324 -Node: Output30500 -Ref: #output30602 -Node: Output destination30729 -Ref: #output-destination30860 -Node: Output format31285 -Ref: #output-format31431 -Node: CSV output33028 -Ref: #csv-output33144 -Node: HTML output33247 -Ref: #html-output33385 -Node: JSON output33479 -Ref: #json-output33617 -Node: SQL output34602 -Ref: #sql-output34718 -Node: Commodity styles35453 -Ref: #commodity-styles35593 -Node: Colour36331 -Ref: #colour36449 -Node: Box-drawing36853 -Ref: #box-drawing36971 -Node: Paging37255 -Ref: #paging37369 -Node: Debug output38322 -Ref: #debug-output38428 -Node: Environment39091 -Ref: #environment39215 -Node: PART 2 DATA FORMATS39782 -Ref: #part-2-data-formats39925 -Node: Journal39925 -Ref: #journal40034 -Node: Journal cheatsheet42402 -Ref: #journal-cheatsheet42529 -Node: Comments48616 -Ref: #comments48744 -Node: Transactions49560 -Ref: #transactions49683 -Node: Dates50697 -Ref: #dates50804 -Node: Simple dates50849 -Ref: #simple-dates50965 -Node: Posting dates51465 -Ref: #posting-dates51583 -Node: Status52552 -Ref: #status52653 -Node: Code54318 -Ref: #code54421 -Node: Description54653 -Ref: #description54784 -Node: Payee and note55340 -Ref: #payee-and-note55446 -Node: Transaction comments56431 -Ref: #transaction-comments56584 -Node: Postings56947 -Ref: #postings57078 -Node: Debits and credits58110 -Ref: #debits-and-credits58257 -Node: The two space delimiter58720 -Ref: #the-two-space-delimiter58877 -Node: Account names59285 -Ref: #account-names59415 -Node: Amounts61089 -Ref: #amounts61217 -Node: Decimal marks62118 -Ref: #decimal-marks62245 -Node: Digit group marks63222 -Ref: #digit-group-marks63375 -Node: Commodity63857 -Ref: #commodity63986 -Node: Costs64974 -Ref: #costs65069 -Node: Balance assertions67226 -Ref: #balance-assertions67379 -Node: Assertions and ordering68463 -Ref: #assertions-and-ordering68652 -Node: Assertions and multiple included files69191 -Ref: #assertions-and-multiple-included-files69451 -Node: Assertions and multiple -f files69951 -Ref: #assertions-and-multiple--f-files70196 -Node: Assertions and costs70593 -Ref: #assertions-and-costs70802 -Node: Assertions and commodities71243 -Ref: #assertions-and-commodities71458 -Node: Assertions and subaccounts72902 -Ref: #assertions-and-subaccounts73128 -Node: Assertions and virtual postings73572 -Ref: #assertions-and-virtual-postings73810 -Node: Assertions and auto postings73942 -Ref: #assertions-and-auto-postings74172 -Node: Assertions and precision74817 -Ref: #assertions-and-precision74999 -Node: Posting comments75266 -Ref: #posting-comments75429 -Node: Transaction balancing75806 -Ref: #transaction-balancing75965 -Node: Tags77808 -Ref: #tags77927 -Node: Tag names79270 -Ref: #tag-names79377 -Node: Special tags79765 -Ref: #special-tags79897 -Node: Tag values81410 -Ref: #tag-values81520 -Node: Directives82392 -Ref: #directives82519 -Node: Directives and multiple files83849 -Ref: #directives-and-multiple-files84027 -Node: Directive effects84794 -Ref: #directive-effects84948 -Node: account directive87950 -Ref: #account-directive88106 -Node: Account comments89400 -Ref: #account-comments89551 -Node: Account error checking90059 -Ref: #account-error-checking90252 -Node: Account display order91441 -Ref: #account-display-order91629 -Node: Account types92639 -Ref: #account-types92780 -Node: alias directive96413 -Ref: #alias-directive96574 -Node: Basic aliases97624 -Ref: #basic-aliases97755 -Node: Regex aliases98499 -Ref: #regex-aliases98656 -Node: Combining aliases99546 -Ref: #combining-aliases99724 -Node: Aliases and multiple files101000 -Ref: #aliases-and-multiple-files101204 -Node: end aliases directive101783 -Ref: #end-aliases-directive102002 -Node: Aliases can generate bad account names102151 -Ref: #aliases-can-generate-bad-account-names102399 -Node: Aliases and account types102984 -Ref: #aliases-and-account-types103176 -Node: commodity directive103872 -Ref: #commodity-directive104046 -Node: Commodity directive syntax105459 -Ref: #commodity-directive-syntax105644 -Node: Commodity error checking107095 -Ref: #commodity-error-checking107276 -Node: decimal-mark directive107570 -Ref: #decimal-mark-directive107752 -Node: include directive108149 -Ref: #include-directive108313 -Node: P directive109225 -Ref: #p-directive109370 -Node: payee directive110259 -Ref: #payee-directive110408 -Node: tag directive110881 -Ref: #tag-directive111036 -Node: Periodic transactions111493 -Ref: #periodic-transactions111658 -Node: Periodic rule syntax113647 -Ref: #periodic-rule-syntax113825 -Node: Periodic rules and relative dates114470 -Ref: #periodic-rules-and-relative-dates114736 -Node: Two spaces between period expression and description!115247 -Ref: #two-spaces-between-period-expression-and-description115524 -Node: Auto postings116208 -Ref: #auto-postings116356 -Node: Auto postings and multiple files119368 -Ref: #auto-postings-and-multiple-files119564 -Node: Auto postings and dates119773 -Ref: #auto-postings-and-dates120039 -Node: Auto postings and transaction balancing / inferred amounts / balance assertions120214 -Ref: #auto-postings-and-transaction-balancing-inferred-amounts-balance-assertions120557 -Node: Auto posting tags121060 -Ref: #auto-posting-tags121319 -Node: Auto postings on forecast transactions only121955 -Ref: #auto-postings-on-forecast-transactions-only122178 -Node: Other syntax122425 -Ref: #other-syntax122541 -Node: Balance assignments123197 -Ref: #balance-assignments123353 -Node: Balance assignments and costs124725 -Ref: #balance-assignments-and-costs124937 -Node: Balance assignments and multiple files125147 -Ref: #balance-assignments-and-multiple-files125377 -Node: Bracketed posting dates125570 -Ref: #bracketed-posting-dates125754 -Node: D directive126268 -Ref: #d-directive126436 -Node: apply account directive128041 -Ref: #apply-account-directive128221 -Node: Y directive128908 -Ref: #y-directive129068 -Node: Secondary dates129896 -Ref: #secondary-dates130050 -Node: Star comments131381 -Ref: #star-comments131541 -Node: Valuation expressions132073 -Ref: #valuation-expressions132250 -Node: Virtual postings132372 -Ref: #virtual-postings132549 -Node: Other Ledger directives133996 -Ref: #other-ledger-directives134192 -Node: Other cost/lot notations134758 -Ref: #other-costlot-notations134931 -Node: CSV137520 -Ref: #csv137611 -Node: CSV rules cheatsheet139603 -Ref: #csv-rules-cheatsheet139730 -Node: source141528 -Ref: #source141649 -Node: separator142529 -Ref: #separator142640 -Node: skip143180 -Ref: #skip143286 -Node: date-format143830 -Ref: #date-format143949 -Node: timezone144673 -Ref: #timezone144794 -Node: newest-first145799 -Ref: #newest-first145935 -Node: intra-day-reversed146512 -Ref: #intra-day-reversed146664 -Node: decimal-mark147112 -Ref: #decimal-mark147251 -Node: fields list147590 -Ref: #fields-list147727 -Node: Field assignment149398 -Ref: #field-assignment149540 -Node: Field names150617 -Ref: #field-names150746 -Node: date field151949 -Ref: #date-field152065 -Node: date2 field152113 -Ref: #date2-field152252 -Node: status field152308 -Ref: #status-field152449 -Node: code field152498 -Ref: #code-field152641 -Node: description field152686 -Ref: #description-field152844 -Node: comment field152903 -Ref: #comment-field153056 -Node: account field153349 -Ref: #account-field153497 -Node: amount field154067 -Ref: #amount-field154214 -Node: currency field156906 -Ref: #currency-field157057 -Node: balance field157314 -Ref: #balance-field157444 -Node: if block157837 -Ref: #if-block157956 -Node: Matchers159364 -Ref: #matchers159476 -Node: What matchers match160273 -Ref: #what-matchers-match160420 -Node: Combining matchers160860 -Ref: #combining-matchers161026 -Node: Match groups161563 -Ref: #match-groups161689 -Node: if table162457 -Ref: #if-table162577 -Node: balance-type164458 -Ref: #balance-type164585 -Node: include165285 -Ref: #include165410 -Node: Working with CSV165854 -Ref: #working-with-csv165999 -Node: Rapid feedback166406 -Ref: #rapid-feedback166537 -Node: Valid CSV166989 -Ref: #valid-csv167133 -Node: File Extension167865 -Ref: #file-extension168036 -Node: Reading CSV from standard input168600 -Ref: #reading-csv-from-standard-input168822 -Node: Reading multiple CSV files168986 -Ref: #reading-multiple-csv-files169215 -Node: Reading files specified by rule169462 -Ref: #reading-files-specified-by-rule169688 -Node: Valid transactions170859 -Ref: #valid-transactions171056 -Node: Deduplicating importing171684 -Ref: #deduplicating-importing171877 -Node: Setting amounts172913 -Ref: #setting-amounts173082 -Node: Amount signs175440 -Ref: #amount-signs175608 -Node: Setting currency/commodity176505 -Ref: #setting-currencycommodity176707 -Node: Amount decimal places177881 -Ref: #amount-decimal-places178085 -Node: Referencing other fields179138 -Ref: #referencing-other-fields179349 -Node: How CSV rules are evaluated180246 -Ref: #how-csv-rules-are-evaluated180461 -Node: Well factored rules181914 -Ref: #well-factored-rules182080 -Node: CSV rules examples182404 -Ref: #csv-rules-examples182537 -Node: Bank of Ireland182602 -Ref: #bank-of-ireland182737 -Node: Coinbase184199 -Ref: #coinbase184335 -Node: Amazon185382 -Ref: #amazon185505 -Node: Paypal187224 -Ref: #paypal187330 -Node: Timeclock194974 -Ref: #timeclock195079 -Node: Timedot197255 -Ref: #timedot197378 -Node: Timedot examples200499 -Ref: #timedot-examples200605 -Node: PART 3 REPORTING CONCEPTS202776 -Ref: #part-3-reporting-concepts202940 -Node: Time periods202940 -Ref: #time-periods203074 -Node: Report start & end date203192 -Ref: #report-start-end-date203344 -Node: Smart dates204668 -Ref: #smart-dates204821 -Node: Report intervals206611 -Ref: #report-intervals206766 -Node: Date adjustment207184 -Ref: #date-adjustment207344 -Node: Period expressions208195 -Ref: #period-expressions208336 -Node: Period expressions with a report interval210100 -Ref: #period-expressions-with-a-report-interval210334 -Node: More complex report intervals210548 -Ref: #more-complex-report-intervals210793 -Node: Multiple weekday intervals212654 -Ref: #multiple-weekday-intervals212843 -Node: Depth213665 -Ref: #depth213767 -Node: Queries214063 -Ref: #queries214165 -Node: Query types215761 -Ref: #query-types215882 -Node: Combining query terms219116 -Ref: #combining-query-terms219293 -Node: Queries and command options220856 -Ref: #queries-and-command-options221061 -Node: Queries and account aliases221310 -Ref: #queries-and-account-aliases221515 -Node: Queries and valuation221635 -Ref: #queries-and-valuation221792 -Node: Pivoting221997 -Ref: #pivoting222111 -Node: Generating data223888 -Ref: #generating-data224020 -Node: Forecasting225688 -Ref: #forecasting225813 -Node: --forecast226344 -Ref: #forecast226475 -Node: Inspecting forecast transactions227445 -Ref: #inspecting-forecast-transactions227647 -Node: Forecast reports228777 -Ref: #forecast-reports228950 -Node: Forecast tags229886 -Ref: #forecast-tags230046 -Node: Forecast period in detail230506 -Ref: #forecast-period-in-detail230700 -Node: Forecast troubleshooting231594 -Ref: #forecast-troubleshooting231762 -Node: Budgeting232665 -Ref: #budgeting232788 -Node: Amount formatting233225 -Ref: #amount-formatting233367 -Node: Commodity display style233469 -Ref: #commodity-display-style233623 -Node: Rounding235310 -Ref: #rounding235465 -Node: Trailing decimal marks235915 -Ref: #trailing-decimal-marks236094 -Node: Amount parseability236848 -Ref: #amount-parseability237004 -Node: Cost reporting238429 -Ref: #cost-reporting238571 -Node: Recording costs239232 -Ref: #recording-costs239368 -Node: Reporting at cost240959 -Ref: #reporting-at-cost241134 -Node: Equity conversion postings241724 -Ref: #equity-conversion-postings241938 -Node: Inferring equity conversion postings244369 -Ref: #inferring-equity-conversion-postings244632 -Node: Combining costs and equity conversion postings245384 -Ref: #combining-costs-and-equity-conversion-postings245694 -Node: Requirements for detecting equity conversion postings246609 -Ref: #requirements-for-detecting-equity-conversion-postings246931 -Node: Infer cost and equity by default ?248131 -Ref: #infer-cost-and-equity-by-default248360 -Node: Value reporting248568 -Ref: #value-reporting248710 -Node: -V Value249449 -Ref: #v-value249581 -Node: -X Value in specified commodity249776 -Ref: #x-value-in-specified-commodity249977 -Node: Valuation date250126 -Ref: #valuation-date250303 -Node: Finding market price251086 -Ref: #finding-market-price251297 -Node: --infer-market-prices market prices from transactions252466 -Ref: #infer-market-prices-market-prices-from-transactions252748 -Node: Valuation commodity255510 -Ref: #valuation-commodity255730 -Node: --value Flexible valuation256943 -Ref: #value-flexible-valuation257142 -Node: Valuation examples258786 -Ref: #valuation-examples258986 -Node: Interaction of valuation and queries260918 -Ref: #interaction-of-valuation-and-queries261158 -Node: Effect of valuation on reports261635 -Ref: #effect-of-valuation-on-reports261838 -Node: PART 4 COMMANDS269533 -Ref: #part-4-commands269676 -Node: Help commands271749 -Ref: #help-commands271894 -Node: help271922 -Ref: #help272011 -Node: demo273599 -Ref: #demo273688 -Node: User interface commands274732 -Ref: #user-interface-commands274901 -Node: ui274926 -Ref: #ui275018 -Node: web275051 -Ref: #web275145 -Node: Data entry commands275179 -Ref: #data-entry-commands275348 -Node: add275377 -Ref: #add275471 -Node: import277932 -Ref: #import278032 -Node: Date skipping279193 -Ref: #date-skipping279316 -Node: Import testing282094 -Ref: #import-testing282257 -Node: Importing balance assignments283100 -Ref: #importing-balance-assignments283307 -Node: Import and commodity styles283956 -Ref: #import-and-commodity-styles284136 -Node: Basic report commands284365 -Ref: #basic-report-commands284539 -Node: accounts284666 -Ref: #accounts284776 -Node: codes287539 -Ref: #codes287663 -Node: commodities288561 -Ref: #commodities288701 -Node: descriptions288805 -Ref: #descriptions288947 -Node: files289272 -Ref: #files289394 -Node: notes289569 -Ref: #notes289685 -Node: payees290081 -Ref: #payees290200 -Node: prices290865 -Ref: #prices290984 -Node: stats291757 -Ref: #stats291872 -Node: tags293498 -Ref: #tags-1293598 -Node: Standard report commands294805 -Ref: #standard-report-commands294990 -Node: print295110 -Ref: #print295218 -Node: print explicitness297556 -Ref: #print-explicitness297697 -Node: print amount style298476 -Ref: #print-amount-style298644 -Node: print parseability299714 -Ref: #print-parseability299884 -Node: print other features300633 -Ref: #print-other-features300810 -Node: print output format301331 -Ref: #print-output-format301477 -Node: aregister304616 -Ref: #aregister304749 -Node: aregister and posting dates308396 -Ref: #aregister-and-posting-dates308541 -Node: register309297 -Ref: #register309435 -Node: Custom register output315600 -Ref: #custom-register-output315729 -Node: balancesheet317076 -Ref: #balancesheet317231 -Node: balancesheetequity321712 -Ref: #balancesheetequity321879 -Node: cashflow326718 -Ref: #cashflow326868 -Node: incomestatement331146 -Ref: #incomestatement331283 -Node: Advanced report commands335610 -Ref: #advanced-report-commands335788 -Node: balance335818 -Ref: #balance335926 -Node: balance features340701 -Ref: #balance-features340841 -Node: Simple balance report342751 -Ref: #simple-balance-report342936 -Node: Balance report line format344561 -Ref: #balance-report-line-format344763 -Node: Filtered balance report346921 -Ref: #filtered-balance-report347113 -Node: List or tree mode347440 -Ref: #list-or-tree-mode347608 -Node: Depth limiting348953 -Ref: #depth-limiting349119 -Node: Dropping top-level accounts349720 -Ref: #dropping-top-level-accounts349920 -Node: Showing declared accounts350230 -Ref: #showing-declared-accounts350429 -Node: Sorting by amount350960 -Ref: #sorting-by-amount351127 -Node: Percentages351797 -Ref: #percentages351956 -Node: Multi-period balance report352504 -Ref: #multi-period-balance-report352704 -Node: Balance change end balance355256 -Ref: #balance-change-end-balance355465 -Node: Balance report types356893 -Ref: #balance-report-types357074 -Node: Calculation type357572 -Ref: #calculation-type357727 -Node: Accumulation type358276 -Ref: #accumulation-type358456 -Node: Valuation type359377 -Ref: #valuation-type359565 -Node: Combining balance report types360566 -Ref: #combining-balance-report-types360760 -Node: Budget report362598 -Ref: #budget-report362760 -Node: Using the budget report364903 -Ref: #using-the-budget-report365076 -Node: Budget date surprises367179 -Ref: #budget-date-surprises367379 -Node: Selecting budget goals368543 -Ref: #selecting-budget-goals368746 -Node: Budgeting vs forecasting369491 -Ref: #budgeting-vs-forecasting369668 -Node: Balance report layout371168 -Ref: #balance-report-layout371353 -Node: Wide layout372306 -Ref: #wide-layout372441 -Node: Tall layout374711 -Ref: #tall-layout374866 -Node: Bare layout376017 -Ref: #bare-layout376172 -Node: Tidy layout378081 -Ref: #tidy-layout378216 -Node: Some useful balance reports379625 -Ref: #some-useful-balance-reports379800 -Node: roi380885 -Ref: #roi380985 -Node: Spaces and special characters in --inv and --pnl383132 -Ref: #spaces-and-special-characters-in---inv-and---pnl383370 -Node: Semantics of --inv and --pnl383858 -Ref: #semantics-of---inv-and---pnl384095 -Node: IRR and TWR explained385945 -Ref: #irr-and-twr-explained386103 -Node: Chart commands389356 -Ref: #chart-commands389514 -Node: activity389537 -Ref: #activity389626 -Node: Data generation commands390034 -Ref: #data-generation-commands390208 -Node: close390240 -Ref: #close390346 -Node: close --migrate392832 -Ref: #close---migrate392957 -Node: close --close394596 -Ref: #close---close394738 -Node: close --open394974 -Ref: #close---open395113 -Node: close --assert395223 -Ref: #close---assert395367 -Node: close --assign395588 -Ref: #close---assign395734 -Node: close --retain396260 -Ref: #close---retain396411 -Node: close customisation397156 -Ref: #close-customisation397333 -Node: close and balance assertions398800 -Ref: #close-and-balance-assertions398995 -Node: close examples400322 -Ref: #close-examples400461 -Node: Retain earnings400559 -Ref: #retain-earnings400716 -Node: Migrate balances to a new file401062 -Ref: #migrate-balances-to-a-new-file401286 -Node: More detailed close examples402414 -Ref: #more-detailed-close-examples402610 -Node: rewrite402636 -Ref: #rewrite402746 -Node: Re-write rules in a file405208 -Ref: #re-write-rules-in-a-file405369 -Node: Diff output format406518 -Ref: #diff-output-format406699 -Node: rewrite vs print --auto407791 -Ref: #rewrite-vs.-print---auto407949 -Node: Maintenance commands408505 -Ref: #maintenance-commands408676 -Node: check408714 -Ref: #check408813 -Node: Basic checks409796 -Ref: #basic-checks409914 -Node: Strict checks410749 -Ref: #strict-checks410890 -Node: Other checks411624 -Ref: #other-checks411764 -Node: Custom checks413479 -Ref: #custom-checks413599 -Node: diff413934 -Ref: #diff414044 -Node: test415141 -Ref: #test415237 -Node: PART 5 COMMON TASKS416013 -Ref: #part-5-common-tasks416172 -Node: Getting help416246 -Ref: #getting-help416395 -Node: Constructing command lines417155 -Ref: #constructing-command-lines417336 -Node: Starting a journal file417993 -Ref: #starting-a-journal-file418175 -Node: Setting LEDGER_FILE419377 -Ref: #setting-ledger_file419549 -Node: Setting opening balances420506 -Ref: #setting-opening-balances420687 -Node: Recording transactions423828 -Ref: #recording-transactions423997 -Node: Reconciling424553 -Ref: #reconciling424685 -Node: Reporting426942 -Ref: #reporting427071 -Node: Migrating to a new file431056 -Ref: #migrating-to-a-new-file431206 -Node: BUGS431505 -Ref: #bugs431599 -Node: Troubleshooting432478 -Ref: #troubleshooting432578 +Node: PART 1 USER INTERFACE4360 +Ref: #part-1-user-interface4499 +Node: Input4499 +Ref: #input4609 +Node: Text encoding5591 +Ref: #text-encoding5705 +Node: Data formats6271 +Ref: #data-formats6406 +Node: Standard input7995 +Ref: #standard-input8135 +Node: Multiple files8384 +Ref: #multiple-files8523 +Node: Strict mode9121 +Ref: #strict-mode9231 +Node: Commands9955 +Ref: #commands10057 +Node: Add-on commands11124 +Ref: #add-on-commands11226 +Node: Options12342 +Ref: #options12443 +Node: Special characters18737 +Ref: #special-characters18874 +Node: Single escaping shell metacharacters19037 +Ref: #single-escaping-shell-metacharacters19278 +Node: Double escaping regular expression metacharacters19881 +Ref: #double-escaping-regular-expression-metacharacters20192 +Node: Triple escaping for add-on commands20718 +Ref: #triple-escaping-for-add-on-commands20978 +Node: Less escaping21622 +Ref: #less-escaping21776 +Node: Unicode characters22100 +Ref: #unicode-characters22265 +Node: Regular expressions23764 +Ref: #regular-expressions23927 +Node: hledger's regular expressions27023 +Ref: #hledgers-regular-expressions27182 +Node: Argument files28568 +Ref: #argument-files28715 +Node: Config files29221 +Ref: #config-files29336 +Node: Output30618 +Ref: #output30720 +Node: Output destination30847 +Ref: #output-destination30978 +Node: Output format31403 +Ref: #output-format31549 +Node: CSV output33034 +Ref: #csv-output33150 +Node: HTML output33253 +Ref: #html-output33391 +Node: JSON output33485 +Ref: #json-output33623 +Node: SQL output34608 +Ref: #sql-output34724 +Node: Commodity styles35459 +Ref: #commodity-styles35599 +Node: Colour36337 +Ref: #colour36455 +Node: Box-drawing36859 +Ref: #box-drawing36977 +Node: Paging37261 +Ref: #paging37375 +Node: Debug output38328 +Ref: #debug-output38434 +Node: Environment39097 +Ref: #environment39221 +Node: PART 2 DATA FORMATS39788 +Ref: #part-2-data-formats39931 +Node: Journal39931 +Ref: #journal40040 +Node: Journal cheatsheet42409 +Ref: #journal-cheatsheet42536 +Node: Comments48623 +Ref: #comments48751 +Node: Transactions49567 +Ref: #transactions49690 +Node: Dates50704 +Ref: #dates50811 +Node: Simple dates50856 +Ref: #simple-dates50972 +Node: Posting dates51472 +Ref: #posting-dates51590 +Node: Status52559 +Ref: #status52660 +Node: Code54325 +Ref: #code54428 +Node: Description54660 +Ref: #description54791 +Node: Payee and note55347 +Ref: #payee-and-note55453 +Node: Transaction comments56438 +Ref: #transaction-comments56591 +Node: Postings56954 +Ref: #postings57085 +Node: Debits and credits58117 +Ref: #debits-and-credits58264 +Node: The two space delimiter58727 +Ref: #the-two-space-delimiter58884 +Node: Account names59292 +Ref: #account-names59422 +Node: Amounts61096 +Ref: #amounts61224 +Node: Decimal marks62125 +Ref: #decimal-marks62252 +Node: Digit group marks63229 +Ref: #digit-group-marks63382 +Node: Commodity63864 +Ref: #commodity63993 +Node: Costs64981 +Ref: #costs65076 +Node: Balance assertions67233 +Ref: #balance-assertions67386 +Node: Assertions and ordering68470 +Ref: #assertions-and-ordering68659 +Node: Assertions and multiple included files69198 +Ref: #assertions-and-multiple-included-files69458 +Node: Assertions and multiple -f files69958 +Ref: #assertions-and-multiple--f-files70203 +Node: Assertions and costs70600 +Ref: #assertions-and-costs70809 +Node: Assertions and commodities71250 +Ref: #assertions-and-commodities71465 +Node: Assertions and subaccounts72909 +Ref: #assertions-and-subaccounts73135 +Node: Assertions and virtual postings73579 +Ref: #assertions-and-virtual-postings73817 +Node: Assertions and auto postings73949 +Ref: #assertions-and-auto-postings74179 +Node: Assertions and precision74824 +Ref: #assertions-and-precision75006 +Node: Posting comments75273 +Ref: #posting-comments75436 +Node: Transaction balancing75813 +Ref: #transaction-balancing75972 +Node: Tags77815 +Ref: #tags77934 +Node: Tag names79277 +Ref: #tag-names79384 +Node: Special tags79772 +Ref: #special-tags79904 +Node: Tag values81417 +Ref: #tag-values81527 +Node: Directives82399 +Ref: #directives82526 +Node: Directives and multiple files83856 +Ref: #directives-and-multiple-files84034 +Node: Directive effects84801 +Ref: #directive-effects84955 +Node: account directive87957 +Ref: #account-directive88113 +Node: Account comments89407 +Ref: #account-comments89558 +Node: Account error checking90066 +Ref: #account-error-checking90259 +Node: Account display order91448 +Ref: #account-display-order91636 +Node: Account types92646 +Ref: #account-types92787 +Node: alias directive96420 +Ref: #alias-directive96581 +Node: Basic aliases97631 +Ref: #basic-aliases97762 +Node: Regex aliases98506 +Ref: #regex-aliases98663 +Node: Combining aliases99553 +Ref: #combining-aliases99731 +Node: Aliases and multiple files101007 +Ref: #aliases-and-multiple-files101211 +Node: end aliases directive101790 +Ref: #end-aliases-directive102009 +Node: Aliases can generate bad account names102158 +Ref: #aliases-can-generate-bad-account-names102406 +Node: Aliases and account types102991 +Ref: #aliases-and-account-types103183 +Node: commodity directive103879 +Ref: #commodity-directive104053 +Node: Commodity directive syntax105466 +Ref: #commodity-directive-syntax105651 +Node: Commodity error checking107102 +Ref: #commodity-error-checking107283 +Node: decimal-mark directive107577 +Ref: #decimal-mark-directive107759 +Node: include directive108156 +Ref: #include-directive108320 +Node: P directive109232 +Ref: #p-directive109377 +Node: payee directive110266 +Ref: #payee-directive110415 +Node: tag directive110888 +Ref: #tag-directive111043 +Node: Periodic transactions111500 +Ref: #periodic-transactions111665 +Node: Periodic rule syntax113654 +Ref: #periodic-rule-syntax113832 +Node: Periodic rules and relative dates114477 +Ref: #periodic-rules-and-relative-dates114743 +Node: Two spaces between period expression and description!115254 +Ref: #two-spaces-between-period-expression-and-description115531 +Node: Auto postings116215 +Ref: #auto-postings116363 +Node: Auto postings and multiple files119375 +Ref: #auto-postings-and-multiple-files119571 +Node: Auto postings and dates119780 +Ref: #auto-postings-and-dates120046 +Node: Auto postings and transaction balancing / inferred amounts / balance assertions120221 +Ref: #auto-postings-and-transaction-balancing-inferred-amounts-balance-assertions120564 +Node: Auto posting tags121067 +Ref: #auto-posting-tags121326 +Node: Auto postings on forecast transactions only121962 +Ref: #auto-postings-on-forecast-transactions-only122185 +Node: Other syntax122432 +Ref: #other-syntax122548 +Node: Balance assignments123204 +Ref: #balance-assignments123360 +Node: Balance assignments and costs124732 +Ref: #balance-assignments-and-costs124944 +Node: Balance assignments and multiple files125154 +Ref: #balance-assignments-and-multiple-files125384 +Node: Bracketed posting dates125577 +Ref: #bracketed-posting-dates125761 +Node: D directive126275 +Ref: #d-directive126443 +Node: apply account directive128048 +Ref: #apply-account-directive128228 +Node: Y directive128915 +Ref: #y-directive129075 +Node: Secondary dates129903 +Ref: #secondary-dates130057 +Node: Star comments131388 +Ref: #star-comments131548 +Node: Valuation expressions132080 +Ref: #valuation-expressions132257 +Node: Virtual postings132379 +Ref: #virtual-postings132556 +Node: Other Ledger directives134003 +Ref: #other-ledger-directives134199 +Node: Other cost/lot notations134765 +Ref: #other-costlot-notations134938 +Node: CSV137527 +Ref: #csv137618 +Node: CSV rules cheatsheet139610 +Ref: #csv-rules-cheatsheet139737 +Node: source141535 +Ref: #source141656 +Node: separator142536 +Ref: #separator142647 +Node: skip143187 +Ref: #skip143293 +Node: date-format143837 +Ref: #date-format143956 +Node: timezone144680 +Ref: #timezone144801 +Node: newest-first145806 +Ref: #newest-first145942 +Node: intra-day-reversed146519 +Ref: #intra-day-reversed146671 +Node: decimal-mark147119 +Ref: #decimal-mark147258 +Node: fields list147597 +Ref: #fields-list147734 +Node: Field assignment149405 +Ref: #field-assignment149547 +Node: Field names150624 +Ref: #field-names150753 +Node: date field151956 +Ref: #date-field152072 +Node: date2 field152120 +Ref: #date2-field152259 +Node: status field152315 +Ref: #status-field152456 +Node: code field152505 +Ref: #code-field152648 +Node: description field152693 +Ref: #description-field152851 +Node: comment field152910 +Ref: #comment-field153063 +Node: account field153356 +Ref: #account-field153504 +Node: amount field154074 +Ref: #amount-field154221 +Node: currency field156913 +Ref: #currency-field157064 +Node: balance field157321 +Ref: #balance-field157451 +Node: if block157844 +Ref: #if-block157963 +Node: Matchers159371 +Ref: #matchers159483 +Node: What matchers match160280 +Ref: #what-matchers-match160427 +Node: Combining matchers160867 +Ref: #combining-matchers161033 +Node: Match groups161570 +Ref: #match-groups161696 +Node: if table162464 +Ref: #if-table162584 +Node: balance-type164465 +Ref: #balance-type164592 +Node: include165292 +Ref: #include165417 +Node: Working with CSV165861 +Ref: #working-with-csv166006 +Node: Rapid feedback166413 +Ref: #rapid-feedback166544 +Node: Valid CSV166996 +Ref: #valid-csv167140 +Node: File Extension167872 +Ref: #file-extension168043 +Node: Reading CSV from standard input168607 +Ref: #reading-csv-from-standard-input168829 +Node: Reading multiple CSV files168993 +Ref: #reading-multiple-csv-files169222 +Node: Reading files specified by rule169469 +Ref: #reading-files-specified-by-rule169695 +Node: Valid transactions170866 +Ref: #valid-transactions171063 +Node: Deduplicating importing171691 +Ref: #deduplicating-importing171884 +Node: Setting amounts172920 +Ref: #setting-amounts173089 +Node: Amount signs175447 +Ref: #amount-signs175615 +Node: Setting currency/commodity176512 +Ref: #setting-currencycommodity176714 +Node: Amount decimal places177888 +Ref: #amount-decimal-places178092 +Node: Referencing other fields179145 +Ref: #referencing-other-fields179356 +Node: How CSV rules are evaluated180253 +Ref: #how-csv-rules-are-evaluated180468 +Node: Well factored rules181921 +Ref: #well-factored-rules182087 +Node: CSV rules examples182411 +Ref: #csv-rules-examples182544 +Node: Bank of Ireland182609 +Ref: #bank-of-ireland182744 +Node: Coinbase184206 +Ref: #coinbase184342 +Node: Amazon185389 +Ref: #amazon185512 +Node: Paypal187231 +Ref: #paypal187337 +Node: Timeclock194981 +Ref: #timeclock195086 +Node: Timedot197250 +Ref: #timedot197373 +Node: Timedot examples200494 +Ref: #timedot-examples200600 +Node: PART 3 REPORTING CONCEPTS202771 +Ref: #part-3-reporting-concepts202935 +Node: Time periods202935 +Ref: #time-periods203069 +Node: Report start & end date203208 +Ref: #report-start-end-date203360 +Node: Smart dates204684 +Ref: #smart-dates204837 +Node: Report intervals206627 +Ref: #report-intervals206783 +Node: Date adjustments207201 +Ref: #date-adjustments207361 +Node: Start date adjustment207421 +Ref: #start-date-adjustment207583 +Node: End date adjustment208324 +Ref: #end-date-adjustment208482 +Node: Period headings209069 +Ref: #period-headings209229 +Node: Period expressions210002 +Ref: #period-expressions210143 +Node: Period expressions with a report interval211907 +Ref: #period-expressions-with-a-report-interval212141 +Node: More complex report intervals212355 +Ref: #more-complex-report-intervals212600 +Node: Multiple weekday intervals214471 +Ref: #multiple-weekday-intervals214660 +Node: Depth215482 +Ref: #depth215584 +Node: Queries215880 +Ref: #queries215982 +Node: Query types217578 +Ref: #query-types217699 +Node: Combining query terms220933 +Ref: #combining-query-terms221110 +Node: Queries and command options222673 +Ref: #queries-and-command-options222878 +Node: Queries and account aliases223127 +Ref: #queries-and-account-aliases223332 +Node: Queries and valuation223452 +Ref: #queries-and-valuation223609 +Node: Pivoting223814 +Ref: #pivoting223928 +Node: Generating data225705 +Ref: #generating-data225837 +Node: Forecasting227505 +Ref: #forecasting227630 +Node: --forecast228161 +Ref: #forecast228292 +Node: Inspecting forecast transactions229262 +Ref: #inspecting-forecast-transactions229464 +Node: Forecast reports230595 +Ref: #forecast-reports230768 +Node: Forecast tags231704 +Ref: #forecast-tags231864 +Node: Forecast period in detail232324 +Ref: #forecast-period-in-detail232518 +Node: Forecast troubleshooting233412 +Ref: #forecast-troubleshooting233580 +Node: Budgeting234483 +Ref: #budgeting234606 +Node: Amount formatting235043 +Ref: #amount-formatting235185 +Node: Commodity display style235287 +Ref: #commodity-display-style235441 +Node: Rounding237128 +Ref: #rounding237283 +Node: Trailing decimal marks237733 +Ref: #trailing-decimal-marks237912 +Node: Amount parseability238666 +Ref: #amount-parseability238822 +Node: Cost reporting240247 +Ref: #cost-reporting240389 +Node: Recording costs241050 +Ref: #recording-costs241186 +Node: Reporting at cost242777 +Ref: #reporting-at-cost242952 +Node: Equity conversion postings243542 +Ref: #equity-conversion-postings243756 +Node: Inferring equity conversion postings246187 +Ref: #inferring-equity-conversion-postings246450 +Node: Combining costs and equity conversion postings247202 +Ref: #combining-costs-and-equity-conversion-postings247512 +Node: Requirements for detecting equity conversion postings248427 +Ref: #requirements-for-detecting-equity-conversion-postings248749 +Node: Infer cost and equity by default ?249949 +Ref: #infer-cost-and-equity-by-default250178 +Node: Value reporting250386 +Ref: #value-reporting250528 +Node: -V Value251267 +Ref: #v-value251399 +Node: -X Value in specified commodity251594 +Ref: #x-value-in-specified-commodity251795 +Node: Valuation date251944 +Ref: #valuation-date252121 +Node: Finding market price252904 +Ref: #finding-market-price253115 +Node: --infer-market-prices market prices from transactions254284 +Ref: #infer-market-prices-market-prices-from-transactions254566 +Node: Valuation commodity257328 +Ref: #valuation-commodity257548 +Node: --value Flexible valuation258761 +Ref: #value-flexible-valuation258960 +Node: Valuation examples260604 +Ref: #valuation-examples260804 +Node: Interaction of valuation and queries262736 +Ref: #interaction-of-valuation-and-queries262976 +Node: Effect of valuation on reports263453 +Ref: #effect-of-valuation-on-reports263656 +Node: PART 4 COMMANDS271351 +Ref: #part-4-commands271494 +Node: Help commands273567 +Ref: #help-commands273712 +Node: help273740 +Ref: #help273829 +Node: demo275417 +Ref: #demo275506 +Node: User interface commands276550 +Ref: #user-interface-commands276719 +Node: ui276744 +Ref: #ui276836 +Node: web276869 +Ref: #web276963 +Node: Data entry commands276997 +Ref: #data-entry-commands277166 +Node: add277195 +Ref: #add277289 +Node: import279650 +Ref: #import279750 +Node: Date skipping280911 +Ref: #date-skipping281034 +Node: Import testing283812 +Ref: #import-testing283975 +Node: Importing balance assignments284818 +Ref: #importing-balance-assignments285025 +Node: Import and commodity styles285674 +Ref: #import-and-commodity-styles285854 +Node: Basic report commands286083 +Ref: #basic-report-commands286257 +Node: accounts286384 +Ref: #accounts286494 +Node: codes289257 +Ref: #codes289381 +Node: commodities290279 +Ref: #commodities290419 +Node: descriptions290523 +Ref: #descriptions290665 +Node: files290990 +Ref: #files291112 +Node: notes291287 +Ref: #notes291403 +Node: payees291799 +Ref: #payees291918 +Node: prices292583 +Ref: #prices292702 +Node: stats293475 +Ref: #stats293590 +Node: tags295216 +Ref: #tags-1295316 +Node: Standard report commands296523 +Ref: #standard-report-commands296708 +Node: print296828 +Ref: #print296936 +Node: print explicitness299274 +Ref: #print-explicitness299415 +Node: print amount style300194 +Ref: #print-amount-style300362 +Node: print parseability301432 +Ref: #print-parseability301602 +Node: print other features302351 +Ref: #print-other-features302528 +Node: print output format303049 +Ref: #print-output-format303195 +Node: aregister306334 +Ref: #aregister306467 +Node: aregister and posting dates310114 +Ref: #aregister-and-posting-dates310259 +Node: register311015 +Ref: #register311153 +Node: Custom register output317318 +Ref: #custom-register-output317447 +Node: balancesheet318794 +Ref: #balancesheet318949 +Node: balancesheetequity323430 +Ref: #balancesheetequity323597 +Node: cashflow328436 +Ref: #cashflow328586 +Node: incomestatement332864 +Ref: #incomestatement333001 +Node: Advanced report commands337328 +Ref: #advanced-report-commands337506 +Node: balance337536 +Ref: #balance337644 +Node: balance features342425 +Ref: #balance-features342565 +Node: Simple balance report344501 +Ref: #simple-balance-report344686 +Node: Balance report line format346311 +Ref: #balance-report-line-format346513 +Node: Filtered balance report348671 +Ref: #filtered-balance-report348863 +Node: List or tree mode349190 +Ref: #list-or-tree-mode349358 +Node: Depth limiting350703 +Ref: #depth-limiting350869 +Node: Dropping top-level accounts351470 +Ref: #dropping-top-level-accounts351670 +Node: Showing declared accounts351980 +Ref: #showing-declared-accounts352179 +Node: Sorting by amount352710 +Ref: #sorting-by-amount352877 +Node: Percentages353547 +Ref: #percentages353706 +Node: Multi-period balance report354254 +Ref: #multi-period-balance-report354454 +Node: Balance change end balance357006 +Ref: #balance-change-end-balance357215 +Node: Balance report types358643 +Ref: #balance-report-types358824 +Node: Calculation type359322 +Ref: #calculation-type359477 +Node: Accumulation type360026 +Ref: #accumulation-type360206 +Node: Valuation type361127 +Ref: #valuation-type361315 +Node: Combining balance report types362316 +Ref: #combining-balance-report-types362510 +Node: Budget report364348 +Ref: #budget-report364510 +Node: Using the budget report366653 +Ref: #using-the-budget-report366826 +Node: Budget date surprises368929 +Ref: #budget-date-surprises369129 +Node: Selecting budget goals370293 +Ref: #selecting-budget-goals370496 +Node: Budgeting vs forecasting371241 +Ref: #budgeting-vs-forecasting371418 +Node: Balance report layout372918 +Ref: #balance-report-layout373103 +Node: Wide layout374056 +Ref: #wide-layout374191 +Node: Tall layout376461 +Ref: #tall-layout376616 +Node: Bare layout377767 +Ref: #bare-layout377922 +Node: Tidy layout379831 +Ref: #tidy-layout379966 +Node: Some useful balance reports381375 +Ref: #some-useful-balance-reports381550 +Node: roi382635 +Ref: #roi382735 +Node: Spaces and special characters in --inv and --pnl384882 +Ref: #spaces-and-special-characters-in---inv-and---pnl385120 +Node: Semantics of --inv and --pnl385608 +Ref: #semantics-of---inv-and---pnl385845 +Node: IRR and TWR explained387695 +Ref: #irr-and-twr-explained387853 +Node: Chart commands391106 +Ref: #chart-commands391264 +Node: activity391287 +Ref: #activity391376 +Node: Data generation commands391784 +Ref: #data-generation-commands391958 +Node: close391990 +Ref: #close392096 +Node: close --migrate394582 +Ref: #close---migrate394707 +Node: close --close396346 +Ref: #close---close396488 +Node: close --open396724 +Ref: #close---open396863 +Node: close --assert396973 +Ref: #close---assert397117 +Node: close --assign397338 +Ref: #close---assign397484 +Node: close --retain398010 +Ref: #close---retain398161 +Node: close customisation398906 +Ref: #close-customisation399083 +Node: close and balance assertions400550 +Ref: #close-and-balance-assertions400745 +Node: close examples402072 +Ref: #close-examples402211 +Node: Retain earnings402309 +Ref: #retain-earnings402466 +Node: Migrate balances to a new file402812 +Ref: #migrate-balances-to-a-new-file403036 +Node: More detailed close examples404164 +Ref: #more-detailed-close-examples404360 +Node: rewrite404386 +Ref: #rewrite404496 +Node: Re-write rules in a file406958 +Ref: #re-write-rules-in-a-file407119 +Node: Diff output format408268 +Ref: #diff-output-format408449 +Node: rewrite vs print --auto409541 +Ref: #rewrite-vs.-print---auto409699 +Node: Maintenance commands410255 +Ref: #maintenance-commands410426 +Node: check410464 +Ref: #check410563 +Node: Basic checks411546 +Ref: #basic-checks411664 +Node: Strict checks412499 +Ref: #strict-checks412640 +Node: Other checks413374 +Ref: #other-checks413514 +Node: Custom checks415229 +Ref: #custom-checks415349 +Node: diff415684 +Ref: #diff415794 +Node: test416891 +Ref: #test416987 +Node: PART 5 COMMON TASKS417763 +Ref: #part-5-common-tasks417922 +Node: Getting help417996 +Ref: #getting-help418145 +Node: Constructing command lines418905 +Ref: #constructing-command-lines419086 +Node: Starting a journal file419743 +Ref: #starting-a-journal-file419925 +Node: Setting LEDGER_FILE421127 +Ref: #setting-ledger_file421299 +Node: Setting opening balances422256 +Ref: #setting-opening-balances422437 +Node: Recording transactions425578 +Ref: #recording-transactions425747 +Node: Reconciling426303 +Ref: #reconciling426435 +Node: Reporting428692 +Ref: #reporting428821 +Node: Migrating to a new file432806 +Ref: #migrating-to-a-new-file432956 +Node: BUGS433255 +Ref: #bugs433349 +Node: Troubleshooting434228 +Ref: #troubleshooting434328  End Tag Table diff --git a/hledger/hledger.txt b/hledger/hledger.txt index 81532c061c9..48d466a04aa 100644 --- a/hledger/hledger.txt +++ b/hledger/hledger.txt @@ -19,29 +19,29 @@ DESCRIPTION and largely compatible with ledger(1), and largely interconvertible with beancount(1). - This manual is for hledger's command line interface, version 1.34.99. - It also describes the common options, file formats and concepts used by - all hledger programs. It might accidentally teach you some bookkeep- - ing/accounting as well! You don't need to know everything in here to - use hledger productively, but when you have a question about function- - ality, this doc should answer it. It is detailed, so do skip ahead or + This manual is for hledger's command line interface, version 1.40. It + also describes the common options, file formats and concepts used by + all hledger programs. It might accidentally teach you some bookkeep- + ing/accounting as well! You don't need to know everything in here to + use hledger productively, but when you have a question about function- + ality, this doc should answer it. It is detailed, so do skip ahead or skim when needed. You can read it on hledger.org, or as an info manual - or man page on your system. You can also open a built-in copy, at a + or man page on your system. You can also open a built-in copy, at a point of interest, by running hledger --man [CMD], hledger --info [CMD] or hledger help [TOPIC]. (And for shorter help, try hledger --tldr [CMD].) - The main function of the hledger CLI is to read plain text files de- + The main function of the hledger CLI is to read plain text files de- scribing financial transactions, crunch the numbers, and print a useful - report on the terminal (or save it as HTML, CSV, JSON or SQL). Many - reports are available, as subcommands. hledger will also detect other + report on the terminal (or save it as HTML, CSV, JSON or SQL). Many + reports are available, as subcommands. hledger will also detect other hledger-* executables as extra subcommands. hledger usually reads from (and appends to) a journal file specified by the LEDGER_FILE environment variable (defaulting to - $HOME/.hledger.journal); or you can specify files with -f options. It - can also read timeclock files, timedot files, or any CSV/SSV/TSV file + $HOME/.hledger.journal); or you can specify files with -f options. It + can also read timeclock files, timedot files, or any CSV/SSV/TSV file with a date field. Here is a small journal file describing one transaction: @@ -50,23 +50,23 @@ DESCRIPTION expenses:food $10 assets:cash - Transactions are dated movements of money (etc.) between two or more - accounts: bank accounts, your wallet, revenue/expense categories, peo- - ple, etc. You can choose any account names you wish, using : to indi- - cate subaccounts. There must be at least two spaces between account - name and amount. Positive amounts are inflow to that account (debit), - negatives are outflow from it (credit). (Some reports show revenue, - liability and equity account balances as negative numbers as a result; + Transactions are dated movements of money (etc.) between two or more + accounts: bank accounts, your wallet, revenue/expense categories, peo- + ple, etc. You can choose any account names you wish, using : to indi- + cate subaccounts. There must be at least two spaces between account + name and amount. Positive amounts are inflow to that account (debit), + negatives are outflow from it (credit). (Some reports show revenue, + liability and equity account balances as negative numbers as a result; this is normal.) hledger's add command can help you add transactions, or you can install other data entry UIs like hledger-web or hledger-iadd. For more exten- - sive/efficient changes, use a text editor: Emacs + ledger-mode, VIM + - vim-ledger, or VS Code + hledger-vscode are some good choices (see + sive/efficient changes, use a text editor: Emacs + ledger-mode, VIM + + vim-ledger, or VS Code + hledger-vscode are some good choices (see https://hledger.org/editors.html). - To get started, run hledger add and follow the prompts, or save some - entries like the above in $HOME/.hledger.journal, then try commands + To get started, run hledger add and follow the prompts, or save some + entries like the above in $HOME/.hledger.journal, then try commands like: $ hledger print -x @@ -75,29 +75,29 @@ DESCRIPTION $ hledger balancesheet $ hledger incomestatement - Run hledger to list the commands. See also the "Starting a journal + Run hledger to list the commands. See also the "Starting a journal file" and "Setting opening balances" sections in PART 5: COMMON TASKS. PART 1: USER INTERFACE Input - hledger reads one or more data files, each time you run it. You can + hledger reads one or more data files, each time you run it. You can specify a file with -f, like so - $ hledger -f FILE print + $ hledger -f FILE [-f FILE2 ...] print - Files are most often in hledger's journal format, with the .journal - file extension (.hledger or .j also work); these files describe trans- + Files are most often in hledger's journal format, with the .journal + file extension (.hledger or .j also work); these files describe trans- actions, like an accounting general journal. - When no file is specified, hledger looks for .hledger.journal in your + When no file is specified, hledger looks for .hledger.journal in your home directory. - But most people prefer to keep financial files in a dedicated folder, - perhaps with version control. Also, starting a new journal file each - year is common (it's not required, but helps keep things fast and or- + But most people prefer to keep financial files in a dedicated folder, + perhaps with version control. Also, starting a new journal file each + year is common (it's not required, but helps keep things fast and or- ganised). So we usually configure a different journal file, by setting - the LEDGER_FILE environment variable, to something like ~/fi- - nance/2023.journal. For more about how to do that on your system, see + the LEDGER_FILE environment variable, to something like ~/fi- + nance/2023.journal. For more about how to do that on your system, see Common tasks > Setting LEDGER_FILE. Text encoding @@ -105,45 +105,45 @@ Input optional byte order mark (BOM) is allowed, at the beginning of the file (only). - Also, your system should be configured with a locale that can decode - UTF-8 text. On some unix systems, you may need set the LANG environ- + Also, your system should be configured with a locale that can decode + UTF-8 text. On some unix systems, you may need set the LANG environ- ment variable, eg. You can read more about this in Unicode characters, below. - On unix systems you can check a file's encoding with the file command. + On unix systems you can check a file's encoding with the file command. If you need to import from a UTF-16-encoded CSV file, say, you can con- vert it to UTF-8 with the iconv command. Data formats - Usually the data file is in hledger's journal format, but it can be in + Usually the data file is in hledger's journal format, but it can be in any of the supported file formats, which currently are: - Reader: Reads: Automatically used for + Reader: Reads: Automatically used for files with extensions: ----------------------------------------------------------------------------- - journal hledger journal files and some .journal .j .hledger + journal hledger journal files and some .journal .j .hledger Ledger journals, for transactions .ledger timeclock timeclock files, for precise time .timeclock logging timedot timedot files, for approximate .timedot time logging - csv Comma or other character sepa- .csv + csv Comma or other character sepa- .csv rated values, for data import ssv Semicolon separated values .ssv tsv Tab separated values .tsv - rules CSV/SSV/TSV/other separated val- .rules + rules CSV/SSV/TSV/other separated val- .rules ues, alternate way These formats are described in more detail below. - hledger detects the format automatically based on the file extensions - shown above. If it can't recognise the file extension, it assumes - journal format. So for non-journal files, it's important to use a + hledger detects the format automatically based on the file extensions + shown above. If it can't recognise the file extension, it assumes + journal format. So for non-journal files, it's important to use a recognised file extension, so as to either read successfully or to show relevant error messages. - You can also force a specific reader/format by prefixing the file path - with the format and a colon. Eg, to read a .dat file containing tab + You can also force a specific reader/format by prefixing the file path + with the format and a colon. Eg, to read a .dat file containing tab separated values: $ hledger -f tsv:/some/file.dat stats @@ -153,29 +153,29 @@ Input $ cat FILE | hledger -f- print - If reading non-journal data in this way, you'll need to write the for- + 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 ? @@ -186,7 +186,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 @@ -194,13 +194,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 @@ -208,43 +208,43 @@ 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. Options can be writ- - ten either before or after the command name. These options are spe- + Run hledger -h to see general command line help. Options can be writ- + ten either before or after the command name. These options are spe- cific to the hledger CLI: Flags: @@ -334,14 +334,14 @@ Options --version show version information --debug=[1-9] show this much debug output (default: 1) - Usually hledger accepts any unambiguous flag prefix, eg you can write + 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 + If the same option appears more than once in a command, usually the last (right-most) wins. - With most commands, arguments are interpreted as a hledger query which - filter the data. Some queries can be expressed either with options or + With most commands, arguments are interpreted as a hledger query which + filter the data. Some queries can be expressed either with options or with arguments. Below are more tips for using the command line interface - feel free to @@ -349,10 +349,10 @@ Options Special characters Single escaping (shell metacharacters) - In shell command lines, characters significant to your shell - such as - spaces, <, >, (, ), |, $ and \ - should be "shell-escaped" if you want - hledger to see them. This is done by enclosing them in single or dou- - ble quotes, or by writing a backslash before them. Eg to match an ac- + In shell command lines, characters significant to your shell - such as + spaces, <, >, (, ), |, $ and \ - should be "shell-escaped" if you want + hledger to see them. This is done by enclosing them in single or dou- + ble quotes, or by writing a backslash before them. Eg to match an ac- count name containing a space: $ hledger register 'credit card' @@ -361,17 +361,17 @@ Options $ hledger register credit\ card - Windows users should keep in mind that cmd treats single quote as a - regular character, so you should be using double quotes exclusively. + Windows users should keep in mind that cmd treats single quote as a + regular character, so you should be using double quotes exclusively. PowerShell treats both single and double quotes as quotes. Double escaping (regular expression metacharacters) - Characters significant in regular expressions (described below) - such - as ., ^, $, [, ], (, ), |, and \ - may need to be "regex-escaped" if - you don't want them to be interpreted by hledger's regular expression - engine. This is done by writing backslashes before them, but since - backslash is typically also a shell metacharacter, both shell-escaping - and regex-escaping will be needed. Eg to match a literal $ sign while + Characters significant in regular expressions (described below) - such + as ., ^, $, [, ], (, ), |, and \ - may need to be "regex-escaped" if + you don't want them to be interpreted by hledger's regular expression + engine. This is done by writing backslashes before them, but since + backslash is typically also a shell metacharacter, both shell-escaping + and regex-escaping will be needed. Eg to match a literal $ sign while using the bash shell: $ hledger balance cur:'\$' @@ -381,10 +381,10 @@ Options $ hledger balance cur:\\$ Triple escaping (for add-on commands) - When you use hledger to run an external add-on command (described be- + When you use hledger to run an external add-on command (described be- low), one level of shell-escaping is lost from any options or arguments - intended for by the add-on command, so those need an extra level of - shell-escaping. Eg to match a literal $ sign while using the bash + intended for by the add-on command, so those need an extra level of + shell-escaping. Eg to match a literal $ sign while using the bash shell and running an add-on command (ui): $ hledger ui cur:'\\$' @@ -400,14 +400,14 @@ Options double-escaped: \\$ triple-escaped: \\\\$ - Or, you can avoid the extra escaping by running the add-on executable + Or, you can avoid the extra escaping by running the add-on executable directly: $ hledger-ui cur:\\$ Less escaping Options and arguments are sometimes used in places other than the shell - command line, where shell-escaping is not needed, so there you should + command line, where shell-escaping is not needed, so there you should use one less level of escaping. Those places include: o an @argumentfile @@ -421,8 +421,8 @@ Options Unicode characters hledger is expected to handle non-ascii characters correctly: - o they should be parsed correctly in input files and on the command - line, by all hledger tools (add, iadd, hledger-web's search/add/edit + o they should be parsed correctly in input files and on the command + line, by all hledger tools (add, iadd, hledger-web's search/add/edit forms, etc.) o they should be displayed correctly by all hledger tools, and @@ -430,40 +430,40 @@ Options This requires a well-configured environment. Here are some tips: - o A system locale must be configured, and it must be one that can de- - code the characters being used. In bash, you can set a locale like - this: export LANG=en_US.UTF-8. There are some more details in Trou- - bleshooting. This step is essential - without it, hledger will quit - on encountering a non-ascii character (as with all GHC-compiled pro- + o A system locale must be configured, and it must be one that can de- + code the characters being used. In bash, you can set a locale like + this: export LANG=en_US.UTF-8. There are some more details in Trou- + bleshooting. This step is essential - without it, hledger will quit + on encountering a non-ascii character (as with all GHC-compiled pro- grams). - o Your terminal software (eg Terminal.app, iTerm, CMD.exe, xterm..) + o Your terminal software (eg Terminal.app, iTerm, CMD.exe, xterm..) must support unicode. On Windows, you may need to use Windows Termi- nal and/or enable UTF-8 support. o The terminal must be using a font which includes the required unicode glyphs. - o The terminal should be configured to display wide characters as dou- + o The terminal should be configured to display wide characters as dou- ble width (for report alignment). - o On Windows, for best results you should run hledger in the same kind - of environment in which it was built. Eg hledger built in the stan- - dard CMD.EXE environment (like the binaries on our download page) - might show display problems when run in a cygwin or msys terminal, + o On Windows, for best results you should run hledger in the same kind + of environment in which it was built. Eg hledger built in the stan- + dard CMD.EXE environment (like the binaries on our download page) + might show display problems when run in a cygwin or msys terminal, and vice versa. (See eg #961). Regular expressions - A regular expression (regexp) is a small piece of text where certain - characters (like ., ^, $, +, *, (), |, [], \) have special meanings, - forming a tiny language for matching text precisely - very useful in - hledger and elsewhere. To learn all about them, visit regular-expres- + A regular expression (regexp) is a small piece of text where certain + characters (like ., ^, $, +, *, (), |, [], \) have special meanings, + forming a tiny language for matching text precisely - very useful in + hledger and elsewhere. To learn all about them, visit regular-expres- sions.info. - hledger supports regexps whenever you are entering a pattern to match - something, eg in query arguments, account aliases, CSV if rules, + hledger supports regexps whenever you are entering a pattern to match + something, eg in query arguments, account aliases, CSV if rules, hledger-web's search form, hledger-ui's / search, etc. You may need to - wrap them in quotes, especially at the command line (see Special char- + wrap them in quotes, especially at the command line (see Special char- acters above). Here are some examples: Account name queries (quoted for command line use): @@ -519,77 +519,80 @@ Options & %date (29|30|31|01|02|03)$ hledger's regular expressions - hledger's regular expressions come from the regex-tdfa library. If - they're not doing what you expect, it's important to know exactly what + hledger's regular expressions come from the regex-tdfa library. If + they're not doing what you expect, it's important to know exactly what they support: 1. they are case insensitive - 2. they are infix matching (they do not need to match the entire thing + 2. they are infix matching (they do not need to match the entire thing being matched) 3. they are POSIX ERE (extended regular expressions) 4. they also support GNU word boundaries (\b, \B, \<, \>) - 5. backreferences are supported when doing text replacement in account - aliases or CSV rules, where backreferences can be used in the re- + 5. backreferences are supported when doing text replacement in account + aliases or CSV rules, where backreferences can be used in the re- placement string to reference capturing groups in the search regexp. Otherwise, if you write \1, it will match the digit 1. - 6. they do not support mode modifiers ((?s)), character classes (\w, + 6. they do not support mode modifiers ((?s)), character classes (\w, \d), or anything else not mentioned above. Some things to note: - o In the alias directive and --alias option, regular expressions must - be enclosed in forward slashes (/REGEX/). Elsewhere in hledger, + o In the alias directive and --alias option, regular expressions must + be enclosed in forward slashes (/REGEX/). Elsewhere in hledger, these are not required. - o In queries, to match a regular expression metacharacter like $ as a - literal character, prepend a backslash. Eg to search for amounts + o In queries, to match a regular expression metacharacter like $ as a + literal character, prepend a backslash. Eg to search for amounts with the dollar sign in hledger-web, write cur:\$. - o On the command line, some metacharacters like $ have a special mean- + o On the command line, some metacharacters like $ have a special mean- ing to the shell and so must be escaped at least once more. See Spe- cial characters. Argument files You can save a set of command line options and arguments in a file, and - then reuse them by writing @FILENAME as a command line argument. Eg: + then reuse them by writing @FILENAME as a command line argument. Eg: hledger bal @foo.args. - (Inside the argument file, each line should contain just one option or - argument. Don't use spaces except inside quotes; write = or nothing - between a flag and its argument. For the special characters mentioned - above, use one less level of quoting than you would at the command + (Inside the argument file, each line should contain just one option or + argument. Don't use spaces except inside quotes; write = or nothing + between a flag and its argument. For the special characters mentioned + above, use one less level of quoting than you would at the command prompt.) Argument files are now superseded by.. Config files hledger will read extra command line options from a hledger.conf config - file. These will be inserted early in the command line, so your later - options can override them if needed. The config file can contain gen- - eral options (which will be used with all commands that support them), + file. These will be inserted early in the command line, so your later + options can override them if needed. The config file can contain gen- + eral options (which will be used with all commands that support them), and command-specific options (or arguments). hledger.conf.sample is an - example, which you can install as ./hledger.conf or + example, which you can install as, eg, ./hledger.conf or $HOME/.hledger.conf. - To be precise, hledger looks for hledger.conf in the current directory - or above, or in your home directory (with a dotted name, - ~/.hledger.conf), or finally in your XDG config directory (~/.con- - fig/hledger/hledger.conf). Or you can select a particular config file - by using the --conf option, or by adding a hledger --conf shebang line + To be precise, hledger looks for hledger.conf in the current directory + or above, or in your home directory (with a dotted name, + ~/.hledger.conf), or finally in your XDG config directory (~/.con- + fig/hledger/hledger.conf). Or you can select a particular config file + by using the --conf option, or by adding a hledger --conf shebang line to a config file and executing it like a script (see the example file). You can inspect the finding and processing of config files with --debug or --debug=8. - If you want to run hledger without a config file, to ensure standard - defaults and behaviour, use the -n/--no-conf flag. This is useful when - troubleshooting problems or sharing examples. + If you want to run hledger without a config file, to ensure standard + defaults and behaviour, use the -n/--no-conf flag. This is recommended + when using hledger in scripts, and when troubleshooting problems. - (Added in 1.40; experimental) + When both --conf and --no-conf options are used, the last (right-most) + wins. + + (in master, experimental) Output Output destination @@ -609,33 +612,31 @@ Output Some commands offer other kinds of output, not just text on the termi- nal. Here are those commands and the formats currently supported: - - txt csv/tsv html json sql - -------------------------------------------------------------------------------------- - aregister Y Y Y Y - balance Y 1 Y 1 Y 1,2 Y - balancesheet Y 1 Y 1 Y 1 Y - balancesheete- Y 1 Y 1 Y 1 Y + - txt csv/tsv html fods json sql + ----------------------------------------------------------------------------------------- + aregister Y Y Y Y + balance Y 1 Y 1 Y 1 Y 1 Y + balancesheet Y 1 Y 1 Y 1 Y + balancesheete- Y 1 Y 1 Y 1 Y quity - cashflow Y 1 Y 1 Y 1 Y - incomestatement Y 1 Y 1 Y 1 Y - print Y Y Y Y - register Y Y Y + cashflow Y 1 Y 1 Y 1 Y + incomestate- Y 1 Y 1 Y 1 Y + ment + print Y Y Y Y + register Y Y Y o 1 Also affected by the balance commands' --layout option. - o 2 balance does not support html output without a report interval or - with --budget. - The output format is selected by the -O/--output-format=FMT option: $ hledger print -O csv # print CSV on stdout - or by the filename extension of an output file specified with the + or by the filename extension of an output file specified with the -o/--output-file=FILE.FMT option: $ hledger balancesheet -o foo.csv # write CSV to foo.csv - The -O option can be combined with -o to override the file extension, + The -O option can be combined with -o to override the file extension, if needed: $ hledger balancesheet -o foo.txt -O csv # write CSV to foo.txt @@ -643,7 +644,7 @@ Output Some notes about the various output formats: CSV output - o In CSV output, digit group marks (such as thousands separators) are + o In CSV output, digit group marks (such as thousands separators) are disabled automatically. HTML output @@ -653,82 +654,82 @@ Output JSON output o This is not yet much used; real-world feedback is welcome. - o Our JSON is rather large and verbose, since it is a faithful repre- - sentation of hledger's internal data types. To understand the JSON, - read the Haskell type definitions, which are mostly in + o Our JSON is rather large and verbose, since it is a faithful repre- + 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. hledger-web's OpenAPI speci- + 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 (text) output, to minimise the risk of display problems, + In terminal (text) output, to minimise the risk of display problems, table borders are drawn using only ascii characters by default. - To see tables with prettier unicode box-drawing characters, add the + To see tables with prettier unicode box-drawing characters, add the --pretty flag. This will also show outer borders and inter-column bor- ders. 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, @@ -738,23 +739,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 @@ -762,42 +763,42 @@ 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 exists (with any value, including - empty), hledger will not use ANSI color codes in terminal output, un- + 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 hledger's usual data source is a plain text file containing journal en- - tries in hledger journal format. If you're looking for a quick refer- - ence, jump ahead to the journal cheatsheet (or use the table of con- + tries in hledger journal format. If you're looking for a quick refer- + ence, jump ahead to the journal cheatsheet (or use the table of con- tents at https://hledger.org/hledger.html). - This file represents an accounting General Journal. The .journal file - extension is most often used, though not strictly required. The jour- - nal file contains a number of transaction entries, each describing a - transfer of money (or any commodity) between two or more named ac- + This file represents an accounting General Journal. The .journal file + extension is most often used, though not strictly required. The jour- + nal file contains a number of transaction entries, each describing a + transfer of money (or any commodity) between two or more named ac- counts, in a simple format readable by both hledger and humans. - hledger's journal format is compatible with most of Ledger's journal + hledger's journal format is compatible with most of Ledger's journal format, but not all of it. The differences and interoperation tips are - described at hledger and Ledger. With some care, and by avoiding in- - compatible features, you can keep your hledger journal readable by - Ledger and vice versa. This can useful eg for comparing the behaviour + described at hledger and Ledger. With some care, and by avoiding in- + compatible features, you can keep your hledger journal readable by + Ledger and vice versa. This can useful eg for comparing the behaviour of one app against the other. You can use hledger without learning any more about this file; just use the add or web or import commands to create and update it. Many users, though, edit the journal file with a text editor, and track - changes with a version control system such as git. Editor addons such + changes with a version control system such as git. Editor add-ons such as ledger-mode or hledger-mode for Emacs, vim-ledger for Vim, and hledger-vscode for Visual Studio Code, make this easier, adding colour, formatting, tab completion, and useful commands. See Editor configura- @@ -4221,12 +4222,13 @@ Timeclock To generate time logs, ie to clock in and clock out, you could: - o use emacs and the built-in timeclock.el, or the extended time- - clock-x.el and perhaps the extras in ledgerutils.el + o use these shell aliases at the command line: - o at the command line, use these bash aliases: cli alias ti="echo i - `date '+%Y-%m-%d %H:%M:%S'` \$* >>$TIMELOG" alias to="echo o - `date '+%Y-%m-%d %H:%M:%S'` >>$TIMELOG" + alias ti='echo i `date "+%Y-%m-%d %H:%M:%S"` $* >>$TIMELOG' + alias to='echo o `date "+%Y-%m-%d %H:%M:%S"` >>$TIMELOG' + + o or Emacs's built-in timeclock.el, or the extended timeclock-x.el, and + perhaps the extras in ledgerutils.el o or use the old ti and to scripts in the ledger 2.x repository. These rely on a "timeclock" executable which I think is just the ledger 2 @@ -4531,44 +4533,81 @@ Time periods More complex intervals can be specified using -p/--period, described below. - Date adjustment - When there is a report interval (other than daily), report start/end - dates which have been inferred, eg from the journal, are automatically - adjusted to natural period boundaries. This is convenient for produc- - ing simple periodic reports. More precisely: + Date adjustments + Start date adjustment + If you let hledger infer a report's start date, it will adjust the date + to the previous natural boundary of the report interval, for convenient + periodic reports. (If you don't want that, specify a start date.) + + For example, if the journal's first transaction is on january 10th, + + o hledger register (no report interval) will start the report on janu- + ary 10th. + + o hledger register --monthly will start the report on the previous + month boundary, january 1st. + + o hledger register --monthly --begin 1/5 will start the report on janu- + ary 5th [1]. + + Also if you are generating transactions or budget goals with periodic + transaction rules, their start date may be adjusted in a similar way + (in certain situations). + + End date adjustment + A report's end date is always adjusted to include a whole number of in- + tervals, so that the last subperiod has the same length as the others. - o an inferred start date will be adjusted earlier if needed to fall on - a natural period boundary + For example, if the journal's last transaction is on february 20th, - o an inferred end date will be adjusted later if needed to make the - last period the same length as the others. + o hledger register will end the report on february 20th. - By contrast, start/end dates which have been specified explicitly, with - -b, -e, -p or date:, will not be adjusted (since hledger 1.29). This - makes it possible to specify non-standard report periods, but it also - means that if you are specifying a start date, you should pick one - that's on a period boundary if you want to see simple report period - headings. + o hledger register --monthly will end the report at the end of febru- + ary. + + o hledger register --monthly --end 2/14 also will end the report at the + end of february. + + o hledger register --monthly --begin 1/5 --end 2/14 will end the report + on march 4th [1]. + + [1] Since hledger 1.29. + + Period headings + With non-standard subperiods, hledger will show "STARTDATE..ENDDATE" + headings. With standard subperiods (ie, starting on a natural interval + boundary), you'll see more compact headings, which are usually prefer- + able. (Though month names will be in english, currently.) + + So if you are specifying a start date and you want compact headings: + choose a start of year for yearly reports, a start of quarter for quar- + terly reports, a start of month for monthly reports, etc. (Remember, + you can write eg -b 2024 or 1/1 as a shortcut for a start of year, or + 2024-04 or 202404 or Apr for a start of month or quarter.) + + For weekly reports, choose a date that's a Monday. (You can try dif- + ferent dates until you see the short headings, or write eg -b '3 weeks + ago'.) Period expressions - The -p/--period option specifies a period expression, which is a com- + The -p/--period option specifies a period expression, which is a com- pact way of expressing a start date, end date, and/or report interval. - Here's a period expression with a start and end date (specifying the + Here's a period expression with a start and end date (specifying the first quarter of 2009): -p "from 2009/1/1 to 2009/4/1" - Several keywords like "from" and "to" are supported for readability; - these are optional. "to" can also be written as ".." or "-". The - spaces are also optional, as long as you don't run two dates together. + Several keywords like "from" and "to" are supported for readability; + these are optional. "to" can also be written as ".." or "-". The + spaces are also optional, as long as you don't run two dates together. So the following are equivalent to the above: -p "2009/1/1 2009/4/1" -p2009/1/1to2009/4/1 -p2009/1/1..2009/4/1 - Dates are smart dates, so if the current year is 2009, these are also + Dates are smart dates, so if the current year is 2009, these are also equivalent to the above: -p "1/1 4/1" @@ -4580,28 +4619,28 @@ Time periods -p "from 2009/1/1" everything after january 1, 2009 - -p "since 2009/1" the same, since is a syn- + -p "since 2009/1" the same, since is a syn- onym -p "from 2009" the same - -p "to 2009" everything before january + -p "to 2009" everything before january 1, 2009 You can also specify a period by writing a single partial or full date: -p "2009" the year 2009; equivalent to "2009/1/1 to 2010/1/1" - -p "2009/1" the month of january 2009; equivalent to "2009/1/1 to + -p "2009/1" the month of january 2009; equivalent to "2009/1/1 to 2009/2/1" - -p "2009/1/1" the first day of 2009; equivalent to "2009/1/1 to + -p "2009/1/1" the first day of 2009; equivalent to "2009/1/1 to 2009/1/2" or by using the "Q" quarter-year syntax (case insensitive): - -p "2009Q1" first quarter of 2009, equivalent to "2009/1/1 to + -p "2009Q1" first quarter of 2009, equivalent to "2009/1/1 to 2009/4/1" -p "q4" fourth quarter of the current year Period expressions with a report interval - A period expression can also begin with a report interval, separated + A period expression can also begin with a report interval, separated from the start/end dates (if any) by a space or the word in: -p "weekly from 2009/1/1 to 2009/4/1" @@ -4624,24 +4663,24 @@ Time periods Weekly on a custom day: - o every Nth day of week (th, nd, rd, or st are all accepted after the + o every Nth day of week (th, nd, rd, or st are all accepted after the number) - o every WEEKDAYNAME (full or three-letter english weekday name, case + o every WEEKDAYNAME (full or three-letter english weekday name, case insensitive) Monthly on a custom day: - o every Nth day [of month] (31st day will be adjusted to each month's + o every Nth day [of month] (31st day will be adjusted to each month's last day) o every Nth WEEKDAYNAME [of month] - Yearly on a custom day: + Yearly on a custom month and day: o every MM/DD [of year] (month number and day of month number) - o every MONTHNAME DDth [of year] (full or three-letter english month + o every MONTHNAME DDth [of year] (full or three-letter english month name, case insensitive, and day of month number) o every DDth MONTHNAME [of year] (equivalent to the above) @@ -4654,21 +4693,21 @@ Time periods 2009/03" -p "every 2nd day of week" periods will go from Tue to Tue -p "every Tue" same - -p "every 15th day" period boundaries will be on 15th of each + -p "every 15th day" period boundaries will be on 15th of each month - -p "every 2nd Monday" period boundaries will be on second Monday + -p "every 2nd Monday" period boundaries will be on second Monday of each month - -p "every 11/05" yearly periods with boundaries on 5th of + -p "every 11/05" yearly periods with boundaries on 5th of November -p "every 5th November" same -p "every Nov 5th" same - Show historical balances at end of the 15th day of each month (N is an + Show historical balances at end of the 15th day of each month (N is an end date, exclusive as always): $ hledger balance -H -p "every 16th day" - Group postings from the start of wednesday to end of the following + Group postings from the start of wednesday to end of the following tuesday (N is both (inclusive) start date and (exclusive) end date): $ hledger register checking -p "every 3rd day of week" @@ -4679,10 +4718,10 @@ Time periods o every WEEKDAYNAME,WEEKDAYNAME,... (full or three-letter english week- day names, case insensitive) - Also, weekday and weekendday are shorthand for mon,tue,wed,thu,fri and + Also, weekday and weekendday are shorthand for mon,tue,wed,thu,fri and sat,sun. - This is mainly intended for use with --forecast, to generate periodic + This is mainly intended for use with --forecast, to generate periodic transactions on arbitrary days of the week. It may be less useful with -p, since it divides each week into subperiods of unequal length, which is unusual. (Related: #1632) @@ -4691,35 +4730,35 @@ Time periods -p "every dates will be Mon, Wed, Fri; periods will be mon,wed,fri" Mon-Tue, Wed-Thu, Fri-Sun - -p "every weekday" dates will be Mon, Tue, Wed, Thu, Fri; periods will + -p "every weekday" dates will be Mon, Tue, Wed, Thu, Fri; periods will be Mon, Tue, Wed, Thu, Fri-Sun -p "every weekend- dates will be Sat, Sun; periods will be Sat, Sun-Fri day" Depth - With the --depth NUM option (short form: -NUM), reports will show ac- - counts only to the specified depth, hiding deeper subaccounts. Use - this when you want a summary with less detail. This flag has the same + With the --depth NUM option (short form: -NUM), reports will show ac- + counts only to the specified depth, hiding deeper subaccounts. Use + this when you want a summary with less detail. This flag has the same effect as a depth: query argument: depth:2, --depth=2 or -2 are equiva- lent. Queries One of hledger's strengths is being able to quickly report on a precise - subset of your data. Most hledger commands accept query arguments, to + subset of your data. Most hledger commands accept query arguments, to restrict their scope. Multiple query terms can be provided to build up a more complex query. - o By default, a query term is interpreted as a case-insensitive sub- + o By default, a query term is interpreted as a case-insensitive sub- string pattern for matching account names: car:fuel dining groceries - o Patterns containing spaces or other special characters must be en- + o Patterns containing spaces or other special characters must be en- closed in single or double quotes: 'personal care' - o These patterns are actually regular expressions, so you can add reg- - exp metacharacters for more precision (see "Regular expressions" + o These patterns are actually regular expressions, so you can add reg- + exp metacharacters for more precision (see "Regular expressions" above for details): '^expenses\b' @@ -4740,15 +4779,15 @@ Queries not:status:'*' not:desc:'opening|closing' not:cur:USD - o Terms with different types are AND-ed, terms with the same type are - OR-ed (mostly; see "Combining query terms" below). The following + o Terms with different types are AND-ed, terms with the same type are + OR-ed (mostly; see "Combining query terms" below). The following query: date:2022 desc:amazon desc:amzn is interpreted as: - date is in 2022 AND ( transaction description contains "amazon" OR + date is in 2022 AND ( transaction description contains "amazon" OR "amzn" ) Query types @@ -4756,15 +4795,15 @@ Queries prefixed with not: to convert them into a negative match. acct:REGEX or REGEX - Match account names containing this case insensitive regular expres- + Match account names containing this case insensitive regular expres- sion. This is the default query type, so we usually don't bother writ- ing the "acct:" prefix. amt:N, amt:N, amt:>=N - Match postings with a single-commodity amount equal to, less than, or - greater than N. (Postings with multi-commodity amounts are not tested + Match postings with a single-commodity amount equal to, less than, or + greater than N. (Postings with multi-commodity amounts are not tested and will always match.) The comparison has two modes: if N is preceded - by a + or - sign (or is 0), the two signed numbers are compared. Oth- + by a + or - sign (or is 0), the two signed numbers are compared. Oth- erwise, the absolute magnitudes are compared, ignoring sign. code:REGEX @@ -4772,10 +4811,10 @@ Queries cur:REGEX Match postings or transactions including any amounts whose cur- - rency/commodity symbol is fully matched by REGEX. (For a partial - match, use .*REGEX.*). Note, to match special characters which are - regex-significant, you need to escape them with \. And for characters - which are significant to your shell you may need one more level of es- + rency/commodity symbol is fully matched by REGEX. (For a partial + match, use .*REGEX.*). Note, to match special characters which are + regex-significant, you need to escape them with \. And for characters + which are significant to your shell you may need one more level of es- caping. So eg to match the dollar sign: hledger print cur:\\$. @@ -4783,21 +4822,21 @@ Queries Match transaction descriptions. date:PERIODEXPR - Match dates (or with the --date2 flag, secondary dates) within the + Match dates (or with the --date2 flag, secondary dates) within the specified period. PERIODEXPR is a period expression with no report in- terval. Examples: date:2016, date:thismonth, date:2/1-2/15, date:2021-07-27..nextquarter. date2:PERIODEXPR - Match secondary dates within the specified period (independent of the + Match secondary dates within the specified period (independent of the --date2 flag). depth:N - Match (or display, depending on command) accounts at or above this + Match (or display, depending on command) accounts at or above this depth. expr:"TERM AND NOT (TERM OR TERM)" (eg) - Match with a boolean combination of queries (which must be enclosed in + Match with a boolean combination of queries (which must be enclosed in quotes). See Combining query terms below. note:REGEX @@ -4805,7 +4844,7 @@ Queries whole description if there's no |). payee:REGEX - Match transaction payee/payer names (the part of the description left + Match transaction payee/payer names (the part of the description left of |, or the whole description if there's no |). real:, real:0 @@ -4815,11 +4854,11 @@ Queries Match unmarked, pending, or cleared transactions respectively. type:TYPECODES - Match by account type (see Declaring accounts > Account types). TYPE- - CODES is one or more of the single-letter account type codes ALERXCV, + Match by account type (see Declaring accounts > Account types). TYPE- + CODES is one or more of the single-letter account type codes ALERXCV, case insensitive. Note type:A and type:E will also match their respec- - tive subtypes C (Cash) and V (Conversion). Certain kinds of account - alias can disrupt account types, see Rewriting accounts > Aliases and + tive subtypes C (Cash) and V (Conversion). Certain kinds of account + alias can disrupt account types, see Rewriting accounts > Aliases and account types. tag:REGEX[=REGEX] @@ -4835,11 +4874,11 @@ Queries o Transactions also acquire the tags of their postings. (inacct:ACCTNAME - A special query term used automatically in hledger-web only: tells + A special query term used automatically in hledger-web only: tells hledger-web to show the transaction register for an account.) Combining query terms - When given multiple space-separated query terms, most commands select + When given multiple space-separated query terms, most commands select things which match: o any of the description terms AND @@ -4860,8 +4899,8 @@ Queries o match all the other terms. - We also support more complex boolean queries with the expr: prefix. - This allows one to combine query terms using and, or, not keywords + We also support more complex boolean queries with the expr: prefix. + This allows one to combine query terms using and, or, not keywords (case insensitive), and to group them by enclosing in parentheses. Some examples: @@ -4874,45 +4913,45 @@ Queries expr:"desc:cool and tag:A" (expr:"desc:cool tag:A" is equivalent) - o Match things which either do not reference the 'expenses:food' ac- + o Match things which either do not reference the 'expenses:food' ac- count, or do have the 'A' tag: expr:"not expenses:food or tag:A" - o Match things which either do not reference the 'expenses:food' ac- - count, or which reference the 'expenses:drink' account and also have + o Match things which either do not reference the 'expenses:food' ac- + count, or which reference the 'expenses:drink' account and also have the 'A' tag: expr:"expenses:food or (expenses:drink and tag:A)" - expr: has a restriction: date: queries may not be used inside or ex- + expr: has a restriction: date: queries may not be used inside or ex- pressions. That would allow disjoint report periods or disjoint result sets, with unclear semantics for our reports. Queries and command options - Some queries can also be expressed as command-line options: depth:2 is + Some queries can also be expressed as command-line options: depth:2 is equivalent to --depth 2, date:2023 is equivalent to -p 2023, etc. When - you mix command options and query arguments, generally the resulting + you mix command options and query arguments, generally the resulting query is their intersection. Queries and account aliases - When account names are rewritten with --alias or alias, acct: will + When account names are rewritten with --alias or alias, acct: will match either the old or the new account name. Queries and valuation - When amounts are converted to other commodities in cost or value re- - ports, cur: and amt: match the old commodity symbol and the old amount + When amounts are converted to other commodities in cost or value re- + ports, cur: and amt: match the old commodity symbol and the old amount quantity, not the new ones. (Except in hledger 1.22, #1625.) Pivoting - Normally, hledger groups and sums amounts within each account. The - --pivot FIELD option substitutes some other transaction field for ac- - count names, causing amounts to be grouped and summed by that field's - value instead. FIELD can be any of the transaction fields acct, sta- - tus, code, desc, payee, note, or a tag name. When pivoting on a tag - and a posting has multiple values of that tag, only the first value is - displayed. Values containing colon:separated:parts will be displayed - hierarchically, like account names. Multiple, colon-delimited fields + Normally, hledger groups and sums amounts within each account. The + --pivot FIELD option substitutes some other transaction field for ac- + count names, causing amounts to be grouped and summed by that field's + value instead. FIELD can be any of the transaction fields acct, sta- + tus, code, desc, payee, note, or a tag name. When pivoting on a tag + and a posting has multiple values of that tag, only the first value is + displayed. Values containing colon:separated:parts will be displayed + hierarchically, like account names. Multiple, colon-delimited fields can be pivoted simultaneously, generating a hierarchical account name. Some examples: @@ -4944,7 +4983,7 @@ Pivoting -------------------- -2 EUR - Another way (the acct: query matches against the pivoted "account + Another way (the acct: query matches against the pivoted "account name"): $ hledger balance --pivot member acct:. @@ -4960,78 +4999,78 @@ Pivoting -2 EUR Generating data - hledger can enrich the data provided to it, or generate new data, in a + hledger can enrich the data provided to it, or generate new data, in a number of ways. Mostly, this is done only if you request it: - o Missing amounts or missing costs in transactions are inferred auto- + o Missing amounts or missing costs in transactions are inferred auto- matically when possible. - o The --infer-equity flag infers missing conversion equity postings + o The --infer-equity flag infers missing conversion equity postings from @/@@ costs. - o The --infer-costs flag infers missing costs from conversion equity + o The --infer-costs flag infers missing costs from conversion equity postings. o The --infer-market-prices flag infers P price directives from costs. - o The --auto flag adds extra postings to transactions matched by auto + o The --auto flag adds extra postings to transactions matched by auto posting rules. - o The --forecast option generates transactions from periodic transac- + o The --forecast option generates transactions from periodic transac- tion rules. - o The balance --budget report infers budget goals from periodic trans- + o The balance --budget report infers budget goals from periodic trans- action rules. - o Commands like close, rewrite, and hledger-interest generate transac- + o Commands like close, rewrite, and hledger-interest generate transac- tions or postings. - o CSV data is converted to transactions by applying CSV conversion + o CSV data is converted to transactions by applying CSV conversion rules.. etc. - Such generated data is temporary, existing only at report time. You - can convert it to permanent recorded data by, eg, capturing the output - of hledger print and saving it in your journal file. This can some- + Such generated data is temporary, existing only at report time. You + can convert it to permanent recorded data by, eg, capturing the output + of hledger print and saving it in your journal file. This can some- times be useful as a data entry aid. - If you are curious what data is being generated and why, run hledger - print -x --verbose-tags. -x/--explicit shows inferred amounts and - --verbose-tags adds tags like generated-transaction (from periodic + If you are curious what data is being generated and why, run hledger + print -x --verbose-tags. -x/--explicit shows inferred amounts and + --verbose-tags adds tags like generated-transaction (from periodic rules) and generated-posting, modified (from auto posting rules). Sim- - ilar hidden tags (with an underscore prefix) are always present, also, - so you can always match such data with queries like tag:generated or + ilar hidden tags (with an underscore prefix) are always present, also, + so you can always match such data with queries like tag:generated or tag:modified. Forecasting - Forecasting, or speculative future reporting, can be useful for esti- + Forecasting, or speculative future reporting, can be useful for esti- mating future balances, or for exploring different future scenarios. The simplest and most flexible way to do it with hledger is to manually record a bunch of future-dated transactions. You could keep these in a - separate future.journal and include that with -f only when you want to + separate future.journal and include that with -f only when you want to see them. --forecast - There is another way: with the --forecast option, hledger can generate - temporary "forecast transactions" for reporting purposes, according to - periodic transaction rules defined in the journal. Each rule can gen- - erate multiple recurring transactions, so by changing one rule you can + There is another way: with the --forecast option, hledger can generate + temporary "forecast transactions" for reporting purposes, according to + periodic transaction rules defined in the journal. Each rule can gen- + erate multiple recurring transactions, so by changing one rule you can change many forecasted transactions. - Forecast transactions usually start after ordinary transactions end. + Forecast transactions usually start after ordinary transactions end. By default, they begin after your latest-dated ordinary transaction, or - today, whichever is later, and they end six months from today. (The + today, whichever is later, and they end six months from today. (The exact rules are a little more complicated, and are given below.) This is the "forecast period", which need not be the same as the report - period. You can override it - eg to forecast farther into the future, + period. You can override it - eg to forecast farther into the future, or to force forecast transactions to overlap your ordinary transactions - - by giving the --forecast option a period expression argument, like - --forecast=..2099 or --forecast=2023-02-15... Note that the = is re- + - by giving the --forecast option a period expression argument, like + --forecast=..2099 or --forecast=2023-02-15... Note that the = is re- quired. Inspecting forecast transactions - print is the best command for inspecting and troubleshooting forecast + print is the best command for inspecting and troubleshooting forecast transactions. Eg: ~ monthly from 2022-12-20 rent @@ -5065,7 +5104,7 @@ Forecasting expenses:rent $1000 Here there are no ordinary transactions, so the forecasted transactions - begin on the first occurence after today's date. (You won't normally + begin on the first occurrence after today's date. (You won't normally use --today; it's just to make these examples reproducible.) Forecast reports @@ -5089,19 +5128,19 @@ Forecasting || $1000 $1000 $1000 $1000 $1000 Forecast tags - Forecast transactions generated by --forecast have a hidden tag, _gen- - erated-transaction. So if you ever need to match forecast transac- + Forecast transactions generated by --forecast have a hidden tag, _gen- + erated-transaction. So if you ever need to match forecast transac- tions, you could use tag:_generated-transaction (or just tag:generated) in a query. - For troubleshooting, you can add the --verbose-tags flag. Then, visi- + For troubleshooting, you can add the --verbose-tags flag. Then, visi- ble generated-transaction tags will be added also, so you can view them - with the print command. Their value indicates which periodic rule was + with the print command. Their value indicates which periodic rule was responsible. Forecast period, in detail Forecast start/end dates are chosen so as to do something useful by de- - fault in almost all situations, while also being flexible. Here are + fault in almost all situations, while also being flexible. Here are (with luck) the exact rules, to help with troubleshooting: The forecast period starts on: @@ -5133,7 +5172,7 @@ Forecasting o otherwise: 180 days (~6 months) from today. Forecast troubleshooting - When --forecast is not doing what you expect, one of these tips should + When --forecast is not doing what you expect, one of these tips should help: o Remember to use the --forecast option. @@ -5143,22 +5182,22 @@ Forecasting o Test with print --forecast. - o Check for typos or too-restrictive start/end dates in your periodic + o Check for typos or too-restrictive start/end dates in your periodic transaction rule. - o Leave at least 2 spaces between the rule's period expression and de- + o Leave at least 2 spaces between the rule's period expression and de- scription fields. - o Check for future-dated ordinary transactions suppressing forecasted + o Check for future-dated ordinary transactions suppressing forecasted transactions. o Try setting explicit report start and/or end dates with -b, -e, -p or date: - o Try adding the -E flag to encourage display of empty periods/zero + o Try adding the -E flag to encourage display of empty periods/zero transactions. - o Try setting explicit forecast start and/or end dates with --fore- + o Try setting explicit forecast start and/or end dates with --fore- cast=START..END o Consult Forecast period, in detail, above. @@ -5166,13 +5205,13 @@ Forecasting o Check inside the engine: add --debug=2 (eg). Budgeting - With the balance command's --budget report, each periodic transaction - rule generates recurring budget goals in specified accounts, and goals - and actual performance can be compared. See the balance command's doc + With the balance command's --budget report, each periodic transaction + rule generates recurring budget goals in specified accounts, and goals + and actual performance can be compared. See the balance command's doc below. - You can generate budget goals and forecast transactions at the same - time, from the same or different periodic transaction rules: hledger + You can generate budget goals and forecast transactions at the same + time, from the same or different periodic transaction rules: hledger bal -M --budget --forecast ... See also: Budgeting and Forecasting. @@ -5180,17 +5219,17 @@ Budgeting Amount formatting Commodity display style For the amounts in each commodity, hledger chooses a consistent display - style (symbol placement, decimal mark and digit group marks, number of + style (symbol placement, decimal mark and digit group marks, number of decimal digits) to use in most reports. This is inferred as follows: - First, if there's a D directive declaring a default commodity, that - commodity symbol and amount format is applied to all no-symbol amounts + First, if there's a D directive declaring a default commodity, that + commodity symbol and amount format is applied to all no-symbol amounts in the journal. - Then each commodity's display style is determined from its commodity - directive. We recommend always declaring commodities with commodity + Then each commodity's display style is determined from its commodity + directive. We recommend always declaring commodities with commodity directives, since they help ensure consistent display styles and preci- - sions, and bring other benefits such as error checking for commodity + sions, and bring other benefits such as error checking for commodity symbols. Here's an example: # Set display styles (and decimal marks, for parsing, if there is no decimal-mark directive) @@ -5200,9 +5239,9 @@ Amount formatting commodity INR 9,99,99,999.00 commodity 1 000 000.9455 - But for convenience, if a commodity directive is not present, hledger - infers a commodity's display styles from its amounts as they are writ- - ten in the journal (excluding cost amounts and amounts in periodic + But for convenience, if a commodity directive is not present, hledger + infers a commodity's display styles from its amounts as they are writ- + ten in the journal (excluding cost amounts and amounts in periodic transaction rules or auto posting rules). It uses o the symbol placement and decimal mark of the first amount seen @@ -5211,7 +5250,7 @@ Amount formatting o and the maximum number of decimal digits seen across all amounts. - And as fallback if no applicable amounts are found, it would use a de- + And as fallback if no applicable amounts are found, it would use a de- fault style, like $1000.00 (symbol on the left with no space, period as decimal mark, and two decimal digits). @@ -5220,16 +5259,16 @@ Amount formatting Rounding Amounts are stored internally as decimal numbers with up to 255 decimal - places. They are displayed with their original journal precisions by - print and print-like reports, and rounded to their display precision + places. They are displayed with their original journal precisions by + print and print-like reports, and rounded to their display precision (the number of decimal digits specified by the commodity display style) - by other reports. When rounding, hledger uses banker's rounding (it + by other reports. When rounding, hledger uses banker's rounding (it rounds to the nearest even digit). So eg 0.5 displayed with zero deci- mal digits appears as "0". Trailing decimal marks If you're wondering why your print report sometimes shows trailing dec- - imal marks, with no decimal digits; it does this when showing amounts + imal marks, with no decimal digits; it does this when showing amounts that have digit group marks but no decimal digits, to disambiguate them and allow them to be re-parsed reliably (see Decimal marks). Eg: @@ -5243,7 +5282,7 @@ Amount formatting (a) $1,000. If this is a problem (eg when exporting to Ledger), you can avoid it by - disabling digit group marks, eg with -c/--commodity (for each affected + disabling digit group marks, eg with -c/--commodity (for each affected commodity): $ hledger print -c '$1000.00' @@ -5260,19 +5299,19 @@ Amount formatting More generally, hledger output falls into three rough categories, which format amounts a little bit differently to suit different consumers: - 1. "hledger-readable output" - should be readable by hledger (and by + 1. "hledger-readable output" - should be readable by hledger (and by humans) - o This is produced by reports that show full journal entries: print, + o This is produced by reports that show full journal entries: print, import, close, rewrite etc. - o It shows amounts with their original journal precisions, which may + o It shows amounts with their original journal precisions, which may not be consistent. - o It adds a trailing decimal mark when needed to avoid showing ambigu- + o It adds a trailing decimal mark when needed to avoid showing ambigu- ous amounts. - o It can be parsed reliably (by hledger and ledger2beancount at least, + o It can be parsed reliably (by hledger and ledger2beancount at least, but perhaps not by Ledger..) 2. "human-readable output" - usually for humans @@ -5284,13 +5323,13 @@ Amount formatting o It shows ambiguous amounts unmodified. - o It can be parsed reliably in the context of a known report (when you + o It can be parsed reliably in the context of a known report (when you know decimals are consistently not being shown, you can assume a sin- gle mark is a digit group mark). 3. "machine-readable output" - usually for other software - o This is produced by all reports when an output format like csv, tsv, + o This is produced by all reports when an output format like csv, tsv, json, or sql is selected. o It shows amounts as 1 or 2 do, but without digit group marks. @@ -5300,17 +5339,17 @@ Amount formatting Cost reporting In some transactions - for example a currency conversion, or a purchase - or sale of stock - one commodity is exchanged for another. In these - transactions there is a conversion rate, also called the cost (when - buying) or selling price (when selling). In hledger docs we just say + or sale of stock - one commodity is exchanged for another. In these + transactions there is a conversion rate, also called the cost (when + buying) or selling price (when selling). In hledger docs we just say "cost", for convenience; feel free to mentally translate to "conversion rate" or "selling price" if helpful. Recording costs - We'll explore several ways of recording transactions involving costs. + We'll explore several ways of recording transactions involving costs. These are also summarised at hledger Cookbook > Cost notation. - Costs can be recorded explicitly in the journal, using the @ UNITCOST + Costs can be recorded explicitly in the journal, using the @ UNITCOST or @@ TOTALCOST notation described in Journal > Costs: Variant 1 @@ -5325,11 +5364,11 @@ Cost reporting assets:dollars $-135 assets:euros 100 @@ $135 ; $135 total cost - Typically, writing the unit cost (variant 1) is preferable; it can be + Typically, writing the unit cost (variant 1) is preferable; it can be more effort, requiring more attention to decimal digits; but it reveals the per-unit cost basis, and makes stock sales easier. - Costs can also be left implicit, and hledger will infer the cost that + Costs can also be left implicit, and hledger will infer the cost that is consistent with a balanced transaction: Variant 3 @@ -5338,49 +5377,49 @@ Cost reporting assets:dollars $-135 assets:euros 100 - Here, hledger will attach a @@ 100 cost to the first amount (you can - see it with hledger print -x). This form looks convenient, but there + Here, hledger will attach a @@ 100 cost to the first amount (you can + see it with hledger print -x). This form looks convenient, but there are downsides: - o It sacrifices some error checking. For example, if you accidentally + o It sacrifices some error checking. For example, if you accidentally wrote 10 instead of 100, hledger would not be able to detect the mis- take. - o It is sensitive to the order of postings - if they were reversed, a + o It is sensitive to the order of postings - if they were reversed, a different entry would be inferred and reports would be different. o The per-unit cost basis is not easy to read. - So generally this kind of entry is not recommended. You can make sure + So generally this kind of entry is not recommended. You can make sure you have none of these by using -s (strict mode), or by running hledger check balanced. Reporting at cost - Now when you add the -B/--cost flag to reports ("B" is from Ledger's - -B/--basis/--cost flag), any amounts which have been annotated with - costs will be converted to their cost's commodity (in the report out- + Now when you add the -B/--cost flag to reports ("B" is from Ledger's + -B/--basis/--cost flag), any amounts which have been annotated with + costs will be converted to their cost's commodity (in the report out- put). Ie they will be displayed "at cost" or "at sale price". Some things to note: - o Costs are attached to specific posting amounts in specific transac- - tions, and once recorded they do not change. This contrasts with + o Costs are attached to specific posting amounts in specific transac- + tions, and once recorded they do not change. This contrasts with market prices, which are ambient and fluctuating. - o Conversion to cost is performed before conversion to market value + o Conversion to cost is performed before conversion to market value (described below). Equity conversion postings - There is a problem with the entries above - they are not conventional - Double Entry Bookkeeping (DEB) notation, and because of the "magical" - transformation of one commodity into another, they cause an imbalance + There is a problem with the entries above - they are not conventional + Double Entry Bookkeeping (DEB) notation, and because of the "magical" + transformation of one commodity into another, they cause an imbalance in the Accounting Equation. This shows up as a non-zero grand total in balance reports like hledger bse. - For most hledger users, this doesn't matter in practice and can safely + For most hledger users, this doesn't matter in practice and can safely be ignored ! But if you'd like to learn more, keep reading. - Conventional DEB uses an extra pair of equity postings to balance the + Conventional DEB uses an extra pair of equity postings to balance the transaction. Of course you can do this in hledger as well: Variant 4 @@ -5391,10 +5430,10 @@ Cost reporting equity:conversion $135 equity:conversion -100 - Now the transaction is perfectly balanced according to standard DEB, + Now the transaction is perfectly balanced according to standard DEB, and hledger bse's total will not be disrupted. - And, hledger can still infer the cost for cost reporting, but it's not + And, hledger can still infer the cost for cost reporting, but it's not done by default - you must add the --infer-costs flag like so: $ hledger print --infer-costs @@ -5416,14 +5455,14 @@ Cost reporting o Instead of -B you must remember to type -B --infer-costs. - o --infer-costs works only where hledger can identify the two eq- - uity:conversion postings and match them up with the two non-equity - postings. So writing the journal entry in a particular format be- + o --infer-costs works only where hledger can identify the two eq- + uity:conversion postings and match them up with the two non-equity + postings. So writing the journal entry in a particular format be- comes more important. More on this below. Inferring equity conversion postings Can we go in the other direction ? Yes, if you have transactions writ- - ten with the @/@@ cost notation, hledger can infer the missing equity + ten with the @/@@ cost notation, hledger can infer the missing equity postings, if you add the --infer-equity flag. Eg: 2022-01-01 @@ -5437,15 +5476,15 @@ Cost reporting equity:conversion:$-: -100 equity:conversion:$-:$ $135.00 - The equity account names will be "equity:conversion:A-B:A" and "eq- - uity:conversion:A-B:B" where A is the alphabetically first commodity + The equity account names will be "equity:conversion:A-B:A" and "eq- + uity:conversion:A-B:B" where A is the alphabetically first commodity symbol. You can customise the "equity:conversion" part by declaring an account with the V/Conversion account type. Combining costs and equity conversion postings Finally, you can use both the @/@@ cost notation and equity postings at - the same time. This in theory gives the best of all worlds - preserv- - ing the accounting equation, revealing the per-unit cost basis, and + the same time. This in theory gives the best of all worlds - preserv- + ing the accounting equation, revealing the per-unit cost basis, and providing more flexibility in how you write the entry: Variant 5 @@ -5456,15 +5495,15 @@ Cost reporting equity:conversion -100 assets:euros 100 @ $1.35 - All the other variants above can (usually) be rewritten to this final + All the other variants above can (usually) be rewritten to this final form with: $ hledger print -x --infer-costs --infer-equity Downsides: - o The precise format of the journal entry becomes more important. If - hledger can't detect and match up the cost and equity postings, it + o The precise format of the journal entry becomes more important. If + hledger can't detect and match up the cost and equity postings, it will give a transaction balancing error. o The add command does not yet accept this kind of entry (#2056). @@ -5472,34 +5511,34 @@ Cost reporting o This is the most verbose form. Requirements for detecting equity conversion postings - --infer-costs has certain requirements (unlike --infer-equity, which + --infer-costs has certain requirements (unlike --infer-equity, which always works). It will infer costs only in transactions with: - o Two non-equity postings, in different commodities. Their order is + o Two non-equity postings, in different commodities. Their order is significant: the cost will be added to the first of them. - o Two postings to equity conversion accounts, next to one another, + o Two postings to equity conversion accounts, next to one another, which balance the two non-equity postings. This balancing is checked - to the same precision (number of decimal places) used in the conver- + to the same precision (number of decimal places) used in the conver- sion posting's amount. Equity conversion accounts are: o any accounts declared with account type V/Conversion, or their sub- accounts - o otherwise, accounts named equity:conversion, equity:trade, or eq- + o otherwise, accounts named equity:conversion, equity:trade, or eq- uity:trading, or their subaccounts. - And multiple such four-posting groups can coexist within a single - transaction. When --infer-costs fails, it does not infer a cost in - that transaction, and does not raise an error (ie, it infers costs + And multiple such four-posting groups can coexist within a single + transaction. When --infer-costs fails, it does not infer a cost in + that transaction, and does not raise an error (ie, it infers costs where it can). - Reading variant 5 journal entries, combining cost notation and equity - postings, has all the same requirements. When reading such an entry + Reading variant 5 journal entries, combining cost notation and equity + postings, has all the same requirements. When reading such an entry fails, hledger raises an "unbalanced transaction" error. Infer cost and equity by default ? - Should --infer-costs and --infer-equity be enabled by default ? Try + Should --infer-costs and --infer-equity be enabled by default ? Try using them always, eg with a shell alias: alias h="hledger --infer-equity --infer-costs" @@ -5507,101 +5546,101 @@ Cost reporting and let us know what problems you find. Value reporting - Instead of reporting amounts in their original commodity, hledger can + Instead of reporting amounts in their original commodity, hledger can convert them to cost/sale amount (using the conversion rate recorded in - the transaction), and/or to market value (using some market price on a - certain date). This is controlled by the --value=TYPE[,COMMODITY] op- - tion, which will be described below. We also provide the simpler -V + the transaction), and/or to market value (using some market price on a + certain date). This is controlled by the --value=TYPE[,COMMODITY] op- + tion, which will be described below. We also provide the simpler -V and -X COMMODITY options, and often one of these is all you need: -V: Value - The -V/--market flag converts amounts to market value in their default + The -V/--market flag converts amounts to market value in their default valuation commodity, using the market prices in effect on the valuation date(s), if any. More on these in a minute. -X: Value in specified commodity The -X/--exchange=COMM option is like -V, except you tell it which cur- - rency you want to convert to, and it tries to convert everything to + rency you want to convert to, and it tries to convert everything to that. Valuation date - Market prices can change from day to day. hledger will use the prices - on a particular valuation date (or on more than one date). By default + Market prices can change from day to day. hledger will use the prices + on a particular valuation date (or on more than one date). By default hledger uses "end" dates for valuation. More specifically: - o For single period reports (including normal print and register re- + o For single period reports (including normal print and register re- ports): o If an explicit report end date is specified, that is used - o Otherwise the latest transaction date or P directive date is used + o Otherwise the latest transaction date or P directive date is used (even if it's in the future) o For multiperiod reports, each period is valued on its last day. - This can be customised with the --value option described below, which + This can be customised with the --value option described below, which can select either "then", "end", "now", or "custom" dates. (Note, this has a bug in hledger-ui <=1.31: turning on valuation with the V key al- ways resets it to "end".) Finding market price - To convert a commodity A to its market value in another commodity B, - hledger looks for a suitable market price (exchange rate) as follows, + To convert a commodity A to its market value in another commodity B, + hledger looks for a suitable market price (exchange rate) as follows, in this order of preference: - 1. A declared market price or inferred market price: A's latest market + 1. A declared market price or inferred market price: A's latest market price in B on or before the valuation date as declared by a P direc- tive, or (with the --infer-market-prices flag) inferred from costs. 2. A reverse market price: the inverse of a declared or inferred market price from B to A. - 3. A forward chain of market prices: a synthetic price formed by com- + 3. A forward chain of market prices: a synthetic price formed by com- bining the shortest chain of "forward" (only 1 above) market prices, leading from A to B. - 4. Any chain of market prices: a chain of any market prices, including - both forward and reverse prices (1 and 2 above), leading from A to + 4. Any chain of market prices: a chain of any market prices, including + both forward and reverse prices (1 and 2 above), leading from A to B. - There is a limit to the length of these price chains; if hledger - reaches that length without finding a complete chain or exhausting all - possibilities, it will give up (with a "gave up" message visible in + There is a limit to the length of these price chains; if hledger + reaches that length without finding a complete chain or exhausting all + possibilities, it will give up (with a "gave up" message visible in --debug=2 output). That limit is currently 1000. - Amounts for which no suitable market price can be found, are not con- + Amounts for which no suitable market price can be found, are not con- verted. --infer-market-prices: market prices from transactions Normally, market value in hledger is fully controlled by, and requires, P directives in your journal. Since adding and updating those can be a - chore, and since transactions usually take place at close to market - value, why not use the recorded costs as additional market prices (as - Ledger does) ? Adding the --infer-market-prices flag to -V, -X or + chore, and since transactions usually take place at close to market + value, why not use the recorded costs as additional market prices (as + Ledger does) ? Adding the --infer-market-prices flag to -V, -X or --value enables this. - So for example, hledger bs -V --infer-market-prices will get market - prices both from P directives and from transactions. If both occur on + So for example, hledger bs -V --infer-market-prices will get market + prices both from P directives and from transactions. If both occur on the same day, the P directive takes precedence. There is a downside: value reports can sometimes be affected in confus- - ing/undesired ways by your journal entries. If this happens to you, - read all of this Value reporting section carefully, and try adding + ing/undesired ways by your journal entries. If this happens to you, + read all of this Value reporting section carefully, and try adding --debug or --debug=2 to troubleshoot. --infer-market-prices can infer market prices from: o multicommodity transactions with explicit prices (@/@@) - o multicommodity transactions with implicit prices (no @, two commodi- - ties, unbalanced). (With these, the order of postings matters. + o multicommodity transactions with implicit prices (no @, two commodi- + ties, unbalanced). (With these, the order of postings matters. hledger print -x can be useful for troubleshooting.) o multicommodity transactions with equity postings, if cost is inferred with --infer-costs. - There is a limitation (bug) currently: when a valuation commodity is - not specified, prices inferred with --infer-market-prices do not help + There is a limitation (bug) currently: when a valuation commodity is + not specified, prices inferred with --infer-market-prices do not help select a default valuation commodity, as P prices would. So conversion might not happen because no valuation commodity was detected (--debug=2 will show this). To be safe, specify the valuation commmodity, eg: @@ -5611,8 +5650,8 @@ Value reporting o --value=then,EUR --infer-market-prices, not --value=then --infer-mar- ket-prices - Signed costs and market prices can be confusing. For reference, here - is the current behaviour, since hledger 1.25. (If you think it should + Signed costs and market prices can be confusing. For reference, here + is the current behaviour, since hledger 1.25. (If you think it should work differently, see #1870.) 2022-01-01 Positive Unit prices @@ -5642,7 +5681,7 @@ Value reporting b B -1 @@ A -1 All of the transactions above are considered balanced (and on each day, - the two transactions are considered equivalent). Here are the market + the two transactions are considered equivalent). Here are the market prices inferred for B: $ hledger -f- --infer-market-prices prices @@ -5655,34 +5694,34 @@ Value reporting Valuation commodity When you specify a valuation commodity (-X COMM or --value TYPE,COMM): - hledger will convert all amounts to COMM, wherever it can find a suit- + hledger will convert all amounts to COMM, wherever it can find a suit- able market price (including by reversing or chaining prices). - When you leave the valuation commodity unspecified (-V or --value + When you leave the valuation commodity unspecified (-V or --value TYPE): - For each commodity A, hledger picks a default valuation commodity as + For each commodity A, hledger picks a default valuation commodity as follows, in this order of preference: 1. The price commodity from the latest P-declared market price for A on or before valuation date. 2. The price commodity from the latest P-declared market price for A on - any date. (Allows conversion to proceed when there are inferred + any date. (Allows conversion to proceed when there are inferred prices before the valuation date.) - 3. If there are no P directives at all (any commodity or date) and the - --infer-market-prices flag is used: the price commodity from the + 3. If there are no P directives at all (any commodity or date) and the + --infer-market-prices flag is used: the price commodity from the latest transaction-inferred price for A on or before valuation date. This means: - o If you have P directives, they determine which commodities -V will + o If you have P directives, they determine which commodities -V will convert, and to what. - o If you have no P directives, and use the --infer-market-prices flag, + o If you have no P directives, and use the --infer-market-prices flag, costs determine it. - Amounts for which no valuation commodity can be found are not con- + Amounts for which no valuation commodity can be found are not con- verted. --value: Flexible valuation @@ -5699,26 +5738,26 @@ Value reporting The TYPE part selects cost or value and valuation date: --value=then - Convert amounts to their value in the default valuation commod- + Convert amounts to their value in the default valuation commod- ity, using market prices on each posting's date. --value=end - Convert amounts to their value in the default valuation commod- - ity, using market prices on the last day of the report period - (or if unspecified, the journal's end date); or in multiperiod + Convert amounts to their value in the default valuation commod- + ity, using market prices on the last day of the report period + (or if unspecified, the journal's end date); or in multiperiod reports, market prices on the last day of each subperiod. --value=now - Convert amounts to their value in the default valuation commod- - ity using current market prices (as of when report is gener- + Convert amounts to their value in the default valuation commod- + ity using current market prices (as of when report is gener- ated). --value=YYYY-MM-DD - Convert amounts to their value in the default valuation commod- + Convert amounts to their value in the default valuation commod- ity using market prices on this date. To select a different valuation commodity, add the optional ,COMM part: - a comma, then the target commodity's symbol. Eg: --value=now,EUR. + a comma, then the target commodity's symbol. Eg: --value=now,EUR. hledger will do its best to convert amounts to this commodity, deducing market prices as described above. @@ -5746,13 +5785,13 @@ Value reporting $ hledger -f t.j bal -N euros -V -e 2016/11/4 $110.00 assets:euros - What are they worth after 2016/12/21 ? (no report end date specified, + What are they worth after 2016/12/21 ? (no report end date specified, defaults to today) $ hledger -f t.j bal -N euros -V $103.00 assets:euros - Here are some examples showing the effect of --value, as seen with + Here are some examples showing the effect of --value, as seen with print: P 2000-01-01 A 1 B @@ -5790,7 +5829,7 @@ Value reporting 2000-02-01 (a) 2 B - With no report period specified, that shows the value as of the last + With no report period specified, that shows the value as of the last day of the journal (2000-03-01): $ hledger -f- print --value=end @@ -5828,7 +5867,7 @@ Value reporting (a) 1 B Interaction of valuation and queries - When matching postings based on queries in the presence of valuation, + When matching postings based on queries in the presence of valuation, the following happens: 1. The query is separated into two parts: @@ -5842,45 +5881,45 @@ Value reporting 3. Valuation is applied to the postings. - 4. The postings are matched to the other parts of the query based on + 4. The postings are matched to the other parts of the query based on post-valued amounts. Related: #1625 Effect of valuation on reports - Here is a reference for how valuation is supposed to affect each part - of hledger's reports. (It's wide, you may need to scroll sideways.) - It may be useful when troubleshooting. If you find problems, please - report them, ideally with a reproducible example. Related: #329, + Here is a reference for how valuation is supposed to affect each part + of hledger's reports. (It's wide, you may need to scroll sideways.) + It may be useful when troubleshooting. If you find problems, please + report them, ideally with a reproducible example. Related: #329, #1083. First, a quick glossary: cost calculated using price(s) recorded in the transaction(s). - value market value using available market price declarations, or the + value market value using available market price declarations, or the unchanged amount if no conversion rate can be found. report start - the first day of the report period specified with -b or -p or + the first day of the report period specified with -b or -p or date:, otherwise today. report or journal start - the first day of the report period specified with -b or -p or - date:, otherwise the earliest transaction date in the journal, + the first day of the report period specified with -b or -p or + date:, otherwise the earliest transaction date in the journal, otherwise today. report end - the last day of the report period specified with -e or -p or + the last day of the report period specified with -e or -p or date:, otherwise today. report or journal end - the last day of the report period specified with -e or -p or - date:, otherwise the latest transaction date in the journal, + the last day of the report period specified with -e or -p or + date:, otherwise the latest transaction date in the journal, otherwise today. report interval - a flag (-D/-W/-M/-Q/-Y) or period expression that activates the + a flag (-D/-W/-M/-Q/-Y) or period expression that activates the report's multi-period mode (whether showing one or many subperi- ods). @@ -5888,8 +5927,8 @@ Value reporting type --value=now -------------------------------------------------------------------------------------------- print - posting cost value at re- value at posting value at re- value at - amounts port end or date port or DATE/today + posting cost value at re- value at posting value at re- value at + amounts port end or date port or DATE/today today journal end balance unchanged unchanged unchanged unchanged unchanged asser- @@ -5905,7 +5944,7 @@ Value reporting (-H) with port or posting was made port or report journal journal interval start start - posting cost value at re- value at posting value at re- value at + posting cost value at re- value at posting value at re- value at amounts port or date port or DATE/today journal end journal end summary summarised value at pe- sum of postings value at pe- value at @@ -5921,8 +5960,8 @@ Value reporting balance (bs, bse, cf, is) - balance sums of value at re- value at posting value at re- value at - changes costs port end or date port or DATE/today of + balance sums of value at re- value at posting value at re- value at + changes costs port end or date port or DATE/today of today of journal end sums of post- sums of of sums of ings postings postings @@ -5930,7 +5969,7 @@ Value reporting amounts changes changes changes ances changes (--bud- get) - grand to- sum of dis- sum of dis- sum of displayed sum of dis- sum of dis- + grand to- sum of dis- sum of dis- sum of displayed sum of dis- sum of dis- tal played val- played val- valued played val- played values ues ues ues @@ -5956,7 +5995,7 @@ Value reporting end bal- sums of same as sums of values of period end value at ances costs of --value=end postings from be- balances, DATE/today of (bal -H, postings fore period start valued at sums of post- - is --H, from before to period end at period ends ings + is --H, from before to period end at period ends ings bs, cf) report start respective post- to period ing dates end @@ -5965,10 +6004,10 @@ Value reporting (--bud- balances balances ances balances get) row to- sums, aver- sums, aver- sums, averages of sums, aver- sums, aver- - tals, row ages of dis- ages of dis- displayed values ages of dis- ages of dis- + tals, row ages of dis- ages of dis- displayed values ages of dis- ages of dis- averages played val- played val- played val- played values (-T, -A) ues ues ues - column sums of dis- sums of dis- sums of displayed sums of dis- sums of dis- + column sums of dis- sums of dis- sums of displayed sums of dis- sums of dis- totals played val- played val- values played val- played values ues ues ues grand to- sum, average sum, average sum, average of sum, average sum, average @@ -5981,9 +6020,7 @@ Value reporting starting balance. PART 4: COMMANDS - - - Here are the standard commands, which you can list by running hledger. + Here are the standard commands, which you can list by running hledger. If you have installed more add-on commands, they also will be listed. Help commands @@ -6032,7 +6069,7 @@ PART 4: COMMANDS o aregister (areg) - show transactions in a particular account - o register (reg) - show postings in one or more accounts & running to- + o register (reg) - show postings in one or more accounts & running to- tal o balancesheet (bs) - show assets, liabilities and net worth @@ -6071,7 +6108,7 @@ PART 4: COMMANDS Help commands help - Show the hledger user manual with info, man, or a pager. With a (case + Show the hledger user manual with info, man, or a pager. With a (case insensitive) TOPIC argument, try to open it at that section heading. Flags: @@ -6080,23 +6117,23 @@ Help commands -p show the manual with $PAGER or less (less is always used if TOPIC is specified) - This command shows the hledger manual built in to your hledger exe- - cutable. It can be useful when offline, or when you prefer the termi- + This command shows the hledger manual built in to your hledger exe- + cutable. It can be useful when offline, or when you prefer the termi- nal to a web browser, or when the appropriate hledger manual or viewers are not installed properly on your system. - By default it chooses the best viewer found in $PATH, trying in this - order: info, man, $PAGER, less, more, stdout. (If a TOPIC is speci- - fied, $PAGER and more are not tried.) You can force the use of info, - man, or a pager with the -i, -m, or -p flags. If no viewer can be - found, or if running non-interactively, it just prints the manual to + By default it chooses the best viewer found in $PATH, trying in this + order: info, man, $PAGER, less, more, stdout. (If a TOPIC is speci- + fied, $PAGER and more are not tried.) You can force the use of info, + man, or a pager with the -i, -m, or -p flags. If no viewer can be + found, or if running non-interactively, it just prints the manual to stdout. - When using info, TOPIC can match either the full heading or a prefix. + When using info, TOPIC can match either the full heading or a prefix. If your info --version is < 6, you'll need to upgrade it, eg with 'brew install texinfo' on mac. - When using man or less, TOPIC must match the full heading. For a pre- + When using man or less, TOPIC must match the full heading. For a pre- fix match, you can write 'TOPIC.*'. Examples @@ -6113,19 +6150,19 @@ Help commands -s --speed=SPEED playback speed (1 is original speed, .5 is half, 2 is double, etc (default: 2)) - Run this command with no argument to list the demos. To play a demo, + Run this command with no argument to list the demos. To play a demo, write its number or a prefix or substring of its title. Tips: Make your terminal window large enough to see the demo clearly. - Use the -s/--speed SPEED option to set your preferred playback speed, + Use the -s/--speed SPEED option to set your preferred playback speed, eg -s4 to play at 4x original speed or -s.5 to play at half speed. The default speed is 2x. - Other asciinema options can be added following a double dash, eg -- + Other asciinema options can be added following a double dash, eg -- -i.1 to limit pauses or -- -h to list asciinema's other options. - During playback, several keys are available: SPACE to pause/unpause, . + During playback, several keys are available: SPACE to pause/unpause, . to step forward (while paused), CTRL-c quit. Examples: @@ -6148,35 +6185,32 @@ Data entry commands Flags: --no-new-accounts don't allow creating new accounts - Many hledger users edit their journals directly with a text editor, or - generate them from CSV. For more interactive data entry, there is the - add command, which prompts interactively on the console for new trans- - actions, and appends them to the main journal file (which should be in - journal format). Existing transactions are not changed. This is one - of the few hledger commands that writes to the journal file (see also + Many hledger users edit their journals directly with a text editor, or + generate them from CSV. For more interactive data entry, there is the + add command, which prompts interactively on the console for new trans- + actions, and appends them to the main journal file (which should be in + journal format). Existing transactions are not changed. This is one + of the few hledger commands that writes to the journal file (see also import). To use it, just run hledger add and follow the prompts. You can add as - many transactions as you like; when you are finished, enter . or press + many transactions as you like; when you are finished, enter . or press control-d or control-c to exit. Features: - o add tries to provide useful defaults, using the most similar (by de- - scription) recent transaction (filtered by the query, if any) as a + o add tries to provide useful defaults, using the most similar (by de- + scription) recent transaction (filtered by the query, if any) as a template. o You can also set the initial defaults with command line arguments. o Readline-style edit keys can be used during data entry. - o The tab key will auto-complete whenever possible - accounts, pay- - ees/descriptions, dates (yesterday, today, tomorrow). If the input + o The tab key will auto-complete whenever possible - accounts, pay- + ees/descriptions, dates (yesterday, today, tomorrow). If the input area is empty, it will insert the default value. - o If the journal defines a default commodity, it will be added to any - bare numbers entered. - o A parenthesised transaction code may be entered following a date. o Comments and tags may be entered following a description or amount. @@ -7498,7 +7532,7 @@ Advanced report commands 'bare' : commodity symbols in one column 'tidy' : every attribute in its own column -O --output-format=FMT select the output format. Supported formats: - txt, html, csv, tsv, json. + txt, html, csv, tsv, json, fods. -o --output-file=FILE write output to FILE. A file extension matching one of the above formats selects that format. @@ -7582,8 +7616,8 @@ Advanced report commands This command supports the output destination and output format options, with output formats txt, csv, tsv (Added in 1.32), json, and (multi-pe- - riod reports only:) html. In txt output in a colour-supporting termi- - nal, negative amounts are shown in red. + riod reports only:) html, fods (Added in 1.40). In txt output in a + colour-supporting terminal, negative amounts are shown in red. Simple balance report With no arguments, balance shows a list of all accounts and their @@ -9598,4 +9632,4 @@ LICENSE SEE ALSO hledger(1), hledger-ui(1), hledger-web(1), ledger(1) -hledger-1.34.99 June 2024 HLEDGER(1) +hledger-1.40 September 2024 HLEDGER(1)