Current Format

As of v0.1.1, augr uses a simple format for storing timesheets and syncing data over syncthing.

• Each device reads and writes to a their own file <device-id>.unknown
  • Each line contains an event, with a rfc3339 datetime and a set of space separated tags
• All of the other files are read from, but not written to

This simple format allows data to be shared and synced without conflicts arising. However, this format cannot model the following:

• Deletion of an event made by a different device
• Modification of an event made by a different device

To be a useful tool, augr must allow corrections to be made to the data.

Format requirements

A new format should support the following:

• create, editing, and deleting events
• synchronising data over syncthing without creating conflicts

Format proposal

The new format is based off of the git and pijul distributed version control systems. Each device will have a central meta/ file that they read and write to. All devices will share an append only patches/ folder.

sync-folder/
	meta/
		laptop.toml
		phone.toml
	patches/
		1220caf81688dd83f19a04d53b02f86032ac242f73ec803cb51c3b30772705b501c9.toml
		12208cd07f3a5ff98f2a78cfc366c13fb123eb8d29c1ca37c79df190425d5b9e424d.toml

Each meta file contains a list of patches that it knows about, meaning that it either created the patch, or it has discovered the patch through another device's meta file.

# meta/<device-id>.toml

# The set of patches that this device knows about
root_patches = [
	"1220caf81688dd83f19a04d53b02f86032ac242f73ec803cb51c3b30772705b501c9",
	"12208cd07f3a5ff98f2a78cfc366c13fb123eb8d29c1ca37c79df190425d5b9e424d",
]

Each patch file lists the patches that it depends on and the changes to make to the timesheet.

# patches/<patch-hash>.toml

# The patches must be applied before this patch. Can be omitted entirely if the
# patch does not depend on any others.
parents = ["12208cd07f3a5ff98f2a78cfc366c13fb123eb8d29c1ca37c79df190425d5b9e424d"]

# An action, like creating, modifying, or deleting an event
[actions.1220449f475c66559505770e97bf6346199b93cb25d0b63e70ab9d0edeeae42a1854]
type = "create_event"
start = 2019-07-20T15:08:35.753524795+00:00
tags = ["augr", "coding"]

[actions.1220dec4786b6a6a805af212141b3d6bc2a6774cb5bf1eee9c00f7e263d8d8061904]
type = "add_tags"
modifying = ["1220ac27e0f2db749eefe8fc555e08aa619a04d3abdb2ff18e9b8bf1dd9293b1e819"]
tags = ["exercise"]

Actions and patches are named by their hash. The hash will be a multihash, and will default to a sha-2 256bit hash.

That's the basics of the idea. Implementing it will require a lot of the specifics to be ironed out, and I'm not sure that this is the best format to use.

Something that should also be noted is that I haven't verified that the model will make everything sync nicely. Depending on how actions are modeled, a user could end up with a lot of sync conflicts, or very few. Actions must be carefully defined so that conflicts are few, and merging is unsurprising.

Output hours tracked each day and total hours tracked, similar to timewarriors charts.

When reviewing data and editing it , the user has to copy a UUID:

$ augr summary --refs coding
Date  Start Duration Total     Tags
――――― ――――― ―――――――― ――――――――  ――――――――
09/21 09:03 7m       7m       augr coding 2ad152fa-966f-41b7-a11e-182784bd8659
      09:10 35m      43m      augr coding feature-short-ref 45037ac0-8826-4b76-8c71-aefeb01c3a7f
$ augr tag 2ad152fa-966f-41b7-a11e-182784bd8659 thinking
b314a4ed-03d7-4177-8b07-64db988f87e2
$ augr summary --refs coding
Date  Start Duration Total     Tags
――――― ――――― ―――――――― ――――――――  ――――――――
09/21 09:03 7m       7m       augr coding thinking 2ad152fa-966f-41b7-a11e-182784bd8659
      09:10 36m      43m      augr coding feature-short-ref 45037ac0-8826-4b76-8c71-aefeb01c3a7f

This is a bit of a pain, especially on mobile devices.

Possible Solutions

Short References

Allow truncated references to refer to an event. So instead of typing 45037ac0-8826-4b76-8c71-aefeb01c3a7f, they could just type 450.

This downside of this approach is that synchronization could make the user accidentally change an event they didn't mean to, or be ambiguous about which event it is.

The upside is that the interface of augr wouldn't need much changing to facilitate this.

I created a dir, linked in ~/.config/augr/config.toml, but I get the following

An error occured: Errors synchronizing data: [IOError { source: IOError { source: Os { code: 2, kind: NotFound, message: "No such file or directory" } } }]

I tried time-tracker, but it failed with

$ target/release/time-tracker                          
An error occured: Error reading data: Unable to read file /tmp/time-tracker/laptop.unknown: Unable to read timesheet from /tmp/time-tracker/laptop.unknown: No such file or directory (os error 2)

The config file is :

sync_folder = "/tmp/time-tracker/"                                                                        
device_id = "laptop"  

In all honesty, I'm not sure when or if augr can be considered "ready", as it's mostly a hobby project of mine.

That said, here are some of the things I want to accomplish.

Platforms

I want augr to run everywhere, and sync data in the most convenient method for the user.

• Frontends
  • Command Line Interface
    • Linux
    • Android
    • Windows (does it run on windows?)
    • Mac OSX
  • Gtk App
    • Desktop
    • Librem 5
  • Web App (for browsers everywhere)
• Sync Methods
  • Syncthing
  • Personal server running an augr daemon?
  • Paid augr service for multiple users?

Features

What features are required before the augr is considered 1.0?

• Reporting
  • Flexible method of generating reports and charts
• Better editing interface
• Importing and Exporting data
  • Timewarrior
  • Toggl

Tests

What verifications should be done before the augr is considered 1.0?

• Unit tests
• Fuzz tests

Final Words

This list is incomplete and probably too ambitious for a hobby project. Expect it to be changed a lot.

Is there a way to explicitly end an event? For example, if I do augr start work, can I do a augr end work and have the software track nothing?

My current strategy is to have a tag called "freetime" that I switch to anytime I don't want to be tracking my time. However, this greatly clutters the summary.

I would be happy to implement this feature if its wanted, if not, I would suggest adding to the Guide a canonical way of handling untracked / free time, as this confused me when first reading it, which again I would be happy to do.

Right now there is some help in the README; but it's not complete and it makes the README longer than it needs to be. Moving it into a separate file (like GUIDE.md) would be preferable.

If the sync_folder specified in the config does not exist, automatically create it.