1.29: removal of equity command alias for close breaks backwards compatibility

Hi,
as described on

equity command does not work anymore

~/.local/hledger/hledger-1.29/hledger -f ./2014.journal equity "assets|liabilities|debts" -e 2015 
hledger: Error: command equity is not recognized, run with no command to see a list

~/.local/hledger/hledger-1.26.1/hledger-linux-x64 -f ./2014.journal equity "assets|liabilities|debts" -e 2015
2014-12-31 closing balances
    assets:Lloyds:current                  £-600.00 = £0.00
    assets:cash                            £-150.00 = £0.00
    assets:pension:aviva                   £-100.00 = £0.00
    equity:opening/closing balances

2015-01-01 opening balances
    assets:Lloyds:current                   £600.00 = £600.00
    assets:cash                             £150.00 = £150.00
    assets:pension:aviva                    £100.00 = £100.00
    equity:opening/closing balances

https://hledger.org/release-notes.html#2023-03-11-hledger-129 > "close
now has three modes, --retain/--migrate/--open, clarifying its uses
and providing more useful defaults."

Ledger's original "equity" command was long ago renamed to "close" in
hledger. I guess at some point (maybe this same release) I dropped the
old "equity" alias. (Sometimes I take a chance and remove ancient
legacy cruft that I think noone is using.)

It seems I should have been more careful to preserve the previous
flags and command alias, or to document the breaking changes in
release notes;

Thanks so much for the regression bounty. It will go to a climate change NGO, eXtinction Rebellion concretely, 🙏🏼 via the same open collective site (which is amazing by the way)

Thanks for hledger project, but especially for your kindness and humility when taking care of issues and requests

hi, i was hit by this today :)
in my case the error is Error: Unknown flag: --closing (use -h to see usage)
is it safe to say that i can replace hledger equity --closing with hledger close --migrate ?

well i figured it out, it's actually hledger close --retain what works for me.

i also had to add --close-desc=DESC and --close-acct=ACCT params, the defaults have changed from what is stated in the help

@simonmichael

this also hit me for hledger equity --opening, i just had to change it to hledger close --open

thanks @simonmichael for your continued support for hledger, i wouldn't have a handle on my financials if it wasn't for this

@jbrodriguez

Thanks @jbrodriguez. See also today's discussion on the mail list or chat, eg orahttps://groups.google.com/g/hledger/c/PWK_OtQkcqI/m/w40euGJoCgAJ , perhaps you'll have thoughts.

thanks, yes, i think some of the suggestion look good, although since migrate and retain behave differently, that behavior should be included in future changes

imp: close: reorder flags, rewrite help/doc (#2020)

fix: close: restore --open-acct option (#2020)

imp: close: reorder/clean options more (#2020)

imp: close: tweak doc more (#2020)

imp: close: more cleanup; add --close; always default to ALE (#2020)

I brought back the equity alias and pretty much all the flags (as hidden legacy flags), minimising roadbumps. There are still some incompatible changes, aimed at simplifying. Here are the planned 1.29.2 change notes:

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.

Phew.

And the help currently looks like

close [OPTIONS] [--close | --open | --migrate | --retain] [ACCTQUERY]
  Generate transactions which transfer account balances to and/or from
  another account (typically equity). This can be useful for migrating
  balances to a new journal file, or for merging earnings into equity at
  end of accounting period.
  By default, it prints a transaction that zeroes out ALE accounts (asset,
  liability, equity accounts; this requires account types to be
  configured); or if ACCTQUERY is provided, the accounts matched by that.
  (experimental)
 
Flags:
     --close                 show a closing transaction (default)
     --open                  show an opening transaction
     --migrate               show both closing and opening transactions
     --retain                show a retain earnings transaction (for RX
                             accounts)
  -x --explicit              show all amounts explicitly
     --show-costs            show amounts with different costs separately
     --interleaved           show source and destination postings together
     --close-desc=DESC       set closing transaction's description
     --close-acct=ACCT       set closing transaction's destination account
     --open-desc=DESC        set opening transaction's description
     --open-acct=ACCT        set opening transaction's source account 
...
This command has four main modes, corresponding to the most common use
cases:
 
1.  With --close (default), it prints a "closing balances" transaction
    that zeroes out ALE (asset, liability, equity) accounts by default
    (this requires account types to be inferred or declared); or, the
    accounts matched by the provided ACCTQUERY arguments.
 
2.  With --open, it prints an opposite "opening balances" transaction
    that restores those balances from zero. This is similar to Ledger's
    equity command.
 
3.  With --migrate, it prints both the closing and opening transactions.
    This is the preferred way to migrate balances to a new file: run
    hledger close --migrate, add the closing transaction at the end of
    the old file, and add the opening transaction at the start of the
    new file. The matching closing/opening transactions cancel each
    other out, preserving correct balances during multi-file reporting.1
 
4.  With --retain, it prints a "retain earnings" transaction that
    transfers RX (revenue and expense) balances to
    equity:retained earnings. Businesses traditionally do this at the
    end of each accounting period; it is less necessary with
    computer-based accounting, but it could still be useful if you want
    to see the accounting equation (A=L+E) satisfied.
 
In all modes, the defaults can be overridden:
 
-   the transaction descriptions can be changed with --close-desc=DESC
    and --open-desc=DESC
-   the account to transfer to/from can be changed with
    --close-acct=ACCT and --open-acct=ACCT
-   the accounts to be closed/opened can be changed with ACCTQUERY
    (account query arguments).
 ...

imp: close: reorder flags, rewrite help/doc (#2020)

fix: close: restore --open-acct option (#2020)

imp: close: reorder/clean options more (#2020)

imp: close: tweak doc more (#2020)

imp: close: more cleanup; add --close; always default to ALE (#2020)

imp: close: restore equity command alias; improve help/doc (#2020)

imp: close: restore legacy flags --closing/--opening/--close-to/--ope…

doc: cli: improve 1.29 changelog for the close command (#2020)

Navigation Menu

Repository navigation

1.29: removal of equity command alias for close breaks backwards compatibility #2020

3 remaining items

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

1.29: removal of equity command alias for close breaks backwards compatibility #2020

Description

Activity

simonmichael commented on Apr 1, 2023

kiteloopdesign commented on Apr 1, 2023

jbrodriguez commented on Apr 4, 2023

jbrodriguez commented on Apr 4, 2023

jbrodriguez commented on Apr 4, 2023

simonmichael commented on Apr 4, 2023

jbrodriguez commented on Apr 5, 2023

3 remaining items

simonmichael commented on Apr 6, 2023

simonmichael commented on Apr 6, 2023

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions