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.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
  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 INSTALL
  62
  63     There are several ways to install homebank2ledger to your system.
  64
  65  using cpanm
  66
  67     You can install homebank2ledger using cpanm. If you have a local perl
  68     (plenv, perlbrew, etc.), you can just do:
  69
  70         cpanm App::Homebank2Ledger
  71
  72     to install the homebank2ledger executable and its dependencies. The
  73     executable will be installed to your perl's bin path, like
  74     ~/perl5/perlbrew/bin/homebank2ledger.
  75
  76     If you're installing to your system perl, you can do:
  77
  78         cpanm --sudo App::Homebank2Ledger
  79
  80     to install the homebank2ledger executable to a system directory, like
  81     /usr/local/bin/homebank2ledger (depending on your perl).
  82
  83  Downloading just the executable
  84
  85     You may also choose to download homebank2ledger as a single executable,
  86     like this:
  87
  88         curl -OL https://raw.githubusercontent.com/chazmcgarvey/homebank2ledger/solo/homebank2ledger
  89         chmod +x homebank2ledger
  90
  91  For developers
  92
  93     If you're a developer and want to hack on the source, clone the
  94     repository and pull the dependencies:
  95
  96         git clone https://github.com/chazmcgarvey/homebank2ledger.git
  97         cd homebank2ledger
  98         make bootstrap      # installs dependencies; requires cpanm
  99
 100 OPTIONS
 101
 102  --version
 103
 104     Print the version and exit.
 105
 106     Alias: -V
 107
 108  --help
 109
 110     Print help/usage info and exit.
 111
 112     Alias: -h, -?
 113
 114  --manual
 115
 116     Print the full manual and exit.
 117
 118     Alias: --man
 119
 120  --input FILEPATH
 121
 122     Specify the path to the HomeBank file to read (must already exist).
 123
 124     Alias: --file, -i
 125
 126  --output FILEPATH
 127
 128     Specify the path to the Ledger file to write (may not exist yet). If
 129     not provided, the formatted ledger will be printed on STDOUT.
 130
 131     Alias: -o
 132
 133  --format STR
 134
 135     Specify the output file format. If provided, must be one of:
 136
 137       * ledger
 138
 139       * beancount
 140
 141  --account-width NUM
 142
 143     Specify the number of characters to reserve for the account column in
 144     transactions. Adjusting this can provide prettier formatting of the
 145     output.
 146
 147     Defaults to 40.
 148
 149  --accounts
 150
 151     Enables account declarations.
 152
 153     Defaults to enabled; use --no-accounts to disable.
 154
 155  --payees
 156
 157     Enables payee declarations.
 158
 159     Defaults to enabled; use --no-payees to disable.
 160
 161  --tags
 162
 163     Enables tag declarations.
 164
 165     Defaults to enabled; use --no-tags to disable.
 166
 167  --commodities
 168
 169     Enables commodity declarations.
 170
 171     Defaults to enabled; use --no-commodities to disable.
 172
 173  --budget
 174
 175     Enables budget transactions.
 176
 177     Budget transactions are only supported by the Ledger format (for now).
 178     This option is silently ignored otherwise.
 179
 180     Defaults to enabled; use --no-budget to disable.
 181
 182  --opening-date DATE
 183
 184     Specify the opening date for the "opening balances" transaction. This
 185     transaction is created (if needed) to support HomeBank's ability to
 186     configure accounts with opening balances.
 187
 188     Date must be in the form "YYYY-MM-DD". Defaults to the date of the
 189     first transaction.
 190
 191  --rename-account STR
 192
 193     Specifies a mapping for renaming accounts in the output. By default
 194     homebank2ledger tries to come up with sensible account names (based on
 195     your HomeBank accounts and categories) that fit into five root
 196     accounts:
 197
 198       * Assets
 199
 200       * Liabilities
 201
 202       * Equity
 203
 204       * Income
 205
 206       * Expenses
 207
 208     The value of the argument must be of the form "REGEXP=REPLACEMENT". See
 209     "EXAMPLES".
 210
 211     Can be repeated to rename multiple accounts.
 212
 213  --exclude-account STR
 214
 215     Specifies an account that will not be included in the output. All
 216     transactions related to this account will be skipped.
 217
 218     Can be repeated to exclude multiple accounts.
 219
 220 EXAMPLES
 221
 222  Basic usage
 223
 224         # Convert homebank.xhb to a Ledger-compatible file:
 225         homebank2ledger path/to/homebank.xhb -o ledger.dat
 226
 227         # Run the Ledger balance report:
 228         ledger -f ledger.dat balance
 229
 230     You can also combine this into one command:
 231
 232         homebank2ledger path/to/homebank.xhb | ledger -f - balance
 233
 234  Account renaming
 235
 236     With the "--rename-account STR" argument, you have some control over
 237     the resulting account structure. This may be useful in cases where the
 238     organization imposed (or encouraged) by HomeBank doesn't necessarily
 239     line up with an ideal double-entry structure.
 240
 241         homebank2ledger path/to/homebank.xhb -o ledger.dat \
 242             --rename-account '^Assets:Credit Union Savings$=Assets:Bank:Credit Union:Savings' \
 243             --rename-account '^Assets:Credit Union Checking$=Assets:Bank:Credit Union:Checking'
 244
 245     Multiple accounts can be renamed at the same time because the first
 246     part of the mapping is a regular expression. The above example could be
 247     written like this:
 248
 249         homebank2ledger path/to/homebank.xhb -o ledger.dat \
 250             --rename-account '^Assets:Credit Union =Assets:Bank:Credit Union:'
 251
 252     You can also merge accounts by simple renaming multiple accounts to the
 253     same name:
 254
 255         homebank2ledger path/to/homebank.xhb -o ledger.dat \
 256             --rename-account '^Liabilities:Chase VISA$=Liabilities:All Credit Cards' \
 257             --rename-account '^Liabilities:Amex$=Liabilities:All Credit Cards'
 258
 259     If you need to do anything more complicated, of course you can edit the
 260     output after converting; it's just plain text.
 261
 262  Beancount
 263
 264         # Convert homebank.xhb to a Beancount-compatible file:
 265         homebank2ledger path/to/homebank.xhb -f beancount -o ledger.beancount
 266
 267         # Run the balances report:
 268         bean-report ledger.beancount balances
 269
 270 CAVEATS
 271
 272       * I didn't intend to make this a releasable robust product, so it's
 273       lacking tests.
 274
 275       * Scheduled transactions are not (yet) converted.
 276
 277       * There are some minor formatting tweaks I will make (e.g.
 278       consolidate transaction tags and payees)
 279
 280 BUGS
 281
 282     Please report any bugs or feature requests on the bugtracker website
 283     https://github.com/chazmcgarvey/homebank2ledger/issues
 284
 285     When submitting a bug or request, please include a test-file or a patch
 286     to an existing test-file that illustrates the bug or desired feature.
 287
 288 AUTHOR
 289
 290     Charles McGarvey <chazmcgarvey@brokenzipper.com>
 291
 292 COPYRIGHT AND LICENSE
 293
 294     This software is Copyright (c) 2019 by Charles McGarvey.
 295
 296     This is free software, licensed under:
 297
 298       The MIT (X11) License
 299