Debian Codegraph @

Hledger/Cli/Commands/Print.txt

raw
1 print
2
3 Show full journal entries, representing transactions.
4
5 Flags:
6 -x --explicit show all amounts explicitly
7 --invert display all amounts with reversed sign
8 --locations add tags showing file paths and line numbers
9 -m --match=DESC fuzzy search for one recent transaction with
10 description closest to DESC
11 --new show only newer-dated transactions added in each
12 file since last run
13 --round=TYPE how much rounding or padding should be done when
14 displaying amounts ?
15 none - show original decimal digits,
16 as in journal (default)
17 soft - just add or remove decimal zeros
18 to match precision
19 hard - round posting amounts to precision
20 (can unbalance transactions)
21 all - also round cost amounts to precision
22 (can unbalance transactions)
23 --base-url=URLPREFIX in html output, generate links to hledger-web,
24 with this prefix. (Usually the base url shown by
25 hledger-web; can also be relative.)
26 -O --output-format=FMT select the output format. Supported formats:
27 txt, beancount, csv, tsv, html, fods, json, sql.
28 -o --output-file=FILE write output to FILE. A file extension matching
29 one of the above formats selects that format.
30
31 The print command displays full journal entries (transactions) from the
32 journal file, sorted by date (or with --date2, by secondary date).
33
34 Directives and inter-transaction comments are not shown, currently. This
35 means the print command is somewhat lossy, and if you are using it to
36 reformat/regenerate your journal you should take care to also copy over
37 the directives and inter-transaction comments.
38
39 Eg:
40
41 $ hledger print -f examples/sample.journal date:200806
42 2008/06/01 gift
43 assets:bank:checking $1
44 income:gifts $-1
45
46 2008/06/02 save
47 assets:bank:saving $1
48 assets:bank:checking $-1
49
50 2008/06/03 * eat & shop
51 expenses:food $1
52 expenses:supplies $1
53 assets:cash $-2
54
55 print amount explicitness
56
57 Normally, whether posting amounts are implicit or explicit is preserved.
58 For example, when an amount is omitted in the journal, it will not
59 appear in the output. Similarly, if a conversion cost is implied but not
60 written, it will not appear in the output.
61
62 You can use the -x/--explicit flag to force explicit display of all
63 amounts and costs. This can be useful for troubleshooting or for making
64 your journal more readable and robust against data entry errors. -x is
65 also implied by using any of -B,-V,-X,--value.
66
67 The -x/--explicit flag will cause any postings with a multi-commodity
68 amount (which can arise when a multi-commodity transaction has an
69 implicit amount) to be split into multiple single-commodity postings,
70 keeping the output parseable.
71
72 print alignment
73
74 Amounts are shown right-aligned within each transaction (but not aligned
75 across all transactions; you can achieve that with ledger-mode in
76 Emacs).
77
78 print amount style
79
80 Amounts will be displayed mostly in their commodity's display style,
81 with standardised symbol placement, decimal mark, and digit group marks.
82 This does not apply to their decimal digits; print normally shows the
83 same decimal digits that are recorded in each journal entry.
84
85 You can override the decimal precisions with print's special --round
86 option (since 1.32). --round tries to show amounts with their
87 commodities' standard decimal precisions, increasingly strongly:
88
89 - --round=none show amounts with original precisions (default)
90 - --round=soft add/remove decimal zeros in amounts (except costs)
91 - --round=hard round amounts (except costs), possibly hiding significant
92 digits
93 - --round=all round all amounts and costs
94
95 soft is good for non-lossy cleanup, displaying more consistent decimals
96 where possible, without making entries unbalanced.
97
98 hard or all can be good for stronger cleanup, when decimal rounding is
99 wanted. Note rounding can produce unbalanced journal entries, perhaps
100 requiring manual fixup.
101
102 print parseability
103
104 Normally, print's output is a valid hledger journal, which you can
105 "pipe" to a second hledger command for further processing. This is
106 sometimes convenient for achieving certain kinds of query (though less
107 needed now that queries have become more powerful):
108
109 # Show running total of food expenses paid from cash.
110 # -f- reads from stdin. -I/--ignore-assertions is sometimes needed.
111 $ hledger print assets:cash | hledger -f- -I reg expenses:food
112
113 But here are some things which can cause print's output to become
114 unparseable:
115
116 - --round (see above) can disrupt transaction balancing.
117 - Account aliases or pivoting can disrupt account names, balance
118 assertions, or balance assignments.
119 - Value reporting also can disrupt balance assertions or balance
120 assignments.
121 - Auto postings can generate too many amountless postings.
122 - --infer-costs or --infer-equity can generate too-complex redundant
123 costs.
124 - Because print always shows transactions in date order, balance
125 assertions involving non-date-ordered transactions (and same-day
126 postings) could be disrupted.
127
128 print, other features
129
130 With -B/--cost, amounts with costs are shown converted to cost.
131
132 With --invert, posting amounts are shown with their sign flipped. It
133 could be useful if you have accidentally recorded some transactions with
134 the wrong signs.
135
136 With --new, print shows only transactions it has not seen on a previous
137 run. This uses the same deduplication system as the import command. (See
138 import's docs for details.)
139
140 With -m DESC/--match=DESC, print shows one recent transaction whose
141 description is most similar to DESC. DESC should contain at least two
142 characters. If there is no similar-enough match, no transaction will be
143 shown and the program exit code will be non-zero.
144
145 With --locations, print adds the source file and line number to every
146 transaction, as a tag.
147
148 print output format
149
150 This command also supports the output destination and output format
151 options The output formats supported are txt, beancount (Added in 1.32),
152 csv, tsv (Added in 1.32), json and sql.
153
154 The beancount format tries to produce Beancount-compatible output, as
155 follows:
156
157 - Transaction and postings with unmarked status are converted to cleared
158 (*) status.
159 - Transactions' payee and note are backslash-escaped and
160 double-quote-escaped and wrapped in double quotes.
161 - Transaction tags are copied to Beancount #tag format.
162 - Commodity symbols are converted to upper case, and a small number of
163 currency symbols like $ are converted to the corresponding currency
164 names.
165 - Account name parts are capitalised and unsupported characters are
166 replaced with -. If an account name part does not begin with a letter,
167 or if the first part is not Assets, Liabilities, Equity, Income, or
168 Expenses, an error is raised. (Use --alias options to bring your
169 accounts into compliance.)
170 - An open directive is generated for each account used, on the earliest
171 transaction date.
172
173 Some limitations:
174
175 - Balance assertions are removed.
176 - Balance assignments become missing amounts.
177 - Virtual and balanced virtual postings become regular postings.
178 - Directives are not converted.
179
180 Here's an example of print's CSV output:
181
182 $ hledger print -Ocsv
183 "txnidx","date","date2","status","code","description","comment","account","amount","commodity","credit","debit","posting-status","posting-comment"
184 "1","2008/01/01","","","","income","","assets:bank:checking","1","$","","1","",""
185 "1","2008/01/01","","","","income","","income:salary","-1","$","1","","",""
186 "2","2008/06/01","","","","gift","","assets:bank:checking","1","$","","1","",""
187 "2","2008/06/01","","","","gift","","income:gifts","-1","$","1","","",""
188 "3","2008/06/02","","","","save","","assets:bank:saving","1","$","","1","",""
189 "3","2008/06/02","","","","save","","assets:bank:checking","-1","$","1","","",""
190 "4","2008/06/03","","*","","eat & shop","","expenses:food","1","$","","1","",""
191 "4","2008/06/03","","*","","eat & shop","","expenses:supplies","1","$","","1","",""
192 "4","2008/06/03","","*","","eat & shop","","assets:cash","-2","$","2","","",""
193 "5","2008/12/31","","*","","pay off","","liabilities:debts","1","$","","1","",""
194 "5","2008/12/31","","*","","pay off","","assets:bank:checking","-1","$","1","","",""
195
196 - There is one CSV record per posting, with the parent transaction's
197 fields repeated.
198 - The "txnidx" (transaction index) field shows which postings belong to
199 the same transaction. (This number might change if transactions are
200 reordered within the file, files are parsed/included in a different
201 order, etc.)
202 - The amount is separated into "commodity" (the symbol) and "amount"
203 (numeric quantity) fields.
204 - The numeric amount is repeated in either the "credit" or "debit"
205 column, for convenience. (Those names are not accurate in the
206 accounting sense; it just puts negative amounts under credit and zero
207 or greater amounts under debit.)