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