Giter VIP home page Giter VIP logo

ttrack's Introduction

ttrack

Go Report Card Coverage Status

A minimal CLI based app that automates keeping track of you actually do things on a daily basis.

Ttrack is built with these things in mind:

  • Daemonless. Time tracking apps don't need to run in the background.
  • Efficient. Ttrack usually writes to a single file cache to keep execution time minimal.
  • Readable. Time tracked information is ultimately stored as human readable text files that play nice with version control.
  • Unix Philosophy. Ttrack's scope is very limited, relying on other programs to take care of non time tracking tasks.
  • Relatable. Ttrack is meant for people who want to set timed goals or view their trends on a daily basis according to their own timezone. Time is measured in hours/minutes/seconds, because most people don't operate at millisecond or nanosecond levels.

Install

Download the latest release from the release page. At the moment, only Linux and Mac are supported.

If you have golang, you can install the latest updates from source. Keep in mind that the main branch is not guaranteed to be stable.

go install github.com/alanxoc3/ttrack

Usage

Some time tracking utilities require you to manually start your time before you begin a task and end your time after you finish. This is unfortunately error prone. You could forget to start or stop the timer. Or maybe you get distracted or take a break while working on a task.

Ttrack instead works by inserting records and specifying a timeout with your record. If ttrack is called again before the duration of the timeout has been reached, then the time is extended. Otherwise, the time is added to your daily total in a human readable text file.

A common use case of ttrack is to call it from the event system of another program. For example, if you want to keep track of how much time you edit files, you could call ttrack's record command on your editor's key press event:

ttrack rec text-editor 5s

Ttrack records 5 seconds into the "text-editor" group. If the rec command is called again within 5 seconds, the time is extended. If not, only 5 seconds will end up getting added to the group.

If you want to see how much time you have used your text editor, use ttrack's aggregate command:

ttrack agg text-editor

Other commands help manage groups, clean the cache, and edit/create entries for other days. Run ttrack help to learn more.

Integrations

Since ttrack is CLI based, it fits nicely into hooks that support shell calls. Here are some snippets that demonstrate how to make ttrack integrate with other applications. If you have another snippet, feel free to open a pull request with your addition.

Tmux

Tmux is a popular terminal multiplexer. Add this to your tmux.conf:

set -g bell-action none
set -g visual-bell off
set -g monitor-activity on
set -g activity-action current
set-hook -g alert-activity "run-shell 'ttrack rec tmux 5s'"

Kakoune

Kakoune is CLI based text editor. Add this to your kakrc or autoload directory:

hook global -group ttrack RawKey . %{
  evaluate-commands %sh{
    {
      [[ $(basename $kak_bufname) =~ '.' ]] && ttrack_name="ext:${kak_bufname##*.}" || ttrack_name="misc"
      [ ! -z "$(command -v ttrack)" ] && ttrack rec "kak/$ttrack_name" 3s
    } > /dev/null 2>&1 < /dev/null &
  }
}

hook global BufCreate .+\.tt %{
    remove-hooks global ttrack
}

Concards

Concards is a CLI based flashcard program. Add this to your event-startup and event-review hooks:

#!/bin/bash
ttrack rec concards 30s

Mpv

Mpv is a CLI based media player. Add this to a ~/.config/mpv/scripts/ttrack.lua file:

mp.add_periodic_timer(1, function()
    os.execute("ttrack rec mpv 3s")
end)

Comparison With Similar Apps

Here are some other time tracking applications and how ttrack relates to them:

  • Watson: Records time by starting and stopping instead of continually updating.
  • Gtm: Similar to watson, but meant for working in git.
  • ActivityWatch: Heavier & more complex, but supports more features and granularity.
  • WakaTime: Plugin oriented instead of cli based.
  • SelfSpy: A daemon that records keystrokes and is X11 specific.

Dependencies

Ttrack has very few dependencies outside of go's standard library. Here are all the direct dependencies:

Internal Details

Folder Structure

Ttrack uses one directory for data and one directory for a cache, following the XDG standard.

The data directory is calculated by the following order until one succeeds:

  1. $TTRACK_DATA_DIR
  2. $XDG_DATA_HOME/ttrack
  3. $HOME/.local/share/ttrack
  4. ./

The cache directory is calculated by the following order until one succeeds:

  1. $TTRACK_CACHE_DIR
  2. $XDG_CACHE_HOME/ttrack
  3. $HOME/.cache/ttrack
  4. ./

Data Directory

Within the data directory, files ending in .tt are read from and written to. Files not ending in .tt are ignored. These data files have a very simple format that looks like this:

2021-01-01: 10m33s
2021-01-02: 1h2m3s
2021-01-06: 3h59m49s
2021-02-15: 30s

Because groups are stored as files, there are some restrictions as to what a group can be named. Invalid names will automatically be parsed to be valid. Here are the restrictions:

  • Groups cannot end with .tt.
  • Groups cannot start with a ..
  • Groups cannot contain any whitespace as specified by golang's unicode package.
  • Groups cannot contain the / character. This is used to separate groups into a folder structure.

Cache Directory

Within the cache directory, only one file named db is read from and written to. This file is a BoltDB database file. Live time ttracking information is stored here to reduce the amount of writes to files in the data directory. The basic format of this database file is:

"<group-name>": {
  "out": 1m00s
  "beg": 2021-01-01T07:34:59Z
  "end": 2021-01-01T07:34:59Z
}

ttrack's People

Contributors

alanxoc3 avatar

Stargazers

 avatar  avatar

Watchers

 avatar  avatar

ttrack's Issues

Think about groups.

How should they be parsed? Which characters are allowed? Group structure with colons? Use files instead of boltdb?

I also want to think about adding regex to group names.

v0.2.0 release

v0.2.0 will include:

  • ttrack help command.
  • ttrack version command.
  • ttrack groups command.
  • ttrack rec command.
  • ttrack set command.
  • ttrack del command.
  • ttrack cp command.
  • ttrack list command.
  • ttrack agg command.
  • CI build, release hook, merge coverage and build checks. #1
  • Presentable documentation in README. #7
  • 80% test coverage. #10

Ponder 0s timeout

It might be useful to have a way to stop a recording and flush the cache for it.

One option is ttrack rec 0s. Right now, that acts like reset, which isn't very useful as there is already a ttrack reset command. Another option might be to add a new command. I'll need to think about this a bit more.

sub command should work on cache

The sub command should work on the cache. I ran into a scenario where I wanted this and it wasn't working. My idea is for the sub command to first operate on the file, then take whatever is left and look at the cache.

v0.3.0 release

v0.3.0 will include:

  • Group refactor. #6
  • Shell completion for groups. #9
  • ttrack timer command. #5

Improve readme.

I need something presentable, so I feel comfortable sharing it.

Fix xdg dir lookup strategy

Ttrack doesn't save to the correct directory if relying on XDG_DATA_DIR & XDG_CONFIG_DIR. This needs to be fixed.

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.