| 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 |