X-Git-Url: https://git.dogcows.com/gitweb?a=blobdiff_plain;ds=sidebyside;f=README;h=9a40d413453d06f00ac239afaae136a39bccd094;hb=e325852aa9ca67592ca857dd4f38cb3f13a97715;hp=edf80f67b68867f093deecf76776401eb0fd5934;hpb=71591e40fa4a522e41ed7283cce39780f4ef8cb5;p=chaz%2Fhomebank2ledger
diff --git a/README b/README
index edf80f6..9a40d41 100644
--- a/README
+++ b/README
@@ -1,52 +1,281 @@
NAME
- App::HomeBank2Ledger - A tool to convert HomeBank files to Ledger
- format
+ homebank2ledger - A tool to convert HomeBank files to Ledger format
VERSION
- version 0.001
+ version 0.008
SYNOPSIS
- App::HomeBank2Ledger->main(@args);
+ 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]
+ [--rename-account STR]... [--exclude-account STR]...
DESCRIPTION
- This module is part of the homebank2ledger script.
+ homebank2ledger converts HomeBank files to a
+ format usable by Ledger . It can also
+ convert directly to the similar Beancount
+ format.
-METHODS
+ This software is EXPERIMENTAL, in early development. Its interface may
+ change without notice.
- main
+ 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.
- App::HomeBank2Ledger->main(@args);
+ Features
- Run the script and exit; does not return.
+ * Converts HomeBank accounts and categories into a typical set of
+ double-entry accounts.
- formatter
+ * Retains HomeBank metadata, including payees and tags.
- $formatter = $app->formatter($homebank, $opts);
+ * Offers some customization of the output ledger, like account
+ renaming.
- Generate a App::HomeBank2Ledger::Formatter.
+ This program is feature-complete in my opinion (well, almost -- see
+ "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!
- convert_homebank_to_ledger
+ Use cases
- my $ledger = $app->convert_homebank_to_ledger($homebank, $opts);
+ You can migrate the data you have in HomeBank so you can start
+ maintaining your accounts in Ledger (or Beancount).
- Converts a File::HomeBank to a App::HomeBank2Ledger::Ledger.
+ 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.
- print_to_file
+INSTALL
- $app->print_to_file($str);
- $app->print_to_file($str, $filepath);
+ There are several ways to install homebank2ledger to your system.
- Print a string to a file (or STDOUT).
+ using cpanm
- parse_args
+ You can install homebank2ledger using cpanm. If you have a local perl
+ (plenv, perlbrew, etc.), you can just do:
- $opts = $app->parse_args(@args);
+ cpanm App::Homebank2Ledger
- Parse command-line arguments.
+ to install the homebank2ledger executable and its dependencies. The
+ executable will be installed to your perl's bin path, like
+ ~/perl5/perlbrew/bin/homebank2ledger.
+
+ If you're installing to your system perl, you can do:
+
+ cpanm --sudo App::Homebank2Ledger
+
+ to install the homebank2ledger executable to a system directory, like
+ /usr/local/bin/homebank2ledger (depending on your perl).
+
+ Downloading just the executable
+
+ You may also choose to download homebank2ledger as a single executable,
+ like this:
+
+ curl -OL https://raw.githubusercontent.com/chazmcgarvey/homebank2ledger/solo/homebank2ledger
+ chmod +x homebank2ledger
+
+ For developers
+
+ If you're a developer and want to hack on the source, clone the
+ repository and pull the dependencies:
+
+ git clone https://github.com/chazmcgarvey/homebank2ledger.git
+ cd homebank2ledger
+ make bootstrap # installs dependencies; requires cpanm
+
+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.
+
+ --budget
+
+ Enables budget transactions.
+
+ Budget transactions are only supported by the Ledger format (for now).
+ This option is silently ignored otherwise.
+
+ Defaults to enabled; use --no-budget 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.
+
+ --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".
+
+ 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" 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.
+
+ * Scheduled transactions are not (yet) converted.
+
+ * There are some minor formatting tweaks I will make (e.g.
+ consolidate transaction tags and payees)
BUGS