Working with Forks

Overview

A spoon is not a repository. For the sake of EnergyPlus/Github discussion, we'll say a fork generally falls into one of three categories:

1. An external collaborator is providing code changes to EnergyPlus and does not have write access to the main NREL/EnergyPlus repo.
2. A developer has write access to NREL/EnergyPlus, but would prefer to use a fork so that they don't make accident goofs inside NREL/EnergyPlus.
3. A developer has write access to NREL/EnergyPlus, but would prefer to use a fork so that they can make commits frequently without triggering lots of CI runs.

Nomenclature

For this conversation, we will refer to the base NREL/EnergyPlus repo as upstream, and the forked repo as simply fork. A remote is a Git artifact, which is simply a pointer to some other repository. They include a name (origin, upstream), and a URL (https://github.com/NREL/EnergyPlus), among other less important things.

Updating from Upstream

One frequent issue to overcome is how to keep the fork up to date with the main repo. First consider the case of operating on a repository that you have write access, and working in a branch:

1. Update your local repository by pulling changes from your remote (git pull). This updates all your remote branch information, so that, for example, origin/develop on your local machine is updated with the latest github/NREL/EnergyPlus/develop version. This also updates your current branch if it is set to track a remote branch. So if you are on develop when you do a git pull, your current develop will be updated to origin/develop.
2. Checkout a new branch to start work on (git checkout -b BugFixBranch), and make changes.
3. Commit the changes to your local repo (git commit -am 'Message')
4. In the meantime, NREL/EnergyPlus/develop has changed. So do a Git Pull and origin/develop will be up to date with the latest changes.
5. Merge those changes into your branch: git merge origin/develop
6. Then push those changes up to GitHub: git push origin BugFixBranch

So the difference when you work with a fork is that you have to interact with more than one remote. Consider the case of someone submitting a contribution to EnergyPlus. We'll look at it from their point of view. Here are their steps:

1. Create a fork of EnergyPlus on GitHub.
2. Clone this fork: `git clone https://github.com/forkuser/EnergyPlus
   • In this fork, there will be a remote named origin that points to forkuser/EnergyPlus.
3. Checkout a new branch (git checkout -b MyBranch), and make changes.
4. In the meantime, NREL/EnergyPlus/develop has changed. A Git Pull doesn't know anything about NREL/EnergyPlus, so if you do Git Pull it will simply update from the fork...which hasn't moved. Instead a Git Pull needs to be done on NREL/EnergyPlus. The way to do this is to add NREL/EnergyPlus as an additional remote: git remote add upstream https://github.com/NREL/EnergyPlus. This will add a remote named upstream that points to NREL/EnergyPlus.
5. Now update your local repo with the upstream changes that have occurred since the fork: git pull upstream. Your local repo already had the origin/BranchName pointers that point to forkuser/EnergyPlus/BranchName. With this pull, you now have a bunch of pointers named upstream/BranchName that point to NREL/EnergyPlus/BranchName.
6. To get up to date with the latest goings-on on the develop branch of NREL, just merge from that! git merge upstream/develop. This is the same thing as step 5 above, you just give it the upstream name qualifier so that it merges from the NREL version.
7. Now make your merged changes known by pushing them up to your fork: git push origin BranchName If you had a pull request from forkuser/EnergyPlus/BranchName into NREL/EnergyPlus/develop, it will now be updated with your latest changes, and up to date with the latest NREL/EnergyPlus/develop changes to quiet any diffs.