Git, Group Fork Merge Process - nordquip/sousms GitHub Wiki
This wiki page is designed to help group fork administrators understand the extra tasks they must perform on the team repository.
These group leaders leaders will have two additional Git tasks, as well as standard Git interaction:
- Every so often, changes made to the entire class repository (nordquip/sousms) must be "pulled" down into the group fork, so that the group may work with these changes.
- Any changes made to the group fork must eventually be "merged" into the class repository (nordquip/sousms) at somewhat-regular intervals.
Before you are able to perform the update process, you'll need to create a remote.
Git Console
As this project involves a repository 'hierarchy' of-sorts, with some unusual merges, it is necessary for group fork owners to run some commands from console.
Here's an excellent Git reference guide, written by the developers behind GitHub:
Specifically, we will be using the following two commands:
As long as you have the GitHub GUI Client installed, you'll be able to bring up a Git console by simply right-clicking a local project and selecting "Open a shell here". If you want to get crazy, you could follow this guide to install a standalone Git client... Most likely, you won't need to do this.
Example Git Console
Setup: Configuring Project Remotes
We need to create a local 'remote' that points to the official "nordquip/sousms" class repository. A 'remote' can be thought of as a 'shortcut' or 'alias' which can be referred to, instead of typing out the whole internet address as an argument with each command. A remote is not shared across computers, and must be setup whenever a new clone is created.
Step 1. Using the GitHub GUI tool, 'clone' your group's project to your local computer if you haven't already. This copies all files from the fork's repository to your local hard drive.
Cloning Repository
Step 2. Open a Git console, and execute the command git remote -v. This will display all remotes associated with this local repository. There should be two entries, both titled "origin", containing the address back to your team's github fork.
Step 3. If the remote does not already exist, run the command git remote add upstream git://github.com/nordquip/sousms.git to create a new remote called "upstream" that will point to the class repository (nordquip/sousms).
Creating the Upstream Remote
Process 1: Updating the Team Fork
GitHub forks do not automatically acquire updates made to parent repositories. As other groups contribute to the class project repository, you'll want to occasionally fold these changes into your group's fork.
Step 1. First, ensure that your local copy of the fork is synchronized with github. You can do this by launching the GitHub GUI tool and looking for the sync icon.
Properly Synced Repository
Step 2. Now that your copy of the fork is up-to-date, open the Git console and run the command git remote -v to verify you have an "upstream" remote.
Step 3. You should be able to type git pull upstream master, which will "pull" all commits made by other groups to your hard-drive.
Pulling Changes from nordquip/sousms
Step 4. After downloading all the new commits from nordquip/sousms, you'll need to switch back to the GitHub GUI again. It should show a list of "unsynced commits" by other classmates. Check for error messages, and then press "Sync" in order to move these changes to your GitHub fork. Your fork now contains recent commits made to the class project.
Syncing Changes Back to Fork
Process 2: "Push" Team Fork Changes Upstream
(Note: Please do not use the console command "git push" to move data upstream -- This appears to discard some VCS meta-data. We will be using pull requests until testing is completed.)
Step 1. Before pushing changes to the upstream nordquip/sousms repository, you'll need to merge the latest upstream commits with your GitHub team fork. To do this, perform the update process described above.
Step 2. Perform a quick check on your local fork for any file version conflicts, simple code bugs, and other problems we wouldn't want propagated to the master repository. Consider yourself a filter, protecting the rest of the class from obvious coding errors and problems.
Step 3. When ready to move files into the master repository, open your team fork's GitHub webpage and create a "Pull Request", using the button at the top of page.
Step 4. After creating a "Pull Request", go to the official "nordquip/sousms" github page, click into the "Pull Request" tab, find your request, and automatically merge/approve it.