4e1f4cf1246bf597aa38f8b1a36d99bcf5b2cf96
[chaz/homebank2ledger] / README
1 NAME
2
3 homebank2ledger - A tool to convert HomeBank files to Ledger format
4
5 VERSION
6
7 version 0.007
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]
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 INSTALL
62
63 There are several ways to install homebank2ledger to your system.
64
65 using cpanm
66
67 You can install homebank2ledger using cpanm. If you have a local perl
68 (plenv, perlbrew, etc.), you can just do:
69
70 cpanm App::Homebank2Ledger
71
72 to install the homebank2ledger executable and its dependencies. The
73 executable will be installed to your perl's bin path, like
74 ~/perl5/perlbrew/bin/homebank2ledger.
75
76 If you're installing to your system perl, you can do:
77
78 cpanm --sudo App::Homebank2Ledger
79
80 to install the homebank2ledger executable to a system directory, like
81 /usr/local/bin/homebank2ledger (depending on your perl).
82
83 Downloading just the executable
84
85 You may also choose to download homebank2ledger as a single executable,
86 like this:
87
88 curl -OL https://raw.githubusercontent.com/chazmcgarvey/homebank2ledger/solo/homebank2ledger
89 chmod +x homebank2ledger
90
91 For developers
92
93 If you're a developer and want to hack on the source, clone the
94 repository and pull the dependencies:
95
96 git clone https://github.com/chazmcgarvey/homebank2ledger.git
97 cd homebank2ledger
98 make bootstrap # installs dependencies; requires cpanm
99
100 OPTIONS
101
102 --version
103
104 Print the version and exit.
105
106 Alias: -V
107
108 --help
109
110 Print help/usage info and exit.
111
112 Alias: -h, -?
113
114 --manual
115
116 Print the full manual and exit.
117
118 Alias: --man
119
120 --input FILEPATH
121
122 Specify the path to the HomeBank file to read (must already exist).
123
124 Alias: --file, -i
125
126 --output FILEPATH
127
128 Specify the path to the Ledger file to write (may not exist yet). If
129 not provided, the formatted ledger will be printed on STDOUT.
130
131 Alias: -o
132
133 --format STR
134
135 Specify the output file format. If provided, must be one of:
136
137 * ledger
138
139 * beancount
140
141 --account-width NUM
142
143 Specify the number of characters to reserve for the account column in
144 transactions. Adjusting this can provide prettier formatting of the
145 output.
146
147 Defaults to 40.
148
149 --accounts
150
151 Enables account declarations.
152
153 Defaults to enabled; use --no-accounts to disable.
154
155 --payees
156
157 Enables payee declarations.
158
159 Defaults to enabled; use --no-payees to disable.
160
161 --tags
162
163 Enables tag declarations.
164
165 Defaults to enabled; use --no-tags to disable.
166
167 --commodities
168
169 Enables commodity declarations.
170
171 Defaults to enabled; use --no-commodities to disable.
172
173 --budget
174
175 Enables budget transactions.
176
177 Budget transactions are only supported by the Ledger format (for now).
178 This option is silently ignored otherwise.
179
180 Defaults to enabled; use --no-budget to disable.
181
182 --opening-date DATE
183
184 Specify the opening date for the "opening balances" transaction. This
185 transaction is created (if needed) to support HomeBank's ability to
186 configure accounts with opening balances.
187
188 Date must be in the form "YYYY-MM-DD". Defaults to the date of the
189 first transaction.
190
191 --rename-account STR
192
193 Specifies a mapping for renaming accounts in the output. By default
194 homebank2ledger tries to come up with sensible account names (based on
195 your HomeBank accounts and categories) that fit into five root
196 accounts:
197
198 * Assets
199
200 * Liabilities
201
202 * Equity
203
204 * Income
205
206 * Expenses
207
208 The value of the argument must be of the form "REGEXP=REPLACEMENT". See
209 "EXAMPLES".
210
211 Can be repeated to rename multiple accounts.
212
213 --exclude-account STR
214
215 Specifies an account that will not be included in the output. All
216 transactions related to this account will be skipped.
217
218 Can be repeated to exclude multiple accounts.
219
220 EXAMPLES
221
222 Basic usage
223
224 # Convert homebank.xhb to a Ledger-compatible file:
225 homebank2ledger path/to/homebank.xhb -o ledger.dat
226
227 # Run the Ledger balance report:
228 ledger -f ledger.dat balance
229
230 You can also combine this into one command:
231
232 homebank2ledger path/to/homebank.xhb | ledger -f - balance
233
234 Account renaming
235
236 With the "--rename-account STR" argument, you have some control over
237 the resulting account structure. This may be useful in cases where the
238 organization imposed (or encouraged) by HomeBank doesn't necessarily
239 line up with an ideal double-entry structure.
240
241 homebank2ledger path/to/homebank.xhb -o ledger.dat \
242 --rename-account '^Assets:Credit Union Savings$=Assets:Bank:Credit Union:Savings' \
243 --rename-account '^Assets:Credit Union Checking$=Assets:Bank:Credit Union:Checking'
244
245 Multiple accounts can be renamed at the same time because the first
246 part of the mapping is a regular expression. The above example could be
247 written like this:
248
249 homebank2ledger path/to/homebank.xhb -o ledger.dat \
250 --rename-account '^Assets:Credit Union =Assets:Bank:Credit Union:'
251
252 You can also merge accounts by simple renaming multiple accounts to the
253 same name:
254
255 homebank2ledger path/to/homebank.xhb -o ledger.dat \
256 --rename-account '^Liabilities:Chase VISA$=Liabilities:All Credit Cards' \
257 --rename-account '^Liabilities:Amex$=Liabilities:All Credit Cards'
258
259 If you need to do anything more complicated, of course you can edit the
260 output after converting; it's just plain text.
261
262 Beancount
263
264 # Convert homebank.xhb to a Beancount-compatible file:
265 homebank2ledger path/to/homebank.xhb -f beancount -o ledger.beancount
266
267 # Run the balances report:
268 bean-report ledger.beancount balances
269
270 CAVEATS
271
272 * I didn't intend to make this a releasable robust product, so it's
273 lacking tests.
274
275 * Scheduled transactions are not (yet) converted.
276
277 * There are some minor formatting tweaks I will make (e.g.
278 consolidate transaction tags and payees)
279
280 BUGS
281
282 Please report any bugs or feature requests on the bugtracker website
283 https://github.com/chazmcgarvey/homebank2ledger/issues
284
285 When submitting a bug or request, please include a test-file or a patch
286 to an existing test-file that illustrates the bug or desired feature.
287
288 AUTHOR
289
290 Charles McGarvey <chazmcgarvey@brokenzipper.com>
291
292 COPYRIGHT AND LICENSE
293
294 This software is Copyright (c) 2019 by Charles McGarvey.
295
296 This is free software, licensed under:
297
298 The MIT (X11) License
299
This page took 0.042992 seconds and 3 git commands to generate.