back

by jotaen·5y ago·view on hn ↗
Hello HN!

As a daily user (and enthusiast) of plain-text file formats such as markdown, ledger or todo.txt, I thought that there should also exist an equally simple way for tracking time.

After some pondering and experimenting I recently released the open-source project “klog”, which is both a file format and a command line tool. The idea is to have a lightweight syntax to record times in plain text, and to be able to run evaluations on the data.

I’m happy so far how the basic approach came out, and I’d appreciate some feedback and thoughts (especially on the file format, since that’s the central idea that everything else builds on).

For anyone interested, I have also written up some of the backstory behind the project on my blog: https://www.jotaen.net/9zRPA/klog-time-tracking-plain-textfi...

7 comments
I use emacs org mode with the built-in time tracking features (org-clock-in). A while ago I built an analyzer for org files that allows to spice and dice how you spent your time: https://github.com/rksm/clj-org-analyzer This has become my daily vehicle for tracking work.
I need to play around more with clj-org-analyzer, but thanks for making it! It was great to visualize time tracking over a long period of time last I used it.
Cool project! Thank you for sharing, and for using .txt as data format. I think it's by far the most resilient and compatible, and the least user-surprising data format we have today.

I have a question about this example:

    2018-03-24
    First day at my new job
        8:30-17:00
        -45m Lunch break
Are you in this case creating two entries, one of 8.5 hours and -45 minutes, for that date, or are you applying that -45 to the previous entry?

My other comment is to strongly advise you against using whitespace for syntax, because that makes copy and paste operations much more problem-prone.

Thanks for your feedback, much appreciated.

The current model is that every record (i.e. that entire block) can have multiple entries that are added up regardless of order. So the resulting total is the just the sum of the individual time values. (Here: `8h30m + (-45m) = 7h45m`)

Regarding whitespace: are you referring to some whitespace specifically (like the indentation) or to whitespace in general? Do you have a concrete idea in mind how you would change the syntax? Curious on your thoughts!

The way I would do it is to parse the blocks sequentially, and ignore the indentation. Maybe you are doing that already?
Problem is (unless I’m misunderstanding you) that the entries must be unanimously distinguishable from the summary text. Consider:

    2018-03-27
    Tried to do this and that,
    but had to stop after
    30m because of a phone call.
        30m Some activity
The fourth line could not be told apart from an entry (the fifth line) without indentation or some other special character.
That's what I'm talking about.

Now, imagine you take that block and copy it from one text file and into another.

The meaning is now completely lost.

I think that using lines as separators is a better idea.

However, it is true that it requires care and brevity when writing your item lines.

The method I chose was a clock-in/clock-out type of system where you can use the tool to start and stop tasks. Of course, you can type in and edit entries if you want, but the formatting is much more strict than your system.

https://github.com/timpark/tasktimes (although I made the repo in 2013, I can't remember how many years earlier I started working on it)

This looks great, plain-text is underrated. Do you use this yourself, and for how long?

Your format looks like a slightly more strict version of this one here: https://jeffhuang.com/productivity_text_file/

Yes, I use it regularly to log my working hours since ~2 months. However, initially I started with a different format which was basically just a YAML schema. That worked well for processing the data, but it turned out to be too verbose to type by hand. A big inspiration came from ledger (an accounting tool/format), which I appreciate a lot because it’s very powerful yet it has a dead simple syntax.

I too think that plain text is very underrated. I think though that this is more due to the tooling aspect than to the data format itself. (Especially if there is only a CLI application.) I like the note management tool Zettlr for that matter, because it demonstrates how both things can be combined.

Highly recommended, I'm using a similar solution for years, and it couldn't be simpler. (Mine is a Perl script – as already mentioned, it's a few years old. Generally, I'm keeping a dedicated list per client, usually residing on top of a directory dedicated to this client, a job inbox of sorts. I might be adding the `-xx` format for subtracting breaks, which is a nice idea.)
Same for me – I have one file per client per month. At the end of the month I do `klog eval 2020-12.klg` and copy&paste the result to the invoice.

Do you have that Perl script online somewhere? Would be curious

It's really simple: the data file contains a line per job, consisting of the date, time spent, optional label for a job. The script reads the lines in a loop, converting hours to minutes, sums by minutes spent, and breaks the total into hours and minutes. (I'm doing this actually just on a given range to be billed, and insert/paste the total and any billings derived from this into the text file as a comment, by this maintaining the text file as a key documentation and marking any billing intervals, as well).
I too enjoy plain text file formats. I have a text file where I keep track of my time, but I'll give this a shot tomorrow!
What are some of the “more than 24 hours in a day” use cases?
E.g. say you want to take over 50h worth of time from somewhere else into a new `.klg` file, then you would be able to note that down under a single record.

My thought was that there are more reasons to allow things like >24h or <0h than to reject them, but maybe it’s too much flexibility for no good reason? In any event it might be worth considering to emit a warning though, in order to prevent mistakes from happening by accident.

The warning sounds good but that use case makes sense - often it's better to allow "slightly unclean" data to make the format work better than to demand that someone work out how to add 40h to a total by splitting it over multiple days