Re: [PATCH 6/6] Documentation: call out commands that nuke untracked files/directories

From: Elijah Newren <newren@gmail.com>
Date: Sep 20, 2021, 16:29 UTC
Message-ID: <CABPp-BEVDs4rRGV3WzeK929CwhefhwwyodSs6=5iP0-dt3cUKg@mail.gmail.com>
In-Reply-To: <f5b88c2f-b265-9342-4227-886049ad7bce@iee.email>

On Sun, Sep 19, 2021 at 6:36 AM Philip Oakley <philipoakley@iee.email> wrote:

Show 30 quoted lines

>
> On 19/09/2021 11:52, Philip Oakley wrote:
> > truly minor nit.
> > On 19/09/2021 00:15, Elijah Newren via GitGitGadget wrote:
> >> From: Elijah Newren <newren@gmail.com>
> >>
> >> Some commands have traditionally also removed untracked files (or
> >> directories) that were in the way of a tracked file we needed.  Document
> >> these cases.
> >>
> >> Signed-off-by: Elijah Newren <newren@gmail.com>
> >> ---
> >>  Documentation/git-checkout.txt  | 5 +++--
> >>  Documentation/git-read-tree.txt | 5 +++--
> >>  Documentation/git-reset.txt     | 3 ++-
> >>  3 files changed, 8 insertions(+), 5 deletions(-)
> >>
> >> diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt
> >> index b1a6fe44997..d473c9bf387 100644
> >> --- a/Documentation/git-checkout.txt
> >> +++ b/Documentation/git-checkout.txt
> >> @@ -118,8 +118,9 @@ OPTIONS
> >>  -f::
> >>  --force::
> >>      When switching branches, proceed even if the index or the
> >> -    working tree differs from `HEAD`.  This is used to throw away
> >> -    local changes.
> >> +    working tree differs from `HEAD`, and even if there are untracked
> >> +    files in the way.  This is used to throw away local changes and
> > double space after full stop?

Note that the original also had a double space after full stop (looking at the previous sentence).

Show 19 quoted lines

> >> +    any untracked files or directories that are in the way.
> >>  +
> >>  When checking out paths from the index, do not fail upon unmerged
> >>  entries; instead, unmerged entries are ignored.
> >> diff --git a/Documentation/git-read-tree.txt b/Documentation/git-read-tree.txt
> >> index 5fa8bab64c2..4731ec3283f 100644
> >> --- a/Documentation/git-read-tree.txt
> >> +++ b/Documentation/git-read-tree.txt
> >> @@ -39,8 +39,9 @@ OPTIONS
> >>
> >>  --reset::
> >>      Same as -m, except that unmerged entries are discarded instead
> >> -    of failing. When used with `-u`, updates leading to loss of
> >> -    working tree changes will not abort the operation.
> >> +    of failing.  When used with `-u`, updates leading to loss of
> > Is the single space to double space change desired?
> > I had the impression that the project had decided on single spaces, but
> > I can't see anything in SubmittingPatches or CodingGuidelines. I don't
> > think there are DocumentationGuidelines.

Double space is better as per Junio's declaration here: https://lore.kernel.org/git/xmqqftchkext.fsf@gitster.c.googlers.com/

However, it's so minor that I wouldn't normally bother to change it specifically. In this case, I originally was tweaking the sentence before as well, and when modifying both sentences I just naturally put two spaces after the full stop between them. But then I re-read and decided to reword and ended up restoring the original first sentence and didn't even notice that resulted in a change of spacing at the end of the sentence.

Show 9 quoted lines

> I may have been mistaken about any project decision. I had a look around
> the archives and only came up with a 2008 post [1] by Junio that, at the
> time, was looking for two spaces after the full stop.
>
> It's not clear if we consider the man pages to be 'typeset' such that a
> single space would be the norm, or mono-spaced 'typewriter' style (two
> spaces). There's much commentary in the Wikipedia article [2].
>
> So still minor.

Yes, the double space is "more correct" in the sources as per Junio's declaration in the link I provided above, but I agree it's pretty minor.

> [1] https://lore.kernel.org/git/7vfxtu3fku.fsf@gitster.siamese.dyndns.org/
> [2] https://en.wikipedia.org/wiki/Sentence_spacing