Dogcows Code - chaz/homebank2ledger/blob - README.md

   1 # NAME
   2
   3 homebank2ledger - A tool to convert HomeBank files to Ledger format
   4
   5 # VERSION
   6
   7 version 0.008
   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