git-hot 0.10

Git extension for reporting source code line lifetime and churn

git-hot

git-hot is a Git extension that reports how ``hot'' (often-changing) the current lines or files in a repository are. It derives line lifetime and churn information from Git history, then highlights files and lines that have changed often or recently.

Install the package and run it as either:

git hot
git-hot

The package installs two commands:

• git-hot, the Git extension command; manual page.
• daglp, a helper, written in Rust, used to compute the longest path through the Git commit DAG; manual page.

Command installation

As an individual user

uv tool install git-hot

or

pipx install git-hot

or (discouraged legacy method)

pip install --user git-hot

For all users

sudo pipx install --global git-hot

In an active virtual environment

uv pip install git-hot

python -m pip install git-hot

After installation, ensure the installation's script directory is on PATH so Git can find git-hot and you can invoke it as git hot.

Usage

Show hot files in the current repository:

git hot

Show hot files at a specific revision:

git hot HEAD

Show line-level churn for one file:

git hot -- src/main.py

Show line ages and birth commits for one file:

git hot -q --format '{days(age)} {hash[:7]} {line}' -- src/main.py

Reconstruct all source files with churn prefixes below a directory:

git hot --dir hot-tree HEAD

Output

Without a path, git hot prints one line per current source file, sorted by path. The default columns are:

• maximum live-line churn in the file
• median changed-line lifetime in days
• median live-line age in days
• repository path

With a path, git hot prints the reconstructed contents of that file. By default each line is preceded by its churn count.

Use --color always or --color never to control color output. Automatic coloring can rank lines by churn, age, or lifetime:

git hot --color always --color-domain age -- src/main.py

Formatting

Use --format to customize file or line output with a restricted Python f-string expression. The available fields depend on whether repository-wide file metrics or selected-path line output is being produced.

Examples:

git hot --format '{max(churn):5d} {days(median(line_age)):5d} {path}'
git hot --format '{days(age)} {hash[:7]} {line}' -- src/main.py

Common helpers include days, max, min, median, mean, quartile_rank, color, and color_reset.

For the complete list of format fields and options, see:

man git-hot

or read the git-hot manual page.

Requirements

git-hot expects to run inside a Git repository. Alternatively, the Git repository can be passed to the git command using the --git-dir option. Internally, it invokes Git commands such as git log, git show, and git diff, and uses rename and copy detection.

Binary files and deleted files are skipped in file-metric output.

Installing From Source

Building from source requires Python 3.10 or later and a Rust toolchain with rustc, because daglp is compiled during installation.

uv sync --group dev
uv pip install -e .
uv run python -m unittest discover -s . -p 'test*.py'
uv run --group dev ruff check .

Run the full Python integration test suite on Unix-like systems with:

make test-python

This rule exercises the Git history fixtures, shell scripts, daglp, and the Python command-line interface. It depends on Bash and standard Unix tools such as sort and diff, so CI runs it only on Linux.

Build a source distribution locally with:

uv build --sdist

Reinstall updated Python source code with:

pipx uninstall git-hot
pipx install .

Platform wheels are built in CI through cibuildwheel, which smoke-tests the installed git-hot and daglp commands and runs the portable Python unit tests against each wheel on Linux, Windows, and macOS.

Research Tools

This repository also contains research-oriented source tools used for fine-grained code lifetime analysis, including lifetime.py, difflog.sh, tokenize.pl, and the top-level daglp.rs. They are kept in source form for reproducibility and experimentation, but the installable package exposes only git-hot and daglp.

For historical and research context, see lifetime-tools.md.

License

git-hot is distributed under the Apache License 2.0. See LICENSE.