Difference between revisions of "FAQ"

From GnuCash
Jump to: navigation, search
(Add personal loans.)
(→‎'''Q: Is there a way to schedule billing the same way we schedule transactions?''': Fix formatting)
Line 312: Line 312:
 
:'''A:'''  No, unfortunately, the business features don't tie into the SX engine.
 
:'''A:'''  No, unfortunately, the business features don't tie into the SX engine.
  
−
==='''Q: How do I account for loaning/browing money to/from a friend?'''
+
==='''Q: How do I account for loaning/browing money to/from a friend?'''===
  
−
:'''A:''' Money that you loan to someone is an Asset to you.  Money you've loaned from someone else is a Liability.  The general recommendation for account names is:
+
:'''A:''' Money that you loan to someone represents an Asset to you.  Money you've borrowed from someone else is a Liability.  The general recommendation for account names is:
  
 
* Assets:Money Owed To Me:[Person]
 
* Assets:Money Owed To Me:[Person]
−
 
 
* Liabilities:Money I Owe To:[Person]
 
* Liabilities:Money I Owe To:[Person]
  

Revision as of 16:36, 4 February 2006

The contents of this FAQ will eventually be merged into the GnuCash help documentation. Or maybe not.

Contents

General Frequently Asked Questions (FAQ) about GnuCash

Q: How can I contribute to the GnuCash project?

A: Further answers about this are on the Development wiki page.
We're working on a more formal process to help you decide how to contribute, but for now you should subscribe to the Mailing Lists gnucash-user and/or gnucash-devel and discuss what you can contribute with the participants on the lists. Please be aware that GnuCash is a large body of code written in C and Scheme (see Developing GNUCash: Source Code Overview if you want to know why). If these are languages that you are not willing to work with, consider contributing in other ways.

Q: How can I make a donation to the GnuCash project?

A: The Development wiki page has information about how you can donate to the GnuCash project. We appreciate your support.

Q: I think I found a bug. How do I report it?

A: First of all, try to verify that it is indeed a bug and that it has not been reported before. Search the mail list archives at gnucash-devel and gnucash-user (and gnucash-de if you speak German). Then search the Bugzilla database.
If you feel you have indeed found a bug, you can then report it in the Bugzilla database via this quick link. Please bear in mind to report your bug as verbosely as possible. The trick here is to learn how to give the best information to the programmers about how to reproduce bugs. A Programmer will usually only be able to fix a bug they can see, if you can't make the programmer see your bug, it won't get fixed! Also see Development for additional tips.

Q: I really want feature XYZ but GnuCash doesn't have it. How do I get it added?

A: Ask nicely. :-) You can file an enhancement request at Bugzilla. Please bear in mind to describe your proposed enhancement as verbosely as possible. The trick here is to learn how to give the best information to the programmers about what your proposed new feature should do. If you want to speed up development significantly, consider donating some money as described on Development.
Note that the fastest way to get a feature added is to implement it yourself. A bug report with an attached patch is very likely to get applied quickly.

Q: Where is my .XML file?

A: It's the file you are using - the one that you named when you created the new file that hold your accounts.

Q: The mail server does not append subject tags indicating which list the email is originating from, such as [gnucash-user] or [gnucash-devel]. Is there some other way of determining from which list the messages are being sent?

A: Yes. Each message has a header "List-Id:" such as one of the following:
List-Id: General Accounting Discussions <gnucash-user.gnucash.org>
List-Id: GnuCash Software Design and Development Discussion <gnucash-devel.gnucash.org>
etc.
(To see these, look at the email source, or turn on rich or full headers.) You may consistently filter off of these.

Q: Is there a version for Gnome2? When will 2.0 be out?

A: The GNOME-2 port, which will be released as 2.0, has been in progress since the Fall of 2004. It is expected to be in progress until mid-2006 at the earliest. See PortingStatus and KnownGnome2Problems for more details. See FAQ#Developing_GNUCash:_Source_Code_Overview for a longer answer.

Q: How do I convert from CSV, TSV, XLS (Excel), or SXC (!OpenOffice.org Calc) to a QIF?

A: One way is to use the macros that exist for Excel and OpenOffice.org. These macros will convert a spreadsheet file into a QIF file. XL2QIF is a script to convert an Excel spreadsheet to a QIF file. CALC2QIF is a script to convert an !OpenOffice.org spreadsheet to a QIF file. These macros may be obtained at http://xl2qif.chez.tiscali.fr/calc2qif_en.php.

Q: How to get gnucash running under gnome2 (gconfd problems)

A: Running gnucash under gnome2, gnucash would crash with:
gtkhtml-ERROR **: gconf error: Failed to contact configuration server
(a likely cause of this is that you have an existing configuration server
(gconfd) running, but it isn't reachable from here - if you're logged in
from two machines at once, you may need to enable TCP networking for ORBit)
Note that this was under Suse 9.1 with various upgraded packages (usr-local-bin etc).
A number of posts on the net recommend starting gconfd-1, but everytime I ran 'gconfd-1' ps showed gconfd-2 was running. I solved the problem by running '/opt/gnome/bin/gconfd-1.bin' instead (gconfd-1turns out to be a shell script which checks for an executable gconfd-2, and runs that if it finds it!). Pete

Q: Temporary (?) files: Running Gnucash 1.6.6 on Linux, it creates many, many files with names ending in ".xac", and not quite as many with names ending in ".log", in the same directory as the main data file. My question is whether these files need to be kept indefinitely (meaning, for as long as I want to keep using this same main data file).

A: Those are log files and backup copies of the main file. Gnucash will remove them after a configurable amount of time (Preferences/General/"Days to retain log files"). If you are sure your data file is OK and you don't need old versions of the file, you can remove the files safely.

Q: I moved/renamed my data file and my reports disappeared. How do I get them back?

A: Reports are stored in a separate file in the ~/.gnucash/books directory. File name is a url-encoded path name for the main data file. To get your reports back, copy old report file over the new reports file, then open ~/.gnome/GnuCash in your favorite editor and copy section corresponding to the old file to the section of the new file

Q: Is there a way to merge two accounts into one? That is, move all transactions from one account into another? That would save a lot of time compaired to moving each transaction!

A: Unfortunately, no, you must manually change each transaction. However, there are some tricks that can make this process go a little faster. Open one of the account registers and select either View→Style→Auto-Split Ledger (or View→Style→Transaction Journal). This will automatically expand all of the splits for the selected transaction. In the simplest case, each transaction will have two splits, one of them to the current account. You want to change the split assigned to the current account to be assigned to the other account instead. Double click on the account name in the split, which should select all of the text. Now instead of using the drop-down list to select the new account, simply type the new account name, using the built-in auto-completion. For example, to move a split to Expenses:Auto:Repair, you might type ex:au:r. When you then hit <enter>, the changes will be saved, and that transaction will disappear since it is no longer tied to the currently open account.

(With the XML file backend, it is possible to merge accounts by directly editing the data file, but this is risky and not recommended)

Q: How do I make reports not display the same strange character (e.g. dashed outlined box) before each desired character?

A: Run GnuCash in a locale not encoded in UTF-8.
I don't know how to do this "for real", but I did the following. You would have to do this each time you run GnuCash.
  1. Open a shell (command line/terminal emulator)
    1. If you don't know YourLocale, "locale | grep LANG"—You should see "LANG=YourLocale.UTF-8"
  2. "LANG=YourLocale gnucash"—Set the LANG without the ".UTF-8" and run GnuCash
  3. Enjoy properly displayed reports in GnuCash
  4. After exiting GnuCash, exit the shell

Or rather than doing this each time write a wrapper script, /usr/local/bin/gnucash 

#!/bin/bash
# Wrapper to get correct LANG (not with UTF-8) for the application /usr/bin/gnucash
# Automatically extract MyLocale from the string 'LANG=MyLocale.UTF-8' which is output by locale
MyLocale=$(locale | grep LANG | cut -f1 -d'.' | cut -f2 -d'=')
export LANG=$MyLocale
/usr/bin/gnucash

If LC_MONETARY is set to a different value from LANG then add the following two lines above the last line (/usr/bin/gnucash): 

MyLocale=$(locale | grep LC_MONETARY | cut -f1 -d'.' | cut -f2 -d'=')
export LC_MONETARY=$MyLocale

Make the script executable 

chmod a+rx /usr/local/bin/gnucash

Usually /usr/local/bin comes before /usr/bin in a user's $PATH so this wrapper will be executed whether the application is started from the command line, from the Gnome menu, or from an icon in the panel or on the desktop. If /usr/local/bin does not come before /usr/bin in $PATH add this to the user's .bashrc 

PATH=/usr/local/bin:$PATH

Questions about Using GnuCash

Q: The View menu has an option to not show voided transactions. How do I void a transaction so that GnuCash recognizes it as such?

A: See https://lists.gnucash.org/pipermail/gnucash-user/2005-July/014281.html

Q: Can I import my (USA) Discover credit-card info?

A: See http://lists.gnucash.org/pipermail/gnucash-user/2005-June/014051.html

Note that the url referenced in that thread does not work without a leading "www" as in http://www.jongsma.org/gc/

Q: I'm trying to read the tutorial/help but it says that it's unable to find the url. What's up with that?

A: You don't have the gnucash-docs package installed. Install that to the same prefix where you installed gnucash and the docs/tutorial will show up properly.

Q: How can I export data?

A: There's an XSLT at http://xslfactory.free.fr/ which can transform a gnucash XML file to a big gnumeric spreadsheet. The Workbook will contain several sheets; One with all the accounts, a diary with all the transactions, and on sheet by account with all the transactions. Prior to running the transform, you'll need to edit the gnucash XML file (preferably a copy of it) to include xmlns data. (Note however that as at 24th Apr '04 it doesn't include support for business objects, eg: invoices.)
There is also http://gnucashtoqif.sourceforge.net/ which is a Java program that can transform a gnucash XML file to a QIF file.

Q: How do I set up and track budgets?

A: There is budgeting support in the development version, which will become gnucash 2.0 (expected mid-2006). Your testing and feedback is encouraged! See Budgets elsewhere on this wiki for more info.

Q: Is there book-closing support, yet?

A: There is some support in CVS, and we're curious to hear your feedback about it. A not-unreasonable work around is to copy your data file, and edit it to add zeroing transactions to each income/expense account. Also note that the reports should be able to provide accurate data even without zeroing transactions, so your P&L and Balance Sheet reports will still work. However your account balances won't show year-to-date.

Other methods:

  • One File Per Year At the end of each year you can start a new gnucash file for the next year. The easiest way to do this and start with all your old account names is to use File->Export->Accounts. Give it the name you intend to use for the new year. Then do File->Open and select the name you just saved. You will need to transfer over your starting balances, but at least the account names are there.
  • New Account Branch for Year-End Totals Another method is to start a new account branch for your year end totals. Choose File->New Account and create an account for "2004 Year End" For each expense category create a transaction on the last day of the year to shift the balance out of the expense account into the 2004 Year End account. The account report for the 2004 Year End account makes a good summary of the information. This method had the advantage that when entering new transactions, the auto-complete features will still work.

Q: I would like to add transactions from an external program. It seems, this could be done with "gnucash --evaluate something". What is the something?

A: gnucash --help will show any available commands for executing scheme, but you will likely have to write a good chunk of code to be invoked this way to import the data.
Probably a saner course of action is to convert the external transactions into a shared format such as QIF or OFX and import them using the existing application functionality.

Q: What is the "SX" thing I see on the lists and IRC periodically?

A: SX stands for Scheduled Transaction, but Scheduled Transaction is a lot to type/write, so it's shortened to SX. Scheduled Transactions are templates for entries that will occur in the future: for example, regularly recurring bills, such as utility or mortgage payments. SX's are meant to make it easier to enter in anything that recurs on a regular basis.

Q: How do I use variables and formula in scheduled transactions?

A: In lieu of formal documentation, see the following:

Q: If my bank doesn't offer OCX or QIF, how can I make it easier to enter my statement data?

A: QIF is a flat text file of a specific format, only a few steps removed from CSV (comma separated values). There are scripts that can do the transfer. Take a look at how another GnuCash user has solved your problem: http://baruch.ev-en.org/proj/gnucash.html "I very quickly found that I'm way too lazy to hand enter the bank statements into GnuCash" From the same site:
It is possible to have " a Perl script that was written to download the data from the Bank internet site, modified to adapt it for my needs, which is simply to export the data in CSV format. I then wrote a Python script to convert the CSV data to QIF format. The QIF files are easily imported into GnuCash with relatively very few keystrokes."

Q: My bank offers OFX Direct Connect. How do I use that?

A: GnuCash uses libofx/aqbanking for OFX/QFX support, so you should look there for Direct Connect support: http://aquamaniac.de/aqbanking/ . Also, there is a python script available that can do this for you at [ http://www.jongsma.org/gc/ ].

Q: I invest in a security which issues ReturnOfCapital, which in Canada results in a decrease in the cost base of the investement for capital gains purposes. How do I include a return of capital in GnuCash.

Q: I exercised ISOs for a nonpublic company, valuable only on paper. How would this most effectively be represented in GnuCash?

A: Exercised ISOs (Incentive Stock Options) are stock.
  1. create a "Stock" account
  2. next to commodity, hit "Select..."
  3. in the "Select currency/security" window, click "New"
  4. Full name: (company name), Symbol: (doesn't matter), Type: (enter "Private"), click "OK"
  5. once the company goes public, sell!!!

Q: The fiscal year is July 1-June 30, how can I change that?

A: There is no way to change this in the 1.8 release. http://article.gmane.org/gmane.comp.gnome.apps.gnucash.user/12944/match=july
The adventurous might want to look at the function gnc:get-start-cur-fin-year [and it's cousins] in gnucash/src/app-util/date-utilities.scm which encode the magic value '6' [=July in a 0-based month indexing].

Q: How can I look at income/expenses/etc. on a monthly basis?

Using Business Features

Q: How do you make the organization name and information appear at the top of reports? on screen, and when you print?

A: You can edit the Style Sheet (Edit -> Style Sheets) and set your company information there. That's probably the best way of doing it. You may want to create a new Style Sheet if you don't like the existing ones. The template stylesheet (stylesheet-fancy.scm) can be found in your_gnucash_directory/share/gnucash/guile-modules/gnucash/report/ . To meet Australian requirements, include your ABN as a separate line in the business address.


Q: How do you make the organization name appear on my Invoices?

A: You can go to File -> Properties and set your business' name and address on the Business page. The Invoice printer uses the data from this entry to fill in your business information.


Q: How can I delete an Invoice, Customer, Vendor, or Employee?

A: Quick answer: you can't. Longer answer: you can mark the item as "inactive" (just uncheck the "active" button) and it will no longer show up in standard searches. There are no plans to ever allow you to delete these objects. If you really care you can just re-use them later.
A: Quick answer: you can. Longer answer: 1 - delete Invoice entries (GncEntry clause), 2 - delete Invoice of these deleted entries (GncInvoice clause), 3 - Customer of these deleted Invoices (gncCustomer), 4 - correct counters (count-data) for those deleted positions. Try to learn database file structure. It takes one hour for me.

Q: How do I change "Invoice" to "Tax Invoice" as required in Australia?

A: Edit invoice.scm and change (define invoice-name (N_ "Invoice Number" )) to (define invoice-name (N_ "Tax Invoice Number" )). If you are using tax tables to calculate GST and add it as an automatic subtotal, then you should also change the line "grand-total" (_ "Tax"))) to "grand-total" (_ "GST")))


Q: How do I handle GST on invoices, and claim GST rebates on purchases?

A: First, create three liability accounts, Liabilities:GST:Paid, Liabilities:GST:Payable, Liabilities:GST:Payments. Paid is for claimable GST you have paid on purchases. Payable is for GST you have charged to customers. Payments is GST amounts you have paid to the government.
Next, create a tax table, using Business=>Tax Tables. Call it GST Payable, and link it to Liabilities:GST:Payable. This is the tax table you will use for invoices to customers.
GST for accounts payable is easy. Just select GST Payable as your tax table for each transaction. This should automatically add the GST amount to the Liabilities::GST::Payable account.
For GST for purchases, we need to create a split transaction. Say you are entering the transaction in your Cash account. Enter the total amount in the spend column, including GST, then hit the split button. You'll see a balancing debit in the receive column. Allocate this to the appropriate account, but decrease the amount to the cost before GST. You will then see a new debit line, with the GST amount in the receive column. Allocate this to Liabilities:GST:Paid account. This will show in this account as a negative amount, that is, as a rebate.
Then, whenever you pay your GST amounts to the government, enter this in Liabilities:GST:Payments.

Q: Is there a wizard or a description to setup basic business accounts?

A: No. There are some basic business template accounts (for US) in the "New file" druid/wizard. But there are no wizards/druids for setting up a business, i.e., setting up tax tables, terms, customers, and vendors. You can do all that under the Business menu.

Customizing

Q: I'd like to write my own custom reports. Where should I start?

A: Unfortunately currently this requires some (small) knowledge of the programming language Scheme. Currently it is not possible to save a customized report (e.g. the "multicolumn report") as an extra menu entry. Instead, each report that shows up as a menu entry has to be created in a Scheme file. An earlier answer to this question by ChristianStimming is here: "You might want to read Christopher Browne's excellent introduction to report writing for Gnucash. If you have compiled and installed the development version of Gnucash in e.g. /usr/local, the document can be found in /usr/local/share/gnome/help/gnucash/C/xacc-repdev.html. As a starting point, you might want to experiment with the "Hello World"-report, to be found in src/scm/report/hello-world.scm in the Gnucash source tree." When you've got a report to try, drop it in the directory with the other reports: /usr/local/share/gnucash/guile-modules/gnucash/report/, and don't forget to register it in report-list.scm in /usr/local/share/gnucash/scm/report/. You have to restart GnuCash each time you want to test a modification of a report file.
Update (2004-04-25): The file xacc-repdev.html is part of the GnuCash 1.6 documentation, which is no longer available or current. You can find the file in the CVS Archive here.
Update (2005-03-21): The previous update meant you can find the original .sgml source there. Dan Widyono is starting to work on an updated version which may be more beneficial to people currently wanting to write custom reports with GnuCash 1.8.x. Updates, corrections, tips, etc. greatly appreciated at widyono _A_T_ seas.upenn.edu.

Q: How can I save my custom check printing configuration?

A: Currently, you cannot use the user interface to save your custom check printing definitions. If you are comfortable making a few simple edits to a scheme file, though, you can redefine one of the existing definitions to print correctly on your checks. To do this, first use the "print cheque" dialog box to add in your custom coordinates to get a check printed correctly. (Note that these dimensions count up from the lower-left of the check. Big numbers move the text up and to the right.)
Once you have the dimensions necessary to print correctly on one of your checks, you can edit the gnucash/scm/printing/print-check.scm file to change one of the existing definitions to print to your checks. The area that you need to change is labelled "stock-check-formats", and probably currently contains two format definitions. Change either one you like. Note that the dimensions defined here are not in the same order as those in the dialog box you were just working in. Now, you'll proabably have to restart gnucash for your new format definition to work.
To keep track of any progress to enhance this part of the application, check out the bugzilla bug 311062: http://bugzilla.gnome.org/show_bug.cgi?id=311062

GnuCash Accounting Questions

Q: What are debits and credits?

A: Debits and credits are the terms used to identify either an increase or decrease in an account. It depends on the type of account that you are talking about as to whether the increase or decrease is a Debit or a Credit. The first step in understanding debits and credits is to forget what your bank tells you. As they are looking at it from their point of view, when they tell you that they will "credit" your bank account (in other words, put money in your account) they are correct. However, to you it is a Debit. Here's why.
Let's start with the accounting equation: Assets = Liabilities + Equity, where Equity = Revenue - Expenses (actually equity is more than just that, but for the purpose of this explanation it will do).
Now think of each of these catagories (Assets, Liabilities, etc) in terms of a T, with the name of the catagory above the top of the T and the transactions being recorded on either side of the vertical part of the T. Debits are recorded on the left side of the T, Credits are recorded on the right side of the T. Lets look now at the Asset accounts. Since the Assets are on the left side of our equation, any increase in assets must be recorded on the left side of our T, this means that an increase in assets is a Debit. Conversely, a decrease in an asset account must be recorded on the right side of the T, meaning that it is a Credit. Looking next at Liabilities and Equity, it is treated exactly opposite to Assets (otherwise the equation wouldn't work). Because Liabilities and Equity are on the right side of the equation, any increase in Liabilities or Equity are recorded on the right side of the T. This means that it is a Credit. A decrease in Liabilites or Equity would then be recorded on the left side of the T, or a Debit.
Now for Revenue and Expenses. Since both of these are a component of Equity, whether they are a Debit or Credit is tied into how Equity fits into the accounting equation. Think of it this way, if you made money during the year, the net effect on your Assets would be an increase, or greater Debit balance. In order for the equation to work, this would mean that Equity would also have increased, or a greater Credit balance. In order for this to happen, Revenue would have to be a Credit, while Expenses would have to be a Debit. The resulting Revenue minus Expense would give you a Credit balance, or an increase in Equity. So Revenue is always a Credit, while Expenses are always Debits.
To go back to the what the bank is telling you, here is why they are right from their point of view. They owe you money (your bank account balance). This, to them, is a Liability. Therefore, any increase in the amount they owe you would be a Credit on their books. However, to you, your bank account is an Asset. Therefore, any increase in your bank account would be a Debit on your books.


Q: How do I record my income tax installments and year-end payment/refund?

A: The difficulty in recording your income tax expense is that you don't know until the year is over what your true expense for the year will be. Because of this, there is no way to accurately record the income tax expense on a monthly basis. My recommendation is to record the monthly installments to a balance sheet account, then, when you complete your tax return for the year and know the expense, record the expense to the income statement account.
Let me illustrate by the way of example. First, I'll make some assumptions:
  • Year end is December 31, 2004
  • Monthly installments of $100.00 are required to be paid
  • The tax return is completed and filed on March 31, 2005 along with a cheque for the balance payable
  • Total taxes payable for the year are $1,300.00. This means that after the installments of $100.00 per month, $100.00 is still owing.
You will need to add the following three accounts, if you don't already have them.
  • Income taxes payable (Liability account)
  • Income taxes receivable (Asset account)
  • Income tax expense (Expense account)
The first entry will be to record the first installment. Post this as a credit to your bank account and a debit to the income tax payable account. Repeat this same transaction every month. In fact, you could set it up as a scheduled transaction. At the end of the year, you will have accumulated $1,200.00 in the income tax payable account.
On March 31, 2005, make an entry dated for December 31, 2004 to record the expense for the year. This would be a debit to the income tax expense account for $1,300.00 and a credit to the income tax payable account. As a result of this entry, the balance in the income tax payable account is a credit balance of $100.00, and the balance in the income tax expense account is a debit balance of $1,300.00.
The final entry would be to record the cheque on March 31, 2005 to pay the balance. This would be a credit to the bank account for $100.00, and a debit to the income tax payable account for $100.00.
The next question is what happens if I have a refund. Let's assume that you only owed $1,100.00. This time, when you record the expense (dated December 31, 2004), you would debit the income tax expense account for $1,100.00 and credit the income tax payable account. This results in a debit balance in the income tax payable account of $100.00. Since this is really a receivable, it needs to be moved to the income tax receivable account. Do this by debiting the income tax receivable account for $100.00 and crediting the income tax payable account. When the refund is received from the government, record it as a debit to the bank account for $100.00 and a credit to the income tax receivable account.


Q: How do I use GnuCash to calculate VAT?

A: Frequently discussed on the mailing list, someone please copy answer here...


Q: How do I use GnuCash to do depreciation?

A: Frequently discussed on the mailing list, someone please copy answer here...


Q: Is there a CPA (Certified Public Accountant) who uses GnuCash in my area?

A: If you are an accountant or book-keeper, add your name and contact info here.


Q: What's a T-account? What's double-entry?

A: This is discussed at great length in the GnuCash documentation.

Q: Is there a way to schedule billing the same way we schedule transactions?

A: No, unfortunately, the business features don't tie into the SX engine.

Q: How do I account for loaning/browing money to/from a friend?

A: Money that you loan to someone represents an Asset to you. Money you've borrowed from someone else is a Liability. The general recommendation for account names is:
  • Assets:Money Owed To Me:[Person]
  • Liabilities:Money I Owe To:[Person]

Q: How do I keep track of capital gains with stocks?

A: The 1.8 series of Gnucash doesn't handle capital gains in an automated fashion, so it's pretty easy to get an incorrect balance sheet after the sale of stock or some currency conversions. Recall that in the double-entry accounting that Gnucash uses, money is never created or destroyed, it only moves from one account to another...at least, in theory. The introduction of stock transactions (or really anything that involves an exchange rate) creates a situation where money can be created.

For example, let's say we have the following accounts: 

Assets
  Broker
    Cash
    XYZ Inc
Expenses
  Broker Fees
Income
  Capital Gains

When we purchase stock in company XYZ, the transaction splits might look like this: 

Account                    Shares   Price    Debit    Credit
Assets:Broker:XYZ Inc      5        $10.00            $50.00
Expenses:Broker Fees                         $7.00
Assets:Broker:Cash                                    $57.00

This is pretty straightforward. We bought five shares at $10 each, and paid a $7 commission. But you have probably already gotten this far and now you're ready to sell. If you entered the intuitive splits, money would be created and everything would get thrown out of balance: 

Account                    Shares   Price    Debit    Credit
Assets:Broker:XYZ Inc      -5       $17.00            $85.00
Expenses:Broker Fees                         $7.00
Assets:Broker:Cash                           $78.00

$35 has come from nowhere! It's actually capital gains, but we can't just add a split for $35, because then the cash value of the transaction doesn't balance out. Now we have to introduce a bit of unpleasantness. We want that split for $35 from Income:Capital Gains, so to balance out the cash portion of the transaction, we create another split wherein we "purchase" 0 shares at $0 each, but spend $35 to do so: 

Account                    Shares   Price    Debit    Credit
Assets:Broker:XYZ Inc      -5       $17.00            $85.00
Expenses:Broker Fees                         $7.00
Assets:Broker:Cash                           $78.00
Income:Capital Gains                                  $35.00
Assets:Broker:XYZ Inc      0        $0       $35.00

This last split exists to balance the capital gain split, but it has deeper meaning as well - it corrects the fundamental imbalance that was created by fluctuating exchange rates. In the upcoming (as of January 2006) 2.0 release, these splits will hopefully be created automatically, but it's certainly possible to enter them by hand in the 1.8 series of Gnucash.

More complicated situations can be resolved in a similar manner, though calculating the capital gains by hand could be wearisome (consider a mutual fund that has been seeing regular contributions for a long time, along with the occasional dividend reinvestment and maintenance fee, and consider only selling a portion of the currently owned shares). The Cash Flow Report and the Transaction Report can help you to calculate your cost basis, but that's beyond the scope of this question.

See these mailing list messages (and other messages in these threads) for further reference:
https://lists.gnucash.org/pipermail/gnucash-user/2006-January/015605.html
https://lists.gnucash.org/pipermail/gnucash-user/2006-January/015620.html
https://lists.gnucash.org/pipermail/gnucash-user/2006-January/015396.html
https://lists.gnucash.org/pipermail/gnucash-user/2005-July/014192.html
https://lists.gnucash.org/pipermail/gnucash-user/2005-February/012863.html
https://lists.gnucash.org/pipermail/gnucash-user/2005-January/012648.html

Questions about GnuCash Localization (L10n) and Internationalization (I18n)

Q: I want to use GnuCash in my own language (Debian users may need it)

A: You have to set: "env LANGUAGE=fr_FR" and "env LANG=fr_FR". This exemple is for french (français). and then launch GnuCash.
For Debian users: make sure your locales are properly installed. If not, run 'dpkg-reconfigure locales'


Q: I want to use GnuCash in a different language than my monetary/decimal seperator

A: Then you want to set the LC_MONETARY envrionment variable different from the LANG: "env LC_MONETARY=fr_FR".

Questions about GnuCash Files and managing a GnuCash installation.

Q: Is the Postgres DB / SQL backend supported?

A: No it is not supported. It is partially functional, but specifically does not support any new-in-1.8 features such as the business or scheduled transactions features. See http://gnucash.org/en/sql.phtml for instructions with the existing code base.
A different approach to providing a DB backend is anticipated for either 2.0 or a 2.x release, and should function for both existing Postgres installations, and an embedded SQLlite DB (with no end-user database administration required).

Q: Can I use GnuCash with multiple users? Maybe via the SQL backend?

A: Especially since the SQL backend doesn't support the business features, which is usually the driving desire for multi-user support, the only recommended multi-user setup right now is through a shared file. Note that this will enforce serialized, exclusive access to the data file and editing; there is no real support for simultaneous editing. File-locking is employed on this file, so it should be NFS-safe. SMB-safe locking is unknown.

Q: What are all these .xac and .log files filling up my directory?

A: These are backup data files and log files that GnuCash creates to prevent data loss. They are dated files and GnuCash automatically removes them after 30 days. You can set change this timeout value in Edit -> Preferences -> General and change the number of "Days to retain log files".

Q: Is it possible to provide security for GC data using CFS, etc.?

A: See gnucash-devel thread here. Note that the link in the post does not work, but this one does: crypto.com. CFS is fairly old code, and has some flakiness, but does work with modern systems (e.g., see pkgsrc/security/cfs in NetBSD's pkgsrc). Also, one should be able to use NetBSD's cgd(4), which is a cryptographic layer for an entire block device, FreeBSD's geom-based encrypttion, TCFS, or other packages that provide encrypted filesystems. GnuCashDevelopment is in pretty strong concensus that some approach like this one is the correct solution. Note that if PostgreSQL is used as a back end then one must encrypt the database storage area, and that may or may not be more difficult in practice.
Loop-AES is another option; see Example 7.3 in particular for setting up an encrypted specifically-mountable loopback partition.

Q: I'm running gnucash under Linux. Can I give another user access to my gnucash files?

A: Yes. You do it the same way you'd share files of any type under Linux: put them in a folder that both of you have access to, and change the permissions so that you both can read and write to the files. You really don't want more than one person to have them open for editing at the same time, however, as whoever saves last will overwrite the changes of whoever saves first.


Q: How do I backup my GC environment, including preferences?

A: Make sure you save not only all your .xac, .log files and the actual ledger file, but also $HOME/.gnucash, $HOME/.gnome/GnuCash, and $HOME/.gnome/accels/GnuCash.

Q: I use the same account on multiple computers (through a repository), how do I also transfer the reports I currently have open?

A: Copy all of $HOME/.gnucash and $HOME/.gnome/GnuCash. Alternatively, from 1.8.10 onwards you can "save a report", which will be saved in $HOME/.gnucash/saved-reports-1.8 (IIRC). If you copy that file to your other computer, you will have the same reports available.

Questions about Installing GnuCash.

Q: I am upgrading from version 1.8.1 to 1.8.9 on RH9 and I get the error

Packages Not Found
The following packages could not be found on your system.  
Installation cannot continue until they are installed.
libgal.so.19
libgtkhtml.so.20
libguile.so.6
libqthreads.so.0
gnucash=1.8.1
Is there anything I need to do before installing the RPM?
A:There are two issues here. First, you are probably not using the GnuCash RPM compiled for RH9. You MUST use a GnuCash binary compiled SPECIFICALLY for your version of Red Hat (or any other OS). You can find RH9 RPMs here. The second problem is that you have gnucash sub-packages installed which depend on the main gnucash package. You will need to upgrade all packages simultaneously, or just remove the sub-packages you do not intend to use.


Q: I'm running Debian/unstable, just upgraded, and GnuCash no longer works. How can I fix that?

A: Contact Debian. Read the gnucash-user archives because someone else probably already reported the problem.
Examples:
If you get an error about gncownercreate, see https://lists.gnucash.org/pipermail/gnucash-user/2004-March/009864.html
If you get an error about format not being found, see https://lists.gnucash.org/pipermail/gnucash-user/2004-March/009676.html
If you get an error about "Unbound variable: gnc:menuname-ncreports", it should be fixed in version 1.8.12-5. See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=348502

Q: I'm having trouble getting GnuCash running on Slackware

A: See http://rjmarq.org/gnucash.html and http://www.slackages.com/linux/slackages/index.html

Q: Is there a version/port for Windows?

A:No, there's not. The active devs don't really need one, but also have no objection to one. The first main issue would be getting the gnome environment and dependencies building. The source is otherwise quite portable, and should compile fine given Windows versions of dependencies and libraries.
On the developer mailing list this issue is regularly discussed. See e.g. here and the whole thread there. Basically the answer is that it's not possible with the gtk1-based-gnucash, but it might be quite easy once the gtk2/gnome2-gnucash is finished.
Other related options would be colinux, VMWare and a windows-based X-server hosting a remote GnuCash session.

Q: How to install on Mac OSX?

A:I installed Gnucash without problems on a new machine with OSX 10.3.4.
  1. X11 is installed from Panther discs.
  2. I installed fink from the binary distribution Fink-0.7.0-Installer.dmg
  3. I installed finkcommander from the above distribution
  4. I upgraded finkcommander per instructions
  5. I ran Source->Selfupdate-rsync (not sure whether this was strictly necessary)
  6. I selected gnucash and ran Binary->Install
  7. Started X11
  8. Applications->Customise->Add Item Name=gnucash Command=/sw/bin/gnucash
  9. Start guncash either from pulldown or by typing guncash in xterm. In xterm error messages are displayed whereas they seem to be suppressed using the Application menu.
  10. If in not in US Edit->Preferences->International select and apply your money and your dates scheme.
  11. Enjoy
A2: Here's another method:
  1. Make sure X11 (XDarwin), X11SDK, Fink, and !FinkCommander are installed and working.
  2. Check the 'Use unstable packages' box in the !FinkCommander Preferences. That will display gnucash in the table.
  3. Select gnucash from the table and click the 'Install package(s) from source' button. Fink will check for dependencies and provide a list of programs & libraries that need to be installed.
  4. If you have more than 3 or 4 that need to be installed, write the list down and install each individually or in small groups. Fink gets confused with large lists of dependencies. Some items may take a while to download and/or install. If download or personal time is limited, you can stop in the middle and come back at a later time. Once the programs & libraries are installed, you don't have to re-install them later.
  5. After installing all the dependencies, select gnucash again and click the 'Install package(s) from source' button. This may also take a while to download and/or install.
  6. Open X11 and in an X11 terminal, start gnucash by typing gnucash<enter>. If gnucash does not start, copy any errors that are printed to the screen and either correct the problem(s) or submit them to the !GnuCash User list at [1] and someone will try to help you.
  7. After starting gnucash from the command line a few times and making sure there are no errors, install the !GnuCash Launcher applet from [ here | http://homepage.mac.com/elliottmce/gnucash_guide/Page005.html]. It's an easy way to start the gnucash application after you have it working from the command line. Just remember that if you are having problems starting the program to try launching from the command line to see any errors that are being generated.


Workaround for "dlcompat" error on launch:
The following note on the fink mailing list from Martin Costabel solved my problem at launch (same as Jamie's): {reproduced without permission...}


From: Martin Costabel <costabel@wa...>
Re: gnucash (binary) problems on Fink 0.7.1  
2004-09-24 16:44

Jamie Caplan wrote:

> loading library: /sw/lib/libbonobox.2.dylib
> loading library: /sw/lib/libbonobo.2.dylib
> ERROR: In procedure dynamic-link:
> ERROR: file: "libgw-gnc", message: "dlcompat: invalid handle"

The next one to load would have been libgtkhtml.20.dylib. Do you have
the package gtkhtml-shlibs installed? {Re}install it.
A3: See also: http://homepage.mac.com/elliottmce/gnucash_guide/

Q: I get "gtkhtml-ERROR **:gconf error: Configuration server couldn't be contacted: [[...]"

A: You've likely got a Gnome2 system with enough Gnome1 libs to run GnuCash; you need one more package: gconfd1 , which GtkHtml depends on. Install it and start the gconfd1 server, and GnuCash should run fine.


Q: GnuCash fails on startup, complaining about "slib:require unsupported feature format".

A: You are very likely using slib-3a1; gnucash requires slib-2d6. NOTE: This was mostly fixed in CVS prior to the 1.8.9 release but one file was left unchanged. This one change means you might not be able to compile gnucash with slib3, but it will still run just fine. It's now fixed in CVS and if there is a 1.8.10 release it will be fixed there. To build 1.8.9 on slib3 just remove the "require format" from src/engine/iso-currencies-to-c.


Q: GnuCash crashes on startup trying to run an SX. How do I fix this?

A: We're still trying to track down all the various SX problems. First, you should make sure you're running the most recent release. Second, if you're running the most recent release and still having problems you should file a bug report with all the output on your terminal (you ARE running gnucash from a terminal, RIGHT???). Third, you should backup your data file because the developers may want to see portions of it to help track down this problem. Finally, run: 
gnucash --nofile
then turn off the AutoRun option from Edit -> Preferences -> Scheduled Transactions . Then exit and restart GnuCash and it should open your data file just fine.


Q: What do I need to do to get GnuCash (1.8.10) to compile on Fedora Core 3?

A: At the very minimum, you'll need to download gal and g-wrap (as indicated in the README), followed by a series of rpm installs. Using yum (as su), you can issue the command "yum install X" where X is (one at a time): guile-devel, gnome-libs-devel, libxml, libxml-devel, gnome-print, gnome-print-devel, libglade, libglade-devel, gal-devel, gtkhtml, gtkhtml-devel, libghttp-devel, Guppi, Guppi-devel. The above packages are necessary, but may not be sufficient. -- contributed by apfejes - Dec 21, 2004 --

Q: GnuCash crashes when I run a Custom Report saying something about a Stack Overflow. What does this mean?

A: There is a problem with the Save Report feature when you save the report settings for a report with the same name as a default report. This problem manifests itself as a recursive execution and causes the program to crash. To keep yourself from hitting this bug, make sure you always change the name of a report before you try to "Save Report". To change the report name click the "Options" button in the toolbar. Note that the "Save Report" button really means "Save Report Options" or "Make Into Custom Report".

If you get into this situation the easiest way to get back a working system is to delete your saved reports: 

* exit gnucash
* delete ~/.gnucash/saved-reports-1.8*
* restart gnucash

Developing GNUCash: Source Code Overview

Q: Is the GnuCash team working on a gtk2 version?

A: Yes, the developers are working on a gtk2/gnome2 version of GnuCash, but it still takes a lot of time. See PortingStatus for status of the Gtk2 port. GnuCash makes use of several custom widgets as well as the Guppi graphing library. To port to gtk2 involves rewriting those widgets (e.g. the ledger, or the account hierarchy which uses GtkCTree) into the appropriate GTK2 widgets and would require the changing of the graphing code to probably use Jody's new graphing code in Gnumeric (Guppi was not ported to gtk2 and is a dead project). But given that the GnuCash team is extremely short on programmers, the process has to exist in parallel to existing product improvements, resulting in a very gradual porting process. If you can code C, by all means, volunteer your time.
This page contains known Gnome2 porting problems.
Some recent gnucash-devel discussion can be reviewed here and here.

Q: I heard it is too hard to compile GnuCash!

A: This was probably true at the time when 1.6.0 was released. It is no longer true today, as almost every distribution ships with all the necessary libraries (except g-wrap, which means there is in fact one extra library to be installed before compiling GnuCash). However, by default, distributions won't install the development packages of the required libraries, so you might need to start your distribution's installer program and tell it to install not only the library packages but also the -devel packages. In general, it was noted that this problem concerns many applications in the gnome domain, and this also boils down to the fact that there is no such thing as one monolithic gnome package.


Q: Ok, what devel packages do I need in order to compile GnuCash?

A: The exact names of the required packages vary a bit from distribution to distribution. For example, for an rpm-based distribution, you'll typically need at least: g-wrap-devel >= 1.3.4, gtkhtml-devel >= 0.8, Guppi-devel, gal-devel, libxml-devel, libglade-devel, libghttp-devel, python-devel, libtermcap-devel, readline-devel, and (optionally) post-gresql-devel. For more details see the Dependencies section of the README file.


Q: Why is GnuCash written in C?

A: The core functionality of GnuCash is written in C, but do not forget that much of this can be accessed through Guile (scheme). There are a number of reasons for why GnuCash is written in C. The first is historical, Gnucash was started in 1996 (or maybe even earlier!) and many of the OOP (C++, Java, Python) compilers were not yet mature and standarized enough on the variety of platforms considered at that time, so C was the only option at that time. A second reason is because the standard GUI GnuCash uses is GTK, which is written in C.


Q: Why don't you rewrite GnuCash in programming language xyz so that I can contribute easily?

A: The quick answer is "We won't". The longer answer is complex but still amounts to "We won't". GnuCash is a large body of code maintained by a small group of developers who are comfortable in C and Scheme (Guile). Actually, 80% of it is in C and approx. 13% is in Scheme/Lisp. There is no valid reason that would justify rewriting this amount of existing code in a newer language. Also, creating language bindings to recent languages such as Python or Ruby or (insert your favourite language here) is labour intensive, and we're already stretched pretty thin maintaining and developing the existing code.
Having said that, this is an open source project and you're free to do with it or contribute what you want. Just don't expect much support if the reason for your changes is that you're not willing to learn C or Scheme. Also, GnuCash used to have SWIG bindings [2] which have been used for some perl programming code. According to a discussion here, these SWIG bindings might still be a way to include other languages into GnuCash, but currently they are unused and unmaintained.

Q: I an having problems compiling g-wrap, specifically during configuring: "checking if guile long_long is at least as big as gint64... no checking if unsigned long is at least as big as guint32... no ./configure: exit: bad non-numeric arg `size'[[...]"

A: Try configuring guile to build with thread support (./configure --with-threads).

Glossary

Doxygen 
a tool for the automated generation of source code documentation. doxygen.org says that "Doxygen is a documentation system for C++, C, Java, IDL (Corba and Microsoft flavors) and to some extent PHP and C#."
g-wrap 
a tool for creating Scheme interfaces to C libraries and vice versa.
GIMP 
the Gnu Image Manipulation Package, i.e. a bitmap manipulation application.
gtk 
the GIMP Tool Kit. It is the underlying graphical library that is used by GIMP but also by the whole Gnome desktop. gtk.org says that "GTK+ is a multi-platform toolkit for creating graphical user interfaces. Offering a complete set of widgets, GTK+ is suitable for projects ranging from small one-off projects to complete application suites."
guile 
is an interpreter for the Scheme programming language, packaged as a library which can be incorporated into your programs. Other interpreters for Scheme are e.g. MIT Scheme, UMB Scheme, Luna, Hobbit, and many others.
Guppi 
a GNOME-based framework for graphing and interactive data analysis. This library created the pie charts and bar charts in GnuCash. Unfortunately, its development has been abandoned.
HBCI 
a bank-independent online banking protocol used by German banks. HBCI (Home Banking Computer Interface) has been developed by the German Central Banking Committee ZKA (Zentraler Kredit-Ausschuss). The standard is publicly available and is used by approx. 50% of German banks, but nowhere else in this world.
LibOFX 
an Open Source library for OFX (see below). It was created by one of the GnuCash developers (Benoit Gregoire), originally to be the OFX interface for GnuCash.
MT940 
a financial information standard defined by SWIFT and used by several European banks. It is also used internally in HBCI. Unfortunately, you can't download the MT940 standard, but some banks (like this one) publish it on their web site.
OFX 
the Open Financial eXchange format. This is a financial information standard (i.e. a file format standard) documented at http://www.ofx.net/ofx/default.asp
OpenHBCI 
an Open Source implementation of the German HBCI.
Scheme 
a functional programming language, a dialect of Lisp. The homepage is at scheme.org. There's a little more information at http://www.swiss.ai.mit.edu/projects/scheme/, where they'll tell you that "Scheme is a statically scoped and properly tail-recursive dialect of the Lisp programming language invented by Guy Lewis Steele Jr. and Gerald Jay Sussman."
Retrieved from "https://wiki.gnucash.org/wiki/index.php?title=FAQ&oldid=1551"