contrib/contacts/git-contacts.txt

   1 git-contacts(1)
   2 ===============
   3
   4 NAME
   5 ----
   6 git-contacts - List people who might be interested in a set of changes
   7
   8
   9 SYNOPSIS
  10 --------
  11 [verse]
  12 'git contacts' (<patch>|<range>|<rev>)...
  13
  14
  15 DESCRIPTION
  16 -----------
  17
  18 Given a set of changes, specified as patch files or revisions, determine people
  19 who might be interested in those changes.  This is done by consulting the
  20 history of each patch or revision hunk to find people mentioned by commits
  21 which touched the lines of files under consideration.
  22
  23 Input consists of one or more patch files or revision arguments.  A revision
  24 argument can be a range or a single `<rev>` which is interpreted as
  25 `<rev>..HEAD`, thus the same revision arguments are accepted as for
  26 linkgit:git-format-patch[1]. Patch files and revision arguments can be combined
  27 in the same invocation.
  28
  29 This command can be useful for determining the list of people with whom to
  30 discuss proposed changes, or for finding the list of recipients to Cc: when
  31 submitting a patch series via `git send-email`. For the latter case, `git
  32 contacts` can be used as the argument to `git send-email`'s `--cc-cmd` option.
  33
  34
  35 DISCUSSION
  36 ----------
  37
  38 `git blame` is invoked for each hunk in a patch file or revision.  For each
  39 commit mentioned by `git blame`, the commit message is consulted for people who
  40 authored, reviewed, signed, acknowledged, or were Cc:'d.  Once the list of
  41 participants is known, each person's relevance is computed by considering how
  42 many commits mentioned that person compared with the total number of commits
  43 under consideration.  The final output consists only of participants who exceed
  44 a minimum threshold of participation.
  45
  46
  47 OUTPUT
  48 ------
  49
  50 For each person of interest, a single line is output, terminated by a newline.
  51 If the person's name is known, ``Name $$<user@host>$$'' is printed; otherwise
  52 only ``$$<user@host>$$'' is printed.
  53
  54
  55 EXAMPLES
  56 --------
  57
  58 * Consult patch files:
  59 +
  60 ------------
  61 $ git contacts feature/*.patch
  62 ------------
  63
  64 * Revision range:
  65 +
  66 ------------
  67 $ git contacts R1..R2
  68 ------------
  69
  70 * From a single revision to `HEAD`:
  71 +
  72 ------------
  73 $ git contacts origin
  74 ------------
  75
  76 * Helper for `git send-email`:
  77 +
  78 ------------
  79 $ git send-email --cc-cmd='git contacts' feature/*.patch
  80 ------------
  81
  82
  83 LIMITATIONS
  84 -----------
  85
  86 Several conditions controlling a person's significance are currently
  87 hard-coded, such as minimum participation level (10%), blame date-limiting (5
  88 years), and `-C` level for detecting moved and copied lines (a single `-C`). In
  89 the future, these conditions may become configurable.
  90
  91
  92 GIT
  93 ---
  94 Part of the linkgit:git[1] suite