~andrewzah/faramir

CLI time tracking utility. Mirror of https://git.andrewzah.com/andrewzah/faramir
Add --keep option for start, add util fns
Add note field to timer struct
run +nightly fmt

refs

master
browse  log 

clone

read-only
https://git.sr.ht/~andrewzah/faramir
read/write
git@git.sr.ht:~andrewzah/faramir

You can also use your local clone with git send-email.

#Faramir

Faramir gif

Faramir is a time tracking cli tool written in Rust, inspired by Watson.

Currently in alpha, so changes will occur.

All times are stored in UTC.

#Usage

See commands below for more detailed information.

% faramir start demo_project -t tag1,tag2 -n "my custom note text"

Successfully started timer b0PQh7q1eqKc for project demo_project.

% faramir status

1 timer(s) found.
  Timer for project demo_project - with id b0PQh7q1eqKc
  Elapsed Time: 0w, 0d, 0h, 0m, 24s
  Start Time: 2020/01/05 21:32:10

% faramir stop
# or: faramir stop -i b0PQh7q1eqKc
Stopped timer b0PQh7q1eqKc.

% faramir ls projects
# or: faramir ls p
1 Project(s) found.
demo_project

% faramir ls tags
% or: faramir ls ta
2 Tag(s) found.
tags: tag1, tag2

% faramir edit b0PQh7q1eqKc
# this opens a tmp json file with $EDITOR to edit

% faramir log
# all times are stored as UTC. this will become prettier!
1 timer(s) retrieved.
b0PQh7q1eqKc - start: 2020-01-05 21:32:10.579684938 UTC, end: 2020-01-05 21:34:30.199521260 UTC

% faramir rm timer b0PQh7q1eqKc
# or faramir rm t ...
# or faramir rm p(roject) ...
Successfully deleted timer b0PQh7q1eqKc.
  start: 2020-01-05 21:32:10.579684938 UTC, end: Some(2020-01-05T21:34:30.199521260Z)

todo (soon TM): commands for detailed reporting.

#Config

By default, faramir looks for $XDG_CONFIG_HOME. If this isn't set, it puts faramir-tt/ under $HOME/.config/.

A different config location can be specified with -c.

{
  "data_dir": "/home/andrew/.config/faramir-tt",
  "time_format": "%Y/%m/%d %H:%M:%S",
  "full_time_format": "%Y/%m/%d %H:%M:%.3f, Day %j, Week %U",
  "timezone": "America/New_York"
}
  • data_dir lets you put the actual faramir data (faramir.db, etc) in a different directory.
  • time_format is used for the add command.
  • full_time_format is used when the -d / --detailed flag is passed for some commands.
  • timezone is a standard timezone. Find yours here.

#Model

A Timer has an id, an rid (random id), a start (datetime<utc>) and end (datetime<utc>).

Projects and Tags have an id and a name.

Every Timer has a Project. Projects have many Timers.

A Timer can have multiple Tags. Tags have many Timers.

Associations are made through join tables, i.e. projects_timers and tags_timers.

#Commands

#add

Manually adds a timer. The format -s and -e use depends on your config's time_format parameter, but it still has to compile to a DateTime. So %Y.%m.%d %H:%M:%S works but %Y/%m/%d doesn't.

faramir add project1 -s "2020/01/04 21:50:00" -e "2020/01/04 21:51:00" -c
  • -s / --start
  • -e / --end
  • -t / --tags
  • -d / --duration => not implemented yet.

#completions

Generates autocompletions for your shell. The output is in your config's data_dir directory.

faramir completions zsh

Possible values: bash, fish, zsh, powershell, elvish

#edit

Edits a timer. Do not edit id or rid, because that'll cause issues in the database.

faramir edit ZFhSTQgU3GtH

You can see a timer's id whenever you create a timer, or run faramir log / faramir status, etc.

The $EDITOR environment variable must be set.

#log

By default, retrieves a log of completed timers (that is, it doesn't include running timers).

% faramir log

3 timer(s) retrieved.
ZFhSTQgU3GtH - start: 2020-01-05 01:27:37.232082717 UTC, end: 2020-01-05 01:28:51.125580395 UTC
PZjIHmdC057W - start: 2020-01-05 02:50:00 UTC, end: 2020-01-05 02:51:00 UTC
3NsfWDtif6Sy - start: 2020-01-05 03:04:20.493443573 UTC, end: 2020-01-05 03:04:30.061320880 UTC
  • -l / --limit => 10 by default.

TODO: Add other qualifiers like date range, etc

#ls

List Projects or Tags.

% faramir ls projects

3 Project(s) found.
proj1, proj2, proj3
% faramir ls tags

3 Project(s) found.
tag1, tag2, tag3

#rename

Rename a Project or Tag.

% faramir rename p proj1 proj4

Successfully renamed project proj1 to proj4.

You can use p, project, or projects for the Project type. You can use t, tag, or tags for the Tag type.

#rm

Deletes a project, tag, or timer, and associated records.

faramir rm <type> <name/id>
% faramir rm p proj1

Project proj1 has 4 timers associated with it. Are you sure you want to remove it?
If so, type 'y'.
y

Successfully removed project proj1.
  • -y / --yes => Automatically deletes all related records. Dangerous!

#start

Starts a timer at the current time, UTC.

This automatically creates the passed in project and tags. Tags are optional.

% faramir start proj5 -t tag3,tag4 -n "my note text here"

Successfully started timer Ga4SXq8XuZi1 for project proj5.

% faramir start -k
  • -k / --keep => Use the same project and tags as last time.

#status

Displays the status of any running timers.

TODO: make this prettier.

% faramir status

1 timer(s) found.
timer for project proj5, with id Ga4SXq8XuZi1
  Elapsed Time: 0w, 0d, 0h, 1m, 23s
  Start Time: 2020/01/05 03:38:48
  • -d / --detailed => TODO: Show more detailed information like tags, etc.

#stop

Stops the timer if only 1 is running. Otherwise, use -i / --id to specify which timer.

% faramir stop

Stopped timer Ga4SXq8XuZi1.
  • -i / --id => Specify a timer manually if multiple are running.

There a few more planned commands.

#License

GPLv3