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

[kiteloopdesign]

Hi, as described on

https://github.com/adept/full-fledged-hledger/issues/26

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

[simonmichael]

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;

[kiteloopdesign]

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

[jbrodriguez]

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 ?

[jbrodriguez]

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

[jbrodriguez]

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

[simonmichael]

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.

[jbrodriguez]

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

[simonmichael]

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.

[simonmichael]

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).
 ...