How to set upstream tracking for a Git branch

A local Git branch without upstream tracking cannot tell which remote branch should receive a plain push or supply a plain pull. A branch that tracks the wrong upstream is worse because status and ahead or behind counts can compare your work against the wrong review branch.

Upstream tracking is stored as branch-specific configuration that points one local branch at a remote and a remote branch name. After it is set, git branch -vv shows the upstream beside the local branch, and git status -sb reports ahead or behind state against that upstream.

The commands assume the remote branch already exists or a fetch can make it visible as a remote-tracking branch. When the branch has never been published, git push -u origin feature/docs can create the remote branch and set tracking in one command; setting an existing upstream explicitly is safer when the remote branch name already matters.

1. Open a terminal in the repository that contains the branch.
2. Confirm the active branch before changing its upstream.

   $ git status -sb
   ## feature/docs

   Commit, stash, or discard unrelated work first when the branch should be compared from a clean working tree.

   Related: How to stash uncommitted changes in Git

3. List the branch tracking details before the change.

   $ git branch -vv
   * feature/docs 200df4a Add docs notes
     main         34ae87b [origin/main] Initial commit

   A branch with no bracketed upstream beside it has no tracking branch. If the bracketed value points at the wrong remote branch, set the upstream again with the intended target.

4. Fetch the latest branch names from origin.

   $ git fetch origin

   Replace origin with the repository's actual remote name when the branch tracks a fork or an upstream remote.

5. Set the upstream for the local branch.

   $ git branch --set-upstream-to=origin/feature/docs feature/docs
   branch 'feature/docs' set up to track 'origin/feature/docs'.

   Omitting the final branch name changes the current branch. Keeping it explicit avoids changing the wrong branch after a shell prompt or worktree switch.

6. Verify that the branch now shows the intended upstream.

   $ git branch -vv
   * feature/docs 200df4a [origin/feature/docs: ahead 1] Add docs notes
     main         34ae87b [origin/main] Initial commit

   The bracketed value should name the remote branch the local branch should pull from and push to. The ahead or behind count is measured against that upstream.

7. Check the short branch status against the upstream.

   $ git status -sb
   ## feature/docs...origin/feature/docs [ahead 1]

8. Dry-run a default push before sending commits.

   $ git push --dry-run
   To /home/user/origin.git
      34ae87b..200df4a  feature/docs -> feature/docs

   --dry-run does not update the remote. If the destination branch is wrong, reset the upstream before using a real push or pull.