Source code for repomatic.mailmap

# Copyright Kevin Deldycke <[email protected]> and contributors.
#
# This program is Free Software; you can redistribute it and/or
# modify it under the terms of the GNU General Public License
# as published by the Free Software Foundation; either version 2
# of the License, or (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program; if not, write to the Free Software
# Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.

"""Group the contributor identities of the git history into a `.mailmap`.

Backs the `sync-mailmap` command: parses the existing mappings as the
reference for identities already grouped, reads every author and committer the
history holds, and appends whatever is not covered yet.
"""

from __future__ import annotations

import logging
from dataclasses import dataclass, field
from pathlib import Path

from .git_ops import list_contributor_identities

MAILMAP_PATH = Path(".mailmap")
"""Canonical path to the `.mailmap` file in the repository root."""


[docs] @dataclass class Record: """A mailmap identity mapping entry.""" canonical: str = "" """The identity every alias maps to, in `Name <email>` form.""" aliases: set[str] = field(default_factory=set) """The other identities of the same contributor.""" pre_comment: str = "" """The comment and blank lines written above the mapping.""" def __post_init__(self) -> None: """Drop a pre-comment made of blank lines only.""" if not self.pre_comment.strip(): self.pre_comment = "" @property def identities(self) -> frozenset[str]: """Every identity of the record, lowercased. Identity matching is case insensitive, per the [mailmap syntax](https://git-scm.com/docs/gitmailmap#_syntax). """ return frozenset(i.lower() for i in (self.canonical, *self.aliases) if i) @property def mapping(self) -> str: """The mapping line: the canonical identity, then the sorted aliases. The aliases sort without case sensitivity. The canonical identity keeps its place in front. """ return " ".join((self.canonical, *sorted(self.aliases, key=str.casefold))) def __str__(self) -> str: """Render the pre-comment first, followed by the identity mapping.""" lines = [] if self.pre_comment: lines.append(self.pre_comment) if self.canonical: lines.append(self.mapping) return "\n".join(lines)
[docs] class Mailmap: """Helpers to manipulate `.mailmap` files. `.mailmap` [file format is documented on Git website](https://git-scm.com/docs/gitmailmap). """ records: list[Record] def __init__(self) -> None: """Initialize the mailmap with an empty list of records.""" self.records = []
[docs] @staticmethod def split_identities(mapping: str) -> tuple[str, set[str]]: """Split a mapping of identities and normalize them.""" identities = [] for identity in map(str.strip, mapping.split(">")): # Skip blank strings produced by uneven spaces. if not identity: continue assert identity.count("<") == 1, f"Unexpected email format in {identity!r}" name, email = identity.split("<", maxsplit=1) identities.append(f"{name.strip()} <{email}>") assert len(identities), f"No identities found in {mapping!r}" identities = list(dict.fromkeys(identities)) return identities[0], set(identities[1:])
[docs] def parse(self, content: str) -> None: """Parse mailmap content and add it to the current list of records. Each non-empty, non-comment line is considered a mapping entry. The preceding lines of a mapping entry are kept attached to it as pre-comments, so the layout will be preserved on rendering, during which records are sorted. """ logging.debug(f"Parsing:\n{content}") pre_lines = [] for line in map(str.strip, content.splitlines()): # Comment lines are added as-is. if line.startswith("#") or not line: pre_lines.append(line) # Mapping entry, which mark the end of a block, so add it to the list # mailmap records. else: canonical, aliases = self.split_identities(line) record = Record( pre_comment="\n".join(pre_lines), canonical=canonical, aliases=aliases, ) logging.debug(record) pre_lines = [] self.records.append(record)
[docs] def update_from_git(self) -> None: """Add to internal records all missing contributors found in commit history. No normalization happens: all variations of authors and committers strings attached to all commits are considered. A contributor already registered, as a canonical identity or as an alias, is not added again. :raises RuntimeError: When git fails, carrying its stderr. """ contributors = list_contributor_identities() logging.debug( "Authors and committers found in Git history:\n" + "\n".join(sorted(contributors, key=str.casefold)) ) known = {identity for record in self.records for identity in record.identities} # Sorted, so the first of two identities differing only in case is # the same on every run. for contributor in sorted(contributors, key=lambda c: (c.casefold(), c)): if contributor.lower() in known: logging.debug(f"Ignore existing identity {contributor}") continue record = Record(canonical=contributor) logging.info(f"Add new identity {record}") self.records.append(record) known |= record.identities
[docs] def render(self) -> str: """Render internal records in Mailmap format. The records sort by canonical identity, without case sensitivity. The pre-comment of the first parsed record is the comment that opens the file, so it stays at the top, whichever record sorts first. """ if not self.records: return "" first = self.records[0] lines = [first.pre_comment] if first.pre_comment else [] for record in sorted(self.records, key=lambda r: r.canonical.casefold()): lines.append(record.mapping if record is first else str(record)) return "\n".join(lines)