contrib/contacts/git-contacts.adoc

git-contacts(1)
===============

NAME
----
git-contacts - List people who might be interested in a set of changes


SYNOPSIS
--------
[verse]
'git contacts' (<patch>|'-'|<range>|<rev>)...


DESCRIPTION
-----------

Given a set of changes, specified as patch files or revisions, determine people
who might be interested in those changes.  This is done by consulting the
history of each patch or revision hunk to find people mentioned by commits
which touched the lines of files under consideration.

Input consists of one or more patch files or revision arguments.  A revision
argument can be a range or a single `<rev>` which is interpreted as
`<rev>..HEAD`, thus the same revision arguments are accepted as for
linkgit:git-format-patch[1].  A single dash `'-'` character in place of a
`<patch>` tells the command to read patch file(s) from the standard input.
Patch files, standard input, and revision arguments can be combined in the same
invocation.

This command can be useful for determining the list of people with whom to
discuss proposed changes, or for finding the list of recipients to Cc: when
submitting a patch series via `git send-email`. For the latter case, `git
contacts` can be used as the argument to `git send-email`'s `--cc-cmd` option.


DISCUSSION
----------

`git blame` is invoked for each hunk in a patch file or revision.  For each
commit mentioned by `git blame`, the commit message is consulted for people who
authored, reviewed, signed, acknowledged, or were Cc:'d.  Once the list of
participants is known, each person's relevance is computed by considering how
many commits mentioned that person compared with the total number of commits
under consideration.  The final output consists only of participants who exceed
a minimum threshold of participation.


OUTPUT
------

For each person of interest, a single line is output, terminated by a newline.
If the person's name is known, ``Name $$<user@host>$$'' is printed; otherwise
only ``$$<user@host>$$'' is printed.


EXAMPLES
--------

* Consult patch files:
+
------------
$ git contacts feature/*.patch
------------

* Revision range:
+
------------
$ git contacts R1..R2
------------

* From a single revision to `HEAD`:
+
------------
$ git contacts origin
------------

* Input a patch via stdin:
+
------------
$ git contacts - <feature.patch
------------

* Helper for `git send-email`:
+
------------
$ git send-email --cc-cmd='git contacts' feature/*.patch
------------


LIMITATIONS
-----------

Several conditions controlling a person's significance are currently
hard-coded, such as minimum participation level (10%), blame date-limiting (5
years), and `-C` level for detecting moved and copied lines (a single `-C`). In
the future, these conditions may become configurable.


GIT
---
Part of the linkgit:git[1] suite