What is Upstream

"Upstream" in Git has two common meanings depending on context.

How it works

Tracking upstream — a local branch can be configured to track a remote-tracking branch. When main tracks origin/main, commands like git pull, git push, and git status (showing "ahead by 2 commits") work without specifying the remote and branch explicitly.

git push -u origin feature    # -u sets upstream
git branch --set-upstream-to=origin/main

The tracking relationship is stored in .git/config:

[branch "main"]
    remote = origin
    merge = refs/heads/main

Fork upstream — in fork-based workflows, "upstream" conventionally refers to the original repository that your fork was created from. You add it as a second remote:

git remote add upstream [email protected]:original/repo.git
git fetch upstream
git merge upstream/main

Why it matters

Setting an upstream tracking branch enables shorthand push and pull commands and lets git status show how far ahead or behind your local branch is. In open-source workflows, the upstream remote is how you sync your fork with the original project.

See How Git Branching Works for remote-tracking branches.