contrib: contacts: add documentation
Assuming that git-contacts may some day be promoted to a core git command, the documentation is written and formatted as if it already belongs in Documentation/ even though it presently resides in contrib/contacts. Signed-off-by: Eric Sunshine <sunshine@sunshineco.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Eric Sunshine committed
Jul 21, 2013 at 06:52 UTC
acb01a359bc2fe3f1ddfb1eb9daa60b8c83e5153
1 file changed
+94
contrib/contacts/git-contacts.txt
new
+94
@@ -0,0 +1,94 @@
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