Re: [PATCH v2 1/6] doc: add new gitmergeconflicts man page

From: Junio C Hamano <gitster@pobox.com>
Date: Oct 10, 2026, 01:45 UTC
Message-ID: <87tsmucoqu.fsf@gitster.g>
In-Reply-To: <b40960d8-3033-4458-973a-67fc41e02b77@app.fastmail.com>

"Julia Evans" <julia@jvns.ca> writes:

Comments on a few more points.

Show 6 quoted lines

>> Is it deliberate to omit 'am -3' and 'checkout -m', perhaps in order
>> to limit ourselves to most common ways to help new people by keeping
>> the description to the absolute minimum?
>
> It's deliberate, we talked about that a bit in the discussion of the v1.
> Can add a note in the commit message.

Being a part of _the_ technical manual on Git, I would like to see us aim for completeness, and where we don't leave a note that the description is not complete. In this case, between

    Merge conflicts can happen during a `git merge`, `git rebase`, `git
    cherry-pick`, `git pull`, `git am -3`, `git checkout -m`, `git
    stash pop`, or `git revert`.

that aims for completeness and

    Merge conflicts can happen during a `git merge`, `git rebase`, `git
    cherry-pick`, `git pull`, or `git revert`, and other operations.

that admits the list is not complete, I have slight preference to the first one.

Show 7 quoted lines

>> By the way, is it just me who finds those "Here's", "there's"
>> contractions disturbing in an official manual?  I've seen many of
>> them while reviewing this to be annoyed enough and had to blurt it
>> out X-<.
>
> I find "here is" and "there is" to be distracting and overly formal,
> different people are different I guess :)

But I wouldn't want you to be "different" here. This is not your diary or personal note. This being a part of the technical manual, I would prefer to see the same formalness applied everywhere.