Git Forks and Upstreams: How-to and a cool tip

Nicola Paolucci Headshot

Developer Advocate

Forking projects to make your own changes lets you easily integrate your own contributions. But if you’re not sending those changes back upstream—which means sending it back to the parent repository—you’re at risk for losing track of them, which can cause divergent lines in your repository. To make sure all contributors are drawing from the same place, you’ll need to know some principles of how git forking interacts with git upstream. In this blog, I’ll introduce you to the basics, the gotchas, and even leave you with a cool tip to get you ahead of the curve.

Git upstream: Keep up-to-date and contribute

Let's start by detailing a common setup and the most basic workflow to interact with upstream repositories.

In a standard setup, you generally have an origin and an upstream remote — the latter being the gatekeeper of the project or the source of truth to which you wish to contribute.

First, verify that you have already setup a remote for the upstream repository, and hopefully an origin too:

git remote -v

origin (fetch)
origin (push)

If you don't have an upstream you can easily add it with the remote command:

git remote add upstream
related material

How to move a full Git repository

Bitbucket logo

Learn Git with Bitbucket Cloud

Verify that the remote is added correctly:

git remote -v

origin (fetch)
origin (push)
upstream (fetch)
upstream (push)

Now you can collect the latest changes of the upstream repository with fetch. Repeat this every time you want to get updates:

(If the project has tags that have not merged to main you should also do: git fetch upstream --tags)

git fetch upstream

Generally, you want to keep your local main branch as a close mirror of the upstream main and execute any work in feature branches, as they might later become pull requests.

At this point, it does not matter if you use merge or rebase, as the result will typically be the same. Let's use merge:

git checkout main
git merge upstream/main

When you want to share some work with the upstream maintainers you branch off main, create a feature branch. When you're satisfied, push it to your remote repository.

You can also use rebase instead, then merge to make sure the upstream has a clean set of commits (ideally one) to evaluate:

git checkout -b feature-x

#some work and some commits happen
#some time passes

git fetch upstream
git rebase upstream/main

Publish with git fork

After the above steps, publish your work in your remote fork with a simple push:

git push origin feature-x
git push -f origin feature-x

Personally I prefer to keep the history as clean as possible and go for option three, but different teams have different workflows. Note: You should do this only when working with your own fork. Rewriting history of shared repositories and branches is something you should NEVER do.

Tip of the day: Ahead/Behind numbers in the prompt

After a fetch, git status shows you how many commits you are ahead or behind of the synced remote branch. Wouldn't it be nice if you could see this information at your faithful command prompt? I thought so too so I started tapping with my bash chopsticks and cooked it up.

Here is how it will look on your prompt once you've configured it:


And this is what you'll need to add to your .bashrc or equivalent—just a single function:

function ahead_behind {
    curr_branch=$(git rev-parse --abbrev-ref HEAD);
    curr_remote=$(git config branch.$curr_branch.remote);
    curr_merge_branch=$(git config branch.$curr_branch.merge | cut -d / -f 3);
    git rev-list --left-right --count $curr_branch...$curr_remote/$curr_merge_branch | tr -s '\t' '|';
export PS1="\h:\w[\$(ahead_behind)]$"

Inner workings

For those who like details and explanations here is how it works:

We get the symbolic name for the current HEAD, i.e. the current branch:

curr_branch=$(git rev-parse --abbrev-ref HEAD);

We get the remote that the current branch is pointing to:

curr_remote=$(git config branch.$curr_branch.remote);

We get the branch onto which this remote should be merged (with a cheap Unix trick to discard everything up to and including the last forward slash [ / ]):

curr_merge_branch=$(git config branch.$curr_branch.merge | cut -d / -f 3);

Now we have what we need to collect the number of counts for the commits we are ahead or behind:

git rev-list --left-right --count $curr_branch...$curr_remote/$curr_merge_branch | tr -s '\t' '|';

We use the age-old Unix tr to convert the TAB to a separator |.

Getting started with git upstream

That is a basic walk-through on git upstream — how to set up a git upstream, create a new branch, collect changes, publish with git fork, and a sweet tip for how many commits ahead/behind you are of your remote branch.

Bitbucket Data Center includes fork synchronization which basically relieves the developer from all the burden of keeping up to date with its forks, and Bitbucket Cloud has an easy 1-step sync check it out!

Nicola Paolucci

Nicola is an all-round hacker who loves exploring and teaching bleeding edge technologies. He writes and talks about Git, development workflows, code collaboration and more recently about Docker. Prior to his current role as Developer Instigator at Atlassian he led software teams, built crowd sourcing applications for geo-spacial data, worked on huge e-commerce deployments. Little known facts about Nicola: he gesticulates a lot while speaking (being Italian), lives in Amsterdam and rides a Ducati.

Share this article
Next Topic

Recommended reading

Bookmark these resources to learn about types of DevOps teams, or for ongoing updates about DevOps at Atlassian.

People collaborating using a wall full of tools

Bitbucket blog

Devops illustration

DevOps learning path

Demo Den Feature demos with Atlassian experts

How Bitbucket Cloud works with Atlassian Open DevOps

Sign up for our DevOps newsletter

Thank you for signing up