Browse files

doc: 1.12 announcement

[ci skip]
  • Loading branch information...
simonmichael committed Dec 3, 2018
1 parent d800067 commit 0d1f7542248773e52cff358ac93fde9c9b01400c
Showing with 165 additions and 25 deletions.
  1. +165 −25 doc/ANNOUNCE
@@ -1,52 +1,193 @@
hledger is a robust, cross-platform "plain text accounting" tool, for
hledger is a robust, cross-platform plain text accounting tool, for
tracking money, time, stocks, cryptocurrencies or any other commodity,
using double-entry accounting, private or shared plain text files,
revision control, and command-line, curses or web UIs.
Find out more at and
I'm pleased to announce the on-schedule release of hledger 1.12.
Thanks to release contributors: A, B.
I'm pleased to announce the release of hledger 1.12!
Thank you release contributors Alex Chen, Jesse Rosenthal, Samuel May,
Mykola Orliuk, Peter Simons, Moritz Kiefer, Dmitry Astapov, Felix Yan,
Aiken Cairncross, and Nikhil Jha.
After two years of regular quarter-end releases, I am speeding up
hledger's release cadence: we now aim to release every 1-3 months, as
needed or wanted, with our normal release window being the first few
days of each month.
What's new
Release notes (
hledger 1.12
* install script: ensure a new-enough version of stack; more informative output
* build with GHC 8.6/base-4.12 (Peter Simons)
Full release notes are at
* add required upper bound for statistics (Samuel May)
* --anon anonymises more thoroughly (including linked original postings) (Moritz Kiefer)
* unbalanced transaction errors now include location info (Mykola Orliuk)
* accounts command: --drop also affects the default flat output, without needing an explicit --flat flag
* accounts command: the --codes flag has been dropped
* accounts command: filtering by non-account-name queries now works
* add command: fix transaction rendering regression during data entry and in journal file
* balance command: fix wrongful eliding of zero-balance parent accounts in tree mode (Dmitry Astapov)
* journal format, bs/bse/cf/is commands: account directives can declare account types (#877)
Previously you had to use one of the standard english account names
(assets, liabilities..) for top-level accounts, if you wanted them to
appear in the right place in the balancesheet, balancesheetequity,
cashflow or incomestatement reports.
Now you can use your preferred account names, and use account directives
to declare which accounting class (Asset, Liability, Equity, Revenue or
eXpense) an account (and its subaccounts) belongs to, by writing one of
the letters A, L, E, R, X after the account name, after two or more
spaces. This syntax may change (see issue). Experimental.
Currently we allow unlimited account type declarations anywhere in the
account tree. So you could declare a liability account somewhere under
assets, and maybe a revenue account under that, and another asset account
even further down. In such cases you start to see oddities like accounts
appearing in multiple places in a tree-mode report. I have left it this
way for now in case it helps with, eg, modelling contra accounts, or
combining multiple files each with their own account type
declarations. (In that scenario, if we only allowed type declarations on
top-level accounts, or only allowed a single account of each type,
complications seem likely.)
* journal format: periodic transaction rules now require a double space separator.
In periodic transaction rules which specify a transaction description or
same-line transaction comment, this must be separated from the period
expression by two or more spaces, to prevent ambiguous parsing. Eg
this will parse correctly as "monthly" thanks to the double space:
~ monthly In 2020 we'll end this monthly transaction.
* journal format: exact/complete balance assertions (Samuel May).
A stronger kind of balance assertion, written with a double equals sign,
asserts an account's complete account balance, not just the balance in
one commodity. (But only if it is a single-commodity balance, for now.)
(a) A 1
(a) B 1
(a) 0 = A 1 ; commodity A balance assertion, succeeds
(a) 0 == A 1 ; complete balance assertion, fails
* journal format: account directives now allow whitespace or a comment after the account name
* journal format: using ~ for home directory in include directives now works (#896) (Mykola Orliuk)
* journal format: prevent misleading parse error messages with cyclic include directives (#853) (Alex Chen)
* journal format: transaction modifier multipliers handle total-priced amounts correctly (#928).
Multipliers (*N) in transaction modifier rules did not multiply
total-priced amounts properly. Now the total prices are also multiplied,
keeping the transaction balanced.
* journal format: do amount inference/balance assignments/assertions before transaction modifiers (#893, #908) (Jesse Rosenthal)
Previously, transaction modifier (auto postings) rules were applied
before missing amounts were inferred. This meant amount multipliers could
generate too many missing-amount postings, making the transaction
unbalanceable (#893).
Now, missing amount inference (and balance assignments, and balance
assertions, which are interdependent) are done earlier, before
transaction modifier rules are applied (#900, #903).
Also, we now disallow the combination of balance assignments and
transaction modifier rules which both affect the same account, which
could otherwise cause confusing balance assertion failures (#912).
(Because assignments now generate amounts to satisfy balance assertions
before transaction modifier rules are applied (#908).)
* journal format: periodic transaction rules are now aware of Y default year directives. (#892)
Ie when a default year Y is in effect, they resolve partial or relative
dates using Y/1/1 as the reference date, rather than today's date.
hledger-ui 1.12
* fix "Any" build error with GHC < 8.4
* error screen: always show error position properly (#904) (Mykola Orliuk)
* accounts screen: show correct balances when there's only periodic transactions
* drop the --status-toggles flag
* periodic transactions and transaction modifiers are always enabled.
Rule-based transactions and postings are always generated
(--forecast and --auto are always on).
* escape key resets to flat mode.
Flat mode is the default at startup. Probably it should reset to tree
mode if --tree was used at startup.
* tree mode tweaks: add --tree/-T/-F flags, make flat mode the default,
toggle tree mode with T, ensure a visible effect on register screen
* hide future txns by default, add --future flag, toggle with F.
You may have transactions dated later than today, perhaps piped from
print --forecast or recorded in the journal, which you don't want to
see except when forecasting.
By default, we now hide future transactions, showing "today's balance".
This can be toggled with the F key, which is easier than setting a
date query. --present and --future flags have been added to set the
initial mode.
(Experimental. Interactions with date queries have not been explored.)
* quick help tweaks; try to show most useful info first
* reorganise help dialog, fit content into 80x25 again
* styling tweaks; cyan/blue -> white/yellow
* less noisy styling in horizontal borders (#838)
* register screen: positive amounts: green -> black
The green/red scheme helped distinguish the changes column from the
black/red balance column, but the default green is hard to read on
the pale background in some terminals. Also the changes column is
non-bold now.
Getting started:
All install methods are described at .
You can download windows binaries, or use a package manager, though in
some cases these will install an older hledger version.
You can build the latest hledger packages with stack:
$ stack install --resolver=lts-12 cassava-megaparsec-1.0.0 hledger-lib-1.11
hledger-1.11 [hledger-ui-1.11] [hledger-web-1.11] [hledger-api-1.11]
$ stack install --resolver=lts-12 megaparsec-7.0.4
cassava-megaparsec-2.0.0 config-ini- hledger-lib-1.12
hledger-1.12 [hledger-ui-1.12] [hledger-web-1.12] [hledger-api-1.12]
or with cabal:
$ cabal update && cabal install hledger-1.11 [hledger-ui-1.11]
[hledger-web-1.11] [hledger-api-1.11]
$ cabal update && cabal install hledger-1.12 [hledger-ui-1.12]
[hledger-web-1.12] [hledger-api-1.12]
If you don't have stack or cabal, or if you are having trouble,
on systems with bash installed (mac, linux, unix-like windows..) is an easy and reliable way to get the latest hledger:
or with the hledger installer, on systems with bash installed
(handy if you don't have a working stack or cabal):
$ curl -s >
$ less # satisfy yourself that the script is safe
$ bash
Getting started
Some commands to try:
$ hledger add # record some transactions, with guidance
$ hledger print # show recorded transactions
@@ -55,11 +196,10 @@ $ hledger -h # show quick help
$ hledger # list available commands
$ hledger help # list built-in manuals
To get oriented, see the tutorials and manuals at .
To get help, say hello and ask questions in the #hledger IRC channel
on Freenode, accessible at .
New users and all forms of help are always welcome!
To get oriented, see the tutorials and manuals at ;
say hello and ask questions in the #hledger IRC channel on Freenode,
accessible at .
New users and contributors are always welcome!

0 comments on commit 0d1f754

Please sign in to comment.