是否` <remote> / <branch> 这个`git checkout`命令中的`代表远程分支还是远程跟踪分支？

Question

The manpage of git checkout says:

 git checkout <branch> 

If <branch> is not found but there does exist a tracking branch in exactly one remote (call it <remote> ) with a matching name, treat as equivalent to

 $ git checkout -b <branch> --track <remote>/<branch> 

which, the manpage of git checkout says, invokes

$ git branch -f <branch> <remote>/<branch>

with -t option to git branch by default (from manpage of git branch )

 -t 

When creating a new branch, set up branch.<branch>.remote and branch.<branch>.merge configuration entries to mark the start-point branch as "upstream" from the new branch.

What does <remote>/<branch> in the equivalent git checkout command and in the git branch command represent?

1. Since the git branch command sets up branch.<branch>.remote and branch.<branch>.merge to be a remote repository and a remote branch, does <remote>/<branch> represent the remote branch (the upstream branch to-be)?

2. Since the git branch command create a new local branch starting from <remote>/<branch> , does <remote>/<branch> represent the remote tracking branch?

Answer 1

git help revisions will tell you how a refname is interpreted.

For reference,

<refname> , eg master , heads/master , refs/heads/master
A symbolic ref name. Eg master typically means the commit object referenced by refs/heads/master. If you happen to have both heads/master and tags/master, you can explicitly say heads/master to tell Git which one you mean. When ambiguous, a is disambiguated by taking the first match in the following rules:

1. If $GIT_DIR/<refname> exists, that is what you mean (this is usually useful only for HEAD, FETCH_HEAD, ORIG_HEAD, MERGE_HEAD and CHERRY_PICK_HEAD);
2. otherwise, refs/<refname> if it exists;
3. otherwise, refs/tags/<refname> if it exists;
4. otherwise, refs/heads/<refname> if it exists;
5. otherwise, refs/remotes/<refname> if it exists;

6. otherwise, refs/remotes/<refname>/HEAD if it exists.

   HEAD names the commit on which you based the changes in the working tree. FETCH_HEAD records the branch which you fetched from a remote repository with your last git fetch invocation. ORIG_HEAD is created by commands that move your HEAD in a drastic way, to record the position of the HEAD before their operation, so that you can easily change the tip of the branch back to the state before you ran them. MERGE_HEAD records the commit(s) which you are merging into your branch when you run git merge. CHERRY_PICK_HEAD records the commit which you are cherry-picking when you run git cherry-pick.

   Note that any of the refs/* cases above may come either from the $GIT_DIR/refs directory or from the $GIT_DIR/packed-refs file. While the ref name encoding is unspecified, UTF-8 is preferred as some output processing may assume ref names in UTF-8.

   @
   @ alone is a shortcut for HEAD.

So when you say origin/master and Git's looking for something in the repo there, it'll search according to that list and unless you've taken to punning your remote names with branch or tag prefixes it'll find the remote-tracking ref refs/remotes/origin/master .

(note that there are a lot of handy ways to refer to this or that set of revisions in Git, see the docs).

Answer 2

See jthill's answer for how things work normally, which is how they should work.

There's a nasty little wrinkle here if you configure your remote.origin.fetch to an unusual set of strings, though. Both git fetch and git checkout —well, anything that uses a branch's upstream, really—wind up using a data structure that Git calls a refmap . Note that there is never, as far as I can tell, any good reason to do what I am about to describe. But Git does it (based on the user's configuration), so we must be aware of its behavior if we wish to program Git correctly when writing our own code to use Git configurations.

Let's say, for example, that you configure remote.origin.fetch this way:

[remote "origin"]
    fetch = +refs/heads/master:refs/remotes/origin/master
    fetch = +refs/heads/develop:refs/remotes/origin/weird_develop

Now when you run:

git fetch origin

you'll get their refs/heads/master and record it in your own repository as refs/remotes/origin/master , quite normally. But you'll treat their refs/heads/develop differently , creating or updating your own refs/remotes/origin/weird_develop in your own repository.

Hence, your remote-tracking branches that remember their master and develop are called origin/master and origin/weird_develop (for short) in your repository, even though they are called master and develop in their repository.

Now suppose you'd like to create your own branch named develop . If you were using sane fetch = configurations, its upstream setting—what git rev-parse --abbrev-ref develop@{upstream} prints—would be origin/develop . But for some (not-sane?) reason, you've configured this rather bizarre set of fetch = settings, so running git fetch creates or updates one weirded remote-tracking name.

Despite the weird remote-tracking names, the branch configurations will use the actual branch names on the upstream. That is, inspecting .git/config after doing:

git checkout --track develop origin/weird_develop

you will see:

[branch "develop"]
    remote = origin
    merge = refs/heads/develop

The question you should ask is: How did Git put refs/heads/develop into this entry, when my upstream setting is origin/weird_develop ?

The answer is that Git has built this refmap thing, that says that their (origin's) refs/heads/develop is your refs/remotes/origin/weird_develop . This refmap goes both ways: Git can either look up their refs/heads/develop to find your remote-tracking name, or Git can look up your refs/remotes/origin/weird_develop to find origin's branch name.

For all this to work, the refmap constructed from the fetch = setting must not change dynamically. That is, if you edit your .git/config file and alter the fetch lines semi-randomly, your own Git will start to behave oddly, once the constructed refmap no longer matches reality, or if you create maps that are not proper bijections. ¹

---

By bijection here, I mean that every name that you do copy from the remote should map to a unique remote-tracking name in your own repository, and this should cover the entire set of remote-tracking names in your repository. The simple case of +refs/heads/*:refs/remotes/origin/* obviously meets this criterion. However, if you say, for instance:

fetch = +refs/heads/*:refs/remotes/origin/*
fetch = +refs/heads/master:refs/remotes/origin/extra_master

you've created a multivalued function in the origin-to-local-repository direction, since master must be copied to two names, and a surjective mapping in the reverse direction, since your origin/master and origin/extra_master both map to their master . Git will stop with various errors for these cases.