2 # ABSTRACT: A tool to convert HomeBank files to Ledger format
3 # PODNAME: homebank2ledger
9 use App::HomeBank2Ledger;
11 our $VERSION = '0.002'; # VERSION
13 App::HomeBank2Ledger->main(@ARGV);
23 homebank2ledger - A tool to convert HomeBank files to Ledger format
31 homebank2ledger --input FILEPATH [--output FILEPATH] [--format FORMAT]
32 [--version|--help|--manual] [--account-width NUM]
33 [--accounts|--no-accounts] [--payees|--no-payees]
34 [--tags|--no-tags] [--commodities|--no-commodities]
35 [--opening-date DATE] [--default-account STR]
36 [--rename-account STR]... [--exclude-account STR]...
40 C<homebank2ledger> converts L<HomeBank|http://homebank.free.fr/> files to a format usable by
41 L<Ledger|https://www.ledger-cli.org/>. It can also convert directly to the similar
42 L<Beancount|http://furius.ca/beancount/> format.
44 This software is B<EXPERIMENTAL>, in early development. Its interface may change without notice.
46 I wrote C<homebank2ledger> because I have been maintaining my own personal finances using HomeBank
47 (which is awesome) and I wanted to investigate using plain text accounting programs. It works well
48 enough for my data, but you may be using HomeBank features that I don't so there may be cases this
49 doesn't handle well or at all. Feel free to file a bug report. This script does NOT try to modify
50 the original HomeBank files it converts from, so there won't be any crazy data loss bugs... but no
59 Converts HomeBank accounts and categories into a typical set of double-entry accounts.
63 Retains HomeBank metadata, including payees and tags.
67 Offers some customization of the output ledger, like account renaming.
71 This program is feature-complete in my opinion (well, almost -- see L</CAVEATS>), but if there is
72 anything you think it could do to be even better, feedback is welcome; just file a bug report. Or
73 fork the code and have fun!
77 You can migrate the data you have in HomeBank so you can start maintaining your accounts in Ledger
80 Or if you don't plan to switch completely off of HomeBank, you can continue to maintain your
81 accounts in HomeBank and use this script to also take advantage of the reports Ledger offers.
87 Print the version and exit.
93 Print help/usage info and exit.
99 Print the full manual and exit.
103 =head2 --input FILEPATH
105 Specify the path to the HomeBank file to read (must already exist).
107 Alias: C<--file>, C<-i>
109 =head2 --output FILEPATH
111 Specify the path to the Ledger file to write (may not exist yet). If not provided, the formatted
112 ledger will be printed on C<STDOUT>.
118 Specify the output file format. If provided, must be one of:
132 =head2 --account-width NUM
134 Specify the number of characters to reserve for the account column in transactions. Adjusting this
135 can provide prettier formatting of the output.
141 Enables account declarations.
143 Defaults to enabled; use C<--no-accounts> to disable.
147 Enables payee declarations.
149 Defaults to enabled; use C<--no-payees> to disable.
153 Enables tag declarations.
155 Defaults to enabled; use C<--no-tags> to disable.
159 Enables commodity declarations.
161 Defaults to enabled; use C<--no-commodities> to disable.
163 =head2 --opening-date DATE
165 Specify the opening date for the "opening balances" transaction. This transaction is created (if
166 needed) to support HomeBank's ability to configure accounts with opening balances.
168 Date must be in the form "YYYY-MM-DD". Defaults to the date of the first transaction.
170 =head2 --default-account STR
172 Specify the account to use for one-sided transactions (if any). Defaults to "Expenses:No Category".
174 A default account may be necessary because with Ledger all transactions are double-entry.
176 =head2 --rename-account STR
178 Specifies a mapping for renaming accounts in the output. By default C<homebank2ledger> tries to come
179 up with sensible account names (based on your HomeBank accounts and categories) that fit into five
206 The value of the argument must be of the form "REGEXP=REPLACEMENT". See L</EXAMPLES>.
208 Can be repeated to rename multiple accounts.
210 =head2 --exclude-account STR
212 Specifies an account that will not be included in the output. All transactions related to this
213 account will be skipped.
215 Can be repeated to exclude multiple accounts.
221 # Convert homebank.xhb to a Ledger-compatible file:
222 homebank2ledger path/to/homebank.xhb -o ledger.dat
224 # Run the Ledger balance report:
225 ledger -f ledger.dat balance
227 You can also combine this into one command:
229 homebank2ledger path/to/homebank.xhb | ledger -f - balance
231 =head2 Account renaming
233 With the L</"--rename-account STR"> argument, you have some control over the resulting account
234 structure. This may be useful in cases where the organization imposed (or encouraged) by HomeBank
235 doesn't necessarily line up with an ideal double-entry structure.
237 homebank2ledger path/to/homebank.xhb -o ledger.dat \
238 --rename-account '^Assets:Credit Union Savings$=Assets:Bank:Credit Union:Savings' \
239 --rename-account '^Assets:Credit Union Checking$=Assets:Bank:Credit Union:Checking'
241 Multiple accounts can be renamed at the same time because the first part of the mapping is a regular
242 expression. The above example could be written like this:
244 homebank2ledger path/to/homebank.xhb -o ledger.dat \
245 --rename-account '^Assets:Credit Union =Assets:Bank:Credit Union:'
247 You can also merge accounts by simple renaming multiple accounts to the same name:
249 homebank2ledger path/to/homebank.xhb -o ledger.dat \
250 --rename-account '^Liabilities:Chase VISA$=Liabilities:All Credit Cards' \
251 --rename-account '^Liabilities:Amex$=Liabilities:All Credit Cards'
253 If you need to do anything more complicated, of course you can edit the output after converting;
254 it's just plain text.
258 # Convert homebank.xhb to a Beancount-compatible file:
259 homebank2ledger path/to/homebank.xhb -f beancount -o ledger.beancount
261 # Run the balances report:
262 bean-report ledger.beancount balances
270 I didn't intend to make this a releasable robust product, so it's lacking tests.
274 Budgets and scheduled transactions are not (yet) converted.
278 There are some minor formatting tweaks I will make (e.g. consolidate transaction tags and payees)
284 Please report any bugs or feature requests on the bugtracker website
285 L<https://github.com/chazmcgarvey/homebank2ledger/issues>
287 When submitting a bug or request, please include a test-file or a
288 patch to an existing test-file that illustrates the bug or desired
293 Charles McGarvey <chazmcgarvey@brokenzipper.com>
295 =head1 COPYRIGHT AND LICENSE
297 This software is Copyright (c) 2019 by Charles McGarvey.
299 This is free software, licensed under:
301 The MIT (X11) License