Dogcows Code - chaz/homebank2ledger/blob - README

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