From: Junio C Hamano <gitster@pobox.com>
Date: Sun, 09 Oct 2022 04:41:02 GMT
Subject: Re: [PATCH v2] symbolic-ref: teach "--[no-]recurse" option
Message-ID: <xmqqr0zha9sx.fsf@gitster.g>
In-Reply-To: <CAPig+cQHw_VjbA2_HaZJj3Q0v8C6uUukr40vXFuizx4M_04XFA@mail.gmail.com>

Eric Sunshine <sunshine@sunshineco.com> writes:

> With his recent documentation-normalization work, I suspect Ævar would
> appreciate an update to the synopsis, as well:
>
>     SYNOPSIS
>     --------
>     [verse]
>     'git symbolic-ref' [-m <reason>] <name> <ref>
>    -'git symbolic-ref' [-q] [--short] <name>
>    +'git symbolic-ref' [-q] [--short] [--no-recurse] <name>
>     'git symbolic-ref' --delete [-q] <name>
>
> or something similar (i.e. plain [--recurse] or composite
> [--[no-]-recurse] or [--recurse | --no-recurse]).

Yeah, that looks good.

I checked the in-code usage that used [<options>] (hence I didn't
have to do anything new), but apparently forgot about the doc.

As there is (and there will ever be) no configuration knob for this
plumbing command to make the non-recursive behaviour the default, I
think listing [--no-recurse] alone, not [--[no-]recurse], would be
the right thing to do in the documentation.

Thanks.