Manipulating files (start, stop, etc.)

[jotaen]

The next major feature for the klog CLI is the capability to write into files, and not just to read or evaluate them. This ticket is used to track the progress on this topic and also discuss ideas, questions or feedback around it.

• start / stop commands for adding/closing an open range entry.
  • An additional blocking mode would be cool. That would put a new open-ended entry into the file (e.g. 8:43 - ?; it then keeps the shell process open with an ongoing counter (i.e. “blocking mode”); once you cancel out (^C or q or the like) it converts the previous open-ended entry into a regular time range (8:43 - 14:22) and saves that.
  • There should be the aliases in and out to allow for the word play klog in (“clock in”)
• A command to add arbitrary time entries to a record, like 4h or 15:00-19:00, so that you can quickly track time values from your command line without having to open the file.
• A command that creates a new record. This is not just more convenient, but it also reduces the risk of making mistakes (e.g. entering a wrong date by accident). The new record can optionally be based off default values, e.g. for the should-total.

I don’t intend to build much more than that (e.g. something like “delete” or “lengthen”), because these kinds of operations can much simpler be carried out by just opening the text editor and manipulating the text directly. (Plain text ftw!)

Providing writing capabilities requires some upfront work, because the current parser and serialiser implementations don’t sufficiently preserve formatting variants and whitespace. Also, it must be avoided by all means to corrupt the data in files by accident, so the implementation must be safe and robust enough.

For reference: there was already some previous discussion around this in https://github.com/jotaen/klog/issues/3.

Current State

• Add experimental support for templates and appending #12 introduced a hidden (experimental) append command that creates new records from templates. This approach looks promising, so after some polishing it will probably be taken over as is.

[wAuner]

These are great ideas! Here are my suggestions/questions:

• instead of start / stop I'd propose klog in / klog out. I think this is a gread wordplay (from to clock in/out), very fitting and it's shorter. win on all fronts :)
• not sure what you mean exactly by blocking mode. As I understand this you're looking for a live tracking mode? In this case I'd suggest to not write the current time and close the current range on exit via ^c or q, but rather keep it open by inserting ?. This way the user can resume tracking. Actually closing the current recording could be done via e.g. w for write (like in vim).
• is new the same what append now does? Then maybeappend would be a more descriptive name for the track feature.

[wAuner]

And as you already said, it's important to keep the data in tact. Maybe a little backup mechanism could be added, e.g. whenever a change is performed on file.txt via any klog command, first make a local copy such as .file_backup.txt. This way we would have always a small safety net. Whether this happens could be turned on/off in the config

[jotaen]

• I tried to clarify the description around the blocking mode. However, I’m still not sure I understand what you mean with the resuming?
• I think the canonical names should be “start” and “stop”, because in the help text it might not be immediately obvious what “in” and “out” is. I like the word play a lot, though, so this could be easily supported through aliases. (Added that to the list above.)
• Good idea with the backups, I’ll keep that in mind depending on how robust the write implementation turns out. At least it could be worthwhile to consider for the initial period.
• I’m not determined about the wording around “new”, “append”, “track” and how to structure these functionalities generally. I think once I start building it and can try it out I’ll get a better feeling for it. I removed the specific naming suggestions (new and track) from the description for now. What I can say, however, is that I’m not a big fan of “append”, because it sounds very technical and in the longer term klog shouldn’t just append to files, but it should also be capable of making additions somewhere in between. E.g., maybe there are people who sort the records in their files from newest to latest and not the other way around.

[jotaen]

The work on this is mostly done, I’ll release it throughout the next days.

I have some bad news about templates though: they are still hidden and I’m seriously considering to ditch them. With the new commands you could effectively replace them with a bash alias:

alias foo=klog create --should='8h!' && klog start

I’ve realised that I find the idea of templates a bit too heavy-weight for the benefit it brings. For the time being the templates feature is still around, though (klog create --template work, before it was klog append --from work).

[tecunningham]

Very happy with v2.0, thank you.

I wonder whether you'd consider a syntax like this:

klog start <comment>

Where the comment is the free-text alongside the entry, including hashtags etc.

I currently am using a keyboard shortcut which writes directly to my KLG file, that allows me to write in some free-text in a dialog box. I'd like to use the API for this, but I think I can't do that currently.

[jotaen]

It’s not possible to make <comment> a positional (unnamed) argument, because this would lead to ambiguity with the file name, since both are optional. (This is different to the track subcommand, where the input argument is mandatory.)

But I agree that specifying a summary text should be possible, so: https://github.com/jotaen/klog/issues/36

[wAuner]

Hm, I'll have to try it first, but I use the template every day and think it is a great feature.