2 # ABSTRACT: A tool to convert HomeBank files to Ledger format
3 # PODNAME: homebank2ledger
7 homebank2ledger --input FILEPATH [--output FILEPATH]
8 [--version|--help|--manual]
9 [--format FORMAT] [--account-width NUM]
10 [--accounts|--no-accounts] [--payees|--no-payees]
11 [--tags|--no-tags] [--commodities|--no-commodities]
12 [--opening-date DATE] [--default-account STR]
13 [--rename-account STR]... [--exclude-account STR]...
17 C<homebank2ledger> converts L<HomeBank|http://homebank.free.fr/> files to a format usable by
18 L<Ledger|https://www.ledger-cli.org/>. It can also convert directly to the similar
19 L<Beancount|http://furius.ca/beancount/> format.
21 This software is B<EXPERIMENTAL>. I wrote it because I have been maintaining my own personal
22 finances using HomeBank (which is awesome) and I wanted to investigate using plain text accounting
23 programs which have great support for commodities. It works well enough for my data, but you may be
24 using HomeBank features that I don't so there may be cases this doesn't handle well or at all. Feel
25 free to file a bug report. This script does NOT try to modify the original HomeBank files it
26 converts from, so there won't be any crazy data loss bugs... but no warranty.
31 * Converts HomeBank accounts and categories into a typical set of double-entry accounts.
32 * Retains HomeBank metadata, including payees and tags.
33 * Offers some customization of the output ledger, like account renaming.
35 There aren't really any features I think this program is missing -- actually it may have too many
36 features -- but if there is anything you think this program could do to be even better, feedback is
37 welcome; just file a bug report. Or fork the code and have fun!
41 You can migrate the data you have in HomeBank so you can start maintaining your accounts in Ledger
44 Or if you don't plan to switch completely off of HomeBank, you can continue to maintain your
45 accounts in HomeBank and use this script to also take advantage of the reports Ledger offers.
51 Print the version and exit.
57 Print help/usage info and exit.
63 Print the full manual and exit.
67 =head2 --input FILEPATH
69 Specify the path to the HomeBank file to read (must already exist).
71 Alias: C<--file>, C<-i>
73 =head2 --output FILEPATH
75 Specify the path to the Ledger file to write (may not exist yet). If not provided, the formatted
76 ledger will be printed on C<STDOUT>.
82 Specify the output file format. If provided, must be one of:
88 =head2 --account-width NUM
90 Specify the number of characters to reserve for the account column in transactions. Adjusting this
91 can provide prettier formatting of the output.
97 Enables account declarations.
99 Defaults to enabled; use C<--no-accounts> to disable.
103 Enables payee declarations.
105 Defaults to enabled; use C<--no-payees> to disable.
109 Enables tag declarations.
111 Defaults to enabled; use C<--no-tags> to disable.
115 Enables commodity declarations.
117 Defaults to enabled; use C<--no-commodities> to disable.
119 =head2 --opening-date DATE
121 Specify the opening date for the "opening balances" transaction. This transaction is created (if
122 needed) to support HomeBank's ability to configure accounts with opening balances.
124 Date must be in the form "YYYY-MM-DD". Defaults to the date of the first transaction.
126 =head2 --default-account STR
128 Specify the account to use for one-sided transactions (if any). Defaults to "Expenses:No Category".
130 A default account may be necessary because with Ledger all transactions are double-entry.
132 =head2 --rename-account STR
134 Specifies a mapping for renaming accounts in the output. By default C<homebank2ledger> tries to come
135 up with sensible account names (based on your HomeBank accounts and categories) that fit into five
145 The value of the argument must be of the form "REGEXP=REPLACEMENT". See L</EXAMPLES>.
147 Can be repeated to rename multiple accounts.
149 =head2 --exclude-account STR
151 Specifies an account that will not be included in the output. All transactions related to this
152 account will be skipped.
154 Can be repeated to exclude multiple accounts.
160 # Convert homebank.xhb to a Ledger-compatible file:
161 homebank2ledger path/to/homebank.xhb -o ledger.dat
163 # Run the Ledger balance report:
164 ledger -f ledger.dat balance
166 You can also combine this into one command:
168 homebank2ledger path/to/homebank.xhb | ledger -f - balance
170 =head2 Account renaming
172 With the L</"--rename-account STR"> argument, you have some control over the resulting account
173 structure. This may be useful in cases where the organization imposed (or encouraged) by HomeBank
174 doesn't necessarily line up with an ideal double-entry structure.
176 homebank2ledger path/to/homebank.xhb -o ledger.dat \
177 --rename-account '^Assets:Credit Union Savings$=Assets:Bank:Credit Union:Savings' \
178 --rename-account '^Assets:Credit Union Checking$=Assets:Bank:Credit Union:Checking'
180 Multiple accounts can be renamed at the same time because the first part of the mapping is a regular
181 expression. The above example could be written like this:
183 homebank2ledger path/to/homebank.xhb -o ledger.dat \
184 --rename-account '^Assets:Credit Union =Assets:Bank:Credit Union:'
186 You can also merge accounts by simple renaming multiple accounts to the same name:
188 homebank2ledger path/to/homebank.xhb -o ledger.dat \
189 --rename-account '^Liabilities:Chase VISA$=Liabilities:All Credit Cards' \
190 --rename-account '^Liabilities:Amex$=Liabilities:All Credit Cards'
192 If you need to do anything more complicated, of course you can edit the output after converting;
193 it's just plain text.
197 # Convert homebank.xhb to a Beancount-compatible file:
198 homebank2ledger path/to/homebank.xhb -f beancount -o ledger.beancount
200 # Run the balances report:
201 bean-report ledger.beancount balances
208 use App::HomeBank2Ledger;
210 our $VERSION = '9999.999'; # VERSION
212 App::HomeBank2Ledger->main(@ARGV);