Re: [PATCH v2] symbolic-ref: teach "--[no-]recurse" option

From: Junio C Hamano <gitster@pobox.com>
Date: Oct 9, 2022, 04:41 UTC
Message-ID: <xmqqr0zha9sx.fsf@gitster.g>
In-Reply-To: <CAPig+cQHw_VjbA2_HaZJj3Q0v8C6uUukr40vXFuizx4M_04XFA@mail.gmail.com>

Eric Sunshine <sunshine@sunshineco.com> writes:

Show 13 quoted lines

> 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.