From: Eric Sunshine <sunshine@sunshineco.com>
Date: Thu, 24 May 2018 19:53:57 GMT
Subject: Re: [PATCH 2/4] config doc: unify the description of fsck.* and receive.fsck.*
Message-ID: <CAPig+cTr2J6yj39NNdV1vT8CQP2qyPxNB1ggaE9bGgXukuq1yQ@mail.gmail.com>
In-Reply-To: <20180524193516.28713-3-avarab@gmail.com>

On Thu, May 24, 2018 at 3:35 PM, Ævar Arnfjörð Bjarmason
<avarab@gmail.com> wrote:
> The documentation for the fsck.<msg-id> and receive.fsck.<msg-id>
> variables was mostly duplicated in two places, with fsck.<msg-id>
> making no mention of the corresponding receive.fsck.<msg-id>, and the
> same for fsck.skipList.
> [...]
> Rectify this situation by describing the feature in general terms
> under the fsck.* documentation, and make the receive.fsck.*
> documentation refer to those variables instead.
> [...]
> Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
> ---
> diff --git a/Documentation/config.txt b/Documentation/config.txt
> @@ -1554,23 +1554,41 @@ filter.<driver>.smudge::
>  fsck.skipList::
> -       The path to a sorted list of object names (i.e. one SHA-1 per
> -       line) that are known to be broken in a non-fatal way and should
> -       be ignored. This feature is useful when an established project
> -       should be accepted despite early commits containing errors that
> -       can be safely ignored such as invalid committer email addresses.
> -       Note: corrupt objects cannot be skipped with this setting.
> +       Like `fsck.<msg-id>` this variable has a corresponding
> +       `receive.fsck.skipList` variant.
> ++
> +The path to a sorted list of object names (i.e. one SHA-1 per line)
> +that are known to be broken in a non-fatal way and should be
> +ignored. This feature is useful when an established project should be
> +accepted despite early commits containing errors that can be safely
> +ignored such as invalid committer email addresses. Note: corrupt
> +objects cannot be skipped with this setting.

Nit: This organization seems backward. Typically, one would describe
what the option is for and then add the incidental note ("Like
fsck.<...>, this variable...") at the end. It's not clear why this
patch demotes the description to a secondary paragraph and considers
the incidental note as primary.