diff --git a/hledger-lib/hledger_journal.5 b/hledger-lib/hledger_journal.5 index d12f0139a..23020bde5 100644 --- a/hledger-lib/hledger_journal.5 +++ b/hledger-lib/hledger_journal.5 @@ -1061,11 +1061,8 @@ and a line containing just \f[C]end\ comment\f[] ends it. See comments. .SS commodity directive .PP -The \f[C]commodity\f[] directive predefines commodities (currently this -is just informational), and also it may define the display format for -amounts in this commodity (overriding the automatically inferred -format). -.PP +The \f[C]commodity\f[] directive declares commodities which may be used +in the journal (though currently we do not enforce this). It may be written on a single line, like this: .IP .nf @@ -1095,6 +1092,15 @@ commodity\ INR \ \ format\ INR\ 9,99,99,999.00 \f[] .fi +.PP +Commodity directives have a second purpose: they define the standard +display format for amounts in the commodity. +Normally the display format is inferred from journal entries, but this +can be unpredictable; declaring it with a commodity directive overrides +this and removes ambiguity. +Towards this end, amounts in commodity directives must always be written +with a decimal point (a period or comma, followed by 0 or more decimal +digits). .SS Default commodity .PP The D directive sets a default commodity (and display format), to be @@ -1114,6 +1120,9 @@ D\ $1,000.00 \ \ b \f[] .fi +.PP +As with the \f[C]commodity\f[] directive, the amount must always be +written with a decimal point. .SS Default year .PP You can set a default year to be used for subsequent dates which don't diff --git a/hledger-lib/hledger_journal.info b/hledger-lib/hledger_journal.info index 029478dd7..44f483010 100644 --- a/hledger-lib/hledger_journal.info +++ b/hledger-lib/hledger_journal.info @@ -997,11 +997,9 @@ File: hledger_journal.info, Node: commodity directive, Next: Default commodity 1.14.5 commodity directive -------------------------- -The 'commodity' directive predefines commodities (currently this is just -informational), and also it may define the display format for amounts in -this commodity (overriding the automatically inferred format). - - It may be written on a single line, like this: +The 'commodity' directive declares commodities which may be used in the +journal (though currently we do not enforce this). It may be written on +a single line, like this: ; commodity EXAMPLEAMOUNT @@ -1023,6 +1021,14 @@ places: commodity INR format INR 9,99,99,999.00 + Commodity directives have a second purpose: they define the standard +display format for amounts in the commodity. Normally the display +format is inferred from journal entries, but this can be unpredictable; +declaring it with a commodity directive overrides this and removes +ambiguity. Towards this end, amounts in commodity directives must +always be written with a decimal point (a period or comma, followed by 0 +or more decimal digits). +  File: hledger_journal.info, Node: Default commodity, Next: Default year, Prev: commodity directive, Up: Directives @@ -1043,6 +1049,9 @@ D $1,000.00 a 5 ; <- commodity-less amount, becomes $1 b + As with the 'commodity' directive, the amount must always be written +with a decimal point. +  File: hledger_journal.info, Node: Default year, Next: Including other files, Prev: Default commodity, Up: Directives @@ -1259,17 +1268,17 @@ Node: Multi-line comments35168 Ref: #multi-line-comments35358 Node: commodity directive35486 Ref: #commodity-directive35670 -Node: Default commodity36542 -Ref: #default-commodity36715 -Node: Default year37252 -Ref: #default-year37417 -Node: Including other files37840 -Ref: #including-other-files37997 -Node: Periodic transactions38394 -Ref: #periodic-transactions38560 -Node: Automated postings39549 -Ref: #automated-postings39712 -Node: EDITOR SUPPORT40840 -Ref: #editor-support40965 +Node: Default commodity36897 +Ref: #default-commodity37070 +Node: Default year37702 +Ref: #default-year37867 +Node: Including other files38290 +Ref: #including-other-files38447 +Node: Periodic transactions38844 +Ref: #periodic-transactions39010 +Node: Automated postings39999 +Ref: #automated-postings40162 +Node: EDITOR SUPPORT41290 +Ref: #editor-support41415  End Tag Table diff --git a/hledger-lib/hledger_journal.txt b/hledger-lib/hledger_journal.txt index 9e42991b3..75373d4c4 100644 --- a/hledger-lib/hledger_journal.txt +++ b/hledger-lib/hledger_journal.txt @@ -770,11 +770,9 @@ FILE FORMAT containing just end comment ends it. See comments. commodity directive - The commodity directive predefines commodities (currently this is just - informational), and also it may define the display format for amounts - in this commodity (overriding the automatically inferred format). - - It may be written on a single line, like this: + The commodity directive declares commodities which may be used in the + journal (though currently we do not enforce this). It may be written + on a single line, like this: ; commodity EXAMPLEAMOUNT @@ -796,6 +794,14 @@ FILE FORMAT commodity INR format INR 9,99,99,999.00 + Commodity directives have a second purpose: they define the standard + display format for amounts in the commodity. Normally the display for- + mat is inferred from journal entries, but this can be unpredictable; + declaring it with a commodity directive overrides this and removes + ambiguity. Towards this end, amounts in commodity directives must + always be written with a decimal point (a period or comma, followed by + 0 or more decimal digits). + Default commodity The D directive sets a default commodity (and display format), to be used for amounts without a commodity symbol (ie, plain numbers). (Note @@ -811,9 +817,12 @@ FILE FORMAT a 5 ; <- commodity-less amount, becomes $1 b + As with the commodity directive, the amount must always be written with + a decimal point. + Default year - You can set a default year to be used for subsequent dates which don't - specify a year. This is a line beginning with Y followed by the year. + You can set a default year to be used for subsequent dates which don't + specify a year. This is a line beginning with Y followed by the year. Eg: Y2009 ; set default year to 2009 @@ -833,58 +842,58 @@ FILE FORMAT assets Including other files - You can pull in the content of additional journal files by writing an + You can pull in the content of additional journal files by writing an include directive, like this: include path/to/file.journal - If the path does not begin with a slash, it is relative to the current + If the path does not begin with a slash, it is relative to the current file. Glob patterns (*) are not currently supported. - The include directive can only be used in journal files. It can + The include directive can only be used in journal files. It can include journal, timeclock or timedot files, but not CSV files. Periodic transactions - Periodic transactions are a kind of rule with a dual purpose: they can - specify recurring future transactions (with --forecast), or budget - goals (with --budget). They look a bit like a transaction, except the + Periodic transactions are a kind of rule with a dual purpose: they can + specify recurring future transactions (with --forecast), or budget + goals (with --budget). They look a bit like a transaction, except the first line is a tilde (~) followed by a period expression: ~ weekly assets:bank:checking $400 ; paycheck income:acme inc - With --forecast, each periodic transaction rule generates recurring - "forecast" transactions at the specified interval, beginning the day - after the latest recorded journal transaction (or today, if there are - no transactions) and ending 6 months from today (or at the report end + With --forecast, each periodic transaction rule generates recurring + "forecast" transactions at the specified interval, beginning the day + after the latest recorded journal transaction (or today, if there are + no transactions) and ending 6 months from today (or at the report end date, if specified). - With balance --budget, each periodic transaction declares recurring + With balance --budget, each periodic transaction declares recurring budget goals for the specified accounts. Eg the example above declares - the goal of receiving $400 from income:acme inc (and also, depositing + the goal of receiving $400 from income:acme inc (and also, depositing $400 into assets:bank:checking) every week. - For more details, see: balance: Budgeting and Budgeting and Forecast- + For more details, see: balance: Budgeting and Budgeting and Forecast- ing. Automated postings - Automated postings are postings added automatically by rule to certain - transactions (with --auto). An automated posting rule looks like a - transaction where the first line is an equal sign (=) followed by a + Automated postings are postings added automatically by rule to certain + transactions (with --auto). An automated posting rule looks like a + transaction where the first line is an equal sign (=) followed by a query: = expenses:gifts budget:gifts *-1 assets:budget *1 - The posting amounts can be of the form *N, which means "the amount of - the matched transaction's first posting, multiplied by N". They can + The posting amounts can be of the form *N, which means "the amount of + the matched transaction's first posting, multiplied by N". They can also be ordinary fixed amounts. Fixed amounts with no commodity symbol - will be given the same commodity as the matched transaction's first + will be given the same commodity as the matched transaction's first posting. - This example adds a corresponding (unbalanced) budget posting to every + This example adds a corresponding (unbalanced) budget posting to every transaction involving the expenses:gifts account: = expenses:gifts @@ -900,18 +909,18 @@ Automated postings (budget:gifts) $-20 assets - Automated postings would not be distinguishable from equivalent post- - ings written by hand. In particular, they would affect [amount infer- - ence|#postings] and [balance assertion|#balance-assertions] checks in + Automated postings would not be distinguishable from equivalent post- + ings written by hand. In particular, they would affect [amount infer- + ence|#postings] and [balance assertion|#balance-assertions] checks in the usual way. EDITOR SUPPORT Add-on modes exist for various text editors, to make working with jour- - nal files easier. They add colour, navigation aids and helpful com- - mands. For hledger users who edit the journal file directly (the + nal files easier. They add colour, navigation aids and helpful com- + mands. For hledger users who edit the journal file directly (the majority), using one of these modes is quite recommended. - These were written with Ledger in mind, but also work with hledger + These were written with Ledger in mind, but also work with hledger files: @@ -930,7 +939,7 @@ EDITOR SUPPORT 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) @@ -944,7 +953,7 @@ COPYRIGHT SEE ALSO - hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1), + hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1), hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_time- dot(5), ledger(1) diff --git a/hledger/hledger.1 b/hledger/hledger.1 index c6bd604cc..8aa25ce29 100644 --- a/hledger/hledger.1 +++ b/hledger/hledger.1 @@ -1018,8 +1018,8 @@ $\ hledger\ \-f\ t.j\ bal\ \-N\ euros\ \-V Currently, hledger's \-V only uses market prices recorded with P directives, not transaction prices (unlike Ledger). .PP -Currently, the \-V has a limitation with in multicolumn balance reports: -it uses the market prices on the report end date for all columns. +Currently, \-V has a limitation in multicolumn balance reports: it uses +the market prices on the report end date for all columns. (Instead of the prices on each column's end date.) .SS Combining \-B and \-V .PP @@ -1550,8 +1550,35 @@ with \[en]budget, show unbudgeted accounts also .RS .RE .PP -The balance command displays accounts and balances. -It is hledger's most featureful and versatile command. +The balance command is hledger's most versatile command. +Note, despite the name, it is not always used for showing real\-world +account balances; the more accounting\-aware balancesheet and +incomestatement may be more convenient for that. +.PP +By default, it displays all accounts, and each account's change in +balance during the entire period of the journal. +Balance changes are calculated by adding up the postings in each +account. +You can limit the postings matched, by a query, to see fewer accounts, +changes over a different time period, changes from only cleared +transactions, etc. +.PP +If you include an account's complete history of postings in the report, +the balance change is equivalent to the account's current ending +balance. +For a real\-world account, typically you won't have all transactions in +the journal; instead you'll have all transactions after a certain date, +and an \[lq]opening balances\[rq] transaction setting the correct +starting balance on that date. +Then the balance command will show real\-world account balances. +In some cases the \-H/\[en]historical flag is used to ensure this (more +below). +.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: .IP .nf \f[C] @@ -1571,12 +1598,6 @@ $\ hledger\ balance \f[] .fi .PP -More precisely, the balance command shows the \f[I]change\f[] to each -account's balance caused by all (matched) postings. -In the common case where you do not filter by date and your journal sets -the correct opening balances, this is the same as the account's ending -balance. -.PP By default, accounts are displayed hierarchically, with subaccounts indented below their parent. At each level of the tree, accounts are sorted by account code if any, @@ -1586,8 +1607,7 @@ Or with \f[C]\-S/\-\-sort\-amount\f[], by their balance amount. \[lq]Boring\[rq] accounts, which contain a single interesting subaccount and no balance of their own, are elided into the following line for more compact output. -(Not yet supported in tabular reports.) Use \f[C]\-\-no\-elide\f[] to -prevent this. +Use \f[C]\-\-no\-elide\f[] to prevent this. .PP Account balances are \[lq]inclusive\[rq] \- they include the balances of any subaccounts. @@ -1597,7 +1617,7 @@ omitted. Use \f[C]\-E/\-\-empty\f[] to show them. .PP A final total is displayed by default; use \f[C]\-N/\-\-no\-total\f[] to -suppress it: +suppress it, eg: .IP .nf \f[C] @@ -1607,11 +1627,89 @@ $\ hledger\ balance\ \-p\ 2008/6\ expenses\ \-\-no\-total \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $1\ \ \ \ supplies \f[] .fi +.SS Customising the classic balance report +.PP +You can customise the layout of classic balance reports with +\f[C]\-\-format\ FMT\f[]: +.IP +.nf +\f[C] +$\ 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 +\f[] +.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[] +.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[] \- a number of spaces equal to the account's +depth, or if MIN is specified, MIN * depth spaces. +.IP \[bu] 2 +\f[C]account\f[] \- the account's name +.IP \[bu] 2 +\f[C]total\f[] \- the account'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[] \- render on multiple lines, bottom\-aligned (the default) +.IP \[bu] 2 +\f[C]%^\f[] \- render on multiple lines, top\-aligned +.IP \[bu] 2 +\f[C]%,\f[] \- render on one line, comma\-separated +.PP +There are some quirks. +Eg in one\-line mode, \f[C]%(depth_spacer)\f[] has no effect, instead +\f[C]%(account)\f[] has indentation built in. + Experimentation may be needed to get pleasing results. +.PP +Some example formats: +.IP \[bu] 2 +\f[C]%(total)\f[] \- the account's total +.IP \[bu] 2 +\f[C]%\-20.20(account)\f[] \- the account's name, left justified, padded +to 20 characters and clipped at 20 characters +.IP \[bu] 2 +\f[C]%,%\-50(account)\ \ %25(total)\f[] \- 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[] \- the default +format for the single\-column balance report +.SS Colour support +.PP +The balance command shows negative amounts in red, if: +.IP \[bu] 2 +the \f[C]TERM\f[] environment variable is not set to \f[C]dumb\f[] +.IP \[bu] 2 +the output is not being redirected or piped anywhere .SS Flat mode .PP -To see a flat list of full account names instead of the default -hierarchical display, use \f[C]\-\-flat\f[]. -In this mode, accounts (unless depth\-clipped) show their +To see a flat list instead of the default hierarchical display, use +\f[C]\-\-flat\f[]. +In this mode, accounts (unless depth\-clipped) show their full names and \[lq]exclusive\[rq] balance, excluding any subaccount balances. In this mode, you can also use \f[C]\-\-drop\ N\f[] to omit the first few account name components. @@ -1625,26 +1723,32 @@ $\ hledger\ balance\ \-p\ 2008/6\ expenses\ \-N\ \-\-flat\ \-\-drop\ 1 .fi .SS Depth limited balance reports .PP -With \f[C]\-\-depth\ N\f[], balance shows accounts only to the specified -depth. -This is very useful to show a complex charts of accounts in less detail. -In flat mode, balances from accounts below the depth limit will be shown -as part of a parent account at the depth limit. +With \f[C]\-\-depth\ N\f[] or \f[C]depth:N\f[] or just \f[C]\-N\f[], +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\ \-\-depth\ 1 +$\ hledger\ balance\ \-N\ \-1 \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-1\ \ assets \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $2\ \ expenses \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-2\ \ income \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $1\ \ liabilities \f[] .fi -.SS Multicolumn balance reports .PP -With a reporting interval, multiple balance columns will be shown, one -for each report period. -There are three types of multi\-column balance report, showing different +Flat\-mode balance reports, which normally show exclusive balances, show +inclusive balances at the depth limit. +.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 information: .IP "1." 3 By default: each column shows the sum of postings in that period, ie the @@ -1716,8 +1820,8 @@ Ending\ balances\ (historical)\ in\ 2008/04/01\-2008/12/31: .fi .RE .PP -Multi\-column balance reports display accounts in flat mode by default; -to see the hierarchy, use \f[C]\-\-tree\f[]. +Multicolumn balance reports display accounts in flat mode by default; to +see the hierarchy, use \f[C]\-\-tree\f[]. .PP With a reporting interval (like \f[C]\-\-quarterly\f[] above), the report start/end dates will be adjusted if necessary so that they @@ -1762,17 +1866,22 @@ Balance\ changes\ in\ 2008: \f[] .fi .PP -The \f[C]\-V/\-\-value\f[] flag currently has a limitation with -multicolumn reports: it uses the market prices on the report end date -for all columns. -(Instead of the prices on each column's end date.) -.SS Budgets +Limitations: .PP -With \f[C]\-\-budget\f[] and a report interval, all periodic -transactions in your journal with that interval, active during the -requested report period, are interpreted as recurring budget goals for -the specified accounts (and subaccounts), and the report will show the -difference between actual and budgeted balances. +In multicolumn reports the \f[C]\-V/\-\-value\f[] flag uses the market +price on the report end date, for all columns (not the price on each +column's end date). +.PP +Eliding of boring parent accounts in tree mode, as in the classic +balance report, is not yet supported in multicolumn reports. +.SS Budget report +.PP +With \f[C]\-\-budget\f[], 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. +\[en]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: @@ -1805,156 +1914,61 @@ categories to construct a minimal monthly budget: \f[] .fi .PP -You can now see a monthly budget performance report: +You can now see a monthly budget report: .IP .nf \f[C] $\ hledger\ balance\ \-M\ \-\-budget -Balance\ changes\ in\ 2017/11/01\-2017/12/31: +Budget\ performance\ in\ 2017/11/01\-2017/12/31: -\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 2017/11\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 2017/12\ -=======================++================================================= -\ :expenses\ ||\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $20\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $100\ -\ assets:bank:checking\ \ ||\ $\-2445\ [99%\ of\ $\-2480]\ \ $\-2665\ [107%\ of\ $\-2480]\ -\ expenses:bus\ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ $49\ [98%\ of\ $50]\ \ \ \ \ \ \ \ $53\ [106%\ of\ $50]\ -\ expenses:food\ \ \ \ \ \ \ \ \ ||\ \ \ \ \ $396\ [99%\ of\ $400]\ \ \ \ \ \ $412\ [103%\ of\ $400]\ -\ expenses:movies\ \ \ \ \ \ \ ||\ \ \ \ \ \ $30\ [100%\ of\ $30]\ \ \ \ \ \ \ \ \ \ \ \ 0\ [0%\ of\ $30]\ -\ income\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ $1950\ [98%\ of\ $2000]\ \ \ \ $2100\ [105%\ of\ $2000]\ -\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- -\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0\ +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 2017/11\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 2017/12\ +======================++================================================= +\ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $20\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $100\ +\ assets:bank:checking\ ||\ $\-2445\ [99%\ of\ $\-2480]\ \ $\-2665\ [107%\ of\ $\-2480]\ +\ expenses:bus\ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ $49\ [98%\ of\ $50]\ \ \ \ \ \ \ \ $53\ [106%\ of\ $50]\ +\ expenses:food\ \ \ \ \ \ \ \ ||\ \ \ \ \ $396\ [99%\ of\ $400]\ \ \ \ \ \ $412\ [103%\ of\ $400]\ +\ expenses:movies\ \ \ \ \ \ ||\ \ \ \ \ \ $30\ [100%\ of\ $30]\ \ \ \ \ \ \ \ \ \ \ \ 0\ [0%\ of\ $30]\ +\ income\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ $1950\ [98%\ of\ $2000]\ \ \ \ $2100\ [105%\ of\ $2000]\ +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0\ \f[] .fi .PP +By default, only accounts with budget goals during the report period are +shown. +\f[C]\-\-show\-unbudgeted\f[] shows unbudgeted accounts as well. +Top\-level accounts with no budget goals anywhere below them are grouped +under \f[C]\f[]. +.PP You can roll over unspent budgets to next period with \f[C]\-\-cumulative\f[]: .IP .nf \f[C] $\ hledger\ balance\ \-M\ \-\-budget\ \-\-cumulative -Ending\ balances\ (cumulative)\ in\ 2017/11/01\-2017/12/31: +Budget\ performance\ in\ 2017/11/01\-2017/12/31: -\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ \ \ \ \ 2017/11/30\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 2017/12/31\ -=======================++================================================= -\ :expenses\ ||\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $20\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $120\ -\ assets:bank:checking\ \ ||\ $\-2445\ [99%\ of\ $\-2480]\ \ $\-5110\ [103%\ of\ $\-4960]\ -\ expenses:bus\ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ $49\ [98%\ of\ $50]\ \ \ \ \ \ $102\ [102%\ of\ $100]\ -\ expenses:food\ \ \ \ \ \ \ \ \ ||\ \ \ \ \ $396\ [99%\ of\ $400]\ \ \ \ \ \ $808\ [101%\ of\ $800]\ -\ expenses:movies\ \ \ \ \ \ \ ||\ \ \ \ \ \ $30\ [100%\ of\ $30]\ \ \ \ \ \ \ \ \ $30\ [50%\ of\ $60]\ -\ income\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ $1950\ [98%\ of\ $2000]\ \ \ \ $4050\ [101%\ of\ $4000]\ -\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- -\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0 -\f[] -.fi -.PP -Accounts with no budget goals (not mentioned in the periodic -transactions) will be aggregated under \f[C]\f[], unless you -add the \f[C]\-\-show\-unbudgeted\f[] flag to display them normally: -.IP -.nf -\f[C] -$\ hledger\ balance\ \-\-budget\ \-\-show\-unbudgeted -Balance\ changes\ in\ 2017/11/01\-2017/12/31: - -\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 2017/11\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 2017/12\ +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ \ \ \ \ 2017/11/30\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 2017/12/31\ ======================++================================================= -\ assets:bank:checking\ ||\ $\-2445\ [99%\ of\ $\-2480]\ \ $\-2665\ [107%\ of\ $\-2480]\ -\ expenses:bus\ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ $49\ [98%\ of\ $50]\ \ \ \ \ \ \ \ $53\ [106%\ of\ $50]\ -\ expenses:food\ \ \ \ \ \ \ \ ||\ \ \ \ \ $396\ [99%\ of\ $400]\ \ \ \ \ \ $412\ [103%\ of\ $400]\ -\ expenses:gifts\ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $100\ -\ expenses:movies\ \ \ \ \ \ ||\ \ \ \ \ \ $30\ [100%\ of\ $30]\ \ \ \ \ \ \ \ \ \ \ \ 0\ [0%\ of\ $30]\ -\ expenses:supplies\ \ \ \ ||\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $20\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0\ -\ income\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ $1950\ [98%\ of\ $2000]\ \ \ \ $2100\ [105%\ of\ $2000]\ +\ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $20\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $120\ +\ assets:bank:checking\ ||\ $\-2445\ [99%\ of\ $\-2480]\ \ $\-5110\ [103%\ of\ $\-4960]\ +\ expenses:bus\ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ $49\ [98%\ of\ $50]\ \ \ \ \ \ $102\ [102%\ of\ $100]\ +\ expenses:food\ \ \ \ \ \ \ \ ||\ \ \ \ \ $396\ [99%\ of\ $400]\ \ \ \ \ \ $808\ [101%\ of\ $800]\ +\ expenses:movies\ \ \ \ \ \ ||\ \ \ \ \ \ $30\ [100%\ of\ $30]\ \ \ \ \ \ \ \ \ $30\ [50%\ of\ $60]\ +\ income\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ $1950\ [98%\ of\ $2000]\ \ \ \ $4050\ [101%\ of\ $4000]\ \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- -\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0\ +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0 \f[] .fi .PP -Note \[en]budget first arrived in hledger in 1.5 and is still pretty -young; join the discussions on mail list and issue tracker to help us -refine it. +Note, the \f[C]\-S/\-\-sort\-amount\f[] flag is not yet fully supported +with \f[C]\-\-budget\f[]. .PP For more examples, see Budgeting and Forecasting. -.SS Custom balance output +.SS Output format .PP -You can customise the layout of simple (non\-tabular) balance reports -with \f[C]\-\-format\ FMT\f[]: -.IP -.nf -\f[C] -$\ 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 -\f[] -.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[] -.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[] \- a number of spaces equal to the account's -depth, or if MIN is specified, MIN * depth spaces. -.IP \[bu] 2 -\f[C]account\f[] \- the account's name -.IP \[bu] 2 -\f[C]total\f[] \- the account'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[] \- render on multiple lines, bottom\-aligned (the default) -.IP \[bu] 2 -\f[C]%^\f[] \- render on multiple lines, top\-aligned -.IP \[bu] 2 -\f[C]%,\f[] \- render on one line, comma\-separated -.PP -There are some quirks. -Eg in one\-line mode, \f[C]%(depth_spacer)\f[] has no effect, instead -\f[C]%(account)\f[] has indentation built in. - Experimentation may be needed to get pleasing results. -.PP -Some example formats: -.IP \[bu] 2 -\f[C]%(total)\f[] \- the account's total -.IP \[bu] 2 -\f[C]%\-20.20(account)\f[] \- the account's name, left justified, padded -to 20 characters and clipped at 20 characters -.IP \[bu] 2 -\f[C]%,%\-50(account)\ \ %25(total)\f[] \- 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[] \- the default -format for the single\-column balance report -.PP -This command also supports output destination and output format +The balance command supports output destination and output format selection. -.SS Colour support -.PP -The balance command shows negative amounts in red, if: -.IP \[bu] 2 -the \f[C]TERM\f[] environment variable is not set to \f[C]dumb\f[] -.IP \[bu] 2 -the output is not being redirected or piped anywhere .SS balancesheet .PP This command displays a simple balance sheet, showing historical ending diff --git a/hledger/hledger.info b/hledger/hledger.info index 2d8d5be52..676b8223f 100644 --- a/hledger/hledger.info +++ b/hledger/hledger.info @@ -685,9 +685,9 @@ $ hledger -f t.j bal -N euros -V Currently, hledger's -V only uses market prices recorded with P directives, not transaction prices (unlike Ledger). - Currently, the -V has a limitation with in multicolumn balance -reports: it uses the market prices on the report end date for all -columns. (Instead of the prices on each column's end date.) + Currently, -V has a limitation in multicolumn balance reports: it +uses the market prices on the report end date for all columns. (Instead +of the prices on each column's end date.)  File: hledger.info, Node: Combining -B and -V, Next: Output destination, Prev: Market value, Up: OPTIONS @@ -1150,8 +1150,46 @@ Show accounts and their balances. Aliases: b, bal. with -budget, show unbudgeted accounts also - The balance command displays accounts and balances. It is hledger's -most featureful and versatile command. + The balance command is hledger's most versatile command. Note, +despite the name, it is not always used for showing real-world account +balances; the more accounting-aware balancesheet and incomestatement may +be more convenient for that. + + By default, it displays all accounts, and each account's change in +balance during the entire period of the journal. Balance changes are +calculated by adding up the postings in each account. You can limit the +postings matched, by a query, to see fewer accounts, changes over a +different time period, changes from only cleared transactions, etc. + + If you include an account's complete history of postings in the +report, the balance change is equivalent to the account's current ending +balance. For a real-world account, typically you won't have all +transactions in the journal; instead you'll have all transactions after +a certain date, and an "opening balances" transaction setting the +correct starting balance on that date. Then the balance command will +show real-world account balances. In some cases the -H/-historical flag +is used to ensure this (more below). + + The balance command can produce several styles of report: +* Menu: + +* Classic balance report:: +* Customising the classic balance report:: +* Colour support:: +* Flat mode:: +* Depth limited balance reports:: +* Multicolumn balance report:: +* Budget report:: +* Output format:: + + +File: hledger.info, Node: Classic balance report, Next: Customising the classic balance report, Up: balance + +4.4.1 Classic balance report +---------------------------- + +This is the original balance report, as found in Ledger. It usually +looks like this: $ hledger balance $-1 assets @@ -1167,11 +1205,6 @@ $ hledger balance -------------------- 0 - More precisely, the balance command shows the _change_ to each -account's balance caused by all (matched) postings. In the common case -where you do not filter by date and your journal sets the correct -opening balances, this is the same as the account's ending balance. - By default, accounts are displayed hierarchically, with subaccounts indented below their parent. At each level of the tree, accounts are sorted by account code if any, then by account name. Or with @@ -1179,8 +1212,7 @@ sorted by account code if any, then by account name. Or with "Boring" accounts, which contain a single interesting subaccount and no balance of their own, are elided into the following line for more -compact output. (Not yet supported in tabular reports.) Use -'--no-elide' to prevent this. +compact output. Use '--no-elide' to prevent this. Account balances are "inclusive" - they include the balances of any subaccounts. @@ -1189,263 +1221,21 @@ subaccounts. omitted. Use '-E/--empty' to show them. A final total is displayed by default; use '-N/--no-total' to -suppress it: +suppress it, eg: $ hledger balance -p 2008/6 expenses --no-total $2 expenses $1 food $1 supplies -* Menu: - -* Flat mode:: -* Depth limited balance reports:: -* Multicolumn balance reports:: -* Budgets:: -* Custom balance output:: -* Colour support:: -  -File: hledger.info, Node: Flat mode, Next: Depth limited balance reports, Up: balance +File: hledger.info, Node: Customising the classic balance report, Next: Colour support, Prev: Classic balance report, Up: balance -4.4.1 Flat mode ---------------- +4.4.2 Customising the classic balance report +-------------------------------------------- -To see a flat list of full account names instead of the default -hierarchical display, use '--flat'. In this mode, accounts (unless -depth-clipped) show their "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: Multicolumn balance reports, Prev: Flat mode, Up: balance - -4.4.2 Depth limited balance reports ------------------------------------ - -With '--depth N', balance shows accounts only to the specified depth. -This is very useful to show a complex charts of accounts in less detail. -In flat mode, balances from accounts below the depth limit will be shown -as part of a parent account at the depth limit. - -$ hledger balance -N --depth 1 - $-1 assets - $2 expenses - $-2 income - $1 liabilities - - -File: hledger.info, Node: Multicolumn balance reports, Next: Budgets, Prev: Depth limited balance reports, Up: balance - -4.4.3 Multicolumn balance reports ---------------------------------- - -With a reporting interval, multiple balance columns will be shown, one -for each report period. There are three types of multi-column balance -report, 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: - - $ 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: - - $ hledger balance --quarterly income expenses -E --cumulative - Ending balances (cumulative) in 2008: - - || 2008/03/31 2008/06/30 2008/09/30 2008/12/31 - ===================++================================================= - expenses:food || 0 $1 $1 $1 - expenses:supplies || 0 $1 $1 $1 - income:gifts || 0 $-1 $-1 $-1 - income:salary || $-1 $-1 $-1 $-1 - -------------------++------------------------------------------------- - || $-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: - - $ hledger balance ^assets ^liabilities --quarterly --historical --begin 2008/4/1 - Ending balances (historical) in 2008/04/01-2008/12/31: - - || 2008/06/30 2008/09/30 2008/12/31 - ======================++===================================== - assets:bank:checking || $1 $1 0 - assets:bank:saving || $1 $1 $1 - assets:cash || $-2 $-2 $-2 - liabilities:debts || 0 0 $1 - ----------------------++------------------------------------- - || 0 0 0 - - Multi-column 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 -will be "full" and comparable to the others. - - The '-E/--empty' flag does two things in multicolumn balance reports: -first, the report will show all columns within the specified report -period (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 row. - - Here's an example of all three: - -$ hledger balance -Q income expenses --tree -ETA -Balance changes in 2008: - - || 2008q1 2008q2 2008q3 2008q4 Total Average -============++=================================================== - expenses || 0 $2 0 0 $2 $1 - food || 0 $1 0 0 $1 0 - supplies || 0 $1 0 0 $1 0 - income || $-1 $-1 0 0 $-2 $-1 - gifts || 0 $-1 0 0 $-1 0 - salary || $-1 0 0 0 $-1 0 -------------++--------------------------------------------------- - || $-1 $1 0 0 0 0 - -# Average is rounded to the dollar here since all journal amounts are - - The '-V/--value' flag currently has a limitation with multicolumn -reports: it uses the market prices on the report end date for all -columns. (Instead of the prices on each column's end date.) - - -File: hledger.info, Node: Budgets, Next: Custom balance output, Prev: Multicolumn balance reports, Up: balance - -4.4.4 Budgets -------------- - -With '--budget' and a report interval, all periodic transactions in your -journal with that interval, active during the requested report period, -are interpreted as recurring budget goals for the specified accounts -(and subaccounts), and the report will show the difference between -actual and budgeted balances. - - For example, you can take average monthly expenses in the common -expense categories to construct a minimal monthly budget: - -;; Budget -~ monthly - income $2000 - expenses:food $400 - expenses:bus $50 - expenses:movies $30 - assets:bank:checking - -;; Two months worth of expenses -2017-11-01 - income $1950 - expenses:food $396 - expenses:bus $49 - expenses:movies $30 - expenses:supplies $20 - assets:bank:checking - -2017-12-01 - income $2100 - expenses:food $412 - expenses:bus $53 - expenses:gifts $100 - assets:bank:checking - - You can now see a monthly budget performance report: - -$ hledger balance -M --budget -Balance changes in 2017/11/01-2017/12/31: - - || 2017/11 2017/12 -=======================++================================================= - :expenses || $20 $100 - assets:bank:checking || $-2445 [99% of $-2480] $-2665 [107% of $-2480] - expenses:bus || $49 [98% of $50] $53 [106% of $50] - expenses:food || $396 [99% of $400] $412 [103% of $400] - expenses:movies || $30 [100% of $30] 0 [0% of $30] - income || $1950 [98% of $2000] $2100 [105% of $2000] ------------------------++------------------------------------------------- - || 0 0 - - You can roll over unspent budgets to next period with '--cumulative': - -$ hledger balance -M --budget --cumulative -Ending balances (cumulative) in 2017/11/01-2017/12/31: - - || 2017/11/30 2017/12/31 -=======================++================================================= - :expenses || $20 $120 - assets:bank:checking || $-2445 [99% of $-2480] $-5110 [103% of $-4960] - expenses:bus || $49 [98% of $50] $102 [102% of $100] - expenses:food || $396 [99% of $400] $808 [101% of $800] - expenses:movies || $30 [100% of $30] $30 [50% of $60] - income || $1950 [98% of $2000] $4050 [101% of $4000] ------------------------++------------------------------------------------- - || 0 0 - - Accounts with no budget goals (not mentioned in the periodic -transactions) will be aggregated under '', unless you add -the '--show-unbudgeted' flag to display them normally: - -$ hledger balance --budget --show-unbudgeted -Balance changes in 2017/11/01-2017/12/31: - - || 2017/11 2017/12 -======================++================================================= - assets:bank:checking || $-2445 [99% of $-2480] $-2665 [107% of $-2480] - expenses:bus || $49 [98% of $50] $53 [106% of $50] - expenses:food || $396 [99% of $400] $412 [103% of $400] - expenses:gifts || 0 $100 - expenses:movies || $30 [100% of $30] 0 [0% of $30] - expenses:supplies || $20 0 - income || $1950 [98% of $2000] $2100 [105% of $2000] -----------------------++------------------------------------------------- - || 0 0 - - Note -budget first arrived in hledger in 1.5 and is still pretty -young; join the discussions on mail list and issue tracker to help us -refine it. - - For more examples, see Budgeting and Forecasting. - - -File: hledger.info, Node: Custom balance output, Next: Colour support, Prev: Budgets, Up: balance - -4.4.5 Custom balance output ---------------------------- - -You can customise the layout of simple (non-tabular) balance reports -with '--format FMT': +You can customise the layout of classic balance reports with '--format +FMT': $ hledger balance --format "%20(account) %12(total)" assets $-1 @@ -1498,13 +1288,10 @@ may be needed to get pleasing results. * '%20(total) %2(depth_spacer)%-(account)' - the default format for the single-column balance report - This command also supports output destination and output format -selection. -  -File: hledger.info, Node: Colour support, Prev: Custom balance output, Up: balance +File: hledger.info, Node: Colour support, Next: Flat mode, Prev: Customising the classic balance report, Up: balance -4.4.6 Colour support +4.4.3 Colour support -------------------- The balance command shows negative amounts in red, if: @@ -1512,6 +1299,241 @@ The balance command shows negative amounts in red, if: * the 'TERM' environment variable is not set to 'dumb' * the output is not being redirected or piped anywhere + +File: hledger.info, Node: Flat mode, Next: Depth limited balance reports, Prev: Colour support, Up: balance + +4.4.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: Multicolumn balance report, Prev: Flat mode, Up: balance + +4.4.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: Multicolumn balance report, Next: Budget report, Prev: Depth limited balance reports, Up: balance + +4.4.6 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: + + 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: + + $ 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: + + $ hledger balance --quarterly income expenses -E --cumulative + Ending balances (cumulative) in 2008: + + || 2008/03/31 2008/06/30 2008/09/30 2008/12/31 + ===================++================================================= + expenses:food || 0 $1 $1 $1 + expenses:supplies || 0 $1 $1 $1 + income:gifts || 0 $-1 $-1 $-1 + income:salary || $-1 $-1 $-1 $-1 + -------------------++------------------------------------------------- + || $-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: + + $ hledger balance ^assets ^liabilities --quarterly --historical --begin 2008/4/1 + Ending balances (historical) in 2008/04/01-2008/12/31: + + || 2008/06/30 2008/09/30 2008/12/31 + ======================++===================================== + assets:bank:checking || $1 $1 0 + assets:bank:saving || $1 $1 $1 + assets:cash || $-2 $-2 $-2 + liabilities:debts || 0 0 $1 + ----------------------++------------------------------------- + || 0 0 0 + + 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 +will be "full" and comparable to the others. + + The '-E/--empty' flag does two things in multicolumn balance reports: +first, the report will show all columns within the specified report +period (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 row. + + Here's an example of all three: + +$ hledger balance -Q income expenses --tree -ETA +Balance changes in 2008: + + || 2008q1 2008q2 2008q3 2008q4 Total Average +============++=================================================== + expenses || 0 $2 0 0 $2 $1 + food || 0 $1 0 0 $1 0 + supplies || 0 $1 0 0 $1 0 + income || $-1 $-1 0 0 $-2 $-1 + gifts || 0 $-1 0 0 $-1 0 + salary || $-1 0 0 0 $-1 0 +------------++--------------------------------------------------- + || $-1 $1 0 0 0 0 + +# Average is rounded to the dollar here since all journal amounts are + + Limitations: + + In multicolumn reports the '-V/--value' flag uses the market price on +the report end date, for all columns (not the price on each column's end +date). + + Eliding of boring parent accounts in tree mode, as in the classic +balance report, is not yet supported in multicolumn reports. + + +File: hledger.info, Node: Budget report, Next: , Prev: Multicolumn balance report, Up: balance + +4.4.7 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. + + For example, you can take average monthly expenses in the common +expense categories to construct a minimal monthly budget: + +;; Budget +~ monthly + income $2000 + expenses:food $400 + expenses:bus $50 + expenses:movies $30 + assets:bank:checking + +;; Two months worth of expenses +2017-11-01 + income $1950 + expenses:food $396 + expenses:bus $49 + expenses:movies $30 + expenses:supplies $20 + assets:bank:checking + +2017-12-01 + income $2100 + expenses:food $412 + expenses:bus $53 + expenses:gifts $100 + assets:bank:checking + + You can now see a monthly budget report: + +$ hledger balance -M --budget +Budget performance in 2017/11/01-2017/12/31: + + || 2017/11 2017/12 +======================++================================================= + || $20 $100 + assets:bank:checking || $-2445 [99% of $-2480] $-2665 [107% of $-2480] + expenses:bus || $49 [98% of $50] $53 [106% of $50] + expenses:food || $396 [99% of $400] $412 [103% of $400] + expenses:movies || $30 [100% of $30] 0 [0% of $30] + income || $1950 [98% of $2000] $2100 [105% of $2000] +----------------------++------------------------------------------------- + || 0 0 + + By default, only accounts with budget goals during the report period +are shown. '--show-unbudgeted' shows unbudgeted accounts as well. +Top-level accounts with no budget goals anywhere below them are grouped +under ''. + + You can roll over unspent budgets to next period with '--cumulative': + +$ hledger balance -M --budget --cumulative +Budget performance in 2017/11/01-2017/12/31: + + || 2017/11/30 2017/12/31 +======================++================================================= + || $20 $120 + assets:bank:checking || $-2445 [99% of $-2480] $-5110 [103% of $-4960] + expenses:bus || $49 [98% of $50] $102 [102% of $100] + expenses:food || $396 [99% of $400] $808 [101% of $800] + expenses:movies || $30 [100% of $30] $30 [50% of $60] + income || $1950 [98% of $2000] $4050 [101% of $4000] +----------------------++------------------------------------------------- + || 0 0 + + Note, the '-S/--sort-amount' flag is not yet fully supported with +'--budget'. + + For more examples, see Budgeting and Forecasting. + +4.4.8 Output format +------------------- + +The balance command supports output destination and output format +selection. +  File: hledger.info, Node: balancesheet, Next: balancesheetequity, Prev: balance, Up: COMMANDS @@ -2441,103 +2463,106 @@ Node: Cost21487 Ref: #cost21595 Node: Market value21713 Ref: #market-value21848 -Node: Combining -B and -V23224 -Ref: #combining--b-and--v23387 -Node: Output destination23534 -Ref: #output-destination23696 -Node: Output format23979 -Ref: #output-format24131 -Node: Regular expressions24516 -Ref: #regular-expressions24653 -Node: QUERIES26014 -Ref: #queries26116 -Node: COMMANDS30078 -Ref: #commands30190 -Node: accounts31172 -Ref: #accounts31270 -Node: activity32516 -Ref: #activity32626 -Node: add32986 -Ref: #add33085 -Node: balance35746 -Ref: #balance35857 -Node: Flat mode39361 -Ref: #flat-mode39486 -Node: Depth limited balance reports39906 -Ref: #depth-limited-balance-reports40107 -Node: Multicolumn balance reports40527 -Ref: #multicolumn-balance-reports40722 -Node: Budgets45608 -Ref: #budgets45755 -Node: Custom balance output49724 -Ref: #custom-balance-output49886 -Node: Colour support52052 -Ref: #colour-support52184 -Node: balancesheet52357 -Ref: #balancesheet52493 -Node: balancesheetequity54804 -Ref: #balancesheetequity54953 -Node: cashflow55490 -Ref: #cashflow55618 -Node: check-dates57741 -Ref: #check-dates57868 -Node: check-dupes57985 -Ref: #check-dupes58109 -Node: close58246 -Ref: #close58353 -Node: help58683 -Ref: #help58783 -Node: import59857 -Ref: #import59971 -Node: incomestatement60701 -Ref: #incomestatement60835 -Node: prices63239 -Ref: #prices63354 -Node: print63397 -Ref: #print63507 -Node: print-unique68401 -Ref: #print-unique68527 -Node: register68595 -Ref: #register68722 -Node: Custom register output73223 -Ref: #custom-register-output73352 -Node: register-match74582 -Ref: #register-match74716 -Node: rewrite74899 -Ref: #rewrite75016 -Node: stats75085 -Ref: #stats75188 -Node: tags76058 -Ref: #tags76156 -Node: test76392 -Ref: #test76476 -Node: ADD-ON COMMANDS76844 -Ref: #add-on-commands76954 -Node: Official add-ons78241 -Ref: #official-add-ons78381 -Node: api78468 -Ref: #api78557 -Node: ui78609 -Ref: #ui78708 -Node: web78766 -Ref: #web78855 -Node: Third party add-ons78901 -Ref: #third-party-add-ons79076 -Node: diff79211 -Ref: #diff79308 -Node: iadd79407 -Ref: #iadd79521 -Node: interest79604 -Ref: #interest79725 -Node: irr79820 -Ref: #irr79918 -Node: Experimental add-ons79996 -Ref: #experimental-add-ons80148 -Node: autosync80428 -Ref: #autosync80539 -Node: chart80778 -Ref: #chart80897 -Node: check80968 -Ref: #check81070 +Node: Combining -B and -V23215 +Ref: #combining--b-and--v23378 +Node: Output destination23525 +Ref: #output-destination23687 +Node: Output format23970 +Ref: #output-format24122 +Node: Regular expressions24507 +Ref: #regular-expressions24644 +Node: QUERIES26005 +Ref: #queries26107 +Node: COMMANDS30069 +Ref: #commands30181 +Node: accounts31163 +Ref: #accounts31261 +Node: activity32507 +Ref: #activity32617 +Node: add32977 +Ref: #add33076 +Node: balance35737 +Ref: #balance35848 +Node: Classic balance report38931 +Ref: #classic-balance-report39104 +Node: Customising the classic balance report40433 +Ref: #customising-the-classic-balance-report40661 +Node: Colour support42735 +Ref: #colour-support42902 +Node: Flat mode43075 +Ref: #flat-mode43223 +Node: Depth limited balance reports43636 +Ref: #depth-limited-balance-reports43836 +Node: Multicolumn balance report44292 +Ref: #multicolumn-balance-report44490 +Node: Budget report49670 +Ref: #budget-report49813 +Ref: #output-format-152847 +Node: balancesheet52925 +Ref: #balancesheet53061 +Node: balancesheetequity55372 +Ref: #balancesheetequity55521 +Node: cashflow56058 +Ref: #cashflow56186 +Node: check-dates58309 +Ref: #check-dates58436 +Node: check-dupes58553 +Ref: #check-dupes58677 +Node: close58814 +Ref: #close58921 +Node: help59251 +Ref: #help59351 +Node: import60425 +Ref: #import60539 +Node: incomestatement61269 +Ref: #incomestatement61403 +Node: prices63807 +Ref: #prices63922 +Node: print63965 +Ref: #print64075 +Node: print-unique68969 +Ref: #print-unique69095 +Node: register69163 +Ref: #register69290 +Node: Custom register output73791 +Ref: #custom-register-output73920 +Node: register-match75150 +Ref: #register-match75284 +Node: rewrite75467 +Ref: #rewrite75584 +Node: stats75653 +Ref: #stats75756 +Node: tags76626 +Ref: #tags76724 +Node: test76960 +Ref: #test77044 +Node: ADD-ON COMMANDS77412 +Ref: #add-on-commands77522 +Node: Official add-ons78809 +Ref: #official-add-ons78949 +Node: api79036 +Ref: #api79125 +Node: ui79177 +Ref: #ui79276 +Node: web79334 +Ref: #web79423 +Node: Third party add-ons79469 +Ref: #third-party-add-ons79644 +Node: diff79779 +Ref: #diff79876 +Node: iadd79975 +Ref: #iadd80089 +Node: interest80172 +Ref: #interest80293 +Node: irr80388 +Ref: #irr80486 +Node: Experimental add-ons80564 +Ref: #experimental-add-ons80716 +Node: autosync80996 +Ref: #autosync81107 +Node: chart81346 +Ref: #chart81465 +Node: check81536 +Ref: #check81638  End Tag Table diff --git a/hledger/hledger.txt b/hledger/hledger.txt index 1b0c3d520..0abe3d8d8 100644 --- a/hledger/hledger.txt +++ b/hledger/hledger.txt @@ -651,9 +651,9 @@ OPTIONS Currently, hledger's -V only uses market prices recorded with P direc- tives, not transaction prices (unlike Ledger). - Currently, the -V has a limitation with in multicolumn balance reports: - it uses the market prices on the report end date for all columns. - (Instead of the prices on each column's end date.) + Currently, -V has a limitation in multicolumn balance reports: it uses + the market prices on the report end date for all columns. (Instead of + the prices on each column's end date.) Combining -B and -V Using -B/-cost and -V/-value together is currently allowed, but the @@ -1052,8 +1052,31 @@ COMMANDS --show-unbudgeted with -budget, show unbudgeted accounts also - The balance command displays accounts and balances. It is hledger's - most featureful and versatile command. + The balance command is hledger's most versatile command. Note, despite + the name, it is not always used for showing real-world account bal- + ances; the more accounting-aware balancesheet and incomestatement may + be more convenient for that. + + By default, it displays all accounts, and each account's change in bal- + ance during the entire period of the journal. Balance changes are cal- + culated by adding up the postings in each account. You can limit the + postings matched, by a query, to see fewer accounts, changes over a + different time period, changes from only cleared transactions, etc. + + If you include an account's complete history of postings in the report, + the balance change is equivalent to the account's current ending bal- + ance. For a real-world account, typically you won't have all transac- + tions in the journal; instead you'll have all transactions after a cer- + tain date, and an "opening balances" transaction setting the correct + starting balance on that date. Then the balance command will show + real-world account balances. In some cases the -H/-historical flag is + used to ensure this (more below). + + 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: $ hledger balance $-1 assets @@ -1069,20 +1092,14 @@ COMMANDS -------------------- 0 - More precisely, the balance command shows the change to each account's - balance caused by all (matched) postings. In the common case where you - do not filter by date and your journal sets the correct opening bal- - ances, this is the same as the account's ending balance. - - By default, accounts are displayed hierarchically, with subaccounts - indented below their parent. At each level of the tree, accounts are - sorted by account code if any, then by account name. Or with + By default, accounts are displayed hierarchically, with subaccounts + indented below their parent. At each level of the tree, accounts are + sorted by account code if any, then by account name. Or with -S/--sort-amount, by their balance amount. "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. (Not yet supported in tabular reports.) Use --no-elide to - prevent this. + balance of their own, are elided into the following line for more com- + pact output. Use --no-elide to prevent this. Account balances are "inclusive" - they include the balances of any subaccounts. @@ -1091,229 +1108,16 @@ COMMANDS omitted. Use -E/--empty to show them. A final total is displayed by default; use -N/--no-total to suppress - it: + it, eg: $ hledger balance -p 2008/6 expenses --no-total $2 expenses $1 food $1 supplies - Flat mode - To see a flat list of full account names instead of the default hierar- - chical display, use --flat. In this mode, accounts (unless - depth-clipped) show their "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, balance shows accounts only to the specified depth. - This is very useful to show a complex charts of accounts in less - detail. In flat mode, balances from accounts below the depth limit - will be shown as part of a parent account at the depth limit. - - $ hledger balance -N --depth 1 - $-1 assets - $2 expenses - $-2 income - $1 liabilities - - Multicolumn balance reports - With a reporting interval, multiple balance columns will be shown, one - for each report period. There are three types of multi-column balance - report, 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: - - $ 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: - - $ hledger balance --quarterly income expenses -E --cumulative - Ending balances (cumulative) in 2008: - - || 2008/03/31 2008/06/30 2008/09/30 2008/12/31 - ===================++================================================= - expenses:food || 0 $1 $1 $1 - expenses:supplies || 0 $1 $1 $1 - income:gifts || 0 $-1 $-1 $-1 - income:salary || $-1 $-1 $-1 $-1 - -------------------++------------------------------------------------- - || $-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: - - $ hledger balance ^assets ^liabilities --quarterly --historical --begin 2008/4/1 - Ending balances (historical) in 2008/04/01-2008/12/31: - - || 2008/06/30 2008/09/30 2008/12/31 - ======================++===================================== - assets:bank:checking || $1 $1 0 - assets:bank:saving || $1 $1 $1 - assets:cash || $-2 $-2 $-2 - liabilities:debts || 0 0 $1 - ----------------------++------------------------------------- - || 0 0 0 - - Multi-column 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 peri- - ods will be "full" and comparable to the others. - - The -E/--empty flag does two things in multicolumn balance reports: - first, the report will show all columns within the specified report - period (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 oth- - erwise 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 - row. - - Here's an example of all three: - - $ hledger balance -Q income expenses --tree -ETA - Balance changes in 2008: - - || 2008q1 2008q2 2008q3 2008q4 Total Average - ============++=================================================== - expenses || 0 $2 0 0 $2 $1 - food || 0 $1 0 0 $1 0 - supplies || 0 $1 0 0 $1 0 - income || $-1 $-1 0 0 $-2 $-1 - gifts || 0 $-1 0 0 $-1 0 - salary || $-1 0 0 0 $-1 0 - ------------++--------------------------------------------------- - || $-1 $1 0 0 0 0 - - # Average is rounded to the dollar here since all journal amounts are - - The -V/--value flag currently has a limitation with multicolumn - reports: it uses the market prices on the report end date for all col- - umns. (Instead of the prices on each column's end date.) - - Budgets - With --budget and a report interval, all periodic transactions in your - journal with that interval, active during the requested report period, - are interpreted as recurring budget goals for the specified accounts - (and subaccounts), and the report will show the difference between - actual and budgeted balances. - - For example, you can take average monthly expenses in the common - expense categories to construct a minimal monthly budget: - - ;; Budget - ~ monthly - income $2000 - expenses:food $400 - expenses:bus $50 - expenses:movies $30 - assets:bank:checking - - ;; Two months worth of expenses - 2017-11-01 - income $1950 - expenses:food $396 - expenses:bus $49 - expenses:movies $30 - expenses:supplies $20 - assets:bank:checking - - 2017-12-01 - income $2100 - expenses:food $412 - expenses:bus $53 - expenses:gifts $100 - assets:bank:checking - - You can now see a monthly budget performance report: - - $ hledger balance -M --budget - Balance changes in 2017/11/01-2017/12/31: - - || 2017/11 2017/12 - =======================++================================================= - :expenses || $20 $100 - assets:bank:checking || $-2445 [99% of $-2480] $-2665 [107% of $-2480] - expenses:bus || $49 [98% of $50] $53 [106% of $50] - expenses:food || $396 [99% of $400] $412 [103% of $400] - expenses:movies || $30 [100% of $30] 0 [0% of $30] - income || $1950 [98% of $2000] $2100 [105% of $2000] - -----------------------++------------------------------------------------- - || 0 0 - - You can roll over unspent budgets to next period with --cumulative: - - $ hledger balance -M --budget --cumulative - Ending balances (cumulative) in 2017/11/01-2017/12/31: - - || 2017/11/30 2017/12/31 - =======================++================================================= - :expenses || $20 $120 - assets:bank:checking || $-2445 [99% of $-2480] $-5110 [103% of $-4960] - expenses:bus || $49 [98% of $50] $102 [102% of $100] - expenses:food || $396 [99% of $400] $808 [101% of $800] - expenses:movies || $30 [100% of $30] $30 [50% of $60] - income || $1950 [98% of $2000] $4050 [101% of $4000] - -----------------------++------------------------------------------------- - || 0 0 - - Accounts with no budget goals (not mentioned in the periodic transac- - tions) will be aggregated under , unless you add the - --show-unbudgeted flag to display them normally: - - $ hledger balance --budget --show-unbudgeted - Balance changes in 2017/11/01-2017/12/31: - - || 2017/11 2017/12 - ======================++================================================= - assets:bank:checking || $-2445 [99% of $-2480] $-2665 [107% of $-2480] - expenses:bus || $49 [98% of $50] $53 [106% of $50] - expenses:food || $396 [99% of $400] $412 [103% of $400] - expenses:gifts || 0 $100 - expenses:movies || $30 [100% of $30] 0 [0% of $30] - expenses:supplies || $20 0 - income || $1950 [98% of $2000] $2100 [105% of $2000] - ----------------------++------------------------------------------------- - || 0 0 - - Note -budget first arrived in hledger in 1.5 and is still pretty young; - join the discussions on mail list and issue tracker to help us refine - it. - - For more examples, see Budgeting and Forecasting. - - Custom balance output - You can customise the layout of simple (non-tabular) balance reports - with --format FMT: + Customising the classic balance report + You can customise the layout of classic balance reports with --for- + mat FMT: $ hledger balance --format "%20(account) %12(total)" assets $-1 @@ -1375,9 +1179,6 @@ COMMANDS o %20(total) %2(depth_spacer)%-(account) - the default format for the single-column balance report - This command also supports output destination and output format selec- - tion. - Colour support The balance command shows negative amounts in red, if: @@ -1385,6 +1186,220 @@ COMMANDS o the output is not being redirected or piped anywhere + 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. + + 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 + interval. + + There are three types of multicolumn balance report, 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: + + $ 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: + + $ hledger balance --quarterly income expenses -E --cumulative + Ending balances (cumulative) in 2008: + + || 2008/03/31 2008/06/30 2008/09/30 2008/12/31 + ===================++================================================= + expenses:food || 0 $1 $1 $1 + expenses:supplies || 0 $1 $1 $1 + income:gifts || 0 $-1 $-1 $-1 + income:salary || $-1 $-1 $-1 $-1 + -------------------++------------------------------------------------- + || $-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: + + $ hledger balance ^assets ^liabilities --quarterly --historical --begin 2008/4/1 + Ending balances (historical) in 2008/04/01-2008/12/31: + + || 2008/06/30 2008/09/30 2008/12/31 + ======================++===================================== + assets:bank:checking || $1 $1 0 + assets:bank:saving || $1 $1 $1 + assets:cash || $-2 $-2 $-2 + liabilities:debts || 0 0 $1 + ----------------------++------------------------------------- + || 0 0 0 + + 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 peri- + ods will be "full" and comparable to the others. + + The -E/--empty flag does two things in multicolumn balance reports: + first, the report will show all columns within the specified report + period (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 oth- + erwise 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 + row. + + Here's an example of all three: + + $ hledger balance -Q income expenses --tree -ETA + Balance changes in 2008: + + || 2008q1 2008q2 2008q3 2008q4 Total Average + ============++=================================================== + expenses || 0 $2 0 0 $2 $1 + food || 0 $1 0 0 $1 0 + supplies || 0 $1 0 0 $1 0 + income || $-1 $-1 0 0 $-2 $-1 + gifts || 0 $-1 0 0 $-1 0 + salary || $-1 0 0 0 $-1 0 + ------------++--------------------------------------------------- + || $-1 $1 0 0 0 0 + + # Average is rounded to the dollar here since all journal amounts are + + Limitations: + + In multicolumn reports the -V/--value flag uses the market price on the + report end date, for all columns (not the price on each column's end + date). + + Eliding of boring parent accounts in tree mode, as in the classic bal- + ance report, is not yet supported in multicolumn reports. + + 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. + + For example, you can take average monthly expenses in the common + expense categories to construct a minimal monthly budget: + + ;; Budget + ~ monthly + income $2000 + expenses:food $400 + expenses:bus $50 + expenses:movies $30 + assets:bank:checking + + ;; Two months worth of expenses + 2017-11-01 + income $1950 + expenses:food $396 + expenses:bus $49 + expenses:movies $30 + expenses:supplies $20 + assets:bank:checking + + 2017-12-01 + income $2100 + expenses:food $412 + expenses:bus $53 + expenses:gifts $100 + assets:bank:checking + + You can now see a monthly budget report: + + $ hledger balance -M --budget + Budget performance in 2017/11/01-2017/12/31: + + || 2017/11 2017/12 + ======================++================================================= + || $20 $100 + assets:bank:checking || $-2445 [99% of $-2480] $-2665 [107% of $-2480] + expenses:bus || $49 [98% of $50] $53 [106% of $50] + expenses:food || $396 [99% of $400] $412 [103% of $400] + expenses:movies || $30 [100% of $30] 0 [0% of $30] + income || $1950 [98% of $2000] $2100 [105% of $2000] + ----------------------++------------------------------------------------- + || 0 0 + + By default, only accounts with budget goals during the report period + are shown. --show-unbudgeted shows unbudgeted accounts as well. + Top-level accounts with no budget goals anywhere below them are grouped + under . + + You can roll over unspent budgets to next period with --cumulative: + + $ hledger balance -M --budget --cumulative + Budget performance in 2017/11/01-2017/12/31: + + || 2017/11/30 2017/12/31 + ======================++================================================= + || $20 $120 + assets:bank:checking || $-2445 [99% of $-2480] $-5110 [103% of $-4960] + expenses:bus || $49 [98% of $50] $102 [102% of $100] + expenses:food || $396 [99% of $400] $808 [101% of $800] + expenses:movies || $30 [100% of $30] $30 [50% of $60] + income || $1950 [98% of $2000] $4050 [101% of $4000] + ----------------------++------------------------------------------------- + || 0 0 + + Note, the -S/--sort-amount flag is not yet fully supported with --bud- + get. + + For more examples, see Budgeting and Forecasting. + + Output format + The balance command supports output destination and output format + selection. + balancesheet This command displays a simple balance sheet, showing historical ending balances of asset and liability accounts (ignoring any report begin