Debian Codegraph @

Hledger/Cli/Commands/Register.txt

raw
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.