| 1 |
register |
| 2 |
|
| 3 |
(reg) |
| 4 |
|
| 5 |
Show postings and their running total. |
| 6 |
|
| 7 |
Flags: |
| 8 |
--cumulative accumulation mode: show running total from report |
| 9 |
start date (default) |
| 10 |
-H --historical accumulation mode: show historical running |
| 11 |
total/balance (includes postings before report |
| 12 |
start date) |
| 13 |
-A --average show running average of posting amounts instead |
| 14 |
of total (implies --empty) |
| 15 |
-m --match=DESC fuzzy search for one recent posting with |
| 16 |
description closest to DESC |
| 17 |
-r --related show postings' siblings instead |
| 18 |
--invert display all amounts with reversed sign |
| 19 |
--drop=N omit N leading account name parts |
| 20 |
--sort=FIELDS sort by: date, desc, account, amount, absamount, |
| 21 |
or a comma-separated combination of these. For a |
| 22 |
descending sort, prefix with -. (Default: date) |
| 23 |
-w --width=N set output width (default: terminal width). -wN,M |
| 24 |
sets description width as well. |
| 25 |
--align-all guarantee alignment across all lines (slower) |
| 26 |
--base-url=URLPREFIX in html output, generate links to hledger-web, |
| 27 |
with this prefix. (Usually the base url shown by |
| 28 |
hledger-web; can also be relative.) |
| 29 |
-O --output-format=FMT select the output format. Supported formats: |
| 30 |
txt, csv, tsv, html, fods, json. |
| 31 |
-o --output-file=FILE write output to FILE. A file extension matching |
| 32 |
one of the above formats selects that format. |
| 33 |
|
| 34 |
The register command displays matched postings, across all accounts, in |
| 35 |
date order, with their running total or running historical balance. (See |
| 36 |
also the aregister command, which shows matched transactions in a |
| 37 |
specific account.) |
| 38 |
|
| 39 |
register normally shows line per posting, but note that multi-commodity |
| 40 |
amounts will occupy multiple lines (one line per commodity). |
| 41 |
|
| 42 |
It is typically used with a query selecting a particular account, to see |
| 43 |
that account's activity: |
| 44 |
|
| 45 |
$ hledger register checking |
| 46 |
2008/01/01 income assets:bank:checking $1 $1 |
| 47 |
2008/06/01 gift assets:bank:checking $1 $2 |
| 48 |
2008/06/02 save assets:bank:checking $-1 $1 |
| 49 |
2008/12/31 pay off assets:bank:checking $-1 0 |
| 50 |
|
| 51 |
With --date2, it shows and sorts by secondary date instead. |
| 52 |
|
| 53 |
For performance reasons, column widths are chosen based on the first |
| 54 |
1000 lines; this means unusually wide values in later lines can cause |
| 55 |
visual discontinuities as column widths are adjusted. If you want to |
| 56 |
ensure perfect alignment, at the cost of more time and memory, use the |
| 57 |
--align-all flag. |
| 58 |
|
| 59 |
The --historical/-H flag adds the balance from any undisplayed prior |
| 60 |
postings to the running total. This is useful when you want to see only |
| 61 |
recent activity, with a historically accurate running balance: |
| 62 |
|
| 63 |
$ hledger register checking -b 2008/6 --historical |
| 64 |
2008/06/01 gift assets:bank:checking $1 $2 |
| 65 |
2008/06/02 save assets:bank:checking $-1 $1 |
| 66 |
2008/12/31 pay off assets:bank:checking $-1 0 |
| 67 |
|
| 68 |
The --depth option limits the amount of sub-account detail displayed. |
| 69 |
|
| 70 |
The --drop option will trim leading segments from account names. |
| 71 |
|
| 72 |
The --average/-A flag shows the running average posting amount instead |
| 73 |
of the running total (so, the final number displayed is the average for |
| 74 |
the whole report period). This flag implies --empty (see below). It is |
| 75 |
affected by --historical. It works best when showing just one account |
| 76 |
and one commodity. |
| 77 |
|
| 78 |
The --related/-r flag shows the other postings in the transactions of |
| 79 |
the postings which would normally be shown. |
| 80 |
|
| 81 |
The --invert flag negates all amounts. For example, it can be used on an |
| 82 |
income account where amounts are normally displayed as negative numbers. |
| 83 |
It's also useful to show postings on the checking account together with |
| 84 |
the related account: |
| 85 |
|
| 86 |
The --sort=FIELDS flag sorts by the fields given, which can be any of |
| 87 |
account, amount, absamount, date, or desc/description, optionally |
| 88 |
separated by commas. For example, --sort account,amount will group all |
| 89 |
transactions in each account, sorted by transaction amount. Each field |
| 90 |
can be negated by a preceding -, so --sort -amount will show |
| 91 |
transactions ordered from smallest amount to largest amount. |
| 92 |
|
| 93 |
$ hledger register --related --invert assets:checking |
| 94 |
|
| 95 |
With a reporting interval, register shows summary postings, one per |
| 96 |
interval, aggregating the postings to each account: |
| 97 |
|
| 98 |
$ hledger register --monthly income |
| 99 |
2008/01 income:salary $-1 $-1 |
| 100 |
2008/06 income:gifts $-1 $-2 |
| 101 |
|
| 102 |
Periods with no activity, and summary postings with a zero amount, are |
| 103 |
not shown by default; use the --empty/-E flag to see them: |
| 104 |
|
| 105 |
$ hledger register --monthly income -E |
| 106 |
2008/01 income:salary $-1 $-1 |
| 107 |
2008/02 0 $-1 |
| 108 |
2008/03 0 $-1 |
| 109 |
2008/04 0 $-1 |
| 110 |
2008/05 0 $-1 |
| 111 |
2008/06 income:gifts $-1 $-2 |
| 112 |
2008/07 0 $-2 |
| 113 |
2008/08 0 $-2 |
| 114 |
2008/09 0 $-2 |
| 115 |
2008/10 0 $-2 |
| 116 |
2008/11 0 $-2 |
| 117 |
2008/12 0 $-2 |
| 118 |
|
| 119 |
Often, you'll want to see just one line per interval. The --depth option |
| 120 |
helps with this, causing subaccounts to be aggregated: |
| 121 |
|
| 122 |
$ hledger register --monthly assets --depth 1 |
| 123 |
2008/01 assets $1 $1 |
| 124 |
2008/06 assets $-1 0 |
| 125 |
2008/12 assets $-1 $-1 |
| 126 |
|
| 127 |
Note when using report intervals, if you specify start/end dates these |
| 128 |
will be adjusted outward if necessary to contain a whole number of |
| 129 |
intervals. This ensures that the first and last intervals are full |
| 130 |
length and comparable to the others in the report. |
| 131 |
|
| 132 |
If you have a deeply nested account tree some reports might benefit from |
| 133 |
trimming leading segments from the account names using --drop. |
| 134 |
|
| 135 |
$ hledger register --monthly income --drop 1 |
| 136 |
2008/01 salary $-1 $-1 |
| 137 |
2008/06 gifts $-1 $-2 |
| 138 |
|
| 139 |
With -m DESC/--match=DESC, register does a fuzzy search for one recent |
| 140 |
posting whose description is most similar to DESC. DESC should contain |
| 141 |
at least two characters. If there is no similar-enough match, no posting |
| 142 |
will be shown and the program exit code will be non-zero. |
| 143 |
|
| 144 |
Custom register output |
| 145 |
|
| 146 |
register normally uses the full terminal width (or 80 columns if it |
| 147 |
can't detect that). You can override this with the --width/-w option. |
| 148 |
|
| 149 |
The description and account columns normally share the space equally |
| 150 |
(about half of (width - 40) each). You can adjust this by adding a |
| 151 |
description width as part of --width's argument, comma-separated: |
| 152 |
--width W,D . Here's a diagram (won't display correctly in --help): |
| 153 |
|
| 154 |
<--------------------------------- width (W) ----------------------------------> |
| 155 |
date (10) description (D) account (W-41-D) amount (12) balance (12) |
| 156 |
DDDDDDDDDD dddddddddddddddddddd aaaaaaaaaaaaaaaaaaa AAAAAAAAAAAA AAAAAAAAAAAA |
| 157 |
|
| 158 |
and some examples: |
| 159 |
|
| 160 |
$ hledger reg # use terminal width (or 80 on windows) |
| 161 |
$ hledger reg -w 100 # use width 100 |
| 162 |
$ hledger reg -w 100,40 # set overall width 100, description width 40 |
| 163 |
|
| 164 |
This command also supports the output destination and output format |
| 165 |
options The output formats supported are txt, csv, tsv (Added in 1.32), |
| 166 |
and json. |