tomfa / git-csv-timesheet

Generate CSV timesheet from your git repositories

git-csv-timesheet

Logging hours? No thanks. Let git-csv-timesheet estimate time spent and print out a csv.

Install

yarn global add git-csv-timesheet

# or with npm

npm install -g git-csv-timesheet

Basic usage

$ timesheet --authors [email protected] --since thismonth
date;hours
2020-07-01;7.5
2020-07-02;8
2020-07-03;10

$ timesheet  \
  --authors [email protected] \
  --since thismonth \
  --repositories /usr/repos/frontend,/usr/repos/backend
date;hours
2020-07-03;/usr/repos/frontend;1.4
2020-07-05;/usr/repos/backend;1.7
2020-07-06;/usr/repos/backend;2.7
2020-07-09;/usr/repos/frontend;1.2
2020-07-13;/usr/repos/frontend;3.2
2020-07-16;/usr/repos/frontend;2.4
2020-07-16;/usr/repos/backend;3.9
2020-07-27;/usr/repos/frontend;2.0
2020-07-28;/usr/repos/frontend;4.1

# Write to file
$ timesheet > report.csv

git-csv-timesheet will by default print out time spent this month in the current repository.

• For more advanced use, see Advanced usage.
• To override month, print for a week, year or specified date range, see time range options.
• To gather data from multiple repositories at once, see timesheetrc config.
• To gather data on individual tasks, see task tracking.

git-csv-timesheet guesses the time spent on individual repositories based on timestamps of git commits. Read more about how it works and configuring assumptions.

The generated output might not be accurate enough to use for billing.

How it works

The algorithm for estimating hours is quite simple. For each author in the commit history, do the following:

Go through all commits and compare the difference between them in time.

If the difference is smaller or equal then a given threshold, group the commits to a same coding session.

If the difference is bigger than a given threshold, the coding session is finished.

To compensate the first commit whose work is unknown, we add extra hours to the coding session.

Continue until we have determined all coding sessions and sum the hours made by individual authors.

The algorithm comes from @kimmobrunfeldt/git-hours and is about 30 lines of code.

Options

Advanced usage

Usage: timesheet [options]

Options:
  -V, --version                         output the version number
  -a, --authors [[email protected]]       Only care about commits from these
                                        emails.
  -d, --max-commit-diff [minutes]       max minutes between commits counted as
                                        one session.
                                        [default: 180]
  -f, --first-commit-add [minutes]      how many minutes first commit of
                                        session should add to total.
                                        [default: 60]
  -s, --since [date]                    Analyze data since date (including).
                                        [today|lastweek|thismonth|yyyy-mm-dd]
                                        [default: always]
  -u, --until [date]                    Analyze data until date (excluding).
                                        [today|lastweek|thismonth|yyyy-mm-dd]
                                        [default: always]
  -r, --repositories [path,other-path]  Git repositories to analyze.
                                        [default: .]
  -e, --email [emailOther=emailMain]    Group person by email.
  -m, --merge-request [false|true]      Include merge requests into
                                        calculation.
                                        [default: true]
  -i, --ignore-timesheetrc              Ignores .timesheetrc from home
                                        directory.
                                        [default: false]
  -j, --json                            Reports in JSON format.
                                        [default: false]
  -v --verbose                          Prints extra stats
                                        [default: false]
  -D --debug                            Prints debug information
                                        [default: false]
  -h, --help                            display help for command

  Examples:

  - Estimate hours of project

   $ timesheet

  - Estimate hours by [email protected]

   $ timesheet -a [email protected]

  - Estimate hours where developers commit seldom

   $ timesheet --max-commit-diff 240

  - Estimate hours in when working 5 hours before first commit of day

   $ timesheet --first-commit-add 300

  - Estimate hours work this month

   $ timesheet --since thismonth

  - Estimate hours work until 2020-01-01

   $ timesheet --until 2020-01-01

Config

.timesheetrc config

By default, the repository parameter will check the current git repository. You can also summarize multiple repositories by adding a config file to your home folder.

The config has the following structure:

{
  "repositories": [
    { "project": "Personal blog", "path": "/Users/tomfa/repos/notes" },
    { "project": "Personal blog", "path": "/Users/tomfa/repos/notes-backend" },
    "/Users/tomfa/repos/random-project",
    {
      "project": "Client 1",
      "path": "/Users/tomfa/repos/app",
      "trackTasks": true
    },
    {
      "project": "Client 1",
      "path": "/Users/tomfa/repos/backend",
      "trackTasks": true,
      "countMerges": false
    }
  ],
  "maxCommitDiffInMinutes": 120,
  "firstCommitAdditionInMinutes": 60,
  "countMerges": true,
  "authors": ["[email protected]"],
  "emailAliases": {
    "[email protected]": "[email protected]",
    "[email protected]": "[email protected]"
  }
}

The config above will:

• track commits by author "[email protected]"
• count commits made by "[email protected]" and "[email protected]" towards the author "[email protected]"
• add 60 minutes before first commits (for a day)
• "glue together" commits that are less than 2 hours between.
• count merges as your commit (TODO: #16)except for /Users/tomfa/repos/backend, where it's overriden)
• TODO: #17 count 1 repo for a "Unspecified" project (/Users/tomfa/repos/random-project)
• TODO: #17 count 2 repos each for the two projects Client 1" and Personal blog.
• TODO: #16 #10 Client 1 repos: it will split up the work into tasks specified in commits (see below.)

With the above config located at ~/.timesheetrc, the script will run from anywhere with the same output:

➜ timesheet --week
date;project;repository;hours
2020-07-27;Personal blog;@tomfa/notes;3.5
2020-07-27;Personal blog;@tomfa/notes-frontend;1
2020-07-27;Client 1;@client/dashboard;3
2020-07-28;Client 1;@client/app;8
2020-07-28;Client 1;client/backend;2
# etc

If you have a config in ~/.timesheetrc, and you do not wish to use it, pass the -i flag to ignore the config file.

Task tracking

TODO: #10 This feature is not yet implemented.

If you need to specify what you've worked on (I'm sorry), git-csv-timesheet can look for # in your commits to categorise work based on individual tasks.

> timesheet --week --config ~/.timesheetrc --tasks
date;project;repository;task;hours
2020-07-27;Personal blog;@tomfa/notes;#14;1.5
2020-07-27;Personal blog;@tomfa/notes;#13;2.5
2020-07-27;Personal blog;@tomfa/notes-frontend;#12;1
2020-07-27;Client 1;@client/dashboard;#152;2
2020-07-27;Client 1;@client/dashboard;;2
2020-07-28;Client 1;@client/app;#81;4
2020-07-28;Client 1;@client/app;#84;2
2020-07-28;Client 1;@client/app;#86;1
2020-07-28;Client 1;@client/app;;1
2020-07-28;Client 1;@client/backend;#421;2
# etc

This requires that your commits contain a task reference, with git commits ala:

Fix bug with login form

#TASK-123

The commit above would add its time to the task #TASK-123. The script includes everything after the first #, up to a space or line shift.

Commits without a task reference are added to a separate line where the task column is blank

git-csv-timesheet's Issues

Avoid manual package versioning updates

For each update, we have to package-dist.json and src/bin/args.js. Avoid that would be great

Add --since lastyear / thisyear

Would be handy (when you report yearly), to add lastyear/thisyear as time args.

# Returning whole previous year
timesheet --since lastyear --until thisyear

# Returning current year
timesheet --since thisyear

Make usage with time options work

Extract to a git-standup repo

What did I do yesterday?
This repo, but just show all commit messages you've commited.

• no need for since or until, but accept a --date parameter
  -- default to yesterday

Add prettier

Allow Repository config to override config

The docs say we can override config on repository level with a .timesheetrc.repository ala

{
  "project": "Client 1",
  "path": "/Users/tomfa/repos/backend",
  "countMerges": false
}

Can you make a --total hours switch?

Thank you for this tool, git-hours keeps giving me install errors.

Could you please consider making a --total hours switch?

In my case I just wanna know how many hours I have spent in my repository.
The problem is is that my repository has 694 commits, feew...

What I would be really glad is something like:
$ timesheet --total
200 hours

Strip common paths

I don't care about the path to the repos, really, just the repo name.

Instead of

date;repository;hours
2020-08-25;/Users/tomasfagerbekk/repos/askeladden.toolbox;2.6
2020-08-25;/Users/tomasfagerbekk/repos/digg.client.app;4.8
2020-08-26;/Users/tomasfagerbekk/repos/digg.client.app;11.2
2020-08-27;/Users/tomasfagerbekk/repos/askeladden.toolbox;0.9
2020-08-27;/Users/tomasfagerbekk/repos/digg.client.app;7.6
2020-08-28;/Users/tomasfagerbekk/repos/FoodSociety.App;1.2
2020-08-28;/Users/tomasfagerbekk/repos/Petrus.Web;1.0
2020-08-28;/Users/tomasfagerbekk/repos/digg.client.app;0.5
2020-08-29;/Users/tomasfagerbekk/repos/askeladden.toolbox;1.0
2020-08-29;/Users/tomasfagerbekk/repos/digg.client.app;1.1
2020-08-30;/Users/tomasfagerbekk/repos/askeladden.toolbox;6.8
2020-08-30;/Users/tomasfagerbekk/repos/digg.client.app;1.6

Make it

date;repository;hours
2020-08-25;askeladden.toolbox;2.6
2020-08-25;digg.client.app;4.8
2020-08-26;digg.client.app;11.2
2020-08-27;askeladden.toolbox;0.9
2020-08-27;digg.client.app;7.6
2020-08-28;FoodSociety.App;1.2
2020-08-28;Petrus.Web;1.0
2020-08-28;digg.client.app;0.5
2020-08-29;askeladden.toolbox;1.0
2020-08-29;digg.client.app;1.1
2020-08-30;askeladden.toolbox;6.8
2020-08-30;digg.client.app;1.6

• Either accomplish this by stripping the common path, or just show the folder name. (preferably the last?)
• Maybe add a flag to show absolute path with --absolute-path

Extract git-hours to library

Logic from git-hours should be callable as an imported library, not as a cli

Convert to TypeScript

Fix cli

The CLI part of this repository does not work(!)

Make basic usage work

Update old packages

Make usage with --tasks work

Upgrade packages and remove old stuff

Move travis-ci to circle-ci

• Check that prettier is run
• Check that ESLint contains no errors (or warnings?)
• Check that things compile
• Automatically release based on semantic commits?

Use isomorphic-git to spare some people from nodegit installation headaches

isomorphic-git looks quite promising & does not have installation & nodejs version comparability issues.

Support combining repo stats into a Project

The docs say we can combine several git repositories into a project using a .timesheetrc.repositories ala

[
  { "project": "Personal blog", "path": "/Users/tomfa/repos/notes" },
  { "project": "Personal blog", "path": "/Users/tomfa/repos/notes-backend" }
]

Option to show all commit messages

I would like feature where I can also add to the csv all commit messages, or export it in another file.

Add badges to README

Support .timesheetrc in git repository

A .timesheetrc located in the git repository should override any .timesheetrc in home, but be overridden by any program arguments

Make usage with config file work

Allow for different CSV output

Instead of

date;repository;hours
2020-08-25;/Users/tomasfagerbekk/repos/askeladden.toolbox;2.6
2020-08-25;/Users/tomasfagerbekk/repos/digg.client.app;4.8
2020-08-26;/Users/tomasfagerbekk/repos/digg.client.app;11.2
2020-08-27;/Users/tomasfagerbekk/repos/askeladden.toolbox;0.9
2020-08-27;/Users/tomasfagerbekk/repos/digg.client.app;7.6
2020-08-28;/Users/tomasfagerbekk/repos/FoodSociety.App;1.2
2020-08-28;/Users/tomasfagerbekk/repos/Petrus.Web;1.0
2020-08-28;/Users/tomasfagerbekk/repos/digg.client.app;0.5
2020-08-29;/Users/tomasfagerbekk/repos/askeladden.toolbox;1.0
2020-08-29;/Users/tomasfagerbekk/repos/digg.client.app;1.1
2020-08-30;/Users/tomasfagerbekk/repos/askeladden.toolbox;6.8
2020-08-30;/Users/tomasfagerbekk/repos/digg.client.app;1.6

Make it

date;askeladden.toolbox;digg.client.app;FoodSociety.app;Petrus.Web;total
2020-08-25;2.6;4.8;0;0;7.4
2020-08-26;0;11.2;0;0;11.2
2020-08-27;0.9;7.6;0;0;8.5
2020-08-28;0;0.5;1.2;1.0;2.7
2020-08-29;1.0;1.1;0;0;2.1
2020-08-30;6.8;1.6;0;0;8.4

This makes it alot easier to copy paste hours into the "real timetracker".

• Maybe hide this behind a --compact flag? Or the inverse, make the old format --readable?

Add tests to match docs

Docs: Describe how to use the repository as a library

The repo can be used as a library, eg:

import timesheet from 'git-csv-timesheet';

const config = ...
const summary = timesheet.analyze(config);