8.4 KiB
| Alias | Tag | Date | DocType | Hierarchy | TimeStamp | location | CollapseMetaTable | |||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
|
2021-08-19 | Confidential | Root2 | 2021-08-19 |
|
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
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:
-
Import data hLedger allows for direct links to your bank or manual entries into the ledger.
-
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:
- Initialise top-level accounts
~~~
account 'name of account'
~~~
- Currencies used
~~~
commodity 'layout + number format'
~~~
- Opening balances
~~~
'Date' set initial 'account name' account balance
'account name'(+optional nesting -> :'sub-account') {+ 2 spaces min} 'amount'
equity:opening balances
~~~
Accounts
- 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:
- 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.
- 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)
~~~
- 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)
- 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
title: Documentation
The documentation can be found [here](https://hledger.org/investments.html)
- 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)
~~~
- 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)
~~~
- Re-pricing Investment
Re-pricing happens through the price file by simply adding a 'P' command with a new date in the .prices file.
- 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
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
- stats: account stats (number of transactions, ccy, exchange rates, etc...)
- print: transaction history
- aregister: transaction history in a particular account
- cashflow: summary of cashflows per asset account & ccy
- balance: show account balances
Other commands
title: Specific tasks
[Error checking](https://hledger.org/checking-for-errors.html)
Tasks & Further steps
title: To explore
- [!] Tax
- [!] Financial forecasting
- hLedger: Tax for Investments ✅ 2022-01-22
- hLedger: Financial forecasting ✅ 2022-01-22
- [S] 💲 hLedger: Update Price file %%done_del%% 🔁 every 3 months on the 1st Friday 📅 2023-04-07
- [S] 💲 hLedger: Update current ledger %%done_del%% 🔁 every 3 months on the 1st Friday 📅 2023-04-07