Re: [PATCH v3 2/4] doc: add an UPSTREAM BRANCHES section to pull/push/fetch

> "Julia Evans via GitGitGadget" <gitgitgadget@gmail.com> writes:
>
>> Since the `git pull`, `git push`, and `git fetch` man pages already
>> include sections on REMOTES and the syntax for URLs, add a section on
>> UPSTREAM BRANCHES to `urls-remotes.adoc` and rename it to
>> `urls-remotes-upstreams.adoc`. That's an awkward name but at least it's
>> clear what's in the file.
>
> You no longer do any such thing ;-) I can locally everyting after
> "and rename it ..." and replace it with a single full-stop "." so
> unless there are other things you would need to update this topic
> with, no need to correct only this part.

>> In the new UPSTREAM BRANCHES section, cover the various ways that
>> upstreams branches are automatically set in Git, since users may
>> mistakenly think that their branch does not have an upstream branch if
>> they didn't explicitly set one.
>>
>> A terminology note: Git uses two terms for this concept:
>>
>> - "tracking" as in "the current branch is _tracking_ some remote"
>>   or the `--track` option to `git branch`
>
> Should we say "tracking some branch at a remote"?  It is not like
> the current branch tracks more than one (or all) branches at the
> remote as a whole.
>
>> - "upstream" or "upstream branch", as in `git push --set-upstream`.
>>   This term is also used in the `git rebase` man page to refer to the
>>   first argument to `git rebase`, as well as in `git pull` to refer to
>>   the branch which is going to be merged into the current branch ("merge
>>   the upstream branch into the current branch")
>
> This side is fine.
>
>> Use "upstream branch" as a heading for this concept even though the term
>> "upstream branch" is not always used strictly in the sense of "the
>> tracking information for the current branch". "Upstream" is used much
>> more often than "tracking" in the Git docs to refer to this concept and
>> the goal is to help users understand the docs.
>
> Good.
>
>> diff --git a/Documentation/urls-remotes.adoc b/Documentation/urls-remotes.adoc
>> index 9b10151198..1138a5889d 100644
>> --- a/Documentation/urls-remotes.adoc
>> +++ b/Documentation/urls-remotes.adoc
>> @@ -91,6 +91,44 @@ git push uses:
>>  	HEAD:refs/heads/<head>
>>  ------------
>>  
>> -
>> -
>> -
>> +UPSTREAM BRANCHES[[UPSTREAM-BRANCHES]]
>> +--------------------------------------
>
> Can we have at least two blank lines between these sections to make
> it visually distinct from a gap between two paragraphs?  I know it
> would not make a difference in the rendered pages, but it would help
> those who read the document in the source form.
>
>> +
>> +Branches in Git can optionally have an upstream remote branch.
>> +Git defaults to using the upstream branch for remote operations, for example:
>> +
>> +* It's the default for `git pull` or `git fetch` with no arguments
>
> I think you'd want to finish this sentence with a full-stop ".", and
> a few lines below, the point beginning with "Various commands".
>
>> +* It's the default for `git push` with no arguments, with some exceptions.
>> +  For example, you can use the `branch.<name>.pushRemote` option to push
>> +  to a different remote than you pull from, and by default with
>> +  `push.default=simple` the upstream branch you configure must have
>> +  the same name.
>> +* Various commands, including `git checkout` and `git status`, will
>> +  show you how many commits have been added to your current branch and
>> +  the upstream since you forked from it, for example "Your branch and
>> +  'origin/main' have diverged, and have 2 and 3 different commits each
>> +  respectively"
>
> Other than these, all changes from the previous version look good to
> me.
>
> Thanks.