User FAQ

Why does this entry give a "no amount" error even though I wrote an amount ?

2019-01-01
  a 1
  b

Because there's only a single space between a and 1, so this is parsed as an account named "a 1", with no amount. There must be at least two spaces between account name and amount.

Why do some directives not affect other files ? Why can't I put account aliases in an included file ?

This is documented at journal format: directives. (Also mentioned at hledger: Input files.) These docs could be improved.

Directives which affect parsing of data vary in their scope, ie the area of input data they affect. Eg, should they affect:

  • entries after the directive, in this file only ?
    • Eg: alias, apply account, comment, Y
  • entries before and after the directive, in this file only ?
  • entries and included files after the directive, until this file's end ?
  • all entries after the directive, in this and all included or subsequent files, including parent files ?
    • Eg: the number notation specified by D or commodity
  • all entries in all files ?
    • Eg: the default commodity specified by D, and account

The differences are partly due to historical accident, and partly by design. We would like to preserve these properties:

  • Reordering files does not change their meaning.
  • Adding a file does not change the meaning of the other files.

This is why some directives are designed to last only until the end of the current file. This can be annoying, but it seems worthwhile to ensure reports are robust, and not changed by simply moving include directives or -f options around.

For alias directives, when you have multiple files, the workaround is to put them inline in a top-level file, before including the other files that the aliases should affect. See #1007.

See also: #510, #217

Why am I seeing some amounts without an account name in reports ?

Some of hledger's older commands (balance, print, register) show a multi-commodity amount with each commodity on its own line, by default (like Ledger).

Here are some examples. In the following journal entry, the implicit balancing amount drawn from the b account will be a multicommodity amount (a euro and a dollar):

2015/1/1
    a         EUR 1
    a         USD 1
    b

the print command shows the b posting's amount on two lines, bottom-aligned:

$ hledger -f t.j print
2015/01/01
    a         USD 1
    a         EUR 1
             EUR -1  ; <-
    b        USD -1  ; <- a euro and a dollar is drawn from b

the balance command shows that both a and b have a multi-commodity balance (again, bottom-aligned):

$ hledger -f t.j balance
               EUR 1     ; <-
               USD 1  a  ; <- a's balance is a euro and a dollar
              EUR -1     ; <-
              USD -1  b  ; <- b's balance is a negative euro and dollar
--------------------
                   0

while the register command shows (top-aligned, this time!) a multi-commodity running total after the second posting, and a multi-commodity amount in the third posting:

$ hledger -f t.j register --width 50
2015/01/01       a             EUR 1         EUR 1
                 a             USD 1         EUR 1  ; <- the running total is now a euro and a dollar        
                                             USD 1  ;                                                        
                 b            EUR -1                ; <- the amount posted to b is a negative euro and dollar
                              USD -1             0  ;

Newer reports like multi-column balance reports show multi-commodity amounts on one line instead, comma-separated. Although wider, this seems clearer and we should probably use it more:

$ hledger -f t.j balance --yearly
Balance changes in 2015:

   ||           2015 
===++================
 a ||   EUR 1, USD 1 
 b || EUR -1, USD -1 
---++----------------
   ||              0

You will also see amounts without a corresponding account name if you remove too many account name segments with --drop (a bug, which we'd like to see fixed):

$ hledger -f t.j balance --drop 1
               EUR 1  
               USD 1  
              EUR -1  
              USD -1  
--------------------
                   0

With hledger-ui in iTerm2/3, why does Shift-Up/Shift-Down move the cursor instead of adjusting the period ?

One way to fix: in iTerm2 do Preferences -> Profiles -> your current profile -> Keys -> Load Preset -> xterm Defaults (not Terminal.app Compatibility). And perhaps open a new tab with this profile.

How do I display a decimal separator different from the one in the input file ?

It's not yet easy to do this with hledger:
https://github.com/simonmichael/hledger/issues/793#issuecomment-603994809

There's just one special case where it works, by a quirk of the implementation: if in the journal you use space as thousands separator, comma as decimal separator, and no commodity directive, hledger will print numbers with period as decimal separator:

; journal
2020-01-01
    (a)       $1 234,56

$ hledger print
2020-01-01
    (a)       $1 234.56

Here's a more general workaround, post-processing the output with sed. Adjust if needed:

; journal
2020-01-01
    (a)       $1.234,56

$ hledger print
2020-01-01
    (a)       $1.234,56

$ hledger print | sed 's/\./~/g; s/,/./g; s/~/,/g'
2020-01-01
    (a)       $1,234.56

How do I control the number of decimal places displayed ?

Use a commodity directive

to set the commodity's display style. Eg:

commodity $1000.00
commodity EUR 1.000,
commodity 1000.00000000 BTC

How could I import/migrate from...

Some quick/rough migration recipes:

Mint.com ?

  1. download examples/csv/mint.csv.rules, and adjust the account1 & account2 rules
  2. touch ~/.hledger.journal
  3. log in to Mint, go to TRANSACTIONS, scroll to the bottom of the page, click on the "Export all N transactions" link, save it as mint.csv on your computer
  4. cd ~/Downloads (or wherever you saved it)
  5. hledger import mint.csv

Now hledger stats and hledger bal should show lots of data. That's your past data migrated.

Then, if you want to leave Mint, you'll need to replace their automatic import from banks with your own import process.

Or if you want to keep using Mint for that, because you like how they aggregate and clean the data: just periodically re-export from Mint, repeating steps 3-5 above.