On Sat, 04 Aug 2007 12:55:43 +0200 David Kastrup <dak@xxxxxxx> wrote: > I am trying to dig through man-pages and user manual and trying to > match them with reality. I seem to have a hard time. My current > understanding (which definitely differs from the documented state) is > that there are two types of branches, local and remote branches, and > both types of branches can be remote-tracking (it may not be possible > to have a non-remote-tracking remote branch, though). > > A local branch is one with a local branch head. In contrast, checking > out a remote branch, while possible, leaves one with a detached head. Yes. > "remote-tracking" basically means that git-pull will update the branch > according to changes in the remote repository. To be clear, it's the job of git-fetch to update remote-tracking branches with any changes found in the remote repository. Git-pull runs git-fetch and then runs a git-merge to update the currently-checked-out branch. When this happens, git-merge must decide which remote-tracking-branch to merge into the currently checked out local branch. You can set which remote-tracking-branch will be selected in this situation with the --track option. So assuming a remote-repo has two branches "master" and "branchX": git clone remote-repo will give us two remote-branch (AKA remote-tracking-branches) of "origin/master" and "origin/branchX". So: git branch --track mylocalbranch origin/branchX git checkout mylocalbranch Creates a local branch named "mylocalbranch" that by default will merge in any changes found in the remote-tracking branch "origin/branchX". Thus: git pull First runs git fetch which will update all remote-tracking branches such as origin/master and origin/branchX. Then it runs git merge. Git merge has to decide whether to merge in the changes from origin/master or origin/branchX. Because of the --track option used to setup "mylocalbranch", "origin/branchX" will be merged. > Creating a branch using git-branch or git-checkout will always create > a local branch which may or may not be remote-tracking according to > the --no-track or --track options. No, a local branch is never a remote-tracking branch; even when created with a --track option. The --track option has muddied the terminology waters a bit and you're not the first to be confused by it. The --track selects a branch from the repo to merge by default. > So there are basically three types of branches in a repository that I > can see: > > local branch, not remote-tracking > local branch, remote-tracking > remote branch, remote-tracking > > The way to add a remote branch basically is not via git-branch or > git-checkout -b (those always create local branches), but by editing > .git/config. > > Is this understanding correct or did I get things completely wrong? > Because there is little sense in myself working on changing the > documentation if I have not understood the situation. Functionally, your understanding is correct. But it helps when you understand that remote-branches are the "real" remote-tracking-branches. You don't commit to them locally, they are essentially read-only copies of exactly what is happening in a remote repository. A local --track branch, is one that merges changes from the proper remote-tracking-branch, and is also a place where you can commit your own work. > Also, the documentation currently uses "remote-tracking" > interchangeably for "local branch, remote-tracking" and "remote > branch, remote-tracking", at some times claiming that one can locally > switch to a "remote-tracking" branch, at other times not. A remote branch and a remote-tracking branch are the same thing. Strictly speaking a local branch is never a remote-tracking-branch although the "--track" option makes that harder to explain. > So the terminology seems fuzzy at the moment, and my attempt to clear > it up might not be the preferred way of doing it. Yeah, the documentation could use some fine tuning. Sean - 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
