Start a journal

hledger reads transactions from, and appends new transactions to, a journal file. This is named after the General Journal in bookkeeping. You can specify it with -f FILE in hledger commands. But it's good to configure a default file, so that you don't have to write -f FILE every time.

hledger setup or hledger files will show if a default file is configured:

PS C:\Users\Simon> hledger files
hledger.exe: Error: data file "C:\Users\Simon\.hledger.journal" was not found.
Please create it first, eg with "hledger add" or a text editor.
Or, specify an existing data file with -f or $LEDGER_FILE.

If you know how to configure its path in the LEDGER_FILE environment variable, you can keep this file wherever you like. For example, you might have LEDGER_FILE=~/finance/main.journal, where ~/finance is a version-controlled directory.

If not, just use the default location: .hledger.journal in your home directory. You can move the file later if needed.

Start the journal

You can start the journal by running

hledger add

and adding a transaction. This will create the file if needed. We'll show this on the next page.

Start the journal, another way

Or if you prefer, you can create the file yourself with your favourite text editor.

On unix systems, eg:

emacs ~/.hledger.journal

or:

touch ~/.hledger.journal

On Windows:

notepad $HOME/.hledger.journal

or:

mv -ErrorAction SilentlyContinue ~/.hledger.journal ~/.hledger.journal.old
Set-Content -Path $HOME/.hledger.journal -Value ""

Note these Windows commands create the file with the system's text encoding, which is necessary.

(You can see what the system text encoding is by running [System.Text.Encoding]::Default.EncodingName. If you want your files to be compatible with non-Windows machines, the "Unicode (UTF-8)" encoding is best. For that, you might need to set "Language for non-Unicode programs > Use Unicode UTF-8 for worldwide language support".)

(Part of hledger by example.)