fa5bb6a40d9d1a648ac0d6edf4dc730d2114e6ff
[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.003
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 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 # OPTIONS
52
53 ## --version
54
55 Print the version and exit.
56
57 Alias: `-V`
58
59 ## --help
60
61 Print help/usage info and exit.
62
63 Alias: `-h`, `-?`
64
65 ## --manual
66
67 Print the full manual and exit.
68
69 Alias: `--man`
70
71 ## --input FILEPATH
72
73 Specify the path to the HomeBank file to read (must already exist).
74
75 Alias: `--file`, `-i`
76
77 ## --output FILEPATH
78
79 Specify the path to the Ledger file to write (may not exist yet). If not provided, the formatted
80 ledger will be printed on `STDOUT`.
81
82 Alias: `-o`
83
84 ## --format STR
85
86 Specify the output file format. If provided, must be one of:
87
88 - ledger
89 - beancount
90
91 ## --account-width NUM
92
93 Specify the number of characters to reserve for the account column in transactions. Adjusting this
94 can provide prettier formatting of the output.
95
96 Defaults to 40.
97
98 ## --accounts
99
100 Enables account declarations.
101
102 Defaults to enabled; use `--no-accounts` to disable.
103
104 ## --payees
105
106 Enables payee declarations.
107
108 Defaults to enabled; use `--no-payees` to disable.
109
110 ## --tags
111
112 Enables tag declarations.
113
114 Defaults to enabled; use `--no-tags` to disable.
115
116 ## --commodities
117
118 Enables commodity declarations.
119
120 Defaults to enabled; use `--no-commodities` to disable.
121
122 ## --opening-date DATE
123
124 Specify the opening date for the "opening balances" transaction. This transaction is created (if
125 needed) to support HomeBank's ability to configure accounts with opening balances.
126
127 Date must be in the form "YYYY-MM-DD". Defaults to the date of the first transaction.
128
129 ## --default-account STR
130
131 Specify the account to use for one-sided transactions (if any). Defaults to "Expenses:No Category".
132
133 A default account may be necessary because with Ledger all transactions are double-entry.
134
135 ## --rename-account STR
136
137 Specifies a mapping for renaming accounts in the output. By default `homebank2ledger` tries to come
138 up with sensible account names (based on your HomeBank accounts and categories) that fit into five
139 root accounts:
140
141 - Assets
142 - Liabilities
143 - Equity
144 - Income
145 - Expenses
146
147 The value of the argument must be of the form "REGEXP=REPLACEMENT". See ["EXAMPLES"](#examples).
148
149 Can be repeated to rename multiple accounts.
150
151 ## --exclude-account STR
152
153 Specifies an account that will not be included in the output. All transactions related to this
154 account will be skipped.
155
156 Can be repeated to exclude multiple accounts.
157
158 # EXAMPLES
159
160 ## Basic usage
161
162 # Convert homebank.xhb to a Ledger-compatible file:
163 homebank2ledger path/to/homebank.xhb -o ledger.dat
164
165 # Run the Ledger balance report:
166 ledger -f ledger.dat balance
167
168 You can also combine this into one command:
169
170 homebank2ledger path/to/homebank.xhb | ledger -f - balance
171
172 ## Account renaming
173
174 With the ["--rename-account STR"](#rename-account-str) argument, you have some control over the resulting account
175 structure. This may be useful in cases where the organization imposed (or encouraged) by HomeBank
176 doesn't necessarily line up with an ideal double-entry structure.
177
178 homebank2ledger path/to/homebank.xhb -o ledger.dat \
179 --rename-account '^Assets:Credit Union Savings$=Assets:Bank:Credit Union:Savings' \
180 --rename-account '^Assets:Credit Union Checking$=Assets:Bank:Credit Union:Checking'
181
182 Multiple accounts can be renamed at the same time because the first part of the mapping is a regular
183 expression. The above example could be written like this:
184
185 homebank2ledger path/to/homebank.xhb -o ledger.dat \
186 --rename-account '^Assets:Credit Union =Assets:Bank:Credit Union:'
187
188 You can also merge accounts by simple renaming multiple accounts to the same name:
189
190 homebank2ledger path/to/homebank.xhb -o ledger.dat \
191 --rename-account '^Liabilities:Chase VISA$=Liabilities:All Credit Cards' \
192 --rename-account '^Liabilities:Amex$=Liabilities:All Credit Cards'
193
194 If you need to do anything more complicated, of course you can edit the output after converting;
195 it's just plain text.
196
197 ## Beancount
198
199 # Convert homebank.xhb to a Beancount-compatible file:
200 homebank2ledger path/to/homebank.xhb -f beancount -o ledger.beancount
201
202 # Run the balances report:
203 bean-report ledger.beancount balances
204
205 # CAVEATS
206
207 - I didn't intend to make this a releasable robust product, so it's lacking tests.
208 - Budgets and scheduled transactions are not (yet) converted.
209 - There are some minor formatting tweaks I will make (e.g. consolidate transaction tags and payees)
210
211 # BUGS
212
213 Please report any bugs or feature requests on the bugtracker website
214 [https://github.com/chazmcgarvey/homebank2ledger/issues](https://github.com/chazmcgarvey/homebank2ledger/issues)
215
216 When submitting a bug or request, please include a test-file or a
217 patch to an existing test-file that illustrates the bug or desired
218 feature.
219
220 # AUTHOR
221
222 Charles McGarvey <chazmcgarvey@brokenzipper.com>
223
224 # COPYRIGHT AND LICENSE
225
226 This software is Copyright (c) 2019 by Charles McGarvey.
227
228 This is free software, licensed under:
229
230 The MIT (X11) License
This page took 0.038855 seconds and 3 git commands to generate.