From f9bb13a3d3fcf3f3fcd2d85217e79967513299cb Mon Sep 17 00:00:00 2001 From: Charles McGarvey Date: Wed, 12 Jun 2019 23:05:12 -0600 Subject: [PATCH] add README --- README.md | 230 ++++++++++++++++++++++++++++++++++++++++++++ bin/homebank2ledger | 5 +- 2 files changed, 232 insertions(+), 3 deletions(-) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..8c560b1 --- /dev/null +++ b/README.md @@ -0,0 +1,230 @@ +# NAME + +homebank2ledger - A tool to convert HomeBank files to Ledger format + +# VERSION + +version 0.001 + +# SYNOPSIS + + homebank2ledger --input FILEPATH [--output FILEPATH] [--format FORMAT] + [--version|--help|--manual] [--account-width NUM] + [--accounts|--no-accounts] [--payees|--no-payees] + [--tags|--no-tags] [--commodities|--no-commodities] + [--opening-date DATE] [--default-account STR] + [--rename-account STR]... [--exclude-account STR]... + +# DESCRIPTION + +`homebank2ledger` converts [HomeBank](http://homebank.free.fr/) files to a format usable by +[Ledger](https://www.ledger-cli.org/). It can also convert directly to the similar +[Beancount](http://furius.ca/beancount/) format. + +This software is **EXPERIMENTAL**, in early development. Its interface may change without notice. + +I wrote `homebank2ledger` because I have been maintaining my own personal finances using HomeBank +(which is awesome) and I wanted to investigate using plain text accounting programs. It works well +enough for my data, but you may be using HomeBank features that I don't so there may be cases this +doesn't handle well or at all. Feel free to file a bug report. This script does NOT try to modify +the original HomeBank files it converts from, so there won't be any crazy data loss bugs... but no +warranty. + +## Features + +- Converts HomeBank accounts and categories into a typical set of double-entry accounts. +- Retains HomeBank metadata, including payees and tags. +- Offers some customization of the output ledger, like account renaming. + +This program is feature-complete in my opinion (well, almost -- see ["CAVEATS"](#caveats)), but if there is +anything you think it could do to be even better, feedback is welcome; just file a bug report. Or +fork the code and have fun! + +## Use cases + +You can migrate the data you have in HomeBank so you can start maintaining your accounts in Ledger +(or Beancount). + +Or if you don't plan to switch completely off of HomeBank, you can continue to maintain your +accounts in HomeBank and use this script to also take advantage of the reports Ledger offers. + +# OPTIONS + +## --version + +Print the version and exit. + +Alias: `-V` + +## --help + +Print help/usage info and exit. + +Alias: `-h`, `-?` + +## --manual + +Print the full manual and exit. + +Alias: `--man` + +## --input FILEPATH + +Specify the path to the HomeBank file to read (must already exist). + +Alias: `--file`, `-i` + +## --output FILEPATH + +Specify the path to the Ledger file to write (may not exist yet). If not provided, the formatted +ledger will be printed on `STDOUT`. + +Alias: `-o` + +## --format STR + +Specify the output file format. If provided, must be one of: + +- ledger +- beancount + +## --account-width NUM + +Specify the number of characters to reserve for the account column in transactions. Adjusting this +can provide prettier formatting of the output. + +Defaults to 40. + +## --accounts + +Enables account declarations. + +Defaults to enabled; use `--no-accounts` to disable. + +## --payees + +Enables payee declarations. + +Defaults to enabled; use `--no-payees` to disable. + +## --tags + +Enables tag declarations. + +Defaults to enabled; use `--no-tags` to disable. + +## --commodities + +Enables commodity declarations. + +Defaults to enabled; use `--no-commodities` to disable. + +## --opening-date DATE + +Specify the opening date for the "opening balances" transaction. This transaction is created (if +needed) to support HomeBank's ability to configure accounts with opening balances. + +Date must be in the form "YYYY-MM-DD". Defaults to the date of the first transaction. + +## --default-account STR + +Specify the account to use for one-sided transactions (if any). Defaults to "Expenses:No Category". + +A default account may be necessary because with Ledger all transactions are double-entry. + +## --rename-account STR + +Specifies a mapping for renaming accounts in the output. By default `homebank2ledger` tries to come +up with sensible account names (based on your HomeBank accounts and categories) that fit into five +root accounts: + +- Assets +- Liabilities +- Equity +- Income +- Expenses + +The value of the argument must be of the form "REGEXP=REPLACEMENT". See ["EXAMPLES"](#examples). + +Can be repeated to rename multiple accounts. + +## --exclude-account STR + +Specifies an account that will not be included in the output. All transactions related to this +account will be skipped. + +Can be repeated to exclude multiple accounts. + +# EXAMPLES + +## Basic usage + + # Convert homebank.xhb to a Ledger-compatible file: + homebank2ledger path/to/homebank.xhb -o ledger.dat + + # Run the Ledger balance report: + ledger -f ledger.dat balance + +You can also combine this into one command: + + homebank2ledger path/to/homebank.xhb | ledger -f - balance + +## Account renaming + +With the ["--rename-account STR"](#rename-account-str) argument, you have some control over the resulting account +structure. This may be useful in cases where the organization imposed (or encouraged) by HomeBank +doesn't necessarily line up with an ideal double-entry structure. + + homebank2ledger path/to/homebank.xhb -o ledger.dat \ + --rename-account '^Assets:Credit Union Savings$=Assets:Bank:Credit Union:Savings' \ + --rename-account '^Assets:Credit Union Checking$=Assets:Bank:Credit Union:Checking' + +Multiple accounts can be renamed at the same time because the first part of the mapping is a regular +expression. The above example could be written like this: + + homebank2ledger path/to/homebank.xhb -o ledger.dat \ + --rename-account '^Assets:Credit Union =Assets:Bank:Credit Union:' + +You can also merge accounts by simple renaming multiple accounts to the same name: + + homebank2ledger path/to/homebank.xhb -o ledger.dat \ + --rename-account '^Liabilities:Chase VISA$=Liabilities:All Credit Cards' \ + --rename-account '^Liabilities:Amex$=Liabilities:All Credit Cards' + +If you need to do anything more complicated, of course you can edit the output after converting; +it's just plain text. + +## Beancount + + # Convert homebank.xhb to a Beancount-compatible file: + homebank2ledger path/to/homebank.xhb -f beancount -o ledger.beancount + + # Run the balances report: + bean-report ledger.beancount balances + +# CAVEATS + +- I didn't intend to make this a releasable robust product, so it's lacking tests. +- Budgets and scheduled transactions are not (yet) converted. +- There are some minor formatting tweaks I will make (e.g. consolidate transaction tags and payees) + +# BUGS + +Please report any bugs or feature requests on the bugtracker website +[https://github.com/chazmcgarvey/homebank2ledger/issues](https://github.com/chazmcgarvey/homebank2ledger/issues) + +When submitting a bug or request, please include a test-file or a +patch to an existing test-file that illustrates the bug or desired +feature. + +# AUTHOR + +Charles McGarvey + +# COPYRIGHT AND LICENSE + +This software is Copyright (c) 2019 by Charles McGarvey. + +This is free software, licensed under: + + The MIT (X11) License diff --git a/bin/homebank2ledger b/bin/homebank2ledger index 9ca57d0..43d4b91 100644 --- a/bin/homebank2ledger +++ b/bin/homebank2ledger @@ -4,9 +4,8 @@ =head1 SYNOPSIS - homebank2ledger --input FILEPATH [--output FILEPATH] - [--version|--help|--manual] - [--format FORMAT] [--account-width NUM] + homebank2ledger --input FILEPATH [--output FILEPATH] [--format FORMAT] + [--version|--help|--manual] [--account-width NUM] [--accounts|--no-accounts] [--payees|--no-payees] [--tags|--no-tags] [--commodities|--no-commodities] [--opening-date DATE] [--default-account STR] -- 2.45.2