2 # ABSTRACT: A tool to convert HomeBank files to Ledger format
3 # PODNAME: homebank2ledger
6 # FATPACK - Do not remove this line.
11 use App::HomeBank2Ledger;
13 our $VERSION = '0.009'; # VERSION
15 App::HomeBank2Ledger->main(@ARGV);
25 homebank2ledger - A tool to convert HomeBank files to Ledger format
33 homebank2ledger --input FILEPATH [--output FILEPATH] [--format FORMAT]
34 [--version|--help|--manual] [--account-width NUM]
35 [--accounts|--no-accounts] [--payees|--no-payees]
36 [--tags|--no-tags] [--commodities|--no-commodities]
38 [--rename-account STR]... [--exclude-account STR]...
42 F<homebank2ledger> converts L<HomeBank|http://homebank.free.fr/> files to a format usable by
43 L<Ledger|https://www.ledger-cli.org/>. It can also convert directly to the similar
44 L<Beancount|https://beancount.github.io/docs/index.html> format.
46 This software is B<EXPERIMENTAL>, in early development. Its interface may change without notice.
48 I wrote F<homebank2ledger> because I have been maintaining my own personal finances using HomeBank
49 (which is awesome) and I wanted to investigate using plain text accounting programs. It works well
50 enough for my data, but you may be using HomeBank features that I don't so there may be cases this
51 doesn't handle well or at all. Feel free to file a bug report. This script does NOT try to modify
52 the original HomeBank files it converts from, so there won't be any crazy data loss bugs... but no
61 Converts HomeBank accounts and categories into a typical set of double-entry accounts.
65 Retains HomeBank metadata, including payees and tags.
69 Offers some customization of the output ledger, like account renaming.
73 This program is feature-complete in my opinion (well, almost -- see L</CAVEATS>), but if there is
74 anything you think it could do to be even better, feedback is welcome; just file a bug report. Or
75 fork the code and have fun!
79 You can migrate the data you have in HomeBank so you can start maintaining your accounts in Ledger
82 Or if you don't plan to switch completely off of HomeBank, you can continue to maintain your
83 accounts in HomeBank and use this script to also take advantage of the reports Ledger offers.
87 There are several ways to install F<homebank2ledger> to your system.
91 You can install F<homebank2ledger> using L<cpanm>. If you have a local perl (plenv, perlbrew, etc.),
94 cpanm App::Homebank2Ledger
96 to install the F<homebank2ledger> executable and its dependencies. The executable will be installed
97 to your perl's bin path, like F<~/perl5/perlbrew/bin/homebank2ledger>.
99 If you're installing to your system perl, you can do:
101 cpanm --sudo App::Homebank2Ledger
103 to install the F<homebank2ledger> executable to a system directory, like
104 F</usr/local/bin/homebank2ledger> (depending on your perl).
106 =head2 Downloading just the executable
108 You may also choose to download F<homebank2ledger> as a single executable, like this:
110 curl -OL https://raw.githubusercontent.com/chazmcgarvey/homebank2ledger/solo/homebank2ledger
111 chmod +x homebank2ledger
113 =head2 For developers
115 If you're a developer and want to hack on the source, clone the repository and pull the
118 git clone https://github.com/chazmcgarvey/homebank2ledger.git
120 make bootstrap # installs dependencies; requires cpanm
126 Print the version and exit.
132 Print help/usage info and exit.
138 Print the full manual and exit.
142 =head2 --input FILEPATH
144 Specify the path to the HomeBank file to read (must already exist).
146 Alias: C<--file>, C<-i>
148 =head2 --output FILEPATH
150 Specify the path to the Ledger file to write (may not exist yet). If not provided, the formatted
151 ledger will be printed on C<STDOUT>.
157 Specify the output file format. If provided, must be one of:
171 =head2 --account-width NUM
173 Specify the number of characters to reserve for the account column in transactions. Adjusting this
174 can provide prettier formatting of the output.
180 Enables account declarations.
182 Defaults to enabled; use C<--no-accounts> to disable.
186 Enables payee declarations.
188 Defaults to enabled; use C<--no-payees> to disable.
192 Enables tag declarations.
194 Defaults to enabled; use C<--no-tags> to disable.
198 Enables commodity declarations.
200 Defaults to enabled; use C<--no-commodities> to disable.
204 Enables budget transactions.
206 Budget transactions are only supported by the Ledger format (for now). This option is silently
209 Defaults to enabled; use C<--no-budget> to disable.
211 =head2 --opening-date DATE
213 Specify the opening date for the "opening balances" transaction. This transaction is created (if
214 needed) to support HomeBank's ability to configure accounts with opening balances.
216 Date must be in the form "YYYY-MM-DD". Defaults to the date of the first transaction.
218 =head2 --rename-account STR
220 Specifies a mapping for renaming accounts in the output. By default F<homebank2ledger> tries to come
221 up with sensible account names (based on your HomeBank accounts and categories) that fit into five
248 The value of the argument must be of the form "REGEXP=REPLACEMENT". See L</EXAMPLES>.
250 Can be repeated to rename multiple accounts.
252 =head2 --exclude-account STR
254 Specifies an account that will not be included in the output. All transactions related to this
255 account will be skipped.
257 Can be repeated to exclude multiple accounts.
263 # Convert homebank.xhb to a Ledger-compatible file:
264 homebank2ledger path/to/homebank.xhb -o ledger.dat
266 # Run the Ledger balance report:
267 ledger -f ledger.dat balance
269 You can also combine this into one command:
271 homebank2ledger path/to/homebank.xhb | ledger -f - balance
273 =head2 Account renaming
275 With the L</"--rename-account STR"> argument, you have some control over the resulting account
276 structure. This may be useful in cases where the organization imposed (or encouraged) by HomeBank
277 doesn't necessarily line up with an ideal double-entry structure.
279 homebank2ledger path/to/homebank.xhb -o ledger.dat \
280 --rename-account '^Assets:Credit Union Savings$=Assets:Bank:Credit Union:Savings' \
281 --rename-account '^Assets:Credit Union Checking$=Assets:Bank:Credit Union:Checking'
283 Multiple accounts can be renamed at the same time because the first part of the mapping is a regular
284 expression. The above example could be written like this:
286 homebank2ledger path/to/homebank.xhb -o ledger.dat \
287 --rename-account '^Assets:Credit Union =Assets:Bank:Credit Union:'
289 You can also merge accounts by simple renaming multiple accounts to the same name:
291 homebank2ledger path/to/homebank.xhb -o ledger.dat \
292 --rename-account '^Liabilities:Chase VISA$=Liabilities:All Credit Cards' \
293 --rename-account '^Liabilities:Amex$=Liabilities:All Credit Cards'
295 If you need to do anything more complicated, of course you can edit the output after converting;
296 it's just plain text.
300 # Convert homebank.xhb to a Beancount-compatible file:
301 homebank2ledger path/to/homebank.xhb -f beancount -o ledger.beancount
303 # Run the balances report:
304 bean-report ledger.beancount balances
312 I didn't intend to make this a releasable robust product, so it's lacking tests.
316 Scheduled transactions are not (yet) converted.
320 There are some minor formatting tweaks I will make (e.g. consolidate transaction tags and payees)
326 Please report any bugs or feature requests on the bugtracker website
327 L<https://github.com/chazmcgarvey/homebank2ledger/issues>
329 When submitting a bug or request, please include a test-file or a
330 patch to an existing test-file that illustrates the bug or desired
335 Charles McGarvey <chazmcgarvey@brokenzipper.com>
337 =head1 COPYRIGHT AND LICENSE
339 This software is Copyright (c) 2019 by Charles McGarvey.
341 This is free software, licensed under:
343 The MIT (X11) License