diff --git a/hledger/hledger.1 b/hledger/hledger.1 index bcbb93cbd..da0d3512e 100644 --- a/hledger/hledger.1 +++ b/hledger/hledger.1 @@ -1487,83 +1487,583 @@ Date\ [2015/05/22]:\ \ $ \f[] .fi .SS balance +.PP +balance, bal, b +.PD 0 +.P +.PD +Show accounts and their balances. +.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 +balancesheet, bs +.PD 0 +.P +.PD This command displays a simple balance sheet, showing historical ending balances of asset and liability accounts (ignoring any report begin date). It assumes that these accounts are under a top\-level \f[C]asset\f[] or \f[C]liability\f[] account (case insensitive, plural forms also allowed). +.PP Note this report shows all account balances with normal positive sign (like conventional financial statements, unlike balance/print/register) (experimental). -(bs) -.TP -.B \f[C]\-\-change\f[] -show balance change in each period, instead of historical ending -balances -.RS -.RE -.TP -.B \f[C]\-\-cumulative\f[] -show balance change accumulated across periods (in multicolumn reports), -instead of historical ending balances -.RS -.RE -.TP -.B \f[C]\-H\ \-\-historical\f[] -show historical ending balance in each period (includes postings before -report start date) (default) -.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]\-\-sort\-amount\f[] -sort by amount instead of account code/name -.RS -.RE .PP Example: .IP @@ -1602,6 +2102,10 @@ This command also supports output destination and output format selection. .SS balancesheetequity .PP +balancesheetequity, bse +.PD 0 +.P +.PD Just like balancesheet, but also reports Equity (which it assumes is under a top\-level \f[C]equity\f[] account). .PP @@ -1636,6 +2140,10 @@ Total: .fi .SS cashflow .PP +cashflow, cf +.PD 0 +.P +.PD This command displays a simple cashflow statement, showing changes in "cash" accounts. It assumes that these accounts are under a top\-level \f[C]asset\f[] @@ -1644,71 +2152,6 @@ account (case insensitive, plural forms also allowed) and do not contain Note this report shows all account balances with normal positive sign (like conventional financial statements, unlike balance/print/register) (experimental). -(cf) -.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), -instead of changes during periods -.RS -.RE -.TP -.B \f[C]\-H\ \-\-historical\f[] -show historical ending balance in each period (includes postings before -report start date), instead of changes during each period -.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 (in simple reports) -.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]\-\-sort\-amount\f[] -sort by amount instead of account code/name -.RS -.RE .PP Example: .IP @@ -1740,11 +2183,25 @@ This command also supports output destination and output format selection. .SS check\-dates .PP +check\-dates +.PD 0 +.P +.PD Check that transactions are sorted by increasing date. +With \-\-date2, checks secondary dates instead. +With \-\-strict, dates must also be unique. With a query, only matched transactions\[aq] dates are checked. +Reads the default journal file, or another specified with \-f. .SS check\-dupes .PP -Report account names having the same leaf but different prefixes. +check\-dupes +.PD 0 +.P +.PD +Reports account names having the same leaf but different prefixes. +In other words, two or more leaves that are categorized differently. +Reads the default journal file, or another specified as an argument. +.PP An example: http://stefanorodighiero.net/software/hledger\-dupes.html .SS close .PP @@ -1853,11 +2310,19 @@ Here\[aq]s one way to resolve that: .fi .SS files .PP +files +.PD 0 +.P +.PD List all files included in the journal. With a REGEX argument, only file names matching the regular expression (case sensitive) are shown. .SS help .PP +help +.PD 0 +.P +.PD Show any of the hledger manuals. .PP The \f[C]help\f[] command displays any of the main hledger manuals, in @@ -1870,6 +2335,8 @@ hledger help will use the first of these display methods that it finds: info, man, $PAGER, less, stdout (or when non\-interactive, just stdout). You can force a particular viewer with the \f[C]\-\-info\f[], \f[C]\-\-man\f[], \f[C]\-\-pager\f[], \f[C]\-\-cat\f[] flags. +.PP +Examples: .IP .nf \f[C] @@ -1900,13 +2367,13 @@ DESCRIPTION .fi .SS import .PP +import +.PD 0 +.P +.PD Read new transactions added to each FILE since last run, and add them to the main journal file. -.TP -.B \f[C]\-\-dry\-run\f[] -just show the transactions to be imported -.RS -.RE +Or with \-\-dry\-run, just print the transactions that would be added. .PP The input files are specified as arguments \- no need to write \-f before each one. @@ -1927,6 +2394,10 @@ $\ hledger\ import\ \-\-dry\ ...\ |\ hledger\ \-f\-\ print\ unknown\ \-\-ignore\ .fi .SS incomestatement .PP +incomestatement, is +.PD 0 +.P +.PD This command displays a simple income statement, showing revenues and expenses during a period. It assumes that these accounts are under a top\-level \f[C]revenue\f[] @@ -1935,71 +2406,6 @@ forms also allowed). Note this report shows all account balances with normal positive sign (like conventional financial statements, unlike balance/print/register) (experimental). -(is) -.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), -instead of changes during periods -.RS -.RE -.TP -.B \f[C]\-H\ \-\-historical\f[] -show historical ending balance in each period (includes postings before -report start date), instead of changes during each period -.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]\-\-sort\-amount\f[] -sort by amount instead of account code/name -.RS -.RE .PP This command displays a simple income statement. It currently assumes that you have top\-level accounts named @@ -2041,6 +2447,10 @@ This command also supports output destination and output format selection. .SS prices .PP +prices +.PD 0 +.P +.PD Print market price directives from the journal. With \-\-costs, also print synthetic market prices based on transaction prices. @@ -2049,36 +2459,22 @@ prices. Prices (and postings providing prices) can be filtered by a query. .SS print .PP -Show transactions from the journal. -Aliases: p, txns. -.TP -.B \f[C]\-m\ STR\ \-\-match=STR\f[] -show the transaction whose description is most similar to STR, and is -most recent -.RS -.RE -.TP -.B \f[C]\-\-new\f[] -show only newer\-dated transactions added in each file since last run -.RS -.RE -.TP -.B \f[C]\-x\ \ \ \ \ \-\-explicit\f[] -show all amounts explicitly -.RS -.RE -.TP -.B \f[C]\-O\ FMT\ \-\-output\-format=FMT\f[] -select the output format. -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 +print, txns, p +.PD 0 +.P +.PD +Show transaction journal entries, sorted by date. +.PP +The print command displays full journal entries (transactions) from the +journal file in date order, tidily formatted. +With \-\-date2, transactions are sorted by secondary date instead. +.PP +print\[aq]s output is always a valid hledger journal. +.PD 0 +.P +.PD +It preserves all transaction information, but it does not preserve +directives or inter\-transaction comments .IP .nf \f[C] @@ -2106,12 +2502,6 @@ $\ hledger\ print \f[] .fi .PP -The print command displays full journal entries (transactions) from the -journal file in date order, tidily formatted. -print\[aq]s output is always a valid hledger journal. -It preserves all transaction information, but it does not preserve -directives or inter\-transaction comments -.PP Normally, the journal entry\[aq]s explicit or implicit amount style is preserved. Ie when an amount is omitted in the journal, it will be omitted in the @@ -2195,54 +2585,37 @@ for convenience. negative amounts under credit and zero or greater amounts under debit.) .SS print\-unique .PP +print\-unique +.PD 0 +.P +.PD Print transactions which do not reuse an already\-seen description. +.PP +Example: +.IP +.nf +\f[C] +$\ cat\ unique.journal +1/1\ test +\ (acct:one)\ \ 1 +2/2\ test +\ (acct:two)\ \ 2 +$\ LEDGER_FILE=unique.journal\ hledger\ print\-unique +(\-f\ option\ not\ supported) +2015/01/01\ test +\ \ \ \ (acct:one)\ \ \ \ \ \ \ \ \ \ \ \ \ 1 +\f[] +.fi .SS register .PP +register, reg, r +.PD 0 +.P +.PD Show postings and their running total. -Aliases: r, reg. -.TP -.B \f[C]\-\-cumulative\f[] -show running total from report start date (default) -.RS -.RE -.TP -.B \f[C]\-H\ \-\-historical\f[] -show historical running total/balance (includes postings before report -start date) -.RS -.RE -.TP -.B \f[C]\-A\ \-\-average\f[] -show running average of posting amounts instead of total (implies -\-\-empty) -.RS -.RE -.TP -.B \f[C]\-r\ \-\-related\f[] -show postings\[aq] siblings instead -.RS -.RE -.TP -.B \f[C]\-w\ N\ \-\-width=N\f[] -set output width (default: terminal width or COLUMNS. -\-wN,M sets description width as well) -.RS -.RE -.TP -.B \f[C]\-O\ FMT\ \-\-output\-format=FMT\f[] -select the output format. -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 .PP -The register command displays postings, one per line, and their running -total. +The register command displays postings in date order, one per line, and +their running total. This is typically used with a query selecting a particular account, to see that account\[aq]s activity: .IP @@ -2256,6 +2629,8 @@ $\ hledger\ register\ checking \f[] .fi .PP +With \-\-date2, it shows and sorts by secondary date instead. +.PP The \f[C]\-\-historical\f[]/\f[C]\-H\f[] flag adds the balance from any undisplayed prior postings to the running total. This is useful when you want to see only recent activity, with a @@ -2373,26 +2748,229 @@ This command also supports output destination and output format selection. .SS register\-match .PP +register\-match +.PD 0 +.P +.PD Print the one posting whose transaction description is closest to DESC, in the style of the register command. +If there are multiple equally good matches, it shows the most recent. +Query options (options, not arguments) can be used to restrict the +search space. Helps ledger\-autosync detect already\-seen transactions when importing. .SS rewrite .PP -Print all transactions, adding custom postings to the matched ones. +rewrite +.PD 0 +.P +.PD +Print all transactions, rewriting the postings of matched transactions. +For now the only rewrite available is adding new postings, like print +\-\-auto. +.PP +This is a start at a generic rewriter of transaction entries. +It reads the default journal and prints the transactions, like print, +but adds one or more specified postings to any transactions matching +QUERY. +The posting amounts can be fixed, or a multiplier of the existing +transaction\[aq]s first posting amount. +.PP +Examples: +.IP +.nf +\f[C] +hledger\-rewrite.hs\ ^income\ \-\-add\-posting\ \[aq](liabilities:tax)\ \ *.33\ \ ;\ income\ tax\[aq]\ \-\-add\-posting\ \[aq](reserve:gifts)\ \ $100\[aq] +hledger\-rewrite.hs\ expenses:gifts\ \-\-add\-posting\ \[aq](reserve:gifts)\ \ *\-1"\[aq] +hledger\-rewrite.hs\ \-f\ rewrites.hledger +\f[] +.fi +.PP +rewrites.hledger may consist of entries like: +.IP +.nf +\f[C] +=\ ^income\ amt:<0\ date:2017 +\ \ (liabilities:tax)\ \ *0.33\ \ ;\ tax\ on\ income +\ \ (reserve:grocery)\ \ *0.25\ \ ;\ reserve\ 25%\ for\ grocery +\ \ (reserve:)\ \ *0.25\ \ ;\ reserve\ 25%\ for\ grocery +\f[] +.fi +.PP +Note the single quotes to protect the dollar sign from bash, and the two +spaces between account and amount. +.PP +More: +.IP +.nf +\f[C] +$\ hledger\ rewrite\ \-\-\ [QUERY]\ \ \ \ \ \ \ \ \-\-add\-posting\ "ACCT\ \ AMTEXPR"\ ... +$\ hledger\ rewrite\ \-\-\ ^income\ \ \ \ \ \ \ \ \-\-add\-posting\ \[aq](liabilities:tax)\ \ *.33\[aq] +$\ hledger\ rewrite\ \-\-\ expenses:gifts\ \-\-add\-posting\ \[aq](budget:gifts)\ \ *\-1"\[aq] +$\ hledger\ rewrite\ \-\-\ ^income\ \ \ \ \ \ \ \ \-\-add\-posting\ \[aq](budget:foreign\ currency)\ \ *0.25\ JPY;\ diversify\[aq] +\f[] +.fi +.PP +Argument for \f[C]\-\-add\-posting\f[] option is a usual posting of +transaction with an exception for amount specification. +More precisely, you can use \f[C]\[aq]*\[aq]\f[] (star symbol) before +the amount to indicate that that this is a factor for an amount of +original matched posting. +If the amount includes a commodity name, the new posting amount will be +in the new commodity; otherwise, it will be in the matched posting +amount\[aq]s commodity. +.SS Re\-write rules in a file +.PP +During the run this tool will execute so called "Automated Transactions" +found in any journal it process. +I.e instead of specifying this operations in command line you can put +them in a journal file. +.IP +.nf +\f[C] +$\ rewrite\-rules.journal +\f[] +.fi +.PP +Make contents look like this: +.IP +.nf +\f[C] +=\ ^income +\ \ \ \ (liabilities:tax)\ \ *.33 + +=\ expenses:gifts +\ \ \ \ budget:gifts\ \ *\-1 +\ \ \ \ assets:budget\ \ *1 +\f[] +.fi +.PP +Note that \f[C]\[aq]=\[aq]\f[] (equality symbol) that is used instead of +date in transactions you usually write. +It indicates the query by which you want to match the posting to add new +ones. +.IP +.nf +\f[C] +$\ hledger\ rewrite\ \-\-\ \-f\ input.journal\ \-f\ rewrite\-rules.journal\ >\ rewritten\-tidy\-output.journal +\f[] +.fi +.PP +This is something similar to the commands pipeline: +.IP +.nf +\f[C] +$\ hledger\ rewrite\ \-\-\ \-f\ input.journal\ \[aq]^income\[aq]\ \-\-add\-posting\ \[aq](liabilities:tax)\ \ *.33\[aq]\ \\ +\ \ |\ hledger\ rewrite\ \-\-\ \-f\ \-\ expenses:gifts\ \ \ \ \ \ \-\-add\-posting\ \[aq]budget:gifts\ \ *\-1\[aq]\ \ \ \ \ \ \ \\ +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \-\-add\-posting\ \[aq]assets:budget\ \ *1\[aq]\ \ \ \ \ \ \ \\ +\ \ >\ rewritten\-tidy\-output.journal +\f[] +.fi +.PP +It is important to understand that relative order of such entries in +journal is important. +You can re\-use result of previously added postings. +.SS Diff output format +.PP +To use this tool for batch modification of your journal files you may +find useful output in form of unified diff. +.IP +.nf +\f[C] +$\ hledger\ rewrite\ \-\-\ \-\-diff\ \-f\ examples/sample.journal\ \[aq]^income\[aq]\ \-\-add\-posting\ \[aq](liabilities:tax)\ \ *.33\[aq] +\f[] +.fi +.PP +Output might look like: +.IP +.nf +\f[C] +\-\-\-\ /tmp/examples/sample.journal ++++\ /tmp/examples/sample.journal +\@\@\ \-18,3\ +18,4\ \@\@ +\ 2008/01/01\ income +\-\ \ \ \ assets:bank:checking\ \ $1 ++\ \ \ \ assets:bank:checking\ \ \ \ \ \ \ \ \ \ \ \ $1 +\ \ \ \ \ income:salary ++\ \ \ \ (liabilities:tax)\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0 +\@\@\ \-22,3\ +23,4\ \@\@ +\ 2008/06/01\ gift +\-\ \ \ \ assets:bank:checking\ \ $1 ++\ \ \ \ assets:bank:checking\ \ \ \ \ \ \ \ \ \ \ \ $1 +\ \ \ \ \ income:gifts ++\ \ \ \ (liabilities:tax)\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0 +\f[] +.fi +.PP +If you\[aq]ll pass this through \f[C]patch\f[] tool you\[aq]ll get +transactions containing the posting that matches your query be updated. +Note that multiple files might be update according to list of input +files specified via \f[C]\-\-file\f[] options and \f[C]include\f[] +directives inside of these files. +.PP +Be careful. +Whole transaction being re\-formatted in a style of output from +\f[C]hledger\ print\f[]. +.PP +See also: +.PP +https://github.com/simonmichael/hledger/issues/99 +.SS rewrite vs. print \-\-auto +.PP +This command predates print \-\-auto, and currently does much the same +thing, but with these differences: +.IP \[bu] 2 +with multiple files, rewrite lets rules in any file affect all other +files. +print \-\-auto uses standard directive scoping; rules affect only child +files. +.IP \[bu] 2 +rewrite\[aq]s query limits which transactions can be rewritten; all are +printed. +print \-\-auto\[aq]s query limits which transactions are printed. +.IP \[bu] 2 +rewrite applies rules specified on command line or in the journal. +print \-\-auto applies rules specified in the journal. .SS roi .PP -Shows time\-weighted (TWR) and money\-weighted (IRR) rate of return on -your investments. -See \f[C]roi\ \-\-help\f[] for more. +roi +.PD 0 +.P +.PD +Shows the time\-weighted (TWR) and money\-weighted (IRR) rate of return +on your investments. +.PP +This command assumes that you have account(s) that hold nothing but your +investments and whenever you record current appraisal/valuation of these +investments you offset unrealized profit and loss into account(s) that, +again, hold nothing but unrealized profit and loss. +.PP +Any transactions affecting balance of investment account(s) and not +originating from unrealized profit and loss account(s) are assumed to be +your investments or withdrawals. +.PP +At a minimum, you need to supply a query (which could be just an account +name) to select your investments with \f[C]\-\-inv\f[], and another +query to identify your profit and loss transactions with +\f[C]\-\-pnl\f[]. +.PP +It will compute and display the internalized rate of return (IRR) and +time\-weighted rate of return (TWR) for your investments for the time +period requested. +Both rates of return are annualized before display, regardless of the +length of reporting interval. .SS stats .PP +stats +.PD 0 +.P +.PD Show some journal statistics. -.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 +.PP +The stats command displays summary information for the whole journal, or +a matched part of it. +With a reporting interval, it shows a report for each report period. +.PP +Example: .IP .nf \f[C] @@ -2410,25 +2988,30 @@ Commodities\ \ \ \ \ \ \ \ \ \ \ \ \ \ :\ 1\ ($) \f[] .fi .PP -The stats command displays summary information for the whole journal, or -a matched part of it. -With a reporting interval, it shows a report for each report period. -.PP This command also supports output destination and output format selection. .SS tags .PP +tags +.PD 0 +.P +.PD List all the tag names used in the journal. With a TAGREGEX argument, only tag names matching the regular expression (case insensitive) are shown. -With additional QUERY arguments, only transactions matching the query -are considered. +With QUERY arguments, only transactions matching the query are +considered. .SS test .PP +test +.PD 0 +.P +.PD Run built\-in unit tests. .PP -Prints test names and their results on stdout. -If any test fails or gives an error, the exit code will be non\-zero. +This command runs the unit tests built in to hledger\-lib and hledger, +printing test names and results on stdout. +If any test fails, the exit code will be non\-zero. .PP Test names include a group prefix. If a (exact, case sensitive) group prefix, or a full test name is diff --git a/hledger/hledger.info b/hledger/hledger.info index 50f1b4a7c..6aaa7b8ca 100644 --- a/hledger/hledger.info +++ b/hledger/hledger.info @@ -1138,61 +1138,526 @@ File: hledger.info, Node: balance, Next: balancesheet, Prev: add, Up: COMMAN 4.4 balance =========== +balance, bal, b +Show accounts and their balances. + + 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 4.5 balancesheet ================ +balancesheet, bs This command displays a simple balance sheet, showing historical ending balances of asset and liability accounts (ignoring any report begin date). It assumes that these accounts are under a top-level 'asset' or -'liability' account (case insensitive, plural forms also allowed). Note -this report shows all account balances with normal positive sign (like -conventional financial statements, unlike balance/print/register) -(experimental). (bs) +'liability' account (case insensitive, plural forms also allowed). -'--change' - - show balance change in each period, instead of historical ending - balances -'--cumulative' - - show balance change accumulated across periods (in multicolumn - reports), instead of historical ending balances -'-H --historical' - - show historical ending balance in each period (includes postings - before report start date) (default) -'--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 -'--sort-amount' - - sort by amount instead of account code/name + Note this report shows all account balances with normal positive sign +(like conventional financial statements, unlike balance/print/register) +(experimental). Example: @@ -1230,6 +1695,7 @@ File: hledger.info, Node: balancesheetequity, Next: cashflow, Prev: balancesh 4.6 balancesheetequity ====================== +balancesheetequity, bse Just like balancesheet, but also reports Equity (which it assumes is under a top-level 'equity' account). @@ -1265,53 +1731,13 @@ File: hledger.info, Node: cashflow, Next: check-dates, Prev: balancesheetequi 4.7 cashflow ============ +cashflow, cf This command displays a simple cashflow statement, showing changes in "cash" accounts. It assumes that these accounts are under a top-level 'asset' account (case insensitive, plural forms also allowed) and do not contain 'receivable' or 'A/R' in their name. Note this report shows all account balances with normal positive sign (like conventional financial -statements, unlike balance/print/register) (experimental). (cf) - -'--change' - - show balance change in each period (default) -'--cumulative' - - show balance change accumulated across periods (in multicolumn - reports), instead of changes during periods -'-H --historical' - - show historical ending balance in each period (includes postings - before report start date), instead of changes during each period -'--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 (in simple reports) -'--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 -'--sort-amount' - - sort by amount instead of account code/name +statements, unlike balance/print/register) (experimental). Example: @@ -1343,8 +1769,11 @@ File: hledger.info, Node: check-dates, Next: check-dupes, Prev: cashflow, Up 4.8 check-dates =============== -Check that transactions are sorted by increasing date. With a query, -only matched transactions' dates are checked. +check-dates +Check that transactions are sorted by increasing date. With -date2, +checks secondary dates instead. With -strict, dates must also be +unique. With a query, only matched transactions' dates are checked. +Reads the default journal file, or another specified with -f.  File: hledger.info, Node: check-dupes, Next: close, Prev: check-dates, Up: COMMANDS @@ -1352,8 +1781,12 @@ File: hledger.info, Node: check-dupes, Next: close, Prev: check-dates, Up: C 4.9 check-dupes =============== -Report account names having the same leaf but different prefixes. An -example: http://stefanorodighiero.net/software/hledger-dupes.html +check-dupes +Reports account names having the same leaf but different prefixes. In +other words, two or more leaves that are categorized differently. Reads +the default journal file, or another specified as an argument. + + An example: http://stefanorodighiero.net/software/hledger-dupes.html  File: hledger.info, Node: close, Next: files, Prev: check-dupes, Up: COMMANDS @@ -1446,6 +1879,7 @@ File: hledger.info, Node: files, Next: help, Prev: close, Up: COMMANDS 4.11 files ========== +files List all files included in the journal. With a REGEX argument, only file names matching the regular expression (case sensitive) are shown. @@ -1455,6 +1889,7 @@ File: hledger.info, Node: help, Next: import, Prev: files, Up: COMMANDS 4.12 help ========= +help Show any of the hledger manuals. The 'help' command displays any of the main hledger manuals, in one @@ -1466,6 +1901,8 @@ use the first of these display methods that it finds: info, man, $PAGER, less, stdout (or when non-interactive, just stdout). You can force a particular viewer with the '--info', '--man', '--pager', '--cat' flags. + Examples: + $ hledger help Please choose a manual by typing "hledger help MANUAL" (a substring is ok). Manuals: hledger hledger-ui hledger-web hledger-api journal csv timeclock timedot @@ -1492,12 +1929,10 @@ File: hledger.info, Node: import, Next: incomestatement, Prev: help, Up: COM 4.13 import =========== +import Read new transactions added to each FILE since last run, and add them to -the main journal file. - -'--dry-run' - - just show the transactions to be imported +the main journal file. Or with -dry-run, just print the transactions +that would be added. The input files are specified as arguments - no need to write -f before each one. So eg to add new transactions from all CSV files to @@ -1518,53 +1953,13 @@ File: hledger.info, Node: incomestatement, Next: prices, Prev: import, Up: C 4.14 incomestatement ==================== +incomestatement, is This command displays a simple income statement, showing revenues and expenses during a period. It assumes that these accounts are under a top-level 'revenue' or 'income' or 'expense' account (case insensitive, plural forms also allowed). Note this report shows all account balances with normal positive sign (like conventional financial statements, -unlike balance/print/register) (experimental). (is) - -'--change' - - show balance change in each period (default) -'--cumulative' - - show balance change accumulated across periods (in multicolumn - reports), instead of changes during periods -'-H --historical' - - show historical ending balance in each period (includes postings - before report start date), instead of changes during each period -'--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 -'--sort-amount' - - sort by amount instead of account code/name +unlike balance/print/register) (experimental). This command displays a simple income statement. It currently assumes that you have top-level accounts named 'income' (or 'revenue') @@ -1605,6 +2000,7 @@ File: hledger.info, Node: prices, Next: print, Prev: incomestatement, Up: CO 4.15 prices =========== +prices Print market price directives from the journal. With -costs, also print synthetic market prices based on transaction prices. With -inverted-costs, also print inverse prices based on transaction prices. @@ -1616,26 +2012,16 @@ File: hledger.info, Node: print, Next: print-unique, Prev: prices, Up: COMMA 4.16 print ========== -Show transactions from the journal. Aliases: p, txns. +print, txns, p +Show transaction journal entries, sorted by date. -'-m STR --match=STR' + The print command displays full journal entries (transactions) from +the journal file in date order, tidily formatted. With -date2, +transactions are sorted by secondary date instead. - show the transaction whose description is most similar to STR, and - is most recent -'--new' - - show only newer-dated transactions added in each file since last - run -'-x --explicit' - - show all amounts explicitly -'-O FMT --output-format=FMT' - - select the output format. 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. + print's output is always a valid hledger journal. +It preserves all transaction information, but it does not preserve +directives or inter-transaction comments $ hledger print 2008/01/01 income @@ -1659,12 +2045,6 @@ $ hledger print liabilities:debts $1 assets:bank:checking $-1 - The print command displays full journal entries (transactions) from -the journal file in date order, tidily formatted. print's output is -always a valid hledger journal. It preserves all transaction -information, but it does not preserve directives or inter-transaction -comments - Normally, the journal entry's explicit or implicit amount style is preserved. Ie when an amount is omitted in the journal, it will be omitted in the output. You can use the '-x'/'--explicit' flag to make @@ -1733,45 +2113,33 @@ File: hledger.info, Node: print-unique, Next: register, Prev: print, Up: COM 4.17 print-unique ================= +print-unique Print transactions which do not reuse an already-seen description. + Example: + +$ cat unique.journal +1/1 test + (acct:one) 1 +2/2 test + (acct:two) 2 +$ LEDGER_FILE=unique.journal hledger print-unique +(-f option not supported) +2015/01/01 test + (acct:one) 1 +  File: hledger.info, Node: register, Next: register-match, Prev: print-unique, Up: COMMANDS 4.18 register ============= -Show postings and their running total. Aliases: r, reg. +register, reg, r +Show postings and their running total. -'--cumulative' - - show running total from report start date (default) -'-H --historical' - - show historical running total/balance (includes postings before - report start date) -'-A --average' - - show running average of posting amounts instead of total (implies - -empty) -'-r --related' - - show postings' siblings instead -'-w N --width=N' - - set output width (default: terminal width or COLUMNS. -wN,M sets - description width as well) -'-O FMT --output-format=FMT' - - select the output format. 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. - - The register command displays postings, one per line, and their -running total. This is typically used with a query selecting a -particular account, to see that account's activity: + The register command displays postings in date order, one per line, +and their running total. This is typically used with a query selecting +a particular account, to see that account's activity: $ hledger register checking 2008/01/01 income assets:bank:checking $1 $1 @@ -1779,6 +2147,8 @@ $ hledger register checking 2008/06/02 save assets:bank:checking $-1 $1 2008/12/31 pay off assets:bank:checking $-1 0 + With -date2, it shows and sorts by secondary date instead. + The '--historical'/'-H' flag adds the balance from any undisplayed prior postings to the running total. This is useful when you want to see only recent activity, with a historically accurate running balance: @@ -1877,9 +2247,12 @@ File: hledger.info, Node: register-match, Next: rewrite, Prev: register, Up: 4.19 register-match =================== +register-match Print the one posting whose transaction description is closest to DESC, -in the style of the register command. Helps ledger-autosync detect -already-seen transactions when importing. +in the style of the register command. If there are multiple equally +good matches, it shows the most recent. Query options (options, not +arguments) can be used to restrict the search space. Helps +ledger-autosync detect already-seen transactions when importing.  File: hledger.info, Node: rewrite, Next: roi, Prev: register-match, Up: COMMANDS @@ -1887,7 +2260,155 @@ File: hledger.info, Node: rewrite, Next: roi, Prev: register-match, Up: COMM 4.20 rewrite ============ -Print all transactions, adding custom postings to the matched ones. +rewrite +Print all transactions, rewriting the postings of matched transactions. +For now the only rewrite available is adding new postings, like print +-auto. + + This is a start at a generic rewriter of transaction entries. It +reads the default journal and prints the transactions, like print, but +adds one or more specified postings to any transactions matching QUERY. +The posting amounts can be fixed, or a multiplier of the existing +transaction's first posting amount. + + Examples: + +hledger-rewrite.hs ^income --add-posting '(liabilities:tax) *.33 ; income tax' --add-posting '(reserve:gifts) $100' +hledger-rewrite.hs expenses:gifts --add-posting '(reserve:gifts) *-1"' +hledger-rewrite.hs -f rewrites.hledger + + rewrites.hledger may consist of entries like: + += ^income amt:<0 date:2017 + (liabilities:tax) *0.33 ; tax on income + (reserve:grocery) *0.25 ; reserve 25% for grocery + (reserve:) *0.25 ; reserve 25% for grocery + + Note the single quotes to protect the dollar sign from bash, and the +two spaces between account and amount. + + More: + +$ hledger rewrite -- [QUERY] --add-posting "ACCT AMTEXPR" ... +$ hledger rewrite -- ^income --add-posting '(liabilities:tax) *.33' +$ hledger rewrite -- expenses:gifts --add-posting '(budget:gifts) *-1"' +$ hledger rewrite -- ^income --add-posting '(budget:foreign currency) *0.25 JPY; diversify' + + Argument for '--add-posting' option is a usual posting of transaction +with an exception for amount specification. More precisely, you can use +''*'' (star symbol) before the amount to indicate that that this is a +factor for an amount of original matched posting. If the amount +includes a commodity name, the new posting amount will be in the new +commodity; otherwise, it will be in the matched posting amount's +commodity. + +* Menu: + +* Re-write rules in a file:: + + +File: hledger.info, Node: Re-write rules in a file, Up: rewrite + +4.20.1 Re-write rules in a file +------------------------------- + +During the run this tool will execute so called "Automated Transactions" +found in any journal it process. I.e instead of specifying this +operations in command line you can put them in a journal file. + +$ rewrite-rules.journal + + Make contents look like this: + += ^income + (liabilities:tax) *.33 + += expenses:gifts + budget:gifts *-1 + assets:budget *1 + + Note that ''='' (equality symbol) that is used instead of date in +transactions you usually write. It indicates the query by which you +want to match the posting to add new ones. + +$ hledger rewrite -- -f input.journal -f rewrite-rules.journal > rewritten-tidy-output.journal + + This is something similar to the commands pipeline: + +$ hledger rewrite -- -f input.journal '^income' --add-posting '(liabilities:tax) *.33' \ + | hledger rewrite -- -f - expenses:gifts --add-posting 'budget:gifts *-1' \ + --add-posting 'assets:budget *1' \ + > rewritten-tidy-output.journal + + It is important to understand that relative order of such entries in +journal is important. You can re-use result of previously added +postings. + +* Menu: + +* Diff output format:: +* rewrite vs print --auto:: + + +File: hledger.info, Node: Diff output format, Next: rewrite vs print --auto, Up: Re-write rules in a file + +4.20.1.1 Diff output format +........................... + +To use this tool for batch modification of your journal files you may +find useful output in form of unified diff. + +$ hledger rewrite -- --diff -f examples/sample.journal '^income' --add-posting '(liabilities:tax) *.33' + + Output might look like: + +--- /tmp/examples/sample.journal ++++ /tmp/examples/sample.journal +@@ -18,3 +18,4 @@ + 2008/01/01 income +- assets:bank:checking $1 ++ assets:bank:checking $1 + income:salary ++ (liabilities:tax) 0 +@@ -22,3 +23,4 @@ + 2008/06/01 gift +- assets:bank:checking $1 ++ assets:bank:checking $1 + income:gifts ++ (liabilities:tax) 0 + + If you'll pass this through 'patch' tool you'll get transactions +containing the posting that matches your query be updated. Note that +multiple files might be update according to list of input files +specified via '--file' options and 'include' directives inside of these +files. + + Be careful. Whole transaction being re-formatted in a style of +output from 'hledger print'. + + See also: + + https://github.com/simonmichael/hledger/issues/99 + + +File: hledger.info, Node: rewrite vs print --auto, Prev: Diff output format, Up: Re-write rules in a file + +4.20.1.2 rewrite vs. print -auto +................................ + +This command predates print -auto, and currently does much the same +thing, but with these differences: + + * with multiple files, rewrite lets rules in any file affect all + other files. print -auto uses standard directive scoping; rules + affect only child files. + + * rewrite's query limits which transactions can be rewritten; all are + printed. print -auto's query limits which transactions are + printed. + + * rewrite applies rules specified on command line or in the journal. + print -auto applies rules specified in the journal.  File: hledger.info, Node: roi, Next: stats, Prev: rewrite, Up: COMMANDS @@ -1895,8 +2416,27 @@ File: hledger.info, Node: roi, Next: stats, Prev: rewrite, Up: COMMANDS 4.21 roi ======== -Shows time-weighted (TWR) and money-weighted (IRR) rate of return on -your investments. See 'roi --help' for more. +roi +Shows the time-weighted (TWR) and money-weighted (IRR) rate of return on +your investments. + + This command assumes that you have account(s) that hold nothing but +your investments and whenever you record current appraisal/valuation of +these investments you offset unrealized profit and loss into account(s) +that, again, hold nothing but unrealized profit and loss. + + Any transactions affecting balance of investment account(s) and not +originating from unrealized profit and loss account(s) are assumed to be +your investments or withdrawals. + + At a minimum, you need to supply a query (which could be just an +account name) to select your investments with '--inv', and another query +to identify your profit and loss transactions with '--pnl'. + + It will compute and display the internalized rate of return (IRR) and +time-weighted rate of return (TWR) for your investments for the time +period requested. Both rates of return are annualized before display, +regardless of the length of reporting interval.  File: hledger.info, Node: stats, Next: tags, Prev: roi, Up: COMMANDS @@ -1904,12 +2444,14 @@ File: hledger.info, Node: stats, Next: tags, Prev: roi, Up: COMMANDS 4.22 stats ========== +stats Show some journal statistics. -'-o FILE --output-file=FILE' + The stats command displays summary information for the whole journal, +or a matched part of it. With a reporting interval, it shows a report +for each report period. - write output to FILE. A file extension matching one of the above - formats selects that format. + Example: $ hledger stats Main journal file : /src/hledger/examples/sample.journal @@ -1923,10 +2465,6 @@ Payees/descriptions : 5 Accounts : 8 (depth 3) Commodities : 1 ($) - The stats command displays summary information for the whole journal, -or a matched part of it. With a reporting interval, it shows a report -for each report period. - This command also supports output destination and output format selection. @@ -1936,10 +2474,11 @@ File: hledger.info, Node: tags, Next: test, Prev: stats, Up: COMMANDS 4.23 tags ========= +tags List all the tag names used in the journal. With a TAGREGEX argument, only tag names matching the regular expression (case insensitive) are -shown. With additional QUERY arguments, only transactions matching the -query are considered. +shown. With QUERY arguments, only transactions matching the query are +considered.  File: hledger.info, Node: test, Prev: tags, Up: COMMANDS @@ -1947,10 +2486,12 @@ File: hledger.info, Node: test, Prev: tags, Up: COMMANDS 4.24 test ========= +test Run built-in unit tests. - Prints test names and their results on stdout. If any test fails or -gives an error, the exit code will be non-zero. + This command runs the unit tests built in to hledger-lib and hledger, +printing test names and results on stdout. If any test fails, the exit +code will be non-zero. Test names include a group prefix. If a (exact, case sensitive) group prefix, or a full test name is provided as the first argument, @@ -2199,75 +2740,98 @@ Node: add34941 Ref: #add35040 Node: balance37627 Ref: #balance37738 -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 +Node: Classic balance report39179 +Ref: #classic-balance-report39352 +Node: Customising the classic balance report40721 +Ref: #customising-the-classic-balance-report40949 +Node: Colour support43023 +Ref: #colour-support43190 +Node: Flat mode43363 +Ref: #flat-mode43511 +Node: Depth limited balance reports43924 +Ref: #depth-limited-balance-reports44124 +Node: Multicolumn balance report44580 +Ref: #multicolumn-balance-report44778 +Node: Budget report50018 +Ref: #budget-report50161 +Node: Nested budgets54845 +Ref: #nested-budgets54957 +Ref: #output-format-158437 +Node: balancesheet58515 +Ref: #balancesheet58651 +Node: balancesheetequity59885 +Ref: #balancesheetequity60034 +Node: cashflow60595 +Ref: #cashflow60723 +Node: check-dates61751 +Ref: #check-dates61878 +Node: check-dupes62157 +Ref: #check-dupes62281 +Node: close62574 +Ref: #close62682 +Node: files66095 +Ref: #files66196 +Node: help66343 +Ref: #help66443 +Node: import67536 +Ref: #import67650 +Node: incomestatement68394 +Ref: #incomestatement68528 +Node: prices69864 +Ref: #prices69979 +Node: print70258 +Ref: #print70368 +Node: print-unique74861 +Ref: #print-unique74987 +Node: register75272 +Ref: #register75399 +Node: Custom register output79292 +Ref: #custom-register-output79421 +Node: register-match80651 +Ref: #register-match80785 +Node: rewrite81136 +Ref: #rewrite81251 +Node: Re-write rules in a file83100 +Ref: #re-write-rules-in-a-file83234 +Node: Diff output format84444 +Ref: #diff-output-format84613 +Node: rewrite vs print --auto85705 +Ref: #rewrite-vs.-print---auto85884 +Node: roi86440 +Ref: #roi86538 +Node: stats87550 +Ref: #stats87649 +Node: tags88403 +Ref: #tags88501 +Node: test88731 +Ref: #test88815 +Node: ADD-ON COMMANDS89576 +Ref: #add-on-commands89686 +Node: Official add-ons90973 +Ref: #official-add-ons91113 +Node: api91200 +Ref: #api91289 +Node: ui91341 +Ref: #ui91440 +Node: web91498 +Ref: #web91587 +Node: Third party add-ons91633 +Ref: #third-party-add-ons91808 +Node: diff91943 +Ref: #diff92040 +Node: iadd92139 +Ref: #iadd92253 +Node: interest92336 +Ref: #interest92457 +Node: irr92552 +Ref: #irr92650 +Node: Experimental add-ons92781 +Ref: #experimental-add-ons92933 +Node: autosync93213 +Ref: #autosync93324 +Node: chart93563 +Ref: #chart93682 +Node: check93753 +Ref: #check93855  End Tag Table diff --git a/hledger/hledger.txt b/hledger/hledger.txt index 5ec96f10b..c959dad56 100644 --- a/hledger/hledger.txt +++ b/hledger/hledger.txt @@ -1014,53 +1014,477 @@ COMMANDS Date [2015/05/22]: $ balance + balance, bal, b + Show accounts and their balances. + + 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 + balancesheet, bs This command displays a simple balance sheet, showing historical ending - balances of asset and liability accounts (ignoring any report begin - date). It assumes that these accounts are under a top-level asset or - liability account (case insensitive, plural forms also allowed). Note - this report shows all account balances with normal positive sign (like - conventional financial statements, unlike balance/print/register) - (experimental). (bs) + balances of asset and liability accounts (ignoring any report begin + date). It assumes that these accounts are under a top-level asset or + liability account (case insensitive, plural forms also allowed). - --change - show balance change in each period, instead of historical ending - balances - - --cumulative - show balance change accumulated across periods (in multicolumn - reports), instead of historical ending balances - - -H --historical - show historical ending balance in each period (includes postings - before report start date) (default) - - --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 - - --sort-amount - sort by amount instead of account code/name + Note this report shows all account balances with normal positive sign + (like conventional financial statements, unlike balance/print/register) + (experimental). Example: @@ -1084,16 +1508,17 @@ COMMANDS 0 With a reporting interval, multiple columns will be shown, one for each - report period. As with multicolumn balance reports, you can alter the - report mode with --change/--cumulative/--historical. Normally bal- - ancesheet shows historical ending balances, which is what you need for + report period. As with multicolumn balance reports, you can alter the + report mode with --change/--cumulative/--historical. Normally bal- + ancesheet shows historical ending balances, which is what you need for a balance sheet; note this means it ignores report begin dates. - This command also supports output destination and output format selec- + This command also supports output destination and output format selec- tion. balancesheetequity - Just like balancesheet, but also reports Equity (which it assumes is + balancesheetequity, bse + Just like balancesheet, but also reports Equity (which it assumes is under a top-level equity account). Example: @@ -1123,50 +1548,13 @@ COMMANDS 0 cashflow - This command displays a simple cashflow statement, showing changes in - "cash" accounts. It assumes that these accounts are under a top-level - asset account (case insensitive, plural forms also allowed) and do not - contain receivable or A/R in their name. Note this report shows all + cashflow, cf + This command displays a simple cashflow statement, showing changes in + "cash" accounts. It assumes that these accounts are under a top-level + asset account (case insensitive, plural forms also allowed) and do not + contain receivable or A/R in their name. Note this report shows all account balances with normal positive sign (like conventional financial - statements, unlike balance/print/register) (experimental). (cf) - - --change - show balance change in each period (default) - - --cumulative - show balance change accumulated across periods (in multicolumn - reports), instead of changes during periods - - -H --historical - show historical ending balance in each period (includes postings - before report start date), instead of changes during each period - - --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 (in simple reports) - - --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 - - --sort-amount - sort by amount instead of account code/name + statements, unlike balance/print/register) (experimental). Example: @@ -1193,62 +1581,69 @@ COMMANDS tion. check-dates - Check that transactions are sorted by increasing date. With a query, - only matched transactions' dates are checked. + check-dates + Check that transactions are sorted by increasing date. With --date2, + checks secondary dates instead. With --strict, dates must also be + unique. With a query, only matched transactions' dates are checked. + Reads the default journal file, or another specified with -f. check-dupes - Report account names having the same leaf but different prefixes. An - example: http://stefanorodighiero.net/software/hledger-dupes.html + check-dupes + Reports account names having the same leaf but different prefixes. In + other words, two or more leaves that are categorized differently. + Reads the default journal file, or another specified as an argument. + + An example: http://stefanorodighiero.net/software/hledger-dupes.html close close, equity - Prints a "closing balances" transaction and an "opening balances" + Prints a "closing balances" transaction and an "opening balances" transaction that bring account balances to and from zero, respectively. Useful for bringing asset/liability balances forward into a new journal - file, or for closing out revenues/expenses to retained earnings at the + file, or for closing out revenues/expenses to retained earnings at the end of a period. - The closing transaction transfers balances to "equity:closing bal- - ances". The opening transaction transfers balances from "equity:open- - ing balances". You can chose to print just one of the transactions by + The closing transaction transfers balances to "equity:closing bal- + ances". The opening transaction transfers balances from "equity:open- + ing balances". You can chose to print just one of the transactions by using the --opening or --closing flag. If you split your journal files by time (eg yearly), you will typically - run this command at the end of the year, and save the closing transac- - tion as last entry of the old file, and the opening transaction as the - first entry of the new file. This makes the files self contained, so - that correct balances are reported no matter which of them are loaded. - Ie, if you load just one file, the balances are initialised correctly; - or if you load several files, the redundant closing/opening transac- - tions cancel each other out. (They will show up in print or register - reports; you can exclude them with a query like not:desc:'(open- + run this command at the end of the year, and save the closing transac- + tion as last entry of the old file, and the opening transaction as the + first entry of the new file. This makes the files self contained, so + that correct balances are reported no matter which of them are loaded. + Ie, if you load just one file, the balances are initialised correctly; + or if you load several files, the redundant closing/opening transac- + tions cancel each other out. (They will show up in print or register + reports; you can exclude them with a query like not:desc:'(open- ing|closing) balances'.) If you're running a business, you might also use this command to "close - the books" at the end of an accounting period, transferring income - statement account balances to retained earnings. (You may want to + the books" at the end of an accounting period, transferring income + statement account balances to retained earnings. (You may want to change the equity account name to something like "equity:retained earn- ings".) - By default, the closing transaction is dated yesterday, the balances - are calculated as of end of yesterday, and the opening transaction is - dated today. To close on some other date, use: hledger close -e OPEN- - INGDATE. Eg, to close/open on the 2018/2019 boundary, use -e 2019. + By default, the closing transaction is dated yesterday, the balances + are calculated as of end of yesterday, and the opening transaction is + dated today. To close on some other date, use: hledger close -e OPEN- + INGDATE. Eg, to close/open on the 2018/2019 boundary, use -e 2019. You can also use -p or date:PERIOD (any starting date is ignored). Both transactions will include balance assertions for the - closed/reopened accounts. You probably shouldn't use status or real- - ness filters (like -C or -R or status:) with this command, or the gen- + closed/reopened accounts. You probably shouldn't use status or real- + ness filters (like -C or -R or status:) with this command, or the gen- erated balance assertions will depend on these flags. Likewise, if you - run this command with --auto, the balance assertions will probably + run this command with --auto, the balance assertions will probably always require --auto. Examples: - Carrying asset/liability balances into a new file for 2019, all from + Carrying asset/liability balances into a new file for 2019, all from command line: - Warning: we use >> here to append; be careful not to type a single > + Warning: we use >> here to append; be careful not to type a single > which would wipe your journal! $ hledger close -f 2018.journal -e 2019 assets liabilities --opening >>2019.journal @@ -1280,21 +1675,25 @@ COMMANDS assets:checking files - List all files included in the journal. With a REGEX argument, only - file names matching the regular expression (case sensitive) are shown. + files + List all files included in the journal. With a REGEX argument, only + file names matching the regular expression (case sensitive) are shown. help + help Show any of the hledger manuals. - The help command displays any of the main hledger manuals, in one of - several ways. Run it with no argument to list the manuals, or provide + The help command displays any of the main hledger manuals, in one of + several ways. Run it with no argument to list the manuals, or provide a full or partial manual name to select one. - hledger manuals are available in several formats. hledger help will - use the first of these display methods that it finds: info, man, - $PAGER, less, stdout (or when non-interactive, just stdout). You can + hledger manuals are available in several formats. hledger help will + use the first of these display methods that it finds: info, man, + $PAGER, less, stdout (or when non-interactive, just stdout). You can force a particular viewer with the --info, --man, --pager, --cat flags. + Examples: + $ hledger help Please choose a manual by typing "hledger help MANUAL" (a substring is ok). Manuals: hledger hledger-ui hledger-web hledger-api journal csv timeclock timedot @@ -1316,11 +1715,10 @@ COMMANDS ... import - Read new transactions added to each FILE since last run, and add them - to the main journal file. - - --dry-run - just show the transactions to be imported + import + Read new transactions added to each FILE since last run, and add them + to the main journal file. Or with --dry-run, just print the transac- + tions that would be added. The input files are specified as arguments - no need to write -f before each one. So eg to add new transactions from all CSV files to the main @@ -1336,53 +1734,16 @@ COMMANDS $ hledger import --dry ... | hledger -f- print unknown --ignore-assertions incomestatement + incomestatement, is This command displays a simple income statement, showing revenues and expenses during a period. It assumes that these accounts are under a top-level revenue or income or expense account (case insensitive, plu- ral forms also allowed). Note this report shows all account balances with normal positive sign (like conventional financial statements, - unlike balance/print/register) (experimental). (is) + unlike balance/print/register) (experimental). - --change - show balance change in each period (default) - - --cumulative - show balance change accumulated across periods (in multicolumn - reports), instead of changes during periods - - -H --historical - show historical ending balance in each period (includes postings - before report start date), instead of changes during each period - - --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 - - --sort-amount - sort by amount instead of account code/name - - This command displays a simple income statement. It currently assumes - that you have top-level accounts named income (or revenue) and expense + This command displays a simple income statement. It currently assumes + that you have top-level accounts named income (or revenue) and expense (plural forms also allowed.) $ hledger incomestatement @@ -1407,39 +1768,32 @@ COMMANDS 0 With a reporting interval, multiple columns will be shown, one for each - report period. Normally incomestatement shows revenues/expenses per - period, though as with multicolumn balance reports you can alter the + report period. Normally incomestatement shows revenues/expenses per + period, though as with multicolumn balance reports you can alter the report mode with --change/--cumulative/--historical. - This command also supports output destination and output format selec- + This command also supports output destination and output format selec- tion. prices - Print market price directives from the journal. With --costs, also - print synthetic market prices based on transaction prices. With + prices + Print market price directives from the journal. With --costs, also + print synthetic market prices based on transaction prices. With --inverted-costs, also print inverse prices based on transaction - prices. Prices (and postings providing prices) can be filtered by a + prices. Prices (and postings providing prices) can be filtered by a query. print - Show transactions from the journal. Aliases: p, txns. + print, txns, p + Show transaction journal entries, sorted by date. - -m STR --match=STR - show the transaction whose description is most similar to STR, - and is most recent + The print command displays full journal entries (transactions) from the + journal file in date order, tidily formatted. With --date2, transac- + tions are sorted by secondary date instead. - --new show only newer-dated transactions added in each file since last - run - - -x --explicit - show all amounts explicitly - - -O FMT --output-format=FMT - select the output format. 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. + print's output is always a valid hledger journal. + It preserves all transaction information, but it does not preserve + directives or inter-transaction comments $ hledger print 2008/01/01 income @@ -1463,11 +1817,6 @@ COMMANDS liabilities:debts $1 assets:bank:checking $-1 - The print command displays full journal entries (transactions) from the - journal file in date order, tidily formatted. print's output is always - a valid hledger journal. It preserves all transaction information, but - it does not preserve directives or inter-transaction comments - Normally, the journal entry's explicit or implicit amount style is pre- served. Ie when an amount is omitted in the journal, it will be omit- ted in the output. You can use the -x/--explicit flag to make all @@ -1535,39 +1884,28 @@ COMMANDS greater amounts under debit.) print-unique + print-unique Print transactions which do not reuse an already-seen description. + Example: + + $ cat unique.journal + 1/1 test + (acct:one) 1 + 2/2 test + (acct:two) 2 + $ LEDGER_FILE=unique.journal hledger print-unique + (-f option not supported) + 2015/01/01 test + (acct:one) 1 + register - Show postings and their running total. Aliases: r, reg. + register, reg, r + Show postings and their running total. - --cumulative - show running total from report start date (default) - - -H --historical - show historical running total/balance (includes postings before - report start date) - - -A --average - show running average of posting amounts instead of total - (implies --empty) - - -r --related - show postings' siblings instead - - -w N --width=N - set output width (default: terminal width or COLUMNS. -wN,M - sets description width as well) - - -O FMT --output-format=FMT - select the output format. 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. - - The register command displays postings, one per line, and their running - total. This is typically used with a query selecting a particular - account, to see that account's activity: + The register command displays postings in date order, one per line, and + their running total. This is typically used with a query selecting a + particular account, to see that account's activity: $ hledger register checking 2008/01/01 income assets:bank:checking $1 $1 @@ -1575,6 +1913,8 @@ COMMANDS 2008/06/02 save assets:bank:checking $-1 $1 2008/12/31 pay off assets:bank:checking $-1 0 + With --date2, it shows and sorts by secondary date instead. + The --historical/-H flag adds the balance from any undisplayed prior postings to the running total. This is useful when you want to see only recent activity, with a historically accurate running balance: @@ -1659,23 +1999,170 @@ COMMANDS tion. register-match + register-match Print the one posting whose transaction description is closest to DESC, - in the style of the register command. Helps ledger-autosync detect - already-seen transactions when importing. + in the style of the register command. If there are multiple equally + good matches, it shows the most recent. Query options (options, not + arguments) can be used to restrict the search space. Helps + ledger-autosync detect already-seen transactions when importing. rewrite - Print all transactions, adding custom postings to the matched ones. + rewrite + Print all transactions, rewriting the postings of matched transactions. + For now the only rewrite available is adding new postings, like print + --auto. + + This is a start at a generic rewriter of transaction entries. It reads + the default journal and prints the transactions, like print, but adds + one or more specified postings to any transactions matching QUERY. The + posting amounts can be fixed, or a multiplier of the existing transac- + tion's first posting amount. + + Examples: + + hledger-rewrite.hs ^income --add-posting '(liabilities:tax) *.33 ; income tax' --add-posting '(reserve:gifts) $100' + hledger-rewrite.hs expenses:gifts --add-posting '(reserve:gifts) *-1"' + hledger-rewrite.hs -f rewrites.hledger + + rewrites.hledger may consist of entries like: + + = ^income amt:<0 date:2017 + (liabilities:tax) *0.33 ; tax on income + (reserve:grocery) *0.25 ; reserve 25% for grocery + (reserve:) *0.25 ; reserve 25% for grocery + + Note the single quotes to protect the dollar sign from bash, and the + two spaces between account and amount. + + More: + + $ hledger rewrite -- [QUERY] --add-posting "ACCT AMTEXPR" ... + $ hledger rewrite -- ^income --add-posting '(liabilities:tax) *.33' + $ hledger rewrite -- expenses:gifts --add-posting '(budget:gifts) *-1"' + $ hledger rewrite -- ^income --add-posting '(budget:foreign currency) *0.25 JPY; diversify' + + Argument for --add-posting option is a usual posting of transaction + with an exception for amount specification. More precisely, you can + use '*' (star symbol) before the amount to indicate that that this is a + factor for an amount of original matched posting. If the amount + includes a commodity name, the new posting amount will be in the new + commodity; otherwise, it will be in the matched posting amount's com- + modity. + + Re-write rules in a file + During the run this tool will execute so called "Automated Transac- + tions" found in any journal it process. I.e instead of specifying this + operations in command line you can put them in a journal file. + + $ rewrite-rules.journal + + Make contents look like this: + + = ^income + (liabilities:tax) *.33 + + = expenses:gifts + budget:gifts *-1 + assets:budget *1 + + Note that '=' (equality symbol) that is used instead of date in trans- + actions you usually write. It indicates the query by which you want to + match the posting to add new ones. + + $ hledger rewrite -- -f input.journal -f rewrite-rules.journal > rewritten-tidy-output.journal + + This is something similar to the commands pipeline: + + $ hledger rewrite -- -f input.journal '^income' --add-posting '(liabilities:tax) *.33' \ + | hledger rewrite -- -f - expenses:gifts --add-posting 'budget:gifts *-1' \ + --add-posting 'assets:budget *1' \ + > rewritten-tidy-output.journal + + It is important to understand that relative order of such entries in + journal is important. You can re-use result of previously added post- + ings. + + Diff output format + To use this tool for batch modification of your journal files you may + find useful output in form of unified diff. + + $ hledger rewrite -- --diff -f examples/sample.journal '^income' --add-posting '(liabilities:tax) *.33' + + Output might look like: + + --- /tmp/examples/sample.journal + +++ /tmp/examples/sample.journal + @@ -18,3 +18,4 @@ + 2008/01/01 income + - assets:bank:checking $1 + + assets:bank:checking $1 + income:salary + + (liabilities:tax) 0 + @@ -22,3 +23,4 @@ + 2008/06/01 gift + - assets:bank:checking $1 + + assets:bank:checking $1 + income:gifts + + (liabilities:tax) 0 + + If you'll pass this through patch tool you'll get transactions contain- + ing the posting that matches your query be updated. Note that multiple + files might be update according to list of input files specified via + --file options and include directives inside of these files. + + Be careful. Whole transaction being re-formatted in a style of output + from hledger print. + + See also: + + https://github.com/simonmichael/hledger/issues/99 + + rewrite vs. print --auto + This command predates print --auto, and currently does much the same + thing, but with these differences: + + o with multiple files, rewrite lets rules in any file affect all other + files. print --auto uses standard directive scoping; rules affect + only child files. + + o rewrite's query limits which transactions can be rewritten; all are + printed. print --auto's query limits which transactions are printed. + + o rewrite applies rules specified on command line or in the journal. + print --auto applies rules specified in the journal. roi - Shows time-weighted (TWR) and money-weighted (IRR) rate of return on - your investments. See roi --help for more. + roi + Shows the time-weighted (TWR) and money-weighted (IRR) rate of return + on your investments. + + This command assumes that you have account(s) that hold nothing but + your investments and whenever you record current appraisal/valuation of + these investments you offset unrealized profit and loss into account(s) + that, again, hold nothing but unrealized profit and loss. + + Any transactions affecting balance of investment account(s) and not + originating from unrealized profit and loss account(s) are assumed to + be your investments or withdrawals. + + At a minimum, you need to supply a query (which could be just an + account name) to select your investments with --inv, and another query + to identify your profit and loss transactions with --pnl. + + It will compute and display the internalized rate of return (IRR) and + time-weighted rate of return (TWR) for your investments for the time + period requested. Both rates of return are annualized before display, + regardless of the length of reporting interval. stats + stats Show some journal statistics. - -o FILE --output-file=FILE - write output to FILE. A file extension matching one of the - above formats selects that format. + The stats command displays summary information for the whole journal, + or a matched part of it. With a reporting interval, it shows a report + for each report period. + + Example: $ hledger stats Main journal file : /src/hledger/examples/sample.journal @@ -1689,24 +2176,23 @@ COMMANDS Accounts : 8 (depth 3) Commodities : 1 ($) - The stats command displays summary information for the whole journal, - or a matched part of it. With a reporting interval, it shows a report - for each report period. - - This command also supports output destination and output format selec- + This command also supports output destination and output format selec- tion. tags - List all the tag names used in the journal. With a TAGREGEX argument, - only tag names matching the regular expression (case insensitive) are - shown. With additional QUERY arguments, only transactions matching the - query are considered. + tags + List all the tag names used in the journal. With a TAGREGEX argument, + only tag names matching the regular expression (case insensitive) are + shown. With QUERY arguments, only transactions matching the query are + considered. test + test Run built-in unit tests. - Prints test names and their results on stdout. If any test fails or - gives an error, the exit code will be non-zero. + This command runs the unit tests built in to hledger-lib and hledger, + printing test names and results on stdout. If any test fails, the exit + code will be non-zero. Test names include a group prefix. If a (exact, case sensitive) group prefix, or a full test name is provided as the first argument, only