borehole

Survey a codebase without sending it anywhere.

borehole reads a git repository on the machine you run it on and sends a bundle of facts about it — counts, file paths, line numbers and a small number of short quoted lines. Your source code does not leave. You get back a report with a commit, a path and a line range behind every finding.

pip install borehole
export BOREHOLE_TOKEN=bh_…          # from borehole.dev/account
borehole collect . --dry-run        # print exactly what would be sent
borehole collect .                  # send it, get a report

Run --dry-run first

It prints the entire bundle and sends nothing about your repository. You are being asked to send facts about your codebase to a third party, and you should be able to read those facts before the first time and whenever you like afterwards.

Run it with your token set. The detection patterns are not in this package; they are fetched for each run, and a dry run with a token fetches them too, so it prints the quoted lines a real run would send. That fetch is the only request it makes, and its body is empty.

Without a token it makes no network request at all, and prints everything except the pattern matches.

What leaves, precisely

Author names and addresses are hashed before they leave, salted per repository, so the same person is the same identity within one survey and not across surveys. Every measurement counts and compares; none of them needs a name.

The hash is a pseudonym, not anonymity. The salt is the repository's head commit, and that commit is in the bundle. So anyone holding a bundle could test whether a guessed address belongs to one of its authors. Borehole does not, and a report stores authorship only as counts.

One honest caveat. Three checks quote the line they matched, because for those the line is the evidence — a TODO's wording, a commit subject, an unpinned dependency. If somebody wrote a colleague's name in a TODO, that text crosses. --dry-run shows you, and the report's owner can strip quoted evidence afterwards.

Any git repository

GitHub, GitLab, Bitbucket, Azure DevOps, a self-hosted install of any of them — or no host at all. A bare repository on a file server, a clone inside a data room, a laptop with the wifi off. If git log works, this works.

Without a host to ask there are no stars, no language breakdown and no repository size. That is audience data rather than engineering data, and a private repository never had it either.

What this package is not

This is the collector. The assessment itself — the thresholds, the bands, the rejection reasons, the wording that makes a finding worth acting on — runs on Borehole's servers and is not in this package. Detection patterns are fetched for each run rather than shipped here.

So reading this source tells you exactly what leaves your machine, which is the question this package exists to let you answer. It does not tell you how the judgement is made. Both of those are deliberate.

Requires

Python 3.10 or newer, and git on the PATH. No other dependencies.

borehole.dev · what happens to your code · terms