Robust, fast, intuitive plain text accounting tool with CLI, TUI and web interfaces.
Fixes
A performance slowdown since 1.29, especially noticeable with many accounts and transactions, has been fixed. #2153
Balance assertions involving mixed-cost balances are checked correctly again (a regression in 1.30). #2150
import --catchup works again (a regression in 1.32). #2156
--anon is now a deprecated hidden flag that raises an error, but is still usable as --obfuscate (also hidden). #2133
Balance assertion error messages are clearer, and show the diff again.
Use hledger-1.32.3
Allow vty 6.2, brick 2.3
bin/hledger-bar: Fix an error when NO_COLOR is not defined; allow color when NO_COLOR is defined but empty, per no-color spec; and fix shellcheck warnings. #2159 (Colin Dean, Simon Michael)
bin/hledger-simplebal: Fix shellcheck warnings. (Colin Dean)
Simon Michael, Colin Dean.
At https://hledger.org/install, binary packages should be available for this release within a few days (look for green badges).
Or, you can build from source as described there, after cloning at tag 1.32.3
:
git clone https://github.com/simonmichael/hledger --depth 1 -b 1.32.3
Or, if under "Assets" below there are release binaries suitable for your OS and hardware, you can use those.
Here are platform-specific instructions for the release binaries. (You can copy & paste each block of commands as a unit to save time.):
At the command line,
cd /usr/local/bin
curl -LOC- https://github.com/simonmichael/hledger/releases/download/1.32.3/hledger-linux-x64.zip # can rerun if interrupted
unzip hledger-linux-x64.zip; tar xvf hledger-linux-x64.tar; rm hledger-linux-x64.{zip,tar} # github workaround, preserves permissions
cd -
hledger --version # should show the new version
touch $HOME/.hledger.journal # ensure a default journal file exists
In a terminal window,
cd /usr/local/bin
curl -LOC- https://github.com/simonmichael/hledger/releases/download/1.32.3/hledger-mac-x64.zip
unzip hledger-mac-x64.zip; tar xvf hledger-mac-x64.tar; rm hledger-mac-x64.{zip,tar} # github workaround, preserves permissions
open .
# for the hledger, hledger-ui, hledger-web icons: right-click, Open, confirm it's ok to run
cd -
hledger --version # should show the new version
touch $HOME/.hledger.journal # ensure a default journal file exists
In a powershell window (press Windows-r, type powershell, press enter),
mkdir -force $HOME\bin >$null
$ENV:PATH += ";"+$HOME+"\bin"
[Environment]::SetEnvironmentVariable("Path", [Environment]::GetEnvironmentVariable("Path", [EnvironmentVariableTarget]::User)+";"+$HOME+"\bin", [EnvironmentVariableTarget]::User)
cd $HOME\bin
curl https://github.com/simonmichael/hledger/releases/download/1.32.3/hledger-windows-x64.zip -OutFile hledger-windows-x64.zip
Expand-Archive hledger-windows-x64.zip -DestinationPath .
rm hledger-windows-x64.zip
cd $HOME
hledger --version # should show the new version
out-file -append -encoding ascii $HOME/.hledger.journal
Once that journal file exists, you can start hledger-web by double-clicking on the icon if you wish.
echo %PATH%
, like C:\Windows
(though that one will require administrator permission); otherwise, your home directory (C:\Users\YOURNAME
)\Windows
, you'll need to scroll down)hledger --version
should show the new versionecho # >> .hledger.journal
to ensure a default journal file exists. (Important: the doubled >> is needed to avoid overwriting existing data.)Problems:
Fixes
In CSV field assignments, %FIELD interpolation and \n
can be used together again. #2134
In timedot data, numbers beginning with a decimal point are accepted again. #2130
In a balance --budget
report, --layout=tall
no longer hides commodity symbols.
Value reports seeing a pathological price chain with 1000 or more steps now write their warning to the console, not a debug log file.
Improvements
Docs
Features
Improvements
Use Notepad as default editor on Windows (ShrykeWindgrace)
Allow brick 2.2 (Vekhir)
Allow megaparsec 9.6
Fixes
Startup messages are more accurate and informative, eg with --socket
. #2127
The non-working --file-url
option has been dropped for now. #2139
Improvements
Allow megaparsec 9.6
hledger-web's tests now respect and can test command line options.
hledger-web's tests now run the app at 127.0.0.1 and port 5000, rather than "any of our IPv4 or IPv6 addresses" and 3000.
2024-01-05: Windows zip file fixed to include hledger-ui.
Fixed: import
with multiple files now updates .latest files correctly. (#2125)
Fixed: print --round=hard
now properly pads/rounds amounts with inferred costs. (#2123)
CSV matcher syntax: mention that ! and & can't be used in the same line yet. (#2088)
Drop the "a difference of ..." line from balance assertion failure output. I feel it made the message harder to read and isn't really necessary.
Declaring the empty payee name with payee ""
now works,
to let hledger check payees
accept payee-less transactions.
(#2119)
Built-in tags with special meaning like type:
and t:
are now implicitly declared,
so using type: in account declarations or generating t: with timedot letters
won't cause hledger check tags
to fail.
(#2119)
At https://hledger.org/install, binary packages should be available for this release within a few days (look for green badges).
Or, you can build from source as described there, after cloning at tag 1.32.1
:
git clone https://github.com/simonmichael/hledger --depth 1 -b 1.32.1
Or, if under "Assets" below there are release binaries suitable for your OS and hardware, you can use those.
Here are platform-specific instructions for the release binaries. (You can copy & paste each block of commands as a unit to save time.):
At the command line,
cd /usr/local/bin
curl -LOC- https://github.com/simonmichael/hledger/releases/download/1.32.1/hledger-linux-x64.zip # can rerun if interrupted
unzip hledger-linux-x64.zip; tar xvf hledger-linux-x64.tar; rm hledger-linux-x64.{zip,tar} # github workaround, preserves permissions
cd -
hledger --version # should show the new version
touch $HOME/.hledger.journal # ensure a default journal file exists
In a terminal window,
cd /usr/local/bin
curl -LOC- https://github.com/simonmichael/hledger/releases/download/1.32.1/hledger-mac-x64.zip
unzip hledger-mac-x64.zip; tar xvf hledger-mac-x64.tar; rm hledger-mac-x64.{zip,tar} # github workaround, preserves permissions
open .
# for the hledger, hledger-ui, hledger-web icons: right-click, Open, confirm it's ok to run
cd -
hledger --version # should show the new version
touch $HOME/.hledger.journal # ensure a default journal file exists
In a powershell window (press Windows-r, type powershell, press enter),
mkdir -force $HOME\bin >$null
$ENV:PATH += ";"+$HOME+"\bin"
[Environment]::SetEnvironmentVariable("Path", [Environment]::GetEnvironmentVariable("Path", [EnvironmentVariableTarget]::User)+";"+$HOME+"\bin", [EnvironmentVariableTarget]::User)
cd $HOME\bin
curl https://github.com/simonmichael/hledger/releases/download/1.32.1/hledger-windows-x64.zip -OutFile hledger-windows-x64.zip
Expand-Archive hledger-windows-x64.zip -DestinationPath .
rm hledger-windows-x64.zip
cd $HOME
hledger --version # should show the new version
out-file -append -encoding ascii $HOME/.hledger.journal
Once that journal file exists, you can start hledger-web by double-clicking on the icon if you wish.
echo %PATH%
, like C:\Windows
(though that one will require administrator permission); otherwise, your home directory (C:\Users\YOURNAME
)\Windows
, you'll need to scroll down)hledger --version
should show the new versionecho # >> .hledger.journal
to ensure a default journal file exists. (Important: the doubled >> is needed to avoid overwriting existing data.)Problems:
More precision control, beancount output, TSV output, --summary-only, strict/idempotent import, CSV rule enhancements, timedot letters, fixes.
Breaking changes
Display styles and display precision are now managed more carefully during calculations and output, fixing a number of issues (#2111, "Precisiongeddon"). In brief:
Cost and value reports, such as print -V
, now (1) consistently
apply commodity display styles, and (2) do not add or discard
decimal digits unnecessarily. (#2105)
When "infinite decimals" arise during calculations (eg in value
reports, or in prices
or roi
output), these are now shown
limited to 8 decimal digits rather than 255.
Non-print-like reports no longer add trailing decimal marks to disambiguate digit group marks (this was an unintended regression in 1.31). (#2115)
We now document number formatting adjustments made in certain reports and output formats (hledger manual > REPORTING CONCEPTS > Amount formatting, parseability).
Features
Timedot format supports a new letters syntax for easier tagged time logging. (#2116)
print
has a new beancount
output format for exporting to Beancount.
This prints journal output more likely (though not guaranteed) to
be readable by Beancount.
In CSV rules, matchers using regular expressions can now interpolate their matched texts into the values they assign to fields (field assignment values can reference match groups). (#2009) (Jonathan Dowland)
In CSV rules, matchers can be negated by prepending !
.
(#2088) (bobobo1618)
Multi-column balance reports (from bal
, bs
, is
etc.) can use
the new --summary-only
flag (--summary
also works) to display
just the Total and Average columns (if enabled by --row-total
and
-A/--average
) and hide the rest.
(#1012) (Stephen Morgan)
All commands that suport csv output now also support tsv
(tab-separated values) output. The data is identical, but the fields
are separated by tab characters and there is no quoting or
escaping. Tab, carriage return, and newline characters in data are
converted to spaces (this should rarely if ever happen in practice).
(#869) (Peter Sagerson).
Improvements
Journal format no longer fails to parse Ledger-style lot costs with spaces
after the {
, improving Ledger compatibility.
import
now does not update any .latest files until it has run
without error (no failing strict checks, no failure while writing
the journal file). This makes it more idempotent, so you can run it
again after fixing problems.
print
now shows zeros with a commodity symbol and decimal digits
when possible, preserving more information.
print
has a new option for controlling amount rounding (#2085):
--round=none
- show amounts with original precisions (default;
like 1.31; avoids implying less or more precision than was
recorded)
--round=soft
- add/remove decimal zeros in non-cost amounts
(like 1.30 but also affects balance assertion amounts)
--round=hard
- round non-cost amounts (can hide significant digits)
--round=all
- round all amounts and costs
For the record:
print
shows four kinds of amount: posting amounts,
balance assertion amounts, and costs for each of those.
Past hledger versions styled and rounded these inconsistently.
Since 1.31 they are all styled, and since 1.32 they are rounded as follows:
hledger-1.32 print | amt | cost | bal | balcost |
---|---|---|---|---|
(default) | none | none | none | none |
--round=soft | soft | none | soft | none |
--round=hard | hard | none | hard | none |
--round=all | hard | hard | hard | hard |
The prices
command has had a number of fixes and improvements (#2111):
It now more accurately lists the prices that hledger would use
when calculating value reports (similar to what you'd see with
hledger bal -V --debug=2
).
The --infer-reverse-prices flag was confusing, since we always
infer and use reverse prices; it has been renamed to --show-reverse
.
--show-reverse
and --infer-market-prices
flags now combine properly.
--show-reverse
now ignores zero prices rather than giving an error.
Price amounts are now shown styled.
Price amounts are now shown with all their decimal digits; or with 8 decimal digits if they appear to be infinite decimals (which can arise with reverse prices).
Filtering prices with cur:
or amt:
now works properly.
Fixes
print
now styles balance assertion costs consistently, like other
amounts.
import
now works with -s/--strict
.
And more generally, when reading multiple input files, eg with
multiple -f
options, strict checks are done only for the overall
combined journal (not for each individual file).
(#2113)
tag:
queries now work when reading CSV files. (#2114)
Using a .json
or .sql
file extension with -o
/--outputfile
now properly selects those output formats.
Auto postings no longer break redundant equity/cost detection and transaction balancing. (#2110)
Amounts set by balance assignment now affect commodity styles again. (#2091, a regression in 1.30)
Timedot quantities with units are parsed more accurately. Eg a quantity like "15m" was evaluated as 0.249999999 not 0.25, and since hledger 1.21, it was printed that way also. Now we round such quantities to two places during parsing to get exact quarter-hour amounts. (#2096)
The demo
command no longer triggers a JSON decode error in asciinema
2.3.0. It now also shows a better error message if asciinema fails
(#2094).
Failing balance assertions with a cost now show correct markers in the error message. (#2083)
Docs
New:
Updated:
Fixes
The V key now preserves the valuation mode specified at the command line, if any. (#2084)
The hledger-ui package no longer wastefully builds its modules twice.
Features
Improvements
The --capabilities and --capabilities-header options have been replaced
with an easier --allow=view|add|edit|sandstorm
option.
add
is the default access level, while sandstorm
is for use on Sandstorm.
UI and docs now speak of "permissions" rather than "capabilities".
(#834)
The Sandstorm app's permissions and roles have been renamed for clarity. (#834)
Permissions are now checked earlier, before the web app is started, producing clearer command line errors when appropriate.
Account's adeclarationinfo
field is now included in JSON output. (#2097) (S. Zeid)
Fixes
The app can now serve on address 0.0.0.0 (exposing it on all interfaces), which previously didn't work. (#2099) (Philipp Klocke)
The broken "File format help" link in the edit form has been fixed. (#2103)
Scripts/addons
hledger-install.sh: replaced hledger-stockquotes with pricehist
added gsheet-csv.hs: fetch a google sheet as CSV
added hledger-report1: an example custom compound report, with haskell and bash versions
justfile: updated import, time report scripts
Examples
New:
Updated:
Docs
New:
Updated:
cli
class instead of shell
for command-line examples,
avoiding inaccurate highlighting.Infrastructure
hledger.org website:
Fixed the webhook that was not updating the site on git push.
Fixed a problem with cloudflare authentication that was preventing automatic TLS certificate renewal on hledger.org.
Updated and committed hledger.org's caddy config and short urls (redirects)
Enabled https for code.hledger.org and site.hledger.org short urls.
Updated the stars.hledger.org redirect (we have reached the top 30 github-starred Haskell projects 🌟 🎉).
Set up a self-hosted Sandstorm server, and a public hledger-web instance (sandbox.hledger.org) in it that is fully writable (until spammers find it). Use it as a pastebin for examples, eg.
Github CI (continuous integration) workflows have been optimised somewhat:
Scheduled weekly builds have been disabled, as they were propagating to forks and running wastefully there in some cases.
Some repeated rebuilding of the hledger-lib and hledger packages that seems unnecessary has been stopped.
hledger-ui no longer builds its modules twice.
Haddock testing now done only at release time.
renamed main CI workflow and branch to "ci"
Tools:
.ghci: added an :rmain alias, which is like :main but reloads first - saves typing, and is useful eg when changing --debug level.
make haddock-watch is now fast
Finance
Updated project finance scripts, regenerated the journal with consistent precisions.
Updated reports with the last few months of data from Open Collective.
Simon Michael, Jonathan Dowland, S. Zeid, Charlie Ambrose, Jacob Weisz, Peter Sagerson, Philipp Klocke, Stephen Morgan, bobobo1618.
At https://hledger.org/install, binary packages should be available for this release within a few days (look for green badges).
Or, you can build from source as described there, after cloning at tag 1.32
:
git clone https://github.com/simonmichael/hledger --depth 1 -b 1.32
Or, if under "Assets" below there are release binaries suitable for your OS and hardware, you can use those.
Here are platform-specific instructions for the release binaries. (You can copy & paste each block of commands as a unit to save time.):
At the command line,
cd /usr/local/bin
curl -LOC- https://github.com/simonmichael/hledger/releases/download/1.32/hledger-linux-x64.zip # can rerun if interrupted
unzip hledger-linux-x64.zip; tar xvf hledger-linux-x64.tar; rm hledger-linux-x64.{zip,tar} # github workaround, preserves permissions
cd -
hledger --version # should show the new version
touch $HOME/.hledger.journal # ensure a default journal file exists
In a terminal window,
cd /usr/local/bin
curl -LOC- https://github.com/simonmichael/hledger/releases/download/1.32/hledger-mac-x64.zip
unzip hledger-mac-x64.zip; tar xvf hledger-mac-x64.tar; rm hledger-mac-x64.{zip,tar} # github workaround, preserves permissions
open .
# for the hledger, hledger-ui, hledger-web icons: right-click, Open, confirm it's ok to run
cd -
hledger --version # should show the new version
touch $HOME/.hledger.journal # ensure a default journal file exists
In a powershell window (press Windows-r, type powershell, press enter),
mkdir -force $HOME\bin >$null
$ENV:PATH += ";"+$HOME+"\bin"
[Environment]::SetEnvironmentVariable("Path", [Environment]::GetEnvironmentVariable("Path", [EnvironmentVariableTarget]::User)+";"+$HOME+"\bin", [EnvironmentVariableTarget]::User)
cd $HOME\bin
curl https://github.com/simonmichael/hledger/releases/download/1.32/hledger-windows-x64.zip -OutFile hledger-windows-x64.zip
Expand-Archive hledger-windows-x64.zip -DestinationPath .
rm hledger-windows-x64.zip
cd $HOME
hledger --version # should show the new version
out-file -append -encoding ascii $HOME/.hledger.journal
Once that journal file exists, you can start hledger-web by double-clicking on the icon if you wish.
echo %PATH%
, like C:\Windows
(though that one will require administrator permission); otherwise, your home directory (C:\Users\YOURNAME
)\Windows
, you'll need to scroll down)hledger --version
should show the new versionecho # >> .hledger.journal
to ensure a default journal file exists. (Important: the doubled >> is needed to avoid overwriting existing data.)Problems:
More tolerant equity/cost matching; print amounts in original style; multi-pivot.
Features
Improvements
The print
command now more closely replicates the original journal
amount styles, which is helpful when round-tripping / cleaning up
journal files:
Amounts in conversion transactions could be displayed rounded to a lower precision; this no longer happens. (#2079)
Amounts could be displayed with extra zeros after the decimal mark; this no longer happens.
Amounts could display with a different precision if the journal included a timedot file; this no longer happens.
Costs in balance assertions were not displayed with standard styles like other amounts; now they are.
Zero amounts were always shown as just "0"; now they are shown with their original commodity symbol and style. (And if an inferred amount has multiple zeros in different commodities, a posting is displayed for each of these.)
print
no longer displays numbers with a single digit group mark
and no decimal mark, which are ambiguous and hard to re-parse. Now
if a number has digit group marks the decimal mark will always be
shown also. Eg 1,000
(where the comma is a thousands separator)
is now shown as 1,000.
.
The check command's
balancedwithautoconversion
and balancednoautoconversion
checks
have been renamed to autobalanced
and balanced
.
hledger check recentassertions
now reports failures at the first
posting that's more than 7 days later than the latest balance
assertion (rather than at the balance assertion). This is the thing
actually triggering the error, and it is more likely to be visible
or at least closer when you are working at the end of a journal
file.
Also, the suggested sample balance assertion now uses the same commodity symbol as in the failing posting (the first, if there are more than one); and, no longer includes a cleared mark.
The import command now shows the file path being imported to.
With --pivot, desc
is now the preferred spelling for pivoting on
description.
The demo command now ignores an invalid journal file, like the other HELP commands.
Debug output for equity conversion postings has been improved, making troubleshooting easier.
Allow aeson 2.2, megaparsec 9.5.
Fixes
In journal files, valid multicommodity transactions where the matching non-equity postings can't be auto-detected are no longer considered an error (as they were in hledger 1.29 and 1.30). Now, such transactions are accepted, and --infer-cost has no effect on them. This is similar to the behaviour of --cost, --infer-equity, and --infer-market-prices. (#2045)
In journal files, equity conversion postings are now detected more tolerantly, using the same precision as the conversion posting's amount (#2041). Eg, the following transaction is now accepted:
2023-01-01
Assets -84.01 USD @ 2.495 GEL
; ^ 209.60495 GEL, recognised as a match for the 209.60 below
Equity:Conversion 84.01 USD
Equity:Conversion -209.60 GEL
Assets 209.60 GEL
The roi command now reports TWR per period and overall TWR for multi-period reports. (#2068, Dmitry Astapov)
The commands list no longer shows bar when hledger-bar is not installed (#2065), and had a few other cleanups.
Improvements
Improvements
Scripts/addons
ft, tt shell scripts for collecting financial and time reports
A justfile implementation of ft and tt
Examples
self-tracking
RPG ledger (Eric Mertens)
Docs
Infrastructure
tools, CI: checkembeddedfiles, checkversions
Shake: avoid making empty commits
make functest-PAT: runs a subset of functional tests
Provide a ghc-tags.yaml file to make use of ghc-tags with Hledger easy.
ghc-tags is a standalone tool to replace the formerly-built-in ":ctags" feature (and I presume ":etags") in GHCi. These walked over the source and produced a TAGS file (in vim-compatible ctags or Emacs-compatible etags format) that allows the relevant editors to quickly navigate around function definitions.
ghc-tags trips over some of the CPP used in Hledger. The solution is to provide ghc-tags with explicit CPP defines via a YAML file. However, if a YAML file is provided, one also must specify the source paths, as the tool XORs config file | paths-on-command-line.
See https://github.com/arybczak/ghc-tags/issues/6 for more information. (Jonathan Dowland)
Simon Michael, Dmitry Astapov, Eric Mertens, Jay Neubrand, Jonathan Dowland.
At https://hledger.org/install, binary packages should be available for this release within a few days (look for green badges).
Or, you can build from source as described there, after cloning at tag 1.31
:
git clone https://github.com/simonmichael/hledger --depth 1 -b 1.31
Or, if under "Assets" below there are release binaries suitable for your OS and hardware, you can use those.
Here are platform-specific instructions for the release binaries. (You can copy & paste each block of commands as a unit to save time.):
At the command line,
cd /usr/local/bin
curl -LOC- https://github.com/simonmichael/hledger/releases/download/1.31/hledger-linux-x64.zip # can rerun if interrupted
unzip hledger-linux-x64.zip; tar xvf hledger-linux-x64.tar; rm hledger-linux-x64.{zip,tar} # github workaround, preserves permissions
cd -
hledger --version # should show the new version
touch $HOME/.hledger.journal # ensure a default journal file exists
In a terminal window,
cd /usr/local/bin
curl -LOC- https://github.com/simonmichael/hledger/releases/download/1.31/hledger-mac-x64.zip
unzip hledger-mac-x64.zip; tar xvf hledger-mac-x64.tar; rm hledger-mac-x64.{zip,tar} # github workaround, preserves permissions
open .
# for the hledger, hledger-ui, hledger-web icons: right-click, Open, confirm it's ok to run
cd -
hledger --version # should show the new version
touch $HOME/.hledger.journal # ensure a default journal file exists
In a powershell window (press Windows-r, type powershell, press enter),
mkdir -force $HOME\bin >$null
$ENV:PATH += ";"+$HOME+"\bin"
[Environment]::SetEnvironmentVariable("Path", [Environment]::GetEnvironmentVariable("Path", [EnvironmentVariableTarget]::User)+";"+$HOME+"\bin", [EnvironmentVariableTarget]::User)
cd $HOME\bin
curl https://github.com/simonmichael/hledger/releases/download/1.31/hledger-windows-x64.zip -OutFile hledger-windows-x64.zip
Expand-Archive hledger-windows-x64.zip -DestinationPath .
rm hledger-windows-x64.zip
cd $HOME
hledger --version # should show the new version
out-file -append -encoding ascii $HOME/.hledger.journal
Once that journal file exists, you can start hledger-web by double-clicking on the icon if you wish.
echo %PATH%
, like C:\Windows
(though that one will require administrator permission); otherwise, your home directory (C:\Users\YOURNAME
)\Windows
, you'll need to scroll down)hledger --version
should show the new versionecho # >> .hledger.journal
to ensure a default journal file exists. (Important: the doubled >> is needed to avoid overwriting existing data.)Problems:
Boolean queries, easier CSV file management, built-in demos, hledger-ui cash accounts screen, fixes.
Breaking changes
The CSV reader now properly skips all empty lines, as specified by docs.
Previously, inner empty lines were not being skipped automatically.
You might need to adjust the skip
count in some CSV rules files.
(#2024)
Timedot format now generates a single multi-posting transaction per date line, and supports comments and tags on all lines. (#1754)
Timeclock format now supports comments and tags. Descriptions can no longer contain semicolons. (#1220)
Features
CSV rules files can now be read directly, as in
hledger -f foo.csv.rules CMD
. By default this will read data
from foo.csv in the same directory.
CSV rules files can use a new source FILE
rule to specify the data file,
with some convenience features:
If the data file does not exist, it is treated as empty, not an error.
If FILE is a relative path, it is relative to the rules file's
directory. If it is just a file name with no path, it is relative
to ~/Downloads/
.
If FILE is a glob pattern, the most recently modified matched file is used.
This helps remove some of the busywork of managing CSV downloads.
Most of your financial institutions's default CSV filenames are
different and can be recognised by a glob pattern. So you can put a
rule like source Checking1*.csv
in foo-checking.csv.rules,
periodically download CSV from Foo's website accepting your browser's
defaults, and then run hledger import checking.csv.rules
to import
any new transactions. The next time, if you have done no cleanup, your
browser will probably save it as something like Checking1-2.csv, and
hledger will still see that because of the * wild card. You can choose
whether to delete CSVs after import, or keep them for a while as
temporary backups, or archive them somewhere.
(Experimental)
The balance command has a new --count report type which reports posting counts instead of amounts.
Full boolean queries, allowing arbitrary use of AND, OR, NOT
(case insensitive) and parentheses for grouping, are now supported.
For backward compatibility, these require an expr:
prefix.
Existing queries work as before, and you can mix and match the
old and new styles if you like.
(Chris Lemaire)
demo: This new command plays brief asciinema screencasts explaining various features and use cases. We will add more of these over time. (Experimental)
Improvements
Add-on commands can now have .js
, .lua
, or .php
file extensions.
Generated and modified transactions and postings have the same hidden
tags (beginning with underscore) as before, but no longer have visible
tags added by default. Use --verbose-tags
if you want them added.
We now try harder to ensure less
(and its more
mode) show our
ANSI formatting properly in help output.
If you use some other $PAGER, you may have to configure it yourself
to show ANSI (or disable ANSI entirely, eg by setting NO_COLOR=1).
This is now documented in hledger manual > Paging.
(#2015)
The print command's --match
mode has been refined.
Previously, similarity completely outweighed recency, so a
slightly-more-similar transaction would always be selected no matter
how old it was. Now similarity and recency are more balanced,
and it should produce the desired transaction more often.
There is also new debug output (at debug level 1) for troubleshooting.
Miscellaneous commands list updates. Help has been added for all published add-on commands (like hledger-lots).
The help command's documentation now mentions an issue caused by
a too-old info
program, as on mac.
(#1770)
Fixes
Unbalanced virtual postings with no amount always infer a zero amount. This is fixing and clarifying the status quo; they always did this, but print always showed them with no amount, even with -x, and the behaviour was undocumented.
On windows systems with multiple drive letters, the commands list could fail to show all installed add-ons. (#2040)
Balancing a transaction with a balance assignment now properly respects costs. (#2039)
The commands list no longer lists non-installed addons. (#2034)
Since hledger 1.25, "every Nth day of month" period rules with N > 28 could
be calculated wrongly by a couple of days when given certain forecast start dates.
Eg ~ every 31st day of month
with --forecast='2023-03-30..'
.
This is now fixed.
(#2032)
Postings are now processed in correct date order when inferring balance assignments. (#2025)
Posting comment lines no longer disrupt the underline position in error messages. (#1927)
Debug output is now formatted to fit the terminal width.
Docs
Miscellaneous manual cleanups.
Rewrite introductory sections, Date adjustment, Directives, Forecasting, etc.
Add Paging section.
Remove archaic mentions of setenv
.
API
Features
Cash
type.Improvements
The top-level menu screen is now the default screen.
Power users can use the --cash
/--bs
/--is
/--all
flags to start up in another screen.
"All accounts" screen has been moved to the bottom of the list.
Screens' help footers have been improved.
Docs
The transaction screen's inability to update is now noted.
Miscellaneous manual cleanups.
Fixes
Docs
Scripts/addons
hledger-bar: new script for making simple bar charts in the terminal
hledger-install: also list cabal, stack, pip tool versions
Examples
examples/csv: added a more up-to-date CSV makefile
examples/i18: Added sample top level account and type declarations in several languages
Docs
A shorter, more example-heavy home page on the website.
Simplified website and FAQ structure.
Simon Michael, Chris Lemaire, Yehoshua Pesach Wallach.
At https://hledger.org/install, binary packages should be available for this release within a few days (look for green badges).
Or, you can build from source as described there, after cloning at tag 1.30
:
git clone https://github.com/simonmichael/hledger --depth 1 -b 1.30
Or, if under "Assets" below there are release binaries suitable for your OS and hardware, you can use those.
Here are platform-specific instructions for the release binaries. (You can copy & paste each block of commands as a unit to save time.):
At the command line,
cd /usr/local/bin
curl -LOC- https://github.com/simonmichael/hledger/releases/download/1.30/hledger-linux-x64.zip # can rerun if interrupted
unzip hledger-linux-x64.zip; tar xvf hledger-linux-x64.tar; rm hledger-linux-x64.{zip,tar} # github workaround, preserves permissions
cd -
hledger --version # should show the new version
touch $HOME/.hledger.journal # ensure a default journal file exists
In a terminal window,
cd /usr/local/bin
curl -LOC- https://github.com/simonmichael/hledger/releases/download/1.30/hledger-mac-x64.zip
unzip hledger-mac-x64.zip; tar xvf hledger-mac-x64.tar; rm hledger-mac-x64.{zip,tar} # github workaround, preserves permissions
open .
# for the hledger, hledger-ui, hledger-web icons: right-click, Open, confirm it's ok to run
cd -
hledger --version # should show the new version
touch $HOME/.hledger.journal # ensure a default journal file exists
In a powershell window (press Windows-r, type powershell, press enter),
mkdir -force $HOME\bin >$null
$ENV:PATH += ";"+$HOME+"\bin"
[Environment]::SetEnvironmentVariable("Path", [Environment]::GetEnvironmentVariable("Path", [EnvironmentVariableTarget]::User)+";"+$HOME+"\bin", [EnvironmentVariableTarget]::User)
cd $HOME\bin
curl https://github.com/simonmichael/hledger/releases/download/1.30/hledger-windows-x64.zip -OutFile hledger-windows-x64.zip
Expand-Archive hledger-windows-x64.zip -DestinationPath .
rm hledger-windows-x64.zip
cd $HOME
hledger --version # should show the new version
out-file -append -encoding ascii $HOME/.hledger.journal
Once that journal file exists, you can start hledger-web by double-clicking on the icon if you wish.
echo %PATH%
, like C:\Windows
(though that one will require administrator permission); otherwise, your home directory (C:\Users\YOURNAME
)\Windows
, you'll need to scroll down)hledger --version
should show the new versionecho # >> .hledger.journal
to ensure a default journal file exists. (Important: the doubled >> is needed to avoid overwriting existing data.)Problems:
2023-06-02: This release is missing some extra-source-files declarations in hledger/package.yaml and hledger/hledger.cabal, which is harmless when downloading/building from github. (https://hackage.haskell.org/package/hledger-1.30.1 was released for people building from Hackage.) #2043
Breaking changes
1.29's cleanup of the close
command has been continued.
Here are all the changes to close
since hledger 1.28:
The default behaviour is now to print only one transaction: a closing transaction.
To print both closing and opening transactions as before,
use the new --migrate
flag.
The accounts closed by default are now just the ALE accounts
(accounts declared or inferred as type Asset
, Liability
, or Equity
).
If you don't have account types configured, or
to close some other set of accounts, provide query arguments that match them.
To close all accounts as before, use a .
argument to match them all.
To print a retain earnings transaction for RX accounts (accounts
of type Revenue
or Expense
), use the new --retain
flag.
The equity
command alias, removed in 1.29, has been restored.
The --open-acct
option, removed in 1.29, has been restored.
The --closing
and --opening
flags have been renamed to --close
and --open
.
(--close
had been removed in 1.29 and is now restored.)
The docs have been rewritten. Also the 1.29 release notes now mention the breaking change.
The command is marked experimental again.
(#2020)
Fixes
type:
queries now "see through" account aliases and pivots,
as they did in hledger <1.27, and as acct:
queries do.
(#2018)
The corruption in 1.29's info manual is fixed. (#2023)
The 1.29 release notes for periodic reports'/periodic transactions' start dates have been improved. Also the hledger manual's "Date adjustment" section has been corrected and clarified.
Improvements
hledger
.Fixes
Improvements
hledger
.Fixes
Scripts/addons
Simon Michael
At https://hledger.org/install, binary packages should be available for this release within a few days (look for green badges).
Or, you can build from source as described there, after cloning at tag 1.29.2
:
git clone https://github.com/simonmichael/hledger --depth 1 -b 1.29.2
Or, if under "Assets" below there are release binaries suitable for your OS and hardware, you can use those.
Here are platform-specific instructions for the release binaries. (You can copy & paste each block of commands as a unit to save time.):
cd /usr/local/bin
curl -LOC- https://github.com/simonmichael/hledger/releases/download/1.29.2/hledger-linux-x64.zip # can rerun if interrupted
unzip hledger-linux-x64.zip; tar xvf hledger-linux-x64.tar; rm hledger-linux-x64.{zip,tar} # github workaround, preserves permissions
cd -
hledger --version # should show the new version
touch $HOME/.hledger.journal # ensure a default journal file exists
cd /usr/local/bin
curl -LOC- https://github.com/simonmichael/hledger/releases/download/1.29.2/hledger-mac-x64.zip
unzip hledger-mac-x64.zip; tar xvf hledger-mac-x64.tar; rm hledger-mac-x64.{zip,tar} # github workaround, preserves permissions
open .
# for the hledger, hledger-ui, hledger-web icons: right-click, Open, confirm it's ok to run
cd -
hledger --version # should show the new version
touch $HOME/.hledger.journal # ensure a default journal file exists
In a powershell window (press Windows-r, type powershell, press enter),
Make a place to keep hledger binaries, and add it to your PATH; this makes running hledger easier. You only need to do this once, not for every release:
mkdir -force $HOME\bin >$null
$ENV:PATH += ";"+$HOME+"\bin"
[Environment]::SetEnvironmentVariable("Path", [Environment]::GetEnvironmentVariable("Path", [EnvironmentVariableTarget]::User)+";"+$HOME+"\bin", [EnvironmentVariableTarget]::User)
Download and install the release binaries:
cd $HOME\bin
curl https://github.com/simonmichael/hledger/releases/download/1.29.2/hledger-windows-x64.zip -OutFile hledger-windows-x64.zip
Expand-Archive hledger-windows-x64.zip -DestinationPath .
rm hledger-windows-x64.zip
cd $HOME
hledger --version # should show the new version
And ensure a default journal file exists:
out-file -append -encoding ascii $HOME/.hledger.journal
Problems:
echo %PATH%
, like C:\Windows
(though that one will require administrator permission); otherwise, your home directory (C:\Users\YOURNAME
)\Windows
, you'll need to scroll down)hledger --version
should show the new versionecho # >> .hledger.journal
to ensure a default journal file exists. (Important: the doubled >> is needed to avoid overwriting existing data.)Problems:
Improvements
Hledger.Cli.Script now also exports
Control.Applicative
Control.Concurrent
Data.Char
Data.Functor
System.IO
System.IO.Error
and new string helpers
strip1Char
stripBy
strip1By
Allow building with GHC 9.6.1 (#2011)
Fixes
Docs
hledger close
docs (Yehoshua Pesach Wallach)At https://hledger.org/install, binary packages should be available for this release within a few days (look for green badges).
Or, you can build from source as described there, after cloning at tag 1.29.1
:
git clone https://github.com/simonmichael/hledger --depth 1 -b 1.29.1
Or, if under "Assets" below there are release binaries suitable for your OS and hardware, you can use those.
Here are platform-specific instructions for the release binaries. (You can copy & paste each block of commands as a unit to save time.):
cd /usr/local/bin
curl -LOC- https://github.com/simonmichael/hledger/releases/download/1.29.1/hledger-linux-x64.zip # can rerun if interrupted
unzip hledger-linux-x64.zip; tar xvf hledger-linux-x64.tar; rm hledger-linux-x64.{zip,tar} # github workaround, preserves permissions
cd -
hledger --version # should show the new version
touch $HOME/.hledger.journal # ensure a default journal file exists
cd /usr/local/bin
curl -LOC- https://github.com/simonmichael/hledger/releases/download/1.29.1/hledger-mac-x64.zip
unzip hledger-mac-x64.zip && tar xvf hledger-mac-x64.tar && rm hledger-mac-x64.{zip,tar} # github workaround, preserves permissions
open .
# for the hledger, hledger-ui, hledger-web icons: right-click, Open, confirm it's ok to run
cd -
hledger --version # should show the new version
touch $HOME/.hledger.journal # ensure a default journal file exists
In a powershell window (press Windows-r, type powershell, press enter),
Make a place to keep hledger binaries, and add it to your PATH; this makes running hledger easier. You only need to do this once, not for every release:
mkdir -force $HOME\bin >$null
$ENV:PATH += ";"+$HOME+"\bin"
[Environment]::SetEnvironmentVariable("Path", [Environment]::GetEnvironmentVariable("Path", [EnvironmentVariableTarget]::User)+";"+$HOME+"\bin", [EnvironmentVariableTarget]::User)
Download and install the release binaries:
cd $HOME\bin
curl https://github.com/simonmichael/hledger/releases/download/1.29.1/hledger-windows-x64.zip -OutFile hledger-windows-x64.zip
Expand-Archive hledger-windows-x64.zip -DestinationPath .
rm hledger-windows-x64.zip
cd $HOME
hledger --version # should show the new version
And ensure a default journal file exists:
out-file -append -encoding ascii $HOME/.hledger.journal
Problems:
echo %PATH%
, like C:\Windows
(though that one will require administrator permission); otherwise, your home directory (C:\Users\YOURNAME
)\Windows
, you'll need to scroll down)hledger --version
should show the new versionecho # >> .hledger.journal
to ensure a default journal file exists. (Important: the doubled >> is needed to avoid overwriting existing data.)Problems:
Improvements
Hledger.Cli.Script now also exports
Control.Applicative
Control.Concurrent
Data.Char
Data.Functor
System.IO
System.IO.Error
and new string helpers
strip1Char
stripBy
strip1By
Allow building with GHC 9.6.1 (#2011)
Fixes
Docs
hledger close
docs (Yehoshua Pesach Wallach)At https://hledger.org/install, binary packages should be available for this release within a few days (look for green badges).
Or, you can build from source as described there, after cloning at tag 1.29.1
:
git clone https://github.com/simonmichael/hledger --depth 1 -b 1.29.1
Or, if under "Assets" below there are release binaries suitable for your OS and hardware, you can use those.
Here are platform-specific instructions for the release binaries. (You can copy & paste each block of commands as a unit to save time.):
cd /usr/local/bin
curl -LOC- https://github.com/simonmichael/hledger/releases/download/1.29.1/hledger-linux-x64.zip # can rerun if interrupted
unzip hledger-linux-x64.zip; tar xvf hledger-linux-x64.tar; rm hledger-linux-x64.{zip,tar} # github workaround, preserves permissions
cd -
hledger --version # should show the new version
touch $HOME/.hledger.journal # ensure a default journal file exists
cd /usr/local/bin
curl -LOC- https://github.com/simonmichael/hledger/releases/download/1.29.1/hledger-mac-x64.zip
unzip hledger-mac-x64.zip && tar xvf hledger-mac-x64.tar && rm hledger-mac-x64.{zip,tar} # github workaround, preserves permissions
open .
# for the hledger, hledger-ui, hledger-web icons: right-click, Open, confirm it's ok to run
cd -
hledger --version # should show the new version
touch $HOME/.hledger.journal # ensure a default journal file exists
In a powershell window (press Windows-r, type powershell, press enter),
Make a place to keep hledger binaries, and add it to your PATH; this makes running hledger easier. You only need to do this once, not for every release:
mkdir -force $HOME\bin >$null
$ENV:PATH += ";"+$HOME+"\bin"
[Environment]::SetEnvironmentVariable("Path", [Environment]::GetEnvironmentVariable("Path", [EnvironmentVariableTarget]::User)+";"+$HOME+"\bin", [EnvironmentVariableTarget]::User)
Download and install the release binaries:
cd $HOME\bin
curl https://github.com/simonmichael/hledger/releases/download/1.29.1/hledger-windows-x64.zip -OutFile hledger-windows-x64.zip
Expand-Archive hledger-windows-x64.zip -DestinationPath .
rm hledger-windows-x64.zip
cd $HOME
hledger --version # should show the new version
And ensure a default journal file exists:
out-file -append -encoding ascii $HOME/.hledger.journal
Problems:
echo %PATH%
, like C:\Windows
(though that one will require administrator permission); otherwise, your home directory (C:\Users\YOURNAME
)\Windows
, you'll need to scroll down)hledger --version
should show the new versionecho # >> .hledger.journal
to ensure a default journal file exists. (Important: the doubled >> is needed to avoid overwriting existing data.)Problems:
Tag checking, flexible multi-period start dates, flexible cost/conversion posting combining, new commands list, hledger manual reorg, easier close command, 10% more Ledger file compatible
Breaking changes
Features
In journal format there is now a tag
directive for declaring tag names,
and the check command now has a tags
check to enforce use of declared tag names.
Periodic transactions and multi-period reports can now start on any date. To enable this while still maintaining pretty good backward compatibility, hledger now treats inferred dates, and dates where the day is unspecified, as "flexible" (which can be automatically adjusted to interval boundaries), and dates specified to the day as "exact" (which can not). Eg:
A periodic rule like ~ monthly from 2023-01-15
now works as
you'd expect instead of raising an error. This also improves
our ability to read Ledger files.
Period options like -p 'monthly from 2023/1/15'
or -M -b 2023/1/15
now start the report on exactly 1/15 instead of being adjusted to 1/1.
Note: periods using in
may look partial but are considered to specify exact dates.
So weekly reports such as -p 'weekly in 2023-01'
, which previously
were adjusted to start on a monday, will now start exactly on 2023-01-01.
This can also cause more verbose column headings.
To guarantee simple week headings, you must now start such reports
exactly on a monday, eg -p 'weekly from 2022-12-26 to 2023-02'
.
(#1982)
You can now freely combine @/@@ costs and conversion postings
in a single transaction. This can help readability, and also allows
more flexibility when recording cost. hledger will check that the
two notations are in agreement, and ignore the redundancy if they are.
(Conversion postings are postings to accounts with type V
/Conversion
or name equity:conversion
/equity:trade
/equity:trading
,
or subaccounts of these. See also COST.)
Improvements
hledger's commands list has been reorganised for clarity. More add-on commands are now recognised and categorised, and unrecognised add-on commands are listed in a more compact multi-column layout. (Simon Michael, Michael Grünewald)
hledger's commands list and command line help now use ANSI (bold headings) when supported.
hledger's commands list and command line help now use a pager (respecting $PAGER) for long output except on MS Windows.
hledger's --version
output no longer shows +
for dev builds made
in dirty repos (it was buggy).
The add command's Description completions now also include payee names
(declared with payee
or recorded in transactions with |
),
not just full descriptions.
aregister now supports HTML output. (#1996) (Jonathan Dowland)
aregister now shows a " (matching query)" hint in report title when extra query args (other than date: or depth:) are used, to reduce confusion.
close now has three modes, --retain
/--migrate
/--open
,
clarifying its uses and providing more useful defaults.
register-match is now the --match
mode of the register command.
(This command was used by ledger-autosync at one point; if you still
need it, hopefully register --match
works similarly.)
print-unique has been dropped, because it doesn't support print's options, it disorders same-day transactions, I don't know of any users or use cases, and it could easily be recreated as an addon script.
print's JSON output now also includes source positions for --forecast
transactions.
(Chris Lemaire)
Journal format now allows the empty commodity symbol to be written
as ""
, so it's now possible to declare market prices for it:
P 2022-01-01 "" $100
. This can be useful for timedot data.
Inferring costs from equity now happens after transaction balancing,
not before. As a result, --infer-costs
now works in transactions
where an amount is left blank.
account
declarations now reject parenthesised account names,
reducing confusion.
(Chris Lemaire)
Our journal reader now accepts more Ledger syntax, improving Ledger file compatibility (#1962). We now test our ability to at least read the sample journals from Ledger's baseline functional tests, and our success rate has improved from 80% to 90% since 1.28.
since
is accepted as synonym of from
in period expressionsapply year
and year
are accepted as synonyms of Y
(lot notes)
in amounts and ((valuation expressions))
after amounts are now ignoredA
, assert
, bucket
, capture
, check
, define
,
expr
, eval
, python
, value
,
apply fixed
, apply tag
,
end apply fixed
, end apply tag
, end apply year
are now ignoredpayee
, tag
, and commodity
(other than format
) are now ignoredpop
directive is no longer supportedWhen reading CSV, we now check that assigned account names are valid (parseable). (#1978)
Fixes
aregister now handles an extra account query correctly. (#2007)
balance's --help
now mentions --layout=tidy
Balance commands with --layout=bare
now generate proper table
layout in HTML output.
register's -w
/--width
option no longer gives ugly parse error messages.
stats's --help
no longer wrongly claims to support -O/--output-format.
Balance assignments with a cost now generate a correct balance assertion. (#1965)
The CSV reader now properly skips header lines before attempting to parse records. (#1967)
Scripts/addons
Scripts can now use Hledger.Cli.Script, a convenient new prelude which helps reduce import boilerplate. It currently re-exports:
Control.Monad
Data.Either
Data.List
Data.Maybe
Data.Ord
Data.Time
Text.Printf hiding (formatString)
Data.Text (Text, pack, unpack)
Safe hiding (at)
System.Directory
System.Environment
System.Exit
System.FilePath
System.Process
Hledger
Hledger.Cli
Hledger.Cli.Main (argsToCliOpts)
(Not much of Data.Text/Data.Text.IO because those need to be qualified.)
Docs
In the help dialog, mention that LEFT shows other screens.
In the manual, mention shift-up/down config needed for Terminal.app.
The add form's typeahead now shows non-ascii text correctly. (#1961) (Arsen Arsenović)
In the manual, improve --base-url's description. (#1562)
Scripts/addons
Docs
Infrastructure
Simon Michael, Chris Lemaire, Caleb Maclennan, Jonathan Dowland, J. B. Rainsberger, Michael Grünewald, Robert Nielsen, Yann Büchau.
At https://hledger.org/install, binary packages should be available for this release within a few days (look for green badges).
Or, you can build from source as described there, after cloning at tag 1.29
:
git clone https://github.com/simonmichael/hledger --depth 1 -b 1.29
Or, if under "Assets" below there are release binaries suitable for your OS and hardware, you can use those.
Here are platform-specific instructions for the release binaries. (You can copy & paste each block of commands as a unit to save time.):
cd /usr/local/bin
curl -LOC- https://github.com/simonmichael/hledger/releases/download/1.29/hledger-linux-x64.zip # can rerun if interrupted
unzip hledger-linux-x64.zip; tar xvf hledger-linux-x64.tar; rm hledger-linux-x64.{zip,tar} # github workaround, preserves permissions
cd -
hledger --version # should show the new version
touch $HOME/.hledger.journal # ensure a default journal file exists
cd /usr/local/bin
curl -LOC- https://github.com/simonmichael/hledger/releases/download/1.29/hledger-mac-x64.zip
unzip hledger-mac-x64.zip && tar xvf hledger-mac-x64.tar && rm hledger-mac-x64.{zip,tar} # github workaround, preserves permissions
open .
# for the hledger, hledger-ui, hledger-web icons: right-click, Open, confirm it's ok to run
cd -
hledger --version # should show the new version
touch $HOME/.hledger.journal # ensure a default journal file exists
In a powershell window (press Windows-r, type powershell, press enter),
Make a place to keep hledger binaries, and add it to your PATH; this makes running hledger easier. You only need to do this once, not for every release:
mkdir -force $HOME\bin >$null
$ENV:PATH += ";"+$HOME+"\bin"
[Environment]::SetEnvironmentVariable("Path", [Environment]::GetEnvironmentVariable("Path", [EnvironmentVariableTarget]::User)+";"+$HOME+"\bin", [EnvironmentVariableTarget]::User)
Download and install the release binaries:
cd $HOME\bin
curl https://github.com/simonmichael/hledger/releases/download/1.29/hledger-windows-x64.zip -OutFile hledger-windows-x64.zip
Expand-Archive hledger-windows-x64.zip -DestinationPath .
rm hledger-windows-x64.zip
cd $HOME
hledger --version # should show the new version
And ensure a default journal file exists:
out-file -append -encoding ascii $HOME/.hledger.journal
Problems:
echo %PATH%
, like C:\Windows
(though that one will require administrator permission); otherwise, your home directory (C:\Users\YOURNAME
)\Windows
, you'll need to scroll down)hledger --version
should show the new versionecho # >> .hledger.journal
to ensure a default journal file exists. (Important: the doubled >> is needed to avoid overwriting existing data.)Problems: