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