When to use git branch --track (meaning of start "watching upstream")?

Question

Until recently, I have not been aware of --track switch for git branch. I read the documentation and tried this command, but it has no sense to me.

--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. This configuration will tell git to show the relationship between the two branches in git status and git branch -v. Furthermore, it directs git pull without arguments to pull from the upstream when the new branch is checked out.

This behavior is the default when the start point is a remote-tracking branch. Set the branch.autoSetupMerge configuration variable to false if you want git checkout and git branch to always behave as if --no-track were given. Set it to always if you want this behavior when the start-point is either a local or remote-tracking branch.

I can see that people relate to this switch when they want to make branch track upstream branch

What does it mean? Is it me or this switch description is confusing. When I use term upstream, I refer to the another remote repo (fork) that I can push changes to.

What happens when I start tracking remote branch? How does it manifest locally?

Answer 1

An upstream branch of a branch, or the tracked remote branch is simply the branch you will interact with by default when using git pull and git push commands.

When pulling a branch into yours you can do it explicitly:

git pull origin the_branch

It will fetch the remote origin then merge the origin/the_branch into your current branch.

If you use to pull always the same branch, by setting an upstream branch, you can just launch git pull:

git branch --set-upstream-to origin/the_branch
git pull

By default, when you start a new branch from a remote one, git will add it as the upstream branch:

git checkout -b origin/the_branch
# Is equivalent to
git branch --track the_branch origin/the_branch
git checkout the_branch

---

When pushing, it's almost the same thing.
The config push.default will determine the default branch to push to when using git push with no parameters.

With the value upstream, it will simply push into the upstream branch.
With the default value simple, it will do the same but only if the local and upstream branch names are the same.
I let you look at the doc to check other config possibilities.

---

You can see the the current upstream branches of all your branches by using the -vv switch:

$ git branch -vv
* my_branch       33f2d4c [origin/mybranch] a useful commit
  master          3ed8e99 [origin/master] Merge
  the_branch      dbbb8c0 [origin/the_branch] commit on the branch

The upstream branch of a branch can also be referred with the @{upstream} reference:

$ git rev-parse --symbolic-full-name --abbrev-ref @{upstream}
origin/the_branch

The push branch as the equivalent @{push} (it will be the same as @{upstream} in 99% of the use cases):

$ git rev-parse --symbolic-full-name --abbrev-ref @{push}
origin/the_branch

The distinction between @{upstream} and @{push} is for the cases when you use a triangular workflow: you pull from a read-only "upstream" project (usually a remote called by convention upstream) and push to a writable repository.
This is the case of the forking workflow used on GitHub.
I made a (french) blog post about this, here is the auto-translated version.