git-stats

#!/usr/bin/env python3
"""Per-author commit/line stats from Git history.

Identities are merged transitively: commits that share an email or a name end
up in the same row, repeated until nothing changes. That fixpoint is the
connected components of the name<->email graph, which union-find finds in one
pass. Placeholder identities never link anything, so they can't chain
unrelated people together.
"""

import argparse
import subprocess
import sys
from collections import Counter, defaultdict

# Placeholders seen in real repos (e.g. copied from git's "Please tell me who
# you are" hint). Commits using them still count; they just never link.
GENERIC_NAMES = {
    "",
    "root",
    "admin",
    "administrator",
    "user",
    "unknown",
    "your name",
    "ubuntu",
    "git",
}
GENERIC_EMAILS = {
    "",
    "you@example.com",
    "none@none",
    "unknown",
    "noreply@github.com",
}
GENERIC_EMAIL_SUFFIXES = ("@localhost", ".(none)", ".localdomain")

COLUMNS = ["author", "commits", "added", "removed"]


def norm(s: str) -> str:
    return " ".join(s.split()).casefold()


def read_history(git_args, mailmap=True):
    """Return {(name, email): [commits, added, removed]}."""
    fmt = "%x1e%aN%x1f%aE" if mailmap else "%x1e%an%x1f%ae"
    cmd = [
        "git",
        "log",
        "--no-merges",
        "--numstat",
        f"--format={fmt}",
        *git_args,
    ]
    stats = defaultdict(lambda: [0, 0, 0])
    cur = None
    with subprocess.Popen(
        cmd,
        stdout=subprocess.PIPE,
        text=True,
        encoding="utf-8",
        errors="replace",
    ) as proc:
        for line in proc.stdout:
            if line.startswith("\x1e"):
                name, _, email = line[1:].rstrip("\n").partition("\x1f")
                cur = stats[name, email]
                cur[0] += 1
            elif cur is not None:  # numstat: added<TAB>removed<TAB>path
                added, _, rest = line.partition("\t")
                removed = rest.partition("\t")[0]
                if added.isdigit():  # binary files show "-"
                    cur[1] += int(added)
                if removed.isdigit():
                    cur[2] += int(removed)
    if proc.returncode != 0:
        sys.exit("error: `git log` failed (bad revision, or not a git repo?)")
    return stats


def most_common(counter: Counter) -> str:
    """Most frequent; ties -> longest, then alphabetical."""
    return min(counter.items(), key=lambda kv: (-kv[1], -len(kv[0]), kv[0]))[0]


def parse_args():
    p = argparse.ArgumentParser(
        description="Per-author commit/line stats, merging identities "
        "transitively by email and name.",
        epilog="Arguments after `--` go to `git log`, e.g. "
        "`-- v1.0..v2.0 --since=2024-01-01`. "
        "Add `--no-max-parents` there to count merge commits.",
    )
    p.add_argument("git_args", nargs="*", metavar="GIT-LOG-ARG")
    p.add_argument("-s", "--sort", default="commits", choices=COLUMNS)
    p.add_argument(
        "-r",
        "--reverse",
        action="store_true",
        help="reverse order (numbers default largest-first, author A-Z)",
    )
    p.add_argument(
        "-e",
        "--emails",
        action="store_true",
        help="add a column with each author's most-used email",
    )
    p.add_argument(
        "-v",
        "--verbose",
        action="store_true",
        help="list every name and email folded into each author",
    )
    p.add_argument(
        "-i",
        "--ignore",
        action="append",
        default=[],
        metavar="ID",
        help="name or email that must never link identities (repeatable)",
    )
    p.add_argument(
        "--no-merge-names",
        action="store_true",
        help="link identities by email only",
    )
    p.add_argument(
        "--no-mailmap",
        action="store_true",
        help="use raw author names/emails, ignoring .mailmap",
    )
    return p.parse_args()


def main():
    args = parse_args()
    stats = read_history(args.git_args, mailmap=not args.no_mailmap)

    extra = {norm(x) for x in args.ignore}
    bad_names = GENERIC_NAMES | extra
    bad_emails = GENERIC_EMAILS | extra

    # union-find over name/email nodes
    parent = {}

    def find(x):
        parent.setdefault(x, x)
        while parent[x] != x:
            parent[x] = parent[parent[x]]  # path halving
            x = parent[x]
        return x

    def union(a, b):
        parent[find(b)] = find(a)

    def nodes_for(name, email):
        n, e = norm(name), norm(email)
        nodes = []
        if e not in bad_emails and not e.endswith(GENERIC_EMAIL_SUFFIXES):
            nodes.append(("email", e))
        if not args.no_merge_names and n not in bad_names:
            nodes.append(("name", n))
        return nodes or [("pair", n, e)]  # nothing usable: stands alone

    anchor = {}
    for pair in stats:
        nodes = nodes_for(*pair)
        for node in nodes[1:]:
            union(nodes[0], node)
        anchor[pair] = nodes[0]

    # aggregate per connected component
    groups = defaultdict(
        lambda: {"n": [0, 0, 0], "names": Counter(), "emails": Counter()}
    )
    for (name, email), (c, a, r) in stats.items():
        g = groups[find(anchor[name, email])]
        g["n"][0] += c
        g["n"][1] += a
        g["n"][2] += r
        if name.strip():
            g["names"][name] += c
        if email.strip():
            g["emails"][email] += c

    # row: (name, commits, added, removed, email, group)
    rows = []
    for g in groups.values():
        name = most_common(g["names"]) if g["names"] else "(unknown)"
        email = most_common(g["emails"]) if g["emails"] else ""
        rows.append((name, *g["n"], email, g))

    # sort: alphabetical base, then stable sort on the chosen column
    col = COLUMNS.index(args.sort)
    rows.sort(key=lambda r: r[0].casefold(), reverse=args.reverse and col == 0)
    if col:
        rows.sort(key=lambda r: r[col], reverse=not args.reverse)

    # output: columns sized to content, nothing truncated
    name_w = max([len("Author")] + [len(r[0]) for r in rows])
    email_w = max([len("Email")] + [len(r[4]) for r in rows])

    def fmt_row(name, email, c, a, r):
        mid = f"  {email:<{email_w}}" if args.emails else ""
        return f"{name:<{name_w}}{mid} {c:>8} {a:>10} {r:>10}"

    print(fmt_row("Author", "Email", "Commits", "Added", "Removed"))
    for name, c, a, r, email, g in rows:
        print(fmt_row(name, email, c, a, r))
        if args.verbose:
            for label, counter in (
                ("names", g["names"]),
                ("emails", g["emails"]),
            ):
                items = ", ".join(
                    f"{k} ({v})" for k, v in counter.most_common()
                )
                print(f"    {label + ':':<8}{items or '-'}")

    if args.verbose:
        merged = sum(
            len(g["names"]) > 1 or len(g["emails"]) > 1
            for g in groups.values()
        )
        source = (
            "raw, .mailmap ignored" if args.no_mailmap else "after .mailmap"
        )
        print(
            f"\n{len(stats)} distinct name/email pairs ({source}) -> "
            f"{len(rows)} authors, {merged} with merged identities"
        )


if __name__ == "__main__":
    main()