From: Junio C Hamano <gitster@pobox•com>
To: "Martin Ågren" <martin.agren@gmail•com>
Cc: git@vger•kernel.org
Subject: Re: [PATCH 2/2] gittutorial: wrap literal examples in backticks
Date: Thu, 20 Apr 2023 14:33:16 -0700 [thread overview]
Message-ID: <xmqqedoexmqr.fsf@gitster.g> (raw)
In-Reply-To: <280c7d18b99e7cfc882d0dad0de536d4f40d4338.1681579244.git.martin.agren@gmail.com> ("Martin Ågren"'s message of "Sat, 15 Apr 2023 19:29:11 +0200")
Martin Ågren <martin.agren@gmail•com> writes:
> Our coding guidelines prefer literal examples to be wrapped in
> `backticks` to typeset them in monospace.
True.
Everything I saw in this patch looked reasonable. Except for one
minor thing that I found a bit iffy.
> ------------------------------------------------
> alice$ cd /home/alice/project
> alice$ git pull /home/bob/myrepo master
> ------------------------------------------------
>
> -This merges the changes from Bob's "master" branch into Alice's
> +This merges the changes from Bob's `master` branch into Alice's
> current branch. If Alice has made her own changes in the meantime,
> then she may need to manually fix any conflicts.
>
> -The "pull" command thus performs two operations: it fetches changes
> +The `pull` command thus performs two operations: it fetches changes
> from a remote branch, then merges them into the current branch.
We use the name of an operation (e.g. "pull", "fetch", ...) to
refer to a specific command name and also as a general concept. The
former should be in `pair of backticks`, but not the latter.
Unfortunately, there is no bright line between the two.
It is OK to say that this "pull" refers to the command line we see
above, i.e. "git pull", but ...
> Note that in general, Alice would want her local changes committed before
> -initiating this "pull". If Bob's work conflicts with what Alice did since
> +initiating this `pull`. If Bob's work conflicts with what Alice did since
... it is unclear if this one should be taken as a "literal
example". It may flow more naturally if we take it as the name of
general concept of one operation, as ...
> their histories forked, Alice will use her working tree and the index to
> resolve conflicts, and existing local changes will interfere with the
> conflict resolution process (Git will still perform the fetch but will
> refuse to merge -- Alice will have to get rid of her local changes in
... it contrasts with the "fetch" operation and the "merge"
operation referred to here a bit better, it seems. The same for the
reference of `fetch` in the next paragraph.
> some way and pull again when this happens).
>
> -Alice can peek at what Bob did without merging first, using the "fetch"
> +Alice can peek at what Bob did without merging first, using the `fetch`
> command; this allows Alice to inspect what Bob did, using a special
> -symbol "FETCH_HEAD", in order to determine if he has anything worth
> +symbol `FETCH_HEAD`, in order to determine if he has anything worth
> pulling, like this:
But as I said, it is quite minor and I am not even convinced it is
wrong, so let's take the whole thing as is and merge it down.
Thanks.
prev parent reply other threads:[~2023-04-20 21:33 UTC|newest]
Thread overview: 5+ messages / expand[flat|nested] mbox.gz Atom feed top
2023-04-15 17:29 [PATCH 0/2] gittutorial: minor correction and monospacing Martin Ågren
2023-04-15 17:29 ` [PATCH 1/2] gittutorial: drop early mention of origin Martin Ågren
2023-04-20 21:15 ` Junio C Hamano
2023-04-15 17:29 ` [PATCH 2/2] gittutorial: wrap literal examples in backticks Martin Ågren
2023-04-20 21:33 ` Junio C Hamano [this message]
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=xmqqedoexmqr.fsf@gitster.g \
--to=gitster@pobox$(echo .)com \
--cc=git@vger$(echo .)kernel.org \
--cc=martin.agren@gmail$(echo .)com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox