Skip to contentSkip to conversation

get_maintainer: add --no-foo options to --help

PATCH In review Brian Norris 2 participants 6 messages Aug 19, 2015 – Oct 14, 2015 GET_MAINTAINER script

lore
Share & tools
lore
#0 lore raw

PATCH 1/2 get_maintainer: add --no-foo options to --help

Many flag options are boolean and support both a positive and a negative invocation from the command line. Some of these are even mentioned by example (e.g., --nogit is mentioned as a default option), but they aren't explicitly mentioned in the list of options. It happens that some of these are pretty important, as they are default-on, and to turn them off, you have to know about the --no-foo version.

Anyway, let's document them now.

---
 scripts/get_maintainer.pl | 48 +++++++++++++++++++++++------------------------
 1 file changed, 24 insertions(+), 24 deletions(-)
scripts/get_maintainer.pl +24 -24
index 98bae869f6d0..04ae47a8a5bd 100755
@@ -771,43 +771,43 @@ usage: $P [options] patchfile
 version: $V
 
 MAINTAINER field selection options:
-  --email => print email address(es) if any
-    --git => include recent git \*-by: signers
-    --git-all-signature-types => include signers regardless of signature type
+  --[no]email => print email address(es) if any
+    --[no]git => include recent git \*-by: signers
+    --[no]git-all-signature-types => include signers regardless of signature type
         or use only ${signature_pattern} signers (default: $email_git_all_signature_types)
-    --git-fallback => use git when no exact MAINTAINERS pattern (default: $email_git_fallback)
-    --git-chief-penguins => include ${penguin_chiefs}
+    --[no]git-fallback => use git when no exact MAINTAINERS pattern (default: $email_git_fallback)
+    --[no]git-chief-penguins => include ${penguin_chiefs}
     --git-min-signatures => number of signatures required (default: $email_git_min_signatures)
     --git-max-maintainers => maximum maintainers to add (default: $email_git_max_maintainers)
     --git-min-percent => minimum percentage of commits required (default: $email_git_min_percent)
-    --git-blame => use git blame to find modified commits for patch or file
+    --[no]git-blame => use git blame to find modified commits for patch or file
     --git-since => git history to use (default: $email_git_since)
     --hg-since => hg history to use (default: $email_hg_since)
-    --interactive => display a menu (mostly useful if used with the --git option)
-    --m => include maintainer(s) if any
-    --r => include reviewer(s) if any
-    --n => include name 'Full Name <addr\@domain.tld>'
-    --l => include list(s) if any
-    --s => include subscriber only list(s) if any
-    --remove-duplicates => minimize duplicate email names/addresses
-    --roles => show roles (status:subsystem, git-signer, list, etc...)
-    --rolestats => show roles and statistics (commits/total_commits, %)
-    --file-emails => add email addresses found in -f file (default: 0 (off))
-  --scm => print SCM tree(s) if any
-  --status => print status if any
-  --subsystem => print subsystem name if any
-  --web => print website(s) if any
+    --[no]interactive => display a menu (mostly useful if used with the --git option)
+    --[no]m => include maintainer(s) if any
+    --[no]r => include reviewer(s) if any
+    --[no]n => include name 'Full Name <addr\@domain.tld>'
+    --[no]l => include list(s) if any
+    --[no]s => include subscriber only list(s) if any
+    --[no]remove-duplicates => minimize duplicate email names/addresses
+    --[no]roles => show roles (status:subsystem, git-signer, list, etc...)
+    --[no]rolestats => show roles and statistics (commits/total_commits, %)
+    --[no]file-emails => add email addresses found in -f file (default: 0 (off))
+  --[no]scm => print SCM tree(s) if any
+  --[no]status => print status if any
+  --[no]subsystem => print subsystem name if any
+  --[no]web => print website(s) if any
 
 Output type options:
   --separator [, ] => separator for multiple entries on 1 line
     using --separator also sets --nomultiline if --separator is not [, ]
-  --multiline => print 1 entry per line
+  --[no]multiline => print 1 entry per line
 
 Other options:
   --pattern-depth => Number of pattern directory traversals (default: 0 (all))
-  --keywords => scan patch for keywords (default: $keywords)
-  --sections => print all of the subsystem sections with pattern matches
-  --mailmap => use .mailmap file (default: $email_use_mailmap)
+  --[no]keywords => scan patch for keywords (default: $keywords)
+  --[no]sections => print all of the subsystem sections with pattern matches
+  --[no]mailmap => use .mailmap file (default: $email_use_mailmap)
   --version => show version
   --help => show this help information
 
Signature · 1 line
2.5.0.276.gf5e568e
#1 lore raw

PATCH 2/2 get_maintainer: add missing documentation for --[no]git-blame-signatures

I really haven't used this option much myself, so feel free to improve on the documentation for it.

---
 scripts/get_maintainer.pl | 1 +
 1 file changed, 1 insertion(+)
scripts/get_maintainer.pl +1 -0
index 04ae47a8a5bd..a57b4d462360 100755
@@ -781,6 +781,7 @@ MAINTAINER field selection options:
     --git-max-maintainers => maximum maintainers to add (default: $email_git_max_maintainers)
     --git-min-percent => minimum percentage of commits required (default: $email_git_min_percent)
     --[no]git-blame => use git blame to find modified commits for patch or file
+    --[no]git-blame-signatures => like --git-blame, but include all commit signers
     --git-since => git history to use (default: $email_git_since)
     --hg-since => hg history to use (default: $email_hg_since)
     --[no]interactive => display a menu (mostly useful if used with the --git option)
Signature · 1 line
2.5.0.276.gf5e568e
#2 lore raw
In reply to Brian Norris

Ping? Should I resend?

Quoted 89 lines · Brian Norris

Many flag options are boolean and support both a positive and a negative invocation from the command line. Some of these are even mentioned by example (e.g., --nogit is mentioned as a default option), but they aren't explicitly mentioned in the list of options. It happens that some of these are pretty important, as they are default-on, and to turn them off, you have to know about the --no-foo version.

Anyway, let's document them now.

---
 scripts/get_maintainer.pl | 48 +++++++++++++++++++++++------------------------
 1 file changed, 24 insertions(+), 24 deletions(-)
scripts/get_maintainer.pl +24 -24
index 98bae869f6d0..04ae47a8a5bd 100755
@@ -771,43 +771,43 @@ usage: $P [options] patchfile
 version: $V
 
 MAINTAINER field selection options:
-  --email => print email address(es) if any
-    --git => include recent git \*-by: signers
-    --git-all-signature-types => include signers regardless of signature type
+  --[no]email => print email address(es) if any
+    --[no]git => include recent git \*-by: signers
+    --[no]git-all-signature-types => include signers regardless of signature type
         or use only ${signature_pattern} signers (default: $email_git_all_signature_types)
-    --git-fallback => use git when no exact MAINTAINERS pattern (default: $email_git_fallback)
-    --git-chief-penguins => include ${penguin_chiefs}
+    --[no]git-fallback => use git when no exact MAINTAINERS pattern (default: $email_git_fallback)
+    --[no]git-chief-penguins => include ${penguin_chiefs}
     --git-min-signatures => number of signatures required (default: $email_git_min_signatures)
     --git-max-maintainers => maximum maintainers to add (default: $email_git_max_maintainers)
     --git-min-percent => minimum percentage of commits required (default: $email_git_min_percent)
-    --git-blame => use git blame to find modified commits for patch or file
+    --[no]git-blame => use git blame to find modified commits for patch or file
     --git-since => git history to use (default: $email_git_since)
     --hg-since => hg history to use (default: $email_hg_since)
-    --interactive => display a menu (mostly useful if used with the --git option)
-    --m => include maintainer(s) if any
-    --r => include reviewer(s) if any
-    --n => include name 'Full Name <addr\@domain.tld>'
-    --l => include list(s) if any
-    --s => include subscriber only list(s) if any
-    --remove-duplicates => minimize duplicate email names/addresses
-    --roles => show roles (status:subsystem, git-signer, list, etc...)
-    --rolestats => show roles and statistics (commits/total_commits, %)
-    --file-emails => add email addresses found in -f file (default: 0 (off))
-  --scm => print SCM tree(s) if any
-  --status => print status if any
-  --subsystem => print subsystem name if any
-  --web => print website(s) if any
+    --[no]interactive => display a menu (mostly useful if used with the --git option)
+    --[no]m => include maintainer(s) if any
+    --[no]r => include reviewer(s) if any
+    --[no]n => include name 'Full Name <addr\@domain.tld>'
+    --[no]l => include list(s) if any
+    --[no]s => include subscriber only list(s) if any
+    --[no]remove-duplicates => minimize duplicate email names/addresses
+    --[no]roles => show roles (status:subsystem, git-signer, list, etc...)
+    --[no]rolestats => show roles and statistics (commits/total_commits, %)
+    --[no]file-emails => add email addresses found in -f file (default: 0 (off))
+  --[no]scm => print SCM tree(s) if any
+  --[no]status => print status if any
+  --[no]subsystem => print subsystem name if any
+  --[no]web => print website(s) if any
 
 Output type options:
   --separator [, ] => separator for multiple entries on 1 line
     using --separator also sets --nomultiline if --separator is not [, ]
-  --multiline => print 1 entry per line
+  --[no]multiline => print 1 entry per line
 
 Other options:
   --pattern-depth => Number of pattern directory traversals (default: 0 (all))
-  --keywords => scan patch for keywords (default: $keywords)
-  --sections => print all of the subsystem sections with pattern matches
-  --mailmap => use .mailmap file (default: $email_use_mailmap)
+  --[no]keywords => scan patch for keywords (default: $keywords)
+  --[no]sections => print all of the subsystem sections with pattern matches
+  --[no]mailmap => use .mailmap file (default: $email_use_mailmap)
   --version => show version
   --help => show this help information
 
Signature · 1 line
2.5.0.276.gf5e568e
maintainer
#3 lore raw
Quoted 1 line · Brian Norris

Ping? Should I resend?

I don't have a strong opinion about this.

It seems the [no] blocks make the generic options more difficult to read.

If you do resend, please cc "Andrew Morton <[email protected]>"

Quoted 90 lines · Brian Norris
Quoted 89 lines

Many flag options are boolean and support both a positive and a negative invocation from the command line. Some of these are even mentioned by example (e.g., --nogit is mentioned as a default option), but they aren't explicitly mentioned in the list of options. It happens that some of these are pretty important, as they are default-on, and to turn them off, you have to know about the --no-foo version.

Anyway, let's document them now.

---
 scripts/get_maintainer.pl | 48 +++++++++++++++++++++++------------------------
 1 file changed, 24 insertions(+), 24 deletions(-)
scripts/get_maintainer.pl +24 -24
index 98bae869f6d0..04ae47a8a5bd 100755
@@ -771,43 +771,43 @@ usage: $P [options] patchfile
 version: $V
 
 MAINTAINER field selection options:
-  --email => print email address(es) if any
-    --git => include recent git \*-by: signers
-    --git-all-signature-types => include signers regardless of signature type
+  --[no]email => print email address(es) if any
+    --[no]git => include recent git \*-by: signers
+    --[no]git-all-signature-types => include signers regardless of signature type
         or use only ${signature_pattern} signers (default: $email_git_all_signature_types)
-    --git-fallback => use git when no exact MAINTAINERS pattern (default: $email_git_fallback)
-    --git-chief-penguins => include ${penguin_chiefs}
+    --[no]git-fallback => use git when no exact MAINTAINERS pattern (default: $email_git_fallback)
+    --[no]git-chief-penguins => include ${penguin_chiefs}
     --git-min-signatures => number of signatures required (default: $email_git_min_signatures)
     --git-max-maintainers => maximum maintainers to add (default: $email_git_max_maintainers)
     --git-min-percent => minimum percentage of commits required (default: $email_git_min_percent)
-    --git-blame => use git blame to find modified commits for patch or file
+    --[no]git-blame => use git blame to find modified commits for patch or file
     --git-since => git history to use (default: $email_git_since)
     --hg-since => hg history to use (default: $email_hg_since)
-    --interactive => display a menu (mostly useful if used with the --git option)
-    --m => include maintainer(s) if any
-    --r => include reviewer(s) if any
-    --n => include name 'Full Name <addr\@domain.tld>'
-    --l => include list(s) if any
-    --s => include subscriber only list(s) if any
-    --remove-duplicates => minimize duplicate email names/addresses
-    --roles => show roles (status:subsystem, git-signer, list, etc...)
-    --rolestats => show roles and statistics (commits/total_commits, %)
-    --file-emails => add email addresses found in -f file (default: 0 (off))
-  --scm => print SCM tree(s) if any
-  --status => print status if any
-  --subsystem => print subsystem name if any
-  --web => print website(s) if any
+    --[no]interactive => display a menu (mostly useful if used with the --git option)
+    --[no]m => include maintainer(s) if any
+    --[no]r => include reviewer(s) if any
+    --[no]n => include name 'Full Name <addr\@domain.tld>'
+    --[no]l => include list(s) if any
+    --[no]s => include subscriber only list(s) if any
+    --[no]remove-duplicates => minimize duplicate email names/addresses
+    --[no]roles => show roles (status:subsystem, git-signer, list, etc...)
+    --[no]rolestats => show roles and statistics (commits/total_commits, %)
+    --[no]file-emails => add email addresses found in -f file (default: 0 (off))
+  --[no]scm => print SCM tree(s) if any
+  --[no]status => print status if any
+  --[no]subsystem => print subsystem name if any
+  --[no]web => print website(s) if any
 
 Output type options:
   --separator [, ] => separator for multiple entries on 1 line
     using --separator also sets --nomultiline if --separator is not [, ]
-  --multiline => print 1 entry per line
+  --[no]multiline => print 1 entry per line
 
 Other options:
   --pattern-depth => Number of pattern directory traversals (default: 0 (all))
-  --keywords => scan patch for keywords (default: $keywords)
-  --sections => print all of the subsystem sections with pattern matches
-  --mailmap => use .mailmap file (default: $email_use_mailmap)
+  --[no]keywords => scan patch for keywords (default: $keywords)
+  --[no]sections => print all of the subsystem sections with pattern matches
+  --[no]mailmap => use .mailmap file (default: $email_use_mailmap)
   --version => show version
   --help => show this help information
 
Signature · 1 line
2.5.0.276.gf5e568e
#4 lore raw

+ akpm

Quoted 7 lines · Joe Perches
Quoted 1 line · Brian Norris

Ping? Should I resend?

I don't have a strong opinion about this.

It seems the [no] blocks make the generic options more difficult to read.

The '[no]' formatting is similar to how some (but not all) man pages do this. If it is too difficult, I'm open to something else. Just a note somewhere that all boolean options have equivalent '--no<foo>' options?

BTW, one thing I didn't note in the commit message is that this is important because some options are already *on* by default, and so it is only sensible to use the --no version, which isn't even documented. Particularly, options like --norolestats.

Brian

Quoted 95 lines

If you do resend, please cc "Andrew Morton <[email protected]>"

Quoted 90 lines · Brian Norris
Quoted 89 lines

Many flag options are boolean and support both a positive and a negative invocation from the command line. Some of these are even mentioned by example (e.g., --nogit is mentioned as a default option), but they aren't explicitly mentioned in the list of options. It happens that some of these are pretty important, as they are default-on, and to turn them off, you have to know about the --no-foo version.

Anyway, let's document them now.

---
 scripts/get_maintainer.pl | 48 +++++++++++++++++++++++------------------------
 1 file changed, 24 insertions(+), 24 deletions(-)
scripts/get_maintainer.pl +24 -24
index 98bae869f6d0..04ae47a8a5bd 100755
@@ -771,43 +771,43 @@ usage: $P [options] patchfile
 version: $V
 
 MAINTAINER field selection options:
-  --email => print email address(es) if any
-    --git => include recent git \*-by: signers
-    --git-all-signature-types => include signers regardless of signature type
+  --[no]email => print email address(es) if any
+    --[no]git => include recent git \*-by: signers
+    --[no]git-all-signature-types => include signers regardless of signature type
         or use only ${signature_pattern} signers (default: $email_git_all_signature_types)
-    --git-fallback => use git when no exact MAINTAINERS pattern (default: $email_git_fallback)
-    --git-chief-penguins => include ${penguin_chiefs}
+    --[no]git-fallback => use git when no exact MAINTAINERS pattern (default: $email_git_fallback)
+    --[no]git-chief-penguins => include ${penguin_chiefs}
     --git-min-signatures => number of signatures required (default: $email_git_min_signatures)
     --git-max-maintainers => maximum maintainers to add (default: $email_git_max_maintainers)
     --git-min-percent => minimum percentage of commits required (default: $email_git_min_percent)
-    --git-blame => use git blame to find modified commits for patch or file
+    --[no]git-blame => use git blame to find modified commits for patch or file
     --git-since => git history to use (default: $email_git_since)
     --hg-since => hg history to use (default: $email_hg_since)
-    --interactive => display a menu (mostly useful if used with the --git option)
-    --m => include maintainer(s) if any
-    --r => include reviewer(s) if any
-    --n => include name 'Full Name <addr\@domain.tld>'
-    --l => include list(s) if any
-    --s => include subscriber only list(s) if any
-    --remove-duplicates => minimize duplicate email names/addresses
-    --roles => show roles (status:subsystem, git-signer, list, etc...)
-    --rolestats => show roles and statistics (commits/total_commits, %)
-    --file-emails => add email addresses found in -f file (default: 0 (off))
-  --scm => print SCM tree(s) if any
-  --status => print status if any
-  --subsystem => print subsystem name if any
-  --web => print website(s) if any
+    --[no]interactive => display a menu (mostly useful if used with the --git option)
+    --[no]m => include maintainer(s) if any
+    --[no]r => include reviewer(s) if any
+    --[no]n => include name 'Full Name <addr\@domain.tld>'
+    --[no]l => include list(s) if any
+    --[no]s => include subscriber only list(s) if any
+    --[no]remove-duplicates => minimize duplicate email names/addresses
+    --[no]roles => show roles (status:subsystem, git-signer, list, etc...)
+    --[no]rolestats => show roles and statistics (commits/total_commits, %)
+    --[no]file-emails => add email addresses found in -f file (default: 0 (off))
+  --[no]scm => print SCM tree(s) if any
+  --[no]status => print status if any
+  --[no]subsystem => print subsystem name if any
+  --[no]web => print website(s) if any
 
 Output type options:
   --separator [, ] => separator for multiple entries on 1 line
     using --separator also sets --nomultiline if --separator is not [, ]
-  --multiline => print 1 entry per line
+  --[no]multiline => print 1 entry per line
 
 Other options:
   --pattern-depth => Number of pattern directory traversals (default: 0 (all))
-  --keywords => scan patch for keywords (default: $keywords)
-  --sections => print all of the subsystem sections with pattern matches
-  --mailmap => use .mailmap file (default: $email_use_mailmap)
+  --[no]keywords => scan patch for keywords (default: $keywords)
+  --[no]sections => print all of the subsystem sections with pattern matches
+  --[no]mailmap => use .mailmap file (default: $email_use_mailmap)
   --version => show version
   --help => show this help information
 
Signature · 1 line
2.5.0.276.gf5e568e
maintainer
#5 lore raw
Quoted 11 lines · Brian Norris

+ akpm

Quoted 7 lines · Joe Perches
Quoted 1 line · Brian Norris

Ping? Should I resend?

I don't have a strong opinion about this.

It seems the [no] blocks make the generic options more difficult to read.

Quoted 8 lines

The '[no]' formatting is similar to how some (but not all) man pages do this. If it is too difficult, I'm open to something else. Just a note somewhere that all boolean options have equivalent '--no<foo>' options?

BTW, one thing I didn't note in the commit message is that this is important because some options are already *on* by default, and so it is only sensible to use the --no version, which isn't even documented. Particularly, options like --norolestats.

Maybe using something like gcc's documentation of options that have negative forms might be better.

$ man gcc
...
Most of these have both positive and negative forms;
the negative form of -ffoo is -fno-foo
...
$