Debian Codegraph @

Hledger/Cli/Commands/Balance.txt

raw
1 balance
2
3 (bal)
4
5 A flexible, general purpose "summing" report that shows accounts with
6 some kind of numeric data. This can be balance changes per period, end
7 balances, budget performance, unrealised capital gains, etc.
8
9 Flags:
10 --sum calculation mode: show sum of posting amounts
11 (default)
12 --valuechange calculation mode: show total change of value of
13 period-end historical balances (caused by deposits,
14 withdrawals, market price fluctuations)
15 --gain calculation mode: show unrealised capital
16 gain/loss (historical balance value minus cost
17 basis)
18 --budget[=DESCPAT] calculation mode: show sum of posting amounts
19 together with budget goals defined by periodic
20 transactions. With a DESCPAT argument (must be
21 separated by = not space),
22 use only periodic transactions with matching
23 description
24 (case insensitive substring match).
25 --count calculation mode: show the count of postings
26 --change accumulation mode: accumulate amounts from column
27 start to column end (in multicolumn reports,
28 default)
29 --cumulative accumulation mode: accumulate amounts from report
30 start (specified by e.g. -b/--begin) to column end
31 -H --historical accumulation mode: accumulate amounts from
32 journal start to column end (includes postings
33 before report start date)
34 -l --flat list/tree mode: show accounts as a flat list
35 (default). Amounts exclude subaccount amounts,
36 except where the account is depth-clipped.
37 -t --tree list/tree mode: show accounts as a tree. Amounts
38 include subaccount amounts.
39 --drop=N in list mode, omit N leading account name parts
40 --declared include non-parent declared accounts (best used
41 with -E)
42 -A --average show a row average column (in multicolumn
43 reports)
44 -T --row-total show a row total column (in multicolumn reports)
45 --summary-only display only row summaries (e.g. row total,
46 average) (in multicolumn reports)
47 -N --no-total omit the final total row
48 --no-elide in tree mode, don't squash boring parent accounts
49 --format=FORMATSTR use this custom line format (in simple reports)
50 -S --sort-amount sort by amount instead of account code/name (in
51 flat mode). With multiple columns, sorts by the row
52 total, or by row average if that is displayed.
53 -% --percent express values in percentage of each column's
54 total
55 -r --related show the other accounts transacted with, instead
56 --invert display all amounts with reversed sign
57 --transpose switch rows and columns (use vertical time axis)
58 --layout=ARG how to lay out multi-commodity amounts and the
59 overall table:
60 'wide[,W]': commodities on same line, up to W wide
61 'tall' : commodities on separate lines
62 'bare' : commodity symbols in a separate column
63 'tidy' : each data field in its own column
64 --base-url=URLPREFIX in html output, generate links to hledger-web,
65 with this prefix. (Usually the base url shown by
66 hledger-web; can also be relative.)
67 -O --output-format=FMT select the output format. Supported formats:
68 txt, html, csv, tsv, json, fods.
69 -o --output-file=FILE write output to FILE. A file extension matching
70 one of the above formats selects that format.
71
72 balance is one of hledger's oldest and most versatile commands, for
73 listing account balances, balance changes, values, value changes and
74 more, during one time period or many. Generally it shows a table, with
75 rows representing accounts, and columns representing periods.
76
77 Note there are some variants of the balance command with convenient
78 defaults, which are simpler to use: balancesheet, balancesheetequity,
79 cashflow and incomestatement. When you need more control, then use
80 balance.
81
82 balance features
83
84 Here's a quick overview of the balance command's features, followed by
85 more detailed descriptions and examples. Many of these work with the
86 other balance-like commands as well (bs, cf, is..).
87
88 balance can show..
89
90 - accounts as a list (-l) or a tree (-t)
91 - optionally depth-limited (-[1-9])
92 - sorted by declaration order and name, or by amount
93
94 ..and their..
95
96 - balance changes (the default)
97 - or actual and planned balance changes (--budget)
98 - or value of balance changes (-V)
99 - or change of balance values (--valuechange)
100 - or unrealised capital gain/loss (--gain)
101 - or balance changes from sibling postings (--related/-r)
102 - or postings count (--count)
103
104 ..in..
105
106 - one time period (the whole journal period by default)
107 - or multiple periods (-D, -W, -M, -Q, -Y, -p INTERVAL)
108
109 ..either..
110
111 - per period (the default)
112 - or accumulated since report start date (--cumulative)
113 - or accumulated since account creation (--historical/-H)
114
115 ..possibly converted to..
116
117 - cost (--value=cost[,COMM]/--cost/-B)
118 - or market value, as of transaction dates (--value=then[,COMM])
119 - or at period ends (--value=end[,COMM])
120 - or now (--value=now)
121 - or at some other date (--value=YYYY-MM-DD)
122
123 ..with..
124
125 - totals (-T), averages (-A), percentages (-%), inverted sign (--invert)
126 - rows and columns swapped (--transpose)
127 - another field used as account name (--pivot)
128 - custom-formatted line items (single-period reports only) (--format)
129 - commodities displayed on the same line or multiple lines (--layout)
130
131 This command supports the output destination and output format options,
132 with output formats txt, csv, tsv (Added in 1.32), json, and
133 (multi-period reports only:) html, fods (Added in 1.40). In txt output
134 in a colour-supporting terminal, negative amounts are shown in red.
135
136 Simple balance report
137
138 With no arguments, balance shows a list of all accounts and their change
139 of balance - ie, the sum of posting amounts, both inflows and outflows -
140 during the entire period of the journal. ("Simple" here means just one
141 column of numbers, covering a single period. You can also have
142 multi-period reports, described later.)
143
144 For real-world accounts, these numbers will normally be their end
145 balance at the end of the journal period; more on this below.
146
147 Accounts are sorted by declaration order if any, and then alphabetically
148 by account name. For instance (using examples/sample.journal):
149
150 $ hledger -f examples/sample.journal bal
151 $1 assets:bank:saving
152 $-2 assets:cash
153 $1 expenses:food
154 $1 expenses:supplies
155 $-1 income:gifts
156 $-1 income:salary
157 $1 liabilities:debts
158 --------------------
159 0
160
161 Accounts with a zero balance (and no non-zero subaccounts, in tree
162 mode - see below) are hidden by default. Use -E/--empty to show them
163 (revealing assets:bank:checking here):
164
165 $ hledger -f examples/sample.journal bal -E
166 0 assets:bank:checking
167 $1 assets:bank:saving
168 $-2 assets:cash
169 $1 expenses:food
170 $1 expenses:supplies
171 $-1 income:gifts
172 $-1 income:salary
173 $1 liabilities:debts
174 --------------------
175 0
176
177 The total of the amounts displayed is shown as the last line, unless
178 -N/--no-total is used.
179
180 Balance report line format
181
182 For single-period balance reports displayed in the terminal (only), you
183 can use --format FMT to customise the format and content of each line.
184 Eg:
185
186 $ hledger -f examples/sample.journal balance --format "%20(account) %12(total)"
187 assets $-1
188 bank:saving $1
189 cash $-2
190 expenses $2
191 food $1
192 supplies $1
193 income $-2
194 gifts $-1
195 salary $-1
196 liabilities:debts $1
197 ---------------------------------
198 0
199
200 The FMT format string specifies the formatting applied to each
201 account/balance pair. It may contain any suitable text, with data fields
202 interpolated like so:
203
204 %[MIN][.MAX](FIELDNAME)
205
206 - MIN pads with spaces to at least this width (optional)
207
208 - MAX truncates at this width (optional)
209
210 - FIELDNAME must be enclosed in parentheses, and can be one of:
211
212 - depth_spacer - a number of spaces equal to the account's depth, or
213 if MIN is specified, MIN * depth spaces.
214 - account - the account's name
215 - total - the account's balance/posted total, right justified
216
217 Also, FMT can begin with an optional prefix to control how
218 multi-commodity amounts are rendered:
219
220 - %_ - render on multiple lines, bottom-aligned (the default)
221 - %^ - render on multiple lines, top-aligned
222 - %, - render on one line, comma-separated
223
224 There are some quirks. Eg in one-line mode, %(depth_spacer) has no
225 effect, instead %(account) has indentation built in. Experimentation may
226 be needed to get pleasing results.
227
228 Some example formats:
229
230 - %(total) - the account's total
231 - %-20.20(account) - the account's name, left justified, padded to 20
232 characters and clipped at 20 characters
233 - %,%-50(account) %25(total) - account name padded to 50 characters,
234 total padded to 20 characters, with multiple commodities rendered on
235 one line
236 - %20(total) %2(depth_spacer)%-(account) - the default format for the
237 single-column balance report
238
239 Filtered balance report
240
241 You can show fewer accounts, a different time period, totals from
242 cleared transactions only, etc. by using query arguments or options to
243 limit the postings being matched. Eg:
244
245 $ hledger -f examples/sample.journal bal --cleared assets date:200806
246 $-2 assets:cash
247 --------------------
248 $-2
249
250 List or tree mode
251
252 By default, or with -l/--flat, accounts are shown as a flat list with
253 their full names visible, as in the examples above.
254
255 With -t/--tree, the account hierarchy is shown, with subaccounts' "leaf"
256 names indented below their parent:
257
258 $ hledger -f examples/sample.journal balance
259 $-1 assets
260 $1 bank:saving
261 $-2 cash
262 $2 expenses
263 $1 food
264 $1 supplies
265 $-2 income
266 $-1 gifts
267 $-1 salary
268 $1 liabilities:debts
269 --------------------
270 0
271
272 Notes:
273
274 - "Boring" accounts are combined with their subaccount for more compact
275 output, unless --no-elide is used. Boring accounts have no balance of
276 their own and just one subaccount (eg assets:bank and liabilities
277 above).
278
279 - All balances shown are "inclusive", ie including the balances from all
280 subaccounts. Note this means some repetition in the output, which
281 requires explanation when sharing reports with
282 non-plaintextaccounting-users. A tree mode report's final total is the
283 sum of the top-level balances shown, not of all the balances shown.
284
285 - Each group of sibling accounts (ie, under a common parent) is sorted
286 separately.
287
288 Depth limiting
289
290 With a depth:NUM query, or --depth NUM option, or just -NUM (eg: -3)
291 balance reports will show accounts only to the specified depth, hiding
292 the deeper subaccounts. This can be useful for getting an overview
293 without too much detail.
294
295 Account balances at the depth limit always include the balances from any
296 deeper subaccounts (even in list mode). Eg, limiting to depth 1:
297
298 $ hledger -f examples/sample.journal balance -1
299 $-1 assets
300 $2 expenses
301 $-2 income
302 $1 liabilities
303 --------------------
304 0
305
306 Dropping top-level accounts
307
308 You can also hide one or more top-level account name parts, using
309 --drop NUM. This can be useful for hiding repetitive top-level account
310 names:
311
312 $ hledger -f examples/sample.journal bal expenses --drop 1
313 $1 food
314 $1 supplies
315 --------------------
316 $2
317
318 Showing declared accounts
319
320 With --declared, accounts which have been declared with an account
321 directive will be included in the balance report, even if they have no
322 transactions. (Since they will have a zero balance, you will also need
323 -E/--empty to see them.)
324
325 More precisely, leaf declared accounts (with no subaccounts) will be
326 included, since those are usually the more useful in reports.
327
328 The idea of this is to be able to see a useful "complete" balance
329 report, even when you don't have transactions in all of your declared
330 accounts yet.
331
332 Sorting by amount
333
334 With -S/--sort-amount, accounts with the largest (most positive)
335 balances are shown first. Eg: hledger bal expenses -MAS shows your
336 biggest averaged monthly expenses first. When more than one commodity is
337 present, they will be sorted by the alphabetically earliest commodity
338 first, and then by subsequent commodities (if an amount is missing a
339 commodity, it is treated as 0).
340
341 Revenues and liability balances are typically negative, however, so -S
342 shows these in reverse order. To work around this, you can add --invert
343 to flip the signs. Or you could use one of the higher-level balance
344 reports (bs, is..), which flip the sign automatically (eg:
345 hledger is -MAS).
346
347 Percentages
348
349 With -%/--percent, balance reports show each account's value expressed
350 as a percentage of the (column) total.
351
352 Note it is not useful to calculate percentages if the amounts in a
353 column have mixed signs. In this case, make a separate report for each
354 sign, eg:
355
356 $ hledger bal -% amt:`>0`
357 $ hledger bal -% amt:`<0`
358
359 Similarly, if the amounts in a column have mixed commodities, convert
360 them to one commodity with -B, -V, -X or --value, or make a separate
361 report for each commodity:
362
363 $ hledger bal -% cur:\\$
364 $ hledger bal -% cur:€
365
366 Multi-period balance report
367
368 With a report interval (set by the -D/--daily, -W/--weekly,
369 -M/--monthly, -Q/--quarterly, -Y/--yearly, or -p/--period flag), balance
370 shows a tabular report, with columns representing successive time
371 periods (and a title):
372
373 $ hledger -f examples/sample.journal bal --quarterly income expenses -E
374 Balance changes in 2008:
375
376 || 2008q1 2008q2 2008q3 2008q4
377 ===================++=================================
378 expenses:food || 0 $1 0 0
379 expenses:supplies || 0 $1 0 0
380 income:gifts || 0 $-1 0 0
381 income:salary || $-1 0 0 0
382 -------------------++---------------------------------
383 || $-1 $1 0 0
384
385 Notes:
386
387 - The report's start/end dates will be expanded, if necessary, to fully
388 encompass the displayed subperiods (so that the first and last
389 subperiods have the same duration as the others).
390 - Leading and trailing periods (columns) containing all zeroes are not
391 shown, unless -E/--empty is used.
392 - Accounts (rows) containing all zeroes are not shown, unless -E/--empty
393 is used.
394 - Amounts with many commodities are shown in abbreviated form, unless
395 --no-elide is used.
396 - Average and/or total columns can be added with the -A/--average and
397 -T/--row-total flags.
398 - The --transpose flag can be used to exchange rows and columns.
399 - The --pivot FIELD option causes a different transaction field to be
400 used as "account name". See PIVOTING.
401 - The --summary-only flag (--summary also works) hides all but the Total
402 and Average columns (those should be enabled with --row-total and
403 -A/--average).
404
405 Multi-period reports with many periods can be too wide for easy viewing
406 in the terminal. Here are some ways to handle that:
407
408 - Hide the totals row with -N/--no-total
409 - Filter to a single currency with cur:
410 - Convert to a single currency with -V [--infer-market-price]
411 - Use a more compact layout like --layout=bare
412 - Maximize the terminal window
413 - Reduce the terminal's font size
414 - View with a pager like less, eg: hledger bal -D --color=yes | less -RS
415 - Output as CSV and use a CSV viewer like visidata
416 (hledger bal -D -O csv | vd -f csv), Emacs' csv-mode
417 (M-x csv-mode, C-c C-a), or a spreadsheet
418 (hledger bal -D -o a.csv && open a.csv)
419 - Output as HTML and view with a browser:
420 hledger bal -D -o a.html && open a.html
421
422 Balance change, end balance
423
424 It's important to be clear on the meaning of the numbers shown in
425 balance reports. Here is some terminology we use:
426
427 A balance change is the net amount added to, or removed from, an account
428 during some period.
429
430 An end balance is the amount accumulated in an account as of some date
431 (and some time, but hledger doesn't store that; assume end of day in
432 your timezone). It is the sum of previous balance changes.
433
434 We call it a historical end balance if it includes all balance changes
435 since the account was created. For a real world account, this means it
436 will match the "historical record", eg the balances reported in your
437 bank statements or bank web UI. (If they are correct!)
438
439 In general, balance changes are what you want to see when reviewing
440 revenues and expenses, and historical end balances are what you want to
441 see when reviewing or reconciling asset, liability and equity accounts.
442
443 balance shows balance changes by default. To see accurate historical end
444 balances:
445
446 1. Initialise account starting balances with an "opening balances"
447 transaction (a transfer from equity to the account), unless the
448 journal covers the account's full lifetime.
449
450 2. Include all of of the account's prior postings in the report, by not
451 specifying a report start date, or by using the -H/--historical
452 flag. (-H causes report start date to be ignored when summing
453 postings.)
454
455 Balance report modes
456
457 The balance command is quite flexible; here is the full detail on how to
458 control what it reports. If the following seems complicated, don't
459 worry - this is for advanced reporting, and it does take time and
460 experimentation to get familiar with all the report modes.
461
462 There are three important option groups:
463
464 hledger balance [CALCULATIONMODE] [ACCUMULATIONMODE] [VALUATIONMODE] ...
465
466 Calculation mode
467
468 The basic calculation to perform for each table cell. It is one of:
469
470 - --sum : sum the posting amounts (default)
471 - --budget : sum the amounts, but also show the budget goal amount (for
472 each account/period)
473 - --valuechange : show the change in period-end historical balance
474 values (caused by deposits, withdrawals, and/or market price
475 fluctuations)
476 - --gain : show the unrealised capital gain/loss, (the current valued
477 balance minus each amount's original cost)
478 - --count : show the count of postings
479
480 Accumulation mode
481
482 How amounts should accumulate across a report's subperiods/columns.
483 Another way to say it: which time period's postings should contribute to
484 each cell's calculation. It is one of:
485
486 - --change : calculate with postings from column start to column end, ie
487 "just this column". Typically used to see revenues/expenses. (default
488 for balance, cashflow, incomestatement)
489
490 - --cumulative : calculate with postings from report start to column
491 end, ie "previous columns plus this column". Typically used to show
492 changes accumulated since the report's start date. Not often used.
493
494 - --historical/-H : calculate with postings from journal start to column
495 end, ie "all postings from before report start date until this
496 column's end". Typically used to see historical end balances of
497 assets/liabilities/equity. (default for balancesheet,
498 balancesheetequity)
499
500 Valuation mode
501
502 Which kind of value or cost conversion should be applied, if any, before
503 displaying the report. See Cost reporting and Value reporting for more
504 about conversions.
505
506 A valuation (or cost) mode can be selected with the --value option:
507
508 - no conversion : don't convert to cost or value (default)
509 - --value=cost[,COMM] : convert amounts to cost (then optionally to some
510 other commodity)
511 - --value=then[,COMM] : convert amounts to market value on transaction
512 dates
513 - --value=end[,COMM] : convert amounts to market value on period end
514 date(s)
515 (default with --valuechange, --gain)
516 - --value=now[,COMM] : convert amounts to market value on today's date
517 - --value=YYYY-MM-DD[,COMM] : convert amounts to market value on another
518 date
519
520 or with the legacy -B/-V/-X options, which are equivalent and easier to
521 type:
522
523 - -B/--cost : like --value=cost
524 - -V/--market : like --value=end
525 - -X COMM/--exchange COMM : like --value=end,COMM
526
527 Note that --value can also convert to cost, as a convenience; but
528 actually --cost and --value are independent options, and could be used
529 together.
530
531 Combining balance report modes
532
533 Most combinations of these modes should produce reasonable reports, but
534 if you find any that seem wrong or misleading, let us know. The
535 following restrictions are applied:
536
537 - --valuechange implies --value=end
538 - --valuechange makes --change the default when used with the
539 balancesheet/balancesheetequity commands
540 - --cumulative or --historical disables --row-total/-T
541
542 For reference, here is what the combinations of accumulation and
543 valuation show:
544
545 ------------------------------------------------------------------------------------------------
546 Valuation:> no valuation --value= then --value= end --value= YYYY-MM-DD /now
547 Accumulation:v
548 ------------------ ---------------- ----------------- --------------- --------------------------
549 --change change in period sum of period-end DATE-value of change in
550 posting-date value of change period
551 market values in in period
552 period
553
554 --cumulative change from sum of period-end DATE-value of change from
555 report start to posting-date value of change report start to period end
556 period end market values from report
557 from report start start to period
558 to period end end
559
560 --historical /-H change from sum of period-end DATE-value of change from
561 journal start to posting-date value of change journal start to period
562 period end market values from journal end
563 (historical end from journal start to period
564 balance) start to period end
565 end
566 ------------------------------------------------------------------------------------------------
567
568 Budget report
569
570 The --budget report is like a regular balance report, but with two main
571 differences:
572
573 - Budget goals and performance percentages are also shown, in brackets
574 - Accounts which don't have budget goals are hidden by default.
575
576 This is useful for comparing planned and actual income, expenses, time
577 usage, etc.
578
579 Periodic transaction rules are used to define budget goals. For example,
580 here's a periodic rule defining monthly goals for bus travel and food
581 expenses:
582
583 ;; Budget
584 ~ monthly
585 (expenses:bus) $30
586 (expenses:food) $400
587
588 After recording some actual expenses,
589
590 ;; Two months worth of expenses
591 2017-11-01
592 income $-1950
593 expenses:bus $35
594 expenses:food:groceries $310
595 expenses:food:dining $42
596 expenses:movies $38
597 assets:bank:checking
598
599 2017-12-01
600 income $-2100
601 expenses:bus $53
602 expenses:food:groceries $380
603 expenses:food:dining $32
604 expenses:gifts $100
605 assets:bank:checking
606
607 we can see a budget report like this:
608
609 $ hledger bal -M --budget
610 Budget performance in 2017-11-01..2017-12-31:
611
612 || Nov Dec
613 ===============++============================================
614 <unbudgeted> || $-425 $-565
615 expenses || $425 [ 99% of $430] $565 [131% of $430]
616 expenses:bus || $35 [117% of $30] $53 [177% of $30]
617 expenses:food || $352 [ 88% of $400] $412 [103% of $400]
618 ---------------++--------------------------------------------
619 || 0 [ 0% of $430] 0 [ 0% of $430]
620
621 This is "goal-based budgeting"; you define goals for accounts and
622 periods, often recurring, and hledger shows performance relative to the
623 goals. This contrasts with "envelope budgeting", which is more detailed
624 and strict - useful when cash is tight, but also quite a bit more work.
625 https://plaintextaccounting.org/Budgeting has more on this topic.
626
627 Using the budget report
628
629 Historically this report has been confusing and fragile. hledger's
630 version should be relatively robust and intuitive, but you may still
631 find surprises. Here are more notes to help with learning and
632 troubleshooting.
633
634 - In the above example, expenses:bus and expenses:food are shown because
635 they have budget goals during the report period.
636
637 - Their parent expenses is also shown, with budget goals aggregated from
638 the children.
639
640 - The subaccounts expenses:food:groceries and expenses:food:dining are
641 not shown since they have no budget goal of their own, but they
642 contribute to expenses:food's actual amount.
643
644 - Unbudgeted accounts expenses:movies and expenses:gifts are also not
645 shown, but they contribute to expenses's actual amount.
646
647 - The other unbudgeted accounts income and assets:bank:checking are
648 grouped as <unbudgeted>.
649
650 - --depth or depth: can be used to limit report depth in the usual way
651 (but will not reveal unbudgeted subaccounts).
652
653 - Amounts are always inclusive of subaccounts (even in -l/--list mode).
654
655 - Numbers displayed in a --budget report will not always agree with the
656 totals, because of hidden unbudgeted accounts; this is normal.
657 -E/--empty can be used to reveal the hidden accounts.
658
659 - In the periodic rules used for setting budget goals, unbalanced
660 postings are convenient.
661
662 - You can filter budget reports with the usual queries, eg to focus on
663 particular accounts. It's common to restrict them to just expenses.
664 (The <unbudgeted> account is occasionally hard to exclude; this is
665 because of date surprises, discussed below.)
666
667 - When you have multiple currencies, you may want to convert them to one
668 (-X COMM --infer-market-prices) and/or show just one at a time
669 (cur:COMM). If you do need to show multiple currencies at once,
670 --layout bare can be helpful.
671
672 - You can "roll over" amounts (actual and budgeted) to the next period
673 with --cumulative.
674
675 See also: https://hledger.org/budgeting.html.
676
677 Budget date surprises
678
679 With small data, or when starting out, some of the generated budget goal
680 transaction dates might fall outside the report periods. Eg with the
681 following journal and report, the first period appears to have no
682 expenses:food budget. (Also the <unbudgeted> account should be excluded
683 by the expenses query, but isn't.):
684
685 ~ monthly in 2020
686 (expenses:food) $500
687
688 2020-01-15
689 expenses:food $400
690 assets:checking
691
692 $ hledger bal --budget expenses
693 Budget performance in 2020-01-15:
694
695 || 2020-01-15
696 ===============++====================
697 <unbudgeted> || $400
698 expenses:food || 0 [ 0% of $500]
699 ---------------++--------------------
700 || $400 [80% of $500]
701
702 In this case, the budget goal transactions are generated on first days
703 of of month (this can be seen with
704 hledger print --forecast tag:generated expenses). Whereas the report
705 period defaults to just the 15th day of january (this can be seen from
706 the report table's column headings).
707
708 To fix this kind of thing, be more explicit about the report period
709 (and/or the periodic rules' dates). In this case, adding -b 2020 does
710 the trick.
711
712 Selecting budget goals
713
714 By default, the budget report uses all available periodic transaction
715 rules to generate goals. This includes rules with a different report
716 interval from your report. Eg if you have daily, weekly and monthly
717 periodic rules, all of these will contribute to the goals in a monthly
718 budget report.
719
720 You can select a subset of periodic rules by providing an argument to
721 the --budget flag. --budget=DESCPAT will match all periodic rules whose
722 description contains DESCPAT, a case-insensitive substring (not a
723 regular expression or query). This means you can give your periodic
724 rules descriptions (remember that two spaces are needed between period
725 expression and description), and then select from multiple budgets
726 defined in your journal.
727
728 Budgeting vs forecasting
729
730 --forecast and --budget both use the periodic transaction rules in the
731 journal to generate temporary transactions for reporting purposes.
732 However they are separate features - though you can use both at the same
733 time if you want. Here are some differences between them:
734
735 -----------------------------------------------------------------------
736 --forecast --budget
737 -------------------------------------- --------------------------------
738 is a general option; it enables is a balance command option; it
739 forecasting with all reports selects the balance report's
740 budget mode
741
742 generates visible transactions which generates invisible transactions
743 appear in reports which produce goal amounts
744
745 generates forecast transactions from generates budget goal
746 after the last regular transaction, to transactions throughout the
747 the end of the report period; or with report period, optionally
748 an argument --forecast=PERIODEXPR restricted by periods specified
749 generates them throughout the in the periodic transaction
750 specified period, both optionally rules
751 restricted by periods specified in the
752 periodic transaction rules
753
754 uses all periodic rules uses all periodic rules; or with
755 an argument --budget=DESCPAT
756 uses just the rules matched by
757 DESCPAT
758 -----------------------------------------------------------------------
759
760 Balance report layout
761
762 The --layout option affects how balance and the other balance-like
763 commands show multi-commodity amounts and commodity symbols. It can
764 improve readability, for humans and/or machines (other software). It has
765 four possible values:
766
767 - --layout=wide[,WIDTH]: commodities are shown on a single line,
768 optionally elided to WIDTH
769 - --layout=tall: each commodity is shown on a separate line
770 - --layout=bare: commodity symbols are in their own column, amounts are
771 bare numbers
772 - --layout=tidy: data is normalised to easily-consumed "tidy" form, with
773 one row per data value. (This one is currently supported only by the
774 balance command.)
775
776 Here are the --layout modes supported by each output format Only CSV
777 output supports all of them:
778
779 - txt csv html json sql
780 ------ ----- ----- ------ ------ -----
781 wide Y Y Y
782 tall Y Y Y
783 bare Y Y Y
784 tidy Y
785
786 Examples:
787
788 Wide layout
789
790 With many commodities, reports can be very wide:
791
792 $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=wide
793 Balance changes in 2012-01-01..2014-12-31:
794
795 || 2012 2013 2014 Total
796 ==================++====================================================================================================================================================================================================================
797 Assets:US:ETrade || 10.00 ITOT, 337.18 USD, 12.00 VEA, 106.00 VHT 70.00 GLD, 18.00 ITOT, -98.12 USD, 10.00 VEA, 18.00 VHT -11.00 ITOT, 4881.44 USD, 14.00 VEA, 170.00 VHT 70.00 GLD, 17.00 ITOT, 5120.50 USD, 36.00 VEA, 294.00 VHT
798 ------------------++--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
799 || 10.00 ITOT, 337.18 USD, 12.00 VEA, 106.00 VHT 70.00 GLD, 18.00 ITOT, -98.12 USD, 10.00 VEA, 18.00 VHT -11.00 ITOT, 4881.44 USD, 14.00 VEA, 170.00 VHT 70.00 GLD, 17.00 ITOT, 5120.50 USD, 36.00 VEA, 294.00 VHT
800
801 A width limit reduces the width, but some commodities will be hidden:
802
803 $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=wide,32
804 Balance changes in 2012-01-01..2014-12-31:
805
806 || 2012 2013 2014 Total
807 ==================++===========================================================================================================================
808 Assets:US:ETrade || 10.00 ITOT, 337.18 USD, 2 more.. 70.00 GLD, 18.00 ITOT, 3 more.. -11.00 ITOT, 3 more.. 70.00 GLD, 17.00 ITOT, 3 more..
809 ------------------++---------------------------------------------------------------------------------------------------------------------------
810 || 10.00 ITOT, 337.18 USD, 2 more.. 70.00 GLD, 18.00 ITOT, 3 more.. -11.00 ITOT, 3 more.. 70.00 GLD, 17.00 ITOT, 3 more..
811
812 Tall layout
813
814 Each commodity gets a new line (may be different in each column), and
815 account names are repeated:
816
817 $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=tall
818 Balance changes in 2012-01-01..2014-12-31:
819
820 || 2012 2013 2014 Total
821 ==================++==================================================
822 Assets:US:ETrade || 10.00 ITOT 70.00 GLD -11.00 ITOT 70.00 GLD
823 Assets:US:ETrade || 337.18 USD 18.00 ITOT 4881.44 USD 17.00 ITOT
824 Assets:US:ETrade || 12.00 VEA -98.12 USD 14.00 VEA 5120.50 USD
825 Assets:US:ETrade || 106.00 VHT 10.00 VEA 170.00 VHT 36.00 VEA
826 Assets:US:ETrade || 18.00 VHT 294.00 VHT
827 ------------------++--------------------------------------------------
828 || 10.00 ITOT 70.00 GLD -11.00 ITOT 70.00 GLD
829 || 337.18 USD 18.00 ITOT 4881.44 USD 17.00 ITOT
830 || 12.00 VEA -98.12 USD 14.00 VEA 5120.50 USD
831 || 106.00 VHT 10.00 VEA 170.00 VHT 36.00 VEA
832 || 18.00 VHT 294.00 VHT
833
834 Bare layout
835
836 Commodity symbols are kept in one column, each commodity has its own
837 row, amounts are bare numbers, account names are repeated:
838
839 $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=bare
840 Balance changes in 2012-01-01..2014-12-31:
841
842 || Commodity 2012 2013 2014 Total
843 ==================++=============================================
844 Assets:US:ETrade || GLD 0 70.00 0 70.00
845 Assets:US:ETrade || ITOT 10.00 18.00 -11.00 17.00
846 Assets:US:ETrade || USD 337.18 -98.12 4881.44 5120.50
847 Assets:US:ETrade || VEA 12.00 10.00 14.00 36.00
848 Assets:US:ETrade || VHT 106.00 18.00 170.00 294.00
849 ------------------++---------------------------------------------
850 || GLD 0 70.00 0 70.00
851 || ITOT 10.00 18.00 -11.00 17.00
852 || USD 337.18 -98.12 4881.44 5120.50
853 || VEA 12.00 10.00 14.00 36.00
854 || VHT 106.00 18.00 170.00 294.00
855
856 Bare layout also affects CSV output, which is useful for producing data
857 that is easier to consume, eg for making charts:
858
859 $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -O csv --layout=bare
860 "account","commodity","balance"
861 "Assets:US:ETrade","GLD","70.00"
862 "Assets:US:ETrade","ITOT","17.00"
863 "Assets:US:ETrade","USD","5120.50"
864 "Assets:US:ETrade","VEA","36.00"
865 "Assets:US:ETrade","VHT","294.00"
866 "Total:","GLD","70.00"
867 "Total:","ITOT","17.00"
868 "Total:","USD","5120.50"
869 "Total:","VEA","36.00"
870 "Total:","VHT","294.00"
871
872 Bare layout will sometimes display an extra row for the no-symbol
873 commodity, because of zero amounts (hledger treats zeroes as
874 commodity-less, usually). This can break hledger-bar confusingly
875 (workaround: add a cur: query to exclude the no-symbol row).
876
877 Tidy layout
878
879 This produces normalised "tidy data" (see
880 https://cran.r-project.org/web/packages/tidyr/vignettes/tidy-data.html)
881 where every variable has its own column and each row represents a single
882 data point. This is the easiest kind of data for other software to
883 consume:
884
885 $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -Y -O csv --layout=tidy
886 "account","period","start_date","end_date","commodity","value"
887 "Assets:US:ETrade","2012","2012-01-01","2012-12-31","GLD","0"
888 "Assets:US:ETrade","2012","2012-01-01","2012-12-31","ITOT","10.00"
889 "Assets:US:ETrade","2012","2012-01-01","2012-12-31","USD","337.18"
890 "Assets:US:ETrade","2012","2012-01-01","2012-12-31","VEA","12.00"
891 "Assets:US:ETrade","2012","2012-01-01","2012-12-31","VHT","106.00"
892 "Assets:US:ETrade","2013","2013-01-01","2013-12-31","GLD","70.00"
893 "Assets:US:ETrade","2013","2013-01-01","2013-12-31","ITOT","18.00"
894 "Assets:US:ETrade","2013","2013-01-01","2013-12-31","USD","-98.12"
895 "Assets:US:ETrade","2013","2013-01-01","2013-12-31","VEA","10.00"
896 "Assets:US:ETrade","2013","2013-01-01","2013-12-31","VHT","18.00"
897 "Assets:US:ETrade","2014","2014-01-01","2014-12-31","GLD","0"
898 "Assets:US:ETrade","2014","2014-01-01","2014-12-31","ITOT","-11.00"
899 "Assets:US:ETrade","2014","2014-01-01","2014-12-31","USD","4881.44"
900 "Assets:US:ETrade","2014","2014-01-01","2014-12-31","VEA","14.00"
901 "Assets:US:ETrade","2014","2014-01-01","2014-12-31","VHT","170.00"
902
903 Balance report output
904
905 As noted in Output format, if you choose HTML output (by using -O html
906 or -o somefile.html), you can create a hledger.css file in the same
907 directory to customise the report's appearance.
908
909 The HTML and FODS output formats can generate hyperlinks to a
910 hledger-web register view for each account and period. E.g. if your
911 hledger-web server is reachable at http://localhost:5000 then you might
912 run the balance command with the extra option
913 --base-url=http://localhost:5000. You can also produce relative links,
914 like --base-url="some/path" or --base-url="".)
915
916 Some useful balance reports
917
918 Some frequently used balance options/reports are:
919
920 - bal -M revenues expenses
921 Show revenues/expenses in each month. Also available as the
922 incomestatement command.
923
924 - bal -M -H assets liabilities
925 Show historical asset/liability balances at each month end. Also
926 available as the balancesheet command.
927
928 - bal -M -H assets liabilities equity
929 Show historical asset/liability/equity balances at each month end.
930 Also available as the balancesheetequity command.
931
932 - bal -M assets not:receivable
933 Show changes to liquid assets in each month. Also available as the
934 cashflow command.
935
936 Also:
937
938 - bal -M expenses -2 -SA
939 Show monthly expenses summarised to depth 2 and sorted by average
940 amount.
941
942 - bal -M --budget expenses
943 Show monthly expenses and budget goals.
944
945 - bal -M --valuechange investments
946 Show monthly change in market value of investment assets.
947
948 - bal investments --valuechange -D date:lastweek amt:'>1000' -STA [--invert]
949 Show top gainers [or losers] last week