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 (see the next page for an example). (If you're using hledger 1.50.3-1.51.1, hledger add -f ~/.hledger.journal is needed.)

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

Files containing non-ascii characters should use the system's text encoding. (See Install: Text encoding.)

On Windows:

notepad $HOME/.hledger.journal

or:

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

These Windows commands ensure the file uses system's text encoding. You can see what your system text encoding is by running [System.Text.Encoding]::Default.EncodingName or hledger setup.

If you need 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.)