Smile Track

Smile Track is an app for auto calculating and tracking time by using your git history.

$ npm install smile-track -g

Table of Contents:

1. Goal and Philosophy
2. Quickstart
3. Features
   1. GUI
   2. CLI
   3. Google Calendar
4. Requirements
   1. Task pattern
   2. Custom task pattern
5. Update
6. Test
7. Build
8. Uninstall
9. Feedback
10. Credits

Goal and Philosophy:

Sometimes it’s difficult to calculate the time spent on tasks due to their quantity. You should check the git history or take notes on what you have done in that day.

smile-track is designed to help you calculate that tasks time in few clicks.

You don't ever need to note or search for your task history. This app will do it for you! It requests all your git history for the selected day and returns a prettified report with time and messages for each task.

Quickstart:

This app is designed primarily for developers. But if you have access to git repository, you can get the report.

1. Install Node.js
2. Install the package globally:

$ npm install smile-track -g

That's it! Now you can use the app in any git folder. But before use it in a project folder, you should config the app:

1. Run the app in your project root:

   $ smile-track

2. When you start this app for the first time in your project folder, you should configure it (e.g.):

   Welcome to the Smile Track!
   Let's make some initial setting:
      
   ? Select your git author name: Dmytro Vakulenko
   ? Select time when you start work: 9:00
   ? Select time when you go dinner: 13:00 - 14:00

3. Select a day that you want to track:

   --- Tracktime ---
   > 2020-04-02 (yesterday, THU, no commits)
     2020-04-01 (WED, no commits)
     2020-03-31 (TUE, no commits)
     2020-03-30 (MON, no commits)
     Other days
   (Move up and down to reveal more choices)

Features:

• [x] Available via npm for the easiest install;
• [x] GUI, for configurate and see easily interact with the app;
• [x] CLI, for use it in console. If you want to use it like API or you know specific day for track, you can use build-in commands for that;
• [x] The Website - https://smile-track.web.app - for convenient displaying of daily tasks, track the progress;

The Website has its own features:

• [x] Integration with Google Calendar. Now all your events won't be missed and will be added to the tracking page.
• [x] Integration with Jira to automatically track all progress, find out the estimated time and how much is left.

GUI:

The GUI is smart enough to collect almost all the necessary data for configuration by using git config and git log. This simplifies your first setup, therefore, you do not need to find out what settings are responsible for.

It can guess your:

• Username

? Select your git author name: (Use arrow keys)
> Dmytro Vakulenko
  Serhii Tsivinskyi
  ThivinskiySergey
  Vladimir Suslov
  Viacheslav Polubotko
  Serhii
  dmytro.vakulenko
(Move up and down to reveal more choices)

• Time when you start working

? Select your git author name: Dmytro Vakulenko
? Select time when you start work: (Use arrow keys)
  7:00
  8:00
> 9:00
  10:00
  11:00
  12:00
  13:00
(Move up and down to reveal more choices)

• Dinner time

? Select time when you go dinner: (Use arrow keys)
  12:00 - 13:00
  12:30 - 13:30
> 13:00 - 14:00
  13:30 - 14:30
  14:00 - 15:00
  Manual Enter

To open the GUI interface, simply run the following command in a terminal:

$ smile-track

CLI:

The CLI supports track [date] command where date is date in format YEAR-MM-DD. Also, there are available alias such as today, yesterday, and last (last untracked day). All commands have shortcuts.

Example:

$ smile-track track 2020-4-30
$ smile-track track 2020-4-3
$ smile-track track last
$ smile-track t l

Displaying help for the CLIs track command:

$ smile-track track --help

Usage: smile-track track|t [options] [date]

track time for specific day.
Also, you can use aliases:
* today (t),
* yesterday (y),
* last (l) (for the last untracked day)

Options:
  -h, --help                        output usage information

Google Calendar:

The Website supports integration with your Google Calendar. It will request all confirmed events that belong to you and display how much time you spent on them.

Confirmed events:

Your event is confirmed when you approve going on this event and click Yes. From this time, this event has been marked as active in your calendar and the app will include it to the final report.

Declined or unchecked events:

Your event is declined when you decline going or it's unchecked if you did nothing. From this time, this event has been marked as pending and the app will ignore it.

Requirements:

Task pattern:

To use this application, you should name your commits with the task number. This helps to analyze what task you were working on.

Smile Track supports two popular task patterns:

1. Jira Smart Commits:

ST-13 updated the package version
ST-13 marking dayoffs as blue
ST-13 displaying days of week

2. Semantic Commits.

refactoring(ST-13): updated the package version
feat(ST-13): marking dayoffs as blue
feat(ST-13): displaying days of week

Let's look to example of commit messages:

Bad, won't work at all, poor git history:

2020-04-03 20:37:06 +0300 ==== updated the package version
2020-04-03 20:15:18 +0300 ==== marking dayoffs as blue
2020-04-03 20:09:27 +0300 ==== displaying days of week
2020-04-03 19:09:19 +0300 ==== added the 0.9.2 build
2020-04-03 19:09:08 +0300 ==== allow to input dates with shortcutted month and day

Best, the cleanest git history and navigation:

2020-04-03 20:37:06 +0300 ==== ST-13 updated the package version
2020-04-03 20:15:18 +0300 ==== ST-13 marking dayoffs as blue
2020-04-03 20:09:27 +0300 ==== ST-13 displaying days of week
2020-04-03 19:09:19 +0300 ==== ST-12 added the 0.9.2 build
2020-04-03 19:09:08 +0300 ==== ST-12 allow to input dates with shortcutted month and day

Acceptable, but looks bad in git history:

2020-04-03 20:37:06 +0300 ==== updated the package version ST-13
2020-04-03 20:15:18 +0300 ==== ST-13 marking dayoffs as blue
2020-04-03 20:09:27 +0300 ==== displaying days of week ST-13
2020-04-03 19:09:19 +0300 ==== added the 0.9.2 ST-12 build
2020-04-03 19:09:08 +0300 ==== allow to input dates with shortcutted month and day ST-12

You should use the best pattern for your commits (mentioned earlier 👆).

Why? It will help you in the future, if you want to find commits for a specific task, and it gives many other advantages. Read about references in commit messages.

What can I do if I'm currently using a different pattern?

You can use custom task pattern.

Custom task pattern:

If you have a custom task pattern, e.g.:

2020-04-03 20:37:06 +0300 ==== __(ST-13)__ updated the package version
2020-04-03 20:15:18 +0300 ==== __(ST-13)__ marking dayoffs as blue
2020-04-03 20:09:27 +0300 ==== __(ST-13)__ displaying days of week
2020-04-03 19:09:19 +0300 ==== added the 0.9.2 build __(ST-12)__
2020-04-03 19:09:08 +0300 ==== allow to input dates with __(ST-12)__ shortcutted month and day

You can add this pattern into Smile Track. You need to navigate to settings (available on the main screen) and go thought setting to find the custom pattern:

Welcome back to the Smile Track!
? Select the action: Update config
? Select your git author name: Dmytro Vakulenko
? Select time when you start work: 9:00
? Select time when you go dinner: 13:00 - 14:00
? Do you want to add the directory for tracks in .gitignore? Yes

? Which commit pattern type do you use for the project? Custom Commits Pattern
? Enter a valid regexp (e.g. __\(${pattern}\)__ equals __(ST-75)__): __\(${pattern}\)__

You could see that regexp contains ${pattern}. This is shortcut of real ticket regexp ([a-zA-Z]+-\d+) so you don't need to input in manually. But if you want, you can input any ticket pattern, e.g. @\(ST-\d+\)@ (this pattern match only @(ST-9999)@ tickets).

Note, that you need to input a valid regexp. Otherwise, Smile Track won't parse your tickets. You can test your regexp on regex101.com.

This setting has validation for ticket pattern and realtime ticket generation. If you input invalid ticket pattern, the app will notify you about it.

Valid pattern:

? Enter a valid regexp (e.g. __\(${pattern}\)__ equals __(ST-75)__): @_${pattern}_@
>> Confirm your pattern. (press Enter)
Generated tickets from pattern: @_W-675_@, @_kv-59_@, @_t-71_@

Not unique pattern:

? Enter a valid regexp (e.g. __\(${pattern}\)__ equals __(ST-75)__): _ST-75_
>> Your pattern is not unique. Please, try another pattern
Generated tickets from pattern: _ST-75_

Invalid pattern:

? Enter a valid regexp (e.g. __\(${pattern}\)__ equals __(ST-75)__): __\d+__
>> Your pattern must includes ${pattern} or match the ticket pattern: [a-zA-Z]+-\d+
Generated tickets from pattern: __02__, __9__, __70__

Invalid regexp:

? Enter a valid regexp (e.g. __\(${pattern}\)__ equals __(ST-75)__): \(ST-\d+)
>> SyntaxError: Invalid regular expression: /\(ST-\d+)/: Unmatched ) at column 8

Update:

If you want to update the app, just install the package again:

$ npm i smile-track -g

You can check current version by running:

$ smile-track -v
0.17.0

Test:

Tests are provided by Jest, so if you want to test the app, just run:

$ npm test

Build:

You can build your own bundle by using the build command:

$ npm run build

Also, you can pack and install your own package by running:

$ npm pack
$ npm install ./smile-track-0.17.0.tgz -g

Feedback:

If you want to leave a feedback to me, suggest a feature, or just ask something you can write me to Workplace.

Credits:

Created with ❤ by Dmytro Vakulenko, 2021.