public inbox for git@vger.kernel.org 
 help / color / mirror / Atom feed

From: Junio C Hamano <gitster@pobox•com>
To: "Kristoffer Haugsbakk" <kristofferhaugsbakk@fastmail•com>
Cc: "Lino Haupt" <linojossfidel.haupt@uni-jena•de>,  git@vger•kernel.org
Subject: Re: doc: git-clone: Improve discoverability of --no-single-branch flag
Date: Wed, 30 Apr 2025 12:17:05 -0700	[thread overview]
Message-ID: <xmqqcyct1mtq.fsf@gitster.g> (raw)
In-Reply-To: <057e8f72-ea67-432b-a687-2b5af08fba05@app.fastmail.com> (Kristoffer Haugsbakk's message of "Wed, 30 Apr 2025 18:49:46 +0200")

"Kristoffer Haugsbakk" <kristofferhaugsbakk@fastmail•com> writes:

> Many options are documented as `--[no-]`.
>
>     git grep --fixed-string -- '--[no-]' Documentation/ ':(exclude)Documentation/RelNotes/'
>
> This is explained in gitcli(7), “Enhanced Option Parser” (for some
> commands), “Negating options”:
>
>        Options with long option names can be negated by prefixing
>        --no-. For example, git branch has the option --track which is on
>        by default. You can use --no-track to override that
>        behaviour. The same goes for --color and --no-color.
>
> A concern might be that changing `--single-branch` in this way would be
> inconsistent with the overall style.

A pair of quick counts:

    $ git grep -E -e '^`?--no-' Documentation/ | wc -l
    189
    $ git grep -E -e '^`?--\[no-\]' Documentation/ | wc -l
    80

I think we should try to unify to the following style:

    `--frotz=<string>`::
    `--no-frotz`::
	When `--frotz` is given, the command does THIS using the
        given argument <string> IN THIS WAY.  The default is not to
        to THIS, unless SUCH AND SUCH CONDITION, in which case THAT
        is used implicitly as <string>.  To disable THIS even when
        SUCH AND SUCH CONDITION is met, use `--no-frotz`.

That is:

 * Both positive and negative form are given separately as a
   headline item, so that "grep" would work well;

 * The description should be unified, so that it is clear to readers
   what happens when the positive form is given, when the negative
   form is given, and when neither is given.

 * Mark-up the text that the users MUST input literally inside a
   pair of backquotes.

Which means that existing "--[no-]opt::" heading should become two
lines, "`--opt`::" and "`--no-opt`::".

Thanks.

next prev parent reply	other threads:[~2025-04-30 19:17 UTC|newest]

Thread overview: 4+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2025-04-30 16:09 doc: git-clone: Improve discoverability of --no-single-branch flag Lino Haupt
2025-04-30 16:49 ` Kristoffer Haugsbakk
2025-04-30 19:17   ` Junio C Hamano [this message]
2025-05-01 18:10     ` D. Ben Knoble

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=xmqqcyct1mtq.fsf@gitster.g \
    --to=gitster@pobox$(echo .)com \
    --cc=git@vger$(echo .)kernel.org \
    --cc=kristofferhaugsbakk@fastmail$(echo .)com \
    --cc=linojossfidel.haupt@uni-jena$(echo .)de \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox