From fa779fa88d18f550421ae777f7e048dd08ad0006 Mon Sep 17 00:00:00 2001 From: Todd Zullinger Date: Sat, 1 Mar 2025 10:36:03 -0500 Subject: contrib/contacts: rename .txt to .adoc The .txt extensions were changed to .adoc in 1f010d6bdf (doc: use .adoc extension for AsciiDoc files, 2025-01-20). Do the same for contrib/contacts. Signed-off-by: Todd Zullinger Signed-off-by: Junio C Hamano --- contrib/contacts/Makefile | 2 +- contrib/contacts/git-contacts.adoc | 94 ++++++++++++++++++++++++++++++++++++++ contrib/contacts/git-contacts.txt | 94 -------------------------------------- contrib/contacts/meson.build | 4 +- 4 files changed, 97 insertions(+), 97 deletions(-) create mode 100644 contrib/contacts/git-contacts.adoc delete mode 100644 contrib/contacts/git-contacts.txt diff --git a/contrib/contacts/Makefile b/contrib/contacts/Makefile index a2990f0dcb..9c4ca4f3bc 100644 --- a/contrib/contacts/Makefile +++ b/contrib/contacts/Makefile @@ -34,7 +34,7 @@ GIT_CONTACTS := git-contacts GIT_CONTACTS_DOC := git-contacts.1 GIT_CONTACTS_XML := git-contacts.xml -GIT_CONTACTS_TXT := git-contacts.txt +GIT_CONTACTS_TXT := git-contacts.adoc GIT_CONTACTS_HTML := git-contacts.html doc: $(GIT_CONTACTS_DOC) $(GIT_CONTACTS_HTML) diff --git a/contrib/contacts/git-contacts.adoc b/contrib/contacts/git-contacts.adoc new file mode 100644 index 0000000000..dd914d1261 --- /dev/null +++ b/contrib/contacts/git-contacts.adoc @@ -0,0 +1,94 @@ +git-contacts(1) +=============== + +NAME +---- +git-contacts - List people who might be interested in a set of changes + + +SYNOPSIS +-------- +[verse] +'git contacts' (||)... + + +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 `` which is interpreted as +`..HEAD`, thus the same revision arguments are accepted as for +linkgit:git-format-patch[1]. Patch files 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 $$$$'' is printed; otherwise +only ``$$$$'' 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 +------------ + +* 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 diff --git a/contrib/contacts/git-contacts.txt b/contrib/contacts/git-contacts.txt deleted file mode 100644 index dd914d1261..0000000000 --- a/contrib/contacts/git-contacts.txt +++ /dev/null @@ -1,94 +0,0 @@ -git-contacts(1) -=============== - -NAME ----- -git-contacts - List people who might be interested in a set of changes - - -SYNOPSIS --------- -[verse] -'git contacts' (||)... - - -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 `` which is interpreted as -`..HEAD`, thus the same revision arguments are accepted as for -linkgit:git-format-patch[1]. Patch files 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 $$$$'' is printed; otherwise -only ``$$$$'' 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 ------------- - -* 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 diff --git a/contrib/contacts/meson.build b/contrib/contacts/meson.build index 6ec92f47c4..73d82dfe52 100644 --- a/contrib/contacts/meson.build +++ b/contrib/contacts/meson.build @@ -16,7 +16,7 @@ if get_option('docs').contains('man') '@INPUT@', ], depends: documentation_deps, - input: 'git-contacts.txt', + input: 'git-contacts.adoc', output: 'git-contacts.xml', ) @@ -47,7 +47,7 @@ if get_option('docs').contains('html') '@INPUT@', ], depends: documentation_deps, - input: 'git-contacts.txt', + input: 'git-contacts.adoc', output: 'git-contacts.html', install: true, install_dir: get_option('datadir') / 'doc/git-doc', -- cgit v1.3