From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.2 (2018-09-13) on dcvr.yhbt.net X-Spam-Level: X-Spam-ASN: AS53758 23.128.96.0/24 X-Spam-Status: No, score=-4.0 required=3.0 tests=AWL,BAYES_00,DKIM_SIGNED, DKIM_VALID,DKIM_VALID_AU,HEADER_FROM_DIFFERENT_DOMAINS, MAILING_LIST_MULTI,RCVD_IN_DNSWL_MED,SPF_HELO_PASS,SPF_PASS shortcircuit=no autolearn=ham autolearn_force=no version=3.4.2 Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by dcvr.yhbt.net (Postfix) with ESMTP id 6D8791F8C8 for ; Wed, 29 Sep 2021 21:20:37 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1346903AbhI2VWQ (ORCPT ); Wed, 29 Sep 2021 17:22:16 -0400 Received: from pb-smtp1.pobox.com ([64.147.108.70]:51328 "EHLO pb-smtp1.pobox.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S232258AbhI2VWP (ORCPT ); Wed, 29 Sep 2021 17:22:15 -0400 Received: from pb-smtp1.pobox.com (unknown [127.0.0.1]) by pb-smtp1.pobox.com (Postfix) with ESMTP id 91EF3EA705; Wed, 29 Sep 2021 17:20:33 -0400 (EDT) (envelope-from junio@pobox.com) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed; d=pobox.com; h=from:to:cc :subject:references:date:in-reply-to:message-id:mime-version :content-type:content-transfer-encoding; s=sasl; bh=ny56gaDgcpUV DmqXZc52ZjOkAkgZ9ybHYqWQC8lvTYk=; b=tid82TuvipStBKscc5N/e1JrV16l uZFK9AA09naW19yNu29BZBj/Bl4pIJVBjz1JdWisnEf6w7gI8NVg6fqXfyuXh8Ww AT+MXFf8tWDUcWP3mjtEXDpW4GA0IRQ3iyedH6pibE3IeZqO209w0U6wXgfMVv13 /KD43PjMjfzwspo= Received: from pb-smtp1.nyi.icgroup.com (unknown [127.0.0.1]) by pb-smtp1.pobox.com (Postfix) with ESMTP id 87B76EA703; Wed, 29 Sep 2021 17:20:33 -0400 (EDT) (envelope-from junio@pobox.com) Received: from pobox.com (unknown [104.133.2.91]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by pb-smtp1.pobox.com (Postfix) with ESMTPSA id E3840EA702; Wed, 29 Sep 2021 17:20:32 -0400 (EDT) (envelope-from junio@pobox.com) From: Junio C Hamano To: Carlo Marcelo Arenas =?utf-8?Q?Bel=C3=B3n?= Cc: Bagas Sanjaya , Thiago Perrotta , avarab@gmail.com, git@vger.kernel.org Subject: Re: [PATCH v5 3/3] send-email docs: add format-patch options References: <87zgs34ccx.fsf@evledraar.gmail.com> <20210924024606.20542-4-tbperrotta@gmail.com> <9a60226c-7a35-0486-a687-31f7691e7551@gmail.com> Date: Wed, 29 Sep 2021 14:20:31 -0700 In-Reply-To: ("Carlo Marcelo Arenas =?utf-8?Q?Bel=C3=B3n=22's?= message of "Fri, 24 Sep 2021 23:13:25 -0700") Message-ID: User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/27.2 (gnu/linux) MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 X-Pobox-Relay-ID: 146CC026-216B-11EC-ACAB-62A2C8D8090B-77302942!pb-smtp1.pobox.com Content-Transfer-Encoding: quoted-printable Precedence: bulk List-ID: X-Mailing-List: git@vger.kernel.org Carlo Marcelo Arenas Bel=C3=B3n writes: >> Everything after "git format-patch", i.e. -2, master, master..HEAD, >> are usable, and there isn't much point in singling out revision >> ranges. FWIW, I think you can even give "-- " at the end, >> which are not options or revision ranges. > > then it is; would the following be worth adding > in top so the recursive reference can be followed? I am not sure what "the recursive reference" is an issue here, but I agree that we may want to improve upon in the part you are touching, which currently we say: There are two ways to specify which commits to operate on. 1. A single commit, , specifies that the commits leading to the tip of the current branch that are not in the history that leads to the to be output. 2. Generic expression (see "SPECIFYING REVISIONS" section in linkgit:gitrevisions[7]) means the commits in the specified range. The first rule takes precedence in the case of a single . To apply the second rule, i.e., format everything since the beginning of history up until , use the `--root` option: `git format-patch --root `. If you want to format only itself, you can do this with `git format-patch -1 `. What we refer to in the prose, e.g. "--root" and " -1", do not appear in the SYNOPSIS section. > diff --git a/Documentation/git-format-patch.txt b/Documentation/git-for= mat-patch.txt > index fe2f69d36e..806ff93259 100644 > --- a/Documentation/git-format-patch.txt > +++ b/Documentation/git-format-patch.txt > @@ -30,7 +30,7 @@ SYNOPSIS > [--range-diff=3D [--creation-factor=3D]] > [--filename-max-length=3D] > [--progress] > - [] > + [] [] > [ | ] I think the "" you are adding here is to enhance what in the original wants to convey. In addition to things like @{u}..HEAD~2 (i.e. "the branch is mostly good, but the tip 2 commits are not yet ready so do not send them out"), you can do "-2" (i.e. "the topmost 2 commits"), which is not exactly what "SPECIFYING REVISIONS" part of gitrevisions(7) describes. So, yes, I like the spirit of the change, but no, I do not think it goes there; rather, it would replace or extend , I would think. In addition, "Generic expression (see "SPECIFYING REVISIONS" section...) may need to be updated. First, what we'd want to refer to is not ways to specify revisions, but ways to specify a range. IOW, it should be referring to "SPECIFYING RANGES" section instead. If we replace with your in the SYNOPSIS, that will fall out as a natural consequence. Perhaps, the second description and an earlier part of the explanation can be rewritten like so: 2. that specifies a range of commits (see linkgit:git-rev-list[1]) to be shown. If you give a single and nothing else, it is taken as the of the first form. If you want to format everything=20 since the beginning of history up until , use ... Thanks.