Set the upstream of an existing Git branch

Use git branch --set-upstream-to=origin/feature-x feature-x to set the upstream of an existing local branch. This changes branch configuration; it does not download commits, merge changes, or publish the branch.

Set the tracking relationship

Fetch the remote branch first, then select either form:

git fetch origin

# Set the upstream of the current branch.
git branch --set-upstream-to=origin/feature-x

# Set it for a named local branch.
git branch --set-upstream-to=origin/feature-x feature-x

When you intend to publish a local branch, pushing can set the upstream at the same time:

git push -u origin feature-x

That command changes the remote as well as local tracking configuration. Check the branch and destination before using it.

Verify, change, or remove it

git branch -vv
git status

# Change the current branch's upstream.
git branch --set-upstream-to=origin/another-branch

# Remove its upstream setting.
git branch --unset-upstream

Ahead/behind counts compare your local branch with the locally stored remote-tracking ref. They become stale when the server changes; fetch again to refresh them.

Common questions

Why does Git say the upstream branch does not exist?

Check git branch -r after fetching. The branch may not exist on the server, or the remote's fetch refspec may exclude it. Publish a new branch with git push -u only if creating it is intended.

Can the two branches have different names?

Yes. Upstream tracking supports that, but it does not guarantee that bare git push will work. With the usual push.default=simple policy, Git refuses to push to a differently named upstream. Use an explicit refspec when that mapping is intentional, such as git push origin local-name:remote-name.

Bare git pull uses the upstream as its default source, subject to pull configuration. Push destinations also depend on settings such as push.default, remote.pushDefault, and per-branch push configuration.

Why does switching sometimes create tracking automatically?

If a local branch is absent and exactly one suitable remote-tracking branch exists, Git can infer the new local branch and its upstream. Ambiguous remotes or differently named branches may require an explicit choice.

References: git branch, git push, and git switch.