git-annotate

Print a file with the author name and commit hash prepended to each line

$ git annotate [path/to/file]

$ git annotate [[-e|--show-email]] [path/to/file]

$ git annotate -L :[regexp] [path/to/file]

git annotate [--options] [revision] [--] file...

-L start,end or -L function
    Limit the blame to a specific line range or function within the file.

--porcelain (-p)
    Output the blame information in a machine-readable format, suitable for scripting.

--whitespace (-w)
    Ignore whitespace changes when attributing lines, focusing on semantic changes.

--move (-M[num])
    Detect moved or copied lines within the same file and attribute them correctly.

--copy (-C[num])
    Detect moved or copied lines from other files in the same commit.

--root
    Do not stop at the first revision, but trace blame across the entire history to the root commit.

--reverse
    Walk history backwards from the current revision, showing what was removed.

revision
    Start blaming from this specific commit ID or reference instead of HEAD.

file...
    The path to the file(s) for which to perform the annotation (blame) operation.

--since=date
    Show only commits after a specific date, filtering the blame history.

--until=date
    Show only commits before a specific date, filtering the blame history.

The git-annotate command, essentially an alias for git-blame, displays the author and commit information for each line of a given file. It traces the history of each line, showing when and by whom it was last modified, aiding in understanding code evolution, debugging, and identifying the origin of specific code segments. This tool is invaluable for code archaeologists and developers trying to understand why a particular line exists or was changed.

It can be configured to ignore whitespace changes, detect moved or copied lines within or across files, and restrict the analysis to specific line ranges or commit revisions. By providing a detailed lineage for each line of code, git-annotate helps pinpoint responsibilities and provides context for code review and maintenance tasks, offering a granular view into the project's commit history.

The git-annotate command is largely an alias for git-blame; most modern Git documentation and discussions refer to git-blame. It attributes lines to the last commit that modified them, not necessarily the original commit that introduced them, unless options like --root are used. It's not designed to show all historical changes to a line, but rather its current state's lineage.

You can configure git-blame (and thus git-annotate) to ignore specific commits, such as mass reformatting or automated changes, when attributing lines. This is done by setting the blame.ignoreRevsFile configuration option or by using the --ignore-revs-file command-line option, pointing to a file containing a list of commit hashes to ignore.

git-annotate has been a part of Git since its early days, often serving as a direct alias or precursor to the more commonly known git-blame command. Both commands provide the same core line-by-line authorship tracking functionality. The naming convention likely evolved, with git-blame becoming the predominant and more semantically descriptive term for its function.

git blame(1), git log(1), git diff(1), git show(1)