Andreas Ericsson <ae@xxxxxx> writes:
> I've got half a patch ready to change all occurrences of anything but
> "remote-tracking branch" to that self-same description. This is what
> I've got in Documentation/glossary.txt so far:
>
> [[def_remote_tracking_branch]]remote-tracking branch:
> A "remote-tracking branch" is a branch set up to track the
> state of a branch in a remote repository which the user has named.
> These branches follow exactly the same rules as the branches which
> reside in the remote repository, except that they are manipulated
> by `git fetch` instead of `git push`. That is, they can only be
> updated if the update would result in a <<def_fastforward,fast
> forward>>, or if the user supplies the '--force' option. They cannot
> be checked out or committed to by users, but serve
> solely as local reference-pointers to their corresponding branches
> in the remote repository.
> The most common example of a remote-tracking branch is origin/master.
Please try to read it as if it were an entry in a glossary.
The sentence "... follow exactly the same rules as ..." was
"Huh?" to me. "rules? what rules? the set of valid characters
in their names?"
When branch 'foo' from remote is tracked with the standard layout
(post 1.3.0) it is copied to refs/remotes/origin/foo and people
often fork their local branch refs/heads/foo to build on top.
The use of the word "corresonding" feels a bit confusing,
because you can arguably say refs/heads/foo at remote
corresopnds to refs/heads/foo in your repository.
I'd drop "These branches follow ... the '--force' option. "
from the above. The rules on how they are updated are
irrelevant, before the reader understands what they are for.
How about this?
A "remote tracking branch" remembers which commit a branch
in the remote repository was pointing at last time you
checked. It cannot be checked out or committed because its
purpose is to serve as a local reference point after you
built your own changes on top of it in your local branch
forked from it. The most common example of a remote
tracking branch is "origin/master", which tracks the
"master" branch of the "origin" remote.
BTW, when you have this data-flow (probably typical in a shared
repository workflow):
Remote repository Your repository
refs/heads/foo -------(A)------> refs/remotes/origin/foo
^ |
| (B)
| |
| V
`-------------(C)---------- refs/heads/foo
(A) "git fetch" with remote.origin.fetch configuration
set to +refs/heads/*:refs/remotes/origin/* keeps
your refs/remotes/origin/foo up-to-date with their
refs/heads/foo
(B) "git merge origin/foo" while on "foo" branch (there
are few shorthands like "git pull origin foo" while
on "foo" branch. If you say "git branch --track
foo origin/foo", then running "git pull" without
parameter while on "foo" branch).
(C) "git push origin foo".
* Everybody seems to agree that "refs/remotes/origin/foo" is
called a "remote tracking branch";
* Your refs/heads/foo follows and builds on top of 'foo' branch
at the remote. Some people errorneously call it "tracking"
but that is because we do not have a good term for it;
* There is no good name for "refs/heads/foo at the remote". We
always say "the remote branch you follow" (or "track").
-
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html
