An "upstream" branch refers to the default remote branch that Git uses for reading and writing operations. This guide will explain how to set, change, and use upstream branches in your Git workflow.
What does "upstream" mean in Git?
In Git, the term "upstream" refers to the main branch from which a given branch was branched off of and to which it may eventually push changes to. By default, Git uses "origin" as the remote name for the upstream repository, but you can configure this to any name.
For a more detailed discussion on the differences between "remote" and "local" branches, see this guide comparing branch branch types in Git.
Setting upstream for a branch
Setting an upstream branch associates your local branch with a branch on a remote repository. This association is crucial for pull and push operations without specifying a particular remote each time.
1. Check existing remote repositories
Before setting an upstream, ensure that the remote repository is added to your local Git configuration. Running this command will list all of the remotes you currently have available:
git remote -v
If the necessary remote is not listed, you can add it using:
git remote add <remote_name> <remote_url>
2. Create a new branch and set upstream
If you are creating a new branch and want to set its upstream immediately, use:
git checkout -b <branch_name>git push -u <remote_name> <branch_name>
The -u option with git push sets the upstream for the branch. This means that later you can just use git push or git pull without specifying the remote name and branch.
3. Set upstream for an existing local branch
To set an upstream for an existing local branch, use the following command:
git push -u <remote_name> <branch_name>
The -u flag sets the upstream for the branch, which means that future git pull commands executed on that branch will automatically know which remote branch to fetch and merge changes from, and future git push commands will know where to push the changes without specifying the remote and branch names. This simplifies subsequent git operations by establishing a tracking relationship between your local branch and its remote counterpart.
You can also set the upstream for a local branch by running:
git branch --set-upstream-to=<remote_name>/<branch_name>
This command explicitly sets the upstream branch to the branch you currently have checked out. To specify a local branch other than the one you are currently on, you can specify the local branch name at the end of this command. The whole command then looks like this:
git branch --set-upstream-to=<remote_name>/<branch_name> [local_branch_name]
Checking the upstream of a branch
To view the upstream configured for your current branch or another branch, run:
git branch -vv
This command shows all local branches along with more information including their upstream branches if set.
Fetching from upstream
Fetching updates from the upstream branch is important to keep your local repository updated:
git fetch <remote_name>
This command pulls down all the new data from the remote repository but doesn't merge any changes into your local branches.
Pushing to upstream
After setting the upstream, pushing changes is straightforward:
git push
Since the upstream is set, Git knows where to push the changes without needing to specify the remote and branch.
Changing the upstream Git branch
If you need to change the upstream branch for any reason, you can reset it using:
git branch --set-upstream-to=<new_remote>/<new_branch>
This command redefines the upstream for the current branch.
For further reading see the official Git documentation.
