1139928ea98c30dd8b8bdc86ef4f5a94e3903f09
[chaz/homebank2ledger] / bin / homebank2ledger
1 #! perl
2 # ABSTRACT: A tool to convert HomeBank files to Ledger format
3 # PODNAME: homebank2ledger
4
5 =head1 SYNOPSIS
6
7 homebank2ledger --input FILEPATH [--output FILEPATH] [--format FORMAT]
8 [--version|--help|--manual] [--account-width NUM]
9 [--accounts|--no-accounts] [--payees|--no-payees]
10 [--tags|--no-tags] [--commodities|--no-commodities]
11 [--opening-date DATE]
12 [--rename-account STR]... [--exclude-account STR]...
13
14 =head1 DESCRIPTION
15
16 C<homebank2ledger> converts L<HomeBank|http://homebank.free.fr/> files to a format usable by
17 L<Ledger|https://www.ledger-cli.org/>. It can also convert directly to the similar
18 L<Beancount|http://furius.ca/beancount/> format.
19
20 This software is B<EXPERIMENTAL>, in early development. Its interface may change without notice.
21
22 I wrote C<homebank2ledger> because I have been maintaining my own personal finances using HomeBank
23 (which is awesome) and I wanted to investigate using plain text accounting programs. It works well
24 enough for my data, but you may be using HomeBank features that I don't so there may be cases this
25 doesn't handle well or at all. Feel free to file a bug report. This script does NOT try to modify
26 the original HomeBank files it converts from, so there won't be any crazy data loss bugs... but no
27 warranty.
28
29 =head2 Features
30
31 =for :list
32 * Converts HomeBank accounts and categories into a typical set of double-entry accounts.
33 * Retains HomeBank metadata, including payees and tags.
34 * Offers some customization of the output ledger, like account renaming.
35
36 This program is feature-complete in my opinion (well, almost -- see L</CAVEATS>), but if there is
37 anything you think it could do to be even better, feedback is welcome; just file a bug report. Or
38 fork the code and have fun!
39
40 =head2 Use cases
41
42 You can migrate the data you have in HomeBank so you can start maintaining your accounts in Ledger
43 (or Beancount).
44
45 Or if you don't plan to switch completely off of HomeBank, you can continue to maintain your
46 accounts in HomeBank and use this script to also take advantage of the reports Ledger offers.
47
48 =head1 OPTIONS
49
50 =head2 --version
51
52 Print the version and exit.
53
54 Alias: C<-V>
55
56 =head2 --help
57
58 Print help/usage info and exit.
59
60 Alias: C<-h>, C<-?>
61
62 =head2 --manual
63
64 Print the full manual and exit.
65
66 Alias: C<--man>
67
68 =head2 --input FILEPATH
69
70 Specify the path to the HomeBank file to read (must already exist).
71
72 Alias: C<--file>, C<-i>
73
74 =head2 --output FILEPATH
75
76 Specify the path to the Ledger file to write (may not exist yet). If not provided, the formatted
77 ledger will be printed on C<STDOUT>.
78
79 Alias: C<-o>
80
81 =head2 --format STR
82
83 Specify the output file format. If provided, must be one of:
84
85 =for :list
86 * ledger
87 * beancount
88
89 =head2 --account-width NUM
90
91 Specify the number of characters to reserve for the account column in transactions. Adjusting this
92 can provide prettier formatting of the output.
93
94 Defaults to 40.
95
96 =head2 --accounts
97
98 Enables account declarations.
99
100 Defaults to enabled; use C<--no-accounts> to disable.
101
102 =head2 --payees
103
104 Enables payee declarations.
105
106 Defaults to enabled; use C<--no-payees> to disable.
107
108 =head2 --tags
109
110 Enables tag declarations.
111
112 Defaults to enabled; use C<--no-tags> to disable.
113
114 =head2 --commodities
115
116 Enables commodity declarations.
117
118 Defaults to enabled; use C<--no-commodities> to disable.
119
120 =head2 --budget
121
122 Enables budget transactions.
123
124 Budget transactions are only supported by the Ledger format (for now). This option is silently
125 ignored otherwise.
126
127 Defaults to enabled; use C<--no-budget> to disable.
128
129 =head2 --opening-date DATE
130
131 Specify the opening date for the "opening balances" transaction. This transaction is created (if
132 needed) to support HomeBank's ability to configure accounts with opening balances.
133
134 Date must be in the form "YYYY-MM-DD". Defaults to the date of the first transaction.
135
136 =head2 --rename-account STR
137
138 Specifies a mapping for renaming accounts in the output. By default C<homebank2ledger> tries to come
139 up with sensible account names (based on your HomeBank accounts and categories) that fit into five
140 root accounts:
141
142 =for :list
143 * Assets
144 * Liabilities
145 * Equity
146 * Income
147 * Expenses
148
149 The value of the argument must be of the form "REGEXP=REPLACEMENT". See L</EXAMPLES>.
150
151 Can be repeated to rename multiple accounts.
152
153 =head2 --exclude-account STR
154
155 Specifies an account that will not be included in the output. All transactions related to this
156 account will be skipped.
157
158 Can be repeated to exclude multiple accounts.
159
160 =head1 EXAMPLES
161
162 =head2 Basic usage
163
164 # Convert homebank.xhb to a Ledger-compatible file:
165 homebank2ledger path/to/homebank.xhb -o ledger.dat
166
167 # Run the Ledger balance report:
168 ledger -f ledger.dat balance
169
170 You can also combine this into one command:
171
172 homebank2ledger path/to/homebank.xhb | ledger -f - balance
173
174 =head2 Account renaming
175
176 With the L</"--rename-account STR"> argument, you have some control over the resulting account
177 structure. This may be useful in cases where the organization imposed (or encouraged) by HomeBank
178 doesn't necessarily line up with an ideal double-entry structure.
179
180 homebank2ledger path/to/homebank.xhb -o ledger.dat \
181 --rename-account '^Assets:Credit Union Savings$=Assets:Bank:Credit Union:Savings' \
182 --rename-account '^Assets:Credit Union Checking$=Assets:Bank:Credit Union:Checking'
183
184 Multiple accounts can be renamed at the same time because the first part of the mapping is a regular
185 expression. The above example could be written like this:
186
187 homebank2ledger path/to/homebank.xhb -o ledger.dat \
188 --rename-account '^Assets:Credit Union =Assets:Bank:Credit Union:'
189
190 You can also merge accounts by simple renaming multiple accounts to the same name:
191
192 homebank2ledger path/to/homebank.xhb -o ledger.dat \
193 --rename-account '^Liabilities:Chase VISA$=Liabilities:All Credit Cards' \
194 --rename-account '^Liabilities:Amex$=Liabilities:All Credit Cards'
195
196 If you need to do anything more complicated, of course you can edit the output after converting;
197 it's just plain text.
198
199 =head2 Beancount
200
201 # Convert homebank.xhb to a Beancount-compatible file:
202 homebank2ledger path/to/homebank.xhb -f beancount -o ledger.beancount
203
204 # Run the balances report:
205 bean-report ledger.beancount balances
206
207 =head1 CAVEATS
208
209 =for :list
210 * I didn't intend to make this a releasable robust product, so it's lacking tests.
211 * Scheduled transactions are not (yet) converted.
212 * There are some minor formatting tweaks I will make (e.g. consolidate transaction tags and payees)
213
214 =cut
215
216 use warnings;
217 use strict;
218
219 use App::HomeBank2Ledger;
220
221 our $VERSION = '9999.999'; # VERSION
222
223 App::HomeBank2Ledger->main(@ARGV);
This page took 0.03897 seconds and 3 git commands to generate.