* [RFC PATCH] Using no- for options instead of duplication
@ 2018-11-12 18:59 Fredi Fowler
2018-11-13 4:37 ` Junio C Hamano
0 siblings, 1 reply; 4+ messages in thread
From: Fredi Fowler @ 2018-11-12 18:59 UTC (permalink / raw)
To: git
---
Documentation/merge-options.txt | 21 +++++++--------------
1 file changed, 7 insertions(+), 14 deletions(-)
diff --git a/Documentation/merge-options.txt b/Documentation/merge-options.txt
index 63a3fc09548ab..fc1122ded51a0 100644
--- a/Documentation/merge-options.txt
+++ b/Documentation/merge-options.txt
@@ -1,5 +1,4 @@
---commit::
---no-commit::
+--[no-]commit::
Perform the merge and commit the result. This option can
be used to override --no-commit.
+
@@ -7,9 +6,8 @@ With --no-commit perform the merge but pretend the merge
failed and do not autocommit, to give the user a chance to
inspect and further tweak the merge result before committing.
---edit::
-e::
---no-edit::
+--[no-]edit::
Invoke an editor before committing successful mechanical merge to
further edit the auto-generated merge message, so that the user
can explain and justify the merge. The `--no-edit` option can be
@@ -58,8 +56,7 @@ set to `no` at the beginning of them.
With --no-log do not list one-line descriptions from the
actual commits being merged.
---signoff::
---no-signoff::
+--[no-]signoff::
Add Signed-off-by line by the committer at the end of the commit
log message. The meaning of a signoff depends on the project,
but it typically certifies that committer has
@@ -69,17 +66,15 @@ actual commits being merged.
+
With --no-signoff do not add a Signed-off-by line.
---stat::
-n::
---no-stat::
+--[no-]stat::
Show a diffstat at the end of the merge. The diffstat is also
controlled by the configuration option merge.stat.
+
With -n or --no-stat do not show a diffstat at the end of the
merge.
---squash::
---no-squash::
+--[no-]squash::
Produce the working tree and index state as if a real merge
happened (except for the merge information), but do not actually
make a commit, move the `HEAD`, or record `$GIT_DIR/MERGE_HEAD`
@@ -112,8 +107,7 @@ option can be used to override --squash.
a trusted key. If the tip commit of the side branch is not signed
with a valid key, the merge is aborted.
---summary::
---no-summary::
+--[no-]summary::
Synonyms to --stat and --no-stat; these are deprecated and will be
removed in the future.
@@ -126,8 +120,7 @@ ifndef::git-pull[]
--verbose::
Be verbose.
---progress::
---no-progress::
+--[no-]progress::
Turn progress on/off explicitly. If neither is specified,
progress is shown if standard error is connected to a terminal.
Note that not all merge strategies may support progress
--
https://github.com/git/git/pull/553
^ permalink raw reply related [flat|nested] 4+ messages in thread
* Re: [RFC PATCH] Using no- for options instead of duplication
2018-11-12 18:59 [RFC PATCH] Using no- for options instead of duplication Fredi Fowler
@ 2018-11-13 4:37 ` Junio C Hamano
2018-11-13 10:18 ` Ævar Arnfjörð Bjarmason
0 siblings, 1 reply; 4+ messages in thread
From: Junio C Hamano @ 2018-11-13 4:37 UTC (permalink / raw)
To: Fredi Fowler; +Cc: git
Fredi Fowler <inredikawb@gmail.com> writes:
Here is a space for you to justify the change and sign off your
patch (see Documentation/SubmittingPatches).
> ---
> Subject: Re: [RFC PATCH] Using no- for options instead of duplication
Try to see if you can format the title in "<area>: <explanation>"
form first, please. I'll come back to it later.
> Documentation/merge-options.txt | 21 +++++++--------------
> 1 file changed, 7 insertions(+), 14 deletions(-)
A quick counting (which may count false positives) tells me that
$ git grep -e '^--no-' Documentation | wc -l
124
$ git grep -e '^--\[no-' Documentation | wc -l
44
you are standardizing to the minority way.
A tangent that somebody might want to tackle. It would be
nice if we had a tool that takes a grep expression (like
'^--no' and '^\[no-' above) and shows histograms of the ages
of lines that match. It might tell us that all 44 combined
ones are more recent (some of them may even have been
updated from the separate form) than the 124 separate ones,
in which case we can say "we started the process of
migrating to list options singly, like '--[no-]option', in
commit X; let's continue doing so" in the log message. Or
it may turn out that we have been going in the other
direction and most of these 44 are stale ones yet to be
split. Without such a tool, the above numbers are the best
measure to go by, which is not quite ideal.
As there are tons of split ones, not just in merge-options.txt, I
suspect that the <area> of the change can just be "doc", so a good
title may be
Subject: [PATCH] doc: list negative options as --[no-]option
or something like that.
If going in the direction of this patch were a good idea, that is.
I am actually not sure if it is a good idea, especially given that
the only change is the enumeration headers and without adjustment to
the text, though.
> diff --git a/Documentation/merge-options.txt b/Documentation/merge-options.txt
> index 63a3fc09548ab..fc1122ded51a0 100644
> --- a/Documentation/merge-options.txt
> +++ b/Documentation/merge-options.txt
> @@ -1,5 +1,4 @@
> ---commit::
> ---no-commit::
> +--[no-]commit::
> Perform the merge and commit the result. This option can
> be used to override --no-commit.
> +
> ...
> With --no-commit perform the merge but pretend the merge
> failed and do not autocommit, to give the user a chance to
> inspect and further tweak the merge result before committing.
For example, the original for this one gives the behaviour for --commit
and --no-commit separately, and it visually makes it easier to see two
distinct header items.
Description of some other options read OK either way, which would
justify not touching the description when combining two headings
into one. But that still does not justify the combining in the
first place.
FWIW, "git help -m merge" begins its OPTIONS section like this:
OPTIONS
--commit, --no-commit
Perform the merge and commit the result. This option can be used to
override --no-commit.
With --no-commit perform the merge but pretend the merge failed and
do not autocommit, to give the user a chance to inspect and further
tweak the merge result before committing.
which is different from heading with a single "--[no-]commit", but I
do not quite see why a single squished form is preferrable. It does
not save lines, and it forces readers to split and reassemble two
options in their head while reading.
^ permalink raw reply [flat|nested] 4+ messages in thread
* Re: [RFC PATCH] Using no- for options instead of duplication
2018-11-13 4:37 ` Junio C Hamano
@ 2018-11-13 10:18 ` Ævar Arnfjörð Bjarmason
2018-11-13 13:09 ` Junio C Hamano
0 siblings, 1 reply; 4+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2018-11-13 10:18 UTC (permalink / raw)
To: Junio C Hamano; +Cc: Fredi Fowler, git
On Tue, Nov 13 2018, Junio C Hamano wrote:
> A tangetn that somebody might want to tackle. It would be
> nice if we had a tool that takes a grep expression (like
> '^--no' and '^\[no-' above) and shows histograms of the ages
> of lines that match. It might tell us that all 44 combined
> ones are more recent (some of them may even have been
> updated from the separate form) than the 124 separate ones,
> in which case we can say "we started the process of
> migrating to list options singly, like '--[no-]option', in
> commit X; let's continue doing so" in the log message. Or
> it may turn out that we have been going in the other
> direction and most of these 44 are stale ones yet to be
> split. Without such a tool, the above numbers are the best
> measure to go by, which is not quite ideal.
This doesn't spew out a histogram, but you can use the various "git
grep/blame" one-liners (https://www.google.nl/search?q=git+grep+blame)
plus shell one-liner to get something useful:
git grep -e '^--no-' -e '^--\[no-' -n | perl -F':' -anpe '$_=`git blame -L$F[1],+1 $F[0]`' | perl -pe 's/^.* (\d{4})-.*\) /$1 /' | sort -n
^ permalink raw reply [flat|nested] 4+ messages in thread
* Re: [RFC PATCH] Using no- for options instead of duplication
2018-11-13 10:18 ` Ævar Arnfjörð Bjarmason
@ 2018-11-13 13:09 ` Junio C Hamano
0 siblings, 0 replies; 4+ messages in thread
From: Junio C Hamano @ 2018-11-13 13:09 UTC (permalink / raw)
To: Ævar Arnfjörð Bjarmason; +Cc: Fredi Fowler, git
Ævar Arnfjörð Bjarmason <avarab@gmail.com> writes:
> This doesn't spew out a histogram, but you can use the various "git
> grep/blame" one-liners (https://www.google.nl/search?q=git+grep+blame)
> plus shell one-liner to get something useful:
>
> git grep -e '^--no-' -e '^--\[no-' -n | perl -F':' -anpe '$_=`git blame -L$F[1],+1 $F[0]`' | perl -pe 's/^.* (\d{4})-.*\) /$1 /' | sort -n
Yikes. I cannot easily unsee this X-<.
^ permalink raw reply [flat|nested] 4+ messages in thread
end of thread, other threads:[~2018-11-13 13:09 UTC | newest]
Thread overview: 4+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2018-11-12 18:59 [RFC PATCH] Using no- for options instead of duplication Fredi Fowler
2018-11-13 4:37 ` Junio C Hamano
2018-11-13 10:18 ` Ævar Arnfjörð Bjarmason
2018-11-13 13:09 ` Junio C Hamano
Code repositories for project(s) associated with this public inbox
https://80x24.org/mirrors/git.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).