maximiliansoerenpollak / zeit

Zeit, erfassen. A command line tool for tracking time spent on activities.

Info

This is a fork of the 'zeit' repo which can be found here

Much thanks to Mrusme for his work and for making it available to the public.
I have decided to fork it as I wanted to have some additions and be able to use this accorss different PC's.
Sadly my setup even with changes did not work with the requiered '.editorconfig',so I couldn't contribute upstream.

The original repo also has some extras inside that might be interesting to some people.

Jump to the original project

---

---

Table of contents:

• What?
• Changes to know
• How to build/install
• Usage
• Issues

What is this?

This project is a cli that allows you to track how much time you spend on a given task on a given project. You can export the statistics to a CSV, display them in the Terminal via a nice statistics screen, or just list them out.

Changes to know

I just realeased the v0.2.0, you can head over there to read about the changes too. Read the release

Here are some changes I have made to my fork, that you should be aware of if you use this one.

V0.2.0 Changes

• Change to SQLITE3 Database
• Able to import 'zeit' or 'csv' outputs
• Remove 'tyme' completely (from import & export)
• Removed some commands to streamline the Process
• Added 'colors' to the 'stats' page
• Changed README to include examples and new screenshots
• Removed Git/hub linking feature
• Made the 'decimal' flag the default everywhere

V0.1.0 Changes

• Removed 'extras' as I had no need for them
• Changed Go Version to 1.22.3 (to make use of new Bugfixes etc.)
• Implemented standard 'GoFmt' formatting
• Changed 'default' arguments for exporting and added options to it.

Building

You can build the project by using the 'makefile' or by just using go itself.

make VERSION=0.2.0 # to make the newest version.

or via go

go build zeit.go  #This however makes it so the 'version' command is not set 

After you just have to move the zeit binary to into your 'PATH' in order to just use it as zeit from anywhere.
You can accomplish this by moving the binary to /bin/.
If you rather would just the user have execute this binary you can also make a bin folder in your home directory and add the zeit binary in there and add the folder to path with adding this to the .bashrc or your shells config file
export PATH="$PATH:/usr/local/bin"

Usage

Lines that start with # inside the commands show you what the output looks like.

Basic Time tracking

Start tracking:

zeit track --task "Working on Issue 3" --project "WorkProject" 
#Started tracking --> Task: Working on Issue 3 on Project: WorkProject 

Finish tracking:

zeit finish
# ■ finished tracking Woorking on Issue 3 on WorkProject for 2,07h

You can also add 'notes' to the task with --notes right when you start tracking it. But, you can also add notes later like this:

zeit entry --notes "Estimate time: 5h" 1
# ● 1
#   Working on Issue 3 on WorkProject
#   2,07h from 2024-08-22 20:44 to 2024-08-22 22:51 
#
#   Notes:
#   Estimate time: 5h

Note: The 1 at the end is the 'id' of the entry. You can find this by doing zeit list. The ID is the number before the entry you wish to change.
Example of zeit list output.

Show all the entries

You can show all entries via list, find out about all flags via zeit list --help

zeit list 
#1 Working on Issue 3 on WorkProject from 2024-08-22 20:44 to 2024-08-22 23:30 (4.77h)
#2 Working on Feature C on WorkProject 2 from 2024-08-23 14:00 to 2024-08-23 20:52 (6.87h)
#3 Test on Test from 2024-08-24 11:00 to 2024-08-24 17:26 (4.45h)
#4 Long ago task on OldProject from 2024-07-01 10:00 to 2024-07-01 13:00 (3.00h)

But you can also just let it show the relations between tasks and projects via --only-projects-and-tasks

zeit list --only-projects-and-tasks
# ◆ OldProject
# └── Long ago task
# ◆ WorkProject
# └── Working on Issue 3
# ◆ WorkProject 2
# └── Working on Feature C
# ◆ Test
# └── Test

Look at Stats

Zeit allows you to display your stats as well, right in your terminal. It colors the projects in 4 rotating colors, to make it easier to disginguish (if your terminal supports colours).
Zeit will always display the last two weeks (in the calendar view up top), but will list all entry if you have not given it any filters

zeit stats

6.87h => 6 hours and 87% of another hour. So (87% of 60 ==> 52min).

With the --decimal=false flag you can change the decimal behaviour.

zeit stats --decimal=false 

6.52h => 6 hours and 52 Minutes

Export to CSV

I have added the option to allow zeit to also export to 'csv'. Currently it will use ; as a seperator. If you do not specify a --file-name zeit will use zeit-export-{yyyy-mm-dd}.csv as the default file name.

$ zeit export --format "csv" 
# ● No file-name provided. Using 'zeit-output-2024-08-24.csv' as default.
# ■ export finished.

If you want to export it, for later import (on a different machine or so) make sure to use the --export-all-fields flag.

The --export-all-fields flag, adds the 'Begin, Finish & Notes' fields to the csv export. For now this only works with the '--format "csv"' and not with 'zeit'. As the zeit format exports all fields by default.

Change an entry

In zeit it's possible to change entries. This can be done via the entry command. For example, let's change the end time for one of our entries.

zeit entry --finish "2024-08-22 23:30" 1
# ● 1
#   Working on Issue 3 on WorkProject
#   4.77h from 2024-08-22 20:44 to 2024-08-22 23:30
#
#   Notes:
#   Estimate time: 5h

We can obviously change anything about the project, --task, --being, --notes, --task, --project, --finish
Find out more via the --help command.

Issues

If you find issues or bugs, by all means please open an issue with a description and I will take a look at it as soon as I can.

zeit's Issues

[DEVELOPMENT | Backlog] Improve UI by implementing BubbleTea

The UI currently is just a pure CLI, which isn't bad. It works very well and if you know what you are doing it's great.

But maybe a BubbleTea UI would be nice, to make it a bit nicer on the eyes.

'This however is an issue to tackle once the other things are solved.

[DEVELOPEMNT] Write Tests for some functionality

Since I want to re-work some of the core functionality I think it would be good to write tests so I can be sure that it works the same afterwards.

Probably should be this or maybe a bit less:

• Testing adding task
• Testing deleting task
• Testing DB insert / read etc.
• Testing filtering & export (via golden file maybe?)

[FEATURE] Add 'export to csv' option

Currently have a workflow that exports everything to JSON then transforming that with JQ and 'csv2xlsx' to an excel file.

Would be nice if at least the JQ step could be skipped, potentially also the excel file convertion.

This is something for the future.

Wanted:

zeit export --csv -> exporting it as 'csv' with , as seperator or a configured seperator with the --sep flag.

[IMPROVEMENT] Change DB to a sqlite3 DB.

The current DB setup works quite well and is actually not bad, as it's also a single file etc.

I would like it to be changed to a sqlite3 DB as then it makes other extensions easier etc.

[BUG] If you create a task and then change it's date the 'date' will not change

[FEATURE] Add a way to group by date or time period to list/export etc.

In many of the now available functions one of the things I currently find lacking.
We have not yet any way to 'group' the tasks together via date or time period.

For example if I have 3 tracked taskes like so:

1a4e7d54-e5a2-4870-8611-1a7609e08a44 TestTask1 on TestProject from 2024-07-23 09:36 +0200 to 2024-07-23 10:37 +0200 (1:00h) 
1a4e7d54-e5a2-4870-8611-1a7609e08a44 TestTask2 on TestProject from 2024-07-23 13:36 +0200 to 2024-07-23 18:37 +0200 (5:00h) 
1a4e7d54-e5a2-4870-8611-1a7609e08a44 TestTask3 on TestProject from 2024-07-28 10:36 +0200 to 2024-07-28 12:00 +0200 (1:24h) 

It would be nice to have it be able via a flag for example to condence the output to this.

TestTask1, TestTask2 on TestProject on 2024-07-23 for a total of 6h

Something along those lines, not yet sure what the things should exactly but the idea is there.

[DEVELOPMENT] Add a way to import CSV / old 'zeit' DATA into the new sqlite3 way

Since this is a completely new way of storing etc. it would be nice if people that used the 'CSV' way or the old 'zeit' system can just import their already recorded tasks into this new way.

[BUG] If task is changed sometimes it doesn't calculate the 'hours' newly.