From: Julia Evans <julia@jvns.ca>
Date: Fri, 03 Oct 2025 17:54:01 GMT
Subject: Re: [PATCH v4 2/5] doc: add an UPSTREAM BRANCHES section to pull/push/fetch
Message-ID: <d86f4f3a-b6eb-4684-823d-35dc1134b50e@app.fastmail.com>
In-Reply-To: <5044672.31r3eYUQgx@cayenne>

>> +UPSTREAM BRANCHES[[UPSTREAM-BRANCHES]]
>> +--------------------------------------
>
> Please do not put anchors on the same line as the paragraph.

Thanks, will fix. I just copied that from elsewhere in the
documentation, but I agree the anchors should be on the line above.

>> +The upstream is stored in `.git/config`, in the "remote" and "merge"
>> +fields. For example, if `main`'s upstream is `origin/main`:
>> +
>> +	[branch "main"]
>> +	   remote = origin
>> +	   merge = refs/heads/main
>> +
>
> Please mark the code block with a dedicated fence:
>
> ----
> [branch "main"]
>    remote = origin
>    merge = refs/heads/main
> ----
>
> using tabs may lead to issues if the text is modified later.

Can do -- previously I was using backticks but they didn't work, so I
switched to indenting it as discussed here:
https://lore.kernel.org/git/xmqqqzw7arls.fsf@gitster.g/

But I can use ---- instead.

It might be useful to document both of those in the part of
CodingGuidelines that explains documentation formatting,
I don't see them there.