The Pull Request Workflow
Let us 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.
Upstream generally refers to the original repo that you have forked. It is the gatekeeper of the project or the source of truth to which you wish to contribute.
Origin is your fork: your repo on GitHub, a clone of the original repo of GitHub.
When a repo is cloned, it has a default remote called origin that points to your fork on GitHub, not the original repo it was forked from.
To keep track of the original repo, you need to add another remote named upstream.
We assume that we do not have push access to the original repository, and hence need to make Pull Requests (PRs) to the repository to make contributions. However, this workflow remains useful even if we do have push access to the original repository (i.e. Upstream).
To set the upstream repository use the command remote add upstream. Since you only set the upstream repository once, you need to execute this command only once.
git remote add upstream https://github.com/miti2001/example.git
Next, you can see the latest changes of the upstream repository with the fetch command. Unless you do git fetch, your local git is not aware if there were newer commits on upstream or origin. Repeat this command every time you want to see the updates in the upstream repository.
git fetch upstream
Note that the fetch command only makes your local environment aware of the changes that were made upstream. To merge these changes from an upstream branch to your local branch, you can use the merge command. Execute the following command from your local branch:
git merge upstream/UpdatedBranchName
git checkout upstream/master
It temporarily sets your current branch as upstream’s master.
Generally, you want to keep your local master branch as a close mirror of the upstream master and execute any work in feature branches.
When you want to share some work with the upstream repository you branch off master, create a feature branch and when you’re satisfied, push it to your remote repository.
git checkout -b feature-1
It creates a new branch feature-1 from upstream/master that has all the latest commits of the upstream master.
To push these changes to the remote repo, write the commands to create a local commit first:
git add .
You add the changes in the working directory to the staging area.
git commit -m “Added Header”
Commit your changes.
git push origin feature-1
Pushes branch named feature-1 to the origin.
Now it may sometimes happen that your feature-1 branch commit has not been merged yet but you want to start working on some other feature-2, then it is possible. You simply create a new branch feature-2 and make a Pull request using that branch.
To create a new feature branch from the upstream/master branch, execute the following commands.
git fetch upstream
This will report the new changes made in upstream by other contributors.
It might happen that while you were working on feature-1 other users have made changes in the upstream repository and you wish to incorporate those changes in your local repository before you work on feature-2. The fetch command ensures that the local repo is updated with the latest commits available on GitHub.
git checkout upstream/master
You once again set the current branch as the upstream’s master
git checkout -b feature-2
You’ll now be on branch feature-2 that is created off of upstream/master branch. This branch will be updated with all the latest commits from the upstream/master.
I hope this article helps you in enhancing your understanding and experience of Git and GitHub.These steps will help you go a long way while contributing to open source.
To get greater insight into the topic you can try out the commands yourself on https://try.github.io/
Here is a link to the Git cheat sheet which you can use to refer to the various Git commands — https://education.github.com/git-cheat-sheet-education.pdf
In case you are a complete beginner, you might want to refer to the following blogs by Code Dementia:
