Re: [PATCH 1/1] doc: fix a typo in gitcore-tutorial.txt

From: Eric Sunshine <sunshine@sunshineco.com>
Date: Jan 7, 2020, 11:35 UTC
Message-ID: <CAPig+cTv5SOxEjjVQ7QvqJ1WbZGbcXegcCP4d5CK+nSdJvkNdQ@mail.gmail.com>
In-Reply-To: <ee8636e0ed40888b2a132cff2dacc97754550ba1.1578391553.git.gitgitgadget@gmail.com>

On Tue, Jan 7, 2020 at 5:06 AM Heba Waly via GitGitGadget <gitgitgadget@gmail.com> wrote:

Show 11 quoted lines

> doc: fix a typo in gitcore-tutorial.txt
>
> Signed-off-by: Heba Waly <heba.waly@gmail.com>
> ---
> diff --git a/Documentation/gitcore-tutorial.txt b/Documentation/gitcore-tutorial.txt
> @@ -751,7 +751,7 @@ to it.
>  ================================================
>  If you make the decision to start your new branch at some
>  other point in the history than the current `HEAD`, you can do so by
> -just telling 'git checkout' what the base of the checkout would be.
> +just telling 'git switch' what the base of the checkout would be.

Calling this change a "typo fix" confuses reviewers since it's clearly not a mere typographical error. It looks instead as if you are recommending git-switch over git-checkout, so a reader would expect the commit message to justify that change rather than merely calling it a "typo fix". However, digging deeper, one finds that this is actually fixing an oversight from an earlier change which already updated this file to prefer git-switch over git-checkout.

To save reviewers the time and effort of having to figure all this out, use the commit message to explain the situation. For example, you might say:

    doc/gitcore-tutorial: fix prose to match example command

    In 328c6cb853 (doc: promote "git switch", 2019-03-29), an example
    was changed to use "git switch" rather than "git checkout" but an
    instance of "git checkout" in the explanatory text preceding the
    example was overlooked. Fix this oversight.