Debian Codegraph @

Hledger/Cli/Commands/Rewrite.txt

raw
1 rewrite
2
3 Print all transactions, rewriting the postings of matched transactions.
4 For now the only rewrite available is adding new postings, like print
5 --auto.
6
7 Flags:
8 --add-posting='ACCT AMTEXPR' add a posting to ACCT, which may be
9 parenthesised. AMTEXPR is either a literal
10 amount, or *N which means the transaction's
11 first matched amount multiplied by N (a
12 decimal number). Two spaces separate ACCT
13 and AMTEXPR.
14 --diff generate diff suitable as an input for
15 patch tool
16
17 This is a start at a generic rewriter of transaction entries. It reads
18 the default journal and prints the transactions, like print, but adds
19 one or more specified postings to any transactions matching QUERY. The
20 posting amounts can be fixed, or a multiplier of the existing
21 transaction's first posting amount.
22
23 Examples:
24
25 $ hledger-rewrite.hs ^income --add-posting '(liabilities:tax) *.33 ; income tax' --add-posting '(reserve:gifts) $100'
26 $ hledger-rewrite.hs expenses:gifts --add-posting '(reserve:gifts) *-1"'
27 $ hledger-rewrite.hs -f rewrites.hledger
28
29 rewrites.hledger may consist of entries like:
30
31 = ^income amt:<0 date:2017
32 (liabilities:tax) *0.33 ; tax on income
33 (reserve:grocery) *0.25 ; reserve 25% for grocery
34 (reserve:) *0.25 ; reserve 25% for grocery
35
36 Note the single quotes to protect the dollar sign from bash, and the two
37 spaces between account and amount.
38
39 More:
40
41 $ hledger rewrite [QUERY] --add-posting "ACCT AMTEXPR" ...
42 $ hledger rewrite ^income --add-posting '(liabilities:tax) *.33'
43 $ hledger rewrite expenses:gifts --add-posting '(budget:gifts) *-1"'
44 $ hledger rewrite ^income --add-posting '(budget:foreign currency) *0.25 JPY; diversify'
45
46 Argument for --add-posting option is a usual posting of transaction with
47 an exception for amount specification. More precisely, you can use '*'
48 (star symbol) before the amount to indicate that that this is a factor
49 for an amount of original matched posting. If the amount includes a
50 commodity name, the new posting amount will be in the new commodity;
51 otherwise, it will be in the matched posting amount's commodity.
52
53 Re-write rules in a file
54
55 During the run this tool will execute so called "Automated Transactions"
56 found in any journal it process. I.e instead of specifying this
57 operations in command line you can put them in a journal file.
58
59 $ rewrite-rules.journal
60
61 Make contents look like this:
62
63 = ^income
64 (liabilities:tax) *.33
65
66 = expenses:gifts
67 budget:gifts *-1
68 assets:budget *1
69
70 Note that '=' (equality symbol) that is used instead of date in
71 transactions you usually write. It indicates the query by which you want
72 to match the posting to add new ones.
73
74 $ hledger rewrite -f input.journal -f rewrite-rules.journal > rewritten-tidy-output.journal
75
76 This is something similar to the commands pipeline:
77
78 $ hledger rewrite -f input.journal '^income' --add-posting '(liabilities:tax) *.33' \
79 | hledger rewrite -f - expenses:gifts --add-posting 'budget:gifts *-1' \
80 --add-posting 'assets:budget *1' \
81 > rewritten-tidy-output.journal
82
83 It is important to understand that relative order of such entries in
84 journal is important. You can re-use result of previously added
85 postings.
86
87 Diff output format
88
89 To use this tool for batch modification of your journal files you may
90 find useful output in form of unified diff.
91
92 $ hledger rewrite --diff -f examples/sample.journal '^income' --add-posting '(liabilities:tax) *.33'
93
94 Output might look like:
95
96 --- /tmp/examples/sample.journal
97 +++ /tmp/examples/sample.journal
98 @@ -18,3 +18,4 @@
99 2008/01/01 income
100 - assets:bank:checking $1
101 + assets:bank:checking $1
102 income:salary
103 + (liabilities:tax) 0
104 @@ -22,3 +23,4 @@
105 2008/06/01 gift
106 - assets:bank:checking $1
107 + assets:bank:checking $1
108 income:gifts
109 + (liabilities:tax) 0
110
111 If you'll pass this through patch tool you'll get transactions
112 containing the posting that matches your query be updated. Note that
113 multiple files might be update according to list of input files
114 specified via --file options and include directives inside of these
115 files.
116
117 Be careful. Whole transaction being re-formatted in a style of output
118 from hledger print.
119
120 See also:
121
122 https://github.com/simonmichael/hledger/issues/99
123
124 rewrite vs. print --auto
125
126 This command predates print --auto, and currently does much the same
127 thing, but with these differences:
128
129 - with multiple files, rewrite lets rules in any file affect all other
130 files. print --auto uses standard directive scoping; rules affect only
131 child files.
132
133 - rewrite's query limits which transactions can be rewritten; all are
134 printed. print --auto's query limits which transactions are printed.
135
136 - rewrite applies rules specified on command line or in the journal.
137 print --auto applies rules specified in the journal.