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.005
   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 # 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 ## --budget
 123
 124 Enables budget transactions.
 125
 126 Budget transactions are only supported by the Ledger format (for now). This option is silently
 127 ignored otherwise.
 128
 129 Defaults to enabled; use `--no-budget` to disable.
 130
 131 ## --opening-date DATE
 132
 133 Specify the opening date for the "opening balances" transaction. This transaction is created (if
 134 needed) to support HomeBank's ability to configure accounts with opening balances.
 135
 136 Date must be in the form "YYYY-MM-DD". Defaults to the date of the first transaction.
 137
 138 ## --rename-account STR
 139
 140 Specifies a mapping for renaming accounts in the output. By default `homebank2ledger` tries to come
 141 up with sensible account names (based on your HomeBank accounts and categories) that fit into five
 142 root accounts:
 143
 144 - Assets
 145 - Liabilities
 146 - Equity
 147 - Income
 148 - Expenses
 149
 150 The value of the argument must be of the form "REGEXP=REPLACEMENT". See ["EXAMPLES"](#examples).
 151
 152 Can be repeated to rename multiple accounts.
 153
 154 ## --exclude-account STR
 155
 156 Specifies an account that will not be included in the output. All transactions related to this
 157 account will be skipped.
 158
 159 Can be repeated to exclude multiple accounts.
 160
 161 # EXAMPLES
 162
 163 ## Basic usage
 164
 165     # Convert homebank.xhb to a Ledger-compatible file:
 166     homebank2ledger path/to/homebank.xhb -o ledger.dat
 167
 168     # Run the Ledger balance report:
 169     ledger -f ledger.dat balance
 170
 171 You can also combine this into one command:
 172
 173     homebank2ledger path/to/homebank.xhb | ledger -f - balance
 174
 175 ## Account renaming
 176
 177 With the ["--rename-account STR"](#rename-account-str) argument, you have some control over the resulting account
 178 structure. This may be useful in cases where the organization imposed (or encouraged) by HomeBank
 179 doesn't necessarily line up with an ideal double-entry structure.
 180
 181     homebank2ledger path/to/homebank.xhb -o ledger.dat \
 182         --rename-account '^Assets:Credit Union Savings$=Assets:Bank:Credit Union:Savings' \
 183         --rename-account '^Assets:Credit Union Checking$=Assets:Bank:Credit Union:Checking'
 184
 185 Multiple accounts can be renamed at the same time because the first part of the mapping is a regular
 186 expression. The above example could be written like this:
 187
 188     homebank2ledger path/to/homebank.xhb -o ledger.dat \
 189         --rename-account '^Assets:Credit Union =Assets:Bank:Credit Union:'
 190
 191 You can also merge accounts by simple renaming multiple accounts to the same name:
 192
 193     homebank2ledger path/to/homebank.xhb -o ledger.dat \
 194         --rename-account '^Liabilities:Chase VISA$=Liabilities:All Credit Cards' \
 195         --rename-account '^Liabilities:Amex$=Liabilities:All Credit Cards'
 196
 197 If you need to do anything more complicated, of course you can edit the output after converting;
 198 it's just plain text.
 199
 200 ## Beancount
 201
 202     # Convert homebank.xhb to a Beancount-compatible file:
 203     homebank2ledger path/to/homebank.xhb -f beancount -o ledger.beancount
 204
 205     # Run the balances report:
 206     bean-report ledger.beancount balances
 207
 208 # CAVEATS
 209
 210 - I didn't intend to make this a releasable robust product, so it's lacking tests.
 211 - Scheduled transactions are not (yet) converted.
 212 - There are some minor formatting tweaks I will make (e.g. consolidate transaction tags and payees)
 213
 214 # BUGS
 215
 216 Please report any bugs or feature requests on the bugtracker website
 217 [https://github.com/chazmcgarvey/homebank2ledger/issues](https://github.com/chazmcgarvey/homebank2ledger/issues)
 218
 219 When submitting a bug or request, please include a test-file or a
 220 patch to an existing test-file that illustrates the bug or desired
 221 feature.
 222
 223 # AUTHOR
 224
 225 Charles McGarvey <chazmcgarvey@brokenzipper.com>
 226
 227 # COPYRIGHT AND LICENSE
 228
 229 This software is Copyright (c) 2019 by Charles McGarvey.
 230
 231 This is free software, licensed under:
 232
 233     The MIT (X11) License