diff --git a/CHANGES.md b/CHANGES.md --- a/CHANGES.md +++ b/CHANGES.md @@ -1,12 +1,11 @@ User-visible changes in the hledger command line tool and library. -# 1.15 2019-09-01 - -- help: don't require a journal file +# ebacb20b -- reg: show negative amounts in red, like balance and Ledger +- add commodities, descriptions, diff, notes, payees commands to manual +# 1.15 2019-09-01 ## General @@ -71,10 +70,14 @@ - descriptions, payees, notes commands added (Caleb Maclennan) -- Gabriel Ebner's hledger-diff is now a built in command, +- diff: Gabriel Ebner's hledger-diff is now a built in command, and https://github.com/gebner/hledger-diff is deprecated. +- help: don't require a journal file + - print: now also canonicalises the display style of balance assertion amounts (#1042) + +- reg: show negative amounts in red, like balance and Ledger - reg: fix `--average`, broken since 1.12 (#1003) diff --git a/Hledger/Cli/Commands/Descriptions.hs b/Hledger/Cli/Commands/Descriptions.hs --- a/Hledger/Cli/Commands/Descriptions.hs +++ b/Hledger/Cli/Commands/Descriptions.hs @@ -8,16 +8,12 @@ {-# LANGUAGE OverloadedStrings #-} {-# LANGUAGE ScopedTypeVariables #-} {-# LANGUAGE TemplateHaskell #-} -{-# LANGUAGE CPP #-} module Hledger.Cli.Commands.Descriptions ( descriptionsmode ,descriptions ) where -#if !(MIN_VERSION_base(4,11,0)) -import Data.Monoid -#endif import Data.List import qualified Data.Text.IO as T diff --git a/Hledger/Cli/Commands/Notes.hs b/Hledger/Cli/Commands/Notes.hs --- a/Hledger/Cli/Commands/Notes.hs +++ b/Hledger/Cli/Commands/Notes.hs @@ -15,9 +15,6 @@ ,notes ) where -#if !(MIN_VERSION_base(4,11,0)) -import Data.Monoid -#endif import Data.List import qualified Data.Text.IO as T diff --git a/Hledger/Cli/Commands/Payees.hs b/Hledger/Cli/Commands/Payees.hs --- a/Hledger/Cli/Commands/Payees.hs +++ b/Hledger/Cli/Commands/Payees.hs @@ -15,9 +15,6 @@ ,payees ) where -#if !(MIN_VERSION_base(4,11,0)) -import Data.Monoid -#endif import Data.List import qualified Data.Text.IO as T diff --git a/embeddedfiles/hledger-ui.txt b/embeddedfiles/hledger-ui.txt --- a/embeddedfiles/hledger-ui.txt +++ b/embeddedfiles/hledger-ui.txt @@ -117,8 +117,8 @@ using period expressions syntax --date2 - match the secondary date instead (see command help for other - effects) + match the secondary date instead (see command help for other ef- + fects) -U --unmarked include only unmarked postings/txns (can combine with -P or -C) @@ -204,8 +204,8 @@ BACKSPACE or DELETE removes all filters, showing all transactions. As mentioned above, hledger-ui shows auto-generated periodic transac- - tions, and hides future transactions (auto-generated or not) by - default. F toggles showing and hiding these future transactions. This + tions, and hides future transactions (auto-generated or not) by de- + fault. F toggles showing and hiding these future transactions. This is similar to using a query like date:-tomorrow, but more convenient. (experimental) @@ -227,8 +227,8 @@ file. This allows some basic data entry. A is like a, but runs the hledger-iadd tool, which provides a curses- - style interface. This key will be available if hledger-iadd is - installed in $PATH. + style interface. This key will be available if hledger-iadd is in- + stalled 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 @@ -250,36 +250,35 @@ Account names are shown as a flat list by default. Press T to toggle tree mode. In flat 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. + counts, except where subaccounts are hidden by a depth limit (see be- + low). In tree mode, all account balances are inclusive of subaccounts. - 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 - ESCAPE. + less detail, collapsing all accounts to a single total. To remove the + depth limit, set it higher than the maximum account depth, or press ES- + CAPE. 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 - before the report start date, so they show the change in balance during + 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 be- + fore 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 - included; and if you activate all three, the filter is removed.) + toggles cleared postings. (By default, balances include all postings; + if you activate one or two status filters, only those postings are in- + cluded; 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. @@ -288,32 +287,32 @@ 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 flat - mode but this account has subaccounts which are not shown due to a - depth limit. In other words, the register always shows the transac- + 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/flat 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. @@ -329,16 +328,16 @@ 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 - (or in certain cases, fewer). + The transaction's date(s) and any cleared flag, transaction code, de- + scription, comments, along with all of its account postings are shown. + Simple transactions have two postings, but there can be more (or in + certain cases, fewer). up and down will step through all transactions listed in the previous account register screen. In the title bar, the numbers in parentheses - show your position within that account register. They will vary - depending on which account register you came from (remember most trans- - actions appear in multiple account registers). The #N number preceding + show your position within that account register. They will vary de- + pending on which account register you came from (remember most transac- + tions appear in multiple account registers). The #N number preceding them is the transaction's position within the complete unfiltered jour- nal, which is a more stable id (at least until the next reload). diff --git a/embeddedfiles/hledger-web.txt b/embeddedfiles/hledger-web.txt --- a/embeddedfiles/hledger-web.txt +++ b/embeddedfiles/hledger-web.txt @@ -19,9 +19,9 @@ hledger-web is hledger's web interface. It starts a simple web appli- cation for browsing and adding transactions, and optionally opens it in a web browser window if possible. It provides a more user-friendly UI - than the hledger CLI or hledger-ui interface, showing more at once - (accounts, the current account register, balance charts) and allowing - history-aware data entry, interactive searching, and bookmarking. + than the hledger CLI or hledger-ui interface, showing more at once (ac- + counts, the current account register, balance charts) and allowing his- + tory-aware data entry, interactive searching, and bookmarking. hledger-web also lets you share a ledger with multiple users, or even the public web. There is no access control, so if you need that you @@ -127,8 +127,8 @@ using period expressions syntax --date2 - match the secondary date instead (see command help for other - effects) + match the secondary date instead (see command help for other ef- + fects) -U --unmarked include only unmarked postings/txns (can combine with -P or -C) @@ -208,14 +208,14 @@ 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 - machine. + o setting the IP address it listens on (see --host above). By default + it listens on 127.0.0.1, accessible to all users on the local ma- + chine. o putting it behind an authenticating proxy, using eg apache or nginx @@ -224,54 +224,54 @@ 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 - included files + o manage - allows editing, uploading or downloading the main or in- + cluded files - o using the --capabilities-header=HTTPHEADER flag to specify a HTTP - header from which it will read capabilities to enable. hledger-web - on Sandstorm uses the X-Sandstorm-Permissions header to integrate + o using the --capabilities-header=HTTPHEADER flag to specify a HTTP + header from which it will read capabilities to enable. hledger-web + on Sandstorm uses the X-Sandstorm-Permissions header to integrate with Sandstorm's permissions. This is disabled by default. EDITING, UPLOADING, DOWNLOADING - If you enable the manage capability mentioned above, you'll see a new - "spanner" button to the right of the search form. Clicking this will - let you edit, upload, or download the journal file or any files it - includes. + If you enable the manage capability mentioned above, you'll see a new + "spanner" button to the right of the search form. Clicking this will + let you edit, upload, or download the journal file or any files it in- + cludes. - Note, unlike any other hledger command, in this mode you (or any visi- + Note, unlike any other hledger command, in this mode you (or any visi- tor) can alter or wipe the data files. - Normally whenever a file is changed in this way, hledger-web saves a - numbered backup (assuming file permissions allow it, the disk is not - full, etc.) hledger-web is not aware of version control systems, cur- - rently; if you use one, you'll have to arrange to commit the changes + Normally whenever a file is changed in this way, hledger-web saves a + numbered backup (assuming file permissions allow it, the disk is not + full, etc.) hledger-web is not aware of version control systems, cur- + rently; if you use one, you'll have to arrange to commit the changes yourself (eg with a cron job or a file watcher like entr). - Changes which would leave the journal file(s) unparseable or non-valid - (eg with failing balance assertions) are prevented. (Probably. This + Changes which would leave the journal file(s) unparseable or non-valid + (eg with failing balance assertions) are prevented. (Probably. This needs re-testing.) RELOADING hledger-web detects changes made to the files by other means (eg if you - edit it directly, outside of hledger-web), and it will show the new - data when you reload the page or navigate to a new page. If a change - makes a file unparseable, hledger-web will display an error message - until the file has been fixed. + edit it directly, outside of hledger-web), and it will show the new + data when you reload the page or navigate to a new page. If a change + makes a file unparseable, hledger-web will display an error message un- + til the file has been fixed. (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 provides some API routes that - serve JSON in response to GET requests. Currently these are same ones - provided by the hledger-api tool, but hledger-web will likely receive + In addition to the web UI, hledger-web provides some API routes that + serve JSON in response to GET requests. Currently these are same ones + provided by the hledger-api tool, but hledger-web will likely receive more attention than hledger-api in future: /accountnames @@ -281,17 +281,17 @@ /accounts /accounttransactions/#AccountName - Also, you can append a new transaction to the journal by sending a PUT - request to /add (hledger-web only). As with the web UI's add form, - hledger-web must be started with the add capability for this (enabled + Also, you can append a new transaction to the journal by sending a PUT + request to /add (hledger-web only). As with the web UI's add form, + hledger-web must be started with the add capability for this (enabled by default). - The payload should be a valid hledger transaction as JSON, similar to + The payload should be a valid hledger transaction as JSON, similar to what you get from /transactions or /accounttransactions. - Another way to generate test data is with the readJsonFile/writeJson- - File helpers in Hledger.Web.Json, which read or write any of hledger's - JSON-capable types from or to a file. Eg here we write the first + Another way to generate test data is with the readJsonFile/writeJson- + File helpers in Hledger.Web.Json, which read or write any of hledger's + JSON-capable types from or to a file. Eg here we write the first transaction of a sample journal: $ make ghci-web @@ -306,23 +306,23 @@ $ curl -s http://127.0.0.1:5000/add -X PUT -H 'Content-Type: application/json' --data-binary @txn.pretty.json; echo - By default, both the server-side HTML UI and the JSON API are served. - Running with --serve-api disables the former, useful if you only want + By default, both the server-side HTML UI and the JSON API are served. + Running with --serve-api disables the former, useful if you only want to serve the API. 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). 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). @@ -336,7 +336,7 @@ 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) @@ -350,7 +350,7 @@ SEE ALSO - hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1), + hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1), hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_time- dot(5), ledger(1) diff --git a/embeddedfiles/hledger.1 b/embeddedfiles/hledger.1 --- a/embeddedfiles/hledger.1 +++ b/embeddedfiles/hledger.1 @@ -1013,36 +1013,32 @@ .SS -V: Market value .PP The \f[C]-V/--market\f[R] flag converts reported amounts to their market -value in a default valuation commodity, using the historical market -prices in effect on a default valuation date. -.PP -For single period reports, the valuation date is today. -For multiperiod reports, it is the last day of each subperiod. +value in a default valuation commodity, using the market prices in +effect on a default valuation date. +For single period reports, the valuation date is today; for multiperiod +reports, it is the last day of each subperiod. +It is equivalent to \f[C]--value=now\f[R] or \f[C]--value=end\f[R] (see +below). .PP -The valuation commodity will be the one referenced in the latest +The default valuation commodity is the one referenced in the latest applicable market price dated on or before the valuation date. If most of your P declarations lead to a single home currency, this will usually be what you want. -.PP -Unlike the similar flag in Ledger, it does not infer market prices from -transaction prices. -In hledger, -B uses transaction prices, -V and -X use market prices. -.PP -It is equivalent to \f[C]--value=now\f[R] or \f[C]--value=end\f[R]. +(To specify the commodity, see -X below.) .PP Here\[aq]s a quick example: .IP .nf \f[C] -# one euro is worth this many dollars from nov 1 +; one euro is worth this many dollars from nov 1 P 2016/11/01 \[Eu] $1.10 -# purchase some euros on nov 3 +; purchase some euros on nov 3 2016/11/3 assets:euros \[Eu]100 assets:checking -# the euro is worth fewer dollars by dec 21 +; the euro is worth fewer dollars by dec 21 P 2016/12/21 \[Eu] $1.03 \f[R] .fi @@ -1074,15 +1070,19 @@ $103.00 assets:euros \f[R] .fi +.PP +Note that in hledger, market prices are always declared explicitly with +P directives; we do not infer them from transaction prices as Ledger +does. .SS -X: Market value in specified commodity .PP The \f[C]-X/--exchange\f[R] option is like \f[C]-V/--market\f[R] except it takes a commodity symbol argument, so that you can select a different target commodity. It is similar to the same option in Ledger, with the same caveat -mentioned for \f[C]-V\f[R]/\f[C]--value\f[R] above. +mentioned above. It is equivalent to \f[C]--value=now,COMM\f[R] or -\f[C]--value=end,COMM\f[R]; for more details, read on. +\f[C]--value=end,COMM\f[R]. .SS --value .PP \f[I](experimental, added 201905)\f[R] @@ -2628,6 +2628,65 @@ assets:checking \f[R] .fi +.SS commodities +.PP +commodities +.PD 0 +.P +.PD +List all commodity/currency symbols used or declared in the journal. +.SS descriptions +.PP +descriptions Show descriptions. +.PP +This command lists all descriptions that appear in transactions. +.PP +Examples: +.IP +.nf +\f[C] +$ hledger descriptions +Store Name +Gas Station | Petrol +Person A +\f[R] +.fi +.SS diff +.PP +diff +.PD 0 +.P +.PD +Compares a particular account\[aq]s transactions in two input files. +It shows any transactions to this account which are in one file but not +in the other. +.PP +More precisely, for each posting affecting this account in either file, +it looks for a corresponding posting in the other file which posts the +same amount to the same account (ignoring date, description, etc.) Since +postings not transactions are compared, this also works when multiple +bank transactions have been combined into a single journal entry. +.PP +This is useful eg if you have downloaded an account\[aq]s transactions +from your bank (eg as CSV data). +When hledger and your bank disagree about the account balance, you can +compare the bank data with your journal to find out the cause. +.PP +Examples: +.IP +.nf +\f[C] +$ hledger diff -f $LEDGER_FILE -f bank.csv assets:bank:giro +These transactions are in the first file only: + +2014/01/01 Opening Balances + assets:bank:giro EUR ... + ... + equity:opening balances EUR -... + +These transactions are in the second file only: +\f[R] +.fi .SS files .PP files @@ -2785,6 +2844,37 @@ .PP This command also supports output destination and output format selection. +.SS notes +.PP +notes Show notes. +.PP +This command lists all notes that appear in transactions. +.PP +Examples: +.IP +.nf +\f[C] +$ hledger notes +Petrol +Snacks +\f[R] +.fi +.SS payees +.PP +payees Show payee names. +.PP +This command lists all payee names that appear in transactions. +.PP +Examples: +.IP +.nf +\f[C] +$ hledger payees +Store Name +Gas Station +Person A +\f[R] +.fi .SS prices .PP prices diff --git a/embeddedfiles/hledger.info b/embeddedfiles/hledger.info --- a/embeddedfiles/hledger.info +++ b/embeddedfiles/hledger.info @@ -773,34 +773,27 @@ ----------------------- The '-V/--market' flag converts reported amounts to their market value -in a default valuation commodity, using the historical market prices in -effect on a default valuation date. - - For single period reports, the valuation date is today. For -multiperiod reports, it is the last day of each subperiod. +in a default valuation commodity, using the market prices in effect on a +default valuation date. For single period reports, the valuation date +is today; for multiperiod reports, it is the last day of each subperiod. +It is equivalent to '--value=now' or '--value=end' (see below). - The valuation commodity will be the one referenced in the latest + The default valuation commodity is the one referenced in the latest applicable market price dated on or before the valuation date. If most of your P declarations lead to a single home currency, this will usually -be what you want. - - Unlike the similar flag in Ledger, it does not infer market prices -from transaction prices. In hledger, -B uses transaction prices, -V and --X use market prices. - - It is equivalent to '--value=now' or '--value=end'. +be what you want. (To specify the commodity, see -X below.) Here's a quick example: -# one euro is worth this many dollars from nov 1 +; one euro is worth this many dollars from nov 1 P 2016/11/01 € $1.10 -# purchase some euros on nov 3 +; purchase some euros on nov 3 2016/11/3 assets:euros €100 assets:checking -# the euro is worth fewer dollars by dec 21 +; the euro is worth fewer dollars by dec 21 P 2016/12/21 € $1.03 How many euros do I have ? @@ -819,6 +812,10 @@ $ hledger -f t.j bal -N euros -V $103.00 assets:euros + Note that in hledger, market prices are always declared explicitly +with P directives; we do not infer them from transaction prices as +Ledger does. +  File: hledger.info, Node: -X Market value in specified commodity, Next: --value, Prev: -V Market value, Up: Valuation @@ -828,8 +825,8 @@ The '-X/--exchange' option is like '-V/--market' except it takes a commodity symbol argument, so that you can select a different target commodity. It is similar to the same option in Ledger, with the same -caveat mentioned for '-V'/'--value' above. It is equivalent to -'--value=now,COMM' or '--value=end,COMM'; for more details, read on. +caveat mentioned above. It is equivalent to '--value=now,COMM' or +'--value=end,COMM'.  File: hledger.info, Node: --value, Next: Combining -B -V -X --value, Prev: -X Market value in specified commodity, Up: Valuation @@ -1294,10 +1291,15 @@ * check-dates:: * check-dupes:: * close:: +* commodities:: +* descriptions:: +* diff:: * files:: * help:: * import:: * incomestatement:: +* notes:: +* payees:: * prices:: * print:: * print-unique:: @@ -2110,7 +2112,7 @@ An example: http://stefanorodighiero.net/software/hledger-dupes.html  -File: hledger.info, Node: close, Next: files, Prev: check-dupes, Up: COMMANDS +File: hledger.info, Node: close, Next: commodities, Prev: check-dupes, Up: COMMANDS 4.10 close ========== @@ -2199,9 +2201,70 @@ assets:checking  -File: hledger.info, Node: files, Next: help, Prev: close, Up: COMMANDS +File: hledger.info, Node: commodities, Next: descriptions, Prev: close, Up: COMMANDS -4.11 files +4.11 commodities +================ + +commodities +List all commodity/currency symbols used or declared in the journal. + + +File: hledger.info, Node: descriptions, Next: diff, Prev: commodities, Up: COMMANDS + +4.12 descriptions +================= + +descriptions Show descriptions. + + This command lists all descriptions that appear in transactions. + + Examples: + +$ hledger descriptions +Store Name +Gas Station | Petrol +Person A + + +File: hledger.info, Node: diff, Next: files, Prev: descriptions, Up: COMMANDS + +4.13 diff +========= + +diff +Compares a particular account's transactions in two input files. It +shows any transactions to this account which are in one file but not in +the other. + + More precisely, for each posting affecting this account in either +file, it looks for a corresponding posting in the other file which posts +the same amount to the same account (ignoring date, description, etc.) +Since postings not transactions are compared, this also works when +multiple bank transactions have been combined into a single journal +entry. + + This is useful eg if you have downloaded an account's transactions +from your bank (eg as CSV data). When hledger and your bank disagree +about the account balance, you can compare the bank data with your +journal to find out the cause. + + Examples: + +$ hledger diff -f $LEDGER_FILE -f bank.csv assets:bank:giro +These transactions are in the first file only: + +2014/01/01 Opening Balances + assets:bank:giro EUR ... + ... + equity:opening balances EUR -... + +These transactions are in the second file only: + + +File: hledger.info, Node: files, Next: help, Prev: diff, Up: COMMANDS + +4.14 files ========== files @@ -2211,7 +2274,7 @@  File: hledger.info, Node: help, Next: import, Prev: files, Up: COMMANDS -4.12 help +4.15 help ========= help @@ -2251,7 +2314,7 @@  File: hledger.info, Node: import, Next: incomestatement, Prev: help, Up: COMMANDS -4.13 import +4.16 import =========== import @@ -2279,7 +2342,7 @@  File: hledger.info, Node: Importing balance assignments, Up: import -4.13.1 Importing balance assignments +4.16.1 Importing balance assignments ------------------------------------ Entries added by import will have their posting amounts made explicit @@ -2296,9 +2359,9 @@ please test it and send a pull request.)  -File: hledger.info, Node: incomestatement, Next: prices, Prev: import, Up: COMMANDS +File: hledger.info, Node: incomestatement, Next: notes, Prev: import, Up: COMMANDS -4.14 incomestatement +4.17 incomestatement ==================== incomestatement, is @@ -2343,11 +2406,44 @@ selection.  -File: hledger.info, Node: prices, Next: print, Prev: incomestatement, Up: COMMANDS +File: hledger.info, Node: notes, Next: payees, Prev: incomestatement, Up: COMMANDS -4.15 prices +4.18 notes +========== + +notes Show notes. + + This command lists all notes that appear in transactions. + + Examples: + +$ hledger notes +Petrol +Snacks + + +File: hledger.info, Node: payees, Next: prices, Prev: notes, Up: COMMANDS + +4.19 payees =========== +payees Show payee names. + + This command lists all payee names that appear in transactions. + + Examples: + +$ hledger payees +Store Name +Gas Station +Person A + + +File: hledger.info, Node: prices, Next: print, Prev: payees, Up: COMMANDS + +4.20 prices +=========== + prices Print market price directives from the journal. With -costs, also print synthetic market prices based on transaction prices. With @@ -2357,7 +2453,7 @@  File: hledger.info, Node: print, Next: print-unique, Prev: prices, Up: COMMANDS -4.16 print +4.21 print ========== print, txns, p @@ -2458,7 +2554,7 @@  File: hledger.info, Node: print-unique, Next: register, Prev: print, Up: COMMANDS -4.17 print-unique +4.22 print-unique ================= print-unique @@ -2479,7 +2575,7 @@  File: hledger.info, Node: register, Next: register-match, Prev: print-unique, Up: COMMANDS -4.18 register +4.23 register ============= register, reg, r @@ -2569,7 +2665,7 @@  File: hledger.info, Node: Custom register output, Up: register -4.18.1 Custom register output +4.23.1 Custom register output ----------------------------- register uses the full terminal width by default, except on windows. @@ -2600,7 +2696,7 @@  File: hledger.info, Node: register-match, Next: rewrite, Prev: register, Up: COMMANDS -4.19 register-match +4.24 register-match =================== register-match @@ -2613,7 +2709,7 @@  File: hledger.info, Node: rewrite, Next: roi, Prev: register-match, Up: COMMANDS -4.20 rewrite +4.25 rewrite ============ rewrite @@ -2665,7 +2761,7 @@  File: hledger.info, Node: Re-write rules in a file, Up: rewrite -4.20.1 Re-write rules in a file +4.25.1 Re-write rules in a file ------------------------------- During the run this tool will execute so called "Automated Transactions" @@ -2708,7 +2804,7 @@  File: hledger.info, Node: Diff output format, Next: rewrite vs print --auto, Up: Re-write rules in a file -4.20.1.1 Diff output format +4.25.1.1 Diff output format ........................... To use this tool for batch modification of your journal files you may @@ -2749,7 +2845,7 @@  File: hledger.info, Node: rewrite vs print --auto, Prev: Diff output format, Up: Re-write rules in a file -4.20.1.2 rewrite vs. print -auto +4.25.1.2 rewrite vs. print -auto ................................ This command predates print -auto, and currently does much the same @@ -2769,7 +2865,7 @@  File: hledger.info, Node: roi, Next: stats, Prev: rewrite, Up: COMMANDS -4.21 roi +4.26 roi ======== roi @@ -2797,7 +2893,7 @@  File: hledger.info, Node: stats, Next: tags, Prev: roi, Up: COMMANDS -4.22 stats +4.27 stats ========== stats @@ -2828,7 +2924,7 @@  File: hledger.info, Node: tags, Next: test, Prev: stats, Up: COMMANDS -4.23 tags +4.28 tags ========= tags @@ -2841,7 +2937,7 @@  File: hledger.info, Node: test, Prev: tags, Up: COMMANDS -4.24 test +4.29 test ========= test @@ -2957,9 +3053,6 @@ * interest:: * irr:: - -File: hledger.info, Node: diff, Next: iadd, Up: Third party add-ons - 5.2.1 diff ---------- @@ -2967,7 +3060,7 @@ journal file and another.  -File: hledger.info, Node: iadd, Next: interest, Prev: diff, Up: Third party add-ons +File: hledger.info, Node: iadd, Next: interest, Prev: , Up: Third party add-ons 5.2.2 iadd ---------- @@ -3084,132 +3177,141 @@ Ref: #b-cost25256 Node: -V Market value25454 Ref: #v-market-value25628 -Node: -X Market value in specified commodity27034 -Ref: #x-market-value-in-specified-commodity27254 -Node: --value27594 -Ref: #value27759 -Node: Valuation type28560 -Ref: #valuation-type28696 -Node: Valuation commodity29581 -Ref: #valuation-commodity29752 -Node: --value examples30452 -Ref: #value-examples30629 -Node: Effect of --value on reports32612 -Ref: #effect-of---value-on-reports32785 -Node: Combining -B -V -X --value35476 -Ref: #combining--b--v--x---value35638 -Node: Output destination35674 -Ref: #output-destination35826 -Node: Output format36109 -Ref: #output-format36261 -Node: Regular expressions36646 -Ref: #regular-expressions36783 -Node: QUERIES38144 -Ref: #queries38246 -Node: COMMANDS42208 -Ref: #commands42320 -Node: accounts43321 -Ref: #accounts43419 -Node: activity44118 -Ref: #activity44228 -Node: add44611 -Ref: #add44710 -Node: balance47455 -Ref: #balance47566 -Node: Classic balance report49008 -Ref: #classic-balance-report49181 -Node: Customising the classic balance report50550 -Ref: #customising-the-classic-balance-report50778 -Node: Colour support52854 -Ref: #colour-support53021 -Node: Flat mode53194 -Ref: #flat-mode53342 -Node: Depth limited balance reports53755 -Ref: #depth-limited-balance-reports53955 -Node: Multicolumn balance report54411 -Ref: #multicolumn-balance-report54609 -Node: Budget report59923 -Ref: #budget-report60066 -Node: Nested budgets65268 -Ref: #nested-budgets65380 -Ref: #output-format-168860 -Node: balancesheet68938 -Ref: #balancesheet69074 -Node: balancesheetequity70389 -Ref: #balancesheetequity70538 -Node: cashflow71099 -Ref: #cashflow71227 -Node: check-dates72255 -Ref: #check-dates72382 -Node: check-dupes72661 -Ref: #check-dupes72785 -Node: close73078 -Ref: #close73186 -Node: files76773 -Ref: #files76874 -Node: help77021 -Ref: #help77121 -Node: import78214 -Ref: #import78328 -Node: Importing balance assignments79116 -Ref: #importing-balance-assignments79264 -Node: incomestatement79913 -Ref: #incomestatement80047 -Node: prices81383 -Ref: #prices81498 -Node: print81777 -Ref: #print81887 -Node: print-unique86380 -Ref: #print-unique86506 -Node: register86791 -Ref: #register86918 -Node: Custom register output91090 -Ref: #custom-register-output91219 -Node: register-match92481 -Ref: #register-match92615 -Node: rewrite92966 -Ref: #rewrite93081 -Node: Re-write rules in a file94936 -Ref: #re-write-rules-in-a-file95070 -Node: Diff output format96280 -Ref: #diff-output-format96449 -Node: rewrite vs print --auto97541 -Ref: #rewrite-vs.-print---auto97720 -Node: roi98276 -Ref: #roi98374 -Node: stats99386 -Ref: #stats99485 -Node: tags100273 -Ref: #tags100371 -Node: test100665 -Ref: #test100749 -Node: ADD-ON COMMANDS101510 -Ref: #add-on-commands101620 -Node: Official add-ons102908 -Ref: #official-add-ons103048 -Node: api103136 -Ref: #api103225 -Node: ui103277 -Ref: #ui103376 -Node: web103434 -Ref: #web103523 -Node: Third party add-ons103569 -Ref: #third-party-add-ons103744 -Node: diff103880 -Ref: #diff103977 -Node: iadd104076 -Ref: #iadd104190 -Node: interest104273 -Ref: #interest104394 -Node: irr104489 -Ref: #irr104587 -Node: Experimental add-ons104718 -Ref: #experimental-add-ons104870 -Node: autosync105151 -Ref: #autosync105262 -Node: chart105501 -Ref: #chart105620 -Node: check105691 -Ref: #check105793 +Node: -X Market value in specified commodity27058 +Ref: #x-market-value-in-specified-commodity27278 +Node: --value27572 +Ref: #value27737 +Node: Valuation type28538 +Ref: #valuation-type28674 +Node: Valuation commodity29559 +Ref: #valuation-commodity29730 +Node: --value examples30430 +Ref: #value-examples30607 +Node: Effect of --value on reports32590 +Ref: #effect-of---value-on-reports32763 +Node: Combining -B -V -X --value35454 +Ref: #combining--b--v--x---value35616 +Node: Output destination35652 +Ref: #output-destination35804 +Node: Output format36087 +Ref: #output-format36239 +Node: Regular expressions36624 +Ref: #regular-expressions36761 +Node: QUERIES38122 +Ref: #queries38224 +Node: COMMANDS42186 +Ref: #commands42298 +Node: accounts43362 +Ref: #accounts43460 +Node: activity44159 +Ref: #activity44269 +Node: add44652 +Ref: #add44751 +Node: balance47496 +Ref: #balance47607 +Node: Classic balance report49049 +Ref: #classic-balance-report49222 +Node: Customising the classic balance report50591 +Ref: #customising-the-classic-balance-report50819 +Node: Colour support52895 +Ref: #colour-support53062 +Node: Flat mode53235 +Ref: #flat-mode53383 +Node: Depth limited balance reports53796 +Ref: #depth-limited-balance-reports53996 +Node: Multicolumn balance report54452 +Ref: #multicolumn-balance-report54650 +Node: Budget report59964 +Ref: #budget-report60107 +Node: Nested budgets65309 +Ref: #nested-budgets65421 +Ref: #output-format-168901 +Node: balancesheet68979 +Ref: #balancesheet69115 +Node: balancesheetequity70430 +Ref: #balancesheetequity70579 +Node: cashflow71140 +Ref: #cashflow71268 +Node: check-dates72296 +Ref: #check-dates72423 +Node: check-dupes72702 +Ref: #check-dupes72826 +Node: close73119 +Ref: #close73233 +Node: commodities76820 +Ref: #commodities76947 +Node: descriptions77029 +Ref: #descriptions77157 +Node: diff77338 +Ref: #diff77444 +Node: files78491 +Ref: #files78591 +Node: help78738 +Ref: #help78838 +Node: import79931 +Ref: #import80045 +Node: Importing balance assignments80833 +Ref: #importing-balance-assignments80981 +Node: incomestatement81630 +Ref: #incomestatement81763 +Node: notes83099 +Ref: #notes83212 +Node: payees83338 +Ref: #payees83444 +Node: prices83602 +Ref: #prices83708 +Node: print83987 +Ref: #print84097 +Node: print-unique88590 +Ref: #print-unique88716 +Node: register89001 +Ref: #register89128 +Node: Custom register output93300 +Ref: #custom-register-output93429 +Node: register-match94691 +Ref: #register-match94825 +Node: rewrite95176 +Ref: #rewrite95291 +Node: Re-write rules in a file97146 +Ref: #re-write-rules-in-a-file97280 +Node: Diff output format98490 +Ref: #diff-output-format98659 +Node: rewrite vs print --auto99751 +Ref: #rewrite-vs.-print---auto99930 +Node: roi100486 +Ref: #roi100584 +Node: stats101596 +Ref: #stats101695 +Node: tags102483 +Ref: #tags102581 +Node: test102875 +Ref: #test102959 +Node: ADD-ON COMMANDS103720 +Ref: #add-on-commands103830 +Node: Official add-ons105118 +Ref: #official-add-ons105258 +Node: api105346 +Ref: #api105435 +Node: ui105487 +Ref: #ui105586 +Node: web105644 +Ref: #web105733 +Node: Third party add-ons105779 +Ref: #third-party-add-ons105954 +Ref: #diff-1106113 +Node: iadd106212 +Ref: #iadd106322 +Node: interest106405 +Ref: #interest106526 +Node: irr106621 +Ref: #irr106719 +Node: Experimental add-ons106850 +Ref: #experimental-add-ons107002 +Node: autosync107283 +Ref: #autosync107394 +Node: chart107633 +Ref: #chart107752 +Node: check107823 +Ref: #check107925  End Tag Table diff --git a/embeddedfiles/hledger.txt b/embeddedfiles/hledger.txt --- a/embeddedfiles/hledger.txt +++ b/embeddedfiles/hledger.txt @@ -176,8 +176,8 @@ using period expressions syntax --date2 - match the secondary date instead (see command help for other - effects) + match the secondary date instead (see command help for other ef- + fects) -U --unmarked include only unmarked postings/txns (can combine with -P or -C) @@ -218,14 +218,14 @@ Some reporting options can also be written as query arguments. Command options - To see options for a particular command, including command-specific - options, run: hledger COMMAND -h. + To see options for a particular command, including command-specific op- + tions, run: hledger COMMAND -h. Command-specific options must be written after the command name, eg: hledger print -x. - Additionally, if the command is an addon, you may need to put its - options after a double-hyphen, eg: hledger ui -- --watch. Or, you can + Additionally, if the command is an addon, you may need to put its op- + tions after a double-hyphen, eg: hledger ui -- --watch. Or, you can run the addon executable directly: hledger-ui --watch. Command arguments @@ -273,7 +273,6 @@ If you asked why four slashes above, this may help: - unescaped: $ escaped: \$ double-escaped: \\$ @@ -321,8 +320,8 @@ This requires a well-configured environment. Here are some tips: - 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 + o A system locale must be configured, and it must be one that can de- + code the characters being used. In bash, you can set a locale like this: export LANG=en_US.UTF-8. There are some more details in Trou- bleshooting. This step is essential - without it, hledger will quit on encountering a non-ascii character (as with all GHC-compiled pro- @@ -365,7 +364,6 @@ format automatically based on the file extension, or if that is not recognised, by trying each built-in "reader" in turn: - Reader: Reads: Used for file extensions: ----------------------------------------------------------------------------- journal hledger's journal format, also .journal .j .hledger .ledger @@ -403,7 +401,6 @@ Examples: - 2004/10/1, 2004-01-01, exact date, several sepa- 2004.9.1 rators allowed. Year is 4+ digits, month is 1-12, @@ -416,66 +413,68 @@ october, oct start of month in current year yesterday, today, tomorrow -1, 0, 1 days from today - last/this/next -1, 0, 1 periods from the + last/this/next -1, 0, 1 periods from the day/week/month/quar- current period ter/year - 20181201 8 digit YYYYMMDD with + 20181201 8 digit YYYYMMDD with valid year month and day - 201812 6 digit YYYYMM with valid + 201812 6 digit YYYYMM with valid year and month - Counterexamples - malformed digit sequences might give surprising - results: - + Counterexamples - malformed digit sequences might give surprising re- + sults: - 201813 6 digits with an invalid - month is parsed as start + 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 + 20181301 8 digits with an invalid + month is parsed as start of 8-digit year - 20181232 8 digits with an invalid + 20181232 8 digits with an invalid day gives an error 201801012 9+ digits beginning with a valid YYYYMMDD gives an error Report start & end date - Most hledger reports show the full span of time represented by the + Most hledger reports show the full span of time represented by the journal data, by default. So, the effective report start and end dates - will be the earliest and latest transaction or posting dates found in + will be the earliest and latest transaction or posting dates found in the journal. - 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 As in Ledger, end dates are exclusive, so you need to write the date + o As in Ledger, end dates are exclusive, so you need to write the date after the last day you want to include. - 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. Examples: - -b 2016/3/17 begin on St. Patrick's day 2016 + + + + -e 12/1 end at the start of decem- ber 1st of the current - year (11/30 will be the + year (11/30 will be the last date included) - -b thismonth all transactions on or - after the 1st of the cur- - rent month + -b thismonth all transactions on or af- + ter the 1st of the current + month -p thismonth all transactions in the current month date:2016/3/17- the above written as @@ -486,15 +485,15 @@ Report intervals A report interval can be specified so that commands like register, bal- - ance and activity will divide their reports into multiple subperiods. - The basic intervals can be selected with one of -D/--daily, - -W/--weekly, -M/--monthly, -Q/--quarterly, or -Y/--yearly. More com- - plex intervals may be specified with a period expression. Report - intervals can not be specified with a query. + ance and activity will divide their reports into multiple subperiods. + The basic intervals can be selected with one of -D/--daily, + -W/--weekly, -M/--monthly, -Q/--quarterly, or -Y/--yearly. More com- + plex intervals may be specified with a period expression. Report in- + tervals can not be specified with a query. 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 @@ -506,7 +505,6 @@ long as you don't run two dates together. "to" can also be written as "-". These are equivalent to the above: - -p "2009/1/1 2009/4/1" -p2009/1/1to2009/4/1 -p2009/1/1-2009/4/1 @@ -514,7 +512,6 @@ Dates are smart dates, so if the current year is 2009, the above can also be written as: - -p "1/1 4/1" -p "january-apr" -p "this year to 4/1" @@ -522,7 +519,6 @@ If you specify only one date, the missing start or end date will be the earliest or latest transaction in your journal: - -p "from 2009/1/1" everything after january 1, 2009 -p "from 2009/1" the same @@ -533,21 +529,21 @@ A single date with no "from" or "to" defines both the start and end date like so: - -p "2009" the year 2009; equivalent to "2009/1/1 to 2010/1/1" -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 to "2009/1/1 to 2009/1/2" - The argument of -p can also begin with, or be, a report interval - expression. The basic report intervals are daily, weekly, monthly, - quarterly, or yearly, which have the same effect as the -D,-W,-M,-Q, or - -Y flags. Between report interval and start/end dates (if any), the - word in is optional. Examples: - + The argument of -p can also begin with, or be, a report interval ex- + pression. The basic report intervals are daily, weekly, monthly, quar- + terly, or yearly, which have the same effect as the -D,-W,-M,-Q, or -Y + flags. Between report interval and start/end dates (if any), the word + in is optional. Examples: -p "weekly from 2009/1/1 to 2009/4/1" -p "monthly in 2008" @@ -555,12 +551,11 @@ Note that weekly, monthly, quarterly and yearly intervals will always start on the first day on week, month, quarter or year accordingly, and - will end on the last day of same period, even if associated period - expression specifies different explicit start and end date. + will end on the last day of same period, even if associated period ex- + pression specifies different explicit start and end date. For example: - -p "weekly from 2009/1/1 to 2009/4/1" -- starts on 2008/12/29, closest pre- ceeding Monday @@ -573,8 +568,8 @@ -p "yearly from 2009-12-29" - starts on 2009/01/01, first day of 2009 - The following more complex report intervals are also supported: - biweekly, bimonthly, every day|week|month|quarter|year, every N + The following more complex report intervals are also supported: bi- + weekly, bimonthly, every day|week|month|quarter|year, every N days|weeks|months|quarters|years. All of these will start on the first day of the requested period and @@ -582,14 +577,13 @@ Examples: - -p "bimonthly from 2008" -- periods will have boundaries on 2008/01/01, 2008/03/01, ... -p "every 2 weeks" -- starts on closest preceeding Monday - -p "every 5 month from 2009/03" -- - periods will have boundaries on + -p "every 5 month from 2009/03" -- pe- + riods will have boundaries on 2009/03/01, 2009/08/01, ... If you want intervals that start on arbitrary day of your choosing and @@ -601,7 +595,6 @@ Examples: - -p "every 2nd day of week" -- periods will go from Tue to Tue -p "every Tue" -- same @@ -610,6 +603,7 @@ -p "every 2nd Monday" -- period bound- aries will be on second Monday of each month + -p "every 11/05" -- yearly periods with boundaries on 5th of Nov -p "every 5th Nov" -- same @@ -628,9 +622,9 @@ Depth limiting With the --depth N option (short form: -N), commands like account, bal- ance and register will show only the uppermost accounts in the account - tree, down to level N. Use this when you want a summary with less - detail. This flag has the same effect as a depth: query argument (so - -2, --depth=2 or depth:2 are basically equivalent). + tree, down to level N. Use this when you want a summary with less de- + tail. This flag has the same effect as a depth: query argument (so -2, + --depth=2 or depth:2 are basically equivalent). Pivoting Normally hledger sums amounts, and organizes them in a hierarchy, based @@ -668,8 +662,8 @@ -------------------- 0 - One way to show only amounts with a member: value (using a query, - described below): + One way to show only amounts with a member: value (using a query, de- + scribed below): $ hledger balance --pivot member tag:member=. -2 EUR John Doe @@ -692,34 +686,27 @@ -V: Market value The -V/--market flag converts reported amounts to their market value in - a default valuation commodity, using the historical market prices in - effect on a default valuation date. - - For single period reports, the valuation date is today. For multi- - period reports, it is the last day of each subperiod. - - The valuation commodity will be the one referenced in the latest appli- - cable market price dated on or before the valuation date. If most of - your P declarations lead to a single home currency, this will usually - be what you want. - - Unlike the similar flag in Ledger, it does not infer market prices from - transaction prices. In hledger, -B uses transaction prices, -V and -X - use market prices. + a default valuation commodity, using the market prices in effect on a + default valuation date. For single period reports, the valuation date + is today; for multiperiod reports, it is the last day of each subpe- + riod. It is equivalent to --value=now or --value=end (see below). - It is equivalent to --value=now or --value=end. + The default valuation commodity is the one referenced in the latest ap- + plicable market price dated on or before the valuation date. If most + of your P declarations lead to a single home currency, this will usu- + ally be what you want. (To specify the commodity, see -X below.) Here's a quick example: - # one euro is worth this many dollars from nov 1 + ; one euro is worth this many dollars from nov 1 P 2016/11/01 EUR $1.10 - # purchase some euros on nov 3 + ; purchase some euros on nov 3 2016/11/3 assets:euros EUR100 assets:checking - # the euro is worth fewer dollars by dec 21 + ; the euro is worth fewer dollars by dec 21 P 2016/12/21 EUR $1.03 How many euros do I have ? @@ -732,18 +719,22 @@ $ hledger -f t.j bal -N euros -V -e 2016/11/4 $110.00 assets:euros - What are they worth after 2016/12/21 ? (no report end date specified, + What are they worth after 2016/12/21 ? (no report end date specified, defaults to today) $ hledger -f t.j bal -N euros -V $103.00 assets:euros + Note that in hledger, market prices are always declared explicitly with + P directives; we do not infer them from transaction prices as Ledger + does. + -X: Market value in specified commodity - The -X/--exchange option is like -V/--market except it takes a commod- - ity symbol argument, so that you can select a different target commod- - ity. It is similar to the same option in Ledger, with the same caveat - mentioned for -V/--value above. It is equivalent to --value=now,COMM - or --value=end,COMM; for more details, read on. + The -X/--exchange option is like -V/--market except it takes a commod- + ity symbol argument, so that you can select a different target commod- + ity. It is similar to the same option in Ledger, with the same caveat + mentioned above. It is equivalent to --value=now,COMM or + --value=end,COMM. --value (experimental, added 201905) @@ -759,45 +750,45 @@ - default valuation commodity (or COMM) using market prices at some date Valuation type - TYPE is one of these keywords, or their first letter, or a date (which + TYPE is one of these keywords, or their first letter, or a date (which must be 8 digits with - or / or . separators): --value=cost - Convert amounts to cost, using the prices recorded in transac- + Convert amounts to cost, using the prices recorded in transac- tions. -B/--cost is equivalent to this. --value=end - Convert amounts to their value in default valuation commodity - using market prices on the last day of the report period (or of - each subperiod in a multiperiod report). When no report period + Convert amounts to their value in default valuation commodity + using market prices on the last day of the report period (or of + each subperiod in a multiperiod report). When no report period is specified, uses the journal's last transaction date. --value=now - Convert amounts to their value in default valuation commodity - using current market prices (as of when report is generated). + Convert amounts to their value in default valuation commodity + using current market prices (as of when report is generated). -V/--market is equivalent to this. --value=YYYY-MM-DD - Convert amounts to their value in default valuation commodity + Convert amounts to their value in default valuation commodity using market prices on this date. Eg --value=2019-04-25. Valuation commodity - The default valuation commodity is the commodity mentioned in the most + The default valuation commodity is the commodity mentioned in the most recent applicable market price declaration. When all your price decla- - rations lead to a single home currency, this will usually do what you + rations lead to a single home currency, this will usually do what you want. - To select a different valuation commodity: write the commodity symbol - after the valuation type, separated by a comma (eg: --value=now,EUR). + To select a different valuation commodity: write the commodity symbol + after the valuation type, separated by a comma (eg: --value=now,EUR). This will use, in this preferred order: o declared prices (from source commodity to valuation commodity) - o reverse prices (declared prices from valuation to source commodity, + o reverse prices (declared prices from valuation to source commodity, inverted) - o indirect prices (prices calculated from the shortest chain of - declared or reverse prices from source to valuation commodity). + o indirect prices (prices calculated from the shortest chain of de- + clared or reverse prices from source to valuation commodity). --value examples Here are the effects of --value as seen with print: @@ -837,7 +828,7 @@ 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 @@ -874,8 +865,8 @@ 2000/03/01 (a) 1 B - You may need to explicitly set a commodity's display style, when - reverse prices are used. Eg this output might be surprising: + You may need to explicitly set a commodity's display style, when re- + verse prices are used. Eg this output might be surprising: P 2000-01-01 A 2B @@ -910,9 +901,8 @@ Below is how --value affects each of hledger's reports, currently. You're not expected to remember all this, but when troubleshooting a report, look here. If you find problems - useless reports, misbehaving - reports, or error messages being printed - please report them (with - reproducible examples) eg at #329. - + reports, or error messages being printed - please report them (with re- + producible examples) eg at #329. Report type --value cost --value end --value DATE/now --------------------------------------------------------------------------------- @@ -920,40 +910,37 @@ posting cost, as market value at report market value at amounts recorded in end DATE transaction - balance show unvalued show unvalued show unvalued - asser- - tions/assign- - ments + balance as- show unvalued show unvalued show unvalued + sertions/as- + signments register - starting bal- cost of start- market value at day market value at - ance with -H ing balance before report start DATE + starting cost of start- market value at day be- market value at + balance with ing balance fore report start DATE + -H posting cost market value at report market value at amounts end DATE posting summarised market value each summary market value each - amounts, mul- cost posting at period end summary posting at - tiperiod DATE - running sum/average of sum/average of the dis- sum/average of the - total/average the displayed played values displayed values + amounts, cost posting at period end summary posting at + multiperiod DATE + running to- sum/average of sum/average of the dis- sum/average of the + tal/average the displayed played values displayed values values - balance (bs, + balance (bs, cf, is..) - - - - starting bal- costs of market value at day market value at - ances with -H starting bal- before report start of DATE of sum of - ances sum of previous postings previous postings - balances, summed costs market value at period market value at - simple bal- end of sum of postings DATE of sum of - ance report postings + starting costs of market value at day be- market value at + balances starting bal- fore report start of sum DATE of sum of + with -H ances of previous postings previous postings balances, summed costs market value at period market value at - multiperiod end of sum of postings DATE of sum of + simple bal- end of sum of postings DATE of sum of + ance report postings + balances, summed costs market value at period market value at + multiperiod end of sum of postings DATE of sum of report postings - budget costs of bud- budget-setting periodic budget-setting - amounts with get amounts txns are valued at period periodic txns are + budget costs of bud- budget-setting periodic budget-setting pe- + amounts with get amounts txns are valued at period riodic txns are --budget end valued at DATE - col- sum/average of market value at period market value at - umn/row/grand the displayed end of sum/average of DATE of sum/aver- + col- sum/average of market value at period market value at + umn/row/grand the displayed end of sum/average of DATE of sum/aver- totals/aver- values postings age of postings ages @@ -961,16 +948,16 @@ The rightmost of these flags wins. Output destination - Some commands (print, register, stats, the balance commands) can write - their output to a destination other than the console. This is con- + Some commands (print, register, stats, the balance commands) can write + their output to a destination other than the console. This is con- trolled by the -o/--output-file option. $ hledger balance -o - # write to stdout (the default) $ hledger balance -o FILE # write to FILE Output format - Some commands can write their output in other formats. Eg print and - register can output CSV, and the balance commands can output CSV or + Some commands can write their output in other formats. Eg print and + register can output CSV, and the balance commands can output CSV or HTML. This is controlled by the -O/--output-format option, or by spec- ifying a .csv or .html file extension with -o/--output-file. @@ -980,56 +967,56 @@ 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. In + hledger's regular expressions come from the regex-tdfa library. In general they: o are case insensitive - o are infix matching (do not need to match the entire thing being + o are infix matching (do not need to match the entire thing being matched) o are POSIX extended regular expressions o also support GNU word boundaries (\<, \>, \b, \B) - o and parenthesised capturing groups and numeric backreferences in - replacement strings + o and parenthesised capturing groups and numeric backreferences in re- + placement strings o do not support mode modifiers like (?s) 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. QUERIES - One of hledger's strengths is being able to quickly report on precise - subsets of your data. Most commands accept an optional query expres- - sion, written as arguments after the command name, to filter the data - by date, account name or other criteria. The syntax is similar to a + One of hledger's strengths is being able to quickly report on precise + subsets of your data. Most commands accept an optional query expres- + sion, written as arguments after the command name, to filter the data + by date, account name or other criteria. The syntax is similar to a web search: one or more space-separated search terms, quotes to enclose - whitespace, prefixes to match specific fields, a not: prefix to negate + whitespace, prefixes to match specific fields, a not: prefix to negate the match. - We do not yet support arbitrary boolean combinations of search terms; - instead most commands show transactions/postings/accounts which match + We do not yet support arbitrary boolean combinations of search terms; + instead most commands show transactions/postings/accounts which match (or negatively match): o any of the description terms AND @@ -1050,31 +1037,31 @@ o match all the other terms. - The following kinds of search terms can be used. Remember these can + The following kinds of search terms can be used. Remember these can also be prefixed with not:, eg to exclude a particular subaccount. REGEX, acct:REGEX - match account names by this regular expression. (With no pre- + match account names by this regular expression. (With no pre- fix, acct: is assumed.) same as above amt:N, amt:N, amt:>=N - match postings with a single-commodity amount that is equal to, - less than, or greater than N. (Multi-commodity amounts are not + match postings with a single-commodity amount that is equal to, + less than, or greater than N. (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. Otherwise, the absolute magnitudes are compared, + are compared. Otherwise, the absolute magnitudes are compared, ignoring sign. code:REGEX match by transaction code (eg check number) cur:REGEX - match postings or transactions including any amounts whose cur- - rency/commodity symbol is fully matched by REGEX. (For a par- + match postings or transactions including any amounts whose cur- + rency/commodity symbol is fully matched by REGEX. (For a par- tial match, use .*REGEX.*). Note, to match characters which are regex-significant, like the dollar sign ($), you need to prepend - \. And when using the command line you need to add one more - level of quoting to hide it from the shell, so eg do: hledger + \. And when using the command line you need to add one more + level of quoting to hide it from the shell, so eg do: hledger print cur:'\$' or hledger print cur:\\$. desc:REGEX @@ -1082,20 +1069,20 @@ date:PERIODEXPR match dates within the specified period. PERIODEXPR is a period - expression (with no report interval). Examples: date:2016, - date:thismonth, date:2000/2/1-2/15, date:lastweek-. If the - --date2 command line flag is present, this matches secondary + expression (with no report interval). Examples: date:2016, + date:thismonth, date:2000/2/1-2/15, date:lastweek-. If the + --date2 command line flag is present, this matches secondary dates instead. date2:PERIODEXPR match secondary dates within the specified period. depth:N - match (or display, depending on command) accounts at or above + match (or display, depending on command) accounts at or above this depth note:REGEX - match transaction notes (part of description right of |, or + match transaction notes (part of description right of |, or whole description when there's no |) payee:REGEX @@ -1109,51 +1096,51 @@ match unmarked, pending, or cleared transactions respectively tag:REGEX[=REGEX] - match by tag name, and optionally also by tag value. Note a - tag: query is considered to match a transaction if it matches - any of the postings. Also remember that postings inherit the + match by tag name, and optionally also by tag value. Note a + tag: query is considered to match a transaction if it matches + any of the postings. Also remember that postings inherit the tags of their parent transaction. The following special search term is used automatically in hledger-web, only: inacct:ACCTNAME - tells hledger-web to show the transaction register for this - account. Can be filtered further with acct etc. + tells hledger-web to show the transaction register for this ac- + count. Can be filtered further with acct etc. Some of these can also be expressed as command-line options (eg depth:2 - is equivalent to --depth 2). Generally you can mix options and query - arguments, and the resulting query will be their intersection (perhaps + is equivalent to --depth 2). Generally you can mix options and query + arguments, and the resulting query will be their intersection (perhaps excluding the -p/--period option). COMMANDS - hledger provides a number of subcommands; hledger with no arguments + hledger provides a number of subcommands; hledger with no arguments shows a list. If you install additional hledger-* packages, or if you put programs or - scripts named hledger-NAME in your PATH, these will also be listed as + scripts named hledger-NAME in your PATH, these will also be listed as subcommands. - Run a subcommand by writing its name as first argument (eg hledger - incomestatement). You can also write one of the standard short aliases - displayed in parentheses in the command list (hledger b), or any any + Run a subcommand by writing its name as first argument (eg hledger in- + comestatement). You can also write one of the standard short aliases + displayed in parentheses in the command list (hledger b), or any any unambiguous prefix of a command name (hledger inc). - Here are all the builtin commands in alphabetical order. See also - hledger for a more organised command list, and hledger CMD -h for - detailed command help. + Here are all the builtin commands in alphabetical order. See also + hledger for a more organised command list, and hledger CMD -h for de- + tailed command help. accounts accounts, a Show account names. - This command lists account names, either declared with account direc- - tives (--declared), posted to (--used), or both (the default). With - query arguments, only matched account names and account names refer- - enced by matched postings are shown. It shows a flat list by default. - With --tree, it uses indentation to show the account hierarchy. In - flat mode you can add --drop N to omit the first few account name com- - ponents. Account names can be depth-clipped with depth:N or --depth N + This command lists account names, either declared with account direc- + tives (--declared), posted to (--used), or both (the default). With + query arguments, only matched account names and account names refer- + enced by matched postings are shown. It shows a flat list by default. + With --tree, it uses indentation to show the account hierarchy. In + flat mode you can add --drop N to omit the first few account name com- + ponents. Account names can be depth-clipped with depth:N or --depth N or -N. Examples: @@ -1172,8 +1159,8 @@ activity Show an ascii barchart of posting counts per interval. - The activity command displays an ascii histogram showing transaction - counts by day, week, month or other reporting interval (by day is the + The activity command displays an ascii histogram showing transaction + counts by day, week, month or other reporting interval (by day is the default). With query arguments, it counts only matched transactions. Examples: @@ -1188,22 +1175,22 @@ add Prompt for transactions and add them to the journal. - Many hledger users edit their journals directly with a text editor, or - generate them from CSV. For more interactive data entry, there is the - add command, which prompts interactively on the console for new trans- + Many hledger users edit their journals directly with a text editor, or + generate them from CSV. For more interactive data entry, there is the + add command, which prompts interactively on the console for new trans- actions, and appends them to the journal file (if there are multiple -f - FILE options, the first file is used.) Existing transactions are not - changed. This is the only hledger command that writes to the journal + FILE options, the first file is used.) Existing transactions are not + changed. This is the only hledger command that writes to the journal file. To use it, just run hledger add and follow the prompts. You can add as - many transactions as you like; when you are finished, enter . or press + many transactions as you like; when you are finished, enter . or press control-d or control-c to exit. Features: - o add tries to provide useful defaults, using the most similar (by - description) recent transaction (filtered by the query, if any) as a + o add tries to provide useful defaults, using the most similar (by de- + scription) recent transaction (filtered by the query, if any) as a template. o You can also set the initial defaults with command line arguments. @@ -1211,20 +1198,20 @@ o Readline-style edit keys can be used during data entry. o The tab key will auto-complete whenever possible - accounts, descrip- - tions, dates (yesterday, today, tomorrow). If the input area is + tions, dates (yesterday, today, tomorrow). If the input area is empty, it will insert the default value. - o If the journal defines a default commodity, it will be added to any + o If the journal defines a default commodity, it will be added to any bare numbers entered. o A parenthesised transaction code may be entered following a date. o Comments and tags may be entered following a description or amount. - o If you make a mistake, enter < at any prompt to restart the transac- + o If you make a mistake, enter < at any prompt to restart the transac- tion. - o Input prompts are displayed in a different colour when the terminal + o Input prompts are displayed in a different colour when the terminal supports it. Example (see the tutorial for a detailed explanation): @@ -1254,8 +1241,8 @@ Starting the next transaction (. or ctrl-D/ctrl-C to quit) Date [2015/05/22]: $ - On Microsoft Windows, the add command makes sure that no part of the - file path ends with a period, as it can cause data loss on that plat- + On Microsoft Windows, the add command makes sure that no part of the + file path ends with a period, as it can cause data loss on that plat- form (cf #1056). balance @@ -1263,29 +1250,29 @@ Show accounts and their balances. The balance command is hledger's most versatile command. Note, despite - the name, it is not always used for showing real-world account bal- - ances; the more accounting-aware balancesheet and incomestatement may + the name, it is not always used for showing real-world account bal- + ances; the more accounting-aware balancesheet and incomestatement may be more convenient for that. By default, it displays all accounts, and each account's change in bal- ance during the entire period of the journal. Balance changes are cal- - culated by adding up the postings in each account. You can limit the - postings matched, by a query, to see fewer accounts, changes over a + culated by adding up the postings in each account. You can limit the + postings matched, by a query, to see fewer accounts, changes over a different time period, changes from only cleared transactions, etc. If you include an account's complete history of postings in the report, - the balance change is equivalent to the account's current ending bal- - ance. For a real-world account, typically you won't have all transac- + the balance change is equivalent to the account's current ending bal- + ance. For a real-world account, typically you won't have all transac- tions in the journal; instead you'll have all transactions after a cer- - tain date, and an "opening balances" transaction setting the correct - starting balance on that date. Then the balance command will show + tain date, and an "opening balances" transaction setting the correct + starting balance on that date. Then the balance command will show real-world account balances. In some cases the -H/--historical flag is used to ensure this (more below). The balance command can produce several styles of report: Classic balance report - This is the original balance report, as found in Ledger. It usually + This is the original balance report, as found in Ledger. It usually looks like this: $ hledger balance @@ -1302,23 +1289,23 @@ -------------------- 0 - By default, accounts are displayed hierarchically, with subaccounts - indented below their parent. At each level of the tree, accounts are - sorted by account code if any, then by account name. Or with + By default, accounts are displayed hierarchically, with subaccounts in- + dented below their parent. At each level of the tree, accounts are + sorted by account code if any, then by account name. Or with -S/--sort-amount, by their balance amount. "Boring" accounts, which contain a single interesting subaccount and no - balance of their own, are elided into the following line for more com- - pact output. (Eg above, the "liabilities" account.) Use --no-elide to + balance of their own, are elided into the following line for more com- + pact output. (Eg above, the "liabilities" account.) Use --no-elide to prevent this. - Account balances are "inclusive" - they include the balances of any + Account balances are "inclusive" - they include the balances of any subaccounts. - Accounts which have zero balance (and no non-zero subaccounts) are + Accounts which have zero balance (and no non-zero subaccounts) are omitted. Use -E/--empty to show them. - A final total is displayed by default; use -N/--no-total to suppress + A final total is displayed by default; use -N/--no-total to suppress it, eg: $ hledger balance -p 2008/6 expenses --no-total @@ -1327,7 +1314,7 @@ $1 supplies Customising the classic balance report - You can customise the layout of classic balance reports with --format + You can customise the layout of classic balance reports with --format FMT: $ hledger balance --format "%20(account) %12(total)" @@ -1345,7 +1332,7 @@ 0 The FMT format string (plus a newline) specifies the formatting applied - to each account/balance pair. It may contain any suitable text, with + to each account/balance pair. It may contain any suitable text, with data fields interpolated like so: %[MIN][.MAX](FIELDNAME) @@ -1356,14 +1343,14 @@ o FIELDNAME must be enclosed in parentheses, and can be one of: - o depth_spacer - a number of spaces equal to the account's depth, or + o depth_spacer - a number of spaces equal to the account's depth, or if MIN is specified, MIN * depth spaces. o account - the account's name o total - the account's balance/posted total, right justified - Also, FMT can begin with an optional prefix to control how multi-com- + Also, FMT can begin with an optional prefix to control how multi-com- modity amounts are rendered: o %_ - render on multiple lines, bottom-aligned (the default) @@ -1372,22 +1359,22 @@ o %, - render on one line, comma-separated - There are some quirks. Eg in one-line mode, %(depth_spacer) has no - effect, instead %(account) has indentation built in. Experimentation - may be needed to get pleasing results. + There are some quirks. Eg in one-line mode, %(depth_spacer) has no ef- + fect, instead %(account) has indentation built in. Experimentation may + be needed to get pleasing results. Some example formats: o %(total) - the account's total - o %-20.20(account) - the account's name, left justified, padded to 20 + o %-20.20(account) - the account's name, left justified, padded to 20 characters and clipped at 20 characters - o %,%-50(account) %25(total) - account name padded to 50 characters, - total padded to 20 characters, with multiple commodities rendered on + o %,%-50(account) %25(total) - account name padded to 50 characters, + total padded to 20 characters, with multiple commodities rendered on one line - o %20(total) %2(depth_spacer)%-(account) - the default format for the + o %20(total) %2(depth_spacer)%-(account) - the default format for the single-column balance report Colour support @@ -1398,9 +1385,9 @@ o the output is not being redirected or piped anywhere Flat mode - To see a flat list instead of the default hierarchical display, use - --flat. In this mode, accounts (unless depth-clipped) show their full - names and "exclusive" balance, excluding any subaccount balances. In + To see a flat list instead of the default hierarchical display, use + --flat. In this mode, accounts (unless depth-clipped) show their full + names and "exclusive" balance, excluding any subaccount balances. In this mode, you can also use --drop N to omit the first few account name components. @@ -1409,8 +1396,8 @@ $1 supplies Depth limited balance reports - With --depth N or depth:N or just -N, balance reports show accounts - only to the specified numeric depth. This is very useful to summarise + With --depth N or depth:N or just -N, balance reports show accounts + only to the specified numeric depth. This is very useful to summarise a complex set of accounts and get an overview. $ hledger balance -N -1 @@ -1423,17 +1410,17 @@ inclusive balances at the depth limit. Multicolumn balance report - Multicolumn or tabular balance reports are a very useful hledger fea- - ture, and usually the preferred style. They share many of the above - features, but they show the report as a table, with columns represent- - ing time periods. This mode is activated by providing a reporting - interval. + Multicolumn or tabular balance reports are a very useful hledger fea- + ture, and usually the preferred style. They share many of the above + features, but they show the report as a table, with columns represent- + ing time periods. This mode is activated by providing a reporting in- + terval. - There are three types of multicolumn balance report, showing different + There are three types of multicolumn balance report, showing different information: 1. By default: each column shows the sum of postings in that period, ie - the account's change of balance in that period. This is useful eg + the account's change of balance in that period. This is useful eg for a monthly income statement: $ hledger balance --quarterly income expenses -E @@ -1448,8 +1435,8 @@ -------------------++--------------------------------- || $-1 $1 0 0 - 2. With --cumulative: each column shows the ending balance for that - period, accumulating the changes across periods, starting from 0 at + 2. With --cumulative: each column shows the ending balance for that pe- + riod, accumulating the changes across periods, starting from 0 at the report start date: $ hledger balance --quarterly income expenses -E --cumulative @@ -1465,8 +1452,8 @@ || $-1 0 0 0 3. With --historical/-H: each column shows the actual historical ending - balance for that period, accumulating the changes across periods, - starting from the actual balance at the report start date. This is + balance for that period, accumulating the changes across periods, + starting from the actual balance at the report start date. This is useful eg for a multi-period balance sheet, and when you are showing only the data after a certain start date: @@ -1485,26 +1472,26 @@ Note that --cumulative or --historical/-H disable --row-total/-T, since summing end balances generally does not make sense. - Multicolumn balance reports display accounts in flat mode by default; + Multicolumn balance reports display accounts in flat mode by default; to see the hierarchy, use --tree. - With a reporting interval (like --quarterly above), the report - start/end dates will be adjusted if necessary so that they encompass + With a reporting interval (like --quarterly above), the report + start/end dates will be adjusted if necessary so that they encompass the displayed report periods. This is so that the first and last peri- ods will be "full" and comparable to the others. - The -E/--empty flag does two things in multicolumn balance reports: - first, the report will show all columns within the specified report - period (without -E, leading and trailing columns with all zeroes are - not shown). Second, all accounts which existed at the report start - date will be considered, not just the ones with activity during the - report period (use -E to include low-activity accounts which would oth- - erwise would be omitted). + The -E/--empty flag does two things in multicolumn balance reports: + first, the report will show all columns within the specified report pe- + riod (without -E, leading and trailing columns with all zeroes are not + shown). Second, all accounts which existed at the report start date + will be considered, not just the ones with activity during the report + period (use -E to include low-activity accounts which would otherwise + would be omitted). The -T/--row-total flag adds an additional column showing the total for each row. - The -A/--average flag adds a column showing the average value in each + The -A/--average flag adds a column showing the average value in each row. Here's an example of all three: @@ -1528,21 +1515,21 @@ Limitations: In multicolumn reports the -V/--value flag uses the market price on the - report end date, for all columns (not the price on each column's end + report end date, for all columns (not the price on each column's end date). - Eliding of boring parent accounts in tree mode, as in the classic bal- + Eliding of boring parent accounts in tree mode, as in the classic bal- ance report, is not yet supported in multicolumn reports. Budget report - With --budget, extra columns are displayed showing budget goals for - each account and period, if any. Budget goals are defined by periodic - transactions. This is very useful for comparing planned and actual - income, expenses, time usage, etc. --budget is most often combined - with a report interval. + With --budget, extra columns are displayed showing budget goals for + each account and period, if any. Budget goals are defined by periodic + transactions. This is very useful for comparing planned and actual in- + come, expenses, time usage, etc. --budget is most often combined with + a report interval. - For example, you can take average monthly expenses in the common - expense categories to construct a minimal monthly budget: + For example, you can take average monthly expenses in the common ex- + pense categories to construct a minimal monthly budget: ;; Budget ~ monthly @@ -1588,25 +1575,25 @@ Note this is different from a normal balance report in several ways: - o Only accounts with budget goals during the report period are shown, + o Only accounts with budget goals during the report period are shown, by default. - o In each column, in square brackets after the actual amount, budgeted + o In each column, in square brackets after the actual amount, budgeted amounts are shown, along with the percentage of budget used. - o All parent accounts are always shown, even in flat mode. Eg assets, + o All parent accounts are always shown, even in flat mode. Eg assets, assets:bank, and expenses above. - o Amounts always include all subaccounts, budgeted or unbudgeted, even + o Amounts always include all subaccounts, budgeted or unbudgeted, even in flat mode. This means that the numbers displayed will not always add up! Eg above, - the expenses actual amount includes the gifts and supplies transac- - tions, but the expenses:gifts and expenses:supplies accounts are not + the expenses actual amount includes the gifts and supplies transac- + tions, but the expenses:gifts and expenses:supplies accounts are not shown, as they have no budget amounts declared. - This can be confusing. When you need to make things clearer, use the - -E/--empty flag, which will reveal all accounts including unbudgeted + This can be confusing. When you need to make things clearer, use the + -E/--empty flag, which will reveal all accounts including unbudgeted ones, giving the full picture. Eg: $ hledger balance -M --budget --empty @@ -1648,12 +1635,12 @@ For more examples, see Budgeting and Forecasting. Nested budgets - You can add budgets to any account in your account hierarchy. If you + You can add budgets to any account in your account hierarchy. If you have budgets on both parent account and some of its children, then bud- - get(s) of the child account(s) would be added to the budget of their + get(s) of the child account(s) would be added to the budget of their parent, much like account balances behave. - In the most simple case this means that once you add a budget to any + In the most simple case this means that once you add a budget to any account, all its parents would have budget as well. To illustrate this, consider the following budget: @@ -1663,14 +1650,14 @@ expenses:personal:electronics $100.00 liabilities - With this, monthly budget for electronics is defined to be $100 and - budget for personal expenses is an additional $1000, which implicity + With this, monthly budget for electronics is defined to be $100 and + budget for personal expenses is an additional $1000, which implicity means that budget for both expenses:personal and expenses is $1100. - Transactions in expenses:personal:electronics will be counted both - towards its $100 budget and $1100 of expenses:personal , and transac- - tions in any other subaccount of expenses:personal would be counted - towards only towards the budget of expenses:personal. + Transactions in expenses:personal:electronics will be counted both to- + wards its $100 budget and $1100 of expenses:personal , and transactions + in any other subaccount of expenses:personal would be counted towards + only towards the budget of expenses:personal. For example, let's consider these transactions: @@ -1695,9 +1682,9 @@ expenses:personal $30.00 liabilities - As you can see, we have transactions in expenses:personal:electron- - ics:upgrades and expenses:personal:train tickets, and since both of - these accounts are without explicitly defined budget, these transac- + As you can see, we have transactions in expenses:personal:electron- + ics:upgrades and expenses:personal:train tickets, and since both of + these accounts are without explicitly defined budget, these transac- tions would be counted towards budgets of expenses:personal:electronics and expenses:personal accordingly: @@ -1713,7 +1700,7 @@ -------------------------------++------------------------------- || 0 [ 0] - And with --empty, we can get a better picture of budget allocation and + And with --empty, we can get a better picture of budget allocation and consumption: $ hledger balance --budget -M --empty @@ -1731,17 +1718,17 @@ || 0 [ 0] Output format - The balance command supports output destination and output format - selection. + The balance command supports output destination and output format se- + lection. balancesheet balancesheet, bs This command displays a simple balance sheet, showing historical ending - balances of asset and liability accounts (ignoring any report begin - date). It assumes that these accounts are under a top-level asset or + balances of asset and liability accounts (ignoring any report begin + date). It assumes that these accounts are under a top-level asset or liability account (case insensitive, plural forms also allowed). - Note this report shows all account balances with normal positive sign + Note this report shows all account balances with normal positive sign (like conventional financial statements, unlike balance/print/register) (experimental). @@ -1767,19 +1754,19 @@ 0 With a reporting interval, multiple columns will be shown, one for each - report period. As with multicolumn balance reports, you can alter the - report mode with --change/--cumulative/--historical. Normally bal- - ancesheet shows historical ending balances, which is what you need for - a balance sheet; note this means it ignores report begin dates (and - -T/--row-total, since summing end balances generally does not make + report period. As with multicolumn balance reports, you can alter the + report mode with --change/--cumulative/--historical. Normally bal- + ancesheet shows historical ending balances, which is what you need for + a balance sheet; note this means it ignores report begin dates (and + -T/--row-total, since summing end balances generally does not make sense). - This command also supports output destination and output format selec- + This command also supports output destination and output format selec- tion. balancesheetequity balancesheetequity, bse - Just like balancesheet, but also reports Equity (which it assumes is + Just like balancesheet, but also reports Equity (which it assumes is under a top-level equity account). Example: @@ -1810,10 +1797,10 @@ cashflow cashflow, cf - This command displays a simple cashflow statement, showing changes in - "cash" accounts. It assumes that these accounts are under a top-level - asset account (case insensitive, plural forms also allowed) and do not - contain receivable or A/R in their name. Note this report shows all + This command displays a simple cashflow statement, showing changes in + "cash" accounts. It assumes that these accounts are under a top-level + asset account (case insensitive, plural forms also allowed) and do not + contain receivable or A/R in their name. Note this report shows all account balances with normal positive sign (like conventional financial statements, unlike balance/print/register) (experimental). @@ -1834,81 +1821,81 @@ $-1 With a reporting interval, multiple columns will be shown, one for each - report period. Normally cashflow shows changes in assets per period, - though as with multicolumn balance reports you can alter the report + report period. Normally cashflow shows changes in assets per period, + though as with multicolumn balance reports you can alter the report mode with --change/--cumulative/--historical. - This command also supports output destination and output format selec- + This command also supports output destination and output format selec- tion. check-dates check-dates - Check that transactions are sorted by increasing date. With --date2, - checks secondary dates instead. With --strict, dates must also be - unique. With a query, only matched transactions' dates are checked. + Check that transactions are sorted by increasing date. With --date2, + checks secondary dates instead. With --strict, dates must also be + unique. With a query, only matched transactions' dates are checked. Reads the default journal file, or another specified with -f. check-dupes check-dupes - Reports account names having the same leaf but different prefixes. In - other words, two or more leaves that are categorized differently. + Reports account names having the same leaf but different prefixes. In + other words, two or more leaves that are categorized differently. Reads the default journal file, or another specified as an argument. An example: http://stefanorodighiero.net/software/hledger-dupes.html close close, equity - Prints a "closing balances" transaction and an "opening balances" + Prints a "closing balances" transaction and an "opening balances" transaction that bring account balances to and from zero, respectively. Useful for bringing asset/liability balances forward into a new journal - file, or for closing out revenues/expenses to retained earnings at the + file, or for closing out revenues/expenses to retained earnings at the end of a period. - The closing transaction transfers balances to "equity:closing bal- - ances". The opening transaction transfers balances from "equity:open- + The closing transaction transfers balances to "equity:closing bal- + ances". The opening transaction transfers balances from "equity:open- ing balances". You can choose to print just one of the transactions by using the --opening or --closing flag. If you split your journal files by time (eg yearly), you will typically - run this command at the end of the year, and save the closing transac- - tion as last entry of the old file, and the opening transaction as the - first entry of the new file. This makes the files self contained, so - that correct balances are reported no matter which of them are loaded. - Ie, if you load just one file, the balances are initialised correctly; - or if you load several files, the redundant closing/opening transac- - tions cancel each other out. (They will show up in print or register - reports; you can exclude them with a query like not:desc:'(open- + run this command at the end of the year, and save the closing transac- + tion as last entry of the old file, and the opening transaction as the + first entry of the new file. This makes the files self contained, so + that correct balances are reported no matter which of them are loaded. + Ie, if you load just one file, the balances are initialised correctly; + or if you load several files, the redundant closing/opening transac- + tions cancel each other out. (They will show up in print or register + reports; you can exclude them with a query like not:desc:'(open- ing|closing) balances'.) If you're running a business, you might also use this command to "close - the books" at the end of an accounting period, transferring income - statement account balances to retained earnings. (You may want to + the books" at the end of an accounting period, transferring income + statement account balances to retained earnings. (You may want to change the equity account name to something like "equity:retained earn- ings".) - By default, the closing transaction is dated yesterday, the balances - are calculated as of end of yesterday, and the opening transaction is - dated today. To close on some other date, use: hledger close -e OPEN- - INGDATE. Eg, to close/open on the 2018/2019 boundary, use -e 2019. + By default, the closing transaction is dated yesterday, the balances + are calculated as of end of yesterday, and the opening transaction is + dated today. To close on some other date, use: hledger close -e OPEN- + INGDATE. Eg, to close/open on the 2018/2019 boundary, use -e 2019. You can also use -p or date:PERIOD (any starting date is ignored). - Both transactions will include balance assertions for the - closed/reopened accounts. You probably shouldn't use status or real- - ness filters (like -C or -R or status:) with this command, or the gen- - erated balance assertions will depend on these flags. Likewise, if you - run this command with --auto, the balance assertions will probably - always require --auto. + Both transactions will include balance assertions for the closed/re- + opened accounts. You probably shouldn't use status or realness filters + (like -C or -R or status:) with this command, or the generated balance + assertions will depend on these flags. Likewise, if you run this com- + mand with --auto, the balance assertions will probably always require + --auto. - When account balances have cost information (transaction prices), the - closing/opening transactions will preserve it, so that eg balance -B + When account balances have cost information (transaction prices), the + closing/opening transactions will preserve it, so that eg balance -B reports will not be affected. Examples: - Carrying asset/liability balances into a new file for 2019, all from + Carrying asset/liability balances into a new file for 2019, all from command line: - Warning: we use >> here to append; be careful not to type a single > + Warning: we use >> here to append; be careful not to type a single > which would wipe your journal! $ hledger close -f 2018.journal -e 2019 assets liabilities --opening >>2019.journal @@ -1939,22 +1926,67 @@ liabilities:pending 5 = 0 assets:checking + commodities + commodities + List all commodity/currency symbols used or declared in the journal. + + descriptions + descriptions Show descriptions. + + This command lists all descriptions that appear in transactions. + + Examples: + + $ hledger descriptions + Store Name + Gas Station | Petrol + Person A + + diff + diff + Compares a particular account's transactions in two input files. It + shows any transactions to this account which are in one file but not in + the other. + + More precisely, for each posting affecting this account in either file, + it looks for a corresponding posting in the other file which posts the + same amount to the same account (ignoring date, description, etc.) + Since postings not transactions are compared, this also works when mul- + tiple bank transactions have been combined into a single journal entry. + + This is useful eg if you have downloaded an account's transactions from + your bank (eg as CSV data). When hledger and your bank disagree about + the account balance, you can compare the bank data with your journal to + find out the cause. + + Examples: + + $ hledger diff -f $LEDGER_FILE -f bank.csv assets:bank:giro + These transactions are in the first file only: + + 2014/01/01 Opening Balances + assets:bank:giro EUR ... + ... + equity:opening balances EUR -... + + These transactions are in the second file only: + files files List all files included in the journal. With a REGEX argument, only - file names matching the regular expression (case sensitive) are shown. + file names matching the regular expression (case sensitive) are shown. help help Show any of the hledger manuals. - The help command displays any of the main hledger manuals, in one of - several ways. Run it with no argument to list the manuals, or provide + The help command displays any of the main hledger manuals, in one of + several ways. Run it with no argument to list the manuals, or provide a full or partial manual name to select one. - hledger manuals are available in several formats. hledger help will - use the first of these display methods that it finds: info, man, - $PAGER, less, stdout (or when non-interactive, just stdout). You can + hledger manuals are available in several formats. hledger help will + use the first of these display methods that it finds: info, man, + $PAGER, less, stdout (or when non-interactive, just stdout). You can force a particular viewer with the --info, --man, --pager, --cat flags. Examples: @@ -2018,8 +2050,8 @@ expenses during a period. It assumes that these accounts are under a top-level revenue or income or expense account (case insensitive, plu- ral forms also allowed). Note this report shows all account balances - with normal positive sign (like conventional financial statements, - unlike balance/print/register) (experimental). + with normal positive sign (like conventional financial statements, un- + like balance/print/register) (experimental). This command displays a simple income statement. It currently assumes that you have top-level accounts named income (or revenue) and expense @@ -2054,25 +2086,47 @@ This command also supports output destination and output format selec- tion. + notes + notes Show notes. + + This command lists all notes that appear in transactions. + + Examples: + + $ hledger notes + Petrol + Snacks + + payees + payees Show payee names. + + This command lists all payee names that appear in transactions. + + Examples: + + $ hledger payees + Store Name + Gas Station + Person A + prices prices Print market price directives from the journal. With --costs, also - print synthetic market prices based on transaction prices. With - --inverted-costs, also print inverse prices based on transaction - prices. Prices (and postings providing prices) can be filtered by a - query. + print synthetic market prices based on transaction prices. With --in- + verted-costs, also print inverse prices based on transaction prices. + Prices (and postings providing prices) can be filtered by a query. print print, txns, p Show transaction journal entries, sorted by date. The print command displays full journal entries (transactions) from the - journal file in date order, tidily formatted. With --date2, transac- + journal file in date order, tidily formatted. With --date2, transac- tions are sorted by secondary date instead. print's output is always a valid hledger journal. - It preserves all transaction information, but it does not preserve - directives or inter-transaction comments + It preserves all transaction information, but it does not preserve di- + rectives or inter-transaction comments $ hledger print 2008/01/01 income @@ -2097,39 +2151,39 @@ assets:bank:checking $-1 Normally, the journal entry's explicit or implicit amount style is pre- - served. Ie when an amount is omitted in the journal, it will be omit- - ted in the output. You can use the -x/--explicit flag to make all + served. Ie when an amount is omitted in the journal, it will be omit- + ted in the output. You can use the -x/--explicit flag to make all amounts explicit, which can be useful for troubleshooting or for making your journal more readable and robust against data entry errors. Note, - -x will cause postings with a multi-commodity amount (these can arise - when a multi-commodity transaction has an implicit amount) will be - split into multiple single-commodity postings, for valid journal out- + -x will cause postings with a multi-commodity amount (these can arise + when a multi-commodity transaction has an implicit amount) will be + split into multiple single-commodity postings, for valid journal out- put. - With -B/--cost, amounts with transaction prices are converted to cost + With -B/--cost, amounts with transaction prices are converted to cost using that price. This can be used for troubleshooting. - With -m/--match and a STR argument, print will show at most one trans- - action: the one one whose description is most similar to STR, and is - most recent. STR should contain at least two characters. If there is + With -m/--match and a STR argument, print will show at most one trans- + action: the one one whose description is most similar to STR, and is + most recent. STR should contain at least two characters. If there is no similar-enough match, no transaction will be shown. With --new, for each FILE being read, hledger reads (and writes) a spe- - cial state file (.latest.FILE in the same directory), containing the - latest transaction date(s) that were seen last time FILE was read. - When this file is found, only transactions with newer dates (and new - transactions on the latest date) are printed. This is useful for - ignoring already-seen entries in import data, such as downloaded CSV + cial state file (.latest.FILE in the same directory), containing the + latest transaction date(s) that were seen last time FILE was read. + When this file is found, only transactions with newer dates (and new + transactions on the latest date) are printed. This is useful for ig- + noring already-seen entries in import data, such as downloaded CSV files. Eg: $ hledger -f bank1.csv print --new # shows transactions added since last print --new on this file - This assumes that transactions added to FILE always have same or - increasing dates, and that transactions on the same day do not get - reordered. See also the import command. + This assumes that transactions added to FILE always have same or in- + creasing dates, and that transactions on the same day do not get re- + ordered. See also the import command. - This command also supports output destination and output format selec- + This command also supports output destination and output format selec- tion. Here's an example of print's CSV output: $ hledger print -Ocsv @@ -2146,20 +2200,20 @@ "5","2008/12/31","","*","","pay off","","liabilities:debts","1","$","","1","","" "5","2008/12/31","","*","","pay off","","assets:bank:checking","-1","$","1","","","" - o There is one CSV record per posting, with the parent transaction's + o There is one CSV record per posting, with the parent transaction's fields repeated. o The "txnidx" (transaction index) field shows which postings belong to - the same transaction. (This number might change if transactions are - reordered within the file, files are parsed/included in a different + the same transaction. (This number might change if transactions are + reordered within the file, files are parsed/included in a different order, etc.) - o The amount is separated into "commodity" (the symbol) and "amount" + o The amount is separated into "commodity" (the symbol) and "amount" (numeric quantity) fields. o The numeric amount is repeated in either the "credit" or "debit" col- - umn, for convenience. (Those names are not accurate in the account- - ing sense; it just puts negative amounts under credit and zero or + umn, for convenience. (Those names are not accurate in the account- + ing sense; it just puts negative amounts under credit and zero or greater amounts under debit.) print-unique @@ -2183,7 +2237,7 @@ Show postings and their running total. The register command displays postings in date order, one per line, and - their running total. This is typically used with a query selecting a + their running total. This is typically used with a query selecting a particular account, to see that account's activity: $ hledger register checking @@ -2194,8 +2248,8 @@ With --date2, it shows and sorts by secondary date instead. - The --historical/-H flag adds the balance from any undisplayed prior - postings to the running total. This is useful when you want to see + The --historical/-H flag adds the balance from any undisplayed prior + postings to the running total. This is useful when you want to see only recent activity, with a historically accurate running balance: $ hledger register checking -b 2008/6 --historical @@ -2205,30 +2259,30 @@ The --depth option limits the amount of sub-account detail displayed. - The --average/-A flag shows the running average posting amount instead + The --average/-A flag shows the running average posting amount instead of the running total (so, the final number displayed is the average for - the whole report period). This flag implies --empty (see below). It - is affected by --historical. It works best when showing just one - account and one commodity. + the whole report period). This flag implies --empty (see below). It + is affected by --historical. It works best when showing just one ac- + count and one commodity. - The --related/-r flag shows the other postings in the transactions of + The --related/-r flag shows the other postings in the transactions of the postings which would normally be shown. - The --invert flag negates all amounts. For example, it can be used on + The --invert flag negates all amounts. For example, it can be used on an income account where amounts are normally displayed as negative num- - bers. It's also useful to show postings on the checking account - together with the related account: + bers. It's also useful to show postings on the checking account to- + gether with the related account: $ hledger register --related --invert assets:checking - With a reporting interval, register shows summary postings, one per - interval, aggregating the postings to each account: + With a reporting interval, register shows summary postings, one per in- + terval, aggregating the postings to each account: $ hledger register --monthly income 2008/01 income:salary $-1 $-1 2008/06 income:gifts $-1 $-2 - Periods with no activity, and summary postings with a zero amount, are + Periods with no activity, and summary postings with a zero amount, are not shown by default; use the --empty/-E flag to see them: $ hledger register --monthly income -E @@ -2245,28 +2299,28 @@ 2008/11 0 $-2 2008/12 0 $-2 - Often, you'll want to see just one line per interval. The --depth - option helps with this, causing subaccounts to be aggregated: + Often, you'll want to see just one line per interval. The --depth op- + tion helps with this, causing subaccounts to be aggregated: $ hledger register --monthly assets --depth 1h 2008/01 assets $1 $1 2008/06 assets $-1 0 2008/12 assets $-1 $-1 - Note when using report intervals, if you specify start/end dates these - will be adjusted outward if necessary to contain a whole number of - intervals. This ensures that the first and last intervals are full + Note when using report intervals, if you specify start/end dates these + will be adjusted outward if necessary to contain a whole number of in- + tervals. This ensures that the first and last intervals are full length and comparable to the others in the report. Custom register output - register uses the full terminal width by default, except on windows. - You can override this by setting the COLUMNS environment variable (not + register uses the full terminal width by default, except on windows. + You can override this by setting the COLUMNS environment variable (not a bash shell variable) or by using the --width/-w option. - The description and account columns normally share the space equally - (about half of (width - 40) each). You can adjust this by adding a - description width as part of --width's argument, comma-separated: - --width W,D . Here's a diagram (won't display correctly in --help): + The description and account columns normally share the space equally + (about half of (width - 40) each). You can adjust this by adding a de- + scription width as part of --width's argument, comma-separated: --width + W,D . Here's a diagram (won't display correctly in --help): <--------------------------------- width (W) ----------------------------------> date (10) description (D) account (W-41-D) amount (12) balance (12) @@ -2281,27 +2335,27 @@ $ hledger reg -w 100,40 # set overall width 100, description width 40 $ hledger reg -w $COLUMNS,40 # use terminal width, & description width 40 - This command also supports output destination and output format selec- + This command also supports output destination and output format selec- tion. register-match register-match Print the one posting whose transaction description is closest to DESC, - in the style of the register command. If there are multiple equally - good matches, it shows the most recent. Query options (options, not - arguments) can be used to restrict the search space. Helps ledger- - autosync detect already-seen transactions when importing. + in the style of the register command. If there are multiple equally + good matches, it shows the most recent. Query options (options, not + arguments) can be used to restrict the search space. Helps ledger-au- + tosync detect already-seen transactions when importing. rewrite rewrite Print all transactions, rewriting the postings of matched transactions. - For now the only rewrite available is adding new postings, like print + For now the only rewrite available is adding new postings, like print --auto. This is a start at a generic rewriter of transaction entries. It reads - the default journal and prints the transactions, like print, but adds + the default journal and prints the transactions, like print, but adds one or more specified postings to any transactions matching QUERY. The - posting amounts can be fixed, or a multiplier of the existing transac- + posting amounts can be fixed, or a multiplier of the existing transac- tion's first posting amount. Examples: @@ -2317,7 +2371,7 @@ (reserve:grocery) *0.25 ; reserve 25% for grocery (reserve:) *0.25 ; reserve 25% for grocery - Note the single quotes to protect the dollar sign from bash, and the + Note the single quotes to protect the dollar sign from bash, and the two spaces between account and amount. More: @@ -2327,16 +2381,16 @@ $ hledger rewrite -- expenses:gifts --add-posting '(budget:gifts) *-1"' $ hledger rewrite -- ^income --add-posting '(budget:foreign currency) *0.25 JPY; diversify' - Argument for --add-posting option is a usual posting of transaction - with an exception for amount specification. More precisely, you can + Argument for --add-posting option is a usual posting of transaction + with an exception for amount specification. More precisely, you can use '*' (star symbol) before the amount to indicate that that this is a - factor for an amount of original matched posting. If the amount - includes a commodity name, the new posting amount will be in the new - commodity; otherwise, it will be in the matched posting amount's com- - modity. + factor for an amount of original matched posting. If the amount in- + cludes a commodity name, the new posting amount will be in the new com- + modity; otherwise, it will be in the matched posting amount's commod- + ity. Re-write rules in a file - During the run this tool will execute so called "Automated Transac- + During the run this tool will execute so called "Automated Transac- tions" found in any journal it process. I.e instead of specifying this operations in command line you can put them in a journal file. @@ -2351,7 +2405,7 @@ budget:gifts *-1 assets:budget *1 - Note that '=' (equality symbol) that is used instead of date in trans- + Note that '=' (equality symbol) that is used instead of date in trans- actions you usually write. It indicates the query by which you want to match the posting to add new ones. @@ -2364,12 +2418,12 @@ --add-posting 'assets:budget *1' \ > rewritten-tidy-output.journal - It is important to understand that relative order of such entries in - journal is important. You can re-use result of previously added post- + It is important to understand that relative order of such entries in + journal is important. You can re-use result of previously added post- ings. Diff output format - To use this tool for batch modification of your journal files you may + To use this tool for batch modification of your journal files you may find useful output in form of unified diff. $ hledger rewrite -- --diff -f examples/sample.journal '^income' --add-posting '(liabilities:tax) *.33' @@ -2393,10 +2447,10 @@ If you'll pass this through patch tool you'll get transactions contain- ing the posting that matches your query be updated. Note that multiple - files might be update according to list of input files specified via + files might be update according to list of input files specified via --file options and include directives inside of these files. - Be careful. Whole transaction being re-formatted in a style of output + Be careful. Whole transaction being re-formatted in a style of output from hledger print. See also: @@ -2404,14 +2458,14 @@ https://github.com/simonmichael/hledger/issues/99 rewrite vs. print --auto - This command predates print --auto, and currently does much the same + This command predates print --auto, and currently does much the same thing, but with these differences: - o with multiple files, rewrite lets rules in any file affect all other - files. print --auto uses standard directive scoping; rules affect + o with multiple files, rewrite lets rules in any file affect all other + files. print --auto uses standard directive scoping; rules affect only child files. - o rewrite's query limits which transactions can be rewritten; all are + o rewrite's query limits which transactions can be rewritten; all are printed. print --auto's query limits which transactions are printed. o rewrite applies rules specified on command line or in the journal. @@ -2431,9 +2485,9 @@ originating from unrealized profit and loss account(s) are assumed to be your investments or withdrawals. - At a minimum, you need to supply a query (which could be just an - account name) to select your investments with --inv, and another query - to identify your profit and loss transactions with --pnl. + At a minimum, you need to supply a query (which could be just an ac- + count name) to select your investments with --inv, and another query to + identify your profit and loss transactions with --pnl. It will compute and display the internalized rate of return (IRR) and time-weighted rate of return (TWR) for your investments for the time @@ -2471,8 +2525,8 @@ List all the tag names used in the journal. With a TAGREGEX argument, only tag names matching the regular expression (case insensitive) are shown. With QUERY arguments, only transactions matching the query are - considered. With --values flag, the tags' unique values are listed - instead. + considered. With --values flag, the tags' unique values are listed in- + stead. test test @@ -2491,8 +2545,8 @@ none of them). This is mainly used by developers, but it's nice to be able to sanity- - check your installed hledger executable at any time. All tests are - expected to pass - if you ever see otherwise, something has gone wrong, + check your installed hledger executable at any time. All tests are ex- + pected to pass - if you ever see otherwise, something has gone wrong, please report a bug! ADD-ON COMMANDS @@ -2551,8 +2605,8 @@ ing to various schemes. irr - hledger-irr calculates the internal rate of return of an investment - account, but it's superseded now by the built-in roi command. + hledger-irr calculates the internal rate of return of an investment ac- + count, but it's superseded now by the built-in roi command. Experimental add-ons These are available in source form in the hledger repo's bin/ direc- @@ -2610,8 +2664,8 @@ Ledger. TROUBLESHOOTING - Here are some issues you might encounter when you run hledger (and - remember you can also seek help from the IRC channel, mail list or bug + Here are some issues you might encounter when you run hledger (and re- + member you can also seek help from the IRC channel, mail list or bug tracker): Successfully installed, but "No command 'hledger' found" @@ -2620,16 +2674,16 @@ that is ~/.local/bin and ~/.cabal/bin respectively. I set a custom LEDGER_FILE, but hledger is still using the default file - LEDGER_FILE should be a real environment variable, not just a shell - variable. The command env | grep LEDGER_FILE should show it. You may + LEDGER_FILE should be a real environment variable, not just a shell + variable. The command env | grep LEDGER_FILE should show it. You may need to use export. Here's an explanation. - "Illegal byte sequence" or "Invalid or incomplete multibyte or wide + "Illegal byte sequence" or "Invalid or incomplete multibyte or wide character" errors In order to handle non-ascii letters and symbols (like ), hledger needs an appropriate locale. This is usually configured system-wide; you can also configure it temporarily. The locale may need to be one that sup- - ports UTF-8, if you built hledger with GHC < 7.2 (or possibly always, + ports UTF-8, if you built hledger with GHC < 7.2 (or possibly always, I'm not sure yet). Here's an example of setting the locale temporarily, on ubuntu @@ -2648,7 +2702,7 @@ $ echo "export LANG=en_US.UTF-8" >>~/.bash_profile $ bash --login - If we preferred to use eg fr_FR.utf8, we might have to install that + If we preferred to use eg fr_FR.utf8, we might have to install that first: $ apt-get install language-pack-fr @@ -2669,7 +2723,7 @@ 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) @@ -2683,7 +2737,7 @@ SEE ALSO - hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1), + hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1), hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_time- dot(5), ledger(1) diff --git a/embeddedfiles/hledger_csv.txt b/embeddedfiles/hledger_csv.txt --- a/embeddedfiles/hledger_csv.txt +++ b/embeddedfiles/hledger_csv.txt @@ -24,9 +24,9 @@ When reading a CSV file named FILE.csv, hledger looks for a conversion rules file named FILE.csv.rules in the same directory. You can over- - ride this with the --rules-file option. If the rules file does not - exist, hledger will auto-create one with some example rules, which - you'll need to adjust. + ride this with the --rules-file option. If the rules file does not ex- + ist, hledger will auto-create one with some example rules, which you'll + need to adjust. At minimum, the rules file must identify the date and amount fields. It's often necessary to specify the date format, and the number of @@ -178,33 +178,33 @@ newest-first newest-first - Consider adding this rule if all of the following are true: you might - be processing just one day of data, your CSV records are in reverse - chronological order (newest first), and you care about preserving the - order of same-day transactions. It usually isn't needed, because - hledger autodetects the CSV order, but when all CSV records have the + Consider adding this rule if all of the following are true: you might + be processing just one day of data, your CSV records are in reverse + chronological order (newest first), and you care about preserving the + order of same-day transactions. It usually isn't needed, because + hledger autodetects the CSV order, but when all CSV records have the same date it will assume they are oldest first. CSV TIPS CSV ordering - The generated journal entries will be sorted by date. The order of - same-day entries will be preserved (except in the special case where + The generated journal entries will be sorted by date. The order of + same-day entries will be preserved (except in the special case where you might need newest-first, see above). CSV accounts - Each journal entry will have two postings, to account1 and account2 - respectively. It's not yet possible to generate entries with more than - two postings. It's conventional and recommended to use account1 for + Each journal entry will have two postings, to account1 and account2 re- + spectively. It's not yet possible to generate entries with more than + two postings. It's conventional and recommended to use account1 for the account whose CSV we are reading. CSV amounts A transaction amount must be set, in one of these ways: - o with an amount field assignment, which sets the first posting's + o with an amount field assignment, which sets the first posting's amount o (When the CSV has debit and credit amounts in separate fields:) - with field assignments for the amount-in and amount-out pseudo fields + with field assignments for the amount-in and amount-out pseudo fields (both of them). Whichever one has a value will be used, with appropri- ate sign. If both contain a value, it might not work so well. @@ -212,30 +212,30 @@ There is some special handling for sign in amounts: - o If an amount value is parenthesised, it will be de-parenthesised and + o If an amount value is parenthesised, it will be de-parenthesised and sign-flipped. o If an amount value begins with a double minus sign, those will cancel out and be removed. - If the currency/commodity symbol is provided as a separate CSV field, + If the currency/commodity symbol is provided as a separate CSV field, assign it to the currency pseudo field; the symbol will be prepended to - the amount (TODO: when there is an amount). Or, you can use an amount + the amount (TODO: when there is an amount). Or, you can use an amount field assignment for more control, eg: fields date,description,currency,amount amount %amount %currency CSV balance assertions/assignments - If the CSV includes a running balance, you can assign that to one of - the pseudo fields balance (or balance1) or balance2. This will gener- - ate a balance assertion (or if the amount is left empty, a balance - assignment), on the first or second posting, whenever the running bal- - ance field is non-empty. (TODO: #1000) + If the CSV includes a running balance, you can assign that to one of + the pseudo fields balance (or balance1) or balance2. This will gener- + ate a balance assertion (or if the amount is left empty, a balance as- + signment), on the first or second posting, whenever the running balance + field is non-empty. (TODO: #1000) Reading multiple CSV files - You can read multiple CSV files at once using multiple -f arguments on - the command line, and hledger will look for a correspondingly-named + You can read multiple CSV files at once using multiple -f arguments on + the command line, and hledger will look for a correspondingly-named rules file for each. Note if you use the --rules-file option, this one rules file will be used for all the CSV files being read. @@ -254,7 +254,7 @@ 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) @@ -268,7 +268,7 @@ SEE ALSO - hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1), + hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1), hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_time- dot(5), ledger(1) diff --git a/embeddedfiles/hledger_journal.5 b/embeddedfiles/hledger_journal.5 --- a/embeddedfiles/hledger_journal.5 +++ b/embeddedfiles/hledger_journal.5 @@ -1175,8 +1175,8 @@ .IP .nf \f[C] -# commodity-less amounts should be treated as dollars -# (and displayed with symbol on the left, thousands separators and two decimal places) +; commodity-less amounts should be treated as dollars +; (and displayed with symbol on the left, thousands separators and two decimal places) D $1,000.00 1/1 @@ -1450,7 +1450,7 @@ .nf \f[C] alias checking = assets:bank:wells fargo:checking -# rewrites \[dq]checking\[dq] to \[dq]assets:bank:wells fargo:checking\[dq], or \[dq]checking:a\[dq] to \[dq]assets:bank:wells fargo:checking:a\[dq] +; rewrites \[dq]checking\[dq] to \[dq]assets:bank:wells fargo:checking\[dq], or \[dq]checking:a\[dq] to \[dq]assets:bank:wells fargo:checking:a\[dq] \f[R] .fi .SS Regex aliases @@ -1476,7 +1476,7 @@ .nf \f[C] alias /\[ha](.+):bank:([\[ha]:]+)(.*)/ = \[rs]1:\[rs]2 \[rs]3 -# rewrites \[dq]assets:bank:wells fargo:checking\[dq] to \[dq]assets:wells fargo checking\[dq] +; rewrites \[dq]assets:bank:wells fargo:checking\[dq] to \[dq]assets:wells fargo checking\[dq] \f[R] .fi .PP diff --git a/embeddedfiles/hledger_journal.info b/embeddedfiles/hledger_journal.info --- a/embeddedfiles/hledger_journal.info +++ b/embeddedfiles/hledger_journal.info @@ -1042,8 +1042,8 @@ and display format will be applied to all subsequent commodity-less amounts, or until the next 'D' directive. -# commodity-less amounts should be treated as dollars -# (and displayed with symbol on the left, thousands separators and two decimal places) +; commodity-less amounts should be treated as dollars +; (and displayed with symbol on the left, thousands separators and two decimal places) D $1,000.00 1/1 @@ -1289,7 +1289,7 @@ Subaccounts are also affected. Eg: alias checking = assets:bank:wells fargo:checking -# rewrites "checking" to "assets:bank:wells fargo:checking", or "checking:a" to "assets:bank:wells fargo:checking:a" +; rewrites "checking" to "assets:bank:wells fargo:checking", or "checking:a" to "assets:bank:wells fargo:checking:a"  File: hledger_journal.info, Node: Regex aliases, Next: Combining aliases, Prev: Basic aliases, Up: Rewriting accounts @@ -1310,7 +1310,7 @@ referenced by the usual numeric backreferences in REPLACEMENT. Eg: alias /^(.+):bank:([^:]+)(.*)/ = \1:\2 \3 -# rewrites "assets:bank:wells fargo:checking" to "assets:wells fargo checking" +; rewrites "assets:bank:wells fargo:checking" to "assets:wells fargo checking" Also note that REPLACEMENT continues to the end of line (or on command line, to end of option argument), so it can contain trailing diff --git a/embeddedfiles/hledger_journal.txt b/embeddedfiles/hledger_journal.txt --- a/embeddedfiles/hledger_journal.txt +++ b/embeddedfiles/hledger_journal.txt @@ -7,24 +7,24 @@ Journal - hledger's default file format, representing a General Journal DESCRIPTION - hledger's usual data source is a plain text file containing journal - entries in hledger journal format. This file represents a standard - accounting general journal. I use file names ending in .journal, but + hledger's usual data source is a plain text file containing journal en- + tries in hledger journal format. This file represents a standard ac- + counting general journal. I use file names ending in .journal, but that's not required. The journal file contains a number of transaction entries, each describing a transfer of money (or any commodity) between two or more named accounts, in a simple format readable by both hledger and humans. - hledger's journal format is a compatible subset, mostly, of ledger's - journal format, so hledger can work with compatible ledger journal - files as well. It's safe, and encouraged, to run both hledger and + hledger's journal format is a compatible subset, mostly, of ledger's + journal format, so hledger can work with compatible ledger journal + files as well. It's safe, and encouraged, to run both hledger and ledger on the same journal file, eg to validate the results you're get- ting. You can use hledger without learning any more about this file; just use - the add or web commands to create and update it. Many users, though, - also edit the journal file directly with a text editor, perhaps - assisted by the helper modes for emacs or vim. + the add or web commands to create and update it. Many users, though, + also edit the journal file directly with a text editor, perhaps as- + sisted by the helper modes for emacs or vim. Here's an example: @@ -57,73 +57,73 @@ FILE FORMAT Transactions - Transactions are movements of some quantity of commodities between - named accounts. Each transaction is represented by a journal entry - beginning with a simple date in column 0. This can be followed by any - of the following, separated by spaces: + Transactions are movements of some quantity of commodities between + named accounts. Each transaction is represented by a journal entry be- + ginning with a simple date in column 0. This can be followed by any of + the following, separated by spaces: o (optional) a status character (empty, !, or *) - o (optional) a transaction code (any short number or text, enclosed in + o (optional) a transaction code (any short number or text, enclosed in parentheses) o (optional) a transaction description (any remaining text until end of line or a semicolon) - o (optional) a transaction comment (any remaining text following a + o (optional) a transaction comment (any remaining text following a semicolon until end of line) - Then comes zero or more (but usually at least 2) indented lines repre- + Then comes zero or more (but usually at least 2) indented lines repre- senting... Postings - A posting is an addition of some amount to, or removal of some amount - from, an account. Each posting line begins with at least one space or + A posting is an addition of some amount to, or removal of some amount + from, an account. Each posting line begins with at least one space or tab (2 or 4 spaces is common), followed by: o (optional) a status character (empty, !, or *), followed by a space - o (required) an account name (any text, optionally containing single + o (required) an account name (any text, optionally containing single spaces, until end of line or a double space) o (optional) two or more spaces or tabs followed by an amount. - Positive amounts are being added to the account, negative amounts are + Positive amounts are being added to the account, negative amounts are being removed. The amounts within a transaction must always sum up to zero. As a con- - venience, one amount may be left blank; it will be inferred so as to + venience, one amount may be left blank; it will be inferred so as to balance the transaction. - Be sure to note the unusual two-space delimiter between account name - and amount. This makes it easy to write account names containing spa- - ces. But if you accidentally leave only one space (or tab) before the + Be sure to note the unusual two-space delimiter between account name + and amount. This makes it easy to write account names containing spa- + ces. But if you accidentally leave only one space (or tab) before the amount, the amount will be considered part of the account name. Dates Simple dates - Within a journal file, transaction dates use Y/M/D (or Y-M-D or Y.M.D) - Leading zeros are optional. The year may be omitted, in which case it - will be inferred from the context - the current transaction, the - default year set with a default year directive, or the current date - when the command is run. Some examples: 2010/01/31, 1/31, 2010-01-31, + Within a journal file, transaction dates use Y/M/D (or Y-M-D or Y.M.D) + Leading zeros are optional. The year may be omitted, in which case it + will be inferred from the context - the current transaction, the de- + fault year set with a default year directive, or the current date when + the command is run. Some examples: 2010/01/31, 1/31, 2010-01-31, 2010.1.31. Secondary dates - Real-life transactions sometimes involve more than one date - eg the + Real-life transactions sometimes involve more than one date - eg the date you write a cheque, and the date it clears in your bank. When you - want to model this, eg for more accurate balances, you can specify - individual posting dates, which I recommend. Or, you can use the sec- - ondary dates (aka auxiliary/effective dates) feature, supported for + want to model this, eg for more accurate balances, you can specify in- + dividual posting dates, which I recommend. Or, you can use the sec- + ondary dates (aka auxiliary/effective dates) feature, supported for compatibility with Ledger. A secondary date can be written after the primary date, separated by an - equals sign. The primary date, on the left, is used by default; the - secondary date, on the right, is used when the --date2 flag is speci- + equals sign. The primary date, on the left, is used by default; the + secondary date, on the right, is used when the --date2 flag is speci- fied (--aux-date or --effective also work). - The meaning of secondary dates is up to you, but it's best to follow a - consistent rule. Eg write the bank's clearing date as primary, and + The meaning of secondary dates is up to you, but it's best to follow a + consistent rule. Eg write the bank's clearing date as primary, and when needed, the date the transaction was initiated as secondary. Here's an example. Note that a secondary date will use the year of the @@ -139,18 +139,18 @@ $ hledger register checking --date2 2010/02/19 movie ticket assets:checking $-10 $-10 - Secondary dates require some effort; you must use them consistently in + Secondary dates require some effort; you must use them consistently in your journal entries and remember whether to use or not use the --date2 flag for your reports. They are included in hledger for Ledger compat- - ibility, but posting dates are a more powerful and less confusing - alternative. + ibility, but posting dates are a more powerful and less confusing al- + ternative. Posting dates - You can give individual postings a different date from their parent - transaction, by adding a posting comment containing a tag (see below) + You can give individual postings a different date from their parent + transaction, by adding a posting comment containing a tag (see below) like date:DATE. This is probably the best way to control posting dates - precisely. Eg in this example the expense should appear in May - reports, and the deduction from checking should be reported on 6/1 for + precisely. Eg in this example the expense should appear in May re- + ports, and the deduction from checking should be reported on 6/1 for easy bank reconciliation: 2015/5/30 @@ -163,24 +163,23 @@ $ hledger -f t.j register checking 2015/06/01 assets:checking $-10 $-10 - DATE should be a simple date; if the year is not specified it will use - the year of the transaction's date. You can set the secondary date - similarly, with date2:DATE2. The date: or date2: tags must have a - valid simple date value if they are present, eg a date: tag with no + DATE should be a simple date; if the year is not specified it will use + the year of the transaction's date. You can set the secondary date + similarly, with date2:DATE2. The date: or date2: tags must have a + valid simple date value if they are present, eg a date: tag with no value is not allowed. Ledger's earlier, more compact bracketed date syntax is also supported: - [DATE], [DATE=DATE2] or [=DATE2]. hledger will attempt to parse any + [DATE], [DATE=DATE2] or [=DATE2]. hledger will attempt to parse any square-bracketed sequence of the 0123456789/-.= characters in this way. - With this syntax, DATE infers its year from the transaction and DATE2 + With this syntax, DATE infers its year from the transaction and DATE2 infers its year from DATE. Status - Transactions, or individual postings within a transaction, can have a - status mark, which is a single character before the transaction - description or posting account name, separated from it by a space, - indicating one of three statuses: - + Transactions, or individual postings within a transaction, can have a + status mark, which is a single character before the transaction de- + scription or posting account name, separated from it by a space, indi- + cating one of three statuses: mark status ------------------ @@ -188,26 +187,25 @@ ! pending * cleared - When reporting, you can filter by status with the -U/--unmarked, - -P/--pending, and -C/--cleared flags; or the status:, status:!, and + When reporting, you can filter by status with the -U/--unmarked, + -P/--pending, and -C/--cleared flags; or the status:, status:!, and status:* queries; or the U, P, C keys in hledger-ui. - Note, in Ledger and in older versions of hledger, the "unmarked" state - is called "uncleared". As of hledger 1.3 we have renamed it to - unmarked for clarity. + Note, in Ledger and in older versions of hledger, the "unmarked" state + is called "uncleared". As of hledger 1.3 we have renamed it to un- + marked for clarity. - To replicate Ledger and old hledger's behaviour of also matching pend- + To replicate Ledger and old hledger's behaviour of also matching pend- ing, combine -U and -P. - Status marks are optional, but can be helpful eg for reconciling with + Status marks are optional, but can be helpful eg for reconciling with real-world accounts. Some editor modes provide highlighting and short- - cuts for working with status. Eg in Emacs ledger-mode, you can toggle + cuts for working with status. Eg in Emacs ledger-mode, you can toggle transaction status with C-c C-e, or posting status with C-c C-c. - What "uncleared", "pending", and "cleared" actually mean is up to you. + What "uncleared", "pending", and "cleared" actually mean is up to you. Here's one suggestion: - status meaning -------------------------------------------------------------------------- uncleared recorded but not yet reconciled; needs review @@ -216,33 +214,33 @@ cleared complete, reconciled as far as possible, and considered cor- rect - With this scheme, you would use -PC to see the current balance at your - bank, -U to see things which will probably hit your bank soon (like - uncashed checks), and no flags to see the most up-to-date state of your + With this scheme, you would use -PC to see the current balance at your + bank, -U to see things which will probably hit your bank soon (like un- + cashed checks), and no flags to see the most up-to-date state of your finances. Description - A transaction's description is the rest of the line following the date - and status mark (or until a comment begins). Sometimes called the + A transaction's description is the rest of the line following the date + and status mark (or until a comment begins). Sometimes called the "narration" in traditional bookkeeping, it can be used for whatever you - wish, or left blank. Transaction descriptions can be queried, unlike + wish, or left blank. Transaction descriptions can be queried, unlike comments. Payee and note You can optionally include a | (pipe) character in descriptions to sub- divide the description into separate fields for payee/payer name on the - left (up to the first |) and an additional note field on the right - (after the first |). This may be worthwhile if you need to do more - precise querying and pivoting by payee or by note. + left (up to the first |) and an additional note field on the right (af- + ter the first |). This may be worthwhile if you need to do more pre- + cise querying and pivoting by payee or by note. Account names - Account names typically have several parts separated by a full colon, - from which hledger derives a hierarchical chart of accounts. They can - be anything you like, but in finance there are traditionally five top- + Account names typically have several parts separated by a full colon, + from which hledger derives a hierarchical chart of accounts. They can + be anything you like, but in finance there are traditionally five top- level accounts: assets, liabilities, income, expenses, and equity. - Account names may contain single spaces, eg: assets:accounts receiv- - able. Because of this, they must always be followed by two or more + Account names may contain single spaces, eg: assets:accounts receiv- + able. Because of this, they must always be followed by two or more spaces (or newline). Account names can be aliased. @@ -251,7 +249,7 @@ After the account name, there is usually an amount. Important: between account name and amount, there must be two or more spaces. - Amounts consist of a number and (usually) a currency symbol or commod- + Amounts consist of a number and (usually) a currency symbol or commod- ity name. Some examples: 2.00001 @@ -267,35 +265,35 @@ As you can see, the amount format is somewhat flexible: - o amounts are a number (the "quantity") and optionally a currency sym- + o amounts are a number (the "quantity") and optionally a currency sym- bol/commodity name (the "commodity"). - o the commodity is a symbol, word, or phrase, on the left or right, - with or without a separating space. If the commodity contains num- - bers, spaces or non-word punctuation it must be enclosed in double + o the commodity is a symbol, word, or phrase, on the left or right, + with or without a separating space. If the commodity contains num- + bers, spaces or non-word punctuation it must be enclosed in double quotes. o negative amounts with a commodity on the left can have the minus sign before or after it - o digit groups (thousands, or any other grouping) can be separated by - space or comma or period and should be used as separator between all + o digit groups (thousands, or any other grouping) can be separated by + space or comma or period and should be used as separator between all groups - o decimal part can be separated by comma or period and should be dif- + o decimal part can be separated by comma or period and should be dif- ferent from digit groups separator - o scientific E-notation is allowed. Be careful not to use a digit - group separator character in scientific notation, as it's not sup- + o scientific E-notation is allowed. Be careful not to use a digit + group separator character in scientific notation, as it's not sup- ported and it might get mistaken for a decimal point. (Declaring the digit group separator character explicitly with a commodity directive will prevent this.) - You can use any of these variations when recording data. However, - there is some ambiguous way of representing numbers like $1.000 and - $1,000 both may mean either one thousand or one dollar. By default - hledger will assume that this is sole delimiter is used only for deci- - mals. On the other hand commodity format declared prior to that line + You can use any of these variations when recording data. However, + there is some ambiguous way of representing numbers like $1.000 and + $1,000 both may mean either one thousand or one dollar. By default + hledger will assume that this is sole delimiter is used only for deci- + mals. On the other hand commodity format declared prior to that line will help to resolve that ambiguity differently: commodity $1,000.00 @@ -304,9 +302,9 @@ expenses:gifts $1,000 assets - Though journal may contain mixed styles to represent amount, when - hledger displays amounts, it will choose a consistent format for each - commodity. (Except for price amounts, which are always formatted as + Though journal may contain mixed styles to represent amount, when + hledger displays amounts, it will choose a consistent format for each + commodity. (Except for price amounts, which are always formatted as written). The display format is chosen as follows: o if there is a commodity directive specifying the format, that is used @@ -582,11 +580,11 @@ nodes to be ignored, allowing emacs users to fold and navigate their journals with org-mode or orgstruct-mode.) - You can attach comments to a transaction by writing them after the - description and/or indented on the following lines (before the post- - ings). Similarly, you can attach comments to an individual posting by - writing them after the amount and/or indented on the following lines. - Transaction and posting comments must begin with a semicolon (;). + You can attach comments to a transaction by writing them after the de- + scription and/or indented on the following lines (before the postings). + Similarly, you can attach comments to an individual posting by writing + them after the amount and/or indented on the following lines. Transac- + tion and posting comments must begin with a semicolon (;). Some examples: @@ -662,47 +660,48 @@ here is a table summarising the directives and their effects, with links to more detailed docs. - - direc- end subdi- purpose can affect (as of - tive directive rec- 2018/06) + direc- end di- subdi- purpose can affect (as of + tive rective rec- 2018/06) tives ------------------------------------------------------------------------------------ + account any document account names, de- all entries in all + text clare account types & dis- files, before or + play order after - account any document account names, all entries in all - text declare account types & dis- files, before or - play order after - alias end rewrite account names following - aliases inline/included - entries until end - of current file or - end directive - apply end apply prepend a common parent to following - account account account names inline/included - entries until end - of current file or - end directive - comment end com- ignore part of journal following - ment inline/included - entries until end - of current file or - end directive - commod- format declare a commodity and its number notation: + + + alias end rewrite account names following in- + aliases line/included en- + tries until end of + current file or end + directive + apply end apply prepend a common parent to following in- + account account account names line/included en- + tries until end of + current file or end + directive + comment end com- ignore part of journal following in- + ment line/included en- + tries until end of + current file or end + directive + commod- format declare a commodity and its number notation: ity number notation & display following entries style in that commodity - in all files; dis- + in all files; dis- play style: amounts of that commodity in reports - D declare a commodity, number commodity: all com- + D declare a commodity, number commodity: all com- notation & display style for modityless entries - commodityless amounts in all files; num- - ber notation: fol- + commodityless amounts in all files; num- + ber notation: fol- lowing commodity- - less entries and + less entries and entries in that - commodity in all + commodity in all files; display style: amounts of that commodity in @@ -710,22 +709,21 @@ include include entries/directives what the included from another file directives affect P declare a market price for a amounts of that - commodity commodity in - reports, when -V is + commodity commodity in re- + ports, when -V is used - Y declare a year for yearless following - dates inline/included - entries until end - of current file + Y declare a year for yearless following in- + dates line/included en- + tries until end of + current file And some definitions: - subdirec- optional indented directive line immediately following a par- tive ent directive - number how to interpret numbers when parsing journal entries (the - notation identity of the decimal separator character). (Currently - each commodity can have its own notation, even in the same + number how to interpret numbers when parsing journal entries (the + notation identity of the decimal separator character). (Currently + each commodity can have its own notation, even in the same file.) display how to display amounts of a commodity in reports (symbol side style and spacing, digit groups, decimal separator, decimal places) @@ -733,8 +731,8 @@ scope are affected by a directive As you can see, directives vary in which journal entries and files they - affect, and whether they are focussed on input (parsing) or output - (reports). Some directives have multiple effects. + affect, and whether they are focussed on input (parsing) or output (re- + ports). Some directives have multiple effects. If you have a journal made up of multiple files, or pass multiple -f options on the command line, note that directives which affect input @@ -758,8 +756,8 @@ file. The include file path may contain common glob patterns (e.g. *). - The include directive can only be used in journal files. It can - include journal, timeclock or timedot files, but not CSV files. + The include directive can only be used in journal files. It can in- + clude journal, timeclock or timedot files, but not CSV files. Default year You can set a default year to be used for subsequent dates which don't @@ -815,8 +813,8 @@ Normally the display format is inferred from journal entries, but this can be unpredictable; declaring it with a commodity directive overrides - this and removes ambiguity. Towards this end, amounts in commodity - directives must always be written with a decimal point (a period or + this and removes ambiguity. Towards this end, amounts in commodity di- + rectives must always be written with a decimal point (a period or comma, followed by 0 or more decimal digits). Commodity directives do not affect how amounts are parsed; the parser @@ -829,8 +827,8 @@ and display format will be applied to all subsequent commodity-less amounts, or until the next D directive. - # commodity-less amounts should be treated as dollars - # (and displayed with symbol on the left, thousands separators and two decimal places) + ; commodity-less amounts should be treated as dollars + ; (and displayed with symbol on the left, thousands separators and two decimal places) D $1,000.00 1/1 @@ -841,8 +839,8 @@ a decimal point. Market prices - The P directive declares a market price, which is an exchange rate - between two commodities on a certain date. (In Ledger, they are called + The P directive declares a market price, which is an exchange rate be- + tween two commodities on a certain date. (In Ledger, they are called "historical prices".) These are often obtained from a stock exchange, cryptocurrency exchange, or the foreign exchange market. @@ -867,8 +865,8 @@ commodity using these prices. Declaring accounts - account directives can be used to pre-declare accounts. Though not - required, they can provide several benefits: + account directives can be used to pre-declare accounts. Though not re- + quired, they can provide several benefits: o They can document your intended chart of accounts, providing a refer- ence. @@ -927,8 +925,8 @@ detected automatically. Account types declared with tags - More generally, you can declare an account's type with an account - directive, by writing a type: tag in a comment, followed by one of the + More generally, you can declare an account's type with an account di- + rective, by writing a type: tag in a comment, followed by one of the words Asset, Liability, Equity, Revenue, Expense, or one of the letters ALERX (case insensitive): @@ -984,16 +982,16 @@ Undeclared accounts, if any, are displayed last, in alphabetical order. - Note that sorting is done at each level of the account tree (within - each group of sibling accounts under the same parent). And currently, + Note that sorting is done at each level of the account tree (within + each group of sibling accounts under the same parent). And currently, this directive: account other:zoo - would influence the position of zoo among other's subaccounts, but not - the position of other among the top-level accounts. This means: - you - will sometimes declare parent accounts (eg account other above) that - you don't intend to post to, just to customize their display order - + would influence the position of zoo among other's subaccounts, but not + the position of other among the top-level accounts. This means: - you + will sometimes declare parent accounts (eg account other above) that + you don't intend to post to, just to customize their display order - sibling accounts stay together (you couldn't display x:y in between a:b and a:c). @@ -1012,14 +1010,14 @@ o customising reports Account aliases also rewrite account names in account directives. They - do not affect account names being entered via hledger add or hledger- + do not affect account names being entered via hledger add or hledger- web. See also Cookbook: Rewrite account names. Basic aliases - To set an account alias, use the alias directive in your journal file. - This affects all subsequent journal entries in the current file or its + To set an account alias, use the alias directive in your journal file. + This affects all subsequent journal entries in the current file or its included files. The spaces around the = are optional: alias OLD = NEW @@ -1027,12 +1025,12 @@ Or, you can use the --alias 'OLD=NEW' option on the command line. This affects all entries. It's useful for trying out aliases interactively. - OLD and NEW are case sensitive full account names. hledger will - replace any occurrence of the old account name with the new one. Sub- - accounts are also affected. Eg: + OLD and NEW are case sensitive full account names. hledger will re- + place any occurrence of the old account name with the new one. Subac- + counts are also affected. Eg: alias checking = assets:bank:wells fargo:checking - # rewrites "checking" to "assets:bank:wells fargo:checking", or "checking:a" to "assets:bank:wells fargo:checking:a" + ; rewrites "checking" to "assets:bank:wells fargo:checking", or "checking:a" to "assets:bank:wells fargo:checking:a" Regex aliases There is also a more powerful variant that uses a regular expression, @@ -1048,7 +1046,7 @@ erenced by the usual numeric backreferences in REPLACEMENT. Eg: alias /^(.+):bank:([^:]+)(.*)/ = \1:\2 \3 - # rewrites "assets:bank:wells fargo:checking" to "assets:wells fargo checking" + ; rewrites "assets:bank:wells fargo:checking" to "assets:wells fargo checking" Also note that REPLACEMENT continues to the end of line (or on command line, to end of option argument), so it can contain trailing white- @@ -1080,23 +1078,23 @@ o aliases defined after/below the entry do not affect it. - This gives nearby aliases precedence over distant ones, and helps pro- - vide semantic stability - aliases will keep working the same way inde- + This gives nearby aliases precedence over distant ones, and helps pro- + vide semantic stability - aliases will keep working the same way inde- pendent of which files are being read and in which order. - In case of trouble, adding --debug=6 to the command line will show + In case of trouble, adding --debug=6 to the command line will show which aliases are being applied when. end aliases - You can clear (forget) all currently defined aliases with the end + You can clear (forget) all currently defined aliases with the end aliases directive: end aliases Default parent account - You can specify a parent account which will be prepended to all - accounts within a section of the journal. Use the apply account and - end apply account directives like so: + You can specify a parent account which will be prepended to all ac- + counts within a section of the journal. Use the apply account and end + apply account directives like so: apply account home @@ -1112,7 +1110,7 @@ home:food $10 home:cash $-10 - If end apply account is omitted, the effect lasts to the end of the + If end apply account is omitted, the effect lasts to the end of the file. Included files are also affected, eg: apply account business @@ -1121,19 +1119,19 @@ apply account personal include personal.journal - Prior to hledger 1.0, legacy account and end spellings were also sup- + Prior to hledger 1.0, legacy account and end spellings were also sup- ported. - A default parent account also affects account directives. It does not - affect account names being entered via hledger add or hledger-web. If - account aliases are present, they are applied after the default parent + A default parent account also affects account directives. It does not + affect account names being entered via hledger add or hledger-web. If + account aliases are present, they are applied after the default parent account. Periodic transactions - Periodic transaction rules describe transactions that recur. They - allow you to generate future transactions for forecasting, without hav- - ing to write them out explicitly in the journal (with --forecast). - Secondly, they also can be used to define budget goals (with --budget). + Periodic transaction rules describe transactions that recur. They al- + low you to generate future transactions for forecasting, without having + to write them out explicitly in the journal (with --forecast). Sec- + ondly, they also can be used to define budget goals (with --budget). A periodic transaction rule looks like a normal journal entry, with the date replaced by a tilde (~) followed by a period expression (mnemonic: @@ -1166,8 +1164,8 @@ income:acme inc Forecasting with periodic transactions - With the --forecast flag, each periodic transaction rule generates - future transactions recurring at the specified interval. These are not + With the --forecast flag, each periodic transaction rule generates fu- + ture transactions recurring at the specified interval. These are not saved in the journal, but appear in all reports. They will look like normal transactions, but with an extra tag: @@ -1225,7 +1223,6 @@ For more details, see: balance: Budget report and Cookbook: Budgeting and Forecasting. - Auto postings / transaction modifiers Transaction modifier rules, AKA auto posting rules, describe changes to be applied automatically to certain matched transactions. Currently @@ -1304,12 +1301,12 @@ tions Currently, transaction modifiers are applied / auto postings are added: - o after missing amounts are inferred, and transactions are checked for + o after missing amounts are inferred, and transactions are checked for balancedness, o but before balance assertions are checked. - Note this means that journal entries must be balanced both before and + Note this means that journal entries must be balanced both before and after auto postings are added. This changed in hledger 1.12+; see #893 for background. @@ -1319,11 +1316,11 @@ o generated-posting:= QUERY - shows this was generated by an auto post- ing rule, and the query - o _generated-posting:= QUERY - a hidden tag, which does not appear in + o _generated-posting:= QUERY - a hidden tag, which does not appear in hledger's output. This can be used to match postings generated "just now", rather than generated in the past and saved to the journal. - Also, any transaction that has been changed by transaction modifier + Also, any transaction that has been changed by transaction modifier rules will have these tags added: o modified: - this transaction was modified @@ -1332,18 +1329,18 @@ tion was modified "just now". EDITOR SUPPORT - Helper modes exist for popular text editors, which make working with + Helper modes exist for popular text editors, which make working with journal files easier. They add colour, formatting, tab completion, and - helpful commands, and are quite recommended if you edit your journal - with a text editor. They include ledger-mode or hledger-mode for - Emacs, vim-ledger for Vim, hledger-vscode for Visual Studio Code, and - others. See the [[Cookbook]] at hledger.org for the latest informa- + helpful commands, and are quite recommended if you edit your journal + with a text editor. They include ledger-mode or hledger-mode for + Emacs, vim-ledger for Vim, hledger-vscode for Visual Studio Code, and + others. See the [[Cookbook]] at hledger.org for the latest informa- tion. 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) @@ -1357,7 +1354,7 @@ SEE ALSO - hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1), + hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1), hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_time- dot(5), ledger(1) diff --git a/embeddedfiles/hledger_timeclock.txt b/embeddedfiles/hledger_timeclock.txt --- a/embeddedfiles/hledger_timeclock.txt +++ b/embeddedfiles/hledger_timeclock.txt @@ -7,11 +7,11 @@ Timeclock - the time logging format of timeclock.el, as read by hledger DESCRIPTION - hledger can read timeclock files. As with Ledger, these are (a subset + hledger can read timeclock files. As with Ledger, these are (a subset of) timeclock.el's format, containing clock-in and clock-out entries as - in the example below. The date is a simple date. The time format is - HH:MM[:SS][+-ZZZZ]. Seconds and timezone are optional. The timezone, - if present, must be four digits and is ignored (currently the time is + in the example below. The date is a simple date. The time format is + HH:MM[:SS][+-ZZZZ]. Seconds and timezone are optional. The timezone, + if present, must be four digits and is ignored (currently the time is always interpreted as a local time). i 2015/03/30 09:00:00 some:account name optional description after two spaces @@ -19,9 +19,9 @@ i 2015/03/31 22:21:45 another account o 2015/04/01 02:00:34 - hledger treats each clock-in/clock-out pair as a transaction posting - some number of hours to an account. Or if the session spans more than - one day, it is split into several transactions, one for each day. For + hledger treats each clock-in/clock-out pair as a transaction posting + some number of hours to an account. Or if the session spans more than + one day, it is split into several transactions, one for each day. For the above time log, hledger print generates these journal entries: $ hledger -f t.timeclock print @@ -42,21 +42,21 @@ To generate time logs, ie to clock in and clock out, you could: - o use emacs and the built-in timeclock.el, or the extended timeclock- + o use emacs and the built-in timeclock.el, or the extended timeclock- x.el and perhaps the extras in ledgerutils.el o at the command line, use these bash aliases: shell alias ti="echo i - `date '+%Y-%m-%d %H:%M:%S'` \$* >>$TIMELOG" alias to="echo o `date + `date '+%Y-%m-%d %H:%M:%S'` \$* >>$TIMELOG" alias to="echo o `date '+%Y-%m-%d %H:%M:%S'` >>$TIMELOG" o or use the old ti and to scripts in the ledger 2.x repository. These - rely on a "timeclock" executable which I think is just the ledger 2 + rely on a "timeclock" executable which I think is just the ledger 2 executable renamed. 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) @@ -70,7 +70,7 @@ SEE ALSO - hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1), + hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1), hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_time- dot(5), ledger(1) diff --git a/embeddedfiles/hledger_timedot.txt b/embeddedfiles/hledger_timedot.txt --- a/embeddedfiles/hledger_timedot.txt +++ b/embeddedfiles/hledger_timedot.txt @@ -28,8 +28,8 @@ Quantities can be written as: - o a sequence of dots (.) representing quarter hours. Spaces may - optionally be used for grouping and readability. Eg: .... .. + o a sequence of dots (.) representing quarter hours. Spaces may op- + tionally be used for grouping and readability. Eg: .... .. o an integral or decimal number, representing hours. Eg: 1.5 diff --git a/hledger.1 b/hledger.1 --- a/hledger.1 +++ b/hledger.1 @@ -1013,36 +1013,32 @@ .SS -V: Market value .PP The \f[C]-V/--market\f[R] flag converts reported amounts to their market -value in a default valuation commodity, using the historical market -prices in effect on a default valuation date. -.PP -For single period reports, the valuation date is today. -For multiperiod reports, it is the last day of each subperiod. +value in a default valuation commodity, using the market prices in +effect on a default valuation date. +For single period reports, the valuation date is today; for multiperiod +reports, it is the last day of each subperiod. +It is equivalent to \f[C]--value=now\f[R] or \f[C]--value=end\f[R] (see +below). .PP -The valuation commodity will be the one referenced in the latest +The default valuation commodity is the one referenced in the latest applicable market price dated on or before the valuation date. If most of your P declarations lead to a single home currency, this will usually be what you want. -.PP -Unlike the similar flag in Ledger, it does not infer market prices from -transaction prices. -In hledger, -B uses transaction prices, -V and -X use market prices. -.PP -It is equivalent to \f[C]--value=now\f[R] or \f[C]--value=end\f[R]. +(To specify the commodity, see -X below.) .PP Here\[aq]s a quick example: .IP .nf \f[C] -# one euro is worth this many dollars from nov 1 +; one euro is worth this many dollars from nov 1 P 2016/11/01 \[Eu] $1.10 -# purchase some euros on nov 3 +; purchase some euros on nov 3 2016/11/3 assets:euros \[Eu]100 assets:checking -# the euro is worth fewer dollars by dec 21 +; the euro is worth fewer dollars by dec 21 P 2016/12/21 \[Eu] $1.03 \f[R] .fi @@ -1074,15 +1070,19 @@ $103.00 assets:euros \f[R] .fi +.PP +Note that in hledger, market prices are always declared explicitly with +P directives; we do not infer them from transaction prices as Ledger +does. .SS -X: Market value in specified commodity .PP The \f[C]-X/--exchange\f[R] option is like \f[C]-V/--market\f[R] except it takes a commodity symbol argument, so that you can select a different target commodity. It is similar to the same option in Ledger, with the same caveat -mentioned for \f[C]-V\f[R]/\f[C]--value\f[R] above. +mentioned above. It is equivalent to \f[C]--value=now,COMM\f[R] or -\f[C]--value=end,COMM\f[R]; for more details, read on. +\f[C]--value=end,COMM\f[R]. .SS --value .PP \f[I](experimental, added 201905)\f[R] @@ -2628,6 +2628,65 @@ assets:checking \f[R] .fi +.SS commodities +.PP +commodities +.PD 0 +.P +.PD +List all commodity/currency symbols used or declared in the journal. +.SS descriptions +.PP +descriptions Show descriptions. +.PP +This command lists all descriptions that appear in transactions. +.PP +Examples: +.IP +.nf +\f[C] +$ hledger descriptions +Store Name +Gas Station | Petrol +Person A +\f[R] +.fi +.SS diff +.PP +diff +.PD 0 +.P +.PD +Compares a particular account\[aq]s transactions in two input files. +It shows any transactions to this account which are in one file but not +in the other. +.PP +More precisely, for each posting affecting this account in either file, +it looks for a corresponding posting in the other file which posts the +same amount to the same account (ignoring date, description, etc.) Since +postings not transactions are compared, this also works when multiple +bank transactions have been combined into a single journal entry. +.PP +This is useful eg if you have downloaded an account\[aq]s transactions +from your bank (eg as CSV data). +When hledger and your bank disagree about the account balance, you can +compare the bank data with your journal to find out the cause. +.PP +Examples: +.IP +.nf +\f[C] +$ hledger diff -f $LEDGER_FILE -f bank.csv assets:bank:giro +These transactions are in the first file only: + +2014/01/01 Opening Balances + assets:bank:giro EUR ... + ... + equity:opening balances EUR -... + +These transactions are in the second file only: +\f[R] +.fi .SS files .PP files @@ -2785,6 +2844,37 @@ .PP This command also supports output destination and output format selection. +.SS notes +.PP +notes Show notes. +.PP +This command lists all notes that appear in transactions. +.PP +Examples: +.IP +.nf +\f[C] +$ hledger notes +Petrol +Snacks +\f[R] +.fi +.SS payees +.PP +payees Show payee names. +.PP +This command lists all payee names that appear in transactions. +.PP +Examples: +.IP +.nf +\f[C] +$ hledger payees +Store Name +Gas Station +Person A +\f[R] +.fi .SS prices .PP prices diff --git a/hledger.cabal b/hledger.cabal --- a/hledger.cabal +++ b/hledger.cabal @@ -4,10 +4,10 @@ -- -- see: https://github.com/sol/hpack -- --- hash: 9b996544825f06ba1fe409f012a89d17e383ca7d94353ac080c40937ba5ce3d5 +-- hash: 2f976d13d0036cdca6fca7319fa10dcec3ffdce46769bcde5421211d23d93e7c name: hledger -version: 1.15 +version: 1.15.1 synopsis: Command-line interface for the hledger accounting tool description: This is hledger's command-line interface. Its basic function is to read a plain text file describing @@ -146,7 +146,7 @@ other-modules: Paths_hledger ghc-options: -Wall -fno-warn-unused-do-bind -fno-warn-name-shadowing -fno-warn-missing-signatures -fno-warn-type-defaults -fno-warn-orphans -optP-Wno-nonportable-include-path - cpp-options: -DVERSION="1.15" + cpp-options: -DVERSION="1.15.1" build-depends: Decimal , Diff @@ -163,7 +163,7 @@ , filepath , hashable >=1.2.4 , haskeline >=0.6 - , hledger-lib >=1.15 && <1.16 + , hledger-lib >=1.15.1 && <1.16 , lucid , math-functions >=0.2.0.0 , megaparsec >=7.0.0 && <8 @@ -199,7 +199,7 @@ hs-source-dirs: app ghc-options: -Wall -fno-warn-unused-do-bind -fno-warn-name-shadowing -fno-warn-missing-signatures -fno-warn-type-defaults -fno-warn-orphans -optP-Wno-nonportable-include-path - cpp-options: -DVERSION="1.15" + cpp-options: -DVERSION="1.15.1" build-depends: Decimal , ansi-terminal >=0.6.2.3 @@ -215,7 +215,7 @@ , filepath , haskeline >=0.6 , hledger - , hledger-lib >=1.15 && <1.16 + , hledger-lib >=1.15.1 && <1.16 , math-functions >=0.2.0.0 , megaparsec >=7.0.0 && <8 , mtl @@ -253,7 +253,7 @@ hs-source-dirs: test ghc-options: -Wall -fno-warn-unused-do-bind -fno-warn-name-shadowing -fno-warn-missing-signatures -fno-warn-type-defaults -fno-warn-orphans -optP-Wno-nonportable-include-path - cpp-options: -DVERSION="1.15" + cpp-options: -DVERSION="1.15.1" build-depends: Decimal , ansi-terminal >=0.6.2.3 @@ -269,7 +269,7 @@ , filepath , haskeline >=0.6 , hledger - , hledger-lib >=1.15 && <1.16 + , hledger-lib >=1.15.1 && <1.16 , math-functions >=0.2.0.0 , megaparsec >=7.0.0 && <8 , mtl @@ -323,7 +323,7 @@ , filepath , haskeline >=0.6 , hledger - , hledger-lib >=1.15 && <1.16 + , hledger-lib >=1.15.1 && <1.16 , html , math-functions >=0.2.0.0 , megaparsec >=7.0.0 && <8 diff --git a/hledger.info b/hledger.info --- a/hledger.info +++ b/hledger.info @@ -773,34 +773,27 @@ ----------------------- The '-V/--market' flag converts reported amounts to their market value -in a default valuation commodity, using the historical market prices in -effect on a default valuation date. - - For single period reports, the valuation date is today. For -multiperiod reports, it is the last day of each subperiod. +in a default valuation commodity, using the market prices in effect on a +default valuation date. For single period reports, the valuation date +is today; for multiperiod reports, it is the last day of each subperiod. +It is equivalent to '--value=now' or '--value=end' (see below). - The valuation commodity will be the one referenced in the latest + The default valuation commodity is the one referenced in the latest applicable market price dated on or before the valuation date. If most of your P declarations lead to a single home currency, this will usually -be what you want. - - Unlike the similar flag in Ledger, it does not infer market prices -from transaction prices. In hledger, -B uses transaction prices, -V and --X use market prices. - - It is equivalent to '--value=now' or '--value=end'. +be what you want. (To specify the commodity, see -X below.) Here's a quick example: -# one euro is worth this many dollars from nov 1 +; one euro is worth this many dollars from nov 1 P 2016/11/01 € $1.10 -# purchase some euros on nov 3 +; purchase some euros on nov 3 2016/11/3 assets:euros €100 assets:checking -# the euro is worth fewer dollars by dec 21 +; the euro is worth fewer dollars by dec 21 P 2016/12/21 € $1.03 How many euros do I have ? @@ -819,6 +812,10 @@ $ hledger -f t.j bal -N euros -V $103.00 assets:euros + Note that in hledger, market prices are always declared explicitly +with P directives; we do not infer them from transaction prices as +Ledger does. +  File: hledger.info, Node: -X Market value in specified commodity, Next: --value, Prev: -V Market value, Up: Valuation @@ -828,8 +825,8 @@ The '-X/--exchange' option is like '-V/--market' except it takes a commodity symbol argument, so that you can select a different target commodity. It is similar to the same option in Ledger, with the same -caveat mentioned for '-V'/'--value' above. It is equivalent to -'--value=now,COMM' or '--value=end,COMM'; for more details, read on. +caveat mentioned above. It is equivalent to '--value=now,COMM' or +'--value=end,COMM'.  File: hledger.info, Node: --value, Next: Combining -B -V -X --value, Prev: -X Market value in specified commodity, Up: Valuation @@ -1294,10 +1291,15 @@ * check-dates:: * check-dupes:: * close:: +* commodities:: +* descriptions:: +* diff:: * files:: * help:: * import:: * incomestatement:: +* notes:: +* payees:: * prices:: * print:: * print-unique:: @@ -2110,7 +2112,7 @@ An example: http://stefanorodighiero.net/software/hledger-dupes.html  -File: hledger.info, Node: close, Next: files, Prev: check-dupes, Up: COMMANDS +File: hledger.info, Node: close, Next: commodities, Prev: check-dupes, Up: COMMANDS 4.10 close ========== @@ -2199,9 +2201,70 @@ assets:checking  -File: hledger.info, Node: files, Next: help, Prev: close, Up: COMMANDS +File: hledger.info, Node: commodities, Next: descriptions, Prev: close, Up: COMMANDS -4.11 files +4.11 commodities +================ + +commodities +List all commodity/currency symbols used or declared in the journal. + + +File: hledger.info, Node: descriptions, Next: diff, Prev: commodities, Up: COMMANDS + +4.12 descriptions +================= + +descriptions Show descriptions. + + This command lists all descriptions that appear in transactions. + + Examples: + +$ hledger descriptions +Store Name +Gas Station | Petrol +Person A + + +File: hledger.info, Node: diff, Next: files, Prev: descriptions, Up: COMMANDS + +4.13 diff +========= + +diff +Compares a particular account's transactions in two input files. It +shows any transactions to this account which are in one file but not in +the other. + + More precisely, for each posting affecting this account in either +file, it looks for a corresponding posting in the other file which posts +the same amount to the same account (ignoring date, description, etc.) +Since postings not transactions are compared, this also works when +multiple bank transactions have been combined into a single journal +entry. + + This is useful eg if you have downloaded an account's transactions +from your bank (eg as CSV data). When hledger and your bank disagree +about the account balance, you can compare the bank data with your +journal to find out the cause. + + Examples: + +$ hledger diff -f $LEDGER_FILE -f bank.csv assets:bank:giro +These transactions are in the first file only: + +2014/01/01 Opening Balances + assets:bank:giro EUR ... + ... + equity:opening balances EUR -... + +These transactions are in the second file only: + + +File: hledger.info, Node: files, Next: help, Prev: diff, Up: COMMANDS + +4.14 files ========== files @@ -2211,7 +2274,7 @@  File: hledger.info, Node: help, Next: import, Prev: files, Up: COMMANDS -4.12 help +4.15 help ========= help @@ -2251,7 +2314,7 @@  File: hledger.info, Node: import, Next: incomestatement, Prev: help, Up: COMMANDS -4.13 import +4.16 import =========== import @@ -2279,7 +2342,7 @@  File: hledger.info, Node: Importing balance assignments, Up: import -4.13.1 Importing balance assignments +4.16.1 Importing balance assignments ------------------------------------ Entries added by import will have their posting amounts made explicit @@ -2296,9 +2359,9 @@ please test it and send a pull request.)  -File: hledger.info, Node: incomestatement, Next: prices, Prev: import, Up: COMMANDS +File: hledger.info, Node: incomestatement, Next: notes, Prev: import, Up: COMMANDS -4.14 incomestatement +4.17 incomestatement ==================== incomestatement, is @@ -2343,11 +2406,44 @@ selection.  -File: hledger.info, Node: prices, Next: print, Prev: incomestatement, Up: COMMANDS +File: hledger.info, Node: notes, Next: payees, Prev: incomestatement, Up: COMMANDS -4.15 prices +4.18 notes +========== + +notes Show notes. + + This command lists all notes that appear in transactions. + + Examples: + +$ hledger notes +Petrol +Snacks + + +File: hledger.info, Node: payees, Next: prices, Prev: notes, Up: COMMANDS + +4.19 payees =========== +payees Show payee names. + + This command lists all payee names that appear in transactions. + + Examples: + +$ hledger payees +Store Name +Gas Station +Person A + + +File: hledger.info, Node: prices, Next: print, Prev: payees, Up: COMMANDS + +4.20 prices +=========== + prices Print market price directives from the journal. With -costs, also print synthetic market prices based on transaction prices. With @@ -2357,7 +2453,7 @@  File: hledger.info, Node: print, Next: print-unique, Prev: prices, Up: COMMANDS -4.16 print +4.21 print ========== print, txns, p @@ -2458,7 +2554,7 @@  File: hledger.info, Node: print-unique, Next: register, Prev: print, Up: COMMANDS -4.17 print-unique +4.22 print-unique ================= print-unique @@ -2479,7 +2575,7 @@  File: hledger.info, Node: register, Next: register-match, Prev: print-unique, Up: COMMANDS -4.18 register +4.23 register ============= register, reg, r @@ -2569,7 +2665,7 @@  File: hledger.info, Node: Custom register output, Up: register -4.18.1 Custom register output +4.23.1 Custom register output ----------------------------- register uses the full terminal width by default, except on windows. @@ -2600,7 +2696,7 @@  File: hledger.info, Node: register-match, Next: rewrite, Prev: register, Up: COMMANDS -4.19 register-match +4.24 register-match =================== register-match @@ -2613,7 +2709,7 @@  File: hledger.info, Node: rewrite, Next: roi, Prev: register-match, Up: COMMANDS -4.20 rewrite +4.25 rewrite ============ rewrite @@ -2665,7 +2761,7 @@  File: hledger.info, Node: Re-write rules in a file, Up: rewrite -4.20.1 Re-write rules in a file +4.25.1 Re-write rules in a file ------------------------------- During the run this tool will execute so called "Automated Transactions" @@ -2708,7 +2804,7 @@  File: hledger.info, Node: Diff output format, Next: rewrite vs print --auto, Up: Re-write rules in a file -4.20.1.1 Diff output format +4.25.1.1 Diff output format ........................... To use this tool for batch modification of your journal files you may @@ -2749,7 +2845,7 @@  File: hledger.info, Node: rewrite vs print --auto, Prev: Diff output format, Up: Re-write rules in a file -4.20.1.2 rewrite vs. print -auto +4.25.1.2 rewrite vs. print -auto ................................ This command predates print -auto, and currently does much the same @@ -2769,7 +2865,7 @@  File: hledger.info, Node: roi, Next: stats, Prev: rewrite, Up: COMMANDS -4.21 roi +4.26 roi ======== roi @@ -2797,7 +2893,7 @@  File: hledger.info, Node: stats, Next: tags, Prev: roi, Up: COMMANDS -4.22 stats +4.27 stats ========== stats @@ -2828,7 +2924,7 @@  File: hledger.info, Node: tags, Next: test, Prev: stats, Up: COMMANDS -4.23 tags +4.28 tags ========= tags @@ -2841,7 +2937,7 @@  File: hledger.info, Node: test, Prev: tags, Up: COMMANDS -4.24 test +4.29 test ========= test @@ -2957,9 +3053,6 @@ * interest:: * irr:: - -File: hledger.info, Node: diff, Next: iadd, Up: Third party add-ons - 5.2.1 diff ---------- @@ -2967,7 +3060,7 @@ journal file and another.  -File: hledger.info, Node: iadd, Next: interest, Prev: diff, Up: Third party add-ons +File: hledger.info, Node: iadd, Next: interest, Prev: , Up: Third party add-ons 5.2.2 iadd ---------- @@ -3084,132 +3177,141 @@ Ref: #b-cost25256 Node: -V Market value25454 Ref: #v-market-value25628 -Node: -X Market value in specified commodity27034 -Ref: #x-market-value-in-specified-commodity27254 -Node: --value27594 -Ref: #value27759 -Node: Valuation type28560 -Ref: #valuation-type28696 -Node: Valuation commodity29581 -Ref: #valuation-commodity29752 -Node: --value examples30452 -Ref: #value-examples30629 -Node: Effect of --value on reports32612 -Ref: #effect-of---value-on-reports32785 -Node: Combining -B -V -X --value35476 -Ref: #combining--b--v--x---value35638 -Node: Output destination35674 -Ref: #output-destination35826 -Node: Output format36109 -Ref: #output-format36261 -Node: Regular expressions36646 -Ref: #regular-expressions36783 -Node: QUERIES38144 -Ref: #queries38246 -Node: COMMANDS42208 -Ref: #commands42320 -Node: accounts43321 -Ref: #accounts43419 -Node: activity44118 -Ref: #activity44228 -Node: add44611 -Ref: #add44710 -Node: balance47455 -Ref: #balance47566 -Node: Classic balance report49008 -Ref: #classic-balance-report49181 -Node: Customising the classic balance report50550 -Ref: #customising-the-classic-balance-report50778 -Node: Colour support52854 -Ref: #colour-support53021 -Node: Flat mode53194 -Ref: #flat-mode53342 -Node: Depth limited balance reports53755 -Ref: #depth-limited-balance-reports53955 -Node: Multicolumn balance report54411 -Ref: #multicolumn-balance-report54609 -Node: Budget report59923 -Ref: #budget-report60066 -Node: Nested budgets65268 -Ref: #nested-budgets65380 -Ref: #output-format-168860 -Node: balancesheet68938 -Ref: #balancesheet69074 -Node: balancesheetequity70389 -Ref: #balancesheetequity70538 -Node: cashflow71099 -Ref: #cashflow71227 -Node: check-dates72255 -Ref: #check-dates72382 -Node: check-dupes72661 -Ref: #check-dupes72785 -Node: close73078 -Ref: #close73186 -Node: files76773 -Ref: #files76874 -Node: help77021 -Ref: #help77121 -Node: import78214 -Ref: #import78328 -Node: Importing balance assignments79116 -Ref: #importing-balance-assignments79264 -Node: incomestatement79913 -Ref: #incomestatement80047 -Node: prices81383 -Ref: #prices81498 -Node: print81777 -Ref: #print81887 -Node: print-unique86380 -Ref: #print-unique86506 -Node: register86791 -Ref: #register86918 -Node: Custom register output91090 -Ref: #custom-register-output91219 -Node: register-match92481 -Ref: #register-match92615 -Node: rewrite92966 -Ref: #rewrite93081 -Node: Re-write rules in a file94936 -Ref: #re-write-rules-in-a-file95070 -Node: Diff output format96280 -Ref: #diff-output-format96449 -Node: rewrite vs print --auto97541 -Ref: #rewrite-vs.-print---auto97720 -Node: roi98276 -Ref: #roi98374 -Node: stats99386 -Ref: #stats99485 -Node: tags100273 -Ref: #tags100371 -Node: test100665 -Ref: #test100749 -Node: ADD-ON COMMANDS101510 -Ref: #add-on-commands101620 -Node: Official add-ons102908 -Ref: #official-add-ons103048 -Node: api103136 -Ref: #api103225 -Node: ui103277 -Ref: #ui103376 -Node: web103434 -Ref: #web103523 -Node: Third party add-ons103569 -Ref: #third-party-add-ons103744 -Node: diff103880 -Ref: #diff103977 -Node: iadd104076 -Ref: #iadd104190 -Node: interest104273 -Ref: #interest104394 -Node: irr104489 -Ref: #irr104587 -Node: Experimental add-ons104718 -Ref: #experimental-add-ons104870 -Node: autosync105151 -Ref: #autosync105262 -Node: chart105501 -Ref: #chart105620 -Node: check105691 -Ref: #check105793 +Node: -X Market value in specified commodity27058 +Ref: #x-market-value-in-specified-commodity27278 +Node: --value27572 +Ref: #value27737 +Node: Valuation type28538 +Ref: #valuation-type28674 +Node: Valuation commodity29559 +Ref: #valuation-commodity29730 +Node: --value examples30430 +Ref: #value-examples30607 +Node: Effect of --value on reports32590 +Ref: #effect-of---value-on-reports32763 +Node: Combining -B -V -X --value35454 +Ref: #combining--b--v--x---value35616 +Node: Output destination35652 +Ref: #output-destination35804 +Node: Output format36087 +Ref: #output-format36239 +Node: Regular expressions36624 +Ref: #regular-expressions36761 +Node: QUERIES38122 +Ref: #queries38224 +Node: COMMANDS42186 +Ref: #commands42298 +Node: accounts43362 +Ref: #accounts43460 +Node: activity44159 +Ref: #activity44269 +Node: add44652 +Ref: #add44751 +Node: balance47496 +Ref: #balance47607 +Node: Classic balance report49049 +Ref: #classic-balance-report49222 +Node: Customising the classic balance report50591 +Ref: #customising-the-classic-balance-report50819 +Node: Colour support52895 +Ref: #colour-support53062 +Node: Flat mode53235 +Ref: #flat-mode53383 +Node: Depth limited balance reports53796 +Ref: #depth-limited-balance-reports53996 +Node: Multicolumn balance report54452 +Ref: #multicolumn-balance-report54650 +Node: Budget report59964 +Ref: #budget-report60107 +Node: Nested budgets65309 +Ref: #nested-budgets65421 +Ref: #output-format-168901 +Node: balancesheet68979 +Ref: #balancesheet69115 +Node: balancesheetequity70430 +Ref: #balancesheetequity70579 +Node: cashflow71140 +Ref: #cashflow71268 +Node: check-dates72296 +Ref: #check-dates72423 +Node: check-dupes72702 +Ref: #check-dupes72826 +Node: close73119 +Ref: #close73233 +Node: commodities76820 +Ref: #commodities76947 +Node: descriptions77029 +Ref: #descriptions77157 +Node: diff77338 +Ref: #diff77444 +Node: files78491 +Ref: #files78591 +Node: help78738 +Ref: #help78838 +Node: import79931 +Ref: #import80045 +Node: Importing balance assignments80833 +Ref: #importing-balance-assignments80981 +Node: incomestatement81630 +Ref: #incomestatement81763 +Node: notes83099 +Ref: #notes83212 +Node: payees83338 +Ref: #payees83444 +Node: prices83602 +Ref: #prices83708 +Node: print83987 +Ref: #print84097 +Node: print-unique88590 +Ref: #print-unique88716 +Node: register89001 +Ref: #register89128 +Node: Custom register output93300 +Ref: #custom-register-output93429 +Node: register-match94691 +Ref: #register-match94825 +Node: rewrite95176 +Ref: #rewrite95291 +Node: Re-write rules in a file97146 +Ref: #re-write-rules-in-a-file97280 +Node: Diff output format98490 +Ref: #diff-output-format98659 +Node: rewrite vs print --auto99751 +Ref: #rewrite-vs.-print---auto99930 +Node: roi100486 +Ref: #roi100584 +Node: stats101596 +Ref: #stats101695 +Node: tags102483 +Ref: #tags102581 +Node: test102875 +Ref: #test102959 +Node: ADD-ON COMMANDS103720 +Ref: #add-on-commands103830 +Node: Official add-ons105118 +Ref: #official-add-ons105258 +Node: api105346 +Ref: #api105435 +Node: ui105487 +Ref: #ui105586 +Node: web105644 +Ref: #web105733 +Node: Third party add-ons105779 +Ref: #third-party-add-ons105954 +Ref: #diff-1106113 +Node: iadd106212 +Ref: #iadd106322 +Node: interest106405 +Ref: #interest106526 +Node: irr106621 +Ref: #irr106719 +Node: Experimental add-ons106850 +Ref: #experimental-add-ons107002 +Node: autosync107283 +Ref: #autosync107394 +Node: chart107633 +Ref: #chart107752 +Node: check107823 +Ref: #check107925  End Tag Table diff --git a/hledger.txt b/hledger.txt --- a/hledger.txt +++ b/hledger.txt @@ -176,8 +176,8 @@ using period expressions syntax --date2 - match the secondary date instead (see command help for other - effects) + match the secondary date instead (see command help for other ef- + fects) -U --unmarked include only unmarked postings/txns (can combine with -P or -C) @@ -218,14 +218,14 @@ Some reporting options can also be written as query arguments. Command options - To see options for a particular command, including command-specific - options, run: hledger COMMAND -h. + To see options for a particular command, including command-specific op- + tions, run: hledger COMMAND -h. Command-specific options must be written after the command name, eg: hledger print -x. - Additionally, if the command is an addon, you may need to put its - options after a double-hyphen, eg: hledger ui -- --watch. Or, you can + Additionally, if the command is an addon, you may need to put its op- + tions after a double-hyphen, eg: hledger ui -- --watch. Or, you can run the addon executable directly: hledger-ui --watch. Command arguments @@ -273,7 +273,6 @@ If you asked why four slashes above, this may help: - unescaped: $ escaped: \$ double-escaped: \\$ @@ -321,8 +320,8 @@ This requires a well-configured environment. Here are some tips: - 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 + o A system locale must be configured, and it must be one that can de- + code the characters being used. In bash, you can set a locale like this: export LANG=en_US.UTF-8. There are some more details in Trou- bleshooting. This step is essential - without it, hledger will quit on encountering a non-ascii character (as with all GHC-compiled pro- @@ -365,7 +364,6 @@ format automatically based on the file extension, or if that is not recognised, by trying each built-in "reader" in turn: - Reader: Reads: Used for file extensions: ----------------------------------------------------------------------------- journal hledger's journal format, also .journal .j .hledger .ledger @@ -403,7 +401,6 @@ Examples: - 2004/10/1, 2004-01-01, exact date, several sepa- 2004.9.1 rators allowed. Year is 4+ digits, month is 1-12, @@ -416,66 +413,68 @@ october, oct start of month in current year yesterday, today, tomorrow -1, 0, 1 days from today - last/this/next -1, 0, 1 periods from the + last/this/next -1, 0, 1 periods from the day/week/month/quar- current period ter/year - 20181201 8 digit YYYYMMDD with + 20181201 8 digit YYYYMMDD with valid year month and day - 201812 6 digit YYYYMM with valid + 201812 6 digit YYYYMM with valid year and month - Counterexamples - malformed digit sequences might give surprising - results: - + Counterexamples - malformed digit sequences might give surprising re- + sults: - 201813 6 digits with an invalid - month is parsed as start + 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 + 20181301 8 digits with an invalid + month is parsed as start of 8-digit year - 20181232 8 digits with an invalid + 20181232 8 digits with an invalid day gives an error 201801012 9+ digits beginning with a valid YYYYMMDD gives an error Report start & end date - Most hledger reports show the full span of time represented by the + Most hledger reports show the full span of time represented by the journal data, by default. So, the effective report start and end dates - will be the earliest and latest transaction or posting dates found in + will be the earliest and latest transaction or posting dates found in the journal. - 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 As in Ledger, end dates are exclusive, so you need to write the date + o As in Ledger, end dates are exclusive, so you need to write the date after the last day you want to include. - 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. Examples: - -b 2016/3/17 begin on St. Patrick's day 2016 + + + + -e 12/1 end at the start of decem- ber 1st of the current - year (11/30 will be the + year (11/30 will be the last date included) - -b thismonth all transactions on or - after the 1st of the cur- - rent month + -b thismonth all transactions on or af- + ter the 1st of the current + month -p thismonth all transactions in the current month date:2016/3/17- the above written as @@ -486,15 +485,15 @@ Report intervals A report interval can be specified so that commands like register, bal- - ance and activity will divide their reports into multiple subperiods. - The basic intervals can be selected with one of -D/--daily, - -W/--weekly, -M/--monthly, -Q/--quarterly, or -Y/--yearly. More com- - plex intervals may be specified with a period expression. Report - intervals can not be specified with a query. + ance and activity will divide their reports into multiple subperiods. + The basic intervals can be selected with one of -D/--daily, + -W/--weekly, -M/--monthly, -Q/--quarterly, or -Y/--yearly. More com- + plex intervals may be specified with a period expression. Report in- + tervals can not be specified with a query. 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 @@ -506,7 +505,6 @@ long as you don't run two dates together. "to" can also be written as "-". These are equivalent to the above: - -p "2009/1/1 2009/4/1" -p2009/1/1to2009/4/1 -p2009/1/1-2009/4/1 @@ -514,7 +512,6 @@ Dates are smart dates, so if the current year is 2009, the above can also be written as: - -p "1/1 4/1" -p "january-apr" -p "this year to 4/1" @@ -522,7 +519,6 @@ If you specify only one date, the missing start or end date will be the earliest or latest transaction in your journal: - -p "from 2009/1/1" everything after january 1, 2009 -p "from 2009/1" the same @@ -533,21 +529,21 @@ A single date with no "from" or "to" defines both the start and end date like so: - -p "2009" the year 2009; equivalent to "2009/1/1 to 2010/1/1" -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 to "2009/1/1 to 2009/1/2" - The argument of -p can also begin with, or be, a report interval - expression. The basic report intervals are daily, weekly, monthly, - quarterly, or yearly, which have the same effect as the -D,-W,-M,-Q, or - -Y flags. Between report interval and start/end dates (if any), the - word in is optional. Examples: - + The argument of -p can also begin with, or be, a report interval ex- + pression. The basic report intervals are daily, weekly, monthly, quar- + terly, or yearly, which have the same effect as the -D,-W,-M,-Q, or -Y + flags. Between report interval and start/end dates (if any), the word + in is optional. Examples: -p "weekly from 2009/1/1 to 2009/4/1" -p "monthly in 2008" @@ -555,12 +551,11 @@ Note that weekly, monthly, quarterly and yearly intervals will always start on the first day on week, month, quarter or year accordingly, and - will end on the last day of same period, even if associated period - expression specifies different explicit start and end date. + will end on the last day of same period, even if associated period ex- + pression specifies different explicit start and end date. For example: - -p "weekly from 2009/1/1 to 2009/4/1" -- starts on 2008/12/29, closest pre- ceeding Monday @@ -573,8 +568,8 @@ -p "yearly from 2009-12-29" - starts on 2009/01/01, first day of 2009 - The following more complex report intervals are also supported: - biweekly, bimonthly, every day|week|month|quarter|year, every N + The following more complex report intervals are also supported: bi- + weekly, bimonthly, every day|week|month|quarter|year, every N days|weeks|months|quarters|years. All of these will start on the first day of the requested period and @@ -582,14 +577,13 @@ Examples: - -p "bimonthly from 2008" -- periods will have boundaries on 2008/01/01, 2008/03/01, ... -p "every 2 weeks" -- starts on closest preceeding Monday - -p "every 5 month from 2009/03" -- - periods will have boundaries on + -p "every 5 month from 2009/03" -- pe- + riods will have boundaries on 2009/03/01, 2009/08/01, ... If you want intervals that start on arbitrary day of your choosing and @@ -601,7 +595,6 @@ Examples: - -p "every 2nd day of week" -- periods will go from Tue to Tue -p "every Tue" -- same @@ -610,6 +603,7 @@ -p "every 2nd Monday" -- period bound- aries will be on second Monday of each month + -p "every 11/05" -- yearly periods with boundaries on 5th of Nov -p "every 5th Nov" -- same @@ -628,9 +622,9 @@ Depth limiting With the --depth N option (short form: -N), commands like account, bal- ance and register will show only the uppermost accounts in the account - tree, down to level N. Use this when you want a summary with less - detail. This flag has the same effect as a depth: query argument (so - -2, --depth=2 or depth:2 are basically equivalent). + tree, down to level N. Use this when you want a summary with less de- + tail. This flag has the same effect as a depth: query argument (so -2, + --depth=2 or depth:2 are basically equivalent). Pivoting Normally hledger sums amounts, and organizes them in a hierarchy, based @@ -668,8 +662,8 @@ -------------------- 0 - One way to show only amounts with a member: value (using a query, - described below): + One way to show only amounts with a member: value (using a query, de- + scribed below): $ hledger balance --pivot member tag:member=. -2 EUR John Doe @@ -692,34 +686,27 @@ -V: Market value The -V/--market flag converts reported amounts to their market value in - a default valuation commodity, using the historical market prices in - effect on a default valuation date. - - For single period reports, the valuation date is today. For multi- - period reports, it is the last day of each subperiod. - - The valuation commodity will be the one referenced in the latest appli- - cable market price dated on or before the valuation date. If most of - your P declarations lead to a single home currency, this will usually - be what you want. - - Unlike the similar flag in Ledger, it does not infer market prices from - transaction prices. In hledger, -B uses transaction prices, -V and -X - use market prices. + a default valuation commodity, using the market prices in effect on a + default valuation date. For single period reports, the valuation date + is today; for multiperiod reports, it is the last day of each subpe- + riod. It is equivalent to --value=now or --value=end (see below). - It is equivalent to --value=now or --value=end. + The default valuation commodity is the one referenced in the latest ap- + plicable market price dated on or before the valuation date. If most + of your P declarations lead to a single home currency, this will usu- + ally be what you want. (To specify the commodity, see -X below.) Here's a quick example: - # one euro is worth this many dollars from nov 1 + ; one euro is worth this many dollars from nov 1 P 2016/11/01 EUR $1.10 - # purchase some euros on nov 3 + ; purchase some euros on nov 3 2016/11/3 assets:euros EUR100 assets:checking - # the euro is worth fewer dollars by dec 21 + ; the euro is worth fewer dollars by dec 21 P 2016/12/21 EUR $1.03 How many euros do I have ? @@ -732,18 +719,22 @@ $ hledger -f t.j bal -N euros -V -e 2016/11/4 $110.00 assets:euros - What are they worth after 2016/12/21 ? (no report end date specified, + What are they worth after 2016/12/21 ? (no report end date specified, defaults to today) $ hledger -f t.j bal -N euros -V $103.00 assets:euros + Note that in hledger, market prices are always declared explicitly with + P directives; we do not infer them from transaction prices as Ledger + does. + -X: Market value in specified commodity - The -X/--exchange option is like -V/--market except it takes a commod- - ity symbol argument, so that you can select a different target commod- - ity. It is similar to the same option in Ledger, with the same caveat - mentioned for -V/--value above. It is equivalent to --value=now,COMM - or --value=end,COMM; for more details, read on. + The -X/--exchange option is like -V/--market except it takes a commod- + ity symbol argument, so that you can select a different target commod- + ity. It is similar to the same option in Ledger, with the same caveat + mentioned above. It is equivalent to --value=now,COMM or + --value=end,COMM. --value (experimental, added 201905) @@ -759,45 +750,45 @@ - default valuation commodity (or COMM) using market prices at some date Valuation type - TYPE is one of these keywords, or their first letter, or a date (which + TYPE is one of these keywords, or their first letter, or a date (which must be 8 digits with - or / or . separators): --value=cost - Convert amounts to cost, using the prices recorded in transac- + Convert amounts to cost, using the prices recorded in transac- tions. -B/--cost is equivalent to this. --value=end - Convert amounts to their value in default valuation commodity - using market prices on the last day of the report period (or of - each subperiod in a multiperiod report). When no report period + Convert amounts to their value in default valuation commodity + using market prices on the last day of the report period (or of + each subperiod in a multiperiod report). When no report period is specified, uses the journal's last transaction date. --value=now - Convert amounts to their value in default valuation commodity - using current market prices (as of when report is generated). + Convert amounts to their value in default valuation commodity + using current market prices (as of when report is generated). -V/--market is equivalent to this. --value=YYYY-MM-DD - Convert amounts to their value in default valuation commodity + Convert amounts to their value in default valuation commodity using market prices on this date. Eg --value=2019-04-25. Valuation commodity - The default valuation commodity is the commodity mentioned in the most + The default valuation commodity is the commodity mentioned in the most recent applicable market price declaration. When all your price decla- - rations lead to a single home currency, this will usually do what you + rations lead to a single home currency, this will usually do what you want. - To select a different valuation commodity: write the commodity symbol - after the valuation type, separated by a comma (eg: --value=now,EUR). + To select a different valuation commodity: write the commodity symbol + after the valuation type, separated by a comma (eg: --value=now,EUR). This will use, in this preferred order: o declared prices (from source commodity to valuation commodity) - o reverse prices (declared prices from valuation to source commodity, + o reverse prices (declared prices from valuation to source commodity, inverted) - o indirect prices (prices calculated from the shortest chain of - declared or reverse prices from source to valuation commodity). + o indirect prices (prices calculated from the shortest chain of de- + clared or reverse prices from source to valuation commodity). --value examples Here are the effects of --value as seen with print: @@ -837,7 +828,7 @@ 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 @@ -874,8 +865,8 @@ 2000/03/01 (a) 1 B - You may need to explicitly set a commodity's display style, when - reverse prices are used. Eg this output might be surprising: + You may need to explicitly set a commodity's display style, when re- + verse prices are used. Eg this output might be surprising: P 2000-01-01 A 2B @@ -910,9 +901,8 @@ Below is how --value affects each of hledger's reports, currently. You're not expected to remember all this, but when troubleshooting a report, look here. If you find problems - useless reports, misbehaving - reports, or error messages being printed - please report them (with - reproducible examples) eg at #329. - + reports, or error messages being printed - please report them (with re- + producible examples) eg at #329. Report type --value cost --value end --value DATE/now --------------------------------------------------------------------------------- @@ -920,40 +910,37 @@ posting cost, as market value at report market value at amounts recorded in end DATE transaction - balance show unvalued show unvalued show unvalued - asser- - tions/assign- - ments + balance as- show unvalued show unvalued show unvalued + sertions/as- + signments register - starting bal- cost of start- market value at day market value at - ance with -H ing balance before report start DATE + starting cost of start- market value at day be- market value at + balance with ing balance fore report start DATE + -H posting cost market value at report market value at amounts end DATE posting summarised market value each summary market value each - amounts, mul- cost posting at period end summary posting at - tiperiod DATE - running sum/average of sum/average of the dis- sum/average of the - total/average the displayed played values displayed values + amounts, cost posting at period end summary posting at + multiperiod DATE + running to- sum/average of sum/average of the dis- sum/average of the + tal/average the displayed played values displayed values values - balance (bs, + balance (bs, cf, is..) - - - - starting bal- costs of market value at day market value at - ances with -H starting bal- before report start of DATE of sum of - ances sum of previous postings previous postings - balances, summed costs market value at period market value at - simple bal- end of sum of postings DATE of sum of - ance report postings + starting costs of market value at day be- market value at + balances starting bal- fore report start of sum DATE of sum of + with -H ances of previous postings previous postings balances, summed costs market value at period market value at - multiperiod end of sum of postings DATE of sum of + simple bal- end of sum of postings DATE of sum of + ance report postings + balances, summed costs market value at period market value at + multiperiod end of sum of postings DATE of sum of report postings - budget costs of bud- budget-setting periodic budget-setting - amounts with get amounts txns are valued at period periodic txns are + budget costs of bud- budget-setting periodic budget-setting pe- + amounts with get amounts txns are valued at period riodic txns are --budget end valued at DATE - col- sum/average of market value at period market value at - umn/row/grand the displayed end of sum/average of DATE of sum/aver- + col- sum/average of market value at period market value at + umn/row/grand the displayed end of sum/average of DATE of sum/aver- totals/aver- values postings age of postings ages @@ -961,16 +948,16 @@ The rightmost of these flags wins. Output destination - Some commands (print, register, stats, the balance commands) can write - their output to a destination other than the console. This is con- + Some commands (print, register, stats, the balance commands) can write + their output to a destination other than the console. This is con- trolled by the -o/--output-file option. $ hledger balance -o - # write to stdout (the default) $ hledger balance -o FILE # write to FILE Output format - Some commands can write their output in other formats. Eg print and - register can output CSV, and the balance commands can output CSV or + Some commands can write their output in other formats. Eg print and + register can output CSV, and the balance commands can output CSV or HTML. This is controlled by the -O/--output-format option, or by spec- ifying a .csv or .html file extension with -o/--output-file. @@ -980,56 +967,56 @@ 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. In + hledger's regular expressions come from the regex-tdfa library. In general they: o are case insensitive - o are infix matching (do not need to match the entire thing being + o are infix matching (do not need to match the entire thing being matched) o are POSIX extended regular expressions o also support GNU word boundaries (\<, \>, \b, \B) - o and parenthesised capturing groups and numeric backreferences in - replacement strings + o and parenthesised capturing groups and numeric backreferences in re- + placement strings o do not support mode modifiers like (?s) 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. QUERIES - One of hledger's strengths is being able to quickly report on precise - subsets of your data. Most commands accept an optional query expres- - sion, written as arguments after the command name, to filter the data - by date, account name or other criteria. The syntax is similar to a + One of hledger's strengths is being able to quickly report on precise + subsets of your data. Most commands accept an optional query expres- + sion, written as arguments after the command name, to filter the data + by date, account name or other criteria. The syntax is similar to a web search: one or more space-separated search terms, quotes to enclose - whitespace, prefixes to match specific fields, a not: prefix to negate + whitespace, prefixes to match specific fields, a not: prefix to negate the match. - We do not yet support arbitrary boolean combinations of search terms; - instead most commands show transactions/postings/accounts which match + We do not yet support arbitrary boolean combinations of search terms; + instead most commands show transactions/postings/accounts which match (or negatively match): o any of the description terms AND @@ -1050,31 +1037,31 @@ o match all the other terms. - The following kinds of search terms can be used. Remember these can + The following kinds of search terms can be used. Remember these can also be prefixed with not:, eg to exclude a particular subaccount. REGEX, acct:REGEX - match account names by this regular expression. (With no pre- + match account names by this regular expression. (With no pre- fix, acct: is assumed.) same as above amt:N, amt:N, amt:>=N - match postings with a single-commodity amount that is equal to, - less than, or greater than N. (Multi-commodity amounts are not + match postings with a single-commodity amount that is equal to, + less than, or greater than N. (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. Otherwise, the absolute magnitudes are compared, + are compared. Otherwise, the absolute magnitudes are compared, ignoring sign. code:REGEX match by transaction code (eg check number) cur:REGEX - match postings or transactions including any amounts whose cur- - rency/commodity symbol is fully matched by REGEX. (For a par- + match postings or transactions including any amounts whose cur- + rency/commodity symbol is fully matched by REGEX. (For a par- tial match, use .*REGEX.*). Note, to match characters which are regex-significant, like the dollar sign ($), you need to prepend - \. And when using the command line you need to add one more - level of quoting to hide it from the shell, so eg do: hledger + \. And when using the command line you need to add one more + level of quoting to hide it from the shell, so eg do: hledger print cur:'\$' or hledger print cur:\\$. desc:REGEX @@ -1082,20 +1069,20 @@ date:PERIODEXPR match dates within the specified period. PERIODEXPR is a period - expression (with no report interval). Examples: date:2016, - date:thismonth, date:2000/2/1-2/15, date:lastweek-. If the - --date2 command line flag is present, this matches secondary + expression (with no report interval). Examples: date:2016, + date:thismonth, date:2000/2/1-2/15, date:lastweek-. If the + --date2 command line flag is present, this matches secondary dates instead. date2:PERIODEXPR match secondary dates within the specified period. depth:N - match (or display, depending on command) accounts at or above + match (or display, depending on command) accounts at or above this depth note:REGEX - match transaction notes (part of description right of |, or + match transaction notes (part of description right of |, or whole description when there's no |) payee:REGEX @@ -1109,51 +1096,51 @@ match unmarked, pending, or cleared transactions respectively tag:REGEX[=REGEX] - match by tag name, and optionally also by tag value. Note a - tag: query is considered to match a transaction if it matches - any of the postings. Also remember that postings inherit the + match by tag name, and optionally also by tag value. Note a + tag: query is considered to match a transaction if it matches + any of the postings. Also remember that postings inherit the tags of their parent transaction. The following special search term is used automatically in hledger-web, only: inacct:ACCTNAME - tells hledger-web to show the transaction register for this - account. Can be filtered further with acct etc. + tells hledger-web to show the transaction register for this ac- + count. Can be filtered further with acct etc. Some of these can also be expressed as command-line options (eg depth:2 - is equivalent to --depth 2). Generally you can mix options and query - arguments, and the resulting query will be their intersection (perhaps + is equivalent to --depth 2). Generally you can mix options and query + arguments, and the resulting query will be their intersection (perhaps excluding the -p/--period option). COMMANDS - hledger provides a number of subcommands; hledger with no arguments + hledger provides a number of subcommands; hledger with no arguments shows a list. If you install additional hledger-* packages, or if you put programs or - scripts named hledger-NAME in your PATH, these will also be listed as + scripts named hledger-NAME in your PATH, these will also be listed as subcommands. - Run a subcommand by writing its name as first argument (eg hledger - incomestatement). You can also write one of the standard short aliases - displayed in parentheses in the command list (hledger b), or any any + Run a subcommand by writing its name as first argument (eg hledger in- + comestatement). You can also write one of the standard short aliases + displayed in parentheses in the command list (hledger b), or any any unambiguous prefix of a command name (hledger inc). - Here are all the builtin commands in alphabetical order. See also - hledger for a more organised command list, and hledger CMD -h for - detailed command help. + Here are all the builtin commands in alphabetical order. See also + hledger for a more organised command list, and hledger CMD -h for de- + tailed command help. accounts accounts, a Show account names. - This command lists account names, either declared with account direc- - tives (--declared), posted to (--used), or both (the default). With - query arguments, only matched account names and account names refer- - enced by matched postings are shown. It shows a flat list by default. - With --tree, it uses indentation to show the account hierarchy. In - flat mode you can add --drop N to omit the first few account name com- - ponents. Account names can be depth-clipped with depth:N or --depth N + This command lists account names, either declared with account direc- + tives (--declared), posted to (--used), or both (the default). With + query arguments, only matched account names and account names refer- + enced by matched postings are shown. It shows a flat list by default. + With --tree, it uses indentation to show the account hierarchy. In + flat mode you can add --drop N to omit the first few account name com- + ponents. Account names can be depth-clipped with depth:N or --depth N or -N. Examples: @@ -1172,8 +1159,8 @@ activity Show an ascii barchart of posting counts per interval. - The activity command displays an ascii histogram showing transaction - counts by day, week, month or other reporting interval (by day is the + The activity command displays an ascii histogram showing transaction + counts by day, week, month or other reporting interval (by day is the default). With query arguments, it counts only matched transactions. Examples: @@ -1188,22 +1175,22 @@ add Prompt for transactions and add them to the journal. - Many hledger users edit their journals directly with a text editor, or - generate them from CSV. For more interactive data entry, there is the - add command, which prompts interactively on the console for new trans- + Many hledger users edit their journals directly with a text editor, or + generate them from CSV. For more interactive data entry, there is the + add command, which prompts interactively on the console for new trans- actions, and appends them to the journal file (if there are multiple -f - FILE options, the first file is used.) Existing transactions are not - changed. This is the only hledger command that writes to the journal + FILE options, the first file is used.) Existing transactions are not + changed. This is the only hledger command that writes to the journal file. To use it, just run hledger add and follow the prompts. You can add as - many transactions as you like; when you are finished, enter . or press + many transactions as you like; when you are finished, enter . or press control-d or control-c to exit. Features: - o add tries to provide useful defaults, using the most similar (by - description) recent transaction (filtered by the query, if any) as a + o add tries to provide useful defaults, using the most similar (by de- + scription) recent transaction (filtered by the query, if any) as a template. o You can also set the initial defaults with command line arguments. @@ -1211,20 +1198,20 @@ o Readline-style edit keys can be used during data entry. o The tab key will auto-complete whenever possible - accounts, descrip- - tions, dates (yesterday, today, tomorrow). If the input area is + tions, dates (yesterday, today, tomorrow). If the input area is empty, it will insert the default value. - o If the journal defines a default commodity, it will be added to any + o If the journal defines a default commodity, it will be added to any bare numbers entered. o A parenthesised transaction code may be entered following a date. o Comments and tags may be entered following a description or amount. - o If you make a mistake, enter < at any prompt to restart the transac- + o If you make a mistake, enter < at any prompt to restart the transac- tion. - o Input prompts are displayed in a different colour when the terminal + o Input prompts are displayed in a different colour when the terminal supports it. Example (see the tutorial for a detailed explanation): @@ -1254,8 +1241,8 @@ Starting the next transaction (. or ctrl-D/ctrl-C to quit) Date [2015/05/22]: $ - On Microsoft Windows, the add command makes sure that no part of the - file path ends with a period, as it can cause data loss on that plat- + On Microsoft Windows, the add command makes sure that no part of the + file path ends with a period, as it can cause data loss on that plat- form (cf #1056). balance @@ -1263,29 +1250,29 @@ Show accounts and their balances. The balance command is hledger's most versatile command. Note, despite - the name, it is not always used for showing real-world account bal- - ances; the more accounting-aware balancesheet and incomestatement may + the name, it is not always used for showing real-world account bal- + ances; the more accounting-aware balancesheet and incomestatement may be more convenient for that. By default, it displays all accounts, and each account's change in bal- ance during the entire period of the journal. Balance changes are cal- - culated by adding up the postings in each account. You can limit the - postings matched, by a query, to see fewer accounts, changes over a + culated by adding up the postings in each account. You can limit the + postings matched, by a query, to see fewer accounts, changes over a different time period, changes from only cleared transactions, etc. If you include an account's complete history of postings in the report, - the balance change is equivalent to the account's current ending bal- - ance. For a real-world account, typically you won't have all transac- + the balance change is equivalent to the account's current ending bal- + ance. For a real-world account, typically you won't have all transac- tions in the journal; instead you'll have all transactions after a cer- - tain date, and an "opening balances" transaction setting the correct - starting balance on that date. Then the balance command will show + tain date, and an "opening balances" transaction setting the correct + starting balance on that date. Then the balance command will show real-world account balances. In some cases the -H/--historical flag is used to ensure this (more below). The balance command can produce several styles of report: Classic balance report - This is the original balance report, as found in Ledger. It usually + This is the original balance report, as found in Ledger. It usually looks like this: $ hledger balance @@ -1302,23 +1289,23 @@ -------------------- 0 - By default, accounts are displayed hierarchically, with subaccounts - indented below their parent. At each level of the tree, accounts are - sorted by account code if any, then by account name. Or with + By default, accounts are displayed hierarchically, with subaccounts in- + dented below their parent. At each level of the tree, accounts are + sorted by account code if any, then by account name. Or with -S/--sort-amount, by their balance amount. "Boring" accounts, which contain a single interesting subaccount and no - balance of their own, are elided into the following line for more com- - pact output. (Eg above, the "liabilities" account.) Use --no-elide to + balance of their own, are elided into the following line for more com- + pact output. (Eg above, the "liabilities" account.) Use --no-elide to prevent this. - Account balances are "inclusive" - they include the balances of any + Account balances are "inclusive" - they include the balances of any subaccounts. - Accounts which have zero balance (and no non-zero subaccounts) are + Accounts which have zero balance (and no non-zero subaccounts) are omitted. Use -E/--empty to show them. - A final total is displayed by default; use -N/--no-total to suppress + A final total is displayed by default; use -N/--no-total to suppress it, eg: $ hledger balance -p 2008/6 expenses --no-total @@ -1327,7 +1314,7 @@ $1 supplies Customising the classic balance report - You can customise the layout of classic balance reports with --format + You can customise the layout of classic balance reports with --format FMT: $ hledger balance --format "%20(account) %12(total)" @@ -1345,7 +1332,7 @@ 0 The FMT format string (plus a newline) specifies the formatting applied - to each account/balance pair. It may contain any suitable text, with + to each account/balance pair. It may contain any suitable text, with data fields interpolated like so: %[MIN][.MAX](FIELDNAME) @@ -1356,14 +1343,14 @@ o FIELDNAME must be enclosed in parentheses, and can be one of: - o depth_spacer - a number of spaces equal to the account's depth, or + o depth_spacer - a number of spaces equal to the account's depth, or if MIN is specified, MIN * depth spaces. o account - the account's name o total - the account's balance/posted total, right justified - Also, FMT can begin with an optional prefix to control how multi-com- + Also, FMT can begin with an optional prefix to control how multi-com- modity amounts are rendered: o %_ - render on multiple lines, bottom-aligned (the default) @@ -1372,22 +1359,22 @@ o %, - render on one line, comma-separated - There are some quirks. Eg in one-line mode, %(depth_spacer) has no - effect, instead %(account) has indentation built in. Experimentation - may be needed to get pleasing results. + There are some quirks. Eg in one-line mode, %(depth_spacer) has no ef- + fect, instead %(account) has indentation built in. Experimentation may + be needed to get pleasing results. Some example formats: o %(total) - the account's total - o %-20.20(account) - the account's name, left justified, padded to 20 + o %-20.20(account) - the account's name, left justified, padded to 20 characters and clipped at 20 characters - o %,%-50(account) %25(total) - account name padded to 50 characters, - total padded to 20 characters, with multiple commodities rendered on + o %,%-50(account) %25(total) - account name padded to 50 characters, + total padded to 20 characters, with multiple commodities rendered on one line - o %20(total) %2(depth_spacer)%-(account) - the default format for the + o %20(total) %2(depth_spacer)%-(account) - the default format for the single-column balance report Colour support @@ -1398,9 +1385,9 @@ o the output is not being redirected or piped anywhere Flat mode - To see a flat list instead of the default hierarchical display, use - --flat. In this mode, accounts (unless depth-clipped) show their full - names and "exclusive" balance, excluding any subaccount balances. In + To see a flat list instead of the default hierarchical display, use + --flat. In this mode, accounts (unless depth-clipped) show their full + names and "exclusive" balance, excluding any subaccount balances. In this mode, you can also use --drop N to omit the first few account name components. @@ -1409,8 +1396,8 @@ $1 supplies Depth limited balance reports - With --depth N or depth:N or just -N, balance reports show accounts - only to the specified numeric depth. This is very useful to summarise + With --depth N or depth:N or just -N, balance reports show accounts + only to the specified numeric depth. This is very useful to summarise a complex set of accounts and get an overview. $ hledger balance -N -1 @@ -1423,17 +1410,17 @@ inclusive balances at the depth limit. Multicolumn balance report - Multicolumn or tabular balance reports are a very useful hledger fea- - ture, and usually the preferred style. They share many of the above - features, but they show the report as a table, with columns represent- - ing time periods. This mode is activated by providing a reporting - interval. + Multicolumn or tabular balance reports are a very useful hledger fea- + ture, and usually the preferred style. They share many of the above + features, but they show the report as a table, with columns represent- + ing time periods. This mode is activated by providing a reporting in- + terval. - There are three types of multicolumn balance report, showing different + There are three types of multicolumn balance report, showing different information: 1. By default: each column shows the sum of postings in that period, ie - the account's change of balance in that period. This is useful eg + the account's change of balance in that period. This is useful eg for a monthly income statement: $ hledger balance --quarterly income expenses -E @@ -1448,8 +1435,8 @@ -------------------++--------------------------------- || $-1 $1 0 0 - 2. With --cumulative: each column shows the ending balance for that - period, accumulating the changes across periods, starting from 0 at + 2. With --cumulative: each column shows the ending balance for that pe- + riod, accumulating the changes across periods, starting from 0 at the report start date: $ hledger balance --quarterly income expenses -E --cumulative @@ -1465,8 +1452,8 @@ || $-1 0 0 0 3. With --historical/-H: each column shows the actual historical ending - balance for that period, accumulating the changes across periods, - starting from the actual balance at the report start date. This is + balance for that period, accumulating the changes across periods, + starting from the actual balance at the report start date. This is useful eg for a multi-period balance sheet, and when you are showing only the data after a certain start date: @@ -1485,26 +1472,26 @@ Note that --cumulative or --historical/-H disable --row-total/-T, since summing end balances generally does not make sense. - Multicolumn balance reports display accounts in flat mode by default; + Multicolumn balance reports display accounts in flat mode by default; to see the hierarchy, use --tree. - With a reporting interval (like --quarterly above), the report - start/end dates will be adjusted if necessary so that they encompass + With a reporting interval (like --quarterly above), the report + start/end dates will be adjusted if necessary so that they encompass the displayed report periods. This is so that the first and last peri- ods will be "full" and comparable to the others. - The -E/--empty flag does two things in multicolumn balance reports: - first, the report will show all columns within the specified report - period (without -E, leading and trailing columns with all zeroes are - not shown). Second, all accounts which existed at the report start - date will be considered, not just the ones with activity during the - report period (use -E to include low-activity accounts which would oth- - erwise would be omitted). + The -E/--empty flag does two things in multicolumn balance reports: + first, the report will show all columns within the specified report pe- + riod (without -E, leading and trailing columns with all zeroes are not + shown). Second, all accounts which existed at the report start date + will be considered, not just the ones with activity during the report + period (use -E to include low-activity accounts which would otherwise + would be omitted). The -T/--row-total flag adds an additional column showing the total for each row. - The -A/--average flag adds a column showing the average value in each + The -A/--average flag adds a column showing the average value in each row. Here's an example of all three: @@ -1528,21 +1515,21 @@ Limitations: In multicolumn reports the -V/--value flag uses the market price on the - report end date, for all columns (not the price on each column's end + report end date, for all columns (not the price on each column's end date). - Eliding of boring parent accounts in tree mode, as in the classic bal- + Eliding of boring parent accounts in tree mode, as in the classic bal- ance report, is not yet supported in multicolumn reports. Budget report - With --budget, extra columns are displayed showing budget goals for - each account and period, if any. Budget goals are defined by periodic - transactions. This is very useful for comparing planned and actual - income, expenses, time usage, etc. --budget is most often combined - with a report interval. + With --budget, extra columns are displayed showing budget goals for + each account and period, if any. Budget goals are defined by periodic + transactions. This is very useful for comparing planned and actual in- + come, expenses, time usage, etc. --budget is most often combined with + a report interval. - For example, you can take average monthly expenses in the common - expense categories to construct a minimal monthly budget: + For example, you can take average monthly expenses in the common ex- + pense categories to construct a minimal monthly budget: ;; Budget ~ monthly @@ -1588,25 +1575,25 @@ Note this is different from a normal balance report in several ways: - o Only accounts with budget goals during the report period are shown, + o Only accounts with budget goals during the report period are shown, by default. - o In each column, in square brackets after the actual amount, budgeted + o In each column, in square brackets after the actual amount, budgeted amounts are shown, along with the percentage of budget used. - o All parent accounts are always shown, even in flat mode. Eg assets, + o All parent accounts are always shown, even in flat mode. Eg assets, assets:bank, and expenses above. - o Amounts always include all subaccounts, budgeted or unbudgeted, even + o Amounts always include all subaccounts, budgeted or unbudgeted, even in flat mode. This means that the numbers displayed will not always add up! Eg above, - the expenses actual amount includes the gifts and supplies transac- - tions, but the expenses:gifts and expenses:supplies accounts are not + the expenses actual amount includes the gifts and supplies transac- + tions, but the expenses:gifts and expenses:supplies accounts are not shown, as they have no budget amounts declared. - This can be confusing. When you need to make things clearer, use the - -E/--empty flag, which will reveal all accounts including unbudgeted + This can be confusing. When you need to make things clearer, use the + -E/--empty flag, which will reveal all accounts including unbudgeted ones, giving the full picture. Eg: $ hledger balance -M --budget --empty @@ -1648,12 +1635,12 @@ For more examples, see Budgeting and Forecasting. Nested budgets - You can add budgets to any account in your account hierarchy. If you + You can add budgets to any account in your account hierarchy. If you have budgets on both parent account and some of its children, then bud- - get(s) of the child account(s) would be added to the budget of their + get(s) of the child account(s) would be added to the budget of their parent, much like account balances behave. - In the most simple case this means that once you add a budget to any + In the most simple case this means that once you add a budget to any account, all its parents would have budget as well. To illustrate this, consider the following budget: @@ -1663,14 +1650,14 @@ expenses:personal:electronics $100.00 liabilities - With this, monthly budget for electronics is defined to be $100 and - budget for personal expenses is an additional $1000, which implicity + With this, monthly budget for electronics is defined to be $100 and + budget for personal expenses is an additional $1000, which implicity means that budget for both expenses:personal and expenses is $1100. - Transactions in expenses:personal:electronics will be counted both - towards its $100 budget and $1100 of expenses:personal , and transac- - tions in any other subaccount of expenses:personal would be counted - towards only towards the budget of expenses:personal. + Transactions in expenses:personal:electronics will be counted both to- + wards its $100 budget and $1100 of expenses:personal , and transactions + in any other subaccount of expenses:personal would be counted towards + only towards the budget of expenses:personal. For example, let's consider these transactions: @@ -1695,9 +1682,9 @@ expenses:personal $30.00 liabilities - As you can see, we have transactions in expenses:personal:electron- - ics:upgrades and expenses:personal:train tickets, and since both of - these accounts are without explicitly defined budget, these transac- + As you can see, we have transactions in expenses:personal:electron- + ics:upgrades and expenses:personal:train tickets, and since both of + these accounts are without explicitly defined budget, these transac- tions would be counted towards budgets of expenses:personal:electronics and expenses:personal accordingly: @@ -1713,7 +1700,7 @@ -------------------------------++------------------------------- || 0 [ 0] - And with --empty, we can get a better picture of budget allocation and + And with --empty, we can get a better picture of budget allocation and consumption: $ hledger balance --budget -M --empty @@ -1731,17 +1718,17 @@ || 0 [ 0] Output format - The balance command supports output destination and output format - selection. + The balance command supports output destination and output format se- + lection. balancesheet balancesheet, bs This command displays a simple balance sheet, showing historical ending - balances of asset and liability accounts (ignoring any report begin - date). It assumes that these accounts are under a top-level asset or + balances of asset and liability accounts (ignoring any report begin + date). It assumes that these accounts are under a top-level asset or liability account (case insensitive, plural forms also allowed). - Note this report shows all account balances with normal positive sign + Note this report shows all account balances with normal positive sign (like conventional financial statements, unlike balance/print/register) (experimental). @@ -1767,19 +1754,19 @@ 0 With a reporting interval, multiple columns will be shown, one for each - report period. As with multicolumn balance reports, you can alter the - report mode with --change/--cumulative/--historical. Normally bal- - ancesheet shows historical ending balances, which is what you need for - a balance sheet; note this means it ignores report begin dates (and - -T/--row-total, since summing end balances generally does not make + report period. As with multicolumn balance reports, you can alter the + report mode with --change/--cumulative/--historical. Normally bal- + ancesheet shows historical ending balances, which is what you need for + a balance sheet; note this means it ignores report begin dates (and + -T/--row-total, since summing end balances generally does not make sense). - This command also supports output destination and output format selec- + This command also supports output destination and output format selec- tion. balancesheetequity balancesheetequity, bse - Just like balancesheet, but also reports Equity (which it assumes is + Just like balancesheet, but also reports Equity (which it assumes is under a top-level equity account). Example: @@ -1810,10 +1797,10 @@ cashflow cashflow, cf - This command displays a simple cashflow statement, showing changes in - "cash" accounts. It assumes that these accounts are under a top-level - asset account (case insensitive, plural forms also allowed) and do not - contain receivable or A/R in their name. Note this report shows all + This command displays a simple cashflow statement, showing changes in + "cash" accounts. It assumes that these accounts are under a top-level + asset account (case insensitive, plural forms also allowed) and do not + contain receivable or A/R in their name. Note this report shows all account balances with normal positive sign (like conventional financial statements, unlike balance/print/register) (experimental). @@ -1834,81 +1821,81 @@ $-1 With a reporting interval, multiple columns will be shown, one for each - report period. Normally cashflow shows changes in assets per period, - though as with multicolumn balance reports you can alter the report + report period. Normally cashflow shows changes in assets per period, + though as with multicolumn balance reports you can alter the report mode with --change/--cumulative/--historical. - This command also supports output destination and output format selec- + This command also supports output destination and output format selec- tion. check-dates check-dates - Check that transactions are sorted by increasing date. With --date2, - checks secondary dates instead. With --strict, dates must also be - unique. With a query, only matched transactions' dates are checked. + Check that transactions are sorted by increasing date. With --date2, + checks secondary dates instead. With --strict, dates must also be + unique. With a query, only matched transactions' dates are checked. Reads the default journal file, or another specified with -f. check-dupes check-dupes - Reports account names having the same leaf but different prefixes. In - other words, two or more leaves that are categorized differently. + Reports account names having the same leaf but different prefixes. In + other words, two or more leaves that are categorized differently. Reads the default journal file, or another specified as an argument. An example: http://stefanorodighiero.net/software/hledger-dupes.html close close, equity - Prints a "closing balances" transaction and an "opening balances" + Prints a "closing balances" transaction and an "opening balances" transaction that bring account balances to and from zero, respectively. Useful for bringing asset/liability balances forward into a new journal - file, or for closing out revenues/expenses to retained earnings at the + file, or for closing out revenues/expenses to retained earnings at the end of a period. - The closing transaction transfers balances to "equity:closing bal- - ances". The opening transaction transfers balances from "equity:open- + The closing transaction transfers balances to "equity:closing bal- + ances". The opening transaction transfers balances from "equity:open- ing balances". You can choose to print just one of the transactions by using the --opening or --closing flag. If you split your journal files by time (eg yearly), you will typically - run this command at the end of the year, and save the closing transac- - tion as last entry of the old file, and the opening transaction as the - first entry of the new file. This makes the files self contained, so - that correct balances are reported no matter which of them are loaded. - Ie, if you load just one file, the balances are initialised correctly; - or if you load several files, the redundant closing/opening transac- - tions cancel each other out. (They will show up in print or register - reports; you can exclude them with a query like not:desc:'(open- + run this command at the end of the year, and save the closing transac- + tion as last entry of the old file, and the opening transaction as the + first entry of the new file. This makes the files self contained, so + that correct balances are reported no matter which of them are loaded. + Ie, if you load just one file, the balances are initialised correctly; + or if you load several files, the redundant closing/opening transac- + tions cancel each other out. (They will show up in print or register + reports; you can exclude them with a query like not:desc:'(open- ing|closing) balances'.) If you're running a business, you might also use this command to "close - the books" at the end of an accounting period, transferring income - statement account balances to retained earnings. (You may want to + the books" at the end of an accounting period, transferring income + statement account balances to retained earnings. (You may want to change the equity account name to something like "equity:retained earn- ings".) - By default, the closing transaction is dated yesterday, the balances - are calculated as of end of yesterday, and the opening transaction is - dated today. To close on some other date, use: hledger close -e OPEN- - INGDATE. Eg, to close/open on the 2018/2019 boundary, use -e 2019. + By default, the closing transaction is dated yesterday, the balances + are calculated as of end of yesterday, and the opening transaction is + dated today. To close on some other date, use: hledger close -e OPEN- + INGDATE. Eg, to close/open on the 2018/2019 boundary, use -e 2019. You can also use -p or date:PERIOD (any starting date is ignored). - Both transactions will include balance assertions for the - closed/reopened accounts. You probably shouldn't use status or real- - ness filters (like -C or -R or status:) with this command, or the gen- - erated balance assertions will depend on these flags. Likewise, if you - run this command with --auto, the balance assertions will probably - always require --auto. + Both transactions will include balance assertions for the closed/re- + opened accounts. You probably shouldn't use status or realness filters + (like -C or -R or status:) with this command, or the generated balance + assertions will depend on these flags. Likewise, if you run this com- + mand with --auto, the balance assertions will probably always require + --auto. - When account balances have cost information (transaction prices), the - closing/opening transactions will preserve it, so that eg balance -B + When account balances have cost information (transaction prices), the + closing/opening transactions will preserve it, so that eg balance -B reports will not be affected. Examples: - Carrying asset/liability balances into a new file for 2019, all from + Carrying asset/liability balances into a new file for 2019, all from command line: - Warning: we use >> here to append; be careful not to type a single > + Warning: we use >> here to append; be careful not to type a single > which would wipe your journal! $ hledger close -f 2018.journal -e 2019 assets liabilities --opening >>2019.journal @@ -1939,22 +1926,67 @@ liabilities:pending 5 = 0 assets:checking + commodities + commodities + List all commodity/currency symbols used or declared in the journal. + + descriptions + descriptions Show descriptions. + + This command lists all descriptions that appear in transactions. + + Examples: + + $ hledger descriptions + Store Name + Gas Station | Petrol + Person A + + diff + diff + Compares a particular account's transactions in two input files. It + shows any transactions to this account which are in one file but not in + the other. + + More precisely, for each posting affecting this account in either file, + it looks for a corresponding posting in the other file which posts the + same amount to the same account (ignoring date, description, etc.) + Since postings not transactions are compared, this also works when mul- + tiple bank transactions have been combined into a single journal entry. + + This is useful eg if you have downloaded an account's transactions from + your bank (eg as CSV data). When hledger and your bank disagree about + the account balance, you can compare the bank data with your journal to + find out the cause. + + Examples: + + $ hledger diff -f $LEDGER_FILE -f bank.csv assets:bank:giro + These transactions are in the first file only: + + 2014/01/01 Opening Balances + assets:bank:giro EUR ... + ... + equity:opening balances EUR -... + + These transactions are in the second file only: + files files List all files included in the journal. With a REGEX argument, only - file names matching the regular expression (case sensitive) are shown. + file names matching the regular expression (case sensitive) are shown. help help Show any of the hledger manuals. - The help command displays any of the main hledger manuals, in one of - several ways. Run it with no argument to list the manuals, or provide + The help command displays any of the main hledger manuals, in one of + several ways. Run it with no argument to list the manuals, or provide a full or partial manual name to select one. - hledger manuals are available in several formats. hledger help will - use the first of these display methods that it finds: info, man, - $PAGER, less, stdout (or when non-interactive, just stdout). You can + hledger manuals are available in several formats. hledger help will + use the first of these display methods that it finds: info, man, + $PAGER, less, stdout (or when non-interactive, just stdout). You can force a particular viewer with the --info, --man, --pager, --cat flags. Examples: @@ -2018,8 +2050,8 @@ expenses during a period. It assumes that these accounts are under a top-level revenue or income or expense account (case insensitive, plu- ral forms also allowed). Note this report shows all account balances - with normal positive sign (like conventional financial statements, - unlike balance/print/register) (experimental). + with normal positive sign (like conventional financial statements, un- + like balance/print/register) (experimental). This command displays a simple income statement. It currently assumes that you have top-level accounts named income (or revenue) and expense @@ -2054,25 +2086,47 @@ This command also supports output destination and output format selec- tion. + notes + notes Show notes. + + This command lists all notes that appear in transactions. + + Examples: + + $ hledger notes + Petrol + Snacks + + payees + payees Show payee names. + + This command lists all payee names that appear in transactions. + + Examples: + + $ hledger payees + Store Name + Gas Station + Person A + prices prices Print market price directives from the journal. With --costs, also - print synthetic market prices based on transaction prices. With - --inverted-costs, also print inverse prices based on transaction - prices. Prices (and postings providing prices) can be filtered by a - query. + print synthetic market prices based on transaction prices. With --in- + verted-costs, also print inverse prices based on transaction prices. + Prices (and postings providing prices) can be filtered by a query. print print, txns, p Show transaction journal entries, sorted by date. The print command displays full journal entries (transactions) from the - journal file in date order, tidily formatted. With --date2, transac- + journal file in date order, tidily formatted. With --date2, transac- tions are sorted by secondary date instead. print's output is always a valid hledger journal. - It preserves all transaction information, but it does not preserve - directives or inter-transaction comments + It preserves all transaction information, but it does not preserve di- + rectives or inter-transaction comments $ hledger print 2008/01/01 income @@ -2097,39 +2151,39 @@ assets:bank:checking $-1 Normally, the journal entry's explicit or implicit amount style is pre- - served. Ie when an amount is omitted in the journal, it will be omit- - ted in the output. You can use the -x/--explicit flag to make all + served. Ie when an amount is omitted in the journal, it will be omit- + ted in the output. You can use the -x/--explicit flag to make all amounts explicit, which can be useful for troubleshooting or for making your journal more readable and robust against data entry errors. Note, - -x will cause postings with a multi-commodity amount (these can arise - when a multi-commodity transaction has an implicit amount) will be - split into multiple single-commodity postings, for valid journal out- + -x will cause postings with a multi-commodity amount (these can arise + when a multi-commodity transaction has an implicit amount) will be + split into multiple single-commodity postings, for valid journal out- put. - With -B/--cost, amounts with transaction prices are converted to cost + With -B/--cost, amounts with transaction prices are converted to cost using that price. This can be used for troubleshooting. - With -m/--match and a STR argument, print will show at most one trans- - action: the one one whose description is most similar to STR, and is - most recent. STR should contain at least two characters. If there is + With -m/--match and a STR argument, print will show at most one trans- + action: the one one whose description is most similar to STR, and is + most recent. STR should contain at least two characters. If there is no similar-enough match, no transaction will be shown. With --new, for each FILE being read, hledger reads (and writes) a spe- - cial state file (.latest.FILE in the same directory), containing the - latest transaction date(s) that were seen last time FILE was read. - When this file is found, only transactions with newer dates (and new - transactions on the latest date) are printed. This is useful for - ignoring already-seen entries in import data, such as downloaded CSV + cial state file (.latest.FILE in the same directory), containing the + latest transaction date(s) that were seen last time FILE was read. + When this file is found, only transactions with newer dates (and new + transactions on the latest date) are printed. This is useful for ig- + noring already-seen entries in import data, such as downloaded CSV files. Eg: $ hledger -f bank1.csv print --new # shows transactions added since last print --new on this file - This assumes that transactions added to FILE always have same or - increasing dates, and that transactions on the same day do not get - reordered. See also the import command. + This assumes that transactions added to FILE always have same or in- + creasing dates, and that transactions on the same day do not get re- + ordered. See also the import command. - This command also supports output destination and output format selec- + This command also supports output destination and output format selec- tion. Here's an example of print's CSV output: $ hledger print -Ocsv @@ -2146,20 +2200,20 @@ "5","2008/12/31","","*","","pay off","","liabilities:debts","1","$","","1","","" "5","2008/12/31","","*","","pay off","","assets:bank:checking","-1","$","1","","","" - o There is one CSV record per posting, with the parent transaction's + o There is one CSV record per posting, with the parent transaction's fields repeated. o The "txnidx" (transaction index) field shows which postings belong to - the same transaction. (This number might change if transactions are - reordered within the file, files are parsed/included in a different + the same transaction. (This number might change if transactions are + reordered within the file, files are parsed/included in a different order, etc.) - o The amount is separated into "commodity" (the symbol) and "amount" + o The amount is separated into "commodity" (the symbol) and "amount" (numeric quantity) fields. o The numeric amount is repeated in either the "credit" or "debit" col- - umn, for convenience. (Those names are not accurate in the account- - ing sense; it just puts negative amounts under credit and zero or + umn, for convenience. (Those names are not accurate in the account- + ing sense; it just puts negative amounts under credit and zero or greater amounts under debit.) print-unique @@ -2183,7 +2237,7 @@ Show postings and their running total. The register command displays postings in date order, one per line, and - their running total. This is typically used with a query selecting a + their running total. This is typically used with a query selecting a particular account, to see that account's activity: $ hledger register checking @@ -2194,8 +2248,8 @@ With --date2, it shows and sorts by secondary date instead. - The --historical/-H flag adds the balance from any undisplayed prior - postings to the running total. This is useful when you want to see + The --historical/-H flag adds the balance from any undisplayed prior + postings to the running total. This is useful when you want to see only recent activity, with a historically accurate running balance: $ hledger register checking -b 2008/6 --historical @@ -2205,30 +2259,30 @@ The --depth option limits the amount of sub-account detail displayed. - The --average/-A flag shows the running average posting amount instead + The --average/-A flag shows the running average posting amount instead of the running total (so, the final number displayed is the average for - the whole report period). This flag implies --empty (see below). It - is affected by --historical. It works best when showing just one - account and one commodity. + the whole report period). This flag implies --empty (see below). It + is affected by --historical. It works best when showing just one ac- + count and one commodity. - The --related/-r flag shows the other postings in the transactions of + The --related/-r flag shows the other postings in the transactions of the postings which would normally be shown. - The --invert flag negates all amounts. For example, it can be used on + The --invert flag negates all amounts. For example, it can be used on an income account where amounts are normally displayed as negative num- - bers. It's also useful to show postings on the checking account - together with the related account: + bers. It's also useful to show postings on the checking account to- + gether with the related account: $ hledger register --related --invert assets:checking - With a reporting interval, register shows summary postings, one per - interval, aggregating the postings to each account: + With a reporting interval, register shows summary postings, one per in- + terval, aggregating the postings to each account: $ hledger register --monthly income 2008/01 income:salary $-1 $-1 2008/06 income:gifts $-1 $-2 - Periods with no activity, and summary postings with a zero amount, are + Periods with no activity, and summary postings with a zero amount, are not shown by default; use the --empty/-E flag to see them: $ hledger register --monthly income -E @@ -2245,28 +2299,28 @@ 2008/11 0 $-2 2008/12 0 $-2 - Often, you'll want to see just one line per interval. The --depth - option helps with this, causing subaccounts to be aggregated: + Often, you'll want to see just one line per interval. The --depth op- + tion helps with this, causing subaccounts to be aggregated: $ hledger register --monthly assets --depth 1h 2008/01 assets $1 $1 2008/06 assets $-1 0 2008/12 assets $-1 $-1 - Note when using report intervals, if you specify start/end dates these - will be adjusted outward if necessary to contain a whole number of - intervals. This ensures that the first and last intervals are full + Note when using report intervals, if you specify start/end dates these + will be adjusted outward if necessary to contain a whole number of in- + tervals. This ensures that the first and last intervals are full length and comparable to the others in the report. Custom register output - register uses the full terminal width by default, except on windows. - You can override this by setting the COLUMNS environment variable (not + register uses the full terminal width by default, except on windows. + You can override this by setting the COLUMNS environment variable (not a bash shell variable) or by using the --width/-w option. - The description and account columns normally share the space equally - (about half of (width - 40) each). You can adjust this by adding a - description width as part of --width's argument, comma-separated: - --width W,D . Here's a diagram (won't display correctly in --help): + The description and account columns normally share the space equally + (about half of (width - 40) each). You can adjust this by adding a de- + scription width as part of --width's argument, comma-separated: --width + W,D . Here's a diagram (won't display correctly in --help): <--------------------------------- width (W) ----------------------------------> date (10) description (D) account (W-41-D) amount (12) balance (12) @@ -2281,27 +2335,27 @@ $ hledger reg -w 100,40 # set overall width 100, description width 40 $ hledger reg -w $COLUMNS,40 # use terminal width, & description width 40 - This command also supports output destination and output format selec- + This command also supports output destination and output format selec- tion. register-match register-match Print the one posting whose transaction description is closest to DESC, - in the style of the register command. If there are multiple equally - good matches, it shows the most recent. Query options (options, not - arguments) can be used to restrict the search space. Helps ledger- - autosync detect already-seen transactions when importing. + in the style of the register command. If there are multiple equally + good matches, it shows the most recent. Query options (options, not + arguments) can be used to restrict the search space. Helps ledger-au- + tosync detect already-seen transactions when importing. rewrite rewrite Print all transactions, rewriting the postings of matched transactions. - For now the only rewrite available is adding new postings, like print + For now the only rewrite available is adding new postings, like print --auto. This is a start at a generic rewriter of transaction entries. It reads - the default journal and prints the transactions, like print, but adds + the default journal and prints the transactions, like print, but adds one or more specified postings to any transactions matching QUERY. The - posting amounts can be fixed, or a multiplier of the existing transac- + posting amounts can be fixed, or a multiplier of the existing transac- tion's first posting amount. Examples: @@ -2317,7 +2371,7 @@ (reserve:grocery) *0.25 ; reserve 25% for grocery (reserve:) *0.25 ; reserve 25% for grocery - Note the single quotes to protect the dollar sign from bash, and the + Note the single quotes to protect the dollar sign from bash, and the two spaces between account and amount. More: @@ -2327,16 +2381,16 @@ $ hledger rewrite -- expenses:gifts --add-posting '(budget:gifts) *-1"' $ hledger rewrite -- ^income --add-posting '(budget:foreign currency) *0.25 JPY; diversify' - Argument for --add-posting option is a usual posting of transaction - with an exception for amount specification. More precisely, you can + Argument for --add-posting option is a usual posting of transaction + with an exception for amount specification. More precisely, you can use '*' (star symbol) before the amount to indicate that that this is a - factor for an amount of original matched posting. If the amount - includes a commodity name, the new posting amount will be in the new - commodity; otherwise, it will be in the matched posting amount's com- - modity. + factor for an amount of original matched posting. If the amount in- + cludes a commodity name, the new posting amount will be in the new com- + modity; otherwise, it will be in the matched posting amount's commod- + ity. Re-write rules in a file - During the run this tool will execute so called "Automated Transac- + During the run this tool will execute so called "Automated Transac- tions" found in any journal it process. I.e instead of specifying this operations in command line you can put them in a journal file. @@ -2351,7 +2405,7 @@ budget:gifts *-1 assets:budget *1 - Note that '=' (equality symbol) that is used instead of date in trans- + Note that '=' (equality symbol) that is used instead of date in trans- actions you usually write. It indicates the query by which you want to match the posting to add new ones. @@ -2364,12 +2418,12 @@ --add-posting 'assets:budget *1' \ > rewritten-tidy-output.journal - It is important to understand that relative order of such entries in - journal is important. You can re-use result of previously added post- + It is important to understand that relative order of such entries in + journal is important. You can re-use result of previously added post- ings. Diff output format - To use this tool for batch modification of your journal files you may + To use this tool for batch modification of your journal files you may find useful output in form of unified diff. $ hledger rewrite -- --diff -f examples/sample.journal '^income' --add-posting '(liabilities:tax) *.33' @@ -2393,10 +2447,10 @@ If you'll pass this through patch tool you'll get transactions contain- ing the posting that matches your query be updated. Note that multiple - files might be update according to list of input files specified via + files might be update according to list of input files specified via --file options and include directives inside of these files. - Be careful. Whole transaction being re-formatted in a style of output + Be careful. Whole transaction being re-formatted in a style of output from hledger print. See also: @@ -2404,14 +2458,14 @@ https://github.com/simonmichael/hledger/issues/99 rewrite vs. print --auto - This command predates print --auto, and currently does much the same + This command predates print --auto, and currently does much the same thing, but with these differences: - o with multiple files, rewrite lets rules in any file affect all other - files. print --auto uses standard directive scoping; rules affect + o with multiple files, rewrite lets rules in any file affect all other + files. print --auto uses standard directive scoping; rules affect only child files. - o rewrite's query limits which transactions can be rewritten; all are + o rewrite's query limits which transactions can be rewritten; all are printed. print --auto's query limits which transactions are printed. o rewrite applies rules specified on command line or in the journal. @@ -2431,9 +2485,9 @@ originating from unrealized profit and loss account(s) are assumed to be your investments or withdrawals. - At a minimum, you need to supply a query (which could be just an - account name) to select your investments with --inv, and another query - to identify your profit and loss transactions with --pnl. + At a minimum, you need to supply a query (which could be just an ac- + count name) to select your investments with --inv, and another query to + identify your profit and loss transactions with --pnl. It will compute and display the internalized rate of return (IRR) and time-weighted rate of return (TWR) for your investments for the time @@ -2471,8 +2525,8 @@ List all the tag names used in the journal. With a TAGREGEX argument, only tag names matching the regular expression (case insensitive) are shown. With QUERY arguments, only transactions matching the query are - considered. With --values flag, the tags' unique values are listed - instead. + considered. With --values flag, the tags' unique values are listed in- + stead. test test @@ -2491,8 +2545,8 @@ none of them). This is mainly used by developers, but it's nice to be able to sanity- - check your installed hledger executable at any time. All tests are - expected to pass - if you ever see otherwise, something has gone wrong, + check your installed hledger executable at any time. All tests are ex- + pected to pass - if you ever see otherwise, something has gone wrong, please report a bug! ADD-ON COMMANDS @@ -2551,8 +2605,8 @@ ing to various schemes. irr - hledger-irr calculates the internal rate of return of an investment - account, but it's superseded now by the built-in roi command. + hledger-irr calculates the internal rate of return of an investment ac- + count, but it's superseded now by the built-in roi command. Experimental add-ons These are available in source form in the hledger repo's bin/ direc- @@ -2610,8 +2664,8 @@ Ledger. TROUBLESHOOTING - Here are some issues you might encounter when you run hledger (and - remember you can also seek help from the IRC channel, mail list or bug + Here are some issues you might encounter when you run hledger (and re- + member you can also seek help from the IRC channel, mail list or bug tracker): Successfully installed, but "No command 'hledger' found" @@ -2620,16 +2674,16 @@ that is ~/.local/bin and ~/.cabal/bin respectively. I set a custom LEDGER_FILE, but hledger is still using the default file - LEDGER_FILE should be a real environment variable, not just a shell - variable. The command env | grep LEDGER_FILE should show it. You may + LEDGER_FILE should be a real environment variable, not just a shell + variable. The command env | grep LEDGER_FILE should show it. You may need to use export. Here's an explanation. - "Illegal byte sequence" or "Invalid or incomplete multibyte or wide + "Illegal byte sequence" or "Invalid or incomplete multibyte or wide character" errors In order to handle non-ascii letters and symbols (like ), hledger needs an appropriate locale. This is usually configured system-wide; you can also configure it temporarily. The locale may need to be one that sup- - ports UTF-8, if you built hledger with GHC < 7.2 (or possibly always, + ports UTF-8, if you built hledger with GHC < 7.2 (or possibly always, I'm not sure yet). Here's an example of setting the locale temporarily, on ubuntu @@ -2648,7 +2702,7 @@ $ echo "export LANG=en_US.UTF-8" >>~/.bash_profile $ bash --login - If we preferred to use eg fr_FR.utf8, we might have to install that + If we preferred to use eg fr_FR.utf8, we might have to install that first: $ apt-get install language-pack-fr @@ -2669,7 +2723,7 @@ 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) @@ -2683,7 +2737,7 @@ SEE ALSO - hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1), + hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1), hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_time- dot(5), ledger(1)