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

Commit Message

Linus Arver via GitGitGadget Jan. 7, 2020, 10:05 a.m. UTC

From: Heba Waly <[e-mail]>

Signed-off-by: Heba Waly <[e-mail]>
---
 Documentation/gitcore-tutorial.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

Comments

Eric Sunshine Jan. 7, 2020, 11:35 a.m. UTC | #1

On Tue, Jan 7, 2020 at 5:06 AM Heba Waly via GitGitGadget
<[e-mail]> wrote:
> doc: fix a typo in gitcore-tutorial.txt
>
> Signed-off-by: Heba Waly <[e-mail]>
> ---
> 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.

Junio C Hamano Jan. 7, 2020, 7:58 p.m. UTC | #2

Eric Sunshine <[e-mail]> writes:

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

Thanks for a ncie educational session ;-)

Heba Waly Jan. 8, 2020, 12:09 a.m. UTC | #3

On Wed, Jan 8, 2020 at 12:35 AM Eric Sunshine <[e-mail]> wrote:
>
>
> 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.

Looks like I overlooked this commit for its simplicity, I thought it
was too simple and self explanatory. I agree with you though.

Thanks,
Heba

Patch

diff --git a/Documentation/gitcore-tutorial.txt b/Documentation/gitcore-tutorial.txt
index f880d21dfb..c0b95256cc 100644
--- 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.
 In other words, if you have an earlier tag or branch, you'd just do
 
 ------------