githeatmap.nvim

A Neovim plugin that analyzes the change frequency of code blocks in git history, helping you identify hotspots and understand modification patterns.

Features

• Track change frequency for code blocks over a configurable time window
• Block-level statistics: total changes, author contributions, latest modification
• Author breakdown sorted by number of changes
• Two counting methods: sum of all line changes or unique commits
• Single-line detailed change history
• Markdown-formatted floating window with syntax highlighting
• LazyVim compatible

Installation

Using lazy.nvim

{
  "yourusername/githeatmap.nvim",
  cmd = "GitHeatmap",
  opts = {
    days = 7,  -- Number of days to look back (default: 7)
  },
}

Manual installation

1. Clone this repository into your Neovim plugin directory
2. Add to your init.lua:

require("githeatmap").setup({
  days = 7,  -- optional, default is 7
})

Usage

Basic Usage

1. Select a line or range of lines in visual mode
2. Run the command: :'<,'>GitHeatmap

Or for the current line:

:GitHeatmap

Visual Mode

" Select lines with V or v
V
" Run the command
:'<,'>GitHeatmap

Behavior

• Single line: Shows detailed change history for that specific line with commits, dates, and messages
• Multiple lines (block): Shows block-level summary with total changes, author breakdown, and latest change date

Example Output

For a code block (multiple lines):

# GitHeatmap - Block Frequency

**Lines 25-30** (6 lines, 30 days)

**Total Changes**: 15 (total changes)
**Latest Change**: Nov 12, 2025

## Authors (sorted by changes)

- **Alice**: 8 changes
- **Bob**: 5 changes
- **Carol**: 2 changes

Press q, Esc, or Enter to close

For a single line:

# GitHeatmap - Block Frequency

**Line 42**: 7 changes in 7 days

## Changes

- `a1b2c3d` **Jan 13, 2025** by *Alice*
  Fix authentication bug
- `e4f5g6h` **Jan 12, 2025** by *Bob*
  Update error handling
...

Configuration

require("githeatmap").setup({
  -- Number of days to look back in git history
  days = 7,

  -- Notification level (vim.log.levels.INFO, WARN, ERROR, etc.)
  notify_level = vim.log.levels.INFO,

  -- How to count changes for a block
  -- "sum" (default): Sum all line changes in the block
  -- "unique_commits": Count each commit once if it touches any line in the block
  count_method = "sum",
})

Count Methods

When analyzing a code block (multiple lines), you can choose how changes are counted:

• "sum" (default) - Counts every change to every line in the block

  • Example: If commit A changed 3 lines in the block, it counts as 3 changes
  • Best for understanding the total modification intensity

• "unique_commits" - Counts each commit only once if it touched any line in the block

  • Example: If commit A changed 3 lines in the block, it counts as 1 change
  • Best for understanding how many times the block was touched

Requirements

• Neovim >= 0.8
• Git must be installed and accessible in PATH
• File must be tracked by git

How it Works

The plugin uses git log -L to track changes to specific line ranges over time, filtering by the configured time window.

• Single line: Displays detailed commit history for that line
• Multiple lines (block): Analyzes all lines in the selection, aggregates commits, calculates author statistics, and presents a summary view showing change frequency and contributor breakdown

License

MIT