7 ms·
Show HN: Time tracking with plain text files
- maxerickson 6y agoThat's how the author of ledger uses ledger. https://groups.google.com/g/ledger-cli/c/XVR4t1B-XFI https://groups.google.com/g/ledger-cli/c/XVR4t1B-XFI
- jotaen 6y agoHello 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-textfiles/ https://www.jotaen.net/9zRPA/klog-time-tracking-plain-textfi...
- AmpsterMan 6y agoI 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!
- bombcar 6y agoWhat are some of the “more than 24 hours in a day” use cases?
- jotaen 6y agoE.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.
- bombcar 6y agoThe 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
- asciident 6y agoThis 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/ https://jeffhuang.com/productivity_text_file/
- jotaen 6y agoYes, 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.
- masswerk 6y agoHighly 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.)
- jotaen 6y agoSame 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
- bmn__ 6y agohttps://metacpan.org/pod/distribution/App-TimeTracker/bin/tracker#USAGE https://metacpan.org/pod/distribution/App-TimeTracker/bin/tr...
- masswerk 6y agoIt'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).
- robertkrahn01 6y agoI 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 https://github.com/rksm/clj-org-analyzer This has become my daily vehicle for tracking work.
- podiki 6y agoI 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 6y agoThe 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 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)
- forgotmypw17 6y agoCool 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.
- jotaen 6y agoThanks 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!
- forgotmypw17 6y agoThe way I would do it is to parse the blocks sequentially, and ignore the indentation. Maybe you are doing that already?
- jotaen 6y agoProblem 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.
- forgotmypw17 6y agoThat'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.
- hprotagonist 6y agoSo far i’ve been happy with org-clock-in https://orgmode.org/manual/Clocking-commands.html#Clocking-commands 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?
- jotaen 6y agoIn 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 6y agoAt least take a look at how Timewarrior stores things, maybe you will get some ideas: https://timewarrior.net/docs/files.html https://timewarrior.net/docs/files.html
- wakatime 6y agoI used a txt file and org-mode, then I built https://wakatime.com https://wakatime.com to automate my time tracking.
- ghartog 6y agoI 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.
- jotaen 6y agoThe 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 6y agoThis 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 https://github.com/anarcat/ledger-timetracking You can also use the aforementioned org-clock-in with it.
- anarcat 6y ago"author" of ledger-timetracking here, AMA, although I don't use it anymore...
- dpcx 6y agoI'm a big fan of time tracking for personal reasons. Does this give something that timewarrior[0] doesn't? [0]: https://timewarrior.net https://timewarrior.net
- jotaen 6y agoThe 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 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 6y agoCall 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: <div><li class="start">202102010845</li><li class="end">202002010930</li></div> 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 6y agoyou 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 6y agoI'd just go for csv files then, which are trivial to process in any language.
- jotaen 6y agoAs 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 6y agoI 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/formats.rst#timelog-txt https://github.com/gtimelog/gtimelog/blob/master/docs/format...
- keyle 6y agoThis 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
- jotaen 6y agoIn 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/ https://jekyllrb.com/docs/front-matter/
- jotaen 6y agoAnd good that you tackle the test setup – that’s neglected far too often unfortunately.
- keyle 6y agoUpdate: https://github.com/keyle/mdtimesheet https://github.com/keyle/mdtimesheet
- jotaen 6y agoWell done, and great that you could adapt the idea to your workflow.
- raleighm 6y agoThis 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 6y agoShameless 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 https://github.com/rlv-dan/cctime
- scooble 6y agoNice. 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 6y agoThanks 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 ;)
- jotaen 6y agoHappy 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.)
- jhunter1016 6y agoReally 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!
- jhunter1016 6y agoAlso 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 6y agoI 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 6y agoAwesome, I wanted to build exactly this and found this project. Would like to build a glossy client for it.
- bu-da 6y agoLooks 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?
- jotaen 6y agoFor 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.