Show HN: Time tracking with plain text files | Hacker News Reader

Show HN: Time tracking with plain text files

github.com

94 pointsjotaen51 comments

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

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!

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

https://metacpan.org/pod/distribution/App-TimeTracker/bin/tr...

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

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)

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

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.

So far i’ve been happy with

  org-clock-in

https://orgmode.org/manual/Clocking-commands.html#Clocking-c...

but i know some taskwarrior folks too.

what is new and cool here that’s a standout feature for you?

In regards to org-clock-in specifically I would say that I don’t have to use Emacs.

On a serious note, the main idea is to focus on time tracking (not todos) as in keeping a record of how you spent your time. The other aspect that was important to me is to put the simplicity of the file format first and to be independent from tools (when it comes to writing the data at least).

At least take a look at how Timewarrior stores things, maybe you will get some ideas: https://timewarrior.net/docs/files.html

Thanks for building this!

I'm especially excited about the "file format" part! Hope others can implement extra clients around this. I could imagine an android app with nextcloud/dropbox integration to sync time tracking entries between devises, e.g.

I once started (but never released) an eventful timetracker; where hooks and wrappers would (retrospectively) send events to the timetracker repo (basically just drop json files in a folder) on "events". Such as `git checkout feature/x`, git commit. Or `cd projects/foobar` or from some ical feed. Walking through these events once your manager "really really need those hours today" is always easier than retrospectively manually going through git commits, google-calendar, release-logs etc.

Seeing your project makes me want to pick that project up and make e.g. "klog.txt" files from a list of such events. Great work, and congrats on actually releasing ;)

Happy to hear that you like it!

I am indeed more focussed on the file format right now than on the command line tool. If the format turns out to be valuable and useful in itself, my plan would be to build a small UI app. As you said, I think the advantage of a well-specified plain-text file format is that tools can be built around independently – with the smallest common denominator always being the text editor of your choice.

By the way, for Mac users there is already a menu bar (systray) widget bundled in, which renders a brief overview of a file. (In a very simplistic fashion though; it’s more a proof of concept than anything else.)

Call me crazy, but html is a great way to track time in plain text. That was actually one of the use cases that opened my eyes to the power of html over markdown as a plain text format. One example:

You can argue that's ugly. And you're right, if you open it in a text editor. Thing is, you can use a browser to display it pretty darn nicely. It has all the advantages of plain text, but one massive additional advantage - you can use JS to work with the DOM to do all your queries and calculations in a few lines of code. HTML can be verbose at times, but it doesn't really matter if you use text snippets.

This is not intended to take anything away from this project. I'm just saying there's a powerful alternative that doesn't require the writing of a special processor.

you can use JS to work with the DOM to do all your queries and calculations in a few lines of code

There's nothing wrong with the approach you took, and there's a lot to be said for just getting stuff done, but I suspect knowing a tool for handling HTML is the reason you're using HTML as a data format rather than any specific virtue of HTML. Rather than use something 'better', you used something familiar. I see that a lot. I'd argue that you missed an opportunity to examine ways to store that specific time series data in a format that could do more stuff faster with the same level of effort, and an opportunity to learn something that is a bit more appropriate for the task.

But, ultimately, you made something that works for you, and maybe that's more important.

I'd just go for csv files then, which are trivial to process in any language.

As an idea, you could consider to use HTML5 elements in order to make it more semantic.

    <dl>
      <dt><time>2018-07-07 14:54:39</time> - <time>2018-07-07 17:12:05</time></dt>
      <dd>Did this and that</dd>
    </dl>

Native support for time ranges (e.g. through ISO8601 or a <range> element) might be coming soon in the HTML spec. Durations are already supported.

Shameless self promotion: I got tired of using Excel but could not find a simple way to track my time so I built my own and I think many here would find it useful:

https://github.com/rlv-dan/cctime

This reminded me of ledger, the plain text accounting tool. FWIW, ledger has time tracking and billing capabilities, too.

For example: https://github.com/anarcat/ledger-timetracking

You can also use the aforementioned org-clock-in with it.

"author" of ledger-timetracking here, AMA, although I don't use it anymore...

I see #tagging capabilities. When work requires time tracking, an entry usually corresponds to a reference ticket number and/or git hash. In a unix|pipe spirit, then posting this well formed data via curl to the usual suspects apis (jira, youtrack, ..). How nice indeed this would be.

The tagging capabilities is a bit of an experiment because I know that some people would be interested in doing analysis on their data. I thought it was a nice add-on, because it basically comes for free and is very flexible. (In contrast to the notion of categories or projects.)

This is a fantastic idea!

I'm going to write a similar one for myself. It never occurred to me that I could use a markdown file as a data files to record time against.

I keep a log of my work, inspired by .plan files, such as this, I will just tuck in the times against each day and get myself a timesheet system, thanks!

   plan.md
   
   ### 2021-01-07-thu :0830-1700-45m 
   
   * fix for initdb generating wrong index causing the tests to fail and creating new c/u every run [bug]
   * more fixes for tests to run reliably

In case you have one file per day you could also consider using a YAML frontmatter like it’s used in Jekyll[1]. Then you could capture the time-related info as structured meta-data.

[1] https://jekyllrb.com/docs/front-matter/

And good that you tackle the test setup – that’s neglected far too often unfortunately.

Update:

https://github.com/keyle/mdtimesheet

Well done, and great that you could adapt the idea to your workflow.

I have been using the format used by gtimelog[1] for years. It has the benefit of adding one entry per line, so processing is extremely simple.

[1]: https://github.com/gtimelog/gtimelog/blob/master/docs/format...

Looks interesting! Out of curiosity, why didn't you choose sqlite instead of a plaintext format? With sqlite the users could write their own queries to get the information they want. Adding entries manually via db browser is also easy. Besides readability and the possibility of using an arbitrary text editor what are the other advantages of your approach?

For me what mattered most was to have a format that allows to access/edit the data without needing specific tools (other than a text editor, that is). But as you said, both formats have their pros and cons depending on what is important to you.

Nice. I use a much simpler format which is basically the task name and the number of minutes worked. These lines are appended to a text file for the day that gives me a timesheet. I start a bash script when I start work which counts the minutes and writes the file when I’m done.

This is great. I keep coming back to plain text when I fall out with other tools. I use it for daily logs and journals. I also use it for five-star ratings: books, albums, and daily performance reviews (e.g. ●●●◍◌ as indicating 3.5 stars). Works well for me.

That's how the author of ledger uses ledger.

https://groups.google.com/g/ledger-cli/c/XVR4t1B-XFI

I'm a big fan of time tracking for personal reasons. Does this give something that timewarrior[0] doesn't?

[0]: https://timewarrior.net

The conceptual difference is the file format, as with klog the main idea is to have a format that looks and feels “natural”. So when opening a `.klg` file you don’t need to know much about the format in order to make sense of it, yet the data can be parsed and processed. And you can type in the entries by hand in a text editor, due to the simple and memorable syntax.

The data format in timewarrior is more opaque, even though it’s still plain text of course. There are, by the way, also cool projects that use sqlite as underlying datastore, like https://github.com/samg/timetrap , which produces a similar output as timewarrior.

I guess both philosophies have different strengths and weaknesses, depending on what is important to you.

Really love this. I try to keep my contracting work time tracking as simple as possible, but I really hate using the spreadsheet I use now. Going to give this a shot!

Also just realized you wrote it in Go. I’ve been slowly trying to pick up Go myself and digging through your source could help.

I use Excel and with a few simple formulas it creates a pivot table that prints a replica of exactly what to type into my time card at the end of the day.

I don't have access to org mode or any third party software so it works for me.

I used a txt file and org-mode, then I built https://wakatime.com to automate my time tracking.

Awesome, I wanted to build exactly this and found this project. Would like to build a glossy client for it.

Reply on news.ycombinator.com