Junio C Hamano wrote:
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.
I'd skip "after you built your own changes ..." and let it go at
that. Will amend. Thanks.
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";
I'd like to insert the significant dash there. remote-tracking vs
remote tracking. It solves the one ambiguity with it, and would
finally make it clear and consistent almost however it's used.
* 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;
"private tracking branch"? Nah...
* There is no good name for "refs/heads/foo at the remote". We
always say "the remote branch you follow" (or "track").
"remote-repo branch" perhaps? The universe doesn't exactly toll its
bells in approval at that, but at least it's not ambiguous.
I've seen it written as "remote tracking branch" on irc a few times.
It causes 10 minutes of confusion where no-one's sure what anyone
else means. With the dash in there, there's no room for ambiguity.
--
Andreas Ericsson andreas.ericsson@xxxxxx
OP5 AB www.op5.se
Tel: +46 8-230225 Fax: +46 8-230231
-
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
