From fcebdfe0cc26098f1eacf8107f2cc860118ffcb6 Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Sat, 26 Jun 2021 00:06:14 -1000 Subject: [PATCH] ;update manuals --- hledger/hledger.1 | 278 ++++++----- hledger/hledger.info | 1007 ++++++++++++++++++++++----------------- hledger/hledger.txt | 1075 ++++++++++++++++++++++-------------------- 3 files changed, 1303 insertions(+), 1057 deletions(-) diff --git a/hledger/hledger.1 b/hledger/hledger.1 index 17a3ac001..a045f5cfe 100644 --- a/hledger/hledger.1 +++ b/hledger/hledger.1 @@ -5263,6 +5263,12 @@ With this scheme, you would use \f[C]-PC\f[R] to see the current balance at your bank, \f[C]-U\f[R] to see things which will probably hit your bank soon (like uncashed checks), and no flags to see the most up-to-date state of your finances. +.SS Code +.PP +After the status mark, but before the description, you can optionally +write a transaction \[dq]code\[dq], enclosed in parentheses. +This is a good place to record a check number, or some other important +transaction id or reference number. .SS Description .PP A transaction\[aq]s description is the rest of the line following the @@ -6395,28 +6401,26 @@ rate between two commodities on a certain date. often obtained from a stock exchange, cryptocurrency exchange, or the foreign exchange market. .PP -Here is the format: +The format is: .IP .nf \f[C] -P DATE COMMODITYA COMMODITYBAMOUNT +P DATE COMMODITY1SYMBOL COMMODITY2AMOUNT \f[R] .fi -.IP \[bu] 2 -DATE is a simple date -.IP \[bu] 2 -COMMODITYA is the symbol of the commodity being priced -.IP \[bu] 2 -COMMODITYBAMOUNT is an amount (symbol and quantity) in a second -commodity, giving the price in commodity B of one unit of commodity A. .PP -These two market price directives say that one euro was worth 1.35 US -dollars during 2009, and $1.40 from 2010 onward: +DATE is a simple date, COMMODITY1SYMBOL is the symbol of the commodity +being priced, and COMMODITY2AMOUNT is the amount (symbol and quantity) +of commodity 2 that one unit of commodity 1 is worth on this date. +Examples: .IP .nf \f[C] -P 2009/1/1 \[Eu] $1.35 -P 2010/1/1 \[Eu] $1.40 +# one euro was worth $1.35 from 2009-01-01 onward: +P 2009-01-01 \[Eu] $1.35 + +# and $1.40 from 2010-01-01 onward: +P 2010-01-01 \[Eu] $1.40 \f[R] .fi .PP @@ -7212,14 +7216,14 @@ below, after the examples: .PP .TS tab(@); -lw(30.1n) lw(39.9n). +lw(26.4n) lw(43.6n). T{ \f[B]\f[CB]skip\f[B]\f[R] T}@T{ skip one or more header lines or matched CSV records T} T{ -\f[B]\f[CB]fields\f[B]\f[R] +\f[B]\f[CB]fields\f[B] list\f[R] T}@T{ name CSV fields, assign them to hledger fields T} @@ -7229,6 +7233,11 @@ T}@T{ assign a value to one hledger field, with interpolation T} T{ +\f[B]Field names\f[R] +T}@T{ +hledger field names, used in the fields list and field assignments +T} +T{ \f[B]\f[CB]separator\f[B]\f[R] T}@T{ a custom field separator @@ -7633,7 +7642,7 @@ whenever your CSV data contains header lines. .PP It also has a second purpose: it can be used inside if blocks to ignore certain CSV records (described below). -.SS \f[C]fields\f[R] +.SS \f[C]fields\f[R] list .IP .nf \f[C] @@ -7644,13 +7653,14 @@ fields FIELDNAME1, FIELDNAME2, ... A fields list (the word \[dq]fields\[dq] followed by comma-separated field names) is the quick way to assign CSV field values to hledger fields. -It does two things: +(The other way is field assignments, see below.) A fields list does does +two things: .IP "1." 3 -it names the CSV fields. +It names the CSV fields. This is optional, but can be convenient later for interpolating them. .IP "2." 3 -when you use a standard hledger field name, it assigns the CSV value to -that part of the hledger transaction. +Whenever you use a standard hledger field name (defined below), the CSV +value is assigned to that part of the hledger transaction. .PP Here\[aq]s an example that says \[dq]use the 1st, 2nd and 4th fields as the transaction\[aq]s date, description and amount; name the last two @@ -7662,91 +7672,27 @@ fields date, description, , amount, , , somefield, anotherfield \f[R] .fi .PP -Field names may not contain whitespace. -Fields you don\[aq]t care about can be left unnamed. -Currently there must be least two items (there must be at least one -comma). -.PP -Note, always use comma in the fields list, even if your CSV uses another +Tips: +.IP \[bu] 2 +The fields list always use commas, even if your CSV data uses another separator character. -.PP -Here are the standard hledger field/pseudo-field names. -For more about the transaction parts they refer to, see the manual for -hledger\[aq]s journal format. -.SS Transaction field names -.PP -\f[C]date\f[R], \f[C]date2\f[R], \f[C]status\f[R], \f[C]code\f[R], -\f[C]description\f[R], \f[C]comment\f[R] can be used to form the -transaction\[aq]s first line. -.SS Posting field names -.SS account -.PP -\f[C]accountN\f[R], where N is 1 to 99, causes a posting to be -generated, with that account name. -.PP -Most often there are two postings, so you\[aq]ll want to set -\f[C]account1\f[R] and \f[C]account2\f[R]. -Typically \f[C]account1\f[R] is associated with the CSV file, and is set -once with a top-level assignment, while \f[C]account2\f[R] is set based -on each transaction\[aq]s description, and in conditional blocks. -.PP -If a posting\[aq]s account name is left unset but its amount is set (see -below), a default account name will be chosen (like -\[dq]expenses:unknown\[dq] or \[dq]income:unknown\[dq]). -.SS amount -.PP -\f[C]amountN\f[R] sets the Nth posting\[aq]s amount. -By assigning to \f[C]amount1\f[R], \f[C]amount2\f[R], ... -etc. -you can generate up to 99 postings. -.PP -If the CSV uses separate fields for debits and credits (inflows and -outflows), you can use \f[C]amountN-in\f[R] and \f[C]amountN-out\f[R] -instead. -Note hledger assumes both of these fields are unsigned, and will -automatically negate the \[dq]-out\[dq] value. -If the fields are signed, see \[dq]Setting amounts\[dq] below. -.PP -There is also an unnumbered form of these names: \f[C]amount\f[R], or -\f[C]amount-in\f[R] and \f[C]amount-out\f[R]. -This is supported to keep pre-hledger-1.17 CSV rules files working (and -for occasional convenience). -It is suitable only for two-posting transactions; it sets both posting -1\[aq]s and posting 2\[aq]s amount. -Posting 2\[aq]s amount will be negated, and also converted to cost if -there\[aq]s a transaction price. -.PP -If you have an existing rules file using the unnumbered form, you might -want to use the numbered form in certain conditional blocks, without -having to update and retest all the old rules. -To facilitate this, posting 1 ignores -\f[C]amount\f[R]/\f[C]amount-in\f[R]/\f[C]amount-out\f[R] if any of -\f[C]amount1\f[R]/\f[C]amount1-in\f[R]/\f[C]amount1-out\f[R] are -assigned, and posting 2 ignores them if any of -\f[C]amount2\f[R]/\f[C]amount2-in\f[R]/\f[C]amount2-out\f[R] are -assigned, avoiding conflicts. -.SS currency -.PP -If the CSV has the currency symbol in a separate field (ie, not part of -the amount field), you can use \f[C]currencyN\f[R] to prepend it to -posting N\[aq]s amount. -Or, \f[C]currency\f[R] with no number affects all postings. -.SS balance -.PP -\f[C]balanceN\f[R] sets a balance assertion amount (or if the posting -amount is left empty, a balance assignment) on posting N. -.PP -Also, for compatibility with hledger <1.17: \f[C]balance\f[R] with no -number is equivalent to \f[C]balance1\f[R]. -.PP -You can adjust the type of assertion/assignment with the -\f[C]balance-type\f[R] rule (see below). -.SS comment -.PP -Finally, \f[C]commentN\f[R] sets a comment on the Nth posting. -Comments can also contain tags, as usual. -.PP -See TIPS below for more about setting amounts and currency. +.IP \[bu] 2 +Currently there must be least two items in the list (at least one +comma). +.IP \[bu] 2 +Field names may not contain spaces. +Spaces before/after field names are optional. +.IP \[bu] 2 +If the CSV contains column headings, it\[aq]s a good idea to use these, +suitably modified, as the basis for your field names (eg lower-cased, +with underscores instead of spaces). +.IP \[bu] 2 +If some heading names match standard hledger fields, but you don\[aq]t +want to set the hledger fields directly, alter those names, eg by +appending an underscore. +.IP \[bu] 2 +Fields you don\[aq]t care about can be given a dummy name (eg: +\f[C]_\f[R] ), or no name. .SS field assignment .IP .nf @@ -7755,13 +7701,17 @@ HLEDGERFIELDNAME FIELDVALUE \f[R] .fi .PP -Instead of or in addition to a fields list, you can use a \[dq]field -assignment\[dq] rule to set the value of a single hledger field, by -writing its name (any of the standard hledger field names above) -followed by a text value. -The value may contain interpolated CSV fields, referenced by their -1-based position in the CSV record (\f[C]%N\f[R]), or by the name they -were given in the fields list (\f[C]%CSVFIELDNAME\f[R]). +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). +.PP +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 interpolate CSV fields, referenced by their 1-based +position in the CSV record (\f[C]%N\f[R]), or by the name they were +given in the fields list (\f[C]%CSVFIELDNAME\f[R]). +.PP Some examples: .IP .nf @@ -7774,9 +7724,108 @@ comment note: %somefield - %anotherfield, date: %1 \f[R] .fi .PP +Tips: +.IP \[bu] 2 Interpolation strips outer whitespace (so a CSV value like \f[C]\[dq] 1 \[dq]\f[R] becomes \f[C]1\f[R] when interpolated) (#1051). -See TIPS below for more about referencing other fields. +.IP \[bu] 2 +See also Tips below. +.SS Field names +.PP +Here are the standard hledger field (and pseudo-field) names, which you +can use in a fields list and in field assignments. +For more about the transaction parts they refer to, see Transactions. +.SS date field +.PP +Assigning to \f[C]date\f[R] sets the transaction date. +.SS date2 field +.PP +\f[C]date2\f[R] sets the transaction\[aq]s secondary date, if any. +.SS status field +.PP +\f[C]status\f[R] sets the transaction\[aq]s status, if any. +.SS code field +.PP +\f[C]code\f[R] sets the transaction\[aq]s code, if any. +.SS description field +.PP +\f[C]description\f[R] sets the transaction\[aq]s description, if any. +.SS comment field +.PP +\f[C]comment\f[R] sets the transaction\[aq]s comment, if any. +.PP +\f[C]commentN\f[R], where N is a number, sets the Nth posting\[aq]s +comment. +.PP +Tips: - Only single-line comments can be assigned. +- Comments can contain tags, as usual. +.SS account field +.PP +Assigning to \f[C]accountN\f[R], where N is 1 to 99, sets the account +name of the Nth posting, and causes that posting to be generated. +.PP +Most often there are two postings, so you\[aq]ll want to set +\f[C]account1\f[R] and \f[C]account2\f[R]. +Typically \f[C]account1\f[R] is associated with the CSV file, and is set +once with a top-level assignment, while \f[C]account2\f[R] is set based +on each transaction\[aq]s description, and in conditional blocks. +.PP +If a posting\[aq]s account name is left unset but its amount is set (see +below), a default account name will be chosen (like +\[dq]expenses:unknown\[dq] or \[dq]income:unknown\[dq]). +.SS amount field +.PP +\f[C]amountN\f[R] sets the amount of the Nth posting, and causes that +posting to be generated. +By assigning to \f[C]amount1\f[R], \f[C]amount2\f[R], ... +etc. +you can generate up to 99 postings. +.PP +\f[C]amountN-in\f[R] and \f[C]amountN-out\f[R] can be used instead, if +the CSV uses separate fields for debits and credits (inflows and +outflows). +hledger assumes both of these CSV fields are unsigned, and will +automatically negate the \[dq]-out\[dq] value. +If they are signed, see \[dq]Setting amounts\[dq] below. +.PP +\f[C]amount\f[R], or \f[C]amount-in\f[R] and \f[C]amount-out\f[R] are a +legacy mode, to keep pre-hledger-1.17 CSV rules files working (and for +occasional convenience). +They are suitable only for two-posting transactions; they set both +posting 1\[aq]s and posting 2\[aq]s amount. +Posting 2\[aq]s amount will be negated, and also converted to cost if +there\[aq]s a transaction price. +.PP +If you have an existing rules file using the unnumbered form, you might +want to use the numbered form in certain conditional blocks, without +having to update and retest all the old rules. +To facilitate this, posting 1 ignores +\f[C]amount\f[R]/\f[C]amount-in\f[R]/\f[C]amount-out\f[R] if any of +\f[C]amount1\f[R]/\f[C]amount1-in\f[R]/\f[C]amount1-out\f[R] are +assigned, and posting 2 ignores them if any of +\f[C]amount2\f[R]/\f[C]amount2-in\f[R]/\f[C]amount2-out\f[R] are +assigned, avoiding conflicts. +.SS currency field +.PP +\f[C]currency\f[R] sets a currency symbol, to be prepended to all +postings\[aq] amounts. +You can use this if the CSV amounts do not have a currency symbol, eg if +it is in a separate column. +.PP +\f[C]currencyN\f[R] prepends a currency symbol to just the Nth +posting\[aq]s amount. +.SS balance field +.PP +\f[C]balanceN\f[R] sets a balance assertion amount (or if the posting +amount is left empty, a balance assignment) on posting N. +.PP +\f[C]balance\f[R] is a compatibility spelling for hledger <1.17; it is +equivalent to \f[C]balance1\f[R]. +.PP +You can adjust the type of assertion/assignment with the +\f[C]balance-type\f[R] rule (see below). +.PP +See Tips below for more about setting amounts and currency. .SS \f[C]separator\f[R] .PP You can use the \f[C]separator\f[R] rule to read other kinds of @@ -8052,6 +8101,11 @@ For the supported strptime syntax, see: .P .PD https://hackage.haskell.org/package/time/docs/Data-Time-Format.html#v:formatTime +.PP +Note that although you can parse date-times which include a time zone, +that time zone is ignored; it will not change the date that is parsed. +This means when reading CSV data with times not in your local time zone, +dates can be \[dq]off by one\[dq]. .SS \f[C]decimal-mark\f[R] .IP .nf diff --git a/hledger/hledger.info b/hledger/hledger.info index bab6fb658..9f0fa0ef6 100644 --- a/hledger/hledger.info +++ b/hledger/hledger.info @@ -4288,6 +4288,7 @@ that looks unnecessary right now. * Transactions:: * Dates:: * Status:: +* Code:: * Description:: * Comments:: * Tags:: @@ -4442,7 +4443,7 @@ characters in this way. With this syntax, DATE infers its year from the transaction and DATE2 infers its year from DATE.  -File: hledger.info, Node: Status, Next: Description, Prev: Dates, Up: JOURNAL FORMAT +File: hledger.info, Node: Status, Next: Code, Prev: Dates, Up: JOURNAL FORMAT 12.3 Status =========== @@ -4492,9 +4493,20 @@ your bank, '-U' to see things which will probably hit your bank soon your finances.  -File: hledger.info, Node: Description, Next: Comments, Prev: Status, Up: JOURNAL FORMAT +File: hledger.info, Node: Code, Next: Description, Prev: Status, Up: JOURNAL FORMAT -12.4 Description +12.4 Code +========= + +After the status mark, but before the description, you can optionally +write a transaction "code", enclosed in parentheses. This is a good +place to record a check number, or some other important transaction id +or reference number. + + +File: hledger.info, Node: Description, Next: Comments, Prev: Code, Up: JOURNAL FORMAT + +12.5 Description ================ A transaction's description is the rest of the line following the date @@ -4510,7 +4522,7 @@ comments.  File: hledger.info, Node: Payee and note, Up: Description -12.4.1 Payee and note +12.5.1 Payee and note --------------------- You can optionally include a '|' (pipe) character in descriptions to @@ -4522,7 +4534,7 @@ precise querying and pivoting by payee or by note.  File: hledger.info, Node: Comments, Next: Tags, Prev: Description, Up: JOURNAL FORMAT -12.5 Comments +12.6 Comments ============= Lines in the journal beginning with a semicolon (';') or hash ('#') or @@ -4562,7 +4574,7 @@ end comment  File: hledger.info, Node: Tags, Next: Postings, Prev: Comments, Up: JOURNAL FORMAT -12.6 Tags +12.7 Tags ========= Tags are a way to add extra labels or labelled data to postings and @@ -4605,7 +4617,7 @@ are simple strings.  File: hledger.info, Node: Postings, Next: Account names, Prev: Tags, Up: JOURNAL FORMAT -12.7 Postings +12.8 Postings ============= A posting is an addition of some amount to, or removal of some amount @@ -4637,7 +4649,7 @@ the amount, the amount will be considered part of the account name.  File: hledger.info, Node: Virtual postings, Up: Postings -12.7.1 Virtual postings +12.8.1 Virtual postings ----------------------- A posting with a parenthesised account name is called a _virtual @@ -4672,7 +4684,7 @@ postings_. You can exclude virtual postings from reports with the  File: hledger.info, Node: Account names, Next: Amounts, Prev: Postings, Up: JOURNAL FORMAT -12.8 Account names +12.9 Account names ================== Account names typically have several parts separated by a full colon, @@ -4690,8 +4702,8 @@ more spaces* (or newline).  File: hledger.info, Node: Amounts, Next: Transaction prices, Prev: Account names, Up: JOURNAL FORMAT -12.9 Amounts -============ +12.10 Amounts +============= After the account name, there is usually an amount. (Important: between account name and amount, there must be *two or more spaces*.) @@ -4739,8 +4751,8 @@ EUR 1E3  File: hledger.info, Node: Decimal marks digit group marks, Next: Commodity, Up: Amounts -12.9.1 Decimal marks, digit group marks ---------------------------------------- +12.10.1 Decimal marks, digit group marks +---------------------------------------- A decimal mark can be written as a period or a comma: @@ -4772,8 +4784,8 @@ about this.  File: hledger.info, Node: Commodity, Next: Commodity directives, Prev: Decimal marks digit group marks, Up: Amounts -12.9.2 Commodity ----------------- +12.10.2 Commodity +----------------- Amounts in hledger have both a "quantity", which is a signed decimal number, and a "commodity", which is a currency symbol, stock ticker, or @@ -4798,8 +4810,8 @@ these are the 'Amount' and 'MixedAmount' types.)  File: hledger.info, Node: Commodity directives, Next: Commodity display style, Prev: Commodity, Up: Amounts -12.9.3 Commodity directives ---------------------------- +12.10.3 Commodity directives +---------------------------- You can add 'commodity' directives to the journal, preferably at the top, to declare your commodities and help with number parsing (see @@ -4816,8 +4828,8 @@ commodity 1 000 000.9455  File: hledger.info, Node: Commodity display style, Next: Rounding, Prev: Commodity directives, Up: Amounts -12.9.4 Commodity display style ------------------------------- +12.10.4 Commodity display style +------------------------------- For the amounts in each commodity, hledger chooses a consistent display style to use in most reports. (Exceptions: price amounts, and all @@ -4871,8 +4883,8 @@ commodity 1 000.  File: hledger.info, Node: Rounding, Prev: Commodity display style, Up: Amounts -12.9.5 Rounding ---------------- +12.10.5 Rounding +---------------- Amounts are stored internally as decimal numbers with up to 255 decimal places, and displayed with the number of decimal places specified by the @@ -4884,7 +4896,7 @@ this could vary if hledger was built with Decimal < 0.5.1.)  File: hledger.info, Node: Transaction prices, Next: Lot prices lot dates, Prev: Amounts, Up: JOURNAL FORMAT -12.10 Transaction prices +12.11 Transaction prices ======================== Within a transaction, you can note an amount's price in another @@ -4951,7 +4963,7 @@ $ hledger bal -N --flat -B  File: hledger.info, Node: Lot prices lot dates, Next: Balance assertions, Prev: Transaction prices, Up: JOURNAL FORMAT -12.11 Lot prices, lot dates +12.12 Lot prices, lot dates =========================== Ledger allows another kind of price, lot price (four variants: @@ -4966,7 +4978,7 @@ assertion if any.  File: hledger.info, Node: Balance assertions, Next: Balance assignments, Prev: Lot prices lot dates, Up: JOURNAL FORMAT -12.12 Balance assertions +12.13 Balance assertions ======================== hledger supports Ledger-style balance assertions in journal files. @@ -5004,7 +5016,7 @@ does not disable balance assignments, below).  File: hledger.info, Node: Assertions and ordering, Next: Assertions and included files, Up: Balance assertions -12.12.1 Assertions and ordering +12.13.1 Assertions and ordering ------------------------------- hledger sorts an account's postings and assertions first by date and @@ -5023,7 +5035,7 @@ can assert intra-day balances.  File: hledger.info, Node: Assertions and included files, Next: Assertions and multiple -f options, Prev: Assertions and ordering, Up: Balance assertions -12.12.2 Assertions and included files +12.13.2 Assertions and included files ------------------------------------- With included files, things are a little more complicated. Including @@ -5035,7 +5047,7 @@ you'll have to put the assertion in the right file.  File: hledger.info, Node: Assertions and multiple -f options, Next: Assertions and commodities, Prev: Assertions and included files, Up: Balance assertions -12.12.3 Assertions and multiple -f options +12.13.3 Assertions and multiple -f options ------------------------------------------ Balance assertions don't work well across files specified with multiple @@ -5044,7 +5056,7 @@ Balance assertions don't work well across files specified with multiple  File: hledger.info, Node: Assertions and commodities, Next: Assertions and prices, Prev: Assertions and multiple -f options, Up: Balance assertions -12.12.4 Assertions and commodities +12.13.4 Assertions and commodities ---------------------------------- The asserted balance must be a simple single-commodity amount, and in @@ -5092,7 +5104,7 @@ commodity into its own subaccount:  File: hledger.info, Node: Assertions and prices, Next: Assertions and subaccounts, Prev: Assertions and commodities, Up: Balance assertions -12.12.5 Assertions and prices +12.13.5 Assertions and prices ----------------------------- Balance assertions ignore transaction prices, and should normally be @@ -5110,7 +5122,7 @@ _assignments_ do use them (see below).  File: hledger.info, Node: Assertions and subaccounts, Next: Assertions and virtual postings, Prev: Assertions and prices, Up: Balance assertions -12.12.6 Assertions and subaccounts +12.13.6 Assertions and subaccounts ---------------------------------- The balance assertions above ('=' and '==') do not count the balance @@ -5127,7 +5139,7 @@ eg:  File: hledger.info, Node: Assertions and virtual postings, Next: Assertions and precision, Prev: Assertions and subaccounts, Up: Balance assertions -12.12.7 Assertions and virtual postings +12.13.7 Assertions and virtual postings --------------------------------------- Balance assertions are checked against all postings, both real and @@ -5137,7 +5149,7 @@ query.  File: hledger.info, Node: Assertions and precision, Prev: Assertions and virtual postings, Up: Balance assertions -12.12.8 Assertions and precision +12.13.8 Assertions and precision -------------------------------- Balance assertions compare the exactly calculated amounts, which are not @@ -5148,7 +5160,7 @@ assertion failure messages show exact amounts.  File: hledger.info, Node: Balance assignments, Next: Directives, Prev: Balance assertions, Up: JOURNAL FORMAT -12.13 Balance assignments +12.14 Balance assignments ========================= Ledger-style balance assignments are also supported. These are like @@ -5185,7 +5197,7 @@ hledger or do the calculations yourself, instead of just reading it.  File: hledger.info, Node: Balance assignments and prices, Up: Balance assignments -12.13.1 Balance assignments and prices +12.14.1 Balance assignments and prices -------------------------------------- A transaction price in a balance assignment will cause the calculated @@ -5201,7 +5213,7 @@ $ hledger print --explicit  File: hledger.info, Node: Directives, Next: Directives and multiple files, Prev: Balance assignments, Up: JOURNAL FORMAT -12.14 Directives +12.15 Directives ================ A directive is a line in the journal beginning with a special keyword, @@ -5292,7 +5304,7 @@ they affect, and whether they are focussed on input (parsing) or output  File: hledger.info, Node: Directives and multiple files, Next: Comment blocks, Prev: Directives, Up: JOURNAL FORMAT -12.15 Directives and multiple files +12.16 Directives and multiple files =================================== If you use multiple '-f'/'--file' options, or the 'include' directive, @@ -5312,7 +5324,7 @@ directives do not affect parent or sibling files (see below).  File: hledger.info, Node: Comment blocks, Next: Including other files, Prev: Directives and multiple files, Up: JOURNAL FORMAT -12.16 Comment blocks +12.17 Comment blocks ==================== A line containing just 'comment' starts a commented region of the file, @@ -5322,7 +5334,7 @@ file) ends it. See also comments.  File: hledger.info, Node: Including other files, Next: Default year, Prev: Comment blocks, Up: JOURNAL FORMAT -12.17 Including other files +12.18 Including other files =========================== You can pull in the content of additional files by writing an include @@ -5353,7 +5365,7 @@ files): 'include timedot:~/notes/2020*.md'.  File: hledger.info, Node: Default year, Next: Declaring payees, Prev: Including other files, Up: JOURNAL FORMAT -12.18 Default year +12.19 Default year ================== You can set a default year to be used for subsequent dates which don't @@ -5379,7 +5391,7 @@ Y2010 ; change default year to 2010  File: hledger.info, Node: Declaring payees, Next: Declaring commodities, Prev: Default year, Up: JOURNAL FORMAT -12.19 Declaring payees +12.20 Declaring payees ====================== The 'payee' directive can be used to declare a limited set of payees @@ -5392,7 +5404,7 @@ payee Whole Foods  File: hledger.info, Node: Declaring commodities, Next: Default commodity, Prev: Declaring payees, Up: JOURNAL FORMAT -12.20 Declaring commodities +12.21 Declaring commodities =========================== You can use 'commodity' directives to declare your commodities. In fact @@ -5465,7 +5477,7 @@ zero decimal digits is "0". (More at Commodity display style.)  File: hledger.info, Node: Commodity error checking, Up: Declaring commodities -12.20.1 Commodity error checking +12.21.1 Commodity error checking -------------------------------- In strict mode, enabled with the '-s'/'--strict' flag, hledger will @@ -5476,7 +5488,7 @@ checking, see the notes there for more details.  File: hledger.info, Node: Default commodity, Next: Declaring market prices, Prev: Declaring commodities, Up: JOURNAL FORMAT -12.21 Default commodity +12.22 Default commodity ======================= The 'D' directive sets a default commodity, to be used for any @@ -5505,7 +5517,7 @@ D $1,000.00  File: hledger.info, Node: Declaring market prices, Next: Declaring accounts, Prev: Default commodity, Up: JOURNAL FORMAT -12.22 Declaring market prices +12.23 Declaring market prices ============================= The 'P' directive declares a market price, which is an exchange rate @@ -5513,21 +5525,20 @@ between two commodities on a certain date. (In Ledger, they are called "historical prices".) These are often obtained from a stock exchange, cryptocurrency exchange, or the foreign exchange market. - Here is the format: + The format is: -P DATE COMMODITYA COMMODITYBAMOUNT +P DATE COMMODITY1SYMBOL COMMODITY2AMOUNT - * DATE is a simple date - * COMMODITYA is the symbol of the commodity being priced - * COMMODITYBAMOUNT is an amount (symbol and quantity) in a second - commodity, giving the price in commodity B of one unit of commodity - A. + DATE is a simple date, COMMODITY1SYMBOL is the symbol of the +commodity being priced, and COMMODITY2AMOUNT is the amount (symbol and +quantity) of commodity 2 that one unit of commodity 1 is worth on this +date. Examples: - These two market price directives say that one euro was worth 1.35 US -dollars during 2009, and $1.40 from 2010 onward: +# one euro was worth $1.35 from 2009-01-01 onward: +P 2009-01-01 € $1.35 -P 2009/1/1 € $1.35 -P 2010/1/1 € $1.40 +# and $1.40 from 2010-01-01 onward: +P 2010-01-01 € $1.40 The '-V', '-X' and '--value' flags use these market prices to show amount values in another commodity. See Valuation. @@ -5535,7 +5546,7 @@ amount values in another commodity. See Valuation.  File: hledger.info, Node: Declaring accounts, Next: Rewriting accounts, Prev: Declaring market prices, Up: JOURNAL FORMAT -12.23 Declaring accounts +12.24 Declaring accounts ======================== 'account' directives can be used to declare accounts (ie, the places @@ -5573,7 +5584,7 @@ account assets:bank:checking  File: hledger.info, Node: Account error checking, Next: Account comments, Up: Declaring accounts -12.23.1 Account error checking +12.24.1 Account error checking ------------------------------ By default, accounts come into existence when a transaction references @@ -5601,7 +5612,7 @@ been declared by an account directive. Some notes:  File: hledger.info, Node: Account comments, Next: Account subdirectives, Prev: Account error checking, Up: Declaring accounts -12.23.2 Account comments +12.24.2 Account comments ------------------------ Comments, beginning with a semicolon, can be added: @@ -5621,7 +5632,7 @@ account assets:bank:checking ; same-line comment, note 2+ spaces before ;  File: hledger.info, Node: Account subdirectives, Next: Account types, Prev: Account comments, Up: Declaring accounts -12.23.3 Account subdirectives +12.24.3 Account subdirectives ----------------------------- We also allow (and ignore) Ledger-style indented subdirectives, just for @@ -5639,7 +5650,7 @@ account ACCTNAME [ACCTTYPE] [;COMMENT]  File: hledger.info, Node: Account types, Next: Account display order, Prev: Account subdirectives, Up: Declaring accounts -12.23.4 Account types +12.24.4 Account types --------------------- hledger recognises five main types of account, corresponding to the @@ -5666,7 +5677,7 @@ or receivables.)  File: hledger.info, Node: Declaring account types, Next: Auto-detected account types, Up: Account types -12.23.4.1 Declaring account types +12.24.4.1 Declaring account types ................................. Generally, to make these reports work you should declare your top-level @@ -5688,7 +5699,7 @@ account expenses ; type: Expense  File: hledger.info, Node: Auto-detected account types, Next: Interference from auto-detected account types, Prev: Declaring account types, Up: Account types -12.23.4.2 Auto-detected account types +12.24.4.2 Auto-detected account types ..................................... If you happen to use common english top-level account names, you may not @@ -5711,7 +5722,7 @@ predictability.  File: hledger.info, Node: Interference from auto-detected account types, Next: Old account type syntax, Prev: Auto-detected account types, Up: Account types -12.23.4.3 Interference from auto-detected account types +12.24.4.3 Interference from auto-detected account types ....................................................... If you assign any account type, it's a good idea to assign all of them, @@ -5731,7 +5742,7 @@ account liabilities ; type:Equity  File: hledger.info, Node: Old account type syntax, Prev: Interference from auto-detected account types, Up: Account types -12.23.4.4 Old account type syntax +12.24.4.4 Old account type syntax ................................. In some hledger journals you might instead see this old syntax (the @@ -5747,7 +5758,7 @@ account expenses X  File: hledger.info, Node: Account display order, Prev: Account types, Up: Declaring accounts -12.23.5 Account display order +12.24.5 Account display order ----------------------------- Account directives also set the order in which accounts are displayed, @@ -5793,7 +5804,7 @@ means:  File: hledger.info, Node: Rewriting accounts, Next: Default parent account, Prev: Declaring accounts, Up: JOURNAL FORMAT -12.24 Rewriting accounts +12.25 Rewriting accounts ======================== You can define account alias rules which rewrite your account names, or @@ -5823,7 +5834,7 @@ hledger-web.  File: hledger.info, Node: Basic aliases, Next: Regex aliases, Up: Rewriting accounts -12.24.1 Basic aliases +12.25.1 Basic aliases --------------------- To set an account alias, use the 'alias' directive in your journal file. @@ -5847,7 +5858,7 @@ alias checking = assets:bank:wells fargo:checking  File: hledger.info, Node: Regex aliases, Next: Combining aliases, Prev: Basic aliases, Up: Rewriting accounts -12.24.2 Regex aliases +12.25.2 Regex aliases --------------------- There is also a more powerful variant that uses a regular expression, @@ -5872,7 +5883,7 @@ whitespace.  File: hledger.info, Node: Combining aliases, Next: Aliases and multiple files, Prev: Regex aliases, Up: Rewriting accounts -12.24.3 Combining aliases +12.25.3 Combining aliases ------------------------- You can define as many aliases as you like, using journal directives @@ -5909,7 +5920,7 @@ which aliases are being applied when.  File: hledger.info, Node: Aliases and multiple files, Next: end aliases, Prev: Combining aliases, Up: Rewriting accounts -12.24.4 Aliases and multiple files +12.25.4 Aliases and multiple files ---------------------------------- As explained at Directives and multiple files, 'alias' directives do not @@ -5941,7 +5952,7 @@ include c.journal ; also affected  File: hledger.info, Node: end aliases, Prev: Aliases and multiple files, Up: Rewriting accounts -12.24.5 'end aliases' +12.25.5 'end aliases' --------------------- You can clear (forget) all currently defined aliases with the 'end @@ -5952,7 +5963,7 @@ end aliases  File: hledger.info, Node: Default parent account, Next: Periodic transactions, Prev: Rewriting accounts, Up: JOURNAL FORMAT -12.25 Default parent account +12.26 Default parent account ============================ You can specify a parent account which will be prepended to all accounts @@ -5993,7 +6004,7 @@ parent account.  File: hledger.info, Node: Periodic transactions, Next: Auto postings, Prev: Default parent account, Up: JOURNAL FORMAT -12.26 Periodic transactions +12.27 Periodic transactions =========================== Periodic transaction rules describe transactions that recur. They allow @@ -6040,7 +6051,7 @@ to define budget goals, shown in budget reports.  File: hledger.info, Node: Periodic rule syntax, Next: Two spaces between period expression and description!, Up: Periodic transactions -12.26.1 Periodic rule syntax +12.27.1 Periodic rule syntax ---------------------------- A periodic transaction rule looks like a normal journal entry, with the @@ -6063,7 +6074,7 @@ will be relative to Y/1/1.  File: hledger.info, Node: Two spaces between period expression and description!, Next: Forecasting with periodic transactions, Prev: Periodic rule syntax, Up: Periodic transactions -12.26.2 Two spaces between period expression and description! +12.27.2 Two spaces between period expression and description! ------------------------------------------------------------- If the period expression is followed by a transaction description, these @@ -6088,7 +6099,7 @@ accidentally alter their meaning, as in this example:  File: hledger.info, Node: Forecasting with periodic transactions, Next: Budgeting with periodic transactions, Prev: Two spaces between period expression and description!, Up: Periodic transactions -12.26.3 Forecasting with periodic transactions +12.27.3 Forecasting with periodic transactions ---------------------------------------------- The '--forecast' flag activates any periodic transaction rules in the @@ -6134,7 +6145,7 @@ examples: '--forecast=202001-202004', '--forecast=jan-',  File: hledger.info, Node: Budgeting with periodic transactions, Prev: Forecasting with periodic transactions, Up: Periodic transactions -12.26.4 Budgeting with periodic transactions +12.27.4 Budgeting with periodic transactions -------------------------------------------- With the '--budget' flag, currently supported by the balance command, @@ -6149,7 +6160,7 @@ compared in budget reports.  File: hledger.info, Node: Auto postings, Prev: Periodic transactions, Up: JOURNAL FORMAT -12.27 Auto postings +12.28 Auto postings =================== "Automated postings" or "auto postings" are extra postings which get @@ -6227,7 +6238,7 @@ $ hledger print --auto  File: hledger.info, Node: Auto postings and multiple files, Next: Auto postings and dates, Up: Auto postings -12.27.1 Auto postings and multiple files +12.28.1 Auto postings and multiple files ---------------------------------------- An auto posting rule can affect any transaction in the current file, or @@ -6237,7 +6248,7 @@ sibling files (when multiple '-f'/'--file' are used - see #1212).  File: hledger.info, Node: Auto postings and dates, Next: Auto postings and transaction balancing / inferred amounts / balance assertions, Prev: Auto postings and multiple files, Up: Auto postings -12.27.2 Auto postings and dates +12.28.2 Auto postings and dates ------------------------------- A posting date (or secondary date) in the matched posting, or (taking @@ -6247,7 +6258,7 @@ used in the generated posting.  File: hledger.info, Node: Auto postings and transaction balancing / inferred amounts / balance assertions, Next: Auto posting tags, Prev: Auto postings and dates, Up: Auto postings -12.27.3 Auto postings and transaction balancing / inferred amounts / +12.28.3 Auto postings and transaction balancing / inferred amounts / -------------------------------------------------------------------- balance assertions Currently, auto postings are added: @@ -6263,7 +6274,7 @@ for background.  File: hledger.info, Node: Auto posting tags, Prev: Auto postings and transaction balancing / inferred amounts / balance assertions, Up: Auto postings -12.27.4 Auto posting tags +12.28.4 Auto posting tags ------------------------- Automated postings will have some extra tags: @@ -6312,26 +6323,28 @@ rules for categorising transactions based on their descriptions. Here's an overview of the CSV rules; these are described more fully below, after the examples: -*'skip'* skip one or more header lines or - matched CSV records -*'fields'* name CSV fields, assign them to hledger - fields -*field assignment* assign a value to one hledger field, - with interpolation -*'separator'* a custom field separator -*'if' block* apply some rules to CSV records matched - by patterns -*'if' table* apply some rules to CSV records matched - by patterns, alternate syntax -*'end'* skip the remaining CSV records -*'date-format'* how to parse dates in CSV records -*'decimal-mark'* the decimal mark used in CSV amounts, - if ambiguous -*'newest-first'* disambiguate record order when there's - only one date -*'include'* inline another CSV rules file -*'balance-type'* choose which type of balance - assignments to use +*'skip'* skip one or more header lines or matched + CSV records +*'fields' list* name CSV fields, assign them to hledger + fields +*field assignment* assign a value to one hledger field, with + interpolation +*Field names* hledger field names, used in the fields + list and field assignments +*'separator'* a custom field separator +*'if' block* apply some rules to CSV records matched by + patterns +*'if' table* apply some rules to CSV records matched by + patterns, alternate syntax +*'end'* skip the remaining CSV records +*'date-format'* how to parse dates in CSV records +*'decimal-mark'* the decimal mark used in CSV amounts, if + ambiguous +*'newest-first'* disambiguate record order when there's only + one date +*'include'* inline another CSV rules file +*'balance-type'* choose which type of balance assignments to + use Note, for best error messages when reading CSV files, use a '.csv', '.tsv' or '.ssv' file extension or file prefix - see File Extension @@ -6664,8 +6677,9 @@ Blank lines and lines beginning with '#' or ';' are ignored. * Menu: * skip:: -* fields:: +* fields list:: * field assignment:: +* Field names:: * separator:: * if block:: * if table:: @@ -6677,7 +6691,7 @@ Blank lines and lines beginning with '#' or ';' are ignored. * balance-type::  -File: hledger.info, Node: skip, Next: fields, Up: CSV rules +File: hledger.info, Node: skip, Next: fields list, Up: CSV rules 13.2.1 'skip' ------------- @@ -6693,22 +6707,23 @@ whenever your CSV data contains header lines. ignore certain CSV records (described below).  -File: hledger.info, Node: fields, Next: field assignment, Prev: skip, Up: CSV rules +File: hledger.info, Node: fields list, Next: field assignment, Prev: skip, Up: CSV rules -13.2.2 'fields' ---------------- +13.2.2 'fields' list +-------------------- fields FIELDNAME1, FIELDNAME2, ... A fields list (the word "fields" followed by comma-separated field names) is the quick way to assign CSV field values to hledger fields. -It does two things: +(The other way is field assignments, see below.) A fields list does +does two things: - 1. it names the CSV fields. This is optional, but can be convenient + 1. It names the CSV fields. This is optional, but can be convenient later for interpolating them. - 2. when you use a standard hledger field name, it assigns the CSV - value to that part of the hledger transaction. + 2. Whenever you use a standard hledger field name (defined below), the + CSV value is assigned to that part of the hledger 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 for @@ -6716,39 +6731,140 @@ later reference; and ignore the others": fields date, description, , amount, , , somefield, anotherfield - Field names may not contain whitespace. Fields you don't care about -can be left unnamed. Currently there must be least two items (there -must be at least one comma). + Tips: - Note, always use comma in the fields list, even if your CSV uses -another separator character. + * The fields list always use commas, even if your CSV data uses + another separator character. + * Currently there must be least two items in the list (at least one + comma). + * Field names may not contain spaces. Spaces before/after field + names are optional. + * If the CSV contains column headings, it's a good idea to use these, + suitably modified, as the basis for your field names (eg + lower-cased, with underscores instead of spaces). + * If some heading names match standard hledger fields, but you don't + want to set the hledger fields directly, alter those names, eg by + appending an underscore. + * Fields you don't care about can be given a dummy name (eg: '_' ), + or no name. - Here are the standard hledger field/pseudo-field names. For more -about the transaction parts they refer to, see the manual for hledger's -journal format. + +File: hledger.info, Node: field assignment, Next: Field names, Prev: fields list, Up: CSV rules + +13.2.3 field assignment +----------------------- + +HLEDGERFIELDNAME FIELDVALUE + + 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 +interpolate CSV fields, referenced by their 1-based position in the CSV +record ('%N'), or by the name they were given in the fields list +('%CSVFIELDNAME'). + + Some examples: + +# set the amount to the 4th CSV field, with " USD" appended +amount %4 USD + +# combine three fields to make a comment, containing note: and date: tags +comment note: %somefield - %anotherfield, date: %1 + + Tips: + + * Interpolation strips outer whitespace (so a CSV value like '" 1 "' + becomes '1' when interpolated) (#1051). + * See also Tips below. + + +File: hledger.info, Node: Field names, Next: separator, Prev: field assignment, Up: CSV rules + +13.2.4 Field names +------------------ + +Here are the standard hledger field (and pseudo-field) names, which you +can use in a fields list and in field assignments. For more about the +transaction parts they refer to, see Transactions. * Menu: -* Transaction field names:: -* Posting field names:: +* date field:: +* date2 field:: +* status field:: +* code field:: +* description field:: +* comment field:: +* account field:: +* amount field:: +* currency field:: +* balance field::  -File: hledger.info, Node: Transaction field names, Next: Posting field names, Up: fields +File: hledger.info, Node: date field, Next: date2 field, Up: Field names -13.2.2.1 Transaction field names -................................ +13.2.4.1 date field +................... -'date', 'date2', 'status', 'code', 'description', 'comment' can be used -to form the transaction's first line. +Assigning to 'date' sets the transaction date.  -File: hledger.info, Node: Posting field names, Prev: Transaction field names, Up: fields +File: hledger.info, Node: date2 field, Next: status field, Prev: date field, Up: Field names -13.2.2.2 Posting field names -............................ +13.2.4.2 date2 field +.................... -account 'accountN', where N is 1 to 99, causes a posting to be -generated, with that account name. +'date2' sets the transaction's secondary date, if any. + + +File: hledger.info, Node: status field, Next: code field, Prev: date2 field, Up: Field names + +13.2.4.3 status field +..................... + +'status' sets the transaction's status, if any. + + +File: hledger.info, Node: code field, Next: description field, Prev: status field, Up: Field names + +13.2.4.4 code field +................... + +'code' sets the transaction's code, if any. + + +File: hledger.info, Node: description field, Next: comment field, Prev: code field, Up: Field names + +13.2.4.5 description field +.......................... + +'description' sets the transaction's description, if any. + + +File: hledger.info, Node: comment field, Next: account field, Prev: description field, Up: Field names + +13.2.4.6 comment field +...................... + +'comment' sets the transaction's comment, if any. + + 'commentN', where N is a number, sets the Nth posting's comment. + + Tips: - Only single-line comments can be assigned. - Comments can +contain tags, as usual. + + +File: hledger.info, Node: account field, Next: amount field, Prev: comment field, Up: Field names + +13.2.4.7 account field +...................... + +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, @@ -6757,21 +6873,28 @@ based on each transaction's description, and in conditional blocks. 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 'amountN' sets the Nth posting's amount. -By assigning to 'amount1', 'amount2', ... etc. you can generate up to -99 postings. +or "income:unknown"). - If the CSV uses separate fields for debits and credits (inflows and -outflows), you can use 'amountN-in' and 'amountN-out' instead. Note -hledger assumes both of these fields are unsigned, and will -automatically negate the "-out" value. If the fields are signed, see -"Setting amounts" below. + +File: hledger.info, Node: amount field, Next: currency field, Prev: account field, Up: Field names - There is also an unnumbered form of these names: 'amount', or -'amount-in' and 'amount-out'. This is supported to keep +13.2.4.8 amount field +..................... + +'amountN' sets the amount of the Nth posting, and causes that posting to +be generated. By assigning to 'amount1', 'amount2', ... etc. you can +generate up to 99 postings. + + 'amountN-in' and 'amountN-out' can be used instead, if the CSV uses +separate fields for debits and credits (inflows and outflows). hledger +assumes both of these CSV fields are unsigned, and will automatically +negate the "-out" value. If they are signed, see "Setting amounts" +below. + + 'amount', or 'amount-in' and 'amount-out' are a legacy mode, to keep pre-hledger-1.17 CSV rules files working (and for occasional -convenience). It is suitable only for two-posting transactions; it sets -both posting 1's and posting 2's amount. Posting 2's amount will be +convenience). They are suitable only for two-posting transactions; they +set both posting 1's and posting 2's amount. Posting 2's amount will be negated, and also converted to cost if there's a transaction price. If you have an existing rules file using the unnumbered form, you @@ -6780,51 +6903,42 @@ without having to update and retest all the old rules. To facilitate this, posting 1 ignores 'amount'/'amount-in'/'amount-out' if any of 'amount1'/'amount1-in'/'amount1-out' are assigned, and posting 2 ignores them if any of 'amount2'/'amount2-in'/'amount2-out' are assigned, -avoiding conflicts. currency If the CSV has the currency symbol in a -separate field (ie, not part of the amount field), you can use -'currencyN' to prepend it to posting N's amount. Or, 'currency' with no -number affects all postings. balance 'balanceN' sets a balance -assertion amount (or if the posting amount is left empty, a balance -assignment) on posting N. +avoiding conflicts. - Also, for compatibility with hledger <1.17: 'balance' with no number -is equivalent to 'balance1'. + +File: hledger.info, Node: currency field, Next: balance field, Prev: amount field, Up: Field names + +13.2.4.9 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 +symbol, eg if it is in a separate column. + + 'currencyN' prepends a currency symbol to just the Nth posting's +amount. + + +File: hledger.info, Node: balance field, Prev: currency field, Up: Field names + +13.2.4.10 balance field +....................... + +'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' rule (see below). comment Finally, 'commentN' sets a -comment on the Nth posting. Comments can also contain tags, as usual. +'balance-type' rule (see below). - See TIPS below for more about setting amounts and currency. + See Tips below for more about setting amounts and currency.  -File: hledger.info, Node: field assignment, Next: separator, Prev: fields, Up: CSV rules +File: hledger.info, Node: separator, Next: if block, Prev: Field names, Up: CSV rules -13.2.3 field assignment ------------------------ - -HLEDGERFIELDNAME FIELDVALUE - - Instead of or in addition to a fields list, you can use a "field -assignment" rule to set the value of a single hledger field, by writing -its name (any of the standard hledger field names above) followed by a -text value. The value may contain interpolated CSV fields, referenced -by their 1-based position in the CSV record ('%N'), or by the name they -were given in the fields list ('%CSVFIELDNAME'). Some examples: - -# set the amount to the 4th CSV field, with " USD" appended -amount %4 USD - -# combine three fields to make a comment, containing note: and date: tags -comment note: %somefield - %anotherfield, date: %1 - - Interpolation strips outer whitespace (so a CSV value like '" 1 "' -becomes '1' when interpolated) (#1051). See TIPS below for more about -referencing other fields. - - -File: hledger.info, Node: separator, Next: if block, Prev: field assignment, Up: CSV rules - -13.2.4 'separator' +13.2.5 'separator' ------------------ You can use the 'separator' rule to read other kinds of @@ -6849,7 +6963,7 @@ inferred automatically, and you won't need this rule.  File: hledger.info, Node: if block, Next: if table, Prev: separator, Up: CSV rules -13.2.5 'if' block +13.2.6 'if' block ----------------- if MATCHER @@ -6877,7 +6991,7 @@ descriptions.  File: hledger.info, Node: Matching the whole record, Next: Matching individual fields, Up: if block -13.2.5.1 Matching the whole record +13.2.6.1 Matching the whole record .................................. Each MATCHER can be a record matcher, which looks like this: @@ -6900,7 +7014,7 @@ actually see '2020-01-01,Acme, Inc., 1,000').  File: hledger.info, Node: Matching individual fields, Next: Combining matchers, Prev: Matching the whole record, Up: if block -13.2.5.2 Matching individual fields +13.2.6.2 Matching individual fields ................................... Or, MATCHER can be a field matcher, like this: @@ -6914,7 +7028,7 @@ is a percent sign followed by the field's name or column number, like  File: hledger.info, Node: Combining matchers, Next: Rules applied on successful match, Prev: Matching individual fields, Up: if block -13.2.5.3 Combining matchers +13.2.6.3 Combining matchers ........................... A single matcher can be written on the same line as the "if"; or @@ -6931,7 +7045,7 @@ MATCHER  File: hledger.info, Node: Rules applied on successful match, Prev: Combining matchers, Up: if block -13.2.5.4 Rules applied on successful match +13.2.6.4 Rules applied on successful match .......................................... After the patterns there should be one or more rules to apply, all @@ -6959,7 +7073,7 @@ banking thru software  File: hledger.info, Node: if table, Next: end, Prev: if block, Up: CSV rules -13.2.6 'if' table +13.2.7 'if' table ----------------- if,CSVFIELDNAME1,CSVFIELDNAME2,...,CSVFIELDNAMEn @@ -7020,7 +7134,7 @@ atm transaction fee,expenses:business:banking,deductible? check it  File: hledger.info, Node: end, Next: date-format, Prev: if table, Up: CSV rules -13.2.7 'end' +13.2.8 'end' ------------ This rule can be used inside if blocks (only), to make hledger stop @@ -7034,7 +7148,7 @@ if ,,,,  File: hledger.info, Node: date-format, Next: decimal-mark, Prev: end, Up: CSV rules -13.2.8 'date-format' +13.2.9 'date-format' -------------------- date-format DATEFMT @@ -7062,11 +7176,16 @@ date-format %-m/%-d/%Y %l:%M %p some other junk For the supported strptime syntax, see: https://hackage.haskell.org/package/time/docs/Data-Time-Format.html#v:formatTime + Note that although you can parse date-times which include a time +zone, that time zone is ignored; it will not change the date that is +parsed. This means when reading CSV data with times not in your local +time zone, dates can be "off by one". +  File: hledger.info, Node: decimal-mark, Next: newest-first, Prev: date-format, Up: CSV rules -13.2.9 'decimal-mark' ---------------------- +13.2.10 'decimal-mark' +---------------------- decimal-mark . @@ -7083,7 +7202,7 @@ misparsed numbers.  File: hledger.info, Node: newest-first, Next: include, Prev: decimal-mark, Up: CSV rules -13.2.10 'newest-first' +13.2.11 'newest-first' ---------------------- hledger always sorts the generated transactions by date. Transactions @@ -7105,7 +7224,7 @@ newest-first  File: hledger.info, Node: include, Next: balance-type, Prev: newest-first, Up: CSV rules -13.2.11 'include' +13.2.12 'include' ----------------- include RULESFILE @@ -7128,7 +7247,7 @@ include categorisation.rules  File: hledger.info, Node: balance-type, Prev: include, Up: CSV rules -13.2.12 'balance-type' +13.2.13 'balance-type' ---------------------- Balance assertions generated by assigning to balanceN are of the simple @@ -8438,245 +8557,265 @@ Node: About add-on commands150828 Ref: #about-add-on-commands150965 Node: JOURNAL FORMAT152096 Ref: #journal-format152224 -Node: Transactions154411 -Ref: #transactions154526 -Node: Dates155540 -Ref: #dates155656 -Node: Simple dates155721 -Ref: #simple-dates155841 -Node: Secondary dates156350 -Ref: #secondary-dates156498 -Node: Posting dates157834 -Ref: #posting-dates157957 -Node: Status159329 -Ref: #status159446 -Node: Description161154 -Ref: #description161284 -Node: Payee and note161604 -Ref: #payee-and-note161712 -Node: Comments162047 -Ref: #comments162169 -Node: Tags163363 -Ref: #tags-1163474 -Node: Postings164867 -Ref: #postings164991 -Node: Virtual postings166017 -Ref: #virtual-postings166128 -Node: Account names167433 -Ref: #account-names167570 -Node: Amounts168058 -Ref: #amounts168193 -Node: Decimal marks digit group marks169149 -Ref: #decimal-marks-digit-group-marks169324 -Node: Commodity170196 -Ref: #commodity170354 -Node: Commodity directives171306 -Ref: #commodity-directives171478 -Node: Commodity display style171965 -Ref: #commodity-display-style172142 -Node: Rounding174250 -Ref: #rounding174368 -Node: Transaction prices174780 -Ref: #transaction-prices174946 -Node: Lot prices lot dates177377 -Ref: #lot-prices-lot-dates177560 -Node: Balance assertions178048 -Ref: #balance-assertions178226 -Node: Assertions and ordering179259 -Ref: #assertions-and-ordering179441 -Node: Assertions and included files180141 -Ref: #assertions-and-included-files180378 -Node: Assertions and multiple -f options180711 -Ref: #assertions-and-multiple--f-options180961 -Node: Assertions and commodities181093 -Ref: #assertions-and-commodities181319 -Node: Assertions and prices182476 -Ref: #assertions-and-prices182684 -Node: Assertions and subaccounts183124 -Ref: #assertions-and-subaccounts183347 -Node: Assertions and virtual postings183671 -Ref: #assertions-and-virtual-postings183907 -Node: Assertions and precision184049 -Ref: #assertions-and-precision184236 -Node: Balance assignments184503 -Ref: #balance-assignments184673 -Node: Balance assignments and prices185837 -Ref: #balance-assignments-and-prices186003 -Node: Directives186227 -Ref: #directives186390 -Node: Directives and multiple files191848 -Ref: #directives-and-multiple-files192044 -Node: Comment blocks192708 -Ref: #comment-blocks192885 -Node: Including other files193061 -Ref: #including-other-files193235 -Node: Default year194159 -Ref: #default-year194317 -Node: Declaring payees194724 -Ref: #declaring-payees194890 -Node: Declaring commodities195136 -Ref: #declaring-commodities195317 -Node: Commodity error checking197697 -Ref: #commodity-error-checking197847 -Node: Default commodity198104 -Ref: #default-commodity198284 -Node: Declaring market prices199160 -Ref: #declaring-market-prices199349 -Node: Declaring accounts200206 -Ref: #declaring-accounts200386 -Node: Account error checking201588 -Ref: #account-error-checking201754 -Node: Account comments202933 -Ref: #account-comments203117 -Node: Account subdirectives203541 -Ref: #account-subdirectives203726 -Node: Account types204039 -Ref: #account-types204213 -Node: Declaring account types204949 -Ref: #declaring-account-types205128 -Node: Auto-detected account types205778 -Ref: #auto-detected-account-types206019 -Node: Interference from auto-detected account types206979 -Ref: #interference-from-auto-detected-account-types207256 -Node: Old account type syntax207739 -Ref: #old-account-type-syntax207936 -Node: Account display order208236 -Ref: #account-display-order208396 -Node: Rewriting accounts209547 -Ref: #rewriting-accounts209726 -Node: Basic aliases210483 -Ref: #basic-aliases210619 -Node: Regex aliases211363 -Ref: #regex-aliases211525 -Node: Combining aliases212244 -Ref: #combining-aliases212427 -Node: Aliases and multiple files213703 -Ref: #aliases-and-multiple-files213902 -Node: end aliases214481 -Ref: #end-aliases214628 -Node: Default parent account214729 -Ref: #default-parent-account214919 -Node: Periodic transactions215803 -Ref: #periodic-transactions215986 -Node: Periodic rule syntax217903 -Ref: #periodic-rule-syntax218103 -Node: Two spaces between period expression and description!218807 -Ref: #two-spaces-between-period-expression-and-description219120 -Node: Forecasting with periodic transactions219804 -Ref: #forecasting-with-periodic-transactions220103 -Node: Budgeting with periodic transactions222158 -Ref: #budgeting-with-periodic-transactions222391 -Node: Auto postings222800 -Ref: #auto-postings222936 -Node: Auto postings and multiple files225115 -Ref: #auto-postings-and-multiple-files225313 -Node: Auto postings and dates225522 -Ref: #auto-postings-and-dates225790 -Node: Auto postings and transaction balancing / inferred amounts / balance assertions225965 -Ref: #auto-postings-and-transaction-balancing-inferred-amounts-balance-assertions226310 -Node: Auto posting tags226652 -Ref: #auto-posting-tags226861 -Node: CSV FORMAT227497 -Ref: #csv-format227625 -Node: Examples230211 -Ref: #examples230314 -Node: Basic230522 -Ref: #basic230624 -Node: Bank of Ireland231166 -Ref: #bank-of-ireland231303 -Node: Amazon232765 -Ref: #amazon232885 -Node: Paypal234604 -Ref: #paypal234700 -Node: CSV rules242344 -Ref: #csv-rules242462 -Node: skip242774 -Ref: #skip242869 -Node: fields243244 -Ref: #fields243368 -Node: Transaction field names244533 -Ref: #transaction-field-names244695 -Node: Posting field names244806 -Ref: #posting-field-names244960 -Node: field assignment247474 -Ref: #field-assignment247619 -Node: separator248437 -Ref: #separator248574 -Node: if block249114 -Ref: #if-block249241 -Node: Matching the whole record249642 -Ref: #matching-the-whole-record249819 -Node: Matching individual fields250622 -Ref: #matching-individual-fields250828 -Node: Combining matchers251052 -Ref: #combining-matchers251250 -Node: Rules applied on successful match251563 -Ref: #rules-applied-on-successful-match251756 -Node: if table252410 -Ref: #if-table252531 -Node: end254269 -Ref: #end254383 -Node: date-format254607 -Ref: #date-format254741 -Node: decimal-mark255490 -Ref: #decimal-mark255635 -Node: newest-first255974 -Ref: #newest-first256117 -Node: include256800 -Ref: #include256933 -Node: balance-type257377 -Ref: #balance-type257499 -Node: Tips258199 -Ref: #tips258290 -Node: Rapid feedback258589 -Ref: #rapid-feedback258708 -Node: Valid CSV259168 -Ref: #valid-csv259300 -Node: File Extension259492 -Ref: #file-extension259646 -Node: Reading multiple CSV files260075 -Ref: #reading-multiple-csv-files260262 -Node: Valid transactions260503 -Ref: #valid-transactions260683 -Node: Deduplicating importing261311 -Ref: #deduplicating-importing261492 -Node: Setting amounts262525 -Ref: #setting-amounts262682 -Node: Amount signs265123 -Ref: #amount-signs265277 -Node: Setting currency/commodity265964 -Ref: #setting-currencycommodity266152 -Node: Amount decimal places267326 -Ref: #amount-decimal-places267518 -Node: Referencing other fields267830 -Ref: #referencing-other-fields268029 -Node: How CSV rules are evaluated268926 -Ref: #how-csv-rules-are-evaluated269101 -Node: TIMECLOCK FORMAT270552 -Ref: #timeclock-format270692 -Node: TIMEDOT FORMAT272753 -Ref: #timedot-format272891 -Node: COMMON TASKS277167 -Ref: #common-tasks277296 -Node: Getting help277703 -Ref: #getting-help277837 -Node: Constructing command lines278390 -Ref: #constructing-command-lines278584 -Node: Starting a journal file279281 -Ref: #starting-a-journal-file279481 -Node: Setting opening balances280669 -Ref: #setting-opening-balances280867 -Node: Recording transactions284008 -Ref: #recording-transactions284190 -Node: Reconciling284746 -Ref: #reconciling284891 -Node: Reporting287148 -Ref: #reporting287290 -Node: Migrating to a new file291289 -Ref: #migrating-to-a-new-file291439 -Node: LIMITATIONS291738 -Ref: #limitations291866 -Node: TROUBLESHOOTING292609 -Ref: #troubleshooting292724 +Node: Transactions154420 +Ref: #transactions154535 +Node: Dates155549 +Ref: #dates155665 +Node: Simple dates155730 +Ref: #simple-dates155850 +Node: Secondary dates156359 +Ref: #secondary-dates156507 +Node: Posting dates157843 +Ref: #posting-dates157966 +Node: Status159338 +Ref: #status159448 +Node: Code161156 +Ref: #code161268 +Node: Description161500 +Ref: #description161628 +Node: Payee and note161948 +Ref: #payee-and-note162056 +Node: Comments162391 +Ref: #comments162513 +Node: Tags163707 +Ref: #tags-1163818 +Node: Postings165211 +Ref: #postings165335 +Node: Virtual postings166361 +Ref: #virtual-postings166472 +Node: Account names167777 +Ref: #account-names167914 +Node: Amounts168402 +Ref: #amounts168539 +Node: Decimal marks digit group marks169495 +Ref: #decimal-marks-digit-group-marks169672 +Node: Commodity170544 +Ref: #commodity170704 +Node: Commodity directives171656 +Ref: #commodity-directives171830 +Node: Commodity display style172317 +Ref: #commodity-display-style172496 +Node: Rounding174604 +Ref: #rounding174724 +Node: Transaction prices175136 +Ref: #transaction-prices175302 +Node: Lot prices lot dates177733 +Ref: #lot-prices-lot-dates177916 +Node: Balance assertions178404 +Ref: #balance-assertions178582 +Node: Assertions and ordering179615 +Ref: #assertions-and-ordering179797 +Node: Assertions and included files180497 +Ref: #assertions-and-included-files180734 +Node: Assertions and multiple -f options181067 +Ref: #assertions-and-multiple--f-options181317 +Node: Assertions and commodities181449 +Ref: #assertions-and-commodities181675 +Node: Assertions and prices182832 +Ref: #assertions-and-prices183040 +Node: Assertions and subaccounts183480 +Ref: #assertions-and-subaccounts183703 +Node: Assertions and virtual postings184027 +Ref: #assertions-and-virtual-postings184263 +Node: Assertions and precision184405 +Ref: #assertions-and-precision184592 +Node: Balance assignments184859 +Ref: #balance-assignments185029 +Node: Balance assignments and prices186193 +Ref: #balance-assignments-and-prices186359 +Node: Directives186583 +Ref: #directives186746 +Node: Directives and multiple files192204 +Ref: #directives-and-multiple-files192400 +Node: Comment blocks193064 +Ref: #comment-blocks193241 +Node: Including other files193417 +Ref: #including-other-files193591 +Node: Default year194515 +Ref: #default-year194673 +Node: Declaring payees195080 +Ref: #declaring-payees195246 +Node: Declaring commodities195492 +Ref: #declaring-commodities195673 +Node: Commodity error checking198053 +Ref: #commodity-error-checking198203 +Node: Default commodity198460 +Ref: #default-commodity198640 +Node: Declaring market prices199516 +Ref: #declaring-market-prices199705 +Node: Declaring accounts200518 +Ref: #declaring-accounts200698 +Node: Account error checking201900 +Ref: #account-error-checking202066 +Node: Account comments203245 +Ref: #account-comments203429 +Node: Account subdirectives203853 +Ref: #account-subdirectives204038 +Node: Account types204351 +Ref: #account-types204525 +Node: Declaring account types205261 +Ref: #declaring-account-types205440 +Node: Auto-detected account types206090 +Ref: #auto-detected-account-types206331 +Node: Interference from auto-detected account types207291 +Ref: #interference-from-auto-detected-account-types207568 +Node: Old account type syntax208051 +Ref: #old-account-type-syntax208248 +Node: Account display order208548 +Ref: #account-display-order208708 +Node: Rewriting accounts209859 +Ref: #rewriting-accounts210038 +Node: Basic aliases210795 +Ref: #basic-aliases210931 +Node: Regex aliases211675 +Ref: #regex-aliases211837 +Node: Combining aliases212556 +Ref: #combining-aliases212739 +Node: Aliases and multiple files214015 +Ref: #aliases-and-multiple-files214214 +Node: end aliases214793 +Ref: #end-aliases214940 +Node: Default parent account215041 +Ref: #default-parent-account215231 +Node: Periodic transactions216115 +Ref: #periodic-transactions216298 +Node: Periodic rule syntax218215 +Ref: #periodic-rule-syntax218415 +Node: Two spaces between period expression and description!219119 +Ref: #two-spaces-between-period-expression-and-description219432 +Node: Forecasting with periodic transactions220116 +Ref: #forecasting-with-periodic-transactions220415 +Node: Budgeting with periodic transactions222470 +Ref: #budgeting-with-periodic-transactions222703 +Node: Auto postings223112 +Ref: #auto-postings223248 +Node: Auto postings and multiple files225427 +Ref: #auto-postings-and-multiple-files225625 +Node: Auto postings and dates225834 +Ref: #auto-postings-and-dates226102 +Node: Auto postings and transaction balancing / inferred amounts / balance assertions226277 +Ref: #auto-postings-and-transaction-balancing-inferred-amounts-balance-assertions226622 +Node: Auto posting tags226964 +Ref: #auto-posting-tags227173 +Node: CSV FORMAT227809 +Ref: #csv-format227937 +Node: Examples230566 +Ref: #examples230669 +Node: Basic230877 +Ref: #basic230979 +Node: Bank of Ireland231521 +Ref: #bank-of-ireland231658 +Node: Amazon233120 +Ref: #amazon233240 +Node: Paypal234959 +Ref: #paypal235055 +Node: CSV rules242699 +Ref: #csv-rules242817 +Node: skip243150 +Ref: #skip243250 +Node: fields list243625 +Ref: #fields-list243764 +Node: field assignment245267 +Ref: #field-assignment245419 +Node: Field names246347 +Ref: #field-names246487 +Node: date field246867 +Ref: #date-field246987 +Node: date2 field247035 +Ref: #date2-field247178 +Node: status field247234 +Ref: #status-field247379 +Node: code field247428 +Ref: #code-field247575 +Node: description field247620 +Ref: #description-field247782 +Node: comment field247841 +Ref: #comment-field247998 +Node: account field248213 +Ref: #account-field248365 +Node: amount field248940 +Ref: #amount-field249091 +Node: currency field250336 +Ref: #currency-field250491 +Node: balance field250748 +Ref: #balance-field250882 +Node: separator251254 +Ref: #separator251386 +Node: if block251926 +Ref: #if-block252053 +Node: Matching the whole record252454 +Ref: #matching-the-whole-record252631 +Node: Matching individual fields253434 +Ref: #matching-individual-fields253640 +Node: Combining matchers253864 +Ref: #combining-matchers254062 +Node: Rules applied on successful match254375 +Ref: #rules-applied-on-successful-match254568 +Node: if table255222 +Ref: #if-table255343 +Node: end257081 +Ref: #end257195 +Node: date-format257419 +Ref: #date-format257553 +Node: decimal-mark258549 +Ref: #decimal-mark258696 +Node: newest-first259035 +Ref: #newest-first259178 +Node: include259861 +Ref: #include259994 +Node: balance-type260438 +Ref: #balance-type260560 +Node: Tips261260 +Ref: #tips261351 +Node: Rapid feedback261650 +Ref: #rapid-feedback261769 +Node: Valid CSV262229 +Ref: #valid-csv262361 +Node: File Extension262553 +Ref: #file-extension262707 +Node: Reading multiple CSV files263136 +Ref: #reading-multiple-csv-files263323 +Node: Valid transactions263564 +Ref: #valid-transactions263744 +Node: Deduplicating importing264372 +Ref: #deduplicating-importing264553 +Node: Setting amounts265586 +Ref: #setting-amounts265743 +Node: Amount signs268184 +Ref: #amount-signs268338 +Node: Setting currency/commodity269025 +Ref: #setting-currencycommodity269213 +Node: Amount decimal places270387 +Ref: #amount-decimal-places270579 +Node: Referencing other fields270891 +Ref: #referencing-other-fields271090 +Node: How CSV rules are evaluated271987 +Ref: #how-csv-rules-are-evaluated272162 +Node: TIMECLOCK FORMAT273613 +Ref: #timeclock-format273753 +Node: TIMEDOT FORMAT275814 +Ref: #timedot-format275952 +Node: COMMON TASKS280228 +Ref: #common-tasks280357 +Node: Getting help280764 +Ref: #getting-help280898 +Node: Constructing command lines281451 +Ref: #constructing-command-lines281645 +Node: Starting a journal file282342 +Ref: #starting-a-journal-file282542 +Node: Setting opening balances283730 +Ref: #setting-opening-balances283928 +Node: Recording transactions287069 +Ref: #recording-transactions287251 +Node: Reconciling287807 +Ref: #reconciling287952 +Node: Reporting290209 +Ref: #reporting290351 +Node: Migrating to a new file294350 +Ref: #migrating-to-a-new-file294500 +Node: LIMITATIONS294799 +Ref: #limitations294927 +Node: TROUBLESHOOTING295670 +Ref: #troubleshooting295785  End Tag Table diff --git a/hledger/hledger.txt b/hledger/hledger.txt index 172d5f0ac..581fd2ee2 100644 --- a/hledger/hledger.txt +++ b/hledger/hledger.txt @@ -3833,30 +3833,36 @@ JOURNAL FORMAT uncashed checks), and no flags to see the most up-to-date state of your finances. + Code + After the status mark, but before the description, you can optionally + write a transaction "code", enclosed in parentheses. This is a good + place to record a check number, or some other important transaction id + or reference number. + Description - A transaction's description is the rest of the line following the date - and status mark (or until a comment begins). Sometimes called the + A transaction's description is the rest of the line following the date + and status mark (or until a comment begins). Sometimes called the "narration" in traditional bookkeeping, it can be used for whatever you - wish, or left blank. Transaction descriptions can be queried, unlike + wish, or left blank. Transaction descriptions can be queried, unlike comments. Payee and note You can optionally include a | (pipe) character in descriptions to sub- divide the description into separate fields for payee/payer name on the - left (up to the first |) and an additional note field on the right - (after the first |). This may be worthwhile if you need to do more + left (up to the first |) and an additional note field on the right + (after the first |). This may be worthwhile if you need to do more precise querying and pivoting by payee or by note. Comments Lines in the journal beginning with a semicolon (;) or hash (#) or star - (*) are comments, and will be ignored. (Star comments cause org-mode - nodes to be ignored, allowing emacs users to fold and navigate their + (*) are comments, and will be ignored. (Star comments cause org-mode + nodes to be ignored, allowing emacs users to fold and navigate their journals with org-mode or orgstruct-mode.) - You can attach comments to a transaction by writing them after the - description and/or indented on the following lines (before the post- - ings). Similarly, you can attach comments to an individual posting by - writing them after the amount and/or indented on the following lines. + You can attach comments to a transaction by writing them after the + description and/or indented on the following lines (before the post- + ings). Similarly, you can attach comments to an individual posting by + writing them after the amount and/or indented on the following lines. Transaction and posting comments must begin with a semicolon (;). Some examples: @@ -3879,24 +3885,24 @@ JOURNAL FORMAT ; another comment line for posting 2 ; a file comment (because not indented) - You can also comment larger regions of a file using comment and end + You can also comment larger regions of a file using comment and end comment directives. Tags - Tags are a way to add extra labels or labelled data to postings and + Tags are a way to add extra labels or labelled data to postings and transactions, which you can then search or pivot on. - A simple tag is a word (which may contain hyphens) followed by a full + A simple tag is a word (which may contain hyphens) followed by a full colon, written inside a transaction or posting comment line: 2017/1/16 bought groceries ; sometag: - Tags can have a value, which is the text after the colon, up to the + Tags can have a value, which is the text after the colon, up to the next comma or end of line, with leading/trailing whitespace removed: expenses:food $10 ; a-posting-tag: the tag value - Note this means hledger's tag values can not contain commas or new- + Note this means hledger's tag values can not contain commas or new- lines. Ending at commas means you can write multiple short tags on one line, comma separated: @@ -3910,57 +3916,57 @@ JOURNAL FORMAT o "tag2" is another tag, whose value is "some value ..." - Tags in a transaction comment affect the transaction and all of its - postings, while tags in a posting comment affect only that posting. - For example, the following transaction has three tags (A, TAG2, third- + Tags in a transaction comment affect the transaction and all of its + postings, while tags in a posting comment affect only that posting. + For example, the following transaction has three tags (A, TAG2, third- tag) and the posting has four (those plus posting-tag): 1/1 a transaction ; A:, TAG2: ; third-tag: a third transaction tag, <- with a value (a) $1 ; posting-tag: - Tags are like Ledger's metadata feature, except hledger's tag values + Tags are like Ledger's metadata feature, except hledger's tag values are simple strings. Postings - A posting is an addition of some amount to, or removal of some amount - from, an account. Each posting line begins with at least one space or + A posting is an addition of some amount to, or removal of some amount + from, an account. Each posting line begins with at least one space or tab (2 or 4 spaces is common), followed by: o (optional) a status character (empty, !, or *), followed by a space - o (required) an account name (any text, optionally containing single + o (required) an account name (any text, optionally containing single spaces, until end of line or a double space) o (optional) two or more spaces or tabs followed by an amount. - Positive amounts are being added to the account, negative amounts are + Positive amounts are being added to the account, negative amounts are being removed. The amounts within a transaction must always sum up to zero. As a con- - venience, one amount may be left blank; it will be inferred so as to + venience, one amount may be left blank; it will be inferred so as to balance the transaction. - Be sure to note the unusual two-space delimiter between account name - and amount. This makes it easy to write account names containing spa- - ces. But if you accidentally leave only one space (or tab) before the + Be sure to note the unusual two-space delimiter between account name + and amount. This makes it easy to write account names containing spa- + ces. But if you accidentally leave only one space (or tab) before the amount, the amount will be considered part of the account name. Virtual postings A posting with a parenthesised account name is called a virtual posting - or unbalanced posting, which means it is exempt from the usual rule + or unbalanced posting, which means it is exempt from the usual rule that a transaction's postings must balance add up to zero. - This is not part of double entry accounting, so you might choose to - avoid this feature. Or you can use it sparingly for certain special - cases where it can be convenient. Eg, you could set opening balances + This is not part of double entry accounting, so you might choose to + avoid this feature. Or you can use it sparingly for certain special + cases where it can be convenient. Eg, you could set opening balances without using a balancing equity account: 1/1 opening balances (assets:checking) $1000 (assets:savings) $2000 - A posting with a bracketed account name is called a balanced virtual + A posting with a bracketed account name is called a balanced virtual posting. The balanced virtual postings in a transaction must add up to zero (separately from other postings). Eg: @@ -3972,34 +3978,34 @@ JOURNAL FORMAT [assets:checking:available] $10 ; <- (something:else) $5 ; <- not required to balance - Ordinary non-parenthesised, non-bracketed postings are called real - postings. You can exclude virtual postings from reports with the + Ordinary non-parenthesised, non-bracketed postings are called real + postings. You can exclude virtual postings from reports with the -R/--real flag or real:1 query. Account names - Account names typically have several parts separated by a full colon, - from which hledger derives a hierarchical chart of accounts. They can - be anything you like, but in finance there are traditionally five top- + Account names typically have several parts separated by a full colon, + from which hledger derives a hierarchical chart of accounts. They can + be anything you like, but in finance there are traditionally five top- level accounts: assets, liabilities, revenue, expenses, and equity. - Account names may contain single spaces, eg: assets:accounts receiv- - able. Because of this, they must always be followed by two or more + Account names may contain single spaces, eg: assets:accounts receiv- + able. Because of this, they must always be followed by two or more spaces (or newline). Account names can be aliased. Amounts - After the account name, there is usually an amount. (Important: + After the account name, there is usually an amount. (Important: between account name and amount, there must be two or more spaces.) - hledger's amount format is flexible, supporting several international - formats. Here are some examples. Amounts have a number (the "quan- + hledger's amount format is flexible, supporting several international + formats. Here are some examples. Amounts have a number (the "quan- tity"): 1 ..and usually a currency symbol or commodity name (more on this below), - to the left or right of the quantity, with or without a separating + to the left or right of the quantity, with or without a separating space: $1 @@ -4007,13 +4013,13 @@ JOURNAL FORMAT 3 "green apples" Amounts can be preceded by a minus sign (or a plus sign, though plus is - the default), The sign can be written before or after a left-side com- + the default), The sign can be written before or after a left-side com- modity symbol: -$1 $-1 - One or more spaces between the sign and the number are acceptable when + One or more spaces between the sign and the number are acceptable when parsing (but they won't be displayed in output): + $1 @@ -4030,8 +4036,8 @@ JOURNAL FORMAT 1.23 1,23456780000009 - In the integer part of the quantity (left of the decimal mark), groups - of digits can optionally be separated by a "digit group mark" - a + In the integer part of the quantity (left of the decimal mark), groups + of digits can optionally be separated by a "digit group mark" - a space, comma, or period (different from the decimal mark): $1,000,000.00 @@ -4045,39 +4051,39 @@ JOURNAL FORMAT 1,000 1.000 - If you don't tell it otherwise, hledger will assume both of the above + If you don't tell it otherwise, hledger will assume both of the above are decimal marks, parsing both numbers as 1. To prevent confusion and - undetected typos, we recommend adding commodity directives at the top - of your journal file to explicitly declare the decimal mark (and - optionally a digit group mark) for each commodity. Read on for more + undetected typos, we recommend adding commodity directives at the top + of your journal file to explicitly declare the decimal mark (and + optionally a digit group mark) for each commodity. Read on for more about this. Commodity - Amounts in hledger have both a "quantity", which is a signed decimal + Amounts in hledger have both a "quantity", which is a signed decimal number, and a "commodity", which is a currency symbol, stock ticker, or any word or phrase describing something you are tracking. If the commodity name contains non-letters (spaces, numbers, or punctu- - ation), you must always write it inside double quotes ("green apples", + ation), you must always write it inside double quotes ("green apples", "ABC123"). - If you write just a bare number, that too will have a commodity, with + If you write just a bare number, that too will have a commodity, with name ""; we call that the "no-symbol commodity". - Actually, hledger combines these single-commodity amounts into more - powerful multi-commodity amounts, which are what it works with most of - the time. A multi-commodity amount could be, eg: 1 USD, 2 EUR, 3.456 - TSLA. In practice, you will only see multi-commodity amounts in + Actually, hledger combines these single-commodity amounts into more + powerful multi-commodity amounts, which are what it works with most of + the time. A multi-commodity amount could be, eg: 1 USD, 2 EUR, 3.456 + TSLA. In practice, you will only see multi-commodity amounts in hledger's output; you can't write them directly in the journal file. - (If you are writing scripts or working with hledger's internals, these + (If you are writing scripts or working with hledger's internals, these are the Amount and MixedAmount types.) Commodity directives You can add commodity directives to the journal, preferably at the top, - to declare your commodities and help with number parsing (see above) - and display (see below). These are optional, but recommended. They - are described in more detail in JOURNAL FORMAT -> Declaring commodi- + to declare your commodities and help with number parsing (see above) + and display (see below). These are optional, but recommended. They + are described in more detail in JOURNAL FORMAT -> Declaring commodi- ties. Here's a quick example: # number format and display style for $, EUR, INR and the no-symbol commodity: @@ -4089,48 +4095,48 @@ JOURNAL FORMAT Commodity display style For the amounts in each commodity, hledger chooses a consistent display - style to use in most reports. (Exceptions: price amounts, and all + style to use in most reports. (Exceptions: price amounts, and all amounts displayed by the print command, are displayed with all of their decimal digits visible.) A commodity's display style is inferred as follows. - First, if a default commodity is declared with D, this commodity and + First, if a default commodity is declared with D, this commodity and its style is applied to any no-symbol amounts in the journal. - Then each commodity's style is inferred from one of the following, in + Then each commodity's style is inferred from one of the following, in order of preference: - o The commodity directive for that commodity (including the no-symbol + o The commodity directive for that commodity (including the no-symbol commodity), if any. - o The amounts in that commodity seen in the journal's transactions. + o The amounts in that commodity seen in the journal's transactions. (Posting amounts only; prices and periodic or auto rules are ignored, currently.) - o The built-in fallback style, which looks like this: $1000.00. (Sym- + o The built-in fallback style, which looks like this: $1000.00. (Sym- bol on the left, period decimal mark, two decimal places.) A style is inferred from journal amounts as follows: - o Use the general style (decimal mark, symbol placement) of the first + o Use the general style (decimal mark, symbol placement) of the first amount - o Use the first-seen digit group style (digit group mark, digit group + o Use the first-seen digit group style (digit group mark, digit group sizes), if any o Use the maximum number of decimal places of all. - Transaction price amounts don't affect the commodity display style - directly, but occasionally they can do so indirectly (eg when a post- - ing's amount is inferred using a transaction price). If you find this + Transaction price amounts don't affect the commodity display style + directly, but occasionally they can do so indirectly (eg when a post- + ing's amount is inferred using a transaction price). If you find this causing problems, use a commodity directive to fix the display style. - To summarise: each commodity's amounts will be normalised to (a) the - style declared by a commodity directive, or (b) the style of the first - posting amount in the journal, with the first-seen digit group style - and the maximum-seen number of decimal places. So if your reports are - showing amounts in a way you don't like, eg with too many decimal + To summarise: each commodity's amounts will be normalised to (a) the + style declared by a commodity directive, or (b) the style of the first + posting amount in the journal, with the first-seen digit group style + and the maximum-seen number of decimal places. So if your reports are + showing amounts in a way you don't like, eg with too many decimal places, use a commodity directive. Some examples: # declare euro, dollar, bitcoin and no-symbol commodities and set their @@ -4142,17 +4148,17 @@ JOURNAL FORMAT Rounding Amounts are stored internally as decimal numbers with up to 255 decimal - places, and displayed with the number of decimal places specified by - the commodity display style. Note, hledger uses banker's rounding: it - rounds to the nearest even number, eg 0.5 displayed with zero decimal - places is "0"). (Guaranteed since hledger 1.17.1; in older versions + places, and displayed with the number of decimal places specified by + the commodity display style. Note, hledger uses banker's rounding: it + rounds to the nearest even number, eg 0.5 displayed with zero decimal + places is "0"). (Guaranteed since hledger 1.17.1; in older versions this could vary if hledger was built with Decimal < 0.5.1.) Transaction prices Within a transaction, you can note an amount's price in another commod- - ity. This can be used to document the cost (in a purchase) or selling - price (in a sale). For example, transaction prices are useful to - record purchases of a foreign currency. Note transaction prices are + ity. This can be used to document the cost (in a purchase) or selling + price (in a sale). For example, transaction prices are useful to + record purchases of a foreign currency. Note transaction prices are fixed at the time of the transaction, and do not change over time. See also market prices, which represent prevailing exchange rates on a cer- tain date. @@ -4178,14 +4184,14 @@ JOURNAL FORMAT assets:euros EUR100 ; one hundred euros purchased assets:dollars $-135 ; for $135 - 4. Like 1, but the @ is parenthesised, i.e. (@); this is for compati- - bility with Ledger journals (Virtual posting costs), and is equiva- + 4. Like 1, but the @ is parenthesised, i.e. (@); this is for compati- + bility with Ledger journals (Virtual posting costs), and is equiva- lent to 1 in hledger. 5. Like 2, but as in 4 the @@ is parenthesised, i.e. (@@); in hledger, this is equivalent to 2. - Use the -B/--cost flag to convert amounts to their transaction price's + Use the -B/--cost flag to convert amounts to their transaction price's commodity, if any. (mnemonic: "B" is from "cost Basis", as in Ledger). Eg here is how -B affects the balance report for the example above: @@ -4196,8 +4202,8 @@ JOURNAL FORMAT $-135 assets:dollars $135 assets:euros # <- the euros' cost - Note -B is sensitive to the order of postings when a transaction price - is inferred: the inferred price will be in the commodity of the last + Note -B is sensitive to the order of postings when a transaction price + is inferred: the inferred price will be in the commodity of the last amount. So if example 3's postings are reversed, while the transaction is equivalent, -B shows something different: @@ -4210,18 +4216,18 @@ JOURNAL FORMAT EUR100 assets:euros Lot prices, lot dates - Ledger allows another kind of price, lot price (four variants: {UNIT- + Ledger allows another kind of price, lot price (four variants: {UNIT- PRICE}, {{TOTALPRICE}}, {=FIXEDUNITPRICE}, {{=FIXEDTOTALPRICE}}), and/or a lot date ([DATE]) to be specified. These are normally used to - select a lot when selling investments. hledger will parse these, for - compatibility with Ledger journals, but currently ignores them. A - transaction price, lot price and/or lot date may appear in any order, + select a lot when selling investments. hledger will parse these, for + compatibility with Ledger journals, but currently ignores them. A + transaction price, lot price and/or lot date may appear in any order, after the posting amount and before the balance assertion if any. Balance assertions - hledger supports Ledger-style balance assertions in journal files. - These look like, for example, = EXPECTEDBALANCE following a posting's - amount. Eg here we assert the expected dollar balance in accounts a + hledger supports Ledger-style balance assertions in journal files. + These look like, for example, = EXPECTEDBALANCE following a posting's + amount. Eg here we assert the expected dollar balance in accounts a and b after each posting: 2013/1/1 @@ -4233,32 +4239,32 @@ JOURNAL FORMAT b $-1 =$-2 After reading a journal file, hledger will check all balance assertions - and report an error if any of them fail. Balance assertions can pro- - tect you from, eg, inadvertently disrupting reconciled balances while - cleaning up old entries. You can disable them temporarily with the + and report an error if any of them fail. Balance assertions can pro- + tect you from, eg, inadvertently disrupting reconciled balances while + cleaning up old entries. You can disable them temporarily with the -I/--ignore-assertions flag, which can be useful for troubleshooting or - for reading Ledger files. (Note: this flag currently does not disable + for reading Ledger files. (Note: this flag currently does not disable balance assignments, below). Assertions and ordering - hledger sorts an account's postings and assertions first by date and - then (for postings on the same day) by parse order. Note this is dif- + hledger sorts an account's postings and assertions first by date and + then (for postings on the same day) by parse order. Note this is dif- ferent from Ledger, which sorts assertions only by parse order. (Also, - Ledger assertions do not see the accumulated effect of repeated post- + Ledger assertions do not see the accumulated effect of repeated post- ings to the same account within a transaction.) So, hledger balance assertions keep working if you reorder differently- - dated transactions within the journal. But if you reorder same-dated - transactions or postings, assertions might break and require updating. + dated transactions within the journal. But if you reorder same-dated + transactions or postings, assertions might break and require updating. This order dependence does bring an advantage: precise control over the order of postings and assertions within a day, so you can assert intra- day balances. Assertions and included files - With included files, things are a little more complicated. Including - preserves the ordering of postings and assertions. If you have multi- - ple postings to an account on the same day, split across different - files, and you also want to assert the account's balance on the same + With included files, things are a little more complicated. Including + preserves the ordering of postings and assertions. If you have multi- + ple postings to an account on the same day, split across different + files, and you also want to assert the account's balance on the same day, you'll have to put the assertion in the right file. Assertions and multiple -f options @@ -4266,15 +4272,15 @@ JOURNAL FORMAT -f options. Use include or concatenate the files instead. Assertions and commodities - The asserted balance must be a simple single-commodity amount, and in - fact the assertion checks only this commodity's balance within the - (possibly multi-commodity) account balance. This is how assertions + The asserted balance must be a simple single-commodity amount, and in + fact the assertion checks only this commodity's balance within the + (possibly multi-commodity) account balance. This is how assertions work in Ledger also. We could call this a "partial" balance assertion. To assert the balance of more than one commodity in an account, you can write multiple postings, each asserting one commodity's balance. - You can make a stronger "total" balance assertion by writing a double + You can make a stronger "total" balance assertion by writing a double equals sign (== EXPECTEDBALANCE). This asserts that there are no other unasserted commodities in the account (or, that their balance is 0). @@ -4294,7 +4300,7 @@ JOURNAL FORMAT a 0 == $1 It's not yet possible to make a complete assertion about a balance that - has multiple commodities. One workaround is to isolate each commodity + has multiple commodities. One workaround is to isolate each commodity into its own subaccount: 2013/1/1 @@ -4308,21 +4314,21 @@ JOURNAL FORMAT a:euro 0 == 1EUR Assertions and prices - Balance assertions ignore transaction prices, and should normally be + Balance assertions ignore transaction prices, and should normally be written without one: 2019/1/1 (a) $1 @ EUR1 = $1 - We do allow prices to be written there, however, and print shows them, - even though they don't affect whether the assertion passes or fails. - This is for backward compatibility (hledger's close command used to - generate balance assertions with prices), and because balance assign- + We do allow prices to be written there, however, and print shows them, + even though they don't affect whether the assertion passes or fails. + This is for backward compatibility (hledger's close command used to + generate balance assertions with prices), and because balance assign- ments do use them (see below). Assertions and subaccounts - The balance assertions above (= and ==) do not count the balance from - subaccounts; they check the account's exclusive balance only. You can + The balance assertions above (= and ==) do not count the balance from + subaccounts; they check the account's exclusive balance only. You can assert the balance including subaccounts by writing =* or ==*, eg: 2019/1/1 @@ -4336,16 +4342,16 @@ JOURNAL FORMAT tual. They are not affected by the --real/-R flag or real: query. Assertions and precision - Balance assertions compare the exactly calculated amounts, which are - not always what is shown by reports. Eg a commodity directive may - limit the display precision, but this will not affect balance asser- + Balance assertions compare the exactly calculated amounts, which are + not always what is shown by reports. Eg a commodity directive may + limit the display precision, but this will not affect balance asser- tions. Balance assertion failure messages show exact amounts. Balance assignments - Ledger-style balance assignments are also supported. These are like - balance assertions, but with no posting amount on the left side of the - equals sign; instead it is calculated automatically so as to satisfy - the assertion. This can be a convenience during data entry, eg when + Ledger-style balance assignments are also supported. These are like + balance assertions, but with no posting amount on the left side of the + equals sign; instead it is calculated automatically so as to satisfy + the assertion. This can be a convenience during data entry, eg when setting opening balances: ; starting a new journal, set asset account balances @@ -4363,14 +4369,14 @@ JOURNAL FORMAT expenses:misc The calculated amount depends on the account's balance in the commodity - at that point (which depends on the previously-dated postings of the - commodity to that account since the last balance assertion or assign- + at that point (which depends on the previously-dated postings of the + commodity to that account since the last balance assertion or assign- ment). Note that using balance assignments makes your journal a little less explicit; to know the exact amount posted, you have to run hledger or do the calculations yourself, instead of just reading it. Balance assignments and prices - A transaction price in a balance assignment will cause the calculated + A transaction price in a balance assignment will cause the calculated amount to have that price attached: 2019/1/1 @@ -4381,52 +4387,52 @@ JOURNAL FORMAT (a) $1 @ EUR2 = $1 @ EUR2 Directives - A directive is a line in the journal beginning with a special keyword, + A directive is a line in the journal beginning with a special keyword, that influences how the journal is processed. hledger's directives are based on a subset of Ledger's, but there are many differences (and also some differences between hledger versions). Directives' behaviour and interactions can get a little bit complex, so - here is a table summarising the directives and their effects, with - links to more detailed docs. Note part of this table is hidden when + here is a table summarising the directives and their effects, with + links to more detailed docs. Note part of this table is hidden when viewed in a web browser - scroll it sideways to see more. - direc- end subdi- purpose can affect (as of + direc- end subdi- purpose can affect (as of tive directive rec- 2018/06) tives ------------------------------------------------------------------------------------ - account any document account names, all entries in all - text declare account types & dis- files, before or + account any document account names, all entries in all + text declare account types & dis- files, before or play order after alias end rewrite account names following entries - aliases until end of cur- + aliases until end of cur- rent file or end directive - apply end apply prepend a common parent to following entries - account account account names until end of cur- + apply end apply prepend a common parent to following entries + account account account names until end of cur- rent file or end directive comment end com- ignore part of journal following entries - ment until end of cur- + ment until end of cur- rent file or end directive - commod- format declare a commodity and its number notation: + commod- format declare a commodity and its number notation: ity number notation & display following entries style in that commodity in all files ; dis- play style: amounts of that commodity in reports - D declare a commodity to be default commodity: + D declare a commodity to be default commodity: used for commodityless following commod- - amounts, and its number ityless entries - notation & display style until end of cur- + amounts, and its number ityless entries + notation & display style until end of cur- rent file; number notation: following entries in that commodity until end - of current file; + of current file; display style: amounts of that commodity in @@ -4434,17 +4440,17 @@ JOURNAL FORMAT include include entries/directives what the included from another file directives affect [payee] declare a payee name following entries - until end of cur- + until end of cur- rent file P declare a market price for a amounts of that commodity commodity in reports, when -V is used - Y declare a year for yearless following entries - dates until end of cur- + Y declare a year for yearless following entries + dates until end of cur- rent file - = declare an auto posting all entries in par- - rule, adding postings to ent/current/child + = declare an auto posting all entries in par- + rule, adding postings to ent/current/child other transactions files (but not sib- ling files, see #1212) @@ -4452,53 +4458,53 @@ JOURNAL FORMAT And some definitions: - subdi- optional indented directive line immediately following a parent + subdi- optional indented directive line immediately following a parent rec- directive tive number how to interpret numbers when parsing journal entries (the iden- - nota- tity of the decimal separator character). (Currently each com- + nota- tity of the decimal separator character). (Currently each com- tion modity can have its own notation, even in the same file.) - dis- how to display amounts of a commodity in reports (symbol side + dis- how to display amounts of a commodity in reports (symbol side play and spacing, digit groups, decimal separator, decimal places) style - direc- which entries and (when there are multiple files) which files + direc- which entries and (when there are multiple files) which files tive are affected by a directive scope As you can see, directives vary in which journal entries and files they - affect, and whether they are focussed on input (parsing) or output + affect, and whether they are focussed on input (parsing) or output (reports). Some directives have multiple effects. Directives and multiple files - If you use multiple -f/--file options, or the include directive, - hledger will process multiple input files. But note that directives + If you use multiple -f/--file options, or the include directive, + hledger will process multiple input files. But note that directives which affect input (see above) typically last only until the end of the file in which they occur. This may seem inconvenient, but it's intentional; it makes reports sta- - ble and deterministic, independent of the order of input. Otherwise - you could see different numbers if you happened to write -f options in - a different order, or if you moved includes around while cleaning up + ble and deterministic, independent of the order of input. Otherwise + you could see different numbers if you happened to write -f options in + a different order, or if you moved includes around while cleaning up your files. - It can be surprising though; for example, it means that alias direc- + It can be surprising though; for example, it means that alias direc- tives do not affect parent or sibling files (see below). Comment blocks - A line containing just comment starts a commented region of the file, + A line containing just comment starts a commented region of the file, and a line containing just end comment (or the end of the current file) ends it. See also comments. Including other files - You can pull in the content of additional files by writing an include + You can pull in the content of additional files by writing an include directive, like this: include FILEPATH - Only journal files can include, and only journal, timeclock or timedot + Only journal files can include, and only journal, timeclock or timedot files can be included (not CSV files, currently). - If the file path does not begin with a slash, it is relative to the + If the file path does not begin with a slash, it is relative to the current file's folder. A tilde means home directory, eg: include ~/main.journal. @@ -4506,18 +4512,18 @@ JOURNAL FORMAT The path may contain glob patterns to match multiple files, eg: include *.journal. - There is limited support for recursive wildcards: **/ (the slash is - required) matches 0 or more subdirectories. It's not super convenient - since you have to avoid include cycles and including directories, but + There is limited support for recursive wildcards: **/ (the slash is + required) matches 0 or more subdirectories. It's not super convenient + since you have to avoid include cycles and including directories, but this can be done, eg: include */**/*.journal. The path may also be prefixed to force a specific file format, overrid- - ing the file extension (as described in hledger.1 -> Input files): + ing the file extension (as described in hledger.1 -> Input files): include timedot:~/notes/2020*.md. Default year - You can set a default year to be used for subsequent dates which don't - specify a year. This is a line beginning with Y followed by the year. + You can set a default year to be used for subsequent dates which don't + specify a year. This is a line beginning with Y followed by the year. Eg: Y2009 ; set default year to 2009 @@ -4537,39 +4543,39 @@ JOURNAL FORMAT assets Declaring payees - The payee directive can be used to declare a limited set of payees - which may appear in transaction descriptions. The "payees" check will - report an error if any transaction refers to a payee that has not been + The payee directive can be used to declare a limited set of payees + which may appear in transaction descriptions. The "payees" check will + report an error if any transaction refers to a payee that has not been declared. Eg: payee Whole Foods Declaring commodities - You can use commodity directives to declare your commodities. In fact + You can use commodity directives to declare your commodities. In fact the commodity directive performs several functions at once: - 1. It declares commodities which may be used in the journal. This can - optionally be enforced, providing useful error checking. (Cf Com- + 1. It declares commodities which may be used in the journal. This can + optionally be enforced, providing useful error checking. (Cf Com- modity error checking) - 2. It declares which decimal mark character (period or comma), to - expect when parsing input - useful to disambiguate international - number formats in your data. Without this, hledger will parse both + 2. It declares which decimal mark character (period or comma), to + expect when parsing input - useful to disambiguate international + number formats in your data. Without this, hledger will parse both 1,000 and 1.000 as 1. (Cf Amounts) - 3. It declares how to render the commodity's amounts when displaying + 3. It declares how to render the commodity's amounts when displaying output - the decimal mark, any digit group marks, the number of dec- - imal places, symbol placement and so on. (Cf Commodity display + imal places, symbol placement and so on. (Cf Commodity display style) - You will run into one of the problems solved by commodity directives + You will run into one of the problems solved by commodity directives sooner or later, so we recommend using them, for robust and predictable parsing and display. - Generally you should put them at the top of your journal file (since + Generally you should put them at the top of your journal file (since for function 2, they affect only following amounts, cf #793). - A commodity directive is just the word commodity followed by a sample + A commodity directive is just the word commodity followed by a sample amount, like this: ;commodity SAMPLEAMOUNT @@ -4577,8 +4583,8 @@ JOURNAL FORMAT commodity $1000.00 commodity 1,000.0000 AAAA ; optional same-line comment - It may also be written on multiple lines, and use the format subdirec- - tive, as in Ledger. Note in this case the commodity symbol appears + It may also be written on multiple lines, and use the format subdirec- + tive, as in Ledger. Note in this case the commodity symbol appears twice; it must be the same in both places: ;commodity SYMBOL @@ -4590,11 +4596,11 @@ JOURNAL FORMAT commodity INR format INR 1,00,00,000.00 - Remember that if the commodity symbol contains spaces, numbers, or + Remember that if the commodity symbol contains spaces, numbers, or punctuation, it must be enclosed in double quotes (cf Commodity). - The amount's quantity does not matter; only the format is significant. - It must include a decimal mark - either a period or a comma - followed + The amount's quantity does not matter; only the format is significant. + It must include a decimal mark - either a period or a comma - followed by 0 or more decimal digits. A few more examples: @@ -4605,27 +4611,27 @@ JOURNAL FORMAT commodity INR 9,99,99,999.0 commodity 1 000 000. - Note hledger normally uses banker's rounding, so 0.5 displayed with + Note hledger normally uses banker's rounding, so 0.5 displayed with zero decimal digits is "0". (More at Commodity display style.) Commodity error checking - In strict mode, enabled with the -s/--strict flag, hledger will report - an error if a commodity symbol is used that has not been declared by a - commodity directive. This works similarly to account error checking, + In strict mode, enabled with the -s/--strict flag, hledger will report + an error if a commodity symbol is used that has not been declared by a + commodity directive. This works similarly to account error checking, see the notes there for more details. Default commodity The D directive sets a default commodity, to be used for any subsequent - commodityless amounts (ie, plain numbers) seen while parsing the jour- - nal. This effect lasts until the next D directive, or the end of the + commodityless amounts (ie, plain numbers) seen while parsing the jour- + nal. This effect lasts until the next D directive, or the end of the journal. - For compatibility/historical reasons, D also acts like a commodity + For compatibility/historical reasons, D also acts like a commodity directive (setting the commodity's decimal mark for parsing and display style for output). - As with commodity, the amount must include a decimal mark (either - period or comma). If both commodity and D directives are used for the + As with commodity, the amount must include a decimal mark (either + period or comma). If both commodity and D directives are used for the same commodity, the commodity style takes precedence. The syntax is D AMOUNT. Eg: @@ -4639,27 +4645,25 @@ JOURNAL FORMAT b Declaring market prices - The P directive declares a market price, which is an exchange rate + The P directive declares a market price, which is an exchange rate between two commodities on a certain date. (In Ledger, they are called - "historical prices".) These are often obtained from a stock exchange, + "historical prices".) These are often obtained from a stock exchange, cryptocurrency exchange, or the foreign exchange market. - Here is the format: + The format is: - P DATE COMMODITYA COMMODITYBAMOUNT + P DATE COMMODITY1SYMBOL COMMODITY2AMOUNT - o DATE is a simple date + DATE is a simple date, COMMODITY1SYMBOL is the symbol of the commodity + being priced, and COMMODITY2AMOUNT is the amount (symbol and quantity) + of commodity 2 that one unit of commodity 1 is worth on this date. + Examples: - o COMMODITYA is the symbol of the commodity being priced + # one euro was worth $1.35 from 2009-01-01 onward: + P 2009-01-01 EUR $1.35 - o COMMODITYBAMOUNT is an amount (symbol and quantity) in a second com- - modity, giving the price in commodity B of one unit of commodity A. - - These two market price directives say that one euro was worth 1.35 US - dollars during 2009, and $1.40 from 2010 onward: - - P 2009/1/1 EUR $1.35 - P 2010/1/1 EUR $1.40 + # and $1.40 from 2010-01-01 onward: + P 2010-01-01 EUR $1.40 The -V, -X and --value flags use these market prices to show amount values in another commodity. See Valuation. @@ -5291,40 +5295,42 @@ CSV FORMAT below, after the examples: - skip skip one or more header lines or matched - CSV records - fields name CSV fields, assign them to hledger - fields - field assignment assign a value to one hledger field, - with interpolation - separator a custom field separator - if block apply some rules to CSV records matched - by patterns - if table apply some rules to CSV records matched - by patterns, alternate syntax - end skip the remaining CSV records - date-format how to parse dates in CSV records - decimal-mark the decimal mark used in CSV amounts, if - ambiguous - newest-first disambiguate record order when there's - only one date - include inline another CSV rules file - balance-type choose which type of balance assignments - to use + skip skip one or more header lines or matched CSV + records + fields list name CSV fields, assign them to hledger + fields + field assignment assign a value to one hledger field, with + interpolation + Field names hledger field names, used in the fields list + and field assignments + separator a custom field separator + if block apply some rules to CSV records matched by + patterns + if table apply some rules to CSV records matched by + patterns, alternate syntax + end skip the remaining CSV records + date-format how to parse dates in CSV records + decimal-mark the decimal mark used in CSV amounts, if + ambiguous + newest-first disambiguate record order when there's only + one date + include inline another CSV rules file + balance-type choose which type of balance assignments to + use - Note, for best error messages when reading CSV files, use a .csv, .tsv + Note, for best error messages when reading CSV files, use a .csv, .tsv or .ssv file extension or file prefix - see File Extension below. There's an introductory Convert CSV files tutorial on hledger.org. Examples - Here are some sample hledger CSV rules files. See also the full col- + Here are some sample hledger CSV rules files. See also the full col- lection at: https://github.com/simonmichael/hledger/tree/master/examples/csv Basic - At minimum, the rules file must identify the date and amount fields, - and often it also specifies the date format and how many header lines + At minimum, the rules file must identify the date and amount fields, + and often it also specifies the date format and how many header lines there are. Here's a simple CSV file and a rules file for it: Date, Description, Id, Amount @@ -5343,8 +5349,8 @@ CSV FORMAT Default account names are chosen, since we didn't set them. Bank of Ireland - Here's a CSV with two amount fields (Debit and Credit), and a balance - field, which we can use to add balance assertions, which is not neces- + Here's a CSV with two amount fields (Debit and Credit), and a balance + field, which we can use to add balance assertions, which is not neces- sary but provides extra error checking: Date,Details,Debit,Credit,Balance @@ -5386,13 +5392,13 @@ CSV FORMAT assets:bank:boi:checking EUR-5.0 = EUR126.0 expenses:unknown EUR5.0 - The balance assertions don't raise an error above, because we're read- - ing directly from CSV, but they will be checked if these entries are + The balance assertions don't raise an error above, because we're read- + ing directly from CSV, but they will be checked if these entries are imported into a journal file. Amazon Here we convert amazon.com order history, and use an if block to gener- - ate a third posting if there's a fee. (In practice you'd probably get + ate a third posting if there's a fee. (In practice you'd probably get this data from your bank instead, but it's an example.) "Date","Type","To/From","Name","Status","Amount","Fees","Transaction ID" @@ -5444,7 +5450,7 @@ CSV FORMAT expenses:fees $1.00 Paypal - Here's a real-world rules file for (customised) Paypal CSV, with some + Here's a real-world rules file for (customised) Paypal CSV, with some Paypal-specific rules, and a second rules file included: "Date","Time","TimeZone","Name","Type","Status","Currency","Gross","Fee","Net","From Email Address","To Email Address","Transaction ID","Item Title","Item ID","Reference Txn ID","Receipt ID","Balance","Note" @@ -5599,26 +5605,27 @@ CSV FORMAT skip skip N - The word "skip" followed by a number (or no number, meaning 1) tells - hledger to ignore this many non-empty lines preceding the CSV data. - (Empty/blank lines are skipped automatically.) You'll need this when- + The word "skip" followed by a number (or no number, meaning 1) tells + hledger to ignore this many non-empty lines preceding the CSV data. + (Empty/blank lines are skipped automatically.) You'll need this when- ever your CSV data contains header lines. It also has a second purpose: it can be used inside if blocks to ignore certain CSV records (described below). - fields + fields list fields FIELDNAME1, FIELDNAME2, ... - A fields list (the word "fields" followed by comma-separated field - names) is the quick way to assign CSV field values to hledger fields. - It does two things: + A fields list (the word "fields" followed by comma-separated field + names) is the quick way to assign CSV field values to hledger fields. + (The other way is field assignments, see below.) A fields list does + does two things: - 1. it names the CSV fields. This is optional, but can be convenient + 1. It names the CSV fields. This is optional, but can be convenient later for interpolating them. - 2. when you use a standard hledger field name, it assigns the CSV value - to that part of the hledger transaction. + 2. Whenever you use a standard hledger field name (defined below), the + CSV value is assigned to that part of the hledger 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 @@ -5626,90 +5633,43 @@ CSV FORMAT fields date, description, , amount, , , somefield, anotherfield - Field names may not contain whitespace. Fields you don't care about - can be left unnamed. Currently there must be least two items (there - must be at least one comma). + Tips: - Note, always use comma in the fields list, even if your CSV uses - another separator character. + o The fields list always use commas, even if your CSV data uses another + separator character. - Here are the standard hledger field/pseudo-field names. For more about - the transaction parts they refer to, see the manual for hledger's jour- - nal format. + o Currently there must be least two items in the list (at least one + comma). - Transaction field names - date, date2, status, code, description, comment can be used to form the - transaction's first line. + o Field names may not contain spaces. Spaces before/after field names + are optional. - Posting field names - account - accountN, where N is 1 to 99, causes a posting to be generated, with - that account name. + o If the CSV contains column headings, it's a good idea to use these, + suitably modified, as the basis for your field names (eg lower-cased, + with underscores instead of spaces). - 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, and in conditional blocks. + o If some heading names match standard hledger fields, but you don't + want to set the hledger fields directly, alter those names, eg by + appending an underscore. - 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 - amountN sets the Nth posting's amount. By assigning to amount1, - amount2, ... etc. you can generate up to 99 postings. - - If the CSV uses separate fields for debits and credits (inflows and - outflows), you can use amountN-in and amountN-out instead. Note - hledger assumes both of these fields are unsigned, and will automati- - cally negate the "-out" value. If the fields are signed, see "Setting - amounts" below. - - There is also an unnumbered form of these names: amount, or amount-in - and amount-out. This is supported to keep pre-hledger-1.17 CSV rules - files working (and for occasional convenience). It is suitable only - for two-posting transactions; it sets both posting 1's and posting 2's - amount. Posting 2's amount will be negated, and also converted to cost - if there's a transaction price. - - If you have an existing rules file using the unnumbered form, you might - want to use the numbered form in certain conditional blocks, without - having to update and retest all the old rules. To facilitate this, - posting 1 ignores amount/amount-in/amount-out if any of - amount1/amount1-in/amount1-out are assigned, and posting 2 ignores them - if any of amount2/amount2-in/amount2-out are assigned, avoiding con- - flicts. - - currency - If the CSV has the currency symbol in a separate field (ie, not part of - the amount field), you can use currencyN to prepend it to posting N's - amount. Or, currency with no number affects all postings. - - balance - balanceN sets a balance assertion amount (or if the posting amount is - left empty, a balance assignment) on posting N. - - Also, for compatibility with hledger <1.17: balance with no number is - equivalent to balance1. - - You can adjust the type of assertion/assignment with the balance-type - rule (see below). - - comment - Finally, commentN sets a comment on the Nth posting. Comments can also - contain tags, as usual. - - See TIPS below for more about setting amounts and currency. + o Fields you don't care about can be given a dummy name (eg: _ ), or no + name. field assignment HLEDGERFIELDNAME FIELDVALUE - Instead of or in addition to a fields list, you can use a "field - assignment" rule to set the value of a single hledger field, by writing - its name (any of the standard hledger field names above) followed by a - text value. The value may contain interpolated CSV fields, referenced - by their 1-based position in the CSV record (%N), or by the name they - were given in the fields list (%CSVFIELDNAME). Some examples: + 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 by their 1-based position in the CSV + record (%N), or by the name they were given in the fields list (%CSV- + FIELDNAME). + + Some examples: # set the amount to the 4th CSV field, with " USD" appended amount %4 USD @@ -5717,9 +5677,97 @@ CSV FORMAT # combine three fields to make a comment, containing note: and date: tags comment note: %somefield - %anotherfield, date: %1 - Interpolation strips outer whitespace (so a CSV value like " 1 " - becomes 1 when interpolated) (#1051). See TIPS below for more about - referencing other fields. + Tips: + + o Interpolation strips outer whitespace (so a CSV value like " 1 " + becomes 1 when interpolated) (#1051). + + o See also Tips below. + + Field names + Here are the standard hledger field (and pseudo-field) names, which you + can use in a fields list and in field assignments. For more about the + transaction parts they refer to, see Transactions. + + date field + Assigning to date sets the transaction date. + + date2 field + date2 sets the transaction's secondary date, if any. + + status field + status sets the transaction's status, if any. + + code field + code sets the transaction's code, if any. + + description field + description sets the transaction's description, if any. + + comment field + comment sets the transaction's comment, if any. + + commentN, where N is a number, sets the Nth posting's comment. + + Tips: - Only single-line comments can be assigned. - Comments can con- + tain tags, as usual. + + account field + 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 + each transaction's description, and in conditional blocks. + + 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 + amountN sets the amount of the Nth posting, and causes that posting to + be generated. By assigning to amount1, amount2, ... etc. you can + generate up to 99 postings. + + amountN-in and amountN-out can be used instead, if the CSV uses sepa- + rate fields for debits and credits (inflows and outflows). hledger + assumes both of these CSV fields are unsigned, and will automatically + negate the "-out" value. If they are signed, see "Setting amounts" + below. + + amount, or amount-in and amount-out are a legacy mode, to keep pre- + hledger-1.17 CSV rules files working (and for occasional convenience). + They are suitable only for two-posting transactions; they set both + posting 1's and posting 2's amount. Posting 2's amount will be + negated, and also converted to cost if there's a transaction price. + + If you have an existing rules file using the unnumbered form, you might + want to use the numbered form in certain conditional blocks, without + having to update and retest all the old rules. To facilitate this, + posting 1 ignores amount/amount-in/amount-out if any of + amount1/amount1-in/amount1-out are assigned, and posting 2 ignores them + if any of amount2/amount2-in/amount2-out are assigned, avoiding con- + flicts. + + 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 + 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 + 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 + rule (see below). + + See Tips below for more about setting amounts and currency. separator You can use the separator rule to read other kinds of character-sepa- @@ -5910,6 +5958,11 @@ CSV FORMAT https://hackage.haskell.org/package/time/docs/Data-Time-For- mat.html#v:formatTime + Note that although you can parse date-times which include a time zone, + that time zone is ignored; it will not change the date that is parsed. + This means when reading CSV data with times not in your local time + zone, dates can be "off by one". + decimal-mark decimal-mark . @@ -5917,22 +5970,22 @@ CSV FORMAT decimal-mark , - hledger automatically accepts either period or comma as a decimal mark - when parsing numbers (cf Amounts). However if any numbers in the CSV - contain digit group marks, such as thousand-separating commas, you - should declare the decimal mark explicitly with this rule, to avoid + hledger automatically accepts either period or comma as a decimal mark + when parsing numbers (cf Amounts). However if any numbers in the CSV + contain digit group marks, such as thousand-separating commas, you + should declare the decimal mark explicitly with this rule, to avoid misparsed numbers. newest-first - hledger always sorts the generated transactions by date. Transactions - on the same date should appear in the same order as their CSV records, - as hledger can usually auto-detect whether the CSV's normal order is + hledger always sorts the generated transactions by date. Transactions + on the same date should appear in the same order as their CSV records, + as hledger can usually auto-detect whether the CSV's normal order is oldest first or newest first. But if all of the following are true: - o the CSV might sometimes contain just one day of data (all records + o the CSV might sometimes contain just one day of data (all records having the same date) - o the CSV records are normally in reverse chronological order (newest + o the CSV records are normally in reverse chronological order (newest at the top) o and you care about preserving the order of same-day transactions @@ -5945,9 +5998,9 @@ CSV FORMAT include include RULESFILE - This includes the contents of another CSV rules file at this point. - RULESFILE is an absolute file path or a path relative to the current - file's directory. This can be useful for sharing common rules between + This includes the contents of another CSV rules file at this point. + RULESFILE is an absolute file path or a path relative to the current + file's directory. This can be useful for sharing common rules between several rules files, eg: # someaccount.csv.rules @@ -5962,10 +6015,10 @@ CSV FORMAT balance-type Balance assertions generated by assigning to balanceN are of the simple - = type by default, which is a single-commodity, subaccount-excluding + = type by default, which is a single-commodity, subaccount-excluding assertion. You may find the subaccount-including variants more useful, - eg if you have created some virtual subaccounts of checking to help - with budgeting. You can select a different type of assertion with the + eg if you have created some virtual subaccounts of checking to help + with budgeting. You can select a different type of assertion with the balance-type rule: # balance assertions will consider all commodities and all subaccounts @@ -5980,19 +6033,19 @@ CSV FORMAT Tips Rapid feedback - It's a good idea to get rapid feedback while creating/troubleshooting + It's a good idea to get rapid feedback while creating/troubleshooting CSV rules. Here's a good way, using entr from http://eradman.com/entr- project : $ ls foo.csv* | entr bash -c 'echo ----; hledger -f foo.csv print desc:SOMEDESC' - A desc: query (eg) is used to select just one, or a few, transactions - of interest. "bash -c" is used to run multiple commands, so we can - echo a separator each time the command re-runs, making it easier to + A desc: query (eg) is used to select just one, or a few, transactions + of interest. "bash -c" is used to run multiple commands, so we can + echo a separator each time the command re-runs, making it easier to read the output. Valid CSV - hledger accepts CSV conforming to RFC 4180. When CSV values are + hledger accepts CSV conforming to RFC 4180. When CSV values are enclosed in quotes, note: o they must be double quotes (not single quotes) @@ -6000,9 +6053,9 @@ CSV FORMAT o spaces outside the quotes are not allowed File Extension - To help hledger identify the format and show the right error messages, - CSV/SSV/TSV files should normally be named with a .csv, .ssv or .tsv - filename extension. Or, the file path should be prefixed with csv:, + To help hledger identify the format and show the right error messages, + CSV/SSV/TSV files should normally be named with a .csv, .ssv or .tsv + filename extension. Or, the file path should be prefixed with csv:, ssv: or tsv:. Eg: $ hledger -f foo.ssv print @@ -6011,48 +6064,48 @@ CSV FORMAT $ cat foo | hledger -f ssv:- foo - You can override the file extension with a separator rule if needed. + You can override the file extension with a separator rule if needed. See also: Input files in the hledger manual. Reading multiple CSV files - If you use multiple -f options to read multiple CSV files at once, - hledger will look for a correspondingly-named rules file for each CSV - file. But if you use the --rules-file option, that rules file will be + If you use multiple -f options to read multiple CSV files at once, + hledger will look for a correspondingly-named rules file for each CSV + file. But if you use the --rules-file option, that rules file will be used for all the CSV files. Valid transactions After reading a CSV file, hledger post-processes and validates the gen- erated journal entries as it would for a journal file - balancing them, - applying balance assignments, and canonicalising amount styles. Any - errors at this stage will be reported in the usual way, displaying the + applying balance assignments, and canonicalising amount styles. Any + errors at this stage will be reported in the usual way, displaying the problem entry. There is one exception: balance assertions, if you have generated them, - will not be checked, since normally these will work only when the CSV - data is part of the main journal. If you do need to check balance + will not be checked, since normally these will work only when the CSV + data is part of the main journal. If you do need to check balance assertions generated from CSV right away, pipe into another hledger: $ hledger -f file.csv print | hledger -f- print Deduplicating, importing - When you download a CSV file periodically, eg to get your latest bank - transactions, the new file may overlap with the old one, containing + When you download a CSV file periodically, eg to get your latest bank + transactions, the new file may overlap with the old one, containing some of the same records. The import command will (a) detect the new transactions, and (b) append just those transactions to your main journal. It is idempotent, so you - don't have to remember how many times you ran it or with which version - of the CSV. (It keeps state in a hidden .latest.FILE.csv file.) This + don't have to remember how many times you ran it or with which version + of the CSV. (It keeps state in a hidden .latest.FILE.csv file.) This is the easiest way to import CSV data. Eg: # download the latest CSV files, then run this command. # Note, no -f flags needed here. $ hledger import *.csv [--dry] - This method works for most CSV files. (Where records have a stable + This method works for most CSV files. (Where records have a stable chronological order, and new records appear only at the new end.) - A number of other tools and workflows, hledger-specific and otherwise, + A number of other tools and workflows, hledger-specific and otherwise, exist for converting, deduplicating, classifying and managing CSV data. See: @@ -6073,13 +6126,13 @@ CSV FORMAT a. If both fields are unsigned: Assign to amountN-in and amountN-out. This sets posting N's amount - to whichever of these has a non-zero value, and negates the "-out" + to whichever of these has a non-zero value, and negates the "-out" value. b. If either field is signed (can contain a minus sign): - Use a conditional rule to flip the sign (of non-empty values). - Since hledger always negates amountN-out, if it was already nega- - tive, we must undo that by negating once more (but only if the + Use a conditional rule to flip the sign (of non-empty values). + Since hledger always negates amountN-out, if it was already nega- + tive, we must undo that by negating once more (but only if the field is non-empty): fields date, description, amount1-in, amount1-out @@ -6087,8 +6140,8 @@ CSV FORMAT amount1-out -%amount1-out c. If both fields, or neither field, can contain a non-zero value: - hledger normally expects exactly one of the fields to have a non- - zero value. Eg, the amountN-in/amountN-out rules would reject + hledger normally expects exactly one of the fields to have a non- + zero value. Eg, the amountN-in/amountN-out rules would reject value pairs like these: "", "" @@ -6096,7 +6149,7 @@ CSV FORMAT "1", "none" So, use smarter conditional rules to set the amount from the appro- - priate field. Eg, these rules would make it use only the value + priate field. Eg, these rules would make it use only the value containing non-zero digits, handling the above: fields date, description, in, out @@ -6105,7 +6158,7 @@ CSV FORMAT if %out [1-9] amount1 %out - 3. If you are stuck with hledger <1.17, or you want posting 2's amount + 3. If you are stuck with hledger <1.17, or you want posting 2's amount converted to cost: Assign to amount (or to amount-in and amount-out). (The old numberless syntax, which sets amount1 and amount2.) @@ -6115,15 +6168,15 @@ CSV FORMAT ance assignment. (Old syntax: balance, equivalent to balance1.) o If hledger guesses the wrong default account name: - When setting the amount via balance assertion, hledger may guess - the wrong default account name. So, set the account name explic- + When setting the amount via balance assertion, hledger may guess + the wrong default account name. So, set the account name explic- itly, eg: fields date, description, balance1 account1 assets:checking Amount signs - There is some special handling for amount signs, to simplify parsing + There is some special handling for amount signs, to simplify parsing and sign-flipping: o If an amount value begins with a plus sign: @@ -6132,17 +6185,17 @@ CSV FORMAT o If an amount value is parenthesised: it will be de-parenthesised and sign-flipped: (AMT) becomes -AMT - o If an amount value has two minus signs (or two sets of parentheses, + o If an amount value has two minus signs (or two sets of parentheses, or a minus sign and parentheses): they cancel out and will be removed: --AMT or -(AMT) becomes AMT - o If an amount value contains just a sign (or just a set of parenthe- + o If an amount value contains just a sign (or just a set of parenthe- ses): - that is removed, making it an empty value. "+" or "-" or "()" becomes + that is removed, making it an empty value. "+" or "-" or "()" becomes "". Setting currency/commodity - If the currency/commodity symbol is included in the CSV's amount + If the currency/commodity symbol is included in the CSV's amount field(s): 2020-01-01,foo,$123.00 @@ -6161,7 +6214,7 @@ CSV FORMAT 2020-01-01,foo,USD,123.00 You can assign that to the currency pseudo-field, which has the special - effect of prepending itself to every amount in the transaction (on the + effect of prepending itself to every amount in the transaction (on the left, with no separating space): fields date,description,currency,amount @@ -6170,7 +6223,7 @@ CSV FORMAT expenses:unknown USD123.00 income:unknown USD-123.00 - Or, you can use a field assignment to construct the amount yourself, + Or, you can use a field assignment to construct the amount yourself, with more control. Eg to put the symbol on the right, and separated by a space: @@ -6181,7 +6234,7 @@ CSV FORMAT expenses:unknown 123.00 USD income:unknown -123.00 USD - Note we used a temporary field name (cur) that is not currency - that + Note we used a temporary field name (cur) that is not currency - that would trigger the prepending effect, which we don't want here. Amount decimal places @@ -6189,13 +6242,13 @@ CSV FORMAT amount1 influence commodity display styles, such as the number of deci- mal places displayed in reports. - The original amounts as written in the CSV file do not affect display + The original amounts as written in the CSV file do not affect display style (because we don't yet reliably know their commodity). Referencing other fields - In field assignments, you can interpolate only CSV fields, not hledger - fields. In the example below, there's both a CSV field and a hledger - field named amount1, but %amount1 always means the CSV field, not the + In field assignments, you can interpolate only CSV fields, not hledger + fields. In the example below, there's both a CSV field and a hledger + field named amount1, but %amount1 always means the CSV field, not the hledger field: # Name the third CSV field "amount1" @@ -6207,7 +6260,7 @@ CSV FORMAT # Set comment to the CSV amount1 (not the amount1 assigned above) comment %amount1 - Here, since there's no CSV amount1 field, %amount1 will produce a lit- + Here, since there's no CSV amount1 field, %amount1 will produce a lit- eral "amount1": fields date,description,csvamount @@ -6215,7 +6268,7 @@ CSV FORMAT # Can't interpolate amount1 here comment %amount1 - When there are multiple field assignments to the same hledger field, + When there are multiple field assignments to the same hledger field, only the last one takes effect. Here, comment's value will be be B, or C if "something" is matched, but never A: @@ -6225,14 +6278,14 @@ CSV FORMAT comment C How CSV rules are evaluated - Here's how to think of CSV rules being evaluated (if you really need + Here's how to think of CSV rules being evaluated (if you really need to). First, - o include - all includes are inlined, from top to bottom, depth first. - (At each include point the file is inlined and scanned for further + o include - all includes are inlined, from top to bottom, depth first. + (At each include point the file is inlined and scanned for further includes, recursively, before proceeding.) - Then "global" rules are evaluated, top to bottom. If a rule is + Then "global" rules are evaluated, top to bottom. If a rule is repeated, the last one wins: o skip (at top level) @@ -6246,33 +6299,33 @@ CSV FORMAT Then for each CSV record in turn: - o test all if blocks. If any of them contain a end rule, skip all + o test all if blocks. If any of them contain a end rule, skip all remaining CSV records. Otherwise if any of them contain a skip rule, - skip that many CSV records. If there are multiple matched skip + skip that many CSV records. If there are multiple matched skip rules, the first one wins. - o collect all field assignments at top level and in matched if blocks. - When there are multiple assignments for a field, keep only the last + o collect all field assignments at top level and in matched if blocks. + When there are multiple assignments for a field, keep only the last one. - o compute a value for each hledger field - either the one that was - assigned to it (and interpolate the %CSVFIELDNAME references), or a + o compute a value for each hledger field - either the one that was + assigned to it (and interpolate the %CSVFIELDNAME references), or a default o generate a synthetic hledger transaction from these values. - This is all part of the CSV reader, one of several readers hledger can - use to parse input files. When all files have been read successfully, - the transactions are passed as input to whichever hledger command the + This is all part of the CSV reader, one of several readers hledger can + use to parse input files. When all files have been read successfully, + the transactions are passed as input to whichever hledger command the user specified. TIMECLOCK FORMAT The time logging format of timeclock.el, as read by hledger. - hledger can read time logs in timeclock format. As with Ledger, these + hledger can read time logs in timeclock format. As with Ledger, these are (a subset of) timeclock.el's format, containing clock-in and clock- - out entries as in the example below. The date is a simple date. The - time format is HH:MM[:SS][+-ZZZZ]. Seconds and timezone are optional. + out entries as in the example below. The date is a simple date. The + time format is HH:MM[:SS][+-ZZZZ]. Seconds and timezone are optional. The timezone, if present, must be four digits and is ignored (currently the time is always interpreted as a local time). @@ -6281,9 +6334,9 @@ TIMECLOCK FORMAT i 2015/03/31 22:21:45 another account o 2015/04/01 02:00:34 - hledger treats each clock-in/clock-out pair as a transaction posting - some number of hours to an account. Or if the session spans more than - one day, it is split into several transactions, one for each day. For + hledger treats each clock-in/clock-out pair as a transaction posting + some number of hours to an account. Or if the session spans more than + one day, it is split into several transactions, one for each day. For the above time log, hledger print generates these journal entries: $ hledger -f t.timeclock print @@ -6304,69 +6357,69 @@ TIMECLOCK FORMAT To generate time logs, ie to clock in and clock out, you could: - o use emacs and the built-in timeclock.el, or the extended timeclock- + o use emacs and the built-in timeclock.el, or the extended timeclock- x.el and perhaps the extras in ledgerutils.el o at the command line, use these bash aliases: shell alias ti="echo - i `date '+%Y-%m-%d %H:%M:%S'` \$* >>$TIMELOG" alias to="echo o + i `date '+%Y-%m-%d %H:%M:%S'` \$* >>$TIMELOG" alias to="echo o `date '+%Y-%m-%d %H:%M:%S'` >>$TIMELOG" o or use the old ti and to scripts in the ledger 2.x repository. These - rely on a "timeclock" executable which I think is just the ledger 2 + rely on a "timeclock" executable which I think is just the ledger 2 executable renamed. TIMEDOT FORMAT hledger's human-friendly time logging format. - Timedot is a plain text format for logging dated, categorised quanti- - ties (of time, usually), supported by hledger. It is convenient for - approximate and retroactive time logging, eg when the real-time clock- - in/out required with a timeclock file is too precise or too interrup- - tive. It can be formatted like a bar chart, making clear at a glance + Timedot is a plain text format for logging dated, categorised quanti- + ties (of time, usually), supported by hledger. It is convenient for + approximate and retroactive time logging, eg when the real-time clock- + in/out required with a timeclock file is too precise or too interrup- + tive. It can be formatted like a bar chart, making clear at a glance where time was spent. - Though called "timedot", this format is read by hledger as commodity- - less quantities, so it could be used to represent dated quantities + Though called "timedot", this format is read by hledger as commodity- + less quantities, so it could be used to represent dated quantities other than time. In the docs below we'll assume it's time. - A timedot file contains a series of day entries. A day entry begins - with a non-indented hledger-style simple date (Y-M-D, Y/M/D, Y.M.D..) - Any additional text on the same line is used as a transaction descrip- + A timedot file contains a series of day entries. A day entry begins + with a non-indented hledger-style simple date (Y-M-D, Y/M/D, Y.M.D..) + Any additional text on the same line is used as a transaction descrip- tion for this day. This is followed by optionally-indented timelog items for that day, one - per line. Each timelog item is a note, usually a - hledger:style:account:name representing a time category, followed by - two or more spaces, and a quantity. Each timelog item generates a + per line. Each timelog item is a note, usually a + hledger:style:account:name representing a time category, followed by + two or more spaces, and a quantity. Each timelog item generates a hledger transaction. Quantities can be written as: - o dots: a sequence of dots (.) representing quarter hours. Spaces may + o dots: a sequence of dots (.) representing quarter hours. Spaces may optionally be used for grouping. Eg: .... .. o an integral or decimal number, representing hours. Eg: 1.5 - o an integral or decimal number immediately followed by a unit symbol - s, m, h, d, w, mo, or y, representing seconds, minutes, hours, days + o an integral or decimal number immediately followed by a unit symbol + s, m, h, d, w, mo, or y, representing seconds, minutes, hours, days weeks, months or years respectively. Eg: 90m. The following equiva- - lencies are assumed, currently: 1m = 60s, 1h = 60m, 1d = 24h, 1w = + lencies are assumed, currently: 1m = 60s, 1h = 60m, 1d = 24h, 1w = 7d, 1mo = 30d, 1y=365d. - There is some flexibility allowing notes and todo lists to be kept + There is some flexibility allowing notes and todo lists to be kept right in the time log, if needed: o Blank lines and lines beginning with # or ; are ignored. o Lines not ending with a double-space and quantity are parsed as items - taking no time, which will not appear in balance reports by default. + taking no time, which will not appear in balance reports by default. (Add -E to see them.) - o Org mode headlines (lines beginning with one or more * followed by a - space) can be used as date lines or timelog items (the stars are - ignored). Also all org headlines before the first date line are - ignored. This means org users can manage their timelog as an org - outline (eg using org-mode/orgstruct-mode in Emacs), for organisa- + o Org mode headlines (lines beginning with one or more * followed by a + space) can be used as date lines or timelog items (the stars are + ignored). Also all org headlines before the first date line are + ignored. This means org users can manage their timelog as an org + outline (eg using org-mode/orgstruct-mode in Emacs), for organisa- tion, faster navigation, controlling visibility etc. Examples: @@ -6431,7 +6484,7 @@ TIMEDOT FORMAT ------------++---------------------------------------- || 7.75 2.25 8.00 - I prefer to use period for separating account components. We can make + I prefer to use period for separating account components. We can make this work with an account alias: 2016/2/4 @@ -6448,9 +6501,9 @@ TIMEDOT FORMAT Here is a sample.timedot. COMMON TASKS - Here are some quick examples of how to do some basic tasks with - hledger. For more details, see the reference section below, the - hledger_journal(5) manual, or the more extensive docs at + Here are some quick examples of how to do some basic tasks with + hledger. For more details, see the reference section below, the + hledger_journal(5) manual, or the more extensive docs at https://hledger.org. Getting help @@ -6466,26 +6519,26 @@ COMMON TASKS https://hledger.org#help-feedback Constructing command lines - hledger has an extensive and powerful command line interface. We + hledger has an extensive and powerful command line interface. We strive to keep it simple and ergonomic, but you may run into one of the confusing real world details described in OPTIONS, below. If that hap- pens, here are some tips that may 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 all options there) (hledger CMD OPTS ARGS) - o running add-on executables directly simplifies command line parsing + o running add-on executables directly simplifies command line parsing (hledger-ui OPTS ARGS) o enclose "problematic" args 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 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 @@ -6493,9 +6546,9 @@ 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. + You can override this by setting the LEDGER_FILE environment variable. 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 + and to start a new file each year. So you could do something like this: $ mkdir ~/finance @@ -6519,20 +6572,20 @@ COMMON TASKS Market prices : 0 () 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 - two accounts, like your checking account or cash wallet; and pick a - recent starting date, like today or the start of the week. You can + 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 + recent starting date, like today or the start of the week. You can always 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: 2020-01-01 * opening balances @@ -6542,19 +6595,19 @@ 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 @@ -6591,18 +6644,18 @@ COMMON TASKS Starting the next transaction (. or ctrl-D/ctrl-C to quit) Date [2020-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' 2020.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: 2020/1/10 * gift received @@ -6618,22 +6671,22 @@ 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 - already-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 + already-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: @@ -6643,26 +6696,26 @@ 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 - reported by hledger reg checking -C. This will be easier if you - generally record transaction dates quite similar to your bank's + action history and running balance from your bank with the one + reported by hledger reg checking -C. This will be easier if you + generally record transaction dates quite similar to your bank's clearing dates. 3. Repeat for other asset/liability accounts. - Tip: instead of the register command, use hledger-ui to see a live- + Tip: instead of the register command, use hledger-ui to see a live- updating register while you edit the journal: hledger-ui --watch --reg- ister 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 2020-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' 2020.journal @@ -6734,7 +6787,7 @@ 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 --flat -2 @@ -6744,7 +6797,7 @@ 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 --flat -2 @@ -6811,15 +6864,15 @@ COMMON TASKS 2020-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. LIMITATIONS - The need to precede add-on command options with -- when invoked from + The need to precede add-on command options with -- when invoked from hledger is awkward. When input data contains non-ascii characters, a suitable system locale @@ -6835,36 +6888,36 @@ LIMITATIONS In a Cygwin/MSYS/Mintty window, the tab key is not supported in hledger add. - Not all of Ledger's journal file syntax is supported. See file format + Not all of Ledger's journal file syntax is supported. See file format differences. - On large data files, hledger is slower and uses more memory than + On large data files, hledger is slower and uses more memory than Ledger. TROUBLESHOOTING - Here are some issues you might encounter when you run hledger (and - remember you can also seek help from the IRC channel, mail list or bug + Here are some issues you might encounter when you run hledger (and + remember you can also seek help from the IRC channel, mail list or bug tracker): Successfully installed, but "No command 'hledger' found" stack and cabal install binaries into a special directory, which should - be added to your PATH environment variable. Eg on unix-like systems, + be added to your PATH environment variable. Eg on unix-like systems, that is ~/.local/bin and ~/.cabal/bin respectively. I set a custom LEDGER_FILE, but hledger is still using the default file - LEDGER_FILE should be a real environment variable, not just a shell - variable. The command env | grep LEDGER_FILE should show it. You may + LEDGER_FILE should be a real environment variable, not just a shell + variable. The command env | grep LEDGER_FILE should show it. You may need to use export. Here's an explanation. - Getting errors like "Illegal byte sequence" or "Invalid or incomplete - multibyte or wide character" or "commitAndReleaseBuffer: invalid argu- + Getting errors like "Illegal byte sequence" or "Invalid or incomplete + multibyte or wide character" or "commitAndReleaseBuffer: invalid argu- ment (invalid character)" Programs compiled with GHC (hledger, haskell build tools, etc.) need to have a UTF-8-aware locale configured in the environment, otherwise they - will fail with these kinds of errors when they encounter non-ascii + will fail with these kinds of errors when they encounter non-ascii characters. - To fix it, set the LANG environment variable to some locale which sup- + To fix it, set the LANG environment variable to some locale which sup- ports UTF-8. The locale you choose must be installed on your system. Here's an example of setting LANG temporarily, on Ubuntu GNU/Linux: @@ -6879,8 +6932,8 @@ TROUBLESHOOTING POSIX $ LANG=en_US.utf8 hledger -f my.journal print # ensure it is used for this command - If available, C.UTF-8 will also work. If your preferred locale isn't - listed by locale -a, you might need to install it. Eg on + If available, C.UTF-8 will also work. If your preferred locale isn't + listed by locale -a, you might need to install it. Eg on Ubuntu/Debian: $ apt-get install language-pack-fr @@ -6900,8 +6953,8 @@ TROUBLESHOOTING $ echo "export LANG=en_US.utf8" >>~/.bash_profile $ bash --login - Exact spelling and capitalisation may be important. Note the differ- - ence on MacOS (UTF-8, not utf8). Some platforms (eg ubuntu) allow + Exact spelling and capitalisation may be important. Note the differ- + ence on MacOS (UTF-8, not utf8). Some platforms (eg ubuntu) allow variant spellings, but others (eg macos) require it to be exact: $ locale -a | grep -iE en_us.*utf @@ -6911,7 +6964,7 @@ TROUBLESHOOTING REPORTING BUGS - Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel + Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel or hledger mail list)