Git Upstream and Tracking Configuration: Connecting Local Branches to Remote Branches

Intermediate

An upstream is branch configuration, not a second branch type

A local branch can have an upstream branch. The relationship is stored in the local repository configuration as branch.<name>.remote and branch.<name>.merge. For example, a local main branch can track origin/main without becoming the same ref: main remains refs/heads/main, while origin/main remains refs/remotes/origin/main.

git branch -vv
git config --local --get branch.main.remote
git config --local --get branch.main.merge

The repository has local main and origin/main.?branch.main.remote and branch.main.merge identify origin/main as main’s upstream.

Creating a branch from a remote-tracking branch can establish tracking

When a local branch is created from a remote-tracking branch, Git can establish tracking automatically. The explicit form git switch --track -c topic origin/topic creates topic and records origin/topic as its upstream. The equivalent branch configuration can be created later with git branch --set-upstream-to=origin/topic topic.

git switch --track -c topic origin/topic
git branch -vv
git rev-parse --abbrev-ref --symbolic-full-name topic@{upstream}

origin/topic exists as a remote-tracking branch.?topic exists locally and topic@{upstream} resolves to origin/topic.

Set or change tracking without moving the branch tip

git branch --set-upstream-to changes tracking configuration without changing the commit to which the local branch points. This is important: configuring an upstream is metadata about a branch relationship, not a history operation. git branch --unset-upstream removes that relationship.

git branch --set-upstream-to=origin/main main
git branch -vv
git branch --unset-upstream main
git branch -vv

main points at commit A while origin/main points at commit B.?main still points at A, but its configured upstream is origin/main.

Upstream configuration drives argument-less pull

When a current branch has an upstream, git pull with no remote or refspec can use that upstream. The upstream therefore supplies the source relationship; it does not itself perform a fetch or merge. V444 owns what pull does after selecting its source.

git branch --set-upstream-to=origin/main main
git pull --ff-only
# equivalent source selection is the configured upstream

main has upstream origin/main.?git pull can select origin/main without a remote/refspec on the command line.

Upstream configuration also participates in argument-less push

An upstream is also relevant to git push without arguments, but the exact destination is additionally governed by push.default and related configuration. The safe curriculum rule is to distinguish the two concepts: upstream identifies a relationship, while push.default determines how an argument-less push maps the current branch to a destination. Explicit push refspecs remain the unambiguous form taught in V445.

git config --local push.default simple
git branch --set-upstream-to=origin/main main
git push --dry-run

main has an upstream and push.default is configured.?The argument-less push destination is derived according to the configured push policy.

Tracking is observable without changing history

git branch -vv shows each local branch and its upstream relationship when one exists. The revision syntax @{upstream} resolves the configured upstream of a branch, and status can report the ahead/behind relationship. These observations do not alter refs.

git branch -vv
git rev-parse --verify main@{upstream}
git status --short --branch

main tracks origin/main.?main@{upstream} resolves to the configured origin/main ref.

Tracking can be inherited or deliberately disabled

Current Git supports --track=direct and --track=inherit when creating branches. branch.autoSetupMerge controls automatic tracking when branch creation or switching does not explicitly specify --track or --no-track. Use --no-track when a local branch should not acquire upstream configuration automatically.

git branch --track=direct topic origin/main
git branch --no-track scratch origin/main
git branch -vv

origin/main exists and a new local branch is being created.?The new branch can point at origin/main without acquiring an upstream relationship.

Practice what you learned

Use the dedicated Git code-completion exercise for this lesson.