The buchhaltung package

This is a package candidate release! Here you can preview how this package release will appear once published to the main package index (which can be accomplished via the 'maintain' link below). Please note that once a package has been published to the main package index it cannot be undone! Please consult the package uploading documentation for more information.

[maintain]

ATTENTION Use `stack build` as this package requires a developement version of hledger! Automatic import and deduplication (from CSV/FinTS/HBCI/OFX), bayesian account matching, and efficient manual entry of ledger transactions.

See Readme on Github.


[Skip to ReadMe]

Properties

Versions0.0.1, 0.0.1, 0.0.2, 0.0.3, 0.0.4, 0.0.5
Change logNone available
Dependenciesaeson (>=1.0.0), ansi-wl-pprint, array, async, base (>=4.0.0.0 && <5), boxes, bytestring, cassava (>=0.4.1.0), containers, data-default, Decimal (>=0.4.2), deepseq, directory, edit-distance, file-embed, filepath, formatting, hashable, haskeline, hint, hledger (>=1.0.0), hledger-lib (>=1.0.0), lens, lifted-base, ListLike, megaparsec (>=5.0.0), MissingH, monad-control, mtl, optparse-applicative (>=0.13), parsec, process (>=1.1.0.2), regex-compat, regex-tdfa, regex-tdfa-text, safe, semigroups, split, strict, temporary, text, time, transformers, unordered-containers, vector, yaml [details]
LicenseMIT
AuthorJohannes Gerer
MaintainerJohannes Gerer <oss@johannesgerer.com>
CategoryFinance
Home pagehttp://johannesgerer.com/buchhaltung
Bug trackerhttp://github.com/johannesgerer/buchhaltung/issues
Source repositoryhead: git clone http://github.com/johannesgerer/buchhaltung
Executablesbuchhaltung
UploadedWed Dec 21 00:45:51 UTC 2016 by johannesgerer

Downloads

Maintainers' corner

For package maintainers and hackage trustees


Readme for buchhaltung-0.0.1

[back to package description]

Buchhaltung Build Status

What advantages does he derive from the system of book-keeping by double entry! It is among the finest inventions of the human mind; every prudent master of a house should introduce it into his economy. -- Johann Wolfgang von Goethe

Buchhaltung (['buːχˌhaltʊŋ], German book keeping), written in Haskell, helps you keep track of your finances on the commandline with minimal effort. It provides tools that help you in creating a complete ledger of all your bank and savings accounts', credit cards', and other transactions, in a text-based ledger format, that is readable by the ledger CLI tool and its many derivatives.

Status & aim

I am actively and successfully using this software since 2010 and my ledger now contains more than 12.000 transactions accurately and continuously tracking the finances of my spouse and me including four checking and two savings accounts, one credit card, two paypal accounts, two cash wallets in EUR, bitcoin trading (both physical and on exchanges) and other currencies like USD, GPB used on trips.

The software is in alpha phase and I am looking for early adopters and their use cases. The aim of this stage is to agree about the functionality and customizability and produce a first shipable version, that can be used without tinkering with the source.

Right now, I am using it on Linux but it should also run wherever GHC runs.

Installation

Prerequisites

Download, compile & install

# download
git clone https://github.com/johannesgerer/buchhaltung.git
cd buchhaltung


# compile and install (usually in ~/.local/bin)
stack install

Configure

  1. Create a folder that will hold all your config and possibly ledger files:

    mkdir ~/.buchhaltung
    cp /path/to/buchhaltung/config.yml ~/.buchhaltung/config.yml
    

    If you want a folder under a different location, either create a symlink or set the BUCHHALTUNG environment variable to that location.

  2. Edit the config.yml.

  3. Make sure the configured ledger files exist.

Getting help

Usage

First usage / clean

To initialize AqBanking after you edited the config file, you need to run:

buchhaltung setup

To clean everythink aqbanking related remove the configured aqBanking.configDir and rerun the setup command.

Manual AqBanking setup

Currently only the PinTan method is supportend (pull requests welcome). For other methods or if the AqBanking setup fails due to other reasons, you can configure AqBanking manually into the configured aqBanking.configDir (see for help here or here, usually via aqhbci-tool4 -C <aqBanking.configDir>).

Importing transactions

There various ways (including from PayPal CSV files) to import transactions into your configured ledgers.imported file. They are presented in the folling, but consult

buchhaltung import -h

and the -h calls to its subcommands to see the currently available functionality.

The accounts of the imported transactions will be taken from the configured bankAccounts and the offsetting balaence will be posted to an account named TODO, and will be replaced by match.

The original source information will be included in the second posting's comment and used for learning the account mappings and to find and handle duplicates.

AqBanking

buchhaltung update

This command fetches and imports all available transactions from all configured AqBanking connections.

Resolve duplicates

Banks often minimally change the way they report transactions which leads to unwanted duplicates.

When importing, Buchhaltung will identify duplicates based on ([(Commodity,Quantity)], AccountName, Day) and interactively resolve them by showing the user what fields have changed. If there are several candidates, it sorts the candidates according to similarity using levenshteinDistance from edit-distance. (See Buchhaltung.Uniques.addNew)

Match accounts

buchhaltung match

This command asks the user for the offsetting accounts of imported transactions, or more specifically, transaction whose second posting's account begins with TODO.

Have a look at the example output here.

The significantly speed up this process, it learns the account mapping from existing transactions in the configured ledgers.imported file using the original source of the imported tansaction.

See this information about the account input field.

Best practices

The Bayesian classifier can only work if similar transactions are always matched with the same account.

Consider frequent credit card payments to Starbucks:

Enter transactions

buchhaltung add

This command opens a transaction editor. Here is an example of the output of this command.

The amount of manual typing is kept to a minimum by two clever suggestion mechanisms and TAB completion.

Input and TAB completion

All input fields save their history in the current directory. It can be browsed using up and down arrow keys.

The account input fields support TAB completion. To make this even more useful, the account hierarchy is read in reverse order. For example Expenses:Food has to be entered as Food:Expenses.

Suggested transactions

After the amount is entered, the user can select a transaction whose title, date, amount and second posting's account will used to prefill an offsetting transaction. Suggestions will consist of all transactions

Suggested accounts

Once the first posting's account has been entered, the editor suggests accounts for the second posting based on the frequecy of the resulting transaction's accounts in the configured ledgers.addedByThisUser file.

Assertions & assignments

Amounts can be entered with assertions or can be assigned.

Default currency

In order to be able to enter naked amounts and have the currency added automatically, add a default currency to the configured addedByThisUser ledger file. Example:

D 1,000.000 EUR

Multi-user add

buchhaltung add -w alice

If there is more than one user configured — possibly each with their own ledger, they can be included/activated via the commandline argument -w. This enables you to enter a transaction where postings belong to different users. When done, a transaction for each user will be generated containing their respective postings and a balancing posting to an account prefixed with the configured accountPrefixOthers.

Example taken from the output of the above command:

#~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

2016/12/19 Dinner

        Account          |  Amount  | Assertion
-------------------------+----------+-----------+----------
0,jo    Wallet:Assets    | $ -100.0 |           |
1,jo    Food:Expenses    | $ 50     |           |
2,alice Food:Expenses    | $ 50     |           |
-------------------------+----------+-----------+----------
Open Balance             | 0        |

generates the following transactions

#######  jo:  Balanced Transaction   #######

2016/12/19 Dinner    ; Entered on "2016-12-19T19:01:00Z" by 'buchhaltung' user jo
    Wallet:Assets                             $ -100.0
    Food:Expenses                                 $ 50
    Accounts receivable:Friends:alice:jo          $ 50



#######  alice:  Balanced Transaction   #######

2016/12/19 Dinner    ; Entered on "2016-12-19T19:01:00Z" by 'buchhaltung' user jo
    Accounts receivable:Friends:jo:jo         $ -50
    Food:Expenses                              $ 50

Getting results

Get current AqBanking account balances

buchhaltung lb

Call ledger or hledger

buchhaltung ledger

buchhaltung hledger

This calls the respective program with the LEDGER environment variable set to the configured mainLedger or mainHledger.

Commit the changes

buchhaltung commit -a -m'checking account ok'

this commits all changes to the git repository that contains the mainLedger file. The commit message will also contain the output of buchhaltung lb and buchhaltung ledger balance --end tomorrow.