new name for hledger-equity.hs ?

[Simon Michael]

extra/hledger-equity.hs is similar to Ledger's "equity" command. Ours generates two opposite transactions that zero out and restore some account balances. More detail:

hledger-equity [HLEDGEROPTS] [QUERY]

Show a "closing balances" transaction that brings the balance of all
accounts (or the matched accounts) to zero, and an opposite
"opening balances" transaction that restores the balances from zero.

The opening balances transaction is useful to carry over
asset/liability balances if you choose to start a new journal file,
eg at the beginning of the year.

The closing balances transaction is useful to zero out balances in
the old file, which gives you the option of reporting on both files
at once while still seeing correct balances.

Balances are calculated, and the opening transaction is dated, as of
the report end date, which you should specify with -e or date: (and
the closing transaction is dated one day earlier). If not specified,
it defaults to today.

If any matched account directly contains multiple commodities, the
output may not be valid journal syntax, and will need some editing.

Example:
$ hledger equity -f 2015.journal -e 2016/1/1 assets liabilities >>2015.journal
move opening balances txn to 2016.journal

Open question: how to handle txns spanning a file boundary ? Eg:
2015/12/30 * food
    expenses:food:dining   $10
    assets:bank:checking  -$10  ; date:2016/1/4

I think the "equity" name is unclear, and I'd like to call it something more descriptive. The best I've come up with is "clopening". Can you do better ? This one kind of exists: https://www.google.com/?gws_rd=ssl#q=clopening

(I don't think it matters that we deviate from Ledger here; we can still support "equity" as an alias.) 

Also I was thinking this should be a built-in command instead of an add-on. Maybe that's true for other things in extra/ and elsewhere, I'm not really sure where to draw the line. Currently it's not that easy to discover/install/use add-ons, so having more things built in is convenient.

[Simon Michael]

PS I meant "clopen". So the new command would be "hledger clopen ...".

--
You received this message because you are subscribed to the Google Groups "hledger" group.
To unsubscribe from this group and stop receiving emails from it, send an email to hledger+u...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[André Fincato]

[I'm not an English native speaker]

1. I also think this should be a built-in feature! I did it manually myself today, and was good as a first-time exercise to understand the procedure, but having a command that does that automatically would be great.

2. I tried to install the add-on but did not succeed (got last in placing the file within the PATH variable)

3. `clopening` looks a bit weird IMHO, `equity` still sounds better though confusing to the actual actions done. Was thinking about that maybe it's clearer to have a command to close assets and equity balances and one to open them?

What about `clear-out` and `clear-in` to respectively close a journal and opening a new one?

[Simon Michael]

Thanks for the input André.

I didn't understand how installing the add-on failed. Any more details ?

Also, although I've been using and talking about these matched assets/liabilities to and from zero transactions at year file boundaries for years,  until now I haven't heard of anybody else doing the same thing. Is the technique useful enough to be a built-in command, or is everybody else doing something different ? (for those of you just tuning in: see the hledger-equity doc below for the use case).

Re two commands rather than one, I thought that running the "open" command against the old journal might be a bit non-obvious:

hledger close -f 2016.journal  assets liabilities  # "makes sense"

hledger open -f 2016.journal  assets liabilities  # "weird, aren't I opening a 2017 journal ?"

Also, I thought that you would pretty much always be running "close" and then "open", so why not make it a more convenient single command. 

If two commands, "open" and "close" are nice easy words, but too overloaded with other meanings, probably (?):

1. "Closing the books" has a definite meaning in accounting (see below)

2. opening and closing is a familiar operation on real-world accounts (creating and destroying)

3. Beancount's journal format has open and close keywords for modelling 2, which we might want to support in future

Other ideas besides your suggestion: zero/unzero ? tozero/fromzero ? tofromzero ? endingbalanceclopen ?

In Ledger and hledger this command uses a hard-coded "equity:..." account name as the balancing account. Is that always what you want ? Is "equity" the right word after all ? If someone could explain why it's the best name for this command, I'll happily leave it alone. 

About 1, accountingtools.com says:

Closing entries are journal entries used to empty temporary accounts at the end of a reporting period and transfer their balances into permanent accounts. The use of closing entries resets the temporary accounts to begin accumulating new transactions in the next period. Otherwise, the balances in these accounts would be incorrectly included in the totals for the following reporting period.

The basic sequence of closing entries is:

• Debit all revenue accounts and credit the income summary account, thereby clearing out the balances in the revenue accounts.

• Credit all expense accounts and debit the income summary account, thereby clearing out the balances in all expense accounts.

• Close the income summary account to the retained earnings account. If there was a profit in the period, then this entry is a debit to the income summary account and a credit to the retained earnings account. If there was a loss in the period, then this entry is a credit to the income summary account and a debit to the retained earnings account.

The net result of these activities is to move the net profit or loss for the period into the retained earnings account, which appears in the stockholders' equity section of the balance sheet.

Since the income summary account is only a transitional account, it is also acceptable to close directly to the retained earnings account and bypass the income summary account entirely.

Soo.. as usual, a bit different from our language. How do these people manage without a hierarchical account names ? :) I guess "retained earnings" is a kind of equity ?

Cc'ing the Ledger list for more advice.

[André Fincato]

`clopening` then, also by reading what it means through the link you shared, seems a good option.

Regarding the option to make it a standard command: I think it might potentially be used more if you document it as part of the set of options through which you can interact with you hledger.journal, so I would lean toward including it.

I will check again `hledger-equity.hs` tomorrow. Completely forgot about this thread.

Which prompts me to say that, I find it very hard to come and check this google group to keep up with things. Not sure where to move it, though, beside making an /r/hledger. But if other people find it easier to discuss here, I understand also that.

Also, is the irc channel still active? Would be curious to hang around there every now and then.

[Simon Michael]

Hi! Thanks for resurrecting this thread. Here it is in order, probably required reading for anyone else to make sense of this: 

https://groups.google.com/d/topic/hledger/TeBp1ymz1RA/discussion

More recent notes:

1. hledger's add-on commands are more discoverable and easier to install now (http://hledger.org/manual.html#experimental-add-ons, http://hledger.org/download.html#d)

2. hledger's equity command has been improved slightly, and now always generates valid journal entries

3. summarising accountingtools.com: in traditional accounting, the "close the books" operation moves revenue and expense balances into the "equity:retained earnings" account, optionally via an "income summary" account, in order to see the total net income for a period.

4. My "zero out assets/liabilities at file boundary" operation, in order to preserve balances in single and multi-file reporting, is a different operation, though it is at least mechanically similar.

5. In h/ledger, instead of "closing the books" we normally just filter revenues/expenses by date. Eg: hledger bal -p 2016 revenues expenses

6. But if we did want to close the books, the hledger-equity command can do it. Zero out revenues/expenses, keep only the closing balances transaction, and change the last posting to "equity:retained earnings", eg:

  hledger-equity -f 2016.journal -e 2017/1/1 revenues expenses | hledger -I -f- print desc:closing --alias '/closing balances/=retained earnings'

7. Now I see why the command is named "equity", and I think that name is ok.

8. Having recently done a bunch of fixes in old journal files, where I had to update the closing and opening entries in each intervening year file, I am finding the "zero out assets/liabilities at file boundary" approach a bit tedious. Is there a better way ? Reminder, the main goal is to preserve correct asset/liability balances in both single-file and multi-file reports. I thought of dropping the "closing balances" transaction and having a magical "opening balances" transaction that's used only when it's an account's first posting. Pro: half as much boilerplate and updating when fixing old transactions, and when starting a new journal. Con: more magical, ending balances are no longer recorded and asserted at file end. 

Thoughts ?

[Simon Michael]

Can you explain more ? Do you read the mail list only via Google's web interface ? 

For me the point of a mail list is that you can (when you wish) interact with it using your regular email client or webmail setup, which can be much more efficient. And unlike IRC, it supports both short- and long-term discussions well.

The IRC channel is our most active discussion venue however. It was very active through january when several of us were putting in some hledger time. Come and say hello. 

IRC channel logs are at http://ircbrowse.net/browse/hledger . Unfortunately this is transitioning to a new maintainer and has lost some functionality and reliability recently.

[André Fincato]

Yes, I ended up for some reason to only check it through Google's web interface, which is a bit confusing.

Now all set through emails, which I love.

* * *

I'll share some comments on the `equity` command above in a couple of days, thank for being so responsive.