Skip to main content

Tool to compute the truck factor of a Git repository

Project description

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.


pip install truckfactor


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:

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

  -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, commit_sha, authors = 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.


The logo is combined from two logos from flaticon:

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

truckfactor-0.3.0.tar.gz (24.0 kB view hashes)

Uploaded Source

Built Distribution

truckfactor-0.3.0-py3-none-any.whl (25.8 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page