From 0b15d5771a5d0a5b6b484cbef5b0abbb08e0833b Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Tue, 18 May 2021 10:35:43 -1000 Subject: [PATCH] ;update manuals --- hledger/hledger.1 | 239 ++++--- hledger/hledger.info | 1067 ++++++++++++++++--------------- hledger/hledger.txt | 1413 ++++++++++++++++++++++-------------------- 3 files changed, 1471 insertions(+), 1248 deletions(-) diff --git a/hledger/hledger.1 b/hledger/hledger.1 index b5202d5f5..ad2183e21 100644 --- a/hledger/hledger.1 +++ b/hledger/hledger.1 @@ -656,9 +656,8 @@ Are all accounts posted to, declared with an \f[C]account\f[R] directive Are all commodities declared with a \f[C]commodity\f[R] directive ? (Commodity error checking) .PP -See also: https://hledger.org/checking-for-errors.html -.PP -\f[I]experimental.\f[R] +You can also use the check command to run these and some additional +checks. .SH TIME PERIODS .SS Smart dates .PP @@ -830,12 +829,35 @@ T} .SS Report intervals .PP A report interval can be specified so that commands like register, -balance and activity will divide their reports into multiple subperiods. -The basic intervals can be selected with one of \f[C]-D/--daily\f[R], -\f[C]-W/--weekly\f[R], \f[C]-M/--monthly\f[R], \f[C]-Q/--quarterly\f[R], -or \f[C]-Y/--yearly\f[R]. -More complex intervals may be specified with a period expression. -Report intervals can not be specified with a query. +balance and activity become multi-period, showing each subperiod as a +separate row or column. +.PP +The following \[dq]standard\[dq] report intervals can be enabled by +using their corresponding flag: +.PP +\f[C]-D/--daily\f[R], \f[C]-W/--weekly\f[R], \f[C]-M/--monthly\f[R], +\f[C]-Q/--quarterly\f[R], \f[C]-Y/--yearly\f[R]. +.PP +These standard intervals always start on natural interval boundaries: eg +\f[C]--weekly\f[R] starts on mondays, \f[C]--monthly\f[R] starts on the +first of the month, \f[C]--yearly\f[R] always starts on January 1st, +etc. +.PP +Certain more complex intervals, and more flexible boundary dates, can be +specified by \f[C]-p/--period\f[R]. +These are described in period expressions, below. +.PP +Report intervals can only be specified by the flags above, and not by +query arguments, currently. +.PP +Report intervals have another effect: multi-period reports are always +expanded to fill a whole number of subperiods. +So if you use a report interval (other than \f[C]--daily\f[R]), and you +have specified a start or end date, you may notice those dates being +overridden (ie, the report starts earlier than your requested start +date, or ends later than your requested end date). +This is done to ensure \[dq]full\[dq] first and last subperiods, so that +all subperiods\[aq] numbers are comparable. .SS Period expressions .PP The \f[C]-p/--period\f[R] option accepts period expressions, a shorthand @@ -2031,6 +2053,12 @@ $ hledger print -o foo.txt $ hledger print -o - # write to stdout (the default) \f[R] .fi +.PP +hledger can optionally produce debug output (if enabled with +\f[C]--debug=N\f[R]); this goes to stderr, and is not affected by +\f[C]-o/--output-file\f[R]. +If you need to capture it, use shell redirects, eg: +\f[C]hledger bal --debug=3 >file 2>&1\f[R]. .SS Output format .PP Some commands (print, register, the balance commands) offer a choice of @@ -3612,7 +3640,8 @@ These checks can be run only by giving their names as arguments to They are more specialised and not desirable for everyone, therefore optional: .IP \[bu] 2 -\f[B]ordereddates\f[R] - transactions are ordered by date in each file +\f[B]ordereddates\f[R] - transactions are ordered by date within each +file .IP \[bu] 2 \f[B]payees\f[R] - all payees used by transactions have been declared .IP \[bu] 2 @@ -5440,23 +5469,15 @@ Amounts have a number (the \[dq]quantity\[dq]): \f[R] .fi .PP -\&..and usually a currency or commodity name (the \[dq]commodity\[dq]). -This is a symbol, word, or phrase, to the left or right of the quantity, -with or without a separating space: +\&..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 space: .IP .nf \f[C] $1 4000 AAPL -\f[R] -.fi -.PP -If the commodity name contains spaces, numbers, or punctuation, it must -be enclosed in double quotes: -.IP -.nf -\f[C] -3 \[dq]no. 42 green apples\[dq] +3 \[dq]green apples\[dq] \f[R] .fi .PP @@ -5526,14 +5547,49 @@ Are these digit group marks or decimal marks ? .PP If you don\[aq]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, especially if your data -contains digit group marks, we recommend you explicitly declare the -decimal mark (and optionally a digit group mark), for each commodity, -using \f[C]commodity\f[R] directives (described below): +To prevent confusion and undetected typos, we recommend adding +\f[C]commodity\f[R] 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. +.SS Commodity +.PP +Amounts in hledger have both a \[dq]quantity\[dq], which is a signed +decimal number, and a \[dq]commodity\[dq], which is a currency symbol, +stock ticker, or any word or phrase describing something you are +tracking. +.PP +If the commodity name contains non-letters (spaces, numbers, or +punctuation), you must always write it inside double quotes +(\f[C]\[dq]green apples\[dq]\f[R], \f[C]\[dq]ABC123\[dq]\f[R]). +.PP +If you write just a bare number, that too will have a commodity, with +name \f[C]\[dq]\[dq]\f[R]; we call that the \[dq]no-symbol +commodity\[dq]. +.PP +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: +\f[C]1 USD, 2 EUR, 3.456 TSLA\f[R]. +In practice, you will only see multi-commodity amounts in hledger\[aq]s +output; you can\[aq]t write them directly in the journal file. +.PP +(If you are writing scripts or working with hledger\[aq]s internals, +these are the \f[C]Amount\f[R] and \f[C]MixedAmount\f[R] types.) +.SS Commodity directives +.PP +You can add \f[C]commodity\f[R] 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 +commodities. +Here\[aq]s a quick example: .IP .nf \f[C] -# number formats for $, EUR, INR and the no-symbol commodity: +# number format and display style for $, EUR, INR and the no-symbol commodity: commodity $1,000.00 commodity EUR 1.000,00 commodity INR 9,99,99,999.00 @@ -5541,19 +5597,15 @@ commodity 1 000 000.9455 \f[R] .fi .PP -Note, \f[C]commodity\f[R] directives declare both the number format for -parsing input, and the display style for showing output. -For the former, they are position-sensitive, affecting only following -amounts, so commodity directives should be at the top of your journal -file. -This is discussed more on #793. -.PP .SS Commodity display style .PP For the amounts in each commodity, hledger chooses a consistent display style to use in most reports. -(Except for price amounts, which are always displayed as written). -The display style is inferred as follows. +(Exceptions: price amounts, and all amounts displayed by the +\f[C]print\f[R] command, are displayed with all of their decimal digits +visible.) +.PP +A commodity\[aq]s display style is inferred as follows. .PP First, if a default commodity is declared with \f[C]D\f[R], this commodity and its style is applied to any no-symbol amounts in the @@ -6206,47 +6258,54 @@ payee Whole Foods .fi .SS Declaring commodities .PP -The \f[C]commodity\f[R] directive has several functions: +You can use \f[C]commodity\f[R] directives to declare your commodities. +In fact the \f[C]commodity\f[R] directive performs several functions at +once: .IP "1." 3 It declares commodities which may be used in the journal. -This is currently not enforced, but can serve as documentation. +This can optionally be enforced, providing useful error checking. +(Cf Commodity error checking) .IP "2." 3 -It declares what 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 \f[C]1,000\f[R] and -\f[C]1.000\f[R] as 1). +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 \f[C]1,000\f[R] and +\f[C]1.000\f[R] as 1. +(Cf Amounts) .IP "3." 3 -It declares a commodity\[aq]s display style in output - decimal and -digit group marks, number of decimal places, symbol placement etc. +It declares how to render the commodity\[aq]s amounts when displaying +output - the decimal mark, any digit group marks, the number of decimal +places, symbol placement and so on. +(Cf Commodity display style) .PP -You are likely to run into one of the problems solved by commodity -directives, sooner or later, so it\[aq]s a good idea to just always use -them to declare your commodities. +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. .PP -A commodity directive is just the word \f[C]commodity\f[R] followed by -an amount. -It may be written on a single line, like this: +Generally you should put them at the top of your journal file (since for +function 2, they affect only following amounts, cf #793). +.PP +A commodity directive is just the word \f[C]commodity\f[R] followed by a +sample amount, like this: .IP .nf \f[C] -; commodity EXAMPLEAMOUNT +;commodity SAMPLEAMOUNT -; display AAAA amounts with the symbol on the right, space-separated, -; using period as decimal point, with four decimal places, and -; separating thousands with comma. -commodity 1,000.0000 AAAA +commodity $1000.00 +commodity 1,000.0000 AAAA ; optional same-line comment \f[R] .fi .PP -or on multiple lines, using the \[dq]format\[dq] subdirective. -(In this case the commodity symbol appears twice and should be the same -in both places.): +It may also be written on multiple lines, and use the \f[C]format\f[R] +subdirective, as in Ledger. +Note in this case the commodity symbol appears twice; it must be the +same in both places: .IP .nf \f[C] -; commodity SYMBOL -; format EXAMPLEAMOUNT +;commodity SYMBOL +; format SAMPLEAMOUNT ; display indian rupees with currency name on the left, ; thousands, lakhs and crores comma-separated, @@ -6256,10 +6315,25 @@ commodity INR \f[R] .fi .PP -The quantity of the amount does not matter; only the format is +Remember that if the commodity symbol contains spaces, numbers, or +punctuation, it must be enclosed in double quotes (cf Commodity). +.PP +The amount\[aq]s quantity does not matter; only the format is significant. -The number must include a decimal mark: either a period or a comma, -followed by 0 or more decimal digits. +It must include a decimal mark - either a period or a comma - followed +by 0 or more decimal digits. +.PP +A few more examples: +.IP +.nf +\f[C] +# number formats for $, EUR, INR and the no-symbol commodity: +commodity $1,000.00 +commodity EUR 1.000,00 +commodity INR 9,99,99,999.0 +commodity 1 000 000. +\f[R] +.fi .PP Note hledger normally uses banker\[aq]s rounding, so 0.5 displayed with zero decimal digits is \[dq]0\[dq]. @@ -6273,19 +6347,20 @@ This works similarly to account error checking, see the notes there for more details. .SS Default commodity .PP -The \f[C]D\f[R] directive sets a default commodity, to be used for -amounts without a commodity symbol (ie, plain numbers). -This commodity will be applied to all subsequent commodity-less amounts, -or until the next \f[C]D\f[R] directive. -(Note, this is different from Ledger\[aq]s \f[C]D\f[R].) +The \f[C]D\f[R] directive sets a default commodity, to be used for any +subsequent commodityless amounts (ie, plain numbers) seen while parsing +the journal. +This effect lasts until the next \f[C]D\f[R] directive, or the end of +the journal. .PP For compatibility/historical reasons, \f[C]D\f[R] also acts like a -\f[C]commodity\f[R] directive, setting the commodity\[aq]s display style -(for output) and decimal mark (for parsing input). -As with \f[C]commodity\f[R], the amount must always be written with a -decimal mark (period or comma). -If both directives are used, \f[C]commodity\f[R]\[aq]s style takes -precedence. +\f[C]commodity\f[R] directive (setting the commodity\[aq]s decimal mark +for parsing and display style for output). +.PP +As with \f[C]commodity\f[R], the amount must include a decimal mark +(either period or comma). +If both \f[C]commodity\f[R] and \f[C]D\f[R] directives are used for the +same commodity, the \f[C]commodity\f[R] style takes precedence. .PP The syntax is \f[C]D AMOUNT\f[R]. Eg: @@ -6494,7 +6569,7 @@ using the following rules: tab(@); l l. T{ -If name matches regular expression: +If name matches this regular expression: T}@T{ account type is: T} @@ -6528,10 +6603,10 @@ T} .PP .TS tab(@); -lw(56.9n) lw(13.1n). +lw(57.6n) lw(12.4n). T{ -If account type is \f[C]Asset\f[R] and name does not contain regular -expression: +If account type is \f[C]Asset\f[R] and name does not contain this +regular expression: T}@T{ account type is: T} @@ -7789,13 +7864,13 @@ REGEX \f[R] .fi .PP -REGEX is a case-insensitive regular expression which tries to match +REGEX is a case-insensitive regular expression that tries to match anywhere within the CSV record. It is a POSIX ERE (extended regular expression) that also supports GNU word boundaries (\f[C]\[rs]b\f[R], \f[C]\[rs]B\f[R], \f[C]\[rs]<\f[R], \f[C]\[rs]>\f[R]), and nothing else. -If you have trouble, be sure to check our -https://hledger.org/hledger.html#regular-expressions doc. +If you have trouble, be sure to check our doc: +https://hledger.org/hledger.html#regular-expressions .PP Important note: the record that is matched is not the original record, but a synthetic one, with any enclosing double quotes (but not enclosing diff --git a/hledger/hledger.info b/hledger/hledger.info index ae9264e81..5372b07cd 100644 --- a/hledger/hledger.info +++ b/hledger/hledger.info @@ -645,9 +645,8 @@ without a lot of declarations: * Are all commodities declared with a `commodity' directive ? (Commodity error checking) - See also: https://hledger.org/checking-for-errors.html - - _experimental._ + You can also use the check command to run these and some additional +checks.  File: hledger.info, Node: TIME PERIODS, Next: DEPTH, Prev: DATA FILES, Up: Top @@ -750,11 +749,33 @@ File: hledger.info, Node: Report intervals, Next: Period expressions, Prev: R ==================== A report interval can be specified so that commands like register, -balance and activity will divide their reports into multiple subperiods. -The basic intervals can be selected with one of `-D/--daily', -`-W/--weekly', `-M/--monthly', `-Q/--quarterly', or `-Y/--yearly'. More -complex intervals may be specified with a period expression. Report -intervals can not be specified with a query. +balance and activity become multi-period, showing each subperiod as a +separate row or column. + + The following "standard" report intervals can be enabled by using +their corresponding flag: + + `-D/--daily', `-W/--weekly', `-M/--monthly', `-Q/--quarterly', +`-Y/--yearly'. + + These standard intervals always start on natural interval +boundaries: eg `--weekly' starts on mondays, `--monthly' starts on the +first of the month, `--yearly' always starts on January 1st, etc. + + Certain more complex intervals, and more flexible boundary dates, +can be specified by `-p/--period'. These are described in period +expressions, below. + + Report intervals can only be specified by the flags above, and not by +query arguments, currently. + + Report intervals have another effect: multi-period reports are always +expanded to fill a whole number of subperiods. So if you use a report +interval (other than `--daily'), and you have specified a start or end +date, you may notice those dates being overridden (ie, the report +starts earlier than your requested start date, or ends later than your +requested end date). This is done to ensure "full" first and last +subperiods, so that all subperiods' numbers are comparable.  File: hledger.info, Node: Period expressions, Prev: Report intervals, Up: TIME PERIODS @@ -1624,6 +1645,11 @@ without needing the shell. Eg: $ hledger print -o foo.txt $ hledger print -o - # write to stdout (the default) + hledger can optionally produce debug output (if enabled with +`--debug=N'); this goes to stderr, and is not affected by +`-o/--output-file'. If you need to capture it, use shell redirects, eg: +`hledger bal --debug=3 >file 2>&1'. +  File: hledger.info, Node: Output format, Prev: Output destination, Up: OUTPUT @@ -3160,7 +3186,7 @@ These checks can be run only by giving their names as arguments to `check'. They are more specialised and not desirable for everyone, therefore optional: - * *ordereddates* - transactions are ordered by date in each file + * *ordereddates* - transactions are ordered by date within each file * *payees* - all payees used by transactions have been declared @@ -4919,19 +4945,14 @@ formats. Here are some examples. Amounts have a number (the "quantity"): 1 - ..and usually a currency or commodity name (the "commodity"). This -is a symbol, word, or phrase, to the left or right of the quantity, -with or without a separating space: + ..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 space: $1 4000 AAPL - - If the commodity name contains spaces, numbers, or punctuation, it -must be enclosed in double quotes: - - -3 "no. 42 green apples" +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 @@ -4957,11 +4978,13 @@ EUR 1E3 * Menu: * Decimal marks digit group marks:: +* Commodity:: +* Commodity directives:: * Commodity display style:: * Rounding::  -File: hledger.info, Node: Decimal marks digit group marks, Next: Commodity display style, Up: Amounts +File: hledger.info, Node: Decimal marks digit group marks, Next: Commodity, Up: Amounts 12.9.1 Decimal marks, digit group marks --------------------------------------- @@ -4991,33 +5014,68 @@ mark is ambiguous. Are these digit group marks or decimal marks ? 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, especially if your data contains digit group marks, we -recommend you explicitly declare the decimal mark (and optionally a -digit group mark), for each commodity, using `commodity' directives -(described below): +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. + + +File: hledger.info, Node: Commodity, Next: Commodity directives, Prev: Decimal marks digit group marks, Up: Amounts + +12.9.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 +any word or phrase describing something you are tracking. + + If the commodity name contains non-letters (spaces, numbers, or +punctuation), 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 +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 +hledger's output; you can't write them directly in the journal file. + + (If you are writing scripts or working with hledger's internals, +these are the `Amount' and `MixedAmount' types.) + + +File: hledger.info, Node: Commodity directives, Next: Commodity display style, Prev: Commodity, Up: Amounts + +12.9.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 +above) and display (see below). These are optional, but recommended. +They are described in more detail in JOURNAL FORMAT -> Declaring +commodities. Here's a quick example: -# number formats for $, EUR, INR and the no-symbol commodity: +# number format and display style for $, EUR, INR and the no-symbol commodity: commodity $1,000.00 commodity EUR 1.000,00 commodity INR 9,99,99,999.00 commodity 1 000 000.9455 - Note, `commodity' directives declare both the number format for -parsing input, and the display style for showing output. For the former, -they are position-sensitive, affecting only following amounts, so -commodity directives should be at the top of your journal file. This is -discussed more on #793. -  -File: hledger.info, Node: Commodity display style, Next: Rounding, Prev: Decimal marks digit group marks, Up: Amounts +File: hledger.info, Node: Commodity display style, Next: Rounding, Prev: Commodity directives, Up: Amounts -12.9.2 Commodity display style +12.9.4 Commodity display style ------------------------------ For the amounts in each commodity, hledger chooses a consistent display -style to use in most reports. (Except for price amounts, which are -always displayed as written). The display style is inferred as follows. +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 its style is applied to any no-symbol amounts in the journal. @@ -5069,7 +5127,7 @@ commodity 1 000.  File: hledger.info, Node: Rounding, Prev: Commodity display style, Up: Amounts -12.9.3 Rounding +12.9.5 Rounding --------------- Amounts are stored internally as decimal numbers with up to 255 decimal @@ -5610,42 +5668,47 @@ File: hledger.info, Node: Declaring commodities, Next: Default commodity, Pre 12.20 Declaring commodities =========================== -The `commodity' directive has several functions: +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 is - currently not enforced, but can serve as documentation. + 1. It declares commodities which may be used in the journal. This can + optionally be enforced, providing useful error checking. (Cf + Commodity error checking) - 2. It declares what decimal mark character (period or comma) to + 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). + number formats in your data. Without this, hledger will parse both + `1,000' and `1.000' as 1. (Cf Amounts) - 3. It declares a commodity's display style in output - decimal and - digit group marks, number of decimal places, symbol placement etc. + 3. It declares how to render the commodity's amounts when displaying + output - the decimal mark, any digit group marks, the number of + decimal places, symbol placement and so on. (Cf Commodity display + style) - You are likely to run into one of the problems solved by commodity -directives, sooner or later, so it's a good idea to just always use them -to declare your commodities. + 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. - A commodity directive is just the word `commodity' followed by an -amount. It may be written on a single line, like this: + 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 amount, like this: -; commodity EXAMPLEAMOUNT +;commodity SAMPLEAMOUNT -; display AAAA amounts with the symbol on the right, space-separated, -; using period as decimal point, with four decimal places, and -; separating thousands with comma. -commodity 1,000.0000 AAAA +commodity $1000.00 +commodity 1,000.0000 AAAA ; optional same-line comment - or on multiple lines, using the "format" subdirective. (In this case -the commodity symbol appears twice and should be the same in both -places.): + It may also be written on multiple lines, and use the `format' +subdirective, as in Ledger. Note in this case the commodity symbol +appears twice; it must be the same in both places: -; commodity SYMBOL -; format EXAMPLEAMOUNT +;commodity SYMBOL +; format SAMPLEAMOUNT ; display indian rupees with currency name on the left, ; thousands, lakhs and crores comma-separated, @@ -5653,9 +5716,21 @@ places.): commodity INR format INR 1,00,00,000.00 - The quantity of the amount does not matter; only the format is -significant. The number must include a decimal mark: either a period or -a comma, followed by 0 or more decimal digits. + 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 by 0 or more decimal digits. + + A few more examples: + + +# number formats for $, EUR, INR and the no-symbol commodity: +commodity $1,000.00 +commodity EUR 1.000,00 +commodity INR 9,99,99,999.0 +commodity 1 000 000. Note hledger normally uses banker's rounding, so 0.5 displayed with zero decimal digits is "0". (More at Commodity display style.) @@ -5681,16 +5756,18 @@ File: hledger.info, Node: Default commodity, Next: Declaring market prices, P 12.21 Default commodity ======================= -The `D' directive sets a default commodity, to be used for amounts -without a commodity symbol (ie, plain numbers). This commodity will be -applied to all subsequent commodity-less amounts, or until the next `D' -directive. (Note, this is different from Ledger's `D'.) +The `D' directive sets a default commodity, to be used for any +subsequent commodityless amounts (ie, plain numbers) seen while parsing +the journal. This effect lasts until the next `D' directive, or the end +of the journal. For compatibility/historical reasons, `D' also acts like a -`commodity' directive, setting the commodity's display style (for -output) and decimal mark (for parsing input). As with `commodity', the -amount must always be written with a decimal mark (period or comma). -If both directives are used, `commodity''s style takes precedence. +`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 same commodity, the `commodity' style takes precedence. The syntax is `D AMOUNT'. Eg: @@ -5914,19 +5991,19 @@ If you happen to use common english top-level account names, you may not need to declare account types, as they will be detected automatically using the following rules: -If name matches regular account type -expression: is: -------------------------------------------------- -`^assets?(:|$)' `Asset' -`^(debts?|liabilit(y|ies))(:|$)' `Liability' -`^equity(:|$)' `Equity' -`^(income|revenue)s?(:|$)' `Revenue' -`^expenses?(:|$)' `Expense' +If name matches this regular expression: account type + is: +--------------------------------------------------------- +`^assets?(:|$)' `Asset' +`^(debts?|liabilit(y|ies))(:|$)' `Liability' +`^equity(:|$)' `Equity' +`^(income|revenue)s?(:|$)' `Revenue' +`^expenses?(:|$)' `Expense' -If account type is `Asset' and name does not contain account type -regular expression: is: +If account type is `Asset' and name does not contain this account type +regular expression: is: -------------------------------------------------------------------------- -`(investment|receivable|:A/R|:fixed)' `Cash' +`(investment|receivable|:A/R|:fixed)' `Cash' Even so, explicit declarations may be a good idea, for clarity and predictability. @@ -7170,11 +7247,11 @@ Each MATCHER can be a record matcher, which looks like this: REGEX - REGEX is a case-insensitive regular expression which tries to match + REGEX is a case-insensitive regular expression that tries to match anywhere within the CSV record. It is a POSIX ERE (extended regular expression) that also supports GNU word boundaries (`\b', `\B', `\<', -`\>'), and nothing else. If you have trouble, be sure to check our -https://hledger.org/hledger.html#regular-expressions doc. +`\>'), and nothing else. If you have trouble, be sure to check our doc: +https://hledger.org/hledger.html#regular-expressions Important note: the record that is matched is not the original record, but a synthetic one, with any enclosing double quotes (but not @@ -8642,415 +8719,419 @@ Node: Multiple files17977 Ref: #multiple-files18119 Node: Strict mode18589 Ref: #strict-mode18704 -Node: TIME PERIODS19354 -Ref: #time-periods19471 -Node: Smart dates19569 -Ref: #smart-dates19695 -Node: Report start & end date20999 -Ref: #report-start-end-date21174 -Node: Report intervals22718 -Ref: #report-intervals22886 -Node: Period expressions23274 -Ref: #period-expressions23414 -Node: DEPTH27793 -Ref: #depth27893 -Node: QUERIES28224 -Ref: #queries28323 -Node: COSTING32275 -Ref: #costing32378 -Node: VALUATION32651 -Ref: #valuation32759 -Node: -V Value33482 -Ref: #v-value33606 -Node: -X Value in specified commodity33800 -Ref: #x-value-in-specified-commodity33993 -Node: Valuation date34142 -Ref: #valuation-date34304 -Node: Market prices34741 -Ref: #market-prices34922 -Node: --infer-market-price market prices from transactions36104 -Ref: #infer-market-price-market-prices-from-transactions36368 -Node: Valuation commodity37717 -Ref: #valuation-commodity37927 -Node: Simple valuation examples39152 -Ref: #simple-valuation-examples39348 -Node: --value Flexible valuation40010 -Ref: #value-flexible-valuation40212 -Node: More valuation examples41854 -Ref: #more-valuation-examples42055 -Node: Effect of valuation on reports44061 -Ref: #effect-of-valuation-on-reports44243 -Node: PIVOTING52140 -Ref: #pivoting52245 -Node: OUTPUT53924 -Ref: #output54026 -Node: Output destination54077 -Ref: #output-destination54210 -Node: Output format54635 -Ref: #output-format54758 -Node: COMMANDS56921 -Ref: #commands57033 -Node: accounts60423 -Ref: #accounts60523 -Node: activity61215 -Ref: #activity61327 -Node: add61709 -Ref: #add61812 -Node: aregister64607 -Ref: #aregister64721 -Node: aregister and custom posting dates66916 -Ref: #aregister-and-custom-posting-dates67082 -Node: balance67903 -Ref: #balance68022 -Node: balance features68935 -Ref: #balance-features69075 -Node: Simple balance report70745 -Ref: #simple-balance-report70927 -Node: Filtered balance report72375 -Ref: #filtered-balance-report72562 -Node: List or tree mode72859 -Ref: #list-or-tree-mode73027 -Node: Depth limiting74344 -Ref: #depth-limiting74510 -Node: Multi-period balance report75268 -Ref: #multi-period-balance-report75460 -Node: Sorting by amount77716 -Ref: #sorting-by-amount77885 -Node: Percentages78347 -Ref: #percentages78503 -Node: Balance change end balance79435 -Ref: #balance-change-end-balance79626 -Node: Balance report types81050 -Ref: #balance-report-types81240 -Node: Useful balance reports85404 -Ref: #useful-balance-reports85585 -Node: Budget report86669 -Ref: #budget-report86853 -Node: Budget report start date92022 -Ref: #budget-report-start-date92191 -Node: Nested budgets93518 -Ref: #nested-budgets93667 -Node: Customising single-period balance reports97054 -Ref: #customising-single-period-balance-reports97263 -Node: balancesheet99420 -Ref: #balancesheet99558 -Node: balancesheetequity100856 -Ref: #balancesheetequity101007 -Node: cashflow102387 -Ref: #cashflow102511 -Node: check103657 -Ref: #check103762 -Node: Basic checks104395 -Ref: #basic-checks104513 -Node: Strict checks105046 -Ref: #strict-checks105187 -Node: Other checks105491 -Ref: #other-checks105631 -Node: Custom checks105984 -Ref: #custom-checks106104 -Node: close106522 -Ref: #close106626 -Node: close usage108143 -Ref: #close-usage108238 -Node: codes111046 -Ref: #codes111156 -Node: commodities111869 -Ref: #commodities111998 -Node: descriptions112080 -Ref: #descriptions112210 -Node: diff112514 -Ref: #diff112622 -Node: files113667 -Ref: #files113769 -Node: help113915 -Ref: #help114017 -Node: import114740 -Ref: #import114856 -Node: Deduplication115718 -Ref: #deduplication115843 -Node: Import testing117731 -Ref: #import-testing117896 -Node: Importing balance assignments118386 -Ref: #importing-balance-assignments118592 -Node: Commodity display styles119239 -Ref: #commodity-display-styles119412 -Node: incomestatement119541 -Ref: #incomestatement119676 -Node: notes120977 -Ref: #notes121092 -Node: payees121459 -Ref: #payees121567 -Node: prices122093 -Ref: #prices122201 -Node: print122540 -Ref: #print122652 -Node: print-unique127962 -Ref: #print-unique128090 -Node: register128376 -Ref: #register128505 -Node: Custom register output132949 -Ref: #custom-register-output133080 -Node: register-match134417 -Ref: #register-match134553 -Node: rewrite134901 -Ref: #rewrite135018 -Node: Re-write rules in a file136924 -Ref: #re-write-rules-in-a-file137087 -Node: Diff output format138237 -Ref: #diff-output-format138420 -Node: rewrite vs print --auto139512 -Ref: #rewrite-vs.-print---auto139672 -Node: roi140222 -Ref: #roi140322 -Node: Semantics of --inv and --pnl141957 -Ref: #semantics-of---inv-and---pnl142139 -Node: IRR and TWR explained143985 -Ref: #irr-and-twr-explained144145 -Node: stats147207 -Ref: #stats147308 -Node: tags148095 -Ref: #tags148195 -Node: test148712 -Ref: #test148828 -Node: About add-on commands149573 -Ref: #about-add-on-commands149710 -Node: JOURNAL FORMAT150843 -Ref: #journal-format150971 -Node: Transactions153151 -Ref: #transactions153266 -Node: Dates154283 -Ref: #dates154399 -Node: Simple dates154464 -Ref: #simple-dates154584 -Node: Secondary dates155091 -Ref: #secondary-dates155239 -Node: Posting dates156573 -Ref: #posting-dates156696 -Node: Status158065 -Ref: #status158182 -Node: Description159887 -Ref: #description160017 -Node: Payee and note160335 -Ref: #payee-and-note160443 -Node: Comments160777 -Ref: #comments160899 -Node: Tags162092 -Ref: #tags-1162203 -Node: Postings163601 -Ref: #postings163725 -Node: Virtual postings164749 -Ref: #virtual-postings164860 -Node: Account names166162 -Ref: #account-names166299 -Node: Amounts166785 -Ref: #amounts166920 -Node: Decimal marks digit group marks167979 -Ref: #decimal-marks-digit-group-marks168168 -Node: Commodity display style169515 -Ref: #commodity-display-style169703 -Node: Rounding171729 -Ref: #rounding171847 -Node: Transaction prices172257 -Ref: #transaction-prices172423 -Node: Lot prices lot dates174853 -Ref: #lot-prices-lot-dates175036 -Node: Balance assertions175523 -Ref: #balance-assertions175701 -Node: Assertions and ordering176731 -Ref: #assertions-and-ordering176913 -Node: Assertions and included files177610 -Ref: #assertions-and-included-files177847 -Node: Assertions and multiple -f options178178 -Ref: #assertions-and-multiple--f-options178428 -Node: Assertions and commodities178559 -Ref: #assertions-and-commodities178785 -Node: Assertions and prices179940 -Ref: #assertions-and-prices180148 -Node: Assertions and subaccounts180589 -Ref: #assertions-and-subaccounts180812 -Node: Assertions and virtual postings181136 -Ref: #assertions-and-virtual-postings181372 -Node: Assertions and precision181513 -Ref: #assertions-and-precision181700 -Node: Balance assignments181965 -Ref: #balance-assignments182135 -Node: Balance assignments and prices183298 -Ref: #balance-assignments-and-prices183464 -Node: Directives183690 -Ref: #directives183853 -Node: Directives and multiple files189258 -Ref: #directives-and-multiple-files189454 -Node: Comment blocks190116 -Ref: #comment-blocks190293 -Node: Including other files190468 -Ref: #including-other-files190642 -Node: Default year191566 -Ref: #default-year191724 -Node: Declaring payees192131 -Ref: #declaring-payees192297 -Node: Declaring commodities192542 -Ref: #declaring-commodities192723 -Node: Commodity error checking194564 -Ref: #commodity-error-checking194714 -Node: Default commodity194970 -Ref: #default-commodity195150 -Node: Declaring market prices196035 -Ref: #declaring-market-prices196224 -Node: Declaring accounts197082 -Ref: #declaring-accounts197262 -Node: Account error checking198469 -Ref: #account-error-checking198635 -Node: Account comments199812 -Ref: #account-comments199996 -Node: Account subdirectives200422 -Ref: #account-subdirectives200607 -Node: Account types200922 -Ref: #account-types201096 -Node: Declaring account types201831 -Ref: #declaring-account-types202010 -Node: Auto-detected account types202661 -Ref: #auto-detected-account-types202902 -Node: Interference from auto-detected account types203801 -Ref: #interference-from-auto-detected-account-types204078 -Node: Old account type syntax204561 -Ref: #old-account-type-syntax204758 -Node: Account display order205059 -Ref: #account-display-order205219 -Node: Rewriting accounts206370 -Ref: #rewriting-accounts206549 -Node: Basic aliases207308 -Ref: #basic-aliases207444 -Node: Regex aliases208146 -Ref: #regex-aliases208308 -Node: Combining aliases209028 -Ref: #combining-aliases209211 -Node: Aliases and multiple files210488 -Ref: #aliases-and-multiple-files210687 -Node: end aliases211268 -Ref: #end-aliases211415 -Node: Default parent account211517 -Ref: #default-parent-account211707 -Node: Periodic transactions212591 -Ref: #periodic-transactions212774 -Node: Periodic rule syntax214691 -Ref: #periodic-rule-syntax214891 -Node: Two spaces between period expression and description!215594 -Ref: #two-spaces-between-period-expression-and-description215907 -Node: Forecasting with periodic transactions216592 -Ref: #forecasting-with-periodic-transactions216891 -Node: Budgeting with periodic transactions218937 -Ref: #budgeting-with-periodic-transactions219170 -Node: Auto postings219577 -Ref: #auto-postings219713 -Node: Auto postings and multiple files221896 -Ref: #auto-postings-and-multiple-files222094 -Node: Auto postings and dates222302 -Ref: #auto-postings-and-dates222570 -Node: Auto postings and transaction balancing / inferred amounts / balance assertions222745 -Ref: #auto-postings-and-transaction-balancing-inferred-amounts-balance-assertions223091 -Node: Auto posting tags223436 -Ref: #auto-posting-tags223645 -Node: CSV FORMAT224282 -Ref: #csv-format224410 -Node: Examples226991 -Ref: #examples227094 -Node: Basic227301 -Ref: #basic227403 -Node: Bank of Ireland227947 -Ref: #bank-of-ireland228084 -Node: Amazon229549 -Ref: #amazon229669 -Node: Paypal231390 -Ref: #paypal231486 -Node: CSV rules239134 -Ref: #csv-rules239252 -Node: skip239564 -Ref: #skip239659 -Node: fields240031 -Ref: #fields240155 -Node: Transaction field names241316 -Ref: #transaction-field-names241478 -Node: Posting field names241589 -Ref: #posting-field-names241743 -Node: field assignment244104 -Ref: #field-assignment244249 -Node: separator245063 -Ref: #separator245200 -Node: if block245742 -Ref: #if-block245869 -Node: Matching the whole record246267 -Ref: #matching-the-whole-record246444 -Node: Matching individual fields247248 -Ref: #matching-individual-fields247454 -Node: Combining matchers247678 -Ref: #combining-matchers247876 -Node: Rules applied on successful match248190 -Ref: #rules-applied-on-successful-match248383 -Node: if table249040 -Ref: #if-table249161 -Node: end250897 -Ref: #end251011 -Node: date-format251235 -Ref: #date-format251369 -Node: decimal-mark252119 -Ref: #decimal-mark252264 -Node: newest-first252601 -Ref: #newest-first252744 -Node: include253427 -Ref: #include253560 -Node: balance-type254002 -Ref: #balance-type254124 -Node: Tips254824 -Ref: #tips254915 -Node: Rapid feedback255214 -Ref: #rapid-feedback255333 -Node: Valid CSV255792 -Ref: #valid-csv255924 -Node: File Extension256116 -Ref: #file-extension256270 -Node: Reading multiple CSV files256699 -Ref: #reading-multiple-csv-files256886 -Node: Valid transactions257126 -Ref: #valid-transactions257306 -Node: Deduplicating importing257934 -Ref: #deduplicating-importing258115 -Node: Setting amounts259147 -Ref: #setting-amounts259304 -Node: Amount signs261523 -Ref: #amount-signs261677 -Node: Setting currency/commodity262364 -Ref: #setting-currencycommodity262552 -Node: Amount decimal places263732 -Ref: #amount-decimal-places263924 -Node: Referencing other fields264236 -Ref: #referencing-other-fields264435 -Node: How CSV rules are evaluated265333 -Ref: #how-csv-rules-are-evaluated265508 -Node: TIMECLOCK FORMAT266957 -Ref: #timeclock-format267097 -Node: TIMEDOT FORMAT269165 -Ref: #timedot-format269303 -Node: COMMON TASKS273566 -Ref: #common-tasks273695 -Node: Getting help274102 -Ref: #getting-help274236 -Node: Constructing command lines274787 -Ref: #constructing-command-lines274981 -Node: Starting a journal file275680 -Ref: #starting-a-journal-file275880 -Node: Setting opening balances277067 -Ref: #setting-opening-balances277265 -Node: Recording transactions280398 -Ref: #recording-transactions280580 -Node: Reconciling281137 -Ref: #reconciling281282 -Node: Reporting283527 -Ref: #reporting283669 -Node: Migrating to a new file287589 -Ref: #migrating-to-a-new-file287739 -Node: LIMITATIONS288037 -Ref: #limitations288165 -Node: TROUBLESHOOTING288906 -Ref: #troubleshooting289021 +Node: TIME PERIODS19355 +Ref: #time-periods19472 +Node: Smart dates19570 +Ref: #smart-dates19696 +Node: Report start & end date21000 +Ref: #report-start-end-date21175 +Node: Report intervals22719 +Ref: #report-intervals22887 +Node: Period expressions24161 +Ref: #period-expressions24301 +Node: DEPTH28680 +Ref: #depth28780 +Node: QUERIES29111 +Ref: #queries29210 +Node: COSTING33162 +Ref: #costing33265 +Node: VALUATION33538 +Ref: #valuation33646 +Node: -V Value34369 +Ref: #v-value34493 +Node: -X Value in specified commodity34687 +Ref: #x-value-in-specified-commodity34880 +Node: Valuation date35029 +Ref: #valuation-date35191 +Node: Market prices35628 +Ref: #market-prices35809 +Node: --infer-market-price market prices from transactions36991 +Ref: #infer-market-price-market-prices-from-transactions37255 +Node: Valuation commodity38604 +Ref: #valuation-commodity38814 +Node: Simple valuation examples40039 +Ref: #simple-valuation-examples40235 +Node: --value Flexible valuation40897 +Ref: #value-flexible-valuation41099 +Node: More valuation examples42741 +Ref: #more-valuation-examples42942 +Node: Effect of valuation on reports44948 +Ref: #effect-of-valuation-on-reports45130 +Node: PIVOTING53027 +Ref: #pivoting53132 +Node: OUTPUT54811 +Ref: #output54913 +Node: Output destination54964 +Ref: #output-destination55097 +Node: Output format55753 +Ref: #output-format55876 +Node: COMMANDS58039 +Ref: #commands58151 +Node: accounts61541 +Ref: #accounts61641 +Node: activity62333 +Ref: #activity62445 +Node: add62827 +Ref: #add62930 +Node: aregister65725 +Ref: #aregister65839 +Node: aregister and custom posting dates68034 +Ref: #aregister-and-custom-posting-dates68200 +Node: balance69021 +Ref: #balance69140 +Node: balance features70053 +Ref: #balance-features70193 +Node: Simple balance report71863 +Ref: #simple-balance-report72045 +Node: Filtered balance report73493 +Ref: #filtered-balance-report73680 +Node: List or tree mode73977 +Ref: #list-or-tree-mode74145 +Node: Depth limiting75462 +Ref: #depth-limiting75628 +Node: Multi-period balance report76386 +Ref: #multi-period-balance-report76578 +Node: Sorting by amount78834 +Ref: #sorting-by-amount79003 +Node: Percentages79465 +Ref: #percentages79621 +Node: Balance change end balance80553 +Ref: #balance-change-end-balance80744 +Node: Balance report types82168 +Ref: #balance-report-types82358 +Node: Useful balance reports86522 +Ref: #useful-balance-reports86703 +Node: Budget report87787 +Ref: #budget-report87971 +Node: Budget report start date93140 +Ref: #budget-report-start-date93309 +Node: Nested budgets94636 +Ref: #nested-budgets94785 +Node: Customising single-period balance reports98172 +Ref: #customising-single-period-balance-reports98381 +Node: balancesheet100538 +Ref: #balancesheet100676 +Node: balancesheetequity101974 +Ref: #balancesheetequity102125 +Node: cashflow103505 +Ref: #cashflow103629 +Node: check104775 +Ref: #check104880 +Node: Basic checks105513 +Ref: #basic-checks105631 +Node: Strict checks106164 +Ref: #strict-checks106305 +Node: Other checks106609 +Ref: #other-checks106749 +Node: Custom checks107106 +Ref: #custom-checks107226 +Node: close107644 +Ref: #close107748 +Node: close usage109265 +Ref: #close-usage109360 +Node: codes112168 +Ref: #codes112278 +Node: commodities112991 +Ref: #commodities113120 +Node: descriptions113202 +Ref: #descriptions113332 +Node: diff113636 +Ref: #diff113744 +Node: files114789 +Ref: #files114891 +Node: help115037 +Ref: #help115139 +Node: import115862 +Ref: #import115978 +Node: Deduplication116840 +Ref: #deduplication116965 +Node: Import testing118853 +Ref: #import-testing119018 +Node: Importing balance assignments119508 +Ref: #importing-balance-assignments119714 +Node: Commodity display styles120361 +Ref: #commodity-display-styles120534 +Node: incomestatement120663 +Ref: #incomestatement120798 +Node: notes122099 +Ref: #notes122214 +Node: payees122581 +Ref: #payees122689 +Node: prices123215 +Ref: #prices123323 +Node: print123662 +Ref: #print123774 +Node: print-unique129084 +Ref: #print-unique129212 +Node: register129498 +Ref: #register129627 +Node: Custom register output134071 +Ref: #custom-register-output134202 +Node: register-match135539 +Ref: #register-match135675 +Node: rewrite136023 +Ref: #rewrite136140 +Node: Re-write rules in a file138046 +Ref: #re-write-rules-in-a-file138209 +Node: Diff output format139359 +Ref: #diff-output-format139542 +Node: rewrite vs print --auto140634 +Ref: #rewrite-vs.-print---auto140794 +Node: roi141344 +Ref: #roi141444 +Node: Semantics of --inv and --pnl143079 +Ref: #semantics-of---inv-and---pnl143261 +Node: IRR and TWR explained145107 +Ref: #irr-and-twr-explained145267 +Node: stats148329 +Ref: #stats148430 +Node: tags149217 +Ref: #tags149317 +Node: test149834 +Ref: #test149950 +Node: About add-on commands150695 +Ref: #about-add-on-commands150832 +Node: JOURNAL FORMAT151965 +Ref: #journal-format152093 +Node: Transactions154273 +Ref: #transactions154388 +Node: Dates155405 +Ref: #dates155521 +Node: Simple dates155586 +Ref: #simple-dates155706 +Node: Secondary dates156213 +Ref: #secondary-dates156361 +Node: Posting dates157695 +Ref: #posting-dates157818 +Node: Status159187 +Ref: #status159304 +Node: Description161009 +Ref: #description161139 +Node: Payee and note161457 +Ref: #payee-and-note161565 +Node: Comments161899 +Ref: #comments162021 +Node: Tags163214 +Ref: #tags-1163325 +Node: Postings164723 +Ref: #postings164847 +Node: Virtual postings165871 +Ref: #virtual-postings165982 +Node: Account names167284 +Ref: #account-names167421 +Node: Amounts167907 +Ref: #amounts168042 +Node: Decimal marks digit group marks169000 +Ref: #decimal-marks-digit-group-marks169175 +Node: Commodity170047 +Ref: #commodity170205 +Node: Commodity directives171155 +Ref: #commodity-directives171327 +Node: Commodity display style171813 +Ref: #commodity-display-style171990 +Node: Rounding174098 +Ref: #rounding174216 +Node: Transaction prices174626 +Ref: #transaction-prices174792 +Node: Lot prices lot dates177222 +Ref: #lot-prices-lot-dates177405 +Node: Balance assertions177892 +Ref: #balance-assertions178070 +Node: Assertions and ordering179100 +Ref: #assertions-and-ordering179282 +Node: Assertions and included files179979 +Ref: #assertions-and-included-files180216 +Node: Assertions and multiple -f options180547 +Ref: #assertions-and-multiple--f-options180797 +Node: Assertions and commodities180928 +Ref: #assertions-and-commodities181154 +Node: Assertions and prices182309 +Ref: #assertions-and-prices182517 +Node: Assertions and subaccounts182958 +Ref: #assertions-and-subaccounts183181 +Node: Assertions and virtual postings183505 +Ref: #assertions-and-virtual-postings183741 +Node: Assertions and precision183882 +Ref: #assertions-and-precision184069 +Node: Balance assignments184334 +Ref: #balance-assignments184504 +Node: Balance assignments and prices185667 +Ref: #balance-assignments-and-prices185833 +Node: Directives186059 +Ref: #directives186222 +Node: Directives and multiple files191627 +Ref: #directives-and-multiple-files191823 +Node: Comment blocks192485 +Ref: #comment-blocks192662 +Node: Including other files192837 +Ref: #including-other-files193011 +Node: Default year193935 +Ref: #default-year194093 +Node: Declaring payees194500 +Ref: #declaring-payees194666 +Node: Declaring commodities194911 +Ref: #declaring-commodities195092 +Node: Commodity error checking197468 +Ref: #commodity-error-checking197618 +Node: Default commodity197874 +Ref: #default-commodity198054 +Node: Declaring market prices198928 +Ref: #declaring-market-prices199117 +Node: Declaring accounts199975 +Ref: #declaring-accounts200155 +Node: Account error checking201362 +Ref: #account-error-checking201528 +Node: Account comments202705 +Ref: #account-comments202889 +Node: Account subdirectives203315 +Ref: #account-subdirectives203500 +Node: Account types203815 +Ref: #account-types203989 +Node: Declaring account types204724 +Ref: #declaring-account-types204903 +Node: Auto-detected account types205554 +Ref: #auto-detected-account-types205795 +Node: Interference from auto-detected account types206761 +Ref: #interference-from-auto-detected-account-types207038 +Node: Old account type syntax207521 +Ref: #old-account-type-syntax207718 +Node: Account display order208019 +Ref: #account-display-order208179 +Node: Rewriting accounts209330 +Ref: #rewriting-accounts209509 +Node: Basic aliases210268 +Ref: #basic-aliases210404 +Node: Regex aliases211106 +Ref: #regex-aliases211268 +Node: Combining aliases211988 +Ref: #combining-aliases212171 +Node: Aliases and multiple files213448 +Ref: #aliases-and-multiple-files213647 +Node: end aliases214228 +Ref: #end-aliases214375 +Node: Default parent account214477 +Ref: #default-parent-account214667 +Node: Periodic transactions215551 +Ref: #periodic-transactions215734 +Node: Periodic rule syntax217651 +Ref: #periodic-rule-syntax217851 +Node: Two spaces between period expression and description!218554 +Ref: #two-spaces-between-period-expression-and-description218867 +Node: Forecasting with periodic transactions219552 +Ref: #forecasting-with-periodic-transactions219851 +Node: Budgeting with periodic transactions221897 +Ref: #budgeting-with-periodic-transactions222130 +Node: Auto postings222537 +Ref: #auto-postings222673 +Node: Auto postings and multiple files224856 +Ref: #auto-postings-and-multiple-files225054 +Node: Auto postings and dates225262 +Ref: #auto-postings-and-dates225530 +Node: Auto postings and transaction balancing / inferred amounts / balance assertions225705 +Ref: #auto-postings-and-transaction-balancing-inferred-amounts-balance-assertions226051 +Node: Auto posting tags226396 +Ref: #auto-posting-tags226605 +Node: CSV FORMAT227242 +Ref: #csv-format227370 +Node: Examples229951 +Ref: #examples230054 +Node: Basic230261 +Ref: #basic230363 +Node: Bank of Ireland230907 +Ref: #bank-of-ireland231044 +Node: Amazon232509 +Ref: #amazon232629 +Node: Paypal234350 +Ref: #paypal234446 +Node: CSV rules242094 +Ref: #csv-rules242212 +Node: skip242524 +Ref: #skip242619 +Node: fields242991 +Ref: #fields243115 +Node: Transaction field names244276 +Ref: #transaction-field-names244438 +Node: Posting field names244549 +Ref: #posting-field-names244703 +Node: field assignment247064 +Ref: #field-assignment247209 +Node: separator248023 +Ref: #separator248160 +Node: if block248702 +Ref: #if-block248829 +Node: Matching the whole record249227 +Ref: #matching-the-whole-record249404 +Node: Matching individual fields250207 +Ref: #matching-individual-fields250413 +Node: Combining matchers250637 +Ref: #combining-matchers250835 +Node: Rules applied on successful match251149 +Ref: #rules-applied-on-successful-match251342 +Node: if table251999 +Ref: #if-table252120 +Node: end253856 +Ref: #end253970 +Node: date-format254194 +Ref: #date-format254328 +Node: decimal-mark255078 +Ref: #decimal-mark255223 +Node: newest-first255560 +Ref: #newest-first255703 +Node: include256386 +Ref: #include256519 +Node: balance-type256961 +Ref: #balance-type257083 +Node: Tips257783 +Ref: #tips257874 +Node: Rapid feedback258173 +Ref: #rapid-feedback258292 +Node: Valid CSV258751 +Ref: #valid-csv258883 +Node: File Extension259075 +Ref: #file-extension259229 +Node: Reading multiple CSV files259658 +Ref: #reading-multiple-csv-files259845 +Node: Valid transactions260085 +Ref: #valid-transactions260265 +Node: Deduplicating importing260893 +Ref: #deduplicating-importing261074 +Node: Setting amounts262106 +Ref: #setting-amounts262263 +Node: Amount signs264482 +Ref: #amount-signs264636 +Node: Setting currency/commodity265323 +Ref: #setting-currencycommodity265511 +Node: Amount decimal places266691 +Ref: #amount-decimal-places266883 +Node: Referencing other fields267195 +Ref: #referencing-other-fields267394 +Node: How CSV rules are evaluated268292 +Ref: #how-csv-rules-are-evaluated268467 +Node: TIMECLOCK FORMAT269916 +Ref: #timeclock-format270056 +Node: TIMEDOT FORMAT272124 +Ref: #timedot-format272262 +Node: COMMON TASKS276525 +Ref: #common-tasks276654 +Node: Getting help277061 +Ref: #getting-help277195 +Node: Constructing command lines277746 +Ref: #constructing-command-lines277940 +Node: Starting a journal file278639 +Ref: #starting-a-journal-file278839 +Node: Setting opening balances280026 +Ref: #setting-opening-balances280224 +Node: Recording transactions283357 +Ref: #recording-transactions283539 +Node: Reconciling284096 +Ref: #reconciling284241 +Node: Reporting286486 +Ref: #reporting286628 +Node: Migrating to a new file290548 +Ref: #migrating-to-a-new-file290698 +Node: LIMITATIONS290996 +Ref: #limitations291124 +Node: TROUBLESHOOTING291865 +Ref: #troubleshooting291980  End Tag Table diff --git a/hledger/hledger.txt b/hledger/hledger.txt index 71ce8d309..58abfbff6 100644 --- a/hledger/hledger.txt +++ b/hledger/hledger.txt @@ -497,20 +497,19 @@ DATA FILES o Are all commodities declared with a commodity directive ? (Commodity error checking) - See also: https://hledger.org/checking-for-errors.html - - experimental. + You can also use the check command to run these and some additional + checks. TIME PERIODS Smart dates hledger's user interfaces accept a flexible "smart date" syntax. Smart - dates allow some english words, can be relative to today's date, and + dates allow some english words, can be relative to today's date, and can have less-significant date parts omitted (defaulting to 1). Examples: - 2004/10/1, 2004-01-01, exact date, several separators allowed. Year + 2004/10/1, 2004-01-01, exact date, several separators allowed. Year 2004.9.1 is 4+ digits, month is 1-12, day is 1-31 2004 start of year 2004/10 start of month @@ -525,13 +524,13 @@ TIME PERIODS 20181201 8 digit YYYYMMDD with valid year month and day 201812 6 digit YYYYMM with valid year and month - Counterexamples - malformed digit sequences might give surprising + Counterexamples - malformed digit sequences might give surprising results: - 201813 6 digits with an invalid month is parsed as start of + 201813 6 digits with an invalid month is parsed as start of 6-digit year - 20181301 8 digits with an invalid month is parsed as start of + 20181301 8 digits with an invalid month is parsed as start of 8-digit year 20181232 8 digits with an invalid day gives an error 201801012 9+ digits beginning with a valid YYYYMMDD gives an error @@ -542,33 +541,33 @@ TIME PERIODS transaction or posting date, and the report end date will be the latest transaction, posting, or market price date. - Often you will want to see a shorter time span, such as the current - month. You can specify a start and/or end date using -b/--begin, + Often you will want to see a shorter time span, such as the current + month. You can specify a start and/or end date using -b/--begin, -e/--end, -p/--period or a date: query (described below). All of these accept the smart date syntax. Some notes: - o As in Ledger, end dates are exclusive, so you need to write the date + o As in Ledger, end dates are exclusive, so you need to write the date after the last day you want to include. - o As noted in reporting options: among start/end dates specified with + o As noted in reporting options: among start/end dates specified with options, the last (i.e. right-most) option takes precedence. - o The effective report start and end dates are the intersection of the - start/end dates from options and that from date: queries. That is, - date:2019-01 date:2019 -p'2000 to 2030' yields January 2019, the + o The effective report start and end dates are the intersection of the + start/end dates from options and that from date: queries. That is, + date:2019-01 date:2019 -p'2000 to 2030' yields January 2019, the smallest common time span. Examples: -b 2016/3/17 begin on St. Patrick's day 2016 - -e 12/1 end at the start of december 1st of the current year + -e 12/1 end at the start of december 1st of the current year (11/30 will be the last date included) -b thismonth all transactions on or after the 1st of the current month -p thismonth all transactions in the current month - date:2016/3/17.. the above written as queries instead (.. can also be + date:2016/3/17.. the above written as queries instead (.. can also be replaced with -) date:..12/1 date:thismonth.. @@ -576,11 +575,32 @@ TIME PERIODS Report intervals A report interval can be specified so that commands like register, bal- - ance and activity will divide their reports into multiple subperiods. - The basic intervals can be selected with one of -D/--daily, - -W/--weekly, -M/--monthly, -Q/--quarterly, or -Y/--yearly. More com- - plex intervals may be specified with a period expression. Report - intervals can not be specified with a query. + ance and activity become multi-period, showing each subperiod as a sep- + arate row or column. + + The following "standard" report intervals can be enabled by using their + corresponding flag: + + -D/--daily, -W/--weekly, -M/--monthly, -Q/--quarterly, -Y/--yearly. + + These standard intervals always start on natural interval boundaries: + eg --weekly starts on mondays, --monthly starts on the first of the + month, --yearly always starts on January 1st, etc. + + Certain more complex intervals, and more flexible boundary dates, can + be specified by -p/--period. These are described in period expres- + sions, below. + + Report intervals can only be specified by the flags above, and not by + query arguments, currently. + + Report intervals have another effect: multi-period reports are always + expanded to fill a whole number of subperiods. So if you use a report + interval (other than --daily), and you have specified a start or end + date, you may notice those dates being overridden (ie, the report + starts earlier than your requested start date, or ends later than your + requested end date). This is done to ensure "full" first and last sub- + periods, so that all subperiods' numbers are comparable. Period expressions The -p/--period option accepts period expressions, a shorthand way of @@ -606,7 +626,6 @@ TIME PERIODS -p "1/1 4/1" - -p "january-apr" -p "this year to 4/1" @@ -1162,8 +1181,6 @@ VALUATION posting cost value at value at posting value at value at amounts report end date report or DATE/today or today journal end - - summary post- summarised value at sum of postings value at value at ing amounts cost period ends in interval, val- period ends DATE/today with report ued at interval @@ -1201,6 +1218,12 @@ VALUATION is, bs postings in period at respec- each period, sums of post- --change, cf period tive posting valued at ings --change) dates period ends + + + + + + end balances sums of same as sums of values of period end value at (bal -H, is costs of --value=end postings from balances, DATE/today of --H, bs, cf) postings before period valued at sums of post- @@ -1322,10 +1345,15 @@ OUTPUT $ hledger print -o foo.txt $ hledger print -o - # write to stdout (the default) + hledger can optionally produce debug output (if enabled with + --debug=N); this goes to stderr, and is not affected by -o/--output- + file. If you need to capture it, use shell redirects, eg: hledger bal + --debug=3 >file 2>&1. + Output format Some commands (print, register, the balance commands) offer a choice of output format. In addition to the usual plain text format (txt), there - are CSV (csv), HTML (html), JSON (json) and SQL (sql). This is con- + are CSV (csv), HTML (html), JSON (json) and SQL (sql). This is con- trolled by the -O/--output-format option: $ hledger print -O csv @@ -1340,42 +1368,42 @@ OUTPUT Some notes about JSON output: - o This feature is marked experimental, and not yet much used; you + o This feature is marked experimental, and not yet much used; you should expect our JSON to evolve. Real-world feedback is welcome. - o Our JSON is rather large and verbose, as it is quite a faithful rep- - resentation of hledger's internal data types. To understand the + o Our JSON is rather large and verbose, as it is quite a faithful rep- + resentation of hledger's internal data types. To understand the JSON, read the Haskell type definitions, which are mostly in https://github.com/simonmichael/hledger/blob/master/hledger- lib/Hledger/Data/Types.hs. - o hledger represents quantities as Decimal values storing up to 255 - significant digits, eg for repeating decimals. Such numbers can + o hledger represents quantities as Decimal values storing up to 255 + significant digits, eg for repeating decimals. Such numbers can arise in practice (from automatically-calculated transaction prices), - and would break most JSON consumers. So in JSON, we show quantities + and would break most JSON consumers. So in JSON, we show quantities as simple Numbers with at most 10 decimal places. We don't limit the - number of integer digits, but that part is under your control. We - hope this approach will not cause problems in practice; if you find + number of integer digits, but that part is under your control. We + hope this approach will not cause problems in practice; if you find otherwise, please let us know. (Cf #1195) Notes about SQL output: - o SQL output is also marked experimental, and much like JSON could use + o SQL output is also marked experimental, and much like JSON could use real-world feedback. o SQL output is expected to work with sqlite, MySQL and PostgreSQL - o SQL output is structured with the expectations that statements will - be executed in the empty database. If you already have tables cre- - ated via SQL output of hledger, you would probably want to either + o SQL output is structured with the expectations that statements will + be executed in the empty database. If you already have tables cre- + ated via SQL output of hledger, you would probably want to either clear tables of existing data (via delete or truncate SQL statements) or drop tables completely as otherwise your postings will be duped. COMMANDS - hledger provides a number of commands for producing reports and manag- - ing your data. Run hledger with no arguments to list the commands - available, and hledger CMD to run a command. CMD can be the full com- - mand name, or its standard abbreviation shown in the commands list, or + hledger provides a number of commands for producing reports and manag- + ing your data. Run hledger with no arguments to list the commands + available, and hledger CMD to run a command. CMD can be the full com- + mand name, or its standard abbreviation shown in the commands list, or any unambiguous prefix of the name. Eg: hledger bal. Here are the built-in commands, with the most often-used in bold: @@ -1419,7 +1447,7 @@ COMMANDS o activity - show postings-per-interval bar charts - o balance (bal) - show balance changes/end balances/budgets in any + o balance (bal) - show balance changes/end balances/budgets in any accounts o codes - show transaction codes @@ -1442,10 +1470,10 @@ COMMANDS o print-unique - show only transactions with unique descriptions - o register (reg) - show postings in one or more accounts & running + o register (reg) - show postings in one or more accounts & running total - o register-match - show a recent posting that best matches a descrip- + o register-match - show a recent posting that best matches a descrip- tion o stats - show journal statistics @@ -1456,8 +1484,8 @@ COMMANDS Add-on commands: - Programs or scripts named hledger-SOMETHING in your PATH are add-on - commands; these appear in the commands list with a + mark. Two of + Programs or scripts named hledger-SOMETHING in your PATH are add-on + commands; these appear in the commands list with a + mark. Two of these are maintained and released with hledger: o ui - an efficient terminal interface (TUI) for hledger @@ -1468,10 +1496,10 @@ COMMANDS o iadd - a more interactive alternative for the add command - o interest - generates interest transactions according to various + o interest - generates interest transactions according to various schemes - o stockquotes - downloads market prices for your commodities from + o stockquotes - downloads market prices for your commodities from AlphaVantage (experimental) Next, the detailed command docs, in alphabetical order. @@ -1480,13 +1508,13 @@ COMMANDS accounts Show account names. - This command lists account names, either declared with account direc- - tives (--declared), posted to (--used), or both (the default). With - query arguments, only matched account names and account names refer- - enced by matched postings are shown. It shows a flat list by default. - With --tree, it uses indentation to show the account hierarchy. In - flat mode you can add --drop N to omit the first few account name com- - ponents. Account names can be depth-clipped with depth:N or --depth N + This command lists account names, either declared with account direc- + tives (--declared), posted to (--used), or both (the default). With + query arguments, only matched account names and account names refer- + enced by matched postings are shown. It shows a flat list by default. + With --tree, it uses indentation to show the account hierarchy. In + flat mode you can add --drop N to omit the first few account name com- + ponents. Account names can be depth-clipped with depth:N or --depth N or -N. Examples: @@ -1505,8 +1533,8 @@ COMMANDS activity Show an ascii barchart of posting counts per interval. - The activity command displays an ascii histogram showing transaction - counts by day, week, month or other reporting interval (by day is the + The activity command displays an ascii histogram showing transaction + counts by day, week, month or other reporting interval (by day is the default). With query arguments, it counts only matched transactions. Examples: @@ -1519,25 +1547,25 @@ COMMANDS add add - Prompt for transactions and add them to the journal. Any arguments + Prompt for transactions and add them to the journal. Any arguments will be used as default inputs for the first N prompts. - Many hledger users edit their journals directly with a text editor, or - generate them from CSV. For more interactive data entry, there is the - add command, which prompts interactively on the console for new trans- + Many hledger users edit their journals directly with a text editor, or + generate them from CSV. For more interactive data entry, there is the + add command, which prompts interactively on the console for new trans- actions, and appends them to the journal file (if there are multiple -f - FILE options, the first file is used.) Existing transactions are not - changed. This is the only hledger command that writes to the journal + FILE options, the first file is used.) Existing transactions are not + changed. This is the only hledger command that writes to the journal file. To use it, just run hledger add and follow the prompts. You can add as - many transactions as you like; when you are finished, enter . or press + many transactions as you like; when you are finished, enter . or press control-d or control-c to exit. Features: - o add tries to provide useful defaults, using the most similar (by - description) recent transaction (filtered by the query, if any) as a + o add tries to provide useful defaults, using the most similar (by + description) recent transaction (filtered by the query, if any) as a template. o You can also set the initial defaults with command line arguments. @@ -1545,10 +1573,10 @@ COMMANDS o Readline-style edit keys can be used during data entry. o The tab key will auto-complete whenever possible - accounts, descrip- - tions, dates (yesterday, today, tomorrow). If the input area is + tions, dates (yesterday, today, tomorrow). If the input area is empty, it will insert the default value. - o If the journal defines a default commodity, it will be added to any + o If the journal defines a default commodity, it will be added to any bare numbers entered. o A parenthesised transaction code may be entered following a date. @@ -1557,7 +1585,7 @@ COMMANDS o If you make a mistake, enter < at any prompt to go one step backward. - o Input prompts are displayed in a different colour when the terminal + o Input prompts are displayed in a different colour when the terminal supports it. Example (see the tutorial for a detailed explanation): @@ -1587,81 +1615,81 @@ COMMANDS Starting the next transaction (. or ctrl-D/ctrl-C to quit) Date [2015/05/22]: $ - On Microsoft Windows, the add command makes sure that no part of the + On Microsoft Windows, the add command makes sure that no part of the file path ends with a period, as that would cause problems (#1056). aregister aregister, areg - Show the transactions and running historical balance in an account, + Show the transactions and running historical balance in an account, with each line item representing one transaction. aregister shows the transactions affecting a particular account and its - subaccounts, with each line item representing a whole transaction - as - in bank statements, hledger-ui, hledger-web and other accounting apps. + subaccounts, with each line item representing a whole transaction - as + in bank statements, hledger-ui, hledger-web and other accounting apps. - Note this is unlike the register command, which shows individual post- + Note this is unlike the register command, which shows individual post- ings and does not always show a single account or a historical balance. A reminder, "historical" balances include any balance from transactions before the report start date, so (if opening balances are recorded cor- - rectly) aregister will show the real-world balances of an account, as + rectly) aregister will show the real-world balances of an account, as you would see in a bank statement. - As a quick rule of thumb, use aregister for reconciling real-world - asset/liability accounts and register for reviewing detailed rev- + As a quick rule of thumb, use aregister for reconciling real-world + asset/liability accounts and register for reviewing detailed rev- enues/expenses. - aregister shows the register for just one account (and its subac- - counts). This account must be specified as the first argument. You - can write either the full account name, or a case-insensitive regular - expression which will select the alphabetically first matched account. - (Eg if you have assets:aaa:checking and assets:bbb:checking accounts, + aregister shows the register for just one account (and its subac- + counts). This account must be specified as the first argument. You + can write either the full account name, or a case-insensitive regular + expression which will select the alphabetically first matched account. + (Eg if you have assets:aaa:checking and assets:bbb:checking accounts, hledger areg checking would select assets:aaa:checking.) - Any additional arguments form a query which will filter the transac- + Any additional arguments form a query which will filter the transac- tions shown. Each aregister line item shows: - o the transaction's date (or the relevant posting's date if different, + o the transaction's date (or the relevant posting's date if different, see below) - o the names of all the other account(s) involved in this transaction + o the names of all the other account(s) involved in this transaction (probably abbreviated) o the total change to this account's balance from this transaction o the account's historical running balance after this transaction. - Transactions making a net change of zero are not shown by default; add + Transactions making a net change of zero are not shown by default; add the -E/--empty flag to show them. aregister ignores a depth limit, so its final total will always match a balance report with similar arguments. - This command also supports the output destination and output format + This command also supports the output destination and output format options The output formats supported are txt, csv, and json. aregister and custom posting dates - Transactions whose date is outside the report period can still be - shown, if they have a posting to this account dated inside the report - period. (And in this case it's the posting date that is shown.) This + Transactions whose date is outside the report period can still be + shown, if they have a posting to this account dated inside the report + period. (And in this case it's the posting date that is shown.) This ensures that aregister can show an accurate historical running balance, matching the one shown by register -H with the same arguments. - To filter strictly by transaction date instead, add the --txn-dates - flag. If you use this flag and some of your postings have custom + To filter strictly by transaction date instead, add the --txn-dates + flag. If you use this flag and some of your postings have custom dates, it's probably best to assume the running balance is wrong. Examples: - Show all transactions and historical running balance in the first + Show all transactions and historical running balance in the first account whose name contains "checking": $ hledger areg checking - Show transactions and historical running balance in all asset accounts + Show transactions and historical running balance in all asset accounts during july: $ hledger areg assets date:jul @@ -1670,19 +1698,19 @@ COMMANDS balance, bal Show accounts and their balances. - balance is one of hledger's oldest and most versatile commands, for - listing account balances, balance changes, values, value changes and + balance is one of hledger's oldest and most versatile commands, for + listing account balances, balance changes, values, value changes and more, during one time period or many. Generally it shows a table, with rows representing accounts, and columns representing periods. - Note there are some higher-level variants of the balance command with - convenient defaults, which can be simpler to use: balancesheet, bal- + Note there are some higher-level variants of the balance command with + convenient defaults, which can be simpler to use: balancesheet, bal- ancesheetequity, cashflow and incomestatement. When you need more con- trol, then use balance. balance features - Here's a quick overview of the balance command's features, followed by - more detailed descriptions and examples. Many of these work with the + Here's a quick overview of the balance command's features, followed by + more detailed descriptions and examples. Many of these work with the higher-level commands as well. balance can show.. @@ -1731,7 +1759,7 @@ COMMANDS ..with.. - o totals (-T), averages (-A), percentages (-%), inverted sign + o totals (-T), averages (-A), percentages (-%), inverted sign (--invert) o rows and columns swapped (--transpose) @@ -1741,18 +1769,18 @@ COMMANDS o custom-formatted line items (single-period reports only) (--format) This command supports the output destination and output format options, - with output formats txt, csv, json, and (multi-period reports only:) - html. In txt output in a colour-supporting terminal, negative amounts + with output formats txt, csv, json, and (multi-period reports only:) + html. In txt output in a colour-supporting terminal, negative amounts are shown in red. Simple balance report - With no arguments, balance shows a list of all accounts and their - change of balance - ie, the sum of posting amounts, both inflows and - outflows - during the entire period of the journal. For real-world - accounts, this should also match their end balance at the end of the + With no arguments, balance shows a list of all accounts and their + change of balance - ie, the sum of posting amounts, both inflows and + outflows - during the entire period of the journal. For real-world + accounts, this should also match their end balance at the end of the journal period (more on this below). - Accounts are sorted by declaration order if any, and then alphabeti- + Accounts are sorted by declaration order if any, and then alphabeti- cally by account name. For instance, using examples/sample.journal: $ hledger bal @@ -1767,7 +1795,7 @@ COMMANDS 0 Accounts with a zero balance (and no non-zero subaccounts, in tree mode - - see below) are hidden by default. Use -E/--empty to show them + - see below) are hidden by default. Use -E/--empty to show them (revealing assets:bank:checking here): $ hledger -f examples/sample.journal bal -E @@ -1782,11 +1810,11 @@ COMMANDS -------------------- 0 - The total of the amounts displayed is shown as the last line, unless + The total of the amounts displayed is shown as the last line, unless -N/--no-total is used. Filtered balance report - You can show fewer accounts, a different time period, totals from + You can show fewer accounts, a different time period, totals from cleared transactions only, etc. by using query arguments or options to limit the postings being matched. Eg: @@ -1796,10 +1824,10 @@ COMMANDS $-2 List or tree mode - By default, or with -l/--flat, accounts are shown as a flat list with + By default, or with -l/--flat, accounts are shown as a flat list with their full names visible, as in the examples above. - With -t/--tree, the account hierarchy is shown, with subaccounts' + With -t/--tree, the account hierarchy is shown, with subaccounts' "leaf" names indented below their parent: $ hledger balance @@ -1819,24 +1847,24 @@ COMMANDS Notes: o "Boring" accounts are combined with their subaccount for more compact - output, unless --no-elide is used. Boring accounts have no balance - of their own and just one subaccount (eg assets:bank and liabilities + output, unless --no-elide is used. Boring accounts have no balance + of their own and just one subaccount (eg assets:bank and liabilities above). - o All balances shown are "inclusive", ie including the balances from - all subaccounts. Note this means some repetition in the output, + o All balances shown are "inclusive", ie including the balances from + all subaccounts. Note this means some repetition in the output, which requires explanation when sharing reports with non-plaintextac- - counting-users. A tree mode report's final total is the sum of the + counting-users. A tree mode report's final total is the sum of the top-level balances shown, not of all the balances shown. - o Each group of sibling accounts (ie, under a common parent) is sorted + o Each group of sibling accounts (ie, under a common parent) is sorted separately. Depth limiting - With a depth:N query, or --depth N option, or just -N, balance reports - will show accounts only to the specified depth, hiding the deeper sub- - accounts. Account balances at the depth limit always include the bal- - ances from any hidden subaccounts (even in list mode). This can be + With a depth:N query, or --depth N option, or just -N, balance reports + will show accounts only to the specified depth, hiding the deeper sub- + accounts. Account balances at the depth limit always include the bal- + ances from any hidden subaccounts (even in list mode). This can be useful for getting an overview. Eg, limiting to depth 1: $ hledger balance -N -1 @@ -1845,7 +1873,7 @@ COMMANDS $-2 income $1 liabilities - You can also hide top-level account name parts, using --drop N. This + You can also hide top-level account name parts, using --drop N. This can be useful for hiding repetitive top-level account names: $ hledger bal expenses --drop 1 @@ -1856,9 +1884,9 @@ COMMANDS Multi-period balance report - With a report interval (set by the -D/--daily, -W/--weekly, - -M/--monthly, -Q/--quarterly, -Y/--yearly, or -p/--period flag), bal- - ance shows a tabular report, with columns representing successive time + With a report interval (set by the -D/--daily, -W/--weekly, + -M/--monthly, -Q/--quarterly, -Y/--yearly, or -p/--period flag), bal- + ance shows a tabular report, with columns representing successive time periods (and a title): $ hledger balance --quarterly income expenses -E @@ -1879,21 +1907,21 @@ COMMANDS encompass the displayed subperiods (so that the first and last subpe- riods have the same duration as the others). - o Leading and trailing periods (columns) containing all zeroes are not + o Leading and trailing periods (columns) containing all zeroes are not shown, unless -E/--empty is used. - o Accounts (rows) containing all zeroes are not shown, unless + o Accounts (rows) containing all zeroes are not shown, unless -E/--empty is used. - o Amounts with many commodities are shown in abbreviated form, unless + o Amounts with many commodities are shown in abbreviated form, unless --no-elide is used. (experimental) - o Average and/or total columns can be added with the -A/--average and + o Average and/or total columns can be added with the -A/--average and -T/--row-total flags. o The --transpose flag can be used to exchange rows and columns. - o The --pivot FIELD option causes a different transaction field to be + o The --pivot FIELD option causes a different transaction field to be used as "account name". See PIVOTING. Multi-period reports with many periods can be too wide for easy viewing @@ -1907,29 +1935,29 @@ COMMANDS o Reduce the terminal's font size - o View with a pager like less, eg: hledger bal -D --color=yes | less + o View with a pager like less, eg: hledger bal -D --color=yes | less -RS - o Output as CSV and use a CSV viewer like visidata (hledger bal -D -O - csv | vd -f csv), Emacs' csv-mode (M-x csv-mode, C-c C-a), or a + o Output as CSV and use a CSV viewer like visidata (hledger bal -D -O + csv | vd -f csv), Emacs' csv-mode (M-x csv-mode, C-c C-a), or a spreadsheet (hledger bal -D -o a.csv && open a.csv) - o Output as HTML and view with a browser: hledger bal -D -o a.html && + o Output as HTML and view with a browser: hledger bal -D -o a.html && open a.html Sorting by amount - With -S/--sort-amount, accounts with the largest (most positive) bal- - ances are shown first. Eg: hledger bal expenses -MAS shows your big- + With -S/--sort-amount, accounts with the largest (most positive) bal- + ances are shown first. Eg: hledger bal expenses -MAS shows your big- gest averaged monthly expenses first. - Revenues and liability balances are typically negative, however, so -S - shows these in reverse order. To work around this, you can add - --invert to flip the signs. (Or, use one of the higher-level reports, - which flip the sign automatically. Eg: hledger incomestatement -MAS). + Revenues and liability balances are typically negative, however, so -S + shows these in reverse order. To work around this, you can add + --invert to flip the signs. (Or, use one of the higher-level reports, + which flip the sign automatically. Eg: hledger incomestatement -MAS). Percentages - With -%/--percent, balance reports show each account's value expressed + With -%/--percent, balance reports show each account's value expressed as a percentage of the (column) total: $ hledger bal expenses -Q -% @@ -1943,62 +1971,62 @@ COMMANDS || 0 100.0 % 0 0 Note it is not useful to calculate percentages if the amounts in a col- - umn have mixed signs. In this case, make a separate report for each + umn have mixed signs. In this case, make a separate report for each sign, eg: $ hledger bal -% amt:`>0` $ hledger bal -% amt:`<0` - Similarly, if the amounts in a column have mixed commodities, convert - them to one commodity with -B, -V, -X or --value, or make a separate + Similarly, if the amounts in a column have mixed commodities, convert + them to one commodity with -B, -V, -X or --value, or make a separate report for each commodity: $ hledger bal -% cur:\\$ $ hledger bal -% cur:EUR Balance change, end balance - It's important to be clear on the meaning of the numbers shown in bal- + It's important to be clear on the meaning of the numbers shown in bal- ance reports. Here is some terminology we use: - A balance change is the net amount added to, or removed from, an + A balance change is the net amount added to, or removed from, an account during some period. - An end balance is the amount accumulated in an account as of some date - (and some time, but hledger doesn't store that; assume end of day in + An end balance is the amount accumulated in an account as of some date + (and some time, but hledger doesn't store that; assume end of day in your timezone). It is the sum of previous balance changes. - We call it a historical end balance if it includes all balance changes + We call it a historical end balance if it includes all balance changes since the account was created. For a real world account, this means it - will match the "historical record", eg the balances reported in your + will match the "historical record", eg the balances reported in your bank statements or bank web UI. (If they are correct!) - In general, balance changes are what you want to see when reviewing + In general, balance changes are what you want to see when reviewing revenues and expenses, and historical end balances are what you want to see when reviewing or reconciling asset, liability and equity accounts. - balance shows balance changes by default. To see accurate historical + balance shows balance changes by default. To see accurate historical end balances: - 1. Initialise account starting balances with an "opening balances" - transaction (a transfer from equity to the account), unless the + 1. Initialise account starting balances with an "opening balances" + transaction (a transfer from equity to the account), unless the journal covers the account's full lifetime. 2. Include all of of the account's prior postings in the report, by not - specifying a report start date, or by using the -H/--historical + specifying a report start date, or by using the -H/--historical flag. (-H causes report start date to be ignored when summing post- ings.) Balance report types For more flexible reporting, there are three important option groups: - hledger balance [CALCULATIONTYPE] [ACCUMULATIONTYPE] [VALUATIONTYPE] + hledger balance [CALCULATIONTYPE] [ACCUMULATIONTYPE] [VALUATIONTYPE] ... - The first two are the most important: calculation type selects the - basic calculation to perform for each table cell, while accumulation + The first two are the most important: calculation type selects the + basic calculation to perform for each table cell, while accumulation type says which postings should be included in each cell's calculation. - Typically one or both of these are selected by default, so you don't - need to write them explicitly. A valuation type can be added if you + Typically one or both of these are selected by default, so you don't + need to write them explicitly. A valuation type can be added if you want to convert the basic report to value or cost. Calculation type: @@ -2012,20 +2040,20 @@ COMMANDS ues Accumulation type: - Which postings should be included in each cell's calculation. It is + Which postings should be included in each cell's calculation. It is one of: - o --change : postings from column start to column end, ie within the - cell's period. Typically used to see revenues/expenses. (default + o --change : postings from column start to column end, ie within the + cell's period. Typically used to see revenues/expenses. (default for balance, incomestatement) - o --cumulative : postings from report start to column end, eg to show + o --cumulative : postings from report start to column end, eg to show changes accumulated since the report's start date. Rarely used. - o --historical/-H : postings from journal start to column end, ie all + o --historical/-H : postings from journal start to column end, ie all postings from account creation to the end of the cell's period. Typ- ically used to see historical end balances of assets/liabili- - ties/equity. (default for balancesheet, balancesheetequity, cash- + ties/equity. (default for balancesheet, balancesheetequity, cash- flow) Valuation type: @@ -2038,7 +2066,7 @@ COMMANDS o --value=then[,COMM] : show value at transaction dates - o --value=end[,COMM] : show value at period end date(s) (default with + o --value=end[,COMM] : show value at period end date(s) (default with --valuechange) o --value=now[,COMM] : show value at today's date @@ -2047,13 +2075,13 @@ COMMANDS or one of their aliases: --cost/-B, --market/-V or --exchange/-X. - Most combinations of these options should produce reasonable reports, - but if you find any that seem wrong or misleading, let us know. The + Most combinations of these options should produce reasonable reports, + but if you find any that seem wrong or misleading, let us know. The following restrictions are applied: o --valuechange implies --value=end - o --valuechange makes --change the default when used with the bal- + o --valuechange makes --change the default when used with the bal- ancesheet/balancesheetequity commands o --cumulative or --historical disables --row-total/-T @@ -2069,16 +2097,16 @@ COMMANDS v ------------------------------------------------------------------------------------ --change change in period sum of posting- period-end DATE-value of - date market val- value of change change in + date market val- value of change change in ues in period in period period --cumu- change from sum of posting- period-end DATE-value of - lative report start to date market val- value of change change from + lative report start to date market val- value of change change from period end ues from report from report report start start to period start to period to period end end end --his- change from sum of posting- period-end DATE-value of - torical journal start to date market val- value of change change from - /-H period end (his- ues from journal from journal journal start + torical journal start to date market val- value of change change from + /-H period end (his- ues from journal from journal journal start torical end bal- start to period start to period to period end ance) end end @@ -2086,25 +2114,25 @@ COMMANDS Some frequently used balance options/reports are: o bal -M revenues expenses - Show revenues/expenses in each month. Also available as the incomes- + Show revenues/expenses in each month. Also available as the incomes- tatement command. o bal -M -H assets liabilities - Show historical asset/liability balances at each month end. Also + Show historical asset/liability balances at each month end. Also available as the balancesheet command. o bal -M -H assets liabilities equity - Show historical asset/liability/equity balances at each month end. + Show historical asset/liability/equity balances at each month end. Also available as the balancesheetequity command. o bal -M assets not:receivable - Show changes to liquid assets in each month. Also available as the + Show changes to liquid assets in each month. Also available as the cashflow command. Also: o bal -M expenses -2 -SA - Show monthly expenses summarised to depth 2 and sorted by average + Show monthly expenses summarised to depth 2 and sorted by average amount. o bal -M --budget expenses @@ -2118,12 +2146,12 @@ COMMANDS Show top gainers [or losers] last week Budget report - The --budget report type activates extra columns showing any budget - goals for each account and period. The budget goals are defined by - periodic transactions. This is very useful for comparing planned and + The --budget report type activates extra columns showing any budget + goals for each account and period. The budget goals are defined by + periodic transactions. This is very useful for comparing planned and actual income, expenses, time usage, etc. - For example, you can take average monthly expenses in the common + For example, you can take average monthly expenses in the common expense categories to construct a minimal monthly budget: ;; Budget @@ -2170,26 +2198,26 @@ COMMANDS This is different from a normal balance report in several ways: - o Only accounts with budget goals during the report period are shown, + o Only accounts with budget goals during the report period are shown, by default. - o In each column, in square brackets after the actual amount, budget - goal amounts are shown, and the actual/goal percentage. (Note: bud- + o In each column, in square brackets after the actual amount, budget + goal amounts are shown, and the actual/goal percentage. (Note: bud- get goals should be in the same commodity as the actual amount.) - o All parent accounts are always shown, even in list mode. Eg assets, + o All parent accounts are always shown, even in list mode. Eg assets, assets:bank, and expenses above. - o Amounts always include all subaccounts, budgeted or unbudgeted, even + o Amounts always include all subaccounts, budgeted or unbudgeted, even in list mode. This means that the numbers displayed will not always add up! Eg above, - the expenses actual amount includes the gifts and supplies transac- - tions, but the expenses:gifts and expenses:supplies accounts are not + the expenses actual amount includes the gifts and supplies transac- + tions, but the expenses:gifts and expenses:supplies accounts are not shown, as they have no budget amounts declared. - This can be confusing. When you need to make things clearer, use the - -E/--empty flag, which will reveal all accounts including unbudgeted + This can be confusing. When you need to make things clearer, use the + -E/--empty flag, which will reveal all accounts including unbudgeted ones, giving the full picture. Eg: $ hledger balance -M --budget --empty @@ -2231,12 +2259,12 @@ COMMANDS For more examples and notes, see Budgeting. Budget report start date - This might be a bug, but for now: when making budget reports, it's a + This might be a bug, but for now: when making budget reports, it's a good idea to explicitly set the report's start date to the first day of - a reporting period, because a periodic rule like ~ monthly generates - its transactions on the 1st of each month, and if your journal has no - regular transactions on the 1st, the default report start date could - exclude that budget goal, which can be a little surprising. Eg here + a reporting period, because a periodic rule like ~ monthly generates + its transactions on the 1st of each month, and if your journal has no + regular transactions on the 1st, the default report start date could + exclude that budget goal, which can be a little surprising. Eg here the default report period is just the day of 2020-01-15: ~ monthly in 2020 @@ -2255,9 +2283,9 @@ COMMANDS --------------++------------ || $400 - To avoid this, specify the budget report's period, or at least the - start date, with -b/-e/-p/date:, to ensure it includes the budget goal - transactions (periodic transactions) that you want. Eg, adding -b + To avoid this, specify the budget report's period, or at least the + start date, with -b/-e/-p/date:, to ensure it includes the budget goal + transactions (periodic transactions) that you want. Eg, adding -b 2020/1/1 to the above: $ hledger bal expenses --budget -b 2020/1/1 @@ -2270,12 +2298,12 @@ COMMANDS || $400 [80% of $500] Nested budgets - You can add budgets to any account in your account hierarchy. If you + You can add budgets to any account in your account hierarchy. If you have budgets on both parent account and some of its children, then bud- - get(s) of the child account(s) would be added to the budget of their + get(s) of the child account(s) would be added to the budget of their parent, much like account balances behave. - In the most simple case this means that once you add a budget to any + In the most simple case this means that once you add a budget to any account, all its parents would have budget as well. To illustrate this, consider the following budget: @@ -2285,13 +2313,13 @@ COMMANDS expenses:personal:electronics $100.00 liabilities - With this, monthly budget for electronics is defined to be $100 and - budget for personal expenses is an additional $1000, which implicitly + With this, monthly budget for electronics is defined to be $100 and + budget for personal expenses is an additional $1000, which implicitly means that budget for both expenses:personal and expenses is $1100. - Transactions in expenses:personal:electronics will be counted both - towards its $100 budget and $1100 of expenses:personal , and transac- - tions in any other subaccount of expenses:personal would be counted + Transactions in expenses:personal:electronics will be counted both + towards its $100 budget and $1100 of expenses:personal , and transac- + tions in any other subaccount of expenses:personal would be counted towards only towards the budget of expenses:personal. For example, let's consider these transactions: @@ -2317,9 +2345,9 @@ COMMANDS expenses:personal $30.00 liabilities - As you can see, we have transactions in expenses:personal:electron- - ics:upgrades and expenses:personal:train tickets, and since both of - these accounts are without explicitly defined budget, these transac- + As you can see, we have transactions in expenses:personal:electron- + ics:upgrades and expenses:personal:train tickets, and since both of + these accounts are without explicitly defined budget, these transac- tions would be counted towards budgets of expenses:personal:electronics and expenses:personal accordingly: @@ -2335,7 +2363,7 @@ COMMANDS -------------------------------++------------------------------- || 0 [ 0] - And with --empty, we can get a better picture of budget allocation and + And with --empty, we can get a better picture of budget allocation and consumption: $ hledger balance --budget -M --empty @@ -2354,7 +2382,7 @@ COMMANDS Customising single-period balance reports For single-period balance reports displayed in the terminal (only), you - can use --format FMT to customise the format and content of each line. + can use --format FMT to customise the format and content of each line. Eg: $ hledger balance --format "%20(account) %12(total)" @@ -2372,7 +2400,7 @@ COMMANDS 0 The FMT format string (plus a newline) specifies the formatting applied - to each account/balance pair. It may contain any suitable text, with + to each account/balance pair. It may contain any suitable text, with data fields interpolated like so: %[MIN][.MAX](FIELDNAME) @@ -2383,14 +2411,14 @@ COMMANDS o FIELDNAME must be enclosed in parentheses, and can be one of: - o depth_spacer - a number of spaces equal to the account's depth, or + o depth_spacer - a number of spaces equal to the account's depth, or if MIN is specified, MIN * depth spaces. o account - the account's name o total - the account's balance/posted total, right justified - Also, FMT can begin with an optional prefix to control how multi-com- + Also, FMT can begin with an optional prefix to control how multi-com- modity amounts are rendered: o %_ - render on multiple lines, bottom-aligned (the default) @@ -2399,34 +2427,34 @@ COMMANDS o %, - render on one line, comma-separated - There are some quirks. Eg in one-line mode, %(depth_spacer) has no - effect, instead %(account) has indentation built in. Experimentation + There are some quirks. Eg in one-line mode, %(depth_spacer) has no + effect, instead %(account) has indentation built in. Experimentation may be needed to get pleasing results. Some example formats: o %(total) - the account's total - o %-20.20(account) - the account's name, left justified, padded to 20 + o %-20.20(account) - the account's name, left justified, padded to 20 characters and clipped at 20 characters - o %,%-50(account) %25(total) - account name padded to 50 characters, - total padded to 20 characters, with multiple commodities rendered on + o %,%-50(account) %25(total) - account name padded to 50 characters, + total padded to 20 characters, with multiple commodities rendered on one line - o %20(total) %2(depth_spacer)%-(account) - the default format for the + o %20(total) %2(depth_spacer)%-(account) - the default format for the single-column balance report balancesheet balancesheet, bs - This command displays a balance sheet, showing historical ending bal- + This command displays a balance sheet, showing historical ending bal- ances of asset and liability accounts. (To see equity as well, use the - balancesheetequity command.) Amounts are shown with normal positive + balancesheetequity command.) Amounts are shown with normal positive sign, as in conventional financial statements. The asset and liability accounts shown are those accounts declared with - the Asset or Cash or Liability type, or otherwise all accounts under a - top-level asset or liability account (case insensitive, plurals + the Asset or Cash or Liability type, or otherwise all accounts under a + top-level asset or liability account (case insensitive, plurals allowed). Example: @@ -2451,23 +2479,23 @@ COMMANDS 0 This command is a higher-level variant of the balance command, and sup- - ports many of that command's features, such as multi-period reports. - It is similar to hledger balance -H assets liabilities, but with - smarter account detection, and liabilities displayed with their sign + ports many of that command's features, such as multi-period reports. + It is similar to hledger balance -H assets liabilities, but with + smarter account detection, and liabilities displayed with their sign flipped. - This command also supports the output destination and output format - options The output formats supported are txt, csv, html, and (experi- + This command also supports the output destination and output format + options The output formats supported are txt, csv, html, and (experi- mental) json. balancesheetequity balancesheetequity, bse - This command displays a balance sheet, showing historical ending bal- - ances of asset, liability and equity accounts. Amounts are shown with + This command displays a balance sheet, showing historical ending bal- + ances of asset, liability and equity accounts. Amounts are shown with normal positive sign, as in conventional financial statements. - The asset, liability and equity accounts shown are those accounts - declared with the Asset, Cash, Liability or Equity type, or otherwise + The asset, liability and equity accounts shown are those accounts + declared with the Asset, Cash, Liability or Equity type, or otherwise all accounts under a top-level asset, liability or equity account (case insensitive, plurals allowed). @@ -2498,24 +2526,24 @@ COMMANDS 0 This command is a higher-level variant of the balance command, and sup- - ports many of that command's features, such as multi-period reports. + ports many of that command's features, such as multi-period reports. It is similar to hledger balance -H assets liabilities equity, but with - smarter account detection, and liabilities/equity displayed with their + smarter account detection, and liabilities/equity displayed with their sign flipped. - This command also supports the output destination and output format - options The output formats supported are txt, csv, html, and (experi- + This command also supports the output destination and output format + options The output formats supported are txt, csv, html, and (experi- mental) json. cashflow cashflow, cf - This command displays a cashflow statement, showing the inflows and - outflows affecting "cash" (ie, liquid) assets. Amounts are shown with + This command displays a cashflow statement, showing the inflows and + outflows affecting "cash" (ie, liquid) assets. Amounts are shown with normal positive sign, as in conventional financial statements. - The "cash" accounts shown are those accounts declared with the Cash - type, or otherwise all accounts under a top-level asset account (case - insensitive, plural allowed) which do not have fixed, investment, + The "cash" accounts shown are those accounts declared with the Cash + type, or otherwise all accounts under a top-level asset account (case + insensitive, plural allowed) which do not have fixed, investment, receivable or A/R in their name. Example: @@ -2535,22 +2563,22 @@ COMMANDS $-1 This command is a higher-level variant of the balance command, and sup- - ports many of that command's features, such as multi-period reports. - It is similar to hledger balance assets not:fixed not:investment + ports many of that command's features, such as multi-period reports. + It is similar to hledger balance assets not:fixed not:investment not:receivable, but with smarter account detection. - This command also supports the output destination and output format - options The output formats supported are txt, csv, html, and (experi- + This command also supports the output destination and output format + options The output formats supported are txt, csv, html, and (experi- mental) json. check check Check for various kinds of errors in your data. - hledger provides a number of built-in error checks to help prevent - problems in your data. Some of these are run automatically; or, you - can use this check command to run them on demand, with no output and a - zero exit code if all is well. Specify their names (or a prefix) as + hledger provides a number of built-in error checks to help prevent + problems in your data. Some of these are run automatically; or, you + can use this check command to run them on demand, with no output and a + zero exit code if all is well. Specify their names (or a prefix) as argument(s). Some examples: @@ -2567,16 +2595,16 @@ COMMANDS o parseable - data files are well-formed and can be successfully parsed - o autobalanced - all transactions are balanced, inferring missing - amounts where necessary, and possibly converting commodities using + o autobalanced - all transactions are balanced, inferring missing + amounts where necessary, and possibly converting commodities using transaction prices or automatically-inferred transaction prices - o assertions - all balance assertions in the journal are passing. + o assertions - all balance assertions in the journal are passing. (This check can be disabled with -I/--ignore-assertions.) Strict checks These additional checks are run when the -s/--strict (strict mode) flag - is used. Or, they can be run by giving their names as arguments to + is used. Or, they can be run by giving their names as arguments to check: o accounts - all account names used by transactions have been declared @@ -2584,24 +2612,24 @@ COMMANDS o commodities - all commodity symbols used have been declared Other checks - These checks can be run only by giving their names as arguments to - check. They are more specialised and not desirable for everyone, + These checks can be run only by giving their names as arguments to + check. They are more specialised and not desirable for everyone, therefore optional: - o ordereddates - transactions are ordered by date in each file + o ordereddates - transactions are ordered by date within each file o payees - all payees used by transactions have been declared o uniqueleafnames - all account leaf names are unique Custom checks - A few more checks are are available as separate add-on commands, in + A few more checks are are available as separate add-on commands, in https://github.com/simonmichael/hledger/tree/master/bin: - o hledger-check-tagfiles - all tag values containing / (a forward + o hledger-check-tagfiles - all tag values containing / (a forward slash) exist as file paths - o hledger-check-fancyassertions - more complex balance assertions are + o hledger-check-fancyassertions - more complex balance assertions are passing You could make similar scripts to perform your own custom checks. See: @@ -2609,64 +2637,64 @@ COMMANDS close close, equity - Prints a "closing balances" transaction and an "opening balances" + Prints a "closing balances" transaction and an "opening balances" transaction that bring account balances to and from zero, respectively. These can be added to your journal file(s), eg to bring asset/liability - balances forward into a new journal file, or to close out rev- + balances forward into a new journal file, or to close out rev- enues/expenses to retained earnings at the end of a period. - You can print just one of these transactions by using the --close or - --open flag. You can customise their descriptions with the --close- + You can print just one of these transactions by using the --close or + --open flag. You can customise their descriptions with the --close- desc and --open-desc options. One amountless posting to "equity:opening/closing balances" is added to - balance the transactions, by default. You can customise this account - name with --close-acct and --open-acct; if you specify only one of + balance the transactions, by default. You can customise this account + name with --close-acct and --open-acct; if you specify only one of these, it will be used for both. With --x/--explicit, the equity posting's amount will be shown. And if - it involves multiple commodities, a posting for each commodity will be + it involves multiple commodities, a posting for each commodity will be shown, as with the print command. - With --interleaved, the equity postings are shown next to the postings + With --interleaved, the equity postings are shown next to the postings they balance, which makes troubleshooting easier. By default, transaction prices in the journal are ignored when generat- - ing the closing/opening transactions. With --show-costs, this cost - information is preserved (balance -B reports will be unchanged after + ing the closing/opening transactions. With --show-costs, this cost + information is preserved (balance -B reports will be unchanged after the transition). Separate postings are generated for each cost in each - commodity. Note this can generate very large journal entries, if you + commodity. Note this can generate very large journal entries, if you have many foreign currency or investment transactions. close usage If you split your journal files by time (eg yearly), you will typically - run this command at the end of the year, and save the closing transac- - tion as last entry of the old file, and the opening transaction as the - first entry of the new file. This makes the files self contained, so - that correct balances are reported no matter which of them are loaded. - Ie, if you load just one file, the balances are initialised correctly; - or if you load several files, the redundant closing/opening transac- - tions cancel each other out. (They will show up in print or register - reports; you can exclude them with a query like not:desc:'(open- + run this command at the end of the year, and save the closing transac- + tion as last entry of the old file, and the opening transaction as the + first entry of the new file. This makes the files self contained, so + that correct balances are reported no matter which of them are loaded. + Ie, if you load just one file, the balances are initialised correctly; + or if you load several files, the redundant closing/opening transac- + tions cancel each other out. (They will show up in print or register + reports; you can exclude them with a query like not:desc:'(open- ing|closing) balances'.) If you're running a business, you might also use this command to "close - the books" at the end of an accounting period, transferring income - statement account balances to retained earnings. (You may want to + the books" at the end of an accounting period, transferring income + statement account balances to retained earnings. (You may want to change the equity account name to something like "equity:retained earn- ings".) - By default, the closing transaction is dated yesterday, the balances - are calculated as of end of yesterday, and the opening transaction is - dated today. To close on some other date, use: hledger close -e OPEN- - INGDATE. Eg, to close/open on the 2018/2019 boundary, use -e 2019. + By default, the closing transaction is dated yesterday, the balances + are calculated as of end of yesterday, and the opening transaction is + dated today. To close on some other date, use: hledger close -e OPEN- + INGDATE. Eg, to close/open on the 2018/2019 boundary, use -e 2019. You can also use -p or date:PERIOD (any starting date is ignored). Both transactions will include balance assertions for the - closed/reopened accounts. You probably shouldn't use status or real- - ness filters (like -C or -R or status:) with this command, or the gen- + closed/reopened accounts. You probably shouldn't use status or real- + ness filters (like -C or -R or status:) with this command, or the gen- erated balance assertions will depend on these flags. Likewise, if you - run this command with --auto, the balance assertions will probably + run this command with --auto, the balance assertions will probably always require --auto. Examples: @@ -2707,13 +2735,13 @@ COMMANDS codes List the codes seen in transactions, in the order parsed. - This command prints the value of each transaction's code field, in the - order transactions were parsed. The transaction code is an optional - value written in parentheses between the date and description, often + This command prints the value of each transaction's code field, in the + order transactions were parsed. The transaction code is an optional + value written in parentheses between the date and description, often used to store a cheque number, order number or similar. Transactions aren't required to have a code, and missing or empty codes - will not be shown by default. With the -E/--empty flag, they will be + will not be shown by default. With the -E/--empty flag, they will be printed as blank lines. You can add a query to select a subset of transactions. @@ -2753,7 +2781,7 @@ COMMANDS List the unique descriptions that appear in transactions. This command lists the unique descriptions that appear in transactions, - in alphabetic order. You can add a query to select a subset of trans- + in alphabetic order. You can add a query to select a subset of trans- actions. Example: @@ -2765,18 +2793,18 @@ COMMANDS diff diff - Compares a particular account's transactions in two input files. It + Compares a particular account's transactions in two input files. It shows any transactions to this account which are in one file but not in the other. More precisely, for each posting affecting this account in either file, - it looks for a corresponding posting in the other file which posts the - same amount to the same account (ignoring date, description, etc.) + it looks for a corresponding posting in the other file which posts the + same amount to the same account (ignoring date, description, etc.) Since postings not transactions are compared, this also works when mul- tiple bank transactions have been combined into a single journal entry. This is useful eg if you have downloaded an account's transactions from - your bank (eg as CSV data). When hledger and your bank disagree about + your bank (eg as CSV data). When hledger and your bank disagree about the account balance, you can compare the bank data with your journal to find out the cause. @@ -2794,18 +2822,18 @@ COMMANDS files files - List all files included in the journal. With a REGEX argument, only - file names matching the regular expression (case sensitive) are shown. + List all files included in the journal. With a REGEX argument, only + file names matching the regular expression (case sensitive) are shown. help help - Show the hledger user manual in one of several formats, optionally - positioned at a given TOPIC (if possible). TOPIC is any heading, or - heading prefix, in the manual. Some examples: commands, print, 'auto + Show the hledger user manual in one of several formats, optionally + positioned at a given TOPIC (if possible). TOPIC is any heading, or + heading prefix, in the manual. Some examples: commands, print, 'auto postings', periodic. - This command shows the user manual built in to this hledger version. - It can be useful if the correct version of the hledger manual, or the + This command shows the user manual built in to this hledger version. + It can be useful if the correct version of the hledger manual, or the usual viewing tools, are not installed on your system. By default it uses the best viewer it can find in $PATH, in this order: @@ -2815,66 +2843,66 @@ COMMANDS import import - Read new transactions added to each FILE since last run, and add them - to the main journal file. Or with --dry-run, just print the transac- - tions that would be added. Or with --catchup, just mark all of the + Read new transactions added to each FILE since last run, and add them + to the main journal file. Or with --dry-run, just print the transac- + tions that would be added. Or with --catchup, just mark all of the FILEs' transactions as imported, without actually importing any. - Unlike other hledger commands, with import the journal file is an out- + Unlike other hledger commands, with import the journal file is an out- put file, and will be modified, though only by appending (existing data - will not be changed). The input files are specified as arguments, so - to import one or more CSV files to your main journal, you will run + will not be changed). The input files are specified as arguments, so + to import one or more CSV files to your main journal, you will run hledger import bank.csv or perhaps hledger import *.csv. Note you can import from any file format, though CSV files are the most common import source, and these docs focus on that case. Deduplication - As a convenience import does deduplication while reading transactions. + As a convenience import does deduplication while reading transactions. This does not mean "ignore transactions that look the same", but rather "ignore transactions that have been seen before". This is intended for - when you are periodically importing foreign data which may contain - already-imported transactions. So eg, if every day you download bank - CSV files containing redundant data, you can safely run hledger import - bank.csv and only new transactions will be imported. (import is idem- + when you are periodically importing foreign data which may contain + already-imported transactions. So eg, if every day you download bank + CSV files containing redundant data, you can safely run hledger import + bank.csv and only new transactions will be imported. (import is idem- potent.) - Since the items being read (CSV records, eg) often do not come with - unique identifiers, hledger detects new transactions by date, assuming + Since the items being read (CSV records, eg) often do not come with + unique identifiers, hledger detects new transactions by date, assuming that: 1. new items always have the newest dates 2. item dates do not change across reads - 3. and items with the same date remain in the same relative order + 3. and items with the same date remain in the same relative order across reads. - These are often true of CSV files representing transactions, or true - enough so that it works pretty well in practice. 1 is important, but + These are often true of CSV files representing transactions, or true + enough so that it works pretty well in practice. 1 is important, but violations of 2 and 3 amongst the old transactions won't matter (and if - you import often, the new transactions will be few, so less likely to + you import often, the new transactions will be few, so less likely to be the ones affected). - hledger remembers the latest date processed in each input file by sav- + hledger remembers the latest date processed in each input file by sav- ing a hidden ".latest" state file in the same directory. Eg when read- - ing finance/bank.csv, it will look for and update the finance/.lat- - est.bank.csv state file. The format is simple: one or more lines con- - taining the same ISO-format date (YYYY-MM-DD), meaning "I have pro- - cessed transactions up to this date, and this many of them on that + ing finance/bank.csv, it will look for and update the finance/.lat- + est.bank.csv state file. The format is simple: one or more lines con- + taining the same ISO-format date (YYYY-MM-DD), meaning "I have pro- + cessed transactions up to this date, and this many of them on that date." Normally you won't see or manipulate these state files yourself. - But if needed, you can delete them to reset the state (making all - transactions "new"), or you can construct them to "catch up" to a cer- + But if needed, you can delete them to reset the state (making all + transactions "new"), or you can construct them to "catch up" to a cer- tain date. - Note deduplication (and updating of state files) can also be done by + Note deduplication (and updating of state files) can also be done by print --new, but this is less often used. Import testing - With --dry-run, the transactions that will be imported are printed to + With --dry-run, the transactions that will be imported are printed to the terminal, without updating your journal or state files. The output - is valid journal format, like the print command, so you can re-parse - it. Eg, to see any importable transactions which CSV rules have not + is valid journal format, like the print command, so you can re-parse + it. Eg, to see any importable transactions which CSV rules have not categorised: $ hledger import --dry bank.csv | hledger -f- -I print unknown @@ -2884,17 +2912,17 @@ COMMANDS $ ls bank.csv* | entr bash -c 'echo ====; hledger import --dry bank.csv | hledger -f- -I print unknown' Importing balance assignments - Entries added by import will have their posting amounts made explicit - (like hledger print -x). This means that any balance assignments in - imported files must be evaluated; but, imported files don't get to see - the main file's account balances. As a result, importing entries with + Entries added by import will have their posting amounts made explicit + (like hledger print -x). This means that any balance assignments in + imported files must be evaluated; but, imported files don't get to see + the main file's account balances. As a result, importing entries with balance assignments (eg from an institution that provides only balances - and not posting amounts) will probably generate incorrect posting + and not posting amounts) will probably generate incorrect posting amounts. To avoid this problem, use print instead of import: $ hledger print IMPORTFILE [--new] >> $LEDGER_FILE - (If you think import should leave amounts implicit like print does, + (If you think import should leave amounts implicit like print does, please test it and send a pull request.) Commodity display styles @@ -2905,12 +2933,12 @@ COMMANDS incomestatement, is This command displays an income statement, showing revenues and - expenses during one or more periods. Amounts are shown with normal + expenses during one or more periods. Amounts are shown with normal positive sign, as in conventional financial statements. The revenue and expense accounts shown are those accounts declared with - the Revenue or Expense type, or otherwise all accounts under a top- - level revenue or income or expense account (case insensitive, plurals + the Revenue or Expense type, or otherwise all accounts under a top- + level revenue or income or expense account (case insensitive, plurals allowed). Example: @@ -2937,22 +2965,22 @@ COMMANDS 0 This command is a higher-level variant of the balance command, and sup- - ports many of that command's features, such as multi-period reports. + ports many of that command's features, such as multi-period reports. It is similar to hledger balance '(revenues|income)' expenses, but with - smarter account detection, and revenues/income displayed with their + smarter account detection, and revenues/income displayed with their sign flipped. - This command also supports the output destination and output format - options The output formats supported are txt, csv, html, and (experi- + This command also supports the output destination and output format + options The output formats supported are txt, csv, html, and (experi- mental) json. notes notes List the unique notes that appear in transactions. - This command lists the unique notes that appear in transactions, in - alphabetic order. You can add a query to select a subset of transac- - tions. The note is the part of the transaction description after a | + This command lists the unique notes that appear in transactions, in + alphabetic order. You can add a query to select a subset of transac- + tions. The note is the part of the transaction description after a | character (or if there is no |, the whole description). Example: @@ -2965,14 +2993,14 @@ COMMANDS payees List the unique payee/payer names that appear in transactions. - This command lists unique payee/payer names which have been declared - with payee directives (--declared), used in transaction descriptions + This command lists unique payee/payer names which have been declared + with payee directives (--declared), used in transaction descriptions (--used), or both (the default). - The payee/payer is the part of the transaction description before a | + The payee/payer is the part of the transaction description before a | character (or if there is no |, the whole description). - You can add query arguments to select a subset of transactions. This + You can add query arguments to select a subset of transactions. This implies --used. Example: @@ -2984,10 +3012,10 @@ COMMANDS prices prices - Print market price directives from the journal. With --costs, also - print synthetic market prices based on transaction prices. With + Print market price directives from the journal. With --costs, also + print synthetic market prices based on transaction prices. With --inverted-costs, also print inverse prices based on transaction - prices. Prices (and postings providing prices) can be filtered by a + prices. Prices (and postings providing prices) can be filtered by a query. Price amounts are always displayed with their full precision. print @@ -2997,17 +3025,17 @@ COMMANDS The print command displays full journal entries (transactions) from the journal file, sorted by date (or with --date2, by secondary date). - Amounts are shown mostly normalised to commodity display style, eg the - placement of commodity symbols will be consistent. All of their deci- + Amounts are shown mostly normalised to commodity display style, eg the + placement of commodity symbols will be consistent. All of their deci- mal places are shown, as in the original journal entry (with one alter- ation: in some cases trailing zeroes are added.) Amounts are shown right-aligned within each transaction (but not across all transactions). - Directives and inter-transaction comments are not shown, currently. + Directives and inter-transaction comments are not shown, currently. This means the print command is somewhat lossy, and if you are using it - to reformat your journal you should take care to also copy over the + to reformat your journal you should take care to also copy over the directives and file-level comments. Eg: @@ -3034,7 +3062,7 @@ COMMANDS liabilities:debts $1 assets:bank:checking $-1 - print's output is usually a valid hledger journal, and you can process + print's output is usually a valid hledger journal, and you can process it again with a second hledger command. This can be useful for certain kinds of search, eg: @@ -3044,39 +3072,39 @@ COMMANDS There are some situations where print's output can become unparseable: - o Valuation affects posting amounts but not balance assertion or bal- + o Valuation affects posting amounts but not balance assertion or bal- ance assignment amounts, potentially causing those to fail. o Auto postings can generate postings with too many missing amounts. Normally, the journal entry's explicit or implicit amount style is pre- served. For example, when an amount is omitted in the journal, it will - not appear in the output. Similarly, when a transaction price is + not appear in the output. Similarly, when a transaction price is implied but not written, it will not appear in the output. You can use - the -x/--explicit flag to make all amounts and transaction prices - explicit, which can be useful for troubleshooting or for making your + the -x/--explicit flag to make all amounts and transaction prices + explicit, which can be useful for troubleshooting or for making your journal more readable and robust against data entry errors. -x is also implied by using any of -B,-V,-X,--value. - Note, -x/--explicit will cause postings with a multi-commodity amount - (these can arise when a multi-commodity transaction has an implicit - amount) to be split into multiple single-commodity postings, keeping + Note, -x/--explicit will cause postings with a multi-commodity amount + (these can arise when a multi-commodity transaction has an implicit + amount) to be split into multiple single-commodity postings, keeping the output parseable. - With -B/--cost, amounts with transaction prices are converted to cost + With -B/--cost, amounts with transaction prices are converted to cost using that price. This can be used for troubleshooting. - With -m/--match and a STR argument, print will show at most one trans- - action: the one one whose description is most similar to STR, and is - most recent. STR should contain at least two characters. If there is + With -m/--match and a STR argument, print will show at most one trans- + action: the one one whose description is most similar to STR, and is + most recent. STR should contain at least two characters. If there is no similar-enough match, no transaction will be shown. - With --new, hledger prints only transactions it has not seen on a pre- - vious run. This uses the same deduplication system as the import com- + With --new, hledger prints only transactions it has not seen on a pre- + vious run. This uses the same deduplication system as the import com- mand. (See import's docs for details.) - This command also supports the output destination and output format - options The output formats supported are txt, csv, and (experimental) + This command also supports the output destination and output format + options The output formats supported are txt, csv, and (experimental) json and sql. Here's an example of print's CSV output: @@ -3095,20 +3123,20 @@ COMMANDS "5","2008/12/31","","*","","pay off","","liabilities:debts","1","$","","1","","" "5","2008/12/31","","*","","pay off","","assets:bank:checking","-1","$","1","","","" - o There is one CSV record per posting, with the parent transaction's + o There is one CSV record per posting, with the parent transaction's fields repeated. o The "txnidx" (transaction index) field shows which postings belong to - the same transaction. (This number might change if transactions are - reordered within the file, files are parsed/included in a different + the same transaction. (This number might change if transactions are + reordered within the file, files are parsed/included in a different order, etc.) - o The amount is separated into "commodity" (the symbol) and "amount" + o The amount is separated into "commodity" (the symbol) and "amount" (numeric quantity) fields. o The numeric amount is repeated in either the "credit" or "debit" col- - umn, for convenience. (Those names are not accurate in the account- - ing sense; it just puts negative amounts under credit and zero or + umn, for convenience. (Those names are not accurate in the account- + ing sense; it just puts negative amounts under credit and zero or greater amounts under debit.) print-unique @@ -3132,14 +3160,14 @@ COMMANDS Show postings and their running total. The register command displays matched postings, across all accounts, in - date order, with their running total or running historical balance. - (See also the aregister command, which shows matched transactions in a + date order, with their running total or running historical balance. + (See also the aregister command, which shows matched transactions in a specific account.) register normally shows line per posting, but note that multi-commodity amounts will occupy multiple lines (one line per commodity). - It is typically used with a query selecting a particular account, to + It is typically used with a query selecting a particular account, to see that account's activity: $ hledger register checking @@ -3150,8 +3178,8 @@ COMMANDS With --date2, it shows and sorts by secondary date instead. - The --historical/-H flag adds the balance from any undisplayed prior - postings to the running total. This is useful when you want to see + The --historical/-H flag adds the balance from any undisplayed prior + postings to the running total. This is useful when you want to see only recent activity, with a historically accurate running balance: $ hledger register checking -b 2008/6 --historical @@ -3161,30 +3189,30 @@ COMMANDS The --depth option limits the amount of sub-account detail displayed. - The --average/-A flag shows the running average posting amount instead + The --average/-A flag shows the running average posting amount instead of the running total (so, the final number displayed is the average for - the whole report period). This flag implies --empty (see below). It - is affected by --historical. It works best when showing just one + the whole report period). This flag implies --empty (see below). It + is affected by --historical. It works best when showing just one account and one commodity. - The --related/-r flag shows the other postings in the transactions of + The --related/-r flag shows the other postings in the transactions of the postings which would normally be shown. - The --invert flag negates all amounts. For example, it can be used on + The --invert flag negates all amounts. For example, it can be used on an income account where amounts are normally displayed as negative num- - bers. It's also useful to show postings on the checking account + bers. It's also useful to show postings on the checking account together with the related account: $ hledger register --related --invert assets:checking - With a reporting interval, register shows summary postings, one per + With a reporting interval, register shows summary postings, one per interval, aggregating the postings to each account: $ hledger register --monthly income 2008/01 income:salary $-1 $-1 2008/06 income:gifts $-1 $-2 - Periods with no activity, and summary postings with a zero amount, are + Periods with no activity, and summary postings with a zero amount, are not shown by default; use the --empty/-E flag to see them: $ hledger register --monthly income -E @@ -3201,7 +3229,7 @@ COMMANDS 2008/11 0 $-2 2008/12 0 $-2 - Often, you'll want to see just one line per interval. The --depth + Often, you'll want to see just one line per interval. The --depth option helps with this, causing subaccounts to be aggregated: $ hledger register --monthly assets --depth 1h @@ -3209,19 +3237,19 @@ COMMANDS 2008/06 assets $-1 0 2008/12 assets $-1 $-1 - Note when using report intervals, if you specify start/end dates these - will be adjusted outward if necessary to contain a whole number of - intervals. This ensures that the first and last intervals are full + Note when using report intervals, if you specify start/end dates these + will be adjusted outward if necessary to contain a whole number of + intervals. This ensures that the first and last intervals are full length and comparable to the others in the report. Custom register output - register uses the full terminal width by default, except on windows. - You can override this by setting the COLUMNS environment variable (not + register uses the full terminal width by default, except on windows. + You can override this by setting the COLUMNS environment variable (not a bash shell variable) or by using the --width/-w option. - The description and account columns normally share the space equally - (about half of (width - 40) each). You can adjust this by adding a - description width as part of --width's argument, comma-separated: + The description and account columns normally share the space equally + (about half of (width - 40) each). You can adjust this by adding a + description width as part of --width's argument, comma-separated: --width W,D . Here's a diagram (won't display correctly in --help): <--------------------------------- width (W) ----------------------------------> @@ -3237,28 +3265,28 @@ COMMANDS $ hledger reg -w 100,40 # set overall width 100, description width 40 $ hledger reg -w $COLUMNS,40 # use terminal width, & description width 40 - This command also supports the output destination and output format - options The output formats supported are txt, csv, and (experimental) + This command also supports the output destination and output format + options The output formats supported are txt, csv, and (experimental) json. register-match register-match Print the one posting whose transaction description is closest to DESC, - in the style of the register command. If there are multiple equally - good matches, it shows the most recent. Query options (options, not - arguments) can be used to restrict the search space. Helps ledger- + in the style of the register command. If there are multiple equally + good matches, it shows the most recent. Query options (options, not + arguments) can be used to restrict the search space. Helps ledger- autosync detect already-seen transactions when importing. rewrite rewrite Print all transactions, rewriting the postings of matched transactions. - For now the only rewrite available is adding new postings, like print + For now the only rewrite available is adding new postings, like print --auto. This is a start at a generic rewriter of transaction entries. It reads - the default journal and prints the transactions, like print, but adds + the default journal and prints the transactions, like print, but adds one or more specified postings to any transactions matching QUERY. The - posting amounts can be fixed, or a multiplier of the existing transac- + posting amounts can be fixed, or a multiplier of the existing transac- tion's first posting amount. Examples: @@ -3274,7 +3302,7 @@ COMMANDS (reserve:grocery) *0.25 ; reserve 25% for grocery (reserve:) *0.25 ; reserve 25% for grocery - Note the single quotes to protect the dollar sign from bash, and the + Note the single quotes to protect the dollar sign from bash, and the two spaces between account and amount. More: @@ -3284,16 +3312,16 @@ COMMANDS $ hledger rewrite -- expenses:gifts --add-posting '(budget:gifts) *-1"' $ hledger rewrite -- ^income --add-posting '(budget:foreign currency) *0.25 JPY; diversify' - Argument for --add-posting option is a usual posting of transaction - with an exception for amount specification. More precisely, you can + Argument for --add-posting option is a usual posting of transaction + with an exception for amount specification. More precisely, you can use '*' (star symbol) before the amount to indicate that that this is a - factor for an amount of original matched posting. If the amount - includes a commodity name, the new posting amount will be in the new - commodity; otherwise, it will be in the matched posting amount's com- + factor for an amount of original matched posting. If the amount + includes a commodity name, the new posting amount will be in the new + commodity; otherwise, it will be in the matched posting amount's com- modity. Re-write rules in a file - During the run this tool will execute so called "Automated Transac- + During the run this tool will execute so called "Automated Transac- tions" found in any journal it process. I.e instead of specifying this operations in command line you can put them in a journal file. @@ -3308,7 +3336,7 @@ COMMANDS budget:gifts *-1 assets:budget *1 - Note that '=' (equality symbol) that is used instead of date in trans- + Note that '=' (equality symbol) that is used instead of date in trans- actions you usually write. It indicates the query by which you want to match the posting to add new ones. @@ -3321,12 +3349,12 @@ COMMANDS --add-posting 'assets:budget *1' \ > rewritten-tidy-output.journal - It is important to understand that relative order of such entries in - journal is important. You can re-use result of previously added post- + It is important to understand that relative order of such entries in + journal is important. You can re-use result of previously added post- ings. Diff output format - To use this tool for batch modification of your journal files you may + To use this tool for batch modification of your journal files you may find useful output in form of unified diff. $ hledger rewrite -- --diff -f examples/sample.journal '^income' --add-posting '(liabilities:tax) *.33' @@ -3350,10 +3378,10 @@ COMMANDS If you'll pass this through patch tool you'll get transactions contain- ing the posting that matches your query be updated. Note that multiple - files might be update according to list of input files specified via + files might be update according to list of input files specified via --file options and include directives inside of these files. - Be careful. Whole transaction being re-formatted in a style of output + Be careful. Whole transaction being re-formatted in a style of output from hledger print. See also: @@ -3361,70 +3389,70 @@ COMMANDS https://github.com/simonmichael/hledger/issues/99 rewrite vs. print --auto - This command predates print --auto, and currently does much the same + This command predates print --auto, and currently does much the same thing, but with these differences: - o with multiple files, rewrite lets rules in any file affect all other - files. print --auto uses standard directive scoping; rules affect + o with multiple files, rewrite lets rules in any file affect all other + files. print --auto uses standard directive scoping; rules affect only child files. - o rewrite's query limits which transactions can be rewritten; all are + o rewrite's query limits which transactions can be rewritten; all are printed. print --auto's query limits which transactions are printed. - o rewrite applies rules specified on command line or in the journal. + o rewrite applies rules specified on command line or in the journal. print --auto applies rules specified in the journal. roi roi - Shows the time-weighted (TWR) and money-weighted (IRR) rate of return + Shows the time-weighted (TWR) and money-weighted (IRR) rate of return on your investments. - At a minimum, you need to supply a query (which could be just an - account name) to select your investment(s) with --inv, and another + At a minimum, you need to supply a query (which could be just an + account name) to select your investment(s) with --inv, and another query to identify your profit and loss transactions with --pnl. - If you do not record changes in the value of your investment manually, - or do not require computation of time-weighted return (TWR), --pnl + If you do not record changes in the value of your investment manually, + or do not require computation of time-weighted return (TWR), --pnl could be an empty query (--pnl "" or --pnl STR where STR does not match any of your accounts). - This command will compute and display the internalized rate of return - (IRR) and time-weighted rate of return (TWR) for your investments for - the time period requested. Both rates of return are annualized before + This command will compute and display the internalized rate of return + (IRR) and time-weighted rate of return (TWR) for your investments for + the time period requested. Both rates of return are annualized before display, regardless of the length of reporting interval. - Price directives will be taken into account if you supply appropriate + Price directives will be taken into account if you supply appropriate --cost or --value flags (see VALUATION). Note, in some cases this report can fail, for these reasons: - o Error (NotBracketed): No solution for Internal Rate of Return (IRR). - Possible causes: IRR is huge (>1000000%), balance of investment + o Error (NotBracketed): No solution for Internal Rate of Return (IRR). + Possible causes: IRR is huge (>1000000%), balance of investment becomes negative at some point in time. - o Error (SearchFailed): Failed to find solution for Internal Rate of + o Error (SearchFailed): Failed to find solution for Internal Rate of Return (IRR). Either search does not converge to a solution, or con- verges too slowly. Examples: - o Using roi to compute total return of investment in stocks: + o Using roi to compute total return of investment in stocks: https://github.com/simonmichael/hledger/blob/master/examples/roi- unrealised.ledger o Cookbook -> Return on Investment Semantics of --inv and --pnl - Query supplied to --inv has to match all transactions that are related + Query supplied to --inv has to match all transactions that are related to your investment. Transactions not matching --inv will be ignored. In these transactions, ROI will conside postings that match --inv to be - "investment postings" and other postings (not matching --inv) will be - sorted into two categories: "cash flow" and "profit and loss", as ROI - needs to know which part of the investment value is your contributions + "investment postings" and other postings (not matching --inv) will be + sorted into two categories: "cash flow" and "profit and loss", as ROI + needs to know which part of the investment value is your contributions and which is due to the return on investment. - o "Cash flow" is depositing or withdrawing money, buying or selling + o "Cash flow" is depositing or withdrawing money, buying or selling assets, or otherwise converting between your investment commodity and any other commodity. Example: @@ -3442,12 +3470,12 @@ COMMANDS investment:snake oil = $57 equity:unrealized profit or loss - All non-investment postings are assumed to be "cash flow", unless they - match --pnl query. Changes in value of your investment due to "profit - and loss" postings will be considered as part of your investment + All non-investment postings are assumed to be "cash flow", unless they + match --pnl query. Changes in value of your investment due to "profit + and loss" postings will be considered as part of your investment return. - Example: if you use --inv snake --pnl equity:unrealized, then postings + Example: if you use --inv snake --pnl equity:unrealized, then postings in the example below would be classifed as: 2019-01-01 Snake Oil #1 @@ -3464,69 +3492,69 @@ COMMANDS snake oil $50 ; investment posting IRR and TWR explained - "ROI" stands for "return on investment". Traditionally this was com- - puted as a difference between current value of investment and its ini- + "ROI" stands for "return on investment". Traditionally this was com- + puted as a difference between current value of investment and its ini- tial value, expressed in percentage of the initial value. However, this approach is only practical in simple cases, where invest- - ments receives no in-flows or out-flows of money, and where rate of + ments receives no in-flows or out-flows of money, and where rate of growth is fixed over time. For more complex scenarios you need differ- - ent ways to compute rate of return, and this command implements two of + ent ways to compute rate of return, and this command implements two of them: IRR and TWR. - Internal rate of return, or "IRR" (also called "money-weighted rate of - return") takes into account effects of in-flows and out-flows. + Internal rate of return, or "IRR" (also called "money-weighted rate of + return") takes into account effects of in-flows and out-flows. Naively, if you are withdrawing from your investment, your future gains - would be smaller (in absolute numbers), and will be a smaller percent- - age of your initial investment, and if you are adding to your invest- - ment, you will receive bigger absolute gains (but probably at the same - rate of return). IRR is a way to compute rate of return for each + would be smaller (in absolute numbers), and will be a smaller percent- + age of your initial investment, and if you are adding to your invest- + ment, you will receive bigger absolute gains (but probably at the same + rate of return). IRR is a way to compute rate of return for each period between in-flow or out-flow of money, and then combine them in a - way that gives you a compound annual rate of return that investment is + way that gives you a compound annual rate of return that investment is expected to generate. - As mentioned before, in-flows and out-flows would be any cash that you + As mentioned before, in-flows and out-flows would be any cash that you personally put in or withdraw, and for the "roi" command, these are the - postings that match the query in the--inv argument and NOT match the + postings that match the query in the--inv argument and NOT match the query in the--pnl argument. - If you manually record changes in the value of your investment as - transactions that balance them against "profit and loss" (or "unreal- - ized gains") account or use price directives, then in order for IRR to - compute the precise effect of your in-flows and out-flows on the rate - of return, you will need to record the value of your investement on or + If you manually record changes in the value of your investment as + transactions that balance them against "profit and loss" (or "unreal- + ized gains") account or use price directives, then in order for IRR to + compute the precise effect of your in-flows and out-flows on the rate + of return, you will need to record the value of your investement on or close to the days when in- or out-flows occur. - In technical terms, IRR uses the same approach as computation of net + In technical terms, IRR uses the same approach as computation of net present value, and tries to find a discount rate that makes net present value of all the cash flows of your investment to add up to zero. This - could be hard to wrap your head around, especially if you haven't done + could be hard to wrap your head around, especially if you haven't done discounted cash flow analysis before. Implementation of IRR in hledger should produce results that match the XIRR formula in Excel. - Second way to compute rate of return that roi command implements is + Second way to compute rate of return that roi command implements is called "time-weighted rate of return" or "TWR". Like IRR, it will also - break the history of your investment into periods between in-flows, - out-flows and value changes, to compute rate of return per each period - and then a compound rate of return. However, internal workings of TWR + break the history of your investment into periods between in-flows, + out-flows and value changes, to compute rate of return per each period + and then a compound rate of return. However, internal workings of TWR are quite different. - TWR represents your investment as an imaginary "unit fund" where in- - flows/ out-flows lead to buying or selling "units" of your investment + TWR represents your investment as an imaginary "unit fund" where in- + flows/ out-flows lead to buying or selling "units" of your investment and changes in its value change the value of "investment unit". Change - in "unit price" over the reporting period gives you rate of return of + in "unit price" over the reporting period gives you rate of return of your investment. - References: * Explanation of rate of return * Explanation of IRR * - Explanation of TWR * Examples of computing IRR and TWR and discussion + References: * Explanation of rate of return * Explanation of IRR * + Explanation of TWR * Examples of computing IRR and TWR and discussion of the limitations of both metrics stats stats Show some journal statistics. - The stats command displays summary information for the whole journal, - or a matched part of it. With a reporting interval, it shows a report + The stats command displays summary information for the whole journal, + or a matched part of it. With a reporting interval, it shows a report for each report period. Example: @@ -3544,35 +3572,35 @@ COMMANDS Commodities : 1 ($) Market prices : 12 ($) - This command also supports output destination and output format selec- + This command also supports output destination and output format selec- tion. tags tags - List the unique tag names used in the journal. With a TAGREGEX argu- + List the unique tag names used in the journal. With a TAGREGEX argu- ment, only tag names matching the regular expression (case insensitive) - are shown. With QUERY arguments, only transactions matching the query + are shown. With QUERY arguments, only transactions matching the query are considered. With the --values flag, the tags' unique values are listed instead. - With --parsed flag, all tags or values are shown in the order they are + With --parsed flag, all tags or values are shown in the order they are parsed from the input data, including duplicates. - With -E/--empty, any blank/empty values will also be shown, otherwise + With -E/--empty, any blank/empty values will also be shown, otherwise they are omitted. test test Run built-in unit tests. - This command runs the unit tests built in to hledger and hledger-lib, - printing the results on stdout. If any test fails, the exit code will + This command runs the unit tests built in to hledger and hledger-lib, + printing the results on stdout. If any test fails, the exit code will be non-zero. - This is mainly used by hledger developers, but you can also use it to - sanity-check the installed hledger executable on your platform. All - tests are expected to pass - if you ever see a failure, please report + This is mainly used by hledger developers, but you can also use it to + sanity-check the installed hledger executable on your platform. All + tests are expected to pass - if you ever see a failure, please report as a bug! This command also accepts tasty test runner options, written after a -- @@ -3581,7 +3609,7 @@ COMMANDS $ hledger test -- -pData.Amount --color=never - For help on these, see https://github.com/feuerbach/tasty#options (-- + For help on these, see https://github.com/feuerbach/tasty#options (-- --help currently doesn't show them). About add-on commands @@ -3589,16 +3617,16 @@ COMMANDS o whose name starts with hledger- - o whose name ends with a recognised file extension: .bat,.com,.exe, + o whose name ends with a recognised file extension: .bat,.com,.exe, .hs,.lhs,.pl,.py,.rb,.rkt,.sh or none o and (on unix, mac) which are executable by the current user. - Add-ons are a relatively easy way to add local features or experiment - with new ideas. They can be written in any language, but haskell - scripts have a big advantage: they can use the same hledger library - functions that built-in commands use for command-line options, parsing - and reporting. Some experimental/example add-on scripts can be found + Add-ons are a relatively easy way to add local features or experiment + with new ideas. They can be written in any language, but haskell + scripts have a big advantage: they can use the same hledger library + functions that built-in commands use for command-line options, parsing + and reporting. Some experimental/example add-on scripts can be found in the hledger repo's bin/ directory. Note in a hledger command line, add-on command flags must have a double @@ -3622,17 +3650,17 @@ COMMANDS JOURNAL FORMAT hledger's default file format, representing a General Journal. - hledger's usual data source is a plain text file containing journal - entries in hledger journal format. This file represents a standard - accounting general journal. I use file names ending in .journal, but + hledger's usual data source is a plain text file containing journal + entries in hledger journal format. This file represents a standard + accounting general journal. I use file names ending in .journal, but that's not required. The journal file contains a number of transaction entries, each describing a transfer of money (or any commodity) between two or more named accounts, in a simple format readable by both hledger and humans. - hledger's journal format is a compatible subset, mostly, of ledger's - journal format, so hledger can work with compatible ledger journal - files as well. It's safe, and encouraged, to run both hledger and + hledger's journal format is a compatible subset, mostly, of ledger's + journal format, so hledger can work with compatible ledger journal + files as well. It's safe, and encouraged, to run both hledger and ledger on the same journal file, eg to validate the results you're get- ting. @@ -3640,25 +3668,25 @@ JOURNAL FORMAT the add or web or import commands to create and update it. Many users, though, edit the journal file with a text editor, and track - changes with a version control system such as git. Editor addons such - as ledger-mode or hledger-mode for Emacs, vim-ledger for Vim, and + changes with a version control system such as git. Editor addons such + as ledger-mode or hledger-mode for Emacs, vim-ledger for Vim, and hledger-vscode for Visual Studio Code, make this easier, adding colour, formatting, tab completion, and useful commands. See Editor configura- tion at hledger.org for the full list. - Here's a description of each part of the file format (and hledger's - data model). These are mostly in the order you'll use them, but in - some cases related concepts have been grouped together for easy refer- - ence, or linked before they are introduced, so feel free to skip over + Here's a description of each part of the file format (and hledger's + data model). These are mostly in the order you'll use them, but in + some cases related concepts have been grouped together for easy refer- + ence, or linked before they are introduced, so feel free to skip over anything that looks unnecessary right now. Transactions - Transactions are the main unit of information in a journal file. They - represent events, typically a movement of some quantity of commodities + Transactions are the main unit of information in a journal file. They + represent events, typically a movement of some quantity of commodities between two or more named accounts. - Each transaction is recorded as a journal entry, beginning with a sim- - ple date in column 0. This can be followed by any of the following + Each transaction is recorded as a journal entry, beginning with a sim- + ple date in column 0. This can be followed by any of the following optional fields, separated by spaces: o a status character (empty, !, or *) @@ -3667,11 +3695,11 @@ JOURNAL FORMAT o a description (any remaining text until end of line or a semicolon) - o a comment (any remaining text following a semicolon until end of + o a comment (any remaining text following a semicolon until end of line, and any following indented lines beginning with a semicolon) o 0 or more indented posting lines, describing what was transferred and - the accounts involved (indented comment lines are also allowed, but + the accounts involved (indented comment lines are also allowed, but not blank lines or non-indented lines). Here's a simple journal file containing one transaction: @@ -3682,35 +3710,35 @@ JOURNAL FORMAT Dates Simple dates - Dates in the journal file use simple dates format: YYYY-MM-DD or + Dates in the journal file use simple dates format: YYYY-MM-DD or YYYY/MM/DD or YYYY.MM.DD, with leading zeros optional. The year may be - omitted, in which case it will be inferred from the context: the cur- - rent transaction, the default year set with a default year directive, - or the current date when the command is run. Some examples: + omitted, in which case it will be inferred from the context: the cur- + rent transaction, the default year set with a default year directive, + or the current date when the command is run. Some examples: 2010-01-31, 2010/01/31, 2010.1.31, 1/31. - (The UI also accepts simple dates, as well as the more flexible smart + (The UI also accepts simple dates, as well as the more flexible smart dates documented in the hledger manual.) Secondary dates - Real-life transactions sometimes involve more than one date - eg the + Real-life transactions sometimes involve more than one date - eg the date you write a cheque, and the date it clears in your bank. When you - want to model this, for more accurate daily balances, you can specify + want to model this, for more accurate daily balances, you can specify individual posting dates. - Or, you can use the older secondary date feature (Ledger calls it aux- - iliary date or effective date). Note: we support this for compatibil- - ity, but I usually recommend avoiding this feature; posting dates are + Or, you can use the older secondary date feature (Ledger calls it aux- + iliary date or effective date). Note: we support this for compatibil- + ity, but I usually recommend avoiding this feature; posting dates are almost always clearer and simpler. A secondary date is written after the primary date, following an equals - sign. If the year is omitted, the primary date's year is assumed. - When running reports, the primary (left) date is used by default, but - with the --date2 flag (or --aux-date or --effective), the secondary + sign. If the year is omitted, the primary date's year is assumed. + When running reports, the primary (left) date is used by default, but + with the --date2 flag (or --aux-date or --effective), the secondary (right) date will be used instead. - The meaning of secondary dates is up to you, but it's best to follow a - consistent rule. Eg "primary = the bank's clearing date, secondary = + The meaning of secondary dates is up to you, but it's best to follow a + consistent rule. Eg "primary = the bank's clearing date, secondary = date the transaction was initiated, if different", as shown here: 2010/2/23=2/19 movie ticket @@ -3724,11 +3752,11 @@ JOURNAL FORMAT 2010-02-19 movie ticket assets:checking $-10 $-10 Posting dates - You can give individual postings a different date from their parent - transaction, by adding a posting comment containing a tag (see below) + You can give individual postings a different date from their parent + transaction, by adding a posting comment containing a tag (see below) like date:DATE. This is probably the best way to control posting dates - precisely. Eg in this example the expense should appear in May - reports, and the deduction from checking should be reported on 6/1 for + precisely. Eg in this example the expense should appear in May + reports, and the deduction from checking should be reported on 6/1 for easy bank reconciliation: 2015/5/30 @@ -3741,22 +3769,22 @@ JOURNAL FORMAT $ hledger -f t.j register checking 2015-06-01 assets:checking $-10 $-10 - DATE should be a simple date; if the year is not specified it will use - the year of the transaction's date. You can set the secondary date - similarly, with date2:DATE2. The date: or date2: tags must have a - valid simple date value if they are present, eg a date: tag with no + DATE should be a simple date; if the year is not specified it will use + the year of the transaction's date. You can set the secondary date + similarly, with date2:DATE2. The date: or date2: tags must have a + valid simple date value if they are present, eg a date: tag with no value is not allowed. Ledger's earlier, more compact bracketed date syntax is also supported: - [DATE], [DATE=DATE2] or [=DATE2]. hledger will attempt to parse any + [DATE], [DATE=DATE2] or [=DATE2]. hledger will attempt to parse any square-bracketed sequence of the 0123456789/-.= characters in this way. - With this syntax, DATE infers its year from the transaction and DATE2 + With this syntax, DATE infers its year from the transaction and DATE2 infers its year from DATE. Status - Transactions, or individual postings within a transaction, can have a - status mark, which is a single character before the transaction - description or posting account name, separated from it by a space, + Transactions, or individual postings within a transaction, can have a + status mark, which is a single character before the transaction + description or posting account name, separated from it by a space, indicating one of three statuses: @@ -3766,23 +3794,23 @@ JOURNAL FORMAT ! pending * cleared - When reporting, you can filter by status with the -U/--unmarked, - -P/--pending, and -C/--cleared flags; or the status:, status:!, and + When reporting, you can filter by status with the -U/--unmarked, + -P/--pending, and -C/--cleared flags; or the status:, status:!, and status:* queries; or the U, P, C keys in hledger-ui. - Note, in Ledger and in older versions of hledger, the "unmarked" state - is called "uncleared". As of hledger 1.3 we have renamed it to + Note, in Ledger and in older versions of hledger, the "unmarked" state + is called "uncleared". As of hledger 1.3 we have renamed it to unmarked for clarity. - To replicate Ledger and old hledger's behaviour of also matching pend- + To replicate Ledger and old hledger's behaviour of also matching pend- ing, combine -U and -P. - Status marks are optional, but can be helpful eg for reconciling with + Status marks are optional, but can be helpful eg for reconciling with real-world accounts. Some editor modes provide highlighting and short- - cuts for working with status. Eg in Emacs ledger-mode, you can toggle + cuts for working with status. Eg in Emacs ledger-mode, you can toggle transaction status with C-c C-e, or posting status with C-c C-c. - What "uncleared", "pending", and "cleared" actually mean is up to you. + What "uncleared", "pending", and "cleared" actually mean is up to you. Here's one suggestion: @@ -3794,35 +3822,35 @@ JOURNAL FORMAT cleared complete, reconciled as far as possible, and considered cor- rect - With this scheme, you would use -PC to see the current balance at your - bank, -U to see things which will probably hit your bank soon (like + With this scheme, you would use -PC to see the current balance at your + bank, -U to see things which will probably hit your bank soon (like uncashed checks), and no flags to see the most up-to-date state of your finances. Description - A transaction's description is the rest of the line following the date - and status mark (or until a comment begins). Sometimes called the + A transaction's description is the rest of the line following the date + and status mark (or until a comment begins). Sometimes called the "narration" in traditional bookkeeping, it can be used for whatever you - wish, or left blank. Transaction descriptions can be queried, unlike + wish, or left blank. Transaction descriptions can be queried, unlike comments. Payee and note You can optionally include a | (pipe) character in descriptions to sub- divide the description into separate fields for payee/payer name on the - left (up to the first |) and an additional note field on the right - (after the first |). This may be worthwhile if you need to do more + 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: @@ -3845,24 +3873,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: @@ -3876,57 +3904,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: @@ -3938,43 +3966,39 @@ 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 or commodity name (the "commodity"). This is - a symbol, word, or phrase, to the left or right of the quantity, with - or without a separating space: + ..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 + space: $1 4000 AAPL - - If the commodity name contains spaces, numbers, or punctuation, it must - be enclosed in double quotes: - - 3 "no. 42 green apples" + 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- @@ -4017,29 +4041,53 @@ JOURNAL FORMAT 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, especially if your data contains digit group marks, - we recommend you explicitly declare the decimal mark (and optionally a - digit group mark), for each commodity, using commodity directives - (described below): + 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. - # number formats for $, EUR, INR and the no-symbol commodity: + 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 + 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", + "ABC123"). + + 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 + hledger's output; you can't write them directly in the journal file. + + (If you are writing scripts or working with hledger's internals, these + are the Amount and MixedAmount types.) + + 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- + ties. Here's a quick example: + + # number format and display style for $, EUR, INR and the no-symbol commodity: commodity $1,000.00 commodity EUR 1.000,00 commodity INR 9,99,99,999.00 commodity 1 000 000.9455 - Note, commodity directives declare both the number format for parsing - input, and the display style for showing output. For the former, they - are position-sensitive, affecting only following amounts, so commodity - directives should be at the top of your journal file. This is dis- - cussed more on #793. - Commodity display style For the amounts in each commodity, hledger chooses a consistent display - style to use in most reports. (Except for price amounts, which are - always displayed as written). The display style is inferred as fol- - lows. + 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 its style is applied to any no-symbol amounts in the journal. @@ -4342,9 +4390,6 @@ JOURNAL FORMAT tive directive rec- 2018/06) tives ------------------------------------------------------------------------------------ - - - account any document account names, all entries in all text declare account types & dis- files, before or play order after @@ -4360,6 +4405,11 @@ JOURNAL FORMAT ment until end of cur- rent file or end directive + + + + + commod- format declare a commodity and its number notation: ity number notation & display following entries style in that commodity @@ -4494,39 +4544,44 @@ JOURNAL FORMAT payee Whole Foods Declaring commodities - The commodity directive has several functions: + 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 is - currently not enforced, but can serve as documentation. + 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 what 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). + 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 a commodity's display style in output - decimal and - digit group marks, number of decimal places, symbol placement etc. + 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 + style) - You are likely to run into one of the problems solved by commodity - directives, sooner or later, so it's a good idea to just always use - them to declare your commodities. + 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. - A commodity directive is just the word commodity followed by an amount. - It may be written on a single line, like this: + Generally you should put them at the top of your journal file (since + for function 2, they affect only following amounts, cf #793). - ; commodity EXAMPLEAMOUNT + A commodity directive is just the word commodity followed by a sample + amount, like this: - ; display AAAA amounts with the symbol on the right, space-separated, - ; using period as decimal point, with four decimal places, and - ; separating thousands with comma. - commodity 1,000.0000 AAAA + ;commodity SAMPLEAMOUNT - or on multiple lines, using the "format" subdirective. (In this case - the commodity symbol appears twice and should be the same in both - places.): + commodity $1000.00 + commodity 1,000.0000 AAAA ; optional same-line comment - ; commodity SYMBOL - ; format EXAMPLEAMOUNT + 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 + ; format SAMPLEAMOUNT ; display indian rupees with currency name on the left, ; thousands, lakhs and crores comma-separated, @@ -4534,9 +4589,20 @@ JOURNAL FORMAT commodity INR format INR 1,00,00,000.00 - The quantity of the amount does not matter; only the format is signifi- - cant. The number must include a decimal mark: either a period or a - comma, followed by 0 or more decimal digits. + 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 + by 0 or more decimal digits. + + A few more examples: + + # number formats for $, EUR, INR and the no-symbol commodity: + commodity $1,000.00 + commodity EUR 1.000,00 + commodity INR 9,99,99,999.0 + commodity 1 000 000. Note hledger normally uses banker's rounding, so 0.5 displayed with zero decimal digits is "0". (More at Commodity display style.) @@ -4548,16 +4614,18 @@ JOURNAL FORMAT see the notes there for more details. Default commodity - The D directive sets a default commodity, to be used for amounts with- - out a commodity symbol (ie, plain numbers). This commodity will be - applied to all subsequent commodity-less amounts, or until the next D - directive. (Note, this is different from Ledger's D.) + 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 + journal. For compatibility/historical reasons, D also acts like a commodity - directive, setting the commodity's display style (for output) and deci- - mal mark (for parsing input). As with commodity, the amount must - always be written with a decimal mark (period or comma). If both - directives are used, commodity's style takes precedence. + 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 + same commodity, the commodity style takes precedence. The syntax is D AMOUNT. Eg: @@ -4718,8 +4786,8 @@ JOURNAL FORMAT cally using the following rules: - If name matches regular account type is: - expression: + If name matches this regu- account type is: + lar expression: ---------------------------------------------- ^assets?(:|$) Asset ^(debts?|lia- Liability @@ -4729,11 +4797,10 @@ JOURNAL FORMAT ^expenses?(:|$) Expense - If account type is Asset and name does not contain regu- account type - lar expression: is: + If account type is Asset and name does not contain this account type + regular expression: is: -------------------------------------------------------------------------- - - (investment|receivable|:A/R|:fixed) Cash + (investment|receivable|:A/R|:fixed) Cash Even so, explicit declarations may be a good idea, for clarity and pre- dictability. @@ -5695,11 +5762,11 @@ CSV FORMAT REGEX - REGEX is a case-insensitive regular expression which tries to match - anywhere within the CSV record. It is a POSIX ERE (extended regular + REGEX is a case-insensitive regular expression that tries to match any- + where within the CSV record. It is a POSIX ERE (extended regular expression) that also supports GNU word boundaries (\b, \B, \<, \>), - and nothing else. If you have trouble, be sure to check our - https://hledger.org/hledger.html#regular-expressions doc. + and nothing else. If you have trouble, be sure to check our doc: + https://hledger.org/hledger.html#regular-expressions Important note: the record that is matched is not the original record, but a synthetic one, with any enclosing double quotes (but not enclos-