Using QHacc

QHacc was designed to be as simple and straightforward as possible. It utilizes popups, pulldowns (and other randy-sounding things), keyboard commands, highlighting, and bold fonts to help you organize your finances easily.

Environment Variables

QHacc utilizes a few environmental variables to get itself going. For the most part, QHacc doesn't need any of these environment variables to operate, but they are useful. The variables are:

Command-Line Interface

QHacc is meant to be used interactively from a graphical display. That interface will be used the most by far. However, QHacc has several command-line options. Some of these options can control or modify QHacc's GUI interface, but many are meant to be used when starting a GUI is not possible or unnecessary. Below is a table of QHacc's command-line options.
-f or --home QHACC_HOME1 Using this switch will override whatever value is currently stored in the QHACC_HOME environment variable, if any. This options allows multiple QHACC_HOMEs to be used for different purposes.
-w or --warranty none show warranty information
-l QHACC_LANGDIR Using this switch will point to a non-default language file for i18n support.
--debug debug level (0-6) Set runtime debugging information level. If passed as the first argument, the debugging will be turned on during the QHACC_HOME load. Otherwise, it will be turned on after the initial data load.
--archive a date string2, or account identifier3, and dump location see Archiving below
--restore archive dump location see Archiving below
--report Report Plugin generate a report. seeReporting below
--import QHACC_HOME1 import data from the given QHACC_HOME into the current QHACC_HOME
--export QHACC_HOME1 export the current data to the given QHACC_HOME location
--create QHACC_HOME1 display commands for creating a functional QHACC_HOME from scratch
--reconcile QHACC_HOME1 reconcile all transactions that are duplicated in the given QHACC_HOME
--verifydb none verify that QHacc's database is in a consistent state
--fixdb none make QHacc's database consistent
--plugins none display the information about the available plugins
--help none show these options
1: valid QHACC_HOMEs are determined from the plugins available to the QHacc engine. Generally, these are identified by <plugin identifier;>:<home string>
2: the user-supplied date string must be consistent with the date format specified in the user
preferences dialog. That is, if you normally use the European format and '-' as the separator, and you are currently in the QHACC_HOME directory, the command: qhacc --archive 29-02-2000:/tmp would archive all transactions before 1 March, 2000 to the /tmp directory.
3: an account identifier can be the account's full name, the account's short name, the account number (only if the "Use Account Numbers for Names" preference is selected), or the account's ID. The user-supplied names are checked in that order.
4: a ledger identifier can be the ledger's name or numeric ID. The user-supplied names are checked in that order.


Before running QHacc, the program must know where it is going to save files, and where to look for already-saved ones. It does this through the use of the QHACC_HOME environment variable. This is usually set before running QHacc, but it can be passed via the command line with the --home option. By default, QHacc will assumes the QHACC_HOME is located in a local directory, but various plugins can override that assumption. Regardless of where QHACC_HOME is, QHacc will only write data into that location. It will not create that location for you if it doesn't exist.

Local Files

"Out of the box," QHacc only supports writing to a directory on the local filesystem. In this case, QHacc will look into the specified directory for all its files. In addition, when saving files, it will change their permissions so that only the user running QHacc can open them later. This avoids having possibly sensitive information available to anyone on the system.

Multiple Personalities

QHacc keeps all the information about a set of accounts in QHACC_HOME, but it also allows a user to switch QHACC_HOME during execution. This functionality may be useful if, for example, a user has a set of business accounts in addition to a set of personal accounts, and wishes to keep both sets exclusive. Thus, each QHACC_HOME can be thought of as a different personality. When requested to switch personalities, QHacc closes the old set of accounts without saving them and then opens the new set of accounts. Be sure to save your work before switching personalities.

Interface Layout

The QHacc window consists of just three main parts: the Account Chooser, the Account Viewer, and the Status Bar. The Account Chooser starts on the left side of the screen, and displays all your accounts and their balances. The rest of the screen is devoted to the Account Viewer. The Account Viewer displays all the transactions in a specific account. The Status Bar runs below the Account Viewer and the Account Chooser. It displays information about the currently-opened account such as it name, type of account, number of transactions (in all journals), and account balance. It also notifies the user if any information has been changed since the last save.

The Account Chooser

The Account Chooser is the navigator and maintenance hub for accounts. Clicking on an account will open that account, and display all its transactions in the Account Viewer. Double-clicking on an account will bring up the Account Edit Dialog box. More about that later.

If you are not using a mouse, the Account Chooser is navigable with the up and down arrows. Pressing the spacebar will open the account.

In both cases, the selected account will be printed in bold font and a colored highlight bar will illuminate the account in the Chooser.

The popup menu available in the Account Chooser allows you to reconcile, edit, add, or delete an account. It is not necessary to open an account in order to use these functions. (i.e., You can be viewing your checking account, and open your savings account for reconciling.) Please be careful when using this liberty to make sure you don't delete the wrong account. The popup also allows you to toggle the Account Chooser's view, to show or hide categories. If you are not using a mouse, these functions are available from the Account or Preferences menubar.

The Account Viewer

The Account Viewer displays all the transactions in the opened account. It looks vaguely like a spreadsheet display, with serveral columns and resizeable column headers. Underneath the headers are all the transactions in the account. Clicking on a transaction will open the Transaction Editor. Alternately, you can click on the "<new>" transaction to insert a totally new transaction. Alternately alternately, you can use the keyboard to navigate the Viewer. Using the up and down arrows will select transactions. As with the Account Chooser, pressing the spacebar will open the transaction for editing.

The Account Viewer window has a popup menu to work on the transactions in the viewer. There are standard functions like add, reconcile, and memorize. Please see the section below for more details on memorizing transactions.

The Viewer and Chooser can be sorted on any column. Clicking on a column header sorts the data on that field. Clicking on the same field resorts the column in reverse order. Unlike previous versions of QHacc, these preferences are saved for future use.

Keyboard Shortcuts

QHacc was designed to be usable with or without a mouse. As a result, there are a number of keyboard shortcuts that are available. Some shortcuts are available when the Chooser has focus, and others are available when the Viewer is the focused object. Still others are available globally. The table below summarizes the keyboard shortcuts available in QHacc.
CTRL-S Global Save files.
CTRL-H Global Change QHacc Home
CTRL-T Global Save files and exit QHacc.
CTRL-Q Global Quit QHacc without saving files.
CTRL-V Global Toggle category view of account chooser.
CTRL-B Global Open a subset of transactions for the highlighted account.
CTRL-R Global Open a reconcile window for the highlighted account.
CTRL-L Global Toggle the reconcile balance display in status bar.
CTRL-N Global Create a new account.
CTRL-E Global Open the Account Editor dialog.
CTRL-SHIFT-X Global Delete the highlighted account.
CTRL-G Global Open the Graphing dialog.
CTRL-Y Global Open the Reporting dialog.
CTRL-F Global Open the Preferences dialog.
spacebar Chooser Open the hilighted account in the Viewer.
del Chooser Delete the account hilighted in bold.
del Viewer Delete the transaction hilighted in bold.
CTRL-C Viewer Copy the hilighted transaction.
CTRL-P Viewer Paste the previously-copied transaction.
CTRL-X Global Cut the highlighted transaction.
i Viewer Insert a transaction. This new transaction will have the same date as the previously-hilighted transaction.
e Viewer Edit the hilighted transaction.
spacebar Viewer Open the Transaction Editor for the hilighted transaction.
spacebar Reconcile Window Mark the hilighted transaction as reconciled.

Creating an Account

The account is the central object in the QHacc engine. All transactions must be part of at least one account to be displayed. That said, creating an account is a painless process. You can either right-click in the Account Chooser and select "new account" from the pulldown, or choose "Create" from the Account menubar. From that dialog, you can enter the specifics of the account like opening balance or institution contact information. You can also specify a parent account to further categorize transactions. There are several types of accounts in QHacc:
Note: The MARKET account type has been removed from QHacc version 2.0. Market accounts from previous versions will be upgraded to Equity accounts, and their transactions upgraded to regular transactions. As of version 3.3, however, market transactions are back in attendance.

You can get more information about how to use these accounts in the Accounting Primer.

Accounts can also be made into categories. A category is an account in every sense of the word, but just a little different. Categories are not included when computing a personalities' total equity. There is also a preference item to exclude Categories from the Account Chooser. This preference is available through the Preferences Dialog or the Chooser's popup. This feature allows a user to maintain a eyeball on those accounts that are most important to him/her, while hiding the ones that are less important.

Transaction Operations

QHacc has a number of different types of transactions. They all work in the same way, so using them is easy. All transactions have five main fields:

Normal Transactions

If you use single-entry bookkeeping, most of the transactions you will probably enter into QHacc will be classified as normal transactions. They contain only the fields listed above. As described above, clicking on the "<new>" part of the Account Viewer is the usual way to enter a new transaction. An opened transaction can be saved by hitting the enter key. The changes can be discarded by pressing esc.

Market Transactions

Market transactions were removed from QHacc in v2.0 for various reasons, but support has been tentatively re-enabled as of v 3.3. Market transactions are effectively just regular transactions with a little extra metadata saved as well. Market transactions are denoted in the interface using a special syntax in the deposit (for purchasing shares) or withdrawal (for selling shares) fields of the Transaction Editor. The syntax is number of shares@price per share. For example, the string 10@12.50 means you bought 10 shares at 12.50 per share. The Account Viewer will calculate the transaction balance from these numbers and display the sum in the appropriate field. Since most market transactions also require a commission to be paid, chances are good they'll end up being SPLIT transactions.

Other interface support for market transactions is mostly non-existant at this time. There is a shares report available from the report dialog, but that merely shows the number of shares bought and sold, and the current number of shares held. The future is ripe for expansion at this point.

It should also be noted that for QHacc at the moment, the term "market transaction" really just means buying and selling shares of stock. There is no support for put-options, for example, or anything like that. If you are intersted in such features, feel free to contact me. I'll need your help.

Split/Double-Entry Transactions

Split and Double-Entry transactions are handled the same way in QHacc. In order to use this transaction type, you must specify double entry bookkeeping from the Preferences Dialog.

Double-Entry transactions are just like single-entry transactions, except that each transaction must be part of two accounts. Double-Entry transactions are generally split between an income and expense account, though this rule is not a requirement. In any event, when you specify double entry bookkeeping, the Transaction Editor will get one more field--the double entry account field.

Split Transactions are a special type of transaction where one transaction has many different double-entry pairs. The most common use of this type of transaction is probably for entering your paycheck, I think. Your employer generally pays you one sum, but also pays taxes on your behalf, or splits your paycheck between several different accounts, like a checking and savings account. All these splits can be entered into a different account, but still only take up one transaction in your "job" account, for example. Is that clear?

In order to change a regular double-entry transaction into a good old-fashioned split transaction, one just needs to push the "split" button in the Transaction Editor. This will open the Split Editor, and you can go merrily on your way. If, on the other hand, you have a split transaction that you would like to make into a double-entry transaction, set its sum to "0" or just leave the appropriate sum field blank. When the transaction is saved, splits with 0 balance will be removed.

When using the Split Editor, it is important to remember that transactions are not modified until the Enter key or the "Enter" button is pressed. When the "Okay" button is pressed in the Split Editor, the transaction editor will display updated values, but the transaction is not modified. Opening the Split Editor again will display only the updated values. To get back to the original values of the transaction, hit "Cancel" in the Split Editor. This will reset all the splits to the transaction's original values.

Named (Memorized) Transactions

In recent versions, QHacc has implemented something I call "named transactions." I was thinking of calculating sales tax when I implemented this feature, but after working on it for a while, I realized the idea is quite general. It's basically a template for a transaction that will get entered many times in slightly different ways.

Suppose you get a paycheck every week, and the total amount changes slightly from week to week, but the percentage of tax withheld doesn't. A named transaction allows you to setup the transaction giving just the account names and percentages (or determinate values) for some fields, and a "remainder" account name for any remaining money to keep the transaction balanced. You can then select the named transaction from the Account Viewer popup, enter the total amount, and the percentages get calculated before the transaction is inserted.

When setting up a named transaction, there are some special characters to keep in mind:

Memorized transactions are a special subset of named transactions where no sum resolution is necessary. Other than that, the two are totally synonymous.

Everytime you enter a named transaction, the new one will be identical to the old one, except for the date. The date of the new transaction will be the same as the hilighted transaction at the time of insertion. This feature works for normal, double-entry, and split transactions, so use it 'til your heart's content. And as an added feature, if you are adding a memorized transaction to your checking account (or any account with an incremental number in the NUM field), and the memorized transaction has a number in the NUM field, the added transaction will automatically have the next incremental number. This allows for memorizing checks without constantly having to change the check number after insertion.

So that's what named transactions are, but how are they created? Easily. There are two main ways of creating named transactions: from the Viewer, select the "memorize" menu option from the content popup; or open the "Memorized Editor" from the "Transaction" part of the main menu. The popup method is easier if you want to duplicate an existing transaction, while creating them from scratch is probably easier from the Editor. In either case, you can also specify a keyboard shortcut which will activate the memorized transaction entry into the Viewer. This feature is especially handy if you are not using a mouse.

QHacc supports cutting, copying, and pasting transactions as well. The mechanism is the same for all operations. When pasting a copied transaction, the transaction date will follow the same behavior as memorized transactions. When pasting a cut transaction, the date will not be reset.

Scheduled Transactions

There used to be to ways to insert a scheduled transaction in QHacc, known as "the old way" and "the new way." Since "the new way" completely duplicates the functionality of "the old way," "the old way" has been removed, and "the new way" is now known as "the way." Now that that's settled...

The (New) Way

As of version 2.9.2, QHacc can automatically insert transactions for you when it starts up. It keeps track of when the transaction was last inserted and the frequency of insertions, and does the insertion when appropriate. It will make enough insertions to satisfy these requirements, so if, for example, the job is supposed to run every week and it's been three weeks since QHacc was last started, QHacc will insert the transaction three times automatically. Each transaction will have the appropriate date assigned before insertion. If the transaction happens to be dependent on an account balance for resolving its sum, the account balance will be calculated based on the date of the transaction. That is, if the above transaction is based on an account balance, the balance will be recalculated three times.

Note that all the functionality of the (old) --cron plugin is duplicated in "named transactions," above.

Void Transactions

When using double entry accounting, QHacc has the ability to void transactions as needed. Using the transaction editor, click the "More" button and select the "This is a void transaction" box. Any type of transaction can be voided. Void transaction maintain all their information, but are excluded from balance calculations. Additionally, "VOID" is displayed in the credit or debit field of the Transaction Viewer.

Loan Calculations

As of version 3.1, QHacc has the ability to calculate loan payments. When adding an account using the account dialog, there is a table entitled "Loan Information," that is enabled when the Liability account type is selected. (Yes, all loans are liabilities.) On this tab, you can specify the annual percentage rate, length of the loan, and monthly payments. Currently, QHacc assumes a monthly payment schedule and that interest is compounded monthly. This is pretty much the simplest case for loan processing.

The loan feature is accessible during transaction entry when using double entry bookkeepping. It is not possible to make loan calculations in single entry mode. When entering a transaction, select the split button. In the split dialog, select the loan account as the double entry account as you normally would, but enter "p" (for payment) in the credit or withdrawal field. Likewise, enter the account you want to use for interest in another field, and enter "i" (for--you guessed it--interest) in that credit or withdrawal field. Other splits can also be added as in any other transaction, and will affect the end sum of the transaction.

There are three caveats to loan processing in QHacc:

  1. The account selected with a "p" sum must be a loan account. If it isn't, the engine will resolve the transaction without the "p" and "i" splits included.
  2. The "p" and "i" fields must be present together
  3. If the auto-complete preference is in effect, the auto-completed transaction will not be processed as a loan payment, but rather as a normal split transaction.
Because of these caveats, it is advisable to create a
memorized transaction of loan payments ahead of time, and always enter new payments from the memorized transaction list.

Drag and Drop

QHacc features "drag and drop" from within most parts of the interface. The table below neatly summarizes the functionality. In every case, dragging can be initiated by pressing and holding the left mouse button.
TransactionViewerViewerChanges the date of the transaction to the drop location's date
TransactionViewerJournal ChooserChanges the transaction's journal
TransactionViewerChooserChanges the transaction's account from the currently-displayed one to the drop location's
AccountChooserViewerChanges the dropped-on transaction's split account to the dropped account
AccountChooserChooserReparents the account to the drop location
AccountChooserCustom Chooser1Adds the account to the custom chooser
AccountCustom Chooser1Custom Chooser1Reorders the dropped account but does not reparent it.
1: Except where indicated by "Custom Chooser," all choosers behave the same.


Reconciling is one of the most important functions of any accounting program. It is the way to compare your balance to your bank's balance. In QHacc, you can open a reconcile window by right-clicking "reconcile" from either the Account Chooser popup or the Account pulldown. The reconcile window allows you to enter the ending date and ending balance for the account. When opening the window, the current date and current balance of the account are pre-entered in their respective fields. Changing the date will recalculate the expected balance. The reconcile window has a Account Viewer as well, but selecting a transaction will simply mark it as reconciled, and not open it for editing.

The reconcile window is a fully-capable Account Viewer. That is, transactions can be added, removed, or edited just as they can be in the main Account Viewer. Both displays will remain synchronized while the reconcile window is open. Any transactions added while the reconcile window is open will automatically be marked as reconciled, regardless of which display is used to enter it. The reconcile window is modeless, so several accounts be reconciled at once.

Reconciling from the command line is also supported. Running qhacc with the --reconcile argument will compare the given QHACC_HOME's data with the already-loaded data and reconcile any duplicate transactions. A transaction is determined to be duplicated if the date and sum are identical. Also see the plugins section, below.

Archiving and Restoring

QHacc provides a method for clearing out old transactions from accounts. This mode can be entered by specifying --archive on the command line. The --archive argument must be followed by an account identifier or the date of the last transaction to prune, a colon, and the dump destination. Account names are matched first, so if your account name happens to be the same as a valid datestring, the account will get archived. Why you would ever be in this situation is beyond me. In any event, the archived transactions are put in the target directory. If an account is archived, it is removed from the Chooser display. In this mode errors are written to standard error, but nothing else is written to the screen.

The opposite of --archive is --restore. It must be followed by a dump location from which to read the archived data.

In reality, the archive and restore arguments are silently transformed to --export ARC: and --import ARC: arguments. That is, they are just regular old export and import filters. Either format is acceptable when calling the functions.

Once nice feature of the ARC plugin is that the QHACC_HOME given as its second or first argument (depending on the function) can itself reference a plugin. The recursion doesn't go on forever--just one level--but the functionality is important. It means that archived data can be written to any sort of QHACC_HOME. Likewise, restored data can come from just about anywhere.

Archiving and restoring files usually alters the accounts so that the current balance is consistent before and after archiving or restoring, but this behavior is customizable.

Exporting and Importing

Besides archiving and restoring transactions, QHacc provides a means of transferring data between QHACC_HOMEs. That mechanism is the --export and --import command line options. Both options take a QHACC_HOME argument to operate. When exporting, the entire contents of the current QHACC_HOME are dumped into the given QHACC_HOME. When importing, the entire contents of the given QHACC_HOME are merged with the current QHACC_HOME. This merge tries to avoid duplicate transactions, and is quite a bit more stringent in finding duplicates than --reconcile (above). For example, for two transactions to be determined to be duplicates, they must have the same date, payee, sum, and parent account. Accounts are merged by name. Any unique data is merged with the old data. See the plugins section, below, for more functionality.

As a side note, if you should decide to move your QHACC_HOME from one location to another, you have two options:

  1. qhacc --home <current QHACC_HOME> --export <new QHACC_HOME>
  2. qhacc --home <new QHACC_HOME> --import <current QHACC_HOME>
The two commands do exactly the same thing, but the first one will be faster because it avoids the duplicate-checking that is part of all --import operations. If the new QHACC_HOME already has data in it, however, only the second option can be used.


Since version 2.8, the QHacc engine has steadily increased its reliance on plugins to provide added functionality. It started with just the QHACC_HOME, and then moved to a generic import/export feature, and, in the current release, includes all graphing and reporting options.

The scheme is simple: every plugin has an identifier that tells the QHacc engine what data it expects to see. To use a plugin, just give QHacc the identifier as part of the QHACC_HOME. For example, if I want to have QHacc export its data in XML instead of its native format, I just run qhacc --export XML:<QHACC_HOME>. If I then want to import it into an empty MySQL database structure, I run qhacc --home MYSQL:<QHACC_HOME> --import XML:<export file>. This same scenario plays out with graphing and reporting. For example, the "transactions" report can be accessed from the command line using qhacc --report TRANS:<account identifier>.

There is even one plugin, which I like to call "The Cliimp," which allows a user to enter transactions interactively (or non-interactively) from the command line, thus making the GUI unnecessary. In the future, there will likely be more additions to this type of functionality.

For the memory conscious, it should be noted that plugins are not actually loaded until they are used. When QHacc first starts, it cycles through the plugin directories to figure out what plugins are available, but then doesn't load any until they are specifically called for. The goal for plugins was to have as much functionality as possible without increasing the memory requirements of the project.

For a complete list of plugins, their identifiers, and their uses, see the plugin page.


Occasionally, pieces of QHacc change in such a way that the saved datafiles need to be upgraded to continue to work. In the past, this upgrade was accomplished via an upgrade script that was distributed with the new program. This process worked reasonably well, but did occasionally hickup when the given interpretter was missing, or incompatible with the script itself. Also, because they were a shell scripts, they tended to be a little--how should we say?--obtuse.

The solution is a plugin that can provide the same functionality. It avoids the shell script problems because if QHacc can be compiled, so can the plugin. The plugin can be a bit more straightforward than the shell scripts as well, because they can utilize the QHacc engine instead of just trying to decode the datafiles. It also brings the upgrade procedure into line with other QHacc-related processes, because it operates as an argument to the QHacc executable instead of a totally separate procedure.

So now that you know why the upgrade plugin exists, how do you use it? It's not very difficult, but there are a couple steps:

  1. Restore any archives you have taken. The upgrade plugin may change the structure of the datafiles, which can in turn affect the structure of the archived files. If you don't restore the archives before upgrading, the archives may not be compatible with the new files, so later restoration may lead to undefined results.
  2. Export your data (qhacc --export /tmp). The upgrade plugin only works against QHacc's native file format, so if you use some other database, you must create a native export.
  3. Run QHacc with the upgrade plugin as its home (qhacc --home UPG:/tmp). This will upgrade your old data and start a new instance of QHacc. Save and close the application.
  4. If necessary, recreate your datastore (qhacc --create PSQL:qhacc). This is a good practice for all upgrades because the upgrade process may change the structure of the data. If you use a database backend, for example, the table structures may change, and these changes must be accounted for.
  5. Import your data to your datastore (qhacc --import /tmp). This completes the upgrade.


QHacc supports limited reporting from the GUI and the command line. The reports are available through the Graphs menu, or in the popup of the Account Chooser. The Report Dialog allows for reports from any date range and for any account or group of accounts. From the command line, the reports are slightly more restricted. Date ranges are not supported from the command line, though a dedicated user can create similar functionalty by creatively using the archive and restore functionailty in combination with the reports. In any event, the reports can be accessed from the command line using the --report option followed by the report plugin of choice. See the plugins page for more details.

Some graphs allow expanded viewing via "click-throughs." Clicking on a section of the graph will open a subset view of the given account for the appropriate month. The subset view also reports several attributes of the transaction set, if the appropriate report plugin is installed.

When using the GUI for graphs and reports, multiple accounts can be selected at once. Select an account, and then hold the shift- or ctrl-key to select either a range of accounts, or individual accounts, respectively.


The preferences object is perhaps the most widely used object in QHacc. It defines how dates are displayed, how currencies are marked, which colors and fonts are used, and which type of bookkeeping you prefer. Any character can be used for a currency symbol, or for the date element separator but I wouldn't recommend using a numerical value for either one (the default of "/" should be good for most dates). The preferences dialog also allows a user to choose the name to display in the titlebar of the program. This is extremely useful when using different personalities, since using different titles for different personalities minimizes confusion.

When switching bookkeeping styles, QHacc performs what I will call "lazy" updating. That is, if you used to use double-entry bookkeeping and you switched to single-entry, none of the links will break. The links between transactions remain intact until the transaction is opened and then resaved. Likewise, single-entry transactions will remain pairless until they are opened as double-entry transactions. This is true even across saves.