Git Usage Guide¶

Pulling the latest code updates¶

Using standard Git¶

Assuming you used our Git setup instructions above (so that your local repository’s upstream remote points to our repo), you can pull our latest changes from a specific branch (e.g. master) by simply typing:

git pull upstream master

Or if you want simply to fetch our latest changes (without actually merging them into your current branch), so that you can look at them, just type:

git fetch upstream

You can then use your graphical viewer (e.g. gitg or SourceTree) to view the latest upstream commits prior to merging them into your own branch(es).

Using Github for Windows / Mac¶

Github for Windows / Mac doesn’t work with multiple remotes – it only synchronizes against your GitHub fork. Working around this limitation, there are two ways to get the latest updates from our GitHub fork:

via the command line¶

If this is the first time you are pulling from our repository, you will need to add a “remote” telling Git the URL of our repository, like so:
```
git remote add upstream https://github.com/cjlee112/socraticqs2.git
```
You can verify the new upstream repository has been added, by listing all the existing remotes:
```
git remote -v
```
You should see the following lines (in addition to your other remotes):
```
upstream  https://github.com/cjlee112/socraticqs2.git (fetch)
upstream  https://github.com/cjlee112/socraticqs2.git (push)
```
Now you are able to pull or fetch the branches and their respective commits from the upstream repository, using the standard Git commands listed in the previous section, e.g.:
```
$ git fetch upstream
```
Once you’ve fetched upstream commits, you can merge them (e.g. from upstream/master) to your current local branch:
```
$ git merge upstream/master
```
This brings your current branch into sync with upstream/master.

Using GitHub desktop client¶

Unfortunately, this is less user friendly. However, you can achieve the same goal by doing following:

Go to the setting tab of your fork.
Change the “Primary remote repository” to the upstream repo you want to use.(ie, https://github.com/cjlee112/socraticqs2.git)
Press “Update Remote”
Press “Sync Branch”
Change the “Primary remote repository” back to the original forked repo you were using.
Press “Update Remote”

Making source-code changes¶

We strongly recommend that you take advantage of Git’s easy revision control “branches” to create a new “experimental” branch for any changes you want to try, e.g. via the command-line:

git checkout -b try

This creates a new branch called try, forked from your current branch (for the purpose of argument, let’s assume it was called previous). Now make and commit whatever changes you want.

As long as your latest changes have been committed, you can instantly switch to another branch, like so:
```
git checkout previous
```
If you decide you want to merge your changes from try into your current branch, just type:
```
git merge try
```
If you now have no further need for try, because all its commits have been merged into your current branch, type:
```
git branch -d try
```
If you decide you want to abandon (completely delete) the changes you made on try, just type:
```
git branch -D try
```
If you decide to abandon your latest commit (undo its changes, and delete the commit), you can type:
```
git reset --hard HEAD^
```
In general, if you want to “reset” your branch to a previous commit (abandoning subsequent changes), just type:
```
git reset --hard 7a529
```
where 7a529 is the commit ID you want to go back to.

See a Git tutorial to learn more about all its great capabilities.

Some best practices to follow¶

don’t push “junk” commits to your public (GitHub) repository. Instead clean up your branch to get rid of unwanted commits (using methods like the above), before pushing it to GitHub.
once your branch is “clean”, make sure the test suite passes before you push your branch to GitHub.
When you branch is clean and all tests pass, you can push it to GitHub so others can access it. For example, to push your try branch:
```
git push origin try
```
Git can do just about anything to help you clean up or reorganize your branches, but its complexities may initially seem mystifying. When in doubt about how to get Git to do what you want, search Google for a tutorial, or ask us for help.