projects / thirdparty / git.git / blame
| Commit | Line | Data |
|---|---|---|
| acb01a35 ES |
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 |