diff --git a/hledger/hledger.1 b/hledger/hledger.1 index 5bc10fd99..cb9da176c 100644 --- a/hledger/hledger.1 +++ b/hledger/hledger.1 @@ -4712,6 +4712,59 @@ when parsing numbers (cf Amounts). However if any numbers in the CSV contain digit group marks, such as thousand\-separating commas, you should declare the decimal mark explicitly with this rule, to avoid misparsed numbers. +.SS CSV fields and hledger fields +This can be confusing, so let\[aq]s start with an overview: +.IP \[bu] 2 +\f[B]CSV fields\f[R] are provided by your data file. +They are named by their position in the CSV record, starting with 1. +You can also give them a readable name. +.IP \[bu] 2 +\f[B]hledger fields\f[R] are predefined; \f[CR]date\f[R], +\f[CR]description\f[R], \f[CR]account1\f[R], \f[CR]amount1\f[R], +\f[CR]account2\f[R] are some of them. +They correspond to parts of a transaction\[aq]s journal entry, mostly. +.IP \[bu] 2 +The CSV fields and hledger fields are the only fields you\[aq]ll be +working with; you can\[aq]t define new fields, or variables as in a +programming language. +(But you could add extra CSV fields to the data in preprocessing, before +running the rules.) +.IP \[bu] 2 +For each CSV record, you\[aq]ll assign values to one or more of the +hledger fields to build up a transaction (journal entry). +Values can be static text, CSV field values from the current record, or +a combination of these. +.IP \[bu] 2 +For simple cases, you can give a CSV field the same name as one of the +hledger fields, then its value will be automatically assigned to that +hledger field. +.IP \[bu] 2 +CSV fields can only be read, not written to. +They\[aq]ll be on the right hand side, with a % prefix. +Eg +.RS 2 +.IP \[bu] 2 +testing a CSV field\[aq]s value: \f[CR]if %CSVFIELD ...\f[R] +.IP \[bu] 2 +interpolating its value: \f[CR]HLEDGERFIELD %CSVFIELD\f[R] +.RE +.IP \[bu] 2 +hledger fields can only be written to, not read. +They\[aq]ll be on the left hand side (or in a fields list), with no +prefix. +Eg +.RS 2 +.IP \[bu] 2 +setting the transaction\[aq]s description to a value: +\f[CR]description VALUE\f[R] +.IP \[bu] 2 +setting the transaction\[aq]s description to the second CSV field\[aq]s +value: +.PD 0 +.P +.PD +\f[CR]fields date, description, amount\f[R] +.RE .SS \f[CR]fields\f[R] list .IP .EX @@ -5081,8 +5134,7 @@ The pattern is, as usual in hledger, a POSIX extended regular expression that also supports GNU word boundaries (\f[CR]\[rs]b\f[R], \f[CR]\[rs]B\f[R], \f[CR]\[rs]<\f[R], \f[CR]\[rs]>\f[R]) and nothing else. -If you have trouble with it, see \[dq]Regular expressions\[dq] in the -hledger manual (https://hledger.org/hledger.html#regular\-expressions). +For more details and tips, see Regular expressions in CSV rules below. .SS Multiple matchers When an if block has multiple matchers, each on its own line, .IP \[bu] 2 @@ -5381,6 +5433,55 @@ See: https://hledger.org/cookbook.html#setups\-and\-workflows .IP \[bu] 2 https://plaintextaccounting.org \-> data import/conversion +.SS Regular expressions in CSV rules +Regular expressions in \f[CR]if\f[R] conditions (AKA matchers) are POSIX +extended regular expressions, that also support GNU word boundaries +(\f[CR]\[rs]b\f[R], \f[CR]\[rs]B\f[R], \f[CR]\[rs]<\f[R], +\f[CR]\[rs]>\f[R]), and nothing else. +(For more detail, see Regular expressions.) +.PP +Here are some examples that might be useful in CSV rules: +.IP \[bu] 2 +Is field \[dq]foo\[dq] truly empty ? +\f[CR]if %foo \[ha]$\f[R] +.IP \[bu] 2 +Is it empty or containing only whitespace ? +\f[CR]if %foo \[ha] *$\f[R] +.IP \[bu] 2 +Is it non\-empty ? +\f[CR]if %foo .\f[R] +.IP \[bu] 2 +Does it contain non\-whitespace ? +\f[CR]if %foo [\[ha] ]\f[R] +.PP +Testing the value of numeric fields is a little harder. +You can\[aq]t use hledger queries like \f[CR]amt:0\f[R] or +\f[CR]amt:>10\f[R] in CSV rules. +But you can often achieve the same thing with a regular expression. +.PP +Note the content and layout of number fields in CSV varies, and can +change over time (eg if you switch data providers). +So numeric regexps are always somewhat specific to your particular CSV +data; and it\[aq]s a good idea to make them defensive and robust if you +can. +.PP +Here are some examples: +.IP \[bu] 2 +Does foo contain a non\-zero number ? +\f[CR]if %foo [1\-9]\f[R] +.IP \[bu] 2 +Is it negative ? +\f[CR]if %foo \-\f[R] +.IP \[bu] 2 +Is it non\-negative ? +\f[CR]if ! %foo \-\f[R] +.IP \[bu] 2 +Is it >= 10 ? +\f[CR]if %foo [1\-9][0\-9]+\[rs].\f[R] (assuming a decimal period and no +leading zeros) +.IP \[bu] 2 +Is it >= 10 and < 20 ? +\f[CR]if %foo \[rs]b1[0\-9]\[rs].\f[R] .SS Setting amounts Continuing from amount field above, here are more tips for amount\-setting: @@ -9802,6 +9903,7 @@ Show journal and performance statistics. .IP .EX Flags: + \-1 show a single line of output \-v \-\-verbose show more detailed output \-o \-\-output\-file=FILE write output to FILE. .EE @@ -9810,26 +9912,27 @@ 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 -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. +It also shows some performance statistics: +.IP \[bu] 2 +how long the program ran for +.IP \[bu] 2 +the number of transactions processed per second +.IP \[bu] 2 +the peak live memory in use by the program to do its work +.IP \[bu] 2 +the peak allocated memory as seen by the program .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. +By default, the output is reasonably discreet; it reveals the main file +name, your activity level, and the speed of your machine. .PP -The \f[CR]stats\f[R] command\[aq]s run time is similar to that of a -balance report. +With \f[CR]\-v/\-\-verbose\f[R], more details are shown: the full paths +of all files, and the names of the commodities you work with. +.PP +With \f[CR]\-1\f[R], only one line of output is shown, in a +machine\-friendly tab\-separated format: the program version, the main +journal file name, and the performance stats, +.PP +The run time of \f[CR]stats\f[R] is similar to that of a balance report. .PP Example: .IP @@ -9848,6 +9951,11 @@ Commodities : 26 Market prices : 1000 Runtime stats : 0.12 s elapsed, 8266 txns/s, 4 MB live, 16 MB alloc .EE +.IP +.EX +$ hledger stats \-1 \-f examples/10ktxns\-1kaccts.journal +1.50.99\-g0835a2485\-20251119, mac\-aarch64 10ktxns\-1kaccts.journal 0.66 s elapsed 15244 txns/s 28 MB live 86 MB alloc +.EE .PP This command supports the \-o/\-\-output\-file option (but not \-O/\-\-output\-format). diff --git a/hledger/hledger.info b/hledger/hledger.info index 69857b3dd..56e70b885 100644 --- a/hledger/hledger.info +++ b/hledger/hledger.info @@ -4179,6 +4179,7 @@ https://github.com/simonmichael/hledger/tree/master/examples/csv. * newest-first:: * intra-day-reversed:: * decimal-mark:: +* CSV fields and hledger fields:: * fields list:: * Field assignment:: * Field names:: @@ -4524,7 +4525,7 @@ first, but same-day records are oldest first: intra-day-reversed  -File: hledger.info, Node: decimal-mark, Next: fields list, Prev: intra-day-reversed, Up: CSV +File: hledger.info, Node: decimal-mark, Next: CSV fields and hledger fields, Prev: intra-day-reversed, Up: CSV 9.11 'decimal-mark' =================== @@ -4542,9 +4543,54 @@ should declare the decimal mark explicitly with this rule, to avoid misparsed numbers.  -File: hledger.info, Node: fields list, Next: Field assignment, Prev: decimal-mark, Up: CSV +File: hledger.info, Node: CSV fields and hledger fields, Next: fields list, Prev: decimal-mark, Up: CSV -9.12 'fields' list +9.12 CSV fields and hledger fields +================================== + +This can be confusing, so let's start with an overview: + + * *CSV fields* are provided by your data file. They are named by + their position in the CSV record, starting with 1. You can also + give them a readable name. + + * *hledger fields* are predefined; 'date', 'description', 'account1', + 'amount1', 'account2' are some of them. They correspond to parts + of a transaction's journal entry, mostly. + + * The CSV fields and hledger fields are the only fields you'll be + working with; you can't define new fields, or variables as in a + programming language. (But you could add extra CSV fields to the + data in preprocessing, before running the rules.) + + * For each CSV record, you'll assign values to one or more of the + hledger fields to build up a transaction (journal entry). Values + can be static text, CSV field values from the current record, or a + combination of these. + + * For simple cases, you can give a CSV field the same name as one of + the hledger fields, then its value will be automatically assigned + to that hledger field. + + * CSV fields can only be read, not written to. They'll be on the + right hand side, with a % prefix. Eg + + * testing a CSV field's value: 'if %CSVFIELD ...' + * interpolating its value: 'HLEDGERFIELD %CSVFIELD' + + * hledger fields can only be written to, not read. They'll be on the + left hand side (or in a fields list), with no prefix. Eg + + * setting the transaction's description to a value: 'description + VALUE' + * setting the transaction's description to the second CSV + field's value: + 'fields date, description, amount' + + +File: hledger.info, Node: fields list, Next: Field assignment, Prev: CSV fields and hledger fields, Up: CSV + +9.13 'fields' list ================== fields FIELDNAME1, FIELDNAME2, ... @@ -4589,7 +4635,7 @@ field (and generating a balance assertion).  File: hledger.info, Node: Field assignment, Next: Field names, Prev: fields list, Up: CSV -9.13 Field assignment +9.14 Field assignment ===================== HLEDGERFIELD FIELDVALUE @@ -4623,7 +4669,7 @@ comment note: %somefield - %anotherfield, date: %1  File: hledger.info, Node: Field names, Next: if block, Prev: Field assignment, Up: CSV -9.14 Field names +9.15 Field names ================ Note the two kinds of field names mentioned here, and used only in @@ -4672,7 +4718,7 @@ happens when you assign values to them:  File: hledger.info, Node: date field, Next: date2 field, Up: Field names -9.14.1 date field +9.15.1 date field ----------------- Assigning to 'date' sets the transaction date. @@ -4680,7 +4726,7 @@ Assigning to 'date' sets the transaction date.  File: hledger.info, Node: date2 field, Next: status field, Prev: date field, Up: Field names -9.14.2 date2 field +9.15.2 date2 field ------------------ 'date2' sets the transaction's secondary date, if any. @@ -4688,7 +4734,7 @@ File: hledger.info, Node: date2 field, Next: status field, Prev: date field,  File: hledger.info, Node: status field, Next: code field, Prev: date2 field, Up: Field names -9.14.3 status field +9.15.3 status field ------------------- 'status' sets the transaction's status, if any. @@ -4696,7 +4742,7 @@ File: hledger.info, Node: status field, Next: code field, Prev: date2 field,  File: hledger.info, Node: code field, Next: description field, Prev: status field, Up: Field names -9.14.4 code field +9.15.4 code field ----------------- 'code' sets the transaction's code, if any. @@ -4704,7 +4750,7 @@ File: hledger.info, Node: code field, Next: description field, Prev: status f  File: hledger.info, Node: description field, Next: comment field, Prev: code field, Up: Field names -9.14.5 description field +9.15.5 description field ------------------------ 'description' sets the transaction's description, if any. @@ -4712,7 +4758,7 @@ File: hledger.info, Node: description field, Next: comment field, Prev: code  File: hledger.info, Node: comment field, Next: account field, Prev: description field, Up: Field names -9.14.6 comment field +9.15.6 comment field -------------------- 'comment' sets the transaction's comment, if any. @@ -4730,7 +4776,7 @@ or a year-less date, will be ignored.  File: hledger.info, Node: account field, Next: amount field, Prev: comment field, Up: Field names -9.14.7 account field +9.15.7 account field -------------------- Assigning to 'accountN', where N is 1 to 99, sets the account name of @@ -4748,7 +4794,7 @@ or "income:unknown").  File: hledger.info, Node: amount field, Next: currency field, Prev: account field, Up: Field names -9.14.8 amount field +9.15.8 amount field ------------------- There are several ways to set posting amounts from CSV, useful in @@ -4806,7 +4852,7 @@ different situations.  File: hledger.info, Node: currency field, Next: balance field, Prev: amount field, Up: Field names -9.14.9 currency field +9.15.9 currency field --------------------- 'currency' sets a currency symbol, to be prepended to all postings' @@ -4819,7 +4865,7 @@ amount.  File: hledger.info, Node: balance field, Prev: currency field, Up: Field names -9.14.10 balance field +9.15.10 balance field --------------------- 'balanceN' sets a balance assertion amount (or if the posting amount is @@ -4837,7 +4883,7 @@ and currency.  File: hledger.info, Node: if block, Next: Matchers, Prev: Field names, Up: CSV -9.15 'if' block +9.16 'if' block =============== Rules can be applied conditionally, depending on patterns in the CSV @@ -4892,7 +4938,7 @@ if ,,,,  File: hledger.info, Node: Matchers, Next: if table, Prev: if block, Up: CSV -9.16 Matchers +9.17 Matchers ============= There are two kinds of matcher: @@ -4932,9 +4978,8 @@ will match if "whole foods" is NOT present. _Added in 1.32._ The pattern is, as usual in hledger, a POSIX extended regular expression that also supports GNU word boundaries ('\b', '\B', '\<', -'\>') and nothing else. If you have trouble with it, see "Regular -expressions" in the hledger manual -(https://hledger.org/hledger.html#regular-expressions). +'\>') and nothing else. For more details and tips, see Regular +expressions in CSV rules below. * Menu: @@ -4944,7 +4989,7 @@ expressions" in the hledger manual  File: hledger.info, Node: Multiple matchers, Next: Match groups, Up: Matchers -9.16.1 Multiple matchers +9.17.1 Multiple matchers ------------------------ When an if block has multiple matchers, each on its own line, @@ -4963,7 +5008,7 @@ and the date field contains "2025-01-01". _Added in 1.42._  File: hledger.info, Node: Match groups, Prev: Multiple matchers, Up: Matchers -9.16.2 Match groups +9.17.2 Match groups ------------------- _Added in 1.32_ @@ -4991,7 +5036,7 @@ if %account1 liabilities:family:(expenses:.*)  File: hledger.info, Node: if table, Next: balance-type, Prev: Matchers, Up: CSV -9.17 'if' table +9.18 'if' table =============== "if tables" are an alternative to if blocks; they can express many @@ -5052,7 +5097,7 @@ atm transaction fee,expenses:business:banking,deductible? check it  File: hledger.info, Node: balance-type, Next: include, Prev: if table, Up: CSV -9.18 'balance-type' +9.19 'balance-type' =================== Balance assertions generated by assigning to balanceN are of the simple @@ -5075,7 +5120,7 @@ balance-type ==*  File: hledger.info, Node: include, Next: Working with CSV, Prev: balance-type, Up: CSV -9.19 'include' +9.20 'include' ============== include RULESFILE @@ -5098,7 +5143,7 @@ include categorisation.rules  File: hledger.info, Node: Working with CSV, Next: CSV rules examples, Prev: include, Up: CSV -9.20 Working with CSV +9.21 Working with CSV ===================== Some tips: @@ -5113,6 +5158,7 @@ Some tips: * Reading files specified by rule:: * Valid transactions:: * Deduplicating importing:: +* Regular expressions in CSV rules:: * Setting amounts:: * Amount signs:: * Setting currency/commodity:: @@ -5124,7 +5170,7 @@ Some tips:  File: hledger.info, Node: Rapid feedback, Next: Valid CSV, Up: Working with CSV -9.20.1 Rapid feedback +9.21.1 Rapid feedback --------------------- It's a good idea to get rapid feedback while creating/troubleshooting @@ -5140,7 +5186,7 @@ output.  File: hledger.info, Node: Valid CSV, Next: File Extension, Prev: Rapid feedback, Up: Working with CSV -9.20.2 Valid CSV +9.21.2 Valid CSV ---------------- Note that hledger will only accept valid CSV conforming to RFC 4180, and @@ -5161,7 +5207,7 @@ permissive CSV parser like python's csv lib.  File: hledger.info, Node: File Extension, Next: Reading CSV from standard input, Prev: Valid CSV, Up: Working with CSV -9.20.3 File Extension +9.21.3 File Extension --------------------- To help hledger choose the CSV file reader and show the right error @@ -5181,7 +5227,7 @@ rule if needed.  File: hledger.info, Node: Reading CSV from standard input, Next: Reading multiple CSV files, Prev: File Extension, Up: Working with CSV -9.20.4 Reading CSV from standard input +9.21.4 Reading CSV from standard input -------------------------------------- You'll need the file format prefix when reading CSV from stdin also, @@ -5192,7 +5238,7 @@ $ cat foo.dat | hledger -f ssv:- print  File: hledger.info, Node: Reading multiple CSV files, Next: Reading files specified by rule, Prev: Reading CSV from standard input, Up: Working with CSV -9.20.5 Reading multiple CSV files +9.21.5 Reading multiple CSV files --------------------------------- If you use multiple '-f' options to read multiple CSV files at once, @@ -5203,7 +5249,7 @@ will be used for all the CSV files.  File: hledger.info, Node: Reading files specified by rule, Next: Valid transactions, Prev: Reading multiple CSV files, Up: Working with CSV -9.20.6 Reading files specified by rule +9.21.6 Reading files specified by rule -------------------------------------- Instead of specifying a CSV file in the command line, you can specify a @@ -5232,7 +5278,7 @@ most recent.  File: hledger.info, Node: Valid transactions, Next: Deduplicating importing, Prev: Reading files specified by rule, Up: Working with CSV -9.20.7 Valid transactions +9.21.7 Valid transactions ------------------------- After reading a CSV file, hledger post-processes and validates the @@ -5249,9 +5295,9 @@ assertions generated from CSV right away, pipe into another hledger: $ hledger -f file.csv print | hledger -f- print  -File: hledger.info, Node: Deduplicating importing, Next: Setting amounts, Prev: Valid transactions, Up: Working with CSV +File: hledger.info, Node: Deduplicating importing, Next: Regular expressions in CSV rules, Prev: Valid transactions, Up: Working with CSV -9.20.8 Deduplicating, importing +9.21.8 Deduplicating, importing ------------------------------- When you download a CSV file periodically, eg to get your latest bank @@ -5279,10 +5325,46 @@ CSV data. See: * https://plaintextaccounting.org -> data import/conversion  -File: hledger.info, Node: Setting amounts, Next: Amount signs, Prev: Deduplicating importing, Up: Working with CSV +File: hledger.info, Node: Regular expressions in CSV rules, Next: Setting amounts, Prev: Deduplicating importing, Up: Working with CSV -9.20.9 Setting amounts ----------------------- +9.21.9 Regular expressions in CSV rules +--------------------------------------- + +Regular expressions in 'if' conditions (AKA matchers) are POSIX extended +regular expressions, that also support GNU word boundaries ('\b', '\B', +'\<', '\>'), and nothing else. (For more detail, see Regular +expressions.) + + Here are some examples that might be useful in CSV rules: + + * Is field "foo" truly empty ? 'if %foo ^$' + * Is it empty or containing only whitespace ? 'if %foo ^ *$' + * Is it non-empty ? 'if %foo .' + * Does it contain non-whitespace ? 'if %foo [^ ]' + + Testing the value of numeric fields is a little harder. You can't +use hledger queries like 'amt:0' or 'amt:>10' in CSV rules. But you can +often achieve the same thing with a regular expression. + + Note the content and layout of number fields in CSV varies, and can +change over time (eg if you switch data providers). So numeric regexps +are always somewhat specific to your particular CSV data; and it's a +good idea to make them defensive and robust if you can. + + Here are some examples: + + * Does foo contain a non-zero number ? 'if %foo [1-9]' + * Is it negative ? 'if %foo -' + * Is it non-negative ? 'if ! %foo -' + * Is it >= 10 ? 'if %foo [1-9][0-9]+\.' (assuming a decimal period + and no leading zeros) + * Is it >= 10 and < 20 ? 'if %foo \b1[0-9]\.' + + +File: hledger.info, Node: Setting amounts, Next: Amount signs, Prev: Regular expressions in CSV rules, Up: Working with CSV + +9.21.10 Setting amounts +----------------------- Continuing from amount field above, here are more tips for amount-setting: @@ -5348,7 +5430,7 @@ amount-setting:  File: hledger.info, Node: Amount signs, Next: Setting currency/commodity, Prev: Setting amounts, Up: Working with CSV -9.20.10 Amount signs +9.21.11 Amount signs -------------------- There is some special handling making it easier to parse and to reverse @@ -5378,7 +5460,7 @@ its absolute value, ie discard its sign.  File: hledger.info, Node: Setting currency/commodity, Next: Amount decimal places, Prev: Amount signs, Up: Working with CSV -9.20.11 Setting currency/commodity +9.21.12 Setting currency/commodity ---------------------------------- If the currency/commodity symbol is included in the CSV's amount @@ -5426,7 +5508,7 @@ that would trigger the prepending effect, which we don't want here.  File: hledger.info, Node: Amount decimal places, Next: Referencing other fields, Prev: Setting currency/commodity, Up: Working with CSV -9.20.12 Amount decimal places +9.21.13 Amount decimal places ----------------------------- When you are reading CSV data, eg with a command like 'hledger -f @@ -5455,7 +5537,7 @@ want, add a 'commodity' directive to specify them.  File: hledger.info, Node: Referencing other fields, Next: How CSV rules are evaluated, Prev: Amount decimal places, Up: Working with CSV -9.20.13 Referencing other fields +9.21.14 Referencing other fields -------------------------------- In field assignments, you can interpolate only CSV fields, not hledger @@ -5492,7 +5574,7 @@ if something  File: hledger.info, Node: How CSV rules are evaluated, Next: Well factored rules, Prev: Referencing other fields, Up: Working with CSV -9.20.14 How CSV rules are evaluated +9.21.15 How CSV rules are evaluated ----------------------------------- Here's how to think of CSV rules being evaluated. If you get a @@ -5552,7 +5634,7 @@ hledger command the user specified.  File: hledger.info, Node: Well factored rules, Prev: How CSV rules are evaluated, Up: Working with CSV -9.20.15 Well factored rules +9.21.16 Well factored rules --------------------------- Some things than can help reduce duplication and complexity in rules @@ -5568,7 +5650,7 @@ files:  File: hledger.info, Node: CSV rules examples, Prev: Working with CSV, Up: CSV -9.21 CSV rules examples +9.22 CSV rules examples ======================= * Menu: @@ -5581,7 +5663,7 @@ File: hledger.info, Node: CSV rules examples, Prev: Working with CSV, Up: CSV  File: hledger.info, Node: Bank of Ireland, Next: Coinbase, Up: CSV rules examples -9.21.1 Bank of Ireland +9.22.1 Bank of Ireland ---------------------- Here's a CSV with two amount fields (Debit and Credit), and a balance @@ -5634,7 +5716,7 @@ imported into a journal file.  File: hledger.info, Node: Coinbase, Next: Amazon, Prev: Bank of Ireland, Up: CSV rules examples -9.21.2 Coinbase +9.22.2 Coinbase --------------- A simple example with some CSV from Coinbase. The spot price is @@ -5661,7 +5743,7 @@ $ hledger print -f coinbase.csv  File: hledger.info, Node: Amazon, Next: Paypal, Prev: Coinbase, Up: CSV rules examples -9.21.3 Amazon +9.22.3 Amazon ------------- Here we convert amazon.com order history, and use an if block to @@ -5719,7 +5801,7 @@ $ hledger -f amazon-orders.csv print  File: hledger.info, Node: Paypal, Prev: Amazon, Up: CSV rules examples -9.21.4 Paypal +9.22.4 Paypal ------------- Here's a real-world rules file for (customised) Paypal CSV, with some @@ -9440,6 +9522,7 @@ File: hledger.info, Node: stats, Next: tags, Prev: prices, Up: Basic report Show journal and performance statistics. Flags: + -1 show a single line of output -v --verbose show more detailed output -o --output-file=FILE write output to FILE. @@ -9447,22 +9530,24 @@ Flags: a matched part of it. With a reporting interval, it shows a report for each report period. - The default output is fairly impersonal, though it reveals the main -file name. With '-v/--verbose', more details are shown, like file -paths, included files, and commodity names. + It also shows some performance statistics: - It also shows some run time statistics: + * how long the program ran for + * the number of transactions processed per second + * the peak live memory in use by the program to do its work + * the peak allocated memory as seen by the program - * 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. + By default, the output is reasonably discreet; it reveals the main +file name, your activity level, and the speed of your machine. - The 'stats' command's run time is similar to that of a balance -report. + With '-v/--verbose', more details are shown: the full paths of all +files, and the names of the commodities you work with. + + With '-1', only one line of output is shown, in a machine-friendly +tab-separated format: the program version, the main journal file name, +and the performance stats, + + The run time of 'stats' is similar to that of a balance report. Example: @@ -9480,6 +9565,9 @@ Commodities : 26 Market prices : 1000 Runtime stats : 0.12 s elapsed, 8266 txns/s, 4 MB live, 16 MB alloc +$ hledger stats -1 -f examples/10ktxns-1kaccts.journal +1.50.99-g0835a2485-20251119, mac-aarch64 10ktxns-1kaccts.journal 0.66 s elapsed 15244 txns/s 28 MB live 86 MB alloc + This command supports the -o/-output-file option (but not -O/-output-format). @@ -13366,270 +13454,272 @@ Node: Virtual postings149983 Node: Other Ledger directives151607 Node: Other cost/lot notations152369 Node: CSV155210 -Node: CSV rules cheatsheet157376 -Node: source159674 -Node: Data cleaning / data generating commands161078 -Node: archive162977 -Node: encoding163905 -Node: separator164948 -Node: skip165601 -Node: date-format166251 -Node: timezone167196 -Node: newest-first168322 -Node: intra-day-reversed169035 -Node: decimal-mark169637 -Node: fields list170117 -Node: Field assignment171925 -Node: Field names173144 -Node: date field174476 -Node: date2 field174640 -Node: status field174835 -Node: code field175025 -Node: description field175213 -Node: comment field175430 -Node: account field175987 -Node: amount field176705 -Node: currency field179544 -Node: balance field179952 -Node: if block180475 -Node: Matchers182002 -Node: Multiple matchers183992 -Node: Match groups184800 -Node: if table185693 -Node: balance-type187756 -Node: include188583 -Node: Working with CSV189152 -Node: Rapid feedback189704 -Node: Valid CSV190287 -Node: File Extension191163 -Node: Reading CSV from standard input191898 -Node: Reading multiple CSV files192284 -Node: Reading files specified by rule192760 -Node: Valid transactions194157 -Node: Deduplicating importing194982 -Node: Setting amounts196211 -Node: Amount signs198738 -Node: Setting currency/commodity199803 -Node: Amount decimal places201179 -Node: Referencing other fields202436 -Node: How CSV rules are evaluated203544 -Node: Well factored rules206261 -Node: CSV rules examples206751 -Node: Bank of Ireland206949 -Node: Coinbase208546 -Node: Amazon209729 -Node: Paypal211571 -Node: Timeclock219321 -Node: Timedot223374 -Node: Timedot examples226851 -Node: PART 3 REPORTING CONCEPTS229128 -Node: Time periods229292 -Node: Report start & end date229565 -Node: Smart dates231041 -Node: Report intervals233164 -Node: Date adjustments233738 -Node: Start date adjustment233958 -Node: End date adjustment234861 -Node: Period headings235642 -Node: Period expressions236575 -Node: Period expressions with a report interval238480 -Node: More complex report intervals238928 -Node: Multiple weekday intervals241044 -Node: Depth242055 -Node: Combining depth options243041 -Node: Queries243991 -Node: Query types246663 -Node: acct query247038 -Node: amt query247349 -Node: code query248046 -Node: cur query248241 -Node: desc query248847 -Node: date query249030 -Node: date2 query249426 -Node: depth query249717 -Node: note query250053 -Node: payee query250319 -Node: real query250600 -Node: status query250805 -Node: type query251045 -Node: tag query251578 -Node: Negative queries252207 -Node: not query252389 -Node: Space-separated queries252676 -Node: Boolean queries253364 -Node: expr query254682 -Node: any query255362 -Node: all query255815 -Node: Queries and command options256397 -Node: Queries and account aliases256845 -Node: Queries and valuation257170 -Node: Pivoting257532 -Node: Generating data259815 -Node: Forecasting261615 -Node: --forecast262271 -Node: Inspecting forecast transactions263372 -Node: Forecast reports264705 -Node: Forecast tags265814 -Node: Forecast period in detail266434 -Node: Forecast troubleshooting267522 -Node: Budgeting268593 -Node: Amount formatting269153 -Node: Commodity display style269397 -Node: Rounding271238 -Node: Trailing decimal marks271843 -Node: Amount parseability272776 -Node: Cost reporting274385 -Node: Recording costs275216 -Node: Reporting at cost276943 -Node: Equity conversion postings277708 -Node: Inferring equity conversion postings280353 -Node: Combining costs and equity conversion postings281495 -Node: Requirements for detecting equity conversion postings282720 -Node: Infer cost and equity by default ?284242 -Node: Value reporting284679 -Node: -X Value in specified commodity285637 -Node: -V Value in default commoditys286497 -Node: Valuation date287234 -Node: Finding market price288066 -Node: --infer-market-prices market prices from transactions289446 -Node: Valuation commodity292490 -Node: --value Flexible valuation293923 -Node: Valuation examples295766 -Node: Interaction of valuation and queries297910 -Node: Effect of valuation on reports298627 -Node: PART 4 COMMANDS306477 -Node: Help commands309266 -Node: commands309452 -Node: demo309660 -Node: help310753 -Node: User interface commands312458 -Node: repl312669 -Node: Examples314933 -Node: run315491 -Node: Examples 2317906 -Node: ui318930 -Node: web319067 -Node: Data entry commands319195 -Node: add319456 -Node: add and balance assertions322030 -Node: add and balance assignments322604 -Node: import323297 -Node: Import dry run324376 -Node: Overlap detection325324 -Node: First import328210 -Node: Importing balance assignments329405 -Node: Import and commodity styles330460 -Node: Import archiving330894 -Node: Import special cases331719 -Node: Deduplication331937 -Node: Varying file name332428 -Node: Multiple versions332812 -Node: Basic report commands333919 -Node: accounts334220 -Node: codes336732 -Node: commodities337754 -Node: descriptions338762 -Node: files339222 -Node: notes339519 -Node: payees340031 -Node: prices341188 -Node: stats342080 -Node: tags343821 -Node: Standard report commands345645 -Node: print345950 -Node: print amount explicitness348681 -Node: print alignment349619 -Node: print amount style349933 -Node: print parseability351163 -Node: print other features352440 -Node: print output format353402 -Node: aregister356687 -Node: aregister and posting dates361152 -Node: register362053 -Node: Custom register output369293 -Node: balancesheet370478 -Node: balancesheetequity375443 -Node: cashflow380778 -Node: incomestatement385591 -Node: Advanced report commands390440 -Node: balance390648 -Node: balance features396069 -Node: Simple balance report398172 -Node: Balance report line format399982 -Node: Filtered balance report402342 -Node: List or tree mode402861 -Node: Depth limiting404374 -Node: Dropping top-level accounts405141 -Node: Showing declared accounts405651 -Node: Sorting by amount406381 -Node: Percentages407235 -Node: Multi-period balance report407942 -Node: Balance change end balance410694 -Node: Balance report modes412331 -Node: Calculation mode413010 -Node: Accumulation mode413714 -Node: Valuation mode414815 -Node: Combining balance report modes416159 -Node: Budget report418189 -Node: Using the budget report420489 -Node: Budget date surprises422765 -Node: Selecting budget goals424129 -Node: Budgeting vs forecasting425077 -Node: Balance report layout426754 -Node: Wide layout427959 -Node: Tall layout430364 -Node: Bare layout431670 -Node: Tidy layout433734 -Node: Balance report output435278 -Node: Some useful balance reports436052 -Node: roi437312 -Node: Spaces and special characters in --inv and --pnl439559 -Node: Semantics of --inv and --pnl440285 -Node: IRR and TWR explained442372 -Node: Chart commands445783 -Node: activity445964 -Node: Data generation commands446461 -Node: close446667 -Node: close --clopen449732 -Node: close --close451628 -Node: close --open452152 -Node: close --assert452402 -Node: close --assign452729 -Node: close --retain453408 -Node: close customisation454265 -Node: close and balance assertions455943 -Node: close examples457465 -Node: Retain earnings457702 -Node: Migrate balances to a new file458205 -Node: More detailed close examples459567 -Node: rewrite459789 -Node: Re-write rules in a file462349 -Node: Diff output format463650 -Node: rewrite vs print --auto464920 -Node: Maintenance commands465634 -Node: check465853 -Node: Basic checks466936 -Node: Strict checks468002 -Node: Other checks468875 -Node: Custom checks470577 -Node: diff471016 -Node: setup472224 -Node: test475091 -Node: PART 5 COMMON TASKS475994 -Node: Getting help476443 -Node: Constructing command lines477344 -Node: Starting a journal file478209 -Node: Setting LEDGER_FILE479613 -Node: Set LEDGER_FILE on unix479901 -Node: Set LEDGER_FILE on mac480418 -Node: Set LEDGER_FILE on Windows481146 -Node: Setting opening balances482869 -Node: Recording transactions486211 -Node: Reconciling486956 -Node: Reporting489365 -Node: Migrating to a new file493499 -Node: BUGS493955 -Node: Troubleshooting494781 +Node: CSV rules cheatsheet157410 +Node: source159708 +Node: Data cleaning / data generating commands161112 +Node: archive163011 +Node: encoding163939 +Node: separator164982 +Node: skip165635 +Node: date-format166285 +Node: timezone167230 +Node: newest-first168356 +Node: intra-day-reversed169069 +Node: decimal-mark169671 +Node: CSV fields and hledger fields170169 +Node: fields list172045 +Node: Field assignment173870 +Node: Field names175089 +Node: date field176421 +Node: date2 field176585 +Node: status field176780 +Node: code field176970 +Node: description field177158 +Node: comment field177375 +Node: account field177932 +Node: amount field178650 +Node: currency field181489 +Node: balance field181897 +Node: if block182420 +Node: Matchers183947 +Node: Multiple matchers185875 +Node: Match groups186683 +Node: if table187576 +Node: balance-type189639 +Node: include190466 +Node: Working with CSV191035 +Node: Rapid feedback191624 +Node: Valid CSV192207 +Node: File Extension193083 +Node: Reading CSV from standard input193818 +Node: Reading multiple CSV files194204 +Node: Reading files specified by rule194680 +Node: Valid transactions196077 +Node: Deduplicating importing196902 +Node: Regular expressions in CSV rules198148 +Node: Setting amounts199640 +Node: Amount signs202178 +Node: Setting currency/commodity203243 +Node: Amount decimal places204619 +Node: Referencing other fields205876 +Node: How CSV rules are evaluated206984 +Node: Well factored rules209701 +Node: CSV rules examples210191 +Node: Bank of Ireland210389 +Node: Coinbase211986 +Node: Amazon213169 +Node: Paypal215011 +Node: Timeclock222761 +Node: Timedot226814 +Node: Timedot examples230291 +Node: PART 3 REPORTING CONCEPTS232568 +Node: Time periods232732 +Node: Report start & end date233005 +Node: Smart dates234481 +Node: Report intervals236604 +Node: Date adjustments237178 +Node: Start date adjustment237398 +Node: End date adjustment238301 +Node: Period headings239082 +Node: Period expressions240015 +Node: Period expressions with a report interval241920 +Node: More complex report intervals242368 +Node: Multiple weekday intervals244484 +Node: Depth245495 +Node: Combining depth options246481 +Node: Queries247431 +Node: Query types250103 +Node: acct query250478 +Node: amt query250789 +Node: code query251486 +Node: cur query251681 +Node: desc query252287 +Node: date query252470 +Node: date2 query252866 +Node: depth query253157 +Node: note query253493 +Node: payee query253759 +Node: real query254040 +Node: status query254245 +Node: type query254485 +Node: tag query255018 +Node: Negative queries255647 +Node: not query255829 +Node: Space-separated queries256116 +Node: Boolean queries256804 +Node: expr query258122 +Node: any query258802 +Node: all query259255 +Node: Queries and command options259837 +Node: Queries and account aliases260285 +Node: Queries and valuation260610 +Node: Pivoting260972 +Node: Generating data263255 +Node: Forecasting265055 +Node: --forecast265711 +Node: Inspecting forecast transactions266812 +Node: Forecast reports268145 +Node: Forecast tags269254 +Node: Forecast period in detail269874 +Node: Forecast troubleshooting270962 +Node: Budgeting272033 +Node: Amount formatting272593 +Node: Commodity display style272837 +Node: Rounding274678 +Node: Trailing decimal marks275283 +Node: Amount parseability276216 +Node: Cost reporting277825 +Node: Recording costs278656 +Node: Reporting at cost280383 +Node: Equity conversion postings281148 +Node: Inferring equity conversion postings283793 +Node: Combining costs and equity conversion postings284935 +Node: Requirements for detecting equity conversion postings286160 +Node: Infer cost and equity by default ?287682 +Node: Value reporting288119 +Node: -X Value in specified commodity289077 +Node: -V Value in default commoditys289937 +Node: Valuation date290674 +Node: Finding market price291506 +Node: --infer-market-prices market prices from transactions292886 +Node: Valuation commodity295930 +Node: --value Flexible valuation297363 +Node: Valuation examples299206 +Node: Interaction of valuation and queries301350 +Node: Effect of valuation on reports302067 +Node: PART 4 COMMANDS309917 +Node: Help commands312706 +Node: commands312892 +Node: demo313100 +Node: help314193 +Node: User interface commands315898 +Node: repl316109 +Node: Examples318373 +Node: run318931 +Node: Examples 2321346 +Node: ui322370 +Node: web322507 +Node: Data entry commands322635 +Node: add322896 +Node: add and balance assertions325470 +Node: add and balance assignments326044 +Node: import326737 +Node: Import dry run327816 +Node: Overlap detection328764 +Node: First import331650 +Node: Importing balance assignments332845 +Node: Import and commodity styles333900 +Node: Import archiving334334 +Node: Import special cases335159 +Node: Deduplication335377 +Node: Varying file name335868 +Node: Multiple versions336252 +Node: Basic report commands337359 +Node: accounts337660 +Node: codes340172 +Node: commodities341194 +Node: descriptions342202 +Node: files342662 +Node: notes342959 +Node: payees343471 +Node: prices344628 +Node: stats345520 +Node: tags347578 +Node: Standard report commands349402 +Node: print349707 +Node: print amount explicitness352438 +Node: print alignment353376 +Node: print amount style353690 +Node: print parseability354920 +Node: print other features356197 +Node: print output format357159 +Node: aregister360444 +Node: aregister and posting dates364909 +Node: register365810 +Node: Custom register output373050 +Node: balancesheet374235 +Node: balancesheetequity379200 +Node: cashflow384535 +Node: incomestatement389348 +Node: Advanced report commands394197 +Node: balance394405 +Node: balance features399826 +Node: Simple balance report401929 +Node: Balance report line format403739 +Node: Filtered balance report406099 +Node: List or tree mode406618 +Node: Depth limiting408131 +Node: Dropping top-level accounts408898 +Node: Showing declared accounts409408 +Node: Sorting by amount410138 +Node: Percentages410992 +Node: Multi-period balance report411699 +Node: Balance change end balance414451 +Node: Balance report modes416088 +Node: Calculation mode416767 +Node: Accumulation mode417471 +Node: Valuation mode418572 +Node: Combining balance report modes419916 +Node: Budget report421946 +Node: Using the budget report424246 +Node: Budget date surprises426522 +Node: Selecting budget goals427886 +Node: Budgeting vs forecasting428834 +Node: Balance report layout430511 +Node: Wide layout431716 +Node: Tall layout434121 +Node: Bare layout435427 +Node: Tidy layout437491 +Node: Balance report output439035 +Node: Some useful balance reports439809 +Node: roi441069 +Node: Spaces and special characters in --inv and --pnl443316 +Node: Semantics of --inv and --pnl444042 +Node: IRR and TWR explained446129 +Node: Chart commands449540 +Node: activity449721 +Node: Data generation commands450218 +Node: close450424 +Node: close --clopen453489 +Node: close --close455385 +Node: close --open455909 +Node: close --assert456159 +Node: close --assign456486 +Node: close --retain457165 +Node: close customisation458022 +Node: close and balance assertions459700 +Node: close examples461222 +Node: Retain earnings461459 +Node: Migrate balances to a new file461962 +Node: More detailed close examples463324 +Node: rewrite463546 +Node: Re-write rules in a file466106 +Node: Diff output format467407 +Node: rewrite vs print --auto468677 +Node: Maintenance commands469391 +Node: check469610 +Node: Basic checks470693 +Node: Strict checks471759 +Node: Other checks472632 +Node: Custom checks474334 +Node: diff474773 +Node: setup475981 +Node: test478848 +Node: PART 5 COMMON TASKS479751 +Node: Getting help480200 +Node: Constructing command lines481101 +Node: Starting a journal file481966 +Node: Setting LEDGER_FILE483370 +Node: Set LEDGER_FILE on unix483658 +Node: Set LEDGER_FILE on mac484175 +Node: Set LEDGER_FILE on Windows484903 +Node: Setting opening balances486626 +Node: Recording transactions489968 +Node: Reconciling490713 +Node: Reporting493122 +Node: Migrating to a new file497256 +Node: BUGS497712 +Node: Troubleshooting498538  End Tag Table diff --git a/hledger/hledger.txt b/hledger/hledger.txt index bd15af21e..66477a5e1 100644 --- a/hledger/hledger.txt +++ b/hledger/hledger.txt @@ -3614,23 +3614,64 @@ CSV should declare the decimal mark explicitly with this rule, to avoid misparsed numbers. + CSV fields and hledger fields + This can be confusing, so let's start with an overview: + + o CSV fields are provided by your data file. They are named by their + position in the CSV record, starting with 1. You can also give them + a readable name. + + o hledger fields are predefined; date, description, account1, amount1, + account2 are some of them. They correspond to parts of a transac- + tion's journal entry, mostly. + + o The CSV fields and hledger fields are the only fields you'll be work- + ing with; you can't define new fields, or variables as in a program- + ming language. (But you could add extra CSV fields to the data in + preprocessing, before running the rules.) + + o For each CSV record, you'll assign values to one or more of the + hledger fields to build up a transaction (journal entry). Values can + be static text, CSV field values from the current record, or a combi- + nation of these. + + o For simple cases, you can give a CSV field the same name as one of + the hledger fields, then its value will be automatically assigned to + that hledger field. + + o CSV fields can only be read, not written to. They'll be on the right + hand side, with a % prefix. Eg + + o testing a CSV field's value: if %CSVFIELD ... + + o interpolating its value: HLEDGERFIELD %CSVFIELD + + o hledger fields can only be written to, not read. They'll be on the + left hand side (or in a fields list), with no prefix. Eg + + o setting the transaction's description to a value: description VALUE + + o setting the transaction's description to the second CSV field's + value: + fields date, description, amount + fields list fields FIELDNAME1, FIELDNAME2, ... A fields list (the word fields followed by comma-separated field names) is optional, but convenient. It does two things: - 1. It names the CSV field in each column. This can be convenient if - you are referencing them in other rules, so you can say %SomeField + 1. It names the CSV field in each column. This can be convenient if + you are referencing them in other rules, so you can say %SomeField instead of remembering %13. - 2. Whenever you use one of the special hledger field names (described - below), it assigns the CSV value in this position to that hledger - field. This is the quickest way to populate hledger's fields and + 2. Whenever you use one of the special hledger field names (described + below), it assigns the CSV value in this position to that hledger + field. This is the quickest way to populate hledger's fields and build a transaction. - Here's an example that says "use the 1st, 2nd and 4th fields as the - transaction's date, description and amount; name the last two fields + Here's an example that says "use the 1st, 2nd and 4th fields as the + transaction's date, description and amount; name the last two fields for later reference; and ignore the others": fields date, description, , amount, , , somefield, anotherfield @@ -3640,35 +3681,35 @@ CSV o There must be least two items in the list (at least one comma). - o Field names may not contain spaces. Spaces before/after field names + o Field names may not contain spaces. Spaces before/after field names are optional. o Field names may contain _ (underscore) or - (hyphen). - o Fields you don't care about can be given a dummy name or an empty + o Fields you don't care about can be given a dummy name or an empty name. - If the CSV contains column headings, it's convenient to use these for - your field names, suitably modified (eg lower-cased with spaces re- + If the CSV contains column headings, it's convenient to use these for + your field names, suitably modified (eg lower-cased with spaces re- placed by underscores). - Sometimes you may want to alter a CSV field name to avoid assigning to - a hledger field with the same name. Eg you could call the CSV's "bal- - ance" field balance_ to avoid directly setting hledger's balance field + Sometimes you may want to alter a CSV field name to avoid assigning to + a hledger field with the same name. Eg you could call the CSV's "bal- + ance" field balance_ to avoid directly setting hledger's balance field (and generating a balance assertion). Field assignment HLEDGERFIELD FIELDVALUE - Field assignments are the more flexible way to assign CSV values to + Field assignments are the more flexible way to assign CSV values to hledger fields. They can be used instead of or in addition to a fields list (see above). - To assign a value to a hledger field, write the field name (any of the - standard hledger field/pseudo-field names, defined below), a space, - followed by a text value on the same line. This text value may inter- - polate CSV fields, referenced either by their 1-based position in the - CSV record (%N) or by the name they were given in the fields list + To assign a value to a hledger field, write the field name (any of the + standard hledger field/pseudo-field names, defined below), a space, + followed by a text value on the same line. This text value may inter- + polate CSV fields, referenced either by their 1-based position in the + CSV record (%N) or by the name they were given in the fields list (%CSVFIELD), and regular expression match groups (\N). Some examples: @@ -3681,26 +3722,26 @@ CSV Tips: - o Interpolation strips outer whitespace (so a CSV value like " 1 " be- + o Interpolation strips outer whitespace (so a CSV value like " 1 " be- comes 1 when interpolated) (#1051). - o Interpolations always refer to a CSV field - you can't interpolate a + o Interpolations always refer to a CSV field - you can't interpolate a hledger field. (See Referencing other fields below). Field names - Note the two kinds of field names mentioned here, and used only in + Note the two kinds of field names mentioned here, and used only in hledger CSV rules files: - 1. CSV field names (CSVFIELD in these docs): you can optionally name - the CSV columns for easy reference (since hledger doesn't yet auto- + 1. CSV field names (CSVFIELD in these docs): you can optionally name + the CSV columns for easy reference (since hledger doesn't yet auto- matically recognise column headings in a CSV file), by writing arbi- trary names in a fields list, eg: fields When, What, Some_Id, Net, Total, Foo, Bar - 2. Special hledger field names (HLEDGERFIELD in these docs): you must - set at least some of these to generate the hledger transaction from - a CSV record, by writing them as the left hand side of a field as- + 2. Special hledger field names (HLEDGERFIELD in these docs): you must + set at least some of these to generate the hledger transaction from + a CSV record, by writing them as the left hand side of a field as- signment, eg: date %When @@ -3715,7 +3756,7 @@ CSV currency $ comment %Foo %Bar - Here are all the special hledger field names available, and what hap- + Here are all the special hledger field names available, and what hap- pens when you assign values to them: date field @@ -3738,7 +3779,7 @@ CSV commentN, where N is a number, sets the Nth posting's comment. - You can assign multi-line comments by writing literal \n in the code. + You can assign multi-line comments by writing literal \n in the code. A comment starting with \n will begin on a new line. Comments can contain tags, as usual. @@ -3750,99 +3791,99 @@ CSV Assigning to accountN, where N is 1 to 99, sets the account name of the Nth posting, and causes that posting to be generated. - Most often there are two postings, so you'll want to set account1 and - account2. Typically account1 is associated with the CSV file, and is - set once with a top-level assignment, while account2 is set based on + Most often there are two postings, so you'll want to set account1 and + account2. Typically account1 is associated with the CSV file, and is + set once with a top-level assignment, while account2 is set based on each transaction's description, in conditional rules. - If a posting's account name is left unset but its amount is set (see - below), a default account name will be chosen (like "expenses:unknown" + If a posting's account name is left unset but its amount is set (see + below), a default account name will be chosen (like "expenses:unknown" or "income:unknown"). amount field - There are several ways to set posting amounts from CSV, useful in dif- + There are several ways to set posting amounts from CSV, useful in dif- ferent situations. - 1. amount is the oldest and simplest. Assigning to this sets the + 1. amount is the oldest and simplest. Assigning to this sets the amount of the first and second postings. In the second posting, the - amount will be negated; also, if it has a cost attached, it will be + amount will be negated; also, if it has a cost attached, it will be converted to cost. - 2. amount-in and amount-out work exactly like the above, but should be - used when the CSV has two amount fields (such as "Debit" and + 2. amount-in and amount-out work exactly like the above, but should be + used when the CSV has two amount fields (such as "Debit" and "Credit", or "Inflow" and "Outflow"). Whichever field has a - non-zero value will be used as the amount of the first and second + non-zero value will be used as the amount of the first and second postings. Here are some tips to avoid confusion: - o It's not "amount-in for posting 1 and amount-out for posting 2", - it is "extract a single amount from the amount-in or amount-out + o It's not "amount-in for posting 1 and amount-out for posting 2", + it is "extract a single amount from the amount-in or amount-out field, and use that for posting 1 and (negated) for posting 2". - o Don't use both amount and amount-in/amount-out in the same rules + o Don't use both amount and amount-in/amount-out in the same rules file; choose based on whether the amount is in a single CSV field or spread across two fields. - o In each record, at most one of the two CSV fields should contain - a non-zero amount; the other field must contain a zero or noth- + o In each record, at most one of the two CSV fields should contain + a non-zero amount; the other field must contain a zero or noth- ing. - o hledger assumes both CSV fields contain unsigned numbers, and it + o hledger assumes both CSV fields contain unsigned numbers, and it automatically negates the amount-out values. - o If the data doesn't fit these requirements, you'll probably need + o If the data doesn't fit these requirements, you'll probably need an if rule (see below). 3. amountN (where N is a number from 1 to 99) sets the amount of only a - single posting: the Nth posting in the transaction. You'll usually - need at least two such assignments to make a balanced transaction. + single posting: the Nth posting in the transaction. You'll usually + need at least two such assignments to make a balanced transaction. You can also generate more than two postings, to represent more com- - plex transactions. The posting numbers don't have to be consecu- - tive; with if rules, higher posting numbers can be useful to ensure + plex transactions. The posting numbers don't have to be consecu- + tive; with if rules, higher posting numbers can be useful to ensure a certain order of postings. - 4. amountN-in and amountN-out work exactly like the above, but should - be used when the CSV has two amount fields. This is analogous to + 4. amountN-in and amountN-out work exactly like the above, but should + be used when the CSV has two amount fields. This is analogous to amount-in and amount-out, and those tips also apply here. 5. Remember that a fields list can also do assignments. So in a fields - list if you name a CSV field "amount", that counts as assigning to - amount. (If you don't want that, call it something else in the + list if you name a CSV field "amount", that counts as assigning to + amount. (If you don't want that, call it something else in the fields list, like "amount_".) - 6. The above don't handle every situation; if you need more flexibil- + 6. The above don't handle every situation; if you need more flexibil- ity, use an if rule to set amounts conditionally. See "Working with - CSV > Setting amounts" below for more on this and on amount-setting + CSV > Setting amounts" below for more on this and on amount-setting generally. currency field - currency sets a currency symbol, to be prepended to all postings' - amounts. You can use this if the CSV amounts do not have a currency + currency sets a currency symbol, to be prepended to all postings' + amounts. You can use this if the CSV amounts do not have a currency symbol, eg if it is in a separate column. currencyN prepends a currency symbol to just the Nth posting's amount. balance field - balanceN sets a balance assertion amount (or if the posting amount is + balanceN sets a balance assertion amount (or if the posting amount is left empty, a balance assignment) on posting N. balance is a compatibility spelling for hledger <1.17; it is equivalent to balance1. - You can adjust the type of assertion/assignment with the balance-type + You can adjust the type of assertion/assignment with the balance-type rule (see below). - See the Working with CSV tips below for more about setting amounts and + See the Working with CSV tips below for more about setting amounts and currency. if block - Rules can be applied conditionally, depending on patterns in the CSV - data. This allows flexibility; in particular, it is how you can cate- - gorise transactions, selecting an appropriate account name based on - their description (for example). There are two ways to write condi- - tional rules: "if blocks", described here, and "if tables", described + Rules can be applied conditionally, depending on patterns in the CSV + data. This allows flexibility; in particular, it is how you can cate- + gorise transactions, selecting an appropriate account name based on + their description (for example). There are two ways to write condi- + tional rules: "if blocks", described here, and "if tables", described below. - An if block is the word if and one or more "matcher" expressions (can + An if block is the word if and one or more "matcher" expressions (can be a word or phrase), one per line, starting either on the same or next line; followed by one or more indented rules. Eg, @@ -3858,11 +3899,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. @@ -3888,41 +3929,40 @@ CSV Matchers There are two kinds of matcher: - 1. A whole record matcher is simplest: it is just a word, single-line - text fragment, or other regular expression, which hledger will try + 1. A whole record matcher is simplest: it is just a word, single-line + text fragment, or other regular expression, which hledger will try to match case-insensitively anywhere within the CSV record. Eg: whole foods. - 2. A field matcher has a percent-prefixed CSV field number or name be- + 2. A field matcher has a percent-prefixed CSV field number or name be- fore the pattern. Eg: %3 whole foods or %description whole foods. hledger will try to match the pattern just within the named CSV field. When using these, there's two things to be aware of: - 1. Whole record matchers don't see the exact original record; they see - a reconstruction of it, in which values are comma-separated, and - quotes enclosing values and whitespace outside those quotes are re- + 1. Whole record matchers don't see the exact original record; they see + a reconstruction of it, in which values are comma-separated, and + quotes enclosing values and whitespace outside those quotes are re- moved. Eg when reading an SSV record like: 2023-01-01 ; "Acme, Inc. " ; 1,000 the whole record matcher sees instead: 2023-01-01,Acme, Inc. ,1,000 2. Field matchers expect either a CSV field number, or a CSV field name - declared with fields. (Don't use a hledger field name here, unless - it is also a CSV field name.) A non-CSV field name will cause the - matcher to match against "" (the empty string), and does not raise - an error, allowing easier reuse of common rules with different CSV + declared with fields. (Don't use a hledger field name here, unless + it is also a CSV field name.) A non-CSV field name will cause the + matcher to match against "" (the empty string), and does not raise + an error, allowing easier reuse of common rules with different CSV files. You can also prefix a matcher with ! (and optional space) to negate it. - Eg ! whole foods, ! %3 whole foods, !%description whole foods will + Eg ! whole foods, ! %3 whole foods, !%description whole foods will match if "whole foods" is NOT present. Added in 1.32. - The pattern is, as usual in hledger, a POSIX extended regular expres- - sion that also supports GNU word boundaries (\b, \B, \<, \>) and noth- - ing else. If you have trouble with it, see "Regular expressions" in - the hledger manual (https://hledger.org/hledger.html#regular-expres- - sions). + The pattern is, as usual in hledger, a POSIX extended regular expres- + sion that also supports GNU word boundaries (\b, \B, \<, \>) and noth- + ing else. For more details and tips, see Regular expressions in CSV + rules below. Multiple matchers When an if block has multiple matchers, each on its own line, @@ -4179,6 +4219,43 @@ CSV o https://plaintextaccounting.org -> data import/conversion + Regular expressions in CSV rules + Regular expressions in if conditions (AKA matchers) are POSIX extended + regular expressions, that also support GNU word boundaries (\b, \B, \<, + \>), and nothing else. (For more detail, see Regular expressions.) + + Here are some examples that might be useful in CSV rules: + + o Is field "foo" truly empty ? if %foo ^$ + + o Is it empty or containing only whitespace ? if %foo ^ *$ + + o Is it non-empty ? if %foo . + + o Does it contain non-whitespace ? if %foo [^ ] + + Testing the value of numeric fields is a little harder. You can't use + hledger queries like amt:0 or amt:>10 in CSV rules. But you can often + achieve the same thing with a regular expression. + + Note the content and layout of number fields in CSV varies, and can + change over time (eg if you switch data providers). So numeric regexps + are always somewhat specific to your particular CSV data; and it's a + good idea to make them defensive and robust if you can. + + Here are some examples: + + o Does foo contain a non-zero number ? if %foo [1-9] + + o Is it negative ? if %foo - + + o Is it non-negative ? if ! %foo - + + o Is it >= 10 ? if %foo [1-9][0-9]+\. (assuming a decimal period and + no leading zeros) + + o Is it >= 10 and < 20 ? if %foo \b1[0-9]\. + Setting amounts Continuing from amount field above, here are more tips for amount-set- ting: @@ -7615,6 +7692,7 @@ Basic report commands Show journal and performance statistics. Flags: + -1 show a single line of output -v --verbose show more detailed output -o --output-file=FILE write output to FILE. @@ -7622,23 +7700,27 @@ Basic report commands matched part of it. With a reporting interval, it shows a report for each report period. - The default output is fairly impersonal, though it reveals the main - file name. With -v/--verbose, more details are shown, like file paths, - included files, and commodity names. + It also shows some performance statistics: - It also shows some run time statistics: + o how long the program ran for - o elapsed time + o the number of transactions processed per second - o throughput: the number of transactions processed per second + o the peak live memory in use by the program to do its work - o live: the peak memory in use by the program to do its work + o the peak allocated memory as seen by the program - 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. + By default, the output is reasonably discreet; it reveals the main file + name, your activity level, and the speed of your machine. - The stats command's run time is similar to that of a balance report. + With -v/--verbose, more details are shown: the full paths of all files, + and the names of the commodities you work with. + + With -1, only one line of output is shown, in a machine-friendly + tab-separated format: the program version, the main journal file name, + and the performance stats, + + The run time of stats is similar to that of a balance report. Example: @@ -7656,7 +7738,10 @@ Basic report commands Market prices : 1000 Runtime stats : 0.12 s elapsed, 8266 txns/s, 4 MB live, 16 MB alloc - This command supports the -o/--output-file option (but not -O/--out- + $ hledger stats -1 -f examples/10ktxns-1kaccts.journal + 1.50.99-g0835a2485-20251119, mac-aarch64 10ktxns-1kaccts.journal 0.66 s elapsed 15244 txns/s 28 MB live 86 MB alloc + + This command supports the -o/--output-file option (but not -O/--out- put-format). tags @@ -7674,26 +7759,26 @@ Basic report commands including duplicates This command lists tag names - all of them by default, or just the ones - which have been used on transactions/postings/accounts, or declared - with tag directives, or used but not declared, or declared but not - used, or just the first one matched by a pattern (with --find, return- + which have been used on transactions/postings/accounts, or declared + with tag directives, or used but not declared, or declared but not + used, or just the first one matched by a pattern (with --find, return- ing a non-zero exit code if it fails). - Note this command's non-standard first argument: it is a case-insensi- - tive infix regular expression for matching tag names, which limits the - tags shown. Any additional arguments are standard query arguments, + Note this command's non-standard first argument: it is a case-insensi- + tive infix regular expression for matching tag names, which limits the + tags shown. Any additional arguments are standard query arguments, which limit the transactions, postings, or accounts providing tags. With --values, the tags' unique non-empty values are listed instead. With -E/--empty, blank/empty values are also shown. - With --parsed, tags or values are shown in the order they were parsed, - with duplicates included. (Except, tags from account declarations are + With --parsed, tags or values are shown in the order they were parsed, + with duplicates included. (Except, tags from account declarations are always shown first.) - Remember that accounts also acquire tags from their parents; postings - also acquire tags from their account and transaction; and transactions + Remember that accounts also acquire tags from their parents; postings + also acquire tags from their account and transaction; and transactions also acquire tags from their postings. Standard report commands @@ -7729,9 +7814,9 @@ Standard report commands The print command displays full journal entries (transactions) from the journal file, sorted by date (or with --date2, by secondary date). - Directives and inter-transaction comments are not shown, currently. + Directives and inter-transaction comments are not shown, currently. This means the print command is somewhat lossy, and if you are using it - to reformat/regenerate your journal you should take care to also copy + to reformat/regenerate your journal you should take care to also copy over the directives and inter-transaction comments. Eg: @@ -7751,33 +7836,33 @@ Standard report commands assets:cash $-2 print amount 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 alignment - Amounts are shown right-aligned within each transaction (but not - aligned across all transactions; you can achieve that with ledger-mode + Amounts are shown right-aligned within each transaction (but not + aligned across all transactions; you can achieve that with ledger-mode in Emacs). print amount style - Amounts will be displayed mostly in their commodity's display style, - with standardised symbol placement, decimal mark, and digit group - marks. This does not apply to their decimal digits; print normally + Amounts will be displayed mostly in their commodity's display style, + with standardised symbol placement, decimal mark, and digit group + marks. This does not apply to their decimal digits; print normally shows the same decimal digits that are recorded in each journal entry. - You can override the decimal precisions with print's special --round + You can override the decimal precisions with print's special --round option (since 1.32). --round tries to show amounts with their commodi- ties' standard decimal precisions, increasingly strongly: @@ -7785,7 +7870,7 @@ Standard report commands 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 @@ -7793,21 +7878,21 @@ Standard report commands soft is good for non-lossy cleanup, displaying more consistent decimals where possible, without making entries unbalanced. - hard or all can be good for stronger cleanup, when decimal rounding is - wanted. Note rounding can produce unbalanced journal entries, perhaps + hard or all can be good for stronger cleanup, when decimal rounding is + wanted. Note rounding can produce unbalanced journal entries, perhaps requiring manual fixup. print parseability - Normally, print's output is a valid hledger journal, which you can - "pipe" to a second hledger command for further processing. This is - sometimes convenient for achieving certain kinds of query (though less + Normally, print's output is a valid hledger journal, which you can + "pipe" to a second hledger command for further processing. This is + sometimes convenient for achieving certain kinds of query (though less needed now that queries have become more powerful): # Show running total of food expenses paid from cash. # -f- reads from stdin. -I/--ignore-assertions is sometimes needed. $ hledger print assets:cash | hledger -f- -I reg expenses:food - But here are some things which can cause print's output to become un- + But here are some things which can cause print's output to become un- parseable: o --round (see above) can disrupt transaction balancing. @@ -7815,12 +7900,12 @@ Standard report commands o Account aliases or pivoting can disrupt account names, balance asser- tions, or balance assignments. - o Value reporting also can disrupt balance assertions or balance as- + o Value reporting also can disrupt balance assertions or balance as- signments. o Auto postings can generate too many amountless postings. - o --infer-costs or --infer-equity can generate too-complex redundant + o --infer-costs or --infer-equity can generate too-complex redundant costs. o Because print always shows transactions in date order, balance asser- @@ -7830,45 +7915,45 @@ Standard report commands print, other features With -B/--cost, amounts with costs are shown converted to cost. - With --invert, posting amounts are shown with their sign flipped. It - could be useful if you have accidentally recorded some transactions + With --invert, posting amounts are shown with their sign flipped. It + could be useful if you have accidentally recorded some transactions with the wrong signs. 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. - With --locations, print adds the source file and line number to every + With --locations, print adds the source file and line number to every transaction, as a tag. 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.) @@ -7901,26 +7986,26 @@ Standard report commands "5","2008/12/31","","*","","pay off","","liabilities:debts","1","$","","1","","" "5","2008/12/31","","*","","pay off","","assets:bank:checking","-1","$","1","","","" - o There is one CSV record per posting, with the parent transaction's + o There is one CSV record per posting, with the parent transaction's fields repeated. o The "txnidx" (transaction index) field shows which postings belong to - the same transaction. (This number might change if transactions are - reordered within the file, files are parsed/included in a different + the same transaction. (This number might change if transactions are + reordered within the file, files are parsed/included in a different order, etc.) - o The amount is separated into "commodity" (the symbol) and "amount" + o The amount is separated into "commodity" (the symbol) and "amount" (numeric quantity) fields. o The numeric amount is repeated in either the "credit" or "debit" col- - umn, for convenience. (Those names are not accurate in the account- - ing sense; it just puts negative amounts under credit and zero or + umn, for convenience. (Those names are not accurate in the account- + ing sense; it just puts negative amounts under credit and zero or greater amounts under debit.) aregister (areg) - Show the transactions and running balances in one account, with each + Show the transactions and running balances in one account, with each transaction on one line. Flags: @@ -7944,66 +8029,66 @@ Standard report commands one of the above formats selects that format. aregister shows the overall transactions affecting a particular account - (and any subaccounts). Each report line represents one transaction in - this account. Transactions before the report start date are included - in the running balance (--historical mode is the default). You can + (and any subaccounts). Each report line represents one transaction in + this account. Transactions before the report start date are included + in the running balance (--historical mode is the default). You can suppress this behaviour using the --cumulative option. - 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: - o aregister is best when reconciling real-world asset/liability ac- + o aregister is best when reconciling real-world asset/liability ac- counts o register is best when reviewing individual revenues/expenses. - Note this command's non-standard, and required, first argument; it - specifies the account whose register will be shown. You can write the - account's name, or (to save typing) a case-insensitive infix regular - expression matching the name, which selects the alphabetically first - matched account. (For example, if you have assets:personal checking - and assets:business checking, hledger areg checking would select as- + Note this command's non-standard, and required, first argument; it + specifies the account whose register will be shown. You can write the + account's name, or (to save typing) a case-insensitive infix regular + expression matching the name, which selects the alphabetically first + matched account. (For example, if you have assets:personal checking + and assets:business checking, hledger areg checking would select as- sets:business checking.) - 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 historical balance report with similar arguments. Any additional arguments are standard query arguments, which will limit - the transactions shown. Note some queries will disturb the running - balance, causing it to be different from the account's real-world run- + the transactions shown. Note some queries will disturb the running + balance, causing it to be different from the account's real-world run- ning 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. - By default, aregister shows a heading above the data. However, when - reporting in a language different from English, it is easier to omit - this heading and prepend your own one. For this purpose, use the + By default, aregister shows a heading above the data. However, when + reporting in a language different from English, it is easier to omit + this heading and prepend your own one. For this purpose, use the --heading=no option. This command also supports the output destination and output format op- @@ -8011,13 +8096,13 @@ Standard report commands html, fods (Added in 1.41) 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. @@ -8057,14 +8142,14 @@ Standard report commands one of the above formats selects that format. The register command displays matched postings, across all accounts, in - date order, with their running total or running historical balance. - (See also the aregister command, which shows matched transactions in a + date order, with their running total or running historical balance. + (See also the aregister command, which shows matched transactions in a specific account.) register normally shows line per posting, but note that multi-commodity amounts will occupy multiple lines (one line per commodity). - It is typically used with a query selecting a particular account, to + It is typically used with a query selecting a particular account, to see that account's activity: $ hledger register checking @@ -8075,14 +8160,14 @@ Standard report commands With --date2, it shows and sorts by secondary date instead. - For performance reasons, column widths are chosen based on the first - 1000 lines; this means unusually wide values in later lines can cause - visual discontinuities as column widths are adjusted. If you want to - ensure perfect alignment, at the cost of more time and memory, use the + For performance reasons, column widths are chosen based on the first + 1000 lines; this means unusually wide values in later lines can cause + visual discontinuities as column widths are adjusted. If you want to + ensure perfect alignment, at the cost of more time and memory, use the --align-all flag. - The --historical/-H flag adds the balance from any undisplayed prior - postings to the running total. This is useful when you want to see + The --historical/-H flag adds the balance from any undisplayed prior + postings to the running total. This is useful when you want to see only recent activity, with a historically accurate running balance: $ hledger register checking -b 2008/6 --historical @@ -8092,25 +8177,25 @@ Standard report commands The --depth option limits the amount of sub-account detail displayed. - The --average/-A flag shows the running average posting amount instead + The --average/-A flag shows the running average posting amount instead of the running total (so, the final number displayed is the average for - the whole report period). This flag implies --empty (see below). It - is affected by --historical. It works best when showing just one ac- + the whole report period). This flag implies --empty (see below). It + is affected by --historical. It works best when showing just one ac- count and one commodity. - The --related/-r flag shows the other postings in the transactions of + The --related/-r flag shows the other postings in the transactions of the postings which would normally be shown. - The --invert flag negates all amounts. For example, it can be used on + The --invert flag negates all amounts. For example, it can be used on an income account where amounts are normally displayed as negative num- - bers. It's also useful to show postings on the checking account to- + bers. It's also useful to show postings on the checking account to- gether with the related account: - The --sort=FIELDS flag sorts by the fields given, which can be any of + The --sort=FIELDS flag sorts by the fields given, which can be any of account, amount, absamount, date, or desc/description, optionally sepa- - rated by commas. For example, --sort account,amount will group all + rated by commas. For example, --sort account,amount will group all transactions in each account, sorted by transaction amount. Each field - can be negated by a preceding -, so --sort -amount will show transac- + can be negated by a preceding -, so --sort -amount will show transac- tions ordered from smallest amount to largest amount. $ hledger register --related --invert assets:checking @@ -8122,7 +8207,7 @@ Standard report 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 @@ -8139,7 +8224,7 @@ Standard report 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 1 @@ -8147,21 +8232,21 @@ Standard report 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 normally uses the full terminal width (or 80 columns if it + register normally uses the full terminal width (or 80 columns if it can't detect that). You can override this with 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): @@ -8177,14 +8262,14 @@ Standard report commands $ hledger reg -w 100,40 # set overall width 100, 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. balancesheet (bs) - Show the end balances in asset and liability accounts. Amounts are - shown with normal positive sign, as in conventional financial state- + Show the end balances in asset and liability accounts. Amounts are + shown with normal positive sign, as in conventional financial state- ments. Flags: @@ -8235,13 +8320,13 @@ Standard report commands -o --output-file=FILE write output to FILE. A file extension matching one of the above formats selects that format. - 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.) Accounts declared with the Asset, Cash or Liability type are shown (see - account types). Or if no such accounts are declared, it shows - top-level accounts named asset or liability (case insensitive, plurals + 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: @@ -8267,20 +8352,20 @@ Standard report commands Net: || 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. Flags: @@ -8331,9 +8416,9 @@ Standard report commands -o --output-file=FILE write output to FILE. A file extension matching one of the above formats selects that format. - 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: @@ -8364,14 +8449,14 @@ Standard report commands Net: || 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 report is the easiest way to see if the accounting equation (A+L+E - = 0) is satisfied (after you have done a close --retain to merge rev- - enues and expenses with equity, and perhaps added --infer-equity to + = 0) is satisfied (after you have done a close --retain to merge rev- + enues and expenses with equity, and perhaps added --infer-equity to balance your commodity conversions). This command also supports the output destination and output format op- @@ -8380,9 +8465,9 @@ Standard report commands cashflow (cf) - This command displays a (simple) cashflow statement, showing the in- - flows and outflows affecting "cash" (ie, liquid, easily convertible) - assets. Amounts are shown with normal positive sign, as in conven- + This command displays a (simple) cashflow statement, showing the in- + flows and outflows affecting "cash" (ie, liquid, easily convertible) + assets. Amounts are shown with normal positive sign, as in conven- tional financial statements. Flags: @@ -8434,10 +8519,10 @@ Standard report commands -o --output-file=FILE write output to FILE. A file extension matching one of the above formats selects that format. - 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. @@ -8464,19 +8549,19 @@ Standard report 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. incomestatement (is) - Show revenue inflows and expense outflows during the report period. - Amounts are shown with normal positive sign, as in conventional finan- + Show revenue inflows and expense outflows during the report period. + Amounts are shown with normal positive sign, as in conventional finan- cial statements. Flags: @@ -8528,12 +8613,12 @@ Standard report commands -o --output-file=FILE write output to FILE. A file extension matching one of the above formats selects that format. - 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. - It shows accounts declared with the Revenue or Expense type (see ac- - count types). Or if no such accounts are declared, it shows top-level - accounts named revenue or income or expense (case insensitive, plurals + It shows accounts declared with the Revenue or Expense type (see ac- + count types). Or if no such accounts are declared, it shows top-level + accounts named revenue or income or expense (case insensitive, plurals allowed) and their subaccounts. Example: @@ -8560,20 +8645,20 @@ Standard report commands Net: || 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. Advanced report commands balance (bal) - A flexible, general purpose "summing" report that shows accounts with + A flexible, general purpose "summing" report that shows accounts with some kind of numeric data. This can be balance changes per period, end balances, budget performance, unrealised capital gains, etc. @@ -8640,19 +8725,19 @@ Advanced report commands -o --output-file=FILE write output to FILE. A file extension matching one of the above formats selects that format. - 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 variants of the balance command with convenient de- - faults, which are simpler to use: balancesheet, balancesheetequity, - cashflow and incomestatement. When you need more control, then use + faults, which are simpler to use: balancesheet, balancesheetequity, + cashflow and incomestatement. When you need more control, 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 other balance-like commands as well (bs, cf, is..). balance can show.. @@ -8707,7 +8792,7 @@ Advanced report 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) @@ -8720,20 +8805,20 @@ Advanced report commands This command supports the output destination and output format options, with output formats txt, csv, tsv (Added in 1.32), json, and (multi-pe- - riod reports only:) html, fods (Added in 1.40). In txt output in a + riod reports only:) html, fods (Added in 1.40). In txt output in a colour-supporting terminal, negative amounts are shown in red. Simple balance report - With no arguments, balance shows a list of all accounts and their - change of balance - ie, the sum of posting amounts, both inflows and - outflows - during the entire period of the journal. ("Simple" here - means just one column of numbers, covering a single period. You can + With no arguments, balance shows a list of all accounts and their + change of balance - ie, the sum of posting amounts, both inflows and + outflows - during the entire period of the journal. ("Simple" here + means just one column of numbers, covering a single period. You can also have multi-period reports, described later.) - For real-world accounts, these numbers will normally be their end bal- + For real-world accounts, these numbers will normally be their end bal- ance at the end of the journal period; more on this below. - Accounts are sorted by declaration order if any, and then alphabeti- + Accounts are sorted by declaration order if any, and then alphabeti- cally by account name. For instance (using examples/sample.journal): $ hledger -f examples/sample.journal bal @@ -8748,7 +8833,7 @@ Advanced report commands 0 Accounts with a zero balance (and no non-zero subaccounts, in tree mode - - see below) are hidden by default. Use -E/--empty to show them (re- + - see below) are hidden by default. Use -E/--empty to show them (re- vealing assets:bank:checking here): $ hledger -f examples/sample.journal bal -E @@ -8763,12 +8848,12 @@ Advanced report commands -------------------- 0 - The total of the amounts displayed is shown as the last line, unless + The total of the amounts displayed is shown as the last line, unless -N/--no-total is used. Balance report line format For single-period balance reports displayed in the terminal (only), you - can use --format FMT to customise the format and content of each line. + can use --format FMT to customise the format and content of each line. Eg: $ hledger -f examples/sample.journal balance --format "%20(account) %12(total)" @@ -8785,7 +8870,7 @@ Advanced report commands --------------------------------- 0 - The FMT format string specifies the formatting applied to each ac- + The FMT format string specifies the formatting applied to each ac- count/balance pair. It may contain any suitable text, with data fields interpolated like so: @@ -8797,14 +8882,14 @@ Advanced report commands o FIELDNAME must be enclosed in parentheses, and can be one of: - o depth_spacer - a number of spaces equal to the account's depth, or + o depth_spacer - a number of spaces equal to the account's depth, or if MIN is specified, MIN * depth spaces. o account - the account's name o total - the account's balance/posted total, right justified - Also, FMT can begin with an optional prefix to control how multi-com- + Also, FMT can begin with an optional prefix to control how multi-com- modity amounts are rendered: o %_ - render on multiple lines, bottom-aligned (the default) @@ -8814,25 +8899,25 @@ Advanced report commands o %, - render on one line, comma-separated There are some quirks. Eg in one-line mode, %(depth_spacer) has no ef- - fect, instead %(account) has indentation built in. Experimentation + fect, instead %(account) has indentation built in. Experimentation may be needed to get pleasing results. Some example formats: o %(total) - the account's total - o %-20.20(account) - the account's name, left justified, padded to 20 + o %-20.20(account) - the account's name, left justified, padded to 20 characters and clipped at 20 characters - o %,%-50(account) %25(total) - account name padded to 50 characters, - total padded to 20 characters, with multiple commodities rendered on + o %,%-50(account) %25(total) - account name padded to 50 characters, + total padded to 20 characters, with multiple commodities rendered on one line - o %20(total) %2(depth_spacer)%-(account) - the default format for the + o %20(total) %2(depth_spacer)%-(account) - the default format for the single-column balance report Filtered balance report - You can show fewer accounts, a different time period, totals from + You can show fewer accounts, a different time period, totals from cleared transactions only, etc. by using query arguments or options to limit the postings being matched. Eg: @@ -8842,10 +8927,10 @@ Advanced report commands $-2 List or tree mode - By default, or with -l/--flat, accounts are shown as a flat list with + By default, or with -l/--flat, accounts are shown as a flat list with their full names visible, as in the examples above. - With -t/--tree, the account hierarchy is shown, with subaccounts' + With -t/--tree, the account hierarchy is shown, with subaccounts' "leaf" names indented below their parent: $ hledger -f examples/sample.journal balance @@ -8865,26 +8950,26 @@ Advanced report commands Notes: o "Boring" accounts are combined with their subaccount for more compact - output, unless --no-elide is used. Boring accounts have no balance - of their own and just one subaccount (eg assets:bank and liabilities + output, unless --no-elide is used. Boring accounts have no balance + of their own and just one subaccount (eg assets:bank and liabilities above). - o All balances shown are "inclusive", ie including the balances from - all subaccounts. Note this means some repetition in the output, + o All balances shown are "inclusive", ie including the balances from + all subaccounts. Note this means some repetition in the output, which requires explanation when sharing reports with non-plaintextac- - counting-users. A tree mode report's final total is the sum of the + counting-users. A tree mode report's final total is the sum of the top-level balances shown, not of all the balances shown. - o Each group of sibling accounts (ie, under a common parent) is sorted + o Each group of sibling accounts (ie, under a common parent) is sorted separately. Depth limiting - With a depth:NUM query, or --depth NUM option, or just -NUM (eg: -3) - balance reports will show accounts only to the specified depth, hiding - the deeper subaccounts. This can be useful for getting an overview + With a depth:NUM query, or --depth NUM option, or just -NUM (eg: -3) + balance reports will show accounts only to the specified depth, hiding + the deeper subaccounts. This can be useful for getting an overview without too much detail. - Account balances at the depth limit always include the balances from + Account balances at the depth limit always include the balances from any deeper subaccounts (even in list mode). Eg, limiting to depth 1: $ hledger -f examples/sample.journal balance -1 @@ -8896,7 +8981,7 @@ Advanced report commands 0 Dropping top-level accounts - You can also hide one or more top-level account name parts, using + You can also hide one or more top-level account name parts, using --drop NUM. This can be useful for hiding repetitive top-level account names: @@ -8907,54 +8992,54 @@ Advanced report commands $2 Showing declared accounts - With --declared, accounts which have been declared with an account di- - rective will be included in the balance report, even if they have no + With --declared, accounts which have been declared with an account di- + rective will be included in the balance report, even if they have no transactions. (Since they will have a zero balance, you will also need -E/--empty to see them.) - More precisely, leaf declared accounts (with no subaccounts) will be + More precisely, leaf declared accounts (with no subaccounts) will be included, since those are usually the more useful in reports. - The idea of this is to be able to see a useful "complete" balance re- + The idea of this is to be able to see a useful "complete" balance re- port, even when you don't have transactions in all of your declared ac- counts yet. Sorting by amount - With -S/--sort-amount, accounts with the largest (most positive) bal- - ances are shown first. Eg: hledger bal expenses -MAS shows your - biggest averaged monthly expenses first. When more than one commodity - is present, they will be sorted by the alphabetically earliest commod- - ity first, and then by subsequent commodities (if an amount is missing + With -S/--sort-amount, accounts with the largest (most positive) bal- + ances are shown first. Eg: hledger bal expenses -MAS shows your + biggest averaged monthly expenses first. When more than one commodity + is present, they will be sorted by the alphabetically earliest commod- + ity first, and then by subsequent commodities (if an amount is missing a commodity, it is treated as 0). - Revenues and liability balances are typically negative, however, so -S - shows these in reverse order. To work around this, you can add --in- - vert to flip the signs. Or you could use one of the higher-level bal- + Revenues and liability balances are typically negative, however, so -S + shows these in reverse order. To work around this, you can add --in- + vert to flip the signs. Or you could use one of the higher-level bal- ance reports (bs, is..), which flip the sign automatically (eg: hledger is -MAS). Percentages - With -%/--percent, balance reports show each account's value expressed + With -%/--percent, balance reports show each account's value expressed as a percentage of the (column) total. Note it is not useful to calculate percentages if the amounts in a col- - umn have mixed signs. In this case, make a separate report for each + umn have mixed signs. In this case, make a separate report for each sign, eg: $ hledger bal -% amt:`>0` $ hledger bal -% amt:`<0` - Similarly, if the amounts in a column have mixed commodities, convert - them to one commodity with -B, -V, -X or --value, or make a separate + Similarly, if the amounts in a column have mixed commodities, convert + them to one commodity with -B, -V, -X or --value, or make a separate report for each commodity: $ hledger bal -% cur:\\$ $ hledger bal -% cur: Multi-period balance report - With a report interval (set by the -D/--daily, -W/--weekly, - -M/--monthly, -Q/--quarterly, -Y/--yearly, or -p/--period flag), bal- - ance shows a tabular report, with columns representing successive time + With a report interval (set by the -D/--daily, -W/--weekly, + -M/--monthly, -Q/--quarterly, -Y/--yearly, or -p/--period flag), bal- + ance shows a tabular report, with columns representing successive time periods (and a title): $ hledger -f examples/sample.journal bal --quarterly income expenses -E @@ -8975,24 +9060,24 @@ Advanced report commands encompass the displayed subperiods (so that the first and last subpe- riods have the same duration as the others). - o Leading and trailing periods (columns) containing all zeroes are not + o Leading and trailing periods (columns) containing all zeroes are not shown, unless -E/--empty is used. - o Accounts (rows) containing all zeroes are not shown, unless + o Accounts (rows) containing all zeroes are not shown, unless -E/--empty is used. - o Amounts with many commodities are shown in abbreviated form, unless + o Amounts with many commodities are shown in abbreviated form, unless --no-elide is used. - o Average and/or total columns can be added with the -A/--average and + o Average and/or total columns can be added with the -A/--average and -T/--row-total flags. o The --transpose flag can be used to exchange rows and columns. - o The --pivot FIELD option causes a different transaction field to be + o The --pivot FIELD option causes a different transaction field to be used as "account name". See PIVOTING. - o The --summary-only flag (--summary also works) hides all but the To- + o The --summary-only flag (--summary also works) hides all but the To- tal and Average columns (those should be enabled with --row-total and -A/--average). @@ -9011,57 +9096,57 @@ Advanced report commands o Reduce the terminal's font size - o View with a pager like less, eg: hledger bal -D --color=yes | less + o View with a pager like less, eg: hledger bal -D --color=yes | less -RS - o Output as CSV and use a CSV viewer like visidata (hledger bal -D -O - csv | vd -f csv), Emacs' csv-mode (M-x csv-mode, C-c C-a), or a + o Output as CSV and use a CSV viewer like visidata (hledger bal -D -O + csv | vd -f csv), Emacs' csv-mode (M-x csv-mode, C-c C-a), or a spreadsheet (hledger bal -D -o a.csv && open a.csv) - o Output as HTML and view with a browser: hledger bal -D -o a.html && + o Output as HTML and view with a browser: hledger bal -D -o a.html && open a.html Balance change, end balance - It's important to be clear on the meaning of the numbers shown in bal- + It's important to be clear on the meaning of the numbers shown in bal- ance reports. Here is some terminology we use: - A balance change is the net amount added to, or removed from, an ac- + A balance change is the net amount added to, or removed from, an ac- count during some period. - An end balance is the amount accumulated in an account as of some date - (and some time, but hledger doesn't store that; assume end of day in + An end balance is the amount accumulated in an account as of some date + (and some time, but hledger doesn't store that; assume end of day in your timezone). It is the sum of previous balance changes. - We call it a historical end balance if it includes all balance changes + We call it a historical end balance if it includes all balance changes since the account was created. For a real world account, this means it - will match the "historical record", eg the balances reported in your + will match the "historical record", eg the balances reported in your bank statements or bank web UI. (If they are correct!) - In general, balance changes are what you want to see when reviewing + In general, balance changes are what you want to see when reviewing revenues and expenses, and historical end balances are what you want to see when reviewing or reconciling asset, liability and equity accounts. - balance shows balance changes by default. To see accurate historical + balance shows balance changes by default. To see accurate historical end balances: - 1. Initialise account starting balances with an "opening balances" - transaction (a transfer from equity to the account), unless the + 1. Initialise account starting balances with an "opening balances" + transaction (a transfer from equity to the account), unless the journal covers the account's full lifetime. 2. Include all of of the account's prior postings in the report, by not - specifying a report start date, or by using the -H/--historical + specifying a report start date, or by using the -H/--historical flag. (-H causes report start date to be ignored when summing post- ings.) Balance report modes - The balance command is quite flexible; here is the full detail on how - to control what it reports. If the following seems complicated, don't - worry - this is for advanced reporting, and it does take time and ex- + The balance command is quite flexible; here is the full detail on how + to control what it reports. If the following seems complicated, don't + worry - this is for advanced reporting, and it does take time and ex- perimentation to get familiar with all the report modes. There are three important option groups: - hledger balance [CALCULATIONMODE] [ACCUMULATIONMODE] [VALUATIONMODE] + hledger balance [CALCULATIONMODE] [ACCUMULATIONMODE] [VALUATIONMODE] ... Calculation mode @@ -9073,35 +9158,35 @@ Advanced report commands each account/period) o --valuechange : show the change in period-end historical balance val- - ues (caused by deposits, withdrawals, and/or market price fluctua- + ues (caused by deposits, withdrawals, and/or market price fluctua- tions) - o --gain : show the unrealised capital gain/loss, (the current valued + o --gain : show the unrealised capital gain/loss, (the current valued balance minus each amount's original cost) o --count : show the count of postings Accumulation mode - How amounts should accumulate across a report's subperiods/columns. - Another way to say it: which time period's postings should contribute + 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. + o --change : calculate with postings from column start to column end, + ie "just this column". Typically used to see revenues/expenses. (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 + o --cumulative : calculate with postings from report start to column + end, ie "previous columns plus this column". Typically used to show changes accumulated since the report's start date. Not often used. - o --historical/-H : calculate with postings from journal start to col- - 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- + o --historical/-H : calculate with postings from journal start to col- + 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) Valuation mode - Which kind of value or cost conversion should be applied, if any, be- + Which kind of value or cost conversion should be applied, if any, be- fore displaying the report. See Cost reporting and Value reporting for more about conversions. @@ -9109,19 +9194,19 @@ Advanced report commands o no conversion : don't convert to cost or value (default) - o --value=cost[,COMM] : convert amounts to cost (then optionally to + o --value=cost[,COMM] : convert amounts to cost (then optionally to some other commodity) - o --value=then[,COMM] : convert amounts to market value on transaction + o --value=then[,COMM] : convert amounts to market value on transaction dates - o --value=end[,COMM] : convert amounts to market value on period end + o --value=end[,COMM] : convert amounts to market value on period end date(s) (default with --valuechange, --gain) o --value=now[,COMM] : convert amounts to market value on today's date - o --value=YYYY-MM-DD[,COMM] : convert amounts to market value on an- + o --value=YYYY-MM-DD[,COMM] : convert amounts to market value on an- other date or with the legacy -B/-V/-X options, which are equivalent and easier to @@ -9134,17 +9219,17 @@ Advanced report commands o -X COMM/--exchange COMM : like --value=end,COMM Note that --value can also convert to cost, as a convenience; but actu- - ally --cost and --value are independent options, and could be used to- + ally --cost and --value are independent options, and could be used to- gether. Combining balance report modes Most combinations of these modes should produce reasonable reports, but - if you find any that seem wrong or misleading, let us know. The fol- + if you find any that seem wrong or misleading, let us know. The fol- lowing restrictions are applied: o --valuechange implies --value=end - o --valuechange makes --change the default when used with the bal- + o --valuechange makes --change the default when used with the bal- ancesheet/balancesheetequity commands o --cumulative or --historical disables --row-total/-T @@ -9157,18 +9242,18 @@ Advanced report commands Accumu- /now lation:v ----------------------------------------------------------------------------------- - --change change in period sum of post- period-end DATE-value of - ing-date market value of change change in pe- + --change change in period sum of post- period-end DATE-value of + ing-date market value of change change in pe- values in period in period riod - --cumu- change from re- sum of post- period-end DATE-value of - lative port start to ing-date market value of change change from + --cumu- change from re- sum of post- period-end DATE-value of + lative port start to ing-date market value of change change from period end values from re- from report report start port start to pe- start to period to period end riod end end - --his- change from sum of post- period-end DATE-value of + --his- change from sum of post- period-end DATE-value of torical journal start to ing-date market value of change change from /-H period end (his- values from jour- from journal journal start - torical end bal- nal start to pe- start to period to period end + torical end bal- nal start to pe- start to period to period end ance) riod end end Budget report @@ -9179,11 +9264,11 @@ Advanced report commands o Accounts which don't have budget goals are hidden by default. - This is useful for comparing planned and actual income, expenses, time + This is useful for comparing planned and actual income, expenses, time usage, etc. - Periodic transaction rules are used to define budget goals. For exam- - ple, here's a periodic rule defining monthly goals for bus travel and + Periodic transaction rules are used to define budget goals. For exam- + ple, here's a periodic rule defining monthly goals for bus travel and food expenses: ;; Budget @@ -9225,66 +9310,66 @@ Advanced report commands || 0 [ 0% of $430] 0 [ 0% of $430] This is "goal-based budgeting"; you define goals for accounts and peri- - ods, often recurring, and hledger shows performance relative to the - goals. This contrasts with "envelope budgeting", which is more de- - tailed and strict - useful when cash is tight, but also quite a bit - more work. https://plaintextaccounting.org/Budgeting has more on this + ods, often recurring, and hledger shows performance relative to the + goals. This contrasts with "envelope budgeting", which is more de- + tailed and strict - useful when cash is tight, but also quite a bit + more work. https://plaintextaccounting.org/Budgeting has more on this topic. Using the budget report - Historically this report has been confusing and fragile. hledger's - version should be relatively robust and intuitive, but you may still - find surprises. Here are more notes to help with learning and trou- + Historically this report has been confusing and fragile. hledger's + version should be relatively robust and intuitive, but you may still + find surprises. Here are more notes to help with learning and trou- bleshooting. - o In the above example, expenses:bus and expenses:food are shown be- + o In the above example, expenses:bus and expenses:food are shown be- cause they have budget goals during the report period. - o Their parent expenses is also shown, with budget goals aggregated + o Their parent expenses is also shown, with budget goals aggregated from the children. - o The subaccounts expenses:food:groceries and expenses:food:dining are - not shown since they have no budget goal of their own, but they con- + o The subaccounts expenses:food:groceries and expenses:food:dining are + not shown since they have no budget goal of their own, but they con- tribute to expenses:food's actual amount. - o Unbudgeted accounts expenses:movies and expenses:gifts are also not + o Unbudgeted accounts expenses:movies and expenses:gifts are also not shown, but they contribute to expenses's actual amount. - o The other unbudgeted accounts income and assets:bank:checking are + o The other unbudgeted accounts income and assets:bank:checking are grouped as . - o --depth or depth: can be used to limit report depth in the usual way + o --depth or depth: can be used to limit report depth in the usual way (but will not reveal unbudgeted subaccounts). o Amounts are always inclusive of subaccounts (even in -l/--list mode). o Numbers displayed in a --budget report will not always agree with the - totals, because of hidden unbudgeted accounts; this is normal. + totals, because of hidden unbudgeted accounts; this is normal. -E/--empty can be used to reveal the hidden accounts. o In the periodic rules used for setting budget goals, unbalanced post- ings are convenient. - o You can filter budget reports with the usual queries, eg to focus on - particular accounts. It's common to restrict them to just expenses. - (The account is occasionally hard to exclude; this is + o You can filter budget reports with the usual queries, eg to focus on + particular accounts. It's common to restrict them to just expenses. + (The account is occasionally hard to exclude; this is because of date surprises, discussed below.) - o When you have multiple currencies, you may want to convert them to - one (-X COMM --infer-market-prices) and/or show just one at a time - (cur:COMM). If you do need to show multiple currencies at once, + o When you have multiple currencies, you may want to convert them to + one (-X COMM --infer-market-prices) and/or show just one at a time + (cur:COMM). If you do need to show multiple currencies at once, --layout bare can be helpful. - o You can "roll over" amounts (actual and budgeted) to the next period + o You can "roll over" amounts (actual and budgeted) to the next period with --cumulative. See also: https://hledger.org/budgeting.html. Budget date surprises - With small data, or when starting out, some of the generated budget - goal transaction dates might fall outside the report periods. Eg with - the following journal and report, the first period appears to have no - expenses:food budget. (Also the account should be ex- + With small data, or when starting out, some of the generated budget + goal transaction dates might fall outside the report periods. Eg with + the following journal and report, the first period appears to have no + expenses:food budget. (Also the account should be ex- cluded by the expenses query, but isn't.): ~ monthly in 2020 @@ -9304,64 +9389,64 @@ Advanced report commands ---------------++-------------------- || $400 [80% of $500] - In this case, the budget goal transactions are generated on first days - of of month (this can be seen with hledger print --forecast tag:gener- - ated expenses). Whereas the report period defaults to just the 15th - day of january (this can be seen from the report table's column head- + In this case, the budget goal transactions are generated on first days + of of month (this can be seen with hledger print --forecast tag:gener- + ated expenses). Whereas the report period defaults to just the 15th + day of january (this can be seen from the report table's column head- ings). - To fix this kind of thing, be more explicit about the report period - (and/or the periodic rules' dates). In this case, adding -b 2020 does + To fix this kind of thing, be more explicit about the report period + (and/or the periodic rules' dates). In this case, adding -b 2020 does the trick. Selecting budget goals - By default, the budget report uses all available periodic transaction - rules to generate goals. This includes rules with a different report - interval from your report. Eg if you have daily, weekly and monthly - periodic rules, all of these will contribute to the goals in a monthly + By default, the budget report uses all available periodic transaction + rules to generate goals. This includes rules with a different report + interval from your report. Eg if you have daily, weekly and monthly + periodic rules, all of these will contribute to the goals in a monthly budget report. - You can select a subset of periodic rules by providing an argument to - the --budget flag. --budget=DESCPAT will match all periodic rules + You can select a subset of periodic rules by providing an argument to + the --budget flag. --budget=DESCPAT will match all periodic rules whose description contains DESCPAT, a case-insensitive substring (not a - regular expression or query). 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 de- + regular expression or query). 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 de- fined in your journal. Budgeting vs forecasting - --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 + --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: --forecast --budget -------------------------------------------------------------------------- - is a general option; it enables fore- is a balance command option; it - casting with all reports selects the balance report's + 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 + 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 + 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 + uses just the rules matched by DESCPAT Balance report layout The --layout option affects how balance and the other balance-like com- - mands show multi-commodity amounts and commodity symbols. It can im- + mands show multi-commodity amounts and commodity symbols. It can im- prove readability, for humans and/or machines (other software). 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 @@ -9369,11 +9454,11 @@ Advanced report 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, - with one row per data value. (This one is currently supported only + o --layout=tidy: data is normalised to easily-consumed "tidy" form, + with one row per data value. (This one is currently supported only by the balance command.) - Here are the --layout modes supported by each output format Only CSV + Here are the --layout modes supported by each output format Only CSV output supports all of them: - txt csv html json sql @@ -9409,7 +9494,7 @@ Advanced report commands || 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 + 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 @@ -9430,7 +9515,7 @@ Advanced report commands || 18.00 VHT 294.00 VHT Bare layout - Commodity symbols are kept in one column, each commodity has its own + 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 @@ -9466,15 +9551,15 @@ Advanced report commands "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- + 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- + 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: @@ -9497,40 +9582,40 @@ Advanced report commands "Assets:US:ETrade","2014","2014-01-01","2014-12-31","VHT","170.00" Balance report output - As noted in Output format, if you choose HTML output (by using -O html + As noted in Output format, if you choose HTML output (by using -O html or -o somefile.html), you can create a hledger.css file in the same di- rectory to customise the report's appearance. The HTML and FODS output formats can generate hyperlinks to a - hledger-web register view for each account and period. E.g. if your + hledger-web register view for each account and period. E.g. if your hledger-web server is reachable at http://localhost:5000 then you might - run the balance command with the extra option --base-url=http://local- - host:5000. You can also produce relative links, like + run the balance command with the extra option --base-url=http://local- + host:5000. You can also produce relative links, like --base-url="some/path" or --base-url="".) 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 @@ -9544,7 +9629,7 @@ Advanced report commands Show top gainers [or losers] last week 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. Flags: @@ -9554,38 +9639,38 @@ Advanced report commands --profit-loss=QUERY --pnl query to select profit-and-loss or appreciation/valuation transactions - 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 @@ -9595,28 +9680,28 @@ Advanced report 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 @@ -9633,12 +9718,12 @@ Advanced report 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 @@ -9655,58 +9740,58 @@ Advanced report 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: @@ -9719,7 +9804,7 @@ Advanced report 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 Chart commands @@ -9729,8 +9814,8 @@ Chart commands Flags: no command-specific flags - 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: @@ -9745,10 +9830,10 @@ Data generation commands close (equity) - close prints several kinds of "closing" and/or "opening" transactions, + close prints several kinds of "closing" and/or "opening" transactions, useful in various situations: migrating balances to a new journal file, - retaining earnings into equity, consolidating balances, viewing lot - costs.. Like print, it prints valid journal entries. You can copy + retaining earnings into equity, consolidating balances, viewing lot + costs.. Like print, it prints valid journal entries. You can copy these into your journal file(s) when you are happy with how they look. Flags: @@ -9779,22 +9864,22 @@ Data generation commands all - also round cost amounts to precision (can unbalance transactions) - close has six modes, selected by choosing one of the mode flags: - --clopen, --close (default), --open, --assert, --assign, or --retain. - They are all doing the same kind of operation, but with different de- + close has six modes, selected by choosing one of the mode flags: + --clopen, --close (default), --open, --assert, --assign, or --retain. + They are all doing the same kind of operation, but with different de- faults for different situations. - The journal entries generated by close will have a clopen: tag, which - is helpful when you want to exclude them from reports. If the main - journal file name contains a number, the tag's value will be that base - file name with the number incremented. Eg if the journal file is - 2025.journal, the tag will be clopen:2026. Or you can set the tag - value by providing an argument to the mode flag. Eg --close=foo or + The journal entries generated by close will have a clopen: tag, which + is helpful when you want to exclude them from reports. If the main + journal file name contains a number, the tag's value will be that base + file name with the number incremented. Eg if the journal file is + 2025.journal, the tag will be clopen:2026. Or you can set the tag + value by providing an argument to the mode flag. Eg --close=foo or --clopen=2025-main. close --clopen This is useful if migrating balances to a new journal file at the start - of a new year. It prints a "closing balances" transaction that zeroes + of a new year. It prints a "closing balances" transaction that zeroes out account balances (Asset and Liability accounts, by default), and an opposite "opening balances" transaction that restores them again. Typ- ically, you would run @@ -9805,40 +9890,40 @@ Data generation commands (and probably also update your LEDGER_FILE environment variable). Why might you do this ? If your reports are fast, you may not need it. - But at some point you will probably want to partition your data by - time, for performance or data integrity or regulatory reasons. A new - file or set of files per year is common. Then, having each file/file- - set "bookended" with opening and closing balance transactions will al- - low you to freely pick and choose which files to read - just the cur- + But at some point you will probably want to partition your data by + time, for performance or data integrity or regulatory reasons. A new + file or set of files per year is common. Then, having each file/file- + set "bookended" with opening and closing balance transactions will al- + low you to freely pick and choose which files to read - just the cur- rent year, any past year, any sequence of years, or all of them - while - showing correct account balances in each case. The earliest opening - balances transaction sets correct starting balances, and any later + showing correct account balances in each case. The earliest opening + balances transaction sets correct starting balances, and any later closing/opening pairs will harmlessly cancel each other out. - The balances will be transferred to and from equity:opening/closing - balances by default. You can override this by using --close-acct + The balances will be transferred to and from equity:opening/closing + balances by default. You can override this by using --close-acct and/or --open-acct. - You can select a different set of accounts to close/open by providing - an account query. Eg to add Equity accounts, provide arguments like - assets liabilities equity or type:ALE. When migrating to a new file, - you'll usually want to bring along the AL or ALE accounts, but not the + You can select a different set of accounts to close/open by providing + an account query. Eg to add Equity accounts, provide arguments like + assets liabilities equity or type:ALE. When migrating to a new file, + you'll usually want to bring along the AL or ALE accounts, but not the RX accounts (Revenue, Expense). - Assertions will be added indicating and checking the new balances of + Assertions will be added indicating and checking the new balances of the closed/opened accounts. close --close - This prints just the closing balances transaction of --clopen. It is + This prints just the closing balances transaction of --clopen. It is the default if you don't specify a mode. - More customisation options are described below. Among other things, + More customisation options are described below. Among other things, you can use close --close to generate a transaction moving the balances from any set of accounts, to a different account. (If you need to move just a portion of the balance, see hledger-move.) close --open - This prints just the opening balances transaction of --clopen. (It is + This prints just the opening balances transaction of --clopen. (It is similar to Ledger's equity command.) close --assert @@ -9848,29 +9933,29 @@ Data generation commands close --assign This prints a transaction that assigns the account balances as they are - on the end date (and adds an "assign:" tag). Unlike balance asser- + on the end date (and adds an "assign:" tag). Unlike balance asser- tions, assignments will post changes to balances as needed to reach the specified amounts. - This is another way to set starting balances when migrating to a new - file, and it will set them correctly even in the presence of earlier - files which do not have a closing balances transaction. However, it - can hide errors, and disturb the accounting equation, so --clopen is + This is another way to set starting balances when migrating to a new + file, and it will set them correctly even in the presence of earlier + files which do not have a closing balances transaction. However, it + can hide errors, and disturb the accounting equation, so --clopen is usually recommended. close --retain - This is like --close, but it closes Revenue and Expense account bal- - ances by default. They will be transferred to equity:retained earn- + This is like --close, but it closes Revenue and Expense account bal- + ances by default. They will be transferred to equity:retained earn- ings, or another account specified with --close-acct. - Revenues and expenses correspond to changes in equity. They are cate- + Revenues and expenses correspond to changes in equity. They are cate- gorised separately for reporting purposes, but traditionally at the end - of each accounting period, businesses consolidate them into equity, + of each accounting period, businesses consolidate them into equity, This is called "retaining earnings", or "closing the books". - In personal accounting, there's not much reason to do this, and most - people don't. (One reason to do it is to help the balancesheetequity - report show a zero total, demonstrating that the accounting equation + In personal accounting, there's not much reason to do this, and most + people don't. (One reason to do it is to help the balancesheetequity + report show a zero total, demonstrating that the accounting equation (A-L=E) is satisfied.) close customisation @@ -9882,56 +9967,56 @@ Data generation 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 transactions' clopen tag value, with a TAGVAL argument for the + o the transactions' clopen tag value, with a TAGVAL argument for the mode flag (see above). - 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. - Single-commodity, subaccount-exclusive balance assertions (=) are gen- - erated by default. This can be changed with --assertion-type='==*' + 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), + 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: @@ -9952,7 +10037,7 @@ Data generation 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' @@ -9964,12 +10049,12 @@ Data generation 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 + For more flexibility, it helps to tag closing and opening transactions with eg clopen:NEWYEAR, then you can ensure correct balances by exclud- ing all opening/closing transactions except the first, like so: @@ -9985,7 +10070,7 @@ Data generation commands 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. Flags: @@ -9999,9 +10084,9 @@ Data generation commands patch tool 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: @@ -10017,7 +10102,7 @@ Data generation 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: @@ -10027,16 +10112,16 @@ Data generation 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. @@ -10051,7 +10136,7 @@ Data generation 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. @@ -10064,12 +10149,12 @@ Data generation 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' @@ -10093,10 +10178,10 @@ Data generation 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: @@ -10104,17 +10189,17 @@ Data generation 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. Maintenance commands @@ -10124,62 +10209,62 @@ Maintenance commands Flags: no command-specific flags - hledger provides a number of built-in correctness checks to help vali- - date your data and prevent errors. Some are run automatically, some - when you enable --strict mode; or you can run any of them on demand by - providing them as arguments to the check command. check produces no + hledger provides a number of built-in correctness checks to help vali- + date your data and prevent errors. Some are run automatically, some + when you enable --strict mode; or you can run any of them on demand by + providing them as arguments to the check command. check produces no output and a zero exit code if all is well. Eg: hledger check # run basic checks hledger check -s # run basic and strict checks hledger check ordereddates payees # run basic checks and two others - 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. They are generally checked in - the order they are shown here, and only the first failure will be re- + the order they are shown here, and only the first failure will be re- ported. Basic checks - These important checks are performed by default, by almost all hledger + These important checks are performed by default, by almost all hledger commands: - o parseable - data files are in a supported format, with no syntax er- - rors and no invalid include directives. This ensures that all files + o parseable - data files are in a supported format, with no syntax er- + rors and no invalid include directives. This ensures that all files exist and are readable. o autobalanced - all transactions are balanced, after automatically in- - ferring missing amounts and conversion rates and then converting - amounts to cost. This ensures that each transaction's journal entry + ferring missing amounts and conversion rates and then converting + amounts to cost. This ensures that each transaction's journal entry is well formed. o assertions - all balance assertions in the journal are passing. Bal- - ance assertions are a strong defense against errors, catching many - problems. This check is on by default, but if it gets in your way, - you can disable it temporarily with -I/--ignore-assertions, or as a + ance assertions are a strong defense against errors, catching many + problems. This check is on by default, but if it gets in your way, + you can disable it temporarily with -I/--ignore-assertions, or as a default by adding that flag to your config file. (Then use -s/--strict or hledger check assertions when you want to enable it). Strict checks - When the -s/--strict flag is used (AKA strict mode), all commands will + When the -s/--strict flag is used (AKA strict mode), all commands will perform the following additional checks (and assertions, above). These provide extra error-catching power to help you keep your data clean and correct: - o balanced - like autobalanced, but implicit conversions between com- - modities are not allowed; all conversion transactions must use cost - notation or equity postings. This prevents wrong conversions caused + o balanced - like autobalanced, but implicit conversions between com- + modities are not allowed; all conversion transactions must use cost + notation or equity postings. This prevents wrong conversions caused by typos. - o commodities - all commodity symbols used must be declared. This + o commodities - all commodity symbols used must be declared. This guards against mistyping or omitting commodity symbols. - o accounts - all account names used must be declared. This prevents + o accounts - all account names used must be declared. This prevents the use of mis-spelled or outdated account names. Other checks - These are not wanted by everyone, but can be run using the check com- + These are not wanted by everyone, but can be run using the check com- mand: o tags - all tags used must be declared. This prevents mis-spelled tag @@ -10189,38 +10274,38 @@ Maintenance commands force you to declare any new payee name before using it. Most people will probably find this a bit too strict. - o ordereddates - within each file, transactions must be ordered by - date. This is a simple and effective error catcher. It's not in- + o ordereddates - within each file, transactions must be ordered by + date. This is a simple and effective error catcher. It's not in- cluded in strict mode, but you can add it by running hledger check -s ordereddates. If enabled, this check is performed before balance as- sertions. o recentassertions - all accounts with balance assertions must have one - that's within the 7 days before their latest posting. This will en- + that's within the 7 days before their latest posting. This will en- courage adding balance assertions for your active asset/liability ac- - counts, which in turn should encourage you to reconcile regularly - with those real world balances - another strong defense against er- - rors. (hledger close --assert >>$LEDGER_FILE is a convenient way to - add new balance assertions. Later these become quite redundant, and + counts, which in turn should encourage you to reconcile regularly + with those real world balances - another strong defense against er- + rors. (hledger close --assert >>$LEDGER_FILE is a convenient way to + add new balance assertions. Later these become quite redundant, and you might choose to remove them to reduce clutter.) o uniqueleafnames - no two accounts may have the same last account name - part (eg the checking in assets:bank:checking). This ensures each + part (eg the checking in assets:bank:checking). This ensures each account can be matched by a unique short name, easier to remember and to type. Custom checks - You can build your own custom checks with add-on command scripts. See + You can build your own custom checks with add-on command scripts. See also Cookbook > Scripting. Here are some examples from hledger/bin/: - o hledger-check-tagfiles - all tag values containing / exist as file + o hledger-check-tagfiles - all tag values containing / exist as file paths - o hledger-check-fancyassertions - more complex balance assertions are + o hledger-check-fancyassertions - more complex balance assertions are passing 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. @@ -10228,16 +10313,16 @@ Maintenance commands no command-specific flags More precisely: for each posting affecting this account in either file, - this command looks for a corresponding posting in the other file which - posts the same amount to the same account (ignoring date, description, + this command looks for a corresponding posting in the other file which + posts the same amount to the same account (ignoring date, description, etc). Since it compares postings, not transactions, this also works when mul- tiple bank transactions have been combined into a single journal entry. - This command is useful eg if you have downloaded an account's transac- - tions from your bank (eg as CSV data): when hledger and your bank dis- - agree about the account balance, you can compare the bank data with + This command is useful eg if you have downloaded an account's transac- + tions from your bank (eg as CSV data): when hledger and your bank dis- + agree about the account balance, you can compare the bank data with your journal to find out the cause. Examples: @@ -10258,18 +10343,18 @@ Maintenance commands Flags: no command-specific flags - setup tests your hledger installation and prints a list of results, - sometimes with helpful hints. This is a good first command to run af- - ter installing hledger. Also after upgrading, or when something's not + setup tests your hledger installation and prints a list of results, + sometimes with helpful hints. This is a good first command to run af- + ter installing hledger. Also after upgrading, or when something's not working, or just when you want a reminder of where things are. - It makes one network request to detect the latest hledger release ver- - sion. It's ok if this fails or times out. It will use ANSI color by - default, unless disabled by NO_COLOR or --color=n. It does not use a + It makes one network request to detect the latest hledger release ver- + sion. It's ok if this fails or times out. It will use ANSI color by + default, unless disabled by NO_COLOR or --color=n. It does not use a pager or a config file. - It expects that the hledger version you are running is installed in - your PATH. If not, it will stop until you have done that (to keep + It expects that the hledger version you are running is installed in + your PATH. If not, it will stop until you have done that (to keep things simple). Example: @@ -10319,17 +10404,17 @@ Maintenance commands Flags: no command-specific flags - This command runs the unit tests built in to hledger and hledger-lib, - printing the results on stdout. If any test fails, the exit code will + This command runs the unit tests built in to hledger and hledger-lib, + printing the results on stdout. If any test fails, the exit code will be non-zero. - This is mainly used by hledger developers, but you can also use it to - sanity-check the installed hledger executable on your platform. All - tests are expected to pass - if you ever see a failure, please report + This is mainly used by hledger developers, but you can also use it to + sanity-check the installed hledger executable on your platform. All + tests are expected to pass - if you ever see a failure, please report as a bug! - Any arguments before a -- argument will be passed to the tasty test - runner as test-selecting -p patterns, and any arguments after -- will + Any arguments before a -- argument will be passed to the tasty test + runner as test-selecting -p patterns, and any arguments after -- will be passed to tasty unchanged. Examples: @@ -10339,7 +10424,7 @@ Maintenance commands $ hledger test -- -h # show tasty's options PART 5: COMMON TASKS - Here are some quick examples of how to do some basic tasks with + Here are some quick examples of how to do some basic tasks with hledger. Getting help @@ -10349,37 +10434,37 @@ PART 5: COMMON TASKS $ hledger --help # show common options $ hledger CMD --help # show CMD's options, common options and CMD's documentation - You can also view your hledger version's manual in several formats by + You can also view your hledger version's manual in several formats by using the help command. Eg: $ hledger help # show the hledger manual with info, man or $PAGER (best available) $ hledger help journal # show the journal topic in the hledger manual $ hledger help --help # find out more about the help command - To view manuals and introductory docs on the web, visit - https://hledger.org. Chat and mail list support and discussion + To view manuals and introductory docs on the web, visit + https://hledger.org. Chat and mail list support and discussion archives can be found at https://hledger.org/support. Constructing command lines - hledger has a flexible command line interface. We strive to keep it - simple and ergonomic, but if you run into one of the sharp edges de- + hledger has a flexible command line interface. We strive to keep it + simple and ergonomic, but if you run into one of the sharp edges de- scribed in OPTIONS, here are some tips that might help: - o command-specific options must go after the command (it's fine to put + o command-specific options must go after the command (it's fine to put common options there too: hledger CMD OPTS ARGS) - o you can run addon commands via hledger (hledger ui [ARGS]) or di- + o you can run addon commands via hledger (hledger ui [ARGS]) or di- rectly (hledger-ui [ARGS]) o enclose "problematic" arguments in single quotes - o if needed, also add a backslash to hide regular expression metachar- + o if needed, also add a backslash to hide regular expression metachar- acters from the shell o to see how a misbehaving command line is being parsed, add --debug=2. Starting a journal file - hledger looks for your accounting data in a journal file, + hledger looks for your accounting data in a journal file, $HOME/.hledger.journal by default: $ hledger stats @@ -10387,9 +10472,9 @@ PART 5: COMMON TASKS Please create it first, eg with "hledger add" or a text editor. Or, specify an existing journal file with -f or LEDGER_FILE. - You can override this by setting the LEDGER_FILE environment variable - (see below). It's a good practice to keep this important file under - version control, and to start a new file each year. So you could do + You can override this by setting the LEDGER_FILE environment variable + (see below). It's a good practice to keep this important file under + version control, and to start a new file each year. So you could do something like this: $ mkdir ~/finance @@ -10414,7 +10499,7 @@ PART 5: COMMON TASKS Setting LEDGER_FILE Set LEDGER_FILE on unix - It depends on your shell, but running these commands in the terminal + It depends on your shell, but running these commands in the terminal will work for many people; adapt if needed: $ echo 'export LEDGER_FILE=~/finance/my.journal' >> ~/.profile @@ -10437,38 +10522,38 @@ PART 5: COMMON TASKS "LEDGER_FILE" : "~/finance/my.journal" } - 2. Run killall Dock in a terminal window (or restart the machine), to + 2. Run killall Dock in a terminal window (or restart the machine), to complete the change. When correctly configured for GUI applications: - o apps started from the dock or a spotlight search, such as a GUI + o apps started from the dock or a spotlight search, such as a GUI Emacs, will be aware of the new LEDGER_FILE setting. Set LEDGER_FILE on Windows Using the gui is easiest: - 1. In task bar, search for environment variables, and choose "Edit en- + 1. In task bar, search for environment variables, and choose "Edit en- vironment variables for your account". - 2. Create or change a LEDGER_FILE setting in the User variables pane. + 2. Create or change a LEDGER_FILE setting in the User variables pane. A typical value would be C:\Users\USERNAME\finance\my.journal. 3. Click OK to complete the change. - 4. And open a new powershell window. (Existing windows won't see the + 4. And open a new powershell window. (Existing windows won't see the change.) Or at the command line, you can do it this way: - 1. In a powershell window, run [Environment]::SetEnvironmentVari- + 1. In a powershell window, run [Environment]::SetEnvironmentVari- able("LEDGER_FILE", "C:\User\USERNAME\finance\my.journal", [Sys- tem.EnvironmentVariableTarget]::User) - 2. And open a new powershell window. (Existing windows won't see the + 2. And open a new powershell window. (Existing windows won't see the change.) - Warning, doing this from the Windows command line can be tricky; other + Warning, doing this from the Windows command line can be tricky; other methods you may find online: o may not affect the current window @@ -10491,26 +10576,26 @@ PART 5: COMMON TASKS When correctly configured: - o in a new powershell window, $env:LEDGER_FILE will show your new set- + o in a new powershell window, $env:LEDGER_FILE will show your new set- ting o and so should hledger setup and (once the file exists) hledger files. Setting opening balances - Pick a starting date for which you can look up the balances of some - real-world assets (bank accounts, wallet..) and liabilities (credit + Pick a starting date for which you can look up the balances of some + real-world assets (bank accounts, wallet..) and liabilities (credit cards..). - To avoid a lot of data entry, you may want to start with just one or + To avoid a lot of data entry, you may want to start with just one or two accounts, like your checking account or cash wallet; and pick a re- - cent starting date, like today or the start of the week. You can al- - ways come back later and add more accounts and older transactions, eg + cent starting date, like today or the start of the week. You can al- + ways come back later and add more accounts and older transactions, eg going back to january 1st. - Add an opening balances transaction to the journal, declaring the bal- + Add an opening balances transaction to the journal, declaring the bal- ances on this date. Here are two ways to do it: - o The first way: open the journal in any text editor and save an entry + o The first way: open the journal in any text editor and save an entry like this: 2023-01-01 * opening balances @@ -10520,19 +10605,19 @@ PART 5: COMMON TASKS liabilities:creditcard $-50 = $-50 equity:opening/closing balances - These are start-of-day balances, ie whatever was in the account at + These are start-of-day balances, ie whatever was in the account at the end of the previous day. - The * after the date is an optional status flag. Here it means + The * after the date is an optional status flag. Here it means "cleared & confirmed". - The currency symbols are optional, but usually a good idea as you'll + The currency symbols are optional, but usually a good idea as you'll be dealing with multiple currencies sooner or later. - The = amounts are optional balance assertions, providing extra error + The = amounts are optional balance assertions, providing extra error checking. - o The second way: run hledger add and follow the prompts to record a + o The second way: run hledger add and follow the prompts to record a similar transaction: $ hledger add @@ -10569,18 +10654,18 @@ PART 5: COMMON TASKS Starting the next transaction (. or ctrl-D/ctrl-C to quit) Date [2023-01-01]: . - If you're using version control, this could be a good time to commit + If you're using version control, this could be a good time to commit the journal. Eg: $ git commit -m 'initial balances' 2023.journal Recording transactions - As you spend or receive money, you can record these transactions using - one of the methods above (text editor, hledger add) or by using the - hledger-iadd or hledger-web add-ons, or by using the import command to + As you spend or receive money, you can record these transactions using + one of the methods above (text editor, hledger add) or by using the + hledger-iadd or hledger-web add-ons, or by using the import command to convert CSV data downloaded from your bank. - Here are some simple transactions, see the hledger_journal(5) manual + Here are some simple transactions, see the hledger_journal(5) manual and hledger.org for more ideas: 2023/1/10 * gift received @@ -10596,22 +10681,22 @@ PART 5: COMMON TASKS assets:bank:checking $1000 Reconciling - Periodically you should reconcile - compare your hledger-reported bal- - ances against external sources of truth, like bank statements or your - bank's website - to be sure that your ledger accurately represents the - real-world balances (and, that the real-world institutions have not - made a mistake!). This gets easy and fast with (1) practice and (2) - frequency. If you do it daily, it can take 2-10 minutes. If you let - it pile up, expect it to take longer as you hunt down errors and dis- + Periodically you should reconcile - compare your hledger-reported bal- + ances against external sources of truth, like bank statements or your + bank's website - to be sure that your ledger accurately represents the + real-world balances (and, that the real-world institutions have not + made a mistake!). This gets easy and fast with (1) practice and (2) + frequency. If you do it daily, it can take 2-10 minutes. If you let + it pile up, expect it to take longer as you hunt down errors and dis- crepancies. A typical workflow: - 1. Reconcile cash. Count what's in your wallet. Compare with what - hledger reports (hledger bal cash). If they are different, try to - remember the missing transaction, or look for the error in the al- - ready-recorded transactions. A register report can be helpful - (hledger reg cash). If you can't find the error, add an adjustment + 1. Reconcile cash. Count what's in your wallet. Compare with what + hledger reports (hledger bal cash). If they are different, try to + remember the missing transaction, or look for the error in the al- + ready-recorded transactions. A register report can be helpful + (hledger reg cash). If you can't find the error, add an adjustment transaction. Eg if you have $105 after the above, and can't explain the missing $2, it could be: @@ -10621,26 +10706,26 @@ PART 5: COMMON TASKS 2. Reconcile checking. Log in to your bank's website. Compare today's (cleared) balance with hledger's cleared balance (hledger bal check- - ing -C). If they are different, track down the error or record the - missing transaction(s) or add an adjustment transaction, similar to + ing -C). If they are different, track down the error or record the + missing transaction(s) or add an adjustment transaction, similar to the above. Unlike the cash case, you can usually compare the trans- - action history and running balance from your bank with the one re- - ported by hledger reg checking -C. This will be easier if you gen- - erally record transaction dates quite similar to your bank's clear- + action history and running balance from your bank with the one re- + ported by hledger reg checking -C. This will be easier if you gen- + erally record transaction dates quite similar to your bank's clear- ing dates. 3. Repeat for other asset/liability accounts. - Tip: instead of the register command, use hledger-ui to see a live-up- + Tip: instead of the register command, use hledger-ui to see a live-up- dating register while you edit the journal: hledger-ui --watch --regis- ter checking -C - After reconciling, it could be a good time to mark the reconciled - transactions' status as "cleared and confirmed", if you want to track - that, by adding the * marker. Eg in the paycheck transaction above, + After reconciling, it could be a good time to mark the reconciled + transactions' status as "cleared and confirmed", if you want to track + that, by adding the * marker. Eg in the paycheck transaction above, insert * between 2023-01-15 and paycheck - If you're using version control, this can be another good time to com- + If you're using version control, this can be another good time to com- mit: $ git commit -m 'txns' 2023.journal @@ -10712,7 +10797,7 @@ PART 5: COMMON TASKS -------------------- 0 - Show only asset and liability balances, as a flat list, limited to + Show only asset and liability balances, as a flat list, limited to depth 2: $ hledger bal assets liabilities -2 @@ -10722,7 +10807,7 @@ PART 5: COMMON TASKS -------------------- $4055 - Show the same thing without negative numbers, formatted as a simple + Show the same thing without negative numbers, formatted as a simple balance sheet: $ hledger bs -2 @@ -10789,62 +10874,62 @@ PART 5: COMMON TASKS 2023-01-13 **** Migrating to a new file - At the end of the year, you may want to continue your journal in a new + At the end of the year, you may want to continue your journal in a new file, so that old transactions don't slow down or clutter your reports, - and to help ensure the integrity of your accounting history. See the + and to help ensure the integrity of your accounting history. See the close command. If using version control, don't forget to git add the new file. BUGS - We welcome bug reports in the hledger issue tracker + We welcome bug reports in the hledger issue tracker (https://bugs.hledger.org), or on the hledger chat or mail list (https://hledger.org/support). Some known issues and limitations: - hledger uses the system's text encoding when reading non-ascii text. - If no system encoding is configured, or if the data's encoding is dif- - ferent, hledger will give an error. (See Text encoding, Troubleshoot- + hledger uses the system's text encoding when reading non-ascii text. + If no system encoding is configured, or if the data's encoding is dif- + ferent, hledger will give an error. (See Text encoding, Troubleshoot- ing.) - On Microsoft Windows, depending what kind of terminal window you use, - non-ascii characters, ANSI text formatting, and/or the add command's - TAB key, may not be fully supported. (For best results, try a power- + On Microsoft Windows, depending what kind of terminal window you use, + non-ascii characters, ANSI text formatting, and/or the add command's + TAB key, may not be fully supported. (For best results, try a power- shell window.) When processing large data files, hledger uses more memory than Ledger. Troubleshooting - Here are some common issues you might encounter when you run hledger, - and how to resolve them (and remember also you can usually get quick + Here are some common issues you might encounter when you run hledger, + and how to resolve them (and remember also you can usually get quick Support): PATH issues: I get an error like "No command 'hledger' found" Depending how you installed hledger, the executables may not be in your - shell's PATH. Eg on unix systems, stack installs hledger in ~/.lo- + shell's PATH. Eg on unix systems, stack installs hledger in ~/.lo- cal/bin and cabal installs it in ~/.cabal/bin. You may need to add one - of these directories to your shell's PATH, and/or open a new terminal + of these directories to your shell's PATH, and/or open a new terminal window. - LEDGER_FILE issues: I configured LEDGER_FILE but hledger is not using + LEDGER_FILE issues: I configured LEDGER_FILE but hledger is not using it - o LEDGER_FILE should be a real environment variable, not just a shell + o LEDGER_FILE should be a real environment variable, not just a shell variable. Eg on unix, the command env | grep LEDGER_FILE should show - it. You may need to use export (see https://stackover- + it. You may need to use export (see https://stackover- flow.com/a/7411509). On Windows, $env:LEDGER_FILE should show it. - o You may need to force your shell to see the new configuration. A + o You may need to force your shell to see the new configuration. A simple way is to close your terminal window and open a new one. Text decoding issues: I get errors like "Illegal byte sequence" or "In- - valid or incomplete multibyte or wide character" or "commitAndRelease- + valid or incomplete multibyte or wide character" or "commitAndRelease- Buffer: invalid argument (invalid character)" - hledger usually needs its input to be decodable with the system lo- + hledger usually needs its input to be decodable with the system lo- cale's text encoding. See Text encoding and Install: Text encoding. COMPATIBILITY ISSUES: hledger gives an error with my Ledger file - Not all of Ledger's journal file syntax or feature set is supported. + Not all of Ledger's journal file syntax or feature set is supported. See hledger and Ledger for full details.