diff --git a/hledger-ui/hledger-ui.1 b/hledger-ui/hledger-ui.1 index 36716f85c..55d51a541 100644 --- a/hledger-ui/hledger-ui.1 +++ b/hledger-ui/hledger-ui.1 @@ -1,5 +1,5 @@ -.TH "HLEDGER-UI" "1" "September 2021" "hledger-ui-1.22.99 " "hledger User Manuals" +.TH "HLEDGER-UI" "1" "September 2021" "hledger-ui-1.23 " "hledger User Manuals" @@ -7,7 +7,7 @@ .PP hledger-ui is a terminal interface (TUI) for the hledger accounting tool. -This manual is for hledger-ui 1.22.99. +This manual is for hledger-ui 1.23. .SH SYNOPSIS .PP \f[C]hledger-ui [OPTIONS] [QUERYARGS]\f[R] @@ -185,6 +185,14 @@ terminal. into \[aq]less -R\[aq]. \[aq]never\[aq] or \[aq]no\[aq]: never. A NO_COLOR environment variable overrides this. +.TP +\f[B]\f[CB]--pretty[=WHEN]\f[B]\f[R] +Show prettier output, e.g. +using unicode box-drawing characters. +Accepts \[aq]yes\[aq] (the default) or \[aq]no\[aq] (\[aq]y\[aq], +\[aq]n\[aq], \[aq]always\[aq], \[aq]never\[aq] also work). +If you provide an argument you must use \[aq]=\[aq], e.g. +\[aq]--pretty=yes\[aq]. .PP When a reporting option appears more than once in the command line, the last one takes precedence. diff --git a/hledger-ui/hledger-ui.info b/hledger-ui/hledger-ui.info index 0e9ac429d..7e45c9765 100644 --- a/hledger-ui/hledger-ui.info +++ b/hledger-ui/hledger-ui.info @@ -12,7 +12,7 @@ hledger-ui(1) ************* hledger-ui is a terminal interface (TUI) for the hledger accounting -tool. This manual is for hledger-ui 1.22.99. +tool. This manual is for hledger-ui 1.23. 'hledger-ui [OPTIONS] [QUERYARGS]' 'hledger ui -- [OPTIONS] [QUERYARGS]' @@ -204,6 +204,12 @@ the data. color-supporting terminal. 'always' or 'yes': always, useful eg when piping output into 'less -R'. 'never' or 'no': never. A NO_COLOR environment variable overrides this. +'--pretty[=WHEN]' + + Show prettier output, e.g. using unicode box-drawing characters. + Accepts 'yes' (the default) or 'no' ('y', 'n', 'always', 'never' + also work). If you provide an argument you must use '=', e.g. + '-pretty=yes'. When a reporting option appears more than once in the command line, the last one takes precedence. @@ -602,32 +608,32 @@ program is restarted.  Tag Table: Node: Top221 -Node: OPTIONS1647 -Ref: #options1744 -Node: KEYS6375 -Ref: #keys6470 -Node: SCREENS10541 -Ref: #screens10639 -Node: Accounts screen10729 -Ref: #accounts-screen10857 -Node: Register screen13072 -Ref: #register-screen13227 -Node: Transaction screen15224 -Ref: #transaction-screen15382 -Node: Error screen16252 -Ref: #error-screen16374 -Node: TIPS16618 -Ref: #tips16717 -Node: Watch mode16769 -Ref: #watch-mode16886 -Node: Watch mode limitations17632 -Ref: #watch-mode-limitations17773 -Node: ENVIRONMENT18909 -Ref: #environment19020 -Node: FILES19827 -Ref: #files19926 -Node: BUGS20139 -Ref: #bugs20216 +Node: OPTIONS1644 +Ref: #options1741 +Node: KEYS6620 +Ref: #keys6715 +Node: SCREENS10786 +Ref: #screens10884 +Node: Accounts screen10974 +Ref: #accounts-screen11102 +Node: Register screen13317 +Ref: #register-screen13472 +Node: Transaction screen15469 +Ref: #transaction-screen15627 +Node: Error screen16497 +Ref: #error-screen16619 +Node: TIPS16863 +Ref: #tips16962 +Node: Watch mode17014 +Ref: #watch-mode17131 +Node: Watch mode limitations17877 +Ref: #watch-mode-limitations18018 +Node: ENVIRONMENT19154 +Ref: #environment19265 +Node: FILES20072 +Ref: #files20171 +Node: BUGS20384 +Ref: #bugs20461  End Tag Table diff --git a/hledger-ui/hledger-ui.txt b/hledger-ui/hledger-ui.txt index d49c60d72..f3203624c 100644 --- a/hledger-ui/hledger-ui.txt +++ b/hledger-ui/hledger-ui.txt @@ -5,7 +5,7 @@ HLEDGER-UI(1) hledger User Manuals HLEDGER-UI(1) NAME hledger-ui is a terminal interface (TUI) for the hledger accounting - tool. This manual is for hledger-ui 1.22.99. + tool. This manual is for hledger-ui 1.23. SYNOPSIS hledger-ui [OPTIONS] [QUERYARGS] @@ -181,6 +181,12 @@ OPTIONS piping output into 'less -R'. 'never' or 'no': never. A NO_COLOR environment variable overrides this. + --pretty[=WHEN] + Show prettier output, e.g. using unicode box-drawing charac- + ters. Accepts 'yes' (the default) or 'no' ('y', 'n', 'always', + 'never' also work). If you provide an argument you must use + '=', e.g. '--pretty=yes'. + When a reporting option appears more than once in the command line, the last one takes precedence. @@ -202,86 +208,86 @@ OPTIONS show debug output (levels 1-9, default: 1) A @FILE argument will be expanded to the contents of FILE, which should - contain one command line option/argument per line. (To prevent this, + contain one command line option/argument per line. (To prevent this, insert a -- argument before.) KEYS - ? shows a help dialog listing all keys. (Some of these also appear in + ? shows a help dialog listing all keys. (Some of these also appear in the quick help at the bottom of each screen.) Press ? again (or ESCAPE, or LEFT, or q) to close it. The following keys work on most screens: The cursor keys navigate: right (or enter) goes deeper, left returns to - the previous screen, up/down/page up/page down/home/end move up and + the previous screen, up/down/page up/page down/home/end move up and down through lists. Emacs-style (ctrl-p/ctrl-n/ctrl-f/ctrl-b) movement - keys are also supported (but not vi-style keys, since hledger-1.19, - sorry!). 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, + keys are also supported (but not vi-style keys, since hledger-1.19, + sorry!). A tip: movement speed is limited by your keyboard repeat + rate, to move faster you may want to adjust it. (If you're on a mac, the karabiner app is one way to do that.) - With shift pressed, the cursor keys adjust the report period, limiting - the transactions to be shown (by default, all are shown). shift- - down/up steps downward and upward through these standard report period - durations: year, quarter, month, week, day. Then, shift-left/right - moves to the previous/next period. T sets the report period to today. - With the --watch option, when viewing a "current" period (the current + 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 --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. - / lets you set a general filter query limiting the data shown, using - the same query terms as in hledger and hledger-web. While editing the - query, you can use CTRL-a/e/d/k, BS, cursor keys; press ENTER to set + / lets you set a general filter query limiting the data shown, using + the same query terms as in hledger and hledger-web. While editing the + query, you can use CTRL-a/e/d/k, BS, cursor keys; press ENTER to set it, or ESCAPEto cancel. There are also keys for quickly adjusting some - common filters like account depth and transaction status (see below). + common filters like account depth and transaction status (see below). BACKSPACE or DELETE removes all filters, showing all transactions. - As mentioned above, by default hledger-ui hides future transactions - + As mentioned above, by default hledger-ui hides future transactions - both ordinary transactions recorded in the journal, and periodic trans- - actions generated by rule. F toggles forecast mode, in which + actions generated by rule. F toggles forecast mode, in which future/forecasted transactions are shown. - 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 + 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. 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 in their transaction price's com- + B toggles cost mode, showing amounts in their transaction price's com- modity (like toggling the -B/--cost flag). - V toggles value mode, showing amounts' current market value in their - default valuation commodity (like toggling the -V/--market flag). - Note, "current market value" means the value on the report end date if - specified, otherwise today. To see the value on another date, you can - temporarily set that as the report end date. Eg: to see a transaction - as it was valued on july 30, go to the accounts or register screen, + V toggles value mode, showing amounts' current market value in their + default valuation commodity (like toggling the -V/--market flag). + Note, "current market value" means the value on the report end date if + specified, otherwise today. To see the value on another date, you can + temporarily set that as the report end date. Eg: to see a transaction + as it was valued on july 30, go to the accounts or register screen, press /, and add date:-7/30 to the query. At most one of cost or value mode can be active at once. - There's not yet any visual reminder when cost or value mode is active; + There's not yet any visual reminder when cost or value mode is active; for now pressing b b v should reliably reset to normal mode. q quits the application. @@ -290,44 +296,44 @@ KEYS SCREENS Accounts screen - This is normally the first screen displayed. It lists accounts and - their balances, like hledger's balance command. By default, it shows - all accounts and their latest ending balances (including the balances - of subaccounts). If you specify a query on the command line, it shows + This is normally the first screen displayed. It lists accounts and + their balances, like hledger's balance command. By default, it shows + all accounts and their latest ending balances (including the balances + of subaccounts). If you specify a query on the command line, it shows just the matched accounts and the balances from matched transactions. - Account names are shown as a flat list by default; press t to toggle - tree mode. In list mode, account balances are exclusive of subac- - counts, except where subaccounts are hidden by a depth limit (see - below). In tree mode, all account balances are inclusive of subac- + Account names are shown as a flat list by default; press t to toggle + tree mode. In list mode, account balances are exclusive of subac- + counts, except where subaccounts are hidden by a depth limit (see + below). In tree mode, all account balances are inclusive of subac- counts. - To see less detail, press a number key, 1 to 9, to set a depth limit. + To see less detail, press a number key, 1 to 9, to set a depth limit. Or use - to decrease and +/= to increase the depth limit. 0 shows even - less detail, collapsing all accounts to a single total. To remove the - depth limit, set it higher than the maximum account depth, or press + less detail, collapsing all accounts to a single total. To remove the + depth limit, set it higher than the maximum account depth, or press ESCAPE. H toggles between showing historical balances or period balances. His- - torical balances (the default) are ending balances at the end of the - report period, taking into account all transactions before that date - (filtered by the filter query if any), including transactions before - the start of the report period. In other words, historical balances - are what you would see on a bank statement for that account (unless - disturbed by a filter query). Period balances ignore transactions + torical balances (the default) are ending balances at the end of the + report period, taking into account all transactions before that date + (filtered by the filter query if any), including transactions before + the start of the report period. In other words, historical balances + are what you would see on a bank statement for that account (unless + disturbed by a filter query). Period balances ignore transactions before the report start date, so they show the change in balance during the report period. They are more useful eg when viewing a time log. U toggles filtering by unmarked status, including or excluding unmarked postings in the balances. Similarly, P toggles pending postings, and C - toggles cleared postings. (By default, balances include all postings; - if you activate one or two status filters, only those postings are + toggles cleared postings. (By default, balances include all postings; + if you activate one or two status filters, only those postings are included; 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 accounts with nonzero balances - are shown (hledger-ui shows zero items by default, unlike command-line + Z toggles nonzero mode, in which only accounts with nonzero balances + are shown (hledger-ui shows zero items by default, unlike command-line hledger). Press right or enter to view an account's transactions register. @@ -336,124 +342,124 @@ SCREENS This screen shows the transactions affecting a particular account, like a check register. 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 historical total or period total for the current account, - after the transaction. This can be toggled with H. Similar to the - accounts screen, the historical total is affected by transactions - (filtered by the filter query) before the report start date, while + after the transaction. This can be toggled with H. Similar to the + accounts screen, the historical total is affected by transactions + (filtered by the filter query) before the report start date, while the period total is not. If the historical total is not disturbed by - a filter query, it will be the running historical balance you would + a filter query, it will be the running historical balance you would see on a bank register for the current account. - 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 (or enter) 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, - description, comments, along with all of its account postings are - shown. Simple transactions have two postings, but there can be more + The transaction's date(s) and any cleared flag, transaction code, + description, 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 + 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 depending on which account register you came from (remember most trans- actions 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). Error screen - This screen will appear if there is a problem, such as a parse error, - when you press g to reload. Once you have fixed the problem, press g + This screen will appear if there is a problem, such as a parse error, + when you press g to reload. Once you have fixed the problem, press g again to reload and resume normal operation. (Or, you can press escape to cancel the reload attempt.) TIPS Watch mode - One of hledger-ui's best features is the auto-reloading --watch mode. - With this flag, it will update the display automatically whenever + One of hledger-ui's best features is the auto-reloading --watch mode. + With this flag, it will update the display automatically whenever 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. Watch mode limitations - There are situations in which it won't work, ie the display will not - update when you save a change (because the underlying inotify library + There are situations in which it won't work, ie the display will not + update when you save a change (because the underlying inotify library does not support it). Here are some that we know of: - o Certain editors: saving with gedit, and perhaps any Gnome applica- - tion, won't be detected (#1617). Jetbrains IDEs, such as IDEA, also + o Certain editors: saving with gedit, and perhaps any Gnome applica- + tion, won't be detected (#1617). Jetbrains IDEs, such as IDEA, also may not work (#911). - o Certain unusual filesystems might not be supported. (All the usual + o Certain unusual filesystems might not be supported. (All the usual ones on unix, mac and windows are supported.) In such cases, the workaround is to switch to the hledger-ui window and - press g each time you want it to reload. (Actually, see #1617 for + press g each time you want it to reload. (Actually, see #1617 for another workaround, and let us know if it works for you.) - If you leave hledger-ui --watch running for days, on certain platforms - (?), perhaps with many transactions in your journal (?), perhaps with - large numbers of other files present (?), you may see it gradually - using more and more memory and CPU over time, as seen in top or Activ- + If you leave hledger-ui --watch running for days, on certain platforms + (?), perhaps with many transactions in your journal (?), perhaps with + large numbers of other files present (?), you may see it gradually + using more and more memory and CPU over time, as seen in top or Activ- ity Monitor or Task Manager. - A workaround is to quit and restart it, or to suspend it (CTRL-z) and + A workaround is to quit and restart it, or to suspend it (CTRL-z) and restart it (fg) if your shell supports that. ENVIRONMENT COLUMNS The screen width to use. Default: the full terminal width. LEDGER_FILE The journal file path when not specified with -f. Default: - ~/.hledger.journal (on windows, perhaps C:/Users/USER/.hledger.jour- + ~/.hledger.journal (on windows, perhaps C:/Users/USER/.hledger.jour- nal). - A typical value is ~/DIR/YYYY.journal, where DIR is a version-con- - trolled finance directory and YYYY is the current year. Or ~/DIR/cur- + A typical value is ~/DIR/YYYY.journal, where DIR is a version-con- + trolled finance directory and YYYY is the current year. Or ~/DIR/cur- rent.journal, where current.journal is a symbolic link to YYYY.journal. On Mac computers, you can set this and other environment variables in a - more thorough way that also affects applications started from the GUI - (say, an Emacs dock icon). Eg on MacOS Catalina I have a + more thorough way that also affects applications started from the GUI + (say, an Emacs dock icon). Eg on MacOS Catalina I have a ~/.MacOSX/environment.plist file containing { @@ -463,13 +469,13 @@ ENVIRONMENT To see the effect you may need to killall Dock, or reboot. FILES - Reads data from one or more files in hledger journal, timeclock, time- - dot, or CSV format specified with -f, or $LEDGER_FILE, or - $HOME/.hledger.journal (on windows, perhaps + Reads data from one or more files in hledger journal, timeclock, time- + dot, or CSV format specified with -f, or $LEDGER_FILE, or + $HOME/.hledger.journal (on windows, perhaps C:/Users/USER/.hledger.journal). BUGS - The need to precede options with -- when invoked from hledger is awk- + The need to precede options with -- when invoked from hledger is awk- ward. -f- doesn't work (hledger-ui can't read from stdin). @@ -477,24 +483,24 @@ BUGS -V affects only the accounts screen. When you press g, the current and all previous screens are regenerated, - which may cause a noticeable pause with large files. Also there is no + which may cause a noticeable pause with large files. Also there is no visual indication that this is in progress. - --watch is not yet fully robust. It works well for normal usage, but - many file changes in a short time (eg saving the file thousands of - times with an editor macro) can cause problems at least on OSX. Symp- - toms include: unresponsive UI, periodic resetting of the cursor posi- + --watch is not yet fully robust. It works well for normal usage, but + many file changes in a short time (eg saving the file thousands of + times with an editor macro) can cause problems at least on OSX. Symp- + toms include: unresponsive UI, periodic resetting of the cursor posi- tion, momentary display of parse errors, high CPU usage eventually sub- siding, and possibly a small but persistent build-up of CPU usage until the program is restarted. - Also, if you are viewing files mounted from another machine, --watch + Also, if you are viewing files mounted from another machine, --watch requires that both machine clocks are roughly in step. REPORTING BUGS - Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel + Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel or hledger mail list) @@ -512,4 +518,4 @@ SEE ALSO -hledger-ui-1.22.99 September 2021 HLEDGER-UI(1) +hledger-ui-1.23 September 2021 HLEDGER-UI(1) diff --git a/hledger-web/hledger-web.1 b/hledger-web/hledger-web.1 index 4e392fbe0..b79aa1fe9 100644 --- a/hledger-web/hledger-web.1 +++ b/hledger-web/hledger-web.1 @@ -1,12 +1,12 @@ -.TH "HLEDGER-WEB" "1" "September 2021" "hledger-web-1.22.99 " "hledger User Manuals" +.TH "HLEDGER-WEB" "1" "September 2021" "hledger-web-1.23 " "hledger User Manuals" .SH NAME .PP hledger-web is a web interface (WUI) for the hledger accounting tool. -This manual is for hledger-web 1.22.99. +This manual is for hledger-web 1.23. .SH SYNOPSIS .PP \f[C]hledger-web [OPTIONS]\f[R] @@ -214,6 +214,14 @@ terminal. into \[aq]less -R\[aq]. \[aq]never\[aq] or \[aq]no\[aq]: never. A NO_COLOR environment variable overrides this. +.TP +\f[B]\f[CB]--pretty[=WHEN]\f[B]\f[R] +Show prettier output, e.g. +using unicode box-drawing characters. +Accepts \[aq]yes\[aq] (the default) or \[aq]no\[aq] (\[aq]y\[aq], +\[aq]n\[aq], \[aq]always\[aq], \[aq]never\[aq] also work). +If you provide an argument you must use \[aq]=\[aq], e.g. +\[aq]--pretty=yes\[aq]. .PP When a reporting option appears more than once in the command line, the last one takes precedence. diff --git a/hledger-web/hledger-web.info b/hledger-web/hledger-web.info index 934508820..b970b01df 100644 --- a/hledger-web/hledger-web.info +++ b/hledger-web/hledger-web.info @@ -12,7 +12,7 @@ hledger-web(1) ************** hledger-web is a web interface (WUI) for the hledger accounting tool. -This manual is for hledger-web 1.22.99. +This manual is for hledger-web 1.23. 'hledger-web [OPTIONS]' 'hledger web -- [OPTIONS]' @@ -230,6 +230,12 @@ before options, as shown in the synopsis above. color-supporting terminal. 'always' or 'yes': always, useful eg when piping output into 'less -R'. 'never' or 'no': never. A NO_COLOR environment variable overrides this. +'--pretty[=WHEN]' + + Show prettier output, e.g. using unicode box-drawing characters. + Accepts 'yes' (the default) or 'no' ('y', 'n', 'always', 'never' + also work). If you provide an argument you must use '=', e.g. + '-pretty=yes'. When a reporting option appears more than once in the command line, the last one takes precedence. @@ -611,22 +617,22 @@ awkward.  Tag Table: Node: Top223 -Node: OPTIONS1889 -Ref: #options1994 -Node: PERMISSIONS9657 -Ref: #permissions9796 -Node: EDITING UPLOADING DOWNLOADING11008 -Ref: #editing-uploading-downloading11189 -Node: RELOADING12023 -Ref: #reloading12157 -Node: JSON API12590 -Ref: #json-api12704 -Node: ENVIRONMENT18194 -Ref: #environment18310 -Node: FILES19043 -Ref: #files19143 -Node: BUGS19356 -Ref: #bugs19434 +Node: OPTIONS1886 +Ref: #options1991 +Node: PERMISSIONS9902 +Ref: #permissions10041 +Node: EDITING UPLOADING DOWNLOADING11253 +Ref: #editing-uploading-downloading11434 +Node: RELOADING12268 +Ref: #reloading12402 +Node: JSON API12835 +Ref: #json-api12949 +Node: ENVIRONMENT18439 +Ref: #environment18555 +Node: FILES19288 +Ref: #files19388 +Node: BUGS19601 +Ref: #bugs19679  End Tag Table diff --git a/hledger-web/hledger-web.txt b/hledger-web/hledger-web.txt index 17acac940..2836cbea4 100644 --- a/hledger-web/hledger-web.txt +++ b/hledger-web/hledger-web.txt @@ -5,7 +5,7 @@ HLEDGER-WEB(1) hledger User Manuals HLEDGER-WEB(1) NAME hledger-web is a web interface (WUI) for the hledger accounting tool. - This manual is for hledger-web 1.22.99. + This manual is for hledger-web 1.23. SYNOPSIS hledger-web [OPTIONS] @@ -204,6 +204,12 @@ OPTIONS piping output into 'less -R'. 'never' or 'no': never. A NO_COLOR environment variable overrides this. + --pretty[=WHEN] + Show prettier output, e.g. using unicode box-drawing charac- + ters. Accepts 'yes' (the default) or 'no' ('y', 'n', 'always', + 'never' also work). If you provide an argument you must use + '=', e.g. '--pretty=yes'. + When a reporting option appears more than once in the command line, the last one takes precedence. @@ -225,54 +231,54 @@ OPTIONS show debug output (levels 1-9, default: 1) A @FILE argument will be expanded to the contents of FILE, which should - contain one command line option/argument per line. (To prevent this, + contain one command line option/argument per line. (To prevent this, insert a -- argument before.) By default, hledger-web starts the web app in "transient mode" and also opens it in your default web browser if possible. In this mode the web app will keep running for as long as you have it open in a browser win- - dow, and will exit after two minutes of inactivity (no requests and no - browser windows viewing it). With --serve, it just runs the web app - without exiting, and logs requests to the console. With --serve-api, - only the JSON web api (see below) is served, with the usual HTML + dow, and will exit after two minutes of inactivity (no requests and no + browser windows viewing it). With --serve, it just runs the web app + without exiting, and logs requests to the console. With --serve-api, + only the JSON web api (see below) is served, with the usual HTML server-side web UI disabled. - By default the server listens on IP address 127.0.0.1, accessible only - to local requests. You can use --host to change this, eg --host + By default the server listens on IP address 127.0.0.1, accessible only + to local requests. You can use --host to change this, eg --host 0.0.0.0 to listen on all configured addresses. - Similarly, use --port to set a TCP port other than 5000, eg if you are + Similarly, use --port to set a TCP port other than 5000, eg if you are running multiple hledger-web instances. Both of these options are ignored when --socket is used. In this case, - it creates an AF_UNIX socket file at the supplied path and uses that - for communication. This is an alternative way of running multiple - hledger-web instances behind a reverse proxy that handles authentica- - tion for different users. The path can be derived in a predictable + it creates an AF_UNIX socket file at the supplied path and uses that + for communication. This is an alternative way of running multiple + hledger-web instances behind a reverse proxy that handles authentica- + tion for different users. The path can be derived in a predictable way, eg by using the username within the path. As an example, nginx as - reverse proxy can use the variable $remote_user to derive a path from - the username used in a HTTP basic authentication. The following - proxy_pass directive allows access to all hledger-web instances that + reverse proxy can use the variable $remote_user to derive a path from + the username used in a HTTP basic authentication. The following + proxy_pass directive allows access to all hledger-web instances that created a socket in /tmp/hledger/: proxy_pass http://unix:/tmp/hledger/${remote_user}.socket; - You can use --base-url to change the protocol, hostname, port and path + You can use --base-url to change the protocol, hostname, port and path that appear in hyperlinks, useful eg for integrating hledger-web within - a larger website. The default is http://HOST:PORT/ using the server's + a larger website. The default is http://HOST:PORT/ using the server's configured host address and TCP port (or http://HOST if PORT is 80). - With --file-url you can set a different base url for static files, eg + With --file-url you can set a different base url for static files, eg for better caching or cookie-less serving on high performance websites. PERMISSIONS - By default, hledger-web allows anyone who can reach it to view the + By default, hledger-web allows anyone who can reach it to view the journal and to add new transactions, but not to change existing data. You can restrict who can reach it by - o setting the IP address it listens on (see --host above). By default - it listens on 127.0.0.1, accessible to all users on the local + o setting the IP address it listens on (see --host above). By default + it listens on 127.0.0.1, accessible to all users on the local machine. o putting it behind an authenticating proxy, using eg apache or nginx @@ -282,53 +288,53 @@ PERMISSIONS You can restrict what the users who reach it can do, by o using the --capabilities=CAP[,CAP..] flag when you start it, enabling - one or more of the following capabilities. The default value is + one or more of the following capabilities. The default value is view,add: o view - allows viewing the journal file and all included files o add - allows adding new transactions to the main journal file - o manage - allows editing, uploading or downloading the main or + o manage - allows editing, uploading or downloading the main or included files - o using the --capabilities-header=HTTPHEADER flag to specify a HTTP - header from which it will read capabilities to enable. hledger-web - on Sandstorm uses the X-Sandstorm-Permissions header to integrate + o using the --capabilities-header=HTTPHEADER flag to specify a HTTP + header from which it will read capabilities to enable. hledger-web + on Sandstorm uses the X-Sandstorm-Permissions header to integrate with Sandstorm's permissions. This is disabled by default. EDITING, UPLOADING, DOWNLOADING - If you enable the manage capability mentioned above, you'll see a new - "spanner" button to the right of the search form. Clicking this will - let you edit, upload, or download the journal file or any files it + If you enable the manage capability mentioned above, you'll see a new + "spanner" button to the right of the search form. Clicking this will + let you edit, upload, or download the journal file or any files it includes. - Note, unlike any other hledger command, in this mode you (or any visi- + Note, unlike any other hledger command, in this mode you (or any visi- tor) can alter or wipe the data files. - Normally whenever a file is changed in this way, hledger-web saves a - numbered backup (assuming file permissions allow it, the disk is not - full, etc.) hledger-web is not aware of version control systems, cur- - rently; if you use one, you'll have to arrange to commit the changes + Normally whenever a file is changed in this way, hledger-web saves a + numbered backup (assuming file permissions allow it, the disk is not + full, etc.) hledger-web is not aware of version control systems, cur- + rently; if you use one, you'll have to arrange to commit the changes yourself (eg with a cron job or a file watcher like entr). - Changes which would leave the journal file(s) unparseable or non-valid - (eg with failing balance assertions) are prevented. (Probably. This + Changes which would leave the journal file(s) unparseable or non-valid + (eg with failing balance assertions) are prevented. (Probably. This needs re-testing.) RELOADING hledger-web detects changes made to the files by other means (eg if you - edit it directly, outside of hledger-web), and it will show the new - data when you reload the page or navigate to a new page. If a change - makes a file unparseable, hledger-web will display an error message + edit it directly, outside of hledger-web), and it will show the new + data when you reload the page or navigate to a new page. If a change + makes a file unparseable, hledger-web will display an error message until the file has been fixed. (Note: if you are viewing files mounted from another machine, make sure that both machine clocks are roughly in step.) JSON API - In addition to the web UI, hledger-web also serves a JSON API that can - be used to get data or add new transactions. If you want the JSON API + In addition to the web UI, hledger-web also serves a JSON API that can + be used to get data or add new transactions. If you want the JSON API only, you can use the --serve-api flag. Eg: $ hledger-web -f examples/sample.journal --serve-api @@ -345,7 +351,7 @@ JSON API /accounttransactions/ACCOUNTNAME Eg, all account names in the journal (similar to the accounts command). - (hledger-web's JSON does not include newlines, here we use python to + (hledger-web's JSON does not include newlines, here we use python to prettify it): $ curl -s http://127.0.0.1:5000/accountnames | python -m json.tool @@ -386,25 +392,25 @@ JSON API "aprice": null, ... - Most of the JSON corresponds to hledger's data types; for details of - what the fields mean, see the Hledger.Data.Json haddock docs and click - on the various data types, eg Transaction. And for a higher level + Most of the JSON corresponds to hledger's data types; for details of + what the fields mean, see the Hledger.Data.Json haddock docs and click + on the various data types, eg Transaction. And for a higher level understanding, see the journal manual. In some cases there is outer JSON corresponding to a "Report" type. To - understand that, go to the Hledger.Web.Handler.MiscR haddock and look - at the source for the appropriate handler to see what it returns. Eg + understand that, go to the Hledger.Web.Handler.MiscR haddock and look + at the source for the appropriate handler to see what it returns. Eg for /accounttransactions it's getAccounttransactionsR, returning a - "accountTransactionsReport ...". Looking up the haddock for that we + "accountTransactionsReport ...". Looking up the haddock for that we can see that /accounttransactions returns an AccountTransactionsReport, - which consists of a report title and a list of AccountTransactionsRe- + which consists of a report title and a list of AccountTransactionsRe- portItem (etc). - You can add a new transaction to the journal with a PUT request to - /add, if hledger-web was started with the add capability (enabled by + You can add a new transaction to the journal with a PUT request to + /add, if hledger-web was started with the add capability (enabled by default). The payload must be the full, exact JSON representation of a - hledger transaction (partial data won't do). You can get sample JSON - from hledger-web's /transactions or /accounttransactions, or you can + hledger transaction (partial data won't do). You can get sample JSON + from hledger-web's /transactions or /accounttransactions, or you can export it with hledger-lib, eg like so: .../hledger$ stack ghci hledger-lib @@ -500,23 +506,23 @@ JSON API "tstatus": "Unmarked" } - And here's how to test adding it with curl. This should add a new + And here's how to test adding it with curl. This should add a new entry to your journal: $ curl http://127.0.0.1:5000/add -X PUT -H 'Content-Type: application/json' --data-binary @txn.json ENVIRONMENT LEDGER_FILE The journal file path when not specified with -f. Default: - ~/.hledger.journal (on windows, perhaps C:/Users/USER/.hledger.jour- + ~/.hledger.journal (on windows, perhaps C:/Users/USER/.hledger.jour- nal). - A typical value is ~/DIR/YYYY.journal, where DIR is a version-con- - trolled finance directory and YYYY is the current year. Or ~/DIR/cur- + A typical value is ~/DIR/YYYY.journal, where DIR is a version-con- + trolled finance directory and YYYY is the current year. Or ~/DIR/cur- rent.journal, where current.journal is a symbolic link to YYYY.journal. On Mac computers, you can set this and other environment variables in a - more thorough way that also affects applications started from the GUI - (say, an Emacs dock icon). Eg on MacOS Catalina I have a + more thorough way that also affects applications started from the GUI + (say, an Emacs dock icon). Eg on MacOS Catalina I have a ~/.MacOSX/environment.plist file containing { @@ -526,13 +532,13 @@ ENVIRONMENT To see the effect you may need to killall Dock, or reboot. FILES - Reads data from one or more files in hledger journal, timeclock, time- - dot, or CSV format specified with -f, or $LEDGER_FILE, or - $HOME/.hledger.journal (on windows, perhaps + Reads data from one or more files in hledger journal, timeclock, time- + dot, or CSV format specified with -f, or $LEDGER_FILE, or + $HOME/.hledger.journal (on windows, perhaps C:/Users/USER/.hledger.journal). BUGS - The need to precede options with -- when invoked from hledger is awk- + The need to precede options with -- when invoked from hledger is awk- ward. -f- doesn't work (hledger-web can't read from stdin). @@ -546,7 +552,7 @@ BUGS REPORTING BUGS - Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel + Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel or hledger mail list) @@ -564,4 +570,4 @@ SEE ALSO -hledger-web-1.22.99 September 2021 HLEDGER-WEB(1) +hledger-web-1.23 September 2021 HLEDGER-WEB(1) diff --git a/hledger/hledger.1 b/hledger/hledger.1 index ab7018670..c39e58247 100644 --- a/hledger/hledger.1 +++ b/hledger/hledger.1 @@ -1,6 +1,6 @@ .\"t -.TH "HLEDGER" "1" "September 2021" "hledger-1.22.99 " "hledger User Manuals" +.TH "HLEDGER" "1" "September 2021" "hledger-1.23 " "hledger User Manuals" @@ -9,7 +9,7 @@ This is the command-line interface (CLI) for the hledger accounting tool. Here we also describe hledger\[aq]s concepts and file formats. -This manual is for hledger 1.22.99. +This manual is for hledger 1.23. .SH SYNOPSIS .PP \f[C]hledger\f[R] @@ -207,6 +207,14 @@ terminal. into \[aq]less -R\[aq]. \[aq]never\[aq] or \[aq]no\[aq]: never. A NO_COLOR environment variable overrides this. +.TP +\f[B]\f[CB]--pretty[=WHEN]\f[B]\f[R] +Show prettier output, e.g. +using unicode box-drawing characters. +Accepts \[aq]yes\[aq] (the default) or \[aq]no\[aq] (\[aq]y\[aq], +\[aq]n\[aq], \[aq]always\[aq], \[aq]never\[aq] also work). +If you provide an argument you must use \[aq]=\[aq], e.g. +\[aq]--pretty=yes\[aq]. .PP When a reporting option appears more than once in the command line, the last one takes precedence. @@ -528,7 +536,7 @@ Default: the full terminal width. .PP \f[B]NO_COLOR\f[R] If this variable exists with any value, hledger will not use ANSI color codes in terminal output. -This overrides the --color/--colour option. +This is overriden by the --color/--colour option. .SH DATA FILES .PP hledger reads transactions from one or more data files. @@ -2308,6 +2316,24 @@ hledger can optionally produce debug output (if enabled with \f[C]-o/--output-file\f[R]. If you need to capture it, use shell redirects, eg: \f[C]hledger bal --debug=3 >file 2>&1\f[R]. +.SS Output styling +.PP +hledger commands can produce colour output when the terminal supports +it. +This is controlled by the \f[C]--color/--colour\f[R] option: - if the +\f[C]--color/--colour\f[R] option is given a value of \f[C]yes\f[R] or +\f[C]always\f[R] (or \f[C]no\f[R] or \f[C]never\f[R]), colour will (or +will not) be used; - otherwise, if the \f[C]NO_COLOR\f[R] environment +variable is set, colour will not be used; - otherwise, colour will be +used if the output (terminal or file) supports it. +.PP +hledger commands can also use unicode box-drawing characters to produce +prettier tables and output. +This is controlled by the \f[C]--pretty\f[R] option: - if the +\f[C]--pretty\f[R] option is given a value of \f[C]yes\f[R] or +\f[C]always\f[R] (or \f[C]no\f[R] or \f[C]never\f[R]), unicode +characters will (or will not) be used; - otherwise, unicode characters +will not be used. .SS Output format .PP Some commands (print, register, the balance commands) offer a choice of diff --git a/hledger/hledger.info b/hledger/hledger.info index 21eeb5184..4915b8b90 100644 --- a/hledger/hledger.info +++ b/hledger/hledger.info @@ -13,7 +13,7 @@ hledger(1) This is the command-line interface (CLI) for the hledger accounting tool. Here we also describe hledger's concepts and file formats. This -manual is for hledger 1.22.99. +manual is for hledger 1.23. 'hledger' @@ -244,6 +244,12 @@ by most hledger commands, run 'hledger -h'. color-supporting terminal. 'always' or 'yes': always, useful eg when piping output into 'less -R'. 'never' or 'no': never. A NO_COLOR environment variable overrides this. +'--pretty[=WHEN]' + + Show prettier output, e.g. using unicode box-drawing characters. + Accepts 'yes' (the default) or 'no' ('y', 'n', 'always', 'never' + also work). If you provide an argument you must use '=', e.g. + '-pretty=yes'. When a reporting option appears more than once in the command line, the last one takes precedence. @@ -520,7 +526,7 @@ a more thorough way that also affects applications started from the GUI the full terminal width. *NO_COLOR* If this variable exists with any value, hledger will not -use ANSI color codes in terminal output. This overrides the +use ANSI color codes in terminal output. This is overriden by the -color/-colour option.  @@ -1787,11 +1793,12 @@ File: hledger.info, Node: OUTPUT, Next: COMMANDS, Prev: PIVOTING, Up: Top * Menu: * Output destination:: +* Output styling:: * Output format:: * Commodity styles::  -File: hledger.info, Node: Output destination, Next: Output format, Up: OUTPUT +File: hledger.info, Node: Output destination, Next: Output styling, Up: OUTPUT 10.1 Output destination ======================= @@ -1814,9 +1821,29 @@ $ hledger print -o - # write to stdout (the default) 'hledger bal --debug=3 >file 2>&1'.  -File: hledger.info, Node: Output format, Next: Commodity styles, Prev: Output destination, Up: OUTPUT +File: hledger.info, Node: Output styling, Next: Output format, Prev: Output destination, Up: OUTPUT -10.2 Output format +10.2 Output styling +=================== + +hledger commands can produce colour output when the terminal supports +it. This is controlled by the '--color/--colour' option: - if the +'--color/--colour' option is given a value of 'yes' or 'always' (or 'no' +or 'never'), colour will (or will not) be used; - otherwise, if the +'NO_COLOR' environment variable is set, colour will not be used; - +otherwise, colour will be used if the output (terminal or file) supports +it. + + hledger commands can also use unicode box-drawing characters to +produce prettier tables and output. This is controlled by the +'--pretty' option: - if the '--pretty' option is given a value of 'yes' +or 'always' (or 'no' or 'never'), unicode characters will (or will not) +be used; - otherwise, unicode characters will not be used. + + +File: hledger.info, Node: Output format, Next: Commodity styles, Prev: Output styling, Up: OUTPUT + +10.3 Output format ================== Some commands (print, register, the balance commands) offer a choice of @@ -1870,7 +1897,7 @@ $ hledger balancesheet -o foo.txt -O html # write HTML to foo.txt  File: hledger.info, Node: Commodity styles, Prev: Output format, Up: OUTPUT -10.3 Commodity styles +10.4 Commodity styles ===================== The display style of a commodity/currency is inferred according to the @@ -8880,512 +8907,514 @@ $ LANG=en_US.UTF-8 hledger -f my.journal print  Tag Table: Node: Top208 -Node: OPTIONS2605 -Ref: #options2706 -Node: General options2848 -Ref: #general-options2973 -Node: Command options6938 -Ref: #command-options7089 -Node: Command arguments7489 -Ref: #command-arguments7647 -Node: Special characters8527 -Ref: #special-characters8690 -Node: Single escaping shell metacharacters8853 -Ref: #single-escaping-shell-metacharacters9094 -Node: Double escaping regular expression metacharacters9697 -Ref: #double-escaping-regular-expression-metacharacters10008 -Node: Triple escaping for add-on commands10534 -Ref: #triple-escaping-for-add-on-commands10794 -Node: Less escaping11438 -Ref: #less-escaping11592 -Node: Unicode characters11916 -Ref: #unicode-characters12081 -Node: Regular expressions13493 -Ref: #regular-expressions13633 -Node: ENVIRONMENT15369 -Ref: #environment15485 -Node: DATA FILES16470 -Ref: #data-files16589 -Node: Data formats17128 -Ref: #data-formats17246 -Node: Multiple files18640 -Ref: #multiple-files18782 -Node: Strict mode19251 -Ref: #strict-mode19366 -Node: TIME PERIODS20072 -Ref: #time-periods20189 -Node: Smart dates20287 -Ref: #smart-dates20413 -Node: Report start & end date21950 -Ref: #report-start-end-date22125 -Node: Report intervals23792 -Ref: #report-intervals23960 -Node: Period expressions25699 -Ref: #period-expressions25839 -Node: Period expressions with a report interval27570 -Ref: #period-expressions-with-a-report-interval27802 -Node: More complex report intervals28883 -Ref: #more-complex-report-intervals29132 -Node: Intervals with custom start date29767 -Ref: #intervals-with-custom-start-date29999 -Node: Periods or dates ?31573 -Ref: #periods-or-dates31775 -Node: Events on multiple weekdays32217 -Ref: #events-on-multiple-weekdays32396 -Node: DEPTH33259 -Ref: #depth33359 -Node: QUERIES33693 -Ref: #queries33792 -Node: Query types34733 -Ref: #query-types34852 -Node: Combining query terms37524 -Ref: #combining-query-terms37699 -Node: Queries and command options38502 -Ref: #queries-and-command-options38705 -Node: Queries and account aliases38954 -Ref: #queries-and-account-aliases39157 -Node: Queries and valuation39277 -Ref: #queries-and-valuation39470 -Node: Querying with account aliases39699 -Ref: #querying-with-account-aliases39908 -Node: Querying with cost or value40038 -Ref: #querying-with-cost-or-value40213 -Node: COSTING40514 -Ref: #costing40617 -Node: VALUATION40891 -Ref: #valuation40999 -Node: -V Value41725 -Ref: #v-value41849 -Node: -X Value in specified commodity42044 -Ref: #x-value-in-specified-commodity42237 -Node: Valuation date42386 -Ref: #valuation-date42548 -Node: Market prices42985 -Ref: #market-prices43167 -Node: --infer-market-prices market prices from transactions44350 -Ref: #infer-market-prices-market-prices-from-transactions44617 -Node: Valuation commodity45973 -Ref: #valuation-commodity46184 -Node: Simple valuation examples47410 -Ref: #simple-valuation-examples47606 -Node: --value Flexible valuation48265 -Ref: #value-flexible-valuation48467 -Node: More valuation examples50111 -Ref: #more-valuation-examples50312 -Node: Effect of valuation on reports52311 -Ref: #effect-of-valuation-on-reports52493 -Node: PIVOTING59894 -Ref: #pivoting59999 -Node: OUTPUT61675 -Ref: #output61777 -Node: Output destination61849 -Ref: #output-destination61982 -Node: Output format62639 -Ref: #output-format62787 -Node: Commodity styles64954 -Ref: #commodity-styles65081 -Node: COMMANDS65857 -Ref: #commands65969 -Node: accounts69334 -Ref: #accounts69434 -Node: activity70130 -Ref: #activity70242 -Node: add70625 -Ref: #add70728 -Node: aregister73521 -Ref: #aregister73635 -Node: aregister and custom posting dates76000 -Ref: #aregister-and-custom-posting-dates76166 -Node: balance76718 -Ref: #balance76837 -Node: balance features77805 -Ref: #balance-features77945 -Node: Simple balance report79735 -Ref: #simple-balance-report79917 -Node: Filtered balance report81397 -Ref: #filtered-balance-report81584 -Node: List or tree mode81911 -Ref: #list-or-tree-mode82079 -Node: Depth limiting83424 -Ref: #depth-limiting83590 -Node: Dropping top-level accounts84191 -Ref: #dropping-top-level-accounts84393 -Node: Multi-period balance report84703 -Ref: #multi-period-balance-report84907 -Node: Commodity column87182 -Ref: #commodity-column87354 -Node: Sorting by amount90255 -Ref: #sorting-by-amount90413 -Node: Percentages91083 -Ref: #percentages91241 -Node: Balance change end balance92202 -Ref: #balance-change-end-balance92395 -Node: Balance report types93823 -Ref: #balance-report-types94013 -Node: Useful balance reports98292 -Ref: #useful-balance-reports98473 -Node: Budget report99558 -Ref: #budget-report99742 -Node: Budget report start date105017 -Ref: #budget-report-start-date105195 -Node: Budgets and subaccounts106527 -Ref: #budgets-and-subaccounts106734 -Node: Selecting budget goals110174 -Ref: #selecting-budget-goals110346 -Node: Customising single-period balance reports111380 -Ref: #customising-single-period-balance-reports111589 -Node: balancesheet113764 -Ref: #balancesheet113902 -Node: balancesheetequity115201 -Ref: #balancesheetequity115352 -Node: cashflow116732 -Ref: #cashflow116856 -Node: check118002 -Ref: #check118107 -Node: Basic checks118741 -Ref: #basic-checks118859 -Node: Strict checks119410 -Ref: #strict-checks119551 -Node: Other checks119987 -Ref: #other-checks120127 -Node: Custom checks120484 -Ref: #custom-checks120604 -Node: close121021 -Ref: #close121125 -Node: close and prices123216 -Ref: #close-and-prices123345 -Node: close date123740 -Ref: #close-date123924 -Node: Example close asset/liability accounts for file transition124681 -Ref: #example-close-assetliability-accounts-for-file-transition124982 -Node: Hiding opening/closing transactions125841 -Ref: #hiding-openingclosing-transactions126112 -Node: close and balance assertions127489 -Ref: #close-and-balance-assertions127747 -Node: Example close revenue/expense accounts to retained earnings129101 -Ref: #example-close-revenueexpense-accounts-to-retained-earnings129379 -Node: codes130269 -Ref: #codes130379 -Node: commodities131091 -Ref: #commodities131220 -Node: descriptions131302 -Ref: #descriptions131432 -Node: diff131736 -Ref: #diff131844 -Node: files132891 -Ref: #files132993 -Node: help133140 -Ref: #help133242 -Node: import134060 -Ref: #import134176 -Node: Deduplication135041 -Ref: #deduplication135166 -Node: Import testing137060 -Ref: #import-testing137225 -Node: Importing balance assignments137713 -Ref: #importing-balance-assignments137919 -Node: Commodity display styles138568 -Ref: #commodity-display-styles138741 -Node: incomestatement138870 -Ref: #incomestatement139005 -Node: notes140310 -Ref: #notes140425 -Node: payees140793 -Ref: #payees140901 -Node: prices141427 -Ref: #prices141535 -Node: print141904 -Ref: #print142016 -Node: print-unique147331 -Ref: #print-unique147459 -Node: register147744 -Ref: #register147873 -Node: Custom register output152319 -Ref: #custom-register-output152450 -Node: register-match153787 -Ref: #register-match153923 -Node: rewrite154274 -Ref: #rewrite154391 -Node: Re-write rules in a file156297 -Ref: #re-write-rules-in-a-file156460 -Node: Diff output format157609 -Ref: #diff-output-format157792 -Node: rewrite vs print --auto158884 -Ref: #rewrite-vs.-print---auto159044 -Node: roi159600 -Ref: #roi159700 -Node: Spaces and special characters in --inv and --pnl161386 -Ref: #spaces-and-special-characters-in---inv-and---pnl161626 -Node: Semantics of --inv and --pnl162114 -Ref: #semantics-of---inv-and---pnl162353 -Node: IRR and TWR explained164203 -Ref: #irr-and-twr-explained164363 -Node: stats167431 -Ref: #stats167532 -Node: tags168320 -Ref: #tags168420 -Node: test168939 -Ref: #test169055 -Node: About add-on commands169802 -Ref: #about-add-on-commands169939 -Node: JOURNAL FORMAT171070 -Ref: #journal-format171198 -Node: Transactions173394 -Ref: #transactions173509 -Node: Dates174523 -Ref: #dates174639 -Node: Simple dates174704 -Ref: #simple-dates174824 -Node: Secondary dates175333 -Ref: #secondary-dates175481 -Node: Posting dates176817 -Ref: #posting-dates176940 -Node: Status178312 -Ref: #status178422 -Node: Code180130 -Ref: #code180242 -Node: Description180474 -Ref: #description180602 -Node: Payee and note180922 -Ref: #payee-and-note181030 -Node: Comments181365 -Ref: #comments181487 -Node: Tags182681 -Ref: #tags-1182792 -Node: Postings184185 -Ref: #postings184309 -Node: Virtual postings185335 -Ref: #virtual-postings185446 -Node: Account names186751 -Ref: #account-names186888 -Node: Amounts187376 -Ref: #amounts187513 -Node: Decimal marks digit group marks188469 -Ref: #decimal-marks-digit-group-marks188646 -Node: Commodity189518 -Ref: #commodity189678 -Node: Commodity directives190630 -Ref: #commodity-directives190804 -Node: Commodity display style191291 -Ref: #commodity-display-style191470 -Node: Rounding193665 -Ref: #rounding193785 -Node: Transaction prices194197 -Ref: #transaction-prices194363 -Node: Lot prices lot dates196794 -Ref: #lot-prices-lot-dates196977 -Node: Balance assertions197465 -Ref: #balance-assertions197643 -Node: Assertions and ordering198676 -Ref: #assertions-and-ordering198858 -Node: Assertions and included files199558 -Ref: #assertions-and-included-files199795 -Node: Assertions and multiple -f options200128 -Ref: #assertions-and-multiple--f-options200378 -Node: Assertions and commodities200510 -Ref: #assertions-and-commodities200736 -Node: Assertions and prices201893 -Ref: #assertions-and-prices202101 -Node: Assertions and subaccounts202541 -Ref: #assertions-and-subaccounts202764 -Node: Assertions and virtual postings203088 -Ref: #assertions-and-virtual-postings203324 -Node: Assertions and precision203466 -Ref: #assertions-and-precision203653 -Node: Balance assignments203920 -Ref: #balance-assignments204090 -Node: Balance assignments and prices205254 -Ref: #balance-assignments-and-prices205420 -Node: Directives205644 -Ref: #directives205807 -Node: Directives and multiple files211161 -Ref: #directives-and-multiple-files211357 -Node: Comment blocks212021 -Ref: #comment-blocks212198 -Node: Including other files212374 -Ref: #including-other-files212548 -Node: Default year213472 -Ref: #default-year213630 -Node: Declaring payees214037 -Ref: #declaring-payees214203 -Node: Declaring commodities214449 -Ref: #declaring-commodities214630 -Node: Commodity error checking217148 -Ref: #commodity-error-checking217298 -Node: Default commodity217555 -Ref: #default-commodity217735 -Node: Declaring market prices218611 -Ref: #declaring-market-prices218800 -Node: Declaring accounts219613 -Ref: #declaring-accounts219793 -Node: Account error checking220995 -Ref: #account-error-checking221161 -Node: Account comments222340 -Ref: #account-comments222524 -Node: Account subdirectives222948 -Ref: #account-subdirectives223133 -Node: Account types223446 -Ref: #account-types223620 -Node: Declaring account types224278 -Ref: #declaring-account-types224457 -Node: Auto-detected account types225511 -Ref: #auto-detected-account-types225698 -Node: Account display order227716 -Ref: #account-display-order227876 -Node: Rewriting accounts229027 -Ref: #rewriting-accounts229206 -Node: Basic aliases229963 -Ref: #basic-aliases230099 -Node: Regex aliases230843 -Ref: #regex-aliases231005 -Node: Combining aliases231724 -Ref: #combining-aliases231907 -Node: Aliases and multiple files233183 -Ref: #aliases-and-multiple-files233382 -Node: end aliases233961 -Ref: #end-aliases234108 -Node: Default parent account234209 -Ref: #default-parent-account234399 -Node: Periodic transactions235283 -Ref: #periodic-transactions235466 -Node: Periodic rule syntax237383 -Ref: #periodic-rule-syntax237583 -Node: Two spaces between period expression and description!238287 -Ref: #two-spaces-between-period-expression-and-description238600 -Node: Forecasting with periodic transactions239284 -Ref: #forecasting-with-periodic-transactions239583 -Node: Budgeting with periodic transactions242354 -Ref: #budgeting-with-periodic-transactions242587 -Node: Auto postings242996 -Ref: #auto-postings243132 -Node: Auto postings and multiple files245311 -Ref: #auto-postings-and-multiple-files245509 -Node: Auto postings and dates245718 -Ref: #auto-postings-and-dates245986 -Node: Auto postings and transaction balancing / inferred amounts / balance assertions246161 -Ref: #auto-postings-and-transaction-balancing-inferred-amounts-balance-assertions246506 -Node: Auto posting tags246848 -Ref: #auto-posting-tags247057 -Node: CSV FORMAT247693 -Ref: #csv-format247821 -Node: Examples250450 -Ref: #examples250553 -Node: Basic250761 -Ref: #basic250863 -Node: Bank of Ireland251405 -Ref: #bank-of-ireland251542 -Node: Amazon253004 -Ref: #amazon253124 -Node: Paypal254843 -Ref: #paypal254939 -Node: CSV rules262583 -Ref: #csv-rules262701 -Node: skip263034 -Ref: #skip263134 -Node: fields list263509 -Ref: #fields-list263648 -Node: field assignment265151 -Ref: #field-assignment265303 -Node: Field names266338 -Ref: #field-names266478 -Node: date field266858 -Ref: #date-field266978 -Node: date2 field267026 -Ref: #date2-field267169 -Node: status field267225 -Ref: #status-field267370 -Node: code field267419 -Ref: #code-field267566 -Node: description field267611 -Ref: #description-field267773 -Node: comment field267832 -Ref: #comment-field267989 -Node: account field268289 -Ref: #account-field268441 -Node: amount field269016 -Ref: #amount-field269167 -Node: currency field270412 -Ref: #currency-field270567 -Node: balance field270824 -Ref: #balance-field270958 -Node: separator271330 -Ref: #separator271462 -Node: if block272002 -Ref: #if-block272129 -Node: Matching the whole record272530 -Ref: #matching-the-whole-record272707 -Node: Matching individual fields273510 -Ref: #matching-individual-fields273716 -Node: Combining matchers273940 -Ref: #combining-matchers274138 -Node: Rules applied on successful match274451 -Ref: #rules-applied-on-successful-match274644 -Node: if table275298 -Ref: #if-table275419 -Node: end277157 -Ref: #end277271 -Node: date-format277495 -Ref: #date-format277629 -Node: decimal-mark278625 -Ref: #decimal-mark278772 -Node: newest-first279111 -Ref: #newest-first279254 -Node: include279937 -Ref: #include280070 -Node: balance-type280514 -Ref: #balance-type280636 -Node: Tips281336 -Ref: #tips281427 -Node: Rapid feedback281726 -Ref: #rapid-feedback281845 -Node: Valid CSV282297 -Ref: #valid-csv282429 -Node: File Extension282621 -Ref: #file-extension282775 -Node: Reading multiple CSV files283204 -Ref: #reading-multiple-csv-files283391 -Node: Valid transactions283632 -Ref: #valid-transactions283812 -Node: Deduplicating importing284440 -Ref: #deduplicating-importing284621 -Node: Setting amounts285654 -Ref: #setting-amounts285811 -Node: Amount signs288252 -Ref: #amount-signs288406 -Node: Setting currency/commodity289093 -Ref: #setting-currencycommodity289281 -Node: Amount decimal places290455 -Ref: #amount-decimal-places290647 -Node: Referencing other fields290959 -Ref: #referencing-other-fields291158 -Node: How CSV rules are evaluated292055 -Ref: #how-csv-rules-are-evaluated292230 -Node: TIMECLOCK FORMAT293681 -Ref: #timeclock-format293821 -Node: TIMEDOT FORMAT295882 -Ref: #timedot-format296020 -Node: COMMON TASKS300582 -Ref: #common-tasks300711 -Node: Getting help301118 -Ref: #getting-help301252 -Node: Constructing command lines301805 -Ref: #constructing-command-lines301999 -Node: Starting a journal file302696 -Ref: #starting-a-journal-file302896 -Node: Setting opening balances304084 -Ref: #setting-opening-balances304282 -Node: Recording transactions307423 -Ref: #recording-transactions307605 -Node: Reconciling308161 -Ref: #reconciling308306 -Node: Reporting310563 -Ref: #reporting310705 -Node: Migrating to a new file314704 -Ref: #migrating-to-a-new-file314854 -Node: LIMITATIONS315153 -Ref: #limitations315281 -Node: TROUBLESHOOTING316024 -Ref: #troubleshooting316139 +Node: OPTIONS2602 +Ref: #options2703 +Node: General options2845 +Ref: #general-options2970 +Node: Command options7183 +Ref: #command-options7334 +Node: Command arguments7734 +Ref: #command-arguments7892 +Node: Special characters8772 +Ref: #special-characters8935 +Node: Single escaping shell metacharacters9098 +Ref: #single-escaping-shell-metacharacters9339 +Node: Double escaping regular expression metacharacters9942 +Ref: #double-escaping-regular-expression-metacharacters10253 +Node: Triple escaping for add-on commands10779 +Ref: #triple-escaping-for-add-on-commands11039 +Node: Less escaping11683 +Ref: #less-escaping11837 +Node: Unicode characters12161 +Ref: #unicode-characters12326 +Node: Regular expressions13738 +Ref: #regular-expressions13878 +Node: ENVIRONMENT15614 +Ref: #environment15730 +Node: DATA FILES16721 +Ref: #data-files16840 +Node: Data formats17379 +Ref: #data-formats17497 +Node: Multiple files18891 +Ref: #multiple-files19033 +Node: Strict mode19502 +Ref: #strict-mode19617 +Node: TIME PERIODS20323 +Ref: #time-periods20440 +Node: Smart dates20538 +Ref: #smart-dates20664 +Node: Report start & end date22201 +Ref: #report-start-end-date22376 +Node: Report intervals24043 +Ref: #report-intervals24211 +Node: Period expressions25950 +Ref: #period-expressions26090 +Node: Period expressions with a report interval27821 +Ref: #period-expressions-with-a-report-interval28053 +Node: More complex report intervals29134 +Ref: #more-complex-report-intervals29383 +Node: Intervals with custom start date30018 +Ref: #intervals-with-custom-start-date30250 +Node: Periods or dates ?31824 +Ref: #periods-or-dates32026 +Node: Events on multiple weekdays32468 +Ref: #events-on-multiple-weekdays32647 +Node: DEPTH33510 +Ref: #depth33610 +Node: QUERIES33944 +Ref: #queries34043 +Node: Query types34984 +Ref: #query-types35103 +Node: Combining query terms37775 +Ref: #combining-query-terms37950 +Node: Queries and command options38753 +Ref: #queries-and-command-options38956 +Node: Queries and account aliases39205 +Ref: #queries-and-account-aliases39408 +Node: Queries and valuation39528 +Ref: #queries-and-valuation39721 +Node: Querying with account aliases39950 +Ref: #querying-with-account-aliases40159 +Node: Querying with cost or value40289 +Ref: #querying-with-cost-or-value40464 +Node: COSTING40765 +Ref: #costing40868 +Node: VALUATION41142 +Ref: #valuation41250 +Node: -V Value41976 +Ref: #v-value42100 +Node: -X Value in specified commodity42295 +Ref: #x-value-in-specified-commodity42488 +Node: Valuation date42637 +Ref: #valuation-date42799 +Node: Market prices43236 +Ref: #market-prices43418 +Node: --infer-market-prices market prices from transactions44601 +Ref: #infer-market-prices-market-prices-from-transactions44868 +Node: Valuation commodity46224 +Ref: #valuation-commodity46435 +Node: Simple valuation examples47661 +Ref: #simple-valuation-examples47857 +Node: --value Flexible valuation48516 +Ref: #value-flexible-valuation48718 +Node: More valuation examples50362 +Ref: #more-valuation-examples50563 +Node: Effect of valuation on reports52562 +Ref: #effect-of-valuation-on-reports52744 +Node: PIVOTING60145 +Ref: #pivoting60250 +Node: OUTPUT61926 +Ref: #output62028 +Node: Output destination62119 +Ref: #output-destination62253 +Node: Output styling62910 +Ref: #output-styling63058 +Node: Output format63815 +Ref: #output-format63959 +Node: Commodity styles66126 +Ref: #commodity-styles66253 +Node: COMMANDS67029 +Ref: #commands67141 +Node: accounts70506 +Ref: #accounts70606 +Node: activity71302 +Ref: #activity71414 +Node: add71797 +Ref: #add71900 +Node: aregister74693 +Ref: #aregister74807 +Node: aregister and custom posting dates77172 +Ref: #aregister-and-custom-posting-dates77338 +Node: balance77890 +Ref: #balance78009 +Node: balance features78977 +Ref: #balance-features79117 +Node: Simple balance report80907 +Ref: #simple-balance-report81089 +Node: Filtered balance report82569 +Ref: #filtered-balance-report82756 +Node: List or tree mode83083 +Ref: #list-or-tree-mode83251 +Node: Depth limiting84596 +Ref: #depth-limiting84762 +Node: Dropping top-level accounts85363 +Ref: #dropping-top-level-accounts85565 +Node: Multi-period balance report85875 +Ref: #multi-period-balance-report86079 +Node: Commodity column88354 +Ref: #commodity-column88526 +Node: Sorting by amount91427 +Ref: #sorting-by-amount91585 +Node: Percentages92255 +Ref: #percentages92413 +Node: Balance change end balance93374 +Ref: #balance-change-end-balance93567 +Node: Balance report types94995 +Ref: #balance-report-types95185 +Node: Useful balance reports99464 +Ref: #useful-balance-reports99645 +Node: Budget report100730 +Ref: #budget-report100914 +Node: Budget report start date106189 +Ref: #budget-report-start-date106367 +Node: Budgets and subaccounts107699 +Ref: #budgets-and-subaccounts107906 +Node: Selecting budget goals111346 +Ref: #selecting-budget-goals111518 +Node: Customising single-period balance reports112552 +Ref: #customising-single-period-balance-reports112761 +Node: balancesheet114936 +Ref: #balancesheet115074 +Node: balancesheetequity116373 +Ref: #balancesheetequity116524 +Node: cashflow117904 +Ref: #cashflow118028 +Node: check119174 +Ref: #check119279 +Node: Basic checks119913 +Ref: #basic-checks120031 +Node: Strict checks120582 +Ref: #strict-checks120723 +Node: Other checks121159 +Ref: #other-checks121299 +Node: Custom checks121656 +Ref: #custom-checks121776 +Node: close122193 +Ref: #close122297 +Node: close and prices124388 +Ref: #close-and-prices124517 +Node: close date124912 +Ref: #close-date125096 +Node: Example close asset/liability accounts for file transition125853 +Ref: #example-close-assetliability-accounts-for-file-transition126154 +Node: Hiding opening/closing transactions127013 +Ref: #hiding-openingclosing-transactions127284 +Node: close and balance assertions128661 +Ref: #close-and-balance-assertions128919 +Node: Example close revenue/expense accounts to retained earnings130273 +Ref: #example-close-revenueexpense-accounts-to-retained-earnings130551 +Node: codes131441 +Ref: #codes131551 +Node: commodities132263 +Ref: #commodities132392 +Node: descriptions132474 +Ref: #descriptions132604 +Node: diff132908 +Ref: #diff133016 +Node: files134063 +Ref: #files134165 +Node: help134312 +Ref: #help134414 +Node: import135232 +Ref: #import135348 +Node: Deduplication136213 +Ref: #deduplication136338 +Node: Import testing138232 +Ref: #import-testing138397 +Node: Importing balance assignments138885 +Ref: #importing-balance-assignments139091 +Node: Commodity display styles139740 +Ref: #commodity-display-styles139913 +Node: incomestatement140042 +Ref: #incomestatement140177 +Node: notes141482 +Ref: #notes141597 +Node: payees141965 +Ref: #payees142073 +Node: prices142599 +Ref: #prices142707 +Node: print143076 +Ref: #print143188 +Node: print-unique148503 +Ref: #print-unique148631 +Node: register148916 +Ref: #register149045 +Node: Custom register output153491 +Ref: #custom-register-output153622 +Node: register-match154959 +Ref: #register-match155095 +Node: rewrite155446 +Ref: #rewrite155563 +Node: Re-write rules in a file157469 +Ref: #re-write-rules-in-a-file157632 +Node: Diff output format158781 +Ref: #diff-output-format158964 +Node: rewrite vs print --auto160056 +Ref: #rewrite-vs.-print---auto160216 +Node: roi160772 +Ref: #roi160872 +Node: Spaces and special characters in --inv and --pnl162558 +Ref: #spaces-and-special-characters-in---inv-and---pnl162798 +Node: Semantics of --inv and --pnl163286 +Ref: #semantics-of---inv-and---pnl163525 +Node: IRR and TWR explained165375 +Ref: #irr-and-twr-explained165535 +Node: stats168603 +Ref: #stats168704 +Node: tags169492 +Ref: #tags169592 +Node: test170111 +Ref: #test170227 +Node: About add-on commands170974 +Ref: #about-add-on-commands171111 +Node: JOURNAL FORMAT172242 +Ref: #journal-format172370 +Node: Transactions174566 +Ref: #transactions174681 +Node: Dates175695 +Ref: #dates175811 +Node: Simple dates175876 +Ref: #simple-dates175996 +Node: Secondary dates176505 +Ref: #secondary-dates176653 +Node: Posting dates177989 +Ref: #posting-dates178112 +Node: Status179484 +Ref: #status179594 +Node: Code181302 +Ref: #code181414 +Node: Description181646 +Ref: #description181774 +Node: Payee and note182094 +Ref: #payee-and-note182202 +Node: Comments182537 +Ref: #comments182659 +Node: Tags183853 +Ref: #tags-1183964 +Node: Postings185357 +Ref: #postings185481 +Node: Virtual postings186507 +Ref: #virtual-postings186618 +Node: Account names187923 +Ref: #account-names188060 +Node: Amounts188548 +Ref: #amounts188685 +Node: Decimal marks digit group marks189641 +Ref: #decimal-marks-digit-group-marks189818 +Node: Commodity190690 +Ref: #commodity190850 +Node: Commodity directives191802 +Ref: #commodity-directives191976 +Node: Commodity display style192463 +Ref: #commodity-display-style192642 +Node: Rounding194837 +Ref: #rounding194957 +Node: Transaction prices195369 +Ref: #transaction-prices195535 +Node: Lot prices lot dates197966 +Ref: #lot-prices-lot-dates198149 +Node: Balance assertions198637 +Ref: #balance-assertions198815 +Node: Assertions and ordering199848 +Ref: #assertions-and-ordering200030 +Node: Assertions and included files200730 +Ref: #assertions-and-included-files200967 +Node: Assertions and multiple -f options201300 +Ref: #assertions-and-multiple--f-options201550 +Node: Assertions and commodities201682 +Ref: #assertions-and-commodities201908 +Node: Assertions and prices203065 +Ref: #assertions-and-prices203273 +Node: Assertions and subaccounts203713 +Ref: #assertions-and-subaccounts203936 +Node: Assertions and virtual postings204260 +Ref: #assertions-and-virtual-postings204496 +Node: Assertions and precision204638 +Ref: #assertions-and-precision204825 +Node: Balance assignments205092 +Ref: #balance-assignments205262 +Node: Balance assignments and prices206426 +Ref: #balance-assignments-and-prices206592 +Node: Directives206816 +Ref: #directives206979 +Node: Directives and multiple files212333 +Ref: #directives-and-multiple-files212529 +Node: Comment blocks213193 +Ref: #comment-blocks213370 +Node: Including other files213546 +Ref: #including-other-files213720 +Node: Default year214644 +Ref: #default-year214802 +Node: Declaring payees215209 +Ref: #declaring-payees215375 +Node: Declaring commodities215621 +Ref: #declaring-commodities215802 +Node: Commodity error checking218320 +Ref: #commodity-error-checking218470 +Node: Default commodity218727 +Ref: #default-commodity218907 +Node: Declaring market prices219783 +Ref: #declaring-market-prices219972 +Node: Declaring accounts220785 +Ref: #declaring-accounts220965 +Node: Account error checking222167 +Ref: #account-error-checking222333 +Node: Account comments223512 +Ref: #account-comments223696 +Node: Account subdirectives224120 +Ref: #account-subdirectives224305 +Node: Account types224618 +Ref: #account-types224792 +Node: Declaring account types225450 +Ref: #declaring-account-types225629 +Node: Auto-detected account types226683 +Ref: #auto-detected-account-types226870 +Node: Account display order228888 +Ref: #account-display-order229048 +Node: Rewriting accounts230199 +Ref: #rewriting-accounts230378 +Node: Basic aliases231135 +Ref: #basic-aliases231271 +Node: Regex aliases232015 +Ref: #regex-aliases232177 +Node: Combining aliases232896 +Ref: #combining-aliases233079 +Node: Aliases and multiple files234355 +Ref: #aliases-and-multiple-files234554 +Node: end aliases235133 +Ref: #end-aliases235280 +Node: Default parent account235381 +Ref: #default-parent-account235571 +Node: Periodic transactions236455 +Ref: #periodic-transactions236638 +Node: Periodic rule syntax238555 +Ref: #periodic-rule-syntax238755 +Node: Two spaces between period expression and description!239459 +Ref: #two-spaces-between-period-expression-and-description239772 +Node: Forecasting with periodic transactions240456 +Ref: #forecasting-with-periodic-transactions240755 +Node: Budgeting with periodic transactions243526 +Ref: #budgeting-with-periodic-transactions243759 +Node: Auto postings244168 +Ref: #auto-postings244304 +Node: Auto postings and multiple files246483 +Ref: #auto-postings-and-multiple-files246681 +Node: Auto postings and dates246890 +Ref: #auto-postings-and-dates247158 +Node: Auto postings and transaction balancing / inferred amounts / balance assertions247333 +Ref: #auto-postings-and-transaction-balancing-inferred-amounts-balance-assertions247678 +Node: Auto posting tags248020 +Ref: #auto-posting-tags248229 +Node: CSV FORMAT248865 +Ref: #csv-format248993 +Node: Examples251622 +Ref: #examples251725 +Node: Basic251933 +Ref: #basic252035 +Node: Bank of Ireland252577 +Ref: #bank-of-ireland252714 +Node: Amazon254176 +Ref: #amazon254296 +Node: Paypal256015 +Ref: #paypal256111 +Node: CSV rules263755 +Ref: #csv-rules263873 +Node: skip264206 +Ref: #skip264306 +Node: fields list264681 +Ref: #fields-list264820 +Node: field assignment266323 +Ref: #field-assignment266475 +Node: Field names267510 +Ref: #field-names267650 +Node: date field268030 +Ref: #date-field268150 +Node: date2 field268198 +Ref: #date2-field268341 +Node: status field268397 +Ref: #status-field268542 +Node: code field268591 +Ref: #code-field268738 +Node: description field268783 +Ref: #description-field268945 +Node: comment field269004 +Ref: #comment-field269161 +Node: account field269461 +Ref: #account-field269613 +Node: amount field270188 +Ref: #amount-field270339 +Node: currency field271584 +Ref: #currency-field271739 +Node: balance field271996 +Ref: #balance-field272130 +Node: separator272502 +Ref: #separator272634 +Node: if block273174 +Ref: #if-block273301 +Node: Matching the whole record273702 +Ref: #matching-the-whole-record273879 +Node: Matching individual fields274682 +Ref: #matching-individual-fields274888 +Node: Combining matchers275112 +Ref: #combining-matchers275310 +Node: Rules applied on successful match275623 +Ref: #rules-applied-on-successful-match275816 +Node: if table276470 +Ref: #if-table276591 +Node: end278329 +Ref: #end278443 +Node: date-format278667 +Ref: #date-format278801 +Node: decimal-mark279797 +Ref: #decimal-mark279944 +Node: newest-first280283 +Ref: #newest-first280426 +Node: include281109 +Ref: #include281242 +Node: balance-type281686 +Ref: #balance-type281808 +Node: Tips282508 +Ref: #tips282599 +Node: Rapid feedback282898 +Ref: #rapid-feedback283017 +Node: Valid CSV283469 +Ref: #valid-csv283601 +Node: File Extension283793 +Ref: #file-extension283947 +Node: Reading multiple CSV files284376 +Ref: #reading-multiple-csv-files284563 +Node: Valid transactions284804 +Ref: #valid-transactions284984 +Node: Deduplicating importing285612 +Ref: #deduplicating-importing285793 +Node: Setting amounts286826 +Ref: #setting-amounts286983 +Node: Amount signs289424 +Ref: #amount-signs289578 +Node: Setting currency/commodity290265 +Ref: #setting-currencycommodity290453 +Node: Amount decimal places291627 +Ref: #amount-decimal-places291819 +Node: Referencing other fields292131 +Ref: #referencing-other-fields292330 +Node: How CSV rules are evaluated293227 +Ref: #how-csv-rules-are-evaluated293402 +Node: TIMECLOCK FORMAT294853 +Ref: #timeclock-format294993 +Node: TIMEDOT FORMAT297054 +Ref: #timedot-format297192 +Node: COMMON TASKS301754 +Ref: #common-tasks301883 +Node: Getting help302290 +Ref: #getting-help302424 +Node: Constructing command lines302977 +Ref: #constructing-command-lines303171 +Node: Starting a journal file303868 +Ref: #starting-a-journal-file304068 +Node: Setting opening balances305256 +Ref: #setting-opening-balances305454 +Node: Recording transactions308595 +Ref: #recording-transactions308777 +Node: Reconciling309333 +Ref: #reconciling309478 +Node: Reporting311735 +Ref: #reporting311877 +Node: Migrating to a new file315876 +Ref: #migrating-to-a-new-file316026 +Node: LIMITATIONS316325 +Ref: #limitations316453 +Node: TROUBLESHOOTING317196 +Ref: #troubleshooting317311  End Tag Table diff --git a/hledger/hledger.txt b/hledger/hledger.txt index b86f0eb8f..0909fb538 100644 --- a/hledger/hledger.txt +++ b/hledger/hledger.txt @@ -6,7 +6,7 @@ HLEDGER(1) hledger User Manuals HLEDGER(1) NAME This is the command-line interface (CLI) for the hledger accounting tool. Here we also describe hledger's concepts and file formats. This - manual is for hledger 1.22.99. + manual is for hledger 1.23. SYNOPSIS hledger @@ -194,35 +194,41 @@ OPTIONS piping output into 'less -R'. 'never' or 'no': never. A NO_COLOR environment variable overrides this. + --pretty[=WHEN] + Show prettier output, e.g. using unicode box-drawing charac- + ters. Accepts 'yes' (the default) or 'no' ('y', 'n', 'always', + 'never' also work). If you provide an argument you must use + '=', e.g. '--pretty=yes'. + When a reporting option appears more than once in the command line, the last one takes precedence. Some reporting options can also be written as query arguments. Command options - To see options for a particular command, including command-specific + To see options for a particular command, including command-specific options, run: hledger COMMAND -h. - Command-specific options must be written after the command name, eg: + Command-specific options must be written after the command name, eg: hledger print -x. - Additionally, if the command is an add-on, you may need to put its - options after a double-hyphen, eg: hledger ui -- --watch. Or, you can + Additionally, if the command is an add-on, you may need to put its + options after a double-hyphen, eg: hledger ui -- --watch. Or, you can run the add-on executable directly: hledger-ui --watch. Command arguments - Most hledger commands accept arguments after the command name, which + Most hledger commands accept arguments after the command name, which are often a query, filtering the data in some way. - You can save a set of command line options/arguments in a file, and - then reuse them by writing @FILENAME as a command line argument. Eg: - hledger bal @foo.args. (To prevent this, eg if you have an argument - that begins with a literal @, precede it with --, eg: hledger bal -- + You can save a set of command line options/arguments in a file, and + then reuse them by writing @FILENAME as a command line argument. Eg: + hledger bal @foo.args. (To prevent this, eg if you have an argument + that begins with a literal @, precede it with --, eg: hledger bal -- @ARG). - Inside the argument file, each line should contain just one option or + Inside the argument file, each line should contain just one option or argument. Avoid the use of spaces, except inside quotes (or you'll see - a confusing error). Between a flag and its argument, use = (or noth- + a confusing error). Between a flag and its argument, use = (or noth- ing). Bad: assets depth:2 @@ -234,7 +240,7 @@ OPTIONS depth:2 -X=USD - For special characters (see below), use one less level of quoting than + For special characters (see below), use one less level of quoting than you would at the command prompt. Bad: -X"$" @@ -247,10 +253,10 @@ OPTIONS Special characters Single escaping (shell metacharacters) - In shell command lines, characters significant to your shell - such as - spaces, <, >, (, ), |, $ and \ - should be "shell-escaped" if you want - hledger to see them. This is done by enclosing them in single or dou- - ble quotes, or by writing a backslash before them. Eg to match an + In shell command lines, characters significant to your shell - such as + spaces, <, >, (, ), |, $ and \ - should be "shell-escaped" if you want + hledger to see them. This is done by enclosing them in single or dou- + ble quotes, or by writing a backslash before them. Eg to match an account name containing a space: $ hledger register 'credit card' @@ -259,17 +265,17 @@ OPTIONS $ hledger register credit\ card - Windows users should keep in mind that cmd treats single quote as a - regular character, so you should be using double quotes exclusively. + Windows users should keep in mind that cmd treats single quote as a + regular character, so you should be using double quotes exclusively. PowerShell treats both single and double quotes as quotes. Double escaping (regular expression metacharacters) - Characters significant in regular expressions (described below) - such - as ., ^, $, [, ], (, ), |, and \ - may need to be "regex-escaped" if - you don't want them to be interpreted by hledger's regular expression - engine. This is done by writing backslashes before them, but since - backslash is typically also a shell metacharacter, both shell-escaping - and regex-escaping will be needed. Eg to match a literal $ sign while + Characters significant in regular expressions (described below) - such + as ., ^, $, [, ], (, ), |, and \ - may need to be "regex-escaped" if + you don't want them to be interpreted by hledger's regular expression + engine. This is done by writing backslashes before them, but since + backslash is typically also a shell metacharacter, both shell-escaping + and regex-escaping will be needed. Eg to match a literal $ sign while using the bash shell: $ hledger balance cur:'\$' @@ -279,10 +285,10 @@ OPTIONS $ hledger balance cur:\\$ Triple escaping (for add-on commands) - When you use hledger to run an external add-on command (described - below), one level of shell-escaping is lost from any options or argu- - ments intended for by the add-on command, so those need an extra level - of shell-escaping. Eg to match a literal $ sign while using the bash + When you use hledger to run an external add-on command (described + below), one level of shell-escaping is lost from any options or argu- + ments intended for by the add-on command, so those need an extra level + of shell-escaping. Eg to match a literal $ sign while using the bash shell and running an add-on command (ui): $ hledger ui cur:'\\$' @@ -299,14 +305,14 @@ OPTIONS double-escaped: \\$ triple-escaped: \\\\$ - Or, you can avoid the extra escaping by running the add-on executable + Or, you can avoid the extra escaping by running the add-on executable directly: $ hledger-ui cur:\\$ Less escaping Options and arguments are sometimes used in places other than the shell - command line, where shell-escaping is not needed, so there you should + command line, where shell-escaping is not needed, so there you should use one less level of escaping. Those places include: o an @argumentfile @@ -320,95 +326,95 @@ OPTIONS Unicode characters hledger is expected to handle non-ascii characters correctly: - o they should be parsed correctly in input files and on the command - line, by all hledger tools (add, iadd, hledger-web's search/add/edit + o they should be parsed correctly in input files and on the command + line, by all hledger tools (add, iadd, hledger-web's search/add/edit forms, etc.) - o they should be displayed correctly by all hledger tools, and on- + o they should be displayed correctly by all hledger tools, and on- screen alignment should be preserved. This requires a well-configured environment. Here are some tips: - o A system locale must be configured, and it must be one that can + o A system locale must be configured, and it must be one that can decode the characters being used. In bash, you can set a locale like - this: export LANG=en_US.UTF-8. There are some more details in Trou- - bleshooting. This step is essential - without it, hledger will quit - on encountering a non-ascii character (as with all GHC-compiled pro- + this: export LANG=en_US.UTF-8. There are some more details in Trou- + bleshooting. This step is essential - without it, hledger will quit + on encountering a non-ascii character (as with all GHC-compiled pro- grams). - o your terminal software (eg Terminal.app, iTerm, CMD.exe, xterm..) + o your terminal software (eg Terminal.app, iTerm, CMD.exe, xterm..) must support unicode o the terminal must be using a font which includes the required unicode glyphs - o the terminal should be configured to display wide characters as dou- + o the terminal should be configured to display wide characters as dou- ble width (for report alignment) - o on Windows, for best results you should run hledger in the same kind - of environment in which it was built. Eg hledger built in the stan- - dard CMD.EXE environment (like the binaries on our download page) - might show display problems when run in a cygwin or msys terminal, + o on Windows, for best results you should run hledger in the same kind + of environment in which it was built. Eg hledger built in the stan- + dard CMD.EXE environment (like the binaries on our download page) + might show display problems when run in a cygwin or msys terminal, and vice versa. (See eg #961). Regular expressions hledger uses regular expressions in a number of places: - o query terms, on the command line and in the hledger-web search form: + o query terms, on the command line and in the hledger-web search form: REGEX, desc:REGEX, cur:REGEX, tag:...=REGEX o CSV rules conditional blocks: if REGEX ... - o account alias directives and options: alias /REGEX/ = REPLACEMENT, + o account alias directives and options: alias /REGEX/ = REPLACEMENT, --alias /REGEX/=REPLACEMENT - hledger's regular expressions come from the regex-tdfa library. If - they're not doing what you expect, it's important to know exactly what + hledger's regular expressions come from the regex-tdfa library. If + they're not doing what you expect, it's important to know exactly what they support: 1. they are case insensitive - 2. they are infix matching (they do not need to match the entire thing + 2. they are infix matching (they do not need to match the entire thing being matched) 3. they are POSIX ERE (extended regular expressions) 4. they also support GNU word boundaries (\b, \B, \<, \>) - 5. they do not support backreferences; if you write \1, it will match - the digit 1. Except when doing text replacement, eg in account - aliases, where backreferences can be used in the replacement string + 5. they do not support backreferences; if you write \1, it will match + the digit 1. Except when doing text replacement, eg in account + aliases, where backreferences can be used in the replacement string to reference capturing groups in the search regexp. - 6. they do not support mode modifiers ((?s)), character classes (\w, + 6. they do not support mode modifiers ((?s)), character classes (\w, \d), or anything else not mentioned above. Some things to note: - o In the alias directive and --alias option, regular expressions must - be enclosed in forward slashes (/REGEX/). Elsewhere in hledger, + o In the alias directive and --alias option, regular expressions must + be enclosed in forward slashes (/REGEX/). Elsewhere in hledger, these are not required. - o In queries, to match a regular expression metacharacter like $ as a - literal character, prepend a backslash. Eg to search for amounts + o In queries, to match a regular expression metacharacter like $ as a + literal character, prepend a backslash. Eg to search for amounts with the dollar sign in hledger-web, write cur:\$. - o On the command line, some metacharacters like $ have a special mean- + o On the command line, some metacharacters like $ have a special mean- ing to the shell and so must be escaped at least once more. See Spe- cial characters. ENVIRONMENT LEDGER_FILE The journal file path when not specified with -f. Default: - ~/.hledger.journal (on windows, perhaps C:/Users/USER/.hledger.jour- + ~/.hledger.journal (on windows, perhaps C:/Users/USER/.hledger.jour- nal). - A typical value is ~/DIR/YYYY.journal, where DIR is a version-con- - trolled finance directory and YYYY is the current year. Or ~/DIR/cur- + A typical value is ~/DIR/YYYY.journal, where DIR is a version-con- + trolled finance directory and YYYY is the current year. Or ~/DIR/cur- rent.journal, where current.journal is a symbolic link to YYYY.journal. On Mac computers, you can set this and other environment variables in a - more thorough way that also affects applications started from the GUI - (say, an Emacs dock icon). Eg on MacOS Catalina I have a + more thorough way that also affects applications started from the GUI + (say, an Emacs dock icon). Eg on MacOS Catalina I have a ~/.MacOSX/environment.plist file containing { @@ -417,16 +423,16 @@ ENVIRONMENT To see the effect you may need to killall Dock, or reboot. - COLUMNS The screen width used by the register command. Default: the + COLUMNS The screen width used by the register command. Default: the full terminal width. - NO_COLOR If this variable exists with any value, hledger will not use - ANSI color codes in terminal output. This overrides the + NO_COLOR If this variable exists with any value, hledger will not use + ANSI color codes in terminal output. This is overriden by the --color/--colour option. DATA FILES - hledger reads transactions from one or more data files. The default - data file is $HOME/.hledger.journal (or on Windows, something like + hledger reads transactions from one or more data files. The default + data file is $HOME/.hledger.journal (or on Windows, something like C:/Users/USER/.hledger.journal). You can override this with the $LEDGER_FILE environment variable: @@ -443,16 +449,16 @@ DATA FILES $ cat some.journal | hledger -f- Data formats - Usually the data file is in hledger's journal format, but it can be in + Usually the data file is in hledger's journal format, but it can be in any of the supported file formats, which currently are: Reader: Reads: Used for file exten- sions: ----------------------------------------------------------------------------- - journal hledger journal files and some Ledger .journal .j .hledger + journal hledger journal files and some Ledger .journal .j .hledger journals, for transactions .ledger - time- timeclock files, for precise time log- .timeclock + time- timeclock files, for precise time log- .timeclock clock ging timedot timedot files, for approximate time .timedot logging @@ -461,13 +467,13 @@ DATA FILES These formats are described in their own sections, below. - hledger detects the format automatically based on the file extensions - shown above. If it can't recognise the file extension, it assumes - journal format. So for non-journal files, it's important to use a + hledger detects the format automatically based on the file extensions + shown above. If it can't recognise the file extension, it assumes + journal format. So for non-journal files, it's important to use a recognised file extension, so as to either read successfully or to show relevant error messages. - You can also force a specific reader/format by prefixing the file path + You can also force a specific reader/format by prefixing the file path with the format and a colon. Eg, to read a .dat file as csv format: $ hledger -f csv:/some/csv-file.dat stats @@ -477,24 +483,24 @@ DATA FILES $ echo 'i 2009/13/1 08:00:00' | hledger print -ftimeclock:- Multiple files - You can specify multiple -f options, to read multiple files as one big + You can specify multiple -f options, to read multiple files as one big journal. There are some limitations with this: o most directives do not affect sibling files - o balance assertions will not see any account balances from previous + o balance assertions will not see any account balances from previous files If you need either of those things, you can o use a single parent file which includes the others - o or concatenate the files into one before reading, eg: cat a.journal + o or concatenate the files into one before reading, eg: cat a.journal b.journal | hledger -f- CMD. Strict mode hledger checks input files for valid data. By default, the most impor- - tant errors are detected, while still accepting easy journal files + tant errors are detected, while still accepting easy journal files without a lot of declarations: o Are the input files parseable, with valid syntax ? @@ -505,7 +511,7 @@ DATA FILES With the -s/--strict flag, additional checks are performed: - o Are all accounts posted to, declared with an account directive ? + o Are all accounts posted to, declared with an account directive ? (Account error checking) o Are all commodities declared with a commodity directive ? (Commodity @@ -513,19 +519,19 @@ DATA FILES o Are all commodity conversions declared explicitly ? - You can also use the check command to run these and some additional + You can also use the check command to run these and some additional checks. TIME PERIODS Smart dates hledger's user interfaces accept a flexible "smart date" syntax. Smart - dates allow some english words, can be relative to today's date, and + dates allow some english words, can be relative to today's date, and can have less-significant date parts omitted (defaulting to 1). Examples: - 2004/10/1, 2004-01-01, exact date, several separators allowed. Year + 2004/10/1, 2004-01-01, exact date, several separators allowed. Year 2004.9.1 is 4+ digits, month is 1-12, day is 1-31 2004 start of year 2004/10 start of month @@ -540,21 +546,19 @@ TIME PERIODS 20181201 8 digit YYYYMMDD with valid year month and day 201812 6 digit YYYYMM with valid year and month - Counterexamples - malformed digit sequences might give surprising + Counterexamples - malformed digit sequences might give surprising results: - 201813 6 digits with an invalid month is parsed as start of + 201813 6 digits with an invalid month is parsed as start of 6-digit year - - - 20181301 8 digits with an invalid month is parsed as start of + 20181301 8 digits with an invalid month is parsed as start of 8-digit year 20181232 8 digits with an invalid day gives an error 201801012 9+ digits beginning with a valid YYYYMMDD gives an error - Note "today's date" can be overridden with the --today option, in case - it's needed for testing or for recreating old reports. (Except for + Note "today's date" can be overridden with the --today option, in case + it's needed for testing or for recreating old reports. (Except for periodic transaction rules; those are not affected by --today.) @@ -564,36 +568,36 @@ TIME PERIODS 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 time span, such as the current - month. You can specify a start and/or end date using -b/--begin, + Often you will want to see a shorter time span, such as the current + month. You can specify a start and/or end date using -b/--begin, -e/--end, -p/--period or a date: query (described below). All of these accept the smart date syntax. Some notes: - o End dates are exclusive, as in Ledger, so you should write the date + o End dates are exclusive, as in Ledger, so you should write the date after the last day you want to see in the report. - o As noted in reporting options: among start/end dates specified with + o As noted in reporting options: among start/end dates specified with options, the last (i.e. right-most) option takes precedence. - o The effective report start and end dates are the intersection of the - start/end dates from options and that from date: queries. That is, - date:2019-01 date:2019 -p'2000 to 2030' yields January 2019, the + o The effective report start and end dates are the intersection of the + start/end dates from options and that from date: queries. That is, + date:2019-01 date:2019 -p'2000 to 2030' yields January 2019, the smallest common time span. - o A report interval (see below) will adjust start/end dates, when + o A report interval (see below) will adjust start/end dates, when needed, so that they fall on subperiod boundaries. Examples: -b 2016/3/17 begin on St. Patrick's day 2016 - -e 12/1 end at the start of december 1st of the current year + -e 12/1 end at the start of december 1st of the current year (11/30 will be the last date included) -b thismonth all transactions on or after the 1st of the current month -p thismonth all transactions in the current month - date:2016/3/17.. the above written as queries instead (.. can also be + date:2016/3/17.. the above written as queries instead (.. can also be replaced with -) date:..12/1 date:thismonth.. @@ -617,51 +621,51 @@ TIME PERIODS o -Y/--yearly - These standard intervals always start on natural interval boundaries: - eg --weekly starts on mondays, --monthly starts on the first of the + These standard intervals always start on natural interval boundaries: + eg --weekly starts on mondays, --monthly starts on the first of the month, --yearly always starts on January 1st, etc. - Certain more complex intervals, and more flexible boundary dates, can - be specified by -p/--period. These are described in period expres- + Certain more complex intervals, and more flexible boundary dates, can + be specified by -p/--period. These are described in period expres- sions, below. - Report intervals can only be specified by the flags above, and not by + Report intervals can only be specified by the flags above, and not by query arguments, currently. - Report intervals have another effect: multi-period reports are always - expanded to fill a whole number of subperiods. So if you use a report - interval (other than --daily), and you have specified a start or end - date, you may notice those dates being overridden (ie, the report - starts earlier than your requested start date, or ends later than your + Report intervals have another effect: multi-period reports are always + expanded to fill a whole number of subperiods. So if you use a report + interval (other than --daily), and you have specified a start or end + date, you may notice those dates being overridden (ie, the report + starts earlier than your requested start date, or ends later than your requested end date). This is done to ensure "full" first and last sub- periods, so that all subperiods' numbers are comparable. To summarise: - o In multiperiod reports, all subperiods are forced to be the same + o In multiperiod reports, all subperiods are forced to be the same length, to simplify reporting. o Reports with the standard --weekly/--monthly/--quarterly/--yearly - intervals are required to start on the first day of a - week/month/quarter/year. We'd like more flexibility here but it + intervals are required to start on the first day of a + week/month/quarter/year. We'd like more flexibility here but it isn't supported yet. - o --period (below) can specify more complex intervals, starting on any + o --period (below) can specify more complex intervals, starting on any date. Period expressions - The -p/--period option accepts period expressions, a shorthand way of - expressing a start date, end date, and/or report interval all at once. + The -p/--period option accepts period expressions, a shorthand way of + expressing a start date, end date, and/or report interval all at once. - Here's a basic period expression specifying the first quarter of 2009. - Note, hledger always treats start dates as inclusive and end dates as + Here's a basic period expression specifying the first quarter of 2009. + Note, hledger always treats start dates as inclusive and end dates as exclusive: -p "from 2009/1/1 to 2009/4/1" - Keywords like "from" and "to" are optional, and so are the spaces, as - long as you don't run two dates together. "to" can also be written as + Keywords like "from" and "to" are optional, and so are the spaces, as + long as you don't run two dates together. "to" can also be written as ".." or "-". These are equivalent to the above: @@ -669,7 +673,7 @@ TIME PERIODS -p2009/1/1to2009/4/1 -p2009/1/1..2009/4/1 - Dates are smart dates, so if the current year is 2009, the above can + Dates are smart dates, so if the current year is 2009, the above can also be written as: @@ -681,40 +685,40 @@ TIME PERIODS earliest or latest transaction in your journal: + -p "from 2009/1/1" everything after january 1, 2009 -p "from 2009/1" the same -p "from 2009" the same - - -p "to 2009" everything before january + -p "to 2009" everything before january 1, 2009 - A single date with no "from" or "to" defines both the start and end + A single date with no "from" or "to" defines both the start and end date like so: - -p "2009" the year 2009; equivalent + -p "2009" the year 2009; equivalent to "2009/1/1 to 2010/1/1" - -p "2009/1" the month of jan; equiva- + -p "2009/1" the month of jan; equiva- lent to "2009/1/1 to 2009/2/1" - -p "2009/1/1" just that day; equivalent + -p "2009/1/1" just that day; equivalent to "2009/1/1 to 2009/1/2" Or you can specify a single quarter like so: - -p "2009Q1" first quarter of 2009, + -p "2009Q1" first quarter of 2009, equivalent to "2009/1/1 to 2009/4/1" -p "q4" fourth quarter of the cur- rent year Period expressions with a report interval - -p/--period's argument can also begin with, or entirely consist of, a + -p/--period's argument can also begin with, or entirely consist of, a report interval. This should be separated from the start/end dates (if - any) by a space, or the word in. The basic intervals (which can also - be written as command line flags) are daily, weekly, monthly, quar- + any) by a space, or the word in. The basic intervals (which can also + be written as command line flags) are daily, weekly, monthly, quar- terly, and yearly. Some examples: @@ -723,24 +727,24 @@ TIME PERIODS -p "quarterly" As mentioned above, the weekly, monthly, quarterly and yearly intervals - require a report start date that is the first day of a week, month, - quarter or year. And, report start/end dates will be expanded if + require a report start date that is the first day of a week, month, + quarter or year. And, report start/end dates will be expanded if needed to span a whole number of intervals. For example: - -p "weekly from 2009/1/1 starts on 2008/12/29, closest preceding Mon- + -p "weekly from 2009/1/1 starts on 2008/12/29, closest preceding Mon- to 2009/4/1" day - -p "monthly in starts on 2018/11/01 + -p "monthly in starts on 2018/11/01 2008/11/25" - -p "quarterly from starts on 2009/04/01, ends on 2009/06/30, + -p "quarterly from starts on 2009/04/01, ends on 2009/06/30, 2009-05-05 to 2009-06-01" which are first and last days of Q2 2009 -p "yearly from starts on 2009/01/01, first day of 2009 2009-12-29" More complex report intervals - Some more complex kinds of interval are also supported in period + Some more complex kinds of interval are also supported in period expressions: o biweekly @@ -753,26 +757,26 @@ TIME PERIODS o every N days|weeks|months|quarters|years - These too will cause report start/end dates to be expanded, if needed, + These too will cause report start/end dates to be expanded, if needed, to span a whole number of intervals. Examples: - -p "bimonthly from 2008" periods will have boundaries on 2008/01/01, + -p "bimonthly from 2008" periods will have boundaries on 2008/01/01, 2008/03/01, ... -p "every 2 weeks" starts on closest preceding Monday - -p "every 5 month from periods will have boundaries on 2009/03/01, + -p "every 5 month from periods will have boundaries on 2009/03/01, 2009/03" 2009/08/01, ... Intervals with custom start date - All intervals mentioned above are required to start on their natural + All intervals mentioned above are required to start on their natural calendar boundaries, but the following intervals can start on any date: Weekly on custom day: - o every Nth day of week (th, nd, rd, or st are all accepted after the + o every Nth day of week (th, nd, rd, or st are all accepted after the number) - o every WEEKDAYNAME (full or three-letter english weekday name, case + o every WEEKDAYNAME (full or three-letter english weekday name, case insensitive) Monthly on custom day: @@ -785,7 +789,7 @@ TIME PERIODS o every MM/DD [of year] (month number and day of month number) - o every MONTHNAME DDth [of year] (full or three-letter english month + o every MONTHNAME DDth [of year] (full or three-letter english month name, case insensitive, and day of month number) o every DDth MONTHNAME [of year] (equivalent to the above) @@ -796,61 +800,61 @@ TIME PERIODS -p "every 2nd day of periods will go from Tue to Tue week" -p "every Tue" same - -p "every 15th day" period boundaries will be on 15th of each + -p "every 15th day" period boundaries will be on 15th of each month - -p "every 2nd Monday" period boundaries will be on second Monday of + -p "every 2nd Monday" period boundaries will be on second Monday of each month -p "every 11/05" yearly periods with boundaries on 5th of November -p "every 5th November" same -p "every Nov 5th" same - Show historical balances at end of the 15th day of each month (N is an + Show historical balances at end of the 15th day of each month (N is an end date, exclusive as always): $ hledger balance -H -p "every 16th day" - Group postings from the start of wednesday to end of the following + Group postings from the start of wednesday to end of the following tuesday (N is both (inclusive) start date and (exclusive) end date): $ hledger register checking -p "every 3rd day of week" Periods or dates ? - Report intervals like the above are most often used with -p|--period, - to divide reports into multiple subperiods - each generated date marks - a subperiod boundary. Here, the periods between the dates are what's + Report intervals like the above are most often used with -p|--period, + to divide reports into multiple subperiods - each generated date marks + a subperiod boundary. Here, the periods between the dates are what's important. - But report intervals can also be used with --forecast to generate - future transactions, or with balance --budget to generate budget goal- - setting transactions. For these, the dates themselves are what mat- + But report intervals can also be used with --forecast to generate + future transactions, or with balance --budget to generate budget goal- + setting transactions. For these, the dates themselves are what mat- ters. Events on multiple weekdays - The every WEEKDAYNAME form has a special variant with multiple day - names, comma-separated. Eg: every mon,thu,sat. Also, weekday and - weekendday are shorthand for mon,tue,wed,thu,fri and sat,sun respec- + The every WEEKDAYNAME form has a special variant with multiple day + names, comma-separated. Eg: every mon,thu,sat. Also, weekday and + weekendday are shorthand for mon,tue,wed,thu,fri and sat,sun respec- tively. This form is mainly intended for use with --forecast, to generate peri- odic transactions on arbitrary days of the week. It may be less useful - with -p, since it divides each week into subperiods of unequal length. - (Because gaps between periods are not allowed; if you'd like to change + with -p, since it divides each week into subperiods of unequal length. + (Because gaps between periods are not allowed; if you'd like to change this, see #1632.) Examples: - -p "every dates will be Mon, Wed, Fri; periods will be Mon- + -p "every dates will be Mon, Wed, Fri; periods will be Mon- mon,wed,fri" Tue, Wed-Thu, Fri-Sun - -p "every weekday" dates will be Mon, Tue, Wed, Thu, Fri; periods will + -p "every weekday" dates will be Mon, Tue, Wed, Thu, Fri; periods will be Mon, Tue, Wed, Thu, Fri-Sun -p "every weekend- dates will be Sat, Sun; periods will be Sat, Sun-Fri day" DEPTH - With the --depth NUM option (short form: -NUM), commands like account, - balance and register will show only the uppermost accounts in the + With the --depth NUM option (short form: -NUM), commands like account, + balance and register will show only the uppermost accounts in the account tree, down to level NUM. Use this when you want a summary with less detail. This flag has the same effect as a depth: query argument: depth:2, --depth=2 or -2 are equivalent. @@ -860,12 +864,12 @@ QUERIES subset of your data. Most hledger commands accept optional query argu- ments to restrict their scope. The syntax is as follows: - o Zero or more space-separated query terms. These are most often + o Zero or more space-separated query terms. These are most often account name substrings: utilities food:groceries - o Terms with spaces or other special characters should be enclosed in + o Terms with spaces or other special characters should be enclosed in quotes: "personal care" @@ -887,16 +891,16 @@ QUERIES prefixed with not: to convert them into a negative match. acct:REGEX, REGEX - Match account names containing this (case insensitive) regular expres- + Match account names containing this (case insensitive) regular expres- sion. This is the default query type when there is no prefix, and reg- - ular expression syntax is typically not needed, so usually we just + ular expression syntax is typically not needed, so usually we just write an account name substring, like expenses or food. amt:N, amt:N, amt:>=N - Match postings with a single-commodity amount equal to, less than, or - greater than N. (Postings with multi-commodity amounts are not tested - and will always match.) The comparison has two modes: if N is preceded - by a + or - sign (or is 0), the two signed numbers are compared. Oth- + Match postings with a single-commodity amount equal to, less than, or + greater than N. (Postings with multi-commodity amounts are not tested + and will always match.) The comparison has two modes: if N is preceded + by a + or - sign (or is 0), the two signed numbers are compared. Oth- erwise, the absolute magnitudes are compared, ignoring sign. code:REGEX @@ -904,10 +908,10 @@ QUERIES cur:REGEX Match postings or transactions including any amounts whose cur- - rency/commodity symbol is fully matched by REGEX. (For a partial - match, use .*REGEX.*). Note, to match special characters which are - regex-significant, you need to escape them with \. And for characters - which are significant to your shell you may need one more level of + rency/commodity symbol is fully matched by REGEX. (For a partial + match, use .*REGEX.*). Note, to match special characters which are + regex-significant, you need to escape them with \. And for characters + which are significant to your shell you may need one more level of escaping. So eg to match the dollar sign: hledger print cur:\\$. @@ -915,17 +919,17 @@ QUERIES Match transaction descriptions. date:PERIODEXPR - Match dates (or with the --date2 flag, secondary dates) within the - specified period. PERIODEXPR is a period expression with no report + Match dates (or with the --date2 flag, secondary dates) within the + specified period. PERIODEXPR is a period expression with no report interval. Examples: date:2016, date:thismonth, date:2/1-2/15, date:2021-07-27..nextquarter. date2:PERIODEXPR - Match secondary dates within the specified period (independent of the + Match secondary dates within the specified period (independent of the --date2 flag). depth:N - Match (or display, depending on command) accounts at or above this + Match (or display, depending on command) accounts at or above this depth. note:REGEX @@ -933,7 +937,7 @@ QUERIES whole description if there's no |). payee:REGEX - Match transaction payee/payer names (the part of the description left + Match transaction payee/payer names (the part of the description left of |, or the whole description if there's no |). real:, real:0 @@ -944,12 +948,12 @@ QUERIES tag:REGEX[=REGEX] Match by tag name, and optionally also by tag value. (To match only by - value, use tag:.=REGEX.) Note that postings also inherit tags from - their transaction, and transactions also acquire tags from their post- + value, use tag:.=REGEX.) Note that postings also inherit tags from + their transaction, and transactions also acquire tags from their post- ings, when querying. (inacct:ACCTNAME - A special query term used automatically in hledger-web only: tells + A special query term used automatically in hledger-web only: tells hledger-web to show the transaction register for an account.) Combining query terms @@ -973,29 +977,29 @@ QUERIES o match all the other terms. - You can do more powerful queries (such as AND-ing two like terms) by - running a first query with print, and piping the result into a second + You can do more powerful queries (such as AND-ing two like terms) by + running a first query with print, and piping the result into a second hledger command. Eg: how much of food expenses was paid with cash ? $ hledger print assets:cash | hledger -f- -I balance expenses:food - If you are interested in full boolean expressions for queries, see + If you are interested in full boolean expressions for queries, see #203. Queries and command options - Some queries can also be expressed as command-line options: depth:2 is + Some queries can also be expressed as command-line options: depth:2 is equivalent to --depth 2, date:2020 is equivalent to -p 2020, etc. When - you mix command options and query arguments, generally the resulting + you mix command options and query arguments, generally the resulting query is their intersection. Queries and account aliases - When account names are rewritten with --alias or alias, acct: will + When account names are rewritten with --alias or alias, acct: will match either the old or the new account name. Queries and valuation - When amounts are converted to other commodities in cost or value - reports, cur: and amt: match the old commodity symbol and the old - amount quantity, not the new ones (except in hledger 1.22.0 where it's + When amounts are converted to other commodities in cost or value + reports, cur: and amt: match the old commodity symbol and the old + amount quantity, not the new ones (except in hledger 1.22.0 where it's reversed, see #1625). Querying with account aliases @@ -1003,92 +1007,92 @@ QUERIES will match either the old or the new account name. Querying with cost or value - When amounts are converted to other commodities in cost or value - reports, note that cur: matches the new commodity symbol, and not the + When amounts are converted to other commodities in cost or value + reports, note that cur: matches the new commodity symbol, and not the old one, and amt: matches the new quantity, and not the old one. Note: - this changed in hledger 1.22, previously it was the reverse, see the + this changed in hledger 1.22, previously it was the reverse, see the discussion at #1625. COSTING - The -B/--cost flag converts amounts to their cost or sale amount at - transaction time, if they have a transaction price specified. If this - flag is supplied, hledger will perform cost conversion first, and will + The -B/--cost flag converts amounts to their cost or sale amount at + transaction time, if they have a transaction price specified. If this + flag is supplied, hledger will perform cost conversion first, and will apply any market price valuations (if requested) afterwards. VALUATION - Instead of reporting amounts in their original commodity, hledger can + Instead of reporting amounts in their original commodity, hledger can convert them to cost/sale amount (using the conversion rate recorded in - the transaction), and/or to market value (using some market price on a - certain date). This is controlled by the --value=TYPE[,COMMODITY] - option, which will be described below. We also provide the simpler -V + the transaction), and/or to market value (using some market price on a + certain date). This is controlled by the --value=TYPE[,COMMODITY] + option, which will be described below. We also provide the simpler -V and -X COMMODITY options, and often one of these is all you need: -V: Value - The -V/--market flag converts amounts to market value in their default + The -V/--market flag converts amounts to market value in their default valuation commodity, using the market prices in effect on the valuation date(s), if any. More on these in a minute. -X: Value in specified commodity The -X/--exchange=COMM option is like -V, except you tell it which cur- - rency you want to convert to, and it tries to convert everything to + rency you want to convert to, and it tries to convert everything to that. Valuation date - Since market prices can change from day to day, market value reports + Since market prices can change from day to day, market value reports have a valuation date (or more than one), which determines which market prices will be used. For single period reports, if an explicit report end date is specified, - that will be used as the valuation date; otherwise the valuation date + that will be used as the valuation date; otherwise the valuation date is the journal's end date. - For multiperiod reports, each column/period is valued on the last day + For multiperiod reports, each column/period is valued on the last day of the period, by default. Market prices - To convert a commodity A to its market value in another commodity B, - hledger looks for a suitable market price (exchange rate) as follows, + To convert a commodity A to its market value in another commodity B, + hledger looks for a suitable market price (exchange rate) as follows, in this order of preference : - 1. A declared market price or inferred market price: A's latest market + 1. A declared market price or inferred market price: A's latest market price in B on or before the valuation date as declared by a P direc- - tive, or (with the --infer-market-prices flag) inferred from trans- + tive, or (with the --infer-market-prices flag) inferred from trans- action prices. 2. A reverse market price: the inverse of a declared or inferred market price from B to A. - 3. A forward chain of market prices: a synthetic price formed by com- + 3. A forward chain of market prices: a synthetic price formed by com- bining the shortest chain of "forward" (only 1 above) market prices, leading from A to B. - 4. Any chain of market prices: a chain of any market prices, including - both forward and reverse prices (1 and 2 above), leading from A to + 4. Any chain of market prices: a chain of any market prices, including + both forward and reverse prices (1 and 2 above), leading from A to B. - There is a limit to the length of these price chains; if hledger - reaches that length without finding a complete chain or exhausting all - possibilities, it will give up (with a "gave up" message visible in + There is a limit to the length of these price chains; if hledger + reaches that length without finding a complete chain or exhausting all + possibilities, it will give up (with a "gave up" message visible in --debug=2 output). That limit is currently 1000. - Amounts for which no suitable market price can be found, are not con- + Amounts for which no suitable market price can be found, are not con- verted. --infer-market-prices: market prices from transactions Normally, market value in hledger is fully controlled by, and requires, P directives in your journal. Since adding and updating those can be a - chore, and since transactions usually take place at close to market + chore, and since transactions usually take place at close to market value, why not use the recorded transaction prices as additional market prices (as Ledger does) ? We could produce value reports without need- ing P directives at all. - Adding the --infer-market-prices flag to -V, -X or --value enables - this. So for example, hledger bs -V --infer-market-prices will get - market prices both from P directives and from transactions. (And if + Adding the --infer-market-prices flag to -V, -X or --value enables + this. So for example, hledger bs -V --infer-market-prices will get + market prices both from P directives and from transactions. (And if both occur on the same day, the P directive takes precedence). There is a downside: value reports can sometimes be affected in confus- - ing/undesired ways by your journal entries. If this happens to you, + ing/undesired ways by your journal entries. If this happens to you, read all of this Valuation section carefully, and try adding --debug or --debug=2 to troubleshoot. @@ -1096,43 +1100,43 @@ VALUATION o multicommodity transactions with explicit prices (@/@@) - o multicommodity transactions with implicit prices (no @, two commodi- - ties, unbalanced). (With these, the order of postings matters. + o multicommodity transactions with implicit prices (no @, two commodi- + ties, unbalanced). (With these, the order of postings matters. hledger print -x can be useful for troubleshooting.) - o but not, currently, from "more correct" multicommodity transactions + o but not, currently, from "more correct" multicommodity transactions (no @, multiple commodities, balanced). Valuation commodity When you specify a valuation commodity (-X COMM or --value TYPE,COMM): - hledger will convert all amounts to COMM, wherever it can find a suit- + hledger will convert all amounts to COMM, wherever it can find a suit- able market price (including by reversing or chaining prices). - When you leave the valuation commodity unspecified (-V or --value + When you leave the valuation commodity unspecified (-V or --value TYPE): - For each commodity A, hledger picks a default valuation commodity as + For each commodity A, hledger picks a default valuation commodity as follows, in this order of preference: 1. The price commodity from the latest P-declared market price for A on or before valuation date. 2. The price commodity from the latest P-declared market price for A on - any date. (Allows conversion to proceed when there are inferred + any date. (Allows conversion to proceed when there are inferred prices before the valuation date.) - 3. If there are no P directives at all (any commodity or date) and the - --infer-market-prices flag is used: the price commodity from the + 3. If there are no P directives at all (any commodity or date) and the + --infer-market-prices flag is used: the price commodity from the latest transaction-inferred price for A on or before valuation date. This means: - o If you have P directives, they determine which commodities -V will + o If you have P directives, they determine which commodities -V will convert, and to what. - o If you have no P directives, and use the --infer-market-prices flag, + o If you have no P directives, and use the --infer-market-prices flag, transaction prices determine it. - Amounts for which no valuation commodity can be found are not con- + Amounts for which no valuation commodity can be found are not con- verted. Simple valuation examples @@ -1159,7 +1163,7 @@ VALUATION $ hledger -f t.j bal -N euros -V -e 2016/11/4 $110.00 assets:euros - What are they worth after 2016/12/21 ? (no report end date specified, + What are they worth after 2016/12/21 ? (no report end date specified, defaults to today) $ hledger -f t.j bal -N euros -V @@ -1179,31 +1183,31 @@ VALUATION The TYPE part selects cost or value and valuation date: --value=then - Convert amounts to their value in the default valuation commod- + Convert amounts to their value in the default valuation commod- ity, using market prices on each posting's date. --value=end - Convert amounts to their value in the default valuation commod- - ity, using market prices on the last day of the report period - (or if unspecified, the journal's end date); or in multiperiod + Convert amounts to their value in the default valuation commod- + ity, using market prices on the last day of the report period + (or if unspecified, the journal's end date); or in multiperiod reports, market prices on the last day of each subperiod. --value=now - Convert amounts to their value in the default valuation commod- - ity using current market prices (as of when report is gener- + Convert amounts to their value in the default valuation commod- + ity using current market prices (as of when report is gener- ated). --value=YYYY-MM-DD - Convert amounts to their value in the default valuation commod- + Convert amounts to their value in the default valuation commod- ity using market prices on this date. To select a different valuation commodity, add the optional ,COMM part: - a comma, then the target commodity's symbol. Eg: --value=now,EUR. + a comma, then the target commodity's symbol. Eg: --value=now,EUR. hledger will do its best to convert amounts to this commodity, deducing market prices as described above. More valuation examples - Here are some examples showing the effect of --value, as seen with + Here are some examples showing the effect of --value, as seen with print: P 2000-01-01 A 1 B @@ -1241,7 +1245,7 @@ VALUATION 2000-02-01 (a) 2 B - With no report period specified, that shows the value as of the last + With no report period specified, that shows the value as of the last day of the journal (2000-03-01): $ hledger -f- print --value=end @@ -1278,7 +1282,7 @@ VALUATION 2000-03-01 (a) 1 B - You may need to explicitly set a commodity's display style, when + You may need to explicitly set a commodity's display style, when reverse prices are used. Eg this output might be surprising: P 2000-01-01 A 2B @@ -1292,10 +1296,10 @@ VALUATION a 0 b 0 - Explanation: because there's no amount or commodity directive specify- - ing a display style for A, 0.5A gets the default style, which shows no + Explanation: because there's no amount or commodity directive specify- + ing a display style for A, 0.5A gets the default style, which shows no decimal digits. Because the displayed amount looks like zero, the com- - modity symbol and minus sign are not displayed either. Adding a com- + modity symbol and minus sign are not displayed either. Adding a com- modity directive sets a more useful display style for A: P 2000-01-01 A 2B @@ -1311,18 +1315,19 @@ VALUATION b -0.50A Effect of valuation on reports - Here is a reference for how valuation is supposed to affect each part - of hledger's reports (and a glossary). (It's wide, you'll have to - scroll sideways.) It may be useful when troubleshooting. If you find - problems, please report them, ideally with a reproducible example. + Here is a reference for how valuation is supposed to affect each part + of hledger's reports (and a glossary). (It's wide, you'll have to + scroll sideways.) It may be useful when troubleshooting. If you find + problems, please report them, ideally with a reproducible example. Related: #329, #1083. + Report -B, --cost -V, -X --value=then --value=end --value=DATE, type --value=now ----------------------------------------------------------------------------------------------- print - posting cost value at value at posting value at value at + posting cost value at value at posting value at value at amounts report end date report or DATE/today or today journal end balance unchanged unchanged unchanged unchanged unchanged @@ -1336,7 +1341,7 @@ VALUATION report or posting was made report or journal journal start start - posting cost value at value at posting value at value at + posting cost value at value at posting value at value at amounts report end date report or DATE/today or today journal end summary post- summarised value at sum of postings value at value at @@ -1349,20 +1354,20 @@ VALUATION balance (bs, bse, cf, is) - balance sums of value at value at posting value at value at + balance sums of value at value at posting value at value at changes costs report end date report or DATE/today of - or today of journal end sums of post- + or today of journal end sums of post- sums of of sums of ings postings postings budget like balance like balance like balance like bal- like balance amounts changes changes changes ances changes (--budget) - grand total sum of dis- sum of dis- sum of displayed sum of dis- sum of dis- + grand total sum of dis- sum of dis- sum of displayed sum of dis- sum of dis- played val- played val- valued played val- played values ues ues ues balance (bs, - bse, cf, is) + bse, cf, is) with report interval starting bal- sums of value at sums of values of value at sums of post- @@ -1376,13 +1381,6 @@ VALUATION is, bs postings in period at respec- each period, sums of post- --change, cf period tive posting valued at ings --change) dates period ends - - - - - - - end balances sums of same as sums of values of period end value at (bal -H, is costs of --value=end postings from balances, DATE/today of --H, bs, cf) postings before period valued at sums of post- @@ -1393,11 +1391,15 @@ VALUATION budget like balance like balance like balance like bal- like balance amounts changes/end changes/end changes/end bal- ances changes/end (--budget) balances balances ances balances + + + + row totals, sums, aver- sums, aver- sums, averages of sums, aver- sums, aver- - row averages ages of dis- ages of dis- displayed values ages of dis- ages of dis- + row averages ages of dis- ages of dis- displayed values ages of dis- ages of dis- (-T, -A) played val- played val- played val- played values ues ues ues - column totals sums of dis- sums of dis- sums of displayed sums of dis- sums of dis- + column totals sums of dis- sums of dis- sums of displayed sums of dis- sums of dis- played val- played val- values played val- played values ues ues ues grand total, sum, average sum, average sum, average of sum, average sum, average @@ -1412,43 +1414,43 @@ VALUATION cost calculated using price(s) recorded in the transaction(s). - value market value using available market price declarations, or the + value market value using available market price declarations, or the unchanged amount if no conversion rate can be found. report start - the first day of the report period specified with -b or -p or + the first day of the report period specified with -b or -p or date:, otherwise today. report or journal start - the first day of the report period specified with -b or -p or - date:, otherwise the earliest transaction date in the journal, + the first day of the report period specified with -b or -p or + date:, otherwise the earliest transaction date in the journal, otherwise today. report end - the last day of the report period specified with -e or -p or + the last day of the report period specified with -e or -p or date:, otherwise today. report or journal end - the last day of the report period specified with -e or -p or - date:, otherwise the latest transaction date in the journal, + the last day of the report period specified with -e or -p or + date:, otherwise the latest transaction date in the journal, otherwise today. report interval - a flag (-D/-W/-M/-Q/-Y) or period expression that activates the + a flag (-D/-W/-M/-Q/-Y) or period expression that activates the report's multi-period mode (whether showing one or many subperi- ods). PIVOTING Normally hledger sums amounts, and organizes them in a hierarchy, based - on account name. The --pivot FIELD option causes it to sum and orga- - nize hierarchy based on the value of some other field instead. FIELD + on account name. The --pivot FIELD option causes it to sum and orga- + nize hierarchy based on the value of some other field instead. FIELD can be: code, description, payee, note, or the full name (case insensi- tive) of any tag. As with account names, values containing colon:sepa- rated:parts will be displayed hierarchically in reports. - --pivot is a general option affecting all reports; you can think of + --pivot is a general option affecting all reports; you can think of hledger transforming the journal before any other processing, replacing - every posting's account name with the value of the specified field on + every posting's account name with the value of the specified field on that posting, inheriting it from the transaction or using a blank value if it's not present. @@ -1474,7 +1476,7 @@ PIVOTING -------------------- 0 - One way to show only amounts with a member: value (using a query, + One way to show only amounts with a member: value (using a query, described below): $ hledger balance --pivot member tag:member=. @@ -1482,7 +1484,7 @@ PIVOTING -------------------- -2 EUR - Another way (the acct: query matches against the pivoted "account + Another way (the acct: query matches against the pivoted "account name"): $ hledger balance --pivot member acct:. @@ -1497,18 +1499,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) - hledger can optionally produce debug output (if enabled with - --debug=N); this goes to stderr, and is not affected by -o/--output- - file. If you need to capture it, use shell redirects, eg: hledger bal + hledger can optionally produce debug output (if enabled with + --debug=N); this goes to stderr, and is not affected by -o/--output- + file. If you need to capture it, use shell redirects, eg: hledger bal --debug=3 >file 2>&1. + Output styling + hledger commands can produce colour output when the terminal supports + it. This is controlled by the --color/--colour option: - if the + --color/--colour option is given a value of yes or always (or no or + never), colour will (or will not) be used; - otherwise, if the NO_COLOR + environment variable is set, colour will not be used; - otherwise, + colour will be used if the output (terminal or file) supports it. + + hledger commands can also use unicode box-drawing characters to produce + prettier tables and output. This is controlled by the --pretty option: + - if the --pretty option is given a value of yes or always (or no or + never), unicode characters will (or will not) be used; - otherwise, + unicode characters will not be used. + Output format Some commands (print, register, the balance commands) offer a choice of output format. In addition to the usual plain text format (txt), there @@ -2335,6 +2351,8 @@ COMMANDS --change change in period sum of posting- period-end DATE-value of date market val- value of change change in ues in period in period period + + --cumu- change from sum of posting- period-end DATE-value of lative report start to date market val- value of change change from period end ues from report from report report start @@ -2960,8 +2978,6 @@ COMMANDS -e 2021-01-01 end dates are exclusive -e 2021 equivalent, per smart dates - - -p 2020 equivalent, the period's begin date is ignored date:2020 equivalent query @@ -4794,11 +4810,6 @@ JOURNAL FORMAT rent file or end directive - - - - - commod- format declare a commodity and its number notation: ity number notation & display following entries style until end of cur- @@ -5737,6 +5748,8 @@ CSV FORMAT newest-first disambiguate record order when there's only one date include inline another CSV rules file + + balance-type choose which type of balance assignments to use @@ -7432,4 +7445,4 @@ SEE ALSO -hledger-1.22.99 September 2021 HLEDGER(1) +hledger-1.23 September 2021 HLEDGER(1)