What is Git Upstream? A Comprehensive Guide for Developers

Git upstream refers to the remote branch that a local repository branch tracks. When you clone a Git repository or add a remote, Git sets up a named relationship between the remote branches and your local branches. This relationship allows you to push/pull changes between the local and remote repositories.

The upstream branch serves as the source of truth – it‘s the definitive reference for the state of the project. Your local repository and branches are copies that you work on independently. By setting an upstream, you tell Git "this is the remote branch I want to sync my local branch with".

Understanding upstream branches in Git is key to leveraging the distributed workflow and collaborating efficiently on projects. This comprehensive guide covers everything you need to know as a developer.

Why Upstream Branches Matter in Git

Git is a distributed version control system. This means every developer gets a full copy of the repository with all commits and branches. You can work independently on your local repository and push changes back to the remote when ready.

The remote repository hosted on GitHub, GitLab, Bitbucket etc. serves as the single source of truth. The main benefit is that you don‘t need constant access to the central server to work – you just sync your local copy by pulling the latest changes and pushing your changes.

Without upstream branches, you would have to manually specify which remote branch to sync with every time. Setting upstreams automates this process by creating named relationships between matching local and remote branches.

Let‘s understand this with an example.

# Origin refers to remote repository
origin/main  

# Local repository 
main

When you git pull or git push from your local main branch, Git automatically looks for origin/main to sync with. This saves you from having to specify the remote branch every time like:

git push origin main

Instead, you can simply do:

git push

Upstreams allow you to follow this simplified workflow for daily development:

# Get latest changes from upstream
git pull 

# Make changes locally
...

# Push changes to upstream  
git push

Without upstreams, you would have to manually handle specifying remote branches. As you can imagine, this gets tedious fast, especially when collaborating with multiple remotes and branches.

How to Set Upstream Branches in Git

When cloning a repository, Git automatically sets up tracking between remote and local branches that have the same name, like origin/main and local/main.

However, this isn‘t always the case. Here are the main scenarios when you will need to set upstreams manually:

• Creating new local branches
• Adding additional remotes
• Changing remote URLs
• Configuring different branch names

Fortunately, setting upstreams in Git is simple no matter the situation.

Set Upstream for New Local Branches

To create a relationship between a new local branch and remote:

# Create branch locally
git checkout -b new-feature

# Set upstream 
git push -u origin new-feature

The -u flag tells Git:

• Push this branch to the origin remote
• And set it as the upstream for the current branch

Next time you push/pull from the new-feature branch, you don‘t have to specify remote or branch.

Change Upstream Remote

To point your existing local branch to a different remote upstream:

# Set new upstream remote 
git branch -u origin/main main

# Verify 
git remote -v
# origin   git@github.com:user/repo.git (fetch)
# origin   git@github.com:user/repo.git (push)

All subsequent pushes and pulls will now sync with the origin/main branch.

Sync Branch Names

Sometimes your local and remote branch names don‘t match, for example:

origin/master

main // local

You can tell Git to treat them as equivalents:

git branch -u origin/master main

Now main will track the upstream master branch.

Re-point to Different Remote Branch

To sync your local branch with a different remote branch:

# Currently tracks main 
git branch -vv
# main 3a3221f [origin/main] Initialize repo

# Change upstream to dev branch
git branch -u origin/dev main  

# Verify
git branch -vv 
# main 3a3221f [origin/dev] Initialize repo

This powerful flexibility allows you to entirely reconfigure upstream relationships on the fly.

Common Git Commands Using Upstream

Once you have an upstream set, you can leverage a number of simplified Git workflows.

Here are some common commands that interact with upstreams:

Git Push

Pushing to upstream branch:

git push

Without upstreams, you would need:

git push origin main

Git Pull

Pull the latest changes from upstream:

git pull

versus:

git pull origin main 

Git Fetch

Fetch updates from the upstream remote:

git fetch

Instead of:

git fetch origin 

Git Rebase

Rebase your local branch on top of upstream:

git rebase

Rather than:

git rebase origin/main

Git Merge

Merge upstream changes into your branch:

git merge

Instead of having to pass the remote branch name explicitly.

Git Status

See if your branch has diverged from upstream:

git status

# On branch main
# Your branch is ahead of ‘origin/main‘ by 2 commits 

As you can see, upstream tracking powers much of modern Git workflows. Understanding how to configure and leverage upstreams will level up your Git skills as a developer.

Viewing Upstream Configuration

There are a couple handy commands to view your currently configured upstreams:

Git Branch -vv

Shows the upstream branch for all local branches:

git branch -vv

  main 3a3221f [origin/main] Initialize repo
* foo   2340dce [origin/foo] Add README

Git Remote Show

View remote tracking branches and mapped upstreams:

git remote show origin

* remote origin
  Fetch URL: git@github.com:user/repo.git
  Push  URL: git@github.com:user/repo.git
  HEAD branch: main
  Remote branches:
    main   tracked   
    foo    tracked
  Local branches configured for ‘git pull‘:
    foo merges with remote foo
    main merges with remote main

Use these to quickly audit and verify your upstream connections.

Why Tracking Multiple Upstreams Matters

Larger projects often have multiple remotes – for example, your team‘s central repository, your forked copy, contributors‘ repositories etc.

Advanced Git workflows leverage this by tracking multiple upstream branches:

           Team Repo (origin)
                  |
        —— main ——main——— 
                  |
      Your Fork (fork)
         — main —

This allows seamless integration of changes from different repositories:

• origin/main to sync with the central team repository
• fork/main to incorporate your own changes

Understanding how to manage workflows with multiple upstreams is an important skill. But covering the details is beyond the scope here.

Learn More about Upstream Workflows

While you now understand the fundamentals of Git upstream branches, there is still much more to master in leveraging upstreams workflows.

Here are some additional topics for taking your skills to the next level:

• Managing multiple upstreams
• Rebasing on upstream branches
• Keeping forked repositories in sync
• Integrating upstream changes
• Resolving merge conflicts against upstream
• Contributing to open source projects with upstream repositories

As you gain more experience with collaborative Git workflows, refer back to these advanced techniques.

Conclusion

Understanding Git "upstream" branches is essential for unlocking the true power of Git collaboration and workflows.

An upstream branch represents the remote branch that a local branch synchronizes with during push/pull operations. By teaching Git "this is the branch I want to track", you streamline workflows with simplified commands.

This guide covered upstream fundamentals from configuration to common commands. You learned:

• Why upstreams matter – Simplifies referencing remote branches
• How to set upstream branches – For new branches or changing remote tracking
• Key commands using upstreams like git push/pull/rebase
• How to view current upstream configuration with git branch -vv and git remote show
• levance of tracking multiple upstreams for advanced scenarios

With these upstream branch basics, you are well on your way towards Git mastery as a developer. These skills will serve you well collaborating on modern software projects big and small.