diff --git a/hledger-lib/hledger_csv.5 b/hledger-lib/hledger_csv.5 index c519610bea9..cc2b912a56c 100644 --- a/hledger-lib/hledger_csv.5 +++ b/hledger-lib/hledger_csv.5 @@ -1,6 +1,6 @@ .\"t -.TH "HLEDGER_CSV" "5" "December 2020" "hledger-lib-1.20.1 " "hledger User Manuals" +.TH "HLEDGER_CSV" "5" "December 2020" "hledger-lib-1.20.3 " "hledger User Manuals" diff --git a/hledger-lib/hledger_csv.txt b/hledger-lib/hledger_csv.txt index c987e78499c..ccb55dabe06 100644 --- a/hledger-lib/hledger_csv.txt +++ b/hledger-lib/hledger_csv.txt @@ -958,4 +958,4 @@ SEE ALSO -hledger-lib-1.20.1 December 2020 HLEDGER_CSV(5) +hledger-lib-1.20.3 December 2020 HLEDGER_CSV(5) diff --git a/hledger-lib/hledger_journal.5 b/hledger-lib/hledger_journal.5 index d67559d1fbc..47dc69d458b 100644 --- a/hledger-lib/hledger_journal.5 +++ b/hledger-lib/hledger_journal.5 @@ -1,6 +1,6 @@ .\"t -.TH "HLEDGER_JOURNAL" "5" "December 2020" "hledger-lib-1.20.1 " "hledger User Manuals" +.TH "HLEDGER_JOURNAL" "5" "December 2020" "hledger-lib-1.20.3 " "hledger User Manuals" diff --git a/hledger-lib/hledger_journal.txt b/hledger-lib/hledger_journal.txt index a028b4d9aa2..7f9579b427c 100644 --- a/hledger-lib/hledger_journal.txt +++ b/hledger-lib/hledger_journal.txt @@ -1575,4 +1575,4 @@ SEE ALSO -hledger-lib-1.20.1 December 2020 HLEDGER_JOURNAL(5) +hledger-lib-1.20.3 December 2020 HLEDGER_JOURNAL(5) diff --git a/hledger-lib/hledger_timeclock.5 b/hledger-lib/hledger_timeclock.5 index 59fc286957d..396a90e4109 100644 --- a/hledger-lib/hledger_timeclock.5 +++ b/hledger-lib/hledger_timeclock.5 @@ -1,5 +1,5 @@ -.TH "HLEDGER_TIMECLOCK" "5" "December 2020" "hledger-lib-1.20.1 " "hledger User Manuals" +.TH "HLEDGER_TIMECLOCK" "5" "December 2020" "hledger-lib-1.20.3 " "hledger User Manuals" diff --git a/hledger-lib/hledger_timeclock.txt b/hledger-lib/hledger_timeclock.txt index 1f3974797eb..a7e60d28208 100644 --- a/hledger-lib/hledger_timeclock.txt +++ b/hledger-lib/hledger_timeclock.txt @@ -77,4 +77,4 @@ SEE ALSO -hledger-lib-1.20.1 December 2020 HLEDGER_TIMECLOCK(5) +hledger-lib-1.20.3 December 2020 HLEDGER_TIMECLOCK(5) diff --git a/hledger-lib/hledger_timedot.5 b/hledger-lib/hledger_timedot.5 index cd25ccba78f..ecd238f6940 100644 --- a/hledger-lib/hledger_timedot.5 +++ b/hledger-lib/hledger_timedot.5 @@ -1,5 +1,5 @@ -.TH "HLEDGER_TIMEDOT" "5" "December 2020" "hledger-lib-1.20.1 " "hledger User Manuals" +.TH "HLEDGER_TIMEDOT" "5" "December 2020" "hledger-lib-1.20.3 " "hledger User Manuals" diff --git a/hledger-lib/hledger_timedot.txt b/hledger-lib/hledger_timedot.txt index 1aeb7ca6c52..5de20fce73e 100644 --- a/hledger-lib/hledger_timedot.txt +++ b/hledger-lib/hledger_timedot.txt @@ -160,4 +160,4 @@ SEE ALSO -hledger-lib-1.20.1 December 2020 HLEDGER_TIMEDOT(5) +hledger-lib-1.20.3 December 2020 HLEDGER_TIMEDOT(5) diff --git a/hledger-ui/hledger-ui.1 b/hledger-ui/hledger-ui.1 index b02bfe2b537..75b732f0d6a 100644 --- a/hledger-ui/hledger-ui.1 +++ b/hledger-ui/hledger-ui.1 @@ -1,5 +1,5 @@ -.TH "HLEDGER-UI" "1" "December 2020" "hledger-ui-1.20.1 " "hledger User Manuals" +.TH "HLEDGER-UI" "1" "December 2020" "hledger-ui-1.20.3 " "hledger User Manuals" diff --git a/hledger-ui/hledger-ui.txt b/hledger-ui/hledger-ui.txt index 9af43e946ee..458100d9956 100644 --- a/hledger-ui/hledger-ui.txt +++ b/hledger-ui/hledger-ui.txt @@ -459,4 +459,4 @@ SEE ALSO -hledger-ui-1.20.1 December 2020 HLEDGER-UI(1) +hledger-ui-1.20.3 December 2020 HLEDGER-UI(1) diff --git a/hledger-web/hledger-web.1 b/hledger-web/hledger-web.1 index 621a893e730..ba12e29b22f 100644 --- a/hledger-web/hledger-web.1 +++ b/hledger-web/hledger-web.1 @@ -1,5 +1,5 @@ -.TH "HLEDGER-WEB" "1" "December 2020" "hledger-web-1.20.1 " "hledger User Manuals" +.TH "HLEDGER-WEB" "1" "December 2020" "hledger-web-1.20.3 " "hledger User Manuals" diff --git a/hledger-web/hledger-web.txt b/hledger-web/hledger-web.txt index 386b09650f4..73d2d234d11 100644 --- a/hledger-web/hledger-web.txt +++ b/hledger-web/hledger-web.txt @@ -552,4 +552,4 @@ SEE ALSO -hledger-web-1.20.1 December 2020 HLEDGER-WEB(1) +hledger-web-1.20.3 December 2020 HLEDGER-WEB(1) diff --git a/hledger/hledger.1 b/hledger/hledger.1 index c1791ceea68..b4e15f1e6ba 100644 --- a/hledger/hledger.1 +++ b/hledger/hledger.1 @@ -1,6 +1,6 @@ .\"t -.TH "HLEDGER" "1" "December 2020" "hledger-1.20.1 " "hledger User Manuals" +.TH "HLEDGER" "1" "December 2020" "hledger-1.20.3 " "hledger User Manuals" @@ -2798,231 +2798,95 @@ options The output formats supported are (in most modes): \f[C]txt\f[R], \f[C]csv\f[R], \f[C]html\f[R], and \f[C]json\f[R]. .PP The balance command can produce several styles of report: -.SS Classic balance report .PP -This is the original balance report, as found in Ledger. -It usually looks like this: +.SS Single-period flat balance report +.PP +This is the default for hledger\[aq]s balance command: a flat list of +all (or with a query, matched) accounts, showing full account names. +Accounts are sorted by declaration order if any, and then by account +name. +Accounts which have zero balance are not shown unless +\f[C]-E/--empty\f[R] is used. +The reported balances\[aq] total is shown as the last line, unless +disabled by \f[C]-N\f[R]/\f[C]--no-total\f[R]. .IP .nf \f[C] -$ hledger balance - $-1 assets - $1 bank:saving - $-2 cash - $2 expenses - $1 food - $1 supplies - $-2 income - $-1 gifts - $-1 salary +$ hledger bal + $1 assets:bank:saving + $-2 assets:cash + $1 expenses:food + $1 expenses:supplies + $-1 income:gifts + $-1 income:salary $1 liabilities:debts -------------------- - 0 + 0 \f[R] .fi .PP -By default, accounts are displayed hierarchically, with subaccounts -indented below their parent, with accounts at each level of the tree -sorted by declaration order if declared, then by account name. -.PP -\[dq]Boring\[dq] accounts, which contain a single interesting subaccount -and no balance of their own, are elided into the following line for more -compact output. -(Eg above, the \[dq]liabilities\[dq] account.) Use \f[C]--no-elide\f[R] -to prevent this. -.PP -Account balances are \[dq]inclusive\[dq] - they include the balances of -any subaccounts. -.PP -Accounts which have zero balance (and no non-zero subaccounts) are -omitted. -Use \f[C]-E/--empty\f[R] to show them. +.SS Single-period tree-mode balance report .PP -A final total is displayed by default; use \f[C]-N/--no-total\f[R] to -suppress it, eg: +With the \f[C]-t/--tree\f[R] flag, accounts are displayed +hierarchically, showing subaccounts as short names indented below their +parent. +(This is the default style in Ledger and in older hledger versions.) .IP .nf \f[C] -$ hledger balance -p 2008/6 expenses --no-total +$ hledger balance + $-1 assets + $1 bank:saving + $-2 cash $2 expenses $1 food $1 supplies -\f[R] -.fi -.SS Customising the classic balance report -.PP -You can customise the layout of classic balance reports with -\f[C]--format FMT\f[R]: -.IP -.nf -\f[C] -$ hledger balance --format \[dq]%20(account) %12(total)\[dq] - assets $-1 - bank:saving $1 - cash $-2 - expenses $2 - food $1 - supplies $1 - income $-2 - gifts $-1 - salary $-1 - liabilities:debts $1 ---------------------------------- - 0 -\f[R] -.fi -.PP -The FMT format string (plus a newline) specifies the formatting applied -to each account/balance pair. -It may contain any suitable text, with data fields interpolated like so: -.PP -\f[C]%[MIN][.MAX](FIELDNAME)\f[R] -.IP \[bu] 2 -MIN pads with spaces to at least this width (optional) -.IP \[bu] 2 -MAX truncates at this width (optional) -.IP \[bu] 2 -FIELDNAME must be enclosed in parentheses, and can be one of: -.RS 2 -.IP \[bu] 2 -\f[C]depth_spacer\f[R] - a number of spaces equal to the account\[aq]s -depth, or if MIN is specified, MIN * depth spaces. -.IP \[bu] 2 -\f[C]account\f[R] - the account\[aq]s name -.IP \[bu] 2 -\f[C]total\f[R] - the account\[aq]s balance/posted total, right -justified -.RE -.PP -Also, FMT can begin with an optional prefix to control how -multi-commodity amounts are rendered: -.IP \[bu] 2 -\f[C]%_\f[R] - render on multiple lines, bottom-aligned (the default) -.IP \[bu] 2 -\f[C]%\[ha]\f[R] - render on multiple lines, top-aligned -.IP \[bu] 2 -\f[C]%,\f[R] - render on one line, comma-separated -.PP -There are some quirks. -Eg in one-line mode, \f[C]%(depth_spacer)\f[R] has no effect, instead -\f[C]%(account)\f[R] has indentation built in. -Experimentation may be needed to get pleasing results. -.PP -Some example formats: -.IP \[bu] 2 -\f[C]%(total)\f[R] - the account\[aq]s total -.IP \[bu] 2 -\f[C]%-20.20(account)\f[R] - the account\[aq]s name, left justified, -padded to 20 characters and clipped at 20 characters -.IP \[bu] 2 -\f[C]%,%-50(account) %25(total)\f[R] - account name padded to 50 -characters, total padded to 20 characters, with multiple commodities -rendered on one line -.IP \[bu] 2 -\f[C]%20(total) %2(depth_spacer)%-(account)\f[R] - the default format -for the single-column balance report -.SS Colour support -.PP -In terminal output, when colour is enabled, the balance command shows -negative amounts in red. -.SS Flat mode -.PP -To see a flat list instead of the default hierarchical display, use -\f[C]--flat\f[R]. -In this mode, accounts (unless depth-clipped) show their full names and -\[dq]exclusive\[dq] balance, excluding any subaccount balances. -In this mode, you can also use \f[C]--drop N\f[R] to omit the first few -account name components. -.IP -.nf -\f[C] -$ hledger balance -p 2008/6 expenses -N --flat --drop 1 - $1 food - $1 supplies -\f[R] -.fi -.SS Depth limited balance reports -.PP -With \f[C]--depth N\f[R] or \f[C]depth:N\f[R] or just \f[C]-N\f[R], -balance reports show accounts only to the specified numeric depth. -This is very useful to summarise a complex set of accounts and get an -overview. -.IP -.nf -\f[C] -$ hledger balance -N -1 - $-1 assets - $2 expenses $-2 income - $1 liabilities -\f[R] -.fi -.PP -Flat-mode balance reports, which normally show exclusive balances, show -inclusive balances at the depth limit. -.SS Percentages -.PP -With \f[C]-%\f[R] or \f[C]--percent\f[R], balance reports show each -account\[aq]s value expressed as a percentage of the column\[aq]s total. -This is useful to get an overview of the relative sizes of account -balances. -For example to obtain an overview of expenses: -.IP -.nf -\f[C] -$ hledger balance expenses -% - 100.0 % expenses - 50.0 % food - 50.0 % supplies + $-1 gifts + $-1 salary + $1 liabilities:debts -------------------- - 100.0 % + 0 \f[R] .fi .PP -Note that \f[C]--tree\f[R] does not have an effect on \f[C]-%\f[R]. -The percentages are always relative to the total sum of each column, -they are never relative to the parent account. -.PP -Since the percentages are relative to the columns sum, it is usually not -useful to calculate percentages if the signs of the amounts are mixed. -Although the results are technically correct, they are most likely -useless. -Especially in a balance report that sums up to zero (eg -\f[C]hledger balance -B\f[R]) all percentage values will be zero. -.PP -This flag does not work if the report contains any mixed commodity -accounts. -If there are mixed commodity accounts in the report be sure to use -\f[C]-V\f[R] or \f[C]-B\f[R] to coerce the report into using a single -commodity. -.SS Sorting by amount -.PP -With \f[C]-S\f[R]/\f[C]--sort-amount\f[R], accounts with the largest -(most positive) balances are shown first. -For example, \f[C]hledger bal expenses -MAS\f[R] shows your biggest -averaged monthly expenses first. -.PP -Revenues and liability balances are typically negative, however, so -\f[C]-S\f[R] shows these in reverse order. -To work around this, you can add \f[C]--invert\f[R] to flip the signs. -Or, use one of the sign-flipping reports like \f[C]balancesheet\f[R] or -\f[C]incomestatement\f[R], which also support \f[C]-S\f[R]. -Eg: \f[C]hledger is -MAS\f[R]. -.SS Multicolumn balance report -.PP -Multicolumn or tabular balance reports are a very useful hledger -feature, and usually the preferred style. -They share many of the above features, but they show the report as a -table, with columns representing time periods. -This mode is activated by providing a reporting interval. -.PP -There are three types of multicolumn balance report, showing different +For more compact output, \[dq]boring\[dq] accounts containing a single +interesting subaccount and no balance of their own +(\f[C]assets:bank\f[R] and \f[C]liabilities\f[R] here) are elided into +the following line, unless \f[C]--no-elide\f[R] is used. +And accounts which have zero balance and no non-zero subaccounts are +omitted, unless \f[C]-E/--empty\f[R] is used. +.PP +Account balances in tree mode are \[dq]inclusive\[dq] - they include the +balances of any subaccounts. +Eg, the \f[C]assets\f[R] \f[C]$-1\f[R] balance here includes the +\f[C]$1\f[R] from \f[C]assets:bank:saving\f[R] and the \f[C]$-2\f[R] +from \f[C]assets:cash\f[R]. +(And it would include balance posted to the \f[C]assets\f[R] account +itself, if there was any). +Note this causes some repetition, and the final total (\f[C]0\f[R]) is +the sum of the top-level balances, not of all the balances shown. +.PP +Each group of sibling accounts is sorted separately, by declaration +order and then by account name. +.SS Multi-period balance report +.PP +Multi-period balance reports are a very useful hledger feature, +activated if you provide one of the reporting interval flags, such as +\f[C]-M\f[R]/\f[C]--monthly\f[R]. +They are similar to single-period balance reports, but they show the +report as a table, with columns representing one or more successive time +periods. +This is the usually the preferred style of balance report in hledger +(even for a single period). +.PP +Multi-period balance reports come in several types, showing different information: .IP "1." 3 -By default: each column shows the sum of postings in that period, ie the -account\[aq]s change of balance in that period. +A balance change report: by default, each column shows the sum of +postings in that period, ie the account\[aq]s change of balance in that +period. This is useful eg for a monthly income statement: -.RS 4 .IP .nf \f[C] @@ -3039,11 +2903,10 @@ Balance changes in 2008: || $-1 $1 0 0 \f[R] .fi -.RE .IP "2." 3 -With \f[C]--cumulative\f[R]: each column shows the ending balance for -that period, accumulating the changes across periods, starting from 0 at -the report start date: +A cumulative end balance report: with \f[C]--cumulative\f[R], each +column shows the end balance for that period, accumulating the changes +across periods, starting from 0 at the report start date: .RS 4 .IP .nf @@ -3063,11 +2926,12 @@ Ending balances (cumulative) in 2008: .fi .RE .IP "3." 3 -With \f[C]--historical/-H\f[R]: each column shows the actual historical -ending balance for that period, accumulating the changes across periods, -starting from the actual balance at the report start date. -This is useful eg for a multi-period balance sheet, and when you are -showing only the data after a certain start date: +A historical end balance report: with \f[C]--historical/-H\f[R], each +column shows the actual historical end balance for that period, +accumulating the changes across periods, and including the balance from +any postings before the report start date. +This is useful eg for a multi-period balance sheet, and when you want to +see balances only after a certain date: .RS 4 .IP .nf @@ -3091,9 +2955,6 @@ Note that \f[C]--cumulative\f[R] or \f[C]--historical/-H\f[R] disable \f[C]--row-total/-T\f[R], since summing end balances generally does not make sense. .PP -Multicolumn balance reports display accounts in flat mode by default; to -see the hierarchy, use \f[C]--tree\f[R]. -.PP With a reporting interval (like \f[C]--quarterly\f[R] above), the report start/end dates will be adjusted if necessary so that they encompass the displayed report periods. @@ -3150,14 +3011,166 @@ the width of multicommodity reports. When the report is still too wide, a good workaround is to pipe it into \f[C]less -RS\f[R] (-R for colour, -S to chop long lines). Eg: \f[C]hledger bal -D --color=yes | less -RS\f[R]. +.SS Depth limiting +.PP +With a \f[C]depth:N\f[R] query, or \f[C]--depth N\f[R] option, or just +\f[C]-N\f[R], balance reports will show accounts only to the specified +depth. +This is very useful to hide low-level accounts and get an overview. +Eg, limiting to depth 1 shows the top-level accounts: +.IP +.nf +\f[C] +$ hledger balance -N -1 + $-1 assets + $2 expenses + $-2 income + $1 liabilities +\f[R] +.fi +.PP +Accounts at the depth limit will include the balances of any hidden +subaccounts (even in flat mode, which normally shows exclusive +balances). +.PP +You can also drop account name components from the start of account +names, using \f[C]--drop N\f[R]. +This can be useful to hide unwanted top-level detail. +.SS Colour support +.PP +In terminal output, when colour is enabled, the balance command shows +negative amounts in red. +.SS Sorting by amount +.PP +With \f[C]-S\f[R]/\f[C]--sort-amount\f[R], accounts with the largest +(most positive) balances are shown first. +For example, \f[C]hledger bal expenses -MAS\f[R] shows your biggest +averaged monthly expenses first. +.PP +Revenues and liability balances are typically negative, however, so +\f[C]-S\f[R] shows these in reverse order. +To work around this, you can add \f[C]--invert\f[R] to flip the signs. +Or, use one of the sign-flipping reports like \f[C]balancesheet\f[R] or +\f[C]incomestatement\f[R], which also support \f[C]-S\f[R]. +Eg: \f[C]hledger is -MAS\f[R]. +.SS Percentages +.PP +With \f[C]-%\f[R] or \f[C]--percent\f[R], balance reports show each +account\[aq]s value expressed as a percentage of the column\[aq]s total. +This is useful to get an overview of the relative sizes of account +balances. +For example to obtain an overview of expenses: +.IP +.nf +\f[C] +$ hledger balance expenses -% + 100.0 % expenses + 50.0 % food + 50.0 % supplies +-------------------- + 100.0 % +\f[R] +.fi +.PP +Note that \f[C]--tree\f[R] does not have an effect on \f[C]-%\f[R]. +The percentages are always relative to the total sum of each column, +they are never relative to the parent account. +.PP +Since the percentages are relative to the columns sum, it is usually not +useful to calculate percentages if the signs of the amounts are mixed. +Although the results are technically correct, they are most likely +useless. +Especially in a balance report that sums up to zero (eg +\f[C]hledger balance -B\f[R]) all percentage values will be zero. +.PP +This flag does not work if the report contains any mixed commodity +accounts. +If there are mixed commodity accounts in the report be sure to use +\f[C]-V\f[R] or \f[C]-B\f[R] to coerce the report into using a single +commodity. +.PP +.SS Customising single-period balance reports +.PP +You can customise the layout of single-period balance reports with +\f[C]--format FMT\f[R], which sets the format of each line. +Eg: +.IP +.nf +\f[C] +$ hledger balance --format \[dq]%20(account) %12(total)\[dq] + assets $-1 + bank:saving $1 + cash $-2 + expenses $2 + food $1 + supplies $1 + income $-2 + gifts $-1 + salary $-1 + liabilities:debts $1 +--------------------------------- + 0 +\f[R] +.fi +.PP +The FMT format string (plus a newline) specifies the formatting applied +to each account/balance pair. +It may contain any suitable text, with data fields interpolated like so: +.PP +\f[C]%[MIN][.MAX](FIELDNAME)\f[R] +.IP \[bu] 2 +MIN pads with spaces to at least this width (optional) +.IP \[bu] 2 +MAX truncates at this width (optional) +.IP \[bu] 2 +FIELDNAME must be enclosed in parentheses, and can be one of: +.RS 2 +.IP \[bu] 2 +\f[C]depth_spacer\f[R] - a number of spaces equal to the account\[aq]s +depth, or if MIN is specified, MIN * depth spaces. +.IP \[bu] 2 +\f[C]account\f[R] - the account\[aq]s name +.IP \[bu] 2 +\f[C]total\f[R] - the account\[aq]s balance/posted total, right +justified +.RE +.PP +Also, FMT can begin with an optional prefix to control how +multi-commodity amounts are rendered: +.IP \[bu] 2 +\f[C]%_\f[R] - render on multiple lines, bottom-aligned (the default) +.IP \[bu] 2 +\f[C]%\[ha]\f[R] - render on multiple lines, top-aligned +.IP \[bu] 2 +\f[C]%,\f[R] - render on one line, comma-separated +.PP +There are some quirks. +Eg in one-line mode, \f[C]%(depth_spacer)\f[R] has no effect, instead +\f[C]%(account)\f[R] has indentation built in. +Experimentation may be needed to get pleasing results. +.PP +Some example formats: +.IP \[bu] 2 +\f[C]%(total)\f[R] - the account\[aq]s total +.IP \[bu] 2 +\f[C]%-20.20(account)\f[R] - the account\[aq]s name, left justified, +padded to 20 characters and clipped at 20 characters +.IP \[bu] 2 +\f[C]%,%-50(account) %25(total)\f[R] - account name padded to 50 +characters, total padded to 20 characters, with multiple commodities +rendered on one line +.IP \[bu] 2 +\f[C]%20(total) %2(depth_spacer)%-(account)\f[R] - the default format +for the single-column balance report .SS Budget report .PP -With \f[C]--budget\f[R], extra columns are displayed showing budget +There is also a special balance report mode for showing budget +performance. +The \f[C]--budget\f[R] flag activates extra columns showing the budget goals for each account and period, if any. -Budget goals are defined by periodic transactions. +For this report, budget goals are defined by periodic transactions. This is very useful for comparing planned and actual income, expenses, time usage, etc. ---budget is most often combined with a report interval. .PP For example, you can take average monthly expenses in the common expense categories to construct a minimal monthly budget: diff --git a/hledger/hledger.info b/hledger/hledger.info index 97bc82365d5..4aba1cc5ecf 100644 --- a/hledger/hledger.info +++ b/hledger/hledger.info @@ -2274,24 +2274,49 @@ options The output formats supported are (in most modes): 'txt', 'csv', * Menu: -* Classic balance report:: -* Customising the classic balance report:: +* Single-period flat balance report:: +* Single-period tree-mode balance report:: +* Multi-period balance report:: +* Depth limiting:: * Colour support:: -* Flat mode:: -* Depth limited balance reports:: -* Percentages:: * Sorting by amount:: -* Multicolumn balance report:: +* Percentages:: +* Customising single-period balance reports:: * Budget report::  -File: hledger.info, Node: Classic balance report, Next: Customising the classic balance report, Up: balance +File: hledger.info, Node: Single-period flat balance report, Next: Single-period tree-mode balance report, Up: balance -3.5.1 Classic balance report ----------------------------- +3.5.1 Single-period flat balance report +--------------------------------------- -This is the original balance report, as found in Ledger. It usually -looks like this: +This is the default for hledger's balance command: a flat list of all +(or with a query, matched) accounts, showing full account names. +Accounts are sorted by declaration order if any, and then by account +name. Accounts which have zero balance are not shown unless +'-E/--empty' is used. The reported balances' total is shown as the last +line, unless disabled by '-N'/'--no-total'. + +$ hledger bal + $1 assets:bank:saving + $-2 assets:cash + $1 expenses:food + $1 expenses:supplies + $-1 income:gifts + $-1 income:salary + $1 liabilities:debts +-------------------- + 0 + + +File: hledger.info, Node: Single-period tree-mode balance report, Next: Multi-period balance report, Prev: Single-period flat balance report, Up: balance + +3.5.2 Single-period tree-mode balance report +-------------------------------------------- + +With the '-t/--tree' flag, accounts are displayed hierarchically, +showing subaccounts as short names indented below their parent. (This +is the default style in Ledger and in older hledger versions.) $ hledger balance $-1 assets @@ -2307,216 +2332,58 @@ $ hledger balance -------------------- 0 - By default, accounts are displayed hierarchically, with subaccounts -indented below their parent, with accounts at each level of the tree -sorted by declaration order if declared, then by account name. - - "Boring" accounts, which contain a single interesting subaccount and -no balance of their own, are elided into the following line for more -compact output. (Eg above, the "liabilities" account.) Use -'--no-elide' to prevent this. - - Account balances are "inclusive" - they include the balances of any -subaccounts. + For more compact output, "boring" accounts containing a single +interesting subaccount and no balance of their own ('assets:bank' and +'liabilities' here) are elided into the following line, unless +'--no-elide' is used. And accounts which have zero balance and no +non-zero subaccounts are omitted, unless '-E/--empty' is used. - Accounts which have zero balance (and no non-zero subaccounts) are -omitted. Use '-E/--empty' to show them. + Account balances in tree mode are "inclusive" - they include the +balances of any subaccounts. Eg, the 'assets' '$-1' balance here +includes the '$1' from 'assets:bank:saving' and the '$-2' from +'assets:cash'. (And it would include balance posted to the 'assets' +account itself, if there was any). Note this causes some repetition, +and the final total ('0') is the sum of the top-level balances, not of +all the balances shown. - A final total is displayed by default; use '-N/--no-total' to -suppress it, eg: - -$ hledger balance -p 2008/6 expenses --no-total - $2 expenses - $1 food - $1 supplies + Each group of sibling accounts is sorted separately, by declaration +order and then by account name.  -File: hledger.info, Node: Customising the classic balance report, Next: Colour support, Prev: Classic balance report, Up: balance +File: hledger.info, Node: Multi-period balance report, Next: , Prev: Single-period tree-mode balance report, Up: balance -3.5.2 Customising the classic balance report --------------------------------------------- - -You can customise the layout of classic balance reports with '--format -FMT': - -$ hledger balance --format "%20(account) %12(total)" - assets $-1 - bank:saving $1 - cash $-2 - expenses $2 - food $1 - supplies $1 - income $-2 - gifts $-1 - salary $-1 - liabilities:debts $1 +3.5.3 Multi-period balance report --------------------------------- - 0 - - The FMT format string (plus a newline) specifies the formatting -applied to each account/balance pair. It may contain any suitable text, -with data fields interpolated like so: - - '%[MIN][.MAX](FIELDNAME)' - - * MIN pads with spaces to at least this width (optional) - - * MAX truncates at this width (optional) - - * FIELDNAME must be enclosed in parentheses, and can be one of: - - * 'depth_spacer' - a number of spaces equal to the account's - depth, or if MIN is specified, MIN * depth spaces. - * 'account' - the account's name - * 'total' - the account's balance/posted total, right justified - - Also, FMT can begin with an optional prefix to control how -multi-commodity amounts are rendered: - - * '%_' - render on multiple lines, bottom-aligned (the default) - * '%^' - render on multiple lines, top-aligned - * '%,' - render on one line, comma-separated - - There are some quirks. Eg in one-line mode, '%(depth_spacer)' has no -effect, instead '%(account)' has indentation built in. Experimentation -may be needed to get pleasing results. - - Some example formats: - - * '%(total)' - the account's total - * '%-20.20(account)' - the account's name, left justified, padded to - 20 characters and clipped at 20 characters - * '%,%-50(account) %25(total)' - account name padded to 50 - characters, total padded to 20 characters, with multiple - commodities rendered on one line - * '%20(total) %2(depth_spacer)%-(account)' - the default format for - the single-column balance report - - -File: hledger.info, Node: Colour support, Next: Flat mode, Prev: Customising the classic balance report, Up: balance - -3.5.3 Colour support --------------------- - -In terminal output, when colour is enabled, the balance command shows -negative amounts in red. - - -File: hledger.info, Node: Flat mode, Next: Depth limited balance reports, Prev: Colour support, Up: balance - -3.5.4 Flat mode ---------------- - -To see a flat list instead of the default hierarchical display, use -'--flat'. In this mode, accounts (unless depth-clipped) show their full -names and "exclusive" balance, excluding any subaccount balances. In -this mode, you can also use '--drop N' to omit the first few account -name components. - -$ hledger balance -p 2008/6 expenses -N --flat --drop 1 - $1 food - $1 supplies - - -File: hledger.info, Node: Depth limited balance reports, Next: Percentages, Prev: Flat mode, Up: balance - -3.5.5 Depth limited balance reports ------------------------------------ - -With '--depth N' or 'depth:N' or just '-N', balance reports show -accounts only to the specified numeric depth. This is very useful to -summarise a complex set of accounts and get an overview. - -$ hledger balance -N -1 - $-1 assets - $2 expenses - $-2 income - $1 liabilities - - Flat-mode balance reports, which normally show exclusive balances, -show inclusive balances at the depth limit. - - -File: hledger.info, Node: Percentages, Next: Sorting by amount, Prev: Depth limited balance reports, Up: balance - -3.5.6 Percentages ------------------ -With '-%' or '--percent', balance reports show each account's value -expressed as a percentage of the column's total. This is useful to get -an overview of the relative sizes of account balances. For example to -obtain an overview of expenses: +Multi-period balance reports are a very useful hledger feature, +activated if you provide one of the reporting interval flags, such as +'-M'/'--monthly'. They are similar to single-period balance reports, +but they show the report as a table, with columns representing one or +more successive time periods. This is the usually the preferred style +of balance report in hledger (even for a single period). -$ hledger balance expenses -% - 100.0 % expenses - 50.0 % food - 50.0 % supplies --------------------- - 100.0 % + Multi-period balance reports come in several types, showing different +information: - Note that '--tree' does not have an effect on '-%'. The percentages -are always relative to the total sum of each column, they are never -relative to the parent account. + 1. A balance change report: by default, each column shows the sum of + postings in that period, ie the account's change of balance in that + period. This is useful eg for a monthly income statement: - Since the percentages are relative to the columns sum, it is usually -not useful to calculate percentages if the signs of the amounts are -mixed. Although the results are technically correct, they are most -likely useless. Especially in a balance report that sums up to zero (eg -'hledger balance -B') all percentage values will be zero. - - This flag does not work if the report contains any mixed commodity -accounts. If there are mixed commodity accounts in the report be sure -to use '-V' or '-B' to coerce the report into using a single commodity. - - -File: hledger.info, Node: Sorting by amount, Next: Multicolumn balance report, Prev: Percentages, Up: balance - -3.5.7 Sorting by amount ------------------------ - -With '-S'/'--sort-amount', accounts with the largest (most positive) -balances are shown first. For example, 'hledger bal expenses -MAS' -shows your biggest 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 sign-flipping reports -like 'balancesheet' or 'incomestatement', which also support '-S'. Eg: -'hledger is -MAS'. - - -File: hledger.info, Node: Multicolumn balance report, Next: Budget report, Prev: Sorting by amount, Up: balance - -3.5.8 Multicolumn balance report --------------------------------- - -Multicolumn or tabular balance reports are a very useful hledger -feature, and usually the preferred style. They share many of the above -features, but they show the report as a table, with columns representing -time periods. This mode is activated by providing a reporting interval. - - There are three types of multicolumn balance report, showing -different information: +$ hledger balance --quarterly income expenses -E +Balance changes in 2008: - 1. By default: each column shows the sum of postings in that period, - ie the account's change of balance in that period. This is useful - eg for a monthly income statement: + || 2008q1 2008q2 2008q3 2008q4 +===================++================================= + expenses:food || 0 $1 0 0 + expenses:supplies || 0 $1 0 0 + income:gifts || 0 $-1 0 0 + income:salary || $-1 0 0 0 +-------------------++--------------------------------- + || $-1 $1 0 0 - $ hledger balance --quarterly income expenses -E - Balance changes in 2008: - - || 2008q1 2008q2 2008q3 2008q4 - ===================++================================= - expenses:food || 0 $1 0 0 - expenses:supplies || 0 $1 0 0 - income:gifts || 0 $-1 0 0 - income:salary || $-1 0 0 0 - -------------------++--------------------------------- - || $-1 $1 0 0 - - 2. With '--cumulative': each column shows the ending balance for that - period, accumulating the changes across periods, starting from 0 at - the report start date: + 2. A cumulative end balance report: with '--cumulative', each column + shows the end balance for that period, accumulating the changes + across periods, starting from 0 at the report start date: $ hledger balance --quarterly income expenses -E --cumulative Ending balances (cumulative) in 2008: @@ -2530,11 +2397,12 @@ different information: -------------------++------------------------------------------------- || $-1 0 0 0 - 3. With '--historical/-H': each column shows the actual historical - ending balance for that period, accumulating the changes across - periods, starting from the actual balance at the report start date. - This is useful eg for a multi-period balance sheet, and when you - are showing only the data after a certain start date: + 3. A historical end balance report: with '--historical/-H', each + column shows the actual historical end balance for that period, + accumulating the changes across periods, and including the balance + from any postings before the report start date. This is useful eg + for a multi-period balance sheet, and when you want to see balances + only after a certain date: $ hledger balance ^assets ^liabilities --quarterly --historical --begin 2008/4/1 Ending balances (historical) in 2008/04/01-2008/12/31: @@ -2552,9 +2420,6 @@ different information: '--row-total/-T', since summing end balances generally does not make sense. - Multicolumn balance reports display accounts in flat mode by default; -to see the hierarchy, use '--tree'. - With a reporting interval (like '--quarterly' above), the report start/end dates will be adjusted if necessary so that they encompass the displayed report periods. This is so that the first and last periods @@ -2605,17 +2470,158 @@ width of multicommodity reports. into 'less -RS' (-R for colour, -S to chop long lines). Eg: 'hledger bal -D --color=yes | less -RS'. +3.5.4 Depth limiting +-------------------- + +With a 'depth:N' query, or '--depth N' option, or just '-N', balance +reports will show accounts only to the specified depth. This is very +useful to hide low-level accounts and get an overview. Eg, limiting to +depth 1 shows the top-level accounts: + +$ hledger balance -N -1 + $-1 assets + $2 expenses + $-2 income + $1 liabilities + + Accounts at the depth limit will include the balances of any hidden +subaccounts (even in flat mode, which normally shows exclusive +balances). + + You can also drop account name components from the start of account +names, using '--drop N'. This can be useful to hide unwanted top-level +detail. + + +File: hledger.info, Node: Colour support, Next: Sorting by amount, Prev: , Up: balance + +3.5.5 Colour support +-------------------- + +In terminal output, when colour is enabled, the balance command shows +negative amounts in red. + + +File: hledger.info, Node: Sorting by amount, Next: Percentages, Prev: Colour support, Up: balance + +3.5.6 Sorting by amount +----------------------- + +With '-S'/'--sort-amount', accounts with the largest (most positive) +balances are shown first. For example, 'hledger bal expenses -MAS' +shows your biggest 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 sign-flipping reports +like 'balancesheet' or 'incomestatement', which also support '-S'. Eg: +'hledger is -MAS'. + + +File: hledger.info, Node: Percentages, Next: Customising single-period balance reports, Prev: Sorting by amount, Up: balance + +3.5.7 Percentages +----------------- + +With '-%' or '--percent', balance reports show each account's value +expressed as a percentage of the column's total. This is useful to get +an overview of the relative sizes of account balances. For example to +obtain an overview of expenses: + +$ hledger balance expenses -% + 100.0 % expenses + 50.0 % food + 50.0 % supplies +-------------------- + 100.0 % + + Note that '--tree' does not have an effect on '-%'. The percentages +are always relative to the total sum of each column, they are never +relative to the parent account. + + Since the percentages are relative to the columns sum, it is usually +not useful to calculate percentages if the signs of the amounts are +mixed. Although the results are technically correct, they are most +likely useless. Especially in a balance report that sums up to zero (eg +'hledger balance -B') all percentage values will be zero. + + This flag does not work if the report contains any mixed commodity +accounts. If there are mixed commodity accounts in the report be sure +to use '-V' or '-B' to coerce the report into using a single commodity. + + +File: hledger.info, Node: Customising single-period balance reports, Next: Budget report, Prev: Percentages, Up: balance + +3.5.8 Customising single-period balance reports +----------------------------------------------- + +You can customise the layout of single-period balance reports with +'--format FMT', which sets the format of each line. Eg: + +$ hledger balance --format "%20(account) %12(total)" + assets $-1 + bank:saving $1 + cash $-2 + expenses $2 + food $1 + supplies $1 + income $-2 + gifts $-1 + salary $-1 + liabilities:debts $1 +--------------------------------- + 0 + + The FMT format string (plus a newline) specifies the formatting +applied to each account/balance pair. It may contain any suitable text, +with data fields interpolated like so: + + '%[MIN][.MAX](FIELDNAME)' + + * MIN pads with spaces to at least this width (optional) + + * MAX truncates at this width (optional) + + * FIELDNAME must be enclosed in parentheses, and can be one of: + + * 'depth_spacer' - a number of spaces equal to the account's + depth, or if MIN is specified, MIN * depth spaces. + * 'account' - the account's name + * 'total' - the account's balance/posted total, right justified + + Also, FMT can begin with an optional prefix to control how +multi-commodity amounts are rendered: + + * '%_' - render on multiple lines, bottom-aligned (the default) + * '%^' - render on multiple lines, top-aligned + * '%,' - render on one line, comma-separated + + There are some quirks. Eg in one-line mode, '%(depth_spacer)' has no +effect, instead '%(account)' has indentation built in. Experimentation +may be needed to get pleasing results. + + Some example formats: + + * '%(total)' - the account's total + * '%-20.20(account)' - the account's name, left justified, padded to + 20 characters and clipped at 20 characters + * '%,%-50(account) %25(total)' - account name padded to 50 + characters, total padded to 20 characters, with multiple + commodities rendered on one line + * '%20(total) %2(depth_spacer)%-(account)' - the default format for + the single-column balance report +  -File: hledger.info, Node: Budget report, Prev: Multicolumn balance report, Up: balance +File: hledger.info, Node: Budget report, Prev: Customising single-period balance reports, Up: balance 3.5.9 Budget report ------------------- -With '--budget', extra columns are displayed showing budget goals for -each account and period, if any. Budget goals are defined by periodic -transactions. This is very useful for comparing planned and actual -income, expenses, time usage, etc. -budget is most often combined with -a report interval. +There is also a special balance report mode for showing budget +performance. The '--budget' flag activates extra columns showing the +budget goals for each account and period, if any. For this report, +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 expense categories to construct a minimal monthly budget: @@ -4297,99 +4303,98 @@ Node: aregister and custom posting dates76512 Ref: #aregister-and-custom-posting-dates76676 Node: balance77497 Ref: #balance77614 -Node: Classic balance report79240 -Ref: #classic-balance-report79413 -Node: Customising the classic balance report80737 -Ref: #customising-the-classic-balance-report80965 -Node: Colour support83041 -Ref: #colour-support83208 -Node: Flat mode83304 -Ref: #flat-mode83452 -Node: Depth limited balance reports83865 -Ref: #depth-limited-balance-reports84050 -Node: Percentages84506 -Ref: #percentages84663 -Node: Sorting by amount85800 -Ref: #sorting-by-amount85966 -Node: Multicolumn balance report86460 -Ref: #multicolumn-balance-report86646 -Node: Budget report92243 -Ref: #budget-report92377 -Node: Budget report start date97666 -Ref: #budget-report-start-date97831 -Node: Nested budgets99163 -Ref: #nested-budgets99308 -Node: balancesheet102748 -Ref: #balancesheet102884 -Node: balancesheetequity104396 -Ref: #balancesheetequity104545 -Node: cashflow105621 -Ref: #cashflow105743 -Node: check106959 -Ref: #check107062 -Node: Basic checks107667 -Ref: #basic-checks107783 -Node: Strict checks108276 -Ref: #strict-checks108415 -Node: Other checks108658 -Ref: #other-checks108796 -Node: Add-on checks109094 -Ref: #add-on-checks109212 -Node: close109665 -Ref: #close109767 -Node: close usage111289 -Ref: #close-usage111382 -Node: codes114195 -Ref: #codes114303 -Node: commodities115015 -Ref: #commodities115142 -Node: descriptions115224 -Ref: #descriptions115352 -Node: diff115656 -Ref: #diff115762 -Node: files116809 -Ref: #files116909 -Node: help117056 -Ref: #help117156 -Node: import118237 -Ref: #import118351 -Node: Importing balance assignments119273 -Ref: #importing-balance-assignments119454 -Node: Commodity display styles120103 -Ref: #commodity-display-styles120274 -Node: incomestatement120403 -Ref: #incomestatement120536 -Node: notes121881 -Ref: #notes121995 -Node: rewrite122363 -Ref: #rewrite122469 -Node: Re-write rules in a file124375 -Ref: #re-write-rules-in-a-file124536 -Node: Diff output format125685 -Ref: #diff-output-format125866 -Node: rewrite vs print --auto126958 -Ref: #rewrite-vs.-print---auto127116 -Node: roi127672 -Ref: #roi127770 -Node: stats139980 -Ref: #stats140079 -Node: tags140867 -Ref: #tags140965 -Node: test141484 -Ref: #test141592 -Node: Add-on commands142339 -Ref: #add-on-commands142485 -Node: Add-on command flags143249 -Ref: #add-on-command-flags143423 -Node: Making add-on commands144003 -Ref: #making-add-on-commands144157 -Node: ENVIRONMENT144750 -Ref: #environment144862 -Node: FILES145847 -Ref: #files-1145950 -Node: LIMITATIONS146163 -Ref: #limitations146282 -Node: TROUBLESHOOTING147025 -Ref: #troubleshooting147138 +Node: Single-period flat balance report79269 +Ref: #single-period-flat-balance-report79475 +Node: Single-period tree-mode balance report80179 +Ref: #single-period-tree-mode-balance-report80431 +Node: Multi-period balance report81876 +Ref: #multi-period-balance-report82073 +Ref: #depth-limiting-187766 +Node: Colour support88462 +Ref: #colour-support88599 +Node: Sorting by amount88695 +Ref: #sorting-by-amount88849 +Node: Percentages89343 +Ref: #percentages89512 +Node: Customising single-period balance reports90649 +Ref: #customising-single-period-balance-reports90874 +Node: Budget report92997 +Ref: #budget-report93146 +Node: Budget report start date98476 +Ref: #budget-report-start-date98641 +Node: Nested budgets99973 +Ref: #nested-budgets100118 +Node: balancesheet103558 +Ref: #balancesheet103694 +Node: balancesheetequity105206 +Ref: #balancesheetequity105355 +Node: cashflow106431 +Ref: #cashflow106553 +Node: check107769 +Ref: #check107872 +Node: Basic checks108477 +Ref: #basic-checks108593 +Node: Strict checks109086 +Ref: #strict-checks109225 +Node: Other checks109468 +Ref: #other-checks109606 +Node: Add-on checks109904 +Ref: #add-on-checks110022 +Node: close110475 +Ref: #close110577 +Node: close usage112099 +Ref: #close-usage112192 +Node: codes115005 +Ref: #codes115113 +Node: commodities115825 +Ref: #commodities115952 +Node: descriptions116034 +Ref: #descriptions116162 +Node: diff116466 +Ref: #diff116572 +Node: files117619 +Ref: #files117719 +Node: help117866 +Ref: #help117966 +Node: import119047 +Ref: #import119161 +Node: Importing balance assignments120083 +Ref: #importing-balance-assignments120264 +Node: Commodity display styles120913 +Ref: #commodity-display-styles121084 +Node: incomestatement121213 +Ref: #incomestatement121346 +Node: notes122691 +Ref: #notes122805 +Node: rewrite123173 +Ref: #rewrite123279 +Node: Re-write rules in a file125185 +Ref: #re-write-rules-in-a-file125346 +Node: Diff output format126495 +Ref: #diff-output-format126676 +Node: rewrite vs print --auto127768 +Ref: #rewrite-vs.-print---auto127926 +Node: roi128482 +Ref: #roi128580 +Node: stats140790 +Ref: #stats140889 +Node: tags141677 +Ref: #tags141775 +Node: test142294 +Ref: #test142402 +Node: Add-on commands143149 +Ref: #add-on-commands143295 +Node: Add-on command flags144059 +Ref: #add-on-command-flags144233 +Node: Making add-on commands144813 +Ref: #making-add-on-commands144967 +Node: ENVIRONMENT145560 +Ref: #environment145672 +Node: FILES146657 +Ref: #files-1146760 +Node: LIMITATIONS146973 +Ref: #limitations147092 +Node: TROUBLESHOOTING147835 +Ref: #troubleshooting147948  End Tag Table diff --git a/hledger/hledger.txt b/hledger/hledger.txt index 69a6afd2a42..286b9a070b3 100644 --- a/hledger/hledger.txt +++ b/hledger/hledger.txt @@ -1969,9 +1969,29 @@ COMMANDS The balance command can produce several styles of report: - Classic balance report - This is the original balance report, as found in Ledger. It usually - looks like this: + Single-period flat balance report + This is the default for hledger's balance command: a flat list of all + (or with a query, matched) accounts, showing full account names. Ac- + counts are sorted by declaration order if any, and then by account + name. Accounts which have zero balance are not shown unless -E/--empty + is used. The reported balances' total is shown as the last line, un- + less disabled by -N/--no-total. + + $ hledger bal + $1 assets:bank:saving + $-2 assets:cash + $1 expenses:food + $1 expenses:supplies + $-1 income:gifts + $-1 income:salary + $1 liabilities:debts + -------------------- + 0 + + Single-period tree-mode balance report + With the -t/--tree flag, accounts are displayed hierarchically, showing + subaccounts as short names indented below their parent. (This is the + default style in Ledger and in older hledger versions.) $ hledger balance $-1 assets @@ -1987,189 +2007,52 @@ COMMANDS -------------------- 0 - By default, accounts are displayed hierarchically, with subaccounts in- - dented below their parent, with accounts at each level of the tree - sorted by declaration order if declared, then by account name. - - "Boring" accounts, which contain a single interesting subaccount and no - balance of their own, are elided into the following line for more com- - pact output. (Eg above, the "liabilities" account.) Use --no-elide to - prevent this. - - Account balances are "inclusive" - they include the balances of any - subaccounts. - - Accounts which have zero balance (and no non-zero subaccounts) are - omitted. Use -E/--empty to show them. - - A final total is displayed by default; use -N/--no-total to suppress - it, eg: - - $ hledger balance -p 2008/6 expenses --no-total - $2 expenses - $1 food - $1 supplies - - Customising the classic balance report - You can customise the layout of classic balance reports with --format - FMT: - - $ hledger balance --format "%20(account) %12(total)" - assets $-1 - bank:saving $1 - cash $-2 - expenses $2 - food $1 - supplies $1 - income $-2 - gifts $-1 - salary $-1 - liabilities:debts $1 - --------------------------------- - 0 - - The FMT format string (plus a newline) specifies the formatting applied - to each account/balance pair. It may contain any suitable text, with - data fields interpolated like so: - - %[MIN][.MAX](FIELDNAME) - - o MIN pads with spaces to at least this width (optional) - - o MAX truncates at this width (optional) - - 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 - 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- - modity amounts are rendered: - - o %_ - render on multiple lines, bottom-aligned (the default) - - o %^ - render on multiple lines, top-aligned - - o %, - render on one line, comma-separated - - There are some quirks. Eg in one-line mode, %(depth_spacer) has no ef- - fect, instead %(account) has indentation built in. Experimentation 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 - 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 - one line - - o %20(total) %2(depth_spacer)%-(account) - the default format for the - single-column balance report - - Colour support - In terminal output, when colour is enabled, the balance command shows - negative amounts in red. - - Flat mode - To see a flat list instead of the default hierarchical display, use - --flat. In this mode, accounts (unless depth-clipped) show their full - names and "exclusive" balance, excluding any subaccount balances. In - this mode, you can also use --drop N to omit the first few account name - components. - - $ hledger balance -p 2008/6 expenses -N --flat --drop 1 - $1 food - $1 supplies - - Depth limited balance reports - With --depth N or depth:N or just -N, balance reports show accounts - only to the specified numeric depth. This is very useful to summarise - a complex set of accounts and get an overview. - - $ hledger balance -N -1 - $-1 assets - $2 expenses - $-2 income - $1 liabilities - - Flat-mode balance reports, which normally show exclusive balances, show - inclusive balances at the depth limit. - - Percentages - With -% or --percent, balance reports show each account's value ex- - pressed as a percentage of the column's total. This is useful to get - an overview of the relative sizes of account balances. For example to - obtain an overview of expenses: - - $ hledger balance expenses -% - 100.0 % expenses - 50.0 % food - 50.0 % supplies - -------------------- - 100.0 % - - Note that --tree does not have an effect on -%. The percentages are - always relative to the total sum of each column, they are never rela- - tive to the parent account. - - Since the percentages are relative to the columns sum, it is usually - not useful to calculate percentages if the signs of the amounts are - mixed. Although the results are technically correct, they are most - likely useless. Especially in a balance report that sums up to zero - (eg hledger balance -B) all percentage values will be zero. - - This flag does not work if the report contains any mixed commodity ac- - counts. If there are mixed commodity accounts in the report be sure to - use -V or -B to coerce the report into using a single commodity. - - Sorting by amount - With -S/--sort-amount, accounts with the largest (most positive) bal- - ances are shown first. For example, hledger bal expenses -MAS shows - your biggest 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 --in- - vert to flip the signs. Or, use one of the sign-flipping reports like - balancesheet or incomestatement, which also support -S. Eg: hledger is - -MAS. - - Multicolumn balance report - Multicolumn or tabular balance reports are a very useful hledger fea- - ture, and usually the preferred style. They share many of the above - features, but they show the report as a table, with columns represent- - ing time periods. This mode is activated by providing a reporting in- - terval. - - There are three types of multicolumn balance report, showing different + For more compact output, "boring" accounts containing a single inter- + esting subaccount and no balance of their own (assets:bank and liabili- + ties here) are elided into the following line, unless --no-elide is + used. And accounts which have zero balance and no non-zero subaccounts + are omitted, unless -E/--empty is used. + + Account balances in tree mode are "inclusive" - they include the bal- + ances of any subaccounts. Eg, the assets $-1 balance here includes the + $1 from assets:bank:saving and the $-2 from assets:cash. (And it would + include balance posted to the assets account itself, if there was any). + Note this causes some repetition, and the final total (0) is the sum of + the top-level balances, not of all the balances shown. + + Each group of sibling accounts is sorted separately, by declaration or- + der and then by account name. + + Multi-period balance report + Multi-period balance reports are a very useful hledger feature, acti- + vated if you provide one of the reporting interval flags, such as + -M/--monthly. They are similar to single-period balance reports, but + they show the report as a table, with columns representing one or more + successive time periods. This is the usually the preferred style of + balance report in hledger (even for a single period). + + Multi-period balance reports come in several types, showing different information: - 1. By default: each column shows the sum of postings in that period, ie - the account's change of balance in that period. This is useful eg - for a monthly income statement: + 1. A balance change report: by default, each column shows the sum of + postings in that period, ie the account's change of balance in that + period. This is useful eg for a monthly income statement: - $ hledger balance --quarterly income expenses -E - Balance changes in 2008: + $ hledger balance --quarterly income expenses -E + Balance changes in 2008: - || 2008q1 2008q2 2008q3 2008q4 - ===================++================================= - expenses:food || 0 $1 0 0 - expenses:supplies || 0 $1 0 0 - income:gifts || 0 $-1 0 0 - income:salary || $-1 0 0 0 - -------------------++--------------------------------- - || $-1 $1 0 0 + || 2008q1 2008q2 2008q3 2008q4 + ===================++================================= + expenses:food || 0 $1 0 0 + expenses:supplies || 0 $1 0 0 + income:gifts || 0 $-1 0 0 + income:salary || $-1 0 0 0 + -------------------++--------------------------------- + || $-1 $1 0 0 - 2. With --cumulative: each column shows the ending balance for that pe- - riod, accumulating the changes across periods, starting from 0 at - the report start date: + 2. A cumulative end balance report: with --cumulative, each column + shows the end balance for that period, accumulating the changes + across periods, starting from 0 at the report start date: $ hledger balance --quarterly income expenses -E --cumulative Ending balances (cumulative) in 2008: @@ -2183,11 +2066,12 @@ COMMANDS -------------------++------------------------------------------------- || $-1 0 0 0 - 3. With --historical/-H: each column shows the actual historical ending - balance for that period, accumulating the changes across periods, - starting from the actual balance at the report start date. This is - useful eg for a multi-period balance sheet, and when you are showing - only the data after a certain start date: + 3. A historical end balance report: with --historical/-H, each column + shows the actual historical end balance for that period, accumulat- + ing the changes across periods, and including the balance from any + postings before the report start date. This is useful eg for a + multi-period balance sheet, and when you want to see balances only + after a certain date: $ hledger balance ^assets ^liabilities --quarterly --historical --begin 2008/4/1 Ending balances (historical) in 2008/04/01-2008/12/31: @@ -2204,26 +2088,23 @@ COMMANDS Note that --cumulative or --historical/-H disable --row-total/-T, since summing end balances generally does not make sense. - Multicolumn balance reports display accounts in flat mode by default; - to see the hierarchy, use --tree. - - With a reporting interval (like --quarterly above), the report - start/end dates will be adjusted if necessary so that they encompass + With a reporting interval (like --quarterly above), the report + start/end dates will be adjusted if necessary so that they encompass the displayed report periods. This is so that the first and last peri- ods will be "full" and comparable to the others. - The -E/--empty flag does two things in multicolumn balance reports: + The -E/--empty flag does two things in multicolumn balance reports: first, the report will show all columns within the specified report pe- - riod (without -E, leading and trailing columns with all zeroes are not - shown). Second, all accounts which existed at the report start date - will be considered, not just the ones with activity during the report - period (use -E to include low-activity accounts which would otherwise + riod (without -E, leading and trailing columns with all zeroes are not + shown). Second, all accounts which existed at the report start date + will be considered, not just the ones with activity during the report + period (use -E to include low-activity accounts which would otherwise would be omitted). The -T/--row-total flag adds an additional column showing the total for each row. - The -A/--average flag adds a column showing the average value in each + The -A/--average flag adds a column showing the average value in each row. Here's an example of all three: @@ -2244,27 +2125,153 @@ COMMANDS (Average is rounded to the dollar here since all journal amounts are) - The --transpose flag can be used to exchange the rows and columns of a + The --transpose flag can be used to exchange the rows and columns of a multicolumn report. - When showing multicommodity amounts, multicolumn balance reports will + When showing multicommodity amounts, multicolumn balance reports will elide any amounts which have more than two commodities, since otherwise - columns could get very wide. The --no-elide flag disables this. Hid- - ing totals with the -N/--no-total flag can also help reduce the width + columns could get very wide. The --no-elide flag disables this. Hid- + ing totals with the -N/--no-total flag can also help reduce the width of multicommodity reports. When the report is still too wide, a good workaround is to pipe it into - less -RS (-R for colour, -S to chop long lines). Eg: hledger bal -D + less -RS (-R for colour, -S to chop long lines). Eg: hledger bal -D --color=yes | less -RS. + Depth limiting + With a depth:N query, or --depth N option, or just -N, balance reports + will show accounts only to the specified depth. This is very useful to + hide low-level accounts and get an overview. Eg, limiting to depth 1 + shows the top-level accounts: + + $ hledger balance -N -1 + $-1 assets + $2 expenses + $-2 income + $1 liabilities + + Accounts at the depth limit will include the balances of any hidden + subaccounts (even in flat mode, which normally shows exclusive bal- + ances). + + You can also drop account name components from the start of account + names, using --drop N. This can be useful to hide unwanted top-level + detail. + + Colour support + In terminal output, when colour is enabled, the balance command shows + negative amounts in red. + + Sorting by amount + With -S/--sort-amount, accounts with the largest (most positive) bal- + ances are shown first. For example, hledger bal expenses -MAS shows + your biggest 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 --in- + vert to flip the signs. Or, use one of the sign-flipping reports like + balancesheet or incomestatement, which also support -S. Eg: hledger is + -MAS. + + Percentages + With -% or --percent, balance reports show each account's value ex- + pressed as a percentage of the column's total. This is useful to get + an overview of the relative sizes of account balances. For example to + obtain an overview of expenses: + + $ hledger balance expenses -% + 100.0 % expenses + 50.0 % food + 50.0 % supplies + -------------------- + 100.0 % + + Note that --tree does not have an effect on -%. The percentages are + always relative to the total sum of each column, they are never rela- + tive to the parent account. + + Since the percentages are relative to the columns sum, it is usually + not useful to calculate percentages if the signs of the amounts are + mixed. Although the results are technically correct, they are most + likely useless. Especially in a balance report that sums up to zero + (eg hledger balance -B) all percentage values will be zero. + + This flag does not work if the report contains any mixed commodity ac- + counts. If there are mixed commodity accounts in the report be sure to + use -V or -B to coerce the report into using a single commodity. + + Customising single-period balance reports + You can customise the layout of single-period balance reports with + --format FMT, which sets the format of each line. Eg: + + $ hledger balance --format "%20(account) %12(total)" + assets $-1 + bank:saving $1 + cash $-2 + expenses $2 + food $1 + supplies $1 + income $-2 + gifts $-1 + salary $-1 + liabilities:debts $1 + --------------------------------- + 0 + + The FMT format string (plus a newline) specifies the formatting applied + to each account/balance pair. It may contain any suitable text, with + data fields interpolated like so: + + %[MIN][.MAX](FIELDNAME) + + o MIN pads with spaces to at least this width (optional) + + o MAX truncates at this width (optional) + + 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 + 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- + modity amounts are rendered: + + o %_ - render on multiple lines, bottom-aligned (the default) + + o %^ - render on multiple lines, top-aligned + + o %, - render on one line, comma-separated + + There are some quirks. Eg in one-line mode, %(depth_spacer) has no ef- + fect, instead %(account) has indentation built in. Experimentation 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 + 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 + one line + + o %20(total) %2(depth_spacer)%-(account) - the default format for the + single-column balance report + Budget report - With --budget, extra columns are displayed showing budget goals for - each account and period, if any. Budget goals are defined by periodic - transactions. This is very useful for comparing planned and actual in- - come, expenses, time usage, etc. --budget is most often combined with - a report interval. + There is also a special balance report mode for showing budget perfor- + mance. The --budget flag activates extra columns showing the budget + goals for each account and period, if any. For this report, 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 ex- + For example, you can take average monthly expenses in the common ex- pense categories to construct a minimal monthly budget: ;; Budget @@ -2311,26 +2318,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 flat mode. Eg assets, + o All parent accounts are always shown, even in flat mode. Eg assets, assets:bank, and expenses above. - o Amounts always include all subaccounts, budgeted or unbudgeted, even + o Amounts always include all subaccounts, budgeted or unbudgeted, even in flat mode. This means that the numbers displayed will not always add up! Eg above, - the expenses actual amount includes the gifts and supplies transac- - tions, but the expenses:gifts and expenses:supplies accounts are not + the expenses actual amount includes the gifts and supplies transac- + tions, but the expenses:gifts and expenses:supplies accounts are not shown, as they have no budget amounts declared. - This can be confusing. When you need to make things clearer, use the - -E/--empty flag, which will reveal all accounts including unbudgeted + This can be confusing. When you need to make things clearer, use the + -E/--empty flag, which will reveal all accounts including unbudgeted ones, giving the full picture. Eg: $ hledger balance -M --budget --empty @@ -2372,12 +2379,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 @@ -2396,9 +2403,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 @@ -2411,12 +2418,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: @@ -2426,13 +2433,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 to- + Transactions in expenses:personal:electronics will be counted both to- wards its $100 budget and $1100 of expenses:personal , and transactions - in any other subaccount of expenses:personal would be counted towards + 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: @@ -2458,9 +2465,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: @@ -2476,7 +2483,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 @@ -2495,14 +2502,14 @@ COMMANDS 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 al- + the Asset or Cash or Liability type, or otherwise all accounts under a + top-level asset or liability account (case insensitive, plurals al- lowed). Example: @@ -2527,25 +2534,25 @@ COMMANDS 0 With a reporting interval, multiple columns will be shown, one for each - report period. As with multicolumn balance reports, you can alter the - report mode with --change/--cumulative/--historical. Normally bal- - ancesheet shows historical ending balances, which is what you need for - a balance sheet; note this means it ignores report begin dates (and - -T/--row-total, since summing end balances generally does not make - sense). Instead of absolute values percentages can be displayed with + report period. As with multicolumn balance reports, you can alter the + report mode with --change/--cumulative/--historical. Normally bal- + ancesheet shows historical ending balances, which is what you need for + a balance sheet; note this means it ignores report begin dates (and + -T/--row-total, since summing end balances generally does not make + sense). Instead of absolute values percentages can be displayed with -%. This command also supports the output destination and output format op- - tions The output formats supported are txt, csv, html, and (experimen- + tions The output formats supported are txt, csv, html, and (experimen- tal) 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 de- + The asset, liability and equity accounts shown are those accounts de- clared with the Asset, Cash, Liability or Equity type, or otherwise all accounts under a top-level asset, liability or equity account (case in- sensitive, plurals allowed). @@ -2577,18 +2584,18 @@ COMMANDS 0 This command also supports the output destination and output format op- - tions The output formats supported are txt, csv, html, and (experimen- + tions The output formats supported are txt, csv, html, and (experimen- tal) 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, re- + 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, re- ceivable or A/R in their name. Example: @@ -2608,22 +2615,22 @@ COMMANDS $-1 With a reporting interval, multiple columns will be shown, one for each - report period. Normally cashflow shows changes in assets per period, - though as with multicolumn balance reports you can alter the report + report period. Normally cashflow shows changes in assets per period, + though as with multicolumn balance reports you can alter the report mode with --change/--cumulative/--historical. Instead of absolute val- ues percentages can be displayed with -%. This command also supports the output destination and output format op- - tions The output formats supported are txt, csv, html, and (experimen- + tions The output formats supported are txt, csv, html, and (experimen- tal) json. check check Check for various kinds of errors in your data. experimental - 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 + 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. Some examples: hledger check # basic checks @@ -2637,15 +2644,15 @@ 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 are always run by this and other commands when -s/--strict is + These are always run by this and other commands when -s/--strict is used (strict mode): o accounts - all account names used by transactions have been declared @@ -2653,13 +2660,13 @@ COMMANDS o commodities - all commodity symbols used have been declared Other checks - These checks can be run by specifying their names as arguments to the + These checks can be run by specifying their names as arguments to the check command: - o ordereddates - transactions are ordered by date (similar to the old + o ordereddates - transactions are ordered by date (similar to the old check-dates command) - o uniqueleafnames - all account leaf names are unique (similar to the + o uniqueleafnames - all account leaf names are unique (similar to the old check-dupes command) Add-on checks @@ -2667,10 +2674,10 @@ COMMANDS as add-on commands in https://github.com/simonmichael/hledger/tree/mas- ter/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 your own similar scripts to perform custom checks; Cook- @@ -2678,64 +2685,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 revenues/ex- + balances forward into a new journal file, or to close out revenues/ex- penses 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 in- - formation 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 + formation 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 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/re- + Both transactions will include balance assertions for the closed/re- opened accounts. You probably shouldn't use status or realness filters - (like -C or -R or status:) with this command, or the generated balance - assertions will depend on these flags. Likewise, if you run this com- - mand with --auto, the balance assertions will probably always require + (like -C or -R or status:) with this command, or the generated balance + assertions will depend on these flags. Likewise, if you run this com- + mand with --auto, the balance assertions will probably always require --auto. Examples: @@ -2776,13 +2783,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. @@ -2822,7 +2829,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: @@ -2834,18 +2841,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. @@ -2863,20 +2870,20 @@ COMMANDS files files - List all files included in the journal. With a REGEX argument, only + List all files included in the journal. With a REGEX argument, only file names matching the regular expression (case sensitive) are shown. help help Show any of the hledger manuals. - The help command displays any of the main hledger manuals, in one of - several ways. Run it with no argument to list the manuals, or provide + The help command displays any of the main hledger manuals, in one of + several ways. Run it with no argument to list the manuals, or provide a full or partial manual name to select one. - hledger manuals are available in several formats. hledger help will - use the first of these display methods that it finds: info, man, - $PAGER, less, stdout (or when non-interactive, just stdout). You can + hledger manuals are available in several formats. hledger help will + use the first of these display methods that it finds: info, man, + $PAGER, less, stdout (or when non-interactive, just stdout). You can force a particular viewer with the --info, --man, --pager, --cat flags. Examples: @@ -2903,9 +2910,9 @@ 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. The input files are specified as arguments - no need to write -f before @@ -2916,23 +2923,23 @@ COMMANDS ing transactions are always added to the input files in increasing date order, and by saving .latest.FILE state files. - The --dry-run output is in journal format, so you can filter it, eg to + The --dry-run output is in journal format, so you can filter it, eg to see only uncategorised transactions: $ hledger import --dry ... | hledger -f- print unknown --ignore-assertions 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 @@ -2941,13 +2948,13 @@ COMMANDS incomestatement incomestatement, is - This command displays an income statement, showing revenues and ex- + This command displays an income statement, showing revenues and ex- penses during one or more periods. Amounts are shown with normal posi- tive sign, as in conventional financial statements. 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: @@ -2974,13 +2981,13 @@ COMMANDS 0 With a reporting interval, multiple columns will be shown, one for each - report period. Normally incomestatement shows revenues/expenses per - period, though as with multicolumn balance reports you can alter the - report mode with --change/--cumulative/--historical. Instead of abso- + report period. Normally incomestatement shows revenues/expenses per + period, though as with multicolumn balance reports you can alter the + report mode with --change/--cumulative/--historical. Instead of abso- lute values percentages can be displayed with -%. This command also supports the output destination and output format op- - tions The output formats supported are txt, csv, html, and (experimen- + tions The output formats supported are txt, csv, html, and (experimen- tal) json. notes @@ -2988,8 +2995,8 @@ COMMANDS List the unique notes that appear in transactions. This command lists the unique notes that appear in transactions, in al- - phabetic order. You can add a query to select a subset of transac- - tions. The note is the part of the transaction description after a | + phabetic order. You can add a query to select a subset of transac- + tions. The note is the part of the transaction description after a | character (or if there is no |, the whole description). Example: @@ -3001,13 +3008,13 @@ COMMANDS 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: @@ -3023,7 +3030,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: @@ -3033,16 +3040,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 in- + factor for an amount of original matched posting. If the amount in- cludes a commodity name, the new posting amount will be in the new com- - modity; otherwise, it will be in the matched posting amount's commod- + modity; otherwise, it will be in the matched posting amount's commod- ity. Re-write rules in a file - During the run this tool will execute so called "Automated Transac- + During the run this tool will execute so called "Automated Transac- tions" found in any journal it process. I.e instead of specifying this operations in command line you can put them in a journal file. @@ -3057,7 +3064,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. @@ -3070,12 +3077,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' @@ -3099,10 +3106,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: @@ -3110,49 +3117,49 @@ 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. - This command assumes that you have account(s) that hold nothing but + This command assumes that you have account(s) that hold nothing but your investments and whenever you record current appraisal/valuation of these investments you offset unrealized profit and loss into account(s) that, again, hold nothing but unrealized profit and loss. - Any transactions affecting balance of investment account(s) and not - originating from unrealized profit and loss account(s) are assumed to + Any transactions affecting balance of investment account(s) and not + originating from unrealized profit and loss account(s) are assumed to be your investments or withdrawals. - At a minimum, you need to supply a query (which could be just an ac- + At a minimum, you need to supply a query (which could be just an ac- count name) to select your investments with --inv, and another query to identify your profit and loss transactions with --pnl. - 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. Note, in some cases this report can fail, for these reasons: - o Error (NotBracketed): No solution for Internal Rate of Return (IRR). - Possible causes: IRR is huge (>1000000%), balance of investment be- + o Error (NotBracketed): No solution for Internal Rate of Return (IRR). + Possible causes: IRR is huge (>1000000%), balance of investment be- comes negative at some point in time. - o Error (SearchFailed): Failed to find solution for Internal Rate of + o Error (SearchFailed): Failed to find solution for Internal Rate of Return (IRR). Either search does not converge to a solution, or con- verges too slowly. @@ -3163,67 +3170,67 @@ COMMANDS More background: - "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 pe- - riod between in-flow or out-flow of money, and then combine them in a + 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 pe- + riod between in-flow or out-flow of money, and then combine them in a way that gives you an annual rate of return that investment is expected to generate. - 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 - transactions that involve account(s) matching --inv argument and NOT + 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 + transactions that involve account(s) matching --inv argument and NOT involve account(s) matching --pnl argument. - Presumably, you will also record changes in the value of your invest- - ment, and balance them against "profit and loss" (or "unrealized + Presumably, you will also record changes in the value of your invest- + ment, and balance them against "profit and loss" (or "unrealized gains") account. Note that in order for IRR to compute the precise ef- - fect 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 + fect 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. - Implementation of IRR in hledger should match the XIRR formula in Ex- + Implementation of IRR in hledger should match the XIRR formula in Ex- cel. - 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 and + break the history of your investment into periods between in-flows and out-flows to compute rate of return per each period and then a compound rate of return. However, internal workings of TWR are quite different. - 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. - 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 * Ex- - planation of TWR * Examples of computing IRR and TWR and discussion of + References: * Explanation of rate of return * Explanation of IRR * Ex- + planation of TWR * Examples of computing IRR and TWR and discussion of the limitations of both metrics More examples: - Lets say that we found an investment in Snake Oil that is proising to + Lets say that we found an investment in Snake Oil that is proising to give us 10% annually: 2019-01-01 Investing in Snake Oil @@ -3234,7 +3241,7 @@ COMMANDS investment:snake oil = $110 equity:unrealized gains - For now, basic computation of the rate of return, as well as IRR and + For now, basic computation of the rate of return, as well as IRR and TWR, gives us the expected 10%: $ hledger roi -Y --inv investment --pnl "unrealized" @@ -3244,10 +3251,10 @@ COMMANDS | 1 || 2019-01-01 | 2019-12-31 || 0 | 100 | 110 | 10 || 10.00% | 10.00% | +---++------------+------------++---------------+----------+-------------+-----++--------+--------+ - However, lets say that shorty after investing in the Snake Oil we - started to have second thoughs, so we prompty withdrew $90, leaving - only $10 in. Before Christmas, though, we started to get the "fear of - mission out", so we put the $90 back in. So for most of the year, our + However, lets say that shorty after investing in the Snake Oil we + started to have second thoughs, so we prompty withdrew $90, leaving + only $10 in. Before Christmas, though, we started to get the "fear of + mission out", so we put the $90 back in. So for most of the year, our investment was just $10 dollars, and it gave us just $1 in growth: 2019-01-01 Investing in Snake Oil @@ -3278,10 +3285,10 @@ COMMANDS Here, IRR tells us that we made close to 10% on the $10 dollars that we had in the account most of the time. And TWR is ... just 1%? Why? - Based on the transactions in our journal, TWR "think" that we are buy- - ing back $90 worst of Snake Oil at the same price that it had at the + Based on the transactions in our journal, TWR "think" that we are buy- + ing back $90 worst of Snake Oil at the same price that it had at the beginning of they year, and then after that our $100 investment gets $1 - increase in value, or 1% of $100. Let's take a closer look at what is + increase in value, or 1% of $100. Let's take a closer look at what is happening here by asking for quarterly reports instead of annual: $ hledger roi -Q --inv investment --pnl "unrealized" @@ -3294,10 +3301,10 @@ COMMANDS | 4 || 2019-10-01 | 2019-12-31 || 10 | 90 | 101 | 1 || 37.80% | 4.03% | +---++------------+------------++---------------+----------+-------------+-----++--------+-------+ - Now both IRR and TWR are thrown off by the fact that all of the growth - for our investment happens in Q4 2019. This happes because IRR compu- + Now both IRR and TWR are thrown off by the fact that all of the growth + for our investment happens in Q4 2019. This happes because IRR compu- tation is still yielding 9.32% and TWR is still 1%, but this time these - are rates for three month period instead of twelve, so in order to get + are rates for three month period instead of twelve, so in order to get an annual rate they should be multiplied by four! Let's try to keep a better record of how Snake Oil grew in value: @@ -3342,10 +3349,10 @@ COMMANDS | 4 || 2019-10-01 | 2019-12-31 || 10.75 | 90 | 101.00 | 0.25 || 8.05% | 1.00% | +---++------------+------------++---------------+----------+-------------+------++--------+--------+ - Something is still wrong with TWR computation for Q4, and if you have - been paying attention you know what it is already: big $90 buy-back is - recorded prior to the only transaction that captures the change of - value of Snake Oil that happened in this time period. Lets combine + Something is still wrong with TWR computation for Q4, and if you have + been paying attention you know what it is already: big $90 buy-back is + recorded prior to the only transaction that captures the change of + value of Snake Oil that happened in this time period. Lets combine transactions from 30th and 31st of Dec into one: 2019-12-30 Fear of missing out and growth of Snake Oil @@ -3366,7 +3373,7 @@ COMMANDS | 4 || 2019-10-01 | 2019-12-31 || 10.75 | 90 | 101.00 | 0.25 || 8.05% | 9.57% | +---++------------+------------++---------------+----------+-------------+------++--------+--------+ - And for annual report, TWR now reports the exact profitability of our + And for annual report, TWR now reports the exact profitability of our investment: $ hledger roi -Y --inv investment --pnl "unrealized" @@ -3380,8 +3387,8 @@ COMMANDS 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: @@ -3399,35 +3406,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 -- @@ -3436,12 +3443,12 @@ 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). Add-on commands Any programs or scripts in your PATH named named hledger-SOMETHING will - also appear in the commands list (with a + mark). These are called + also appear in the commands list (with a + mark). These are called add-on commands. These offical add-ons are maintained and released along with hledger: @@ -3456,10 +3463,10 @@ COMMANDS o interest generates interest transactions according to various schemes - o stockquotes downloads market prices for your commodities from Alpha- + o stockquotes downloads market prices for your commodities from Alpha- Vantage (experimental) - Additional experimental add-ons, which may not be in a working state, + Additional experimental add-ons, which may not be in a working state, can be found in the bin/ directory in the hledger repo. Add-on command flags @@ -3474,8 +3481,8 @@ COMMANDS (because the --serve flag belongs to hledger-web, not hledger). - The -h/--help and --version flags work without --, with their position - deciding which program they refer to. Eg hledger -h web shows + The -h/--help and --version flags work without --, with their position + deciding which program they refer to. Eg hledger -h web shows hledger's help, hledger web -h shows hledger-web's help. If you have any trouble with this, remember you can always run the add- @@ -3488,28 +3495,28 @@ 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 + 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. ENVIRONMENT LEDGER_FILE The journal file path when not specified with -f. Default: - ~/.hledger.journal (on windows, perhaps C:/Users/USER/.hledger.jour- + ~/.hledger.journal (on windows, perhaps C:/Users/USER/.hledger.jour- nal). - A typical value is ~/DIR/YYYY.journal, where DIR is a version-con- - trolled finance directory and YYYY is the current year. Or ~/DIR/cur- + A typical value is ~/DIR/YYYY.journal, where DIR is a version-con- + trolled finance directory and YYYY is the current year. Or ~/DIR/cur- rent.journal, where current.journal is a symbolic link to YYYY.journal. On Mac computers, you can set this and other environment variables in a - more thorough way that also affects applications started from the GUI + more thorough way that also affects applications started from the GUI (say, an Emacs dock icon). Eg on MacOS Catalina I have a ~/.MacOSX/en- vironment.plist file containing @@ -3519,21 +3526,21 @@ ENVIRONMENT To see the effect you may need to killall Dock, or reboot. - COLUMNS The screen width used by the register command. Default: the + COLUMNS The screen width used by the register command. Default: the full terminal width. - NO_COLOR If this variable exists with any value, hledger will not use - ANSI color codes in terminal output. This overrides the + NO_COLOR If this variable exists with any value, hledger will not use + ANSI color codes in terminal output. This overrides the --color/--colour option. FILES - Reads data from one or more files in hledger journal, timeclock, time- - dot, or CSV format specified with -f, or $LEDGER_FILE, or - $HOME/.hledger.journal (on windows, perhaps + Reads data from one or more files in hledger journal, timeclock, time- + dot, or CSV format specified with -f, or $LEDGER_FILE, or + $HOME/.hledger.journal (on windows, perhaps C:/Users/USER/.hledger.journal). LIMITATIONS - The need to precede add-on command options with -- when invoked from + The need to precede add-on command options with -- when invoked from hledger is awkward. When input data contains non-ascii characters, a suitable system locale @@ -3549,36 +3556,36 @@ LIMITATIONS In a Cygwin/MSYS/Mintty window, the tab key is not supported in hledger add. - Not all of Ledger's journal file syntax is supported. See file format + Not all of Ledger's journal file syntax is supported. See file format differences. - On large data files, hledger is slower and uses more memory than + On large data files, hledger is slower and uses more memory than Ledger. TROUBLESHOOTING - Here are some issues you might encounter when you run hledger (and re- - member you can also seek help from the IRC channel, mail list or bug + Here are some issues you might encounter when you run hledger (and re- + member you can also seek help from the IRC channel, mail list or bug tracker): Successfully installed, but "No command 'hledger' found" stack and cabal install binaries into a special directory, which should - be added to your PATH environment variable. Eg on unix-like systems, + be added to your PATH environment variable. Eg on unix-like systems, that is ~/.local/bin and ~/.cabal/bin respectively. I set a custom LEDGER_FILE, but hledger is still using the default file - LEDGER_FILE should be a real environment variable, not just a shell - variable. The command env | grep LEDGER_FILE should show it. You may + LEDGER_FILE should be a real environment variable, not just a shell + variable. The command env | grep LEDGER_FILE should show it. You may need to use export. Here's an explanation. - Getting errors like "Illegal byte sequence" or "Invalid or incomplete - multibyte or wide character" or "commitAndReleaseBuffer: invalid argu- + Getting errors like "Illegal byte sequence" or "Invalid or incomplete + multibyte or wide character" or "commitAndReleaseBuffer: invalid argu- ment (invalid character)" Programs compiled with GHC (hledger, haskell build tools, etc.) need to have a UTF-8-aware locale configured in the environment, otherwise they - will fail with these kinds of errors when they encounter non-ascii + will fail with these kinds of errors when they encounter non-ascii characters. - To fix it, set the LANG environment variable to some locale which sup- + To fix it, set the LANG environment variable to some locale which sup- ports UTF-8. The locale you choose must be installed on your system. Here's an example of setting LANG temporarily, on Ubuntu GNU/Linux: @@ -3593,8 +3600,8 @@ TROUBLESHOOTING POSIX $ LANG=en_US.utf8 hledger -f my.journal print # ensure it is used for this command - If available, C.UTF-8 will also work. If your preferred locale isn't - listed by locale -a, you might need to install it. Eg on Ubuntu/De- + If available, C.UTF-8 will also work. If your preferred locale isn't + listed by locale -a, you might need to install it. Eg on Ubuntu/De- bian: $ apt-get install language-pack-fr @@ -3614,8 +3621,8 @@ TROUBLESHOOTING $ echo "export LANG=en_US.utf8" >>~/.bash_profile $ bash --login - Exact spelling and capitalisation may be important. Note the differ- - ence on MacOS (UTF-8, not utf8). Some platforms (eg ubuntu) allow + Exact spelling and capitalisation may be important. Note the differ- + ence on MacOS (UTF-8, not utf8). Some platforms (eg ubuntu) allow variant spellings, but others (eg macos) require it to be exact: $ locale -a | grep -iE en_us.*utf @@ -3625,7 +3632,7 @@ TROUBLESHOOTING REPORTING BUGS - Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel + Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel or hledger mail list) @@ -3646,4 +3653,4 @@ SEE ALSO -hledger-1.20.1 December 2020 HLEDGER(1) +hledger-1.20.3 December 2020 HLEDGER(1)