Release App-HomeBank2Ledger 0.009
[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 F<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|https://beancount.github.io/docs/index.html> format.
19
20 This software is B<EXPERIMENTAL>, in early development. Its interface may change without notice.
21
22 I wrote F<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 INSTALL
49
50 There are several ways to install F<homebank2ledger> to your system.
51
52 =head2 using cpanm
53
54 You can install F<homebank2ledger> using L<cpanm>. If you have a local perl (plenv, perlbrew, etc.),
55 you can just do:
56
57 cpanm App::Homebank2Ledger
58
59 to install the F<homebank2ledger> executable and its dependencies. The executable will be installed
60 to your perl's bin path, like F<~/perl5/perlbrew/bin/homebank2ledger>.
61
62 If you're installing to your system perl, you can do:
63
64 cpanm --sudo App::Homebank2Ledger
65
66 to install the F<homebank2ledger> executable to a system directory, like
67 F</usr/local/bin/homebank2ledger> (depending on your perl).
68
69 =head2 Downloading just the executable
70
71 You may also choose to download F<homebank2ledger> as a single executable, like this:
72
73 curl -OL https://raw.githubusercontent.com/chazmcgarvey/homebank2ledger/solo/homebank2ledger
74 chmod +x homebank2ledger
75
76 =head2 For developers
77
78 If you're a developer and want to hack on the source, clone the repository and pull the
79 dependencies:
80
81 git clone https://github.com/chazmcgarvey/homebank2ledger.git
82 cd homebank2ledger
83 make bootstrap # installs dependencies; requires cpanm
84
85 =head1 OPTIONS
86
87 =head2 --version
88
89 Print the version and exit.
90
91 Alias: C<-V>
92
93 =head2 --help
94
95 Print help/usage info and exit.
96
97 Alias: C<-h>, C<-?>
98
99 =head2 --manual
100
101 Print the full manual and exit.
102
103 Alias: C<--man>
104
105 =head2 --input FILEPATH
106
107 Specify the path to the HomeBank file to read (must already exist).
108
109 Alias: C<--file>, C<-i>
110
111 =head2 --output FILEPATH
112
113 Specify the path to the Ledger file to write (may not exist yet). If not provided, the formatted
114 ledger will be printed on C<STDOUT>.
115
116 Alias: C<-o>
117
118 =head2 --format STR
119
120 Specify the output file format. If provided, must be one of:
121
122 =for :list
123 * ledger
124 * beancount
125
126 =head2 --account-width NUM
127
128 Specify the number of characters to reserve for the account column in transactions. Adjusting this
129 can provide prettier formatting of the output.
130
131 Defaults to 40.
132
133 =head2 --accounts
134
135 Enables account declarations.
136
137 Defaults to enabled; use C<--no-accounts> to disable.
138
139 =head2 --payees
140
141 Enables payee declarations.
142
143 Defaults to enabled; use C<--no-payees> to disable.
144
145 =head2 --tags
146
147 Enables tag declarations.
148
149 Defaults to enabled; use C<--no-tags> to disable.
150
151 =head2 --commodities
152
153 Enables commodity declarations.
154
155 Defaults to enabled; use C<--no-commodities> to disable.
156
157 =head2 --budget
158
159 Enables budget transactions.
160
161 Budget transactions are only supported by the Ledger format (for now). This option is silently
162 ignored otherwise.
163
164 Defaults to enabled; use C<--no-budget> to disable.
165
166 =head2 --opening-date DATE
167
168 Specify the opening date for the "opening balances" transaction. This transaction is created (if
169 needed) to support HomeBank's ability to configure accounts with opening balances.
170
171 Date must be in the form "YYYY-MM-DD". Defaults to the date of the first transaction.
172
173 =head2 --rename-account STR
174
175 Specifies a mapping for renaming accounts in the output. By default F<homebank2ledger> tries to come
176 up with sensible account names (based on your HomeBank accounts and categories) that fit into five
177 root accounts:
178
179 =for :list
180 * Assets
181 * Liabilities
182 * Equity
183 * Income
184 * Expenses
185
186 The value of the argument must be of the form "REGEXP=REPLACEMENT". See L</EXAMPLES>.
187
188 Can be repeated to rename multiple accounts.
189
190 =head2 --exclude-account STR
191
192 Specifies an account that will not be included in the output. All transactions related to this
193 account will be skipped.
194
195 Can be repeated to exclude multiple accounts.
196
197 =head1 EXAMPLES
198
199 =head2 Basic usage
200
201 # Convert homebank.xhb to a Ledger-compatible file:
202 homebank2ledger path/to/homebank.xhb -o ledger.dat
203
204 # Run the Ledger balance report:
205 ledger -f ledger.dat balance
206
207 You can also combine this into one command:
208
209 homebank2ledger path/to/homebank.xhb | ledger -f - balance
210
211 =head2 Account renaming
212
213 With the L</"--rename-account STR"> argument, you have some control over the resulting account
214 structure. This may be useful in cases where the organization imposed (or encouraged) by HomeBank
215 doesn't necessarily line up with an ideal double-entry structure.
216
217 homebank2ledger path/to/homebank.xhb -o ledger.dat \
218 --rename-account '^Assets:Credit Union Savings$=Assets:Bank:Credit Union:Savings' \
219 --rename-account '^Assets:Credit Union Checking$=Assets:Bank:Credit Union:Checking'
220
221 Multiple accounts can be renamed at the same time because the first part of the mapping is a regular
222 expression. The above example could be written like this:
223
224 homebank2ledger path/to/homebank.xhb -o ledger.dat \
225 --rename-account '^Assets:Credit Union =Assets:Bank:Credit Union:'
226
227 You can also merge accounts by simple renaming multiple accounts to the same name:
228
229 homebank2ledger path/to/homebank.xhb -o ledger.dat \
230 --rename-account '^Liabilities:Chase VISA$=Liabilities:All Credit Cards' \
231 --rename-account '^Liabilities:Amex$=Liabilities:All Credit Cards'
232
233 If you need to do anything more complicated, of course you can edit the output after converting;
234 it's just plain text.
235
236 =head2 Beancount
237
238 # Convert homebank.xhb to a Beancount-compatible file:
239 homebank2ledger path/to/homebank.xhb -f beancount -o ledger.beancount
240
241 # Run the balances report:
242 bean-report ledger.beancount balances
243
244 =head1 CAVEATS
245
246 =for :list
247 * I didn't intend to make this a releasable robust product, so it's lacking tests.
248 * Scheduled transactions are not (yet) converted.
249 * There are some minor formatting tweaks I will make (e.g. consolidate transaction tags and payees)
250
251 =cut
252
253 # FATPACK - Do not remove this line.
254
255 use warnings;
256 use strict;
257
258 use App::HomeBank2Ledger;
259
260 our $VERSION = '9999.999'; # VERSION
261
262 App::HomeBank2Ledger->main(@ARGV);
This page took 0.050988 seconds and 5 git commands to generate.