Show HN: Time tracking with plain text files

by jotaen • 5 years ago

94 51 5 years ago

jotaen15• 5 years ago

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

AmpsterMan• 5 years ago

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!

asciident• 5 years ago

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/

jotaen15• 5 years ago

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.

masswerk2• 5 years ago

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

jotaen15• 5 years ago

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

robertkrahn01• 5 years ago

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.

podiki• 5 years ago

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.

timpark• 5 years ago

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)

bombcar2• 5 years ago

What are some of the “more than 24 hours in a day” use cases?

jotaen15• 5 years ago

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.

forgotmypw173• 5 years ago

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.

jotaen15• 5 years ago

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!

hprotagonist• 5 years ago

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?

jotaen15• 5 years ago

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

gregopet• 5 years ago

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

wakatime• 5 years ago

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

ghartog• 5 years ago

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.

jotaen15• 5 years ago

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

7kay• 5 years ago

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.

anarcat• 5 years ago

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

dpcx• 5 years ago

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

[0] https://timewarrior.net

jotaen15• 5 years ago

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.

bachmeier• 5 years ago

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.

onion2k• 5 years ago

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.

alpaca128• 5 years ago

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

jotaen15• 5 years ago

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.

ximm• 5 years ago

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

keyle2• 5 years ago

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

jotaen15• 5 years ago

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/

jotaen15• 5 years ago

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

keyle2• 5 years ago

Update:

https://github.com/keyle/mdtimesheet

jotaen15• 5 years ago

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

raleighm• 5 years ago

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.

rlv-dan• 5 years ago

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

scooble• 5 years ago

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.

berkes• 5 years ago

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 ;)

jotaen15• 5 years ago

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

jhunter10162• 5 years ago

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!

jhunter10162• 5 years ago

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.

2OEH8eoCRo0• 5 years ago

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.

jamil7• 5 years ago

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

bu-da• 5 years ago

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?

jotaen15• 5 years ago

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.

maxerickson• 5 years ago

That's how the author of ledger uses ledger.

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

Show HN: Time tracking with plain text files

Related Stories