Obsidian/06.01 Finances/hLedger.md

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

Parent:: @Finances

---

^Top

 

name Save
type command
action Save current file
id Save

^button-hLedgerSave

 

hLedger

 

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

 

style: number

 

---

 

Documentation

 

Plain text Accounting

hledger

Ledger manual

Ledger helpers

Ledger help

 

---

 

hLedger

 

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

~~~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

~~~
account 'name of account'
~~~

2. Currencies used

~~~
commodity 'layout + number format'
~~~

2. Opening balances

~~~
'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.

~~~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 hLedger allows for three methods for entering transactions:

1. Through command-line

This method is well-guided with hLedger:

~~~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:

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

3. Import

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

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 do not really form part of hledger or plaintextaccounting per se. The below code helps to understand how recurring budgets can be declared:

~~~
~ 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:

~~~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
~~~

 

Make sure that the file is executable:

chmod a+wrx (filepath & name)

 

Fill the cron job:

crontab -e

and then:

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

 

Investments

#^Top

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:

~~~
(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:

~~~
include (filename).prices
~~~

Prices are inputed as follows:

~~~
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:

~~~
(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.

 

Closing books

#^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:

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

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

 

Reports

#^Top

title: Documentation
Simple reports can be found [here](https://hledger.org/quickstart.html#run-reports)

Income statement report

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

Balance sheet report

~~~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

~~~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

 

Tools

 

Useful commands

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

 

Other commands

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

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

 

Tasks & Further steps

 

title: To explore
- [!] Tax
- [!] Financial forecasting

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