What's the difference between git "--track" and "--set-upstream-to"?

Question

As I can see, both git --track and --set-upstream-to modify a branch so it becames a tracking (or upstream) branch. But where is a subtle difference I can't comprehend. The --track records "remote branch tracks local":

$ git checkout foo -b
$ git branch --track origin/retarget

Branch origin/retarget set up to track local branch foo.

$ cat .git/config
[branch "origin/retarget"]
        remote = .
        merge = refs/heads/foo

While --set-upstream-to records "local branch tracks remote branch":

$ git checkout foo -b
$ git branch --set-upstream-to origin/retarget

Branch foo set up to track remote branch retarget from origin.

$ cat .git/config
[branch "foo"]
        remote = origin
        merge = refs/heads/retarget

What's the difference between this two? I was sure that "tracking branch" is simple concept with additional upstream pointer inside branch that tracks head position of specified branch in remote repository. But seems it's much more complicated?

Answer 1

$ git checkout foo -b
$ git branch --track origin/retarget

The first two commands instruct git to:

• create a local branch named "origin/retarget" (very bad idea, as it is named as a remote tracking branch", while it is actually a simple local branch with a '/' in its name)
• starting from the current branch ("foo", another local branch)
• to make that new local branch tracking its starting point.

See git branch

--track

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

You would use track when you create a branch starting from a remote tracking one.

In other word, your first example isn't how you would use --track.
This would work better:

git checkout -b foo --track origin/retarget

Or, using the more recent (Git 2.23+, Q3 2019) git switch command:

git switch -c foo --track origin/retarget

(there is no --set-upstream-to with git switch)

---

As for the difference between --track and --set-upstream-to:

--set-upstream-to

If specified branch does not exist yet or if --force has been given, acts exactly like --track.
Otherwise, sets up configuration like --track would when creating the branch, except that where branch points to is not changed.

---

Note that with git 2.37 (Q2 2022), you can even forget about --track or --set-upstream-to with:

git config --global push.autoSetupRemote true

Then a git push origin/retarget would automatically link the current local and remote branch.

Answer 2

Let's assume that you have one master branch which is checked out. Now when you do a

$ git branch --track someBranch

you will create a new branch named someBranch which changes will be tracked according to the master branch. But this branch has no remote branch set. Thus you see remote = . in the git config.

Now that someBranch is tracked it means that changes will appear in git status and git branch -v as if a remote exists.

For example if you make a commit on someBranch git will tell you that you are 1 ahead when you do a git branch -v or when you do a git status it shows you

Your branch is ahead of 'master' by 1 commit.

And this is the interessting part. The branch is tracked and git shows you that it is 1 commit ahead of master (the branch that was checked out when you created someBranch)