In previous post I introduced you to Ledger by showing you its basic functionality, how movements are tracked, and how to query it to extract useful information. I also mentioned how the potential of this software was much wider. Today it’s time to show you how to use it to track your investments.
What is a commodity
From an economic/financial point of view, the term commodity indicates a good whose value does not vary according to its source. So the euro can be seen as a commodity because a euro is always worth the same regardless of who we receive it from. The same applies to a gold bar or a barrel of oil. Apples, on the other hand, are not really commodities because their source also influences the quality of the product. In Ledger, commodities are defined in a broader way and can be seen as the unit of measure of transactions. In the first post I told you that within a Ledger journal money movements between accounts are tracked, but actually the concept can be generalized as it is possible to use transactions to move things from one account to another.
Ledger doesn’t require an explicit definition of commodities, but I recommend using it as it makes things cleaner.
The definition of commodities is done inside the journal by means of the keyword commodity followed by its symbol.
For example we can define the commodity euro with the following notation.
commodity EUR
default
In this case we have also used the keyword default to indicate that the commodity in question is the primary one.
Track investments
Financial instruments and securities are mentioned below, their use is for example purposes only and should not be construed as advice to sell or buy.
The example journal is available here
Let’s assume you have 2000€ to invest and you want to do it through a D.C.A. on an ETF1 All-World like the VWCE. So first let’s go enter the new commodity into the Journal and create the opening transaction.
commodity VWCE
2022-01-01 Opening Balances
assets:current:checking 2000 EUR
equity:open -2000 EUR
We can check the correctness of the data entered through the command balance.
2000 EUR assets:current:checking
-2000 EUR equity:open
--------------------
0
We don’t want to invest all our capital in one go, and decide to invest a maximum of 500€ each month to buy as many shares of our ETF as possible. Assuming that a share in January costs 95€, we will be able to buy five shares. We can describe this scenario in Ledger through the following transaction.
2022-01-03 ETF All-World
assets:investments:pac 5 VWCE @ 95 EUR
assets:current:checking
With this notation we are telling Ledger that on January 3 we purchased 5 units of the ETF VWCE at a price of 95 EUR each[^total-price].
The total purchase cost is not explicitly stated, but Ledger is smart enough to know that it is equivalent to 475€ (5 * 95).
Let’s check the result of this transaction through the balance command.
1525 EUR
5 VWCE assets
1525 EUR current:checking
5 VWCE investments:pac
-2000 EUR equity:open
--------------------
-475 EUR
5 VWCE
Here we start to see something interesting.
When using multiple commodities, the command balance, shows the balance of the accounts in both commodities.
In this case the assets account balance is 1525 EUR, but there are also 5 ETF shares.
February arrives and we buy more shares. During the month of January the stock has appreciated so now a share costs 99€. So in Ledger we will have the following transaction.
2022-02-01 ETF All-World
assets:investments:pac 5 VWCE @ 99 EUR
assets:current:checking
And running the balance command gives the following output:
1030 EUR
10 VWCE assets
1030 EUR current:checking
10 VWCE investments:pac
-2000 EUR equity:open
--------------------
-970 EUR
10 VWCE
We continue with our accumulation plan and in March we go to execute a new order. In this case the single share costs 102€ so we will only be able to buy four shares as we have decided to spend a maximum of 500€ per month. The transaction on the journal will be of the type:
2022-03-01 ETF All-World
assets:investments:pac 4 VWCE @ 102 EUR
assets:current:checking
I think at this point the mechanism is pretty clear to you.
All very nice, but it would be useful to see your balance sheet in euros so that we can understand how much our assets are today.
We can pursue our goal through the --exchange flag which allows us to convert all commodities into one currency.
But how to convert them?
Ledger allows us to perform two conversions, one based on the purchase price (--basis) and one based on the current market value (--market).
So by running the command ledger -f ledger.journal balance --exchange EUR --basis you get the following result:
2000 EUR assets
622 EUR current:checking
1378 EUR investments:pac
-2000 EUR equity:open
--------------------
0
As you can see the balance of the account assets:investments:pac is 1378 EUR.
From where it comes out?
As said the flag --basis considers the purchase price, so we will have 5 shares purchased at 95€, plus 5 shares purchased at 99€ and finally 4 shares purchased at 102€, taking the calculator and adding the sum we get just 1378€.
Interesting, but it is not what we wanted to obtain, we are interested to know the value of our patrimony today so we must use the flag --market.
In this case we get:
2050 EUR assets
622 EUR current:checking
1428 EUR investments:pac
-2000 EUR equity:open
--------------------
50 EUR
In this case the calculation is much easier just take the number of ETF shares (14) and multiply it by the last known value, from the time point of view, in this case 102€.
How much have we gained (or lost)?
You can calculate the difference between the value obtained with the flag --market and the one with --basis or exploit the potentialities of Ledger and use the command register with the flag --gain obtaining the following result:
2022-02-01 Commodities revalued <Revalued> 20 EUR 20 EUR
2022-03-01 Commodities revalued <Revalued> 30 EUR 50 EUR
In two months we have earned 50€, not bad!
Record price variations
In the previous example, the price of the ETF changed over time.
Ledger noticed this change from our purchases.
Now you may be wondering: “Is it possible to update the price of a commodity without having to buy it?.
The answer is trivially yes, just add within the journal the P directive.
P 2022-03-04 VWCE 100 EUR
This line is telling Ledger that on March four, the price of a share of the VWCE ETF is €100.
Try adding this P directive to the journal and running the command ledger -f ledger.journal register pac --gain you should find that we are still in the positive, but have made less money.
Registering a sale
A couple of days have passed, in which you have realized that you are not yet ready for the stock markets; all this up and down creates anxiety. In the meantime, the price of the ETF has risen slightly and is at 101€ a share so you decide to sell everything, but how do you record a sale of a commodity in Ledger? First let’s look at the transaction and then I’ll explain what it means.
2022-03-09 ETF All-Warld
assets:investments:pac -5 VWCE {95 EUR} @ 101 EUR
assets:investments:pac -5 VWCE {99 EUR} @ 101 EUR
assets:investments:pac -4 VWCE {102 EUR} @ 101 EUR
income:gain -36 EUR
assets:current:checking 1414 EUR
The notation used for the sale seems similar to that used for the purchase, but has a new feature, the use of curly brackets.
The line -5 VWCE {95 EUR} @ 101 EUR is telling Ledger that we are selling 5 units of the ETF at a price of 101 EUR per unit.
It is also specifying that these shares were originally purchased at 95 EUR per share, so Ledger knows that on this batch of shares we earned 6 EUR per share.
The profit from the sale of these fourteen shares is 1414€, the difference between the purchase price and the sale price is 36€ which is our gain (before tax).
An ETF is a fund that can be traded in the markets. The funds within them can contain several financial securities. For example, an All-World equity ETF contains within it equity securities of companies from all over the world. ↩︎