git branch --set-upstream-to: Usage, Options & Common CI Errors

git branch --set-upstream-to tells a local branch which remote branch it tracks.

Tracking config is what lets bare git push and git pull know where to go. CI often needs to set it after creating a branch from a detached checkout.

What it does

git branch --set-upstream-to=<remote>/<branch> records the upstream for a local branch, so future git push/pull/status compare against it without naming the remote each time.

Common usage

Terminal

git branch --set-upstream-to=origin/main main
git branch -u origin/feature           # short form, current branch
git branch --unset-upstream            # remove tracking
git push -u origin feature             # push and set upstream at once

Options

Flag	What it does
--set-upstream-to=<ref> / -u	Set the tracked upstream
--unset-upstream	Remove upstream tracking
<branch>	Target local branch (default: current)

Common errors in CI

error: the requested upstream branch ‘origin/X’ does not exist - fetch it first so the remote-tracking ref exists, or push with -u to create and link in one move. fatal: branch ‘X’ does not exist means you named a local branch that was never created.

Related guides

git branch -d / -D: Usage, Options & Common CI Errorsgit branch -d deletes a merged branch; -D force-deletes any branch. Reference for the not-fully-merged error,… git push: Usage, Options & Common CI Errorsgit push uploads local commits to a remote. Reference for -u, --force-with-lease, and tags, plus the rejected… git branch: Usage, Options & Common CI Errorsgit branch lists, creates, renames, and deletes branches. Reference for -d, -D, -m, --set-upstream-to, and th… git fetch: Usage, Options & Common CI Errorsgit fetch downloads remote objects and refs without touching your working tree. Reference for --depth, --unsh…