From 30aeb662f2154b5ff1df32dbd252caacfac73886 Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Mon, 9 Sep 2024 14:07:29 -0700 Subject: [PATCH] doc: update manuals --- hledger-lib/.date.m4 | 2 +- hledger-ui/.date.m4 | 2 +- hledger-ui/hledger-ui.1 | 56 +- hledger-ui/hledger-ui.info | 94 +- hledger-ui/hledger-ui.txt | 225 ++-- hledger-web/.date.m4 | 2 +- hledger-web/hledger-web.1 | 4 +- hledger-web/hledger-web.info | 2 +- hledger-web/hledger-web.txt | 4 +- hledger/.date.m4 | 2 +- hledger/hledger.1 | 215 +++- hledger/hledger.info | 1585 +++++++++++++------------ hledger/hledger.txt | 2109 ++++++++++++++++++---------------- 13 files changed, 2281 insertions(+), 2021 deletions(-) diff --git a/hledger-lib/.date.m4 b/hledger-lib/.date.m4 index 705091ff8..c5f4680a4 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 705091ff8..c5f4680a4 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 67303deff..e6e3a6c00 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.99 " "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.99. See also the hledger manual for common concepts and file formats. .PP hledger is a robust, user\-friendly, cross\-platform set of programs for @@ -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 3e6c15f3f..00875e5c7 100644 --- a/hledger-ui/hledger-ui.info +++ b/hledger-ui/hledger-ui.info @@ -18,7 +18,7 @@ plain text accounting app. or 'hledger ui -- [OPTS] [QUERYARGS]' - This manual is for hledger's terminal interface, version 1.34.99. + This manual is for hledger's terminal interface, version 1.40.99. See also the hledger manual for common concepts and file formats. hledger is a robust, user-friendly, cross-platform set of programs @@ -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.) +movement keys are also supported. - 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.) + (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. @@ -537,30 +541,30 @@ 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: SCREENS13396 +Ref: #screens13500 +Node: Menu screen14136 +Ref: #menu-screen14257 +Node: Cash accounts screen14452 +Ref: #cash-accounts-screen14629 +Node: Balance sheet accounts screen14813 +Ref: #balance-sheet-accounts-screen15029 +Node: Income statement accounts screen15149 +Ref: #income-statement-accounts-screen15370 +Node: All accounts screen15534 +Ref: #all-accounts-screen15715 +Node: Register screen15897 +Ref: #register-screen16056 +Node: Transaction screen18340 +Ref: #transaction-screen18498 +Node: Error screen19915 +Ref: #error-screen20037 +Node: WATCH MODE20281 +Ref: #watch-mode20398 +Node: ENVIRONMENT21857 +Ref: #environment21973 +Node: BUGS22164 +Ref: #bugs22247  End Tag Table diff --git a/hledger-ui/hledger-ui.txt b/hledger-ui/hledger-ui.txt index 3ce514477..32bb78478 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.99. 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.) + (k,j,l,h) movement keys are also supported. - 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.) + (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.99 September 2024 HLEDGER-UI(1) diff --git a/hledger-web/.date.m4 b/hledger-web/.date.m4 index 705091ff8..c5f4680a4 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 99bc2592f..6755fe208 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.99 " "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.99. See also the hledger manual for common concepts and file formats. .PP hledger is a robust, user\-friendly, cross\-platform set of programs for diff --git a/hledger-web/hledger-web.info b/hledger-web/hledger-web.info index 35d1bef97..a5ec138cd 100644 --- a/hledger-web/hledger-web.info +++ b/hledger-web/hledger-web.info @@ -18,7 +18,7 @@ plain text accounting app. or 'hledger web -- [OPTS] [QUERY]' - This manual is for hledger's web interface, version 1.34.99. See + This manual is for hledger's web interface, version 1.40.99. See also the hledger manual for common concepts and file formats. hledger is a robust, user-friendly, cross-platform set of programs diff --git a/hledger-web/hledger-web.txt b/hledger-web/hledger-web.txt index 5354c322c..23212846f 100644 --- a/hledger-web/hledger-web.txt +++ b/hledger-web/hledger-web.txt @@ -11,7 +11,7 @@ SYNOPSIS hledger web -- [OPTS] [QUERY] DESCRIPTION - This manual is for hledger's web interface, version 1.34.99. See also + This manual is for hledger's web interface, version 1.40.99. See also the hledger manual for common concepts and file formats. hledger is a robust, user-friendly, cross-platform set of programs for @@ -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.99 September 2024 HLEDGER-WEB(1) diff --git a/hledger/.date.m4 b/hledger/.date.m4 index 705091ff8..c5f4680a4 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 67b929faa..12061639c 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.99 " "hledger User Manuals" @@ -33,7 +33,7 @@ hledger is inspired by and largely compatible with ledger(1), and largely interconvertible with beancount(1). .PP This manual is for hledger\[aq]s command line interface, version -1.34.99. +1.40.99. It also describes the common options, file formats and concepts used by all hledger programs. It might accidentally teach you some bookkeeping/accounting as well! @@ -112,7 +112,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 @@ -731,32 +731,62 @@ quoting than you would at the command prompt.) .PP Argument files are now superseded by.. .SS Config files -hledger will read extra command line options from a -\f[CR]hledger.conf\f[R] 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 -\f[CR]./hledger.conf\f[R] or \f[CR]$HOME/.hledger.conf\f[R]. +As of hledger 1.40, you can optionally save command line options (or +arguments) to be used when running hledger commands, in a config file. +Here\[aq]s a small example: +.IP +.EX +\f[I]# General options are listed first, one or more per line.\f[R] +\f[I]# These will be used with all hledger commands that support them.\f[R] +\-\-pretty + +\f[I]# Options following a \[ga][COMMANDNAME]\[ga] heading are used with that hledger command only.\f[R] +\f[B][print]\f[R] +\-\-explicit \-\-show\-costs +.EE .PP -To be precise, hledger looks for \f[CR]hledger.conf\f[R] in the current -directory or above, or in your home directory (with a dotted name, -\f[CR]\[ti]/.hledger.conf\f[R]), or finally in your XDG config directory -(\f[CR]\[ti]/.config/hledger/hledger.conf\f[R]). -Or you can select a particular config file by using the -\f[CR]\-\-conf\f[R] option, or by adding a \f[CR]hledger \-\-conf\f[R] -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 -\f[CR]\-\-debug\f[R] or \f[CR]\-\-debug=8\f[R]. +To use a config file, specify it with the \f[CR]\-\-conf\f[R] option. +Its options will be inserted near the start of your command line (so you +can override them if needed). +Or, you can add a \f[CR]hledger \-\-conf\f[R] shebang line to a config +file and execute it like a script. .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. +Or, you can set up an automatic config file that is used whenever you +run hledger. +This can be \f[CR]hledger.conf\f[R] in the current directory or above, +or \f[CR].hledger.conf\f[R] in your home directory +(\f[CR]\[ti]/.hledger.conf\f[R]), or \f[CR]hledger.conf\f[R] in your XDG +config directory (\f[CR]\[ti]/.config/hledger/hledger.conf\f[R]). .PP -\f[I](Added in 1.40; experimental)\f[R] +You can ignore config files by adding the \f[CR]\-n/\-\-no\-conf\f[R] +flag. +This is useful when using hledger in scripts, or when troubleshooting. +(When both \f[CR]\-\-conf\f[R] and \f[CR]\-\-no\-conf\f[R] options are +used, the right\-most wins.) +To inspect the processing of config files, use \f[CR]\-\-debug\f[R] or +\f[CR]\-\-debug=8\f[R]. +.PP +Here is another example config file you could start with: +https://github.com/simonmichael/hledger/blob/master/hledger.conf.sample +.PP +Automatic config files are convenient, but have a cost: it\[aq]s easy to +change a report\[aq]s behaviour, or break scripts/applications which use +hledger, in unintended ways that will surprise you later. +They change the nature of hledger somewhat, making it less transparent +and predictable. +If you decide to use one, here are some tips: +.IP \[bu] 2 +Be conservative about what you put in it. +Try to consider the effect on all your reports. +.IP \[bu] 2 +Whenever a hledger command does not work as expected, try it again with +\f[CR]\-n\f[R]. +.IP \[bu] 2 +If that helps, you can run it with \f[CR]\-\-debug\f[R] to see how a +config file affected it. +.PP +This feature has been added in hledger 1.40 and is considered +\f[I]experimental\f[R]. .SH Output .SS Output destination hledger commands send their output to the terminal by default. @@ -783,7 +813,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 +823,8 @@ csv/tsv T}@T{ html T}@T{ +fods +T}@T{ json T}@T{ sql @@ -807,6 +839,7 @@ Y T}@T{ Y T}@T{ +T}@T{ Y T}@T{ T} @@ -817,7 +850,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 +866,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 +879,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 +892,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 +905,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 +917,7 @@ T}@T{ Y T}@T{ T}@T{ +T}@T{ Y T}@T{ Y @@ -890,6 +930,7 @@ T}@T{ Y T}@T{ T}@T{ +T}@T{ Y T}@T{ T} @@ -897,9 +938,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 +1142,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 +5367,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 +5731,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. +.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 -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. +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 +5953,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 +6599,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 +7835,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 +8046,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. @@ -8827,6 +8903,9 @@ Flags: description closest to DESC \-r \-\-related show postings\[aq] siblings instead \-\-invert display all amounts with reversed sign + \-\-sort=FIELDS sort by: date, desc, account, amount, absamount, + or a comma\-separated combination of these. For a + descending sort, prefix with \-. (Default: date) \-w \-\-width=N set output width (default: terminal width or $COLUMNS). \-wN,M sets description width as well. \-\-align\-all guarantee alignment across all lines (slower) @@ -8894,6 +8973,16 @@ For example, it can be used on an income account where amounts are normally displayed as negative numbers. It\[aq]s also useful to show postings on the checking account together with the related account: +.PP +The \f[CR]\-\-sort=FIELDS\f[R] flag sorts by the fields given, which can +be any of \f[CR]account\f[R], \f[CR]amount\f[R], \f[CR]absamount\f[R], +\f[CR]date\f[R], or \f[CR]desc\f[R]/\f[CR]description\f[R], optionally +separated by commas. +For example, \f[CR]\-\-sort account,amount\f[R] will group all +transactions in each account, sorted by transaction amount. +Each field can be negated by a preceding \f[CR]\-\f[R], so +\f[CR]\-\-sort \-amount\f[R] will show transactions ordered from +smallest amount to largest amount. .IP .EX $ hledger register \-\-related \-\-invert assets:checking @@ -9450,7 +9539,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 +9632,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 0223610a8..97a393eb9 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.99. It also describes the common options, file formats and concepts used by all hledger programs. It might accidentally teach you some bookkeeping/accounting as well! You don't need to know everything in @@ -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 @@ -745,28 +745,52 @@ File: hledger.info, Node: Config files, Prev: Argument files, Up: Options 4.5 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 -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 -'$HOME/.hledger.conf'. +As of hledger 1.40, you can optionally save command line options (or +arguments) to be used when running hledger commands, in a config file. +Here's a small example: - 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 -('~/.config/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'. +# General options are listed first, one or more per line. +# These will be used with all hledger commands that support them. +--pretty - 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. +# Options following a `[COMMANDNAME]` heading are used with that hledger command only. +[print] +--explicit --show-costs - _(Added in 1.40; experimental)_ + To use a config file, specify it with the '--conf' option. Its +options will be inserted near the start of your command line (so you can +override them if needed). Or, you can add a 'hledger --conf' shebang +line to a config file and execute it like a script. + + Or, you can set up an automatic config file that is used whenever you +run hledger. This can be 'hledger.conf' in the current directory or +above, or '.hledger.conf' in your home directory ('~/.hledger.conf'), or +'hledger.conf' in your XDG config directory +('~/.config/hledger/hledger.conf'). + + You can ignore config files by adding the '-n/--no-conf' flag. This +is useful when using hledger in scripts, or when troubleshooting. (When +both '--conf' and '--no-conf' options are used, the right-most wins.) +To inspect the processing of config files, use '--debug' or '--debug=8'. + + Here is another example config file you could start with: +https://github.com/simonmichael/hledger/blob/master/hledger.conf.sample + + Automatic config files are convenient, but have a cost: it's easy to +change a report's behaviour, or break scripts/applications which use +hledger, in unintended ways that will surprise you later. They change +the nature of hledger somewhat, making it less transparent and +predictable. If you decide to use one, here are some tips: + + * Be conservative about what you put in it. Try to consider the + effect on all your reports. + * Whenever a hledger command does not work as expected, try it again + with '-n'. + * If that helps, you can run it with '--debug' to see how a config + file affected it. + + This feature has been added in hledger 1.40 and is considered +_experimental_.  File: hledger.info, Node: Output, Next: Environment, Prev: Options, Up: Top @@ -811,20 +835,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 +1083,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 +5335,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 +5552,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 +5673,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 +5695,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 +===================== -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: +* Menu: - * an inferred start date will be adjusted earlier if needed to fall - on a natural period boundary - - * an inferred end date will be adjusted later if needed to make the - last period the same length as the others. - - 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. +* Start date adjustment:: +* End date adjustment::  -File: hledger.info, Node: Period expressions, Prev: Date adjustment, Up: Time periods +File: hledger.info, Node: Start date adjustment, Next: End date adjustment, Up: Date adjustments -13.5 Period expressions +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, + + * '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]. + + 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). + + +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. + + +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: Period headings, Up: Time periods + +13.6 Period expressions ======================= The '-p/--period' option specifies a period expression, which is a @@ -5757,7 +5834,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 +5847,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 +5872,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 +5911,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 +6376,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 +7675,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 @@ -8513,6 +8588,9 @@ Flags: description closest to DESC -r --related show postings' siblings instead --invert display all amounts with reversed sign + --sort=FIELDS sort by: date, desc, account, amount, absamount, + or a comma-separated combination of these. For a + descending sort, prefix with -. (Default: date) -w --width=N set output width (default: terminal width or $COLUMNS). -wN,M sets description width as well. --align-all guarantee alignment across all lines (slower) @@ -8573,6 +8651,14 @@ on an income account where amounts are normally displayed as negative numbers. It's also useful to show postings on the checking account together with the related account: + The '--sort=FIELDS' flag sorts by the fields given, which can be any +of 'account', 'amount', 'absamount', 'date', or 'desc'/'description', +optionally separated by commas. For example, '--sort account,amount' +will group all transactions in each account, sorted by transaction +amount. Each field can be negated by a preceding '-', so '--sort +-amount' will show transactions ordered from smallest amount to largest +amount. + $ hledger register --related --invert assets:checking With a reporting interval, register shows summary postings, one per @@ -9124,7 +9210,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 +9301,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 @@ -11619,680 +11706,686 @@ 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: Text encoding5594 +Ref: #text-encoding5708 +Node: Data formats6274 +Ref: #data-formats6409 +Node: Standard input7998 +Ref: #standard-input8138 +Node: Multiple files8387 +Ref: #multiple-files8526 +Node: Strict mode9124 +Ref: #strict-mode9234 +Node: Commands9958 +Ref: #commands10060 +Node: Add-on commands11127 +Ref: #add-on-commands11229 +Node: Options12345 +Ref: #options12446 +Node: Special characters18740 +Ref: #special-characters18877 +Node: Single escaping shell metacharacters19040 +Ref: #single-escaping-shell-metacharacters19281 +Node: Double escaping regular expression metacharacters19884 +Ref: #double-escaping-regular-expression-metacharacters20195 +Node: Triple escaping for add-on commands20721 +Ref: #triple-escaping-for-add-on-commands20981 +Node: Less escaping21625 +Ref: #less-escaping21779 +Node: Unicode characters22103 +Ref: #unicode-characters22268 +Node: Regular expressions23767 +Ref: #regular-expressions23930 +Node: hledger's regular expressions27026 +Ref: #hledgers-regular-expressions27185 +Node: Argument files28571 +Ref: #argument-files28718 +Node: Config files29224 +Ref: #config-files29339 +Node: Output31441 +Ref: #output31543 +Node: Output destination31670 +Ref: #output-destination31801 +Node: Output format32226 +Ref: #output-format32372 +Node: CSV output33857 +Ref: #csv-output33973 +Node: HTML output34076 +Ref: #html-output34214 +Node: JSON output34308 +Ref: #json-output34446 +Node: SQL output35431 +Ref: #sql-output35547 +Node: Commodity styles36282 +Ref: #commodity-styles36422 +Node: Colour37160 +Ref: #colour37278 +Node: Box-drawing37682 +Ref: #box-drawing37800 +Node: Paging38084 +Ref: #paging38198 +Node: Debug output39151 +Ref: #debug-output39257 +Node: Environment39920 +Ref: #environment40044 +Node: PART 2 DATA FORMATS40611 +Ref: #part-2-data-formats40754 +Node: Journal40754 +Ref: #journal40863 +Node: Journal cheatsheet43232 +Ref: #journal-cheatsheet43359 +Node: Comments49446 +Ref: #comments49574 +Node: Transactions50390 +Ref: #transactions50513 +Node: Dates51527 +Ref: #dates51634 +Node: Simple dates51679 +Ref: #simple-dates51795 +Node: Posting dates52295 +Ref: #posting-dates52413 +Node: Status53382 +Ref: #status53483 +Node: Code55148 +Ref: #code55251 +Node: Description55483 +Ref: #description55614 +Node: Payee and note56170 +Ref: #payee-and-note56276 +Node: Transaction comments57261 +Ref: #transaction-comments57414 +Node: Postings57777 +Ref: #postings57908 +Node: Debits and credits58940 +Ref: #debits-and-credits59087 +Node: The two space delimiter59550 +Ref: #the-two-space-delimiter59707 +Node: Account names60115 +Ref: #account-names60245 +Node: Amounts61919 +Ref: #amounts62047 +Node: Decimal marks62948 +Ref: #decimal-marks63075 +Node: Digit group marks64052 +Ref: #digit-group-marks64205 +Node: Commodity64687 +Ref: #commodity64816 +Node: Costs65804 +Ref: #costs65899 +Node: Balance assertions68056 +Ref: #balance-assertions68209 +Node: Assertions and ordering69293 +Ref: #assertions-and-ordering69482 +Node: Assertions and multiple included files70021 +Ref: #assertions-and-multiple-included-files70281 +Node: Assertions and multiple -f files70781 +Ref: #assertions-and-multiple--f-files71026 +Node: Assertions and costs71423 +Ref: #assertions-and-costs71632 +Node: Assertions and commodities72073 +Ref: #assertions-and-commodities72288 +Node: Assertions and subaccounts73732 +Ref: #assertions-and-subaccounts73958 +Node: Assertions and virtual postings74402 +Ref: #assertions-and-virtual-postings74640 +Node: Assertions and auto postings74772 +Ref: #assertions-and-auto-postings75002 +Node: Assertions and precision75647 +Ref: #assertions-and-precision75829 +Node: Posting comments76096 +Ref: #posting-comments76259 +Node: Transaction balancing76636 +Ref: #transaction-balancing76795 +Node: Tags78638 +Ref: #tags78757 +Node: Tag names80100 +Ref: #tag-names80207 +Node: Special tags80595 +Ref: #special-tags80727 +Node: Tag values82240 +Ref: #tag-values82350 +Node: Directives83222 +Ref: #directives83349 +Node: Directives and multiple files84679 +Ref: #directives-and-multiple-files84857 +Node: Directive effects85624 +Ref: #directive-effects85778 +Node: account directive88780 +Ref: #account-directive88936 +Node: Account comments90230 +Ref: #account-comments90381 +Node: Account error checking90889 +Ref: #account-error-checking91082 +Node: Account display order92271 +Ref: #account-display-order92459 +Node: Account types93469 +Ref: #account-types93610 +Node: alias directive97243 +Ref: #alias-directive97404 +Node: Basic aliases98454 +Ref: #basic-aliases98585 +Node: Regex aliases99329 +Ref: #regex-aliases99486 +Node: Combining aliases100376 +Ref: #combining-aliases100554 +Node: Aliases and multiple files101830 +Ref: #aliases-and-multiple-files102034 +Node: end aliases directive102613 +Ref: #end-aliases-directive102832 +Node: Aliases can generate bad account names102981 +Ref: #aliases-can-generate-bad-account-names103229 +Node: Aliases and account types103814 +Ref: #aliases-and-account-types104006 +Node: commodity directive104702 +Ref: #commodity-directive104876 +Node: Commodity directive syntax106289 +Ref: #commodity-directive-syntax106474 +Node: Commodity error checking107925 +Ref: #commodity-error-checking108106 +Node: decimal-mark directive108400 +Ref: #decimal-mark-directive108582 +Node: include directive108979 +Ref: #include-directive109143 +Node: P directive110055 +Ref: #p-directive110200 +Node: payee directive111089 +Ref: #payee-directive111238 +Node: tag directive111711 +Ref: #tag-directive111866 +Node: Periodic transactions112323 +Ref: #periodic-transactions112488 +Node: Periodic rule syntax114477 +Ref: #periodic-rule-syntax114655 +Node: Periodic rules and relative dates115300 +Ref: #periodic-rules-and-relative-dates115566 +Node: Two spaces between period expression and description!116077 +Ref: #two-spaces-between-period-expression-and-description116354 +Node: Auto postings117038 +Ref: #auto-postings117186 +Node: Auto postings and multiple files120198 +Ref: #auto-postings-and-multiple-files120394 +Node: Auto postings and dates120603 +Ref: #auto-postings-and-dates120869 +Node: Auto postings and transaction balancing / inferred amounts / balance assertions121044 +Ref: #auto-postings-and-transaction-balancing-inferred-amounts-balance-assertions121387 +Node: Auto posting tags121890 +Ref: #auto-posting-tags122149 +Node: Auto postings on forecast transactions only122785 +Ref: #auto-postings-on-forecast-transactions-only123008 +Node: Other syntax123255 +Ref: #other-syntax123371 +Node: Balance assignments124027 +Ref: #balance-assignments124183 +Node: Balance assignments and costs125555 +Ref: #balance-assignments-and-costs125767 +Node: Balance assignments and multiple files125977 +Ref: #balance-assignments-and-multiple-files126207 +Node: Bracketed posting dates126400 +Ref: #bracketed-posting-dates126584 +Node: D directive127098 +Ref: #d-directive127266 +Node: apply account directive128871 +Ref: #apply-account-directive129051 +Node: Y directive129738 +Ref: #y-directive129898 +Node: Secondary dates130726 +Ref: #secondary-dates130880 +Node: Star comments132211 +Ref: #star-comments132371 +Node: Valuation expressions132903 +Ref: #valuation-expressions133080 +Node: Virtual postings133202 +Ref: #virtual-postings133379 +Node: Other Ledger directives134826 +Ref: #other-ledger-directives135022 +Node: Other cost/lot notations135588 +Ref: #other-costlot-notations135761 +Node: CSV138350 +Ref: #csv138441 +Node: CSV rules cheatsheet140433 +Ref: #csv-rules-cheatsheet140560 +Node: source142358 +Ref: #source142479 +Node: separator143359 +Ref: #separator143470 +Node: skip144010 +Ref: #skip144116 +Node: date-format144660 +Ref: #date-format144779 +Node: timezone145503 +Ref: #timezone145624 +Node: newest-first146629 +Ref: #newest-first146765 +Node: intra-day-reversed147342 +Ref: #intra-day-reversed147494 +Node: decimal-mark147942 +Ref: #decimal-mark148081 +Node: fields list148420 +Ref: #fields-list148557 +Node: Field assignment150228 +Ref: #field-assignment150370 +Node: Field names151447 +Ref: #field-names151576 +Node: date field152779 +Ref: #date-field152895 +Node: date2 field152943 +Ref: #date2-field153082 +Node: status field153138 +Ref: #status-field153279 +Node: code field153328 +Ref: #code-field153471 +Node: description field153516 +Ref: #description-field153674 +Node: comment field153733 +Ref: #comment-field153886 +Node: account field154179 +Ref: #account-field154327 +Node: amount field154897 +Ref: #amount-field155044 +Node: currency field157736 +Ref: #currency-field157887 +Node: balance field158144 +Ref: #balance-field158274 +Node: if block158667 +Ref: #if-block158786 +Node: Matchers160194 +Ref: #matchers160306 +Node: What matchers match161103 +Ref: #what-matchers-match161250 +Node: Combining matchers161690 +Ref: #combining-matchers161856 +Node: Match groups162393 +Ref: #match-groups162519 +Node: if table163287 +Ref: #if-table163407 +Node: balance-type165288 +Ref: #balance-type165415 +Node: include166115 +Ref: #include166240 +Node: Working with CSV166684 +Ref: #working-with-csv166829 +Node: Rapid feedback167236 +Ref: #rapid-feedback167367 +Node: Valid CSV167819 +Ref: #valid-csv167963 +Node: File Extension168695 +Ref: #file-extension168866 +Node: Reading CSV from standard input169430 +Ref: #reading-csv-from-standard-input169652 +Node: Reading multiple CSV files169816 +Ref: #reading-multiple-csv-files170045 +Node: Reading files specified by rule170292 +Ref: #reading-files-specified-by-rule170518 +Node: Valid transactions171689 +Ref: #valid-transactions171886 +Node: Deduplicating importing172514 +Ref: #deduplicating-importing172707 +Node: Setting amounts173743 +Ref: #setting-amounts173912 +Node: Amount signs176270 +Ref: #amount-signs176438 +Node: Setting currency/commodity177335 +Ref: #setting-currencycommodity177537 +Node: Amount decimal places178711 +Ref: #amount-decimal-places178915 +Node: Referencing other fields179968 +Ref: #referencing-other-fields180179 +Node: How CSV rules are evaluated181076 +Ref: #how-csv-rules-are-evaluated181291 +Node: Well factored rules182744 +Ref: #well-factored-rules182910 +Node: CSV rules examples183234 +Ref: #csv-rules-examples183367 +Node: Bank of Ireland183432 +Ref: #bank-of-ireland183567 +Node: Coinbase185029 +Ref: #coinbase185165 +Node: Amazon186212 +Ref: #amazon186335 +Node: Paypal188054 +Ref: #paypal188160 +Node: Timeclock195804 +Ref: #timeclock195909 +Node: Timedot198073 +Ref: #timedot198196 +Node: Timedot examples201317 +Ref: #timedot-examples201423 +Node: PART 3 REPORTING CONCEPTS203594 +Ref: #part-3-reporting-concepts203758 +Node: Time periods203758 +Ref: #time-periods203892 +Node: Report start & end date204031 +Ref: #report-start-end-date204183 +Node: Smart dates205507 +Ref: #smart-dates205660 +Node: Report intervals207450 +Ref: #report-intervals207606 +Node: Date adjustments208024 +Ref: #date-adjustments208184 +Node: Start date adjustment208244 +Ref: #start-date-adjustment208406 +Node: End date adjustment209147 +Ref: #end-date-adjustment209305 +Node: Period headings209892 +Ref: #period-headings210052 +Node: Period expressions210825 +Ref: #period-expressions210966 +Node: Period expressions with a report interval212730 +Ref: #period-expressions-with-a-report-interval212964 +Node: More complex report intervals213178 +Ref: #more-complex-report-intervals213423 +Node: Multiple weekday intervals215294 +Ref: #multiple-weekday-intervals215483 +Node: Depth216305 +Ref: #depth216407 +Node: Queries216703 +Ref: #queries216805 +Node: Query types218401 +Ref: #query-types218522 +Node: Combining query terms221756 +Ref: #combining-query-terms221933 +Node: Queries and command options223496 +Ref: #queries-and-command-options223701 +Node: Queries and account aliases223950 +Ref: #queries-and-account-aliases224155 +Node: Queries and valuation224275 +Ref: #queries-and-valuation224432 +Node: Pivoting224637 +Ref: #pivoting224751 +Node: Generating data226528 +Ref: #generating-data226660 +Node: Forecasting228328 +Ref: #forecasting228453 +Node: --forecast228984 +Ref: #forecast229115 +Node: Inspecting forecast transactions230085 +Ref: #inspecting-forecast-transactions230287 +Node: Forecast reports231418 +Ref: #forecast-reports231591 +Node: Forecast tags232527 +Ref: #forecast-tags232687 +Node: Forecast period in detail233147 +Ref: #forecast-period-in-detail233341 +Node: Forecast troubleshooting234235 +Ref: #forecast-troubleshooting234403 +Node: Budgeting235306 +Ref: #budgeting235429 +Node: Amount formatting235866 +Ref: #amount-formatting236008 +Node: Commodity display style236110 +Ref: #commodity-display-style236264 +Node: Rounding237951 +Ref: #rounding238106 +Node: Trailing decimal marks238556 +Ref: #trailing-decimal-marks238735 +Node: Amount parseability239489 +Ref: #amount-parseability239645 +Node: Cost reporting241070 +Ref: #cost-reporting241212 +Node: Recording costs241873 +Ref: #recording-costs242009 +Node: Reporting at cost243600 +Ref: #reporting-at-cost243775 +Node: Equity conversion postings244365 +Ref: #equity-conversion-postings244579 +Node: Inferring equity conversion postings247010 +Ref: #inferring-equity-conversion-postings247273 +Node: Combining costs and equity conversion postings248025 +Ref: #combining-costs-and-equity-conversion-postings248335 +Node: Requirements for detecting equity conversion postings249250 +Ref: #requirements-for-detecting-equity-conversion-postings249572 +Node: Infer cost and equity by default ?250772 +Ref: #infer-cost-and-equity-by-default251001 +Node: Value reporting251209 +Ref: #value-reporting251351 +Node: -V Value252090 +Ref: #v-value252222 +Node: -X Value in specified commodity252417 +Ref: #x-value-in-specified-commodity252618 +Node: Valuation date252767 +Ref: #valuation-date252944 +Node: Finding market price253727 +Ref: #finding-market-price253938 +Node: --infer-market-prices market prices from transactions255107 +Ref: #infer-market-prices-market-prices-from-transactions255389 +Node: Valuation commodity258151 +Ref: #valuation-commodity258371 +Node: --value Flexible valuation259584 +Ref: #value-flexible-valuation259783 +Node: Valuation examples261427 +Ref: #valuation-examples261627 +Node: Interaction of valuation and queries263559 +Ref: #interaction-of-valuation-and-queries263799 +Node: Effect of valuation on reports264276 +Ref: #effect-of-valuation-on-reports264479 +Node: PART 4 COMMANDS272174 +Ref: #part-4-commands272317 +Node: Help commands274390 +Ref: #help-commands274535 +Node: help274563 +Ref: #help274652 +Node: demo276240 +Ref: #demo276329 +Node: User interface commands277373 +Ref: #user-interface-commands277542 +Node: ui277567 +Ref: #ui277659 +Node: web277692 +Ref: #web277786 +Node: Data entry commands277820 +Ref: #data-entry-commands277989 +Node: add278018 +Ref: #add278112 +Node: import280473 +Ref: #import280573 +Node: Date skipping281734 +Ref: #date-skipping281857 +Node: Import testing284635 +Ref: #import-testing284798 +Node: Importing balance assignments285641 +Ref: #importing-balance-assignments285848 +Node: Import and commodity styles286497 +Ref: #import-and-commodity-styles286677 +Node: Basic report commands286906 +Ref: #basic-report-commands287080 +Node: accounts287207 +Ref: #accounts287317 +Node: codes290080 +Ref: #codes290204 +Node: commodities291102 +Ref: #commodities291242 +Node: descriptions291346 +Ref: #descriptions291488 +Node: files291813 +Ref: #files291935 +Node: notes292110 +Ref: #notes292226 +Node: payees292622 +Ref: #payees292741 +Node: prices293406 +Ref: #prices293525 +Node: stats294298 +Ref: #stats294413 +Node: tags296039 +Ref: #tags-1296139 +Node: Standard report commands297346 +Ref: #standard-report-commands297531 +Node: print297651 +Ref: #print297759 +Node: print explicitness300097 +Ref: #print-explicitness300238 +Node: print amount style301017 +Ref: #print-amount-style301185 +Node: print parseability302255 +Ref: #print-parseability302425 +Node: print other features303174 +Ref: #print-other-features303351 +Node: print output format303872 +Ref: #print-output-format304018 +Node: aregister307157 +Ref: #aregister307290 +Node: aregister and posting dates310937 +Ref: #aregister-and-posting-dates311082 +Node: register311838 +Ref: #register311976 +Node: Custom register output318797 +Ref: #custom-register-output318926 +Node: balancesheet320273 +Ref: #balancesheet320428 +Node: balancesheetequity324909 +Ref: #balancesheetequity325076 +Node: cashflow329915 +Ref: #cashflow330065 +Node: incomestatement334343 +Ref: #incomestatement334480 +Node: Advanced report commands338807 +Ref: #advanced-report-commands338985 +Node: balance339015 +Ref: #balance339123 +Node: balance features343904 +Ref: #balance-features344044 +Node: Simple balance report345980 +Ref: #simple-balance-report346165 +Node: Balance report line format347790 +Ref: #balance-report-line-format347992 +Node: Filtered balance report350150 +Ref: #filtered-balance-report350342 +Node: List or tree mode350669 +Ref: #list-or-tree-mode350837 +Node: Depth limiting352182 +Ref: #depth-limiting352348 +Node: Dropping top-level accounts352949 +Ref: #dropping-top-level-accounts353149 +Node: Showing declared accounts353459 +Ref: #showing-declared-accounts353658 +Node: Sorting by amount354189 +Ref: #sorting-by-amount354356 +Node: Percentages355026 +Ref: #percentages355185 +Node: Multi-period balance report355733 +Ref: #multi-period-balance-report355933 +Node: Balance change end balance358485 +Ref: #balance-change-end-balance358694 +Node: Balance report types360122 +Ref: #balance-report-types360303 +Node: Calculation type360801 +Ref: #calculation-type360956 +Node: Accumulation type361505 +Ref: #accumulation-type361685 +Node: Valuation type362606 +Ref: #valuation-type362794 +Node: Combining balance report types363795 +Ref: #combining-balance-report-types363989 +Node: Budget report365827 +Ref: #budget-report365989 +Node: Using the budget report368132 +Ref: #using-the-budget-report368305 +Node: Budget date surprises370408 +Ref: #budget-date-surprises370608 +Node: Selecting budget goals371772 +Ref: #selecting-budget-goals371975 +Node: Budgeting vs forecasting372720 +Ref: #budgeting-vs-forecasting372897 +Node: Balance report layout374397 +Ref: #balance-report-layout374582 +Node: Wide layout375535 +Ref: #wide-layout375670 +Node: Tall layout377940 +Ref: #tall-layout378095 +Node: Bare layout379246 +Ref: #bare-layout379401 +Node: Tidy layout381310 +Ref: #tidy-layout381445 +Node: Some useful balance reports382854 +Ref: #some-useful-balance-reports383029 +Node: roi384114 +Ref: #roi384214 +Node: Spaces and special characters in --inv and --pnl386361 +Ref: #spaces-and-special-characters-in---inv-and---pnl386599 +Node: Semantics of --inv and --pnl387087 +Ref: #semantics-of---inv-and---pnl387324 +Node: IRR and TWR explained389174 +Ref: #irr-and-twr-explained389332 +Node: Chart commands392585 +Ref: #chart-commands392743 +Node: activity392766 +Ref: #activity392855 +Node: Data generation commands393263 +Ref: #data-generation-commands393437 +Node: close393469 +Ref: #close393575 +Node: close --migrate396061 +Ref: #close---migrate396186 +Node: close --close397825 +Ref: #close---close397967 +Node: close --open398203 +Ref: #close---open398342 +Node: close --assert398452 +Ref: #close---assert398596 +Node: close --assign398817 +Ref: #close---assign398963 +Node: close --retain399489 +Ref: #close---retain399640 +Node: close customisation400385 +Ref: #close-customisation400562 +Node: close and balance assertions402029 +Ref: #close-and-balance-assertions402224 +Node: close examples403551 +Ref: #close-examples403690 +Node: Retain earnings403788 +Ref: #retain-earnings403945 +Node: Migrate balances to a new file404291 +Ref: #migrate-balances-to-a-new-file404515 +Node: More detailed close examples405643 +Ref: #more-detailed-close-examples405839 +Node: rewrite405865 +Ref: #rewrite405975 +Node: Re-write rules in a file408437 +Ref: #re-write-rules-in-a-file408598 +Node: Diff output format409747 +Ref: #diff-output-format409928 +Node: rewrite vs print --auto411020 +Ref: #rewrite-vs.-print---auto411178 +Node: Maintenance commands411734 +Ref: #maintenance-commands411905 +Node: check411943 +Ref: #check412042 +Node: Basic checks413025 +Ref: #basic-checks413143 +Node: Strict checks413978 +Ref: #strict-checks414119 +Node: Other checks414853 +Ref: #other-checks414993 +Node: Custom checks416708 +Ref: #custom-checks416828 +Node: diff417163 +Ref: #diff417273 +Node: test418370 +Ref: #test418466 +Node: PART 5 COMMON TASKS419242 +Ref: #part-5-common-tasks419401 +Node: Getting help419475 +Ref: #getting-help419624 +Node: Constructing command lines420384 +Ref: #constructing-command-lines420565 +Node: Starting a journal file421222 +Ref: #starting-a-journal-file421404 +Node: Setting LEDGER_FILE422606 +Ref: #setting-ledger_file422778 +Node: Setting opening balances423735 +Ref: #setting-opening-balances423916 +Node: Recording transactions427057 +Ref: #recording-transactions427226 +Node: Reconciling427782 +Ref: #reconciling427914 +Node: Reporting430171 +Ref: #reporting430300 +Node: Migrating to a new file434285 +Ref: #migrating-to-a-new-file434435 +Node: BUGS434734 +Ref: #bugs434828 +Node: Troubleshooting435707 +Ref: #troubleshooting435807  End Tag Table diff --git a/hledger/hledger.txt b/hledger/hledger.txt index 81532c061..2cbc24dd3 100644 --- a/hledger/hledger.txt +++ b/hledger/hledger.txt @@ -19,7 +19,7 @@ DESCRIPTION and largely compatible with ledger(1), and largely interconvertible with beancount(1). - This manual is for hledger's command line interface, version 1.34.99. + This manual is for hledger's command line interface, version 1.40.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 @@ -83,7 +83,7 @@ Input 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- @@ -568,28 +568,54 @@ Options 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), - and command-specific options (or arguments). hledger.conf.sample is an - example, which you can install as ./hledger.conf or - $HOME/.hledger.conf. + As of hledger 1.40, you can optionally save command line options (or + arguments) to be used when running hledger commands, in a config file. + Here's a small example: - 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. + # General options are listed first, one or more per line. + # These will be used with all hledger commands that support them. + --pretty - 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. + # Options following a `[COMMANDNAME]` heading are used with that hledger command only. + [print] + --explicit --show-costs - (Added in 1.40; experimental) + To use a config file, specify it with the --conf option. Its options + will be inserted near the start of your command line (so you can over- + ride them if needed). Or, you can add a hledger --conf shebang line to + a config file and execute it like a script. + + Or, you can set up an automatic config file that is used whenever you + run hledger. This can be hledger.conf in the current directory or + above, or .hledger.conf in your home directory (~/.hledger.conf), or + hledger.conf in your XDG config directory (~/.con- + fig/hledger/hledger.conf). + + You can ignore config files by adding the -n/--no-conf flag. This is + useful when using hledger in scripts, or when troubleshooting. (When + both --conf and --no-conf options are used, the right-most wins.) To + inspect the processing of config files, use --debug or --debug=8. + + Here is another example config file you could start with: + https://github.com/simonmichael/hledger/blob/master/hledger.conf.sample + + Automatic config files are convenient, but have a cost: it's easy to + change a report's behaviour, or break scripts/applications which use + hledger, in unintended ways that will surprise you later. They change + the nature of hledger somewhat, making it less transparent and pre- + dictable. If you decide to use one, here are some tips: + + o Be conservative about what you put in it. Try to consider the effect + on all your reports. + + o Whenever a hledger command does not work as expected, try it again + with -n. + + o If that helps, you can run it with --debug to see how a config file + affected it. + + This feature has been added in hledger 1.40 and is considered experi- + mental. Output Output destination @@ -598,34 +624,32 @@ Output $ hledger print > foo.txt - Some commands (print, register, stats, the balance commands) also pro- - vide the -o/--output-file option, which does the same thing without + Some commands (print, register, stats, the balance commands) also pro- + vide the -o/--output-file option, which does the same thing without needing the shell. Eg: $ hledger print -o foo.txt $ hledger print -o - # write to stdout (the default) Output format - Some commands offer other kinds of output, not just text on the termi- + Some commands offer other kinds of output, not just text on the termi- nal. Here are those commands and the formats currently supported: - - 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 @@ -797,17 +821,17 @@ Journal 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 - as ledger-mode or hledger-mode for Emacs, vim-ledger for Vim, and + 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- tion at hledger.org for the full list. A hledger journal file can contain three kinds of thing: comment lines, - transactions, and/or directives (including periodic transaction rules - and auto posting rules). Understanding the journal file format will - also give you a good understanding of hledger's data model. Here's a - quick cheatsheet/overview, followed by detailed descriptions of each + transactions, and/or directives (including periodic transaction rules + and auto posting rules). Understanding the journal file format will + also give you a good understanding of hledger's data model. Here's a + quick cheatsheet/overview, followed by detailed descriptions of each part. Journal cheatsheet @@ -941,7 +965,7 @@ Journal Comments Lines in the journal will be ignored if they begin with a hash (#) or a - semicolon (;). (See also Other syntax.) hledger will also ignore re- + semicolon (;). (See also Other syntax.) hledger will also ignore re- gions beginning with a comment line and ending with an end comment line (or file end). Here's a suggestion for choosing between them: @@ -963,15 +987,15 @@ Journal end comment Some hledger entries can have same-line comments attached to them, from - ; (semicolon) to end of line. See Transaction comments, Posting com- + ; (semicolon) to end of line. See Transaction comments, Posting com- ments, and Account comments below. Transactions - Transactions are the main unit of information in a journal file. They - represent events, typically a movement of some quantity of commodities + Transactions are the main unit of information in a journal file. They + represent events, typically a movement of some quantity of commodities between two or more named accounts. - Each transaction is recorded as a journal entry, beginning with a sim- + Each transaction is recorded as a journal entry, beginning with a sim- ple date in column 0. This can be followed by any of the following op- tional fields, separated by spaces: @@ -981,11 +1005,11 @@ Journal o a description (any remaining text until end of line or a semicolon) - o a comment (any remaining text following a semicolon until end of + o a comment (any remaining text following a semicolon until end of line, and any following indented lines beginning with a semicolon) o 0 or more indented posting lines, describing what was transferred and - the accounts involved (indented comment lines are also allowed, but + the accounts involved (indented comment lines are also allowed, but not blank lines or non-indented lines). Here's a simple journal file containing one transaction: @@ -996,22 +1020,22 @@ Journal Dates Simple dates - Dates in the journal file use simple dates format: YYYY-MM-DD or + Dates in the journal file use simple dates format: YYYY-MM-DD or YYYY/MM/DD or YYYY.MM.DD, with leading zeros optional. The year may be - omitted, in which case it will be inferred from the context: the cur- - rent transaction, the default year set with a Y directive, or the cur- + omitted, in which case it will be inferred from the context: the cur- + rent transaction, the default year set with a Y directive, or the cur- rent date when the command is run. Some examples: 2010-01-31, 2010/01/31, 2010.1.31, 1/31. - (The UI also accepts simple dates, as well as the more flexible smart + (The UI also accepts simple dates, as well as the more flexible smart dates documented in the hledger manual.) Posting dates - You can give individual postings a different date from their parent - transaction, by adding a posting comment containing a tag (see below) + You can give individual postings a different date from their parent + transaction, by adding a posting comment containing a tag (see below) like date:DATE. This is probably the best way to control posting dates - precisely. Eg in this example the expense should appear in May re- - ports, and the deduction from checking should be reported on 6/1 for + precisely. Eg in this example the expense should appear in May re- + ports, and the deduction from checking should be reported on 6/1 for easy bank reconciliation: 2015/5/30 @@ -1024,15 +1048,15 @@ Journal $ hledger -f t.j register checking 2015-06-01 assets:checking $-10 $-10 - DATE should be a simple date; if the year is not specified it will use + DATE should be a simple date; if the year is not specified it will use the year of the transaction's date. - The date: tag must have a valid simple date value if it is present, eg + The date: tag must have a valid simple date value if it is present, eg a date: tag with no value is not allowed. Status - Transactions (or individual postings within a transaction) can have a - status mark, which is a single character before the transaction de- - scription (or posting account name), separated from it by a space, in- + Transactions (or individual postings within a transaction) can have a + status mark, which is a single character before the transaction de- + scription (or posting account name), separated from it by a space, in- dicating one of three statuses: mark status @@ -1041,20 +1065,20 @@ Journal ! pending * cleared - When reporting, you can filter by status with the -U/--unmarked, + When reporting, you can filter by status with the -U/--unmarked, -P/--pending, and -C/--cleared flags (and you can combine these, eg -UP - to match all except cleared things). Or you can use the status:, sta- + to match all except cleared things). Or you can use the status:, sta- tus:!, and status:* queries, or the U, P, C keys in hledger-ui. (Note: in Ledger the "unmarked" state is called "uncleared"; in hledger we renamed it to "unmarked" for semantic clarity.) - Status marks are optional, but can be helpful eg for reconciling with + Status marks are optional, but can be helpful eg for reconciling with real-world accounts. Some editor modes provide highlighting and short- - cuts for working with status. Eg in Emacs ledger-mode, you can toggle + cuts for working with status. Eg in Emacs ledger-mode, you can toggle transaction status with C-c C-e, or posting status with C-c C-c. - What "uncleared", "pending", and "cleared" actually mean is up to you. + What "uncleared", "pending", and "cleared" actually mean is up to you. Here's one suggestion: status meaning @@ -1065,55 +1089,55 @@ Journal cleared complete, reconciled as far as possible, and considered cor- rect - With this scheme, you would use -PC to see the current balance at your + With this scheme, you would use -PC to see the current balance at your bank, -U to see things which will probably hit your bank soon (like un- - cashed checks), and no flags to see the most up-to-date state of your + cashed checks), and no flags to see the most up-to-date state of your finances. Code - After the status mark, but before the description, you can optionally - write a transaction "code", enclosed in parentheses. This is a good - place to record a check number, or some other important transaction id + After the status mark, but before the description, you can optionally + write a transaction "code", enclosed in parentheses. This is a good + place to record a check number, or some other important transaction id or reference number. Description - After the date, status mark and/or code fields, the rest of the line - (or until a comment is begun with ;) is the transaction's description. + After the date, status mark and/or code fields, the rest of the line + (or until a comment is begun with ;) is the transaction's description. Here you can describe the transaction (called the "narration" in tradi- - tional bookkeeping), or you can record a payee/payer name, or you can + tional bookkeeping), or you can record a payee/payer name, or you can leave it empty. - Transaction descriptions show up in print output and in register re- + Transaction descriptions show up in print output and in register re- ports, and can be listed with the descriptions command. - You can query by description with desc:DESCREGEX, or pivot on descrip- + You can query by description with desc:DESCREGEX, or pivot on descrip- tion with --pivot desc. Payee and note Sometimes people want a dedicated payee/payer field that can be queried - and checked more strictly. If you want that, you can write a | (pipe) - character in the description. This divides it into a "payee" field on + and checked more strictly. If you want that, you can write a | (pipe) + character in the description. This divides it into a "payee" field on the left, and a "note" field on the right. (Either can be empty.) - You can query these with payee:PAYEEREGEX and note:NOTEREGEX, list - their values with the payees and notes commands, or pivot on payee or + You can query these with payee:PAYEEREGEX and note:NOTEREGEX, list + their values with the payees and notes commands, or pivot on payee or note. Note: in transactions with no | character, description, payee, and note all have the same value. Once a | is added, they become distinct. (If - you'd like to change this behaviour, please propose it on the mail + you'd like to change this behaviour, please propose it on the mail list.) If you want more strict error checking, you can declare the valid payee - names with payee directives, and then enforce these with hledger check - payees. (Note: because of the above, for this you'll need to ensure - every transaction description contains a | and therefore a checkable + names with payee directives, and then enforce these with hledger check + payees. (Note: because of the above, for this you'll need to ensure + every transaction description contains a | and therefore a checkable payee name, even if it's empty.) Transaction comments - Text following ;, after a transaction description, and/or on indented - lines immediately below it, form comments for that transaction. They - are reproduced by print but otherwise ignored, except they may contain + Text following ;, after a transaction description, and/or on indented + lines immediately below it, form comments for that transaction. They + are reproduced by print but otherwise ignored, except they may contain tags, which are not ignored. 2012-01-01 something ; a transaction comment @@ -1122,63 +1146,63 @@ Journal assets Postings - A posting is an addition of some amount to, or removal of some amount - from, an account. Each posting line begins with at least one space or + A posting is an addition of some amount to, or removal of some amount + from, an account. Each posting line begins with at least one space or tab (2 or 4 spaces is common), followed by: o (optional) a status character (empty, !, or *), followed by a space - o (required) an account name (any text, optionally containing single + o (required) an account name (any text, optionally containing single spaces, until end of line or a double space) o (optional) two or more spaces (or tabs) followed by an amount. - If the amount is positive, it is being added to the account; if nega- + If the amount is positive, it is being added to the account; if nega- tive, it is being removed from the account. - The posting amounts in a transaction must sum up to zero, indicating - that the inflows and outflows are equal. We call this a balanced + The posting amounts in a transaction must sum up to zero, indicating + that the inflows and outflows are equal. We call this a balanced transaction. (You can read more about the nitty-gritty details of "sum up to zero" in Transaction balancing below.) - As a convenience, you can optionally leave one amount blank; hledger + As a convenience, you can optionally leave one amount blank; hledger will infer what it should be so as to balance the transaction. Debits and credits The traditional accounting concepts of debit and credit of course exist - in hledger, but we represent them with numeric sign, as described - above. Positive and negative posting amounts represent debits and + in hledger, but we represent them with numeric sign, as described + above. Positive and negative posting amounts represent debits and credits respectively. - You don't need to remember that, but if you would like to - eg for - helping newcomers or for talking with your accountant - here's a handy + You don't need to remember that, but if you would like to - eg for + helping newcomers or for talking with your accountant - here's a handy mnemonic: debit / plus / left / short words credit / minus / right / longer words The two space delimiter - Be sure to notice the unusual separator between the account name and + Be sure to notice the unusual separator between the account name and the following amount. Because hledger allows account names with spaces - in them, you must separate the account name and amount (if any) by two - or more spaces (or tabs). It's easy to forget at first. If you ever - see the amount being treated as part of the account name, you'll know + in them, you must separate the account name and amount (if any) by two + or more spaces (or tabs). It's easy to forget at first. If you ever + see the amount being treated as part of the account name, you'll know you probably need to add another space between them. Account names - Accounts are the main way of categorising things in hledger. As in - Double Entry Bookkeeping, they can represent real world accounts (such + Accounts are the main way of categorising things in hledger. As in + Double Entry Bookkeeping, they can represent real world accounts (such as a bank account), or more abstract categories such as "money borrowed from Frank" or "money spent on electricity". - You can use any account names you like, but we usually start with the + You can use any account names you like, but we usually start with the traditional accounting categories, which in english are assets, liabil- ities, equity, revenues, expenses. (You might see these referred to as A, L, E, R, X for short.) - For more precise reporting, we usually divide the top level accounts + For more precise reporting, we usually divide the top level accounts into more detailed subaccounts, by writing a full colon between account - name parts. For example, from the account names assets:bank:checking + name parts. For example, from the account names assets:bank:checking and expenses:food, hledger will infer this hierarchy of five accounts: assets @@ -1196,33 +1220,33 @@ Journal food hledger reports can summarise the account tree to any depth, so you can - go as deep as you like with subcategories, but keeping your account + go as deep as you like with subcategories, but keeping your account names relatively simple may be best when starting out. Account names may be capitalised or not; they may contain letters, num- - bers, symbols, or single spaces. Note, when an account name and an - amount are written on the same line, they must be separated by two or + bers, symbols, or single spaces. Note, when an account name and an + amount are written on the same line, they must be separated by two or more spaces (or tabs). - Parentheses or brackets enclosing the full account name indicate vir- - tual postings, described below. Parentheses or brackets internal to + Parentheses or brackets enclosing the full account name indicate vir- + tual postings, described below. Parentheses or brackets internal to the account name have no special meaning. - Account names can be altered temporarily or permanently by account + Account names can be altered temporarily or permanently by account aliases. Amounts After the account name, there is usually an amount. (Remember: between account name and amount, there must be two or more spaces.) - hledger's amount format is flexible, supporting several international - formats. Here are some examples. Amounts have a number (the "quan- + hledger's amount format is flexible, supporting several international + formats. Here are some examples. Amounts have a number (the "quan- tity"): 1 ..and usually a currency symbol or commodity name (more on this below), - to the left or right of the quantity, with or without a separating + to the left or right of the quantity, with or without a separating space: $1 @@ -1230,13 +1254,13 @@ Journal 3 "green apples" Amounts can be preceded by a minus sign (or a plus sign, though plus is - the default), The sign can be written before or after a left-side com- + the default), The sign can be written before or after a left-side com- modity symbol: -$1 $-1 - One or more spaces between the sign and the number are acceptable when + One or more spaces between the sign and the number are acceptable when parsing (but they won't be displayed in output): + $1 @@ -1254,31 +1278,31 @@ Journal 1,23 Both of these are common in international number formats, so hledger is - not biased towards one or the other. Because hledger also supports - digit group marks (eg thousands separators), this means that a number - like 1,000 or 1.000 containing just one period or comma is ambiguous. - In such cases, hledger by default assumes it is a decimal mark, and + not biased towards one or the other. Because hledger also supports + digit group marks (eg thousands separators), this means that a number + like 1,000 or 1.000 containing just one period or comma is ambiguous. + In such cases, hledger by default assumes it is a decimal mark, and will parse both of those as 1. - To help hledger parse such ambiguous numbers more accurately, if you - use digit group marks, we recommend declaring the decimal mark explic- - itly. The best way is to add a decimal-mark directive at the top of + To help hledger parse such ambiguous numbers more accurately, if you + use digit group marks, we recommend declaring the decimal mark explic- + itly. The best way is to add a decimal-mark directive at the top of each data file, like this: decimal-mark . - Or you can declare it per commodity with commodity directives, de- + Or you can declare it per commodity with commodity directives, de- scribed below. - hledger also accepts numbers like 10. with no digits after the decimal - mark (and will sometimes display numbers that way to disambiguate them + hledger also accepts numbers like 10. with no digits after the decimal + mark (and will sometimes display numbers that way to disambiguate them - see Trailing decimal marks). Digit group marks - In the integer part of the amount quantity (left of the decimal mark), - groups of digits can optionally be separated by a digit group mark - a - comma or period (whichever is not used as decimal mark), or a space - (several Unicode space variants, like no-break space, are also ac- + In the integer part of the amount quantity (left of the decimal mark), + groups of digits can optionally be separated by a digit group mark - a + comma or period (whichever is not used as decimal mark), or a space + (several Unicode space variants, like no-break space, are also ac- cepted). So these are all valid amounts in a journal file: $1,000,000.00 @@ -1288,46 +1312,46 @@ Journal 1 000 000.00 ; <- no-break space Commodity - Amounts in hledger have both a "quantity", which is a signed decimal + Amounts in hledger have both a "quantity", which is a signed decimal number, and a "commodity", which is a currency symbol, stock ticker, or any word or phrase describing something you are tracking. If the commodity name contains non-letters (spaces, numbers, or punctu- - ation), you must always write it inside double quotes ("green apples", + ation), you must always write it inside double quotes ("green apples", "ABC123"). - If you write just a bare number, that too will have a commodity, with + If you write just a bare number, that too will have a commodity, with name ""; we call that the "no-symbol commodity". - Actually, hledger combines these single-commodity amounts into more - powerful multi-commodity amounts, which are what it works with most of - the time. A multi-commodity amount could be, eg: 1 USD, 2 EUR, 3.456 - TSLA. In practice, you will only see multi-commodity amounts in + Actually, hledger combines these single-commodity amounts into more + powerful multi-commodity amounts, which are what it works with most of + the time. A multi-commodity amount could be, eg: 1 USD, 2 EUR, 3.456 + TSLA. In practice, you will only see multi-commodity amounts in hledger's output; you can't write them directly in the journal file. By default, the format of amounts in the journal influences how hledger - displays them in output. This is explained in Commodity display style + displays them in output. This is explained in Commodity display style below. Costs - After a posting amount, you can note its cost (when buying) or selling - price (when selling) in another commodity, by writing either @ UNIT- - PRICE or @@ TOTALPRICE after it. This indicates a conversion transac- + After a posting amount, you can note its cost (when buying) or selling + price (when selling) in another commodity, by writing either @ UNIT- + PRICE or @@ TOTALPRICE after it. This indicates a conversion transac- tion, where one commodity is exchanged for another. - (You might also see this called "transaction price" in hledger docs, - discussions, or code; that term was directionally neutral and reminded - that it is a price specific to a transaction, but we now just call it + (You might also see this called "transaction price" in hledger docs, + discussions, or code; that term was directionally neutral and reminded + that it is a price specific to a transaction, but we now just call it "cost", with the understanding that the transaction could be a purchase or a sale.) - Costs are usually written explicitly with @ or @@, but can also be in- + Costs are usually written explicitly with @ or @@, but can also be in- ferred automatically for simple multi-commodity transactions. Note, if - costs are inferred, the order of postings is significant; the first + costs are inferred, the order of postings is significant; the first posting will have a cost attached, in the commodity of the second. - As an example, here are several ways to record purchases of a foreign - currency in hledger, using the cost notation either explicitly or im- + As an example, here are several ways to record purchases of a foreign + currency in hledger, using the cost notation either explicitly or im- plicitly: 1. Write the price per unit, as @ UNITPRICE after the amount: @@ -1351,17 +1375,17 @@ Journal assets:euros 100 ; one hundred euros purchased assets:dollars $-135 ; for $135 - Amounts can be converted to cost at report time using the -B/--cost + Amounts can be converted to cost at report time using the -B/--cost flag; this is discussed more in the Cost reporting section. - Note that the cost normally should be a positive amount, though it's - not required to be. This can be a little confusing, see discussion at + Note that the cost normally should be a positive amount, though it's + not required to be. This can be a little confusing, see discussion at --infer-market-prices: market prices from transactions. Balance assertions - hledger supports Ledger-style balance assertions in journal files. - These look like, for example, = EXPECTEDBALANCE following a posting's - amount. Eg here we assert the expected dollar balance in accounts a + hledger supports Ledger-style balance assertions in journal files. + These look like, for example, = EXPECTEDBALANCE following a posting's + amount. Eg here we assert the expected dollar balance in accounts a and b after each posting: 2013/1/1 @@ -1373,42 +1397,42 @@ Journal b $-1 = $-2 After reading a journal file, hledger will check all balance assertions - and report an error if any of them fail. Balance assertions can pro- - tect you from, eg, inadvertently disrupting reconciled balances while - cleaning up old entries. You can disable them temporarily with the + and report an error if any of them fail. Balance assertions can pro- + tect you from, eg, inadvertently disrupting reconciled balances while + cleaning up old entries. You can disable them temporarily with the -I/--ignore-assertions flag, which can be useful for troubleshooting or - for reading Ledger files. (Note: this flag currently does not disable + for reading Ledger files. (Note: this flag currently does not disable balance assignments, described below). Assertions and ordering - hledger calculates and checks an account's balance assertions in date + hledger calculates and checks an account's balance assertions in date order (and when there are multiple assertions on the same day, in parse - order). Note this is different from Ledger, which checks assertions + order). Note this is different from Ledger, which checks assertions always in parse order, ignoring dates. This means in hledger you can freely reorder transactions, postings, or files, and balance assertions will usually keep working. The exception - is when you reorder multiple postings on the same day, to the same ac- + is when you reorder multiple postings on the same day, to the same ac- count, which have balance assertions; those will likely need updating. Assertions and multiple included files - Multiple files included with the include directive are processed as if - concatenated into one file, preserving their order and the posting or- - der within each file. It means that balance assertions in later files + Multiple files included with the include directive are processed as if + concatenated into one file, preserving their order and the posting or- + der within each file. It means that balance assertions in later files will see balance from earlier files. - And if you have multiple postings to an account on the same day, split - across multiple files, and you want to assert the account's balance on + And if you have multiple postings to an account on the same day, split + across multiple files, and you want to assert the account's balance on that day, you'll need to put the assertion in the right file - the last one in the sequence, probably. Assertions and multiple -f files - Unlike include, when multiple files are specified on the command line - with multiple -f/--file options, balance assertions will not see bal- + Unlike include, when multiple files are specified on the command line + with multiple -f/--file options, balance assertions will not see bal- ance from earlier files. This can be useful when you do not want prob- lems in earlier files to disrupt valid assertions in later files. - If you do want assertions to see balance from earlier files, use in- + If you do want assertions to see balance from earlier files, use in- clude, or concatenate the files temporarily. Assertions and costs @@ -1418,20 +1442,20 @@ Journal 2019/1/1 (a) $1 @ 1 = $1 - We do allow costs to be written in balance assertion amounts, however, - and print shows them, but they don't affect whether the assertion - passes or fails. This is for backward compatibility (hledger's close - command used to generate balance assertions with costs), and because + We do allow costs to be written in balance assertion amounts, however, + and print shows them, but they don't affect whether the assertion + passes or fails. This is for backward compatibility (hledger's close + command used to generate balance assertions with costs), and because balance assignments do use costs (see below). Assertions and commodities - The balance assertions described so far are "single commodity balance + The balance assertions described so far are "single commodity balance assertions": they assert and check the balance in one commodity, ignor- - ing any others that may be present. This is how balance assertions + ing any others that may be present. This is how balance assertions work in Ledger also. - If an account contains multiple commodities, you can assert their bal- - ances by writing multiple postings with balance assertions, one for + If an account contains multiple commodities, you can assert their bal- + ances by writing multiple postings with balance assertions, one for each commodity: 2013/1/1 @@ -1443,8 +1467,8 @@ Journal both 0 = $1 both 0 = 1 - In hledger you can make a stronger "sole commodity balance assertion" - by writing two equals signs (== EXPECTEDBALANCE). This also asserts + In hledger you can make a stronger "sole commodity balance assertion" + by writing two equals signs (== EXPECTEDBALANCE). This also asserts that there are no other commodities in the account besides the asserted one (or at least, that their current balance is zero): @@ -1454,12 +1478,12 @@ Journal both ;== $1 ; this one would fail because 'both' contains $ and It's less easy to make a "sole commodities balance assertion" (note the - plural) - ie, asserting that an account contains two or more specified + plural) - ie, asserting that an account contains two or more specified commodities and no others. It can be done by 1. isolating each commodity in a subaccount, and asserting those - 2. and also asserting there are no commodities in the parent account + 2. and also asserting there are no commodities in the parent account itself: 2013/1/1 @@ -1471,10 +1495,10 @@ Journal Assertions and subaccounts All of the balance assertions above (both = and ==) are "subaccount-ex- - clusive balance assertions"; they ignore any balances that exist in + clusive balance assertions"; they ignore any balances that exist in deeper subaccounts. - In hledger you can make "subaccount-inclusive balance assertions" by + In hledger you can make "subaccount-inclusive balance assertions" by adding a star after the equals (=* or ==*): 2019/1/1 @@ -1488,10 +1512,10 @@ Journal are not affected by the --real/-R flag or real: query. Assertions and auto postings - Balance assertions are affected by the --auto flag, which generates + Balance assertions are affected by the --auto flag, which generates auto postings, which can alter account balances. Because auto postings are optional in hledger, accounts affected by them effectively have two - balances. But balance assertions can only test one or the other of + balances. But balance assertions can only test one or the other of these. So to avoid making fragile assertions, either: o assert the balance calculated with --auto, and always use --auto with @@ -1504,15 +1528,15 @@ Journal avoid auto postings entirely). Assertions and precision - Balance assertions compare the exactly calculated amounts, which are - not always what is shown by reports. Eg a commodity directive may - limit the display precision, but this will not affect balance asser- + Balance assertions compare the exactly calculated amounts, which are + not always what is shown by reports. Eg a commodity directive may + limit the display precision, but this will not affect balance asser- tions. Balance assertion failure messages show exact amounts. Posting comments - Text following ;, at the end of a posting line, and/or on indented - lines immediately below it, form comments for that posting. They are - reproduced by print but otherwise ignored, except they may contain + Text following ;, at the end of a posting line, and/or on indented + lines immediately below it, form comments for that posting. They are + reproduced by print but otherwise ignored, except they may contain tags, which are not ignored. 2012-01-01 @@ -1522,55 +1546,55 @@ Journal ; a second comment line for posting 2 Transaction balancing - How exactly does hledger decide when a transaction is balanced ? The + How exactly does hledger decide when a transaction is balanced ? The general goal is that if you look at the journal entry and calculate the amounts' sum perfectly with pencil and paper, hledger should agree with you. - Real world transactions, especially for investments or cryptocurren- - cies, often involve imprecise costs, complex decimals, and/or infi- - nitely-recurring decimals, which are difficult or inconvenient to han- + Real world transactions, especially for investments or cryptocurren- + cies, often involve imprecise costs, complex decimals, and/or infi- + nitely-recurring decimals, which are difficult or inconvenient to han- dle on a computer. So to be a practical accounting system, hledger al- - lows some imprecision when checking transaction balancedness. The + lows some imprecision when checking transaction balancedness. The question is, how much imprecision should be allowed ? - hledger currently decides it based on the commodity display styles: if + hledger currently decides it based on the commodity display styles: if the postings' sum would appear to be zero when displayed with the stan- dard display precisions, the transaction is considered balanced. Or equivalently: if the journal entry is displayed with amounts rounded - to the standard display precisions (with hledger print --round=hard), - and a human with pencil and paper would agree that those displayed + to the standard display precisions (with hledger print --round=hard), + and a human with pencil and paper would agree that those displayed amounts add up to zero, the transaction is considered balanced. - This has some advantages: it is fairly intuitive, general not - hard-coded, yet configurable when needed. On the downside it means - that transaction balancedness is related to commodity display preci- - sions, so eg when using -c/--commodity-style to display things with - more than usual precision, you might need to fix some of your journal + This has some advantages: it is fairly intuitive, general not + hard-coded, yet configurable when needed. On the downside it means + that transaction balancedness is related to commodity display preci- + sions, so eg when using -c/--commodity-style to display things with + more than usual precision, you might need to fix some of your journal entries (ie, add decimal digits to make them balance more precisely). Other PTA tools (Ledger, Beancount..) have their own ways of doing it. Possible improvements are discussed at #1964. - Note: if you have multiple journal files, and are relying on commodity - directives to make imprecise journal entries balance, the directives' + Note: if you have multiple journal files, and are relying on commodity + directives to make imprecise journal entries balance, the directives' placement might be important - see commodity directive. Tags - Tags are a way to add extra labels or data fields to transactions, + Tags are a way to add extra labels or data fields to transactions, postings, or accounts, which you can then search or pivot on. - A tag is a word, optionally hyphenated, immediately followed by a full + A tag is a word, optionally hyphenated, immediately followed by a full colon, in the comment of a transaction, a posting, or an account direc- - tive. Eg: 2024-01-01 a transaction ; foo: Note this is an exception + tive. Eg: 2024-01-01 a transaction ; foo: Note this is an exception to the usual rule that things in comments are ignored. - You can write multiple tags on one line, separated by comma. Or you - can write each tag on its own comment line (no comma needed in this + You can write multiple tags on one line, separated by comma. Or you + can write each tag on its own comment line (no comma needed in this case). - For example, here are five different tags: one on the assets:checking + For example, here are five different tags: one on the assets:checking account, two on the transaction, and two on the expenses:food posting: account assets:checking ; accounttag: @@ -1580,15 +1604,15 @@ Journal assets:checking $-1 expenses:food $1 ; postingtag:, another-posting-tag: - Postings also inherit tags from their transaction and their account. - And transactions also acquire tags from their postings (and postings' - accounts). So in the example above, the expenses posting effectively + Postings also inherit tags from their transaction and their account. + And transactions also acquire tags from their postings (and postings' + accounts). So in the example above, the expenses posting effectively has all five tags (by inheriting from the account and transaction), and - the transaction also has all five tags (by acquiring from the expenses + the transaction also has all five tags (by acquiring from the expenses posting). Tag names - Most non-whitespace characters are allowed in tag names. Eg : is a + Most non-whitespace characters are allowed in tag names. Eg : is a valid tag. You can list the tag names used in your journal with the tags command: @@ -1597,13 +1621,13 @@ Journal In commands which use a query, you can match by tag name. Eg: hledger print tag:NAMEREGEX - You can declare valid tag names with the tag directive and then check + You can declare valid tag names with the tag directive and then check them with the check command. Special tags - Some tag names have special significance to hledger. There's not much - harm in using them yourself, but some could produce an error message, - particularly the date: and type: tags. They are explained elsewhere, + Some tag names have special significance to hledger. There's not much + harm in using them yourself, but some could produce an error message, + particularly the date: and type: tags. They are explained elsewhere, but here is a quick list for reference: Tags you can set to influence hledger's behaviour: @@ -1631,34 +1655,34 @@ Journal _conversion-matched -- exists on postings which have been matched with a nearby @/@@ cost annotation Tag values - Tags can have a value, which is any text after the colon up until a - comma or end of line, with surrounding whitespace removed. Ending at + Tags can have a value, which is any text after the colon up until a + comma or end of line, with surrounding whitespace removed. Ending at comma allows us to write multiple tags on one line, but also means that tag values can not contain commas. - Eg in the following posting, the three tags' values are "value 1", + Eg in the following posting, the three tags' values are "value 1", "value 2", and "" (empty) respectively: expenses:food $10 ; foo, tag1: value 1 , tag2:value 2, bar tag3: , baz - Multiple tags with the same name are additive rather than overriding: - when the same tag name is seen again with a new value, the new + Multiple tags with the same name are additive rather than overriding: + when the same tag name is seen again with a new value, the new name:value pair is added to the tags. It is not possible to override a previous tag's value or remove a tag. - You can list all the values used for a particular tag in the journal + You can list all the values used for a particular tag in the journal with hledger tags TAGNAME --values You can match on tag values with a query like tag:NAMEREGEX=VALUEREGEX Directives - Besides transactions, there is something else you can put in a journal - file: directives. These are declarations, beginning with a keyword, - that modify hledger's behaviour. Some directives can have more spe- - cific subdirectives, indented below them. hledger's directives are + Besides transactions, there is something else you can put in a journal + file: directives. These are declarations, beginning with a keyword, + that modify hledger's behaviour. Some directives can have more spe- + cific subdirectives, indented below them. hledger's directives are similar to Ledger's in many cases, but there are also many differences. - Directives are not required, but can be useful. Here are the main di- + Directives are not required, but can be useful. Here are the main di- rectives: purpose directive @@ -1666,16 +1690,16 @@ Journal READING DATA: Rewrite account names alias Comment out sections of the file comment - Declare file's decimal mark, to help decimal-mark + Declare file's decimal mark, to help decimal-mark parse amounts accurately Include other data files include GENERATING DATA: - Generate recurring transactions or bud- ~ + Generate recurring transactions or bud- ~ get goals - Generate extra postings on existing = + Generate extra postings on existing = transactions CHECKING FOR ERRORS: - Define valid entities to provide more account, commodity, payee, tag + Define valid entities to provide more account, commodity, payee, tag error checking REPORTING: Declare accounts' type and display order account @@ -1683,23 +1707,23 @@ Journal Declare market prices P Directives and multiple files - Directives vary in their scope, ie which journal entries and which in- + Directives vary in their scope, ie which journal entries and which in- put files they affect. Most often, a directive will affect the follow- - ing entries and included files if any, until the end of the current + ing entries and included files if any, until the end of the current file - and no further. You might find this inconvenient! For example, - alias directives do not affect parent or sibling files. But there are + alias directives do not affect parent or sibling files. But there are usually workarounds; for example, put alias directives in your top-most file, before including other files. - The restriction, though it may be annoying at first, is in a good + The restriction, though it may be annoying at first, is in a good cause; it allows reports to be stable and deterministic, independent of - the order of input. Without it, reports could show different numbers - depending on the order of -f options, or the positions of include di- + the order of input. Without it, reports could show different numbers + depending on the order of -f options, or the positions of include di- rectives in your files. Directive effects - Here are all hledger's directives, with their effects and scope sum- - marised - nine main directives, plus four others which we consider + Here are all hledger's directives, with their effects and scope sum- + marised - nine main directives, plus four others which we consider non-essential: di- what it does ends @@ -1707,53 +1731,53 @@ Journal tive file end? -------------------------------------------------------------------------------------- - ac- Declares an account, for checking all entries in all files; and N + ac- Declares an account, for checking all entries in all files; and N count its display order and type. Subdirectives: any text, ignored. - alias Rewrites account names, in following entries until end of cur- Y + alias Rewrites account names, in following entries until end of cur- Y rent file or end aliases. Command line equivalent: --alias - com- Ignores part of the journal file, until end of current file or Y + com- Ignores part of the journal file, until end of current file or Y ment end comment. com- Declares up to four things: 1. a commodity symbol, for checking N,N,Y,Y - mod- all amounts in all files 2. the display style for all amounts - ity of this commodity 3. the decimal mark for parsing amounts of - this commodity, in the rest of this file and its children, if - there is no decimal-mark directive 4. the precision to use for - balanced-transaction checking in this commodity, in this file - and its children. Takes precedence over D. Subdirectives: + mod- all amounts in all files 2. the display style for all amounts + ity of this commodity 3. the decimal mark for parsing amounts of + this commodity, in the rest of this file and its children, if + there is no decimal-mark directive 4. the precision to use for + balanced-transaction checking in this commodity, in this file + and its children. Takes precedence over D. Subdirectives: format (ignored). Command line equivalent: -c/--commodity-style - deci- Declares the decimal mark, for parsing amounts of all commodi- Y + deci- Declares the decimal mark, for parsing amounts of all commodi- Y mal-mark ties in following entries until next decimal-mark or end of cur- - rent file. Included files can override. Takes precedence over + rent file. Included files can override. Takes precedence over commodity and D. - include Includes entries and directives from another file, as if they N - were written inline. Command line alternative: multiple + include Includes entries and directives from another file, as if they N + were written inline. Command line alternative: multiple -f/--file payee Declares a payee name, for checking all entries in all files. N P Declares the market price of a commodity on some date, for value N reports. - ~ Declares a periodic transaction rule that generates future N - (tilde) transactions with --forecast and budget goals with balance + ~ Declares a periodic transaction rule that generates future N + (tilde) transactions with --forecast and budget goals with balance --budget. Other syntax: - apply Prepends a common parent account to all account names, in fol- Y + apply Prepends a common parent account to all account names, in fol- Y account lowing entries until end of current file or end apply account. - D Sets a default commodity to use for no-symbol amounts;and, if Y,Y,N,N - there is no commodity directive for this commodity: its decimal + D Sets a default commodity to use for no-symbol amounts;and, if Y,Y,N,N + there is no commodity directive for this commodity: its decimal mark, balancing precision, and display style, as above. - Y Sets a default year to use for any yearless dates, in following Y + Y Sets a default year to use for any yearless dates, in following Y entries until end of current file. - = Declares an auto posting rule that generates extra postings on partly - (equals) matched transactions with --auto, in current, parent, and child + = Declares an auto posting rule that generates extra postings on partly + (equals) matched transactions with --auto, in current, parent, and child files (but not sibling files, see #1212). - Other Other directives from Ledger's file format are accepted but ig- + Other Other directives from Ledger's file format are accepted but ig- Ledger nored. direc- tives account directive account directives can be used to declare accounts (ie, the places that - amounts are transferred from and to). Though not required, these dec- + amounts are transferred from and to). Though not required, these dec- larations can provide several benefits: o They can document your intended chart of accounts, providing a refer- @@ -1765,17 +1789,17 @@ Journal o They can restrict which accounts may be posted to by transactions, eg in strict mode, which helps prevent errors. - o They influence account display order in reports, allowing non-alpha- + o They influence account display order in reports, allowing non-alpha- betic sorting (eg Revenues to appear above Expenses). - o They can help hledger know your accounts' types (asset, liability, + o They can help hledger know your accounts' types (asset, liability, equity, revenue, expense), enabling reports like balancesheet and in- comestatement. - o They help with account name completion (in hledger add, hledger-web, + o They help with account name completion (in hledger add, hledger-web, hledger-iadd, ledger-mode, etc.) - They are written as the word account followed by a hledger-style ac- + They are written as the word account followed by a hledger-style ac- count name. Eg: account assets:bank:checking @@ -1787,11 +1811,11 @@ Journal Account comments Text following two or more spaces and ; at the end of an account direc- - tive line, and/or following ; on indented lines immediately below it, - form comments for that account. They are ignored except they may con- + tive line, and/or following ; on indented lines immediately below it, + form comments for that account. They are ignored except they may con- tain tags, which are not ignored. - The two-space requirement for same-line account comments is because ; + The two-space requirement for same-line account comments is because ; is allowed in account names. account assets:bank:checking ; same-line comment, at least 2 spaces before the semicolon @@ -1799,34 +1823,34 @@ Journal ; some tags - type:A, acctnum:12345 Account error checking - By default, accounts need not be declared; they come into existence - when a posting references them. This is convenient, but it means - hledger can't warn you when you mis-spell an account name in the jour- + By default, accounts need not be declared; they come into existence + when a posting references them. This is convenient, but it means + hledger can't warn you when you mis-spell an account name in the jour- nal. Usually you'll find that error later, as an extra account in bal- ance reports, or an incorrect balance when reconciling. - In strict mode, enabled with the -s/--strict flag, hledger will report - an error if any transaction uses an account name that has not been de- + In strict mode, enabled with the -s/--strict flag, hledger will report + an error if any transaction uses an account name that has not been de- clared by an account directive. Some notes: - o The declaration is case-sensitive; transactions must use the correct + o The declaration is case-sensitive; transactions must use the correct account name capitalisation. - o The account directive's scope is "whole file and below" (see direc- + o The account directive's scope is "whole file and below" (see direc- tives). This means it affects all of the current file, and any files - it includes, but not parent or sibling files. The position of ac- - count directives within the file does not matter, though it's usual + it includes, but not parent or sibling files. The position of ac- + count directives within the file does not matter, though it's usual to put them at the top. - o Accounts can only be declared in journal files, but will affect in- + o Accounts can only be declared in journal files, but will affect in- cluded files of all types. - o It's currently not possible to declare "all possible subaccounts" + o It's currently not possible to declare "all possible subaccounts" with a wildcard; every account posted to must be declared. Account display order Account directives also cause hledger to display accounts in a particu- - lar order, not just alphabetically. Eg, here is a conventional order- + lar order, not just alphabetically. Eg, here is a conventional order- ing for the top-level accounts: account assets @@ -1844,42 +1868,42 @@ Journal revenues expenses - If there are undeclared accounts, those will be displayed last, in al- + If there are undeclared accounts, those will be displayed last, in al- phabetical order. Sorting is done within each group of sibling accounts, at each level of - the account tree. Eg, a declaration like account parent:child influ- + the account tree. Eg, a declaration like account parent:child influ- ences child's position among its siblings. - Note, it does not affect parent's position; for that, you need an ac- + Note, it does not affect parent's position; for that, you need an ac- count parent declaration. - Sibling accounts are always displayed together; hledger won't display + Sibling accounts are always displayed together; hledger won't display x:y in between a:b and a:c. - An account directive both declares an account as a valid posting tar- - get, and declares its display order; you can't easily do one without + An account directive both declares an account as a valid posting tar- + get, and declares its display order; you can't easily do one without the other. Account types hledger knows that accounts come in several types: assets, liabilities, - expenses and so on. This enables easy reports like balancesheet and + expenses and so on. This enables easy reports like balancesheet and incomestatement, and filtering by account type with the type: query. As a convenience, hledger will detect these account types automatically - if you are using common english-language top-level account names (de- - scribed below). But it's more robust to declare accounts' types ex- - plicitly, by adding type: tags to their account directives. The tag's + if you are using common english-language top-level account names (de- + scribed below). But it's more robust to declare accounts' types ex- + plicitly, by adding type: tags to their account directives. The tag's value should be one of the five main account types: o A or Asset (things you own) o L or Liability (things you owe) - o E or Equity (investment/ownership; balanced counterpart of assets & + o E or Equity (investment/ownership; balanced counterpart of assets & liabilities) - o R or Revenue (what you received money from, AKA income; technically + o R or Revenue (what you received money from, AKA income; technically part of Equity) o X or Expense (what you spend money on; technically part of Equity) @@ -1889,7 +1913,7 @@ Journal o C or Cash (a subtype of Asset, indicating liquid assets for the cash- flow report) - o V or Conversion (a subtype of Equity, for conversions (see Cost re- + o V or Conversion (a subtype of Equity, for conversions (see Cost re- porting).) Subaccounts inherit their parent's type, or they can override it. Here @@ -1908,7 +1932,7 @@ Journal Here are some tips for working with account types. - o The rules for inferring types from account names are as follows. + o The rules for inferring types from account names are as follows. These are just a convenience that sometimes help new users get going; if they don't work for you, just ignore them and declare your account types. See also Regular expressions. @@ -1923,25 +1947,25 @@ Journal ^(income|revenue)s?(:|$) | Revenue ^expenses?(:|$) | Expense - o If you declare any account types, it's a good idea to declare an ac- + o If you declare any account types, it's a good idea to declare an ac- count for all of the account types, because a mixture of declared and name-inferred types can disrupt certain reports. - o Certain uses of account aliases can disrupt account types. See + o Certain uses of account aliases can disrupt account types. See Rewriting accounts > Aliases and account types. o As mentioned above, subaccounts will inherit a type from their parent - account. More precisely, an account's type is decided by the first + account. More precisely, an account's type is decided by the first of these that exists: 1. A type: declaration for this account. - 2. A type: declaration in the parent accounts above it, preferring + 2. A type: declaration in the parent accounts above it, preferring the nearest. 3. An account type inferred from this account's name. - 4. An account type inferred from a parent account's name, preferring + 4. An account type inferred from a parent account's name, preferring the nearest parent. 5. Otherwise, it will have no type. @@ -1967,7 +1991,7 @@ Journal o customising reports Account aliases also rewrite account names in account directives. They - do not affect account names being entered via hledger add or + do not affect account names being entered via hledger add or hledger-web. Account aliases are very powerful. They are generally easy to use cor- @@ -1977,9 +2001,9 @@ Journal See also Rewrite account names. Basic aliases - To set an account alias, use the alias directive in your journal file. - This affects all subsequent journal entries in the current file or its - included files (but note: not sibling or parent files). The spaces + To set an account alias, use the alias directive in your journal file. + This affects all subsequent journal entries in the current file or its + included files (but note: not sibling or parent files). The spaces around the = are optional: alias OLD = NEW @@ -1987,17 +2011,17 @@ Journal Or, you can use the --alias 'OLD=NEW' option on the command line. This affects all entries. It's useful for trying out aliases interactively. - OLD and NEW are case sensitive full account names. hledger will re- - place any occurrence of the old account name with the new one. Subac- + OLD and NEW are case sensitive full account names. hledger will re- + place any occurrence of the old account name with the new one. Subac- counts are also affected. Eg: alias checking = assets:bank:wells fargo:checking ; rewrites "checking" to "assets:bank:wells fargo:checking", or "checking:a" to "assets:bank:wells fargo:checking:a" Regex aliases - There is also a more powerful variant that uses a regular expression, - indicated by wrapping the pattern in forward slashes. (This is the - only place where hledger requires forward slashes around a regular ex- + There is also a more powerful variant that uses a regular expression, + indicated by wrapping the pattern in forward slashes. (This is the + only place where hledger requires forward slashes around a regular ex- pression.) Eg: @@ -2008,13 +2032,13 @@ Journal $ hledger --alias '/REGEX/=REPLACEMENT' ... - Any part of an account name matched by REGEX will be replaced by RE- + Any part of an account name matched by REGEX will be replaced by RE- PLACEMENT. REGEX is case-insensitive as usual. - If you need to match a forward slash, escape it with a backslash, eg + If you need to match a forward slash, escape it with a backslash, eg /\/=:. - If REGEX contains parenthesised match groups, these can be referenced + If REGEX contains parenthesised match groups, these can be referenced by the usual backslash and number in REPLACEMENT: alias /^(.+):bank:([^:]+):(.*)/ = \1:\2 \3 @@ -2024,21 +2048,21 @@ Journal option argument), so it can contain trailing whitespace. Combining aliases - You can define as many aliases as you like, using journal directives + You can define as many aliases as you like, using journal directives and/or command line options. - Recursive aliases - where an account name is rewritten by one alias, - then by another alias, and so on - are allowed. Each alias sees the + Recursive aliases - where an account name is rewritten by one alias, + then by another alias, and so on - are allowed. Each alias sees the effect of previously applied aliases. - In such cases it can be important to understand which aliases will be - applied and in which order. For (each account name in) each journal + In such cases it can be important to understand which aliases will be + applied and in which order. For (each account name in) each journal entry, we apply: - 1. alias directives preceding the journal entry, most recently parsed + 1. alias directives preceding the journal entry, most recently parsed first (ie, reading upward from the journal entry, bottom to top) - 2. --alias options, in the order they appeared on the command line + 2. --alias options, in the order they appeared on the command line (left to right). In other words, for (an account name in) a given journal entry: @@ -2049,20 +2073,20 @@ Journal o aliases defined after/below the entry do not affect it. - This gives nearby aliases precedence over distant ones, and helps pro- - vide semantic stability - aliases will keep working the same way inde- + This gives nearby aliases precedence over distant ones, and helps pro- + vide semantic stability - aliases will keep working the same way inde- pendent of which files are being read and in which order. - In case of trouble, adding --debug=6 to the command line will show + In case of trouble, adding --debug=6 to the command line will show which aliases are being applied when. Aliases and multiple files - As explained at Directives and multiple files, alias directives do not + As explained at Directives and multiple files, alias directives do not affect parent or sibling files. Eg in this command, hledger -f a.aliases -f b.journal - account aliases defined in a.aliases will not affect b.journal. In- + account aliases defined in a.aliases will not affect b.journal. In- cluding the aliases doesn't work either: include a.aliases @@ -2090,7 +2114,7 @@ Journal end aliases Aliases can generate bad account names - Be aware that account aliases can produce malformed account names, + Be aware that account aliases can produce malformed account names, which could cause confusing reports or invalid print output. For exam- ple, you could erase all account names: @@ -2102,8 +2126,8 @@ Journal 2021-01-01 1 - The above print output is not a valid journal. Or you could insert an - illegal double space, causing print output that would give a different + The above print output is not a valid journal. Or you could insert an + illegal double space, causing print output that would give a different journal when reparsed: 2021-01-01 @@ -2120,15 +2144,15 @@ Journal types) is renamed by an alias, normally the account type remains in ef- fect. - However, renaming in a way that reshapes the account tree (eg renaming - parent accounts but not their children, or vice versa) could prevent + However, renaming in a way that reshapes the account tree (eg renaming + parent accounts but not their children, or vice versa) could prevent child accounts from inheriting the account type of their parents. - Secondly, if an account's type is being inferred from its name, renam- + Secondly, if an account's type is being inferred from its name, renam- ing it by an alias could prevent or alter that. - If you are using account aliases and the type: query is not matching - accounts as you expect, try troubleshooting with the accounts command, + If you are using account aliases and the type: query is not matching + accounts as you expect, try troubleshooting with the accounts command, eg something like: $ hledger accounts --alias assets=bassetts type:a @@ -2136,37 +2160,37 @@ Journal commodity directive The commodity directive performs several functions: - 1. It declares which commodity symbols may be used in the journal, en- - abling useful error checking with strict mode or the check command. + 1. It declares which commodity symbols may be used in the journal, en- + abling useful error checking with strict mode or the check command. See Commodity error checking below. - 2. It declares how all amounts in this commodity should be displayed, + 2. It declares how all amounts in this commodity should be displayed, eg how many decimals to show. See Commodity display style above. - 3. (If no decimal-mark directive is in effect:) It sets the decimal - mark to expect (period or comma) when parsing amounts in this com- + 3. (If no decimal-mark directive is in effect:) It sets the decimal + mark to expect (period or comma) when parsing amounts in this com- modity, in this file and files it includes, from the directive until end of current file. See Decimal marks above. 4. It declares the precision with which this commodity's amounts should - be compared when checking for balanced transactions, anywhere in + be compared when checking for balanced transactions, anywhere in this file and files it includes, until end of current file. - Declaring commodities solves several common parsing/display problems, + Declaring commodities solves several common parsing/display problems, so we recommend it. Note that effects 3 and 4 above end at the end of the directive's file, - and will not affect sibling or parent files. So if you are relying on - them (especially 4) and using multiple files, placing your commodity - directives in a top-level parent file might be important. Or, keep - your decimal marks unambiguous and your entries well balanced and pre- + and will not affect sibling or parent files. So if you are relying on + them (especially 4) and using multiple files, placing your commodity + directives in a top-level parent file might be important. Or, keep + your decimal marks unambiguous and your entries well balanced and pre- cise. (Related: #793) Commodity directive syntax A commodity directive is normally the word commodity followed by a sam- - ple amount (and optionally a comment). Only the amount's symbol and + ple amount (and optionally a comment). Only the amount's symbol and format is significant. Eg: commodity $1000.00 @@ -2175,19 +2199,19 @@ Journal Commodities do not have tags (tags in the comment will be ignored). - A commodity directive's sample amount must always include a period or - comma decimal mark (this rule helps disambiguate decimal marks and - digit group marks). If you don't want to show any decimal digits, + A commodity directive's sample amount must always include a period or + comma decimal mark (this rule helps disambiguate decimal marks and + digit group marks). If you don't want to show any decimal digits, write the decimal mark at the end: commodity 1000. AAAA ; show AAAA with no decimals - Commodity symbols containing spaces, numbers, or punctuation must be + Commodity symbols containing spaces, numbers, or punctuation must be enclosed in double quotes, as usual: commodity 1.0000 "AAAA 2023" - Commodity directives normally include a sample amount, but can declare + Commodity directives normally include a sample amount, but can declare only a symbol (ie, just function 1 above): commodity $ @@ -2196,7 +2220,7 @@ Journal commodity "" ; the no-symbol commodity Commodity directives may also be written with an indented format subdi- - rective, as in Ledger. The symbol is repeated and must be the same in + rective, as in Ledger. The symbol is repeated and must be the same in both places. Other subdirectives are currently ignored: ; display indian rupees with currency name on the left, @@ -2207,10 +2231,10 @@ Journal an unsupported subdirective ; ignored by hledger Commodity error checking - In strict mode (-s/--strict) (or when you run hledger check commodi- - ties), hledger will report an error if an undeclared commodity symbol - is used. (With one exception: zero amounts are always allowed to have - no commodity symbol.) It works like account error checking (described + In strict mode (-s/--strict) (or when you run hledger check commodi- + ties), hledger will report an error if an undeclared commodity symbol + is used. (With one exception: zero amounts are always allowed to have + no commodity symbol.) It works like account error checking (described above). decimal-mark directive @@ -2224,20 +2248,20 @@ Journal decimal-mark , - This prevents any ambiguity when parsing numbers in the file, so we - recommend it, especially if the file contains digit group marks (eg + This prevents any ambiguity when parsing numbers in the file, so we + recommend it, especially if the file contains digit group marks (eg thousands separators). include directive - You can pull in the content of additional files by writing an include + You can pull in the content of additional files by writing an include directive, like this: include FILEPATH - Only journal files can include, and only journal, timeclock or timedot + Only journal files can include, and only journal, timeclock or timedot files can be included (not CSV files, currently). - If the file path does not begin with a slash, it is relative to the + If the file path does not begin with a slash, it is relative to the current file's folder. A tilde means home directory, eg: include ~/main.journal. @@ -2246,27 +2270,27 @@ Journal *.journal. There is limited support for recursive wildcards: **/ (the slash is re- - quired) matches 0 or more subdirectories. It's not super convenient - since you have to avoid include cycles and including directories, but + quired) matches 0 or more subdirectories. It's not super convenient + since you have to avoid include cycles and including directories, but this can be done, eg: include */**/*.journal. The path may also be prefixed to force a specific file format, overrid- - ing the file extension (as described in Data formats): include time- + ing the file extension (as described in Data formats): include time- dot:~/notes/2023*.md. P directive The P directive declares a market price, which is a conversion rate be- - tween two commodities on a certain date. This allows value reports to + tween two commodities on a certain date. This allows value reports to convert amounts of one commodity to their value in another, on or after - that date. These prices are often obtained from a stock exchange, + that date. These prices are often obtained from a stock exchange, cryptocurrency exchange, the or foreign exchange market. The format is: P DATE COMMODITY1SYMBOL COMMODITY2AMOUNT - DATE is a simple date, COMMODITY1SYMBOL is the symbol of the commodity - being priced, and COMMODITY2AMOUNT is the amount (symbol and quantity) + DATE is a simple date, COMMODITY1SYMBOL is the symbol of the commodity + being priced, and COMMODITY2AMOUNT is the amount (symbol and quantity) of commodity 2 that one unit of commodity 1 is worth on this date. Ex- amples: @@ -2276,15 +2300,15 @@ Journal # and $1.40 from 2010-01-01 onward: P 2010-01-01 $1.40 - The -V, -X and --value flags use these market prices to show amount + The -V, -X and --value flags use these market prices to show amount values in another commodity. See Value reporting. payee directive payee PAYEE NAME This directive can be used to declare a limited set of payees which may - appear in transaction descriptions. The "payees" check will report an - error if any transaction refers to a payee that has not been declared. + appear in transaction descriptions. The "payees" check will report an + error if any transaction refers to a payee that has not been declared. Eg: payee Whole Foods ; a comment @@ -2300,58 +2324,58 @@ Journal tag directive tag TAGNAME - This directive can be used to declare a limited set of tag names al- + This directive can be used to declare a limited set of tag names al- lowed in tags. TAGNAME should be a valid tag name (no spaces). Eg: tag item-id Any indented subdirectives are currently ignored. - The "tags" check will report an error if any undeclared tag name is + The "tags" check will report an error if any undeclared tag name is used. It is quite easy to accidentally create a tag through normal use of colons in comments; if you want to prevent this, you can declare and check your tags . Periodic transactions - The ~ directive declares a "periodic rule" which generates temporary + The ~ directive declares a "periodic rule" which generates temporary extra transactions, usually recurring at some interval, when hledger is run with the --forecast flag. These "forecast transactions" are useful - for forecasting future activity. They exist only for the duration of + for forecasting future activity. They exist only for the duration of the report, and only when --forecast is used; they are not saved in the journal file by hledger. - Periodic rules also have a second use: with the --budget flag they set + Periodic rules also have a second use: with the --budget flag they set budget goals for budgeting. - Periodic rules can be a little tricky, so before you use them, read + Periodic rules can be a little tricky, so before you use them, read this whole section, or at least the following tips: - 1. Two spaces accidentally added or omitted will cause you trouble - + 1. Two spaces accidentally added or omitted will cause you trouble - read about this below. - 2. For troubleshooting, show the generated transactions with hledger - print --forecast tag:generated or hledger register --forecast + 2. For troubleshooting, show the generated transactions with hledger + print --forecast tag:generated or hledger register --forecast tag:generated. - 3. Forecasted transactions will begin only after the last non-fore- + 3. Forecasted transactions will begin only after the last non-fore- casted transaction's date. - 4. Forecasted transactions will end 6 months from today, by default. + 4. Forecasted transactions will end 6 months from today, by default. See below for the exact start/end rules. - 5. period expressions can be tricky. Their documentation needs im- + 5. period expressions can be tricky. Their documentation needs im- provement, but is worth studying. - 6. Some period expressions with a repeating interval must begin on a - natural boundary of that interval. Eg in weekly from DATE, DATE - must be a monday. ~ weekly from 2019/10/1 (a tuesday) will give an + 6. Some period expressions with a repeating interval must begin on a + natural boundary of that interval. Eg in weekly from DATE, DATE + must be a monday. ~ weekly from 2019/10/1 (a tuesday) will give an error. 7. Other period expressions with an interval are automatically expanded - to cover a whole number of that interval. (This is done to improve + to cover a whole number of that interval. (This is done to improve reports, but it also affects periodic transactions. Yes, it's a bit - inconsistent with the above.) Eg: ~ every 10th day of month from - 2023/01, which is equivalent to ~ every 10th day of month from + inconsistent with the above.) Eg: ~ every 10th day of month from + 2023/01, which is equivalent to ~ every 10th day of month from 2023/01/01, will be adjusted to start on 2019/12/10. Periodic rule syntax @@ -2369,14 +2393,14 @@ Journal expenses:utilities $400 assets:bank:checking - The period expression is the same syntax used for specifying multi-pe- - riod reports, just interpreted differently; there, it specifies report + The period expression is the same syntax used for specifying multi-pe- + riod reports, just interpreted differently; there, it specifies report periods; here it specifies recurrence dates (the periods' start dates). Periodic rules and relative dates - Partial or relative dates (like 12/31, 25, tomorrow, last week, next - quarter) are usually not recommended in periodic rules, since the re- - sults will change as time passes. If used, they will be interpreted + Partial or relative dates (like 12/31, 25, tomorrow, last week, next + quarter) are usually not recommended in periodic rules, since the re- + sults will change as time passes. If used, they will be interpreted relative to, in order of preference: 1. the first day of the default year specified by a recent Y directive @@ -2385,11 +2409,11 @@ Journal 3. or the date on which you are running the report. - They will not be affected at all by report period or forecast period + They will not be affected at all by report period or forecast period dates. Two spaces between period expression and description! - If the period expression is followed by a transaction description, + If the period expression is followed by a transaction description, these must be separated by two or more spaces. This helps hledger know where the period expression ends, so that descriptions can not acciden- tally alter their meaning, as in this example: @@ -2403,51 +2427,51 @@ Journal So, - o Do write two spaces between your period expression and your transac- + o Do write two spaces between your period expression and your transac- tion description, if any. - o Don't accidentally write two spaces in the middle of your period ex- + o Don't accidentally write two spaces in the middle of your period ex- pression. Auto postings The = directive declares an "auto posting rule", which adds extra post- - ings to existing transactions. (Remember, postings are the account + ings to existing transactions. (Remember, postings are the account name & amount lines below a transaction's date & description.) - In the journal, an auto posting rule looks quite like a transaction, - but instead of date and description it has = (mnemonic: "match") and a + In the journal, an auto posting rule looks quite like a transaction, + but instead of date and description it has = (mnemonic: "match") and a query, like this: = QUERY ACCOUNT AMOUNT ... - Queries are just like command line queries; an account name substring - is most common. Query terms containing spaces should be enclosed in + Queries are just like command line queries; an account name substring + is most common. Query terms containing spaces should be enclosed in single or double quotes. - Each = rule works like this: when hledger is run with the --auto flag, - wherever the QUERY matches a posting in the journal, the rule's post- + Each = rule works like this: when hledger is run with the --auto flag, + wherever the QUERY matches a posting in the journal, the rule's post- ings are added to that transaction, immediately below the matched post- - ing. Note these generated postings are temporary, existing only for - the duration of the report, and only when --auto is used; they are not + ing. Note these generated postings are temporary, existing only for + the duration of the report, and only when --auto is used; they are not saved in the journal file by hledger. Generated postings' amounts can depend on the matched posting's amount. - So auto postings can be useful for, eg, adding tax postings with a + So auto postings can be useful for, eg, adding tax postings with a standard percentage. AMOUNT can be: - o a number with no commodity symbol, like 2. The matched posting's + o a number with no commodity symbol, like 2. The matched posting's commodity symbol will be added to this. - o a normal amount with a commodity symbol, like $2. This will be used + o a normal amount with a commodity symbol, like $2. This will be used as-is. - o an asterisk followed by a number, like *2. This will multiply the + o an asterisk followed by a number, like *2. This will multiply the matched posting's amount (and total price, if any) by the number. - o an asterisk followed by an amount with commodity symbol, like *$2. - This multiplies and also replaces the commodity symbol with this new + o an asterisk followed by an amount with commodity symbol, like *$2. + This multiplies and also replaces the commodity symbol with this new one. Some examples: @@ -2482,38 +2506,38 @@ Journal assets:checking $20 Note that depending fully on generated data such as this has some draw- - backs - it's less portable, less future-proof, less auditable by oth- + backs - it's less portable, less future-proof, less auditable by oth- ers, and less robust (eg your balance assertions will depend on whether - you use or don't use --auto). An alternative is to use auto postings + you use or don't use --auto). An alternative is to use auto postings in "one time" fashion - use them to help build a complex journal entry, - view it with hledger print --auto, and then copy that output into the + view it with hledger print --auto, and then copy that output into the journal file to make it permanent. Auto postings and multiple files An auto posting rule can affect any transaction in the current file, or - in any parent file or child file. Note, currently it will not affect + in any parent file or child file. Note, currently it will not affect sibling files (when multiple -f/--file are used - see #1212). Auto postings and dates - A posting date (or secondary date) in the matched posting, or (taking - precedence) a posting date in the auto posting rule itself, will also + A posting date (or secondary date) in the matched posting, or (taking + precedence) a posting date in the auto posting rule itself, will also be used in the generated posting. Auto postings and transaction balancing / inferred amounts / balance asser- tions Currently, auto postings are added: - o after missing amounts are inferred, and transactions are checked for + o after missing amounts are inferred, and transactions are checked for balancedness, o but before balance assertions are checked. - Note this means that journal entries must be balanced both before and + Note this means that journal entries must be balanced both before and after auto postings are added. This changed in hledger 1.12+; see #893 for background. - This also means that you cannot have more than one auto-posting with a - missing amount applied to a given transaction, as it will be unable to + This also means that you cannot have more than one auto-posting with a + missing amount applied to a given transaction, as it will be unable to infer amounts. Auto posting tags @@ -2522,11 +2546,11 @@ Journal o generated-posting:= QUERY - shows this was generated by an auto post- ing rule, and the query - o _generated-posting:= QUERY - a hidden tag, which does not appear in + o _generated-posting:= QUERY - a hidden tag, which does not appear in hledger's output. This can be used to match postings generated "just now", rather than generated in the past and saved to the journal. - Also, any transaction that has been changed by auto posting rules will + Also, any transaction that has been changed by auto posting rules will have these tags added: o modified: - this transaction was modified @@ -2535,24 +2559,24 @@ Journal tion was modified "just now". Auto postings on forecast transactions only - Tip: you can can make auto postings that will apply to forecast trans- - actions but not recorded transactions, by adding tag:_generated-trans- - action to their QUERY. This can be useful when generating new journal + Tip: you can can make auto postings that will apply to forecast trans- + actions but not recorded transactions, by adding tag:_generated-trans- + action to their QUERY. This can be useful when generating new journal entries to be saved in the journal. Other syntax - hledger journal format supports quite a few other features, mainly to - make interoperating with or converting from Ledger easier. Note some - of the features below are powerful and can be useful in special cases, - but in general, features in this section are considered less important - or even not recommended for most users. Downsides are mentioned to + hledger journal format supports quite a few other features, mainly to + make interoperating with or converting from Ledger easier. Note some + of the features below are powerful and can be useful in special cases, + but in general, features in this section are considered less important + or even not recommended for most users. Downsides are mentioned to help you decide if you want to use them. Balance assignments - Ledger-style balance assignments are also supported. These are like - balance assertions, but with no posting amount on the left side of the - equals sign; instead it is calculated automatically so as to satisfy - the assertion. This can be a convenience during data entry, eg when + Ledger-style balance assignments are also supported. These are like + balance assertions, but with no posting amount on the left side of the + equals sign; instead it is calculated automatically so as to satisfy + the assertion. This can be a convenience during data entry, eg when setting opening balances: ; starting a new journal, set asset account balances @@ -2570,15 +2594,15 @@ Journal expenses:misc The calculated amount depends on the account's balance in the commodity - at that point (which depends on the previously-dated postings of the - commodity to that account since the last balance assertion or assign- + at that point (which depends on the previously-dated postings of the + commodity to that account since the last balance assertion or assign- ment). - Downsides: using balance assignments makes your journal less explicit; + Downsides: using balance assignments makes your journal less explicit; to know the exact amount posted, you have to run hledger or do the cal- - culations yourself, instead of just reading it. Also balance assign- + culations yourself, instead of just reading it. Also balance assign- ments' forcing of balances can hide errors. These things make your fi- - nancial data less portable, less future-proof, and less trustworthy in + nancial data less portable, less future-proof, and less trustworthy in an audit. Balance assignments and costs @@ -2593,31 +2617,31 @@ Journal (a) $1 @ 2 = $1 @ 2 Balance assignments and multiple files - Balance assignments handle multiple files like balance assertions. - They see balance from other files previously included from the current + Balance assignments handle multiple files like balance assertions. + They see balance from other files previously included from the current file, but not from previous sibling or parent files. Bracketed posting dates - For setting posting dates and secondary posting dates, Ledger's brack- + For setting posting dates and secondary posting dates, Ledger's brack- eted date syntax is also supported: [DATE], [DATE=DATE2] or [=DATE2] in - posting comments. hledger will attempt to parse any square-bracketed - sequence of the 0123456789/-.= characters in this way. With this syn- - tax, DATE infers its year from the transaction and DATE2 infers its + posting comments. hledger will attempt to parse any square-bracketed + sequence of the 0123456789/-.= characters in this way. With this syn- + tax, DATE infers its year from the transaction and DATE2 infers its year from DATE. - Downsides: another syntax to learn, redundant with hledger's + Downsides: another syntax to learn, redundant with hledger's date:/date2: tags, and confusingly similar to Ledger's lot date syntax. D directive D AMOUNT - This directive sets a default commodity, to be used for any subsequent - commodityless amounts (ie, plain numbers) seen while parsing the jour- - nal. This effect lasts until the next D directive, or the end of the + This directive sets a default commodity, to be used for any subsequent + commodityless amounts (ie, plain numbers) seen while parsing the jour- + nal. This effect lasts until the next D directive, or the end of the current file. - For compatibility/historical reasons, D also acts like a commodity di- - rective (setting the commodity's decimal mark for parsing and display + For compatibility/historical reasons, D also acts like a commodity di- + rective (setting the commodity's decimal mark for parsing and display style for output). So its argument is not just a commodity symbol, but a full amount demonstrating the style. The amount must include a deci- mal mark (either period or comma). Eg: @@ -2632,23 +2656,23 @@ Journal Interactions with other directives: - For setting a commodity's display style, a commodity directive has + For setting a commodity's display style, a commodity directive has highest priority, then a D directive. - For detecting a commodity's decimal mark during parsing, decimal-mark + For detecting a commodity's decimal mark during parsing, decimal-mark has highest priority, then commodity, then D. - For checking commodity symbols with the check command, a commodity di- + For checking commodity symbols with the check command, a commodity di- rective is required (hledger check commodities ignores D directives). - Downsides: omitting commodity symbols makes your financial data less - explicit, less portable, and less trustworthy in an audit. It is usu- - ally an unsustainable shortcut; sooner or later you will want to track - multiple commodities. D is overloaded with functions redundant with + Downsides: omitting commodity symbols makes your financial data less + explicit, less portable, and less trustworthy in an audit. It is usu- + ally an unsustainable shortcut; sooner or later you will want to track + multiple commodities. D is overloaded with functions redundant with commodity and decimal-mark. And it works differently from Ledger's D. apply account directive - This directive sets a default parent account, which will be prepended + This directive sets a default parent account, which will be prepended to all accounts in following entries, until an end apply account direc- tive or end of current file. Eg: @@ -2670,10 +2694,10 @@ Journal Account names entered via hledger add or hledger-web are not affected. - Account aliases, if any, are applied after the parent account is + Account aliases, if any, are applied after the parent account is prepended. - Downsides: this can make your financial data less explicit, less + Downsides: this can make your financial data less explicit, less portable, and less trustworthy in an audit. Y directive @@ -2683,7 +2707,7 @@ Journal year YEAR apply year YEAR - The space is optional. This sets a default year to be used for subse- + The space is optional. This sets a default year to be used for subse- quent dates which don't specify a year. Eg: Y2009 ; set default year to 2009 @@ -2704,38 +2728,38 @@ Journal Downsides: omitting the year (from primary transaction dates, at least) makes your financial data less explicit, less portable, and less trust- - worthy in an audit. Such dates can get separated from their corre- - sponding Y directive, eg when evaluating a region of the journal in - your editor. A missing Y directive makes reports dependent on today's + worthy in an audit. Such dates can get separated from their corre- + sponding Y directive, eg when evaluating a region of the journal in + your editor. A missing Y directive makes reports dependent on today's date. Secondary dates A secondary date is written after the primary date, following an equals - sign: DATE1=DATE2. If the year is omitted, the primary date's year is + sign: DATE1=DATE2. If the year is omitted, the primary date's year is assumed. When running reports, the primary (left side) date is used by default, but with the --date2 flag (--aux-date or--effective also work, - for Ledger users), the secondary (right side) date will be used in- + for Ledger users), the secondary (right side) date will be used in- stead. - The meaning of secondary dates is up to you. Eg it could be "primary - is the bank's clearing date, secondary is the date the transaction was + The meaning of secondary dates is up to you. Eg it could be "primary + is the bank's clearing date, secondary is the date the transaction was initiated, if different". In practice, this feature usually adds confusion: - o You have to remember the primary and secondary dates' meaning, and + o You have to remember the primary and secondary dates' meaning, and follow that consistently. - o It splits your bookkeeping into two modes, and you have to remember + o It splits your bookkeeping into two modes, and you have to remember which mode is appropriate for a given report. - o Usually your balance assertions will work with only one of these + o Usually your balance assertions will work with only one of these modes. - o It makes your financial data more complicated, less portable, and + o It makes your financial data more complicated, less portable, and less clear in an audit. - o It interacts with every feature, creating an ongoing cost for imple- + o It interacts with every feature, creating an ongoing cost for imple- mentors. o It distracts new users and supporters. @@ -2743,38 +2767,38 @@ Journal o Posting dates are simpler and work better. So secondary dates are officially deprecated in hledger, remaining only - as a Ledger compatibility aid; we recommend using posting dates in- + as a Ledger compatibility aid; we recommend using posting dates in- stead. Star comments - Lines beginning with * (star/asterisk) are also comment lines. This + Lines beginning with * (star/asterisk) are also comment lines. This feature allows Emacs users to insert org headings in their journal, al- lowing them to fold/unfold/navigate it like an outline when viewed with org mode. - Downsides: another, unconventional comment syntax to learn. Decreases - your journal's portability. And switching to Emacs org mode just for - folding/unfolding meant losing the benefits of ledger mode; nowadays - you can add outshine mode to ledger mode to get folding without losing + Downsides: another, unconventional comment syntax to learn. Decreases + your journal's portability. And switching to Emacs org mode just for + folding/unfolding meant losing the benefits of ledger mode; nowadays + you can add outshine mode to ledger mode to get folding without losing ledger mode's features. Valuation expressions - Ledger allows a valuation function or value to be written in double + Ledger allows a valuation function or value to be written in double parentheses after an amount. hledger ignores these. Virtual postings A posting with parentheses around the account name, like (some:account) - 10, is called an unbalanced virtual posting. These postings do not - participate in transaction balancing. (And if you write them without - an amount, a zero amount is always inferred.) These can occasionally - be convenient for special circumstances, but they violate double entry - bookkeeping and make your data less portable across applications, so + 10, is called an unbalanced virtual posting. These postings do not + participate in transaction balancing. (And if you write them without + an amount, a zero amount is always inferred.) These can occasionally + be convenient for special circumstances, but they violate double entry + bookkeeping and make your data less portable across applications, so many people avoid using them at all. - A posting with brackets around the account name ([some:account]) is - called a balanced virtual posting. The balanced virtual postings in a + A posting with brackets around the account name ([some:account]) is + called a balanced virtual posting. The balanced virtual postings in a transaction must add up to zero, just like ordinary postings, but sepa- - rately from them. These are not part of double entry bookkeeping ei- + rately from them. These are not part of double entry bookkeeping ei- ther, but they are at least balanced. An example: 2022-01-01 buy food with cash, update budget envelope subaccounts, & something else @@ -2785,13 +2809,13 @@ Journal [assets:checking:available] $10 ; <- (something:else) $5 ; <- this is not required to balance - Ordinary postings, whose account names are neither parenthesised nor - bracketed, are called real postings. You can exclude virtual postings + Ordinary postings, whose account names are neither parenthesised nor + bracketed, are called real postings. You can exclude virtual postings from reports with the -R/--real flag or a real:1 query. Other Ledger directives These other Ledger directives are currently accepted but ignored. This - allows hledger to read more Ledger files, but be aware that hledger's + allows hledger to read more Ledger files, but be aware that hledger's reports may differ from Ledger's if you use these. apply fixed COMM AMT @@ -2812,26 +2836,26 @@ Journal value EXPR --command-line-flags - See also https://hledger.org/ledger.html for a detailed hledger/Ledger + See also https://hledger.org/ledger.html for a detailed hledger/Ledger syntax comparison. Other cost/lot notations - A slight digression for Ledger and Beancount users. Ledger has a num- + A slight digression for Ledger and Beancount users. Ledger has a num- ber of cost/lot-related notations: o @ UNITCOST and @@ TOTALCOST o expresses a conversion rate, as in hledger - o when buying, also creates a lot than can be selected at selling + o when buying, also creates a lot than can be selected at selling time o (@) UNITCOST and (@@) TOTALCOST (virtual cost) - o like the above, but also means "this cost was exceptional, don't + o like the above, but also means "this cost was exceptional, don't use it when inferring market prices". - Currently, hledger treats the above like @ and @@; the parentheses are + Currently, hledger treats the above like @ and @@; the parentheses are ignored. o {=FIXEDUNITCOST} and {{=FIXEDTOTALCOST}} (fixed price) @@ -2841,10 +2865,10 @@ Journal o {UNITCOST} and {{TOTALCOST}} (lot price) - o can be used identically to @ UNITCOST and @@ TOTALCOST, also cre- + o can be used identically to @ UNITCOST and @@ TOTALCOST, also cre- ates a lot - o when selling, combined with @ ..., specifies an investment lot by + o when selling, combined with @ ..., specifies an investment lot by its cost basis; does not check if that lot is present o and related: [YYYY/MM/DD] (lot date) @@ -2859,7 +2883,7 @@ Journal o when selling, selects a lot by its note - Currently, hledger accepts any or all of the above in any order after + Currently, hledger accepts any or all of the above in any order after the posting amount, but ignores them. (This can break transaction bal- ancing.) @@ -2870,12 +2894,12 @@ Journal o expresses a cost without creating a lot, as in hledger o when buying (augmenting) or selling (reducing) a lot, combined with - {...}: documents the cost/selling price (not used for transaction + {...}: documents the cost/selling price (not used for transaction balancing) o {UNITCOST} and {{TOTALCOST}} - o when buying (augmenting), expresses the cost for transaction bal- + o when buying (augmenting), expresses the cost for transaction bal- ancing, and also creates a lot with this cost basis attached o when selling (reducing), @@ -2887,38 +2911,38 @@ Journal o expresses the selling price for transaction balancing - Currently, hledger accepts the {UNITCOST}/{{TOTALCOST}} notation but + Currently, hledger accepts the {UNITCOST}/{{TOTALCOST}} notation but ignores it. - o variations: {}, {YYYY-MM-DD}, {"LABEL"}, {UNITCOST, "LABEL"}, {UNIT- + o variations: {}, {YYYY-MM-DD}, {"LABEL"}, {UNITCOST, "LABEL"}, {UNIT- COST, YYYY-MM-DD, "LABEL"} etc. Currently, hledger rejects these. CSV - hledger can read CSV files (Character Separated Value - usually comma, - semicolon, or tab) containing dated records, automatically converting + hledger can read CSV files (Character Separated Value - usually comma, + semicolon, or tab) containing dated records, automatically converting each record into a transaction. (To learn about writing CSV, see CSV output.) - For best error messages when reading CSV/TSV/SSV files, make sure they + For best error messages when reading CSV/TSV/SSV files, make sure they have a corresponding .csv, .tsv or .ssv file extension or use a hledger file prefix (see File Extension below). Each CSV file must be described by a corresponding rules file. - This contains rules describing the CSV data (header line, fields lay- - out, date format etc.), how to construct hledger transactions from it, - and how to categorise transactions based on description or other at- + This contains rules describing the CSV data (header line, fields lay- + out, date format etc.), how to construct hledger transactions from it, + and how to categorise transactions based on description or other at- tributes. - By default, hledger expects this rules file to be named like the CSV - file, with an extra .rules extension added, in the same directory. Eg - when asked to read foo/FILE.csv, hledger looks for foo/FILE.csv.rules. + By default, hledger expects this rules file to be named like the CSV + file, with an extra .rules extension added, in the same directory. Eg + when asked to read foo/FILE.csv, hledger looks for foo/FILE.csv.rules. You can specify a different rules file with the --rules option. - At minimum, the rules file must identify the date and amount fields, - and often it also specifies the date format and how many header lines + At minimum, the rules file must identify the date and amount fields, + and often it also specifies the date format and how many header lines there are. Here's a simple CSV file and a rules file for it: Date, Description, Id, Amount @@ -2935,56 +2959,56 @@ CSV income:unknown -10.23 There's an introductory Importing CSV data tutorial on hledger.org, and - more CSV rules examples below, and a larger collection at + more CSV rules examples below, and a larger collection at https://github.com/simonmichael/hledger/tree/master/examples/csv. CSV rules cheatsheet The following kinds of rule can appear in the rules file, in any order. (Blank lines and lines beginning with # or ; or * are ignored.) - source optionally declare which file to read data + source optionally declare which file to read data from - separator declare the field separator, instead of rely- + separator declare the field separator, instead of rely- ing on file extension skip skip one or more header lines at start of file date-format declare how to parse CSV dates/date-times - timezone declare the time zone of ambiguous CSV + timezone declare the time zone of ambiguous CSV date-times - newest-first improve txn order when: there are multiple + newest-first improve txn order when: there are multiple records, newest first, all with the same date - intra-day-reversed improve txn order when: same-day txns are in + intra-day-reversed improve txn order when: same-day txns are in opposite order to the overall file - decimal-mark declare the decimal mark used in CSV amounts, + decimal-mark declare the decimal mark used in CSV amounts, when ambiguous - fields list name CSV fields for easy reference, and op- + fields list name CSV fields for easy reference, and op- tionally assign their values to hledger fields - Field assignment assign a CSV value or interpolated text value + Field assignment assign a CSV value or interpolated text value to a hledger field if block conditionally assign values to hledger fields, or skip a record or end (skip rest of file) if table conditionally assign values to hledger fields, using compact syntax - balance-type select which type of balance assertions/as- + balance-type select which type of balance assertions/as- signments to generate include inline another CSV rules file - Working with CSV tips can be found below, including How CSV rules are + Working with CSV tips can be found below, including How CSV rules are evaluated. source - If you tell hledger to read a csv file with -f foo.csv, it will look - for rules in foo.csv.rules. Or, you can tell it to read the rules - file, with -f foo.csv.rules, and it will look for data in foo.csv + If you tell hledger to read a csv file with -f foo.csv, it will look + for rules in foo.csv.rules. Or, you can tell it to read the rules + file, with -f foo.csv.rules, and it will look for data in foo.csv (since 1.30). - These are mostly equivalent, but the second method provides some extra - features. For one, the data file can be missing, without causing an - error; it is just considered empty. And, you can specify a different + These are mostly equivalent, but the second method provides some extra + features. For one, the data file can be missing, without causing an + error; it is just considered empty. And, you can specify a different data file by adding a "source" rule: source ./Checking1.csv - If you specify just a file name with no path, hledger will look for it + If you specify just a file name with no path, hledger will look for it in your system's downloads directory (~/Downloads, currently): source Checking1.csv @@ -2997,9 +3021,9 @@ CSV See also "Working with CSV > Reading files specified by rule". separator - You can use the separator rule to read other kinds of character-sepa- - rated data. The argument is any single separator character, or the - words tab or space (case insensitive). Eg, for comma-separated values + You can use the separator rule to read other kinds of character-sepa- + rated data. The argument is any single separator character, or the + words tab or space (case insensitive). Eg, for comma-separated values (CSV): separator , @@ -3012,32 +3036,32 @@ CSV separator TAB - If the input file has a .csv, .ssv or .tsv file extension (or a csv:, + If the input file has a .csv, .ssv or .tsv file extension (or a csv:, ssv:, tsv: prefix), the appropriate separator will be inferred automat- ically, and you won't need this rule. skip skip N - The word skip followed by a number (or no number, meaning 1) tells - hledger to ignore this many non-empty lines at the start of the input - data. You'll need this whenever your CSV data contains header lines. - Note, empty and blank lines are skipped automatically, so you don't + The word skip followed by a number (or no number, meaning 1) tells + hledger to ignore this many non-empty lines at the start of the input + data. You'll need this whenever your CSV data contains header lines. + Note, empty and blank lines are skipped automatically, so you don't need to count those. - skip has a second meaning: it can be used inside if blocks (described - below), to skip one or more records whenever the condition is true. + skip has a second meaning: it can be used inside if blocks (described + below), to skip one or more records whenever the condition is true. Records skipped in this way are ignored, except they are still required to be valid CSV. date-format date-format DATEFMT - This is a helper for the date (and date2) fields. If your CSV dates - are not formatted like YYYY-MM-DD, YYYY/MM/DD or YYYY.MM.DD, you'll - need to add a date-format rule describing them with a strptime-style - date parsing pattern - see https://hackage.haskell.org/pack- - age/time/docs/Data-Time-Format.html#v:formatTime. The pattern must + This is a helper for the date (and date2) fields. If your CSV dates + are not formatted like YYYY-MM-DD, YYYY/MM/DD or YYYY.MM.DD, you'll + need to add a date-format rule describing them with a strptime-style + date parsing pattern - see https://hackage.haskell.org/pack- + age/time/docs/Data-Time-Format.html#v:formatTime. The pattern must parse the CSV date value completely. Some examples: # MM/DD/YY @@ -3057,33 +3081,33 @@ CSV timezone timezone TIMEZONE - When CSV contains date-times that are implicitly in some time zone + When CSV contains date-times that are implicitly in some time zone other than yours, but containing no explicit time zone information, you - can use this rule to declare the CSV's native time zone, which helps + can use this rule to declare the CSV's native time zone, which helps prevent off-by-one dates. - When the CSV date-times do contain time zone information, you don't - need this rule; instead, use %Z in date-format (or %z, %EZ, %Ez; see + When the CSV date-times do contain time zone information, you don't + need this rule; instead, use %Z in date-format (or %z, %EZ, %Ez; see the formatTime link above). In either of these cases, hledger will do a time-zone-aware conversion, localising the CSV date-times to your current system time zone. If you prefer to localise to some other time zone, eg for reproducibility, you - can (on unix at least) set the output timezone with the TZ environment + can (on unix at least) set the output timezone with the TZ environment variable, eg: $ TZ=-1000 hledger print -f foo.csv # or TZ=-1000 hledger import foo.csv - timezone currently does not understand timezone names, except "UTC", - "GMT", "EST", "EDT", "CST", "CDT", "MST", "MDT", "PST", or "PDT". For + timezone currently does not understand timezone names, except "UTC", + "GMT", "EST", "EDT", "CST", "CDT", "MST", "MDT", "PST", or "PDT". For others, use numeric format: +HHMM or -HHMM. newest-first hledger tries to ensure that the generated transactions will be ordered chronologically, including same-day transactions. Usually it can - auto-detect how the CSV records are ordered. But if it encounters CSV + auto-detect how the CSV records are ordered. But if it encounters CSV where all records are on the same date, it assumes that the records are - oldest first. If in fact the CSV's records are normally newest first, + oldest first. If in fact the CSV's records are normally newest first, like: 2022-10-01, txn 3... @@ -3097,9 +3121,9 @@ CSV newest-first intra-day-reversed - If CSV records within a single day are ordered opposite to the overall - record order, you can add the intra-day-reversed rule to improve the - order of journal entries. Eg, here the overall record order is newest + If CSV records within a single day are ordered opposite to the overall + record order, you can add the intra-day-reversed rule to improve the + order of journal entries. Eg, here the overall record order is newest first, but same-day records are oldest first: 2022-10-02, txn 3... @@ -3117,10 +3141,10 @@ CSV decimal-mark , - hledger automatically accepts either period or comma as a decimal mark - when parsing numbers (cf Amounts). However if any numbers in the CSV - contain digit group marks, such as thousand-separating commas, you - should declare the decimal mark explicitly with this rule, to avoid + hledger automatically accepts either period or comma as a decimal mark + when parsing numbers (cf Amounts). However if any numbers in the CSV + contain digit group marks, such as thousand-separating commas, you + should declare the decimal mark explicitly with this rule, to avoid misparsed numbers. fields list @@ -3129,17 +3153,17 @@ CSV A fields list (the word fields followed by comma-separated field names) is optional, but convenient. It does two things: - 1. It names the CSV field in each column. This can be convenient if - you are referencing them in other rules, so you can say %SomeField + 1. It names the CSV field in each column. This can be convenient if + you are referencing them in other rules, so you can say %SomeField instead of remembering %13. - 2. Whenever you use one of the special hledger field names (described - below), it assigns the CSV value in this position to that hledger - field. This is the quickest way to populate hledger's fields and + 2. Whenever you use one of the special hledger field names (described + below), it assigns the CSV value in this position to that hledger + field. This is the quickest way to populate hledger's fields and build a transaction. - Here's an example that says "use the 1st, 2nd and 4th fields as the - transaction's date, description and amount; name the last two fields + Here's an example that says "use the 1st, 2nd and 4th fields as the + transaction's date, description and amount; name the last two fields for later reference; and ignore the others": fields date, description, , amount, , , somefield, anotherfield @@ -3149,35 +3173,35 @@ CSV o There must be least two items in the list (at least one comma). - o Field names may not contain spaces. Spaces before/after field names + o Field names may not contain spaces. Spaces before/after field names are optional. o Field names may contain _ (underscore) or - (hyphen). - o Fields you don't care about can be given a dummy name or an empty + o Fields you don't care about can be given a dummy name or an empty name. - If the CSV contains column headings, it's convenient to use these for - your field names, suitably modified (eg lower-cased with spaces re- + If the CSV contains column headings, it's convenient to use these for + your field names, suitably modified (eg lower-cased with spaces re- placed by underscores). - Sometimes you may want to alter a CSV field name to avoid assigning to - a hledger field with the same name. Eg you could call the CSV's "bal- - ance" field balance_ to avoid directly setting hledger's balance field + Sometimes you may want to alter a CSV field name to avoid assigning to + a hledger field with the same name. Eg you could call the CSV's "bal- + ance" field balance_ to avoid directly setting hledger's balance field (and generating a balance assertion). Field assignment HLEDGERFIELD FIELDVALUE - Field assignments are the more flexible way to assign CSV values to + Field assignments are the more flexible way to assign CSV values to hledger fields. They can be used instead of or in addition to a fields list (see above). - To assign a value to a hledger field, write the field name (any of the - standard hledger field/pseudo-field names, defined below), a space, - followed by a text value on the same line. This text value may inter- - polate CSV fields, referenced either by their 1-based position in the - CSV record (%N) or by the name they were given in the fields list + To assign a value to a hledger field, write the field name (any of the + standard hledger field/pseudo-field names, defined below), a space, + followed by a text value on the same line. This text value may inter- + polate CSV fields, referenced either by their 1-based position in the + CSV record (%N) or by the name they were given in the fields list (%CSVFIELD), and regular expression match groups (\N). Some examples: @@ -3190,26 +3214,26 @@ CSV Tips: - o Interpolation strips outer whitespace (so a CSV value like " 1 " be- + o Interpolation strips outer whitespace (so a CSV value like " 1 " be- comes 1 when interpolated) (#1051). - o Interpolations always refer to a CSV field - you can't interpolate a + o Interpolations always refer to a CSV field - you can't interpolate a hledger field. (See Referencing other fields below). Field names - Note the two kinds of field names mentioned here, and used only in + Note the two kinds of field names mentioned here, and used only in hledger CSV rules files: - 1. CSV field names (CSVFIELD in these docs): you can optionally name - the CSV columns for easy reference (since hledger doesn't yet auto- + 1. CSV field names (CSVFIELD in these docs): you can optionally name + the CSV columns for easy reference (since hledger doesn't yet auto- matically recognise column headings in a CSV file), by writing arbi- trary names in a fields list, eg: fields When, What, Some_Id, Net, Total, Foo, Bar - 2. Special hledger field names (HLEDGERFIELD in these docs): you must - set at least some of these to generate the hledger transaction from - a CSV record, by writing them as the left hand side of a field as- + 2. Special hledger field names (HLEDGERFIELD in these docs): you must + set at least some of these to generate the hledger transaction from + a CSV record, by writing them as the left hand side of a field as- signment, eg: date %When @@ -3224,7 +3248,7 @@ CSV currency $ comment %Foo %Bar - Here are all the special hledger field names available, and what hap- + Here are all the special hledger field names available, and what hap- pens when you assign values to them: date field @@ -3247,7 +3271,7 @@ CSV commentN, where N is a number, sets the Nth posting's comment. - You can assign multi-line comments by writing literal \n in the code. + You can assign multi-line comments by writing literal \n in the code. A comment starting with \n will begin on a new line. Comments can contain tags, as usual. @@ -3256,99 +3280,99 @@ CSV Assigning to accountN, where N is 1 to 99, sets the account name of the Nth posting, and causes that posting to be generated. - Most often there are two postings, so you'll want to set account1 and - account2. Typically account1 is associated with the CSV file, and is - set once with a top-level assignment, while account2 is set based on + Most often there are two postings, so you'll want to set account1 and + account2. Typically account1 is associated with the CSV file, and is + set once with a top-level assignment, while account2 is set based on each transaction's description, in conditional rules. - If a posting's account name is left unset but its amount is set (see - below), a default account name will be chosen (like "expenses:unknown" + If a posting's account name is left unset but its amount is set (see + below), a default account name will be chosen (like "expenses:unknown" or "income:unknown"). amount field - There are several ways to set posting amounts from CSV, useful in dif- + There are several ways to set posting amounts from CSV, useful in dif- ferent situations. - 1. amount is the oldest and simplest. Assigning to this sets the + 1. amount is the oldest and simplest. Assigning to this sets the amount of the first and second postings. In the second posting, the - amount will be negated; also, if it has a cost attached, it will be + amount will be negated; also, if it has a cost attached, it will be converted to cost. - 2. amount-in and amount-out work exactly like the above, but should be - used when the CSV has two amount fields (such as "Debit" and + 2. amount-in and amount-out work exactly like the above, but should be + used when the CSV has two amount fields (such as "Debit" and "Credit", or "Inflow" and "Outflow"). Whichever field has a - non-zero value will be used as the amount of the first and second + non-zero value will be used as the amount of the first and second postings. Here are some tips to avoid confusion: - o It's not "amount-in for posting 1 and amount-out for posting 2", - it is "extract a single amount from the amount-in or amount-out + o It's not "amount-in for posting 1 and amount-out for posting 2", + it is "extract a single amount from the amount-in or amount-out field, and use that for posting 1 and (negated) for posting 2". - o Don't use both amount and amount-in/amount-out in the same rules + o Don't use both amount and amount-in/amount-out in the same rules file; choose based on whether the amount is in a single CSV field or spread across two fields. - o In each record, at most one of the two CSV fields should contain - a non-zero amount; the other field must contain a zero or noth- + o In each record, at most one of the two CSV fields should contain + a non-zero amount; the other field must contain a zero or noth- ing. - o hledger assumes both CSV fields contain unsigned numbers, and it + o hledger assumes both CSV fields contain unsigned numbers, and it automatically negates the amount-out values. - o If the data doesn't fit these requirements, you'll probably need + o If the data doesn't fit these requirements, you'll probably need an if rule (see below). 3. amountN (where N is a number from 1 to 99) sets the amount of only a - single posting: the Nth posting in the transaction. You'll usually - need at least two such assignments to make a balanced transaction. + single posting: the Nth posting in the transaction. You'll usually + need at least two such assignments to make a balanced transaction. You can also generate more than two postings, to represent more com- - plex transactions. The posting numbers don't have to be consecu- - tive; with if rules, higher posting numbers can be useful to ensure + plex transactions. The posting numbers don't have to be consecu- + tive; with if rules, higher posting numbers can be useful to ensure a certain order of postings. - 4. amountN-in and amountN-out work exactly like the above, but should - be used when the CSV has two amount fields. This is analogous to + 4. amountN-in and amountN-out work exactly like the above, but should + be used when the CSV has two amount fields. This is analogous to amount-in and amount-out, and those tips also apply here. 5. Remember that a fields list can also do assignments. So in a fields - list if you name a CSV field "amount", that counts as assigning to - amount. (If you don't want that, call it something else in the + list if you name a CSV field "amount", that counts as assigning to + amount. (If you don't want that, call it something else in the fields list, like "amount_".) - 6. The above don't handle every situation; if you need more flexibil- + 6. The above don't handle every situation; if you need more flexibil- ity, use an if rule to set amounts conditionally. See "Working with - CSV > Setting amounts" below for more on this and on amount-setting + CSV > Setting amounts" below for more on this and on amount-setting generally. currency field - currency sets a currency symbol, to be prepended to all postings' - amounts. You can use this if the CSV amounts do not have a currency + currency sets a currency symbol, to be prepended to all postings' + amounts. You can use this if the CSV amounts do not have a currency symbol, eg if it is in a separate column. currencyN prepends a currency symbol to just the Nth posting's amount. balance field - balanceN sets a balance assertion amount (or if the posting amount is + balanceN sets a balance assertion amount (or if the posting amount is left empty, a balance assignment) on posting N. balance is a compatibility spelling for hledger <1.17; it is equivalent to balance1. - You can adjust the type of assertion/assignment with the balance-type + You can adjust the type of assertion/assignment with the balance-type rule (see below). - See the Working with CSV tips below for more about setting amounts and + See the Working with CSV tips below for more about setting amounts and currency. if block - Rules can be applied conditionally, depending on patterns in the CSV - data. This allows flexibility; in particular, it is how you can cate- - gorise transactions, selecting an appropriate account name based on - their description (for example). There are two ways to write condi- - tional rules: "if blocks", described here, and "if tables", described + Rules can be applied conditionally, depending on patterns in the CSV + data. This allows flexibility; in particular, it is how you can cate- + gorise transactions, selecting an appropriate account name based on + their description (for example). There are two ways to write condi- + tional rules: "if blocks", described here, and "if tables", described below. - An if block is the word if and one or more "matcher" expressions (can + An if block is the word if and one or more "matcher" expressions (can be a word or phrase), one per line, starting either on the same or next line; followed by one or more indented rules. Eg, @@ -3364,11 +3388,11 @@ CSV RULE RULE - If any of the matchers succeeds, all of the indented rules will be ap- - plied. They are usually field assignments, but the following special + If any of the matchers succeeds, all of the indented rules will be ap- + plied. They are usually field assignments, but the following special rules may also be used within an if block: - o skip - skips the matched CSV record (generating no transaction from + o skip - skips the matched CSV record (generating no transaction from it) o end - skips the rest of the current CSV file. @@ -3394,27 +3418,27 @@ CSV Matchers There are two kinds: - 1. A record matcher is a word or single-line text fragment or regular - expression (REGEX), which hledger will try to match case-insensi- + 1. A record matcher is a word or single-line text fragment or regular + expression (REGEX), which hledger will try to match case-insensi- tively anywhere within the CSV record. Eg: whole foods - 2. A field matcher is preceded with a percent sign and CSV field name - (%CSVFIELD REGEX). hledger will try to match these just within the + 2. A field matcher is preceded with a percent sign and CSV field name + (%CSVFIELD REGEX). hledger will try to match these just within the named CSV field. Eg: %date 2023 - The regular expression is (as usual in hledger) a POSIX extended regu- - lar expression, that also supports GNU word boundaries (\b, \B, \<, - \>), and nothing else. If you have trouble, see "Regular expressions" + The regular expression is (as usual in hledger) a POSIX extended regu- + lar expression, that also supports GNU word boundaries (\b, \B, \<, + \>), and nothing else. If you have trouble, see "Regular expressions" in the hledger manual (https://hledger.org/hledger.html#regular-expres- sions). What matchers match With record matchers, it's important to know that the record matched is - not the original CSV record, but a modified one: separators will be - converted to commas, and enclosing double quotes (but not enclosing - whitespace) are removed. So for example, when reading an SSV file, if + not the original CSV record, but a modified one: separators will be + converted to commas, and enclosing double quotes (but not enclosing + whitespace) are removed. So for example, when reading an SSV file, if the original record was: 2023-01-01; "Acme, Inc."; 1,000 @@ -3429,10 +3453,10 @@ CSV o By default they are OR'd (any of them can match) o When a matcher is preceded by ampersand (&, at the start of the line) - it will be AND'ed with the previous matcher (all in the AND'ed group + it will be AND'ed with the previous matcher (all in the AND'ed group must match) - o Added in 1.32 When a matcher is preceded by an exclamation mark (!), + o Added in 1.32 When a matcher is preceded by an exclamation mark (!), it is negated (it must not match). Note currently there is a limitation: you can't use both & and ! on the @@ -3442,13 +3466,13 @@ CSV Added in 1.32 Matchers can define match groups: parenthesised portions of the regular - expression which are available for reference in field assignments. + expression which are available for reference in field assignments. Groups are enclosed in regular parentheses (( and )) and can be nested. - Each group is available in field assignments using the token \N, where - N is an index into the match groups for this conditional block (e.g. + Each group is available in field assignments using the token \N, where + N is an index into the match groups for this conditional block (e.g. \1, \2, etc.). - Example: Warp credit card payment postings to the beginning of the + Example: Warp credit card payment postings to the beginning of the billing period (Month start), to match how they are presented in state- ments, using posting dates: @@ -3462,8 +3486,8 @@ CSV account1 \1 if table - "if tables" are an alternative to if blocks; they can express many - matchers and field assignments in a more compact tabular format, like + "if tables" are an alternative to if blocks; they can express many + matchers and field assignments in a more compact tabular format, like this: if,HLEDGERFIELD1,HLEDGERFIELD2,... @@ -3474,21 +3498,21 @@ CSV The first character after if is taken to be this if table's field sepa- - rator. It is unrelated to the separator used in the CSV file. It + rator. It is unrelated to the separator used in the CSV file. It should be a non-alphanumeric character like , or | that does not appear - anywhere else in the table (it should not be used in field names or + anywhere else in the table (it should not be used in field names or matchers or values, and it cannot be escaped with a backslash). - Each line must contain the same number of separators; empty values are - allowed. Whitespace can be used in the matcher lines for readability - (but not in the if line, currently). You can use the comment lines in - the table body. The table must be terminated by an empty line (or end + Each line must contain the same number of separators; empty values are + allowed. Whitespace can be used in the matcher lines for readability + (but not in the if line, currently). You can use the comment lines in + the table body. The table must be terminated by an empty line (or end of file). - An if table like the above is interpreted as follows: try all of the + An if table like the above is interpreted as follows: try all of the matchers; whenever a matcher succeeds, assign all of the values on that - line to the corresponding hledger fields; If multiple lines match, - later lines will override fields assigned by the earlier ones - just + line to the corresponding hledger fields; If multiple lines match, + later lines will override fields assigned by the earlier ones - just like the sequence of if blocks would behave. If table presented above is equivalent to this sequence of if blocks: @@ -3519,10 +3543,10 @@ CSV balance-type Balance assertions generated by assigning to balanceN are of the simple - = type by default, which is a single-commodity, subaccount-excluding + = type by default, which is a single-commodity, subaccount-excluding assertion. You may find the subaccount-including variants more useful, - eg if you have created some virtual subaccounts of checking to help - with budgeting. You can select a different type of assertion with the + eg if you have created some virtual subaccounts of checking to help + with budgeting. You can select a different type of assertion with the balance-type rule: # balance assertions will consider all commodities and all subaccounts @@ -3538,9 +3562,9 @@ CSV include include RULESFILE - This includes the contents of another CSV rules file at this point. - RULESFILE is an absolute file path or a path relative to the current - file's directory. This can be useful for sharing common rules between + This includes the contents of another CSV rules file at this point. + RULESFILE is an absolute file path or a path relative to the current + file's directory. This can be useful for sharing common rules between several rules files, eg: # someaccount.csv.rules @@ -3557,42 +3581,42 @@ CSV Some tips: Rapid feedback - It's a good idea to get rapid feedback while creating/troubleshooting + It's a good idea to get rapid feedback while creating/troubleshooting CSV rules. Here's a good way, using entr from eradman.com/entrproject: $ ls foo.csv* | entr bash -c 'echo ----; hledger -f foo.csv print desc:SOMEDESC' - A desc: query (eg) is used to select just one, or a few, transactions - of interest. "bash -c" is used to run multiple commands, so we can - echo a separator each time the command re-runs, making it easier to + A desc: query (eg) is used to select just one, or a few, transactions + of interest. "bash -c" is used to run multiple commands, so we can + echo a separator each time the command re-runs, making it easier to read the output. Valid CSV - Note that hledger will only accept valid CSV conforming to RFC 4180, + Note that hledger will only accept valid CSV conforming to RFC 4180, and equivalent SSV and TSV formats (like RFC 4180 but with semicolon or tab as separators). This means, eg: o Values may be enclosed in double quotes, or not. Enclosing in single quotes is not allowed. (Eg 'A','B' is rejected.) - o When values are enclosed in double quotes, spaces outside the quotes + o When values are enclosed in double quotes, spaces outside the quotes are not allowed. (Eg "A", "B" is rejected.) - o When values are not enclosed in quotes, they may not contain double + o When values are not enclosed in quotes, they may not contain double quotes. (Eg A"A, B is rejected.) - If your CSV/SSV/TSV is not valid in this sense, you'll need to trans- - form it before reading with hledger. Try using sed, or a more permis- + If your CSV/SSV/TSV is not valid in this sense, you'll need to trans- + form it before reading with hledger. Try using sed, or a more permis- sive CSV parser like python's csv lib. File Extension - To help hledger choose the CSV file reader and show the right error - messages (and choose the right field separator character by default), - it's best if CSV/SSV/TSV files are named with a .csv, .ssv or .tsv + To help hledger choose the CSV file reader and show the right error + messages (and choose the right field separator character by default), + it's best if CSV/SSV/TSV files are named with a .csv, .ssv or .tsv filename extension. (More about this at Data formats.) - When reading files with the "wrong" extension, you can ensure the CSV - reader (and the default field separator) by prefixing the file path + When reading files with the "wrong" extension, you can ensure the CSV + reader (and the default field separator) by prefixing the file path with csv:, ssv: or tsv:: Eg: $ hledger -f ssv:foo.dat print @@ -3601,29 +3625,29 @@ CSV if needed. Reading CSV from standard input - You'll need the file format prefix when reading CSV from stdin also, + You'll need the file format prefix when reading CSV from stdin also, since hledger assumes journal format by default. Eg: $ cat foo.dat | hledger -f ssv:- print Reading multiple CSV files - If you use multiple -f options to read multiple CSV files at once, - hledger will look for a correspondingly-named rules file for each CSV - file. But if you specify a rules file with --rules, that rules file + If you use multiple -f options to read multiple CSV files at once, + hledger will look for a correspondingly-named rules file for each CSV + file. But if you specify a rules file with --rules, that rules file will be used for all the CSV files. Reading files specified by rule Instead of specifying a CSV file in the command line, you can specify a - rules file, as in hledger -f foo.csv.rules CMD. By default this will - read data from foo.csv in the same directory, but you can add a source - rule to specify a different data file, perhaps located in your web + rules file, as in hledger -f foo.csv.rules CMD. By default this will + read data from foo.csv in the same directory, but you can add a source + rule to specify a different data file, perhaps located in your web browser's download directory. This feature was added in hledger 1.30, so you won't see it in most CSV - rules examples. But it helps remove some of the busywork of managing + rules examples. But it helps remove some of the busywork of managing CSV downloads. Most of your financial institutions's default CSV file- - names are different and can be recognised by a glob pattern. So you - can put a rule like source Checking1*.csv in foo-checking.csv.rules, + names are different and can be recognised by a glob pattern. So you + can put a rule like source Checking1*.csv in foo-checking.csv.rules, and then periodically follow a workflow like: 1. Download CSV from Foo's website, using your browser's defaults @@ -3631,45 +3655,45 @@ CSV 2. Run hledger import foo-checking.csv.rules to import any new transac- tions - After import, you can: discard the CSV, or leave it where it is for a - while, or move it into your archives, as you prefer. If you do noth- - ing, next time your browser will save something like Checking1-2.csv, - and hledger will use that because of the * wild card and because it is + After import, you can: discard the CSV, or leave it where it is for a + while, or move it into your archives, as you prefer. If you do noth- + ing, next time your browser will save something like Checking1-2.csv, + and hledger will use that because of the * wild card and because it is the most recent. Valid transactions After reading a CSV file, hledger post-processes and validates the gen- erated journal entries as it would for a journal file - balancing them, - applying balance assignments, and canonicalising amount styles. Any - errors at this stage will be reported in the usual way, displaying the + applying balance assignments, and canonicalising amount styles. Any + errors at this stage will be reported in the usual way, displaying the problem entry. There is one exception: balance assertions, if you have generated them, - will not be checked, since normally these will work only when the CSV - data is part of the main journal. If you do need to check balance as- + will not be checked, since normally these will work only when the CSV + data is part of the main journal. If you do need to check balance as- sertions generated from CSV right away, pipe into another hledger: $ hledger -f file.csv print | hledger -f- print Deduplicating, importing - When you download a CSV file periodically, eg to get your latest bank - transactions, the new file may overlap with the old one, containing + When you download a CSV file periodically, eg to get your latest bank + transactions, the new file may overlap with the old one, containing some of the same records. The import command will (a) detect the new transactions, and (b) append just those transactions to your main journal. It is idempotent, so you - don't have to remember how many times you ran it or with which version - of the CSV. (It keeps state in a hidden .latest.FILE.csv file.) This + don't have to remember how many times you ran it or with which version + of the CSV. (It keeps state in a hidden .latest.FILE.csv file.) This is the easiest way to import CSV data. Eg: # download the latest CSV files, then run this command. # Note, no -f flags needed here. $ hledger import *.csv [--dry] - This method works for most CSV files. (Where records have a stable + This method works for most CSV files. (Where records have a stable chronological order, and new records appear only at the new end.) - A number of other tools and workflows, hledger-specific and otherwise, + A number of other tools and workflows, hledger-specific and otherwise, exist for converting, deduplicating, classifying and managing CSV data. See: @@ -3678,16 +3702,16 @@ CSV o https://plaintextaccounting.org -> data import/conversion Setting amounts - Continuing from amount field above, here are more tips for amount-set- + Continuing from amount field above, here are more tips for amount-set- ting: 1. If the amount is in a single CSV field: a. If its sign indicates direction of flow: - Assign it to amountN, to set the Nth posting's amount. N is usu- + Assign it to amountN, to set the Nth posting's amount. N is usu- ally 1 or 2 but can go up to 99. b. If another field indicates direction of flow: - Use one or more conditional rules to set the appropriate amount + Use one or more conditional rules to set the appropriate amount sign. Eg: # assume a withdrawal unless Type contains "deposit": @@ -3695,15 +3719,15 @@ CSV if %Type deposit amount1 %Amount - 2. If the amount is in two CSV fields (such as Debit and Credit, or In + 2. If the amount is in two CSV fields (such as Debit and Credit, or In and Out): a. If both fields are unsigned: - Assign one field to amountN-in and the other to amountN-out. - hledger will automatically negate the "out" field, and will use + Assign one field to amountN-in and the other to amountN-out. + hledger will automatically negate the "out" field, and will use whichever field value is non-zero as posting N's amount. b. If either field is signed: - You will probably need to override hledger's sign for one or the + You will probably need to override hledger's sign for one or the other field, as in the following example: # Negate the -out value, but only if it is not empty: @@ -3711,12 +3735,12 @@ CSV if %amount1-out [1-9] amount1-out -%amount1-out - c. If both fields can contain a non-zero value (or both can be + c. If both fields can contain a non-zero value (or both can be empty): - The -in/-out rules normally choose the value which is - non-zero/non-empty. Some value pairs can be ambiguous, such as 1 + The -in/-out rules normally choose the value which is + non-zero/non-empty. Some value pairs can be ambiguous, such as 1 and none. For such cases, use conditional rules to help select the - amount. Eg, to handle the above you could select the value con- + amount. Eg, to handle the above you could select the value con- taining non-zero digits: fields date, description, in, out @@ -3729,8 +3753,8 @@ CSV Use the unnumbered amount (or amount-in and amount-out) syntax. 4. If the CSV has only balance amounts, not transaction amounts: - Assign to balanceN, to set a balance assignment on the Nth posting, - causing the posting's amount to be calculated automatically. balance + Assign to balanceN, to set a balance assignment on the Nth posting, + causing the posting's amount to be calculated automatically. balance with no number is equivalent to balance1. In this situation hledger is more likely to guess the wrong default account name, so you may need to set that explicitly. @@ -3746,20 +3770,20 @@ CSV o If an amount value is parenthesised: it will be de-parenthesised and sign-flipped: (AMT) becomes -AMT - o If an amount value has two minus signs (or two sets of parentheses, + o If an amount value has two minus signs (or two sets of parentheses, or a minus sign and parentheses): they cancel out and will be removed: --AMT or -(AMT) becomes AMT - o If an amount value contains just a sign (or just a set of parenthe- + o If an amount value contains just a sign (or just a set of parenthe- ses): - that is removed, making it an empty value. "+" or "-" or "()" becomes + that is removed, making it an empty value. "+" or "-" or "()" becomes "". - It's not possible (without preprocessing the CSV) to set an amount to + It's not possible (without preprocessing the CSV) to set an amount to its absolute value, ie discard its sign. Setting currency/commodity - If the currency/commodity symbol is included in the CSV's amount + If the currency/commodity symbol is included in the CSV's amount field(s): 2023-01-01,foo,$123.00 @@ -3778,7 +3802,7 @@ CSV 2023-01-01,foo,USD,123.00 You can assign that to the currency pseudo-field, which has the special - effect of prepending itself to every amount in the transaction (on the + effect of prepending itself to every amount in the transaction (on the left, with no separating space): fields date,description,currency,amount @@ -3787,7 +3811,7 @@ CSV expenses:unknown USD123.00 income:unknown USD-123.00 - Or, you can use a field assignment to construct the amount yourself, + Or, you can use a field assignment to construct the amount yourself, with more control. Eg to put the symbol on the right, and separated by a space: @@ -3798,38 +3822,38 @@ CSV expenses:unknown 123.00 USD income:unknown -123.00 USD - Note we used a temporary field name (cur) that is not currency - that + Note we used a temporary field name (cur) that is not currency - that would trigger the prepending effect, which we don't want here. Amount decimal places - When you are reading CSV data, eg with a command like hledger -f - foo.csv print, hledger will infer each commodity's decimal precision - (and other commodity display styles) from the amounts - much as when + When you are reading CSV data, eg with a command like hledger -f + foo.csv print, hledger will infer each commodity's decimal precision + (and other commodity display styles) from the amounts - much as when reading a journal file without commodity directives (see the link). - Note, the commodity styles are not inferred from the numbers in the + Note, the commodity styles are not inferred from the numbers in the original CSV data; rather, they are inferred from the amounts generated by the CSV rules. When you are importing CSV data with the import command, eg hledger im- - port foo.csv, there's another step: import tries to make the new en- - tries conform to the journal's existing styles. So for each commodity + port foo.csv, there's another step: import tries to make the new en- + tries conform to the journal's existing styles. So for each commodity - let's say it's EUR - import will choose: 1. the style declared for EUR by a commodity directive in the journal 2. otherwise, the style inferred from EUR amounts in the journal - 3. otherwise, the style inferred from EUR amounts generated by the CSV + 3. otherwise, the style inferred from EUR amounts generated by the CSV rules. - TLDR: if import is not generating the precisions or styles you want, + TLDR: if import is not generating the precisions or styles you want, add a commodity directive to specify them. Referencing other fields - In field assignments, you can interpolate only CSV fields, not hledger - fields. In the example below, there's both a CSV field and a hledger - field named amount1, but %amount1 always means the CSV field, not the + In field assignments, you can interpolate only CSV fields, not hledger + fields. In the example below, there's both a CSV field and a hledger + field named amount1, but %amount1 always means the CSV field, not the hledger field: # Name the third CSV field "amount1" @@ -3841,7 +3865,7 @@ CSV # Set comment to the CSV amount1 (not the amount1 assigned above) comment %amount1 - Here, since there's no CSV amount1 field, %amount1 will produce a lit- + Here, since there's no CSV amount1 field, %amount1 will produce a lit- eral "amount1": fields date,description,csvamount @@ -3849,7 +3873,7 @@ CSV # Can't interpolate amount1 here comment %amount1 - When there are multiple field assignments to the same hledger field, + When there are multiple field assignments to the same hledger field, only the last one takes effect. Here, comment's value will be be B, or C if "something" is matched, but never A: @@ -3859,14 +3883,14 @@ CSV comment C How CSV rules are evaluated - Here's how to think of CSV rules being evaluated (if you really need + Here's how to think of CSV rules being evaluated (if you really need to). First, - o include - all includes are inlined, from top to bottom, depth first. - (At each include point the file is inlined and scanned for further + o include - all includes are inlined, from top to bottom, depth first. + (At each include point the file is inlined and scanned for further includes, recursively, before proceeding.) - Then "global" rules are evaluated, top to bottom. If a rule is re- + Then "global" rules are evaluated, top to bottom. If a rule is re- peated, the last one wins: o skip (at top level) @@ -3880,30 +3904,30 @@ CSV Then for each CSV record in turn: - o test all if blocks. If any of them contain a end rule, skip all re- - maining CSV records. Otherwise if any of them contain a skip rule, - skip that many CSV records. If there are multiple matched skip + o test all if blocks. If any of them contain a end rule, skip all re- + maining CSV records. Otherwise if any of them contain a skip rule, + skip that many CSV records. If there are multiple matched skip rules, the first one wins. - o collect all field assignments at top level and in matched if blocks. - When there are multiple assignments for a field, keep only the last + o collect all field assignments at top level and in matched if blocks. + When there are multiple assignments for a field, keep only the last one. - o compute a value for each hledger field - either the one that was as- + o compute a value for each hledger field - either the one that was as- signed to it (and interpolate the %CSVFIELD references), or a default o generate a hledger transaction (journal entry) from these values. - This is all part of the CSV reader, one of several readers hledger can - use to parse input files. When all files have been read successfully, - the transactions are passed as input to whichever hledger command the + This is all part of the CSV reader, one of several readers hledger can + use to parse input files. When all files have been read successfully, + the transactions are passed as input to whichever hledger command the user specified. Well factored rules - Some things than can help reduce duplication and complexity in rules + Some things than can help reduce duplication and complexity in rules files: - o Extracting common rules usable with multiple CSV files into a com- + o Extracting common rules usable with multiple CSV files into a com- mon.rules, and adding include common.rules to each CSV's rules file. o Splitting if blocks into smaller if blocks, extracting the frequently @@ -3911,8 +3935,8 @@ CSV CSV rules examples Bank of Ireland - Here's a CSV with two amount fields (Debit and Credit), and a balance - field, which we can use to add balance assertions, which is not neces- + Here's a CSV with two amount fields (Debit and Credit), and a balance + field, which we can use to add balance assertions, which is not neces- sary but provides extra error checking: Date,Details,Debit,Credit,Balance @@ -3954,13 +3978,13 @@ CSV assets:bank:boi:checking EUR-5.0 = EUR126.0 expenses:unknown EUR5.0 - The balance assertions don't raise an error above, because we're read- - ing directly from CSV, but they will be checked if these entries are + The balance assertions don't raise an error above, because we're read- + ing directly from CSV, but they will be checked if these entries are imported into a journal file. Coinbase - A simple example with some CSV from Coinbase. The spot price is - recorded using cost notation. The legacy amount field name conve- + A simple example with some CSV from Coinbase. The spot price is + recorded using cost notation. The legacy amount field name conve- niently sets amount 2 (posting 2's amount) to the total cost. # Timestamp,Transaction Type,Asset,Quantity Transacted,Spot Price Currency,Spot Price at Transaction,Subtotal,Total (inclusive of fees and/or spread),Fees and/or Spread,Notes @@ -3982,7 +4006,7 @@ CSV Amazon Here we convert amazon.com order history, and use an if block to gener- - ate a third posting if there's a fee. (In practice you'd probably get + ate a third posting if there's a fee. (In practice you'd probably get this data from your bank instead, but it's an example.) "Date","Type","To/From","Name","Status","Amount","Fees","Transaction ID" @@ -4034,7 +4058,7 @@ CSV expenses:fees $1.00 Paypal - Here's a real-world rules file for (customised) Paypal CSV, with some + Here's a real-world rules file for (customised) Paypal CSV, with some Paypal-specific rules, and a second rules file included: "Date","Time","TimeZone","Name","Type","Status","Currency","Gross","Fee","Net","From Email Address","To Email Address","Transaction ID","Item Title","Item ID","Reference Txn ID","Receipt ID","Balance","Note" @@ -4185,12 +4209,12 @@ CSV Timeclock The time logging format of timeclock.el, as read by hledger. - hledger can read time logs in timeclock format. As with Ledger, these - are (a subset of) timeclock.el's format, containing clock-in and - clock-out entries as in the example below. The date is a simple date. - The time format is HH:MM[:SS][+-ZZZZ]. Seconds and timezone are op- - tional. The timezone, if present, must be four digits and is ignored - (currently the time is always interpreted as a local time). Lines be- + hledger can read time logs in timeclock format. As with Ledger, these + are (a subset of) timeclock.el's format, containing clock-in and + clock-out entries as in the example below. The date is a simple date. + The time format is HH:MM[:SS][+-ZZZZ]. Seconds and timezone are op- + tional. The timezone, if present, must be four digits and is ignored + (currently the time is always interpreted as a local time). Lines be- ginning with # or ; or *, and blank lines, are ignored. i 2015/03/30 09:00:00 some account optional description after 2 spaces ; optional comment, tags: @@ -4198,9 +4222,9 @@ Timeclock i 2015/03/31 22:21:45 another:account o 2015/04/01 02:00:34 - hledger treats each clock-in/clock-out pair as a transaction posting - some number of hours to an account. Or if the session spans more than - one day, it is split into several transactions, one for each day. For + hledger treats each clock-in/clock-out pair as a transaction posting + some number of hours to an account. Or if the session spans more than + one day, it is split into several transactions, one for each day. For the above time log, hledger print generates these journal entries: $ hledger -f t.timeclock print @@ -4221,21 +4245,22 @@ 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 + rely on a "timeclock" executable which I think is just the ledger 2 executable renamed. Timedot - timedot format is hledger's human-friendly time logging format. Com- - pared to timeclock format, it is more convenient for quick, approxi- - mate, and retroactive time logging, and more human-readable (you can + timedot format is hledger's human-friendly time logging format. Com- + pared to timeclock format, it is more convenient for quick, approxi- + mate, and retroactive time logging, and more human-readable (you can see at a glance where time was spent). A quick example: 2023-05-01 @@ -4254,54 +4279,54 @@ Timedot (per:admin:finance) 0 A timedot file contains a series of transactions (usually one per day). - Each begins with a simple date (Y-M-D, Y/M/D, or Y.M.D), optionally be + Each begins with a simple date (Y-M-D, Y/M/D, or Y.M.D), optionally be followed on the same line by a transaction description, and/or a trans- action comment following a semicolon. After the date line are zero or more time postings, consisting of: - o An account name - any hledger-style account name, optionally in- + o An account name - any hledger-style account name, optionally in- dented. - o Two or more spaces - required if there is an amount (as in journal + o Two or more spaces - required if there is an amount (as in journal format). o A timedot amount, which can be o empty (representing zero) - o a number, optionally followed by a unit s, m, h, d, w, mo, or y, - representing a precise number of seconds, minutes, hours, days + o a number, optionally followed by a unit s, m, h, d, w, mo, or y, + representing a precise number of seconds, minutes, hours, days weeks, months or years (hours is assumed by default), which will be - converted to hours according to 60s = 1m, 60m = 1h, 24h = 1d, 7d = + converted to hours according to 60s = 1m, 60m = 1h, 24h = 1d, 7d = 1w, 30d = 1mo, 365d = 1y. - o one or more dots (period characters), each representing 0.25. - These are the dots in "timedot". Spaces are ignored and can be + o one or more dots (period characters), each representing 0.25. + These are the dots in "timedot". Spaces are ignored and can be used for grouping/alignment. - o Added in 1.32 one or more letters. These are like dots but they - also generate a tag t: (short for "type") with the letter as its - value, and a separate posting for each of the values. This pro- - vides a second dimension of categorisation, viewable in reports + o Added in 1.32 one or more letters. These are like dots but they + also generate a tag t: (short for "type") with the letter as its + value, and a separate posting for each of the values. This pro- + vides a second dimension of categorisation, viewable in reports with --pivot t. - o An optional comment following a semicolon (a hledger-style posting + o An optional comment following a semicolon (a hledger-style posting comment). - There is some flexibility to help with keeping time log data and notes + There is some flexibility to help with keeping time log data and notes in the same file: o Blank lines and lines beginning with # or ; are ignored. - o After the first date line, lines which do not contain a double space + o After the first date line, lines which do not contain a double space are parsed as postings with zero amount. (hledger's register reports will show these if you add -E). - o Before the first date line, lines beginning with * (eg org headings) - are ignored. And from the first date line onward, Emacs org mode + o Before the first date line, lines beginning with * (eg org headings) + are ignored. And from the first date line onward, Emacs org mode heading prefixes at the start of lines (one or more *'s followed by a - space) will be ignored. This means the time log can also be a org + space) will be ignored. This means the time log can also be a org outline. Timedot examples @@ -4409,21 +4434,21 @@ Timedot PART 3: REPORTING CONCEPTS Time periods Report start & end date - Most hledger reports will by default show the full time period repre- - sented by the journal. The report start date will be the earliest + Most hledger reports will by default show the full time period repre- + sented by the journal. The report start date will be the earliest transaction or posting date, and the report end date will be the latest transaction, posting, or market price date. Often you will want to see a shorter period, such as the current month. - You can specify a start and/or end date with the -b/--begin, -e/--end, - or -p/--period options, or a date: query argument, described below. + You can specify a start and/or end date with the -b/--begin, -e/--end, + or -p/--period options, or a date: query argument, described below. All of these accept the smart date syntax, also described below. End dates are exclusive; specify the day after the last day you want to see in the report. When dates are specified by multiple options, the last (right-most) op- - tion wins. And when date: queries and date options are combined, the + tion wins. And when date: queries and date options are combined, the report period will be their intersection. Examples: @@ -4451,17 +4476,17 @@ Time periods -b and -e) Smart dates - In hledger's user interfaces (though not in the journal file), you can - optionally use "smart date" syntax. Smart dates can be written with - english words, can be relative, and can have parts omitted. Missing - parts are inferred as 1, when needed. Smart dates can be interpreted + In hledger's user interfaces (though not in the journal file), you can + optionally use "smart date" syntax. Smart dates can be written with + english words, can be relative, and can have parts omitted. Missing + parts are inferred as 1, when needed. Smart dates can be interpreted as dates or periods depending on context. Examples: 2004-01-01, 2004/10/1, 2004.9.1, 20240504 : - Exact dates. The year must have at least four digits, the month must - be 1-12, the day must be 1-31, the separator can be - or / or . or + Exact dates. The year must have at least four digits, the month must + be 1-12, the day must be 1-31, the separator can be - or / or . or nothing. 2004-10 @@ -4494,7 +4519,7 @@ Time periods 201812 6 digit YYYYMM with valid year and month - Dates with no separators are allowed but might give surprising results + Dates with no separators are allowed but might give surprising results if mistyped: o 20181301 (YYYYMMDD with an invalid month) is parsed as an eight-digit @@ -4502,20 +4527,20 @@ Time periods o 20181232 (YYYYMMDD with an invalid day) gives a parse error - o 201801012 (a valid YYYYMMDD followed by additional digits) gives a + o 201801012 (a valid YYYYMMDD followed by additional digits) gives a parse error - The meaning of relative dates depends on today's date. If you need to - test or reproduce old reports, you can use the --today option to over- - ride that. (Except for periodic transaction rules, which are not af- + The meaning of relative dates depends on today's date. If you need to + test or reproduce old reports, you can use the --today option to over- + ride that. (Except for periodic transaction rules, which are not af- fected by --today.) Report intervals - A report interval can be specified so that reports like register, bal- + A report interval can be specified so that reports like register, bal- ance or activity become multi-period, showing each subperiod as a sepa- rate row or column. - The following standard intervals can be enabled with command-line + The following standard intervals can be enabled with command-line flags: o -D/--daily @@ -4528,27 +4553,64 @@ Time periods o -Y/--yearly - More complex intervals can be specified using -p/--period, described + 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.) - o an inferred start date will be adjusted earlier if needed to fall on - a natural period boundary + For example, if the journal's first transaction is on january 10th, - 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 (no report interval) will start the report on janu- + ary 10th. - 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 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. + + For example, if the journal's last transaction is on february 20th, + + o hledger register will end the report on february 20th. + + 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- @@ -4637,7 +4699,7 @@ Time periods 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) @@ -5065,7 +5127,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 @@ -5981,8 +6043,6 @@ Value reporting starting balance. PART 4: COMMANDS - - 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. @@ -6174,24 +6234,21 @@ Data entry commands 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. o If you make a mistake, enter < at any prompt to go one step backward. - o Input prompts are displayed in a different colour when the terminal + o Input prompts are displayed in a different colour when the terminal supports it. Notes: o If you enter a number with no commodity symbol, and you have declared - a default commodity with a D directive, you might expect add to add - this symbol for you. It does not do this; we assume that if you are - using a D directive you prefer not to see the commodity symbol re- + a default commodity with a D directive, you might expect add to add + this symbol for you. It does not do this; we assume that if you are + using a D directive you prefer not to see the commodity symbol re- peated on amounts in the journal. Examples: @@ -6212,14 +6269,14 @@ Data entry commands There is a detailed tutorial at https://hledger.org/add.html. import - Import new transactions from one or more data files to the main jour- + Import new transactions from one or more data files to the main jour- nal. Flags: --catchup just mark all transactions as already imported --dry-run just show the transactions to be imported - This command detects new transactions in each FILE argument since it + This command detects new transactions in each FILE argument since it was last run, and appends them to the main journal. Or with --dry-run, it just print the transactions that would be added. @@ -6230,31 +6287,31 @@ Data entry commands This is one of the few hledger commands that writes to the journal file (see also add). It only appends; existing data will not be changed. - The input files are specified as arguments, so to import one or more + The input files are specified as arguments, so to import one or more CSV files to your main journal, you will run hledger import bank.csv or perhaps hledger import *.csv. Note you can import from any file format, though CSV files are the most - common import source, and these docs focus on that case. The target + common import source, and these docs focus on that case. The target file (main journal) should be in journal format. Date skipping - import tries to import only the transactions which are new since the - last import, ignoring any that it has seen in previous runs. So if - your bank's CSV includes the last three months of data, you can down- - load and import it every month (or week, or day) and only the new + import tries to import only the transactions which are new since the + last import, ignoring any that it has seen in previous runs. So if + your bank's CSV includes the last three months of data, you can down- + load and import it every month (or week, or day) and only the new transactions will be imported each time. It works as follows: for each imported FILE, - o It tries to read the latest date previously seen, from .latest.FILE + o It tries to read the latest date previously seen, from .latest.FILE in the same directory o Then it processes FILE, ignoring transactions on or before that date - And after a successful import, unless --dry-run was used, it updates - the .latest.FILE(s) for next time. This is a simple system that works - for most real-world CSV files; it assumes the following are true, or + And after a successful import, unless --dry-run was used, it updates + the .latest.FILE(s) for next time. This is a simple system that works + for most real-world CSV files; it assumes the following are true, or true enough: 1. the name of the input file is stable across successive downloads @@ -6267,36 +6324,36 @@ Data entry commands Tips: - o To help ensure a stable file name, remember you can use a CSV rules + o To help ensure a stable file name, remember you can use a CSV rules file as an input file. - o If you have a bank whose CSV dates or ordering occasionally change, - you can reduce the chance of this happening in new transactions by - importing more often. (If it happens in old transactions, that's + o If you have a bank whose CSV dates or ordering occasionally change, + you can reduce the chance of this happening in new transactions by + importing more often. (If it happens in old transactions, that's harmless.) - Note this is just one kind of "deduplication": not reprocessing the - same dates across successive runs. import doesn't detect other kinds - of duplication, such as the same transaction appearing multiple times - within a single run, or a new transaction that looks identical to a - transaction already in the journal. (Because these can happen legiti- + Note this is just one kind of "deduplication": not reprocessing the + same dates across successive runs. import doesn't detect other kinds + of duplication, such as the same transaction appearing multiple times + within a single run, or a new transaction that looks identical to a + transaction already in the journal. (Because these can happen legiti- mately in real-world data.) - Here's a situation where you need to run import with care: say you + Here's a situation where you need to run import with care: say you download but forget to import bank.1.csv, and a week later you download - bank.2.csv with some overlapping data. You should not process both of - these as a single import (hledger import bank.1.csv bank.2.csv), be- + bank.2.csv with some overlapping data. You should not process both of + these as a single import (hledger import bank.1.csv bank.2.csv), be- cause the overlapping transactions would not be deduplicated. Instead, import one file at a time, using the same filename each time: $ mv bank.1.csv bank.csv; hledger import bank.csv $ mv bank.2.csv bank.csv; hledger import bank.csv - Normally you don't need to think about .latest.* files, but you can - create or modify them to catch up to a certain date, or delete them to - mark all transactions as new. Their format is a single ISO-format + Normally you don't need to think about .latest.* files, but you can + create or modify them to catch up to a certain date, or delete them to + mark all transactions as new. Their format is a single ISO-format YYYY-MM-DD date, optionally repeated on multiple lines, meaning "I have - seen the transactions before this date, and this many of them on this + seen the transactions before this date, and this many of them on this date". hledger print --new also uses and updates these .latest.* files, but it @@ -6305,10 +6362,10 @@ Data entry commands Related: CSV > Working with CSV > Deduplicating, importing. Import testing - With --dry-run, the transactions that will be imported are printed to + With --dry-run, the transactions that will be imported are printed to the terminal, without updating your journal or state files. The output - is valid journal format, like the print command, so you can re-parse - it. Eg, to see any importable transactions which CSV rules have not + is valid journal format, like the print command, so you can re-parse + it. Eg, to see any importable transactions which CSV rules have not categorised: $ hledger import --dry bank.csv | hledger -f- -I print unknown @@ -6324,22 +6381,22 @@ Data entry commands do a --dry-run first and fix any problems before the real import. Importing balance assignments - Entries added by import will have their posting amounts made explicit - (like hledger print -x). This means that any balance assignments in - imported files must be evaluated; but, imported files don't get to see - the main file's account balances. As a result, importing entries with + Entries added by import will have their posting amounts made explicit + (like hledger print -x). This means that any balance assignments in + imported files must be evaluated; but, imported files don't get to see + the main file's account balances. As a result, importing entries with balance assignments (eg from an institution that provides only balances - and not posting amounts) will probably generate incorrect posting + and not posting amounts) will probably generate incorrect posting amounts. To avoid this problem, use print instead of import: $ hledger print IMPORTFILE [--new] >> $LEDGER_FILE - (If you think import should leave amounts implicit like print does, + (If you think import should leave amounts implicit like print does, please test it and send a pull request.) Import and commodity styles - Amounts in entries added by import will be formatted according to the - journal's canonical commodity styles, as declared by commodity direc- + Amounts in entries added by import will be formatted according to the + journal's canonical commodity styles, as declared by commodity direc- tives or inferred from the journal's amounts. Related: CSV > Amount decimal places. @@ -6363,38 +6420,38 @@ Basic report commands -t --tree show accounts as a tree --drop=N flat mode: omit N leading account name parts - This command lists account names. By default it shows all known ac- - counts, either used in transactions or declared with account direc- + This command lists account names. By default it shows all known ac- + counts, either used in transactions or declared with account direc- tives. With query arguments, only matched account names and account names ref- erenced by matched postings are shown. - Or it can show just the used accounts (--used/-u), the declared ac- - counts (--declared/-d), the accounts declared but not used (--unused), + Or it can show just the used accounts (--used/-u), the declared ac- + counts (--declared/-d), the accounts declared but not used (--unused), the accounts used but not declared (--undeclared), or the first account matched by an account name pattern, if any (--find). - It shows a flat list by default. With --tree, it uses indentation to - show the account hierarchy. In flat mode you can add --drop N to omit - the first few account name components. Account names can be + It shows a flat list by default. With --tree, it uses indentation to + show the account hierarchy. In flat mode you can add --drop N to omit + the first few account name components. Account names can be depth-clipped with depth:N or --depth N or -N. - With --types, it also shows each account's type, if it's known. (See + With --types, it also shows each account's type, if it's known. (See Declaring accounts > Account types.) - With --positions, it also shows the file and line number of each ac- - count's declaration, if any, and the account's overall declaration or- + With --positions, it also shows the file and line number of each ac- + count's declaration, if any, and the account's overall declaration or- der; these may be useful when troubleshooting account display order. - With --directives, it adds the account keyword, showing valid account + With --directives, it adds the account keyword, showing valid account directives which can be pasted into a journal file. This is useful to- - gether with --undeclared when updating your account declarations to + gether with --undeclared when updating your account declarations to satisfy hledger check accounts. - The --find flag can be used to look up a single account name, in the - same way that the aregister command does. It returns the alphanumeri- - cally-first matched account name, or if none can be found, it fails + The --find flag can be used to look up a single account name, in the + same way that the aregister command does. It returns the alphanumeri- + cally-first matched account name, or if none can be found, it fails with a non-zero exit code. Examples: @@ -6418,13 +6475,13 @@ Basic report commands Flags: no command-specific flags - This command prints the value of each transaction's code field, in the - order transactions were parsed. The transaction code is an optional - value written in parentheses between the date and description, often + This command prints the value of each transaction's code field, in the + order transactions were parsed. The transaction code is an optional + value written in parentheses between the date and description, often used to store a cheque number, order number or similar. Transactions aren't required to have a code, and missing or empty codes - will not be shown by default. With the -E/--empty flag, they will be + will not be shown by default. With the -E/--empty flag, they will be printed as blank lines. You can add a query to select a subset of transactions. @@ -6471,7 +6528,7 @@ Basic report commands no command-specific flags This command lists the unique descriptions that appear in transactions, - in alphabetic order. You can add a query to select a subset of trans- + in alphabetic order. You can add a query to select a subset of trans- actions. Example: @@ -6482,7 +6539,7 @@ Basic report commands Person A files - List all files included in the journal. With a REGEX argument, only + List all files included in the journal. With a REGEX argument, only file names matching the regular expression (case sensitive) are shown. Flags: @@ -6495,8 +6552,8 @@ Basic report commands no command-specific flags This command lists the unique notes that appear in transactions, in al- - phabetic order. You can add a query to select a subset of transac- - tions. The note is the part of the transaction description after a | + phabetic order. You can add a query to select a subset of transac- + tions. The note is the part of the transaction description after a | character (or if there is no |, the whole description). Example: @@ -6512,14 +6569,14 @@ Basic report commands --declared show payees declared with payee directives --used show payees referenced by transactions - This command lists unique payee/payer names which have been declared - with payee directives (--declared), used in transaction descriptions + This command lists unique payee/payer names which have been declared + with payee directives (--declared), used in transaction descriptions (--used), or both (the default). - The payee/payer is the part of the transaction description before a | + The payee/payer is the part of the transaction description before a | character (or if there is no |, the whole description). - You can add query arguments to select a subset of transactions. This + You can add query arguments to select a subset of transactions. This implies --used. Example: @@ -6530,8 +6587,8 @@ Basic report commands Person A prices - Print the market prices declared with P directives. With --infer-mar- - ket-prices, also show any additional prices inferred from costs. With + Print the market prices declared with P directives. With --infer-mar- + ket-prices, also show any additional prices inferred from costs. With --show-reverse, also show additional prices inferred by reversing known prices. @@ -6539,14 +6596,14 @@ Basic report commands --show-reverse also show the prices inferred by reversing known prices - Price amounts are always displayed with their full precision, except + Price amounts are always displayed with their full precision, except for reverse prices which are limited to 8 decimal digits. Prices can be filtered by a date:, cur: or amt: query. Generally if you run this command with --infer-market-prices --show-re- - verse, it will show the same prices used internally to calculate value - reports. But if in doubt, you can inspect those directly by running + verse, it will show the same prices used internally to calculate value + reports. But if in doubt, you can inspect those directly by running the value report with --debug=2. stats @@ -6557,10 +6614,10 @@ Basic report commands -o --output-file=FILE write output to FILE. The stats command shows summary information for the whole journal, or a - matched part of it. With a reporting interval, it shows a report for + matched part of it. With a reporting interval, it shows a report for each report period. - The default output is fairly impersonal, though it reveals the main + The default output is fairly impersonal, though it reveals the main file name. With -v/--verbose, more details are shown, like file paths, included files, and commodity names. @@ -6572,8 +6629,8 @@ Basic report commands o live: the peak memory in use by the program to do its work - o alloc: the peak memory allocation from the OS as seen by GHC. Mea- - suring this externally, eg with GNU time, is more accurate; usually + o alloc: the peak memory allocation from the OS as seen by GHC. Mea- + suring this externally, eg with GNU time, is more accurate; usually that will be a larger number; sometimes (with swapping?) smaller. The stats command's run time is similar to that of a balance report. @@ -6594,7 +6651,7 @@ Basic report commands Market prices : 1000 Runtime stats : 0.12 s elapsed, 8266 txns/s, 4 MB live, 16 MB alloc - This command supports the -o/--output-file option (but not -O/--out- + This command supports the -o/--output-file option (but not -O/--out- put-format). tags @@ -6608,22 +6665,22 @@ Basic report commands This command lists the tag names used in the journal, whether on trans- actions, postings, or account declarations. - With a TAGREGEX argument, only tag names matching this regular expres- + With a TAGREGEX argument, only tag names matching this regular expres- sion (case insensitive, infix matched) are shown. - With QUERY arguments, only transactions and accounts matching this + With QUERY arguments, only transactions and accounts matching this query are considered. If the query involves transaction fields (date:, desc:, amt:, ...), the search is restricted to the matched transactions and their accounts. - With the --values flag, the tags' unique non-empty values are listed + With the --values flag, the tags' unique non-empty values are listed instead. With -E/--empty, blank/empty values are also shown. - With --parsed, tags or values are shown in the order they were parsed, - with duplicates included. (Except, tags from account declarations are + With --parsed, tags or values are shown in the order they were parsed, + with duplicates included. (Except, tags from account declarations are always shown first.) - Tip: remember, accounts also acquire tags from their parents, postings + Tip: remember, accounts also acquire tags from their parents, postings also acquire tags from their account and transaction, transactions also acquire tags from their postings. @@ -6657,9 +6714,9 @@ Standard report commands The print command displays full journal entries (transactions) from the journal file, sorted by date (or with --date2, by secondary date). - Directives and inter-transaction comments are not shown, currently. + Directives and inter-transaction comments are not shown, currently. This means the print command is somewhat lossy, and if you are using it - to reformat/regenerate your journal you should take care to also copy + to reformat/regenerate your journal you should take care to also copy over the directives and inter-transaction comments. Eg: @@ -6679,55 +6736,55 @@ Standard report commands assets:cash $-2 print explicitness - Normally, whether posting amounts are implicit or explicit is pre- + Normally, whether posting amounts are implicit or explicit is pre- served. For example, when an amount is omitted in the journal, it will - not appear in the output. Similarly, if a conversion cost is implied + not appear in the output. Similarly, if a conversion cost is implied but not written, it will not appear in the output. - You can use the -x/--explicit flag to force explicit display of all - amounts and costs. This can be useful for troubleshooting or for mak- - ing your journal more readable and robust against data entry errors. + You can use the -x/--explicit flag to force explicit display of all + amounts and costs. This can be useful for troubleshooting or for mak- + ing your journal more readable and robust against data entry errors. -x is also implied by using any of -B,-V,-X,--value. - The -x/--explicit flag will cause any postings with a multi-commodity - amount (which can arise when a multi-commodity transaction has an im- - plicit amount) to be split into multiple single-commodity postings, + The -x/--explicit flag will cause any postings with a multi-commodity + amount (which can arise when a multi-commodity transaction has an im- + plicit amount) to be split into multiple single-commodity postings, keeping the output parseable. print amount style - Amounts are shown right-aligned within each transaction (but not - aligned across all transactions; you can do that with ledger-mode in + Amounts are shown right-aligned within each transaction (but not + aligned across all transactions; you can do that with ledger-mode in Emacs). - Amounts will be (mostly) normalised to their commodity display style: - their symbol placement, decimal mark, and digit group marks will be - made consistent. By default, decimal digits are shown as they are + Amounts will be (mostly) normalised to their commodity display style: + their symbol placement, decimal mark, and digit group marks will be + made consistent. By default, decimal digits are shown as they are written in the journal. - With the --round (Added in 1.32) option, print will try increasingly - hard to display decimal digits according to the commodity display + With the --round (Added in 1.32) option, print will try increasingly + hard to display decimal digits according to the commodity display styles: o --round=none show amounts with original precisions (default) o --round=soft add/remove decimal zeros in amounts (except costs) - o --round=hard round amounts (except costs), possibly hiding signifi- + o --round=hard round amounts (except costs), possibly hiding signifi- cant digits o --round=all round all amounts and costs - soft is good for non-lossy cleanup, formatting amounts more consis- + soft is good for non-lossy cleanup, formatting amounts more consis- tently where it's safe to do so. - hard and all can cause print to show invalid unbalanced journal en- - tries; they may be useful eg for stronger cleanup, with manual fixups + hard and all can cause print to show invalid unbalanced journal en- + tries; they may be useful eg for stronger cleanup, with manual fixups when needed. print parseability - print's output is usually a valid hledger journal, and you can process + print's output is usually a valid hledger journal, and you can process it again with a second hledger command. This can be useful for certain - kinds of search (though the same can be achieved with expr: queries + kinds of search (though the same can be achieved with expr: queries now): # Show running total of food expenses paid from cash. @@ -6736,7 +6793,7 @@ Standard report commands There are some situations where print's output can become unparseable: - o Value reporting affects posting amounts but not balance assertion or + o Value reporting affects posting amounts but not balance assertion or balance assignment amounts, potentially causing those to fail. o Auto postings can generate postings with too many missing amounts. @@ -6747,37 +6804,37 @@ Standard report commands With -B/--cost, amounts with costs are shown converted to cost. With --new, print shows only transactions it has not seen on a previous - run. This uses the same deduplication system as the import command. + run. This uses the same deduplication system as the import command. (See import's docs for details.) With -m DESC/--match=DESC, print shows one recent transaction whose de- - scription is most similar to DESC. DESC should contain at least two - characters. If there is no similar-enough match, no transaction will + scription is most similar to DESC. DESC should contain at least two + characters. If there is no similar-enough match, no transaction will be shown and the program exit code will be non-zero. print output format This command also supports the output destination and output format op- - tions The output formats supported are txt, beancount (Added in 1.32), + tions The output formats supported are txt, beancount (Added in 1.32), csv, tsv (Added in 1.32), json and sql. - The beancount format tries to produce Beancount-compatible output, as + The beancount format tries to produce Beancount-compatible output, as follows: - o Transaction and postings with unmarked status are converted to + o Transaction and postings with unmarked status are converted to cleared (*) status. - o Transactions' payee and note are backslash-escaped and dou- + o Transactions' payee and note are backslash-escaped and dou- ble-quote-escaped and wrapped in double quotes. o Transaction tags are copied to Beancount #tag format. - o Commodity symbols are converted to upper case, and a small number of - currency symbols like $ are converted to the corresponding currency + o Commodity symbols are converted to upper case, and a small number of + currency symbols like $ are converted to the corresponding currency names. o Account name parts are capitalised and unsupported characters are re- placed with -. If an account name part does not begin with a letter, - or if the first part is not Assets, Liabilities, Equity, Income, or + or if the first part is not Assets, Liabilities, Equity, Income, or Expenses, an error is raised. (Use --alias options to bring your ac- counts into compliance.) @@ -6810,26 +6867,26 @@ Standard report commands "5","2008/12/31","","*","","pay off","","liabilities:debts","1","$","","1","","" "5","2008/12/31","","*","","pay off","","assets:bank:checking","-1","$","1","","","" - o There is one CSV record per posting, with the parent transaction's + o There is one CSV record per posting, with the parent transaction's fields repeated. o The "txnidx" (transaction index) field shows which postings belong to - the same transaction. (This number might change if transactions are - reordered within the file, files are parsed/included in a different + the same transaction. (This number might change if transactions are + reordered within the file, files are parsed/included in a different order, etc.) - o The amount is separated into "commodity" (the symbol) and "amount" + o The amount is separated into "commodity" (the symbol) and "amount" (numeric quantity) fields. o The numeric amount is repeated in either the "credit" or "debit" col- - umn, for convenience. (Those names are not accurate in the account- - ing sense; it just puts negative amounts under credit and zero or + umn, for convenience. (Those names are not accurate in the account- + ing sense; it just puts negative amounts under credit and zero or greater amounts under debit.) aregister (areg) - Show the transactions and running balances in one account, with each + Show the transactions and running balances in one account, with each transaction on one line. Flags: @@ -6846,58 +6903,58 @@ Standard report commands one of the above formats selects that format. aregister shows the overall transactions affecting a particular account - (and any subaccounts). Each report line represents one transaction in + (and any subaccounts). Each report line represents one transaction in this account. Transactions before the report start date are always in- cluded in the running balance (--historical mode is always on). - This is a more "real world", bank-like view than the register command - (which shows individual postings, possibly from multiple accounts, not + This is a more "real world", bank-like view than the register command + (which shows individual postings, possibly from multiple accounts, not necessarily in historical mode). As a quick rule of thumb: - use areg- ister for reviewing and reconciling real-world asset/liability accounts - use register for reviewing detailed revenues/expenses. - aregister requires one argument: the account to report on. You can - write either the full account name, or a case-insensitive regular ex- + aregister requires one argument: the account to report on. You can + write either the full account name, or a case-insensitive regular ex- pression which will select the alphabetically first matched account. When there are multiple matches, the alphabetically-first choice can be - surprising; eg if you have assets:per:checking 1 and assets:biz:check- - ing 2 accounts, hledger areg checking would select assets:biz:checking - 2. It's just a convenience to save typing, so if in doubt, write the + surprising; eg if you have assets:per:checking 1 and assets:biz:check- + ing 2 accounts, hledger areg checking would select assets:biz:checking + 2. It's just a convenience to save typing, so if in doubt, write the full account name, or a distinctive substring that matches uniquely. - Transactions involving subaccounts of this account will also be shown. - aregister ignores depth limits, so its final total will always match a + Transactions involving subaccounts of this account will also be shown. + aregister ignores depth limits, so its final total will always match a balance report with similar arguments. - Any additional arguments form a query which will filter the transac- + Any additional arguments form a query which will filter the transac- tions shown. Note some queries will disturb the running balance, caus- ing it to be different from the account's real-world running balance. - An example: this shows the transactions and historical running balance + An example: this shows the transactions and historical running balance during july, in the first account whose name contains "checking": $ hledger areg checking date:jul Each aregister line item shows: - o the transaction's date (or the relevant posting's date if different, + o the transaction's date (or the relevant posting's date if different, see below) - o the names of all the other account(s) involved in this transaction + o the names of all the other account(s) involved in this transaction (probably abbreviated) o the total change to this account's balance from this transaction o the account's historical running balance after this transaction. - Transactions making a net change of zero are not shown by default; add + Transactions making a net change of zero are not shown by default; add the -E/--empty flag to show them. - For performance reasons, column widths are chosen based on the first - 1000 lines; this means unusually wide values in later lines can cause - visual discontinuities as column widths are adjusted. If you want to - ensure perfect alignment, at the cost of more time and memory, use the + For performance reasons, column widths are chosen based on the first + 1000 lines; this means unusually wide values in later lines can cause + visual discontinuities as column widths are adjusted. If you want to + ensure perfect alignment, at the cost of more time and memory, use the --align-all flag. This command also supports the output destination and output format op- @@ -6905,13 +6962,13 @@ Standard report commands and json. aregister and posting dates - aregister always shows one line (and date and amount) per transaction. - But sometimes transactions have postings with different dates. Also, - not all of a transaction's postings may be within the report period. + aregister always shows one line (and date and amount) per transaction. + But sometimes transactions have postings with different dates. Also, + not all of a transaction's postings may be within the report period. To resolve this, aregister shows the earliest of the transaction's date and posting dates that is in-period, and the sum of the in-period post- - ings. In other words it will show a combined line item with just the - earliest date, and the running balance will (temporarily, until the + ings. In other words it will show a combined line item with just the + earliest date, and the running balance will (temporarily, until the transaction's last posting) be inaccurate. Use register -H if you need to see the individual postings. @@ -6935,6 +6992,9 @@ Standard report commands description closest to DESC -r --related show postings' siblings instead --invert display all amounts with reversed sign + --sort=FIELDS sort by: date, desc, account, amount, absamount, + or a comma-separated combination of these. For a + descending sort, prefix with -. (Default: date) -w --width=N set output width (default: terminal width or $COLUMNS). -wN,M sets description width as well. --align-all guarantee alignment across all lines (slower) @@ -6944,14 +7004,14 @@ Standard report commands one of the above formats selects that format. The register command displays matched postings, across all accounts, in - date order, with their running total or running historical balance. - (See also the aregister command, which shows matched transactions in a + date order, with their running total or running historical balance. + (See also the aregister command, which shows matched transactions in a specific account.) register normally shows line per posting, but note that multi-commodity amounts will occupy multiple lines (one line per commodity). - It is typically used with a query selecting a particular account, to + It is typically used with a query selecting a particular account, to see that account's activity: $ hledger register checking @@ -6962,14 +7022,14 @@ Standard report commands With --date2, it shows and sorts by secondary date instead. - For performance reasons, column widths are chosen based on the first - 1000 lines; this means unusually wide values in later lines can cause - visual discontinuities as column widths are adjusted. If you want to - ensure perfect alignment, at the cost of more time and memory, use the + For performance reasons, column widths are chosen based on the first + 1000 lines; this means unusually wide values in later lines can cause + visual discontinuities as column widths are adjusted. If you want to + ensure perfect alignment, at the cost of more time and memory, use the --align-all flag. - The --historical/-H flag adds the balance from any undisplayed prior - postings to the running total. This is useful when you want to see + The --historical/-H flag adds the balance from any undisplayed prior + postings to the running total. This is useful when you want to see only recent activity, with a historically accurate running balance: $ hledger register checking -b 2008/6 --historical @@ -6979,20 +7039,27 @@ Standard report commands The --depth option limits the amount of sub-account detail displayed. - The --average/-A flag shows the running average posting amount instead + The --average/-A flag shows the running average posting amount instead of the running total (so, the final number displayed is the average for - the whole report period). This flag implies --empty (see below). It - is affected by --historical. It works best when showing just one ac- + the whole report period). This flag implies --empty (see below). It + is affected by --historical. It works best when showing just one ac- count and one commodity. - The --related/-r flag shows the other postings in the transactions of + The --related/-r flag shows the other postings in the transactions of the postings which would normally be shown. - The --invert flag negates all amounts. For example, it can be used on + The --invert flag negates all amounts. For example, it can be used on an income account where amounts are normally displayed as negative num- - bers. It's also useful to show postings on the checking account to- + bers. It's also useful to show postings on the checking account to- gether with the related account: + The --sort=FIELDS flag sorts by the fields given, which can be any of + account, amount, absamount, date, or desc/description, optionally sepa- + rated by commas. For example, --sort account,amount will group all + transactions in each account, sorted by transaction amount. Each field + can be negated by a preceding -, so --sort -amount will show transac- + tions ordered from smallest amount to largest amount. + $ hledger register --related --invert assets:checking With a reporting interval, register shows summary postings, one per in- @@ -7498,7 +7565,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 +7649,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 +9665,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.99 September 2024 HLEDGER(1)