diff --git a/hledger-lib/.date.m4 b/hledger-lib/.date.m4 index 89541032f3d..54ea9b97733 100644 --- a/hledger-lib/.date.m4 +++ b/hledger-lib/.date.m4 @@ -1,2 +1,2 @@ m4_dnl Date to show in man pages. Updated by "Shake manuals" -m4_define({{_monthyear_}}, {{February 2024}})m4_dnl +m4_define({{_monthyear_}}, {{March 2024}})m4_dnl diff --git a/hledger-ui/.date.m4 b/hledger-ui/.date.m4 index 89541032f3d..54ea9b97733 100644 --- a/hledger-ui/.date.m4 +++ b/hledger-ui/.date.m4 @@ -1,2 +1,2 @@ m4_dnl Date to show in man pages. Updated by "Shake manuals" -m4_define({{_monthyear_}}, {{February 2024}})m4_dnl +m4_define({{_monthyear_}}, {{March 2024}})m4_dnl diff --git a/hledger-ui/hledger-ui.1 b/hledger-ui/hledger-ui.1 index 378bc5c3ff6..510dfb1275b 100644 --- a/hledger-ui/hledger-ui.1 +++ b/hledger-ui/hledger-ui.1 @@ -1,5 +1,5 @@ -.TH "HLEDGER\-UI" "1" "February 2024" "hledger-ui-1.32.99 " "hledger User Manuals" +.TH "HLEDGER\-UI" "1" "March 2024" "hledger-ui-1.32.99 " "hledger User Manuals" diff --git a/hledger-ui/hledger-ui.txt b/hledger-ui/hledger-ui.txt index b0b25f907e0..1834fb34c02 100644 --- a/hledger-ui/hledger-ui.txt +++ b/hledger-ui/hledger-ui.txt @@ -535,4 +535,4 @@ LICENSE SEE ALSO hledger(1), hledger-ui(1), hledger-web(1), ledger(1) -hledger-ui-1.32.99 February 2024 HLEDGER-UI(1) +hledger-ui-1.32.99 March 2024 HLEDGER-UI(1) diff --git a/hledger-web/.date.m4 b/hledger-web/.date.m4 index 89541032f3d..54ea9b97733 100644 --- a/hledger-web/.date.m4 +++ b/hledger-web/.date.m4 @@ -1,2 +1,2 @@ m4_dnl Date to show in man pages. Updated by "Shake manuals" -m4_define({{_monthyear_}}, {{February 2024}})m4_dnl +m4_define({{_monthyear_}}, {{March 2024}})m4_dnl diff --git a/hledger-web/hledger-web.1 b/hledger-web/hledger-web.1 index c6369a6fb88..17312e0e878 100644 --- a/hledger-web/hledger-web.1 +++ b/hledger-web/hledger-web.1 @@ -1,5 +1,5 @@ -.TH "HLEDGER\-WEB" "1" "February 2024" "hledger-web-1.32.99 " "hledger User Manuals" +.TH "HLEDGER\-WEB" "1" "March 2024" "hledger-web-1.32.99 " "hledger User Manuals" @@ -128,6 +128,15 @@ hledger\-web also supports many of hledger\[aq]s general options. Query options and arguments may be used to set an initial filter, which although not shown in the UI, will restrict the data shown, in addition to any search query entered in the UI. +.PP +Note that hledger\-web shows accounts with zero balances by default, +like \f[CR]hledger\-ui\f[R] (and unlike \f[CR]hledger\f[R]). +Using the \f[CR]\-E/\-\-empty\f[R] flag at startup will hide them. +.PP +If you see accounts which appear to have a zero balance, but cannot be +hidden with \f[CR]\-E\f[R]: these have a mixed\-cost balance which looks +like zero when costs are hidden. +Currently hledger\-web does not show costs at all. .SS General help options .TP \f[CR]\-h \-\-help\f[R] diff --git a/hledger-web/hledger-web.info b/hledger-web/hledger-web.info index 2a7390066c7..016b948f283 100644 --- a/hledger-web/hledger-web.info +++ b/hledger-web/hledger-web.info @@ -142,6 +142,15 @@ options and arguments may be used to set an initial filter, which although not shown in the UI, will restrict the data shown, in addition to any search query entered in the UI. + Note that hledger-web shows accounts with zero balances by default, +like 'hledger-ui' (and unlike 'hledger'). Using the '-E/--empty' flag +at startup will hide them. + + If you see accounts which appear to have a zero balance, but cannot +be hidden with '-E': these have a mixed-cost balance which looks like +zero when costs are hidden. Currently hledger-web does not show costs +at all. + * Menu: * General help options:: @@ -631,28 +640,28 @@ Tag Table: Node: Top223 Node: OPTIONS2578 Ref: #options2683 -Node: General help options5257 -Ref: #general-help-options5407 -Node: General input options5689 -Ref: #general-input-options5875 -Node: General reporting options6532 -Ref: #general-reporting-options6697 -Node: PERMISSIONS10087 -Ref: #permissions10226 -Node: EDITING UPLOADING DOWNLOADING11438 -Ref: #editing-uploading-downloading11619 -Node: RELOADING12453 -Ref: #reloading12587 -Node: JSON API13020 -Ref: #json-api13135 -Node: DEBUG OUTPUT18623 -Ref: #debug-output18748 -Node: Debug output18775 -Ref: #debug-output-118876 -Node: ENVIRONMENT19293 -Ref: #environment19412 -Node: BUGS19529 -Ref: #bugs19613 +Node: General help options5648 +Ref: #general-help-options5798 +Node: General input options6080 +Ref: #general-input-options6266 +Node: General reporting options6923 +Ref: #general-reporting-options7088 +Node: PERMISSIONS10478 +Ref: #permissions10617 +Node: EDITING UPLOADING DOWNLOADING11829 +Ref: #editing-uploading-downloading12010 +Node: RELOADING12844 +Ref: #reloading12978 +Node: JSON API13411 +Ref: #json-api13526 +Node: DEBUG OUTPUT19014 +Ref: #debug-output19139 +Node: Debug output19166 +Ref: #debug-output-119267 +Node: ENVIRONMENT19684 +Ref: #environment19803 +Node: BUGS19920 +Ref: #bugs20004  End Tag Table diff --git a/hledger-web/hledger-web.txt b/hledger-web/hledger-web.txt index 7001d2f2bb8..043bf1844ac 100644 --- a/hledger-web/hledger-web.txt +++ b/hledger-web/hledger-web.txt @@ -113,6 +113,15 @@ OPTIONS though not shown in the UI, will restrict the data shown, in addition to any search query entered in the UI. + Note that hledger-web shows accounts with zero balances by default, + like hledger-ui (and unlike hledger). Using the -E/--empty flag at + startup will hide them. + + If you see accounts which appear to have a zero balance, but cannot be + hidden with -E: these have a mixed-cost balance which looks like zero + when costs are hidden. Currently hledger-web does not show costs at + all. + General help options -h --help show general or COMMAND help @@ -133,7 +142,7 @@ OPTIONS $LEDGER_FILE or $HOME/.hledger.journal) --rules-file=RULESFILE - Conversion rules file to use when reading CSV (default: + Conversion rules file to use when reading CSV (default: FILE.rules) --separator=CHAR @@ -150,7 +159,7 @@ OPTIONS assignments) -s --strict - do extra error checking (check that all posted accounts are de- + do extra error checking (check that all posted accounts are de- clared) General reporting options @@ -178,7 +187,7 @@ OPTIONS multiperiod/multicolumn report by year -p --period=PERIODEXP - set start date, end date, and/or reporting interval all at once + set start date, end date, and/or reporting interval all at once using period expressions syntax --date2 @@ -186,7 +195,7 @@ OPTIONS fects) --today=DATE - override today's date (affects relative smart dates, for + override today's date (affects relative smart dates, for tests/examples) -U --unmarked @@ -205,21 +214,21 @@ OPTIONS hide/aggregate accounts or postings more than NUM levels deep -E --empty - show items with zero amount, normally hidden (and vice-versa in + show items with zero amount, normally hidden (and vice-versa in hledger-ui/hledger-web) -B --cost convert amounts to their cost/selling amount at transaction time -V --market - convert amounts to their market value in default valuation com- + convert amounts to their market value in default valuation com- modities -X --exchange=COMM convert amounts to their market value in commodity COMM --value - convert amounts to cost or market value, more flexibly than + convert amounts to cost or market value, more flexibly than -B/-V/-X --infer-equity @@ -229,38 +238,38 @@ OPTIONS infer costs from conversion equity postings --infer-market-prices - use costs as additional market prices, as if they were P direc- + use costs as additional market prices, as if they were P direc- tives --forecast - generate transactions from periodic rules, between the latest - recorded txn and 6 months from today, or during the specified - PERIOD (= is required). Auto posting rules will be applied to - these transactions as well. Also, in hledger-ui make fu- + generate transactions from periodic rules, between the latest + recorded txn and 6 months from today, or during the specified + PERIOD (= is required). Auto posting rules will be applied to + these transactions as well. Also, in hledger-ui make fu- ture-dated transactions visible. - --auto generate extra postings by applying auto posting rules to all + --auto generate extra postings by applying auto posting rules to all txns (not just forecast txns) --verbose-tags - add visible tags indicating transactions or postings which have + add visible tags indicating transactions or postings which have been generated/modified --commodity-style - Override the commodity style in the output for the specified + Override the commodity style in the output for the specified commodity. For example 'EUR1.000,00'. --color=WHEN (or --colour=WHEN) - Should color-supporting commands use ANSI color codes in text + Should color-supporting commands use ANSI color codes in text output. 'auto' (default): whenever stdout seems to be a color-supporting terminal. 'always' or 'yes': always, useful eg - when piping output into 'less -R'. 'never' or 'no': never. A + when piping output into 'less -R'. 'never' or 'no': never. A NO_COLOR environment variable overrides this. --pretty[=WHEN] - Show prettier output, e.g. using unicode box-drawing charac- - ters. Accepts 'yes' (the default) or 'no' ('y', 'n', 'always', - 'never' also work). If you provide an argument you must use + Show prettier output, e.g. using unicode box-drawing charac- + ters. Accepts 'yes' (the default) or 'no' ('y', 'n', 'always', + 'never' also work). If you provide an argument you must use '=', e.g. '--pretty=yes'. When a reporting option appears more than once in the command line, the @@ -269,13 +278,13 @@ OPTIONS Some reporting options can also be written as query arguments. PERMISSIONS - By default, hledger-web allows anyone who can reach it to view the + By default, hledger-web allows anyone who can reach it to view the journal and to add new transactions, but not to change existing data. You can restrict who can reach it by - o setting the IP address it listens on (see --host above). By default - it listens on 127.0.0.1, accessible to all users on the local ma- + o setting the IP address it listens on (see --host above). By default + it listens on 127.0.0.1, accessible to all users on the local ma- chine. o putting it behind an authenticating proxy, using eg apache or nginx @@ -285,44 +294,44 @@ PERMISSIONS You can restrict what the users who reach it can do, by o using the --capabilities=CAP[,CAP..] flag when you start it, enabling - one or more of the following capabilities. The default value is + one or more of the following capabilities. The default value is view,add: o view - allows viewing the journal file and all included files o add - allows adding new transactions to the main journal file - o manage - allows editing, uploading or downloading the main or in- + o manage - allows editing, uploading or downloading the main or in- cluded files - o using the --capabilities-header=HTTPHEADER flag to specify a HTTP - header from which it will read capabilities to enable. hledger-web - on Sandstorm uses the X-Sandstorm-Permissions header to integrate + o using the --capabilities-header=HTTPHEADER flag to specify a HTTP + header from which it will read capabilities to enable. hledger-web + on Sandstorm uses the X-Sandstorm-Permissions header to integrate with Sandstorm's permissions. This is disabled by default. EDITING, UPLOADING, DOWNLOADING - If you enable the manage capability mentioned above, you'll see a new - "spanner" button to the right of the search form. Clicking this will - let you edit, upload, or download the journal file or any files it in- + If you enable the manage capability mentioned above, you'll see a new + "spanner" button to the right of the search form. Clicking this will + let you edit, upload, or download the journal file or any files it in- cludes. - Note, unlike any other hledger command, in this mode you (or any visi- + Note, unlike any other hledger command, in this mode you (or any visi- tor) can alter or wipe the data files. - Normally whenever a file is changed in this way, hledger-web saves a - numbered backup (assuming file permissions allow it, the disk is not - full, etc.) hledger-web is not aware of version control systems, cur- - rently; if you use one, you'll have to arrange to commit the changes + Normally whenever a file is changed in this way, hledger-web saves a + numbered backup (assuming file permissions allow it, the disk is not + full, etc.) hledger-web is not aware of version control systems, cur- + rently; if you use one, you'll have to arrange to commit the changes yourself (eg with a cron job or a file watcher like entr). - Changes which would leave the journal file(s) unparseable or non-valid - (eg with failing balance assertions) are prevented. (Probably. This + Changes which would leave the journal file(s) unparseable or non-valid + (eg with failing balance assertions) are prevented. (Probably. This needs re-testing.) RELOADING hledger-web detects changes made to the files by other means (eg if you - edit it directly, outside of hledger-web), and it will show the new - data when you reload the page or navigate to a new page. If a change + edit it directly, outside of hledger-web), and it will show the new + data when you reload the page or navigate to a new page. If a change makes a file unparseable, hledger-web will display an error message un- til the file has been fixed. @@ -330,8 +339,8 @@ RELOADING that both machine clocks are roughly in step.) JSON API - In addition to the web UI, hledger-web also serves a JSON API that can - be used to get data or add new transactions. If you want the JSON API + In addition to the web UI, hledger-web also serves a JSON API that can + be used to get data or add new transactions. If you want the JSON API only, you can use the --serve-api flag. Eg: $ hledger-web -f examples/sample.journal --serve-api @@ -348,7 +357,7 @@ JSON API /accounttransactions/ACCOUNTNAME Eg, all account names in the journal (similar to the accounts command). - (hledger-web's JSON does not include newlines, here we use python to + (hledger-web's JSON does not include newlines, here we use python to prettify it): $ curl -s http://127.0.0.1:5000/accountnames | python -m json.tool @@ -389,25 +398,25 @@ JSON API "aprice": null, ... - Most of the JSON corresponds to hledger's data types; for details of - what the fields mean, see the Hledger.Data.Json haddock docs and click - on the various data types, eg Transaction. And for a higher level un- + Most of the JSON corresponds to hledger's data types; for details of + what the fields mean, see the Hledger.Data.Json haddock docs and click + on the various data types, eg Transaction. And for a higher level un- derstanding, see the journal docs. In some cases there is outer JSON corresponding to a "Report" type. To - understand that, go to the Hledger.Web.Handler.MiscR haddock and look - at the source for the appropriate handler to see what it returns. Eg + understand that, go to the Hledger.Web.Handler.MiscR haddock and look + at the source for the appropriate handler to see what it returns. Eg for /accounttransactions it's getAccounttransactionsR, returning a "ac- - countTransactionsReport ...". Looking up the haddock for that we can - see that /accounttransactions returns an AccountTransactionsReport, - which consists of a report title and a list of AccountTransactionsRe- + countTransactionsReport ...". Looking up the haddock for that we can + see that /accounttransactions returns an AccountTransactionsReport, + which consists of a report title and a list of AccountTransactionsRe- portItem (etc). - You can add a new transaction to the journal with a PUT request to - /add, if hledger-web was started with the add capability (enabled by + You can add a new transaction to the journal with a PUT request to + /add, if hledger-web was started with the add capability (enabled by default). The payload must be the full, exact JSON representation of a - hledger transaction (partial data won't do). You can get sample JSON - from hledger-web's /transactions or /accounttransactions, or you can + hledger transaction (partial data won't do). You can get sample JSON + from hledger-web's /transactions or /accounttransactions, or you can export it with hledger-lib, eg like so: .../hledger$ stack ghci hledger-lib @@ -503,28 +512,28 @@ JSON API "tstatus": "Unmarked" } - And here's how to test adding it with curl. This should add a new en- + And here's how to test adding it with curl. This should add a new en- try to your journal: $ curl http://127.0.0.1:5000/add -X PUT -H 'Content-Type: application/json' --data-binary @txn.json DEBUG OUTPUT Debug output - You can add --debug[=N] to the command line to log debug output. N + You can add --debug[=N] to the command line to log debug output. N ranges from 1 (least output, the default) to 9 (maximum output). Typi- - cally you would start with 1 and increase until you are seeing enough. - Debug output goes to stderr, interleaved with the requests logged on + cally you would start with 1 and increase until you are seeing enough. + Debug output goes to stderr, interleaved with the requests logged on stdout. To capture debug output in a log file instead, you can usually redirect stderr, eg: hledger-web --debug=3 2>hledger-web.log. ENVIRONMENT - LEDGER_FILE The main journal file to use when not specified with + LEDGER_FILE The main journal file to use when not specified with -f/--file. Default: $HOME/.hledger.journal. BUGS We welcome bug reports in the hledger issue tracker (shortcut: - http://bugs.hledger.org), or on the #hledger chat or hledger mail list + http://bugs.hledger.org), or on the #hledger chat or hledger mail list (https://hledger.org/support). Some known issues: @@ -549,4 +558,4 @@ LICENSE SEE ALSO hledger(1), hledger-ui(1), hledger-web(1), ledger(1) -hledger-web-1.32.99 February 2024 HLEDGER-WEB(1) +hledger-web-1.32.99 March 2024 HLEDGER-WEB(1) diff --git a/hledger/.date.m4 b/hledger/.date.m4 index 89541032f3d..54ea9b97733 100644 --- a/hledger/.date.m4 +++ b/hledger/.date.m4 @@ -1,2 +1,2 @@ m4_dnl Date to show in man pages. Updated by "Shake manuals" -m4_define({{_monthyear_}}, {{February 2024}})m4_dnl +m4_define({{_monthyear_}}, {{March 2024}})m4_dnl diff --git a/hledger/hledger.1 b/hledger/hledger.1 index 8e2f803b70c..c824e49f358 100644 --- a/hledger/hledger.1 +++ b/hledger/hledger.1 @@ -1,6 +1,6 @@ .\"t -.TH "HLEDGER" "1" "February 2024" "hledger-1.32.99 " "hledger User Manuals" +.TH "HLEDGER" "1" "March 2024" "hledger-1.32.99 " "hledger User Manuals" @@ -83,29 +83,15 @@ good choices (see https://hledger.org/editors.html). To get started, run \f[CR]hledger add\f[R] and follow the prompts, or save some entries like the above in \f[CR]$HOME/.hledger.journal\f[R], then try commands like: -.PD 0 -.P -.PD -\f[CR]hledger print \-x\f[R] -.PD 0 -.P -.PD -\f[CR]hledger aregister assets\f[R] -.PD 0 -.P -.PD -\f[CR]hledger balance\f[R] -.PD 0 -.P -.PD -\f[CR]hledger balancesheet\f[R] -.PD 0 -.P -.PD -\f[CR]hledger incomestatement\f[R]. -.PD 0 -.P -.PD +.IP +.EX +$ hledger print \-x +$ hledger aregister assets +$ hledger balance +$ hledger balancesheet +$ hledger incomestatement +.EE +.PP Run \f[CR]hledger\f[R] to list the commands. See also the \[dq]Starting a journal file\[dq] and \[dq]Setting opening balances\[dq] sections in PART 5: COMMON TASKS. @@ -135,6 +121,18 @@ So we usually configure a different journal file, by setting the \f[CR]\[ti]/finance/2023.journal\f[R]. For more about how to do that on your system, see Common tasks > Setting LEDGER_FILE. +.SS Text encoding +Data files containing non\-ascii characters must use UTF\-8 encoding. +Also, your system should be configured with a locale that can decode +UTF\-8 text. +On some unix systems, you may need set the \f[CR]LANG\f[R] environment +variable, eg. +You can read more about this in Unicode characters, below. +.PP +On unix systems you can check a file\[aq]s encoding with the +\f[CR]file\f[R] command. +If you need to import from a UTF\-16\-encoded CSV file, say, you can +convert it to UTF\-8 with the \f[CR]iconv\f[R] command. .SS Data formats Usually the data file is in hledger\[aq]s journal format, but it can be in any of the supported file formats, which currently are: @@ -1010,10 +1008,8 @@ This option can repeated to set the display style for multiple commodities/currencies. Its argument is as described in the commodity directive. .PP -hledger will occasionally make some additional adjustments to number -formatting, eg adding a trailing decimal mark to disambiguate numbers -with digit group marks; for details, see Amount formatting, -parseability. +In some cases hledger will adjust number formatting to improve their +parseability (such as adding trailing decimal marks when needed). .SS Colour In terminal output, some commands can produce colour when the terminal supports it: @@ -1096,106 +1092,15 @@ hledger will not use ANSI color codes in terminal output, unless overridden by an explicit \f[CR]\-\-color/\-\-colour\f[R] option. .SH PART 2: DATA FORMATS .SH Journal -hledger\[aq]s default file format, representing a General Journal. -Here\[aq]s a cheatsheet/mini\-tutorial, or you can skip ahead to About -journal format. -.SS Journal cheatsheet -.IP -.EX -# Here is the main syntax of hledger\[aq]s journal format -# (omitting extra Ledger compatibility syntax). -# hledger journals contain comments, directives, and transactions, in any order: - -############################################################################### -# 1. Comment lines are for notes or temporarily disabling things. -# They begin with #, ;, or a line containing the word \[dq]comment\[dq]. - -# hash comment line -; semicolon comment line -comment -These lines -are commented. -end comment - -# Some but not all hledger entries can have same\-line comments attached to them, -# from ; (semicolon) to end of line. - -############################################################################### -# 2. Directives modify parsing or reports in some way. -# They begin with a word or letter (or symbol). - -account actifs ; type:A, declare an account that is an Asset. 2+ spaces before ;. -account passifs ; type:L, declare an account that is a Liability, and so on.. (ALERX) -alias chkg = assets:checking -commodity $0.00 -decimal\-mark . -include /dev/null -payee Whole Foods -P 2022\-01\-01 AAAA $1.40 -\[ti] monthly budget goals ; <\- 2+ spaces between period expression and description - expenses:food $400 - expenses:home $1000 - budgeted - -############################################################################### -# 3. Transactions are what it\[aq]s all about; they are dated events, -# usually describing movements of money. -# They begin with a date. - -# DATE DESCRIPTION ; This is a transaction comment. -# ACCOUNT NAME 1 AMOUNT1 ; <\- posting 1. This is a posting comment. -# ACCOUNT NAME 2 AMOUNT2 ; <\- posting 2. Postings must be indented. -# ; \[ha]\[ha] At least 2 spaces between account and amount. -# ... ; Any number of postings is allowed. The amounts must balance (sum to 0). - -2022\-01\-01 opening balances are declared this way - assets:checking $1000 ; Account names can be anything. lower case is easy to type. - assets:savings $1000 ; assets, liabilities, equity, revenues, expenses are common. - assets:cash:wallet $100 ; : indicates subaccounts. - liabilities:credit card $\-200 ; liabilities, equity, revenues balances are usually negative. - equity ; One amount can be left blank; $\-1900 is inferred here. - -2022\-04\-15 * (#12345) pay taxes - ; There can be a ! or * after the date meaning \[dq]pending\[dq] or \[dq]cleared\[dq]. - ; There can be a transaction code (text in parentheses) after the date/status. - ; Amounts\[aq] sign represents direction of flow, or credit/debit: - assets:checking $\-500 ; minus means removed from this account (credit) - expenses:tax:us:2021 $500 ; plus means added to this account (debit) - ; revenue/expense categories are also \[dq]accounts\[dq] - -2022\-01\-01 ; The description is optional. - ; Any currency/commodity symbols are allowed, on either side. - assets:cash:wallet GBP \-10 - expenses:clothing GBP 10 - assets:gringotts \-10 gold - assets:pouch 10 gold - revenues:gifts \-2 \[dq]Liquorice Wands\[dq] ; Complex symbols - assets:bag 2 \[dq]Liquorice Wands\[dq] ; must be double\-quoted. - -2022\-01\-01 Cost in another commodity can be noted with \[at] or \[at]\[at] - assets:investments 2.0 AAAA \[at] $1.50 ; \[at] means per\-unit cost - assets:investments 3.0 AAAA \[at]\[at] $4 ; \[at]\[at] means total cost - assets:checking $\-7.00 - -2022\-01\-02 assert balances - ; Balances can be asserted for extra error checking, in any transaction. - assets:investments 0 AAAA = 5.0 AAAA - assets:pouch 0 gold = 10 gold - assets:savings $0 = $1000 - -1999\-12\-31 Ordering transactions by date is recommended but not required. - ; Postings are not required. - -2022.01.01 These date -2022/1/1 formats are -12/31 also allowed (but consistent YYYY\-MM\-DD is recommended). -.EE -.SS About journal format hledger\[aq]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 \f[CR].journal\f[R], but that\[aq]s not -required. +entries in hledger \f[CR]journal\f[R] format. +If you\[aq]re looking for a quick reference, jump ahead to the journal +cheatsheet (or use the table of contents at +https://hledger.org/hledger.html). +.PP +This file represents an accounting General Journal. +The \f[CR].journal\f[R] file extension is most often used, though not +strictly 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. @@ -1220,12 +1125,144 @@ this easier, adding colour, formatting, tab completion, and useful commands. See Editor configuration at hledger.org for the full list. .PP -Here\[aq]s a description of each part of the file format (and -hledger\[aq]s data model). -.PP -A hledger journal file can contain three kinds of thing: file comments, -transactions, and/or directives (counting periodic transaction rules and -auto posting rules as directives). +A hledger journal file can contain three kinds of thing: comment lines, +transactions, and/or directives (including periodic transaction rules +and auto posting rules). +Understanding the journal file format will also give you a good +understanding of hledger\[aq]s data model. +Here\[aq]s a quick cheatsheet/overview, followed by detailed +descriptions of each part. +.SS Journal cheatsheet +.IP +.EX +# Here is the main syntax of hledger\[aq]s journal format +# (omitting extra Ledger compatibility syntax). + +############################################################################### + +# 1. These are comment lines, for notes or temporarily disabling things. +; They begin with # or ; + +comment +Or, lines can be enclosed within \[dq]comment\[dq] / \[dq]end comment\[dq]. +This is a block of +commented lines. +end comment + +# Some journal entries can have semicolon comments at end of line ; like this +# Some of them require 2 or more spaces before the semicolon. + +############################################################################### + +# 2. Directives customise processing or output in some way. +# You don\[aq]t need any directives to get started. +# But they can add more error checking, or change how things are displayed. +# They begin with a word, letter, or symbol. +# They are most often placed at the top, before transactions. + +account assets ; Declare valid account names and display order. +account assets:savings ; A subaccount. This one represents a bank account. +account assets:checking ; Another. Note, 2+ spaces after the account name. +account assets:receivable ; Accounting type is inferred from english names, +account passifs ; or declared with a \[dq]type\[dq] tag, type:L +account expenses ; type:X + ; A follow\-on comment line, indented. +account expenses:rent ; Expense and revenue categories are also accounts. + ; Subaccounts inherit their parent\[aq]s type. + +commodity $0.00 ; Declare valid commodities and their display styles. +commodity 1.000,00 EUR + +decimal\-mark . ; The decimal mark used in this file (if ambiguous). + +payee Whole Foods ; Declare a valid payee name. + +tag trip ; Declare a valid tag name. + +P 2024\-03\-01 AAPL $179 ; Declare a market price for AAPL in $ on this date. + +include other.journal ; Include another journal file here. + +# Declare a recurring \[dq]periodic transaction\[dq], for budget/forecast reports +\[ti] monthly set budget goals ; <\- Note, 2+ spaces before the description. + (expenses:rent) $1000 + (expenses:food) $500 + +# Declare an auto posting rule, to modify existing transactions in reports += revenues:consulting + liabilities:tax:2024:us *0.25 ; Add a tax liability & expense + expenses:tax:2024:us *\-0.25 ; for 25% of the revenue. + +############################################################################### + +# 3. Transactions are what it\[aq]s all about. +# They are dated events, usually movements of money between 2 or more accounts. +# They begin with a numeric date. +# Here is their basic shape: +# +# DATE DESCRIPTION ; The transaction\[aq]s date and optional description. +# ACCOUNT1 AMOUNT ; A posting of an amount to/from this account, indented. +# ACCOUNT2 AMOUNT ; A second posting, balancing the first. +# ... ; More if needed. Amounts must sum to zero. +# ; Note, 2+ spaces between account names and amounts. + +2024\-01\-01 opening balances ; At the start, declare pre\-existing balances this way. + assets:savings $10000 ; Account names can be anything. lower case is easy to type. + assets:checking $1000 ; assets, liabilities, equity, revenues, expenses are common. + liabilities:credit card $\-500 ; liabilities, equity, revenues balances are usually negative. + equity:start ; One amount can be left blank. $\-10500 is inferred here. + ; Some of these accounts we didn\[aq]t declare above, + ; so \-s/\-\-strict would complain. + +2024\-01\-03 ! (12345) pay rent + ; Additional transaction comment lines, indented. + ; There can be a ! or * after the date meaning \[dq]pending\[dq] or \[dq]cleared\[dq]. + ; There can be a parenthesised (code) after the date/status. + ; Amounts\[aq] sign shows direction of flow. + assets:checking $\-500 ; Minus means removed from this account (credit). + expenses:rent $500 ; Plus means added to this account (debit). + +; Keeping transactions in date order is optional (but helps error checking). + +2024\-01\-02 Gringott\[aq]s Bank | withdrawal ; Description can be PAYEE | NOTE + assets:bank:gold \-10 gold + assets:pouch 10 gold + +2024\-01\-02 shopping + expenses:clothing 1 gold + expenses:wands 5 gold + assets:pouch \-6 gold + +2024\-01\-02 receive gift + revenues:gifts \-3 \[dq]Chocolate Frogs\[dq] ; Complex commodity symbols + assets:pouch 3 \[dq]Chocolate Frogs\[dq] ; must be in double quotes. + +2024\-01\-15 buy some shares, in two lots ; Cost can be noted. + assets:investments:2024\-01\-15 2.0 AAAA \[at] $1.50 ; \[at] means per\-unit cost + assets:investments:2024\-01\-15\-02 3.0 AAAA \[at]\[at] $4 ; \[at]\[at] means total cost + ; \[ha] Per\-lot subaccounts are sometimes useful. + assets:checking $\-7 + +2024\-01\-15 assert some account balances on this date + ; Balances can be asserted in any transaction, with =, for extra error checking. + ; Assertion txns like this one can be made with hledger close \-\-assert \-\-show\-costs + ; + assets:savings $0 = $10000 + assets:checking $0 = $493 + assets:bank:gold 0 gold = \-10 gold + assets:pouch 0 gold = 4 gold + assets:pouch 0 \[dq]Chocolate Frogs\[dq] = 3 \[dq]Chocolate Frogs\[dq] + assets:investments:2024\-01\-15 0.0 AAAA = 2.0 AAAA \[at] $1.50 + assets:investments:2024\-01\-15\-02 0.0 AAAA = 3.0 AAAA \[at]\[at] $4 + liabilities:credit card $0 = $\-500 + +2024\-02\-01 note some event, or a transaction not yet fully entered, on this date + ; Postings are not required. + +; Some other date formats are allowed (but, consistent YYYY\-MM\-DD is useful). +2024.01.01 +2024/1/1 +.EE .SS Comments Lines in the journal will be ignored if they begin with a hash (\f[CR]#\f[R]) or a semicolon (\f[CR];\f[R]). @@ -1332,9 +1369,9 @@ the year of the transaction\[aq]s date. The \f[CR]date:\f[R] tag must have a valid simple date value if it is present, eg a \f[CR]date:\f[R] tag with no value is not allowed. .SS Status -Transactions, or individual postings within a transaction, can have a +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, +description (or posting account name), separated from it by a space, indicating one of three statuses: .PP .TS @@ -1365,16 +1402,14 @@ T} .PP When reporting, you can filter by status with the \f[CR]\-U/\-\-unmarked\f[R], \f[CR]\-P/\-\-pending\f[R], and -\f[CR]\-C/\-\-cleared\f[R] flags; or the \f[CR]status:\f[R], -\f[CR]status:!\f[R], and \f[CR]status:*\f[R] queries; or the U, P, C -keys in hledger\-ui. -.PP -Note, in Ledger and in older versions of hledger, the \[dq]unmarked\[dq] -state is called \[dq]uncleared\[dq]. -As of hledger 1.3 we have renamed it to unmarked for clarity. +\f[CR]\-C/\-\-cleared\f[R] flags (and you can combine these, eg +\f[CR]\-UP\f[R] to match all except cleared things). +Or you can use the \f[CR]status:\f[R], \f[CR]status:!\f[R], and +\f[CR]status:*\f[R] queries, or the U, P, C keys in hledger\-ui. .PP -To replicate Ledger and old hledger\[aq]s behaviour of also matching -pending, combine \-U and \-P. +(Note: in Ledger the \[dq]unmarked\[dq] state is called +\[dq]uncleared\[dq]; in hledger we renamed it to \[dq]unmarked\[dq] for +semantic clarity.) .PP Status marks are optional, but can be helpful eg for reconciling with real\-world accounts. @@ -1455,11 +1490,11 @@ Once a \f[CR]|\f[R] is added, they become distinct. mail list.) .PP If you want more strict error checking, you can declare the valid payee -names with \f[CR]payee\f[R] directives, and then enforce these with -\f[CR]hledger check payees\f[R]. -Note: because of the above, for this you\[aq]ll need to ensure every +names with payee directives, and then enforce these with hledger check +payees. +(Note: because of the above, for this you\[aq]ll need to ensure every transaction description contains a \f[CR]|\f[R] and therefore a -checkable payee name (even if it\[aq]s empty). +checkable payee name, even if it\[aq]s empty.) .SS Transaction comments Text following \f[CR];\f[R], after a transaction description, and/or on indented lines immediately below it, form comments for that transaction. @@ -1484,20 +1519,43 @@ followed by a space (required) an account name (any text, optionally containing \f[B]single spaces\f[R], until end of line or a double space) .IP \[bu] 2 -(optional) \f[B]two or more spaces\f[R] or tabs followed by an amount. +(optional) \f[B]two or more spaces\f[R] (or tabs) followed by an amount. .PP -Positive amounts are being added to the account, negative amounts are -being removed. +If the amount is positive, it is being added to the account; if +negative, it is being removed from the account. .PP -The amounts within a transaction must always sum up to zero. -As a convenience, one amount may be left blank; it will be inferred so -as to balance the transaction. +The posting amounts in a transaction must sum up to zero, indicating +that the inflows and outflows are equal. +We call this a balanced transaction. +(You can read more about the nitty\-gritty details of \[dq]sum up to +zero\[dq] in Transaction balancing below.) .PP -Be sure to note the unusual two\-space delimiter between account name -and amount. -This makes it easy to write account names containing spaces. -But if you accidentally leave only one space (or tab) before the amount, -the amount will be considered part of the account name. +As a convenience, you can optionally leave one amount blank; hledger +will infer what it should be so as to balance the transaction. +.SS Debits and credits +The traditional accounting concepts of debit and credit of course exist +in hledger, but we represent them with numeric sign, as described above. +Positive and negative posting amounts represent debits and credits +respectively. +.PP +You don\[aq]t need to remember that, but if you would like to \- eg for +helping newcomers or for talking with your accountant \- here\[aq]s a +handy mnemonic: +.PP +\f[I]\f[CI]debit / plus / left / short words\f[I]\f[R] +.PD 0 +.P +.PD +\f[I]\f[CI]credit / minus / right / longer words\f[I]\f[R] +.SS The two space delimiter +Be sure to notice the unusual separator between the account name and the +following amount. +Because hledger allows account names with spaces in them, you must +separate the account name and amount (if any) by \f[B]two or more +spaces\f[R] (or tabs). +It\[aq]s easy to forget at first. +If you ever see the amount being treated as part of the account name, +you\[aq]ll know you probably need to add another space between them. .SS Account names Accounts are the main way of categorising things in hledger. As in Double Entry Bookkeeping, they can represent real world accounts @@ -1553,8 +1611,8 @@ Account names can be altered temporarily or permanently by account aliases. .SS Amounts After the account name, there is usually an amount. -(Important: between account name and amount, there must be \f[B]two or -more spaces\f[R].) +(Remember: between account name and amount, there must be two or more +spaces.) .PP hledger\[aq]s amount format is flexible, supporting several international formats. @@ -1598,7 +1656,8 @@ Scientific E notation is allowed: 1E\-6 EUR 1E3 .EE -.SS Decimal marks, digit group marks +.PP +.SS Decimal marks A \f[I]decimal mark\f[R] can be written as a period or a comma: .IP .EX @@ -1606,28 +1665,44 @@ A \f[I]decimal mark\f[R] can be written as a period or a comma: 1,23 .EE .PP -In the integer part of the quantity (left of the decimal mark), groups -of digits can optionally be separated by a \f[I]digit group mark\f[R] \- -a space, comma, or period (different from the decimal mark): +Both of these are common in international number formats, so hledger is +not biased towards one or the other. +Because hledger also supports digit group marks (eg thousands +separators), this means that a number like \f[CR]1,000\f[R] or +\f[CR]1.000\f[R] containing just one period or comma is ambiguous. +In such cases, hledger by default assumes it is a decimal mark, and will +parse both of those as 1. +.PP +To help hledger parse such ambiguous numbers more accurately, if you use +digit group marks, we recommend declaring the decimal mark explicitly. +The best way is to add a \f[CR]decimal\-mark\f[R] directive at the top +of each data file, like this: +.IP +.EX +decimal\-mark . +.EE +.PP +Or you can declare it per commodity with \f[CR]commodity\f[R] +directives, described below. +.PP +hledger also accepts numbers like \f[CR]10.\f[R] with no digits after +the decimal mark (and will sometimes display numbers that way to +disambiguate them \- see Trailing decimal marks). +.SS Digit group marks +In the integer part of the amount quantity (left of the decimal mark), +groups of digits can optionally be separated by a \f[I]digit group +mark\f[R] \- a comma or period (whichever is not used as decimal mark), +or a space (several Unicode space variants, like no\-break space, are +also accepted). +\ So these are all valid amounts in a journal file: .IP .EX $1,000,000.00 EUR 2.000.000,00 INR 9,99,99,999.00 - 1 000 000.9455 + 1 000 000.00 ; <\- ordinary space + 1\ 000\ 000.00 ; <\- no\-break space .EE -.PP -hledger is not biased towards period or comma decimal marks, so a number -containing just one period or comma, like \f[CR]1,000\f[R] or -\f[CR]1.000\f[R], is ambiguous. -In such cases hledger assumes it is a decimal mark, parsing both of -these as 1. -.PP -To disambiguate these and ensure accurate number parsing, especially if -you use digit group marks, we recommend declaring the decimal mark. -You can declare it for each file with \f[CR]decimal\-mark\f[R] -directives, or for each commodity with \f[CR]commodity\f[R] directives -(described below). .SS Commodity Amounts in hledger have both a \[dq]quantity\[dq], which is a signed decimal number, and a \[dq]commodity\[dq], which is a currency symbol, @@ -1649,76 +1724,11 @@ A multi\-commodity amount could be, eg: \f[CR]1 USD, 2 EUR, 3.456 TSLA\f[R]. In practice, you will only see multi\-commodity amounts in hledger\[aq]s output; you can\[aq]t write them directly in the journal file. +\ .PP -(If you are writing scripts or working with hledger\[aq]s internals, -these are the \f[CR]Amount\f[R] and \f[CR]MixedAmount\f[R] types.) -.SS Directives influencing number parsing and display -You can add \f[CR]decimal\-mark\f[R] and \f[CR]commodity\f[R] directives -to the journal, to declare and control these things more explicitly and -precisely. -These are described below, but here\[aq]s a quick example: -.IP -.EX -# the decimal mark character used by all amounts in this file (all commodities) -decimal\-mark . - -# display styles for the $, EUR, INR and no\-symbol commodities: -commodity $1,000.00 -commodity EUR 1.000,00 -commodity INR 9,99,99,999.00 -commodity 1 000 000.9455 -.EE -.PP -.SS Commodity display style -For the amounts in each commodity, hledger chooses a consistent display -style (symbol placement, decimal mark and digit group marks, number of -decimal digits) to use in most reports. -This is inferred as follows: -.PP -First, if there\[aq]s a \f[CR]D\f[R] directive declaring a default -commodity, that commodity symbol and amount format is applied to all -no\-symbol amounts in the journal. -.PP -Then each commodity\[aq]s display style is determined from its -\f[CR]commodity\f[R] directive. -We recommend always declaring commodities with \f[CR]commodity\f[R] -directives, since they help ensure consistent display styles and -precisions, and bring other benefits such as error checking for -commodity symbols. -.PP -But if a \f[CR]commodity\f[R] directive is not present, hledger infers a -commodity\[aq]s display styles from its amounts as they are written in -the journal (excluding cost amounts and amounts in periodic transaction -rules or auto posting rules). -It uses -.IP \[bu] 2 -the symbol placement and decimal mark of the first amount seen -.IP \[bu] 2 -the digit group marks of the first amount with digit group marks -.IP \[bu] 2 -and the maximum number of decimal digits seen across all amounts. -.PP -And as fallback if no applicable amounts are found, it would use a -default style, like \f[CR]$1000.00\f[R] (symbol on the left with no -space, period as decimal mark, and two decimal digits). -.PP -Finally, commodity styles can be overridden by the -\f[CR]\-c/\-\-commodity\-style\f[R] command line option. -.SS Rounding -Amounts are stored internally as decimal numbers with up to 255 decimal -places. -They are displayed with their original journal precisions by print and -print\-like reports, and rounded to their display precision (the number -of decimal digits specified by the commodity display style) by other -reports. -When rounding, hledger uses banker\[aq]s rounding (it rounds to the -nearest even digit). -So eg 0.5 displayed with zero decimal digits appears as \[dq]0\[dq]. -.SS Number format -hledger will occasionally make some additional adjustments to number -formatting, eg adding a trailing decimal mark to disambiguate numbers -with digit group marks; for details, see Amount formatting, -parseability. +By default, the format of amounts in the journal influences how hledger +displays them in output. +This is explained in Commodity display style below. .PP .SS Costs After a posting amount, you can note its cost (when buying) or selling @@ -1786,105 +1796,6 @@ Note that the cost normally should be a positive amount, though it\[aq]s not required to be. This can be a little confusing, see discussion at \-\-infer\-market\-prices: market prices from transactions. -.SS Other cost/lot notations -A slight digression for Ledger and Beancount users. -Ledger has a number of cost/lot\-related notations: -.IP \[bu] 2 -\f[CR]\[at] UNITCOST\f[R] and \f[CR]\[at]\[at] TOTALCOST\f[R] -.RS 2 -.IP \[bu] 2 -expresses a conversion rate, as in hledger -.IP \[bu] 2 -when buying, also creates a lot than can be selected at selling time -.RE -.IP \[bu] 2 -\f[CR](\[at]) UNITCOST\f[R] and \f[CR](\[at]\[at]) TOTALCOST\f[R] -(virtual cost) -.RS 2 -.IP \[bu] 2 -like the above, but also means \[dq]this cost was exceptional, don\[aq]t -use it when inferring market prices\[dq]. -.RE -.PP -Currently, hledger treats the above like \f[CR]\[at]\f[R] and -\f[CR]\[at]\[at]\f[R]; the parentheses are ignored. -.IP \[bu] 2 -\f[CR]{=FIXEDUNITCOST}\f[R] and \f[CR]{{=FIXEDTOTALCOST}}\f[R] (fixed -price) -.RS 2 -.IP \[bu] 2 -when buying, means \[dq]this cost is also the fixed price, don\[aq]t let -it fluctuate in value reports\[dq] -.RE -.IP \[bu] 2 -\f[CR]{UNITCOST}\f[R] and \f[CR]{{TOTALCOST}}\f[R] (lot price) -.RS 2 -.IP \[bu] 2 -can be used identically to \f[CR]\[at] UNITCOST\f[R] and -\f[CR]\[at]\[at] TOTALCOST\f[R], also creates a lot -.IP \[bu] 2 -when selling, combined with \f[CR]\[at] ...\f[R], specifies an -investment lot by its cost basis; does not check if that lot is present -.RE -.IP \[bu] 2 -and related: \f[CR][YYYY/MM/DD]\f[R] (lot date) -.RS 2 -.IP \[bu] 2 -when buying, attaches this acquisition date to the lot -.IP \[bu] 2 -when selling, selects a lot by its acquisition date -.RE -.IP \[bu] 2 -\f[CR](SOME TEXT)\f[R] (lot note) -.RS 2 -.IP \[bu] 2 -when buying, attaches this note to the lot -.IP \[bu] 2 -when selling, selects a lot by its note -.RE -.PP -Currently, hledger accepts any or all of the above in any order after -the posting amount, but ignores them. -(This can break transaction balancing.) -.PP -For Beancount users, the notation and behaviour is different: -.IP \[bu] 2 -\f[CR]\[at] UNITCOST\f[R] and \f[CR]\[at]\[at] TOTALCOST\f[R] -.RS 2 -.IP \[bu] 2 -expresses a cost without creating a lot, as in hledger -.IP \[bu] 2 -when buying (augmenting) or selling (reducing) a lot, combined with -\f[CR]{...}\f[R]: documents the cost/selling price (not used for -transaction balancing) -.RE -.IP \[bu] 2 -\f[CR]{UNITCOST}\f[R] and \f[CR]{{TOTALCOST}}\f[R] -.RS 2 -.IP \[bu] 2 -when buying (augmenting), expresses the cost for transaction balancing, -and also creates a lot with this cost basis attached -.IP \[bu] 2 -when selling (reducing), -.RS 2 -.IP \[bu] 2 -selects a lot by its cost basis -.IP \[bu] 2 -raises an error if that lot is not present or can not be selected -unambiguously (depending on booking method configured) -.IP \[bu] 2 -expresses the selling price for transaction balancing -.RE -.RE -.PP -Currently, hledger accepts the -\f[CR]{UNITCOST}\f[R]/\f[CR]{{TOTALCOST}}\f[R] notation but ignores it. -.IP \[bu] 2 -variations: \f[CR]{}\f[R], \f[CR]{YYYY\-MM\-DD}\f[R], -\f[CR]{\[dq]LABEL\[dq]}\f[R], \f[CR]{UNITCOST, \[dq]LABEL\[dq]}\f[R], -\f[CR]{UNITCOST, YYYY\-MM\-DD, \[dq]LABEL\[dq]}\f[R] etc. -.PP -Currently, hledger rejects these. .SS Balance assertions hledger supports Ledger\-style balance assertions in journal files. These look like, for example, \f[CR]= EXPECTEDBALANCE\f[R] following a @@ -2061,6 +1972,46 @@ they may contain tags, which are not ignored. ; a comment for posting 2 ; a second comment line for posting 2 .EE +.SS Transaction balancing +How exactly does hledger decide when a transaction is balanced ? +The general goal is that if you look at the journal entry and calculate +the amounts\[aq] sum perfectly with pencil and paper, hledger should +agree with you. +.PP +Real world transactions, especially for investments or cryptocurrencies, +often involve imprecise costs, complex decimals, and/or +infinitely\-recurring decimals, which are difficult or inconvenient to +handle on a computer. +So to be a practical accounting system, hledger allows some imprecision +when checking transaction balancedness. +The question is, how much imprecision should be allowed ? +.PP +hledger currently decides it based on the commodity display styles: if +the postings\[aq] sum would appear to be zero when displayed with the +standard display precisions, the transaction is considered balanced. +.PP +Or equivalently: if the journal entry is displayed with amounts rounded +to the standard display precisions (with +\f[CR]hledger print \-\-round=hard\f[R]), and a human with pencil and +paper would agree that those displayed amounts add up to zero, the +transaction is considered balanced. +.PP +This has some advantages: it is fairly intuitive, general not +hard\-coded, yet configurable when needed. +On the downside it means that transaction balancedness is related to +commodity display precisions, so eg when using +\f[CR]\-c/\-\-commodity\-style\f[R] to display things with more than +usual precision, you might need to fix some of your journal entries (ie, +add decimal digits to make them balance more precisely). +.PP +Other PTA tools (Ledger, Beancount..) +have their own ways of doing it. +Possible improvements are discussed at #1964. +.PP +Note: if you have multiple journal files, and are relying on commodity +directives to make imprecise journal entries balance, the +directives\[aq] placement might be important \- see \f[CR]commodity\f[R] +directive. .SS Tags Tags are a way to add extra labels or data fields to transactions, postings, or accounts, which you can then search or pivot on. @@ -2117,7 +2068,8 @@ them with the check command. .SS Special tags Some tag names have special significance to hledger. There\[aq]s not much harm in using them yourself, but some could produce -an error message, particularly the \f[CR]date:\f[R] tag. +an error message, particularly the \f[CR]date:\f[R] and \f[CR]type:\f[R] +tags. They are explained elsewhere, but here is a quick list for reference: .PP Tags you can set to influence hledger\[aq]s behaviour: @@ -2329,17 +2281,17 @@ T{ T}@T{ Declares up to four things: 1. a commodity symbol, for checking all amounts in all files 2. -the decimal mark for parsing amounts of this commodity, in the following -entries until end of current file (if there is no -\f[CR]decimal\-mark\f[R] directive) 3. -and the display style for amounts of this commodity 4. -which is also the precision to use for balanced\-transaction checking in -this commodity. -Takes precedence over \f[CR]D\f[R]. -Subdirectives: \f[CR]format\f[R] (Ledger\-compatible syntax). +the display style for all amounts of this commodity 3. +the decimal mark for parsing amounts of this commodity, in the rest of +this file and its children, if there is no \f[CR]decimal\-mark\f[R] +directive 4. +the precision to use for balanced\-transaction checking in this +commodity, in this file and its children. +\ Takes precedence over \f[CR]D\f[R]. +Subdirectives: \f[CR]format\f[R] (ignored). Command line equivalent: \f[CR]\-c/\-\-commodity\-style\f[R] T}@T{ -N,Y,N,N +N,N,Y,Y T} T{ \f[B]\f[CB]decimal\-mark\f[B]\f[R] @@ -2874,26 +2826,34 @@ The \f[CR]commodity\f[R] directive performs several functions: .IP "1." 3 It declares which commodity symbols may be used in the journal, enabling useful error checking with strict mode or the check command. -(See Commodity error checking below.) +See Commodity error checking below. .IP "2." 3 -It declares the precision with which this commodity\[aq]s amounts should -be compared when checking for balanced transactions. +It declares how all amounts in this commodity should be displayed, eg +how many decimals to show. +See Commodity display style above. .IP "3." 3 -It declares how this commodity\[aq]s amounts should be displayed, eg -their symbol placement, digit group mark if any, digit group sizes, -decimal mark (period or comma), and the number of decimal places. -(See Commodity display style above.) +(If no \f[CR]decimal\-mark\f[R] directive is in effect:) It sets the +decimal mark to expect (period or comma) when parsing amounts in this +commodity, in this file and files it includes, from the directive until +end of current file. +See Decimal marks above. .IP "4." 3 -It sets which decimal mark (period or comma) to expect when parsing -subsequent amounts in this commodity (if there is no -\f[CR]decimal\-mark\f[R] directive in effect. -See Decimal marks, digit group marks above. -For related dev discussion, see #793.) +It declares the precision with which this commodity\[aq]s amounts should +be compared when checking for balanced transactions, anywhere in this +file and files it includes, until end of current file. .PP Declaring commodities solves several common parsing/display problems, so we recommend it. -Generally you should put \f[CR]commodity\f[R] directives at the top of -your journal file (because function 4 is position\-sensitive). +.PP +Note that effects 3 and 4 above end at the end of the directive\[aq]s +file, and will not affect sibling or parent files. +So if you are relying on them (especially 4) and using multiple files, +placing your commodity directives in a top\-level parent file might be +important. +Or, keep your decimal marks unambiguous and your entries well balanced +and precise. +.PP +(Related: #793) .SS Commodity directive syntax A commodity directive is normally the word \f[CR]commodity\f[R] followed by a sample amount (and optionally a comment). @@ -3609,6 +3569,105 @@ value EXPR .PP See also https://hledger.org/ledger.html for a detailed hledger/Ledger syntax comparison. +.SS Other cost/lot notations +A slight digression for Ledger and Beancount users. +Ledger has a number of cost/lot\-related notations: +.IP \[bu] 2 +\f[CR]\[at] UNITCOST\f[R] and \f[CR]\[at]\[at] TOTALCOST\f[R] +.RS 2 +.IP \[bu] 2 +expresses a conversion rate, as in hledger +.IP \[bu] 2 +when buying, also creates a lot than can be selected at selling time +.RE +.IP \[bu] 2 +\f[CR](\[at]) UNITCOST\f[R] and \f[CR](\[at]\[at]) TOTALCOST\f[R] +(virtual cost) +.RS 2 +.IP \[bu] 2 +like the above, but also means \[dq]this cost was exceptional, don\[aq]t +use it when inferring market prices\[dq]. +.RE +.PP +Currently, hledger treats the above like \f[CR]\[at]\f[R] and +\f[CR]\[at]\[at]\f[R]; the parentheses are ignored. +.IP \[bu] 2 +\f[CR]{=FIXEDUNITCOST}\f[R] and \f[CR]{{=FIXEDTOTALCOST}}\f[R] (fixed +price) +.RS 2 +.IP \[bu] 2 +when buying, means \[dq]this cost is also the fixed price, don\[aq]t let +it fluctuate in value reports\[dq] +.RE +.IP \[bu] 2 +\f[CR]{UNITCOST}\f[R] and \f[CR]{{TOTALCOST}}\f[R] (lot price) +.RS 2 +.IP \[bu] 2 +can be used identically to \f[CR]\[at] UNITCOST\f[R] and +\f[CR]\[at]\[at] TOTALCOST\f[R], also creates a lot +.IP \[bu] 2 +when selling, combined with \f[CR]\[at] ...\f[R], specifies an +investment lot by its cost basis; does not check if that lot is present +.RE +.IP \[bu] 2 +and related: \f[CR][YYYY/MM/DD]\f[R] (lot date) +.RS 2 +.IP \[bu] 2 +when buying, attaches this acquisition date to the lot +.IP \[bu] 2 +when selling, selects a lot by its acquisition date +.RE +.IP \[bu] 2 +\f[CR](SOME TEXT)\f[R] (lot note) +.RS 2 +.IP \[bu] 2 +when buying, attaches this note to the lot +.IP \[bu] 2 +when selling, selects a lot by its note +.RE +.PP +Currently, hledger accepts any or all of the above in any order after +the posting amount, but ignores them. +(This can break transaction balancing.) +.PP +For Beancount users, the notation and behaviour is different: +.IP \[bu] 2 +\f[CR]\[at] UNITCOST\f[R] and \f[CR]\[at]\[at] TOTALCOST\f[R] +.RS 2 +.IP \[bu] 2 +expresses a cost without creating a lot, as in hledger +.IP \[bu] 2 +when buying (augmenting) or selling (reducing) a lot, combined with +\f[CR]{...}\f[R]: documents the cost/selling price (not used for +transaction balancing) +.RE +.IP \[bu] 2 +\f[CR]{UNITCOST}\f[R] and \f[CR]{{TOTALCOST}}\f[R] +.RS 2 +.IP \[bu] 2 +when buying (augmenting), expresses the cost for transaction balancing, +and also creates a lot with this cost basis attached +.IP \[bu] 2 +when selling (reducing), +.RS 2 +.IP \[bu] 2 +selects a lot by its cost basis +.IP \[bu] 2 +raises an error if that lot is not present or can not be selected +unambiguously (depending on booking method configured) +.IP \[bu] 2 +expresses the selling price for transaction balancing +.RE +.RE +.PP +Currently, hledger accepts the +\f[CR]{UNITCOST}\f[R]/\f[CR]{{TOTALCOST}}\f[R] notation but ignores it. +.IP \[bu] 2 +variations: \f[CR]{}\f[R], \f[CR]{YYYY\-MM\-DD}\f[R], +\f[CR]{\[dq]LABEL\[dq]}\f[R], \f[CR]{UNITCOST, \[dq]LABEL\[dq]}\f[R], +\f[CR]{UNITCOST, YYYY\-MM\-DD, \[dq]LABEL\[dq]}\f[R] etc. +.PP +Currently, hledger rejects these. .PP .SH CSV hledger can read CSV files (Character Separated Value \- usually comma, @@ -3629,14 +3688,13 @@ This contains rules describing the CSV data (header line, fields layout, date format etc.), how to construct hledger transactions from it, and how to categorise transactions based on description or other attributes. .PP -By default hledger looks for a rules file named like the CSV file with -an extra \f[CR].rules\f[R] extension, in the same directory. +By default, hledger expects this rules file to be named like the CSV +file, with an extra \f[CR].rules\f[R] extension added, in the same +directory. Eg when asked to read \f[CR]foo/FILE.csv\f[R], hledger looks for \f[CR]foo/FILE.csv.rules\f[R]. You can specify a different rules file with the \f[CR]\-\-rules\-file\f[R] option. -If no rules file is found, hledger will create a sample rules file, -which you\[aq]ll need to adjust. .PP At minimum, the rules file must identify the date and amount fields, and often it also specifies the date format and how many header lines there @@ -4198,7 +4256,8 @@ equivalent to \f[CR]balance1\f[R]. You can adjust the type of assertion/assignment with the \f[CR]balance\-type\f[R] rule (see below). .PP -See Tips below for more about setting amounts and currency. +See the Working with CSV tips below for more about setting amounts and +currency. .SS \f[CR]if\f[R] block Rules can be applied conditionally, depending on patterns in the CSV data. @@ -4306,16 +4365,18 @@ the regex would see, and try to match, this modified record text: .SS Combining matchers When an if block has multiple matchers, they are combined as follows: .IP \[bu] 2 -By default they are OR\[aq]d (any one of them can match) +By default they are OR\[aq]d (any of them can match) .IP \[bu] 2 -When a matcher is preceded by ampersand (\f[CR]&\f[R]) it will be -AND\[aq]ed with the previous matcher (both of them must match) +When a matcher is preceded by ampersand (\f[CR]&\f[R], at the start of +the line) it will be AND\[aq]ed with the previous matcher (all in the +AND\[aq]ed group must match) .IP \[bu] 2 \f[I]Added in 1.32\f[R] When a matcher is preceded by an exclamation -mark (\f[CR]!\f[R]), the matcher is negated (it may not match). +mark (\f[CR]!\f[R]), it is negated (it must not match). .PP -Currently there is a limitation: you can\[aq]t use both \f[CR]&\f[R] and -\f[CR]!\f[R] on the same line (you can\[aq]t AND a negated matcher). +Note currently there is a limitation: you can\[aq]t use both +\f[CR]&\f[R] and \f[CR]!\f[R] on the same line (you can\[aq]t AND a +negated matcher). .SS Match groups \f[I]Added in 1.32\f[R] .PP @@ -4353,6 +4414,7 @@ like this: if,HLEDGERFIELD1,HLEDGERFIELD2,... MATCHERA,VALUE1,VALUE2,... MATCHERB,VALUE1,VALUE2,... +; Comment line that explains MATCHERC MATCHERC,VALUE1,VALUE2,... .EE @@ -4369,13 +4431,16 @@ Each line must contain the same number of separators; empty values are allowed. Whitespace can be used in the matcher lines for readability (but not in the if line, currently). +You can use the comment lines in the table body. The table must be terminated by an empty line (or end of file). .PP An if table like the above is interpreted as follows: try all of the matchers; whenever a matcher succeeds, assign all of the values on that -line to the corresponding hledger fields; later lines can overrider -earlier ones. -It is equivalent to this sequence of if blocks: +line to the corresponding hledger fields; If multiple lines match, later +lines will override fields assigned by the earlier ones \- just like the +sequence of \f[CR]if\f[R] blocks would behave. +.PP +If table presented above is equivalent to this sequence of if blocks: .IP .EX if MATCHERA @@ -4388,6 +4453,7 @@ if MATCHERB HLEDGERFIELD2 VALUE2 ... +; Comment line which explains MATCHERC if MATCHERC HLEDGERFIELD1 VALUE1 HLEDGERFIELD2 VALUE2 @@ -4400,6 +4466,7 @@ Example: if,account2,comment atm transaction fee,expenses:business:banking,deductible? check it %description groceries,expenses:groceries, +;; Comment line that desribes why this particular date is special 2023/01/12.*Plumbing LLC,expenses:house:upkeep,emergency plumbing call\-out .EE .SS \f[CR]balance\-type\f[R] @@ -5239,7 +5306,7 @@ use emacs and the built\-in timeclock.el, or the extended timeclock\-x.el and perhaps the extras in ledgerutils.el .IP \[bu] 2 at the command line, use these bash aliases: -\f[CR]shell alias ti=\[dq]echo i \[ga]date \[aq]+%Y\-%m\-%d %H:%M:%S\[aq]\[ga] \[rs]$* >>$TIMELOG\[dq] alias to=\[dq]echo o \[ga]date \[aq]+%Y\-%m\-%d %H:%M:%S\[aq]\[ga] >>$TIMELOG\[dq]\f[R] +\f[CR]cli alias ti=\[dq]echo i \[ga]date \[aq]+%Y\-%m\-%d %H:%M:%S\[aq]\[ga] \[rs]$* >>$TIMELOG\[dq] alias to=\[dq]echo o \[ga]date \[aq]+%Y\-%m\-%d %H:%M:%S\[aq]\[ga] >>$TIMELOG\[dq]\f[R] .IP \[bu] 2 or use the old \f[CR]ti\f[R] and \f[CR]to\f[R] scripts in the ledger 2.x repository. @@ -5445,20 +5512,76 @@ fos.ledger .. .EE .IP .EX -$ hledger \-f a.timedot \-\-alias \[aq]/\[rs]./=:\[aq] bal \-t - 4.50 fos - 4.00 hledger:timedot - 0.50 ledger -\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- - 4.50 +$ hledger \-f a.timedot \-\-alias \[aq]/\[rs]./=:\[aq] bal \-t + 4.50 fos + 4.00 hledger:timedot + 0.50 ledger +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- + 4.50 +.EE +.SH PART 3: REPORTING CONCEPTS +.SH Amount formatting +.SS Commodity display style +For the amounts in each commodity, hledger chooses a consistent display +style (symbol placement, decimal mark and digit group marks, number of +decimal digits) to use in most reports. +This is inferred as follows: +.PP +First, if there\[aq]s a \f[CR]D\f[R] directive declaring a default +commodity, that commodity symbol and amount format is applied to all +no\-symbol amounts in the journal. +.PP +Then each commodity\[aq]s display style is determined from its +\f[CR]commodity\f[R] directive. +We recommend always declaring commodities with \f[CR]commodity\f[R] +directives, since they help ensure consistent display styles and +precisions, and bring other benefits such as error checking for +commodity symbols. +Here\[aq]s an example: +.IP +.EX +# Set display styles (and decimal marks, for parsing, if there is no decimal\-mark directive) +# for the $, EUR, INR and no\-symbol commodities: +commodity $1,000.00 +commodity EUR 1.000,00 +commodity INR 9,99,99,999.00 +commodity 1 000 000.9455 .EE -.SH PART 3: REPORTING CONCEPTS -.SH Amount formatting, parseability +.PP +But for convenience, if a \f[CR]commodity\f[R] directive is not present, +hledger infers a commodity\[aq]s display styles from its amounts as they +are written in the journal (excluding cost amounts and amounts in +periodic transaction rules or auto posting rules). +It uses +.IP \[bu] 2 +the symbol placement and decimal mark of the first amount seen +.IP \[bu] 2 +the digit group marks of the first amount with digit group marks +.IP \[bu] 2 +and the maximum number of decimal digits seen across all amounts. +.PP +And as fallback if no applicable amounts are found, it would use a +default style, like \f[CR]$1000.00\f[R] (symbol on the left with no +space, period as decimal mark, and two decimal digits). +.PP +Finally, commodity styles can be overridden by the +\f[CR]\-c/\-\-commodity\-style\f[R] command line option. +.SS Rounding +Amounts are stored internally as decimal numbers with up to 255 decimal +places. +They are displayed with their original journal precisions by print and +print\-like reports, and rounded to their display precision (the number +of decimal digits specified by the commodity display style) by other +reports. +When rounding, hledger uses banker\[aq]s rounding (it rounds to the +nearest even digit). +So eg 0.5 displayed with zero decimal digits appears as \[dq]0\[dq]. +.SS Trailing decimal marks If you\[aq]re wondering why your \f[CR]print\f[R] report sometimes shows trailing decimal marks, with no decimal digits; it does this when showing amounts that have digit group marks but no decimal digits, to -disambiguate them and allow them to be re\-parsed reliably (see also -Decimal marks, digit group marks. +disambiguate them and allow them to be re\-parsed reliably (see Decimal +marks). Eg: .IP .EX @@ -5491,8 +5614,8 @@ $ hledger print \-c \[aq]$1,000.00\[aq] \-\-round=soft 2023\-01\-02 (a) $1,000.00 .EE -.PP -More generally: hledger output falls into three rough categories, which +.SS Amount parseability +More generally, hledger output falls into three rough categories, which format amounts a little bit differently to suit different consumers: .PP \f[B]1. @@ -6335,12 +6458,12 @@ have no postings matching any of the negative account terms AND .IP \[bu] 2 match all the other terms. .PP -We also support more complex boolean queries with the \[aq]expr:\[aq] +We also support more complex boolean queries with the \f[CR]expr:\f[R] prefix. -This allows one to combine queries using one of three operators: AND, -OR, and NOT, where NOT is different syntax for \[aq]not:\[aq]. -.PP -Examples of such queries are: +This allows one to combine queries using \f[CR]AND\f[R], \f[CR]OR\f[R], +and \f[CR]NOT\f[R]. +(\f[CR]NOT\f[R] is equivalent to the \f[CR]not:\f[R] prefix.) +Some examples: .IP \[bu] 2 Match transactions with \[aq]cool\[aq] in the description AND with the \[aq]A\[aq] tag @@ -6371,22 +6494,15 @@ Some queries can also be expressed as command\-line options: \f[CR]date:2023\f[R] is equivalent to \f[CR]\-p 2023\f[R], etc. When you mix command options and query arguments, generally the resulting query is their intersection. +.SS Queries and account aliases +When account names are rewritten with \f[CR]\-\-alias\f[R] or +\f[CR]alias\f[R], \f[CR]acct:\f[R] will match either the old or the new +account name. .SS Queries and valuation When amounts are converted to other commodities in cost or value reports, \f[CR]cur:\f[R] and \f[CR]amt:\f[R] match the old commodity -symbol and the old amount quantity, not the new ones (except in hledger -1.22.0 where it\[aq]s reversed, see #1625). -.SS Querying with account aliases -When account names are rewritten with \f[CR]\-\-alias\f[R] or -\f[CR]alias\f[R], note that \f[CR]acct:\f[R] will match either the old -or the new account name. -.SS Querying with cost or value -When amounts are converted to other commodities in cost or value -reports, note that \f[CR]cur:\f[R] matches the new commodity symbol, and -not the old one, and \f[CR]amt:\f[R] matches the new quantity, and not -the old one. -Note: this changed in hledger 1.22, previously it was the reverse, see -the discussion at #1625. +symbol and the old amount quantity, not the new ones. +(Except in hledger 1.22, #1625.) .SH Pivoting Normally, hledger groups and sums amounts within each account. The \f[CR]\-\-pivot FIELD\f[R] option substitutes some other transaction @@ -7130,43 +7246,6 @@ If you have no P directives, and use the \f[CR]\-\-infer\-market\-prices\f[R] flag, costs determine it. .PP Amounts for which no valuation commodity can be found are not converted. -.SS Simple valuation examples -Here are some quick examples of \f[CR]\-V\f[R]: -.IP -.EX -; one euro is worth this many dollars from nov 1 -P 2016/11/01 € $1.10 - -; purchase some euros on nov 3 -2016/11/3 - assets:euros €100 - assets:checking - -; the euro is worth fewer dollars by dec 21 -P 2016/12/21 € $1.03 -.EE -.PP -How many euros do I have ? -.IP -.EX -$ hledger \-f t.j bal \-N euros - €100 assets:euros -.EE -.PP -What are they worth at end of nov 3 ? -.IP -.EX -$ hledger \-f t.j bal \-N euros \-V \-e 2016/11/4 - $110.00 assets:euros -.EE -.PP -What are they worth after 2016/12/21 ? -(no report end date specified, defaults to today) -.IP -.EX -$ hledger \-f t.j bal \-N euros \-V - $103.00 assets:euros -.EE .SS \-\-value: Flexible valuation \f[CR]\-V\f[R] and \f[CR]\-X\f[R] are special cases of the more general \f[CR]\-\-value\f[R] option: @@ -7206,7 +7285,44 @@ To select a different valuation commodity, add the optional Eg: \f[B]\f[CB]\-\-value=now,EUR\f[B]\f[R]. hledger will do its best to convert amounts to this commodity, deducing market prices as described above. -.SS More valuation examples +.SS Valuation examples +Here are some quick examples of \f[CR]\-V\f[R]: +.IP +.EX +; one euro is worth this many dollars from nov 1 +P 2016/11/01 € $1.10 + +; purchase some euros on nov 3 +2016/11/3 + assets:euros €100 + assets:checking + +; the euro is worth fewer dollars by dec 21 +P 2016/12/21 € $1.03 +.EE +.PP +How many euros do I have ? +.IP +.EX +$ hledger \-f t.j bal \-N euros + €100 assets:euros +.EE +.PP +What are they worth at end of nov 3 ? +.IP +.EX +$ hledger \-f t.j bal \-N euros \-V \-e 2016/11/4 + $110.00 assets:euros +.EE +.PP +What are they worth after 2016/12/21 ? +(no report end date specified, defaults to today) +.IP +.EX +$ hledger \-f t.j bal \-N euros \-V + $103.00 assets:euros +.EE +.PP Here are some examples showing the effect of \f[CR]\-\-value\f[R], as seen with \f[CR]print\f[R]: .IP @@ -7296,7 +7412,7 @@ $ hledger \-f\- print \-\-value=2000\-01\-15 .EE .SS Interaction of valuation and queries When matching postings based on queries in the presence of valuation, -the following happens. +the following happens: .IP "1." 3 The query is separated into two parts: .RS 4 @@ -7314,16 +7430,46 @@ Valuation is applied to the postings. The postings are matched to the other parts of the query based on post\-valued amounts. .PP -See: 1625 +Related: #1625 .SS Effect of valuation on reports Here is a reference for how valuation is supposed to affect each part of -hledger\[aq]s reports (and a glossary). -(It\[aq]s wide, you\[aq]ll have to scroll sideways.) +hledger\[aq]s reports. +(It\[aq]s wide, you may need to scroll sideways.) It may be useful when troubleshooting. If you find problems, please report them, ideally with a reproducible example. Related: #329, #1083. .PP +First, a quick glossary: +.TP +\f[I]cost\f[R] +calculated using price(s) recorded in the transaction(s). +.TP +\f[I]value\f[R] +market value using available market price declarations, or the unchanged +amount if no conversion rate can be found. +.TP +\f[I]report start\f[R] +the first day of the report period specified with \-b or \-p or date:, +otherwise today. +.TP +\f[I]report or journal start\f[R] +the first day of the report period specified with \-b or \-p or date:, +otherwise the earliest transaction date in the journal, otherwise today. +.TP +\f[I]report end\f[R] +the last day of the report period specified with \-e or \-p or date:, +otherwise today. +.TP +\f[I]report or journal end\f[R] +the last day of the report period specified with \-e or \-p or date:, +otherwise the latest transaction date in the journal, otherwise today. +.TP +\f[I]report interval\f[R] +a flag (\-D/\-W/\-M/\-Q/\-Y) or period expression that activates the +report\[aq]s multi\-period mode (whether showing one or many +subperiods). +.PP .TS tab(@); lw(9.5n) lw(11.8n) lw(12.0n) lw(17.2n) lw(12.0n) lw(7.4n). @@ -7628,36 +7774,6 @@ T} .PP \f[CR]\-\-cumulative\f[R] is omitted to save space, it works like \f[CR]\-H\f[R] but with a zero starting balance. -.PP -\f[B]Glossary:\f[R] -.TP -\f[I]cost\f[R] -calculated using price(s) recorded in the transaction(s). -.TP -\f[I]value\f[R] -market value using available market price declarations, or the unchanged -amount if no conversion rate can be found. -.TP -\f[I]report start\f[R] -the first day of the report period specified with \-b or \-p or date:, -otherwise today. -.TP -\f[I]report or journal start\f[R] -the first day of the report period specified with \-b or \-p or date:, -otherwise the earliest transaction date in the journal, otherwise today. -.TP -\f[I]report end\f[R] -the last day of the report period specified with \-e or \-p or date:, -otherwise today. -.TP -\f[I]report or journal end\f[R] -the last day of the report period specified with \-e or \-p or date:, -otherwise the latest transaction date in the journal, otherwise today. -.TP -\f[I]report interval\f[R] -a flag (\-D/\-W/\-M/\-Q/\-Y) or period expression that activates the -report\[aq]s multi\-period mode (whether showing one or many -subperiods). .SH PART 4: COMMANDS .SS Commands overview Here are the built\-in commands: @@ -8041,6 +8157,9 @@ or change of balance values (\f[CR]\-\-valuechange\f[R]) .IP \[bu] 2 or unrealised capital gain/loss (\f[CR]\-\-gain\f[R]) .IP \[bu] 2 +or balance changes from sibling postings +(\f[CR]\-\-related\f[R]/\f[CR]\-r\f[R]) +.IP \[bu] 2 or postings count (\f[CR]\-\-count\f[R]) .PP \&..in.. @@ -8093,10 +8212,6 @@ with output formats \f[CR]txt\f[R], \f[CR]csv\f[R], \f[CR]tsv\f[R] only:) \f[CR]html\f[R]. In \f[CR]txt\f[R] output in a colour\-supporting terminal, negative amounts are shown in red. -.PP -The \f[CR]\-\-related\f[R]/\f[CR]\-r\f[R] flag shows the balance of the -\f[I]other\f[R] postings in the transactions of the postings which would -normally be shown. .SS Simple balance report With no arguments, \f[CR]balance\f[R] shows a list of all accounts and their change of balance \- ie, the sum of posting amounts, both inflows @@ -8404,7 +8519,12 @@ Here are some ways to handle that: .IP \[bu] 2 Hide the totals row with \f[CR]\-N/\-\-no\-total\f[R] .IP \[bu] 2 -Convert to a single currency with \f[CR]\-V\f[R] +Filter to a single currency with \f[CR]cur:\f[R] +.IP \[bu] 2 +Convert to a single currency with +\f[CR]\-V [\-\-infer\-market\-price]\f[R] +.IP \[bu] 2 +Use a more compact layout like \f[CR]\-\-layout=bare\f[R] .IP \[bu] 2 Maximize the terminal window .IP \[bu] 2 @@ -8484,7 +8604,7 @@ current valued balance minus each amount\[aq]s original cost) .IP \[bu] 2 \f[CR]\-\-count\f[R] : show the count of postings .SS Accumulation type -How amounts should accumulate across report periods. +How amounts should accumulate across a report\[aq]s subperiods/columns. Another way to say it: which time period\[aq]s postings should contribute to each cell\[aq]s calculation. It is one of: @@ -8492,7 +8612,7 @@ It is one of: \f[CR]\-\-change\f[R] : calculate with postings from column start to column end, ie \[dq]just this column\[dq]. Typically used to see revenues/expenses. -(\f[B]default for balance, incomestatement\f[R]) +(\f[B]default for balance, cashflow, incomestatement\f[R]) .IP \[bu] 2 \f[CR]\-\-cumulative\f[R] : calculate with postings from report start to column end, ie \[dq]previous columns plus this column\[dq]. @@ -8505,7 +8625,7 @@ start to column end, ie \[dq]all postings from before report start date until this column\[aq]s end\[dq]. Typically used to see historical end balances of assets/liabilities/equity. -(\f[B]default for balancesheet, balancesheetequity, cashflow\f[R]) +(\f[B]default for balancesheet, balancesheetequity\f[R]) .SS Valuation type Which kind of value or cost conversion should be applied, if any, before displaying the report. @@ -8782,48 +8902,51 @@ This means you can give your periodic rules descriptions (remember that two spaces are needed between period expression and description), and then select from multiple budgets defined in your journal. .SS Budgeting vs forecasting -\f[CR]\-\-budget\f[R] and \f[CR]\-\-forecast\f[R] both use the periodic +\f[CR]\-\-forecast\f[R] and \f[CR]\-\-budget\f[R] both use the periodic transaction rules in the journal to generate temporary transactions for reporting purposes. However they are separate features \- though you can use both at the same time if you want. Here are some differences between them: -.IP "1." 3 -\f[CR]\-\-budget\f[R] is a command\-specific option; it selects the -\f[B]budget report\f[R]. -.RS 4 -.PP -\f[CR]\-\-forecast\f[R] is a general option; \f[B]forecasting works with -all reports\f[R]. -.RE -.IP "2." 3 -\f[CR]\-\-budget\f[R] uses \f[B]all periodic rules\f[R]; -\f[CR]\-\-budget=DESCPAT\f[R] uses \f[B]just the rules matched\f[R] by -DESCPAT. -.RS 4 .PP -\f[CR]\-\-forecast\f[R] uses \f[B]all periodic rules\f[R]. -.RE -.IP "3." 3 -\f[CR]\-\-budget\f[R]\[aq]s budget goal transactions are invisible, -except that they produce \f[B]goal amounts\f[R]. -.RS 4 -.PP -\f[CR]\-\-forecast\f[R]\[aq]s forecast transactions are visible, and -\f[B]appear in reports\f[R]. -.RE -.IP "4." 3 -\f[CR]\-\-budget\f[R] generates budget goal transactions \f[B]throughout -the report period\f[R], optionally restricted by periods specified in -the periodic transaction rules. -.RS 4 -.PP -\f[CR]\-\-forecast\f[R] generates forecast transactions from \f[B]after -the last regular transaction\f[R], to the end of the report period; -while \f[CR]\-\-forecast=PERIODEXPR\f[R] generates them \f[B]throughout -the specified period\f[R]; both optionally restricted by periods -specified in the periodic transaction rules. -.RE +.TS +tab(@); +lw(38.2n) lw(31.8n). +T{ +\-\-forecast +T}@T{ +\-\-budget +T} +_ +T{ +is a general option; it enables forecasting with all reports +T}@T{ +is a balance command option; it selects the balance report\[aq]s budget +mode +T} +T{ +generates visible transactions which appear in reports +T}@T{ +generates invisible transactions which produce goal amounts +T} +T{ +generates forecast transactions from after the last regular transaction, +to the end of the report period; or with an argument +\f[CR]\-\-forecast=PERIODEXPR\f[R] generates them throughout the +specified period, both optionally restricted by periods specified in the +periodic transaction rules +T}@T{ +generates budget goal transactions throughout the report period, +optionally restricted by periods specified in the periodic transaction +rules +T} +T{ +uses all periodic rules +T}@T{ +uses all periodic rules; or with an argument +\f[CR]\-\-budget=DESCPAT\f[R] uses just the rules matched by DESCPAT +T} +.TE .SS Balance report layout The \f[CR]\-\-layout\f[R] option affects how balance reports show multi\-commodity amounts and commodity symbols, which can improve @@ -8842,8 +8965,8 @@ amounts are bare numbers \f[CR]\-\-layout=tidy\f[R]: data is normalised to easily\-consumed \[dq]tidy\[dq] form, with one row per data value .PP -Here are the \f[CR]\-\-layout\f[R] modes supported by each output -format; note only CSV output supports all of them: +Here are the \f[CR]\-\-layout\f[R] modes supported by each output format +Only CSV output supports all of them: .PP .TS tab(@); @@ -8907,10 +9030,8 @@ T} .TE .PP Examples: -.IP \[bu] 2 -Wide layout. +.SS Wide layout With many commodities, reports can be very wide: -.RS 2 .IP .EX $ hledger \-f examples/bcexample.hledger bal assets:us:etrade \-3 \-T \-Y \-\-layout=wide @@ -8922,11 +9043,8 @@ Balance changes in 2012\-01\-01..2014\-12\-31: \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- || 10.00 ITOT, 337.18 USD, 12.00 VEA, 106.00 VHT 70.00 GLD, 18.00 ITOT, \-98.12 USD, 10.00 VEA, 18.00 VHT \-11.00 ITOT, 4881.44 USD, 14.00 VEA, 170.00 VHT 70.00 GLD, 17.00 ITOT, 5120.50 USD, 36.00 VEA, 294.00 VHT .EE -.RE -.IP \[bu] 2 -Limited wide layout. +.PP A width limit reduces the width, but some commodities will be hidden: -.RS 2 .IP .EX $ hledger \-f examples/bcexample.hledger bal assets:us:etrade \-3 \-T \-Y \-\-layout=wide,32 @@ -8938,12 +9056,9 @@ Balance changes in 2012\-01\-01..2014\-12\-31: \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- || 10.00 ITOT, 337.18 USD, 2 more.. 70.00 GLD, 18.00 ITOT, 3 more.. \-11.00 ITOT, 3 more.. 70.00 GLD, 17.00 ITOT, 3 more.. .EE -.RE -.IP \[bu] 2 -Tall layout. +.SS Tall layout Each commodity gets a new line (may be different in each column), and account names are repeated: -.RS 2 .IP .EX $ hledger \-f examples/bcexample.hledger bal assets:us:etrade \-3 \-T \-Y \-\-layout=tall @@ -8963,12 +9078,9 @@ Balance changes in 2012\-01\-01..2014\-12\-31: || 106.00 VHT 10.00 VEA 170.00 VHT 36.00 VEA || 18.00 VHT 294.00 VHT .EE -.RE -.IP \[bu] 2 -Bare layout. -Commodity symbols are kept in one column, each commodity gets its own -report row, account names are repeated: -.RS 2 +.SS Bare layout +Commodity symbols are kept in one column, each commodity has its own +row, amounts are bare numbers, account names are repeated: .IP .EX $ hledger \-f examples/bcexample.hledger bal assets:us:etrade \-3 \-T \-Y \-\-layout=bare @@ -8988,11 +9100,9 @@ Balance changes in 2012\-01\-01..2014\-12\-31: || VEA 12.00 10.00 14.00 36.00 || VHT 106.00 18.00 170.00 294.00 .EE -.RE -.IP \[bu] 2 +.PP Bare layout also affects CSV output, which is useful for producing data that is easier to consume, eg for making charts: -.RS 2 .IP .EX $ hledger \-f examples/bcexample.hledger bal assets:us:etrade \-3 \-O csv \-\-layout=bare @@ -9008,22 +9118,18 @@ $ hledger \-f examples/bcexample.hledger bal assets:us:etrade \-3 \-O csv \-\-la \[dq]total\[dq],\[dq]VEA\[dq],\[dq]36.00\[dq] \[dq]total\[dq],\[dq]VHT\[dq],\[dq]294.00\[dq] .EE -.RE -.IP \[bu] 2 -Note: bare layout will sometimes display an extra row for the no\-symbol +.PP +Bare layout will sometimes display an extra row for the no\-symbol commodity, because of zero amounts (hledger treats zeroes as commodity\-less, usually). This can break \f[CR]hledger\-bar\f[R] confusingly (workaround: add a \f[CR]cur:\f[R] query to exclude the no\-symbol row). -.IP \[bu] 2 -Tidy layout produces normalised \[dq]tidy data\[dq], where every -variable has its own column and each row represents a single data point. -See -https://cran.r\-project.org/web/packages/tidyr/vignettes/tidy\-data.html -for more. -This is the easiest kind of data for other software to consume. -Here\[aq]s how it looks: -.RS 2 +.SS Tidy layout +This produces normalised \[dq]tidy data\[dq] (see +https://cran.r\-project.org/web/packages/tidyr/vignettes/tidy\-data.html) +where every variable has its own column and each row represents a single +data point. +This is the easiest kind of data for other software to consume: .IP .EX $ hledger \-f examples/bcexample.hledger bal assets:us:etrade \-3 \-Y \-O csv \-\-layout=tidy @@ -9044,8 +9150,7 @@ $ hledger \-f examples/bcexample.hledger bal assets:us:etrade \-3 \-Y \-O csv \- \[dq]Assets:US:ETrade\[dq],\[dq]2014\[dq],\[dq]2014\-01\-01\[dq],\[dq]2014\-12\-31\[dq],\[dq]VEA\[dq],\[dq]14.00\[dq] \[dq]Assets:US:ETrade\[dq],\[dq]2014\[dq],\[dq]2014\-01\-01\[dq],\[dq]2014\-12\-31\[dq],\[dq]VHT\[dq],\[dq]170.00\[dq] .EE -.RE -.SS Useful balance reports +.SS Some useful balance reports Some frequently used \f[CR]balance\f[R] options/reports are: .IP \[bu] 2 \f[CR]bal \-M revenues expenses\f[R] @@ -9492,6 +9597,11 @@ previous balances in an opening transaction. These provide useful error checking, but you can ignore them temporarily with \f[CR]\-I\f[R], or remove them if you prefer. .PP +Single\-commodity, subaccount\-exclusive balance assertions +(\f[CR]=\f[R]) are generated by default. +This can be changed with \f[CR]\-\-assertion\-type=\[aq]==*\[aq]\f[R] +(eg). +.PP When running \f[CR]close\f[R] you should probably avoid using \f[CR]\-C\f[R], \f[CR]\-R\f[R], \f[CR]status:\f[R] (filtering by status or realness) or \f[CR]\-\-auto\f[R] (generating postings), since the @@ -9756,51 +9866,58 @@ files to your main journal, you will run .PP Note you can import from any file format, though CSV files are the most common import source, and these docs focus on that case. -.SS Deduplication -\f[CR]import\f[R] does \f[I]time\-based deduplication\f[R], to detect -only the new transactions since the last successful import. -(This does not mean \[dq]ignore transactions that look the same\[dq], -but rather \[dq]ignore transactions that have been seen before\[dq].) -This is intended for when you are periodically importing downloaded -data, which may overlap with previous downloads. -Eg if every week (or every day) you download a bank\[aq]s last three -months of CSV data, you can safely run -\f[CR]hledger import thebank.csv\f[R] each time and only new -transactions will be imported. -.PP -Since the items being read (CSV records, eg) often do not come with -unique identifiers, hledger detects new transactions by date, assuming -that: +.SS \[dq]Deduplication\[dq] +\f[CR]import\f[R] tries to import only the transactions which are new +since the last import. +So if your bank\[aq]s CSV includes the last three months of data, you +can download and \f[CR]import\f[R] it every month (or week, or day) and +only the new transactions will be imported each time. +.PP +It works as follows. +For each imported \f[CR]FILE\f[R] (usually a CSV file): \- It tries to +find the latest date seen previously, by reading it from a hidden +\f[CR].latest.FILE\f[R] in the same directory. +\- Then it processes \f[CR]FILE\f[R], ignoring any transactions on or +before the \[dq]latest seen\[dq] date. +.PP +And after a successful import, it updates the \f[CR].latest.FILE\f[R](s) +for next time (unless \f[CR]\-\-dry\-run\f[R] was used). +.PP +This is simple but fairly effective. +It assumes: .IP "1." 3 new items always have the newest dates .IP "2." 3 -item dates do not change across reads +item dates are stable across successive CSV downloads .IP "3." 3 -and items with the same date remain in the same relative order across -reads. -.PP -These are often true of CSV files representing transactions, or true -enough so that it works pretty well in practice. -1 is important, but violations of 2 and 3 amongst the old transactions -won\[aq]t matter (and if you import often, the new transactions will be -few, so less likely to be the ones affected). -.PP -hledger remembers the latest date processed in each input file by saving -a hidden \[dq].latest.FILE\[dq] file in FILE\[aq]s directory (after a -succesful import). -.PP -Eg when reading \f[CR]finance/bank.csv\f[R], it will look for and update -the \f[CR]finance/.latest.bank.csv\f[R] state file. -The format is simple: one or more lines containing the same ISO\-format -date (YYYY\-MM\-DD), meaning \[dq]I have processed transactions up to -this date, and this many of them on that date.\[dq] Normally you -won\[aq]t see or manipulate these state files yourself. -But if needed, you can delete them to reset the state (making all -transactions \[dq]new\[dq]), or you can construct them to \[dq]catch -up\[dq] to a certain date. -.PP -Note deduplication (and updating of state files) can also be done by -\f[CR]print \-\-new\f[R], but this is less often used. +the order of same\-date items is stable across CSV downloads +.PP +These are true of most CSV files representing transactions, or true +enough. +If you have a bank whose CSV dates or ordering occasionally changes, you +can reduce the chance of this happening in new transactions by importing +more often (and in old transactions it doesn\[aq]t matter). +.PP +Note, \f[CR]import\f[R] avoids reprocessing the same dates across +successive runs, but it does not detect transactions that are duplicated +within a single run. +So eg if you downloaded but did not import \f[CR]bank.1.csv\f[R], and +later downloaded \f[CR]bank.2.csv\f[R] with overlapping data, you should +not import both of them in a single run +(\f[CR]hledger import bank.1.csv bank.2.csv\f[R]); instead, import them +one at a time (\f[CR]hledger import bank.1.csv\f[R], then +\f[CR]hledger import bank.2.csv\f[R]). +.PP +Normally you can ignore the \f[CR].latest.*\f[R] files, but if needed, +you can delete them (to make all transactions unseen), or +construct/modify them (to catch up to a certain date). +The format is just a single ISO\-format date (\f[CR]YYYY\-MM\-DD\f[R]), +possibly repeated on multiple lines. +It means \[dq]I have seen transactions up to this date, and this many of +them occurring on that date\[dq]. +.PP +(\f[CR]hledger print \-\-new\f[R] also uses and updates these +\f[CR].latest.*\f[R] files, but it is not often used.) .PP Related: CSV > Working with CSV > Deduplicating, importing. .SS Import testing @@ -10637,40 +10754,51 @@ both metrics .SS stats Show journal and performance statistics. .PP -The stats command displays summary information for the whole journal, or -a matched part of it. +The stats command shows summary information for the whole journal, or a +matched part of it. With a reporting interval, it shows a report for each report period. .PP -At the end, it shows (in the terminal) the overall run time and number -of transactions processed per second. -Note these are approximate and will vary based on machine, current load, -data size, hledger version, haskell lib versions, GHC version.. -but they may be of interest. +The default output is fairly impersonal, though it reveals the main file +name. +With \f[CR]\-v/\-\-verbose\f[R], more details are shown, like file +paths, included files, and commodity names. +.PP +It also shows some run time statistics: +.IP \[bu] 2 +elapsed time +.IP \[bu] 2 +throughput: the number of transactions processed per second +.IP \[bu] 2 +live: the peak memory in use by the program to do its work +.IP \[bu] 2 +alloc: the peak memory allocation from the OS as seen by GHC. +Measuring this externally, eg with GNU time, is more accurate; usually +that will be a larger number; sometimes (with swapping?) +smaller. +.PP The \f[CR]stats\f[R] command\[aq]s run time is similar to that of a -single\-column balance report. +balance report. .PP Example: .IP .EX -$ hledger stats \-f examples/1000x1000x10.journal -Main file : /Users/simon/src/hledger/examples/1000x1000x10.journal -Included files : -Transactions span : 2000\-01\-01 to 2002\-09\-27 (1000 days) -Last transaction : 2002\-09\-26 (6995 days ago) -Transactions : 1000 (1.0 per day) -Transactions last 30 days: 0 (0.0 per day) -Transactions last 7 days : 0 (0.0 per day) -Payees/descriptions : 1000 -Accounts : 1000 (depth 10) -Commodities : 26 (A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P, Q, R, S, T, U, V, W, X, Y, Z) -Market prices : 1000 (A) - -Run time : 0.12 s -Throughput : 8342 txns/s +$ hledger stats \-f examples/1ktxns\-1kaccts.journal +Main file : .../1ktxns\-1kaccts.journal +Included files : 0 +Txns span : 2000\-01\-01 to 2002\-09\-27 (1000 days) +Last txn : 2002\-09\-26 (7827 days ago) +Txns : 1000 (1.0 per day) +Txns last 30 days : 0 (0.0 per day) +Txns last 7 days : 0 (0.0 per day) +Payees/descriptions : 1000 +Accounts : 1000 (depth 10) +Commodities : 26 +Market prices : 1000 +Runtime stats : 0.12 s elapsed, 8266 txns/s, 4 MB live, 16 MB alloc .EE .PP This command supports the \-o/\-\-output\-file option (but not -\-O/\-\-output\-format selection). +\-O/\-\-output\-format). .SS tags List the tags used in the journal, or their values. .PP diff --git a/hledger/hledger.info b/hledger/hledger.info index 001a914dcaf..786ea203536 100644 --- a/hledger/hledger.info +++ b/hledger/hledger.info @@ -70,12 +70,14 @@ https://hledger.org/editors.html). To get started, run 'hledger add' and follow the prompts, or save some entries like the above in '$HOME/.hledger.journal', then try commands like: -'hledger print -x' -'hledger aregister assets' -'hledger balance' -'hledger balancesheet' -'hledger incomestatement'. -Run 'hledger' to list the commands. See also the "Starting a journal + +$ hledger print -x +$ hledger aregister assets +$ hledger balance +$ hledger balancesheet +$ hledger incomestatement + + Run 'hledger' to list the commands. See also the "Starting a journal file" and "Setting opening balances" sections in PART 5: COMMON TASKS. * Menu: @@ -93,7 +95,7 @@ file" and "Setting opening balances" sections in PART 5: COMMON TASKS. * Timeclock:: * Timedot:: * PART 3 REPORTING CONCEPTS:: -* Amount formatting parseability:: +* Amount formatting:: * Time periods:: * Depth:: * Queries:: @@ -141,15 +143,32 @@ see Common tasks > Setting LEDGER_FILE. * Menu: +* Text encoding:: * Data formats:: * Standard input:: * Multiple files:: * Strict mode::  -File: hledger.info, Node: Data formats, Next: Standard input, Up: Input +File: hledger.info, Node: Text encoding, Next: Data formats, Up: Input + +2.1 Text encoding +================= + +Data files containing non-ascii characters must use UTF-8 encoding. +Also, your system should be configured with a locale that can decode +UTF-8 text. On some unix systems, you may need set the 'LANG' +environment variable, eg. You can read more about this in Unicode +characters, below. + + On unix systems you can check a file's encoding with the 'file' +command. If you need to import from a UTF-16-encoded CSV file, say, you +can convert it to UTF-8 with the 'iconv' command. + + +File: hledger.info, Node: Data formats, Next: Standard input, Prev: Text encoding, Up: Input -2.1 Data formats +2.2 Data formats ================ Usually the data file is in hledger's journal format, but it can be in @@ -190,7 +209,7 @@ $ hledger -f tsv:/some/file.dat stats  File: hledger.info, Node: Standard input, Next: Multiple files, Prev: Data formats, Up: Input -2.2 Standard input +2.3 Standard input ================== The file name '-' means standard input: @@ -205,7 +224,7 @@ $ echo 'i 2009/13/1 08:00:00' | hledger print -f timeclock:-  File: hledger.info, Node: Multiple files, Next: Strict mode, Prev: Standard input, Up: Input -2.3 Multiple files +2.4 Multiple files ================== You can specify multiple '-f' options, to read multiple files as one big @@ -224,7 +243,7 @@ a.journal b.journal | hledger -f- CMD'.  File: hledger.info, Node: Strict mode, Prev: Multiple files, Up: Input -2.4 Strict mode +2.5 Strict mode =============== hledger checks input files for valid data. By default, the most @@ -954,10 +973,8 @@ $ hledger print -c '$1.000,0' commodities/currencies. Its argument is as described in the commodity directive. - hledger will occasionally make some additional adjustments to number -formatting, eg adding a trailing decimal mark to disambiguate numbers -with digit group marks; for details, see Amount formatting, -parseability. + In some cases hledger will adjust number formatting to improve their +parseability (such as adding trailing decimal marks when needed).  File: hledger.info, Node: Colour, Next: Box-drawing, Prev: Commodity styles, Up: Output @@ -1061,13 +1078,44 @@ File: hledger.info, Node: Journal, Next: CSV, Prev: PART 2 DATA FORMATS, Up: 9 Journal ********* -hledger's default file format, representing a General Journal. Here's a -cheatsheet/mini-tutorial, or you can skip ahead to About journal format. +hledger's usual data source is a plain text file containing journal +entries in hledger 'journal' format. If you're looking for a quick +reference, jump ahead to the journal cheatsheet (or use the table of +contents at https://hledger.org/hledger.html). + + This file represents an accounting General Journal. The '.journal' +file extension is most often used, though not strictly required. The +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 compatible with most of Ledger's journal +format, but not all of it. The differences and interoperation tips are +described at hledger and Ledger. With some care, and by avoiding +incompatible features, you can keep your hledger journal readable by +Ledger and vice versa. This can useful eg for comparing the behaviour +of one app against the other. + + You can use hledger without learning any more about this file; just +use the add or web or import commands to create and update it. + + Many users, though, edit the journal file with a text editor, and +track changes with a version control system such as git. Editor addons +such as ledger-mode or hledger-mode for Emacs, vim-ledger for Vim, and +hledger-vscode for Visual Studio Code, make this easier, adding colour, +formatting, tab completion, and useful commands. See Editor +configuration at hledger.org for the full list. + + A hledger journal file can contain three kinds of thing: comment +lines, transactions, and/or directives (including periodic transaction +rules and auto posting rules). Understanding the journal file format +will also give you a good understanding of hledger's data model. Here's +a quick cheatsheet/overview, followed by detailed descriptions of each +part. * Menu: * Journal cheatsheet:: -* About journal format:: * Comments:: * Transactions:: * Dates:: @@ -1078,9 +1126,9 @@ cheatsheet/mini-tutorial, or you can skip ahead to About journal format. * Postings:: * Account names:: * Amounts:: -* Costs:: * Balance assertions:: * Posting comments:: +* Transaction balancing:: * Tags:: * Directives:: * account directive:: @@ -1096,141 +1144,143 @@ cheatsheet/mini-tutorial, or you can skip ahead to About journal format. * Other syntax::  -File: hledger.info, Node: Journal cheatsheet, Next: About journal format, Up: Journal +File: hledger.info, Node: Journal cheatsheet, Next: Comments, Up: Journal 9.1 Journal cheatsheet ====================== # Here is the main syntax of hledger's journal format # (omitting extra Ledger compatibility syntax). -# hledger journals contain comments, directives, and transactions, in any order: ############################################################################### -# 1. Comment lines are for notes or temporarily disabling things. -# They begin with #, ;, or a line containing the word "comment". -# hash comment line -; semicolon comment line +# 1. These are comment lines, for notes or temporarily disabling things. +; They begin with # or ; + comment -These lines -are commented. +Or, lines can be enclosed within "comment" / "end comment". +This is a block of +commented lines. end comment -# Some but not all hledger entries can have same-line comments attached to them, -# from ; (semicolon) to end of line. +# Some journal entries can have semicolon comments at end of line ; like this +# Some of them require 2 or more spaces before the semicolon. ############################################################################### -# 2. Directives modify parsing or reports in some way. -# They begin with a word or letter (or symbol). -account actifs ; type:A, declare an account that is an Asset. 2+ spaces before ;. -account passifs ; type:L, declare an account that is a Liability, and so on.. (ALERX) -alias chkg = assets:checking -commodity $0.00 -decimal-mark . -include /dev/null -payee Whole Foods -P 2022-01-01 AAAA $1.40 -~ monthly budget goals ; <- 2+ spaces between period expression and description - expenses:food $400 - expenses:home $1000 - budgeted +# 2. Directives customise processing or output in some way. +# You don't need any directives to get started. +# But they can add more error checking, or change how things are displayed. +# They begin with a word, letter, or symbol. +# They are most often placed at the top, before transactions. + +account assets ; Declare valid account names and display order. +account assets:savings ; A subaccount. This one represents a bank account. +account assets:checking ; Another. Note, 2+ spaces after the account name. +account assets:receivable ; Accounting type is inferred from english names, +account passifs ; or declared with a "type" tag, type:L +account expenses ; type:X + ; A follow-on comment line, indented. +account expenses:rent ; Expense and revenue categories are also accounts. + ; Subaccounts inherit their parent's type. + +commodity $0.00 ; Declare valid commodities and their display styles. +commodity 1.000,00 EUR -############################################################################### -# 3. Transactions are what it's all about; they are dated events, -# usually describing movements of money. -# They begin with a date. - -# DATE DESCRIPTION ; This is a transaction comment. -# ACCOUNT NAME 1 AMOUNT1 ; <- posting 1. This is a posting comment. -# ACCOUNT NAME 2 AMOUNT2 ; <- posting 2. Postings must be indented. -# ; ^^ At least 2 spaces between account and amount. -# ... ; Any number of postings is allowed. The amounts must balance (sum to 0). - -2022-01-01 opening balances are declared this way - assets:checking $1000 ; Account names can be anything. lower case is easy to type. - assets:savings $1000 ; assets, liabilities, equity, revenues, expenses are common. - assets:cash:wallet $100 ; : indicates subaccounts. - liabilities:credit card $-200 ; liabilities, equity, revenues balances are usually negative. - equity ; One amount can be left blank; $-1900 is inferred here. - -2022-04-15 * (#12345) pay taxes - ; There can be a ! or * after the date meaning "pending" or "cleared". - ; There can be a transaction code (text in parentheses) after the date/status. - ; Amounts' sign represents direction of flow, or credit/debit: - assets:checking $-500 ; minus means removed from this account (credit) - expenses:tax:us:2021 $500 ; plus means added to this account (debit) - ; revenue/expense categories are also "accounts" - -2022-01-01 ; The description is optional. - ; Any currency/commodity symbols are allowed, on either side. - assets:cash:wallet GBP -10 - expenses:clothing GBP 10 - assets:gringotts -10 gold - assets:pouch 10 gold - revenues:gifts -2 "Liquorice Wands" ; Complex symbols - assets:bag 2 "Liquorice Wands" ; must be double-quoted. - -2022-01-01 Cost in another commodity can be noted with @ or @@ - assets:investments 2.0 AAAA @ $1.50 ; @ means per-unit cost - assets:investments 3.0 AAAA @@ $4 ; @@ means total cost - assets:checking $-7.00 - -2022-01-02 assert balances - ; Balances can be asserted for extra error checking, in any transaction. - assets:investments 0 AAAA = 5.0 AAAA - assets:pouch 0 gold = 10 gold - assets:savings $0 = $1000 - -1999-12-31 Ordering transactions by date is recommended but not required. - ; Postings are not required. +decimal-mark . ; The decimal mark used in this file (if ambiguous). -2022.01.01 These date -2022/1/1 formats are -12/31 also allowed (but consistent YYYY-MM-DD is recommended). +payee Whole Foods ; Declare a valid payee name. - -File: hledger.info, Node: About journal format, Next: Comments, Prev: Journal cheatsheet, Up: Journal +tag trip ; Declare a valid tag name. -9.2 About journal format -======================== +P 2024-03-01 AAPL $179 ; Declare a market price for AAPL in $ on this date. -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 -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. +include other.journal ; Include another journal file here. - hledger's journal format is compatible with most of Ledger's journal -format, but not all of it. The differences and interoperation tips are -described at hledger and Ledger. With some care, and by avoiding -incompatible features, you can keep your hledger journal readable by -Ledger and vice versa. This can useful eg for comparing the behaviour -of one app against the other. +# Declare a recurring "periodic transaction", for budget/forecast reports +~ monthly set budget goals ; <- Note, 2+ spaces before the description. + (expenses:rent) $1000 + (expenses:food) $500 - You can use hledger without learning any more about this file; just -use the add or web or import commands to create and update it. +# Declare an auto posting rule, to modify existing transactions in reports += revenues:consulting + liabilities:tax:2024:us *0.25 ; Add a tax liability & expense + expenses:tax:2024:us *-0.25 ; for 25% of the revenue. - Many users, though, edit the journal file with a text editor, and -track changes with a version control system such as git. Editor addons -such as ledger-mode or hledger-mode for Emacs, vim-ledger for Vim, and -hledger-vscode for Visual Studio Code, make this easier, adding colour, -formatting, tab completion, and useful commands. See Editor -configuration at hledger.org for the full list. +############################################################################### - Here's a description of each part of the file format (and hledger's -data model). +# 3. Transactions are what it's all about. +# They are dated events, usually movements of money between 2 or more accounts. +# They begin with a numeric date. +# Here is their basic shape: +# +# DATE DESCRIPTION ; The transaction's date and optional description. +# ACCOUNT1 AMOUNT ; A posting of an amount to/from this account, indented. +# ACCOUNT2 AMOUNT ; A second posting, balancing the first. +# ... ; More if needed. Amounts must sum to zero. +# ; Note, 2+ spaces between account names and amounts. + +2024-01-01 opening balances ; At the start, declare pre-existing balances this way. + assets:savings $10000 ; Account names can be anything. lower case is easy to type. + assets:checking $1000 ; assets, liabilities, equity, revenues, expenses are common. + liabilities:credit card $-500 ; liabilities, equity, revenues balances are usually negative. + equity:start ; One amount can be left blank. $-10500 is inferred here. + ; Some of these accounts we didn't declare above, + ; so -s/--strict would complain. + +2024-01-03 ! (12345) pay rent + ; Additional transaction comment lines, indented. + ; There can be a ! or * after the date meaning "pending" or "cleared". + ; There can be a parenthesised (code) after the date/status. + ; Amounts' sign shows direction of flow. + assets:checking $-500 ; Minus means removed from this account (credit). + expenses:rent $500 ; Plus means added to this account (debit). + +; Keeping transactions in date order is optional (but helps error checking). + +2024-01-02 Gringott's Bank | withdrawal ; Description can be PAYEE | NOTE + assets:bank:gold -10 gold + assets:pouch 10 gold + +2024-01-02 shopping + expenses:clothing 1 gold + expenses:wands 5 gold + assets:pouch -6 gold + +2024-01-02 receive gift + revenues:gifts -3 "Chocolate Frogs" ; Complex commodity symbols + assets:pouch 3 "Chocolate Frogs" ; must be in double quotes. + +2024-01-15 buy some shares, in two lots ; Cost can be noted. + assets:investments:2024-01-15 2.0 AAAA @ $1.50 ; @ means per-unit cost + assets:investments:2024-01-15-02 3.0 AAAA @@ $4 ; @@ means total cost + ; ^ Per-lot subaccounts are sometimes useful. + assets:checking $-7 + +2024-01-15 assert some account balances on this date + ; Balances can be asserted in any transaction, with =, for extra error checking. + ; Assertion txns like this one can be made with hledger close --assert --show-costs + ; + assets:savings $0 = $10000 + assets:checking $0 = $493 + assets:bank:gold 0 gold = -10 gold + assets:pouch 0 gold = 4 gold + assets:pouch 0 "Chocolate Frogs" = 3 "Chocolate Frogs" + assets:investments:2024-01-15 0.0 AAAA = 2.0 AAAA @ $1.50 + assets:investments:2024-01-15-02 0.0 AAAA = 3.0 AAAA @@ $4 + liabilities:credit card $0 = $-500 + +2024-02-01 note some event, or a transaction not yet fully entered, on this date + ; Postings are not required. - A hledger journal file can contain three kinds of thing: file -comments, transactions, and/or directives (counting periodic transaction -rules and auto posting rules as directives). +; Some other date formats are allowed (but, consistent YYYY-MM-DD is useful). +2024.01.01 +2024/1/1  -File: hledger.info, Node: Comments, Next: Transactions, Prev: About journal format, Up: Journal +File: hledger.info, Node: Comments, Next: Transactions, Prev: Journal cheatsheet, Up: Journal -9.3 Comments +9.2 Comments ============ Lines in the journal will be ignored if they begin with a hash ('#') or @@ -1260,7 +1310,7 @@ comments, and Account comments below.  File: hledger.info, Node: Transactions, Next: Dates, Prev: Comments, Up: Journal -9.4 Transactions +9.3 Transactions ================ Transactions are the main unit of information in a journal file. They @@ -1289,7 +1339,7 @@ optional fields, separated by spaces:  File: hledger.info, Node: Dates, Next: Status, Prev: Transactions, Up: Journal -9.5 Dates +9.4 Dates ========= * Menu: @@ -1300,7 +1350,7 @@ File: hledger.info, Node: Dates, Next: Status, Prev: Transactions, Up: Journ  File: hledger.info, Node: Simple dates, Next: Posting dates, Up: Dates -9.5.1 Simple dates +9.4.1 Simple dates ------------------ Dates in the journal file use _simple dates_ format: 'YYYY-MM-DD' or @@ -1316,7 +1366,7 @@ dates documented in the hledger manual.)  File: hledger.info, Node: Posting dates, Prev: Simple dates, Up: Dates -9.5.2 Posting dates +9.4.2 Posting dates ------------------- You can give individual postings a different date from their parent @@ -1344,12 +1394,12 @@ a 'date:' tag with no value is not allowed.  File: hledger.info, Node: Status, Next: Code, Prev: Dates, Up: Journal -9.6 Status +9.5 Status ========== -Transactions, or individual postings within a transaction, can have a +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, +description (or posting account name), separated from it by a space, indicating one of three statuses: mark status @@ -1360,15 +1410,13 @@ mark status '*' cleared 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. +'-P/--pending', and '-C/--cleared' flags (and you can combine these, eg +'-UP' to match all except cleared things). Or you can use the +'status:', 'status:!', and 'status:*' queries, or the U, P, C keys in +hledger-ui. - To replicate Ledger and old hledger's behaviour of also matching -pending, combine -U and -P. + (Note: in Ledger the "unmarked" state is called "uncleared"; in +hledger we renamed it to "unmarked" for semantic clarity.) Status marks are optional, but can be helpful eg for reconciling with real-world accounts. Some editor modes provide highlighting and @@ -1394,7 +1442,7 @@ your finances.  File: hledger.info, Node: Code, Next: Description, Prev: Status, Up: Journal -9.7 Code +9.6 Code ======== After the status mark, but before the description, you can optionally @@ -1405,7 +1453,7 @@ or reference number.  File: hledger.info, Node: Description, Next: Transaction comments, Prev: Code, Up: Journal -9.8 Description +9.7 Description =============== After the date, status mark and/or code fields, the rest of the line (or @@ -1427,7 +1475,7 @@ description with '--pivot desc'.  File: hledger.info, Node: Payee and note, Up: Description -9.8.1 Payee and note +9.7.1 Payee and note -------------------- Sometimes people want a dedicated payee/payer field that can be queried @@ -1445,15 +1493,15 @@ distinct. (If you'd like to change this behaviour, please propose it on the mail list.) If you want more strict error checking, you can declare the valid -payee names with 'payee' directives, and then enforce these with -'hledger check payees'. Note: because of the above, for this you'll -need to ensure every transaction description contains a '|' and -therefore a checkable payee name (even if it's empty). +payee names with payee directives, and then enforce these with hledger +check payees. (Note: because of the above, for this you'll need to +ensure every transaction description contains a '|' and therefore a +checkable payee name, even if it's empty.)  File: hledger.info, Node: Transaction comments, Next: Postings, Prev: Description, Up: Journal -9.9 Transaction comments +9.8 Transaction comments ======================== Text following ';', after a transaction description, and/or on indented @@ -1469,8 +1517,8 @@ tags, which are not ignored.  File: hledger.info, Node: Postings, Next: Account names, Prev: Transaction comments, Up: Journal -9.10 Postings -============= +9.9 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 @@ -1480,24 +1528,59 @@ tab (2 or 4 spaces is common), followed by: space * (required) an account name (any text, optionally containing *single spaces*, until end of line or a double space) - * (optional) *two or more spaces* or tabs followed by an amount. + * (optional) *two or more spaces* (or tabs) followed by an amount. + + If the amount is positive, it is being added to the account; if +negative, it is being removed from the account. + + The posting amounts in a transaction must sum up to zero, indicating +that the inflows and outflows are equal. We call this a balanced +transaction. (You can read more about the nitty-gritty details of "sum +up to zero" in Transaction balancing below.) + + As a convenience, you can optionally leave one amount blank; hledger +will infer what it should be so as to balance the transaction. + +* Menu: + +* Debits and credits:: +* The two space delimiter:: + + +File: hledger.info, Node: Debits and credits, Next: The two space delimiter, Up: Postings - Positive amounts are being added to the account, negative amounts are -being removed. +9.9.1 Debits and credits +------------------------ + +The traditional accounting concepts of debit and credit of course exist +in hledger, but we represent them with numeric sign, as described above. +Positive and negative posting amounts represent debits and credits +respectively. + + You don't need to remember that, but if you would like to - eg for +helping newcomers or for talking with your accountant - here's a handy +mnemonic: + + _'debit / plus / left / short words'_ +_'credit / minus / right / longer words'_ + + +File: hledger.info, Node: The two space delimiter, Prev: Debits and credits, Up: Postings - The amounts within a transaction must always sum up to zero. As a -convenience, one amount may be left blank; it will be inferred so as to -balance the transaction. +9.9.2 The two space delimiter +----------------------------- - Be sure to note the unusual two-space delimiter between account name -and amount. This makes it easy to write account names containing -spaces. But if you accidentally leave only one space (or tab) before -the amount, the amount will be considered part of the account name. +Be sure to notice the unusual separator between the account name and the +following amount. Because hledger allows account names with spaces in +them, you must separate the account name and amount (if any) by *two or +more spaces* (or tabs). It's easy to forget at first. If you ever see +the amount being treated as part of the account name, you'll know you +probably need to add another space between them.  File: hledger.info, Node: Account names, Next: Amounts, Prev: Postings, Up: Journal -9.11 Account names +9.10 Account names ================== Accounts are the main way of categorising things in hledger. As in @@ -1546,13 +1629,13 @@ the account name have no special meaning. aliases.  -File: hledger.info, Node: Amounts, Next: Costs, Prev: Account names, Up: Journal +File: hledger.info, Node: Amounts, Next: Balance assertions, Prev: Account names, Up: Journal -9.12 Amounts +9.11 Amounts ============ -After the account name, there is usually an amount. (Important: between -account name and amount, there must be *two or more spaces*.) +After the account name, there is usually an amount. (Remember: between +account name and amount, there must be two or more spaces.) hledger's amount format is flexible, supporting several international formats. Here are some examples. Amounts have a number (the @@ -1588,47 +1671,65 @@ EUR 1E3 * Menu: -* Decimal marks digit group marks:: +* Decimal marks:: +* Digit group marks:: * Commodity:: -* Directives influencing number parsing and display:: -* Commodity display style:: -* Rounding:: -* Number format:: +* Costs::  -File: hledger.info, Node: Decimal marks digit group marks, Next: Commodity, Up: Amounts +File: hledger.info, Node: Decimal marks, Next: Digit group marks, Up: Amounts -9.12.1 Decimal marks, digit group marks ---------------------------------------- +9.11.1 Decimal marks +-------------------- A _decimal mark_ can be written as a period or a comma: 1.23 1,23 - In the integer part of the quantity (left of the decimal mark), + Both of these are common in international number formats, so hledger +is not biased towards one or the other. Because hledger also supports +digit group marks (eg thousands separators), this means that a number +like '1,000' or '1.000' containing just one period or comma is +ambiguous. In such cases, hledger by default assumes it is a decimal +mark, and will parse both of those as 1. + + To help hledger parse such ambiguous numbers more accurately, if you +use digit group marks, we recommend declaring the decimal mark +explicitly. The best way is to add a 'decimal-mark' directive at the +top of each data file, like this: + +decimal-mark . + + Or you can declare it per commodity with 'commodity' directives, +described below. + + hledger also accepts numbers like '10.' with no digits after the +decimal mark (and will sometimes display numbers that way to +disambiguate them - see Trailing decimal marks). + + +File: hledger.info, Node: Digit group marks, Next: Commodity, Prev: Decimal marks, Up: Amounts + +9.11.2 Digit group marks +------------------------ + +In the integer part of the amount quantity (left of the decimal mark), groups of digits can optionally be separated by a _digit group mark_ - a -space, comma, or period (different from the decimal mark): +comma or period (whichever is not used as decimal mark), or a space +(several Unicode space variants, like no-break space, are also +accepted). So these are all valid amounts in a journal file: $1,000,000.00 EUR 2.000.000,00 INR 9,99,99,999.00 - 1 000 000.9455 - - hledger is not biased towards period or comma decimal marks, so a -number containing just one period or comma, like '1,000' or '1.000', is -ambiguous. In such cases hledger assumes it is a decimal mark, parsing -both of these as 1. - - To disambiguate these and ensure accurate number parsing, especially -if you use digit group marks, we recommend declaring the decimal mark. -You can declare it for each file with 'decimal-mark' directives, or for -each commodity with 'commodity' directives (described below). + 1 000 000.00 ; <- ordinary space + 1 000 000.00 ; <- no-break space  -File: hledger.info, Node: Commodity, Next: Directives influencing number parsing and display, Prev: Decimal marks digit group marks, Up: Amounts +File: hledger.info, Node: Commodity, Next: Costs, Prev: Digit group marks, Up: Amounts -9.12.2 Commodity +9.11.3 Commodity ---------------- Amounts in hledger have both a "quantity", which is a signed decimal @@ -1648,94 +1749,15 @@ the time. A multi-commodity amount could be, eg: '1 USD, 2 EUR, 3.456 TSLA'. In practice, you will only see multi-commodity amounts in hledger's output; you can't write them directly in the journal file. - (If you are writing scripts or working with hledger's internals, -these are the 'Amount' and 'MixedAmount' types.) - - -File: hledger.info, Node: Directives influencing number parsing and display, Next: Commodity display style, Prev: Commodity, Up: Amounts - -9.12.3 Directives influencing number parsing and display --------------------------------------------------------- - -You can add 'decimal-mark' and 'commodity' directives to the journal, to -declare and control these things more explicitly and precisely. These -are described below, but here's a quick example: - -# the decimal mark character used by all amounts in this file (all commodities) -decimal-mark . - -# display styles for the $, EUR, INR and no-symbol commodities: -commodity $1,000.00 -commodity EUR 1.000,00 -commodity INR 9,99,99,999.00 -commodity 1 000 000.9455 - - -File: hledger.info, Node: Commodity display style, Next: Rounding, Prev: Directives influencing number parsing and display, Up: Amounts - -9.12.4 Commodity display style ------------------------------- - -For the amounts in each commodity, hledger chooses a consistent display -style (symbol placement, decimal mark and digit group marks, number of -decimal digits) to use in most reports. This is inferred as follows: - - First, if there's a 'D' directive declaring a default commodity, that -commodity symbol and amount format is applied to all no-symbol amounts -in the journal. - - Then each commodity's display style is determined from its -'commodity' directive. We recommend always declaring commodities with -'commodity' directives, since they help ensure consistent display styles -and precisions, and bring other benefits such as error checking for -commodity symbols. - - But if a 'commodity' directive is not present, hledger infers a -commodity's display styles from its amounts as they are written in the -journal (excluding cost amounts and amounts in periodic transaction -rules or auto posting rules). It uses - - * the symbol placement and decimal mark of the first amount seen - * the digit group marks of the first amount with digit group marks - * and the maximum number of decimal digits seen across all amounts. - - And as fallback if no applicable amounts are found, it would use a -default style, like '$1000.00' (symbol on the left with no space, period -as decimal mark, and two decimal digits). - - Finally, commodity styles can be overridden by the -'-c/--commodity-style' command line option. - - -File: hledger.info, Node: Rounding, Next: Number format, Prev: Commodity display style, Up: Amounts - -9.12.5 Rounding ---------------- - -Amounts are stored internally as decimal numbers with up to 255 decimal -places. They are displayed with their original journal precisions by -print and print-like reports, and rounded to their display precision -(the number of decimal digits specified by the commodity display style) -by other reports. When rounding, hledger uses banker's rounding (it -rounds to the nearest even digit). So eg 0.5 displayed with zero -decimal digits appears as "0". - - -File: hledger.info, Node: Number format, Prev: Rounding, Up: Amounts - -9.12.6 Number format --------------------- - -hledger will occasionally make some additional adjustments to number -formatting, eg adding a trailing decimal mark to disambiguate numbers -with digit group marks; for details, see Amount formatting, -parseability. + By default, the format of amounts in the journal influences how +hledger displays them in output. This is explained in Commodity display +style below.  -File: hledger.info, Node: Costs, Next: Balance assertions, Prev: Amounts, Up: Journal +File: hledger.info, Node: Costs, Prev: Commodity, Up: Amounts -9.13 Costs -========== +9.11.4 Costs +------------ After a posting amount, you can note its cost (when buying) or selling price (when selling) in another commodity, by writing either '@ @@ -1785,84 +1807,10 @@ flag; this is discussed more in the Cost reporting section. not required to be. This can be a little confusing, see discussion at -infer-market-prices: market prices from transactions. -* Menu: - -* Other cost/lot notations:: - - -File: hledger.info, Node: Other cost/lot notations, Up: Costs - -9.13.1 Other cost/lot notations -------------------------------- - -A slight digression for Ledger and Beancount users. Ledger has a number -of cost/lot-related notations: - - * '@ UNITCOST' and '@@ TOTALCOST' - * expresses a conversion rate, as in hledger - * when buying, also creates a lot than can be selected at - selling time - - * '(@) UNITCOST' and '(@@) TOTALCOST' (virtual cost) - * like the above, but also means "this cost was exceptional, - don't use it when inferring market prices". - - Currently, hledger treats the above like '@' and '@@'; the -parentheses are ignored. - - * '{=FIXEDUNITCOST}' and '{{=FIXEDTOTALCOST}}' (fixed price) - * when buying, means "this cost is also the fixed price, don't - let it fluctuate in value reports" - - * '{UNITCOST}' and '{{TOTALCOST}}' (lot price) - * can be used identically to '@ UNITCOST' and '@@ TOTALCOST', - also creates a lot - * when selling, combined with '@ ...', specifies an investment - lot by its cost basis; does not check if that lot is present - - * and related: '[YYYY/MM/DD]' (lot date) - * when buying, attaches this acquisition date to the lot - * when selling, selects a lot by its acquisition date - - * '(SOME TEXT)' (lot note) - * when buying, attaches this note to the lot - * when selling, selects a lot by its note - - Currently, hledger accepts any or all of the above in any order after -the posting amount, but ignores them. (This can break transaction -balancing.) - - For Beancount users, the notation and behaviour is different: - - * '@ UNITCOST' and '@@ TOTALCOST' - * expresses a cost without creating a lot, as in hledger - * when buying (augmenting) or selling (reducing) a lot, combined - with '{...}': documents the cost/selling price (not used for - transaction balancing) - - * '{UNITCOST}' and '{{TOTALCOST}}' - * when buying (augmenting), expresses the cost for transaction - balancing, and also creates a lot with this cost basis - attached - * when selling (reducing), - * selects a lot by its cost basis - * raises an error if that lot is not present or can not be - selected unambiguously (depending on booking method - configured) - * expresses the selling price for transaction balancing - - Currently, hledger accepts the '{UNITCOST}'/'{{TOTALCOST}}' notation -but ignores it. - - * variations: '{}', '{YYYY-MM-DD}', '{"LABEL"}', '{UNITCOST, - "LABEL"}', '{UNITCOST, YYYY-MM-DD, "LABEL"}' etc. - - Currently, hledger rejects these. -  -File: hledger.info, Node: Balance assertions, Next: Posting comments, Prev: Costs, Up: Journal +File: hledger.info, Node: Balance assertions, Next: Posting comments, Prev: Amounts, Up: Journal -9.14 Balance assertions +9.12 Balance assertions ======================= hledger supports Ledger-style balance assertions in journal files. @@ -1901,7 +1849,7 @@ does not disable balance assignments, described below).  File: hledger.info, Node: Assertions and ordering, Next: Assertions and multiple included files, Up: Balance assertions -9.14.1 Assertions and ordering +9.12.1 Assertions and ordering ------------------------------ hledger sorts an account's postings and assertions first by date and @@ -1920,7 +1868,7 @@ can assert intra-day balances.  File: hledger.info, Node: Assertions and multiple included files, Next: Assertions and multiple -f files, Prev: Assertions and ordering, Up: Balance assertions -9.14.2 Assertions and multiple included files +9.12.2 Assertions and multiple included files --------------------------------------------- Multiple files included with the 'include' directive are processed as if @@ -1936,7 +1884,7 @@ balance on that day, you'll need to put the assertion in the right file  File: hledger.info, Node: Assertions and multiple -f files, Next: Assertions and commodities, Prev: Assertions and multiple included files, Up: Balance assertions -9.14.3 Assertions and multiple -f files +9.12.3 Assertions and multiple -f files --------------------------------------- Unlike 'include', when multiple files are specified on the command line @@ -1950,7 +1898,7 @@ problems in earlier files to disrupt valid assertions in later files.  File: hledger.info, Node: Assertions and commodities, Next: Assertions and costs, Prev: Assertions and multiple -f files, Up: Balance assertions -9.14.4 Assertions and commodities +9.12.4 Assertions and commodities --------------------------------- The asserted balance must be a simple single-commodity amount, and in @@ -1998,7 +1946,7 @@ commodity into its own subaccount:  File: hledger.info, Node: Assertions and costs, Next: Assertions and subaccounts, Prev: Assertions and commodities, Up: Balance assertions -9.14.5 Assertions and costs +9.12.5 Assertions and costs --------------------------- Balance assertions ignore costs, and should normally be written without @@ -2016,7 +1964,7 @@ costs), and because balance _assignments_ do use costs (see below).  File: hledger.info, Node: Assertions and subaccounts, Next: Assertions and virtual postings, Prev: Assertions and costs, Up: Balance assertions -9.14.6 Assertions and subaccounts +9.12.6 Assertions and subaccounts --------------------------------- The balance assertions above ('=' and '==') do not count the balance @@ -2033,7 +1981,7 @@ eg:  File: hledger.info, Node: Assertions and virtual postings, Next: Assertions and auto postings, Prev: Assertions and subaccounts, Up: Balance assertions -9.14.7 Assertions and virtual postings +9.12.7 Assertions and virtual postings -------------------------------------- Balance assertions always consider both real and virtual postings; they @@ -2042,7 +1990,7 @@ are not affected by the '--real/-R' flag or 'real:' query.  File: hledger.info, Node: Assertions and auto postings, Next: Assertions and precision, Prev: Assertions and virtual postings, Up: Balance assertions -9.14.8 Assertions and auto postings +9.12.8 Assertions and auto postings ----------------------------------- Balance assertions _are_ affected by the '--auto' flag, which generates @@ -2061,7 +2009,7 @@ these. So to avoid making fragile assertions, either:  File: hledger.info, Node: Assertions and precision, Prev: Assertions and auto postings, Up: Balance assertions -9.14.9 Assertions and precision +9.12.9 Assertions and precision ------------------------------- Balance assertions compare the exactly calculated amounts, which are not @@ -2070,9 +2018,9 @@ display precision, but this will not affect balance assertions. Balance assertion failure messages show exact amounts.  -File: hledger.info, Node: Posting comments, Next: Tags, Prev: Balance assertions, Up: Journal +File: hledger.info, Node: Posting comments, Next: Transaction balancing, Prev: Balance assertions, Up: Journal -9.15 Posting comments +9.13 Posting comments ===================== Text following ';', at the end of a posting line, and/or on indented @@ -2087,9 +2035,51 @@ tags, which are not ignored. ; a second comment line for posting 2  -File: hledger.info, Node: Tags, Next: Directives, Prev: Posting comments, Up: Journal +File: hledger.info, Node: Transaction balancing, Next: Tags, Prev: Posting comments, Up: Journal + +9.14 Transaction balancing +========================== + +How exactly does hledger decide when a transaction is balanced ? The +general goal is that if you look at the journal entry and calculate the +amounts' sum perfectly with pencil and paper, hledger should agree with +you. + + Real world transactions, especially for investments or +cryptocurrencies, often involve imprecise costs, complex decimals, +and/or infinitely-recurring decimals, which are difficult or +inconvenient to handle on a computer. So to be a practical accounting +system, hledger allows some imprecision when checking transaction +balancedness. The question is, how much imprecision should be allowed ? + + hledger currently decides it based on the commodity display styles: +if the postings' sum would appear to be zero when displayed with the +standard display precisions, the transaction is considered balanced. + + Or equivalently: if the journal entry is displayed with amounts +rounded to the standard display precisions (with 'hledger print +--round=hard'), and a human with pencil and paper would agree that those +displayed amounts add up to zero, the transaction is considered +balanced. + + This has some advantages: it is fairly intuitive, general not +hard-coded, yet configurable when needed. On the downside it means that +transaction balancedness is related to commodity display precisions, so +eg when using '-c/--commodity-style' to display things with more than +usual precision, you might need to fix some of your journal entries (ie, +add decimal digits to make them balance more precisely). + + Other PTA tools (Ledger, Beancount..) have their own ways of doing +it. Possible improvements are discussed at #1964. + + Note: if you have multiple journal files, and are relying on +commodity directives to make imprecise journal entries balance, the +directives' placement might be important - see 'commodity' directive. + + +File: hledger.info, Node: Tags, Next: Directives, Prev: Transaction balancing, Up: Journal -9.16 Tags +9.15 Tags ========= Tags are a way to add extra labels or data fields to transactions, @@ -2131,7 +2121,7 @@ posting).  File: hledger.info, Node: Tag names, Next: Special tags, Up: Tags -9.16.1 Tag names +9.15.1 Tag names ---------------- Most non-whitespace characters are allowed in tag names. Eg '😀:' is a @@ -2150,13 +2140,13 @@ them with the check command.  File: hledger.info, Node: Special tags, Next: Tag values, Prev: Tag names, Up: Tags -9.16.2 Special tags +9.15.2 Special tags ------------------- Some tag names have special significance to hledger. There's not much harm in using them yourself, but some could produce an error message, -particularly the 'date:' tag. They are explained elsewhere, but here is -a quick list for reference: +particularly the 'date:' and 'type:' tags. They are explained +elsewhere, but here is a quick list for reference: Tags you can set to influence hledger's behaviour: @@ -2185,7 +2175,7 @@ Not displayed, but queryable:  File: hledger.info, Node: Tag values, Prev: Special tags, Up: Tags -9.16.3 Tag values +9.15.3 Tag values ----------------- Tags can have a value, which is any text after the colon up until a @@ -2213,7 +2203,7 @@ with  File: hledger.info, Node: Directives, Next: account directive, Prev: Tags, Up: Journal -9.17 Directives +9.16 Directives =============== Besides transactions, there is something else you can put in a 'journal' @@ -2253,7 +2243,7 @@ Declare market prices 'P'  File: hledger.info, Node: Directives and multiple files, Next: Directive effects, Up: Directives -9.17.1 Directives and multiple files +9.16.1 Directives and multiple files ------------------------------------ Directives vary in their scope, ie which journal entries and which input @@ -2273,7 +2263,7 @@ directives in your files.  File: hledger.info, Node: Directive effects, Prev: Directives and multiple files, Up: Directives -9.17.2 Directive effects +9.16.2 Directive effects ------------------------ Here are all hledger's directives, with their effects and scope @@ -2292,14 +2282,14 @@ directivewhat it does ends '--alias' *'comment'*Ignores part of the journal file, until end of current file orY 'end comment'. -*'commodity'*Declares up to four things: 1. a commodity symbol, for checkingN,Y,N,N - all amounts in all files 2. the decimal mark for parsing - amounts of this commodity, in the following entries until end of - current file (if there is no 'decimal-mark' directive) 3. and - the display style for amounts of this commodity 4. which is - also the precision to use for balanced-transaction checking in - this commodity. Takes precedence over 'D'. Subdirectives: - 'format' (Ledger-compatible syntax). Command line equivalent: +*'commodity'*Declares up to four things: 1. a commodity symbol, for checkingN,N,Y,Y + all amounts in all files 2. the display style for all amounts + of this commodity 3. the decimal mark for parsing amounts of + this commodity, in the rest of this file and its children, if + there is no 'decimal-mark' directive 4. the precision to use + for balanced-transaction checking in this commodity, in this + file and its children. Takes precedence over 'D'. + Subdirectives: 'format' (ignored). Command line equivalent: '-c/--commodity-style' *'decimal-mark'*Declares the decimal mark, for parsing amounts of all Y commodities in following entries until next 'decimal-mark' or @@ -2334,7 +2324,7 @@ directives*  File: hledger.info, Node: account directive, Next: alias directive, Prev: Directives, Up: Journal -9.18 'account' directive +9.17 'account' directive ======================== 'account' directives can be used to declare accounts (ie, the places @@ -2375,7 +2365,7 @@ account assets:bank:checking  File: hledger.info, Node: Account comments, Next: Account error checking, Up: account directive -9.18.1 Account comments +9.17.1 Account comments ----------------------- Text following *two or more spaces* and ';' at the end of an account @@ -2393,7 +2383,7 @@ account assets:bank:checking ; same-line comment, at least 2 spaces before th  File: hledger.info, Node: Account error checking, Next: Account display order, Prev: Account comments, Up: account directive -9.18.2 Account error checking +9.17.2 Account error checking ----------------------------- By default, accounts need not be declared; they come into existence when @@ -2421,7 +2411,7 @@ been declared by an account directive. Some notes:  File: hledger.info, Node: Account display order, Next: Account types, Prev: Account error checking, Up: account directive -9.18.3 Account display order +9.17.3 Account display order ---------------------------- Account directives also cause hledger to display accounts in a @@ -2463,7 +2453,7 @@ the other.  File: hledger.info, Node: Account types, Prev: Account display order, Up: account directive -9.18.4 Account types +9.17.4 Account types -------------------- hledger knows that accounts come in several types: assets, liabilities, @@ -2549,7 +2539,7 @@ account equity:conversion ; type: V  File: hledger.info, Node: alias directive, Next: commodity directive, Prev: account directive, Up: Journal -9.19 'alias' directive +9.18 'alias' directive ====================== You can define account alias rules which rewrite your account names, or @@ -2586,7 +2576,7 @@ more on this below.  File: hledger.info, Node: Basic aliases, Next: Regex aliases, Up: alias directive -9.19.1 Basic aliases +9.18.1 Basic aliases -------------------- To set an account alias, use the 'alias' directive in your journal file. @@ -2610,7 +2600,7 @@ alias checking = assets:bank:wells fargo:checking  File: hledger.info, Node: Regex aliases, Next: Combining aliases, Prev: Basic aliases, Up: alias directive -9.19.2 Regex aliases +9.18.2 Regex aliases -------------------- There is also a more powerful variant that uses a regular expression, @@ -2644,7 +2634,7 @@ of option argument), so it can contain trailing whitespace.  File: hledger.info, Node: Combining aliases, Next: Aliases and multiple files, Prev: Regex aliases, Up: alias directive -9.19.3 Combining aliases +9.18.3 Combining aliases ------------------------ You can define as many aliases as you like, using journal directives @@ -2681,7 +2671,7 @@ which aliases are being applied when.  File: hledger.info, Node: Aliases and multiple files, Next: end aliases directive, Prev: Combining aliases, Up: alias directive -9.19.4 Aliases and multiple files +9.18.4 Aliases and multiple files --------------------------------- As explained at Directives and multiple files, 'alias' directives do not @@ -2713,7 +2703,7 @@ include c.journal ; also affected  File: hledger.info, Node: end aliases directive, Next: Aliases can generate bad account names, Prev: Aliases and multiple files, Up: alias directive -9.19.5 'end aliases' directive +9.18.5 'end aliases' directive ------------------------------ You can clear (forget) all currently defined aliases (seen in the @@ -2724,7 +2714,7 @@ end aliases  File: hledger.info, Node: Aliases can generate bad account names, Next: Aliases and account types, Prev: end aliases directive, Up: alias directive -9.19.6 Aliases can generate bad account names +9.18.6 Aliases can generate bad account names --------------------------------------------- Be aware that account aliases can produce malformed account names, which @@ -2755,7 +2745,7 @@ $ hledger print --alias old="new USD" | hledger -f- print  File: hledger.info, Node: Aliases and account types, Prev: Aliases can generate bad account names, Up: alias directive -9.19.7 Aliases and account types +9.18.7 Aliases and account types -------------------------------- If an account with a type declaration (see Declaring accounts > Account @@ -2779,31 +2769,39 @@ $ hledger accounts --alias assets=bassetts type:a  File: hledger.info, Node: commodity directive, Next: decimal-mark directive, Prev: alias directive, Up: Journal -9.20 'commodity' directive +9.19 'commodity' directive ========================== The 'commodity' directive performs several functions: 1. It declares which commodity symbols may be used in the journal, enabling useful error checking with strict mode or the check - command. (See Commodity error checking below.) + command. See Commodity error checking below. - 2. It declares the precision with which this commodity's amounts - should be compared when checking for balanced transactions. + 2. It declares how all amounts in this commodity should be displayed, + eg how many decimals to show. See Commodity display style above. - 3. It declares how this commodity's amounts should be displayed, eg - their symbol placement, digit group mark if any, digit group sizes, - decimal mark (period or comma), and the number of decimal places. - (See Commodity display style above.) + 3. (If no 'decimal-mark' directive is in effect:) It sets the decimal + mark to expect (period or comma) when parsing amounts in this + commodity, in this file and files it includes, from the directive + until end of current file. See Decimal marks above. - 4. It sets which decimal mark (period or comma) to expect when parsing - subsequent amounts in this commodity (if there is no 'decimal-mark' - directive in effect. See Decimal marks, digit group marks above. - For related dev discussion, see #793.) + 4. It declares the precision with which this commodity's amounts + should be compared when checking for balanced transactions, + anywhere in this file and files it includes, until end of current + file. Declaring commodities solves several common parsing/display problems, -so we recommend it. Generally you should put 'commodity' directives at -the top of your journal file (because function 4 is position-sensitive). +so we recommend it. + + Note that effects 3 and 4 above end at the end of the directive's +file, and will not affect sibling or parent files. So if you are +relying on them (especially 4) and using multiple files, placing your +commodity directives in a top-level parent file might be important. Or, +keep your decimal marks unambiguous and your entries well balanced and +precise. + + (Related: #793) * Menu: @@ -2813,7 +2811,7 @@ the top of your journal file (because function 4 is position-sensitive).  File: hledger.info, Node: Commodity directive syntax, Next: Commodity error checking, Up: commodity directive -9.20.1 Commodity directive syntax +9.19.1 Commodity directive syntax --------------------------------- A commodity directive is normally the word 'commodity' followed by a @@ -2860,7 +2858,7 @@ commodity INR  File: hledger.info, Node: Commodity error checking, Prev: Commodity directive syntax, Up: commodity directive -9.20.2 Commodity error checking +9.19.2 Commodity error checking ------------------------------- In strict mode ('-s'/'--strict') (or when you run 'hledger check @@ -2872,7 +2870,7 @@ have no commodity symbol.) It works like account error checking  File: hledger.info, Node: decimal-mark directive, Next: include directive, Prev: commodity directive, Up: Journal -9.21 'decimal-mark' directive +9.20 'decimal-mark' directive ============================= You can use a 'decimal-mark' directive - usually one per file, at the @@ -2892,7 +2890,7 @@ thousands separators).  File: hledger.info, Node: include directive, Next: P directive, Prev: decimal-mark directive, Up: Journal -9.22 'include' directive +9.21 'include' directive ======================== You can pull in the content of additional files by writing an include @@ -2923,7 +2921,7 @@ timedot:~/notes/2023*.md'.  File: hledger.info, Node: P directive, Next: payee directive, Prev: include directive, Up: Journal -9.23 'P' directive +9.22 'P' directive ================== The 'P' directive declares a market price, which is a conversion rate @@ -2953,7 +2951,7 @@ amount values in another commodity. See Value reporting.  File: hledger.info, Node: payee directive, Next: tag directive, Prev: P directive, Up: Journal -9.24 'payee' directive +9.23 'payee' directive ====================== 'payee PAYEE NAME' @@ -2976,7 +2974,7 @@ payee ""  File: hledger.info, Node: tag directive, Next: Periodic transactions, Prev: payee directive, Up: Journal -9.25 'tag' directive +9.24 'tag' directive ==================== 'tag TAGNAME' @@ -2996,7 +2994,7 @@ check your tags .  File: hledger.info, Node: Periodic transactions, Next: Auto postings, Prev: tag directive, Up: Journal -9.26 Periodic transactions +9.25 Periodic transactions ========================== The '~' directive declares a "periodic rule" which generates temporary @@ -3044,7 +3042,7 @@ this whole section, or at least the following tips:  File: hledger.info, Node: Periodic rule syntax, Next: Periodic rules and relative dates, Up: Periodic transactions -9.26.1 Periodic rule syntax +9.25.1 Periodic rule syntax --------------------------- A periodic transaction rule looks like a normal journal entry, with the @@ -3069,7 +3067,7 @@ dates).  File: hledger.info, Node: Periodic rules and relative dates, Next: Two spaces between period expression and description!, Prev: Periodic rule syntax, Up: Periodic transactions -9.26.2 Periodic rules and relative dates +9.25.2 Periodic rules and relative dates ---------------------------------------- Partial or relative dates (like '12/31', '25', 'tomorrow', 'last week', @@ -3088,7 +3086,7 @@ dates.  File: hledger.info, Node: Two spaces between period expression and description!, Prev: Periodic rules and relative dates, Up: Periodic transactions -9.26.3 Two spaces between period expression and description! +9.25.3 Two spaces between period expression and description! ------------------------------------------------------------ If the period expression is followed by a transaction description, these @@ -3113,7 +3111,7 @@ accidentally alter their meaning, as in this example:  File: hledger.info, Node: Auto postings, Next: Other syntax, Prev: Periodic transactions, Up: Journal -9.27 Auto postings +9.26 Auto postings ================== The '=' directive declares an "auto posting rule", which adds extra @@ -3203,7 +3201,7 @@ output into the journal file to make it permanent.  File: hledger.info, Node: Auto postings and multiple files, Up: Auto postings -9.27.1 Auto postings and multiple files +9.26.1 Auto postings and multiple files --------------------------------------- An auto posting rule can affect any transaction in the current file, or @@ -3220,7 +3218,7 @@ sibling files (when multiple '-f'/'--file' are used - see #1212).  File: hledger.info, Node: Auto postings and dates, Next: Auto postings and transaction balancing / inferred amounts / balance assertions, Up: Auto postings and multiple files -9.27.1.1 Auto postings and dates +9.26.1.1 Auto postings and dates ................................ A posting date (or secondary date) in the matched posting, or (taking @@ -3230,7 +3228,7 @@ used in the generated posting.  File: hledger.info, Node: Auto postings and transaction balancing / inferred amounts / balance assertions, Next: Auto posting tags, Prev: Auto postings and dates, Up: Auto postings and multiple files -9.27.1.2 Auto postings and transaction balancing / inferred +9.26.1.2 Auto postings and transaction balancing / inferred ........................................................... amounts / balance assertions Currently, auto postings are added: @@ -3250,7 +3248,7 @@ infer amounts.  File: hledger.info, Node: Auto posting tags, Next: Auto postings on forecast transactions only, Prev: Auto postings and transaction balancing / inferred amounts / balance assertions, Up: Auto postings and multiple files -9.27.1.3 Auto posting tags +9.26.1.3 Auto posting tags .......................... Automated postings will have some extra tags: @@ -3272,7 +3270,7 @@ will have these tags added:  File: hledger.info, Node: Auto postings on forecast transactions only, Prev: Auto posting tags, Up: Auto postings and multiple files -9.27.1.4 Auto postings on forecast transactions only +9.26.1.4 Auto postings on forecast transactions only .................................................... Tip: you can can make auto postings that will apply to forecast @@ -3283,7 +3281,7 @@ generating new journal entries to be saved in the journal.  File: hledger.info, Node: Other syntax, Prev: Auto postings, Up: Journal -9.28 Other syntax +9.27 Other syntax ================= hledger journal format supports quite a few other features, mainly to @@ -3305,11 +3303,12 @@ you decide if you want to use them. * Valuation expressions:: * Virtual postings:: * Other Ledger directives:: +* Other cost/lot notations::  File: hledger.info, Node: Balance assignments, Next: Bracketed posting dates, Up: Other syntax -9.28.1 Balance assignments +9.27.1 Balance assignments -------------------------- Ledger-style balance assignments are also supported. These are like @@ -3352,7 +3351,7 @@ trustworthy in an audit.  File: hledger.info, Node: Balance assignments and costs, Next: Balance assignments and multiple files, Up: Balance assignments -9.28.1.1 Balance assignments and costs +9.27.1.1 Balance assignments and costs ...................................... A cost in a balance assignment will cause the calculated amount to have @@ -3368,7 +3367,7 @@ $ hledger print --explicit  File: hledger.info, Node: Balance assignments and multiple files, Prev: Balance assignments and costs, Up: Balance assignments -9.28.1.2 Balance assignments and multiple files +9.27.1.2 Balance assignments and multiple files ............................................... Balance assignments handle multiple files like balance assertions. They @@ -3378,7 +3377,7 @@ but not from previous sibling or parent files.  File: hledger.info, Node: Bracketed posting dates, Next: D directive, Prev: Balance assignments, Up: Other syntax -9.28.2 Bracketed posting dates +9.27.2 Bracketed posting dates ------------------------------ For setting posting dates and secondary posting dates, Ledger's @@ -3395,7 +3394,7 @@ syntax.  File: hledger.info, Node: D directive, Next: apply account directive, Prev: Bracketed posting dates, Up: Other syntax -9.28.3 'D' directive +9.27.3 'D' directive -------------------- 'D AMOUNT' @@ -3441,7 +3440,7 @@ Ledger's 'D'.  File: hledger.info, Node: apply account directive, Next: Y directive, Prev: D directive, Up: Other syntax -9.28.4 'apply account' directive +9.27.4 'apply account' directive -------------------------------- This directive sets a default parent account, which will be prepended to @@ -3477,7 +3476,7 @@ portable, and less trustworthy in an audit.  File: hledger.info, Node: Y directive, Next: Secondary dates, Prev: apply account directive, Up: Other syntax -9.28.5 'Y' directive +9.27.5 'Y' directive -------------------- 'Y YEAR' @@ -3515,7 +3514,7 @@ date.  File: hledger.info, Node: Secondary dates, Next: Star comments, Prev: Y directive, Up: Other syntax -9.28.6 Secondary dates +9.27.6 Secondary dates ---------------------- A secondary date is written after the primary date, following an equals @@ -3537,7 +3536,7 @@ better.  File: hledger.info, Node: Star comments, Next: Valuation expressions, Prev: Secondary dates, Up: Other syntax -9.28.7 Star comments +9.27.7 Star comments -------------------- Lines beginning with '*' (star/asterisk) are also comment lines. This @@ -3554,7 +3553,7 @@ losing ledger mode's features.  File: hledger.info, Node: Valuation expressions, Next: Virtual postings, Prev: Star comments, Up: Other syntax -9.28.8 Valuation expressions +9.27.8 Valuation expressions ---------------------------- Ledger allows a valuation function or value to be written in double @@ -3563,7 +3562,7 @@ parentheses after an amount. hledger ignores these.  File: hledger.info, Node: Virtual postings, Next: Other Ledger directives, Prev: Valuation expressions, Up: Other syntax -9.28.9 Virtual postings +9.27.9 Virtual postings ----------------------- A posting with parentheses around the account name ('(some:account)') is @@ -3593,35 +3592,105 @@ bracketed, are called _real postings_. You can exclude virtual postings from reports with the '-R/--real' flag or a 'real:1' query.  -File: hledger.info, Node: Other Ledger directives, Prev: Virtual postings, Up: Other syntax +File: hledger.info, Node: Other Ledger directives, Next: Other cost/lot notations, Prev: Virtual postings, Up: Other syntax -9.28.10 Other Ledger directives +9.27.10 Other Ledger directives ------------------------------- These other Ledger directives are currently accepted but ignored. This allows hledger to read more Ledger files, but be aware that hledger's reports may differ from Ledger's if you use these. -apply fixed COMM AMT -apply tag TAG -assert EXPR -bucket / A ACCT -capture ACCT REGEX -check EXPR -define VAR=EXPR -end apply fixed -end apply tag -end apply year -end tag -eval / expr EXPR -python - PYTHONCODE -tag NAME -value EXPR ---command-line-flags +apply fixed COMM AMT +apply tag TAG +assert EXPR +bucket / A ACCT +capture ACCT REGEX +check EXPR +define VAR=EXPR +end apply fixed +end apply tag +end apply year +end tag +eval / expr EXPR +python + PYTHONCODE +tag NAME +value EXPR +--command-line-flags + + See also https://hledger.org/ledger.html for a detailed +hledger/Ledger syntax comparison. + + +File: hledger.info, Node: Other cost/lot notations, Prev: Other Ledger directives, Up: Other syntax + +9.27.11 Other cost/lot notations +-------------------------------- + +A slight digression for Ledger and Beancount users. Ledger has a number +of cost/lot-related notations: + + * '@ UNITCOST' and '@@ TOTALCOST' + * expresses a conversion rate, as in hledger + * when buying, also creates a lot than can be selected at + selling time + + * '(@) UNITCOST' and '(@@) TOTALCOST' (virtual cost) + * like the above, but also means "this cost was exceptional, + don't use it when inferring market prices". + + Currently, hledger treats the above like '@' and '@@'; the +parentheses are ignored. + + * '{=FIXEDUNITCOST}' and '{{=FIXEDTOTALCOST}}' (fixed price) + * when buying, means "this cost is also the fixed price, don't + let it fluctuate in value reports" + + * '{UNITCOST}' and '{{TOTALCOST}}' (lot price) + * can be used identically to '@ UNITCOST' and '@@ TOTALCOST', + also creates a lot + * when selling, combined with '@ ...', specifies an investment + lot by its cost basis; does not check if that lot is present + + * and related: '[YYYY/MM/DD]' (lot date) + * when buying, attaches this acquisition date to the lot + * when selling, selects a lot by its acquisition date + + * '(SOME TEXT)' (lot note) + * when buying, attaches this note to the lot + * when selling, selects a lot by its note + + Currently, hledger accepts any or all of the above in any order after +the posting amount, but ignores them. (This can break transaction +balancing.) + + For Beancount users, the notation and behaviour is different: + + * '@ UNITCOST' and '@@ TOTALCOST' + * expresses a cost without creating a lot, as in hledger + * when buying (augmenting) or selling (reducing) a lot, combined + with '{...}': documents the cost/selling price (not used for + transaction balancing) + + * '{UNITCOST}' and '{{TOTALCOST}}' + * when buying (augmenting), expresses the cost for transaction + balancing, and also creates a lot with this cost basis + attached + * when selling (reducing), + * selects a lot by its cost basis + * raises an error if that lot is not present or can not be + selected unambiguously (depending on booking method + configured) + * expresses the selling price for transaction balancing + + Currently, hledger accepts the '{UNITCOST}'/'{{TOTALCOST}}' notation +but ignores it. + + * variations: '{}', '{YYYY-MM-DD}', '{"LABEL"}', '{UNITCOST, + "LABEL"}', '{UNITCOST, YYYY-MM-DD, "LABEL"}' etc. - See also https://hledger.org/ledger.html for a detailed -hledger/Ledger syntax comparison. + Currently, hledger rejects these.  File: hledger.info, Node: CSV, Next: Timeclock, Prev: Journal, Up: Top @@ -3644,12 +3713,11 @@ This contains rules describing the CSV data (header line, fields layout, date format etc.), how to construct hledger transactions from it, and how to categorise transactions based on description or other attributes. - By default hledger looks for a rules file named like the CSV file -with an extra '.rules' extension, in the same directory. Eg when asked -to read 'foo/FILE.csv', hledger looks for 'foo/FILE.csv.rules'. You can -specify a different rules file with the '--rules-file' option. If no -rules file is found, hledger will create a sample rules file, which -you'll need to adjust. + By default, hledger expects this rules file to be named like the CSV +file, with an extra '.rules' extension added, in the same directory. Eg +when asked to read 'foo/FILE.csv', hledger looks for +'foo/FILE.csv.rules'. You can specify a different rules file with the +'--rules-file' option. At minimum, the rules file must identify the date and amount fields, and often it also specifies the date format and how many header lines @@ -4213,7 +4281,8 @@ equivalent to 'balance1'. You can adjust the type of assertion/assignment with the 'balance-type' rule (see below). - See Tips below for more about setting amounts and currency. + See the Working with CSV tips below for more about setting amounts +and currency.  File: hledger.info, Node: if block, Next: Matchers, Prev: Field names, Up: CSV @@ -4326,14 +4395,15 @@ File: hledger.info, Node: Combining matchers, Next: Match groups, Prev: What When an if block has multiple matchers, they are combined as follows: - * By default they are OR'd (any one of them can match) - * When a matcher is preceded by ampersand ('&') it will be AND'ed - with the previous matcher (both of them must match) + * By default they are OR'd (any of them can match) + * When a matcher is preceded by ampersand ('&', at the start of the + line) it will be AND'ed with the previous matcher (all in the + AND'ed group must match) * _Added in 1.32_ When a matcher is preceded by an exclamation mark - ('!'), the matcher is negated (it may not match). + ('!'), it is negated (it must not match). - Currently there is a limitation: you can't use both '&' and '!' on -the same line (you can't AND a negated matcher). + Note currently there is a limitation: you can't use both '&' and '!' +on the same line (you can't AND a negated matcher).  File: hledger.info, Node: Match groups, Prev: Combining matchers, Up: Matchers @@ -4376,6 +4446,7 @@ this: if,HLEDGERFIELD1,HLEDGERFIELD2,... MATCHERA,VALUE1,VALUE2,... MATCHERB,VALUE1,VALUE2,... +; Comment line that explains MATCHERC MATCHERC,VALUE1,VALUE2,... @@ -4387,13 +4458,17 @@ or matchers or values, and it cannot be escaped with a backslash). Each line must contain the same number of separators; empty values are allowed. Whitespace can be used in the matcher lines for -readability (but not in the if line, currently). The table must be -terminated by an empty line (or end of file). +readability (but not in the if line, currently). You can use the +comment lines in the table body. The table must be terminated by an +empty line (or end of file). An if table like the above is interpreted as follows: try all of the matchers; whenever a matcher succeeds, assign all of the values on that -line to the corresponding hledger fields; later lines can overrider -earlier ones. It is equivalent to this sequence of if blocks: +line to the corresponding hledger fields; If multiple lines match, later +lines will override fields assigned by the earlier ones - just like the +sequence of 'if' blocks would behave. + + If table presented above is equivalent to this sequence of if blocks: if MATCHERA HLEDGERFIELD1 VALUE1 @@ -4405,6 +4480,7 @@ if MATCHERB HLEDGERFIELD2 VALUE2 ... +; Comment line which explains MATCHERC if MATCHERC HLEDGERFIELD1 VALUE1 HLEDGERFIELD2 VALUE2 @@ -4415,6 +4491,7 @@ if MATCHERC if,account2,comment atm transaction fee,expenses:business:banking,deductible? check it %description groceries,expenses:groceries, +;; Comment line that desribes why this particular date is special 2023/01/12.*Plumbing LLC,expenses:house:upkeep,emergency plumbing call-out  @@ -5250,9 +5327,9 @@ $ hledger -f sample.timeclock register -p weekly --depth 1 --empty # time summa * use emacs and the built-in timeclock.el, or the extended timeclock-x.el and perhaps the extras in ledgerutils.el - * 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 '+%Y-%m-%d %H:%M:%S'` >>$TIMELOG"' + * at the command line, use these bash aliases: 'cli alias ti="echo i + `date '+%Y-%m-%d %H:%M:%S'` \$* >>$TIMELOG" alias to="echo o `date + '+%Y-%m-%d %H:%M:%S'` >>$TIMELOG"' * 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 @@ -5447,22 +5524,91 @@ $ hledger -f a.timedot --alias '/\./=:' bal -t 4.50  -File: hledger.info, Node: PART 3 REPORTING CONCEPTS, Next: Amount formatting parseability, Prev: Timedot, Up: Top +File: hledger.info, Node: PART 3 REPORTING CONCEPTS, Next: Amount formatting, Prev: Timedot, Up: Top 13 PART 3: REPORTING CONCEPTS *****************************  -File: hledger.info, Node: Amount formatting parseability, Next: Time periods, Prev: PART 3 REPORTING CONCEPTS, Up: Top +File: hledger.info, Node: Amount formatting, Next: Time periods, Prev: PART 3 REPORTING CONCEPTS, Up: Top + +14 Amount formatting +******************** + +* Menu: + +* Commodity display style:: +* Rounding:: +* Trailing decimal marks:: +* Amount parseability:: + + +File: hledger.info, Node: Commodity display style, Next: Rounding, Up: Amount formatting + +14.1 Commodity display style +============================ + +For the amounts in each commodity, hledger chooses a consistent display +style (symbol placement, decimal mark and digit group marks, number of +decimal digits) to use in most reports. This is inferred as follows: + + First, if there's a 'D' directive declaring a default commodity, that +commodity symbol and amount format is applied to all no-symbol amounts +in the journal. + + Then each commodity's display style is determined from its +'commodity' directive. We recommend always declaring commodities with +'commodity' directives, since they help ensure consistent display styles +and precisions, and bring other benefits such as error checking for +commodity symbols. Here's an example: + +# Set display styles (and decimal marks, for parsing, if there is no decimal-mark directive) +# for the $, EUR, INR and no-symbol commodities: +commodity $1,000.00 +commodity EUR 1.000,00 +commodity INR 9,99,99,999.00 +commodity 1 000 000.9455 + + But for convenience, if a 'commodity' directive is not present, +hledger infers a commodity's display styles from its amounts as they are +written in the journal (excluding cost amounts and amounts in periodic +transaction rules or auto posting rules). It uses + + * the symbol placement and decimal mark of the first amount seen + * the digit group marks of the first amount with digit group marks + * and the maximum number of decimal digits seen across all amounts. + + And as fallback if no applicable amounts are found, it would use a +default style, like '$1000.00' (symbol on the left with no space, period +as decimal mark, and two decimal digits). + + Finally, commodity styles can be overridden by the +'-c/--commodity-style' command line option. + + +File: hledger.info, Node: Rounding, Next: Trailing decimal marks, Prev: Commodity display style, Up: Amount formatting + +14.2 Rounding +============= + +Amounts are stored internally as decimal numbers with up to 255 decimal +places. They are displayed with their original journal precisions by +print and print-like reports, and rounded to their display precision +(the number of decimal digits specified by the commodity display style) +by other reports. When rounding, hledger uses banker's rounding (it +rounds to the nearest even digit). So eg 0.5 displayed with zero +decimal digits appears as "0". + + +File: hledger.info, Node: Trailing decimal marks, Next: Amount parseability, Prev: Rounding, Up: Amount formatting -14 Amount formatting, parseability -********************************** +14.3 Trailing decimal marks +=========================== If you're wondering why your 'print' report sometimes shows trailing decimal marks, with no decimal digits; it does this when showing amounts that have digit group marks but no decimal digits, to disambiguate them -and allow them to be re-parsed reliably (see also Decimal marks, digit -group marks. Eg: +and allow them to be re-parsed reliably (see Decimal marks). Eg: commodity $1,000.00 @@ -5487,9 +5633,14 @@ $ hledger print -c '$1,000.00' --round=soft 2023-01-02 (a) $1,000.00 - More generally: hledger output falls into three rough categories, -which format amounts a little bit differently to suit different -consumers: + +File: hledger.info, Node: Amount parseability, Prev: Trailing decimal marks, Up: Amount formatting + +14.4 Amount parseability +======================== + +More generally, hledger output falls into three rough categories, which +format amounts a little bit differently to suit different consumers: *1. "hledger-readable output" - should be readable by hledger (and by humans)* @@ -5522,7 +5673,7 @@ by humans)* changed with -c/-commodity-style).  -File: hledger.info, Node: Time periods, Next: Depth, Prev: Amount formatting parseability, Up: Top +File: hledger.info, Node: Time periods, Next: Depth, Prev: Amount formatting, Up: Top 15 Time periods *************** @@ -5914,9 +6065,8 @@ a more complex query. * Query types:: * Combining query terms:: * Queries and command options:: +* Queries and account aliases:: * Queries and valuation:: -* Querying with account aliases:: -* Querying with cost or value::  File: hledger.info, Node: Query types, Next: Combining query terms, Up: Queries @@ -6032,10 +6182,8 @@ things which match: * match all the other terms. We also support more complex boolean queries with the 'expr:' prefix. -This allows one to combine queries using one of three operators: AND, -OR, and NOT, where NOT is different syntax for 'not:'. - - Examples of such queries are: +This allows one to combine queries using 'AND', 'OR', and 'NOT'. ('NOT' +is equivalent to the 'not:' prefix.) Some examples: * Match transactions with 'cool' in the description AND with the 'A' tag @@ -6055,7 +6203,7 @@ OR, and NOT, where NOT is different syntax for 'not:'. 'expr:"expenses:food OR (tag:A expenses:drink)"'  -File: hledger.info, Node: Queries and command options, Next: Queries and valuation, Prev: Combining query terms, Up: Queries +File: hledger.info, Node: Queries and command options, Next: Queries and account aliases, Prev: Combining query terms, Up: Queries 17.3 Queries and command options ================================ @@ -6066,36 +6214,23 @@ When you mix command options and query arguments, generally the resulting query is their intersection.  -File: hledger.info, Node: Queries and valuation, Next: Querying with account aliases, Prev: Queries and command options, Up: Queries - -17.4 Queries and valuation -========================== - -When amounts are converted to other commodities in cost or value -reports, 'cur:' and 'amt:' match the old commodity symbol and the old -amount quantity, not the new ones (except in hledger 1.22.0 where it's -reversed, see #1625). - - -File: hledger.info, Node: Querying with account aliases, Next: Querying with cost or value, Prev: Queries and valuation, Up: Queries +File: hledger.info, Node: Queries and account aliases, Next: Queries and valuation, Prev: Queries and command options, Up: Queries -17.5 Querying with account aliases -================================== +17.4 Queries and account aliases +================================ -When account names are rewritten with '--alias' or 'alias', note that -'acct:' will match either the old or the new account name. +When account names are rewritten with '--alias' or 'alias', 'acct:' will +match either the old or the new account name.  -File: hledger.info, Node: Querying with cost or value, Prev: Querying with account aliases, Up: Queries +File: hledger.info, Node: Queries and valuation, Prev: Queries and account aliases, Up: Queries -17.6 Querying with cost or value -================================ +17.5 Queries and valuation +========================== When amounts are converted to other commodities in cost or value -reports, note that 'cur:' matches the new commodity symbol, and not the -old one, and 'amt:' matches the new quantity, and not the old one. -Note: this changed in hledger 1.22, previously it was the reverse, see -the discussion at #1625. +reports, 'cur:' and 'amt:' match the old commodity symbol and the old +amount quantity, not the new ones. (Except in hledger 1.22, #1625.)  File: hledger.info, Node: Pivoting, Next: Generating data, Prev: Queries, Up: Top @@ -6683,9 +6818,8 @@ and '-X COMMODITY' options, and often one of these is all you need: * Finding market price:: * --infer-market-prices market prices from transactions:: * Valuation commodity:: -* Simple valuation examples:: * --value Flexible valuation:: -* More valuation examples:: +* Valuation examples:: * Interaction of valuation and queries:: * Effect of valuation on reports:: @@ -6853,7 +6987,7 @@ P 2022-01-03 B A -1 P 2022-01-03 B A -1.0  -File: hledger.info, Node: Valuation commodity, Next: Simple valuation examples, Prev: --infer-market-prices market prices from transactions, Up: Value reporting +File: hledger.info, Node: Valuation commodity, Next: --value Flexible valuation, Prev: --infer-market-prices market prices from transactions, Up: Value reporting 23.6 Valuation commodity ======================== @@ -6892,44 +7026,9 @@ follows, in this order of preference: converted.  -File: hledger.info, Node: Simple valuation examples, Next: --value Flexible valuation, Prev: Valuation commodity, Up: Value reporting - -23.7 Simple valuation examples -============================== - -Here are some quick examples of '-V': - -; one euro is worth this many dollars from nov 1 -P 2016/11/01 € $1.10 - -; purchase some euros on nov 3 -2016/11/3 - assets:euros €100 - assets:checking - -; the euro is worth fewer dollars by dec 21 -P 2016/12/21 € $1.03 - - How many euros do I have ? - -$ hledger -f t.j bal -N euros - €100 assets:euros - - What are they worth at end of nov 3 ? - -$ 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, defaults to today) - -$ hledger -f t.j bal -N euros -V - $103.00 assets:euros - - -File: hledger.info, Node: --value Flexible valuation, Next: More valuation examples, Prev: Simple valuation examples, Up: Value reporting +File: hledger.info, Node: --value Flexible valuation, Next: Valuation examples, Prev: Valuation commodity, Up: Value reporting -23.8 -value: Flexible valuation +23.7 -value: Flexible valuation =============================== '-V' and '-X' are special cases of the more general '--value' option: @@ -6969,12 +7068,41 @@ part: a comma, then the target commodity's symbol. Eg: this commodity, deducing market prices as described above.  -File: hledger.info, Node: More valuation examples, Next: Interaction of valuation and queries, Prev: --value Flexible valuation, Up: Value reporting +File: hledger.info, Node: Valuation examples, Next: Interaction of valuation and queries, Prev: --value Flexible valuation, Up: Value reporting -23.9 More valuation examples -============================ +23.8 Valuation examples +======================= + +Here are some quick examples of '-V': + +; one euro is worth this many dollars from nov 1 +P 2016/11/01 € $1.10 + +; purchase some euros on nov 3 +2016/11/3 + assets:euros €100 + assets:checking + +; the euro is worth fewer dollars by dec 21 +P 2016/12/21 € $1.03 + + How many euros do I have ? + +$ hledger -f t.j bal -N euros + €100 assets:euros + + What are they worth at end of nov 3 ? + +$ 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, defaults to today) -Here are some examples showing the effect of '--value', as seen with +$ hledger -f t.j bal -N euros -V + $103.00 assets:euros + + Here are some examples showing the effect of '--value', as seen with 'print': P 2000-01-01 A 1 B @@ -7051,13 +7179,13 @@ $ hledger -f- print --value=2000-01-15 (a) 1 B  -File: hledger.info, Node: Interaction of valuation and queries, Next: Effect of valuation on reports, Prev: More valuation examples, Up: Value reporting +File: hledger.info, Node: Interaction of valuation and queries, Next: Effect of valuation on reports, Prev: Valuation examples, Up: Value reporting -23.10 Interaction of valuation and queries -========================================== +23.9 Interaction of valuation and queries +========================================= When matching postings based on queries in the presence of valuation, -the following happens. +the following happens: 1. The query is separated into two parts: 1. the currency ('cur:') or amount ('amt:'). @@ -7069,19 +7197,51 @@ the following happens. 4. The postings are matched to the other parts of the query based on post-valued amounts. - See: 1625 + Related: #1625  File: hledger.info, Node: Effect of valuation on reports, Prev: Interaction of valuation and queries, Up: Value reporting -23.11 Effect of valuation on reports +23.10 Effect of valuation on reports ==================================== Here is a reference for how valuation is supposed to affect each part of -hledger's reports (and a glossary). (It's wide, you'll have to scroll -sideways.) It may be useful when troubleshooting. If you find -problems, please report them, ideally with a reproducible example. -Related: #329, #1083. +hledger's reports. (It's wide, you may need to scroll sideways.) It +may be useful when troubleshooting. If you find problems, please report +them, ideally with a reproducible example. Related: #329, #1083. + + First, a quick glossary: + +_cost_ + + calculated using price(s) recorded in the transaction(s). +_value_ + + market value using available market price declarations, or the + unchanged amount if no conversion rate can be found. +_report start_ + + the first day of the report period specified with -b or -p or + date:, otherwise today. +_report or journal start_ + + the first day of the report period specified with -b or -p or + date:, otherwise the earliest transaction date in the journal, + otherwise today. +_report end_ + + the last day of the report period specified with -e or -p or date:, + otherwise today. +_report or journal end_ + + the last day of the report period specified with -e or -p or date:, + otherwise the latest transaction date in the journal, otherwise + today. +_report interval_ + + a flag (-D/-W/-M/-Q/-Y) or period expression that activates the + report's multi-period mode (whether showing one or many + subperiods). Report '-B', '-V', '-X' '--value=then' '--value=end''--value=DATE', type '--cost' '--value=now' @@ -7187,39 +7347,6 @@ average totals totals totals column '--cumulative' is omitted to save space, it works like '-H' but with a zero starting balance. - *Glossary:* - -_cost_ - - calculated using price(s) recorded in the transaction(s). -_value_ - - market value using available market price declarations, or the - unchanged amount if no conversion rate can be found. -_report start_ - - the first day of the report period specified with -b or -p or - date:, otherwise today. -_report or journal start_ - - the first day of the report period specified with -b or -p or - date:, otherwise the earliest transaction date in the journal, - otherwise today. -_report end_ - - the last day of the report period specified with -e or -p or date:, - otherwise today. -_report or journal end_ - - the last day of the report period specified with -e or -p or date:, - otherwise the latest transaction date in the journal, otherwise - today. -_report interval_ - - a flag (-D/-W/-M/-Q/-Y) or period expression that activates the - report's multi-period mode (whether showing one or many - subperiods). -  File: hledger.info, Node: PART 4 COMMANDS, Next: PART 5 COMMON TASKS, Prev: Value reporting, Up: Top @@ -7664,7 +7791,7 @@ more control, then use 'balance'. * Balance report types:: * Budget report:: * Balance report layout:: -* Useful balance reports:: +* Some useful balance reports::  File: hledger.info, Node: balance features, Next: Simple balance report, Up: balance @@ -7689,6 +7816,7 @@ higher-level commands as well. * or value of balance changes ('-V') * or change of balance values ('--valuechange') * or unrealised capital gain/loss ('--gain') + * or balance changes from sibling postings ('--related'/'-r') * or postings count ('--count') ..in.. @@ -7726,9 +7854,6 @@ options, with output formats 'txt', 'csv', 'tsv' (_Added in 1.32_), 'json', and (multi-period reports only:) 'html'. In 'txt' output in a colour-supporting terminal, negative amounts are shown in red. - The '--related'/'-r' flag shows the balance of the _other_ postings -in the transactions of the postings which would normally be shown. -  File: hledger.info, Node: Simple balance report, Next: Balance report line format, Prev: balance features, Up: balance @@ -8040,7 +8165,9 @@ Balance changes in 2008: viewing in the terminal. Here are some ways to handle that: * Hide the totals row with '-N/--no-total' - * Convert to a single currency with '-V' + * Filter to a single currency with 'cur:' + * Convert to a single currency with '-V [--infer-market-price]' + * Use a more compact layout like '--layout=bare' * Maximize the terminal window * Reduce the terminal's font size * View with a pager like less, eg: 'hledger bal -D --color=yes | less @@ -8135,13 +8262,14 @@ File: hledger.info, Node: Accumulation type, Next: Valuation type, Prev: Calc 24.6.13.2 Accumulation type ........................... -How amounts should accumulate across report periods. Another way to say -it: which time period's postings should contribute to each cell's -calculation. It is one of: +How amounts should accumulate across a report's subperiods/columns. +Another way to say it: which time period's postings should contribute to +each cell's calculation. It is one of: * '--change' : calculate with postings from column start to column end, ie "just this column". Typically used to see - revenues/expenses. (*default for balance, incomestatement*) + revenues/expenses. (*default for balance, cashflow, + incomestatement*) * '--cumulative' : calculate with postings from report start to column end, ie "previous columns plus this column". Typically used @@ -8152,7 +8280,7 @@ calculation. It is one of: column end, ie "all postings from before report start date until this column's end". Typically used to see historical end balances of assets/liabilities/equity. (*default for balancesheet, - balancesheetequity, cashflow*) + balancesheetequity*)  File: hledger.info, Node: Valuation type, Next: Combining balance report types, Prev: Accumulation type, Up: Balance report types @@ -8416,40 +8544,34 @@ File: hledger.info, Node: Budgeting vs forecasting, Prev: Selecting budget goa 24.6.14.4 Budgeting vs forecasting .................................. -'--budget' and '--forecast' both use the periodic transaction rules in +'--forecast' and '--budget' both use the periodic transaction rules in the journal to generate temporary transactions for reporting purposes. However they are separate features - though you can use both at the same time if you want. Here are some differences between them: - 1. '--budget' is a command-specific option; it selects the *budget - report*. - - '--forecast' is a general option; *forecasting works with all - reports*. - - 2. '--budget' uses *all periodic rules*; '--budget=DESCPAT' uses *just - the rules matched* by DESCPAT. - - '--forecast' uses *all periodic rules*. - - 3. '--budget''s budget goal transactions are invisible, except that - they produce *goal amounts*. - - '--forecast''s forecast transactions are visible, and *appear in - reports*. - - 4. '--budget' generates budget goal transactions *throughout the - report period*, optionally restricted by periods specified in the - periodic transaction rules. - - '--forecast' generates forecast transactions from *after the last - regular transaction*, to the end of the report period; while - '--forecast=PERIODEXPR' generates them *throughout the specified - period*; both optionally restricted by periods specified in the - periodic transaction rules. - - -File: hledger.info, Node: Balance report layout, Next: Useful balance reports, Prev: Budget report, Up: balance +-forecast -budget +-------------------------------------------------------------------------- +is a general option; it enables is a balance command option; +forecasting with all reports it selects the balance + report's budget mode +generates visible transactions which generates invisible +appear in reports transactions which produce + goal amounts +generates forecast transactions from generates budget goal +after the last regular transaction, to transactions throughout the +the end of the report period; or with report period, optionally +an argument '--forecast=PERIODEXPR' restricted by periods +generates them throughout the specified in the periodic +specified period, both optionally transaction rules +restricted by periods specified in the +periodic transaction rules +uses all periodic rules uses all periodic rules; or + with an argument + '--budget=DESCPAT' uses just + the rules matched by DESCPAT + + +File: hledger.info, Node: Balance report layout, Next: Some useful balance reports, Prev: Budget report, Up: balance 24.6.15 Balance report layout ----------------------------- @@ -8467,8 +8589,8 @@ four possible values: * '--layout=tidy': data is normalised to easily-consumed "tidy" form, with one row per data value - Here are the '--layout' modes supported by each output format; note -only CSV output supports all of them: + Here are the '--layout' modes supported by each output format Only +CSV output supports all of them: - txt csv html json sql --------------------------------------- @@ -8479,121 +8601,149 @@ tidy Y Examples: - * Wide layout. With many commodities, reports can be very wide: +* Menu: - $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=wide - Balance changes in 2012-01-01..2014-12-31: - - || 2012 2013 2014 Total - ==================++==================================================================================================================================================================================================================== - Assets:US:ETrade || 10.00 ITOT, 337.18 USD, 12.00 VEA, 106.00 VHT 70.00 GLD, 18.00 ITOT, -98.12 USD, 10.00 VEA, 18.00 VHT -11.00 ITOT, 4881.44 USD, 14.00 VEA, 170.00 VHT 70.00 GLD, 17.00 ITOT, 5120.50 USD, 36.00 VEA, 294.00 VHT - ------------------++-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- - || 10.00 ITOT, 337.18 USD, 12.00 VEA, 106.00 VHT 70.00 GLD, 18.00 ITOT, -98.12 USD, 10.00 VEA, 18.00 VHT -11.00 ITOT, 4881.44 USD, 14.00 VEA, 170.00 VHT 70.00 GLD, 17.00 ITOT, 5120.50 USD, 36.00 VEA, 294.00 VHT +* Wide layout:: +* Tall layout:: +* Bare layout:: +* Tidy layout:: + + +File: hledger.info, Node: Wide layout, Next: Tall layout, Up: Balance report layout - * Limited wide layout. A width limit reduces the width, but some - commodities will be hidden: +24.6.15.1 Wide layout +..................... - $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=wide,32 - Balance changes in 2012-01-01..2014-12-31: - - || 2012 2013 2014 Total - ==================++=========================================================================================================================== - Assets:US:ETrade || 10.00 ITOT, 337.18 USD, 2 more.. 70.00 GLD, 18.00 ITOT, 3 more.. -11.00 ITOT, 3 more.. 70.00 GLD, 17.00 ITOT, 3 more.. - ------------------++--------------------------------------------------------------------------------------------------------------------------- - || 10.00 ITOT, 337.18 USD, 2 more.. 70.00 GLD, 18.00 ITOT, 3 more.. -11.00 ITOT, 3 more.. 70.00 GLD, 17.00 ITOT, 3 more.. +With many commodities, reports can be very wide: - * Tall layout. Each commodity gets a new line (may be different in - each column), and account names are repeated: +$ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=wide +Balance changes in 2012-01-01..2014-12-31: - $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=tall - Balance changes in 2012-01-01..2014-12-31: - - || 2012 2013 2014 Total - ==================++================================================== - Assets:US:ETrade || 10.00 ITOT 70.00 GLD -11.00 ITOT 70.00 GLD - Assets:US:ETrade || 337.18 USD 18.00 ITOT 4881.44 USD 17.00 ITOT - Assets:US:ETrade || 12.00 VEA -98.12 USD 14.00 VEA 5120.50 USD - Assets:US:ETrade || 106.00 VHT 10.00 VEA 170.00 VHT 36.00 VEA - Assets:US:ETrade || 18.00 VHT 294.00 VHT - ------------------++-------------------------------------------------- - || 10.00 ITOT 70.00 GLD -11.00 ITOT 70.00 GLD - || 337.18 USD 18.00 ITOT 4881.44 USD 17.00 ITOT - || 12.00 VEA -98.12 USD 14.00 VEA 5120.50 USD - || 106.00 VHT 10.00 VEA 170.00 VHT 36.00 VEA - || 18.00 VHT 294.00 VHT - - * Bare layout. Commodity symbols are kept in one column, each - commodity gets its own report row, account names are repeated: - - $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=bare - Balance changes in 2012-01-01..2014-12-31: - - || Commodity 2012 2013 2014 Total - ==================++============================================= - Assets:US:ETrade || GLD 0 70.00 0 70.00 - Assets:US:ETrade || ITOT 10.00 18.00 -11.00 17.00 - Assets:US:ETrade || USD 337.18 -98.12 4881.44 5120.50 - Assets:US:ETrade || VEA 12.00 10.00 14.00 36.00 - Assets:US:ETrade || VHT 106.00 18.00 170.00 294.00 - ------------------++--------------------------------------------- - || GLD 0 70.00 0 70.00 - || ITOT 10.00 18.00 -11.00 17.00 - || USD 337.18 -98.12 4881.44 5120.50 - || VEA 12.00 10.00 14.00 36.00 - || VHT 106.00 18.00 170.00 294.00 - - * Bare layout also affects CSV output, which is useful for producing - data that is easier to consume, eg for making charts: - - $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -O csv --layout=bare - "account","commodity","balance" - "Assets:US:ETrade","GLD","70.00" - "Assets:US:ETrade","ITOT","17.00" - "Assets:US:ETrade","USD","5120.50" - "Assets:US:ETrade","VEA","36.00" - "Assets:US:ETrade","VHT","294.00" - "total","GLD","70.00" - "total","ITOT","17.00" - "total","USD","5120.50" - "total","VEA","36.00" - "total","VHT","294.00" - - * Note: bare layout will sometimes display an extra row for the - no-symbol commodity, because of zero amounts (hledger treats zeroes - as commodity-less, usually). This can break 'hledger-bar' - confusingly (workaround: add a 'cur:' query to exclude the - no-symbol row). - - * Tidy layout produces normalised "tidy data", where every variable - has its own column and each row represents a single data point. - See - https://cran.r-project.org/web/packages/tidyr/vignettes/tidy-data.html - for more. This is the easiest kind of data for other software to - consume. Here's how it looks: - - $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -Y -O csv --layout=tidy - "account","period","start_date","end_date","commodity","value" - "Assets:US:ETrade","2012","2012-01-01","2012-12-31","GLD","0" - "Assets:US:ETrade","2012","2012-01-01","2012-12-31","ITOT","10.00" - "Assets:US:ETrade","2012","2012-01-01","2012-12-31","USD","337.18" - "Assets:US:ETrade","2012","2012-01-01","2012-12-31","VEA","12.00" - "Assets:US:ETrade","2012","2012-01-01","2012-12-31","VHT","106.00" - "Assets:US:ETrade","2013","2013-01-01","2013-12-31","GLD","70.00" - "Assets:US:ETrade","2013","2013-01-01","2013-12-31","ITOT","18.00" - "Assets:US:ETrade","2013","2013-01-01","2013-12-31","USD","-98.12" - "Assets:US:ETrade","2013","2013-01-01","2013-12-31","VEA","10.00" - "Assets:US:ETrade","2013","2013-01-01","2013-12-31","VHT","18.00" - "Assets:US:ETrade","2014","2014-01-01","2014-12-31","GLD","0" - "Assets:US:ETrade","2014","2014-01-01","2014-12-31","ITOT","-11.00" - "Assets:US:ETrade","2014","2014-01-01","2014-12-31","USD","4881.44" - "Assets:US:ETrade","2014","2014-01-01","2014-12-31","VEA","14.00" - "Assets:US:ETrade","2014","2014-01-01","2014-12-31","VHT","170.00" - - -File: hledger.info, Node: Useful balance reports, Prev: Balance report layout, Up: balance - -24.6.16 Useful balance reports ------------------------------- + || 2012 2013 2014 Total +==================++==================================================================================================================================================================================================================== + Assets:US:ETrade || 10.00 ITOT, 337.18 USD, 12.00 VEA, 106.00 VHT 70.00 GLD, 18.00 ITOT, -98.12 USD, 10.00 VEA, 18.00 VHT -11.00 ITOT, 4881.44 USD, 14.00 VEA, 170.00 VHT 70.00 GLD, 17.00 ITOT, 5120.50 USD, 36.00 VEA, 294.00 VHT +------------------++-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- + || 10.00 ITOT, 337.18 USD, 12.00 VEA, 106.00 VHT 70.00 GLD, 18.00 ITOT, -98.12 USD, 10.00 VEA, 18.00 VHT -11.00 ITOT, 4881.44 USD, 14.00 VEA, 170.00 VHT 70.00 GLD, 17.00 ITOT, 5120.50 USD, 36.00 VEA, 294.00 VHT + + A width limit reduces the width, but some commodities will be hidden: + +$ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=wide,32 +Balance changes in 2012-01-01..2014-12-31: + + || 2012 2013 2014 Total +==================++=========================================================================================================================== + Assets:US:ETrade || 10.00 ITOT, 337.18 USD, 2 more.. 70.00 GLD, 18.00 ITOT, 3 more.. -11.00 ITOT, 3 more.. 70.00 GLD, 17.00 ITOT, 3 more.. +------------------++--------------------------------------------------------------------------------------------------------------------------- + || 10.00 ITOT, 337.18 USD, 2 more.. 70.00 GLD, 18.00 ITOT, 3 more.. -11.00 ITOT, 3 more.. 70.00 GLD, 17.00 ITOT, 3 more.. + + +File: hledger.info, Node: Tall layout, Next: Bare layout, Prev: Wide layout, Up: Balance report layout + +24.6.15.2 Tall layout +..................... + +Each commodity gets a new line (may be different in each column), and +account names are repeated: + +$ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=tall +Balance changes in 2012-01-01..2014-12-31: + + || 2012 2013 2014 Total +==================++================================================== + Assets:US:ETrade || 10.00 ITOT 70.00 GLD -11.00 ITOT 70.00 GLD + Assets:US:ETrade || 337.18 USD 18.00 ITOT 4881.44 USD 17.00 ITOT + Assets:US:ETrade || 12.00 VEA -98.12 USD 14.00 VEA 5120.50 USD + Assets:US:ETrade || 106.00 VHT 10.00 VEA 170.00 VHT 36.00 VEA + Assets:US:ETrade || 18.00 VHT 294.00 VHT +------------------++-------------------------------------------------- + || 10.00 ITOT 70.00 GLD -11.00 ITOT 70.00 GLD + || 337.18 USD 18.00 ITOT 4881.44 USD 17.00 ITOT + || 12.00 VEA -98.12 USD 14.00 VEA 5120.50 USD + || 106.00 VHT 10.00 VEA 170.00 VHT 36.00 VEA + || 18.00 VHT 294.00 VHT + + +File: hledger.info, Node: Bare layout, Next: Tidy layout, Prev: Tall layout, Up: Balance report layout + +24.6.15.3 Bare layout +..................... + +Commodity symbols are kept in one column, each commodity has its own +row, amounts are bare numbers, account names are repeated: + +$ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=bare +Balance changes in 2012-01-01..2014-12-31: + + || Commodity 2012 2013 2014 Total +==================++============================================= + Assets:US:ETrade || GLD 0 70.00 0 70.00 + Assets:US:ETrade || ITOT 10.00 18.00 -11.00 17.00 + Assets:US:ETrade || USD 337.18 -98.12 4881.44 5120.50 + Assets:US:ETrade || VEA 12.00 10.00 14.00 36.00 + Assets:US:ETrade || VHT 106.00 18.00 170.00 294.00 +------------------++--------------------------------------------- + || GLD 0 70.00 0 70.00 + || ITOT 10.00 18.00 -11.00 17.00 + || USD 337.18 -98.12 4881.44 5120.50 + || VEA 12.00 10.00 14.00 36.00 + || VHT 106.00 18.00 170.00 294.00 + + Bare layout also affects CSV output, which is useful for producing +data that is easier to consume, eg for making charts: + +$ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -O csv --layout=bare +"account","commodity","balance" +"Assets:US:ETrade","GLD","70.00" +"Assets:US:ETrade","ITOT","17.00" +"Assets:US:ETrade","USD","5120.50" +"Assets:US:ETrade","VEA","36.00" +"Assets:US:ETrade","VHT","294.00" +"total","GLD","70.00" +"total","ITOT","17.00" +"total","USD","5120.50" +"total","VEA","36.00" +"total","VHT","294.00" + + Bare layout will sometimes display an extra row for the no-symbol +commodity, because of zero amounts (hledger treats zeroes as +commodity-less, usually). This can break 'hledger-bar' confusingly +(workaround: add a 'cur:' query to exclude the no-symbol row). + + +File: hledger.info, Node: Tidy layout, Prev: Bare layout, Up: Balance report layout + +24.6.15.4 Tidy layout +..................... + +This produces normalised "tidy data" (see +https://cran.r-project.org/web/packages/tidyr/vignettes/tidy-data.html) +where every variable has its own column and each row represents a single +data point. This is the easiest kind of data for other software to +consume: + +$ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -Y -O csv --layout=tidy +"account","period","start_date","end_date","commodity","value" +"Assets:US:ETrade","2012","2012-01-01","2012-12-31","GLD","0" +"Assets:US:ETrade","2012","2012-01-01","2012-12-31","ITOT","10.00" +"Assets:US:ETrade","2012","2012-01-01","2012-12-31","USD","337.18" +"Assets:US:ETrade","2012","2012-01-01","2012-12-31","VEA","12.00" +"Assets:US:ETrade","2012","2012-01-01","2012-12-31","VHT","106.00" +"Assets:US:ETrade","2013","2013-01-01","2013-12-31","GLD","70.00" +"Assets:US:ETrade","2013","2013-01-01","2013-12-31","ITOT","18.00" +"Assets:US:ETrade","2013","2013-01-01","2013-12-31","USD","-98.12" +"Assets:US:ETrade","2013","2013-01-01","2013-12-31","VEA","10.00" +"Assets:US:ETrade","2013","2013-01-01","2013-12-31","VHT","18.00" +"Assets:US:ETrade","2014","2014-01-01","2014-12-31","GLD","0" +"Assets:US:ETrade","2014","2014-01-01","2014-12-31","ITOT","-11.00" +"Assets:US:ETrade","2014","2014-01-01","2014-12-31","USD","4881.44" +"Assets:US:ETrade","2014","2014-01-01","2014-12-31","VEA","14.00" +"Assets:US:ETrade","2014","2014-01-01","2014-12-31","VHT","170.00" + + +File: hledger.info, Node: Some useful balance reports, Prev: Balance report layout, Up: balance + +24.6.16 Some useful balance reports +----------------------------------- Some frequently used 'balance' options/reports are: @@ -9092,6 +9242,10 @@ balances in an opening transaction. These provide useful error checking, but you can ignore them temporarily with '-I', or remove them if you prefer. + Single-commodity, subaccount-exclusive balance assertions ('=') are +generated by default. This can be changed with '--assertion-type='==*'' +(eg). + When running 'close' you should probably avoid using '-C', '-R', 'status:' (filtering by status or realness) or '--auto' (generating postings), since the generated balance assertions would then require @@ -9392,61 +9546,63 @@ most common import source, and these docs focus on that case. * Menu: -* Deduplication:: +* "Deduplication":: * Import testing:: * Importing balance assignments:: * Commodity display styles::  -File: hledger.info, Node: Deduplication, Next: Import testing, Up: import +File: hledger.info, Node: "Deduplication", Next: Import testing, Up: import -24.19.1 Deduplication ---------------------- +24.19.1 "Deduplication" +----------------------- + +'import' tries to import only the transactions which are new since the +last import. So if your bank's CSV includes the last three months of +data, you can download and 'import' it every month (or week, or day) and +only the new transactions will be imported each time. -'import' does _time-based deduplication_, to detect only the new -transactions since the last successful import. (This does not mean -"ignore transactions that look the same", but rather "ignore -transactions that have been seen before".) This is intended for when -you are periodically importing downloaded data, which may overlap with -previous downloads. Eg if every week (or every day) you download a -bank's last three months of CSV data, you can safely run 'hledger import -thebank.csv' each time and only new transactions will be imported. + It works as follows. For each imported 'FILE' (usually a CSV file): +- It tries to find the latest date seen previously, by reading it from a +hidden '.latest.FILE' in the same directory. - Then it processes +'FILE', ignoring any transactions on or before the "latest seen" date. - Since the items being read (CSV records, eg) often do not come with -unique identifiers, hledger detects new transactions by date, assuming -that: + And after a successful import, it updates the '.latest.FILE'(s) for +next time (unless '--dry-run' was used). + + This is simple but fairly effective. It assumes: 1. new items always have the newest dates - 2. item dates do not change across reads - 3. and items with the same date remain in the same relative order - across reads. - - These are often true of CSV files representing transactions, or true -enough so that it works pretty well in practice. 1 is important, but -violations of 2 and 3 amongst the old transactions won't matter (and if -you import often, the new transactions will be few, so less likely to be -the ones affected). - - hledger remembers the latest date processed in each input file by -saving a hidden ".latest.FILE" file in FILE's directory (after a -succesful import). - - Eg when reading 'finance/bank.csv', it will look for and update the -'finance/.latest.bank.csv' state file. The format is simple: one or -more lines containing the same ISO-format date (YYYY-MM-DD), meaning "I -have processed transactions up to this date, and this many of them on -that date." Normally you won't see or manipulate these state files -yourself. But if needed, you can delete them to reset the state (making -all transactions "new"), or you can construct them to "catch up" to a -certain date. - - Note deduplication (and updating of state files) can also be done by -'print --new', but this is less often used. + 2. item dates are stable across successive CSV downloads + 3. the order of same-date items is stable across CSV downloads + + These are true of most CSV files representing transactions, or true +enough. If you have a bank whose CSV dates or ordering occasionally +changes, you can reduce the chance of this happening in new transactions +by importing more often (and in old transactions it doesn't matter). + + Note, 'import' avoids reprocessing the same dates across successive +runs, but it does not detect transactions that are duplicated within a +single run. So eg if you downloaded but did not import 'bank.1.csv', +and later downloaded 'bank.2.csv' with overlapping data, you should not +import both of them in a single run ('hledger import bank.1.csv +bank.2.csv'); instead, import them one at a time ('hledger import +bank.1.csv', then 'hledger import bank.2.csv'). + + Normally you can ignore the '.latest.*' files, but if needed, you can +delete them (to make all transactions unseen), or construct/modify them +(to catch up to a certain date). The format is just a single ISO-format +date ('YYYY-MM-DD'), possibly repeated on multiple lines. It means "I +have seen transactions up to this date, and this many of them occurring +on that date". + + ('hledger print --new' also uses and updates these '.latest.*' files, +but it is not often used.) Related: CSV > Working with CSV > Deduplicating, importing.  -File: hledger.info, Node: Import testing, Next: Importing balance assignments, Prev: Deduplication, Up: import +File: hledger.info, Node: Import testing, Next: Importing balance assignments, Prev: "Deduplication", Up: import 24.19.2 Import testing ---------------------- @@ -10304,37 +10460,45 @@ File: hledger.info, Node: stats, Next: tags, Prev: roi, Up: PART 4 COMMANDS Show journal and performance statistics. - The stats command displays summary information for the whole journal, -or a matched part of it. With a reporting interval, it shows a report -for each report period. + The stats command shows summary information for the whole journal, or +a matched part of it. With a reporting interval, it shows a report for +each report period. - At the end, it shows (in the terminal) the overall run time and -number of transactions processed per second. Note these are approximate -and will vary based on machine, current load, data size, hledger -version, haskell lib versions, GHC version.. but they may be of -interest. The 'stats' command's run time is similar to that of a -single-column balance report. + The default output is fairly impersonal, though it reveals the main +file name. With '-v/--verbose', more details are shown, like file +paths, included files, and commodity names. - Example: + It also shows some run time statistics: -$ hledger stats -f examples/1000x1000x10.journal -Main file : /Users/simon/src/hledger/examples/1000x1000x10.journal -Included files : -Transactions span : 2000-01-01 to 2002-09-27 (1000 days) -Last transaction : 2002-09-26 (6995 days ago) -Transactions : 1000 (1.0 per day) -Transactions last 30 days: 0 (0.0 per day) -Transactions last 7 days : 0 (0.0 per day) -Payees/descriptions : 1000 -Accounts : 1000 (depth 10) -Commodities : 26 (A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P, Q, R, S, T, U, V, W, X, Y, Z) -Market prices : 1000 (A) + * elapsed time + * throughput: the number of transactions processed per second + * live: the peak memory in use by the program to do its work + * alloc: the peak memory allocation from the OS as seen by GHC. + Measuring this externally, eg with GNU time, is more accurate; + usually that will be a larger number; sometimes (with swapping?) + smaller. + + The 'stats' command's run time is similar to that of a balance +report. + + Example: -Run time : 0.12 s -Throughput : 8342 txns/s +$ hledger stats -f examples/1ktxns-1kaccts.journal +Main file : .../1ktxns-1kaccts.journal +Included files : 0 +Txns span : 2000-01-01 to 2002-09-27 (1000 days) +Last txn : 2002-09-26 (7827 days ago) +Txns : 1000 (1.0 per day) +Txns last 30 days : 0 (0.0 per day) +Txns last 7 days : 0 (0.0 per day) +Payees/descriptions : 1000 +Accounts : 1000 (depth 10) +Commodities : 26 +Market prices : 1000 +Runtime stats : 0.12 s elapsed, 8266 txns/s, 4 MB live, 16 MB alloc This command supports the -o/-output-file option (but not --O/-output-format selection). +-O/-output-format).  File: hledger.info, Node: tags, Next: test, Prev: stats, Up: PART 4 COMMANDS @@ -10947,678 +11111,690 @@ See hledger and Ledger for full details.  Tag Table: Node: Top208 -Node: PART 1 USER INTERFACE3821 -Ref: #part-1-user-interface3960 -Node: Input3960 -Ref: #input4070 -Node: Data formats5019 -Ref: #data-formats5132 -Node: Standard input6721 -Ref: #standard-input6861 -Node: Multiple files7088 -Ref: #multiple-files7227 -Node: Strict mode7825 -Ref: #strict-mode7935 -Node: Commands8659 -Ref: #commands8761 -Node: Add-on commands9828 -Ref: #add-on-commands9930 -Node: Options11046 -Ref: #options11158 -Node: General help options11486 -Ref: #general-help-options11632 -Node: General input options11914 -Ref: #general-input-options12096 -Node: General reporting options12753 -Ref: #general-reporting-options12914 -Node: Command line tips16304 -Ref: #command-line-tips16434 -Node: Option repetition16693 -Ref: #option-repetition16837 -Node: Special characters16941 -Ref: #special-characters17114 -Node: Single escaping shell metacharacters17277 -Ref: #single-escaping-shell-metacharacters17518 -Node: Double escaping regular expression metacharacters18121 -Ref: #double-escaping-regular-expression-metacharacters18432 -Node: Triple escaping for add-on commands18958 -Ref: #triple-escaping-for-add-on-commands19218 -Node: Less escaping19862 -Ref: #less-escaping20016 -Node: Unicode characters20340 -Ref: #unicode-characters20515 -Node: Regular expressions21927 -Ref: #regular-expressions22100 -Node: hledger's regular expressions25196 -Ref: #hledgers-regular-expressions25355 -Node: Argument files26741 -Ref: #argument-files26877 -Node: Output27374 -Ref: #output27486 -Node: Output destination27613 -Ref: #output-destination27744 -Node: Output format28169 -Ref: #output-format28315 -Node: CSV output29912 -Ref: #csv-output30028 -Node: HTML output30131 -Ref: #html-output30269 -Node: JSON output30363 -Ref: #json-output30501 -Node: SQL output31423 -Ref: #sql-output31539 -Node: Commodity styles32274 -Ref: #commodity-styles32414 -Node: Colour33230 -Ref: #colour33348 -Node: Box-drawing33752 -Ref: #box-drawing33870 -Node: Paging34160 -Ref: #paging34274 -Node: Debug output35227 -Ref: #debug-output35333 -Node: Environment35996 -Ref: #environment36120 -Node: PART 2 DATA FORMATS36664 -Ref: #part-2-data-formats36807 -Node: Journal36807 -Ref: #journal36916 -Node: Journal cheatsheet37573 -Ref: #journal-cheatsheet37712 -Node: About journal format41697 -Ref: #about-journal-format41857 -Node: Comments43473 -Ref: #comments43603 -Node: Transactions44419 -Ref: #transactions44542 -Node: Dates45556 -Ref: #dates45663 -Node: Simple dates45708 -Ref: #simple-dates45824 -Node: Posting dates46324 -Ref: #posting-dates46442 -Node: Status47411 -Ref: #status47512 -Node: Code49220 -Ref: #code49323 -Node: Description49555 -Ref: #description49686 -Node: Payee and note50242 -Ref: #payee-and-note50348 -Node: Transaction comments51336 -Ref: #transaction-comments51489 -Node: Postings51852 -Ref: #postings51985 -Node: Account names52980 -Ref: #account-names53110 -Node: Amounts54784 -Ref: #amounts54899 -Node: Decimal marks digit group marks55902 -Ref: #decimal-marks-digit-group-marks56077 -Node: Commodity56936 -Ref: #commodity57123 -Node: Directives influencing number parsing and display58075 -Ref: #directives-influencing-number-parsing-and-display58334 -Node: Commodity display style58786 -Ref: #commodity-display-style58992 -Node: Rounding60402 -Ref: #rounding60542 -Node: Number format60992 -Ref: #number-format61110 -Node: Costs61324 -Ref: #costs61440 -Node: Other cost/lot notations63636 -Ref: #other-costlot-notations63768 -Node: Balance assertions66357 -Ref: #balance-assertions66508 -Node: Assertions and ordering67590 -Ref: #assertions-and-ordering67779 -Node: Assertions and multiple included files68479 -Ref: #assertions-and-multiple-included-files68739 -Node: Assertions and multiple -f files69239 -Ref: #assertions-and-multiple--f-files69490 -Node: Assertions and commodities69887 -Ref: #assertions-and-commodities70108 -Node: Assertions and costs71288 -Ref: #assertions-and-costs71491 -Node: Assertions and subaccounts71932 -Ref: #assertions-and-subaccounts72152 -Node: Assertions and virtual postings72476 -Ref: #assertions-and-virtual-postings72714 -Node: Assertions and auto postings72846 -Ref: #assertions-and-auto-postings73076 -Node: Assertions and precision73721 -Ref: #assertions-and-precision73903 -Node: Posting comments74170 -Ref: #posting-comments74316 -Node: Tags74693 -Ref: #tags74807 -Node: Tag names76150 -Ref: #tag-names76257 -Node: Special tags76645 -Ref: #special-tags76777 -Node: Tag values78277 -Ref: #tag-values78387 -Node: Directives79259 -Ref: #directives79386 -Node: Directives and multiple files80716 -Ref: #directives-and-multiple-files80894 -Node: Directive effects81661 -Ref: #directive-effects81815 -Node: account directive84828 -Ref: #account-directive84984 -Node: Account comments86278 -Ref: #account-comments86429 -Node: Account error checking86937 -Ref: #account-error-checking87130 -Node: Account display order88319 -Ref: #account-display-order88507 -Node: Account types89517 -Ref: #account-types89658 -Node: alias directive93291 -Ref: #alias-directive93452 -Node: Basic aliases94502 -Ref: #basic-aliases94633 -Node: Regex aliases95377 -Ref: #regex-aliases95534 -Node: Combining aliases96424 -Ref: #combining-aliases96602 -Node: Aliases and multiple files97878 -Ref: #aliases-and-multiple-files98082 -Node: end aliases directive98661 -Ref: #end-aliases-directive98880 -Node: Aliases can generate bad account names99029 -Ref: #aliases-can-generate-bad-account-names99277 -Node: Aliases and account types99862 -Ref: #aliases-and-account-types100054 -Node: commodity directive100750 -Ref: #commodity-directive100924 -Node: Commodity directive syntax102109 -Ref: #commodity-directive-syntax102294 -Node: Commodity error checking103745 -Ref: #commodity-error-checking103926 -Node: decimal-mark directive104220 -Ref: #decimal-mark-directive104402 -Node: include directive104799 -Ref: #include-directive104963 -Node: P directive105875 -Ref: #p-directive106020 -Node: payee directive106909 -Ref: #payee-directive107058 -Node: tag directive107531 -Ref: #tag-directive107686 -Node: Periodic transactions108143 -Ref: #periodic-transactions108308 -Node: Periodic rule syntax110297 -Ref: #periodic-rule-syntax110475 -Node: Periodic rules and relative dates111120 -Ref: #periodic-rules-and-relative-dates111386 -Node: Two spaces between period expression and description!111897 -Ref: #two-spaces-between-period-expression-and-description112174 -Node: Auto postings112858 -Ref: #auto-postings113006 -Node: Auto postings and multiple files115836 -Ref: #auto-postings-and-multiple-files116000 -Node: Auto postings and dates116401 -Ref: #auto-postings-and-dates116649 -Node: Auto postings and transaction balancing / inferred amounts / balance assertions116824 -Ref: #auto-postings-and-transaction-balancing-inferred-amounts-balance-assertions117180 -Node: Auto posting tags117683 -Ref: #auto-posting-tags117965 -Node: Auto postings on forecast transactions only118601 -Ref: #auto-postings-on-forecast-transactions-only118847 -Node: Other syntax119094 -Ref: #other-syntax119210 -Node: Balance assignments119837 -Ref: #balance-assignments119993 -Node: Balance assignments and costs121365 -Ref: #balance-assignments-and-costs121577 -Node: Balance assignments and multiple files121787 -Ref: #balance-assignments-and-multiple-files122017 -Node: Bracketed posting dates122210 -Ref: #bracketed-posting-dates122394 -Node: D directive122908 -Ref: #d-directive123076 -Node: apply account directive124676 -Ref: #apply-account-directive124856 -Node: Y directive125543 -Ref: #y-directive125703 -Node: Secondary dates126531 -Ref: #secondary-dates126685 -Node: Star comments127499 -Ref: #star-comments127659 -Node: Valuation expressions128191 -Ref: #valuation-expressions128368 -Node: Virtual postings128490 -Ref: #virtual-postings128667 -Node: Other Ledger directives130104 -Ref: #other-ledger-directives130267 -Node: CSV130833 -Ref: #csv130926 -Node: CSV rules cheatsheet133006 -Ref: #csv-rules-cheatsheet133135 -Node: source134933 -Ref: #source135056 -Node: separator135936 -Ref: #separator136049 -Node: skip136589 -Ref: #skip136697 -Node: date-format137241 -Ref: #date-format137362 -Node: timezone138086 -Ref: #timezone138209 -Node: newest-first139214 -Ref: #newest-first139352 -Node: intra-day-reversed139929 -Ref: #intra-day-reversed140083 -Node: decimal-mark140531 -Ref: #decimal-mark140672 -Node: fields list141011 -Ref: #fields-list141150 -Node: Field assignment142821 -Ref: #field-assignment142965 -Node: Field names144042 -Ref: #field-names144173 -Node: date field145376 -Ref: #date-field145494 -Node: date2 field145542 -Ref: #date2-field145683 -Node: status field145739 -Ref: #status-field145882 -Node: code field145931 -Ref: #code-field146076 -Node: description field146121 -Ref: #description-field146281 -Node: comment field146340 -Ref: #comment-field146495 -Node: account field146788 -Ref: #account-field146938 -Node: amount field147508 -Ref: #amount-field147657 -Node: currency field150349 -Ref: #currency-field150502 -Node: balance field150759 -Ref: #balance-field150891 -Node: if block151263 -Ref: #if-block151384 -Node: Matchers152792 -Ref: #matchers152906 -Node: What matchers match153703 -Ref: #what-matchers-match153852 -Node: Combining matchers154292 -Ref: #combining-matchers154460 -Node: Match groups154962 -Ref: #match-groups155090 -Node: if table155858 -Ref: #if-table155980 -Node: balance-type157542 -Ref: #balance-type157671 -Node: include158371 -Ref: #include158498 -Node: Working with CSV158942 -Ref: #working-with-csv159089 -Node: Rapid feedback159496 -Ref: #rapid-feedback159629 -Node: Valid CSV160081 -Ref: #valid-csv160227 -Node: File Extension160959 -Ref: #file-extension161132 -Node: Reading CSV from standard input161696 -Ref: #reading-csv-from-standard-input161920 -Node: Reading multiple CSV files162084 -Ref: #reading-multiple-csv-files162315 -Node: Reading files specified by rule162556 -Ref: #reading-files-specified-by-rule162784 -Node: Valid transactions163955 -Ref: #valid-transactions164154 -Node: Deduplicating importing164782 -Ref: #deduplicating-importing164977 -Node: Setting amounts166013 -Ref: #setting-amounts166184 -Node: Amount signs168542 -Ref: #amount-signs168712 -Node: Setting currency/commodity169609 -Ref: #setting-currencycommodity169813 -Node: Amount decimal places170987 -Ref: #amount-decimal-places171193 -Node: Referencing other fields171505 -Ref: #referencing-other-fields171718 -Node: How CSV rules are evaluated172615 -Ref: #how-csv-rules-are-evaluated172832 -Node: Well factored rules174285 -Ref: #well-factored-rules174453 -Node: CSV rules examples174777 -Ref: #csv-rules-examples174912 -Node: Bank of Ireland174977 -Ref: #bank-of-ireland175114 -Node: Coinbase176576 -Ref: #coinbase176714 -Node: Amazon177761 -Ref: #amazon177886 -Node: Paypal179605 -Ref: #paypal179713 -Node: Timeclock187357 -Ref: #timeclock187462 -Node: Timedot189640 -Ref: #timedot189763 -Node: Timedot examples192884 -Ref: #timedot-examples192990 -Node: PART 3 REPORTING CONCEPTS195161 -Ref: #part-3-reporting-concepts195343 -Node: Amount formatting parseability195343 -Ref: #amount-formatting-parseability195540 -Node: Time periods197745 -Ref: #time-periods197884 -Node: Report start & end date198002 -Ref: #report-start-end-date198154 -Node: Smart dates199813 -Ref: #smart-dates199966 -Node: Report intervals201834 -Ref: #report-intervals201989 -Node: Date adjustment202407 -Ref: #date-adjustment202567 -Node: Period expressions203418 -Ref: #period-expressions203559 -Node: Period expressions with a report interval205323 -Ref: #period-expressions-with-a-report-interval205557 -Node: More complex report intervals205771 -Ref: #more-complex-report-intervals206016 -Node: Multiple weekday intervals207817 -Ref: #multiple-weekday-intervals208006 -Node: Depth208828 -Ref: #depth208930 -Node: Queries209226 -Ref: #queries209328 -Node: Query types210958 -Ref: #query-types211079 -Node: Combining query terms214313 -Ref: #combining-query-terms214490 -Node: Queries and command options215758 -Ref: #queries-and-command-options215957 -Node: Queries and valuation216206 -Ref: #queries-and-valuation216401 -Node: Querying with account aliases216630 -Ref: #querying-with-account-aliases216841 -Node: Querying with cost or value216971 -Ref: #querying-with-cost-or-value217148 -Node: Pivoting217449 -Ref: #pivoting217563 -Node: Generating data219340 -Ref: #generating-data219472 -Node: Forecasting221055 -Ref: #forecasting221180 -Node: --forecast221711 -Ref: #forecast221842 -Node: Inspecting forecast transactions222812 -Ref: #inspecting-forecast-transactions223014 -Node: Forecast reports224144 -Ref: #forecast-reports224317 -Node: Forecast tags225253 -Ref: #forecast-tags225413 -Node: Forecast period in detail225873 -Ref: #forecast-period-in-detail226067 -Node: Forecast troubleshooting226961 -Ref: #forecast-troubleshooting227129 -Node: Budgeting228032 -Ref: #budgeting228152 -Node: Cost reporting228589 -Ref: #cost-reporting228723 -Node: Recording costs229384 -Ref: #recording-costs229520 -Node: Reporting at cost231111 -Ref: #reporting-at-cost231286 -Node: Equity conversion postings231876 -Ref: #equity-conversion-postings232090 -Node: Inferring equity conversion postings234521 -Ref: #inferring-equity-conversion-postings234784 -Node: Combining costs and equity conversion postings235536 -Ref: #combining-costs-and-equity-conversion-postings235846 -Node: Requirements for detecting equity conversion postings236761 -Ref: #requirements-for-detecting-equity-conversion-postings237083 -Node: Infer cost and equity by default ?238283 -Ref: #infer-cost-and-equity-by-default238512 -Node: Value reporting238720 -Ref: #value-reporting238862 -Node: -V Value239636 -Ref: #v-value239768 -Node: -X Value in specified commodity239963 -Ref: #x-value-in-specified-commodity240164 -Node: Valuation date240313 -Ref: #valuation-date240490 -Node: Finding market price241273 -Ref: #finding-market-price241484 -Node: --infer-market-prices market prices from transactions242653 -Ref: #infer-market-prices-market-prices-from-transactions242935 -Node: Valuation commodity245697 -Ref: #valuation-commodity245916 -Node: Simple valuation examples247129 -Ref: #simple-valuation-examples247333 -Node: --value Flexible valuation247992 -Ref: #value-flexible-valuation248202 -Node: More valuation examples249846 -Ref: #more-valuation-examples250061 -Node: Interaction of valuation and queries251331 -Ref: #interaction-of-valuation-and-queries251578 -Node: Effect of valuation on reports252050 -Ref: #effect-of-valuation-on-reports252253 -Node: PART 4 COMMANDS259950 -Ref: #part-4-commands260099 -Node: Commands overview260478 -Ref: #commands-overview260612 -Node: DATA ENTRY260791 -Ref: #data-entry260915 -Node: DATA CREATION261114 -Ref: #data-creation261268 -Node: DATA MANAGEMENT261386 -Ref: #data-management261551 -Node: REPORTS FINANCIAL261672 -Ref: #reports-financial261847 -Node: REPORTS VERSATILE262152 -Ref: #reports-versatile262325 -Node: REPORTS BASIC262578 -Ref: #reports-basic262730 -Node: HELP263239 -Ref: #help263361 -Node: ADD-ONS263471 -Ref: #add-ons263577 -Node: accounts264156 -Ref: #accounts264289 -Node: activity266176 -Ref: #activity266295 -Node: add266669 -Ref: #add266779 -Node: aregister269765 -Ref: #aregister269886 -Node: aregister and posting dates272792 -Ref: #aregister-and-posting-dates272937 -Node: balance273693 -Ref: #balance273819 -Node: balance features274804 -Ref: #balance-features274944 -Node: Simple balance report276928 -Ref: #simple-balance-report277113 -Node: Balance report line format278738 -Ref: #balance-report-line-format278940 -Node: Filtered balance report281098 -Ref: #filtered-balance-report281290 -Node: List or tree mode281617 -Ref: #list-or-tree-mode281785 -Node: Depth limiting283130 -Ref: #depth-limiting283296 -Node: Dropping top-level accounts283897 -Ref: #dropping-top-level-accounts284097 -Node: Showing declared accounts284407 -Ref: #showing-declared-accounts284606 -Node: Sorting by amount285137 -Ref: #sorting-by-amount285304 -Node: Percentages285974 -Ref: #percentages286133 -Node: Multi-period balance report286681 -Ref: #multi-period-balance-report286881 -Node: Balance change end balance289138 -Ref: #balance-change-end-balance289347 -Node: Balance report types290775 -Ref: #balance-report-types290956 -Node: Calculation type291454 -Ref: #calculation-type291609 -Node: Accumulation type292158 -Ref: #accumulation-type292338 -Node: Valuation type293240 -Ref: #valuation-type293428 -Node: Combining balance report types294429 -Ref: #combining-balance-report-types294623 -Node: Budget report296461 -Ref: #budget-report296623 -Node: Using the budget report298766 -Ref: #using-the-budget-report298939 -Node: Budget date surprises301042 -Ref: #budget-date-surprises301242 -Node: Selecting budget goals302406 -Ref: #selecting-budget-goals302609 -Node: Budgeting vs forecasting303354 -Ref: #budgeting-vs-forecasting303531 -Node: Balance report layout304802 -Ref: #balance-report-layout304982 -Node: Useful balance reports313167 -Ref: #useful-balance-reports313327 -Node: balancesheet314412 -Ref: #balancesheet314557 -Node: balancesheetequity315887 -Ref: #balancesheetequity316045 -Node: cashflow317426 -Ref: #cashflow317557 -Node: check318995 -Ref: #check319109 -Node: Default checks319913 -Ref: #default-checks320039 -Node: Strict checks320536 -Ref: #strict-checks320681 -Node: Other checks321161 -Ref: #other-checks321303 -Node: Custom checks321836 -Ref: #custom-checks321993 -Node: More about specific checks322410 -Ref: #more-about-specific-checks322572 -Node: close323278 -Ref: #close323389 -Node: close --migrate324042 -Ref: #close---migrate324169 -Node: close --close325808 -Ref: #close---close325952 -Node: close --open326188 -Ref: #close---open326329 -Node: close --assert326439 -Ref: #close---assert326585 -Node: close --assign326806 -Ref: #close---assign326954 -Node: close --retain327480 -Ref: #close---retain327633 -Node: close customisation328378 -Ref: #close-customisation328557 -Node: close and balance assertions330024 -Ref: #close-and-balance-assertions330221 -Node: close examples331397 -Ref: #close-examples331538 -Node: Retain earnings331636 -Ref: #retain-earnings331795 -Node: Migrate balances to a new file332141 -Ref: #migrate-balances-to-a-new-file332367 -Node: More detailed close examples333495 -Ref: #more-detailed-close-examples333693 -Node: codes333719 -Ref: #codes333836 -Node: commodities334700 -Ref: #commodities334828 -Node: demo334898 -Ref: #demo335019 -Node: descriptions335935 -Ref: #descriptions336065 -Node: diff336356 -Ref: #diff336471 -Node: files337513 -Ref: #files337622 -Node: help337763 -Ref: #help-1337872 -Node: import339245 -Ref: #import339368 -Node: Deduplication340476 -Ref: #deduplication340601 -Node: Import testing342620 -Ref: #import-testing342785 -Node: Importing balance assignments343628 -Ref: #importing-balance-assignments343834 -Node: Commodity display styles344483 -Ref: #commodity-display-styles344656 -Node: incomestatement344785 -Ref: #incomestatement344927 -Node: notes346258 -Ref: #notes346380 -Node: payees346742 -Ref: #payees346857 -Node: prices347376 -Ref: #prices347491 -Node: print348144 -Ref: #print348259 -Node: print explicitness349235 -Ref: #print-explicitness349378 -Node: print amount style350157 -Ref: #print-amount-style350327 -Node: print parseability351397 -Ref: #print-parseability351569 -Node: print other features352318 -Ref: #print-other-features352497 -Node: print output format353018 -Ref: #print-output-format353166 -Node: register356305 -Ref: #register356427 -Node: Custom register output361458 -Ref: #custom-register-output361589 -Node: rewrite362936 -Ref: #rewrite363054 -Node: Re-write rules in a file364952 -Ref: #re-write-rules-in-a-file365115 -Node: Diff output format366264 -Ref: #diff-output-format366447 -Node: rewrite vs print --auto367539 -Ref: #rewrite-vs.-print---auto367699 -Node: roi368255 -Ref: #roi368362 -Node: Spaces and special characters in --inv and --pnl370174 -Ref: #spaces-and-special-characters-in---inv-and---pnl370414 -Node: Semantics of --inv and --pnl370902 -Ref: #semantics-of---inv-and---pnl371141 -Node: IRR and TWR explained372991 -Ref: #irr-and-twr-explained373151 -Node: stats376404 -Ref: #stats376512 -Node: tags377899 -Ref: #tags-1378006 -Node: test379015 -Ref: #test379108 -Node: PART 5 COMMON TASKS379850 -Ref: #part-5-common-tasks379996 -Node: Getting help380294 -Ref: #getting-help380435 -Node: Constructing command lines381195 -Ref: #constructing-command-lines381396 -Node: Starting a journal file382053 -Ref: #starting-a-journal-file382255 -Node: Setting LEDGER_FILE383457 -Ref: #setting-ledger_file383649 -Node: Setting opening balances384606 -Ref: #setting-opening-balances384807 -Node: Recording transactions387948 -Ref: #recording-transactions388137 -Node: Reconciling388693 -Ref: #reconciling388845 -Node: Reporting391102 -Ref: #reporting391251 -Node: Migrating to a new file395236 -Ref: #migrating-to-a-new-file395393 -Node: BUGS395692 -Ref: #bugs395782 -Node: Troubleshooting396661 -Ref: #troubleshooting396761 +Node: PART 1 USER INTERFACE3812 +Ref: #part-1-user-interface3951 +Node: Input3951 +Ref: #input4061 +Node: Text encoding5028 +Ref: #text-encoding5142 +Node: Data formats5620 +Ref: #data-formats5755 +Node: Standard input7344 +Ref: #standard-input7484 +Node: Multiple files7711 +Ref: #multiple-files7850 +Node: Strict mode8448 +Ref: #strict-mode8558 +Node: Commands9282 +Ref: #commands9384 +Node: Add-on commands10451 +Ref: #add-on-commands10553 +Node: Options11669 +Ref: #options11781 +Node: General help options12109 +Ref: #general-help-options12255 +Node: General input options12537 +Ref: #general-input-options12719 +Node: General reporting options13376 +Ref: #general-reporting-options13537 +Node: Command line tips16927 +Ref: #command-line-tips17057 +Node: Option repetition17316 +Ref: #option-repetition17460 +Node: Special characters17564 +Ref: #special-characters17737 +Node: Single escaping shell metacharacters17900 +Ref: #single-escaping-shell-metacharacters18141 +Node: Double escaping regular expression metacharacters18744 +Ref: #double-escaping-regular-expression-metacharacters19055 +Node: Triple escaping for add-on commands19581 +Ref: #triple-escaping-for-add-on-commands19841 +Node: Less escaping20485 +Ref: #less-escaping20639 +Node: Unicode characters20963 +Ref: #unicode-characters21138 +Node: Regular expressions22550 +Ref: #regular-expressions22723 +Node: hledger's regular expressions25819 +Ref: #hledgers-regular-expressions25978 +Node: Argument files27364 +Ref: #argument-files27500 +Node: Output27997 +Ref: #output28109 +Node: Output destination28236 +Ref: #output-destination28367 +Node: Output format28792 +Ref: #output-format28938 +Node: CSV output30535 +Ref: #csv-output30651 +Node: HTML output30754 +Ref: #html-output30892 +Node: JSON output30986 +Ref: #json-output31124 +Node: SQL output32046 +Ref: #sql-output32162 +Node: Commodity styles32897 +Ref: #commodity-styles33037 +Node: Colour33775 +Ref: #colour33893 +Node: Box-drawing34297 +Ref: #box-drawing34415 +Node: Paging34705 +Ref: #paging34819 +Node: Debug output35772 +Ref: #debug-output35878 +Node: Environment36541 +Ref: #environment36665 +Node: PART 2 DATA FORMATS37209 +Ref: #part-2-data-formats37352 +Node: Journal37352 +Ref: #journal37461 +Node: Journal cheatsheet39829 +Ref: #journal-cheatsheet39956 +Node: Comments46043 +Ref: #comments46171 +Node: Transactions46987 +Ref: #transactions47110 +Node: Dates48124 +Ref: #dates48231 +Node: Simple dates48276 +Ref: #simple-dates48392 +Node: Posting dates48892 +Ref: #posting-dates49010 +Node: Status49979 +Ref: #status50080 +Node: Code51745 +Ref: #code51848 +Node: Description52080 +Ref: #description52211 +Node: Payee and note52767 +Ref: #payee-and-note52873 +Node: Transaction comments53858 +Ref: #transaction-comments54011 +Node: Postings54374 +Ref: #postings54505 +Node: Debits and credits55537 +Ref: #debits-and-credits55684 +Node: The two space delimiter56147 +Ref: #the-two-space-delimiter56304 +Node: Account names56712 +Ref: #account-names56842 +Node: Amounts58516 +Ref: #amounts58644 +Node: Decimal marks59545 +Ref: #decimal-marks59672 +Node: Digit group marks60649 +Ref: #digit-group-marks60802 +Node: Commodity61284 +Ref: #commodity61413 +Node: Costs62401 +Ref: #costs62496 +Node: Balance assertions64653 +Ref: #balance-assertions64806 +Node: Assertions and ordering65888 +Ref: #assertions-and-ordering66077 +Node: Assertions and multiple included files66777 +Ref: #assertions-and-multiple-included-files67037 +Node: Assertions and multiple -f files67537 +Ref: #assertions-and-multiple--f-files67788 +Node: Assertions and commodities68185 +Ref: #assertions-and-commodities68406 +Node: Assertions and costs69586 +Ref: #assertions-and-costs69789 +Node: Assertions and subaccounts70230 +Ref: #assertions-and-subaccounts70450 +Node: Assertions and virtual postings70774 +Ref: #assertions-and-virtual-postings71012 +Node: Assertions and auto postings71144 +Ref: #assertions-and-auto-postings71374 +Node: Assertions and precision72019 +Ref: #assertions-and-precision72201 +Node: Posting comments72468 +Ref: #posting-comments72631 +Node: Transaction balancing73008 +Ref: #transaction-balancing73167 +Node: Tags75010 +Ref: #tags75129 +Node: Tag names76472 +Ref: #tag-names76579 +Node: Special tags76967 +Ref: #special-tags77099 +Node: Tag values78612 +Ref: #tag-values78722 +Node: Directives79594 +Ref: #directives79721 +Node: Directives and multiple files81051 +Ref: #directives-and-multiple-files81229 +Node: Directive effects81996 +Ref: #directive-effects82150 +Node: account directive85152 +Ref: #account-directive85308 +Node: Account comments86602 +Ref: #account-comments86753 +Node: Account error checking87261 +Ref: #account-error-checking87454 +Node: Account display order88643 +Ref: #account-display-order88831 +Node: Account types89841 +Ref: #account-types89982 +Node: alias directive93615 +Ref: #alias-directive93776 +Node: Basic aliases94826 +Ref: #basic-aliases94957 +Node: Regex aliases95701 +Ref: #regex-aliases95858 +Node: Combining aliases96748 +Ref: #combining-aliases96926 +Node: Aliases and multiple files98202 +Ref: #aliases-and-multiple-files98406 +Node: end aliases directive98985 +Ref: #end-aliases-directive99204 +Node: Aliases can generate bad account names99353 +Ref: #aliases-can-generate-bad-account-names99601 +Node: Aliases and account types100186 +Ref: #aliases-and-account-types100378 +Node: commodity directive101074 +Ref: #commodity-directive101248 +Node: Commodity directive syntax102661 +Ref: #commodity-directive-syntax102846 +Node: Commodity error checking104297 +Ref: #commodity-error-checking104478 +Node: decimal-mark directive104772 +Ref: #decimal-mark-directive104954 +Node: include directive105351 +Ref: #include-directive105515 +Node: P directive106427 +Ref: #p-directive106572 +Node: payee directive107461 +Ref: #payee-directive107610 +Node: tag directive108083 +Ref: #tag-directive108238 +Node: Periodic transactions108695 +Ref: #periodic-transactions108860 +Node: Periodic rule syntax110849 +Ref: #periodic-rule-syntax111027 +Node: Periodic rules and relative dates111672 +Ref: #periodic-rules-and-relative-dates111938 +Node: Two spaces between period expression and description!112449 +Ref: #two-spaces-between-period-expression-and-description112726 +Node: Auto postings113410 +Ref: #auto-postings113558 +Node: Auto postings and multiple files116388 +Ref: #auto-postings-and-multiple-files116552 +Node: Auto postings and dates116953 +Ref: #auto-postings-and-dates117201 +Node: Auto postings and transaction balancing / inferred amounts / balance assertions117376 +Ref: #auto-postings-and-transaction-balancing-inferred-amounts-balance-assertions117732 +Node: Auto posting tags118235 +Ref: #auto-posting-tags118517 +Node: Auto postings on forecast transactions only119153 +Ref: #auto-postings-on-forecast-transactions-only119399 +Node: Other syntax119646 +Ref: #other-syntax119762 +Node: Balance assignments120418 +Ref: #balance-assignments120574 +Node: Balance assignments and costs121946 +Ref: #balance-assignments-and-costs122158 +Node: Balance assignments and multiple files122368 +Ref: #balance-assignments-and-multiple-files122598 +Node: Bracketed posting dates122791 +Ref: #bracketed-posting-dates122975 +Node: D directive123489 +Ref: #d-directive123657 +Node: apply account directive125257 +Ref: #apply-account-directive125437 +Node: Y directive126124 +Ref: #y-directive126284 +Node: Secondary dates127112 +Ref: #secondary-dates127266 +Node: Star comments128080 +Ref: #star-comments128240 +Node: Valuation expressions128772 +Ref: #valuation-expressions128949 +Node: Virtual postings129071 +Ref: #virtual-postings129248 +Node: Other Ledger directives130685 +Ref: #other-ledger-directives130881 +Node: Other cost/lot notations131447 +Ref: #other-costlot-notations131620 +Node: CSV134209 +Ref: #csv134302 +Node: CSV rules cheatsheet136299 +Ref: #csv-rules-cheatsheet136428 +Node: source138226 +Ref: #source138349 +Node: separator139229 +Ref: #separator139342 +Node: skip139882 +Ref: #skip139990 +Node: date-format140534 +Ref: #date-format140655 +Node: timezone141379 +Ref: #timezone141502 +Node: newest-first142507 +Ref: #newest-first142645 +Node: intra-day-reversed143222 +Ref: #intra-day-reversed143376 +Node: decimal-mark143824 +Ref: #decimal-mark143965 +Node: fields list144304 +Ref: #fields-list144443 +Node: Field assignment146114 +Ref: #field-assignment146258 +Node: Field names147335 +Ref: #field-names147466 +Node: date field148669 +Ref: #date-field148787 +Node: date2 field148835 +Ref: #date2-field148976 +Node: status field149032 +Ref: #status-field149175 +Node: code field149224 +Ref: #code-field149369 +Node: description field149414 +Ref: #description-field149574 +Node: comment field149633 +Ref: #comment-field149788 +Node: account field150081 +Ref: #account-field150231 +Node: amount field150801 +Ref: #amount-field150950 +Node: currency field153642 +Ref: #currency-field153795 +Node: balance field154052 +Ref: #balance-field154184 +Node: if block154577 +Ref: #if-block154698 +Node: Matchers156106 +Ref: #matchers156220 +Node: What matchers match157017 +Ref: #what-matchers-match157166 +Node: Combining matchers157606 +Ref: #combining-matchers157774 +Node: Match groups158311 +Ref: #match-groups158439 +Node: if table159207 +Ref: #if-table159329 +Node: balance-type161210 +Ref: #balance-type161339 +Node: include162039 +Ref: #include162166 +Node: Working with CSV162610 +Ref: #working-with-csv162757 +Node: Rapid feedback163164 +Ref: #rapid-feedback163297 +Node: Valid CSV163749 +Ref: #valid-csv163895 +Node: File Extension164627 +Ref: #file-extension164800 +Node: Reading CSV from standard input165364 +Ref: #reading-csv-from-standard-input165588 +Node: Reading multiple CSV files165752 +Ref: #reading-multiple-csv-files165983 +Node: Reading files specified by rule166224 +Ref: #reading-files-specified-by-rule166452 +Node: Valid transactions167623 +Ref: #valid-transactions167822 +Node: Deduplicating importing168450 +Ref: #deduplicating-importing168645 +Node: Setting amounts169681 +Ref: #setting-amounts169852 +Node: Amount signs172210 +Ref: #amount-signs172380 +Node: Setting currency/commodity173277 +Ref: #setting-currencycommodity173481 +Node: Amount decimal places174655 +Ref: #amount-decimal-places174861 +Node: Referencing other fields175173 +Ref: #referencing-other-fields175386 +Node: How CSV rules are evaluated176283 +Ref: #how-csv-rules-are-evaluated176500 +Node: Well factored rules177953 +Ref: #well-factored-rules178121 +Node: CSV rules examples178445 +Ref: #csv-rules-examples178580 +Node: Bank of Ireland178645 +Ref: #bank-of-ireland178782 +Node: Coinbase180244 +Ref: #coinbase180382 +Node: Amazon181429 +Ref: #amazon181554 +Node: Paypal183273 +Ref: #paypal183381 +Node: Timeclock191025 +Ref: #timeclock191130 +Node: Timedot193306 +Ref: #timedot193429 +Node: Timedot examples196550 +Ref: #timedot-examples196656 +Node: PART 3 REPORTING CONCEPTS198827 +Ref: #part-3-reporting-concepts198996 +Node: Amount formatting198996 +Ref: #amount-formatting199152 +Node: Commodity display style199254 +Ref: #commodity-display-style199408 +Node: Rounding201095 +Ref: #rounding201250 +Node: Trailing decimal marks201700 +Ref: #trailing-decimal-marks201879 +Node: Amount parseability202633 +Ref: #amount-parseability202789 +Node: Time periods204214 +Ref: #time-periods204340 +Node: Report start & end date204458 +Ref: #report-start-end-date204610 +Node: Smart dates206269 +Ref: #smart-dates206422 +Node: Report intervals208290 +Ref: #report-intervals208445 +Node: Date adjustment208863 +Ref: #date-adjustment209023 +Node: Period expressions209874 +Ref: #period-expressions210015 +Node: Period expressions with a report interval211779 +Ref: #period-expressions-with-a-report-interval212013 +Node: More complex report intervals212227 +Ref: #more-complex-report-intervals212472 +Node: Multiple weekday intervals214273 +Ref: #multiple-weekday-intervals214462 +Node: Depth215284 +Ref: #depth215386 +Node: Queries215682 +Ref: #queries215784 +Node: Query types217380 +Ref: #query-types217501 +Node: Combining query terms220735 +Ref: #combining-query-terms220912 +Node: Queries and command options222147 +Ref: #queries-and-command-options222352 +Node: Queries and account aliases222601 +Ref: #queries-and-account-aliases222806 +Node: Queries and valuation222926 +Ref: #queries-and-valuation223083 +Node: Pivoting223288 +Ref: #pivoting223402 +Node: Generating data225179 +Ref: #generating-data225311 +Node: Forecasting226894 +Ref: #forecasting227019 +Node: --forecast227550 +Ref: #forecast227681 +Node: Inspecting forecast transactions228651 +Ref: #inspecting-forecast-transactions228853 +Node: Forecast reports229983 +Ref: #forecast-reports230156 +Node: Forecast tags231092 +Ref: #forecast-tags231252 +Node: Forecast period in detail231712 +Ref: #forecast-period-in-detail231906 +Node: Forecast troubleshooting232800 +Ref: #forecast-troubleshooting232968 +Node: Budgeting233871 +Ref: #budgeting233991 +Node: Cost reporting234428 +Ref: #cost-reporting234562 +Node: Recording costs235223 +Ref: #recording-costs235359 +Node: Reporting at cost236950 +Ref: #reporting-at-cost237125 +Node: Equity conversion postings237715 +Ref: #equity-conversion-postings237929 +Node: Inferring equity conversion postings240360 +Ref: #inferring-equity-conversion-postings240623 +Node: Combining costs and equity conversion postings241375 +Ref: #combining-costs-and-equity-conversion-postings241685 +Node: Requirements for detecting equity conversion postings242600 +Ref: #requirements-for-detecting-equity-conversion-postings242922 +Node: Infer cost and equity by default ?244122 +Ref: #infer-cost-and-equity-by-default244351 +Node: Value reporting244559 +Ref: #value-reporting244701 +Node: -V Value245440 +Ref: #v-value245572 +Node: -X Value in specified commodity245767 +Ref: #x-value-in-specified-commodity245968 +Node: Valuation date246117 +Ref: #valuation-date246294 +Node: Finding market price247077 +Ref: #finding-market-price247288 +Node: --infer-market-prices market prices from transactions248457 +Ref: #infer-market-prices-market-prices-from-transactions248739 +Node: Valuation commodity251501 +Ref: #valuation-commodity251721 +Node: --value Flexible valuation252934 +Ref: #value-flexible-valuation253133 +Node: Valuation examples254777 +Ref: #valuation-examples254977 +Node: Interaction of valuation and queries256909 +Ref: #interaction-of-valuation-and-queries257149 +Node: Effect of valuation on reports257626 +Ref: #effect-of-valuation-on-reports257829 +Node: PART 4 COMMANDS265524 +Ref: #part-4-commands265673 +Node: Commands overview266052 +Ref: #commands-overview266186 +Node: DATA ENTRY266365 +Ref: #data-entry266489 +Node: DATA CREATION266688 +Ref: #data-creation266842 +Node: DATA MANAGEMENT266960 +Ref: #data-management267125 +Node: REPORTS FINANCIAL267246 +Ref: #reports-financial267421 +Node: REPORTS VERSATILE267726 +Ref: #reports-versatile267899 +Node: REPORTS BASIC268152 +Ref: #reports-basic268304 +Node: HELP268813 +Ref: #help268935 +Node: ADD-ONS269045 +Ref: #add-ons269151 +Node: accounts269730 +Ref: #accounts269863 +Node: activity271750 +Ref: #activity271869 +Node: add272243 +Ref: #add272353 +Node: aregister275339 +Ref: #aregister275460 +Node: aregister and posting dates278366 +Ref: #aregister-and-posting-dates278511 +Node: balance279267 +Ref: #balance279393 +Node: balance features280383 +Ref: #balance-features280523 +Node: Simple balance report282433 +Ref: #simple-balance-report282618 +Node: Balance report line format284243 +Ref: #balance-report-line-format284445 +Node: Filtered balance report286603 +Ref: #filtered-balance-report286795 +Node: List or tree mode287122 +Ref: #list-or-tree-mode287290 +Node: Depth limiting288635 +Ref: #depth-limiting288801 +Node: Dropping top-level accounts289402 +Ref: #dropping-top-level-accounts289602 +Node: Showing declared accounts289912 +Ref: #showing-declared-accounts290111 +Node: Sorting by amount290642 +Ref: #sorting-by-amount290809 +Node: Percentages291479 +Ref: #percentages291638 +Node: Multi-period balance report292186 +Ref: #multi-period-balance-report292386 +Node: Balance change end balance294763 +Ref: #balance-change-end-balance294972 +Node: Balance report types296400 +Ref: #balance-report-types296581 +Node: Calculation type297079 +Ref: #calculation-type297234 +Node: Accumulation type297783 +Ref: #accumulation-type297963 +Node: Valuation type298884 +Ref: #valuation-type299072 +Node: Combining balance report types300073 +Ref: #combining-balance-report-types300267 +Node: Budget report302105 +Ref: #budget-report302267 +Node: Using the budget report304410 +Ref: #using-the-budget-report304583 +Node: Budget date surprises306686 +Ref: #budget-date-surprises306886 +Node: Selecting budget goals308050 +Ref: #selecting-budget-goals308253 +Node: Budgeting vs forecasting308998 +Ref: #budgeting-vs-forecasting309175 +Node: Balance report layout310675 +Ref: #balance-report-layout310860 +Node: Wide layout311813 +Ref: #wide-layout311948 +Node: Tall layout314218 +Ref: #tall-layout314373 +Node: Bare layout315524 +Ref: #bare-layout315679 +Node: Tidy layout317583 +Ref: #tidy-layout317718 +Node: Some useful balance reports319127 +Ref: #some-useful-balance-reports319302 +Node: balancesheet320387 +Ref: #balancesheet320532 +Node: balancesheetequity321862 +Ref: #balancesheetequity322020 +Node: cashflow323401 +Ref: #cashflow323532 +Node: check324970 +Ref: #check325084 +Node: Default checks325888 +Ref: #default-checks326014 +Node: Strict checks326511 +Ref: #strict-checks326656 +Node: Other checks327136 +Ref: #other-checks327278 +Node: Custom checks327811 +Ref: #custom-checks327968 +Node: More about specific checks328385 +Ref: #more-about-specific-checks328547 +Node: close329253 +Ref: #close329364 +Node: close --migrate330017 +Ref: #close---migrate330144 +Node: close --close331783 +Ref: #close---close331927 +Node: close --open332163 +Ref: #close---open332304 +Node: close --assert332414 +Ref: #close---assert332560 +Node: close --assign332781 +Ref: #close---assign332929 +Node: close --retain333455 +Ref: #close---retain333608 +Node: close customisation334353 +Ref: #close-customisation334532 +Node: close and balance assertions335999 +Ref: #close-and-balance-assertions336196 +Node: close examples337523 +Ref: #close-examples337664 +Node: Retain earnings337762 +Ref: #retain-earnings337921 +Node: Migrate balances to a new file338267 +Ref: #migrate-balances-to-a-new-file338493 +Node: More detailed close examples339621 +Ref: #more-detailed-close-examples339819 +Node: codes339845 +Ref: #codes339962 +Node: commodities340826 +Ref: #commodities340954 +Node: demo341024 +Ref: #demo341145 +Node: descriptions342061 +Ref: #descriptions342191 +Node: diff342482 +Ref: #diff342597 +Node: files343639 +Ref: #files343748 +Node: help343889 +Ref: #help-1343998 +Node: import345371 +Ref: #import345494 +Node: "Deduplication"346604 +Ref: #deduplication346735 +Node: Import testing348911 +Ref: #import-testing349078 +Node: Importing balance assignments349921 +Ref: #importing-balance-assignments350127 +Node: Commodity display styles350776 +Ref: #commodity-display-styles350949 +Node: incomestatement351078 +Ref: #incomestatement351220 +Node: notes352551 +Ref: #notes352673 +Node: payees353035 +Ref: #payees353150 +Node: prices353669 +Ref: #prices353784 +Node: print354437 +Ref: #print354552 +Node: print explicitness355528 +Ref: #print-explicitness355671 +Node: print amount style356450 +Ref: #print-amount-style356620 +Node: print parseability357690 +Ref: #print-parseability357862 +Node: print other features358611 +Ref: #print-other-features358790 +Node: print output format359311 +Ref: #print-output-format359459 +Node: register362598 +Ref: #register362720 +Node: Custom register output367751 +Ref: #custom-register-output367882 +Node: rewrite369229 +Ref: #rewrite369347 +Node: Re-write rules in a file371245 +Ref: #re-write-rules-in-a-file371408 +Node: Diff output format372557 +Ref: #diff-output-format372740 +Node: rewrite vs print --auto373832 +Ref: #rewrite-vs.-print---auto373992 +Node: roi374548 +Ref: #roi374655 +Node: Spaces and special characters in --inv and --pnl376467 +Ref: #spaces-and-special-characters-in---inv-and---pnl376707 +Node: Semantics of --inv and --pnl377195 +Ref: #semantics-of---inv-and---pnl377434 +Node: IRR and TWR explained379284 +Ref: #irr-and-twr-explained379444 +Node: stats382697 +Ref: #stats382805 +Node: tags384319 +Ref: #tags-1384426 +Node: test385435 +Ref: #test385528 +Node: PART 5 COMMON TASKS386270 +Ref: #part-5-common-tasks386416 +Node: Getting help386714 +Ref: #getting-help386855 +Node: Constructing command lines387615 +Ref: #constructing-command-lines387816 +Node: Starting a journal file388473 +Ref: #starting-a-journal-file388675 +Node: Setting LEDGER_FILE389877 +Ref: #setting-ledger_file390069 +Node: Setting opening balances391026 +Ref: #setting-opening-balances391227 +Node: Recording transactions394368 +Ref: #recording-transactions394557 +Node: Reconciling395113 +Ref: #reconciling395265 +Node: Reporting397522 +Ref: #reporting397671 +Node: Migrating to a new file401656 +Ref: #migrating-to-a-new-file401813 +Node: BUGS402112 +Ref: #bugs402202 +Node: Troubleshooting403081 +Ref: #troubleshooting403181  End Tag Table diff --git a/hledger/hledger.txt b/hledger/hledger.txt index 36d44c88ef5..0a4cdcf3e16 100644 --- a/hledger/hledger.txt +++ b/hledger/hledger.txt @@ -63,11 +63,13 @@ DESCRIPTION To get started, run hledger add and follow the prompts, or save some entries like the above in $HOME/.hledger.journal, then try commands like: - hledger print -x - hledger aregister assets - hledger balance - hledger balancesheet - hledger incomestatement. + + $ hledger print -x + $ hledger aregister assets + $ hledger balance + $ hledger balancesheet + $ hledger incomestatement + Run hledger to list the commands. See also the "Starting a journal file" and "Setting opening balances" sections in PART 5: COMMON TASKS. @@ -93,6 +95,17 @@ Input nance/2023.journal. For more about how to do that on your system, see Common tasks > Setting LEDGER_FILE. + Text encoding + Data files containing non-ascii characters must use UTF-8 encoding. + Also, your system should be configured with a locale that can decode + UTF-8 text. On some unix systems, you may need set the LANG environ- + ment variable, eg. You can read more about this in Unicode characters, + below. + + On unix systems you can check a file's encoding with the file command. + If you need to import from a UTF-16-encoded CSV file, say, you can con- + vert it to UTF-8 with the iconv command. + Data formats Usually the data file is in hledger's journal format, but it can be in any of the supported file formats, which currently are: @@ -716,10 +729,8 @@ Output ties/currencies. Its argument is as described in the commodity direc- tive. - hledger will occasionally make some additional adjustments to number - formatting, eg adding a trailing decimal mark to disambiguate numbers - with digit group marks; for details, see Amount formatting, parseabil- - ity. + In some cases hledger will adjust number formatting to improve their + parseability (such as adding trailing decimal marks when needed). Colour In terminal output, some commands can produce colour when the terminal @@ -793,135 +804,173 @@ Environment PART 2: DATA FORMATS Journal - hledger's default file format, representing a General Journal. Here's - a cheatsheet/mini-tutorial, or you can skip ahead to About journal for- - mat. + hledger's usual data source is a plain text file containing journal en- + tries in hledger journal format. If you're looking for a quick refer- + ence, jump ahead to the journal cheatsheet (or use the table of con- + tents at https://hledger.org/hledger.html). + + This file represents an accounting General Journal. The .journal file + extension is most often used, though not strictly required. The jour- + nal file contains a number of transaction entries, each describing a + transfer of money (or any commodity) between two or more named ac- + counts, in a simple format readable by both hledger and humans. + + hledger's journal format is compatible with most of Ledger's journal + format, but not all of it. The differences and interoperation tips are + described at hledger and Ledger. With some care, and by avoiding in- + compatible features, you can keep your hledger journal readable by + Ledger and vice versa. This can useful eg for comparing the behaviour + of one app against the other. + + You can use hledger without learning any more about this file; just use + the add or web or import commands to create and update it. + + Many users, though, edit the journal file with a text editor, and track + changes with a version control system such as git. Editor addons such + as ledger-mode or hledger-mode for Emacs, vim-ledger for Vim, and + hledger-vscode for Visual Studio Code, make this easier, adding colour, + formatting, tab completion, and useful commands. See Editor configura- + tion at hledger.org for the full list. + + A hledger journal file can contain three kinds of thing: comment lines, + transactions, and/or directives (including periodic transaction rules + and auto posting rules). Understanding the journal file format will + also give you a good understanding of hledger's data model. Here's a + quick cheatsheet/overview, followed by detailed descriptions of each + part. Journal cheatsheet # Here is the main syntax of hledger's journal format # (omitting extra Ledger compatibility syntax). - # hledger journals contain comments, directives, and transactions, in any order: ############################################################################### - # 1. Comment lines are for notes or temporarily disabling things. - # They begin with #, ;, or a line containing the word "comment". - # hash comment line - ; semicolon comment line + # 1. These are comment lines, for notes or temporarily disabling things. + ; They begin with # or ; + comment - These lines - are commented. + Or, lines can be enclosed within "comment" / "end comment". + This is a block of + commented lines. end comment - # Some but not all hledger entries can have same-line comments attached to them, - # from ; (semicolon) to end of line. + # Some journal entries can have semicolon comments at end of line ; like this + # Some of them require 2 or more spaces before the semicolon. ############################################################################### - # 2. Directives modify parsing or reports in some way. - # They begin with a word or letter (or symbol). - account actifs ; type:A, declare an account that is an Asset. 2+ spaces before ;. - account passifs ; type:L, declare an account that is a Liability, and so on.. (ALERX) - alias chkg = assets:checking - commodity $0.00 - decimal-mark . - include /dev/null - payee Whole Foods - P 2022-01-01 AAAA $1.40 - ~ monthly budget goals ; <- 2+ spaces between period expression and description - expenses:food $400 - expenses:home $1000 - budgeted + # 2. Directives customise processing or output in some way. + # You don't need any directives to get started. + # But they can add more error checking, or change how things are displayed. + # They begin with a word, letter, or symbol. + # They are most often placed at the top, before transactions. + + account assets ; Declare valid account names and display order. + account assets:savings ; A subaccount. This one represents a bank account. + account assets:checking ; Another. Note, 2+ spaces after the account name. + account assets:receivable ; Accounting type is inferred from english names, + account passifs ; or declared with a "type" tag, type:L + account expenses ; type:X + ; A follow-on comment line, indented. + account expenses:rent ; Expense and revenue categories are also accounts. + ; Subaccounts inherit their parent's type. + + commodity $0.00 ; Declare valid commodities and their display styles. + commodity 1.000,00 EUR - ############################################################################### - # 3. Transactions are what it's all about; they are dated events, - # usually describing movements of money. - # They begin with a date. - - # DATE DESCRIPTION ; This is a transaction comment. - # ACCOUNT NAME 1 AMOUNT1 ; <- posting 1. This is a posting comment. - # ACCOUNT NAME 2 AMOUNT2 ; <- posting 2. Postings must be indented. - # ; ^^ At least 2 spaces between account and amount. - # ... ; Any number of postings is allowed. The amounts must balance (sum to 0). - - 2022-01-01 opening balances are declared this way - assets:checking $1000 ; Account names can be anything. lower case is easy to type. - assets:savings $1000 ; assets, liabilities, equity, revenues, expenses are common. - assets:cash:wallet $100 ; : indicates subaccounts. - liabilities:credit card $-200 ; liabilities, equity, revenues balances are usually negative. - equity ; One amount can be left blank; $-1900 is inferred here. - - 2022-04-15 * (#12345) pay taxes - ; There can be a ! or * after the date meaning "pending" or "cleared". - ; There can be a transaction code (text in parentheses) after the date/status. - ; Amounts' sign represents direction of flow, or credit/debit: - assets:checking $-500 ; minus means removed from this account (credit) - expenses:tax:us:2021 $500 ; plus means added to this account (debit) - ; revenue/expense categories are also "accounts" - - 2022-01-01 ; The description is optional. - ; Any currency/commodity symbols are allowed, on either side. - assets:cash:wallet GBP -10 - expenses:clothing GBP 10 - assets:gringotts -10 gold - assets:pouch 10 gold - revenues:gifts -2 "Liquorice Wands" ; Complex symbols - assets:bag 2 "Liquorice Wands" ; must be double-quoted. - - 2022-01-01 Cost in another commodity can be noted with @ or @@ - assets:investments 2.0 AAAA @ $1.50 ; @ means per-unit cost - assets:investments 3.0 AAAA @@ $4 ; @@ means total cost - assets:checking $-7.00 - - 2022-01-02 assert balances - ; Balances can be asserted for extra error checking, in any transaction. - assets:investments 0 AAAA = 5.0 AAAA - assets:pouch 0 gold = 10 gold - assets:savings $0 = $1000 - - 1999-12-31 Ordering transactions by date is recommended but not required. - ; Postings are not required. + decimal-mark . ; The decimal mark used in this file (if ambiguous). - 2022.01.01 These date - 2022/1/1 formats are - 12/31 also allowed (but consistent YYYY-MM-DD is recommended). + payee Whole Foods ; Declare a valid payee name. - About journal format - 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 compatible with most of Ledger's journal - format, but not all of it. The differences and interoperation tips are - described at hledger and Ledger. With some care, and by avoiding in- - compatible features, you can keep your hledger journal readable by - Ledger and vice versa. This can useful eg for comparing the behaviour - of one app against the other. + tag trip ; Declare a valid tag name. - You can use hledger without learning any more about this file; just use - the add or web or import commands to create and update it. + P 2024-03-01 AAPL $179 ; Declare a market price for AAPL in $ on this date. - Many users, though, edit the journal file with a text editor, and track - changes with a version control system such as git. Editor addons such - as ledger-mode or hledger-mode for Emacs, vim-ledger for Vim, and - hledger-vscode for Visual Studio Code, make this easier, adding colour, - formatting, tab completion, and useful commands. See Editor configura- - tion at hledger.org for the full list. + include other.journal ; Include another journal file here. + + # Declare a recurring "periodic transaction", for budget/forecast reports + ~ monthly set budget goals ; <- Note, 2+ spaces before the description. + (expenses:rent) $1000 + (expenses:food) $500 + + # Declare an auto posting rule, to modify existing transactions in reports + = revenues:consulting + liabilities:tax:2024:us *0.25 ; Add a tax liability & expense + expenses:tax:2024:us *-0.25 ; for 25% of the revenue. - Here's a description of each part of the file format (and hledger's - data model). + ############################################################################### + + # 3. Transactions are what it's all about. + # They are dated events, usually movements of money between 2 or more accounts. + # They begin with a numeric date. + # Here is their basic shape: + # + # DATE DESCRIPTION ; The transaction's date and optional description. + # ACCOUNT1 AMOUNT ; A posting of an amount to/from this account, indented. + # ACCOUNT2 AMOUNT ; A second posting, balancing the first. + # ... ; More if needed. Amounts must sum to zero. + # ; Note, 2+ spaces between account names and amounts. + + 2024-01-01 opening balances ; At the start, declare pre-existing balances this way. + assets:savings $10000 ; Account names can be anything. lower case is easy to type. + assets:checking $1000 ; assets, liabilities, equity, revenues, expenses are common. + liabilities:credit card $-500 ; liabilities, equity, revenues balances are usually negative. + equity:start ; One amount can be left blank. $-10500 is inferred here. + ; Some of these accounts we didn't declare above, + ; so -s/--strict would complain. + + 2024-01-03 ! (12345) pay rent + ; Additional transaction comment lines, indented. + ; There can be a ! or * after the date meaning "pending" or "cleared". + ; There can be a parenthesised (code) after the date/status. + ; Amounts' sign shows direction of flow. + assets:checking $-500 ; Minus means removed from this account (credit). + expenses:rent $500 ; Plus means added to this account (debit). + + ; Keeping transactions in date order is optional (but helps error checking). + + 2024-01-02 Gringott's Bank | withdrawal ; Description can be PAYEE | NOTE + assets:bank:gold -10 gold + assets:pouch 10 gold + + 2024-01-02 shopping + expenses:clothing 1 gold + expenses:wands 5 gold + assets:pouch -6 gold + + 2024-01-02 receive gift + revenues:gifts -3 "Chocolate Frogs" ; Complex commodity symbols + assets:pouch 3 "Chocolate Frogs" ; must be in double quotes. + + 2024-01-15 buy some shares, in two lots ; Cost can be noted. + assets:investments:2024-01-15 2.0 AAAA @ $1.50 ; @ means per-unit cost + assets:investments:2024-01-15-02 3.0 AAAA @@ $4 ; @@ means total cost + ; ^ Per-lot subaccounts are sometimes useful. + assets:checking $-7 + + 2024-01-15 assert some account balances on this date + ; Balances can be asserted in any transaction, with =, for extra error checking. + ; Assertion txns like this one can be made with hledger close --assert --show-costs + ; + assets:savings $0 = $10000 + assets:checking $0 = $493 + assets:bank:gold 0 gold = -10 gold + assets:pouch 0 gold = 4 gold + assets:pouch 0 "Chocolate Frogs" = 3 "Chocolate Frogs" + assets:investments:2024-01-15 0.0 AAAA = 2.0 AAAA @ $1.50 + assets:investments:2024-01-15-02 0.0 AAAA = 3.0 AAAA @@ $4 + liabilities:credit card $0 = $-500 + + 2024-02-01 note some event, or a transaction not yet fully entered, on this date + ; Postings are not required. - A hledger journal file can contain three kinds of thing: file comments, - transactions, and/or directives (counting periodic transaction rules - and auto posting rules as directives). + ; Some other date formats are allowed (but, consistent YYYY-MM-DD is useful). + 2024.01.01 + 2024/1/1 Comments Lines in the journal will be ignored if they begin with a hash (#) or a - semicolon (;). (See also Other syntax.) hledger will also ignore re- + semicolon (;). (See also Other syntax.) hledger will also ignore re- gions beginning with a comment line and ending with an end comment line (or file end). Here's a suggestion for choosing between them: @@ -943,15 +992,15 @@ Journal end comment Some hledger entries can have same-line comments attached to them, from - ; (semicolon) to end of line. See Transaction comments, Posting com- + ; (semicolon) to end of line. See Transaction comments, Posting com- ments, and Account comments below. Transactions - Transactions are the main unit of information in a journal file. They - represent events, typically a movement of some quantity of commodities + Transactions are the main unit of information in a journal file. They + represent events, typically a movement of some quantity of commodities between two or more named accounts. - Each transaction is recorded as a journal entry, beginning with a sim- + Each transaction is recorded as a journal entry, beginning with a sim- ple date in column 0. This can be followed by any of the following op- tional fields, separated by spaces: @@ -961,11 +1010,11 @@ Journal o a description (any remaining text until end of line or a semicolon) - o a comment (any remaining text following a semicolon until end of + o a comment (any remaining text following a semicolon until end of line, and any following indented lines beginning with a semicolon) o 0 or more indented posting lines, describing what was transferred and - the accounts involved (indented comment lines are also allowed, but + the accounts involved (indented comment lines are also allowed, but not blank lines or non-indented lines). Here's a simple journal file containing one transaction: @@ -976,22 +1025,22 @@ Journal Dates Simple dates - Dates in the journal file use simple dates format: YYYY-MM-DD or + Dates in the journal file use simple dates format: YYYY-MM-DD or YYYY/MM/DD or YYYY.MM.DD, with leading zeros optional. The year may be - omitted, in which case it will be inferred from the context: the cur- - rent transaction, the default year set with a Y directive, or the cur- + omitted, in which case it will be inferred from the context: the cur- + rent transaction, the default year set with a Y directive, or the cur- rent date when the command is run. Some examples: 2010-01-31, 2010/01/31, 2010.1.31, 1/31. - (The UI also accepts simple dates, as well as the more flexible smart + (The UI also accepts simple dates, as well as the more flexible smart dates documented in the hledger manual.) Posting dates - You can give individual postings a different date from their parent - transaction, by adding a posting comment containing a tag (see below) + You can give individual postings a different date from their parent + transaction, by adding a posting comment containing a tag (see below) like date:DATE. This is probably the best way to control posting dates - precisely. Eg in this example the expense should appear in May re- - ports, and the deduction from checking should be reported on 6/1 for + precisely. Eg in this example the expense should appear in May re- + ports, and the deduction from checking should be reported on 6/1 for easy bank reconciliation: 2015/5/30 @@ -1004,16 +1053,16 @@ Journal $ hledger -f t.j register checking 2015-06-01 assets:checking $-10 $-10 - DATE should be a simple date; if the year is not specified it will use + DATE should be a simple date; if the year is not specified it will use the year of the transaction's date. - The date: tag must have a valid simple date value if it is present, eg + The date: tag must have a valid simple date value if it is present, eg a date: tag with no value is not allowed. Status - Transactions, or individual postings within a transaction, can have a - status mark, which is a single character before the transaction de- - scription or posting account name, separated from it by a space, indi- - cating 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, in- + dicating one of three statuses: mark status ------------------ @@ -1021,16 +1070,13 @@ Journal ! pending * cleared - 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. + When reporting, you can filter by status with the -U/--unmarked, + -P/--pending, and -C/--cleared flags (and you can combine these, eg -UP + to match all except cleared things). Or you can use the status:, sta- + tus:!, 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 un- - marked for clarity. - - To replicate Ledger and old hledger's behaviour of also matching pend- - ing, combine -U and -P. + (Note: in Ledger the "unmarked" state is called "uncleared"; in hledger + we renamed it to "unmarked" for semantic clarity.) Status marks are optional, but can be helpful eg for reconciling with real-world accounts. Some editor modes provide highlighting and short- @@ -1089,9 +1135,9 @@ Journal If you want more strict error checking, you can declare the valid payee names with payee directives, and then enforce these with hledger check - payees. Note: because of the above, for this you'll need to ensure + payees. (Note: because of the above, for this you'll need to ensure every transaction description contains a | and therefore a checkable - payee name (even if it's empty). + payee name, even if it's empty.) Transaction comments Text following ;, after a transaction description, and/or on indented @@ -1114,34 +1160,54 @@ Journal 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. + o (optional) two or more spaces (or tabs) followed by an amount. + + If the amount is positive, it is being added to the account; if nega- + tive, it is being removed from the account. + + The posting amounts in a transaction must sum up to zero, indicating + that the inflows and outflows are equal. We call this a balanced + transaction. (You can read more about the nitty-gritty details of "sum + up to zero" in Transaction balancing below.) + + As a convenience, you can optionally leave one amount blank; hledger + will infer what it should be so as to balance the transaction. + + Debits and credits + The traditional accounting concepts of debit and credit of course exist + in hledger, but we represent them with numeric sign, as described + above. Positive and negative posting amounts represent debits and + credits respectively. - Positive amounts are being added to the account, negative amounts are - being removed. + You don't need to remember that, but if you would like to - eg for + helping newcomers or for talking with your accountant - here's a handy + mnemonic: - 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 - balance the transaction. + debit / plus / left / short words + credit / minus / right / longer words - Be sure to note the unusual two-space delimiter between account name - and amount. This makes it easy to write account names containing - spaces. But if you accidentally leave only one space (or tab) before - the amount, the amount will be considered part of the account name. + The two space delimiter + Be sure to notice the unusual separator between the account name and + the following amount. Because hledger allows account names with spaces + in them, you must separate the account name and amount (if any) by two + or more spaces (or tabs). It's easy to forget at first. If you ever + see the amount being treated as part of the account name, you'll know + you probably need to add another space between them. Account names - Accounts are the main way of categorising things in hledger. As in - Double Entry Bookkeeping, they can represent real world accounts (such + Accounts are the main way of categorising things in hledger. As in + Double Entry Bookkeeping, they can represent real world accounts (such as a bank account), or more abstract categories such as "money borrowed from Frank" or "money spent on electricity". - You can use any account names you like, but we usually start with the + You can use any account names you like, but we usually start with the traditional accounting categories, which in english are assets, liabil- ities, equity, revenues, expenses. (You might see these referred to as A, L, E, R, X for short.) - For more precise reporting, we usually divide the top level accounts + For more precise reporting, we usually divide the top level accounts into more detailed subaccounts, by writing a full colon between account - name parts. For example, from the account names assets:bank:checking + name parts. For example, from the account names assets:bank:checking and expenses:food, hledger will infer this hierarchy of five accounts: assets @@ -1159,24 +1225,24 @@ Journal food hledger reports can summarise the account tree to any depth, so you can - go as deep as you like with subcategories, but keeping your account + go as deep as you like with subcategories, but keeping your account names relatively simple may be best when starting out. Account names may be capitalised or not; they may contain letters, num- - bers, symbols, or single spaces. Note, when an account name and an - amount are written on the same line, they must be separated by two or + bers, symbols, or single spaces. Note, when an account name and an + amount are written on the same line, they must be separated by two or more spaces (or tabs). - Parentheses or brackets enclosing the full account name indicate vir- - tual postings, described below. Parentheses or brackets internal to + Parentheses or brackets enclosing the full account name indicate vir- + tual postings, described below. Parentheses or brackets internal to the account name have no special meaning. - Account names can be altered temporarily or permanently by account + Account names can be altered temporarily or permanently by account aliases. Amounts - After the account name, there is usually an amount. (Important: be- - tween account name and amount, there must be two or more spaces.) + After the account name, there is usually an amount. (Remember: between + account name and amount, there must be two or more spaces.) hledger's amount format is flexible, supporting several international formats. Here are some examples. Amounts have a number (the "quan- @@ -1210,133 +1276,87 @@ Journal 1E-6 EUR 1E3 - Decimal marks, digit group marks + Decimal marks A decimal mark can be written as a period or a comma: 1.23 1,23 - In the integer part of the quantity (left of the decimal mark), groups - of digits can optionally be separated by a digit group mark - a space, - comma, or period (different from the decimal mark): + Both of these are common in international number formats, so hledger is + not biased towards one or the other. Because hledger also supports + digit group marks (eg thousands separators), this means that a number + like 1,000 or 1.000 containing just one period or comma is ambiguous. + In such cases, hledger by default assumes it is a decimal mark, and + will parse both of those as 1. + + To help hledger parse such ambiguous numbers more accurately, if you + use digit group marks, we recommend declaring the decimal mark explic- + itly. The best way is to add a decimal-mark directive at the top of + each data file, like this: + + decimal-mark . + + Or you can declare it per commodity with commodity directives, de- + scribed below. + + hledger also accepts numbers like 10. with no digits after the decimal + mark (and will sometimes display numbers that way to disambiguate them + - see Trailing decimal marks). + + Digit group marks + In the integer part of the amount quantity (left of the decimal mark), + groups of digits can optionally be separated by a digit group mark - a + comma or period (whichever is not used as decimal mark), or a space + (several Unicode space variants, like no-break space, are also ac- + cepted). So these are all valid amounts in a journal file: $1,000,000.00 EUR 2.000.000,00 INR 9,99,99,999.00 - 1 000 000.9455 - - hledger is not biased towards period or comma decimal marks, so a num- - ber containing just one period or comma, like 1,000 or 1.000, is am- - biguous. In such cases hledger assumes it is a decimal mark, parsing - both of these as 1. - - To disambiguate these and ensure accurate number parsing, especially if - you use digit group marks, we recommend declaring the decimal mark. - You can declare it for each file with decimal-mark directives, or for - each commodity with commodity directives (described below). + 1 000 000.00 ; <- ordinary space + 1 000 000.00 ; <- no-break space Commodity - Amounts in hledger have both a "quantity", which is a signed decimal + Amounts in hledger have both a "quantity", which is a signed decimal number, and a "commodity", which is a currency symbol, stock ticker, or any word or phrase describing something you are tracking. If the commodity name contains non-letters (spaces, numbers, or punctu- - ation), you must always write it inside double quotes ("green apples", + ation), you must always write it inside double quotes ("green apples", "ABC123"). - If you write just a bare number, that too will have a commodity, with + If you write just a bare number, that too will have a commodity, with name ""; we call that the "no-symbol commodity". - Actually, hledger combines these single-commodity amounts into more - powerful multi-commodity amounts, which are what it works with most of - the time. A multi-commodity amount could be, eg: 1 USD, 2 EUR, 3.456 - TSLA. In practice, you will only see multi-commodity amounts in + Actually, hledger combines these single-commodity amounts into more + powerful multi-commodity amounts, which are what it works with most of + the time. A multi-commodity amount could be, eg: 1 USD, 2 EUR, 3.456 + TSLA. In practice, you will only see multi-commodity amounts in hledger's output; you can't write them directly in the journal file. - (If you are writing scripts or working with hledger's internals, these - are the Amount and MixedAmount types.) - - Directives influencing number parsing and display - You can add decimal-mark and commodity directives to the journal, to - declare and control these things more explicitly and precisely. These - are described below, but here's a quick example: - - # the decimal mark character used by all amounts in this file (all commodities) - decimal-mark . - - # display styles for the $, EUR, INR and no-symbol commodities: - commodity $1,000.00 - commodity EUR 1.000,00 - commodity INR 9,99,99,999.00 - commodity 1 000 000.9455 - - Commodity display style - For the amounts in each commodity, hledger chooses a consistent display - style (symbol placement, decimal mark and digit group marks, number of - decimal digits) to use in most reports. This is inferred as follows: - - First, if there's a D directive declaring a default commodity, that - commodity symbol and amount format is applied to all no-symbol amounts - in the journal. - - Then each commodity's display style is determined from its commodity - directive. We recommend always declaring commodities with commodity - directives, since they help ensure consistent display styles and preci- - sions, and bring other benefits such as error checking for commodity - symbols. - - But if a commodity directive is not present, hledger infers a commod- - ity's display styles from its amounts as they are written in the jour- - nal (excluding cost amounts and amounts in periodic transaction rules - or auto posting rules). It uses - - o the symbol placement and decimal mark of the first amount seen - - o the digit group marks of the first amount with digit group marks - - o and the maximum number of decimal digits seen across all amounts. - - And as fallback if no applicable amounts are found, it would use a de- - fault style, like $1000.00 (symbol on the left with no space, period as - decimal mark, and two decimal digits). - - Finally, commodity styles can be overridden by the -c/--commodity-style - command line option. - - Rounding - Amounts are stored internally as decimal numbers with up to 255 decimal - places. They are displayed with their original journal precisions by - print and print-like reports, and rounded to their display precision - (the number of decimal digits specified by the commodity display style) - by other reports. When rounding, hledger uses banker's rounding (it - rounds to the nearest even digit). So eg 0.5 displayed with zero deci- - mal digits appears as "0". - - Number format - hledger will occasionally make some additional adjustments to number - formatting, eg adding a trailing decimal mark to disambiguate numbers - with digit group marks; for details, see Amount formatting, parseabil- - ity. + By default, the format of amounts in the journal influences how hledger + displays them in output. This is explained in Commodity display style + below. Costs - After a posting amount, you can note its cost (when buying) or selling - price (when selling) in another commodity, by writing either @ UNIT- - PRICE or @@ TOTALPRICE after it. This indicates a conversion transac- + After a posting amount, you can note its cost (when buying) or selling + price (when selling) in another commodity, by writing either @ UNIT- + PRICE or @@ TOTALPRICE after it. This indicates a conversion transac- tion, where one commodity is exchanged for another. - (You might also see this called "transaction price" in hledger docs, - discussions, or code; that term was directionally neutral and reminded - that it is a price specific to a transaction, but we now just call it + (You might also see this called "transaction price" in hledger docs, + discussions, or code; that term was directionally neutral and reminded + that it is a price specific to a transaction, but we now just call it "cost", with the understanding that the transaction could be a purchase or a sale.) - Costs are usually written explicitly with @ or @@, but can also be in- + Costs are usually written explicitly with @ or @@, but can also be in- ferred automatically for simple multi-commodity transactions. Note, if - costs are inferred, the order of postings is significant; the first + costs are inferred, the order of postings is significant; the first posting will have a cost attached, in the commodity of the second. - As an example, here are several ways to record purchases of a foreign - currency in hledger, using the cost notation either explicitly or im- + As an example, here are several ways to record purchases of a foreign + currency in hledger, using the cost notation either explicitly or im- plicitly: 1. Write the price per unit, as @ UNITPRICE after the amount: @@ -1360,93 +1380,13 @@ Journal assets:euros 100 ; one hundred euros purchased assets:dollars $-135 ; for $135 - Amounts can be converted to cost at report time using the -B/--cost + Amounts can be converted to cost at report time using the -B/--cost flag; this is discussed more in the Cost reporting section. - Note that the cost normally should be a positive amount, though it's - not required to be. This can be a little confusing, see discussion at + Note that the cost normally should be a positive amount, though it's + not required to be. This can be a little confusing, see discussion at --infer-market-prices: market prices from transactions. - Other cost/lot notations - A slight digression for Ledger and Beancount users. Ledger has a num- - ber of cost/lot-related notations: - - o @ UNITCOST and @@ TOTALCOST - - o expresses a conversion rate, as in hledger - - o when buying, also creates a lot than can be selected at selling - time - - o (@) UNITCOST and (@@) TOTALCOST (virtual cost) - - o like the above, but also means "this cost was exceptional, don't - use it when inferring market prices". - - Currently, hledger treats the above like @ and @@; the parentheses are - ignored. - - o {=FIXEDUNITCOST} and {{=FIXEDTOTALCOST}} (fixed price) - - o when buying, means "this cost is also the fixed price, don't let it - fluctuate in value reports" - - o {UNITCOST} and {{TOTALCOST}} (lot price) - - o can be used identically to @ UNITCOST and @@ TOTALCOST, also cre- - ates a lot - - o when selling, combined with @ ..., specifies an investment lot by - its cost basis; does not check if that lot is present - - o and related: [YYYY/MM/DD] (lot date) - - o when buying, attaches this acquisition date to the lot - - o when selling, selects a lot by its acquisition date - - o (SOME TEXT) (lot note) - - o when buying, attaches this note to the lot - - o when selling, selects a lot by its note - - Currently, hledger accepts any or all of the above in any order after - the posting amount, but ignores them. (This can break transaction bal- - ancing.) - - For Beancount users, the notation and behaviour is different: - - o @ UNITCOST and @@ TOTALCOST - - o expresses a cost without creating a lot, as in hledger - - o when buying (augmenting) or selling (reducing) a lot, combined with - {...}: documents the cost/selling price (not used for transaction - balancing) - - o {UNITCOST} and {{TOTALCOST}} - - o when buying (augmenting), expresses the cost for transaction bal- - ancing, and also creates a lot with this cost basis attached - - o when selling (reducing), - - o selects a lot by its cost basis - - o raises an error if that lot is not present or can not be selected - unambiguously (depending on booking method configured) - - o expresses the selling price for transaction balancing - - Currently, hledger accepts the {UNITCOST}/{{TOTALCOST}} notation but - ignores it. - - o variations: {}, {YYYY-MM-DD}, {"LABEL"}, {UNITCOST, "LABEL"}, {UNIT- - COST, YYYY-MM-DD, "LABEL"} etc. - - Currently, hledger rejects these. - Balance assertions hledger supports Ledger-style balance assertions in journal files. These look like, for example, = EXPECTEDBALANCE following a posting's @@ -1608,20 +1548,56 @@ Journal ; a comment for posting 2 ; a second comment line for posting 2 + Transaction balancing + How exactly does hledger decide when a transaction is balanced ? The + general goal is that if you look at the journal entry and calculate the + amounts' sum perfectly with pencil and paper, hledger should agree with + you. + + Real world transactions, especially for investments or cryptocurren- + cies, often involve imprecise costs, complex decimals, and/or infi- + nitely-recurring decimals, which are difficult or inconvenient to han- + dle on a computer. So to be a practical accounting system, hledger al- + lows some imprecision when checking transaction balancedness. The + question is, how much imprecision should be allowed ? + + hledger currently decides it based on the commodity display styles: if + the postings' sum would appear to be zero when displayed with the stan- + dard display precisions, the transaction is considered balanced. + + Or equivalently: if the journal entry is displayed with amounts rounded + to the standard display precisions (with hledger print --round=hard), + and a human with pencil and paper would agree that those displayed + amounts add up to zero, the transaction is considered balanced. + + This has some advantages: it is fairly intuitive, general not + hard-coded, yet configurable when needed. On the downside it means + that transaction balancedness is related to commodity display preci- + sions, so eg when using -c/--commodity-style to display things with + more than usual precision, you might need to fix some of your journal + entries (ie, add decimal digits to make them balance more precisely). + + Other PTA tools (Ledger, Beancount..) have their own ways of doing it. + Possible improvements are discussed at #1964. + + Note: if you have multiple journal files, and are relying on commodity + directives to make imprecise journal entries balance, the directives' + placement might be important - see commodity directive. + Tags - Tags are a way to add extra labels or data fields to transactions, + Tags are a way to add extra labels or data fields to transactions, postings, or accounts, which you can then search or pivot on. - A tag is a word, optionally hyphenated, immediately followed by a full + A tag is a word, optionally hyphenated, immediately followed by a full colon, in the comment of a transaction, a posting, or an account direc- - tive. Eg: 2024-01-01 a transaction ; foo: Note this is an exception + tive. Eg: 2024-01-01 a transaction ; foo: Note this is an exception to the usual rule that things in comments are ignored. - You can write multiple tags on one line, separated by comma. Or you - can write each tag on its own comment line (no comma needed in this + You can write multiple tags on one line, separated by comma. Or you + can write each tag on its own comment line (no comma needed in this case). - For example, here are five different tags: one on the assets:checking + For example, here are five different tags: one on the assets:checking account, two on the transaction, and two on the expenses:food posting: account assets:checking ; accounttag: @@ -1631,15 +1607,15 @@ Journal assets:checking $-1 expenses:food $1 ; postingtag:, another-posting-tag: - Postings also inherit tags from their transaction and their account. - And transactions also acquire tags from their postings (and postings' - accounts). So in the example above, the expenses posting effectively + Postings also inherit tags from their transaction and their account. + And transactions also acquire tags from their postings (and postings' + accounts). So in the example above, the expenses posting effectively has all five tags (by inheriting from the account and transaction), and - the transaction also has all five tags (by acquiring from the expenses + the transaction also has all five tags (by acquiring from the expenses posting). Tag names - Most non-whitespace characters are allowed in tag names. Eg : is a + Most non-whitespace characters are allowed in tag names. Eg : is a valid tag. You can list the tag names used in your journal with the tags command: @@ -1648,14 +1624,14 @@ Journal In commands which use a query, you can match by tag name. Eg: hledger print tag:NAMEREGEX - You can declare valid tag names with the tag directive and then check + You can declare valid tag names with the tag directive and then check them with the check command. Special tags - Some tag names have special significance to hledger. There's not much - harm in using them yourself, but some could produce an error message, - particularly the date: tag. They are explained elsewhere, but here is - a quick list for reference: + Some tag names have special significance to hledger. There's not much + harm in using them yourself, but some could produce an error message, + particularly the date: and type: tags. They are explained elsewhere, + but here is a quick list for reference: Tags you can set to influence hledger's behaviour: @@ -1682,34 +1658,34 @@ Journal _conversion-matched -- exists on postings which have been matched with a nearby @/@@ cost annotation Tag values - Tags can have a value, which is any text after the colon up until a - comma or end of line, with surrounding whitespace removed. Ending at + Tags can have a value, which is any text after the colon up until a + comma or end of line, with surrounding whitespace removed. Ending at comma allows us to write multiple tags on one line, but also means that tag values can not contain commas. - Eg in the following posting, the three tags' values are "value 1", + Eg in the following posting, the three tags' values are "value 1", "value 2", and "" (empty) respectively: expenses:food $10 ; foo, tag1: value 1 , tag2:value 2, bar tag3: , baz - Multiple tags with the same name are additive rather than overriding: - when the same tag name is seen again with a new value, the new + Multiple tags with the same name are additive rather than overriding: + when the same tag name is seen again with a new value, the new name:value pair is added to the tags. It is not possible to override a previous tag's value or remove a tag. - You can list all the values used for a particular tag in the journal + You can list all the values used for a particular tag in the journal with hledger tags TAGNAME --values You can match on tag values with a query like tag:NAMEREGEX=VALUEREGEX Directives - Besides transactions, there is something else you can put in a journal - file: directives. These are declarations, beginning with a keyword, - that modify hledger's behaviour. Some directives can have more spe- - cific subdirectives, indented below them. hledger's directives are + Besides transactions, there is something else you can put in a journal + file: directives. These are declarations, beginning with a keyword, + that modify hledger's behaviour. Some directives can have more spe- + cific subdirectives, indented below them. hledger's directives are similar to Ledger's in many cases, but there are also many differences. - Directives are not required, but can be useful. Here are the main di- + Directives are not required, but can be useful. Here are the main di- rectives: purpose directive @@ -1717,16 +1693,16 @@ Journal READING DATA: Rewrite account names alias Comment out sections of the file comment - Declare file's decimal mark, to help decimal-mark + Declare file's decimal mark, to help decimal-mark parse amounts accurately Include other data files include GENERATING DATA: - Generate recurring transactions or bud- ~ + Generate recurring transactions or bud- ~ get goals - Generate extra postings on existing = + Generate extra postings on existing = transactions CHECKING FOR ERRORS: - Define valid entities to provide more account, commodity, payee, tag + Define valid entities to provide more account, commodity, payee, tag error checking REPORTING: Declare accounts' type and display order account @@ -1734,23 +1710,23 @@ Journal Declare market prices P Directives and multiple files - Directives vary in their scope, ie which journal entries and which in- + Directives vary in their scope, ie which journal entries and which in- put files they affect. Most often, a directive will affect the follow- - ing entries and included files if any, until the end of the current + ing entries and included files if any, until the end of the current file - and no further. You might find this inconvenient! For example, - alias directives do not affect parent or sibling files. But there are + alias directives do not affect parent or sibling files. But there are usually workarounds; for example, put alias directives in your top-most file, before including other files. - The restriction, though it may be annoying at first, is in a good + The restriction, though it may be annoying at first, is in a good cause; it allows reports to be stable and deterministic, independent of - the order of input. Without it, reports could show different numbers - depending on the order of -f options, or the positions of include di- + the order of input. Without it, reports could show different numbers + depending on the order of -f options, or the positions of include di- rectives in your files. Directive effects - Here are all hledger's directives, with their effects and scope sum- - marised - nine main directives, plus four others which we consider + Here are all hledger's directives, with their effects and scope sum- + marised - nine main directives, plus four others which we consider non-essential: di- what it does ends @@ -1758,21 +1734,20 @@ Journal tive file end? -------------------------------------------------------------------------------------- - ac- Declares an account, for checking all entries in all files; and N + ac- Declares an account, for checking all entries in all files; and N count its display order and type. Subdirectives: any text, ignored. - alias Rewrites account names, in following entries until end of cur- Y + alias Rewrites account names, in following entries until end of cur- Y rent file or end aliases. Command line equivalent: --alias - com- Ignores part of the journal file, until end of current file or Y + com- Ignores part of the journal file, until end of current file or Y ment end comment. - com- Declares up to four things: 1. a commodity symbol, for checking N,Y,N,N - mod- all amounts in all files 2. the decimal mark for parsing - ity amounts of this commodity, in the following entries until end of - current file (if there is no decimal-mark directive) 3. and the - display style for amounts of this commodity 4. which is also - the precision to use for balanced-transaction checking in this - commodity. Takes precedence over D. Subdirectives: format - (Ledger-compatible syntax). Command line equivalent: -c/--com- - modity-style + com- Declares up to four things: 1. a commodity symbol, for checking N,N,Y,Y + mod- all amounts in all files 2. the display style for all amounts + ity of this commodity 3. the decimal mark for parsing amounts of + this commodity, in the rest of this file and its children, if + there is no decimal-mark directive 4. the precision to use for + balanced-transaction checking in this commodity, in this file + and its children. Takes precedence over D. Subdirectives: + format (ignored). Command line equivalent: -c/--commodity-style deci- Declares the decimal mark, for parsing amounts of all commodi- Y mal-mark ties in following entries until next decimal-mark or end of cur- rent file. Included files can override. Takes precedence over @@ -2190,25 +2165,31 @@ Journal 1. It declares which commodity symbols may be used in the journal, en- abling useful error checking with strict mode or the check command. - (See Commodity error checking below.) + See Commodity error checking below. - 2. It declares the precision with which this commodity's amounts should - be compared when checking for balanced transactions. + 2. It declares how all amounts in this commodity should be displayed, + eg how many decimals to show. See Commodity display style above. - 3. It declares how this commodity's amounts should be displayed, eg - their symbol placement, digit group mark if any, digit group sizes, - decimal mark (period or comma), and the number of decimal places. - (See Commodity display style above.) + 3. (If no decimal-mark directive is in effect:) It sets the decimal + mark to expect (period or comma) when parsing amounts in this com- + modity, in this file and files it includes, from the directive until + end of current file. See Decimal marks above. - 4. It sets which decimal mark (period or comma) to expect when parsing - subsequent amounts in this commodity (if there is no decimal-mark - directive in effect. See Decimal marks, digit group marks above. - For related dev discussion, see #793.) + 4. It declares the precision with which this commodity's amounts should + be compared when checking for balanced transactions, anywhere in + this file and files it includes, until end of current file. Declaring commodities solves several common parsing/display problems, - so we recommend it. Generally you should put commodity directives at - the top of your journal file (because function 4 is position-sensi- - tive). + so we recommend it. + + Note that effects 3 and 4 above end at the end of the directive's file, + and will not affect sibling or parent files. So if you are relying on + them (especially 4) and using multiple files, placing your commodity + directives in a top-level parent file might be important. Or, keep + your decimal marks unambiguous and your entries well balanced and pre- + cise. + + (Related: #793) Commodity directive syntax A commodity directive is normally the word commodity followed by a sam- @@ -2841,29 +2822,107 @@ Journal See also https://hledger.org/ledger.html for a detailed hledger/Ledger syntax comparison. + Other cost/lot notations + A slight digression for Ledger and Beancount users. Ledger has a num- + ber of cost/lot-related notations: + + o @ UNITCOST and @@ TOTALCOST + + o expresses a conversion rate, as in hledger + + o when buying, also creates a lot than can be selected at selling + time + + o (@) UNITCOST and (@@) TOTALCOST (virtual cost) + + o like the above, but also means "this cost was exceptional, don't + use it when inferring market prices". + + Currently, hledger treats the above like @ and @@; the parentheses are + ignored. + + o {=FIXEDUNITCOST} and {{=FIXEDTOTALCOST}} (fixed price) + + o when buying, means "this cost is also the fixed price, don't let it + fluctuate in value reports" + + o {UNITCOST} and {{TOTALCOST}} (lot price) + + o can be used identically to @ UNITCOST and @@ TOTALCOST, also cre- + ates a lot + + o when selling, combined with @ ..., specifies an investment lot by + its cost basis; does not check if that lot is present + + o and related: [YYYY/MM/DD] (lot date) + + o when buying, attaches this acquisition date to the lot + + o when selling, selects a lot by its acquisition date + + o (SOME TEXT) (lot note) + + o when buying, attaches this note to the lot + + o when selling, selects a lot by its note + + Currently, hledger accepts any or all of the above in any order after + the posting amount, but ignores them. (This can break transaction bal- + ancing.) + + For Beancount users, the notation and behaviour is different: + + o @ UNITCOST and @@ TOTALCOST + + o expresses a cost without creating a lot, as in hledger + + o when buying (augmenting) or selling (reducing) a lot, combined with + {...}: documents the cost/selling price (not used for transaction + balancing) + + o {UNITCOST} and {{TOTALCOST}} + + o when buying (augmenting), expresses the cost for transaction bal- + ancing, and also creates a lot with this cost basis attached + + o when selling (reducing), + + o selects a lot by its cost basis + + o raises an error if that lot is not present or can not be selected + unambiguously (depending on booking method configured) + + o expresses the selling price for transaction balancing + + Currently, hledger accepts the {UNITCOST}/{{TOTALCOST}} notation but + ignores it. + + o variations: {}, {YYYY-MM-DD}, {"LABEL"}, {UNITCOST, "LABEL"}, {UNIT- + COST, YYYY-MM-DD, "LABEL"} etc. + + Currently, hledger rejects these. + CSV - hledger can read CSV files (Character Separated Value - usually comma, - semicolon, or tab) containing dated records, automatically converting + hledger can read CSV files (Character Separated Value - usually comma, + semicolon, or tab) containing dated records, automatically converting each record into a transaction. (To learn about writing CSV, see CSV output.) - For best error messages when reading CSV/TSV/SSV files, make sure they + For best error messages when reading CSV/TSV/SSV files, make sure they have a corresponding .csv, .tsv or .ssv file extension or use a hledger file prefix (see File Extension below). Each CSV file must be described by a corresponding rules file. - This contains rules describing the CSV data (header line, fields lay- - out, date format etc.), how to construct hledger transactions from it, - and how to categorise transactions based on description or other at- + This contains rules describing the CSV data (header line, fields lay- + out, date format etc.), how to construct hledger transactions from it, + and how to categorise transactions based on description or other at- tributes. - By default hledger looks for a rules file named like the CSV file with - an extra .rules extension, in the same directory. Eg when asked to - read foo/FILE.csv, hledger looks for foo/FILE.csv.rules. You can spec- - ify a different rules file with the --rules-file option. If no rules - file is found, hledger will create a sample rules file, which you'll - need to adjust. + By default, hledger expects this rules file to be named like the CSV + file, with an extra .rules extension added, in the same directory. Eg + when asked to read foo/FILE.csv, hledger looks for foo/FILE.csv.rules. + You can specify a different rules file with the --rules-file option. At minimum, the rules file must identify the date and amount fields, and often it also specifies the date format and how many header lines @@ -3285,17 +3344,18 @@ CSV You can adjust the type of assertion/assignment with the balance-type rule (see below). - See Tips below for more about setting amounts and currency. + See the Working with CSV tips below for more about setting amounts and + currency. if block - Rules can be applied conditionally, depending on patterns in the CSV - data. This allows flexibility; in particular, it is how you can cate- - gorise transactions, selecting an appropriate account name based on - their description (for example). There are two ways to write condi- - tional rules: "if blocks", described here, and "if tables", described + Rules can be applied conditionally, depending on patterns in the CSV + data. This allows flexibility; in particular, it is how you can cate- + gorise transactions, selecting an appropriate account name based on + their description (for example). There are two ways to write condi- + tional rules: "if blocks", described here, and "if tables", described below. - An if block is the word if and one or more "matcher" expressions (can + An if block is the word if and one or more "matcher" expressions (can be a word or phrase), one per line, starting either on the same or next line; followed by one or more indented rules. Eg, @@ -3311,11 +3371,11 @@ CSV RULE RULE - If any of the matchers succeeds, all of the indented rules will be ap- - plied. They are usually field assignments, but the following special + If any of the matchers succeeds, all of the indented rules will be ap- + plied. They are usually field assignments, but the following special rules may also be used within an if block: - o skip - skips the matched CSV record (generating no transaction from + o skip - skips the matched CSV record (generating no transaction from it) o end - skips the rest of the current CSV file. @@ -3341,27 +3401,27 @@ CSV Matchers There are two kinds: - 1. A record matcher is a word or single-line text fragment or regular - expression (REGEX), which hledger will try to match case-insensi- + 1. A record matcher is a word or single-line text fragment or regular + expression (REGEX), which hledger will try to match case-insensi- tively anywhere within the CSV record. Eg: whole foods - 2. A field matcher is preceded with a percent sign and CSV field name - (%CSVFIELD REGEX). hledger will try to match these just within the + 2. A field matcher is preceded with a percent sign and CSV field name + (%CSVFIELD REGEX). hledger will try to match these just within the named CSV field. Eg: %date 2023 - The regular expression is (as usual in hledger) a POSIX extended regu- - lar expression, that also supports GNU word boundaries (\b, \B, \<, - \>), and nothing else. If you have trouble, see "Regular expressions" + The regular expression is (as usual in hledger) a POSIX extended regu- + lar expression, that also supports GNU word boundaries (\b, \B, \<, + \>), and nothing else. If you have trouble, see "Regular expressions" in the hledger manual (https://hledger.org/hledger.html#regular-expres- sions). What matchers match With record matchers, it's important to know that the record matched is - not the original CSV record, but a modified one: separators will be - converted to commas, and enclosing double quotes (but not enclosing - whitespace) are removed. So for example, when reading an SSV file, if + not the original CSV record, but a modified one: separators will be + converted to commas, and enclosing double quotes (but not enclosing + whitespace) are removed. So for example, when reading an SSV file, if the original record was: 2023-01-01; "Acme, Inc."; 1,000 @@ -3373,28 +3433,29 @@ CSV Combining matchers When an if block has multiple matchers, they are combined as follows: - o By default they are OR'd (any one of them can match) + o By default they are OR'd (any of them can match) - o When a matcher is preceded by ampersand (&) it will be AND'ed with - the previous matcher (both of them must match) + o When a matcher is preceded by ampersand (&, at the start of the line) + it will be AND'ed with the previous matcher (all in the AND'ed group + must match) - o Added in 1.32 When a matcher is preceded by an exclamation mark (!), - the matcher is negated (it may not match). + o Added in 1.32 When a matcher is preceded by an exclamation mark (!), + it is negated (it must not match). - Currently there is a limitation: you can't use both & and ! on the same - line (you can't AND a negated matcher). + Note currently there is a limitation: you can't use both & and ! on the + same line (you can't AND a negated matcher). Match groups Added in 1.32 Matchers can define match groups: parenthesised portions of the regular - expression which are available for reference in field assignments. + expression which are available for reference in field assignments. Groups are enclosed in regular parentheses (( and )) and can be nested. - Each group is available in field assignments using the token \N, where - N is an index into the match groups for this conditional block (e.g. + Each group is available in field assignments using the token \N, where + N is an index into the match groups for this conditional block (e.g. \1, \2, etc.). - Example: Warp credit card payment postings to the beginning of the + Example: Warp credit card payment postings to the beginning of the billing period (Month start), to match how they are presented in state- ments, using posting dates: @@ -3408,31 +3469,36 @@ CSV account1 \1 if table - "if tables" are an alternative to if blocks; they can express many - matchers and field assignments in a more compact tabular format, like + "if tables" are an alternative to if blocks; they can express many + matchers and field assignments in a more compact tabular format, like this: if,HLEDGERFIELD1,HLEDGERFIELD2,... MATCHERA,VALUE1,VALUE2,... MATCHERB,VALUE1,VALUE2,... + ; Comment line that explains MATCHERC MATCHERC,VALUE1,VALUE2,... The first character after if is taken to be this if table's field sepa- - rator. It is unrelated to the separator used in the CSV file. It + rator. It is unrelated to the separator used in the CSV file. It should be a non-alphanumeric character like , or | that does not appear - anywhere else in the table (it should not be used in field names or + anywhere else in the table (it should not be used in field names or matchers or values, and it cannot be escaped with a backslash). - Each line must contain the same number of separators; empty values are - allowed. Whitespace can be used in the matcher lines for readability - (but not in the if line, currently). The table must be terminated by - an empty line (or end of file). + Each line must contain the same number of separators; empty values are + allowed. Whitespace can be used in the matcher lines for readability + (but not in the if line, currently). You can use the comment lines in + the table body. The table must be terminated by an empty line (or end + of file). An if table like the above is interpreted as follows: try all of the matchers; whenever a matcher succeeds, assign all of the values on that - line to the corresponding hledger fields; later lines can overrider - earlier ones. It is equivalent to this sequence of if blocks: + line to the corresponding hledger fields; If multiple lines match, + later lines will override fields assigned by the earlier ones - just + like the sequence of if blocks would behave. + + If table presented above is equivalent to this sequence of if blocks: if MATCHERA HLEDGERFIELD1 VALUE1 @@ -3444,6 +3510,7 @@ CSV HLEDGERFIELD2 VALUE2 ... + ; Comment line which explains MATCHERC if MATCHERC HLEDGERFIELD1 VALUE1 HLEDGERFIELD2 VALUE2 @@ -3454,14 +3521,15 @@ CSV if,account2,comment atm transaction fee,expenses:business:banking,deductible? check it %description groceries,expenses:groceries, + ;; Comment line that desribes why this particular date is special 2023/01/12.*Plumbing LLC,expenses:house:upkeep,emergency plumbing call-out balance-type Balance assertions generated by assigning to balanceN are of the simple - = type by default, which is a single-commodity, subaccount-excluding + = type by default, which is a single-commodity, subaccount-excluding assertion. You may find the subaccount-including variants more useful, - eg if you have created some virtual subaccounts of checking to help - with budgeting. You can select a different type of assertion with the + eg if you have created some virtual subaccounts of checking to help + with budgeting. You can select a different type of assertion with the balance-type rule: # balance assertions will consider all commodities and all subaccounts @@ -3477,9 +3545,9 @@ CSV include include RULESFILE - This includes the contents of another CSV rules file at this point. - RULESFILE is an absolute file path or a path relative to the current - file's directory. This can be useful for sharing common rules between + This includes the contents of another CSV rules file at this point. + RULESFILE is an absolute file path or a path relative to the current + file's directory. This can be useful for sharing common rules between several rules files, eg: # someaccount.csv.rules @@ -3496,42 +3564,42 @@ CSV Some tips: Rapid feedback - It's a good idea to get rapid feedback while creating/troubleshooting + It's a good idea to get rapid feedback while creating/troubleshooting CSV rules. Here's a good way, using entr from eradman.com/entrproject: $ ls foo.csv* | entr bash -c 'echo ----; hledger -f foo.csv print desc:SOMEDESC' - A desc: query (eg) is used to select just one, or a few, transactions - of interest. "bash -c" is used to run multiple commands, so we can - echo a separator each time the command re-runs, making it easier to + A desc: query (eg) is used to select just one, or a few, transactions + of interest. "bash -c" is used to run multiple commands, so we can + echo a separator each time the command re-runs, making it easier to read the output. Valid CSV - Note that hledger will only accept valid CSV conforming to RFC 4180, + Note that hledger will only accept valid CSV conforming to RFC 4180, and equivalent SSV and TSV formats (like RFC 4180 but with semicolon or tab as separators). This means, eg: o Values may be enclosed in double quotes, or not. Enclosing in single quotes is not allowed. (Eg 'A','B' is rejected.) - o When values are enclosed in double quotes, spaces outside the quotes + o When values are enclosed in double quotes, spaces outside the quotes are not allowed. (Eg "A", "B" is rejected.) - o When values are not enclosed in quotes, they may not contain double + o When values are not enclosed in quotes, they may not contain double quotes. (Eg A"A, B is rejected.) - If your CSV/SSV/TSV is not valid in this sense, you'll need to trans- - form it before reading with hledger. Try using sed, or a more permis- + If your CSV/SSV/TSV is not valid in this sense, you'll need to trans- + form it before reading with hledger. Try using sed, or a more permis- sive CSV parser like python's csv lib. File Extension - To help hledger choose the CSV file reader and show the right error - messages (and choose the right field separator character by default), - it's best if CSV/SSV/TSV files are named with a .csv, .ssv or .tsv + To help hledger choose the CSV file reader and show the right error + messages (and choose the right field separator character by default), + it's best if CSV/SSV/TSV files are named with a .csv, .ssv or .tsv filename extension. (More about this at Data formats.) - When reading files with the "wrong" extension, you can ensure the CSV - reader (and the default field separator) by prefixing the file path + When reading files with the "wrong" extension, you can ensure the CSV + reader (and the default field separator) by prefixing the file path with csv:, ssv: or tsv:: Eg: $ hledger -f ssv:foo.dat print @@ -3540,29 +3608,29 @@ CSV if needed. Reading CSV from standard input - You'll need the file format prefix when reading CSV from stdin also, + You'll need the file format prefix when reading CSV from stdin also, since hledger assumes journal format by default. Eg: $ cat foo.dat | hledger -f ssv:- print Reading multiple CSV files - If you use multiple -f options to read multiple CSV files at once, - hledger will look for a correspondingly-named rules file for each CSV - file. But if you use the --rules-file option, that rules file will be + If you use multiple -f options to read multiple CSV files at once, + hledger will look for a correspondingly-named rules file for each CSV + file. But if you use the --rules-file option, that rules file will be used for all the CSV files. Reading files specified by rule Instead of specifying a CSV file in the command line, you can specify a - rules file, as in hledger -f foo.csv.rules CMD. By default this will - read data from foo.csv in the same directory, but you can add a source - rule to specify a different data file, perhaps located in your web + rules file, as in hledger -f foo.csv.rules CMD. By default this will + read data from foo.csv in the same directory, but you can add a source + rule to specify a different data file, perhaps located in your web browser's download directory. This feature was added in hledger 1.30, so you won't see it in most CSV - rules examples. But it helps remove some of the busywork of managing + rules examples. But it helps remove some of the busywork of managing CSV downloads. Most of your financial institutions's default CSV file- - names are different and can be recognised by a glob pattern. So you - can put a rule like source Checking1*.csv in foo-checking.csv.rules, + names are different and can be recognised by a glob pattern. So you + can put a rule like source Checking1*.csv in foo-checking.csv.rules, and then periodically follow a workflow like: 1. Download CSV from Foo's website, using your browser's defaults @@ -3570,45 +3638,45 @@ CSV 2. Run hledger import foo-checking.csv.rules to import any new transac- tions - After import, you can: discard the CSV, or leave it where it is for a - while, or move it into your archives, as you prefer. If you do noth- - ing, next time your browser will save something like Checking1-2.csv, - and hledger will use that because of the * wild card and because it is + After import, you can: discard the CSV, or leave it where it is for a + while, or move it into your archives, as you prefer. If you do noth- + ing, next time your browser will save something like Checking1-2.csv, + and hledger will use that because of the * wild card and because it is the most recent. Valid transactions After reading a CSV file, hledger post-processes and validates the gen- erated journal entries as it would for a journal file - balancing them, - applying balance assignments, and canonicalising amount styles. Any - errors at this stage will be reported in the usual way, displaying the + applying balance assignments, and canonicalising amount styles. Any + errors at this stage will be reported in the usual way, displaying the problem entry. There is one exception: balance assertions, if you have generated them, - will not be checked, since normally these will work only when the CSV - data is part of the main journal. If you do need to check balance as- + will not be checked, since normally these will work only when the CSV + data is part of the main journal. If you do need to check balance as- sertions generated from CSV right away, pipe into another hledger: $ hledger -f file.csv print | hledger -f- print Deduplicating, importing - When you download a CSV file periodically, eg to get your latest bank - transactions, the new file may overlap with the old one, containing + When you download a CSV file periodically, eg to get your latest bank + transactions, the new file may overlap with the old one, containing some of the same records. The import command will (a) detect the new transactions, and (b) append just those transactions to your main journal. It is idempotent, so you - don't have to remember how many times you ran it or with which version - of the CSV. (It keeps state in a hidden .latest.FILE.csv file.) This + don't have to remember how many times you ran it or with which version + of the CSV. (It keeps state in a hidden .latest.FILE.csv file.) This is the easiest way to import CSV data. Eg: # download the latest CSV files, then run this command. # Note, no -f flags needed here. $ hledger import *.csv [--dry] - This method works for most CSV files. (Where records have a stable + This method works for most CSV files. (Where records have a stable chronological order, and new records appear only at the new end.) - A number of other tools and workflows, hledger-specific and otherwise, + A number of other tools and workflows, hledger-specific and otherwise, exist for converting, deduplicating, classifying and managing CSV data. See: @@ -3617,16 +3685,16 @@ CSV o https://plaintextaccounting.org -> data import/conversion Setting amounts - Continuing from amount field above, here are more tips for amount-set- + Continuing from amount field above, here are more tips for amount-set- ting: 1. If the amount is in a single CSV field: a. If its sign indicates direction of flow: - Assign it to amountN, to set the Nth posting's amount. N is usu- + Assign it to amountN, to set the Nth posting's amount. N is usu- ally 1 or 2 but can go up to 99. b. If another field indicates direction of flow: - Use one or more conditional rules to set the appropriate amount + Use one or more conditional rules to set the appropriate amount sign. Eg: # assume a withdrawal unless Type contains "deposit": @@ -3634,15 +3702,15 @@ CSV if %Type deposit amount1 %Amount - 2. If the amount is in two CSV fields (such as Debit and Credit, or In + 2. If the amount is in two CSV fields (such as Debit and Credit, or In and Out): a. If both fields are unsigned: - Assign one field to amountN-in and the other to amountN-out. - hledger will automatically negate the "out" field, and will use + Assign one field to amountN-in and the other to amountN-out. + hledger will automatically negate the "out" field, and will use whichever field value is non-zero as posting N's amount. b. If either field is signed: - You will probably need to override hledger's sign for one or the + You will probably need to override hledger's sign for one or the other field, as in the following example: # Negate the -out value, but only if it is not empty: @@ -3650,12 +3718,12 @@ CSV if %amount1-out [1-9] amount1-out -%amount1-out - c. If both fields can contain a non-zero value (or both can be + c. If both fields can contain a non-zero value (or both can be empty): - The -in/-out rules normally choose the value which is - non-zero/non-empty. Some value pairs can be ambiguous, such as 1 + The -in/-out rules normally choose the value which is + non-zero/non-empty. Some value pairs can be ambiguous, such as 1 and none. For such cases, use conditional rules to help select the - amount. Eg, to handle the above you could select the value con- + amount. Eg, to handle the above you could select the value con- taining non-zero digits: fields date, description, in, out @@ -3668,8 +3736,8 @@ CSV Use the unnumbered amount (or amount-in and amount-out) syntax. 4. If the CSV has only balance amounts, not transaction amounts: - Assign to balanceN, to set a balance assignment on the Nth posting, - causing the posting's amount to be calculated automatically. balance + Assign to balanceN, to set a balance assignment on the Nth posting, + causing the posting's amount to be calculated automatically. balance with no number is equivalent to balance1. In this situation hledger is more likely to guess the wrong default account name, so you may need to set that explicitly. @@ -3685,20 +3753,20 @@ CSV o If an amount value is parenthesised: it will be de-parenthesised and sign-flipped: (AMT) becomes -AMT - o If an amount value has two minus signs (or two sets of parentheses, + o If an amount value has two minus signs (or two sets of parentheses, or a minus sign and parentheses): they cancel out and will be removed: --AMT or -(AMT) becomes AMT - o If an amount value contains just a sign (or just a set of parenthe- + o If an amount value contains just a sign (or just a set of parenthe- ses): - that is removed, making it an empty value. "+" or "-" or "()" becomes + that is removed, making it an empty value. "+" or "-" or "()" becomes "". - It's not possible (without preprocessing the CSV) to set an amount to + It's not possible (without preprocessing the CSV) to set an amount to its absolute value, ie discard its sign. Setting currency/commodity - If the currency/commodity symbol is included in the CSV's amount + If the currency/commodity symbol is included in the CSV's amount field(s): 2023-01-01,foo,$123.00 @@ -3717,7 +3785,7 @@ CSV 2023-01-01,foo,USD,123.00 You can assign that to the currency pseudo-field, which has the special - effect of prepending itself to every amount in the transaction (on the + effect of prepending itself to every amount in the transaction (on the left, with no separating space): fields date,description,currency,amount @@ -3726,7 +3794,7 @@ CSV expenses:unknown USD123.00 income:unknown USD-123.00 - Or, you can use a field assignment to construct the amount yourself, + Or, you can use a field assignment to construct the amount yourself, with more control. Eg to put the symbol on the right, and separated by a space: @@ -3737,7 +3805,7 @@ CSV expenses:unknown 123.00 USD income:unknown -123.00 USD - Note we used a temporary field name (cur) that is not currency - that + Note we used a temporary field name (cur) that is not currency - that would trigger the prepending effect, which we don't want here. Amount decimal places @@ -3745,13 +3813,13 @@ CSV amount1 influence commodity display styles, such as the number of deci- mal places displayed in reports. - The original amounts as written in the CSV file do not affect display + The original amounts as written in the CSV file do not affect display style (because we don't yet reliably know their commodity). Referencing other fields - In field assignments, you can interpolate only CSV fields, not hledger - fields. In the example below, there's both a CSV field and a hledger - field named amount1, but %amount1 always means the CSV field, not the + In field assignments, you can interpolate only CSV fields, not hledger + fields. In the example below, there's both a CSV field and a hledger + field named amount1, but %amount1 always means the CSV field, not the hledger field: # Name the third CSV field "amount1" @@ -3763,7 +3831,7 @@ CSV # Set comment to the CSV amount1 (not the amount1 assigned above) comment %amount1 - Here, since there's no CSV amount1 field, %amount1 will produce a lit- + Here, since there's no CSV amount1 field, %amount1 will produce a lit- eral "amount1": fields date,description,csvamount @@ -3771,7 +3839,7 @@ CSV # Can't interpolate amount1 here comment %amount1 - When there are multiple field assignments to the same hledger field, + When there are multiple field assignments to the same hledger field, only the last one takes effect. Here, comment's value will be be B, or C if "something" is matched, but never A: @@ -3781,14 +3849,14 @@ CSV comment C How CSV rules are evaluated - Here's how to think of CSV rules being evaluated (if you really need + Here's how to think of CSV rules being evaluated (if you really need to). First, - o include - all includes are inlined, from top to bottom, depth first. - (At each include point the file is inlined and scanned for further + o include - all includes are inlined, from top to bottom, depth first. + (At each include point the file is inlined and scanned for further includes, recursively, before proceeding.) - Then "global" rules are evaluated, top to bottom. If a rule is re- + Then "global" rules are evaluated, top to bottom. If a rule is re- peated, the last one wins: o skip (at top level) @@ -3802,30 +3870,30 @@ CSV Then for each CSV record in turn: - o test all if blocks. If any of them contain a end rule, skip all re- - maining CSV records. Otherwise if any of them contain a skip rule, - skip that many CSV records. If there are multiple matched skip + o test all if blocks. If any of them contain a end rule, skip all re- + maining CSV records. Otherwise if any of them contain a skip rule, + skip that many CSV records. If there are multiple matched skip rules, the first one wins. - o collect all field assignments at top level and in matched if blocks. - When there are multiple assignments for a field, keep only the last + o collect all field assignments at top level and in matched if blocks. + When there are multiple assignments for a field, keep only the last one. - o compute a value for each hledger field - either the one that was as- + o compute a value for each hledger field - either the one that was as- signed to it (and interpolate the %CSVFIELD references), or a default o generate a hledger transaction (journal entry) from these values. - This is all part of the CSV reader, one of several readers hledger can - use to parse input files. When all files have been read successfully, - the transactions are passed as input to whichever hledger command the + This is all part of the CSV reader, one of several readers hledger can + use to parse input files. When all files have been read successfully, + the transactions are passed as input to whichever hledger command the user specified. Well factored rules - Some things than can help reduce duplication and complexity in rules + Some things than can help reduce duplication and complexity in rules files: - o Extracting common rules usable with multiple CSV files into a com- + o Extracting common rules usable with multiple CSV files into a com- mon.rules, and adding include common.rules to each CSV's rules file. o Splitting if blocks into smaller if blocks, extracting the frequently @@ -3833,8 +3901,8 @@ CSV CSV rules examples Bank of Ireland - Here's a CSV with two amount fields (Debit and Credit), and a balance - field, which we can use to add balance assertions, which is not neces- + Here's a CSV with two amount fields (Debit and Credit), and a balance + field, which we can use to add balance assertions, which is not neces- sary but provides extra error checking: Date,Details,Debit,Credit,Balance @@ -3876,13 +3944,13 @@ CSV assets:bank:boi:checking EUR-5.0 = EUR126.0 expenses:unknown EUR5.0 - The balance assertions don't raise an error above, because we're read- - ing directly from CSV, but they will be checked if these entries are + The balance assertions don't raise an error above, because we're read- + ing directly from CSV, but they will be checked if these entries are imported into a journal file. Coinbase - A simple example with some CSV from Coinbase. The spot price is - recorded using cost notation. The legacy amount field name conve- + A simple example with some CSV from Coinbase. The spot price is + recorded using cost notation. The legacy amount field name conve- niently sets amount 2 (posting 2's amount) to the total cost. # Timestamp,Transaction Type,Asset,Quantity Transacted,Spot Price Currency,Spot Price at Transaction,Subtotal,Total (inclusive of fees and/or spread),Fees and/or Spread,Notes @@ -3904,7 +3972,7 @@ CSV Amazon Here we convert amazon.com order history, and use an if block to gener- - ate a third posting if there's a fee. (In practice you'd probably get + ate a third posting if there's a fee. (In practice you'd probably get this data from your bank instead, but it's an example.) "Date","Type","To/From","Name","Status","Amount","Fees","Transaction ID" @@ -3956,7 +4024,7 @@ CSV expenses:fees $1.00 Paypal - Here's a real-world rules file for (customised) Paypal CSV, with some + Here's a real-world rules file for (customised) Paypal CSV, with some Paypal-specific rules, and a second rules file included: "Date","Time","TimeZone","Name","Type","Status","Currency","Gross","Fee","Net","From Email Address","To Email Address","Transaction ID","Item Title","Item ID","Reference Txn ID","Receipt ID","Balance","Note" @@ -4107,12 +4175,12 @@ CSV Timeclock The time logging format of timeclock.el, as read by hledger. - hledger can read time logs in timeclock format. As with Ledger, these - are (a subset of) timeclock.el's format, containing clock-in and - clock-out entries as in the example below. The date is a simple date. - The time format is HH:MM[:SS][+-ZZZZ]. Seconds and timezone are op- - tional. The timezone, if present, must be four digits and is ignored - (currently the time is always interpreted as a local time). Lines be- + hledger can read time logs in timeclock format. As with Ledger, these + are (a subset of) timeclock.el's format, containing clock-in and + clock-out entries as in the example below. The date is a simple date. + The time format is HH:MM[:SS][+-ZZZZ]. Seconds and timezone are op- + tional. The timezone, if present, must be four digits and is ignored + (currently the time is always interpreted as a local time). Lines be- ginning with # or ; or *, and blank lines, are ignored. i 2015/03/30 09:00:00 some account optional description after 2 spaces ; optional comment, tags: @@ -4120,9 +4188,9 @@ Timeclock i 2015/03/31 22:21:45 another:account o 2015/04/01 02:00:34 - hledger treats each clock-in/clock-out pair as a transaction posting - some number of hours to an account. Or if the session spans more than - one day, it is split into several transactions, one for each day. For + hledger treats each clock-in/clock-out pair as a transaction posting + some number of hours to an account. Or if the session spans more than + one day, it is split into several transactions, one for each day. For the above time log, hledger print generates these journal entries: $ hledger -f t.timeclock print @@ -4143,21 +4211,21 @@ Timeclock To generate time logs, ie to clock in and clock out, you could: - o use emacs and the built-in timeclock.el, or the extended time- + o use emacs and the built-in timeclock.el, or the extended time- clock-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 + o at the command line, use these bash aliases: cli alias ti="echo i + `date '+%Y-%m-%d %H:%M:%S'` \$* >>$TIMELOG" alias to="echo o `date '+%Y-%m-%d %H:%M:%S'` >>$TIMELOG" o or use the old ti and to scripts in the ledger 2.x repository. These - rely on a "timeclock" executable which I think is just the ledger 2 + rely on a "timeclock" executable which I think is just the ledger 2 executable renamed. Timedot - timedot format is hledger's human-friendly time logging format. Com- - pared to timeclock format, it is more convenient for quick, approxi- - mate, and retroactive time logging, and more human-readable (you can + timedot format is hledger's human-friendly time logging format. Com- + pared to timeclock format, it is more convenient for quick, approxi- + mate, and retroactive time logging, and more human-readable (you can see at a glance where time was spent). A quick example: 2023-05-01 @@ -4176,54 +4244,54 @@ Timedot (per:admin:finance) 0 A timedot file contains a series of transactions (usually one per day). - Each begins with a simple date (Y-M-D, Y/M/D, or Y.M.D), optionally be + Each begins with a simple date (Y-M-D, Y/M/D, or Y.M.D), optionally be followed on the same line by a transaction description, and/or a trans- action comment following a semicolon. After the date line are zero or more time postings, consisting of: - o An account name - any hledger-style account name, optionally in- + o An account name - any hledger-style account name, optionally in- dented. - o Two or more spaces - required if there is an amount (as in journal + o Two or more spaces - required if there is an amount (as in journal format). o A timedot amount, which can be o empty (representing zero) - o a number, optionally followed by a unit s, m, h, d, w, mo, or y, - representing a precise number of seconds, minutes, hours, days + o a number, optionally followed by a unit s, m, h, d, w, mo, or y, + representing a precise number of seconds, minutes, hours, days weeks, months or years (hours is assumed by default), which will be - converted to hours according to 60s = 1m, 60m = 1h, 24h = 1d, 7d = + converted to hours according to 60s = 1m, 60m = 1h, 24h = 1d, 7d = 1w, 30d = 1mo, 365d = 1y. - o one or more dots (period characters), each representing 0.25. - These are the dots in "timedot". Spaces are ignored and can be + o one or more dots (period characters), each representing 0.25. + These are the dots in "timedot". Spaces are ignored and can be used for grouping/alignment. - o Added in 1.32 one or more letters. These are like dots but they - also generate a tag t: (short for "type") with the letter as its - value, and a separate posting for each of the values. This pro- - vides a second dimension of categorisation, viewable in reports + o Added in 1.32 one or more letters. These are like dots but they + also generate a tag t: (short for "type") with the letter as its + value, and a separate posting for each of the values. This pro- + vides a second dimension of categorisation, viewable in reports with --pivot t. - o An optional comment following a semicolon (a hledger-style posting + o An optional comment following a semicolon (a hledger-style posting comment). - There is some flexibility to help with keeping time log data and notes + There is some flexibility to help with keeping time log data and notes in the same file: o Blank lines and lines beginning with # or ; are ignored. - o After the first date line, lines which do not contain a double space + o After the first date line, lines which do not contain a double space are parsed as postings with zero amount. (hledger's register reports will show these if you add -E). - o Before the first date line, lines beginning with * (eg org headings) - are ignored. And from the first date line onward, Emacs org mode + o Before the first date line, lines beginning with * (eg org headings) + are ignored. And from the first date line onward, Emacs org mode heading prefixes at the start of lines (one or more *'s followed by a - space) will be ignored. This means the time log can also be a org + space) will be ignored. This means the time log can also be a org outline. Timedot examples @@ -4329,12 +4397,61 @@ Timedot 4.50 PART 3: REPORTING CONCEPTS -Amount formatting, parseability +Amount formatting + Commodity display style + For the amounts in each commodity, hledger chooses a consistent display + style (symbol placement, decimal mark and digit group marks, number of + decimal digits) to use in most reports. This is inferred as follows: + + First, if there's a D directive declaring a default commodity, that + commodity symbol and amount format is applied to all no-symbol amounts + in the journal. + + Then each commodity's display style is determined from its commodity + directive. We recommend always declaring commodities with commodity + directives, since they help ensure consistent display styles and preci- + sions, and bring other benefits such as error checking for commodity + symbols. Here's an example: + + # Set display styles (and decimal marks, for parsing, if there is no decimal-mark directive) + # for the $, EUR, INR and no-symbol commodities: + commodity $1,000.00 + commodity EUR 1.000,00 + commodity INR 9,99,99,999.00 + commodity 1 000 000.9455 + + But for convenience, if a commodity directive is not present, hledger + infers a commodity's display styles from its amounts as they are writ- + ten in the journal (excluding cost amounts and amounts in periodic + transaction rules or auto posting rules). It uses + + o the symbol placement and decimal mark of the first amount seen + + o the digit group marks of the first amount with digit group marks + + o and the maximum number of decimal digits seen across all amounts. + + And as fallback if no applicable amounts are found, it would use a de- + fault style, like $1000.00 (symbol on the left with no space, period as + decimal mark, and two decimal digits). + + Finally, commodity styles can be overridden by the -c/--commodity-style + command line option. + + Rounding + Amounts are stored internally as decimal numbers with up to 255 decimal + places. They are displayed with their original journal precisions by + print and print-like reports, and rounded to their display precision + (the number of decimal digits specified by the commodity display style) + by other reports. When rounding, hledger uses banker's rounding (it + rounds to the nearest even digit). So eg 0.5 displayed with zero deci- + mal digits appears as "0". + + Trailing decimal marks If you're wondering why your print report sometimes shows trailing dec- imal marks, with no decimal digits; it does this when showing amounts that have digit group marks but no decimal digits, to disambiguate them - and allow them to be re-parsed reliably (see also Decimal marks, digit - group marks. Eg: + and allow them to be re-parsed reliably (see Decimal marks). Eg: commodity $1,000.00 @@ -4346,7 +4463,7 @@ Amount formatting, parseability (a) $1,000. If this is a problem (eg when exporting to Ledger), you can avoid it by - disabling digit group marks, eg with -c/--commodity (for each affected + disabling digit group marks, eg with -c/--commodity (for each affected commodity): $ hledger print -c '$1000.00' @@ -4359,22 +4476,23 @@ Amount formatting, parseability 2023-01-02 (a) $1,000.00 - More generally: hledger output falls into three rough categories, which + Amount parseability + More generally, hledger output falls into three rough categories, which format amounts a little bit differently to suit different consumers: - 1. "hledger-readable output" - should be readable by hledger (and by + 1. "hledger-readable output" - should be readable by hledger (and by humans) - o This is produced by reports that show full journal entries: print, + o This is produced by reports that show full journal entries: print, import, close, rewrite etc. - o It shows amounts with their original journal precisions, which may + o It shows amounts with their original journal precisions, which may not be consistent. - o It adds a trailing decimal mark when needed to avoid showing ambigu- + o It adds a trailing decimal mark when needed to avoid showing ambigu- ous amounts. - o It can be parsed reliably (by hledger and ledger2beancount at least, + o It can be parsed reliably (by hledger and ledger2beancount at least, but perhaps not by Ledger..) 2. "human-readable output" - usually for humans @@ -4386,13 +4504,13 @@ Amount formatting, parseability o It shows ambiguous amounts unmodified. - o It can be parsed reliably in the context of a known report (when you + o It can be parsed reliably in the context of a known report (when you know decimals are consistently not being shown, you can assume a sin- gle mark is a digit group mark). 3. "machine-readable output" - usually for other software - o This is produced by all reports when an output format like csv, tsv, + o This is produced by all reports when an output format like csv, tsv, json, or sql is selected. o It shows amounts as 1 or 2 do, but without digit group marks. @@ -4403,39 +4521,39 @@ Amount formatting, parseability Time periods Report start & end date By default, most hledger reports will show the full span of time repre- - sented by the journal. The report start date will be the earliest + sented by the journal. The report start date will be the earliest transaction or posting date, and the report end date will be the latest transaction, posting, or market price date. - Often you will want to see a shorter 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 (below). Some notes: - o End dates are exclusive, as in Ledger, so you should write the date + o End dates are exclusive, as in Ledger, so you should write the date after the last day you want to see in the report. - o As noted in reporting options: among start/end dates specified with + o As noted in reporting options: among start/end dates specified with options, the last (i.e. right-most) option takes precedence. - o The effective report start and end dates are the intersection of the - start/end dates from options and that from date: queries. That is, - date:2019-01 date:2019 -p'2000 to 2030' yields January 2019, the + o The effective report start and end dates are the intersection of the + start/end dates from options and that from date: queries. That is, + date:2019-01 date:2019 -p'2000 to 2030' yields January 2019, the smallest common time span. - o In some cases a report interval will adjust start/end dates to fall + o In some cases a report interval will adjust start/end dates to fall on interval boundaries (see below). Examples: -b 2016/3/17 begin on St. Patrick's day 2016 - -e 12/1 end at the start of december 1st of the current year + -e 12/1 end at the start of december 1st of the current year (11/30 will be the last date included) -b thismonth all transactions on or after the 1st of the current month -p thismonth all transactions in the current month - date:2016/3/17.. the above written as queries instead (.. can also be re- + date:2016/3/17.. the above written as queries instead (.. can also be re- placed with -) date:..12/1 date:thismonth.. @@ -4443,11 +4561,11 @@ Time periods Smart dates hledger's user interfaces accept a "smart date" syntax for added conve- - nience. Smart dates optionally can be relative to today's date, be - written with english words, and have less-significant parts omitted + nience. Smart dates optionally can be relative to today's date, be + written with english words, and have less-significant parts omitted (missing parts are inferred as 1). Some examples: - 2004/10/1, 2004-01-01, exact date, several separators allowed. Year + 2004/10/1, 2004-01-01, exact date, several separators allowed. Year 2004.9.1 is 4+ digits, month is 1-12, day is 1-31 2004 start of year 2004/10 start of month @@ -4471,26 +4589,26 @@ Time periods 20181201 8 digit YYYYMMDD with valid year month and day 201812 6 digit YYYYMM with valid year and month - Some counterexamples - malformed digit sequences might give surprising + Some counterexamples - malformed digit sequences might give surprising results: - 201813 6 digits with an invalid month is parsed as start of + 201813 6 digits with an invalid month is parsed as start of 6-digit year - 20181301 8 digits with an invalid month is parsed as start of + 20181301 8 digits with an invalid month is parsed as start of 8-digit year 20181232 8 digits with an invalid day gives an error 201801012 9+ digits beginning with a valid YYYYMMDD gives an error - "Today's date" can be overridden with the --today option, in case it's + "Today's date" can be overridden with the --today option, in case it's needed for testing or for recreating old reports. (Except for periodic transaction rules, which are not affected by --today.) Report intervals - A report interval can be specified so that reports like register, bal- + A report interval can be specified so that reports like register, bal- ance or activity become multi-period, showing each subperiod as a sepa- rate row or column. - The following standard intervals can be enabled with command-line + The following standard intervals can be enabled with command-line flags: o -D/--daily @@ -4503,47 +4621,47 @@ Time periods o -Y/--yearly - More complex intervals can be specified using -p/--period, described + More complex intervals can be specified using -p/--period, described below. Date adjustment - When there is a report interval (other than daily), report start/end - dates which have been inferred, eg from the journal, are automatically - adjusted to natural period boundaries. This is convenient for produc- + When there is a report interval (other than daily), report start/end + dates which have been inferred, eg from the journal, are automatically + adjusted to natural period boundaries. This is convenient for produc- ing simple periodic reports. More precisely: - o an inferred start date will be adjusted earlier if needed to fall on + o an inferred start date will be adjusted earlier if needed to fall on a natural period boundary - o an inferred end date will be adjusted later if needed to make the + o an inferred end date will be adjusted later if needed to make the last period the same length as the others. By contrast, start/end dates which have been specified explicitly, with - -b, -e, -p or date:, will not be adjusted (since hledger 1.29). This - makes it possible to specify non-standard report periods, but it also - means that if you are specifying a start date, you should pick one - that's on a period boundary if you want to see simple report period + -b, -e, -p or date:, will not be adjusted (since hledger 1.29). This + makes it possible to specify non-standard report periods, but it also + means that if you are specifying a start date, you should pick one + that's on a period boundary if you want to see simple report period headings. Period expressions - The -p/--period option specifies a period expression, which is a com- + The -p/--period option specifies a period expression, which is a com- pact way of expressing a start date, end date, and/or report interval. - Here's a period expression with a start and end date (specifying the + Here's a period expression with a start and end date (specifying the first quarter of 2009): -p "from 2009/1/1 to 2009/4/1" - Several keywords like "from" and "to" are supported for readability; - these are optional. "to" can also be written as ".." or "-". The - spaces are also optional, as long as you don't run two dates together. + Several keywords like "from" and "to" are supported for readability; + these are optional. "to" can also be written as ".." or "-". The + spaces are also optional, as long as you don't run two dates together. So the following are equivalent to the above: -p "2009/1/1 2009/4/1" -p2009/1/1to2009/4/1 -p2009/1/1..2009/4/1 - Dates are smart dates, so if the current year is 2009, these are also + Dates are smart dates, so if the current year is 2009, these are also equivalent to the above: -p "1/1 4/1" @@ -4555,28 +4673,28 @@ Time periods -p "from 2009/1/1" everything after january 1, 2009 - -p "since 2009/1" the same, since is a syn- + -p "since 2009/1" the same, since is a syn- onym -p "from 2009" the same - -p "to 2009" everything before january + -p "to 2009" everything before january 1, 2009 You can also specify a period by writing a single partial or full date: -p "2009" the year 2009; equivalent to "2009/1/1 to 2010/1/1" - -p "2009/1" the month of january 2009; equivalent to "2009/1/1 to + -p "2009/1" the month of january 2009; equivalent to "2009/1/1 to 2009/2/1" - -p "2009/1/1" the first day of 2009; equivalent to "2009/1/1 to + -p "2009/1/1" the first day of 2009; equivalent to "2009/1/1 to 2009/1/2" or by using the "Q" quarter-year syntax (case insensitive): - -p "2009Q1" first quarter of 2009, equivalent to "2009/1/1 to + -p "2009Q1" first quarter of 2009, equivalent to "2009/1/1 to 2009/4/1" -p "q4" fourth quarter of the current year Period expressions with a report interval - A period expression can also begin with a report interval, separated + A period expression can also begin with a report interval, separated from the start/end dates (if any) by a space or the word in: -p "weekly from 2009/1/1 to 2009/4/1" @@ -4599,10 +4717,10 @@ Time periods Weekly on a custom day: - o every Nth day of week (th, nd, rd, or st are all accepted after the + o every Nth day of week (th, nd, rd, or st are all accepted after the number) - o every WEEKDAYNAME (full or three-letter english weekday name, case + o every WEEKDAYNAME (full or three-letter english weekday name, case insensitive) Monthly on a custom day: @@ -4615,7 +4733,7 @@ Time periods o every MM/DD [of year] (month number and day of month number) - o every MONTHNAME DDth [of year] (full or three-letter english month + o every MONTHNAME DDth [of year] (full or three-letter english month name, case insensitive, and day of month number) o every DDth MONTHNAME [of year] (equivalent to the above) @@ -4628,21 +4746,21 @@ Time periods 2009/03" -p "every 2nd day of week" periods will go from Tue to Tue -p "every Tue" same - -p "every 15th day" period boundaries will be on 15th of each + -p "every 15th day" period boundaries will be on 15th of each month - -p "every 2nd Monday" period boundaries will be on second Monday + -p "every 2nd Monday" period boundaries will be on second Monday of each month - -p "every 11/05" yearly periods with boundaries on 5th of + -p "every 11/05" yearly periods with boundaries on 5th of November -p "every 5th November" same -p "every Nov 5th" same - Show historical balances at end of the 15th day of each month (N is an + Show historical balances at end of the 15th day of each month (N is an end date, exclusive as always): $ hledger balance -H -p "every 16th day" - Group postings from the start of wednesday to end of the following + Group postings from the start of wednesday to end of the following tuesday (N is both (inclusive) start date and (exclusive) end date): $ hledger register checking -p "every 3rd day of week" @@ -4653,10 +4771,10 @@ Time periods o every WEEKDAYNAME,WEEKDAYNAME,... (full or three-letter english week- day names, case insensitive) - Also, weekday and weekendday are shorthand for mon,tue,wed,thu,fri and + Also, weekday and weekendday are shorthand for mon,tue,wed,thu,fri and sat,sun. - This is mainly intended for use with --forecast, to generate periodic + This is mainly intended for use with --forecast, to generate periodic transactions on arbitrary days of the week. It may be less useful with -p, since it divides each week into subperiods of unequal length, which is unusual. (Related: #1632) @@ -4665,35 +4783,35 @@ Time periods -p "every dates will be Mon, Wed, Fri; periods will be mon,wed,fri" Mon-Tue, Wed-Thu, Fri-Sun - -p "every weekday" dates will be Mon, Tue, Wed, Thu, Fri; periods will + -p "every weekday" dates will be Mon, Tue, Wed, Thu, Fri; periods will be Mon, Tue, Wed, Thu, Fri-Sun -p "every weekend- dates will be Sat, Sun; periods will be Sat, Sun-Fri day" Depth - With the --depth NUM option (short form: -NUM), reports will show ac- - counts only to the specified depth, hiding deeper subaccounts. Use - this when you want a summary with less detail. This flag has the same + With the --depth NUM option (short form: -NUM), reports will show ac- + counts only to the specified depth, hiding deeper subaccounts. Use + this when you want a summary with less detail. This flag has the same effect as a depth: query argument: depth:2, --depth=2 or -2 are equiva- lent. Queries One of hledger's strengths is being able to quickly report on a precise - subset of your data. Most hledger commands accept query arguments, to + subset of your data. Most hledger commands accept query arguments, to restrict their scope. Multiple query terms can be provided to build up a more complex query. - o By default, a query term is interpreted as a case-insensitive sub- + o By default, a query term is interpreted as a case-insensitive sub- string pattern for matching account names: car:fuel dining groceries - o Patterns containing spaces or other special characters must be en- + o Patterns containing spaces or other special characters must be en- closed in single or double quotes: 'personal care' - o These patterns are actually regular expressions, so you can add reg- - exp metacharacters for more precision (see "Regular expressions" + o These patterns are actually regular expressions, so you can add reg- + exp metacharacters for more precision (see "Regular expressions" above for details): '^expenses\b' @@ -4714,15 +4832,15 @@ Queries not:status:'*' not:desc:'opening|closing' not:cur:USD - o Terms with different types are AND-ed, terms with the same type are - OR-ed (mostly; see "Combining query terms" below). The following + o Terms with different types are AND-ed, terms with the same type are + OR-ed (mostly; see "Combining query terms" below). The following query: date:2022 desc:amazon desc:amzn is interpreted as: - date is in 2022 AND ( transaction description contains "amazon" OR + date is in 2022 AND ( transaction description contains "amazon" OR "amzn" ) Query types @@ -4730,15 +4848,15 @@ Queries prefixed with not: to convert them into a negative match. acct:REGEX or REGEX - Match account names containing this case insensitive regular expres- + Match account names containing this case insensitive regular expres- sion. This is the default query type, so we usually don't bother writ- ing the "acct:" prefix. amt:N, amt:N, amt:>=N - Match postings with a single-commodity amount equal to, less than, or - greater than N. (Postings with multi-commodity amounts are not tested + Match postings with a single-commodity amount equal to, less than, or + greater than N. (Postings with multi-commodity amounts are not tested and will always match.) The comparison has two modes: if N is preceded - by a + or - sign (or is 0), the two signed numbers are compared. Oth- + by a + or - sign (or is 0), the two signed numbers are compared. Oth- erwise, the absolute magnitudes are compared, ignoring sign. code:REGEX @@ -4746,10 +4864,10 @@ Queries cur:REGEX Match postings or transactions including any amounts whose cur- - rency/commodity symbol is fully matched by REGEX. (For a partial - match, use .*REGEX.*). Note, to match special characters which are - regex-significant, you need to escape them with \. And for characters - which are significant to your shell you may need one more level of es- + rency/commodity symbol is fully matched by REGEX. (For a partial + match, use .*REGEX.*). Note, to match special characters which are + regex-significant, you need to escape them with \. And for characters + which are significant to your shell you may need one more level of es- caping. So eg to match the dollar sign: hledger print cur:\\$. @@ -4757,21 +4875,21 @@ Queries Match transaction descriptions. date:PERIODEXPR - Match dates (or with the --date2 flag, secondary dates) within the + Match dates (or with the --date2 flag, secondary dates) within the specified period. PERIODEXPR is a period expression with no report in- terval. Examples: date:2016, date:thismonth, date:2/1-2/15, date:2021-07-27..nextquarter. date2:PERIODEXPR - Match secondary dates within the specified period (independent of the + Match secondary dates within the specified period (independent of the --date2 flag). depth:N - Match (or display, depending on command) accounts at or above this + Match (or display, depending on command) accounts at or above this depth. expr:"TERM AND NOT (TERM OR TERM)" (eg) - Match with a boolean combination of queries (which must be enclosed in + Match with a boolean combination of queries (which must be enclosed in quotes). See Combining query terms below. note:REGEX @@ -4779,7 +4897,7 @@ Queries whole description if there's no |). payee:REGEX - Match transaction payee/payer names (the part of the description left + Match transaction payee/payer names (the part of the description left of |, or the whole description if there's no |). real:, real:0 @@ -4789,11 +4907,11 @@ Queries Match unmarked, pending, or cleared transactions respectively. type:TYPECODES - Match by account type (see Declaring accounts > Account types). TYPE- - CODES is one or more of the single-letter account type codes ALERXCV, + Match by account type (see Declaring accounts > Account types). TYPE- + CODES is one or more of the single-letter account type codes ALERXCV, case insensitive. Note type:A and type:E will also match their respec- - tive subtypes C (Cash) and V (Conversion). Certain kinds of account - alias can disrupt account types, see Rewriting accounts > Aliases and + tive subtypes C (Cash) and V (Conversion). Certain kinds of account + alias can disrupt account types, see Rewriting accounts > Aliases and account types. tag:REGEX[=REGEX] @@ -4809,11 +4927,11 @@ Queries o Transactions also acquire the tags of their postings. (inacct:ACCTNAME - A special query term used automatically in hledger-web only: tells + A special query term used automatically in hledger-web only: tells hledger-web to show the transaction register for an account.) Combining query terms - When given multiple space-separated query terms, most commands select + When given multiple space-separated query terms, most commands select things which match: o any of the description terms AND @@ -4834,13 +4952,11 @@ Queries o match all the other terms. - We also support more complex boolean queries with the 'expr:' prefix. - This allows one to combine queries using one of three operators: AND, - OR, and NOT, where NOT is different syntax for 'not:'. - - Examples of such queries are: + We also support more complex boolean queries with the expr: prefix. + This allows one to combine queries using AND, OR, and NOT. (NOT is + equivalent to the not: prefix.) Some examples: - o Match transactions with 'cool' in the description AND with the 'A' + o Match transactions with 'cool' in the description AND with the 'A' tag expr:"desc:cool AND tag:A" @@ -4850,34 +4966,26 @@ Queries expr:"NOT expenses:food OR tag:A" - o Match transactions NOT involving the 'expenses:food' account OR with - the 'A' tag AND involving the 'expenses:drink' account. (the AND is + o Match transactions NOT involving the 'expenses:food' account OR with + the 'A' tag AND involving the 'expenses:drink' account. (the AND is implicitly added by space-separation, following the rules above) expr:"expenses:food OR (tag:A expenses:drink)" Queries and command options - Some queries can also be expressed as command-line options: depth:2 is + Some queries can also be expressed as command-line options: depth:2 is equivalent to --depth 2, date:2023 is equivalent to -p 2023, etc. When - you mix command options and query arguments, generally the resulting + you mix command options and query arguments, generally the resulting query is their intersection. + Queries and account aliases + When account names are rewritten with --alias or alias, acct: will + match either the old or the new account name. + Queries and valuation When amounts are converted to other commodities in cost or value re- ports, cur: and amt: match the old commodity symbol and the old amount - quantity, not the new ones (except in hledger 1.22.0 where it's re- - versed, see #1625). - - Querying with account aliases - When account names are rewritten with --alias or alias, note that acct: - will match either the old or the new account name. - - Querying with cost or value - When amounts are converted to other commodities in cost or value re- - ports, note that cur: matches the new commodity symbol, and not the old - one, and amt: matches the new quantity, and not the old one. Note: - this changed in hledger 1.22, previously it was the reverse, see the - discussion at #1625. + quantity, not the new ones. (Except in hledger 1.22, #1625.) Pivoting Normally, hledger groups and sums amounts within each account. The @@ -5529,36 +5637,6 @@ Value reporting Amounts for which no valuation commodity can be found are not con- verted. - Simple valuation examples - Here are some quick examples of -V: - - ; one euro is worth this many dollars from nov 1 - P 2016/11/01 $1.10 - - ; purchase some euros on nov 3 - 2016/11/3 - assets:euros 100 - assets:checking - - ; the euro is worth fewer dollars by dec 21 - P 2016/12/21 $1.03 - - How many euros do I have ? - - $ hledger -f t.j bal -N euros - 100 assets:euros - - What are they worth at end of nov 3 ? - - $ 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, - defaults to today) - - $ hledger -f t.j bal -N euros -V - $103.00 assets:euros - --value: Flexible valuation -V and -X are special cases of the more general --value option: @@ -5573,30 +5651,59 @@ Value reporting The TYPE part selects cost or value and valuation date: --value=then - Convert amounts to their value in the default valuation commod- + Convert amounts to their value in the default valuation commod- ity, using market prices on each posting's date. --value=end - Convert amounts to their value in the default valuation commod- - ity, using market prices on the last day of the report period - (or if unspecified, the journal's end date); or in multiperiod + Convert amounts to their value in the default valuation commod- + ity, using market prices on the last day of the report period + (or if unspecified, the journal's end date); or in multiperiod reports, market prices on the last day of each subperiod. --value=now - Convert amounts to their value in the default valuation commod- - ity using current market prices (as of when report is gener- + Convert amounts to their value in the default valuation commod- + ity using current market prices (as of when report is gener- ated). --value=YYYY-MM-DD - Convert amounts to their value in the default valuation commod- + Convert amounts to their value in the default valuation commod- ity using market prices on this date. To select a different valuation commodity, add the optional ,COMM part: - a comma, then the target commodity's symbol. Eg: --value=now,EUR. + a comma, then the target commodity's symbol. Eg: --value=now,EUR. hledger will do its best to convert amounts to this commodity, deducing market prices as described above. - More valuation examples + Valuation examples + Here are some quick examples of -V: + + ; one euro is worth this many dollars from nov 1 + P 2016/11/01 $1.10 + + ; purchase some euros on nov 3 + 2016/11/3 + assets:euros 100 + assets:checking + + ; the euro is worth fewer dollars by dec 21 + P 2016/12/21 $1.03 + + How many euros do I have ? + + $ hledger -f t.j bal -N euros + 100 assets:euros + + What are they worth at end of nov 3 ? + + $ 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, + defaults to today) + + $ hledger -f t.j bal -N euros -V + $103.00 assets:euros + Here are some examples showing the effect of --value, as seen with print: @@ -5674,7 +5781,7 @@ Value reporting Interaction of valuation and queries When matching postings based on queries in the presence of valuation, - the following happens. + the following happens: 1. The query is separated into two parts: @@ -5690,21 +5797,51 @@ Value reporting 4. The postings are matched to the other parts of the query based on post-valued amounts. - See: 1625 + Related: #1625 Effect of valuation on reports Here is a reference for how valuation is supposed to affect each part - of hledger's reports (and a glossary). (It's wide, you'll have to - scroll sideways.) It may be useful when troubleshooting. If you find - problems, please report them, ideally with a reproducible example. Re- - lated: #329, #1083. + of hledger's reports. (It's wide, you may need to scroll sideways.) + It may be useful when troubleshooting. If you find problems, please + report them, ideally with a reproducible example. Related: #329, + #1083. + + First, a quick glossary: + + cost calculated using price(s) recorded in the transaction(s). + + value market value using available market price declarations, or the + unchanged amount if no conversion rate can be found. + + report start + the first day of the report period specified with -b or -p or + date:, otherwise today. + + report or journal start + the first day of the report period specified with -b or -p or + date:, otherwise the earliest transaction date in the journal, + otherwise today. + + report end + the last day of the report period specified with -e or -p or + date:, otherwise today. + + report or journal end + the last day of the report period specified with -e or -p or + date:, otherwise the latest transaction date in the journal, + otherwise today. + + report interval + a flag (-D/-W/-M/-Q/-Y) or period expression that activates the + report's multi-period mode (whether showing one or many subperi- + ods). Report -B, --cost -V, -X --value=then --value=end --value=DATE, type --value=now -------------------------------------------------------------------------------------------- print - posting cost value at re- value at posting value at re- value at - amounts port end or date port or DATE/today + posting cost value at re- value at posting value at re- value at + amounts port end or date port or DATE/today today journal end balance unchanged unchanged unchanged unchanged unchanged asser- @@ -5720,7 +5857,7 @@ Value reporting (-H) with port or posting was made port or report journal journal interval start start - posting cost value at re- value at posting value at re- value at + posting cost value at re- value at posting value at re- value at amounts port or date port or DATE/today journal end journal end summary summarised value at pe- sum of postings value at pe- value at @@ -5736,8 +5873,8 @@ Value reporting balance (bs, bse, cf, is) - balance sums of value at re- value at posting value at re- value at - changes costs port end or date port or DATE/today of + balance sums of value at re- value at posting value at re- value at + changes costs port end or date port or DATE/today of today of journal end sums of post- sums of of sums of ings postings postings @@ -5745,7 +5882,7 @@ Value reporting amounts changes changes changes ances changes (--bud- get) - grand to- sum of dis- sum of dis- sum of displayed sum of dis- sum of dis- + grand to- sum of dis- sum of dis- sum of displayed sum of dis- sum of dis- tal played val- played val- valued played val- played values ues ues ues @@ -5771,7 +5908,7 @@ Value reporting end bal- sums of same as sums of values of period end value at ances costs of --value=end postings from be- balances, DATE/today of (bal -H, postings fore period start valued at sums of post- - is --H, from before to period end at period ends ings + is --H, from before to period end at period ends ings bs, cf) report start respective post- to period ing dates end @@ -5780,10 +5917,10 @@ Value reporting (--bud- balances balances ances balances get) row to- sums, aver- sums, aver- sums, averages of sums, aver- sums, aver- - tals, row ages of dis- ages of dis- displayed values ages of dis- ages of dis- + tals, row ages of dis- ages of dis- displayed values ages of dis- ages of dis- averages played val- played val- played val- played values (-T, -A) ues ues ues - column sums of dis- sums of dis- sums of displayed sums of dis- sums of dis- + column sums of dis- sums of dis- sums of displayed sums of dis- sums of dis- totals played val- played val- values played val- played values ues ues ues grand to- sum, average sum, average sum, average of sum, average sum, average @@ -5795,36 +5932,6 @@ Value reporting --cumulative is omitted to save space, it works like -H but with a zero starting balance. - Glossary: - - cost calculated using price(s) recorded in the transaction(s). - - value market value using available market price declarations, or the - unchanged amount if no conversion rate can be found. - - report start - the first day of the report period specified with -b or -p or - date:, otherwise today. - - report or journal start - the first day of the report period specified with -b or -p or - date:, otherwise the earliest transaction date in the journal, - otherwise today. - - report end - the last day of the report period specified with -e or -p or - date:, otherwise today. - - report or journal end - the last day of the report period specified with -e or -p or - date:, otherwise the latest transaction date in the journal, - otherwise today. - - report interval - a flag (-D/-W/-M/-Q/-Y) or period expression that activates the - report's multi-period mode (whether showing one or many subperi- - ods). - PART 4: COMMANDS Commands overview Here are the built-in commands: @@ -5863,7 +5970,7 @@ PART 4: COMMANDS o print - show transactions or export journal data - o register (reg) - show postings in one or more accounts & running to- + o register (reg) - show postings in one or more accounts & running to- tal o roi - show return on investments @@ -5900,7 +6007,7 @@ PART 4: COMMANDS ADD-ONS And here are some typical add-on commands. Some of these are installed - by the hledger-install script. If installed, they will appear in + by the hledger-install script. If installed, they will appear in hledger's commands list: o ui - run hledger's terminal UI @@ -5913,7 +6020,7 @@ PART 4: COMMANDS o stockquotes - download market prices from AlphaVantage - o Scripts and add-ons - check-fancyassertions, edit, fifo, git, move, + o Scripts and add-ons - check-fancyassertions, edit, fifo, git, move, pijul, plot, and more.. Next, each command is described in detail, in alphabetical order. @@ -5921,38 +6028,38 @@ PART 4: COMMANDS accounts Show account names. - This command lists account names. By default it shows all known ac- - counts, either used in transactions or declared with account direc- + This command lists account names. By default it shows all known ac- + counts, either used in transactions or declared with account direc- tives. With query arguments, only matched account names and account names ref- erenced by matched postings are shown. - Or it can show just the used accounts (--used/-u), the declared ac- - counts (--declared/-d), the accounts declared but not used (--unused), + Or it can show just the used accounts (--used/-u), the declared ac- + counts (--declared/-d), the accounts declared but not used (--unused), the accounts used but not declared (--undeclared), or the first account matched by an account name pattern, if any (--find). - It shows a flat list by default. With --tree, it uses indentation to - show the account hierarchy. In flat mode you can add --drop N to omit - the first few account name components. Account names can be + It shows a flat list by default. With --tree, it uses indentation to + show the account hierarchy. In flat mode you can add --drop N to omit + the first few account name components. Account names can be depth-clipped with depth:N or --depth N or -N. - With --types, it also shows each account's type, if it's known. (See + With --types, it also shows each account's type, if it's known. (See Declaring accounts > Account types.) - With --positions, it also shows the file and line number of each ac- - count's declaration, if any, and the account's overall declaration or- + With --positions, it also shows the file and line number of each ac- + count's declaration, if any, and the account's overall declaration or- der; these may be useful when troubleshooting account display order. - With --directives, it adds the account keyword, showing valid account + With --directives, it adds the account keyword, showing valid account directives which can be pasted into a journal file. This is useful to- - gether with --undeclared when updating your account declarations to + gether with --undeclared when updating your account declarations to satisfy hledger check accounts. - The --find flag can be used to look up a single account name, in the - same way that the aregister command does. It returns the alphanumeri- - cally-first matched account name, or if none can be found, it fails + The --find flag can be used to look up a single account name, in the + same way that the aregister command does. It returns the alphanumeri- + cally-first matched account name, or if none can be found, it fails with a non-zero exit code. Examples: @@ -5973,8 +6080,8 @@ PART 4: COMMANDS 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: @@ -5986,36 +6093,36 @@ PART 4: COMMANDS 2008-10-01 ** add - Prompt for transactions and add them to the journal. Any arguments + Prompt for transactions and add them to the journal. Any arguments will be used as default inputs for the first N prompts. - Many hledger users edit their journals directly with a text editor, or - generate them from CSV. For more interactive data entry, there is the - add command, which prompts interactively on the console for new trans- - actions, and appends them to the main journal file (which should be in - journal format). Existing transactions are not changed. This is one - of the few hledger commands that writes to the journal file (see also + Many hledger users edit their journals directly with a text editor, or + generate them from CSV. For more interactive data entry, there is the + add command, which prompts interactively on the console for new trans- + actions, and appends them to the main journal file (which should be in + journal format). Existing transactions are not changed. This is one + of the few hledger commands that writes to the journal file (see also import). To use it, just run hledger add and follow the prompts. You can add as - many transactions as you like; when you are finished, enter . or press + many transactions as you like; when you are finished, enter . or press control-d or control-c to exit. Features: - o add tries to provide useful defaults, using the most similar (by de- - scription) recent transaction (filtered by the query, if any) as a + o add tries to provide useful defaults, using the most similar (by de- + scription) recent transaction (filtered by the query, if any) as a template. o You can also set the initial defaults with command line arguments. o Readline-style edit keys can be used during data entry. - o The tab key will auto-complete whenever possible - accounts, pay- - ees/descriptions, dates (yesterday, today, tomorrow). If the input + o The tab key will auto-complete whenever possible - accounts, pay- + ees/descriptions, dates (yesterday, today, tomorrow). If the input area is empty, it will insert the default value. - o If the journal defines a default commodity, it will be added to any + 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. @@ -6024,7 +6131,7 @@ PART 4: COMMANDS o If you make a mistake, enter < at any prompt to go one step backward. - o Input prompts are displayed in a different colour when the terminal + o Input prompts are displayed in a different colour when the terminal supports it. Example (see https://hledger.org/add.html for a detailed tutorial): @@ -6055,70 +6162,70 @@ PART 4: COMMANDS Date [2015/05/22]: $ If you enter a number with no commodity symbol, and you have declared a - default commodity with a D directive, you might expect add to add this + default commodity with a D directive, you might expect add to add this symbol for you. It does not do this; we assume that if you are using a - D directive you prefer not to see the commodity symbol repeated on + D directive you prefer not to see the commodity symbol repeated on amounts in the journal. aregister (areg) - Show the transactions and running historical balance of a single ac- + Show the transactions and running historical balance of a single ac- count, with each transaction displayed as one line. aregister shows the overall transactions affecting a particular account - (and any subaccounts). Each report line represents one transaction in + (and any subaccounts). Each report line represents one transaction in this account. Transactions before the report start date are always in- cluded in the running balance (--historical mode is always on). - This is a more "real world", bank-like view than the register command - (which shows individual postings, possibly from multiple accounts, not + This is a more "real world", bank-like view than the register command + (which shows individual postings, possibly from multiple accounts, not necessarily in historical mode). As a quick rule of thumb: - use areg- ister for reviewing and reconciling real-world asset/liability accounts - use register for reviewing detailed revenues/expenses. - aregister requires one argument: the account to report on. You can - write either the full account name, or a case-insensitive regular ex- + aregister requires one argument: the account to report on. You can + write either the full account name, or a case-insensitive regular ex- pression which will select the alphabetically first matched account. When there are multiple matches, the alphabetically-first choice can be - surprising; eg if you have assets:per:checking 1 and assets:biz:check- - ing 2 accounts, hledger areg checking would select assets:biz:checking - 2. It's just a convenience to save typing, so if in doubt, write the + surprising; eg if you have assets:per:checking 1 and assets:biz:check- + ing 2 accounts, hledger areg checking would select assets:biz:checking + 2. It's just a convenience to save typing, so if in doubt, write the full account name, or a distinctive substring that matches uniquely. - Transactions involving subaccounts of this account will also be shown. - aregister ignores depth limits, so its final total will always match a + Transactions involving subaccounts of this account will also be shown. + aregister ignores depth limits, so its final total will always match a balance report with similar arguments. - Any additional arguments form a query which will filter the transac- + Any additional arguments form a query which will filter the transac- tions shown. Note some queries will disturb the running balance, caus- ing it to be different from the account's real-world running balance. - An example: this shows the transactions and historical running balance + An example: this shows the transactions and historical running balance during july, in the first account whose name contains "checking": $ hledger areg checking date:jul Each aregister line item shows: - o the transaction's date (or the relevant posting's date if different, + o the transaction's date (or the relevant posting's date if different, see below) - o the names of all the other account(s) involved in this transaction + o the names of all the other account(s) involved in this transaction (probably abbreviated) o the total change to this account's balance from this transaction o the account's historical running balance after this transaction. - Transactions making a net change of zero are not shown by default; add + Transactions making a net change of zero are not shown by default; add the -E/--empty flag to show them. - For performance reasons, column widths are chosen based on the first - 1000 lines; this means unusually wide values in later lines can cause - visual discontinuities as column widths are adjusted. If you want to - ensure perfect alignment, at the cost of more time and memory, use the + For performance reasons, column widths are chosen based on the first + 1000 lines; this means unusually wide values in later lines can cause + visual discontinuities as column widths are adjusted. If you want to + ensure perfect alignment, at the cost of more time and memory, use the --align-all flag. This command also supports the output destination and output format op- @@ -6126,13 +6233,13 @@ PART 4: COMMANDS and json. aregister and posting dates - aregister always shows one line (and date and amount) per transaction. - But sometimes transactions have postings with different dates. Also, - not all of a transaction's postings may be within the report period. + aregister always shows one line (and date and amount) per transaction. + But sometimes transactions have postings with different dates. Also, + not all of a transaction's postings may be within the report period. To resolve this, aregister shows the earliest of the transaction's date and posting dates that is in-period, and the sum of the in-period post- - ings. In other words it will show a combined line item with just the - earliest date, and the running balance will (temporarily, until the + ings. In other words it will show a combined line item with just the + earliest date, and the running balance will (temporarily, until the transaction's last posting) be inaccurate. Use register -H if you need to see the individual postings. @@ -6145,19 +6252,19 @@ PART 4: COMMANDS Show accounts and their balances. - balance is one of hledger's oldest and most versatile commands, for - listing account balances, balance changes, values, value changes and + balance is one of hledger's oldest and most versatile commands, for + listing account balances, balance changes, values, value changes and more, during one time period or many. Generally it shows a table, with rows representing accounts, and columns representing periods. - Note there are some higher-level variants of the balance command with - convenient defaults, which can be simpler to use: balancesheet, bal- + Note there are some higher-level variants of the balance command with + convenient defaults, which can be simpler to use: balancesheet, bal- ancesheetequity, cashflow and incomestatement. When you need more con- trol, then use balance. balance features - Here's a quick overview of the balance command's features, followed by - more detailed descriptions and examples. Many of these work with the + Here's a quick overview of the balance command's features, followed by + more detailed descriptions and examples. Many of these work with the higher-level commands as well. balance can show.. @@ -6180,6 +6287,8 @@ PART 4: COMMANDS o or unrealised capital gain/loss (--gain) + o or balance changes from sibling postings (--related/-r) + o or postings count (--count) ..in.. @@ -6210,7 +6319,7 @@ PART 4: COMMANDS ..with.. - o totals (-T), averages (-A), percentages (-%), inverted sign (--in- + o totals (-T), averages (-A), percentages (-%), inverted sign (--in- vert) o rows and columns swapped (--transpose) @@ -6223,12 +6332,9 @@ PART 4: COMMANDS This command supports the output destination and output format options, with output formats txt, csv, tsv (Added in 1.32), json, and (multi-pe- - riod reports only:) html. In txt output in a colour-supporting termi- + riod reports only:) html. In txt output in a colour-supporting termi- nal, negative amounts are shown in red. - The --related/-r flag shows the balance of the other postings in the - transactions of the postings which would normally be shown. - Simple balance report With no arguments, balance shows a list of all accounts and their change of balance - ie, the sum of posting amounts, both inflows and @@ -6502,7 +6608,11 @@ PART 4: COMMANDS o Hide the totals row with -N/--no-total - o Convert to a single currency with -V + o Filter to a single currency with cur: + + o Convert to a single currency with -V [--infer-market-price] + + o Use a more compact layout like --layout=bare o Maximize the terminal window @@ -6579,13 +6689,13 @@ PART 4: COMMANDS o --count : show the count of postings Accumulation type - How amounts should accumulate across report periods. Another way to - say it: which time period's postings should contribute to each cell's - calculation. It is one of: + How amounts should accumulate across a report's subperiods/columns. + Another way to say it: which time period's postings should contribute + to each cell's calculation. It is one of: o --change : calculate with postings from column start to column end, ie "just this column". Typically used to see revenues/expenses. - (default for balance, incomestatement) + (default for balance, cashflow, incomestatement) o --cumulative : calculate with postings from report start to column end, ie "previous columns plus this column". Typically used to show @@ -6595,7 +6705,7 @@ PART 4: COMMANDS umn end, ie "all postings from before report start date until this column's end". Typically used to see historical end balances of as- sets/liabilities/equity. (default for balancesheet, balancesheete- - quity, cashflow) + quity) Valuation type Which kind of value or cost conversion should be applied, if any, be- @@ -6822,43 +6932,38 @@ PART 4: COMMANDS fined in your journal. Budgeting vs forecasting - --budget and --forecast both use the periodic transaction rules in the + --forecast and --budget both use the periodic transaction rules in the journal to generate temporary transactions for reporting purposes. However they are separate features - though you can use both at the same time if you want. Here are some differences between them: - 1. --budget is a command-specific option; it selects the budget report. - - --forecast is a general option; forecasting works with all reports. - - 2. --budget uses all periodic rules; --budget=DESCPAT uses just the - rules matched by DESCPAT. - - --forecast uses all periodic rules. - - 3. --budget's budget goal transactions are invisible, except that they - produce goal amounts. - - --forecast's forecast transactions are visible, and appear in re- - ports. - - 4. --budget generates budget goal transactions throughout the report - period, optionally restricted by periods specified in the periodic - transaction rules. - - --forecast generates forecast transactions from after the last reg- - ular transaction, to the end of the report period; while --fore- - cast=PERIODEXPR generates them throughout the specified period; - both optionally restricted by periods specified in the periodic - transaction rules. + --forecast --budget + -------------------------------------------------------------------------- + is a general option; it enables fore- is a balance command option; it + casting with all reports selects the balance report's + budget mode + generates visible transactions which generates invisible transactions + appear in reports which produce goal amounts + generates forecast transactions from generates budget goal transac- + after the last regular transaction, to tions throughout the report pe- + the end of the report period; or with riod, optionally restricted by + an argument --forecast=PERIODEXPR gen- periods specified in the peri- + erates them throughout the specified odic transaction rules + period, both optionally restricted by + periods specified in the periodic + transaction rules + uses all periodic rules uses all periodic rules; or with + an argument --budget=DESCPAT + uses just the rules matched by + DESCPAT Balance report layout - The --layout option affects how balance reports show multi-commodity - amounts and commodity symbols, which can improve readability. It can + The --layout option affects how balance reports show multi-commodity + amounts and commodity symbols, which can improve readability. It can also normalise the data for easy consumption by other programs. It has four possible values: - o --layout=wide[,WIDTH]: commodities are shown on a single line, op- + o --layout=wide[,WIDTH]: commodities are shown on a single line, op- tionally elided to WIDTH o --layout=tall: each commodity is shown on a separate line @@ -6866,11 +6971,11 @@ PART 4: COMMANDS o --layout=bare: commodity symbols are in their own column, amounts are bare numbers - o --layout=tidy: data is normalised to easily-consumed "tidy" form, + o --layout=tidy: data is normalised to easily-consumed "tidy" form, with one row per data value - Here are the --layout modes supported by each output format; note only - CSV output supports all of them: + Here are the --layout modes supported by each output format Only CSV + output supports all of them: - txt csv html json sql ------------------------------------- @@ -6881,137 +6986,140 @@ PART 4: COMMANDS Examples: - o Wide layout. With many commodities, reports can be very wide: - - $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=wide - Balance changes in 2012-01-01..2014-12-31: - - || 2012 2013 2014 Total - ==================++==================================================================================================================================================================================================================== - Assets:US:ETrade || 10.00 ITOT, 337.18 USD, 12.00 VEA, 106.00 VHT 70.00 GLD, 18.00 ITOT, -98.12 USD, 10.00 VEA, 18.00 VHT -11.00 ITOT, 4881.44 USD, 14.00 VEA, 170.00 VHT 70.00 GLD, 17.00 ITOT, 5120.50 USD, 36.00 VEA, 294.00 VHT - ------------------++-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- - || 10.00 ITOT, 337.18 USD, 12.00 VEA, 106.00 VHT 70.00 GLD, 18.00 ITOT, -98.12 USD, 10.00 VEA, 18.00 VHT -11.00 ITOT, 4881.44 USD, 14.00 VEA, 170.00 VHT 70.00 GLD, 17.00 ITOT, 5120.50 USD, 36.00 VEA, 294.00 VHT - - o Limited wide layout. A width limit reduces the width, but some com- - modities will be hidden: - - $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=wide,32 - Balance changes in 2012-01-01..2014-12-31: - - || 2012 2013 2014 Total - ==================++=========================================================================================================================== - Assets:US:ETrade || 10.00 ITOT, 337.18 USD, 2 more.. 70.00 GLD, 18.00 ITOT, 3 more.. -11.00 ITOT, 3 more.. 70.00 GLD, 17.00 ITOT, 3 more.. - ------------------++--------------------------------------------------------------------------------------------------------------------------- - || 10.00 ITOT, 337.18 USD, 2 more.. 70.00 GLD, 18.00 ITOT, 3 more.. -11.00 ITOT, 3 more.. 70.00 GLD, 17.00 ITOT, 3 more.. - - o Tall layout. Each commodity gets a new line (may be different in - each column), and account names are repeated: - - $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=tall - Balance changes in 2012-01-01..2014-12-31: - - || 2012 2013 2014 Total - ==================++================================================== - Assets:US:ETrade || 10.00 ITOT 70.00 GLD -11.00 ITOT 70.00 GLD - Assets:US:ETrade || 337.18 USD 18.00 ITOT 4881.44 USD 17.00 ITOT - Assets:US:ETrade || 12.00 VEA -98.12 USD 14.00 VEA 5120.50 USD - Assets:US:ETrade || 106.00 VHT 10.00 VEA 170.00 VHT 36.00 VEA - Assets:US:ETrade || 18.00 VHT 294.00 VHT - ------------------++-------------------------------------------------- - || 10.00 ITOT 70.00 GLD -11.00 ITOT 70.00 GLD - || 337.18 USD 18.00 ITOT 4881.44 USD 17.00 ITOT - || 12.00 VEA -98.12 USD 14.00 VEA 5120.50 USD - || 106.00 VHT 10.00 VEA 170.00 VHT 36.00 VEA - || 18.00 VHT 294.00 VHT - - o Bare layout. Commodity symbols are kept in one column, each commod- - ity gets its own report row, account names are repeated: - - $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=bare - Balance changes in 2012-01-01..2014-12-31: - - || Commodity 2012 2013 2014 Total - ==================++============================================= - Assets:US:ETrade || GLD 0 70.00 0 70.00 - Assets:US:ETrade || ITOT 10.00 18.00 -11.00 17.00 - Assets:US:ETrade || USD 337.18 -98.12 4881.44 5120.50 - Assets:US:ETrade || VEA 12.00 10.00 14.00 36.00 - Assets:US:ETrade || VHT 106.00 18.00 170.00 294.00 - ------------------++--------------------------------------------- - || GLD 0 70.00 0 70.00 - || ITOT 10.00 18.00 -11.00 17.00 - || USD 337.18 -98.12 4881.44 5120.50 - || VEA 12.00 10.00 14.00 36.00 - || VHT 106.00 18.00 170.00 294.00 - - o Bare layout also affects CSV output, which is useful for producing - data that is easier to consume, eg for making charts: - - $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -O csv --layout=bare - "account","commodity","balance" - "Assets:US:ETrade","GLD","70.00" - "Assets:US:ETrade","ITOT","17.00" - "Assets:US:ETrade","USD","5120.50" - "Assets:US:ETrade","VEA","36.00" - "Assets:US:ETrade","VHT","294.00" - "total","GLD","70.00" - "total","ITOT","17.00" - "total","USD","5120.50" - "total","VEA","36.00" - "total","VHT","294.00" - - o Note: bare layout will sometimes display an extra row for the no-sym- - bol commodity, because of zero amounts (hledger treats zeroes as com- - modity-less, usually). This can break hledger-bar confusingly - (workaround: add a cur: query to exclude the no-symbol row). - - o Tidy layout produces normalised "tidy data", where every variable has - its own column and each row represents a single data point. See - https://cran.r-project.org/web/packages/tidyr/vi- - gnettes/tidy-data.html for more. This is the easiest kind of data - for other software to consume. Here's how it looks: - - $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -Y -O csv --layout=tidy - "account","period","start_date","end_date","commodity","value" - "Assets:US:ETrade","2012","2012-01-01","2012-12-31","GLD","0" - "Assets:US:ETrade","2012","2012-01-01","2012-12-31","ITOT","10.00" - "Assets:US:ETrade","2012","2012-01-01","2012-12-31","USD","337.18" - "Assets:US:ETrade","2012","2012-01-01","2012-12-31","VEA","12.00" - "Assets:US:ETrade","2012","2012-01-01","2012-12-31","VHT","106.00" - "Assets:US:ETrade","2013","2013-01-01","2013-12-31","GLD","70.00" - "Assets:US:ETrade","2013","2013-01-01","2013-12-31","ITOT","18.00" - "Assets:US:ETrade","2013","2013-01-01","2013-12-31","USD","-98.12" - "Assets:US:ETrade","2013","2013-01-01","2013-12-31","VEA","10.00" - "Assets:US:ETrade","2013","2013-01-01","2013-12-31","VHT","18.00" - "Assets:US:ETrade","2014","2014-01-01","2014-12-31","GLD","0" - "Assets:US:ETrade","2014","2014-01-01","2014-12-31","ITOT","-11.00" - "Assets:US:ETrade","2014","2014-01-01","2014-12-31","USD","4881.44" - "Assets:US:ETrade","2014","2014-01-01","2014-12-31","VEA","14.00" - "Assets:US:ETrade","2014","2014-01-01","2014-12-31","VHT","170.00" - - Useful balance reports + Wide layout + With many commodities, reports can be very wide: + + $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=wide + Balance changes in 2012-01-01..2014-12-31: + + || 2012 2013 2014 Total + ==================++==================================================================================================================================================================================================================== + Assets:US:ETrade || 10.00 ITOT, 337.18 USD, 12.00 VEA, 106.00 VHT 70.00 GLD, 18.00 ITOT, -98.12 USD, 10.00 VEA, 18.00 VHT -11.00 ITOT, 4881.44 USD, 14.00 VEA, 170.00 VHT 70.00 GLD, 17.00 ITOT, 5120.50 USD, 36.00 VEA, 294.00 VHT + ------------------++-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- + || 10.00 ITOT, 337.18 USD, 12.00 VEA, 106.00 VHT 70.00 GLD, 18.00 ITOT, -98.12 USD, 10.00 VEA, 18.00 VHT -11.00 ITOT, 4881.44 USD, 14.00 VEA, 170.00 VHT 70.00 GLD, 17.00 ITOT, 5120.50 USD, 36.00 VEA, 294.00 VHT + + A width limit reduces the width, but some commodities will be hidden: + + $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=wide,32 + Balance changes in 2012-01-01..2014-12-31: + + || 2012 2013 2014 Total + ==================++=========================================================================================================================== + Assets:US:ETrade || 10.00 ITOT, 337.18 USD, 2 more.. 70.00 GLD, 18.00 ITOT, 3 more.. -11.00 ITOT, 3 more.. 70.00 GLD, 17.00 ITOT, 3 more.. + ------------------++--------------------------------------------------------------------------------------------------------------------------- + || 10.00 ITOT, 337.18 USD, 2 more.. 70.00 GLD, 18.00 ITOT, 3 more.. -11.00 ITOT, 3 more.. 70.00 GLD, 17.00 ITOT, 3 more.. + + Tall layout + Each commodity gets a new line (may be different in each column), and + account names are repeated: + + $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=tall + Balance changes in 2012-01-01..2014-12-31: + + || 2012 2013 2014 Total + ==================++================================================== + Assets:US:ETrade || 10.00 ITOT 70.00 GLD -11.00 ITOT 70.00 GLD + Assets:US:ETrade || 337.18 USD 18.00 ITOT 4881.44 USD 17.00 ITOT + Assets:US:ETrade || 12.00 VEA -98.12 USD 14.00 VEA 5120.50 USD + Assets:US:ETrade || 106.00 VHT 10.00 VEA 170.00 VHT 36.00 VEA + Assets:US:ETrade || 18.00 VHT 294.00 VHT + ------------------++-------------------------------------------------- + || 10.00 ITOT 70.00 GLD -11.00 ITOT 70.00 GLD + || 337.18 USD 18.00 ITOT 4881.44 USD 17.00 ITOT + || 12.00 VEA -98.12 USD 14.00 VEA 5120.50 USD + || 106.00 VHT 10.00 VEA 170.00 VHT 36.00 VEA + || 18.00 VHT 294.00 VHT + + Bare layout + Commodity symbols are kept in one column, each commodity has its own + row, amounts are bare numbers, account names are repeated: + + $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=bare + Balance changes in 2012-01-01..2014-12-31: + + || Commodity 2012 2013 2014 Total + ==================++============================================= + Assets:US:ETrade || GLD 0 70.00 0 70.00 + Assets:US:ETrade || ITOT 10.00 18.00 -11.00 17.00 + Assets:US:ETrade || USD 337.18 -98.12 4881.44 5120.50 + Assets:US:ETrade || VEA 12.00 10.00 14.00 36.00 + Assets:US:ETrade || VHT 106.00 18.00 170.00 294.00 + ------------------++--------------------------------------------- + || GLD 0 70.00 0 70.00 + || ITOT 10.00 18.00 -11.00 17.00 + || USD 337.18 -98.12 4881.44 5120.50 + || VEA 12.00 10.00 14.00 36.00 + || VHT 106.00 18.00 170.00 294.00 + + Bare layout also affects CSV output, which is useful for producing data + that is easier to consume, eg for making charts: + + $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -O csv --layout=bare + "account","commodity","balance" + "Assets:US:ETrade","GLD","70.00" + "Assets:US:ETrade","ITOT","17.00" + "Assets:US:ETrade","USD","5120.50" + "Assets:US:ETrade","VEA","36.00" + "Assets:US:ETrade","VHT","294.00" + "total","GLD","70.00" + "total","ITOT","17.00" + "total","USD","5120.50" + "total","VEA","36.00" + "total","VHT","294.00" + + Bare layout will sometimes display an extra row for the no-symbol com- + modity, because of zero amounts (hledger treats zeroes as commod- + ity-less, usually). This can break hledger-bar confusingly + (workaround: add a cur: query to exclude the no-symbol row). + + Tidy layout + This produces normalised "tidy data" (see + https://cran.r-project.org/web/packages/tidyr/vignettes/tidy-data.html) + where every variable has its own column and each row represents a sin- + gle data point. This is the easiest kind of data for other software to + consume: + + $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -Y -O csv --layout=tidy + "account","period","start_date","end_date","commodity","value" + "Assets:US:ETrade","2012","2012-01-01","2012-12-31","GLD","0" + "Assets:US:ETrade","2012","2012-01-01","2012-12-31","ITOT","10.00" + "Assets:US:ETrade","2012","2012-01-01","2012-12-31","USD","337.18" + "Assets:US:ETrade","2012","2012-01-01","2012-12-31","VEA","12.00" + "Assets:US:ETrade","2012","2012-01-01","2012-12-31","VHT","106.00" + "Assets:US:ETrade","2013","2013-01-01","2013-12-31","GLD","70.00" + "Assets:US:ETrade","2013","2013-01-01","2013-12-31","ITOT","18.00" + "Assets:US:ETrade","2013","2013-01-01","2013-12-31","USD","-98.12" + "Assets:US:ETrade","2013","2013-01-01","2013-12-31","VEA","10.00" + "Assets:US:ETrade","2013","2013-01-01","2013-12-31","VHT","18.00" + "Assets:US:ETrade","2014","2014-01-01","2014-12-31","GLD","0" + "Assets:US:ETrade","2014","2014-01-01","2014-12-31","ITOT","-11.00" + "Assets:US:ETrade","2014","2014-01-01","2014-12-31","USD","4881.44" + "Assets:US:ETrade","2014","2014-01-01","2014-12-31","VEA","14.00" + "Assets:US:ETrade","2014","2014-01-01","2014-12-31","VHT","170.00" + + Some useful balance reports Some frequently used balance options/reports are: o bal -M revenues expenses - Show revenues/expenses in each month. Also available as the incomes- + Show revenues/expenses in each month. Also available as the incomes- tatement command. o bal -M -H assets liabilities - Show historical asset/liability balances at each month end. Also + Show historical asset/liability balances at each month end. Also available as the balancesheet command. o bal -M -H assets liabilities equity - Show historical asset/liability/equity balances at each month end. + Show historical asset/liability/equity balances at each month end. Also available as the balancesheetequity command. o bal -M assets not:receivable - Show changes to liquid assets in each month. Also available as the + Show changes to liquid assets in each month. Also available as the cashflow command. Also: o bal -M expenses -2 -SA - Show monthly expenses summarised to depth 2 and sorted by average + Show monthly expenses summarised to depth 2 and sorted by average amount. o bal -M --budget expenses @@ -7027,14 +7135,14 @@ PART 4: COMMANDS balancesheet (bs) - This command displays a balance sheet, showing historical ending bal- + This command displays a balance sheet, showing historical ending bal- ances of asset and liability accounts. (To see equity as well, use the - balancesheetequity command.) Amounts are shown with normal positive + balancesheetequity command.) Amounts are shown with normal positive sign, as in conventional financial statements. - This report shows accounts declared with the Asset, Cash or Liability - type (see account types). Or if no such accounts are declared, it - shows top-level accounts named asset or liability (case insensitive, + This report shows accounts declared with the Asset, Cash or Liability + type (see account types). Or if no such accounts are declared, it + shows top-level accounts named asset or liability (case insensitive, plurals allowed) and their subaccounts. Example: @@ -7059,25 +7167,25 @@ PART 4: COMMANDS 0 This command is a higher-level variant of the balance command, and sup- - ports many of that command's features, such as multi-period reports. - It is similar to hledger balance -H assets liabilities, but with - smarter account detection, and liabilities displayed with their sign + ports many of that command's features, such as multi-period reports. + It is similar to hledger balance -H assets liabilities, but with + smarter account detection, and liabilities displayed with their sign flipped. This command also supports the output destination and output format op- - tions The output formats supported are txt, csv, tsv (Added in 1.32), + tions The output formats supported are txt, csv, tsv (Added in 1.32), html, and json. balancesheetequity (bse) - This command displays a balance sheet, showing historical ending bal- - ances of asset, liability and equity accounts. Amounts are shown with + This command displays a balance sheet, showing historical ending bal- + ances of asset, liability and equity accounts. Amounts are shown with normal positive sign, as in conventional financial statements. - This report shows accounts declared with the Asset, Cash, Liability or - Equity type (see account types). Or if no such accounts are declared, - it shows top-level accounts named asset, liability or equity (case in- + This report shows accounts declared with the Asset, Cash, Liability or + Equity type (see account types). Or if no such accounts are declared, + it shows top-level accounts named asset, liability or equity (case in- sensitive, plurals allowed) and their subaccounts. Example: @@ -7107,9 +7215,9 @@ PART 4: COMMANDS 0 This command is a higher-level variant of the balance command, and sup- - ports many of that command's features, such as multi-period reports. + ports many of that command's features, such as multi-period reports. It is similar to hledger balance -H assets liabilities equity, but with - smarter account detection, and liabilities/equity displayed with their + smarter account detection, and liabilities/equity displayed with their sign flipped. This command also supports the output destination and output format op- @@ -7118,15 +7226,15 @@ PART 4: COMMANDS cashflow (cf) - This command displays a cashflow statement, showing the inflows and - outflows affecting "cash" (ie, liquid, easily convertible) assets. - Amounts are shown with normal positive sign, as in conventional finan- + This command displays a cashflow statement, showing the inflows and + outflows affecting "cash" (ie, liquid, easily convertible) assets. + Amounts are shown with normal positive sign, as in conventional finan- cial statements. - This report shows accounts declared with the Cash type (see account + This report shows accounts declared with the Cash type (see account types). Or if no such accounts are declared, it shows accounts - o under a top-level account named asset (case insensitive, plural al- + o under a top-level account named asset (case insensitive, plural al- lowed) o whose name contains some variation of cash, bank, checking or saving. @@ -7155,21 +7263,21 @@ PART 4: COMMANDS $-1 This command is a higher-level variant of the balance command, and sup- - ports many of that command's features, such as multi-period reports. - It is similar to hledger balance assets not:fixed not:investment + ports many of that command's features, such as multi-period reports. + It is similar to hledger balance assets not:fixed not:investment not:receivable, but with smarter account detection. This command also supports the output destination and output format op- - tions The output formats supported are txt, csv, tsv (Added in 1.32), + tions The output formats supported are txt, csv, tsv (Added in 1.32), html, and json. check Check for various kinds of errors in your data. - hledger provides a number of built-in error checks to help prevent - problems in your data. Some of these are run automatically; or, you - can use this check command to run them on demand, with no output and a - zero exit code if all is well. Specify their names (or a prefix) as + hledger provides a number of built-in error checks to help prevent + problems in your data. Some of these are run automatically; or, you + can use this check command to run them on demand, with no output and a + zero exit code if all is well. Specify their names (or a prefix) as argument(s). Some examples: @@ -7178,7 +7286,7 @@ PART 4: COMMANDS hledger check -s # basic + strict checks hledger check ordereddates payees # basic + two other checks - If you are an Emacs user, you can also configure flycheck-hledger to + If you are an Emacs user, you can also configure flycheck-hledger to run these checks, providing instant feedback as you edit the journal. Here are the checks currently available: @@ -7186,23 +7294,23 @@ PART 4: COMMANDS Default checks These checks are run automatically by (almost) all hledger commands: - o parseable - data files are in a supported format, with no syntax er- + o parseable - data files are in a supported format, with no syntax er- rors and no invalid include directives. - o autobalanced - all transactions are balanced, after converting to - cost. Missing amounts and missing costs are inferred automatically + o autobalanced - all transactions are balanced, after converting to + cost. Missing amounts and missing costs are inferred automatically where possible. - o assertions - all balance assertions in the journal are passing. + o assertions - all balance assertions in the journal are passing. (This check can be disabled with -I/--ignore-assertions.) Strict checks These additional checks are run when the -s/--strict (strict mode) flag - is used. Or, they can be run by giving their names as arguments to + is used. Or, they can be run by giving their names as arguments to check: - o balanced - all transactions are balanced after converting to cost, - without inferring missing costs. If conversion costs are required, + o balanced - all transactions are balanced after converting to cost, + without inferring missing costs. If conversion costs are required, they must be explicit. o accounts - all account names used by transactions have been declared @@ -7210,14 +7318,14 @@ PART 4: COMMANDS o commodities - all commodity symbols used have been declared Other checks - These checks can be run only by giving their names as arguments to + These checks can be run only by giving their names as arguments to check. They are more specialised and not desirable for everyone: o ordereddates - transactions are ordered by date within each file o payees - all payees used by transactions have been declared - o recentassertions - all accounts with balance assertions have a bal- + o recentassertions - all accounts with balance assertions have a bal- ance assertion within 7 days of their latest posting o tags - all tags used by transactions have been declared @@ -7225,26 +7333,26 @@ PART 4: COMMANDS o uniqueleafnames - all account leaf names are unique Custom checks - A few more checks are are available as separate add-on commands, in + A few more checks are are available as separate add-on commands, in https://github.com/simonmichael/hledger/tree/master/bin: - o hledger-check-tagfiles - all tag values containing / (a forward + o hledger-check-tagfiles - all tag values containing / (a forward slash) exist as file paths - o hledger-check-fancyassertions - more complex balance assertions are + o hledger-check-fancyassertions - more complex balance assertions are passing You could make similar scripts to perform your own custom checks. See: Cookbook -> Scripting. More about specific checks - hledger check recentassertions will complain if any balance-asserted - account has postings more than 7 days after its latest balance asser- - tion. This aims to prevent the situation where you are regularly up- - dating your journal, but forgetting to check your balances against the - real world, then one day must dig back through months of data to find - an error. It assumes that adding a balance assertion requires/reminds - you to check the real-world balance. (That may not be true if you + hledger check recentassertions will complain if any balance-asserted + account has postings more than 7 days after its latest balance asser- + tion. This aims to prevent the situation where you are regularly up- + dating your journal, but forgetting to check your balances against the + real world, then one day must dig back through months of data to find + an error. It assumes that adding a balance assertion requires/reminds + you to check the real-world balance. (That may not be true if you auto-generate balance assertions from bank data; in that case, I recom- mend to import transactions uncleared, and when you manually review and clear them, also check the latest assertion against the real-world bal- @@ -7253,87 +7361,87 @@ PART 4: COMMANDS close (equity) - close generates several kinds of "closing" and/or "opening" transac- - tions, useful in certain situations, including migrating balances to a - new journal file, retaining earnings into equity, consolidating bal- - ances, or viewing lots. Like print, it prints valid journal entries. + close generates several kinds of "closing" and/or "opening" transac- + tions, useful in certain situations, including migrating balances to a + new journal file, retaining earnings into equity, consolidating bal- + ances, or viewing lots. Like print, it prints valid journal entries. You can append or copy these to your journal file(s) when you are happy with how they look. close currently has six modes, selected by a single mode flag: close --migrate - This is the most common mode. It prints a "closing balances" transac- + This is the most common mode. It prints a "closing balances" transac- tion that zeroes out all asset and liability balances (by default), and - an opposite "opening balances" transaction that restores them again. - The balancing account will be equity:opening/closing balances (or an- + an opposite "opening balances" transaction that restores them again. + The balancing account will be equity:opening/closing balances (or an- other specified by --close-acct or --open-acct). - This is useful when migrating balances to a new journal file at the - start of a new year. Essentially, you run hledger close --mi- - grate=NEWYEAR -e NEWYEAR and then copy the closing transaction to the + This is useful when migrating balances to a new journal file at the + start of a new year. Essentially, you run hledger close --mi- + grate=NEWYEAR -e NEWYEAR and then copy the closing transaction to the end of the old file and the opening transaction to the start of the new - file. The opening transaction sets correct starting balances in the - new file when it is used alone, and the closing transaction keeps bal- - ances correct when you use both old and new files together, by can- + file. The opening transaction sets correct starting balances in the + new file when it is used alone, and the closing transaction keeps bal- + ances correct when you use both old and new files together, by can- celling out the following opening transaction and preventing buildup of - duplicated opening balances. Think of the closing/opening pair as + duplicated opening balances. Think of the closing/opening pair as "moving the balances into the next file". - You can close a different set of accounts by providing a query. Eg if - you want to include equity, you can add assets liabilities equity or - type:ALE arguments. (The balancing account is always excluded.) Rev- + You can close a different set of accounts by providing a query. Eg if + you want to include equity, you can add assets liabilities equity or + type:ALE arguments. (The balancing account is always excluded.) Rev- enues and expenses usually are not migrated to a new file directly; see --retain below. - The generated transactions will have a start: tag, with its value set - to --migrate's NEW argument if any, for easier matching or exclusion. - When NEW is not specified, it will be inferred if possible by incre- - menting a number (eg a year number) within the default journal's main + The generated transactions will have a start: tag, with its value set + to --migrate's NEW argument if any, for easier matching or exclusion. + When NEW is not specified, it will be inferred if possible by incre- + menting a number (eg a year number) within the default journal's main file name. The other modes behave similarly. close --close - This prints just the closing balances transaction of --migrate. It is - the default behaviour if you specify no mode flag. Using the customi- + This prints just the closing balances transaction of --migrate. It is + the default behaviour if you specify no mode flag. Using the customi- sation options below, you can move balances from any set of accounts to a different account. close --open - This prints just the opening balances transaction of --migrate. It is + This prints just the opening balances transaction of --migrate. It is similar to Ledger's equity command. close --assert This prints a "closing balances" transaction (with balances: tag), that - just declares balance assertions for the current balances without - changing them. It could be useful as documention and to guard against + just declares balance assertions for the current balances without + changing them. It could be useful as documention and to guard against changes. close --assign This prints an "opening balances" transaction that restores the account - balances using balance assignments. Balance assignments work regard- - less of any previous balance, so a preceding closing balances transac- + balances using balance assignments. Balance assignments work regard- + less of any previous balance, so a preceding closing balances transac- tion is not needed. - However, omitting the closing balances transaction would unbalance eq- - uity. This is relatively harmless for personal reports, but it dis- - turbs the accounting equation, removing a source of error detection. - So --migrate is generally the best way to set to set balances in new + However, omitting the closing balances transaction would unbalance eq- + uity. This is relatively harmless for personal reports, but it dis- + turbs the accounting equation, removing a source of error detection. + So --migrate is generally the best way to set to set balances in new files, for now. close --retain This is like --close with different defaults: it prints a "retain earn- - ings" transaction (with retain: tag), that transfers revenue and ex- + ings" transaction (with retain: tag), that transfers revenue and ex- pense balances to equity:retained earnings. - This is a different kind of closing, called "retaining earnings" or + This is a different kind of closing, called "retaining earnings" or "closing the books"; it is traditionally performed by businesses at the - end of each accounting period, to consolidate revenues and expenses - into the main equity balance. ("Revenues" and "expenses" are actually - equity by another name, kept separate temporarily for reporting pur- + end of each accounting period, to consolidate revenues and expenses + into the main equity balance. ("Revenues" and "expenses" are actually + equity by another name, kept separate temporarily for reporting pur- poses.) - In personal accounting you generally don't need to do this, unless you - want the balancesheetequity report to show a zero total, demonstrating + In personal accounting you generally don't need to do this, unless you + want the balancesheetequity report to show a zero total, demonstrating that the accounting equation (A-L=E) is satisfied. close customisation @@ -7343,53 +7451,57 @@ PART 4: COMMANDS o the balancing account, with --close-acct=ACCT and/or --open-acct=ACCT - o the transaction descriptions, with --close-desc=DESC and + o the transaction descriptions, with --close-desc=DESC and --open-desc=DESC o the transaction's tag value, with a --MODE=NEW option argument o the closing/opening dates, with -e OPENDATE - By default, the closing date is yesterday, or the journal's end date, - whichever is later; and the opening date is always one day after the - closing date. You can change these by specifying a report end date; + By default, the closing date is yesterday, or the journal's end date, + whichever is later; and the opening date is always one day after the + closing date. You can change these by specifying a report end date; the closing date will be the last day of the report period. Eg -e 2024 means "close on 2023-12-31, open on 2024-01-01". With --x/--explicit, the balancing amount will be shown explicitly, and - if it involves multiple commodities, a separate posting will be gener- + if it involves multiple commodities, a separate posting will be gener- ated for each of them (similar to print -x). - With --interleaved, each individual transfer is shown with source and - destination postings next to each other (perhaps useful for trou- + With --interleaved, each individual transfer is shown with source and + destination postings next to each other (perhaps useful for trou- bleshooting). With --show-costs, balances' costs are also shown, with different costs - kept separate. This may generate very large journal entries, if you - have many currency conversions or investment transactions. close - --show-costs is currently the best way to view investment lots with - hledger. (To move or dispose of lots, see the more capable + kept separate. This may generate very large journal entries, if you + have many currency conversions or investment transactions. close + --show-costs is currently the best way to view investment lots with + hledger. (To move or dispose of lots, see the more capable hledger-move script.) close and balance assertions close adds balance assertions verifying that the accounts have been re- set to zero in a closing transaction or restored to their previous bal- - ances in an opening transaction. These provide useful error checking, + ances in an opening transaction. These provide useful error checking, but you can ignore them temporarily with -I, or remove them if you pre- fer. - When running close you should probably avoid using -C, -R, status: - (filtering by status or realness) or --auto (generating postings), + Single-commodity, subaccount-exclusive balance assertions (=) are gen- + erated by default. This can be changed with --assertion-type='==*' + (eg). + + When running close you should probably avoid using -C, -R, status: + (filtering by status or realness) or --auto (generating postings), since the generated balance assertions would then require these. - Transactions with multiple dates (eg posting dates) spanning the file + Transactions with multiple dates (eg posting dates) spanning the file boundary also can disrupt the balance assertions: 2023-12-30 a purchase made in december, cleared in january expenses:food 5 assets:bank:checking -5 ; date: 2023-01-02 - To solve this you can transfer the money to and from a temporary ac- + To solve this you can transfer the money to and from a temporary ac- count, splitting the multi-day transaction into two single-day transac- tions: @@ -7410,7 +7522,7 @@ PART 4: COMMANDS $ hledger close --retain -f 2022.journal -p 2022 >> 2022.journal - After this, to see 2022's revenues and expenses you must exclude the + After this, to see 2022's revenues and expenses you must exclude the retain earnings transaction: $ hledger -f 2022.journal is not:desc:'retain earnings' @@ -7422,13 +7534,13 @@ PART 4: COMMANDS # copy/paste the closing transaction to the end of 2022.journal # copy/paste the opening transaction to the start of 2023.journal - After this, to see 2022's end-of-year balances you must exclude the + After this, to see 2022's end-of-year balances you must exclude the closing balances transaction: $ hledger -f 2022.journal bs not:desc:'closing balances' - For more flexibility, it helps to tag closing and opening transactions - with eg start:NEWYEAR, then you can ensure correct balances by exclud- + For more flexibility, it helps to tag closing and opening transactions + with eg start:NEWYEAR, then you can ensure correct balances by exclud- ing all opening/closing transactions except the first, like so: $ hledger bs -Y -f 2021.j -f 2022.j -f 2023.j expr:'tag:start=2021 or not tag:start' @@ -7444,13 +7556,13 @@ PART 4: COMMANDS codes List the codes seen in transactions, in the order parsed. - This command prints the value of each transaction's code field, in the - order transactions were parsed. The transaction code is an optional - value written in parentheses between the date and description, often + This command prints the value of each transaction's code field, in the + order transactions were parsed. The transaction code is an optional + value written in parentheses between the date and description, often used to store a cheque number, order number or similar. Transactions aren't required to have a code, and missing or empty codes - will not be shown by default. With the -E/--empty flag, they will be + will not be shown by default. With the -E/--empty flag, they will be printed as blank lines. You can add a query to select a subset of transactions. @@ -7490,19 +7602,19 @@ PART 4: COMMANDS demo Play demos of hledger usage in the terminal, if asciinema is installed. - Run this command with no argument to list the demos. To play a demo, + Run this command with no argument to list the demos. To play a demo, write its number or a prefix or substring of its title. Tips: Make your terminal window large enough to see the demo clearly. - Use the -s/--speed SPEED option to set your preferred playback speed, + Use the -s/--speed SPEED option to set your preferred playback speed, eg -s4 to play at 4x original speed or -s.5 to play at half speed. The default speed is 2x. - Other asciinema options can be added following a double dash, eg -- + Other asciinema options can be added following a double dash, eg -- -i.1 to limit pauses or -- -h to list asciinema's other options. - During playback, several keys are available: SPACE to pause/unpause, . + During playback, several keys are available: SPACE to pause/unpause, . to step forward (while paused), CTRL-c quit. Examples: @@ -7515,7 +7627,7 @@ PART 4: COMMANDS List the unique descriptions that appear in transactions. This command lists the unique descriptions that appear in transactions, - in alphabetic order. You can add a query to select a subset of trans- + in alphabetic order. You can add a query to select a subset of trans- actions. Example: @@ -7526,18 +7638,18 @@ PART 4: COMMANDS Person A diff - Compares a particular account's transactions in two input files. It + 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.) + 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 + 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. @@ -7554,30 +7666,30 @@ PART 4: COMMANDS These transactions are in the second file only: files - List all files included in the journal. With a REGEX argument, only + List all files included in the journal. With a REGEX argument, only file names matching the regular expression (case sensitive) are shown. help - Show the hledger user manual in the terminal, with info, man, or a - pager. With a TOPIC argument, open it at that topic if possible. - TOPIC can be any heading in the manual, or a heading prefix, case in- + Show the hledger user manual in the terminal, with info, man, or a + pager. With a TOPIC argument, open it at that topic if possible. + TOPIC can be any heading in the manual, or a heading prefix, case in- sensitive. Eg: commands, print, forecast, journal, amount, "auto post- ings". This command shows the hledger manual built in to your hledger version. It can be useful when offline, or when you prefer the terminal to a web - browser, or when the appropriate hledger manual or viewing tools are + browser, or when the appropriate hledger manual or viewing tools are not installed on your system. - By default it chooses the best viewer found in $PATH, trying (in this - order): info, man, $PAGER, less, more. You can force the use of info, - man, or a pager with the -i, -m, or -p flags, If no viewer can be + By default it chooses the best viewer found in $PATH, trying (in this + order): info, man, $PAGER, less, more. You can force the use of info, + man, or a pager with the -i, -m, or -p flags, If no viewer can be found, or the command is run non-interactively, it just prints the man- ual to stdout. - If using info, note that version 6 or greater is needed for TOPIC - lookup. If you are on mac you will likely have info 4.8, and should - consider installing a newer version, eg with brew install texinfo + If using info, note that version 6 or greater is needed for TOPIC + lookup. If you are on mac you will likely have info 4.8, and should + consider installing a newer version, eg with brew install texinfo (#1770). Examples @@ -7588,75 +7700,78 @@ PART 4: COMMANDS $ hledger help -m journal # show it with man, even if info is installed import - Read new transactions added to each FILE provided as arguments since - last run, and add them to the journal. Or with --dry-run, just print + Read new transactions added to each FILE provided as arguments since + last run, and add them to the journal. Or with --dry-run, just print the transactions that would be added. Or with --catchup, just mark all of the FILEs' current transactions as imported, without importing them. - This command may append new transactions to the main journal file - (which should be in journal format). Existing transactions are not - changed. This is one of the few hledger commands that writes to the + This command may append new transactions to the main journal file + (which should be in journal format). Existing transactions are not + changed. This is one of the few hledger commands that writes to the journal file (see also add). - Unlike other hledger commands, with import the journal file is an out- + Unlike other hledger commands, with import the journal file is an out- put file, and will be modified, though only by appending (existing data - will not be changed). The input files are specified as arguments, so - to import one or more CSV files to your main journal, you will run + will not be changed). The input files are specified as arguments, so + to import one or more CSV files to your main journal, you will run hledger import bank.csv or perhaps hledger import *.csv. Note you can import from any file format, though CSV files are the most common import source, and these docs focus on that case. - Deduplication - import does time-based deduplication, to detect only the new transac- - tions since the last successful import. (This does not mean "ignore - transactions that look the same", but rather "ignore transactions that - have been seen before".) This is intended for when you are periodi- - cally importing downloaded data, which may overlap with previous down- - loads. Eg if every week (or every day) you download a bank's last - three months of CSV data, you can safely run hledger import thebank.csv - each time and only new transactions will be imported. + "Deduplication" + import tries to import only the transactions which are new since the + last import. So if your bank's CSV includes the last three months of + data, you can download and import it every month (or week, or day) and + only the new transactions will be imported each time. + + It works as follows. For each imported FILE (usually a CSV file): - It + tries to find the latest date seen previously, by reading it from a + hidden .latest.FILE in the same directory. - Then it processes FILE, + ignoring any transactions on or before the "latest seen" date. - Since the items being read (CSV records, eg) often do not come with - unique identifiers, hledger detects new transactions by date, assuming - that: + And after a successful import, it updates the .latest.FILE(s) for next + time (unless --dry-run was used). + + This is simple but fairly effective. It assumes: 1. new items always have the newest dates - 2. item dates do not change across reads + 2. item dates are stable across successive CSV downloads - 3. and items with the same date remain in the same relative order - across reads. + 3. the order of same-date items is stable across CSV downloads - These are often true of CSV files representing transactions, or true - enough so that it works pretty well in practice. 1 is important, but - violations of 2 and 3 amongst the old transactions won't matter (and if - you import often, the new transactions will be few, so less likely to - be the ones affected). + These are true of most CSV files representing transactions, or true + enough. If you have a bank whose CSV dates or ordering occasionally + changes, you can reduce the chance of this happening in new transac- + tions by importing more often (and in old transactions it doesn't mat- + ter). - hledger remembers the latest date processed in each input file by sav- - ing a hidden ".latest.FILE" file in FILE's directory (after a succesful - import). + Note, import avoids reprocessing the same dates across successive runs, + but it does not detect transactions that are duplicated within a single + run. So eg if you downloaded but did not import bank.1.csv, and later + downloaded bank.2.csv with overlapping data, you should not import both + of them in a single run (hledger import bank.1.csv bank.2.csv); in- + stead, import them one at a time (hledger import bank.1.csv, then + hledger import bank.2.csv). - Eg when reading finance/bank.csv, it will look for and update the fi- - nance/.latest.bank.csv state file. The format is simple: one or more - lines containing the same ISO-format date (YYYY-MM-DD), meaning "I have - processed transactions up to this date, and this many of them on that - date." Normally you won't see or manipulate these state files yourself. - But if needed, you can delete them to reset the state (making all - transactions "new"), or you can construct them to "catch up" to a cer- - tain date. + Normally you can ignore the .latest.* files, but if needed, you can + delete them (to make all transactions unseen), or construct/modify them + (to catch up to a certain date). The format is just a single ISO-for- + mat date (YYYY-MM-DD), possibly repeated on multiple lines. It means + "I have seen transactions up to this date, and this many of them occur- + ring on that date". - Note deduplication (and updating of state files) can also be done by - print --new, but this is less often used. + (hledger print --new also uses and updates these .latest.* files, but + it is not often used.) Related: CSV > Working with CSV > Deduplicating, importing. Import testing - With --dry-run, the transactions that will be imported are printed to + With --dry-run, the transactions that will be imported are printed to the terminal, without updating your journal or state files. The output - is valid journal format, like the print command, so you can re-parse - it. Eg, to see any importable transactions which CSV rules have not + is valid journal format, like the print command, so you can re-parse + it. Eg, to see any importable transactions which CSV rules have not categorised: $ hledger import --dry bank.csv | hledger -f- -I print unknown @@ -7672,17 +7787,17 @@ PART 4: COMMANDS do a --dry-run first and fix any problems before the real import. Importing balance assignments - Entries added by import will have their posting amounts made explicit - (like hledger print -x). This means that any balance assignments in - imported files must be evaluated; but, imported files don't get to see - the main file's account balances. As a result, importing entries with + Entries added by import will have their posting amounts made explicit + (like hledger print -x). This means that any balance assignments in + imported files must be evaluated; but, imported files don't get to see + the main file's account balances. As a result, importing entries with balance assignments (eg from an institution that provides only balances - and not posting amounts) will probably generate incorrect posting + and not posting amounts) will probably generate incorrect posting amounts. To avoid this problem, use print instead of import: $ hledger print IMPORTFILE [--new] >> $LEDGER_FILE - (If you think import should leave amounts implicit like print does, + (If you think import should leave amounts implicit like print does, please test it and send a pull request.) Commodity display styles @@ -7692,13 +7807,13 @@ PART 4: COMMANDS incomestatement (is) - This command displays an income statement, showing revenues and ex- + This command displays an income statement, showing revenues and ex- penses during one or more periods. Amounts are shown with normal posi- tive sign, as in conventional financial statements. - This report shows accounts declared with the Revenue or Expense type - (see account types). Or if no such accounts are declared, it shows - top-level accounts named revenue or income or expense (case insensi- + This report shows accounts declared with the Revenue or Expense type + (see account types). Or if no such accounts are declared, it shows + top-level accounts named revenue or income or expense (case insensi- tive, plurals allowed) and their subaccounts. Example: @@ -7725,21 +7840,21 @@ PART 4: COMMANDS 0 This command is a higher-level variant of the balance command, and sup- - ports many of that command's features, such as multi-period reports. + ports many of that command's features, such as multi-period reports. It is similar to hledger balance '(revenues|income)' expenses, but with - smarter account detection, and revenues/income displayed with their + smarter account detection, and revenues/income displayed with their sign flipped. This command also supports the output destination and output format op- - tions The output formats supported are txt, csv, tsv (Added in 1.32), + tions The output formats supported are txt, csv, tsv (Added in 1.32), html, and json. notes List the unique notes that appear in transactions. This command lists the unique notes that appear in transactions, in al- - phabetic order. You can add a query to select a subset of transac- - tions. The note is the part of the transaction description after a | + phabetic order. You can add a query to select a subset of transac- + tions. The note is the part of the transaction description after a | character (or if there is no |, the whole description). Example: @@ -7751,14 +7866,14 @@ PART 4: COMMANDS payees List the unique payee/payer names that appear in transactions. - This command lists unique payee/payer names which have been declared - with payee directives (--declared), used in transaction descriptions + This command lists unique payee/payer names which have been declared + with payee directives (--declared), used in transaction descriptions (--used), or both (the default). - The payee/payer is the part of the transaction description before a | + The payee/payer is the part of the transaction description before a | character (or if there is no |, the whole description). - You can add query arguments to select a subset of transactions. This + You can add query arguments to select a subset of transactions. This implies --used. Example: @@ -7769,19 +7884,19 @@ PART 4: COMMANDS Person A prices - Print the market prices declared with P directives. With --infer-mar- - ket-prices, also show any additional prices inferred from costs. With + Print the market prices declared with P directives. With --infer-mar- + ket-prices, also show any additional prices inferred from costs. With --show-reverse, also show additional prices inferred by reversing known prices. - Price amounts are always displayed with their full precision, except + Price amounts are always displayed with their full precision, except for reverse prices which are limited to 8 decimal digits. Prices can be filtered by a date:, cur: or amt: query. Generally if you run this command with --infer-market-prices --show-re- - verse, it will show the same prices used internally to calculate value - reports. But if in doubt, you can inspect those directly by running + verse, it will show the same prices used internally to calculate value + reports. But if in doubt, you can inspect those directly by running the value report with --debug=2. print @@ -7790,9 +7905,9 @@ PART 4: COMMANDS The print command displays full journal entries (transactions) from the journal file, sorted by date (or with --date2, by secondary date). - Directives and inter-transaction comments are not shown, currently. + Directives and inter-transaction comments are not shown, currently. This means the print command is somewhat lossy, and if you are using it - to reformat/regenerate your journal you should take care to also copy + to reformat/regenerate your journal you should take care to also copy over the directives and inter-transaction comments. Eg: @@ -7812,55 +7927,55 @@ PART 4: COMMANDS assets:cash $-2 print explicitness - Normally, whether posting amounts are implicit or explicit is pre- + Normally, whether posting amounts are implicit or explicit is pre- served. For example, when an amount is omitted in the journal, it will - not appear in the output. Similarly, if a conversion cost is implied + not appear in the output. Similarly, if a conversion cost is implied but not written, it will not appear in the output. - You can use the -x/--explicit flag to force explicit display of all - amounts and costs. This can be useful for troubleshooting or for mak- - ing your journal more readable and robust against data entry errors. + You can use the -x/--explicit flag to force explicit display of all + amounts and costs. This can be useful for troubleshooting or for mak- + ing your journal more readable and robust against data entry errors. -x is also implied by using any of -B,-V,-X,--value. - The -x/--explicit flag will cause any postings with a multi-commodity - amount (which can arise when a multi-commodity transaction has an im- - plicit amount) to be split into multiple single-commodity postings, + The -x/--explicit flag will cause any postings with a multi-commodity + amount (which can arise when a multi-commodity transaction has an im- + plicit amount) to be split into multiple single-commodity postings, keeping the output parseable. print amount style - Amounts are shown right-aligned within each transaction (but not - aligned across all transactions; you can do that with ledger-mode in + Amounts are shown right-aligned within each transaction (but not + aligned across all transactions; you can do that with ledger-mode in Emacs). - Amounts will be (mostly) normalised to their commodity display style: - their symbol placement, decimal mark, and digit group marks will be - made consistent. By default, decimal digits are shown as they are + Amounts will be (mostly) normalised to their commodity display style: + their symbol placement, decimal mark, and digit group marks will be + made consistent. By default, decimal digits are shown as they are written in the journal. - With the --round (Added in 1.32) option, print will try increasingly - hard to display decimal digits according to the commodity display + With the --round (Added in 1.32) option, print will try increasingly + hard to display decimal digits according to the commodity display styles: o --round=none show amounts with original precisions (default) o --round=soft add/remove decimal zeros in amounts (except costs) - o --round=hard round amounts (except costs), possibly hiding signifi- + o --round=hard round amounts (except costs), possibly hiding signifi- cant digits o --round=all round all amounts and costs - soft is good for non-lossy cleanup, formatting amounts more consis- + soft is good for non-lossy cleanup, formatting amounts more consis- tently where it's safe to do so. - hard and all can cause print to show invalid unbalanced journal en- - tries; they may be useful eg for stronger cleanup, with manual fixups + hard and all can cause print to show invalid unbalanced journal en- + tries; they may be useful eg for stronger cleanup, with manual fixups when needed. print parseability - print's output is usually a valid hledger journal, and you can process + print's output is usually a valid hledger journal, and you can process it again with a second hledger command. This can be useful for certain - kinds of search (though the same can be achieved with expr: queries + kinds of search (though the same can be achieved with expr: queries now): # Show running total of food expenses paid from cash. @@ -7869,7 +7984,7 @@ PART 4: COMMANDS There are some situations where print's output can become unparseable: - o Value reporting affects posting amounts but not balance assertion or + o Value reporting affects posting amounts but not balance assertion or balance assignment amounts, potentially causing those to fail. o Auto postings can generate postings with too many missing amounts. @@ -7880,37 +7995,37 @@ PART 4: COMMANDS With -B/--cost, amounts with costs are shown converted to cost. With --new, print shows only transactions it has not seen on a previous - run. This uses the same deduplication system as the import command. + run. This uses the same deduplication system as the import command. (See import's docs for details.) With -m DESC/--match=DESC, print shows one recent transaction whose de- - scription is most similar to DESC. DESC should contain at least two - characters. If there is no similar-enough match, no transaction will + scription is most similar to DESC. DESC should contain at least two + characters. If there is no similar-enough match, no transaction will be shown and the program exit code will be non-zero. print output format This command also supports the output destination and output format op- - tions The output formats supported are txt, beancount (Added in 1.32), + tions The output formats supported are txt, beancount (Added in 1.32), csv, tsv (Added in 1.32), json and sql. - The beancount format tries to produce Beancount-compatible output, as + The beancount format tries to produce Beancount-compatible output, as follows: - o Transaction and postings with unmarked status are converted to + o Transaction and postings with unmarked status are converted to cleared (*) status. - o Transactions' payee and note are backslash-escaped and dou- + o Transactions' payee and note are backslash-escaped and dou- ble-quote-escaped and wrapped in double quotes. o Transaction tags are copied to Beancount #tag format. - o Commodity symbols are converted to upper case, and a small number of - currency symbols like $ are converted to the corresponding currency + o Commodity symbols are converted to upper case, and a small number of + currency symbols like $ are converted to the corresponding currency names. o Account name parts are capitalised and unsupported characters are re- placed with -. If an account name part does not begin with a letter, - or if the first part is not Assets, Liabilities, Equity, Income, or + or if the first part is not Assets, Liabilities, Equity, Income, or Expenses, an error is raised. (Use --alias options to bring your ac- counts into compliance.) @@ -7943,20 +8058,20 @@ PART 4: COMMANDS "5","2008/12/31","","*","","pay off","","liabilities:debts","1","$","","1","","" "5","2008/12/31","","*","","pay off","","assets:bank:checking","-1","$","1","","","" - o There is one CSV record per posting, with the parent transaction's + o There is one CSV record per posting, with the parent transaction's fields repeated. o The "txnidx" (transaction index) field shows which postings belong to - the same transaction. (This number might change if transactions are - reordered within the file, files are parsed/included in a different + the same transaction. (This number might change if transactions are + reordered within the file, files are parsed/included in a different order, etc.) - o The amount is separated into "commodity" (the symbol) and "amount" + o The amount is separated into "commodity" (the symbol) and "amount" (numeric quantity) fields. o The numeric amount is repeated in either the "credit" or "debit" col- - umn, for convenience. (Those names are not accurate in the account- - ing sense; it just puts negative amounts under credit and zero or + umn, for convenience. (Those names are not accurate in the account- + ing sense; it just puts negative amounts under credit and zero or greater amounts under debit.) register @@ -7965,14 +8080,14 @@ PART 4: COMMANDS Show postings and their running total. The register command displays matched postings, across all accounts, in - date order, with their running total or running historical balance. - (See also the aregister command, which shows matched transactions in a + date order, with their running total or running historical balance. + (See also the aregister command, which shows matched transactions in a specific account.) register normally shows line per posting, but note that multi-commodity amounts will occupy multiple lines (one line per commodity). - It is typically used with a query selecting a particular account, to + It is typically used with a query selecting a particular account, to see that account's activity: $ hledger register checking @@ -7983,14 +8098,14 @@ PART 4: COMMANDS With --date2, it shows and sorts by secondary date instead. - For performance reasons, column widths are chosen based on the first - 1000 lines; this means unusually wide values in later lines can cause - visual discontinuities as column widths are adjusted. If you want to - ensure perfect alignment, at the cost of more time and memory, use the + For performance reasons, column widths are chosen based on the first + 1000 lines; this means unusually wide values in later lines can cause + visual discontinuities as column widths are adjusted. If you want to + ensure perfect alignment, at the cost of more time and memory, use the --align-all flag. - The --historical/-H flag adds the balance from any undisplayed prior - postings to the running total. This is useful when you want to see + The --historical/-H flag adds the balance from any undisplayed prior + postings to the running total. This is useful when you want to see only recent activity, with a historically accurate running balance: $ hledger register checking -b 2008/6 --historical @@ -8000,18 +8115,18 @@ PART 4: COMMANDS The --depth option limits the amount of sub-account detail displayed. - The --average/-A flag shows the running average posting amount instead + The --average/-A flag shows the running average posting amount instead of the running total (so, the final number displayed is the average for - the whole report period). This flag implies --empty (see below). It - is affected by --historical. It works best when showing just one ac- + the whole report period). This flag implies --empty (see below). It + is affected by --historical. It works best when showing just one ac- count and one commodity. - The --related/-r flag shows the other postings in the transactions of + The --related/-r flag shows the other postings in the transactions of the postings which would normally be shown. - The --invert flag negates all amounts. For example, it can be used on + The --invert flag negates all amounts. For example, it can be used on an income account where amounts are normally displayed as negative num- - bers. It's also useful to show postings on the checking account to- + bers. It's also useful to show postings on the checking account to- gether with the related account: $ hledger register --related --invert assets:checking @@ -8023,7 +8138,7 @@ PART 4: COMMANDS 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 @@ -8040,7 +8155,7 @@ PART 4: COMMANDS 2008/11 0 $-2 2008/12 0 $-2 - Often, you'll want to see just one line per interval. The --depth op- + 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 @@ -8048,22 +8163,22 @@ PART 4: COMMANDS 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 in- - tervals. 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. - With -m DESC/--match=DESC, register does a fuzzy search for one recent + With -m DESC/--match=DESC, register does a fuzzy search for one recent posting whose description is most similar to DESC. DESC should contain at least two characters. If there is no similar-enough match, no post- ing will be shown and the program exit code will be non-zero. 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 + 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): @@ -8082,18 +8197,18 @@ PART 4: COMMANDS $ hledger reg -w $COLUMNS,40 # use terminal width, & description width 40 This command also supports the output destination and output format op- - tions The output formats supported are txt, csv, tsv (Added in 1.32), + tions The output formats supported are txt, csv, tsv (Added in 1.32), and json. 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: @@ -8109,7 +8224,7 @@ PART 4: COMMANDS (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: @@ -8119,16 +8234,16 @@ PART 4: COMMANDS $ 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 in- + 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- + 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. @@ -8143,7 +8258,7 @@ PART 4: COMMANDS 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. @@ -8156,12 +8271,12 @@ PART 4: COMMANDS --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' @@ -8185,10 +8300,10 @@ PART 4: COMMANDS 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: @@ -8196,55 +8311,55 @@ PART 4: COMMANDS 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. + o rewrite applies rules specified on command line or in the journal. print --auto applies rules specified in the journal. roi - Shows the time-weighted (TWR) and money-weighted (IRR) rate of return + Shows the time-weighted (TWR) and money-weighted (IRR) rate of return on your investments. - At a minimum, you need to supply a query (which could be just an ac- - count name) to select your investment(s) with --inv, and another query + At a minimum, you need to supply a query (which could be just an ac- + count name) to select your investment(s) with --inv, and another query to identify your profit and loss transactions with --pnl. - If you do not record changes in the value of your investment manually, - or do not require computation of time-weighted return (TWR), --pnl + If you do not record changes in the value of your investment manually, + or do not require computation of time-weighted return (TWR), --pnl could be an empty query (--pnl "" or --pnl STR where STR does not match any of your accounts). - This command will compute and display the internalized rate of return - (IRR, also known as money-weighted rate of return) and time-weighted - rate of return (TWR) for your investments for the time period re- - quested. IRR is always annualized due to the way it is computed, but - TWR is reported both as a rate over the chosen reporting period and as + This command will compute and display the internalized rate of return + (IRR, also known as money-weighted rate of return) and time-weighted + rate of return (TWR) for your investments for the time period re- + quested. IRR is always annualized due to the way it is computed, but + TWR is reported both as a rate over the chosen reporting period and as an annual rate. - Price directives will be taken into account if you supply appropriate + Price directives will be taken into account if you supply appropriate --cost or --value flags (see VALUATION). Note, in some cases this report can fail, for these reasons: - o Error (NotBracketed): No solution for Internal Rate of Return (IRR). - Possible causes: IRR is huge (>1000000%), balance of investment be- + o Error (NotBracketed): No solution for Internal Rate of Return (IRR). + Possible causes: IRR is huge (>1000000%), balance of investment be- comes negative at some point in time. - o Error (SearchFailed): Failed to find solution for Internal Rate of + o Error (SearchFailed): Failed to find solution for Internal Rate of Return (IRR). Either search does not converge to a solution, or con- verges too slowly. Examples: - o Using roi to compute total return of investment in stocks: + o Using roi to compute total return of investment in stocks: https://github.com/simonmichael/hledger/blob/master/examples/invest- ing/roi-unrealised.ledger @@ -8254,28 +8369,28 @@ PART 4: COMMANDS Note that --inv and --pnl's argument is a query, and queries could have several space-separated terms (see QUERIES). - To indicate that all search terms form single command-line argument, + To indicate that all search terms form single command-line argument, you will need to put them in quotes (see Special characters): $ hledger roi --inv 'term1 term2 term3 ...' - If any query terms contain spaces themselves, you will need an extra + If any query terms contain spaces themselves, you will need an extra level of nested quoting, eg: $ hledger roi --inv="'Assets:Test 1'" --pnl="'Equity:Unrealized Profit and Loss'" Semantics of --inv and --pnl - Query supplied to --inv has to match all transactions that are related + Query supplied to --inv has to match all transactions that are related to your investment. Transactions not matching --inv will be ignored. In these transactions, ROI will conside postings that match --inv to be - "investment postings" and other postings (not matching --inv) will be - sorted into two categories: "cash flow" and "profit and loss", as ROI - needs to know which part of the investment value is your contributions + "investment postings" and other postings (not matching --inv) will be + sorted into two categories: "cash flow" and "profit and loss", as ROI + needs to know which part of the investment value is your contributions and which is due to the return on investment. o "Cash flow" is depositing or withdrawing money, buying or selling as- - sets, or otherwise converting between your investment commodity and + sets, or otherwise converting between your investment commodity and any other commodity. Example: 2019-01-01 Investing in Snake Oil @@ -8292,12 +8407,12 @@ PART 4: COMMANDS investment:snake oil = $57 equity:unrealized profit or loss - All non-investment postings are assumed to be "cash flow", unless they - match --pnl query. Changes in value of your investment due to "profit - and loss" postings will be considered as part of your investment re- + All non-investment postings are assumed to be "cash flow", unless they + match --pnl query. Changes in value of your investment due to "profit + and loss" postings will be considered as part of your investment re- turn. - Example: if you use --inv snake --pnl equity:unrealized, then postings + Example: if you use --inv snake --pnl equity:unrealized, then postings in the example below would be classifed as: 2019-01-01 Snake Oil #1 @@ -8314,58 +8429,58 @@ PART 4: COMMANDS snake oil $50 ; investment posting IRR and TWR explained - "ROI" stands for "return on investment". Traditionally this was com- - puted as a difference between current value of investment and its ini- + "ROI" stands for "return on investment". Traditionally this was com- + puted as a difference between current value of investment and its ini- tial value, expressed in percentage of the initial value. However, this approach is only practical in simple cases, where invest- - ments receives no in-flows or out-flows of money, and where rate of + ments receives no in-flows or out-flows of money, and where rate of growth is fixed over time. For more complex scenarios you need differ- - ent ways to compute rate of return, and this command implements two of + ent ways to compute rate of return, and this command implements two of them: IRR and TWR. - Internal rate of return, or "IRR" (also called "money-weighted rate of - return") takes into account effects of in-flows and out-flows, and the - time between them. Investment at a particular fixed interest rate is - going to give you more interest than the same amount invested at the - same interest rate, but made later in time. If you are withdrawing - from your investment, your future gains would be smaller (in absolute - numbers), and will be a smaller percentage of your initial investment, + Internal rate of return, or "IRR" (also called "money-weighted rate of + return") takes into account effects of in-flows and out-flows, and the + time between them. Investment at a particular fixed interest rate is + going to give you more interest than the same amount invested at the + same interest rate, but made later in time. If you are withdrawing + from your investment, your future gains would be smaller (in absolute + numbers), and will be a smaller percentage of your initial investment, so your IRR will be smaller. And if you are adding to your investment, you will receive bigger absolute gains, which will be a bigger percent- age of your initial investment, so your IRR will be larger. - As mentioned before, in-flows and out-flows would be any cash that you + As mentioned before, in-flows and out-flows would be any cash that you personally put in or withdraw, and for the "roi" command, these are the - postings that match the query in the--inv argument and NOT match the + postings that match the query in the--inv argument and NOT match the query in the--pnl argument. - If you manually record changes in the value of your investment as - transactions that balance them against "profit and loss" (or "unreal- - ized gains") account or use price directives, then in order for IRR to - compute the precise effect of your in-flows and out-flows on the rate - of return, you will need to record the value of your investement on or + If you manually record changes in the value of your investment as + transactions that balance them against "profit and loss" (or "unreal- + ized gains") account or use price directives, then in order for IRR to + compute the precise effect of your in-flows and out-flows on the rate + of return, you will need to record the value of your investement on or close to the days when in- or out-flows occur. - In technical terms, IRR uses the same approach as computation of net + In technical terms, IRR uses the same approach as computation of net present value, and tries to find a discount rate that makes net present value of all the cash flows of your investment to add up to zero. This - could be hard to wrap your head around, especially if you haven't done + could be hard to wrap your head around, especially if you haven't done discounted cash flow analysis before. Implementation of IRR in hledger should produce results that match the =XIRR formula in Excel. - Second way to compute rate of return that roi command implements is - called "time-weighted rate of return" or "TWR". Like IRR, it will ac- - count for the effect of your in-flows and out-flows, but unlike IRR it - will try to compute the true rate of return of the underlying asset, - compensating for the effect that deposits and withdrawas have on the + Second way to compute rate of return that roi command implements is + called "time-weighted rate of return" or "TWR". Like IRR, it will ac- + count for the effect of your in-flows and out-flows, but unlike IRR it + will try to compute the true rate of return of the underlying asset, + compensating for the effect that deposits and withdrawas have on the apparent rate of growth of your investment. - TWR represents your investment as an imaginary "unit fund" where - in-flows/ out-flows lead to buying or selling "units" of your invest- - ment and changes in its value change the value of "investment unit". - Change in "unit price" over the reporting period gives you rate of re- - turn of your investment, and make TWR less sensitive than IRR to the + TWR represents your investment as an imaginary "unit fund" where + in-flows/ out-flows lead to buying or selling "units" of your invest- + ment and changes in its value change the value of "investment unit". + Change in "unit price" over the reporting period gives you rate of re- + turn of your investment, and make TWR less sensitive than IRR to the effects of cash in-flows and out-flows. References: @@ -8378,43 +8493,52 @@ PART 4: COMMANDS o IRR vs TWR - o Examples of computing IRR and TWR and discussion of the limitations + o Examples of computing IRR and TWR and discussion of the limitations of both metrics stats Show journal and performance statistics. - The stats command displays summary information for the whole journal, - or a matched part of it. With a reporting interval, it shows a report - for each report period. + The stats command shows summary information for the whole journal, or a + matched part of it. With a reporting interval, it shows a report for + each report period. - At the end, it shows (in the terminal) the overall run time and number - of transactions processed per second. Note these are approximate and - will vary based on machine, current load, data size, hledger version, - haskell lib versions, GHC version.. but they may be of interest. The - stats command's run time is similar to that of a single-column balance - report. + The default output is fairly impersonal, though it reveals the main + file name. With -v/--verbose, more details are shown, like file paths, + included files, and commodity names. - Example: + It also shows some run time statistics: - $ hledger stats -f examples/1000x1000x10.journal - Main file : /Users/simon/src/hledger/examples/1000x1000x10.journal - Included files : - Transactions span : 2000-01-01 to 2002-09-27 (1000 days) - Last transaction : 2002-09-26 (6995 days ago) - Transactions : 1000 (1.0 per day) - Transactions last 30 days: 0 (0.0 per day) - Transactions last 7 days : 0 (0.0 per day) - Payees/descriptions : 1000 - Accounts : 1000 (depth 10) - Commodities : 26 (A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P, Q, R, S, T, U, V, W, X, Y, Z) - Market prices : 1000 (A) + o elapsed time + + o throughput: the number of transactions processed per second + + o live: the peak memory in use by the program to do its work + + o alloc: the peak memory allocation from the OS as seen by GHC. Mea- + suring this externally, eg with GNU time, is more accurate; usually + that will be a larger number; sometimes (with swapping?) smaller. + + The stats command's run time is similar to that of a balance report. + + Example: - Run time : 0.12 s - Throughput : 8342 txns/s + $ hledger stats -f examples/1ktxns-1kaccts.journal + Main file : .../1ktxns-1kaccts.journal + Included files : 0 + Txns span : 2000-01-01 to 2002-09-27 (1000 days) + Last txn : 2002-09-26 (7827 days ago) + Txns : 1000 (1.0 per day) + Txns last 30 days : 0 (0.0 per day) + Txns last 7 days : 0 (0.0 per day) + Payees/descriptions : 1000 + Accounts : 1000 (depth 10) + Commodities : 26 + Market prices : 1000 + Runtime stats : 0.12 s elapsed, 8266 txns/s, 4 MB live, 16 MB alloc This command supports the -o/--output-file option (but not -O/--out- - put-format selection). + put-format). tags List the tags used in the journal, or their values. @@ -8957,4 +9081,4 @@ LICENSE SEE ALSO hledger(1), hledger-ui(1), hledger-web(1), ledger(1) -hledger-1.32.99 February 2024 HLEDGER(1) +hledger-1.32.99 March 2024 HLEDGER(1)