A semicolon should always begin a comment in timeclock files

[reesmichael1]

In timeclock files, to disambiguate the account from the description, we require two spaces between the account name and the description. This works well when both of those entries are present, but following #2362, I'd like to propose allowing timeclock comments to appear directly after the account name (i.e., without a description) with only a single space.

The current behavior is slightly more of a problem now that the account name on a clock-out has to match a previous clock-in. For example, I think this is a natural way for the uninitiated to write a timeclock file:

i 2025-06-01 10:00:00 Projects:OSS:hledger ; feature:X
o 2025-06-01 12:00:00 Projects:OSS:hledger ; take break for lunch

In previous versions, this would parse but the account name would be Projects:OSS:hledger ; feature:X--annoying, but easy to see how to fix. Post #2362, this doesn't parse anymore with

hledger: Error: /home/michael/test.timeclock:2:1:
2 | o 2025-06-01 11:00:00 Projects:OSS:hledger ; take break for lunch
  | ^

Could not find previous clockin to match this clockout.

This is technically the expected behavior, but I think it's a sharp edge we can soften. Note also that the current behavior introduces an easy-to-miss gotcha where, even in 1.32 where this parses successfully, the tag feature:X can't be used in any queries.

If this is agreeable, I'm happy to implement this myself.

[simonmichael]

More notes:

https://hledger.org/dev/hledger.html#timeclock

The original timeclock.el has 0-1 fields after the time: [COMMENT] Ledger's timeclock format has 1-2: ACCOUNT[ PAYEE] hledger's timeclock format has 1-3: ACCOUNT[ DESCRIPTION[;COMMENT]]

Before I hurt myself overthinking... what would be the impact on existing data and the migration strategy ?

[simonmichael]

I think we can unambiguously say that semicolon always ends the account or description and starts a comment ?

[reesmichael1]

I'd be very surprised if anyone is intentionally using the fact that a ; only one space after the account name isn't currently treated as a comment. (I guess maybe if someone wants to use a semicolon in the account name? Do we allow escaping the comment character in any way?) Still, I think this would fix far more existing files than it would break.

I thought about saying we could make this change part of the --timeclock-old flag if we want to see if anyone ends up reporting a migration issue, but that defeats much of the purpose of the change (since --timeclock-old resets the old timeclock behavior and therefore the descriptions/names are less important).

[simonmichael]

In journal format (and timeclock reuses parsers from there) we don't allow escaping ; in any way, and it can't appear inside an account name or a description/payee/note.

[simonmichael]

To be clear, I agree with you, I think it's ok to enforce that a semicolon always begins the comment field, even though this will be a change in how our timeclock format has worked until now.

[reesmichael1]

I didn't fully appreciate until now that everything in the timeclock is optional after the timestamp (including the account!). So this is better phrased in the way you described it: "enforce that a semicolon always begins the comment field," even if it appears right after the timestamp or in the middle of the account name or description.

[simonmichael]

I thought an account name was required on clockin entries. But I see it's not, as long as there's no trailing space:

i 2025-04-02 18:00:00
o 2025-04-02 18:01:00

$ hledger -f a.timeclock  print
2025-04-02 * 18:00-18:01
    ()           0.19h

And hledger will successfully parse this entry with an empty account name:

$ hledger -f a.timeclock  print | hledger -f- bal
               0.02h  
--------------------
               0.02h  

Probably we should fix both of these: do require an account name on clockin, and don't accept an entry with an empty account name.

[simonmichael]

(Also, https://hledger.org/dev/hledger.html#timeclock could be clearer.)

[simonmichael]

In journal format (and timeclock reuses parsers from there) we don't allow escaping ; in any way, and it can't appear inside an account name or a description/payee/note.

I must correct myself: in journal format,

• a semicolon anywhere in the description immediately starts a comment
• but semicolons are allowed within account names; only end of line or 2+ spaces ends an account name.

This is probably the reverse of what we'd prefer; bank descriptions do sometimes contain semicolons, and needing semicolons in account names seems pretty unlikely..

In timeclock format, at least, I am about to make this change; there, a semicolon will immediately start a comment, ending the account name or description. This makes things simpler.