Working with remote repositories gets confusing when the names of the remote repositories in your local Git repo are inconsistent.
One approach to solving this issue is to standardize the use and meaning of two words:
origin, referring to your personal
example.com/<USER>/* repos, and
upstream, referring to the
example.com repo from which you forked the
origin repo. In other words,
upstream refers to the upstream repo where work is publicly submitted, while
origin refers to your local fork of the upstream repo from which you generate pull requests (PRs), for example.
Using the pbench repo as an example, here is a step-by-step approach to set up a new local clone with
upstream defined consistently.
On most Git hosting services, you must fork a project when you want to work on it. When you run your own Git server, that's not necessary, but for a codebase that's open to the public, it's an easy way to transfer diffs among contributors.
Create a fork of a Git repository. For this example, assume your fork is located at
Next, you must obtain a Uniform Resource Identifier (URI) for cloning over SSH. On most Git hosting services, such as GitLab or GitHub, it's in a button or panel labeled Clone or Clone over SSH. Copy the clone URI to your clipboard.
On your development system, clone the repo using the text you copied:
$ git clone firstname.lastname@example.org:<USER>/pbench.git
This clones the Git repository with the default name
originfor your forked copy of the pbench repo.
Change directory to the repo you just cloned:
$ cd ~/pbench
Next, obtain the SSH URI of the source repo (the one you originally forked). This is probably done the same way as above: Find the Clone button or panel and copy the clone address. In software development, this is typically referred to as "upstream" because (in theory) this is where most commits happen, and you intend to let those commits flow downstream into your copy of the repository.
Add the URI to your local copy of the repository. Yes, there will be two different remotes assigned to your local copy of the repository:
$ git remote add upstream email@example.com:bigproject/pbench.git
You now have two named remote repos:
upstream. You can see your remote repos with the remote subcommand:
$ git remote -v
Right now, your local
masterbranch is tracking the
originmaster, which is not necessarily what you want. You probably want to track the
upstreamversion of this branch because upstream is where most development takes place. The idea is that you are adding your changes on top of whatever you get from upstream.
Change your local master branch to track
upstream/master:$ git fetch upstream
$ git branch --set-upstream-to=upstream/master master
You can do this for any branch you want, not just
master. For instance, some projects use a
devbranch for all unstable changes, reserving
masterfor code approved for release.
Once you've set your tracking branches, be sure to
rebaseyour master to bring it up to date to any new changes made to the upstream repo:$ git remote update
$ git checkout master
$ git rebase
This is a great way to keep your Git repositories synchronized between forks. If you want to automate this, read Seth Kenlon's article on cohosting Git repositories with Ansible to learn how.