I often see the --set-upstream flag suggested when doing a git push for the first time. I’ve read parts of the Git manual, but I’m still unclear on what git set upstream really does. How exactly does it affect my local and remote branch relationship, and in what scenarios is it necessary to use?
The --set-upstream flag is basically you telling Git, “Hey, this local branch should track that remote branch going forward.”
That way, next time you do a git push or git pull, you don’t have to specify the remote and branch; Git already knows what to do. It’s most useful the first time you push a new branch.
After that, you can just do git push or git pull without extra flags.
Think of it like pairing your local branch with a remote one. By default, Git doesn’t assume they’re connected, especially if you created the branch locally.
git push --set-upstream origin my-feature-branch tells Git to remember that “my-feature-branch” locally is linked to the one on “origin”.
It’s super handy if you want to simplify future push/pull commands.
I use this when working on feature branches in team projects. After creating a local branch and making some commits, running:
git push --set-upstream origin my-branch
sets up the tracking relationship. This is essential for tools like GitHub Desktop or git status to understand where to push/pull from.
Without it, Git will keep asking for more info each time you push or pull. It’s basically a one-time setup per branch when it’s not tracking anything yet.