gitwrk

README

GitWrk

GitWrk is a small commandline application that helps you with monthly reports by extracting working hours directly from git repository.

How it works

The idea is very simple. We're following very simple convention. Every commit we spent some times contain this information via spent trailer line.

git commit -m “feat: Add feature X to module Y” -m “spent: 4h15m” 

Another allowed form is non-trailer convention without ::

git commit -m “feat: Add feature X to module Y” -m “Spent 1h20m,7h30m” 

For better insights and transparency we adapted conventional commits. Then you can easily create monthly report for given contributor by typing:

> gitwrk --last-month --author zdenko.vrabel@unravela.com

Motivation

As freelance developers or outsourced developers, we need to report our work hours. For years we used tools like Jira or some weird 3rd party tools for logging our hours. Having 3 different tools for reporting our work is always exhausting and error prone. Because we love transparency, we want to provide good data.

This approach has several advantages: 

• We’re lazy engineers.  We don’t like to handle 3 different tools for one think. Git is the ultimate tool for our daily work. 
• Everything in one place. Multiple tools leads to disconnected information. 
• Better transparency. Customer exactly know how much of time we spent on what.
• We can analyze where are our bottlenecks, where we’re burning too many of our work time.

Programming isn't 100% of our daily work of course. Sometimes you have a meeting, sometimes some administrative work to do, but programming is still a majority.The --allow-empty flag allows you to track also non-coding work. 

Example of meeting:

git commit --allow-empty -m "meet: planning for next sprint" -m "spent: 45m" 

Installation

Install on Ubuntu (Snap)

You can install the application easily via Snap

snap install gitwrk

Test if app is installed

gitwrk --help

Install on Linux (DEB)

Download the .DEB package and install it

wget https://github.com/unravela/gitwrk/releases/download/v1.0.8/gitwrk_1.0.8_linux_64-bit.deb
dpkg -i ./gitwrk_1.0.8_linux_64-bit.deb

Install on Linux (RPM)

Download the .RPM package and install it

wget https://github.com/unravela/gitwrk/releases/download/v1.0.8/gitwrk_1.0.8_linux_64-bit.rpm
rpm -U ./gitwrk_1.0.8_linux_64-bit.rpm

Install on Windows (Scoop)

First, ensure the scoop is present in your environment. If not install it.

Run commands

scoop bucket add unravela https://github.com/unravela/scoop-bucket
scoop install gitwrk

Install on MacOS (Homebrew)

If you have Homebrew present in your environment, run command:

brew install unravela/tap/gitwrk

Build from source code

If you have Go (version 1.13) installed on your system, you can use command:

go get github.com/unravela/gitwrk

This command will download and install gitwrk into your GOPATH/bin folder.

How to use

The best way how to explore what gitwrk offers you is by help page:

    gitwrk --help

By default, the gitwrk will create report for all users for all commits. If you want to create report for concrete contributor in current month, you can use combination of flags -current-month and --author.

Time frames

    gitwrk --current-month --author me@company.com

You can also request report for last finished month:

    gitwrk --last-month --author me@company.com

If you wish report for some time window e.g. since November of 2019 to Jaunary 2020, you can use flags --since and --till:

    gitwrk --since 2019-11-01 --till 2020-01-31

Semantic commit message

The gitwrk is also supporting filtering by type and scope of semantic commit message. You can use flags --type and --scope for filtering. For example you want to know how many hours you spent on documentation:

    gitwrk --type docs --author me@company.com

Or how many hours spent developers on module-a last month:

    gitwrk --scope module-a --last-month

JSON and CSV output

The gitwrk can produce also JSON or CSV reports. This is usefull if you want to automatize and export your work hours to external systems. All you need is tell the gitwrk the output format via --output or -o flag.

    gitwrk --last-month --author me@copmany.com -o json

This command will produce output:

[
        {
                "when": "2020-02-11T17:27:24+01:00",
                "author": "me@company.com",
                "scm_type": "docs",
                "scm_scope": "",
                "spent": "30m0s",
                "spent_minutes": 30
        },
        {
                "when": "2020-02-10T17:12:04+01:00",
                "author": "me@gmail.com",
                "scm_type": "docs",
                "scm_scope": "",
                "spent": "1h10m0s",
                "spent_minutes": 70
        }
]

Documentation

Index

• func GetVersion() string
• type SemanticCommitMessage
  • func ParseSemanticCommitMessage(t string) *SemanticCommitMessage
• type WorkLog
• type WorkLogs
  • func Create(author string, when time.Time, msg string) WorkLogs
  • func GetWorkLogFromRepo(dir string, since time.Time, till time.Time) (WorkLogs, error)
  • func (wlogs WorkLogs) Filter(match func(WorkLog) bool) WorkLogs

Functions

func GetVersion

func GetVersion() string

GetVersion returns you version of Gitwk. If you get the 'devel' version, that means you're running directly from source code. The actual version is getting here via tag and ldflag:

go build -ldflags="-X 'github.com/unravela/gitwrk.version=v1.0.0'"

Types

type SemanticCommitMessage

type SemanticCommitMessage struct {
	Type    string
	Scope   string
	Subject string
}

SemanticCommitMessage is main structure that represent: 'type(scope): subject'

func ParseSemanticCommitMessage

func ParseSemanticCommitMessage(t string) *SemanticCommitMessage

ParseSemanticCommitMessage consume plain text of the commit message and produce the CommitMessage structure with type scope and subject.

If commit message doesn't match to semantic commit message, then it's type NONE where subject is first line of messsage

type WorkLog

type WorkLog struct {
	Author string
	When   time.Time
	Spent  time.Duration
	Scm    *SemanticCommitMessage
}

WorkLog is main structure representing working log

type WorkLogs

type WorkLogs []WorkLog

WorkLogs is array of WorkLog-s

func Create

func Create(author string, when time.Time, msg string) WorkLogs

Create construct the single working log or multiple working logs, depends on message

func GetWorkLogFromRepo

func GetWorkLogFromRepo(dir string, since time.Time, till time.Time) (WorkLogs, error)

GetWorkLogFromRepo go through all commits matching time window and extrac work logs for each commit.

func (WorkLogs) Filter

func (wlogs WorkLogs) Filter(match func(WorkLog) bool) WorkLogs

Filter go through worklogs and return only these, they're matching by passed 'match' function