What is this?

This tool, truckfactor computes the truck (bus/lorry/lottery) factor for a given Git repository.

The truck factor is

the number of people on your team that have to be hit by a truck (or quit) before the project is in serious trouble

L. Williams and R. Kessler, Pair Programming Illuminated. Addison Wesley, 2003.

Installation

pip install truckfactor

Requirements

The tool requires that git is installed and accessible on PATH.

How to use it?

You have to either point the tool to a directory containing a Git repository or to a URL with a remote repository. In case a URL is given, the tool will clone the repository into a temporary directory.

From the terminal, the tool can be run as in the following:

Usage:
  truckfactor <repository> [<commit_sha>] [--output=<kind>]
  truckfactor -h | --help
  truckfactor --version

Options:
  -h --help     Show this screen.
  --version     Show version.
  --output=<kind>  Kind of output, either csv or verbose.

For example, in its most basic form it can be called like this:

$ truckfactor <path_or_url_to_repository>
The truck factor of <path_to_repository> (<commit_sha>) is: <number>

If no output switch is given, the tool produces a single line output above. Otherwise, it will output a line in CSV format or in key: value form.

Calling it from code:

from truckfactor.compute import main


truckfactor = main("<path_to_repo>")

How does the tool compute the truck factor?

In essence the tool does the following:

• Reads a git log from the repository
• Computes for each file who has the knowledge ownership of it.
  • A contributor has knowledge ownership of a file when she edited the most lines in it.
  • That computation is inspired by A. Thornhill Your Code as a Crime Scene.
  • Note, only for text files knowledge ownership is computed. The tool may not return a good answer for repositories containing only binary files.
• Then similar to G. Avelino et al. A novel approach for estimating Truck Factors low-contributing authors are removed from the analysis as long as still more than half of all files have a knowledge owner. The amount of remaining knowledge owners is the truck factor of the given repository.

Why does it exist?

This tool was developed since in Dec. 2020, we could not find an open-source and readily installable tool to compute truck factors of projects on PyPI or Rubygems.