klog report currently aggregates by day. There could be additional aggregation modes that output the same format but with different period buckets:

• --by month
• --by week. Caveat: in some regions the week starts Sunday, in some on Monday, so that would need to be configurable. Maybe via --by week-monday and --by week-sunday (default), where --by week is an alias for the latter.
• --by quarter
• --by year
• --by day. That’s the current behaviour and should be the default if no option is given.

The --fill flag should continue to work for all those options.

A should-total MUST be a duration value [...]

It feels unnatural to specify a negative duration, however the spec allows it.

I believe it would be good to clarify this by either

• giving a negative duration as an example, or
• specifying only positive durations are allowed (what I assumed to be the case)

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

Current State

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

I’m currently experimenting with wrapping shell scripts around klog, e.g. to automatically create new .klg files based on a date pattern. Say, you follow the convention YYYY-MM.klg then such a shell script could take care of creating a new file on the fly at the beginning of a new month. (Just for reference: incorporating such functionality directly into klog is out of scope.)

In order to improve that kind of programatic access to klog, the following things would be handy:

• Distinct error codes, so that certain error cases can be reliably distinguished (e.g. “file not found“). Currently, all errors cause klog to exit with -1.
• A “quiet” output mode, to only print the raw “response” of a command without any labels meant to structure the text for humans, e.g.:
  klog bookmark get → Current bookmark: /home/users/foo/myfile.klg
klog bookmark get --quiet → /home/users/foo/myfile.klg
  That way you can do CURRENT_BOOKMARK=$(klog bookmark get --quiet) in a more robust way.
  • This flag only makes sense on certain subcommands, e.g. total, bookmark or version
  • --quiet should imply --no-color

Same as #18 but this time on the CLI.

https://github.com/jotaen/klog/blob/main/src/app/cli/cmd_now.go#L23 needs to be moved one line down.

The eval feature currently takes only one tag at a time. It will be helpful to list aggregates for all categories at the same time.
eg:

klog eval --tag=ALL

# Output
work  5h
personal 6h
client 3h

When using the --no-style option, the --diff flag renders different output, because it omits the + for positive values (e.g. +5h regularly, but only 5h with --no-style).

For macOS there is a great productivity tool called alfred. Once the core functionality of klog has matured, I think it would be cool to add an alfred integration. If I find the time, I‘d be happy to help with that.
All that should be needed would probably be an option that returns the output as json.

This way mac users could call klog from anywhere instantly without opening the terminal.

It might be nice for the KLOG-format to allow entries just at a single point in time, with no duration, e.g.:

2018-03-24
First day at my new job
    8:30 - 17:00
    12:00 #workout 

You can already have zero-duration entries, like 12:00-12:00, but this format might be a bit more natural. Some use-cases:

• Keeping track of doing exercise, when duration doesn't really matter
• Keeping track of meals
• Keeping track of commits

I have been reading through the specification, and I believe there are a few things which needs further clarifications.

I. Records

Summary

It MUST be separated from the entry one “space”

Incorrect wording, I believe.

Range

There MUST be a - between the two values, which MAY be surrounded by one “space” on each side.

Ambigious. Can there be ...

• ... multiple spaces?
• ... spaces on just one side?

klog currently actually accepts ranges in the format of 00:00 -01:11

The ? MAY be written in repeatedly, e.g. ???.

Incorrect wording. Maybe use "in a recurring succession"?

Duration

I would very much like to see a clarification that the minute part cannot be greater than 59, if it is in combination with an hour part. I assume this is the intended behaviour, since klog throws an error if the minutes are greater than 60. However, surprisingly it actually accepts 1h60m and interprets that as 2h. I believe this is a bug with the program, but I might be wrong.

II. Organizing records in files

Subsequent records MUST be separated by one “blank line”; there MAY be additional blank lines.

Contradictory. I interpret the first sentence as "must be separated by one and only one blank line". I wish for this to be clarified.

Here's some basic code to pull JSON data, parse it, and draw a visualization in R.

I wanted to share for interest, I will try to slowly improve it.

library(tidyverse)
library(lubridate)
library(hms)
library(scales)
library(ggfittext)

read_json= function() {
  json= system('klog json', intern=TRUE)
  entries_parsed= jsonlite::fromJSON(json, flatten=TRUE )
  entries= entries_parsed$records %>% 
    tidyr::unnest(entries, names_repair='universal') %>%
    tidyr::unnest(tags...12, names_repair='universal') %>%
    mutate( summary= gsub('#[a-zA-Z]+[ ]*', '', summary...11, perl=TRUE) ) # remove hashtags
  return(entries)
}

# a function to reverse scale-order, taken from
# https://stackoverflow.com/questions/43625341/reverse-datetime-posixct-data-axis-in-ggplot
c_trans <- function(a, b, breaks = b$breaks, format = b$format) {
  a <- as.trans(a)
  b <- as.trans(b)
  name <- paste(a$name, b$name, sep = "-")
  trans <- function(x) a$trans(b$trans(x))
  inv <- function(x) b$inverse(a$inverse(x))
  trans_new(name, trans, inverse = inv, breaks = breaks, format=format)
}
rev_date <- c_trans("reverse", "time")

entries= read_json()
ggplot(entries,
        aes(
      ymax=floor_date(as.Date(date)),
      ymin=floor_date(as.Date(date)+1),
      xmin=as_hms(paste0(start,':00')),
      xmax=as_hms(paste0(end,':00')),
      label=summary...11)) +
  geom_rect(aes(fill=tags...12))+
  geom_fit_text(aes(label=summary),reflow=TRUE)+
  scale_y_continuous(trans = rev_date) +
  theme_minimal()

If there is no records for the current date, then you would get a error message:

Error: No eligible record at date 2021-04-17
Please make sure the record exists and it contains an open-ended time range which start time is prior to your desired end time.

You receive a similar error msg when you start tracking the day before and klog stop in the next day. Then I have to edit the entry for both dates like the following:

2021-03-28
    22:05 - 23:59 Task 1

2021-03-29
    00:00 - 00:57 Task 1 continue

It would be great if the new date is entered automatically and as well as a new entry with open ended time range starting at 00:00

I've added klog to my PATH and tried few commands. I can operate the logs, print them etc but the bookmark feature did not work. I'd love to provide further details but the error received is just that plain.

C:\_clienti>klog bookmark set timelog.klog
Error: Failed to create bookmark


C:\_clienti>klog version
Command line tool: v2.2  [0bb0d83]
File format: version 1 (RFC)

Checking for newer version...
You already have the latest version!

I noticed something that I'm really missing:
The sum of my overtime -not including- the current time. For example for klog now -d

            Today    Overall
Total          2m    165h27m
Should        8h!      168h!
Diff       -7h58m     -2h33m
E.T.A.      1:31>      20:06

I wish there was maybe a first line which would tell me what's the total of my overtime without taking the current time into account (or assuming I fulfill my should time today). Not sure how to best name and display it, but I think that's very important.

Say I have this sample file:

2021-03-25
Back to #school
  8:30 - 11:30 Classes
  -10m Passing Period
  1h #homework

When I use klog print in a VSCode PowerShell terminal, it appears how I assume it should:

However, when I run the same command in the Windows command prompt, it outputs:

I don't know if this is an issue on my end - cmd.exe seems to have TrueColor support - or if there isn't a platform-specific check for ANSI codes.

Additionally, it yields the same results in a Windows-native PowerShell terminal:

I browsed the issue board to see if anyone else has had this. Sorry in advance if this is a duplicate, I just want to bring this to attention.

klog report and klog today both print tabular data. The column width of the tables is fixed, though, so it can only handle values up to a certain length. This should be fine for most use cases, but it can still break for larger numbers.

             Total    Should     Diff
Today           0m       8h!      -8h
Other     128981h30m     119h!+128862h30m
          ===========================
All       128981h30m     127h!+128854h30m

The code for creating these tables is also very repetitive, so it would be better to use a helper struct. (klog tags can also use it then.)

It would be useful to have basic build instructions in the “Contribute” section of the README to encourage people to build klog from sources.

Originated in #70.

Hi,
first of all great tool, I think plain text as database is heavily underrated and a huge pro for considering to use klog.

As I am working on different projects per day, it would be convenient if I can simply stop tracking time for the current project and start tracking time for another project.

Currently the following steps are necessary to switch from one timer to another:

# start working on project A
$ klog start a.klog

# ...

# oops, a bug report of project B came in and must be addressed immediately
$ klog stop a.klog

# start working on bugfix
$ klog start -s "bugfix #123" b.klog

# ...

# implementation of bugfix finished
$ klog stop b.klog

# resume work on projectA
$ klog start b.klog

A simple klog switch 2.klg would simplify this workflow.

However, additional work and clarification is needed:

• klog needs to keep track of running timers because it must stop them.
  Possible solution: klog maintains a running timers file (e.g. /home/$user/.klog where the path to the .klg file is added when the timer starts and removed when the timer is stopped
• What to do when multiple timers are currently running?
  • stop only most recently started timer
  • stop all timers
  • let user choose.

Edit:
Another possibility that arises from keeping track of running timers is that you easily query a list of running timers.
For instance something like that:

$ klog status

Running timers:
+------------------+-------------+----------------+---------------+
|      Start       | Running for |  Description   |     File      |
+------------------+-------------+----------------+---------------+
| 2021-04-01 08:00 |    00:04:22 | Bugfix #1337   | project_a.klg |
| 2021-03-15 10:22 |    15:04:00 | Implement Task | project_b.klg |
+------------------+-------------+----------------+---------------+

However klog can only display the status for timers that have been started with klog. Maybe time sheets can be registered at klog, for keeping track of them (or entire directories)?

But that would be another task :)

Thanks!
Regards

It would be nice to install klog via Homebrew so I don't have to worry about installing/updating

I already love it, it's better than my current setup which is in a similar format but on paper :^)

The tool looks great, thank you for developing it! Looks like just what I've been looking for, I'll give it a try starting today.

Just like how you have support - can you consider an option for +

eg:

2018-03-24
First day at my new job
    8:30-17:00
    -45m Lunch break
    +30m commute to office

Given you support logging more than 24hrs a day, this should be hopefully not very hard.

In analogy to tracking a negative duration (-1h) it could be useful to allow tracking “negative” time ranges, i.e. a specific period of time to be deduced from the total.

Syntax ideas:

2020-01-01
    8:00-17:00 Work
    -12:00-13:00 Lunch break
    -(12:00-13:00) Lunch break
    -[12:00-13:00] Lunch break

Currently favouring the [] syntax, as it’s more distinct from the should-total.

Source: #3

Sometimes you want something done in a certain amount of time, sort of like a deadline but in a certain time constraint. Other times, you know that a task could take more than the time you expect it could. It would be nice if there was a feature for this.

As < and > are already in use for day shifting, here's what I propose:

2021-03-26
  8h another day at my #job
  ?30m lunch #break, I gotta get my report done!
  1h? watching #football

Alternatively, it could be >1h or 30m<, but that could cause issues with the current day shifting syntax. I think either one is pleasing to the eye.

As for klog totaling this record, these could be ignored as with open-ended time ranges, or (and I think this is better) they could be accounted for by denoting "or more" (or "or less" by a certain margin).

For example, the record above would be totaled as such:

Total: at least 9h or less by ~30m
(In 1 record)

Typing that out, it feels clunky. Perhaps there's a better, more intuitive method of totaling that. Overall, though, I think this would be a beneficial addition.

A regression occurred in the output for parser errors: there is a misplaced argument passed to fmt.Sprintf that causes the %!(EXTRA string= to be appended by the Go runtime.

$ klog total
 ERROR in line 28: 
    5h
    ^^
    Unexpected indentation: Please correct the indentation of 
this line. %!(EXTRA string=
    )

When tracking a time entry via track you can already specify an entry summary, e.g.:

klog track '1h washing dishes' chores.klg

In analogy to that the start and stop subcommands should also allow this. In contrast to track, however (where the entry text is mandatory) we must use named flags here, because otherwise there would be multiple optional positional arguments: <summary> and <filename>.

So for start it could be:

klog start --summary 'this and that' foo.klg

stop should be equivalent – however, the question is how klog should deal with an entry summary that is already present, e.g.:

2000-01-01
    15:00 - ? Foo bar baz

tl;dr: in the whitespace definition, replace another character with any other characters.

In the specification, “whitespace” is defined as:

A “space”, a “tab”, or another character that appears blank

I interpret the "[…] or another character […]" as "[…] or one other character […]", as if there were three distinct whitespace characters. The last one mentioned is not specified, and thus could be interpreted as letting the user select a third blank character, or possibly that the third character was forgotten and not put in the specification.

A more appropriate definition would be:

A “space”, a “tab”, or any other characters that appears blank

This issue is a spin-off of #27. --after and --before are currently inclusive, which is not intuitive. On the other hand, there could also be legitimiate use cases for it, e.g. --after=2000-01-01, instead of --after=1999-12-31. I think the ultimate solution is this:

• Make --after and --before exclusive
• Offer a separate inclusive version of the flag e.g. --after-or-at or --after-incl --since and --until
• Support date ranges for convenience, i.e. --in=2018 for “all in 2018” or --in=2018-01 for “all in January 2018”.

All exact names tbd., suggestions welcome.

I am attempting to pipe output to klog.exe on Windows, version v2.2 [0bb0d83].

In this example I receive the following error:

$ cat .\time.klg | .\klog.exe total
Error: No input given
Please do one of the following:
    a) pass one or multiple file names as argument
    b) pipe file contents via stdin
    c) specify a bookmark to read from by default

This was attempted using PowerShell 7 (Preview) and Git for Windows (bash) respectively.

I propose a command like klog status (feel free to come up with a better name) that does these things:
When the user makes an entry with an open ended timeframe like 08:00 - ? then klog status returns the current running time from 08:00 - now.

If additionally a should time is provided, it also reports back the delta to the should time. e.g. 8h! and it is 14:00, -45min, then it would say "-2h45m" and ideally also the time when the should time would be reached, 16:45 in this case.

I would love if the KLG format could support free text in the headline (the line where the date goes).

Personally I think it would improve readability, e.g. in the following having day-of-the-week in the headlines makes it easier for me to remember what the context was for the work I did that day:

2021-02-28 Sunday
   06:00-7:00  #writing
   08:00-10:00 #writing (pareto frontier)
   12:00-12:40 #implicit preferences

2021-03-01 Monday
   06:00-07:00 #writing
   09:10-11:44 #implicit
   14:20-15:50 #implicit
   16:00-17:00 garden
   21:00-22:00 looking at text file time-trackers
   
2021-03-02 Tuesday
    5:40-07:00 #writing
    9:00-12:20 #implicit -
   12:50-13:10 #implicit jon
   13:30-14:00 talking to eduardo about jobs
   14:46-16:12 #implicit working on foundations
   19:14-20:15 try out Pareto frontier with R
   20:25-21:55 #implicit

I'm tinkering around with the alfred integration. It would be helpful to have options for create, start, stop etc to get unformatted plain text or even json returned, instead of the colorized text output. Maybe something like klog stop --raw

I created an entry from a template with klog append but today it does not seem to work:

The entry created looks like this:

2021-02-11 (8h!)
Wooooork!
   6:56 - ?

When I now run klog total --today (with or without the diff flag) it always says the total is 0m.
This could be a parsing error in klog total

Probably this is obvious, but just occured to me that this would be a great visualization of the klog data:

I will try to do this in R sometime, but also occurred to me it would be cool to do in the terminal: e.g. each cell can be a number representing number of hours recorded on that day, it would be a very efficient way of representing the total work on a long-running project.

The specification is currently mostly focussed on formal aspects of the file format. It should also go more into detail about certain practical topics, e.g.

• What is the total time of a record?
• Clarify that it’s legal to track more than 24h a day or that overlapping time ranges are permitted, etc.

Originated in #61

The following record is erroneously considered invalid by the CLI:

2021-06-02
   60m
   120m

This is behaviour not compliant with the spec, because the 60 minute restriction should only come into effect when there is an hour part, e.g. 1h30m but not when the minute part is standalone, e.g. 120m.

The concept of comma-separated “properties” was really premature optimisation. It doesn’t have any practical effect except for causing confusion maybe. The should-total is the only property that there is.

“Properties” as a generic idea can be brought back in case another parameter is ever needed.

Would be cool to have an custom icon for .klg files, e.g. to display in file browsers.

Thoughts and suggestions are welcome.

It would be useful if the file formats supported (block or line) comments.

These would be ignored completely by the tool.

This is an idea that came up in #74 (comment): currently, the CLI only supports one bookmark at a time. That doesn’t work well, however, for the use case when someone keeps multiple files at a time, e.g. one for every client or one for every activitiy.

Therefore, I propose the following:

• First of, the current use-case (one default bookmark) should continue to work as is.
• When a bookmark is set, it can be given a name, e.g. klog bookmark set --name client1 ./file.klg
• Bookmarks can then be referenced via that name, e.g. klog total @client1 or klog total @reading. There probably should be some sort of mechanism to distinguish a named bookmark from a file name, hence the @ prefix.
  • Todo: decide what prefix character to use. @ is technically valid for file names on UNIX, but at least it’s probably very uncommon for files to start with it.
  • Todo: whatever the prefix character is, make sure it works on Windows too.
• If the user doesn’t provide a name, assign the name default implicitly. That one works the same as the default (unnamed) bookmark right now.
• Instead of creating a symlink at ~/.klog/bookmark, create a JSON file at ~/.klog/bookmarks.json to store all that info. This would conveniently happen to solve #66 as well.
• Implement all necessary convenience for the bookmark subcommand, especially:
  • Listing them
  • Renaming bookmarks, e.g. klog bookmark rename client1 client2

It'd be great if the MacOS systray widget displayed today's cumulative time in the menubar.

Could have an option to display all time, or just for a specific tag.

I've taken the time to test the release candiate and read the guide and specifications. I really like it, good job!
My main use case would be to track my working time, especially overtime. To make this as convenient as possible, I'd be really happy to have the following features:

• a config file mechanism: maybe a user global file like ~/.klogconf. In this file I'd like to put a default directory where I keep all my records and my default "should value" and maybe addtional settings. There could even be a mechanism that looks in the local directory for a local config first, should that be necessary
• the ability to create records/entries via the cli:
  • something like klog in to create an entry with the default "should value", date, current time and open ended entry, maybe a default tag from the config (also an option to add or omit certain values). Ideally this would automatically choose the right file, like one file for each month in the configured directory.
  • also klog out to create the corresponding value that "closes" the previous klog in
• nice to have: allow negative ranges such as -(08:00-09:30) to be the same as -1h30m

If you do klog track '2h' or klog start it fails if there is no record at the current date. So you have to do klog create first. It would be useful if the commands would just create the record right away.

Originated in #59.

In record summaries (the text directly underneath the date) you can write multiple lines, but in entry summaries (the text behind the time values) you are restricted to a single line.

klog should support multiple lines for the entry summaries as well, by making use of the indentation. That allows for more flexibility.

As an example:

2020-02-02
    4h Today I finally answered all my
       unread emails, yay
    1h Reading

This requires a change of the spec, though, so I want to wait until v1.0 of the file format is finalised.

This issue came out of #50

Currently overlapping times are allowed, with the specification mentioning nothing about overlapping time ranges. The following is legal according to the specification and klog:

2021-04-20
    00:00 - 01:00 foo
    00:00 - 01:00 bar

This intuitively feels as if an error has been made when manually entering times.

I believe overlapping time ranges' legality should be clarified, whether that would be an error, a warning, or perfectly legal.

Side note: I am unsure if this is the appropriate issue to bring this up, but with overlapping time ranges I can log more than 24 hours for a date. The same is true for time durations, where you can log 9999h for a day.

Personally, I am unsure where I, myself, would draw the line. If overlapping times should be illegal, I also believe that a maximum of 24 hours would be allowed to be logged per date (disregarding summertime). If it is legal, then I believe there should be no maximum cap for time logged per date.

For klog bookmark edit, in case the $EDITOR environment variable is not set, the tool could just try the usual suspects one after the other. That would be a bit more user-friendly than just to error out.

Candidates:

• UNIX: vim, vi, nano, pico, code, subl
• Windows: code, subl, notepad

Not sure how to decide the order, on the other hand this is what $EDITOR is there for.

It should also print a hint when having guessed an editor, so that people are aware they can set an $EDITOR preference.

Compiling klog on Windows has no apparent problems when using Windows Terminal.

Are there any reasons to why a Windows binary is not present?

This is a very extreme suggestion, but I thought it's worth mentioning to see what other people think.

I've been putting longer descriptions alongside each of my entries, and it occurred to me it'd be nice to be able to integrate the whole thing with markdown, such that the klog format is a subset of markdown.

Here's one way it could work: an entry is a bulleted list with a time-code, and the entry-description is anything which is attached to that bullet (including sub-bullets, etc.)

# 2021-03-22 Monday
- 07:00-08:30 #writing, wrote to Arash, Jon, Per.
- 08:30-10:30 
   - Found Hall's marriage theorem, which says saxophone and diagonal representation of inequalities are equivalent, which allowed me to prove the diagonal lemma & so the theorem.
   - Was able to cut out a bunch of extra material from the paper.
      - Including cutting all the corollaries.

- 13:00-18:00 Read
   > "It is in the chemistry of these subtle substances, these curious precipitates and explosive gases which are suddenly formed by the contact of mind with mind, that James is unequalled"

# 2021-03-23 Tuesday
Terrible hangover.

- 14:00 coffee
- 14:00-13:00 read my letters, wrote to my mother.

When filtering for tags on the command line it could be useful to be able to search with wildcards, e.g.

klog total --tag 'issue_*' coding.klg

This is not strictly necessary, because instead of tagging with #issue_123 you could also tag with #issue #123, but the semantics of the latter is still slightly different. Having wildcard fiters would effectively promote the use-case of hierarchical tags for those who want that.

This idea originated in #55.

The widget appears to read and evaluate the open-ended range from the bookmarked file once after it’s started, but then it doesn’t update itself anymore. All other data changes are properly reflected, but not the ongoing counter.

(Technical note: this is a recent regression, due to switching from gotime.Now() to ctx.Now())

This is more of a question than a suggestion.

At my workplace I need to keep track of two things:

• the time period I am at the workplace (when I get there, and when I leave)
• the time I spend with specific projects

Usually, I do a multitude of things for my department. But sometimes I get assigned to a project where we bill for the time we spent on that project.

What I want to do is to write down an entry when I get to work and when I leave. Then I'd like to make an entry for the time spend with the project, which would be a "part" of that time. At the end of the month I'd like to summarize the total of hours spent with that project.

The only way I think I could do this as of right now would be:

2021-03-26
  08:00 - 17:00
  -1h lunch
  4h20m #foo
  -4h20m

This will give that I worked 8 hours that day, and when I summarize #foo, it would give 4h20m. Is there an best practice to do what I want?

(If this was to be some additional feature to the language, I have no idea how that would work.)