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