diff --git a/hledger/Hledger/Cli/Commands/Balance.hs b/hledger/Hledger/Cli/Commands/Balance.hs index 4ba75d722..0e5fbf7c7 100644 --- a/hledger/Hledger/Cli/Commands/Balance.hs +++ b/hledger/Hledger/Cli/Commands/Balance.hs @@ -235,6 +235,7 @@ Currently, empty cells show 0. {-# LANGUAGE OverloadedStrings #-} {-# LANGUAGE ExtendedDefaultRules #-} {-# LANGUAGE ScopedTypeVariables #-} +{-# LANGUAGE TemplateHaskell #-} module Hledger.Cli.Commands.Balance ( balancemode @@ -268,36 +269,33 @@ import Hledger.Read.CsvReader (CSV, printCSV) -- | Command line options for this command. -balancemode = (defCommandMode $ ["balance"] ++ aliases) { -- also accept but don't show the common bal alias - modeHelp = "show accounts and balances" `withAliases` aliases - ,modeGroupFlags = C.Group { - groupUnnamed = [ - flagNone ["change"] (\opts -> setboolopt "change" opts) - "show balance change in each period (default)" - ,flagNone ["cumulative"] (\opts -> setboolopt "cumulative" opts) - "show balance change accumulated across periods (in multicolumn reports)" - ,flagNone ["historical","H"] (\opts -> setboolopt "historical" opts) - "show historical ending balance in each period (includes postings before report start date)\n " - ,flagNone ["tree"] (\opts -> setboolopt "tree" opts) "show accounts as a tree; amounts include subaccounts (default in simple reports)" - ,flagNone ["flat"] (\opts -> setboolopt "flat" opts) "show accounts as a list; amounts exclude subaccounts except when account is depth-clipped (default in multicolumn reports)\n " - ,flagNone ["average","A"] (\opts -> setboolopt "average" opts) "show a row average column (in multicolumn reports)" - ,flagNone ["row-total","T"] (\opts -> setboolopt "row-total" opts) "show a row total column (in multicolumn reports)" - ,flagNone ["no-total","N"] (\opts -> setboolopt "no-total" opts) "omit the final total row" - ,flagReq ["drop"] (\s opts -> Right $ setopt "drop" s opts) "N" "omit N leading account name parts (in flat mode)" - ,flagNone ["no-elide"] (\opts -> setboolopt "no-elide" opts) "don't squash boring parent accounts (in tree mode)" - ,flagReq ["format"] (\s opts -> Right $ setopt "format" s opts) "FORMATSTR" "use this custom line format (in simple reports)" - ,flagNone ["pretty-tables"] (\opts -> setboolopt "pretty-tables" opts) "use unicode to display prettier tables" - ,flagNone ["sort-amount","S"] (\opts -> setboolopt "sort-amount" opts) "sort by amount instead of account code/name (in flat mode). With multiple columns, sorts by the row total, or by row average if that is displayed." - ,flagNone ["budget"] (setboolopt "budget") "show performance compared to budget goals defined by periodic transactions" - ,flagNone ["invert"] (setboolopt "invert") "display all amounts with reversed sign" - ,flagNone ["transpose"] (setboolopt "transpose") "transpose rows and columns" - ] - ++ outputflags - ,groupHidden = [] - ,groupNamed = [generalflagsgroup1] - } - } - where aliases = ["b","bal"] +balancemode = hledgerCommandMode + $(hereFileRelative "Hledger/Cli/Commands/Balance.md") + ([flagNone ["change"] (\opts -> setboolopt "change" opts) + "show balance change in each period (default)" + ,flagNone ["cumulative"] (\opts -> setboolopt "cumulative" opts) + "show balance change accumulated across periods (in multicolumn reports)" + ,flagNone ["historical","H"] (\opts -> setboolopt "historical" opts) + "show historical ending balance in each period (includes postings before report start date)\n " + ,flagNone ["tree"] (\opts -> setboolopt "tree" opts) "show accounts as a tree; amounts include subaccounts (default in simple reports)" + ,flagNone ["flat"] (\opts -> setboolopt "flat" opts) "show accounts as a list; amounts exclude subaccounts except when account is depth-clipped (default in multicolumn reports)\n " + ,flagNone ["average","A"] (\opts -> setboolopt "average" opts) "show a row average column (in multicolumn reports)" + ,flagNone ["row-total","T"] (\opts -> setboolopt "row-total" opts) "show a row total column (in multicolumn reports)" + ,flagNone ["no-total","N"] (\opts -> setboolopt "no-total" opts) "omit the final total row" + ,flagReq ["drop"] (\s opts -> Right $ setopt "drop" s opts) "N" "omit N leading account name parts (in flat mode)" + ,flagNone ["no-elide"] (\opts -> setboolopt "no-elide" opts) "don't squash boring parent accounts (in tree mode)" + ,flagReq ["format"] (\s opts -> Right $ setopt "format" s opts) "FORMATSTR" "use this custom line format (in simple reports)" + ,flagNone ["pretty-tables"] (\opts -> setboolopt "pretty-tables" opts) "use unicode to display prettier tables" + ,flagNone ["sort-amount","S"] (\opts -> setboolopt "sort-amount" opts) "sort by amount instead of account code/name (in flat mode). With multiple columns, sorts by the row total, or by row average if that is displayed." + ,flagNone ["budget"] (setboolopt "budget") "show performance compared to budget goals defined by periodic transactions" + ,flagNone ["invert"] (setboolopt "invert") "display all amounts with reversed sign" + ,flagNone ["transpose"] (setboolopt "transpose") "transpose rows and columns" + ] + ++ outputflags + ) + [generalflagsgroup1] + [] + ([], Just $ argsFlag "[QUERY]") -- | The balance command, prints a balance report. balance :: CliOpts -> Journal -> IO () diff --git a/hledger/hledger_balance.m4.md b/hledger/Hledger/Cli/Commands/Balance.md similarity index 92% rename from hledger/hledger_balance.m4.md rename to hledger/Hledger/Cli/Commands/Balance.md index 6973ad676..09614b7b8 100644 --- a/hledger/hledger_balance.m4.md +++ b/hledger/Hledger/Cli/Commands/Balance.md @@ -1,61 +1,7 @@ -## balance -Show accounts and their balances. Aliases: b, bal. +balance, bal, b\ +Show accounts and their balances. -`--change` -: show balance change in each period (default) - -`--cumulative` -: show balance change accumulated across periods (in multicolumn reports) - -`-H --historical` -: show historical ending balance in each period (includes postings before report start date) - -`--tree` -: show accounts as a tree; amounts include subaccounts (default in simple reports) - -`--flat` -: show accounts as a list; amounts exclude subaccounts except when account is depth-clipped (default in multicolumn reports) - -`-A --average` -: show a row average column (in multicolumn mode) - -`-T --row-total` -: show a row total column (in multicolumn mode) - -`-N --no-total` -: don't show the final total row - -`--drop=N` -: omit N leading account name parts (in flat mode) - -`--no-elide` -: don't squash boring parent accounts (in tree mode) - -`--format=LINEFORMAT` -: in single-column balance reports: use this custom line format - -`-O FMT --output-format=FMT ` -: select the output format. Supported formats: -txt, csv, html. - -`--transpose` -: transposes rows and columns in multi-column reports. Supported formats: -txt, csv - -`-o FILE --output-file=FILE` -: write output to FILE. A file extension matching one of the above formats selects that format. - -`--pretty-tables` -: use unicode to display prettier tables. - -`--sort-amount` -: sort by amount instead of account code/name (in flat mode). With multiple columns, sorts by the row total, or by row average if that is displayed. - -`--invert` -: display all amounts with reversed sign - -`--budget` -: show performance compared to budget goals defined by [periodic transactions](journal.html#periodic-transactions) +_FLAGS_ The balance command is hledger's most versatile command. Note, despite the name, it is not always used for showing real-world account balances; diff --git a/hledger/hledger.1 b/hledger/hledger.1 index a1409008c..bcbb93cbd 100644 --- a/hledger/hledger.1 +++ b/hledger/hledger.1 @@ -1487,663 +1487,6 @@ Date\ [2015/05/22]:\ \ $ \f[] .fi .SS balance -.PP -Show accounts and their balances. -Aliases: b, bal. -.TP -.B \f[C]\-\-change\f[] -show balance change in each period (default) -.RS -.RE -.TP -.B \f[C]\-\-cumulative\f[] -show balance change accumulated across periods (in multicolumn reports) -.RS -.RE -.TP -.B \f[C]\-H\ \-\-historical\f[] -show historical ending balance in each period (includes postings before -report start date) -.RS -.RE -.TP -.B \f[C]\-\-tree\f[] -show accounts as a tree; amounts include subaccounts (default in simple -reports) -.RS -.RE -.TP -.B \f[C]\-\-flat\f[] -show accounts as a list; amounts exclude subaccounts except when account -is depth\-clipped (default in multicolumn reports) -.RS -.RE -.TP -.B \f[C]\-A\ \-\-average\f[] -show a row average column (in multicolumn mode) -.RS -.RE -.TP -.B \f[C]\-T\ \-\-row\-total\f[] -show a row total column (in multicolumn mode) -.RS -.RE -.TP -.B \f[C]\-N\ \-\-no\-total\f[] -don\[aq]t show the final total row -.RS -.RE -.TP -.B \f[C]\-\-drop=N\f[] -omit N leading account name parts (in flat mode) -.RS -.RE -.TP -.B \f[C]\-\-no\-elide\f[] -don\[aq]t squash boring parent accounts (in tree mode) -.RS -.RE -.TP -.B \f[C]\-\-format=LINEFORMAT\f[] -in single\-column balance reports: use this custom line format -.RS -.RE -.TP -.B \f[C]\-O\ FMT\ \-\-output\-format=FMT\f[] -select the output format. -Supported formats: txt, csv, html. -.RS -.RE -.TP -.B \f[C]\-\-transpose\f[] -transposes rows and columns in multi\-column reports. -Supported formats: txt, csv -.RS -.RE -.TP -.B \f[C]\-o\ FILE\ \-\-output\-file=FILE\f[] -write output to FILE. -A file extension matching one of the above formats selects that format. -.RS -.RE -.TP -.B \f[C]\-\-pretty\-tables\f[] -use unicode to display prettier tables. -.RS -.RE -.TP -.B \f[C]\-\-sort\-amount\f[] -sort by amount instead of account code/name (in flat mode). -With multiple columns, sorts by the row total, or by row average if that -is displayed. -.RS -.RE -.TP -.B \f[C]\-\-invert\f[] -display all amounts with reversed sign -.RS -.RE -.TP -.B \f[C]\-\-budget\f[] -show performance compared to budget goals defined by periodic -transactions -.RS -.RE -.PP -The balance command is hledger\[aq]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\[aq]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\[aq]s complete history of postings in the -report, the balance change is equivalent to the account\[aq]s current -ending balance. -For a real\-world account, typically you won\[aq]t have all transactions -in the journal; instead you\[aq]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). -.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] -$\ hledger\ balance -\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-1\ \ assets -\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $1\ \ \ \ bank:saving -\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-2\ \ \ \ cash -\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $2\ \ expenses -\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $1\ \ \ \ food -\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $1\ \ \ \ supplies -\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-2\ \ income -\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-1\ \ \ \ gifts -\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-1\ \ \ \ salary -\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $1\ \ liabilities:debts -\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- -\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0 -\f[] -.fi -.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, -then by account name. -Or with \f[C]\-S/\-\-sort\-amount\f[], by their balance amount. -.PP -"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 \f[C]\-\-no\-elide\f[] to -prevent this. -.PP -Account balances are "inclusive" \- 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[] to show them. -.PP -A final total is displayed by default; use \f[C]\-N/\-\-no\-total\f[] to -suppress it, eg: -.IP -.nf -\f[C] -$\ hledger\ balance\ \-p\ 2008/6\ expenses\ \-\-no\-total -\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $2\ \ expenses -\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $1\ \ \ \ food -\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $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\[aq]s -depth, or if MIN is specified, MIN * depth spaces. -.IP \[bu] 2 -\f[C]account\f[] \- the account\[aq]s name -.IP \[bu] 2 -\f[C]total\f[] \- 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[] \- 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\[aq]s total -.IP \[bu] 2 -\f[C]%\-20.20(account)\f[] \- 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[] \- 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 instead of the default hierarchical display, use -\f[C]\-\-flat\f[]. -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 \f[C]\-\-drop\ N\f[] 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[] -.fi -.SS Depth limited balance reports -.PP -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\ \-1 -\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-1\ \ assets -\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $2\ \ expenses -\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-2\ \ income -\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $1\ \ liabilities -\f[] -.fi -.PP -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 -account\[aq]s change of balance in that period. -This is useful eg for a monthly income statement: -.RS 4 -.IP -.nf -\f[C] -$\ 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\ -\f[] -.fi -.RE -.IP "2." 3 -With \f[C]\-\-cumulative\f[]: each column shows the ending balance for -that period, accumulating the changes across periods, starting from 0 at -the report start date: -.RS 4 -.IP -.nf -\f[C] -$\ 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\ -\f[] -.fi -.RE -.IP "3." 3 -With \f[C]\-\-historical/\-H\f[]: 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: -.RS 4 -.IP -.nf -\f[C] -$\ 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\ -\f[] -.fi -.RE -.PP -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 -encompass the displayed report periods. -This is so that the first and last periods will be "full" and comparable -to the others. -.PP -The \f[C]\-E/\-\-empty\f[] 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). -With \f[C]\-\-budget\f[], \f[C]\-\-empty\f[] also shows unbudgeted -accounts. -.PP -The \f[C]\-T/\-\-row\-total\f[] flag adds an additional column showing -the total for each row. -.PP -The \f[C]\-A/\-\-average\f[] flag adds a column showing the average -value in each row. -.PP -Here\[aq]s an example of all three: -.IP -.nf -\f[C] -$\ 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 -\f[] -.fi -.PP -Limitations: -.PP -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\[aq]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. -\-\-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: -.IP -.nf -\f[C] -;;\ 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 -\f[] -.fi -.PP -You can now see a monthly budget report: -.IP -.nf -\f[C] -$\ hledger\ balance\ \-M\ \-\-budget -Budget\ performance\ in\ 2017/11/01\-2017/12/31: - -\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ Nov\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ Dec\ -======================++==================================================== -\ assets\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ $\-2445\ [\ \ 99%\ of\ $\-2480]\ \ $\-2665\ [\ 107%\ of\ $\-2480]\ -\ assets:bank\ \ \ \ \ \ \ \ \ \ ||\ $\-2445\ [\ \ 99%\ of\ $\-2480]\ \ $\-2665\ [\ 107%\ of\ $\-2480]\ -\ assets:bank:checking\ ||\ $\-2445\ [\ \ 99%\ of\ $\-2480]\ \ $\-2665\ [\ 107%\ of\ $\-2480]\ -\ expenses\ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ $495\ [\ 103%\ of\ \ \ $480]\ \ \ \ $565\ [\ 118%\ of\ \ \ $480]\ -\ 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]\ \ \ \ \ \ \ 0\ [\ \ \ \ \ \ \ \ \ \ \ \ \ \ 0]\ -\f[] -.fi -.PP -By default, only accounts with budget goals during the report period are -shown. -In the example above, transactions in \f[C]expenses:gifts\f[] and -\f[C]expenses:supplies\f[] are counted towards \f[C]expenses\f[] budget, -but accounts \f[C]expenses:gifts\f[] and \f[C]expenses:supplies\f[] are -not shown, as they don\[aq]t have any budgets. -.PP -You can use \f[C]\-\-empty\f[] shows unbudgeted accounts as well: -.IP -.nf -\f[C] -$\ hledger\ balance\ \-M\ \-\-budget\ \-\-empty -Budget\ performance\ in\ 2017/11/01\-2017/12/31: - -\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ Nov\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ Dec\ -======================++==================================================== -\ assets\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ $\-2445\ [\ \ 99%\ of\ $\-2480]\ \ $\-2665\ [\ 107%\ of\ $\-2480]\ -\ assets:bank\ \ \ \ \ \ \ \ \ \ ||\ $\-2445\ [\ \ 99%\ of\ $\-2480]\ \ $\-2665\ [\ 107%\ of\ $\-2480]\ -\ assets:bank:checking\ ||\ $\-2445\ [\ \ 99%\ of\ $\-2480]\ \ $\-2665\ [\ 107%\ of\ $\-2480]\ -\ expenses\ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ $495\ [\ 103%\ of\ \ \ $480]\ \ \ \ $565\ [\ 118%\ of\ \ \ $480]\ -\ 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]\ \ \ \ \ \ \ 0\ [\ \ \ \ \ \ \ \ \ \ \ \ \ \ 0]\ -\f[] -.fi -.PP -You can roll over unspent budgets to next period with -\f[C]\-\-cumulative\f[]: -.IP -.nf -\f[C] -$\ hledger\ balance\ \-M\ \-\-budget\ \-\-cumulative -Budget\ performance\ in\ 2017/11/01\-2017/12/31: - -\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ Nov\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ Dec\ -======================++==================================================== -\ assets\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ $\-2445\ [\ \ 99%\ of\ $\-2480]\ \ $\-5110\ [\ 103%\ of\ $\-4960]\ -\ assets:bank\ \ \ \ \ \ \ \ \ \ ||\ $\-2445\ [\ \ 99%\ of\ $\-2480]\ \ $\-5110\ [\ 103%\ of\ $\-4960]\ -\ assets:bank:checking\ ||\ $\-2445\ [\ \ 99%\ of\ $\-2480]\ \ $\-5110\ [\ 103%\ of\ $\-4960]\ -\ expenses\ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ $495\ [\ 103%\ of\ \ \ $480]\ \ \ $1060\ [\ 110%\ of\ \ \ $960]\ -\ 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, 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 Nested budgets -.PP -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 budget(s) of the child account(s) would be added to the budget of -their parent, much like account balances behave. -.PP -In the most simple case this means that once you add a budget to any -account, all its parents would have budget as well. -.PP -To illustrate this, consider the following budget: -.IP -.nf -\f[C] -~\ monthly\ from\ 2019/01 -\ \ \ \ expenses:personal\ \ \ \ \ \ \ \ \ \ \ \ \ $1,000.00 -\ \ \ \ expenses:personal:electronics\ \ \ \ $100.00 -\ \ \ \ liabilities -\f[] -.fi -.PP -With this, monthly budget for electronics is defined to be $100 and -budget for personal expenses is an additional $1000, which implicity -means that budget for both \f[C]expenses:personal\f[] and -\f[C]expenses\f[] is $1100. -.PP -Transactions in \f[C]expenses:personal:electronics\f[] will be counted -both towards its $100 budget and $1100 of \f[C]expenses:personal\f[] , -and transactions in any other subaccount of \f[C]expenses:personal\f[] -would be counted towards only towards the budget of -\f[C]expenses:personal\f[]. -.PP -For example, let\[aq]s consider these transactions: -.IP -.nf -\f[C] -~\ monthly\ from\ 2019/01 -\ \ \ \ expenses:personal\ \ \ \ \ \ \ \ \ \ \ \ \ $1,000.00 -\ \ \ \ expenses:personal:electronics\ \ \ \ $100.00 -\ \ \ \ liabilities - -2019/01/01\ Google\ home\ hub -\ \ \ \ expenses:personal:electronics\ \ \ \ \ \ \ \ \ \ $90.00 -\ \ \ \ liabilities\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-90.00 - -2019/01/02\ Phone\ screen\ protector -\ \ \ \ expenses:personal:electronics:upgrades\ \ \ \ \ \ \ \ \ \ $10.00 -\ \ \ \ liabilities - -2019/01/02\ Weekly\ train\ ticket -\ \ \ \ expenses:personal:train\ tickets\ \ \ \ \ \ \ $153.00 -\ \ \ \ liabilities - -2019/01/03\ Flowers -\ \ \ \ expenses:personal\ \ \ \ \ \ \ \ \ \ $30.00 -\ \ \ \ liabilities -\f[] -.fi -.PP -As you can see, we have transactions in -\f[C]expenses:personal:electronics:upgrades\f[] and -\f[C]expenses:personal:train\ tickets\f[], and since both of these -accounts are without explicitly defined budget, these transactions would -be counted towards budgets of \f[C]expenses:personal:electronics\f[] and -\f[C]expenses:personal\f[] accordingly: -.IP -.nf -\f[C] -$\ hledger\ balance\ \-\-budget\ \-M -Budget\ performance\ in\ 2019/01: - -\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ Jan\ -===============================++=============================== -\ expenses\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ $283.00\ [\ \ 26%\ of\ \ $1100.00]\ -\ expenses:personal\ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ $283.00\ [\ \ 26%\ of\ \ $1100.00]\ -\ expenses:personal:electronics\ ||\ \ $100.00\ [\ 100%\ of\ \ \ $100.00]\ -\ liabilities\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ $\-283.00\ [\ \ 26%\ of\ $\-1100.00]\ -\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- -\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ 0\ [\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0]\ -\f[] -.fi -.PP -And with \f[C]\-\-empty\f[], we can get a better picture of budget -allocation and consumption: -.IP -.nf -\f[C] -$\ hledger\ balance\ \-\-budget\ \-M\ \-\-empty -Budget\ performance\ in\ 2019/01: - -\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ Jan\ -========================================++=============================== -\ expenses\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ $283.00\ [\ \ 26%\ of\ \ $1100.00]\ -\ expenses:personal\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ $283.00\ [\ \ 26%\ of\ \ $1100.00]\ -\ expenses:personal:electronics\ \ \ \ \ \ \ \ \ \ ||\ \ $100.00\ [\ 100%\ of\ \ \ $100.00]\ -\ expenses:personal:electronics:upgrades\ ||\ \ \ $10.00\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ -\ expenses:personal:train\ tickets\ \ \ \ \ \ \ \ ||\ \ $153.00\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ -\ liabilities\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ $\-283.00\ [\ \ 26%\ of\ $\-1100.00]\ -\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- -\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ 0\ [\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0]\ -\f[] -.fi -.SS Output format -.PP -The balance command supports output destination and output format -selection. .SS balancesheet .PP This command displays a simple balance sheet, showing historical ending diff --git a/hledger/hledger.info b/hledger/hledger.info index 67ee1a2c3..50f1b4a7c 100644 --- a/hledger/hledger.info +++ b/hledger/hledger.info @@ -1138,574 +1138,6 @@ File: hledger.info, Node: balance, Next: balancesheet, Prev: add, Up: COMMAN 4.4 balance =========== -Show accounts and their balances. Aliases: b, bal. - -'--change' - - show balance change in each period (default) -'--cumulative' - - show balance change accumulated across periods (in multicolumn - reports) -'-H --historical' - - show historical ending balance in each period (includes postings - before report start date) -'--tree' - - show accounts as a tree; amounts include subaccounts (default in - simple reports) -'--flat' - - show accounts as a list; amounts exclude subaccounts except when - account is depth-clipped (default in multicolumn reports) -'-A --average' - - show a row average column (in multicolumn mode) -'-T --row-total' - - show a row total column (in multicolumn mode) -'-N --no-total' - - don't show the final total row -'--drop=N' - - omit N leading account name parts (in flat mode) -'--no-elide' - - don't squash boring parent accounts (in tree mode) -'--format=LINEFORMAT' - - in single-column balance reports: use this custom line format -'-O FMT --output-format=FMT' - - select the output format. Supported formats: txt, csv, html. -'--transpose' - - transposes rows and columns in multi-column reports. Supported - formats: txt, csv -'-o FILE --output-file=FILE' - - write output to FILE. A file extension matching one of the above - formats selects that format. -'--pretty-tables' - - use unicode to display prettier tables. -'--sort-amount' - - sort by amount instead of account code/name (in flat mode). With - multiple columns, sorts by the row total, or by row average if that - is displayed. -'--invert' - - display all amounts with reversed sign -'--budget' - - show performance compared to budget goals defined by periodic - transactions - - 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 - $1 bank:saving - $-2 cash - $2 expenses - $1 food - $1 supplies - $-2 income - $-1 gifts - $-1 salary - $1 liabilities:debts --------------------- - 0 - - 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 -compact 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 - - -File: hledger.info, Node: Customising the classic balance report, Next: Colour support, Prev: Classic balance report, Up: balance - -4.4.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 ---------------------------------- - 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 - -4.4.3 Colour support --------------------- - -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). With '--budget', '--empty' also shows unbudgeted -accounts. - - 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: - - || Nov Dec -======================++==================================================== - assets || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480] - assets:bank || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480] - assets:bank:checking || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480] - expenses || $495 [ 103% of $480] $565 [ 118% of $480] - 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] 0 [ 0] - - By default, only accounts with budget goals during the report period -are shown. In the example above, transactions in 'expenses:gifts' and -'expenses:supplies' are counted towards 'expenses' budget, but accounts -'expenses:gifts' and 'expenses:supplies' are not shown, as they don't -have any budgets. - - You can use '--empty' shows unbudgeted accounts as well: - -$ hledger balance -M --budget --empty -Budget performance in 2017/11/01-2017/12/31: - - || Nov Dec -======================++==================================================== - assets || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480] - assets:bank || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480] - assets:bank:checking || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480] - expenses || $495 [ 103% of $480] $565 [ 118% of $480] - 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] 0 [ 0] - - 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: - - || Nov Dec -======================++==================================================== - assets || $-2445 [ 99% of $-2480] $-5110 [ 103% of $-4960] - assets:bank || $-2445 [ 99% of $-2480] $-5110 [ 103% of $-4960] - assets:bank:checking || $-2445 [ 99% of $-2480] $-5110 [ 103% of $-4960] - expenses || $495 [ 103% of $480] $1060 [ 110% of $960] - 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] - - Note, the '-S/--sort-amount' flag is not yet fully supported with -'--budget'. - - For more examples, see Budgeting and Forecasting. -* Menu: - -* Nested budgets:: - - -File: hledger.info, Node: Nested budgets, Up: Budget report - -4.4.7.1 Nested budgets -...................... - -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 -budget(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 -account, all its parents would have budget as well. - - To illustrate this, consider the following budget: - -~ monthly from 2019/01 - expenses:personal $1,000.00 - 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 implicity -means that budget for both 'expenses:personal' and 'expenses' is $1100. - - Transactions in 'expenses:personal:electronics' will be counted both -towards its $100 budget and $1100 of 'expenses:personal' , and -transactions 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: - -~ monthly from 2019/01 - expenses:personal $1,000.00 - expenses:personal:electronics $100.00 - liabilities - -2019/01/01 Google home hub - expenses:personal:electronics $90.00 - liabilities $-90.00 - -2019/01/02 Phone screen protector - expenses:personal:electronics:upgrades $10.00 - liabilities - -2019/01/02 Weekly train ticket - expenses:personal:train tickets $153.00 - liabilities - -2019/01/03 Flowers - expenses:personal $30.00 - liabilities - - As you can see, we have transactions in -'expenses:personal:electronics:upgrades' and 'expenses:personal:train -tickets', and since both of these accounts are without explicitly -defined budget, these transactions would be counted towards budgets of -'expenses:personal:electronics' and 'expenses:personal' accordingly: - -$ hledger balance --budget -M -Budget performance in 2019/01: - - || Jan -===============================++=============================== - expenses || $283.00 [ 26% of $1100.00] - expenses:personal || $283.00 [ 26% of $1100.00] - expenses:personal:electronics || $100.00 [ 100% of $100.00] - liabilities || $-283.00 [ 26% of $-1100.00] --------------------------------++------------------------------- - || 0 [ 0] - - And with '--empty', we can get a better picture of budget allocation -and consumption: - -$ hledger balance --budget -M --empty -Budget performance in 2019/01: - - || Jan -========================================++=============================== - expenses || $283.00 [ 26% of $1100.00] - expenses:personal || $283.00 [ 26% of $1100.00] - expenses:personal:electronics || $100.00 [ 100% of $100.00] - expenses:personal:electronics:upgrades || $10.00 - expenses:personal:train tickets || $153.00 - liabilities || $-283.00 [ 26% of $-1100.00] -----------------------------------------++------------------------------- - || 0 [ 0] - -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 @@ -2767,92 +2199,75 @@ Node: add34941 Ref: #add35040 Node: balance37627 Ref: #balance37738 -Node: Classic balance report40858 -Ref: #classic-balance-report41031 -Node: Customising the classic balance report42400 -Ref: #customising-the-classic-balance-report42628 -Node: Colour support44702 -Ref: #colour-support44869 -Node: Flat mode45042 -Ref: #flat-mode45190 -Node: Depth limited balance reports45603 -Ref: #depth-limited-balance-reports45803 -Node: Multicolumn balance report46259 -Ref: #multicolumn-balance-report46457 -Node: Budget report51697 -Ref: #budget-report51840 -Node: Nested budgets56524 -Ref: #nested-budgets56636 -Ref: #output-format-160116 -Node: balancesheet60194 -Ref: #balancesheet60330 -Node: balancesheetequity62641 -Ref: #balancesheetequity62790 -Node: cashflow63327 -Ref: #cashflow63455 -Node: check-dates65578 -Ref: #check-dates65705 -Node: check-dupes65822 -Ref: #check-dupes65946 -Node: close66083 -Ref: #close66191 -Node: files69604 -Ref: #files69705 -Node: help69846 -Ref: #help69946 -Node: import71020 -Ref: #import71134 -Node: incomestatement71864 -Ref: #incomestatement71998 -Node: prices74402 -Ref: #prices74517 -Node: print74789 -Ref: #print74899 -Node: print-unique79793 -Ref: #print-unique79919 -Node: register79987 -Ref: #register80114 -Node: Custom register output84615 -Ref: #custom-register-output84744 -Node: register-match85974 -Ref: #register-match86108 -Node: rewrite86291 -Ref: #rewrite86406 -Node: roi86475 -Ref: #roi86573 -Node: stats86689 -Ref: #stats86788 -Node: tags87658 -Ref: #tags87756 -Node: test87992 -Ref: #test88076 -Node: ADD-ON COMMANDS88784 -Ref: #add-on-commands88894 -Node: Official add-ons90181 -Ref: #official-add-ons90321 -Node: api90408 -Ref: #api90497 -Node: ui90549 -Ref: #ui90648 -Node: web90706 -Ref: #web90795 -Node: Third party add-ons90841 -Ref: #third-party-add-ons91016 -Node: diff91151 -Ref: #diff91248 -Node: iadd91347 -Ref: #iadd91461 -Node: interest91544 -Ref: #interest91665 -Node: irr91760 -Ref: #irr91858 -Node: Experimental add-ons91989 -Ref: #experimental-add-ons92141 -Node: autosync92421 -Ref: #autosync92532 -Node: chart92771 -Ref: #chart92890 -Node: check92961 -Ref: #check93063 +Node: balancesheet37738 +Ref: #balancesheet37874 +Node: balancesheetequity40185 +Ref: #balancesheetequity40334 +Node: cashflow40871 +Ref: #cashflow40999 +Node: check-dates43122 +Ref: #check-dates43249 +Node: check-dupes43366 +Ref: #check-dupes43490 +Node: close43627 +Ref: #close43735 +Node: files47148 +Ref: #files47249 +Node: help47390 +Ref: #help47490 +Node: import48564 +Ref: #import48678 +Node: incomestatement49408 +Ref: #incomestatement49542 +Node: prices51946 +Ref: #prices52061 +Node: print52333 +Ref: #print52443 +Node: print-unique57337 +Ref: #print-unique57463 +Node: register57531 +Ref: #register57658 +Node: Custom register output62159 +Ref: #custom-register-output62288 +Node: register-match63518 +Ref: #register-match63652 +Node: rewrite63835 +Ref: #rewrite63950 +Node: roi64019 +Ref: #roi64117 +Node: stats64233 +Ref: #stats64332 +Node: tags65202 +Ref: #tags65300 +Node: test65536 +Ref: #test65620 +Node: ADD-ON COMMANDS66328 +Ref: #add-on-commands66438 +Node: Official add-ons67725 +Ref: #official-add-ons67865 +Node: api67952 +Ref: #api68041 +Node: ui68093 +Ref: #ui68192 +Node: web68250 +Ref: #web68339 +Node: Third party add-ons68385 +Ref: #third-party-add-ons68560 +Node: diff68695 +Ref: #diff68792 +Node: iadd68891 +Ref: #iadd69005 +Node: interest69088 +Ref: #interest69209 +Node: irr69304 +Ref: #irr69402 +Node: Experimental add-ons69533 +Ref: #experimental-add-ons69685 +Node: autosync69965 +Ref: #autosync70076 +Node: chart70315 +Ref: #chart70434 +Node: check70505 +Ref: #check70607  End Tag Table diff --git a/hledger/hledger.txt b/hledger/hledger.txt index 4fcc1d7ff..5ec96f10b 100644 --- a/hledger/hledger.txt +++ b/hledger/hledger.txt @@ -1014,527 +1014,6 @@ COMMANDS Date [2015/05/22]: $ balance - Show accounts and their balances. Aliases: b, bal. - - --change - show balance change in each period (default) - - --cumulative - show balance change accumulated across periods (in multicolumn - reports) - - -H --historical - show historical ending balance in each period (includes postings - before report start date) - - --tree show accounts as a tree; amounts include subaccounts (default in - simple reports) - - --flat show accounts as a list; amounts exclude subaccounts except when - account is depth-clipped (default in multicolumn reports) - - -A --average - show a row average column (in multicolumn mode) - - -T --row-total - show a row total column (in multicolumn mode) - - -N --no-total - don't show the final total row - - --drop=N - omit N leading account name parts (in flat mode) - - --no-elide - don't squash boring parent accounts (in tree mode) - - --format=LINEFORMAT - in single-column balance reports: use this custom line format - - -O FMT --output-format=FMT - select the output format. Supported formats: txt, csv, html. - - --transpose - transposes rows and columns in multi-column reports. Supported - formats: txt, csv - - -o FILE --output-file=FILE - write output to FILE. A file extension matching one of the - above formats selects that format. - - --pretty-tables - use unicode to display prettier tables. - - --sort-amount - sort by amount instead of account code/name (in flat mode). - With multiple columns, sorts by the row total, or by row average - if that is displayed. - - --invert - display all amounts with reversed sign - - --budget - show performance compared to budget goals defined by periodic - transactions - - 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 - $1 bank:saving - $-2 cash - $2 expenses - $1 food - $1 supplies - $-2 income - $-1 gifts - $-1 salary - $1 liabilities:debts - -------------------- - 0 - - 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. (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 --for- - mat 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 - effect, instead %(account) has indentation built in. - Experimentation may be needed to get pleasing results. - - Some example formats: - - o %(total) - the account's total - - o %-20.20(account) - the account's name, left justified, padded to 20 - 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 - The balance command shows negative amounts in red, if: - - o the TERM environment variable is not set to dumb - - 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). With --budget, --empty also shows unbudgeted - accounts. - - 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: - - || Nov Dec - ======================++==================================================== - assets || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480] - assets:bank || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480] - assets:bank:checking || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480] - expenses || $495 [ 103% of $480] $565 [ 118% of $480] - 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] 0 [ 0] - - By default, only accounts with budget goals during the report period - are shown. In the example above, transactions in expenses:gifts and - expenses:supplies are counted towards expenses budget, but accounts - expenses:gifts and expenses:supplies are not shown, as they don't have - any budgets. - - You can use --empty shows unbudgeted accounts as well: - - $ hledger balance -M --budget --empty - Budget performance in 2017/11/01-2017/12/31: - - || Nov Dec - ======================++==================================================== - assets || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480] - assets:bank || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480] - assets:bank:checking || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480] - expenses || $495 [ 103% of $480] $565 [ 118% of $480] - 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] 0 [ 0] - - 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: - - || Nov Dec - ======================++==================================================== - assets || $-2445 [ 99% of $-2480] $-5110 [ 103% of $-4960] - assets:bank || $-2445 [ 99% of $-2480] $-5110 [ 103% of $-4960] - assets:bank:checking || $-2445 [ 99% of $-2480] $-5110 [ 103% of $-4960] - expenses || $495 [ 103% of $480] $1060 [ 110% of $960] - 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] - - Note, the -S/--sort-amount flag is not yet fully supported with --bud- - get. - - For more examples, see Budgeting and Forecasting. - - Nested budgets - 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 - parent, much like account balances behave. - - 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: - - ~ monthly from 2019/01 - expenses:personal $1,000.00 - 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 implicity - means that budget for both expenses:personal and expenses is $1100. - - Transactions in expenses:personal:electronics will be counted both - towards its $100 budget and $1100 of expenses:personal , and transac- - tions in any other subaccount of expenses:personal would be counted - towards only towards the budget of expenses:personal. - - For example, let's consider these transactions: - - ~ monthly from 2019/01 - expenses:personal $1,000.00 - expenses:personal:electronics $100.00 - liabilities - - 2019/01/01 Google home hub - expenses:personal:electronics $90.00 - liabilities $-90.00 - - 2019/01/02 Phone screen protector - expenses:personal:electronics:upgrades $10.00 - liabilities - - 2019/01/02 Weekly train ticket - expenses:personal:train tickets $153.00 - liabilities - - 2019/01/03 Flowers - 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- - tions would be counted towards budgets of expenses:personal:electronics - and expenses:personal accordingly: - - $ hledger balance --budget -M - Budget performance in 2019/01: - - || Jan - ===============================++=============================== - expenses || $283.00 [ 26% of $1100.00] - expenses:personal || $283.00 [ 26% of $1100.00] - expenses:personal:electronics || $100.00 [ 100% of $100.00] - liabilities || $-283.00 [ 26% of $-1100.00] - -------------------------------++------------------------------- - || 0 [ 0] - - And with --empty, we can get a better picture of budget allocation and - consumption: - - $ hledger balance --budget -M --empty - Budget performance in 2019/01: - - || Jan - ========================================++=============================== - expenses || $283.00 [ 26% of $1100.00] - expenses:personal || $283.00 [ 26% of $1100.00] - expenses:personal:electronics || $100.00 [ 100% of $100.00] - expenses:personal:electronics:upgrades || $10.00 - expenses:personal:train tickets || $153.00 - liabilities || $-283.00 [ 26% of $-1100.00] - ----------------------------------------++------------------------------- - || 0 [ 0] - - 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 diff --git a/hledger/hledger_commands.m4.md b/hledger/hledger_commands.m4.md index 7bfe82d8e..27ddcfdcb 100644 --- a/hledger/hledger_commands.m4.md +++ b/hledger/hledger_commands.m4.md @@ -35,7 +35,9 @@ _include_(Hledger/Cli/Commands/Activity.md) _include_(Hledger/Cli/Commands/Add.md) -_include_({{hledger_balance.m4.md}}) +## balance + +_include_({{Hledger/Cli/Commands/Balance.md}}) ## balancesheet This command displays a simple balance sheet, showing historical ending