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