penny-bin-0.6.0.0: examples/stocks.pny
# This file documents some recommended practices for dealing
# with multi-commodity transactions.
# You might want to examine this tutorial that discusses
# multiple-commodity double-entry accounting generally; it is quite
# useful.
#
# http://www.mscs.dal.ca/~selinger/accounting/tutorial.html
# All the examples in the starter.pny file use dollars as the
# commodity. However, Penny is flexible: you can track any commodity
# you want. The simple rule is that all transactions must be
# balanced--that is, the sum of the debits must be equal to the sum of
# the credits. Each posting can have only one commodity. A debit sum
# of one commodity must be offset by a credit sum of the same
# commodity. So, let's say you buy 100 shares of F for $1 each. The
# following transaction is INVALID so it is commented out:
# 2012/12/19 Buy stock
# Assets:Checking > $100.00
# Assets:Brokerage < 100 F
# That transaction is not balanced. The $100 credit needs an
# offsetting $100 debit, and the debit of 100 F needs an offsetting
# credit of 100 F. Here's the method I recommend:
2012-10-19 Purchase stock
Assets:Brokerage < 100 F
Assets:Checking > $1000.00
Basis:F:2012-10-19 > 100 F
Basis:F:2012-10-19 < $1000.00
# Offsetting your debit and credit against a single Basis account will
# allow you to get more useful information out of your ledger file, as
# we will see later. By naming the Basis account as shown here (with
# the second sub-account being the commodity symbol, and the third
# sub-account being the date on which the commodity was purchased) the
# penny-selloff program will be able to help you out later when you
# sell the commodity.
# You will also want to enter a price into your file. The convert
# report will use this information. A price tells the convert report
# how to convert one commodity to another. Prices have no effect on
# any other Penny report. For instance this price expresses the price
# of the prevoius transaction:
@ 2012-10-19 F $10.00
# This means that one unit of F is equivalent to $10.00. Prices only
# work one way; that is, the price above does NOT tell Penny that
# $10.00 is equivalent to one unit of F. If you wanted to express
# that, include another price. It is only possible to express that ONE
# unit of some commodity is equal to some number of units of another
# commodity. For instance, this price would be invalid:
#
# @ 2012-10-19 100F $1000.00
# Any transaction that has two commodities will have at least four
# postings. This is because all transasctions in Penny must always be
# balanced, and every debit balance must be offset with a credit
# balance of the exact same commodity.
# A month later I sell my stock. Let's say it has done very well.
2012-11-19 Sell stock
Assets:Brokerage > 100 F
Assets:Checking < $1400.00
Basis:F:2012-10-19 < 100 F
Basis:F:2012-10-19 > $1400.00
# And a corresponding price:
@ 2012-11-19 F $14.00
# At this point, Basis:F:2012-10-19 has a credit balance of
# $400.00. This is your capital gain from the sale. You probably want
# to close out the Basis:F:2012-10-19 account by transferring its
# balance to an income account. (You could even do this in the same
# transaction as the stock sale.)
2012-11-19 Capital Gain
Basis:F:2012-10-19 < $400.00
{Income:Capital Gain:F:2012-10-19} > $400.00
# That's one way to do it. It's simple enough when you just have
# one lot of stock. What if you have a bunch of different lots?
# This can happen with dividend reinvestment especially. Here's
# an example:
2012-10-19 Purchase stock
Assets:Brokerage < 100 LUV
Assets:Checking > $1000.00
Basis:LUV:2012-10-19 > 100 LUV
Basis:LUV:2012-10-19 < $1000.00
2012-11-19 Purchase stock
Assets:Brokerage < 100 LUV
Assets:Checking > $1200.00
Basis:LUV:2012-11-19 > 100 LUV
Basis:LUV:2012-11-19 < $1200.00
2012-12-19 Purchase stock
Assets:Brokerage < 100 LUV
Assets:Checking > $1400.00
Basis:LUV:2012-12-19 > 100 LUV
Basis:LUV:2012-12-19 < $1400.00
# Okay, time to sell. Get rid of all the LUV. To get the capital gain
# right, it must be distributed amongst all the LUV purchases. You
# could do this yourself but who wants to? So enter a transaction
# like this first:
2012-12-31 Sell stock
Assets:Brokerage > 300 LUV
Assets:Checking < $4800.00
Proceeds:LUV:2012-12-31 < 300 LUV
Proceeds:LUV:2012-12-31 > $4800.00
# At this point your assets and brokerage accounts look good. If you
# don't care about capital gains, you can just stop here. But if you
# want to close out the Basis accounts, you can use the penny-selloff
# program. It creates transactions for you, which you can append to
# your Penny file. You pass penny-selloff two arguments: first, the
# name of the Proceeds account, and second, the filename to draw from.
# penny-selloff 'Proceeds:LUV:2012-12-31' filename
# penny-selloff will use all transactions from all the filenames
# given. First it will make sure that the given Proceeds account has a
# balance that consists of a debit amount and a credit amount with
# differing commodities. penny-selloff takes the debit amount to be
# the commodity you are selling off, and the credit amount of the
# balance is the amount you received in the sale.
# penny-selloff then takes the second sub-account from the given
# account. Here, it is LUV. It then looks for accounts named
# Basis:SUB-ACCOUNT:***. Here it looks for Basis:LUV:***. *** is a
# Penny date (and optional time.) All of these accounts that have a
# balance are totaled up. This total balance must have a credit
# balance that is greater than or equal to the debit balance of the
# Proceeds account, and a debit balance whose commodity is the same
# commodity as the credit balance of the Proceeds account.
# penny-selloff then computes a per-share price of the proceeds and
# calculates sale postings for each Basis account that has a
# balance. Shares are sold off on a FIFO (first-in, first-out) basis,
# so the oldest available shares are sold first. blah blah blah blah
# so for example, with the above transactions, running
# penny-selloff 'Proceeds:LUV:2012-12-31' stocks.pny
# will create a posting that looks like this:
;transaction created by penny-selloff for sale on 2012-12-31
2012-12-31 Realize gain or loss
Proceeds:LUV:2012-12-31 < $ 4800.00
Proceeds:LUV:2012-12-31 > LUV 300
Basis:LUV:2012-10-19 < LUV 100
Basis:LUV:2012-10-19 > $ 1000.00
{Income:Capital Gain:LUV:2012-12-31:2012-10-19} > $ 333.33
Basis:LUV:2012-11-19 < LUV 100
Basis:LUV:2012-11-19 > $ 1200.00
{Income:Capital Gain:LUV:2012-12-31:2012-11-19} > $ 400.01
Basis:LUV:2012-12-19 < LUV 100
Basis:LUV:2012-12-19 > $ 1400.00
{Income:Capital Gain:LUV:2012-12-31:2012-12-19} > $ 466.66
# Thus the capital gain shows up in the Capital Gain account, and all
# the Basis accounts and the Proceeds account have zero balances.
# You could also track commodities other than stocks. Let's say you
# buy a house.
2012-12-31 Buy a house
{Assets:Real Estate} < HouseA 1
Liabilities:Mortgage > $ 80 000.00
Assets:Savings > $ 20 000.00
'Down payment
Basis:House1:2012-12-31 > HouseA 1
Basis:House1:2012-12-31 < $ 100 000.00
@ 2012-12-31 HouseA $100 000.00
# And some more stock purchases that we can use as examples in the
# penny-commodities man page:
2012-09-17 Buy stock
Assets:Brokerage < 100 YHOO
Basis:YHOO:2012-09-17 > 100 YHOO
Assets:Checking > $1568.00
Basis:YHOO:2012-09-17 < $1568.00
@ 2012-09-17 YHOO $15.68
2012-11-16 Buy stock
Assets:Brokerage < 100 YHOO
Basis:YHOO:2012-11-16 > 100 YHOO
Assets:Checking > $1786.00
Basis:YHOO:2012-11-16 < $1786.00
@ 2012-11-16 YHOO $17.86
2012-12-18 Buy stock
Assets:Brokerage < 100 YHOO
Basis:YHOO:2012-12-18 > 100 YHOO
Assets:Checking > $1982.00
Basis:YHOO:2012-12-18 < $1982.00
@ 2012-12-18 YHOO $19.82
@ 2012-12-20 YHOO $19.69
# And your house is going up in value:
@ 2013-01-01 HouseA $101 000.00
@ 2013-06-01 HouseA $102 000.00
# And an example involving the purchase and sale of stock:
2012-01-03 Buy stock
Assets:Brokerage < 100 UNP
Assets:Checking > $10800.00
Basis:UNP:2012-01-03 > 100 UNP
Basis:UNP:2012-01-03 < $10800.00
2012-12-28 Sell stock
Assets:Brokerage > 100 UNP
Assets:Checking < $12354.00
Basis:UNP:2012-01-03 < 100 UNP
Basis:UNP:2012-01-03 > $12354.00
# Here is another example of a sale using a Proceeds account:
2012-01-03 Buy stock
Assets:Brokerage < 100 C
Assets:Checking > $3072.00
Basis:C:2012-01-03 > 100 C
Basis:C:2012-01-03 < $3072.00
2012-12-03 Sell stock
Assets:Brokerage > 100 C
Assets:Checking < $3901.00
Proceeds:C:2012-12-03 < 100 C
Proceeds:C:2012-12-03 > $3901.00