Obsidian/06.01 Finances/hLedger.md

---

Alias: ["Personal Accounting"]
Tag: ["🤖", "💲", "💻", "📲"]
Date: 2021-08-19
DocType: "Confidential"
Hierarchy: "Root2"
TimeStamp: 2021-08-19
location: [51.514678599999996, -0.18378583926867909]
CollapseMetaTable: true

---

Parent:: [[@Finances]]

---

 ^Top

 

```button
name Save
type command
action Save current file
id Save
```
^button-hLedgerSave

 

# hLedger

 

```ad-abstract
title: Summary
collapse: open
This note describes the workings of plain text accounting through hLedger
```

 

```toc
style: number
```

 

---

 

### Documentation

 

[Plain text Accounting](https://plaintextaccounting.org/)

[hledger](https://hledger.org/create-a-journal.html)

[Ledger manual](https://www.ledger-cli.org/3.0/doc/ledger3.html#index-account_002c-alias)

[Ledger helpers](https://github.com/ledger/ledger/wiki/Entering-transactions-with-ledgerhelpers-GUI-apps)

[Ledger help](https://github.com/ledger/ledger/wiki/Entering-data)

 

---

 

### hLedger

 

Plain Text Accounting is accessible through command-line clients like hledger.
Installation is simple:


```ad-command
~~~bash
brew install hledger
~~~
```

Some extensions may be required for certain functionalities to work and will be documented accordingly.

 

#### Structure

The structure of the tool and resulting file is rather simple. The tool offers two main functionalities:

1. **Import data**
hLedger allows for direct links to your bank or manual entries into the ledger.

2. **Reports on aggregated data**
A suite of reports is available to visualise financial data

The underlying database is a (collection of) file(s) readable through classic text editors with a list of the transactions made during the period.

 

#### Initialisation

At start of the year/period in any given file, a certain number of initialisations need to be made:

1. **Initialise top-level accounts**

```ad-code
~~~
account 'name of account'
~~~
```

2. **Currencies used**

```ad-code
~~~
commodity 'layout + number format'
~~~
```

2. **Opening balances**

```ad-code
~~~
'Date' set initial 'account name' account balance
	'account name'(+optional nesting -> :'sub-account') {+ 2 spaces min} 'amount'
	equity:opening balances
~~~
```

 

#### Accounts

1. **Aliasing**

Aliases can be defined for simplifying writing/reading accounts.

```ad-code
~~~bash
alias a=assets
alias c=a:Cash
~~~
```

Flags can be used in reports:

> [!command] 
> —recursive-aliases –> expand recursive aliases
> —no-aliases –> does not expand aliases

 

#### Transactions
[[#^Top|TOP]]
hLedger allows for three methods for entering transactions:

1. **Through command-line**

This method is well-guided with hLedger:


```ad-command
~~~bash
hledger add -f 'journalname'
~~~
```


The function will then prompt the user for appropriate entries.

2. **Manually into the .journal file**

Open the .journal file and manually enter transactions with the following format:

```ad-code
~~~
(date) 'transaction name'
	'account 1' {2+ spaces} (amount)
	'account 2' {2+ spaces} !(amount)
~~~
```

3. **Import**

```ad-command
title: Import from Note
~~~bash
hledger import -f 'journalname' 'filename'
~~~
```

 ```ad-note
title: CSV Import
hLedger requires a certain level of customisation to import .csv.
Instructions can be found [here](https://hledger.org/import-csv.html)
```

4. **Recurring transactions**

[Recurring transactions](https://hledger.org/hledger.html#periodic-transactions) do not really form part of hledger or plaintextaccounting per se. The below code helps to understand how recurring budgets can be declared:

```ad-code
~~~
~ monthly (or other periodicity) (optional 'from')
	(account 1):(sub-account 1) {2+ spaces} (amount)
	(account 2):(sub-account 2)
~~~
```

In order to create recurring transactions, scripts need to be written and cronjobs set. Find below an outline of the process.

 

Create a `.sh` file with the below code:

```ad-code
~~~sh
#!/bin/sh
LEDGER_RECURRING='/Volumes/Computer Vault/Wealth/Compta/.journal.ledger'
cat >> $LEDGER_RECURRING <<EOF

$(date +%Y/%m/%d) $3
  $2:CHF $1
  assets:Cash:CHF
EOF
~~~
```

&emsp;

Make sure that the file is executable:

`chmod a+wrx (filepath & name)`

&emsp;

Fill the cron job:

`crontab -e`

and then:

`0 0 28 * * $HOME/(script & arguments)`

&emsp;

#### Investments
[[#^Top|TOP]]
```ad-info
title: Documentation
The documentation can be found [here](https://hledger.org/investments.html)
```

1. **Adding an Investment**

Using a strict and clear nomenclature, an initial investment is inputed manually using the following block:

```ad-code
~~~
(Investment date)
	Investment:(sub-account):(asset-account) (units) (internal stock mnemonic)
	equity:conversion    -(units) (internal mnemonic)
	equity:conversion    (monetary amount)
	funding account      -(monetary amount)
~~~
```

2. **Price file**

A price file can be created separately to manage asset prices and actual transactions in separate docs. To this effect, both files are required to be in the same folder and the main journal carries the following command:


```ad-code
~~~
include (filename).prices
~~~
```

Prices are inputed as follows:

```ad-code
~~~
P (date) (asset1) (asset2)(conversion value)
~~~
```

3. **Re-pricing Investment**

Re-pricing happens through the price file by simply adding a 'P' command with a new date in the .prices file.

4. **Selling an investment**

To respect the coherence of the Accounting Equation, sales will follow the same nomenclature as purchases, with an explicit declaration of realised p&l:

```ad-code
~~~
(Investment date)
	Investment:(sub-account):(asset-account)   -(units) (internal stock mnemonic)
	equity:conversion    (units) (internal mnemonic)
	equity:conversion    -(monetary amount @ purchase)
	revenues:capital gain  -(p&l)
	receiving account      (monetary amount)
~~~
```

This flexibility enables to implement FIFO/LIFO as per prevailing fiscal rules.

&emsp;

#### Closing books
[[#^Top|TOP]]
In order to close books, revenues/expenses need to amount to 0 and only show Asset, Liability and Equity. The below is a growing mapping of revenues and expenses lines:

```ad-code
~~~
(Closing date)
	revenues:Salary   (outstanding balance) = 0
	revenues:investment income  (outstanding balance) = 0
	revenues:capital gains  (outstanding balance) = 0
	equity:retained earnings  -(resulting amount)
~~~
```

```ad-code
~~~
(Closing date)
	expenses   (outstanding balance) = 0
	equity:running costs   -(resulting amount)
~~~
```

&emsp;

#### Reports
[[#^Top|TOP]]
```ad-info
title: Documentation
Simple reports can be found [here](https://hledger.org/quickstart.html#run-reports)
```

**Income statement report**


```ad-command
~~~bash
hledger -f 'filename' is -Y (period argument) -3 (depth argument) -S (sorting by amount argument) -o (output file argument)
~~~
```


**Balance sheet report**

```ad-command
~~~bash
hledger -f 'filename' bs -Y (period argument) -V (optional price basis: end of year each year, local ccy; --value=end,(ccy) for forcing GBP/EUR) (optional --infer-value) -o (output file argument)
~~~
```


'bs' can be replaced by 'bse' to show the Equity block.

**ROI report**

```ad-command
~~~bash
hledger -f 'filename' roi --investment (investment account) -Y (period argument) --value=then,"(ccy)" --infer-market-price --pnl "unrealized"
~~~
```

**Arguments**

`--no-elide`: explicitly print all values

&emsp;

#### Tools

&emsp;

#### Useful commands

1.  <mark class="green">stats</mark>:  account stats (number of transactions, ccy, exchange rates, etc...)
2.  <mark class="green">print</mark>: transaction history
3.  <mark class="green">aregister</mark>: transaction history in a particular account
4.  <mark class="green">cashflow</mark>: summary of cashflows per asset account & ccy
5.  <mark class="green">balance</mark>: show account balances

&emsp;

#### Other commands

```ad-example
title: Specific tasks
[Error checking](https://hledger.org/checking-for-errors.html)

[Mac environment variables](https://hledger.org/hledger-web.html)
```

&emsp;

### Tasks & Further steps

&emsp;

```ad-question
title: To explore
- [!] Tax
- [!] Financial forecasting
```

- [x] [[hLedger]]: Tax for Investments ✅ 2022-01-22
- [x] [[hLedger]]: Financial forecasting ✅ 2022-01-22
- [ ] :heavy_dollar_sign: [[hLedger]]: Update Price file %%done_del%% 🔁 every 3 months on the 1st Friday 📅 2024-07-05
- [x] :heavy_dollar_sign: [[hLedger]]: Update Price file %%done_del%% 🔁 every 3 months on the 1st Friday 📅 2024-04-05 ✅ 2024-04-05
- [x] :heavy_dollar_sign: [[hLedger]]: Update Price file %%done_del%% 🔁 every 3 months on the 1st Friday 📅 2024-01-05 ✅ 2024-01-05
- [x] :heavy_dollar_sign: [[hLedger]]: Update Price file %%done_del%% 🔁 every 3 months on the 1st Friday 📅 2023-10-06 ✅ 2023-10-06
- [x] :heavy_dollar_sign: [[hLedger]]: Update Price file %%done_del%% 🔁 every 3 months on the 1st Friday 📅 2023-07-07 ✅ 2023-07-07
- [x] :heavy_dollar_sign: [[hLedger]]: Update Price file %%done_del%% 🔁 every 3 months on the 1st Friday 📅 2023-04-07 ✅ 2023-04-07
- [ ] :heavy_dollar_sign: [[hLedger]]: Update current ledger %%done_del%% 🔁 every 3 months on the 1st Friday 📅 2024-07-05
- [x] :heavy_dollar_sign: [[hLedger]]: Update current ledger %%done_del%% 🔁 every 3 months on the 1st Friday 📅 2024-04-05 ✅ 2024-04-05
- [x] :heavy_dollar_sign: [[hLedger]]: Update current ledger %%done_del%% 🔁 every 3 months on the 1st Friday 📅 2024-01-05 ✅ 2024-01-05
- [x] :heavy_dollar_sign: [[hLedger]]: Update current ledger %%done_del%% 🔁 every 3 months on the 1st Friday 📅 2023-10-06 ✅ 2023-10-06
- [x] :heavy_dollar_sign: [[hLedger]]: Update current ledger %%done_del%% 🔁 every 3 months on the 1st Friday 📅 2023-07-07 ✅ 2023-07-14
- [x] :heavy_dollar_sign: [[hLedger]]: Update current ledger %%done_del%% 🔁 every 3 months on the 1st Friday 📅 2023-04-07 ✅ 2023-04-07

&emsp;
&emsp;