"Julia Evans via GitGitGadget" <gitgitgadget@xxxxxxxxx> writes:
> diff --git a/Documentation/urls-remotes.adoc b/Documentation/urls-remotes-upstreams.adoc
> similarity index 63%
> rename from Documentation/urls-remotes.adoc
> rename to Documentation/urls-remotes-upstreams.adoc
I'd personally recommend against making this rename, as we would
likely add more kinds of information later, just like we are adding
one now with this patch, than we would remove any. For example, we
may find that this is a good place to also touch upon a triangular
workflow, where you would track your upstream by pulling from there,
and then you publish your work to your own remote that others can
pull from (and the expectation is that your upstream would pull from
that publishing repository of yours, which complets the triangle),
instead of leaving it vague in the `git push` description as "See
push.default and git-config for details" in the section we are
adding in this patch. We will not rename the file again to
Documentation/urls-remotes-upstreams-triangles.adoc when that
happens ;-).
> index 9b10151198..1e9c56dc5f 100644
> --- a/Documentation/urls-remotes.adoc
> +++ b/Documentation/urls-remotes-upstreams.adoc
> @@ -91,6 +91,41 @@ git push uses:
> HEAD:refs/heads/<head>
> ------------
>
> -
> -
> -
> +UPSTREAM BRANCHES[[UPSTREAM-BRANCHES]]
> +--------------------------------------
> +
> +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
> +* It's sometimes the default for `git push` with no arguments. See the
> + `push.default` section of linkgit:git-config[1] for the details.
> +* `git status` and `git branch -v` will show the
> + relationship between the current branch and the upstream,
> + for example "Your branch is up to date with origin/main"
Although I would rewrite the second one (i.e. "push") for clarity,
to be more explicit that we are discussing only about centralized
workflow in this description, the above is a good write up. Here is
my version, including the push one:
It is the default for `git fetch` (hence `git pull`) and `git
push` when no arguments are given, and you are using the
centralized workflow. To use a triangular workflow, in which
you fetch/pull from your upstream but you push your work to a
third repository, `git push` can be configured to push to
somewhere other than your upstream remote branch.
Various commands, including `git status`, `git checkout`, and
`git branch -v`, reminds you how many commits you have on top of
your upstream, and how many commits they added to your upstream
since your branch has forked from it.
When we would upgrade this file with a more detailed description of
the triangular workflow, we'd remove the "To use a triangular..."
sentence from above, and leave it to the new section.
> +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
> +```
> +
> +You can set an upstream branch explicitly with
> +`git push --set-upstream <remote> <branch>` or `git branch --track`,
> +but Git will often automatically set the upstream for you, for example:
> +
> +* When you clone a repository, Git will automatically set the upstream
> + for the default branch.
> +* If you have the `push.autoSetupRemote` configuration option set,
> + `git push` will automatically set the upstream the first time you push
> + a branch.
> +* Checking out a remote-tracking branch with `git checkout <branch>`
> + will automatically create a local branch with that name and set
> + the upstream to the remote branch.
> +
> +[NOTE]
> +Upstream branches are sometimes referred to as "tracking information",
> +as in "set the branch's tracking information".
Everything you wrote here looks like a great addition.
Nicely done.
