git-spend : time tracker using git commit message commands

Purpose

Collect, addition and return all the /spend and /spent time-tracking directives in git commit messages.

This looks at the git log of the currently checked out branch of the working directory, and therefore requires git to be installed on your system.

TLDR; JUST DOWNLOAD LINUX/MAC — DOWNLOAD WINDOWS

By Example

Say you are in the directory of a project with one commit like so :

feat(crunch): implement a nice feature

Careful, it's still sharp.
/spend 10h30

Running:

$ git spend sum

would yield:

1 day 2 hours 30 minutes

Of course, git-spend really shines when you have multiple commits with /spend commands that you want to tally and sum.

💡 You can use git-spend sum or git spend sum, they are equivalent.

Specifications

We assume 8 hours per day, 5 days per week, 4 weeks per month. (like Gitlab does) These can be configured at runtime if needed, using environment variables.

The complete specification can be found in the rules of the test data, and in excruciating detail in the grammar.

The acceptance testing suite also holds many usage examples.

Usage

Go into your git-versioned project's directory:

cd <some git versioned project with commits using /spend directives>

and run:

git spend sum

2 days 1 hour 42 minutes

Or run git-spend from anywhere, but specify the --target directory (which defaults to .):

git spend sum --target <some git versioned project dir>

2 days 1 hour 42 minutes

⛑ Use git spend sum --help or man git-spend-sum to see all the options. Meanwhile, let's look at some available options, below.

Format the output

You can get the spent time in a specific unit :

git spend sum --minutes
git spend sum --hours
git spend sum --days

These values will always be rounded to integers, for convenience, although git-spend does understand floating point numbers in /spend directives.

Filter by commit authors

You can track the time of specified authors only, by name or email :

git spend sum --author Alice --author bob@email.net

Exclude merge commits

You can also exclude merge commits :

git spend sum --no-merges

Restrict to a range of commits

You can restrict to a range of commits, using a commit hash, a tag, or even HEAD~N.

git spend sum --since <ref> --until <ref>

For example, to get the time spent on the last 15 commits :

git spend sum --since HEAD~15

Or the time spent on a tag since previous tag :

git spend sum --since 0.1.0 --until 0.1.1

You can also use dates and datetimes, but remember to quote them if you specify the time:

git spend sum --since 2023-03-21
git spend sum --since "2023-03-21 13:37:00"

📅 Other supported time formats: RFC3339, RFC822, RFC850. If you need a specific timezone, try setting the TZ environment variable: TZ="Europe/Paris" git-spend sum --since 2023-03-21

Download

Direct download

You can ⮋ download the binary straight from the latest build in the releases, and move it anywhere in your $PATH, such as /usr/local/bin/git-spend for example.

⚠ Remember to enable the execution bit with chmod u+x ./git-spend, for example.

There is an experimental install script that does exactly this, plus man pages generation:

curl https://raw.githubusercontent.com/Goutte/git-spend/main/install.sh | sh

🐧 This script only works for linux/amd64, for now. Stigmergy?

Via go get

You can also install via go get (hopefully) :

go get -u github.com/goutte/git-spend

or go install:

go install github.com/goutte/git-spend

If that fails, you can install by cloning and running make install.

Advanced Usage

Read from standard input

You can also directly parse messages from stdin instead of attempting to read the git log:

git log > git.log
cat git.log | git-spend sum --stdin

git spend ignores standard input otherwise.

Configure the time modulo

If you live somewhere where work hours per week are limited (to 35 for example) in order to mitigate labor oppression tactics from monopoly hoarders, you can use environment variables to control how time is "rolled over" between units :

GIT_SPEND_HOURS_PER_DAY=7 git-spend sum

Here are the available environment variables :

• GIT_SPEND_MINUTES_PER_HOUR (default: 60)
• GIT_SPEND_HOURS_PER_DAY (default: 8)
• GIT_SPEND_DAYS_PER_WEEK (default: 5)
• GIT_SPEND_WEEKS_PER_MONTH (default: 4)

Install the man pages

If you installed via direct download, you might want to install the man pages:

sudo git spend man --install

git help spend will then work as expected.

Develop

First, you'll need to install Golang.

git clone https://github.com/Goutte/git-spend.git
cd git-spend
go get
go run main.go

Build & Run & Install

The binaries in the releases are built by our Continuous Integration.

Nevertheless, if you want to build your own git-spend, you can clone this project and run:

make
make install

upx is used to reduce the binary size in make install-release.

---

You can compare the checksums, and they should be the same unless microsoft is being naughty.

Build for other platforms

You may use the GOOS and GOARCH environment variables to control the build targets:

GOOS=<target-OS> GOARCH=<target-architecture> go build -o build/git-spend .

To list available targets (os/arch), you can run:

go tool dist list

There's an example in the Makefile, with the recipe make build-windows-amd64.

Contribute

Merge requests are welcome. Make sure you record the time you /spend in your commit messages. :)

Translations

Translations files are in locale/*.toml. To add another language, add a new file, some sugar, some water, and … voilà !

Ideas Stash

You can pick and start any, or do something else entirely. If you don't like any of these, please voice your concerns as early as possible.

• curl install.sh | sudo sh (ongoing, wider support needed)
• i18n (ongoing, cobra forked)
• git-spend sum --format <custom format>
• git-spend sum --short → 1d3h27m
• git-spend chrono start → start an internal chronometer
• git-spend chrono add → add time to the chronometer
• Rewriting of /spend chrono [± <duration>] by commit hook
• Rewriting of /spend <ref> [± <duration>] by commit hook 🌟
• git spend hook --install to install git hooks for rewriting
• git spend hook --remove to remove installed git hooks
• git-spend amend <duration> → amend previous commit with /spend <duration>
• git-spend amend --add <duration> → same but adds
• git-spend amend --subtract <duration> → same but subtracts (alias: --sub ?)
• docker (docker run git-spend -- awkward? ; would need a volume)
• flatpak perhaps (road blocked, see packaging/)
• Right-To-Left (ساعد)