Introduction to Github

Getting Github

1. Download it from here. You can use either the GUI or the command line for Github if you install this version.

2. Sign up for an account with your northwestern.edu email account at Github. Once you have done that, go to Github Education and hit the "Request a discount" button to get your 5 free private repositories for the next 2 years.

3. I regret to announce that if you are a collaborator of a private repository, it counts towards your "5 free private" totals.

Cloning the repository

1. cd in the directory where you want the repository to appear

2. In the command line, type git clone https://github.com/lkloh/Cascades-2014.git

3. By default, you should be on the branch master.

4. We assume you are always in the repository aimbat (or whatever other parent repository) from now on, on the command line.

Making Commits

1. Supposed I have made changes to a file, and added a function to, for instance, draw a funny face. I now want git to save my changes.

2. Type in the command line, git add . to stage the commits, and then

git commit -m 'added function to draw a funny face'

3. The syntax of the commit command is kind of like

git commit -m '[YOUR COMMIT MESSAGE HERE]'

4. To check if my commit was saved by Github, type git log. If it was saved, you should see the latest commit with your message there, and all other commits you made previously, in chronological order.

5. Doing git status is also similar and shows you what changes you made. To exit the git log, just type q for quit.

6. You should commit each time you make a significant change, and just before you push your changes to Github, or switch branches. Github will issue a warning if you don't, and disallow such commands if it notices you have un-committed changes.

Going back to a previous commit

1. Now supposed I was wrong. I wanted to draw an angry face, not a funny face. I wish to get rid of the funny face function I just committed. What do I do?

2. Do git log and check for the last commit when I drew the funny face. There's a commit hash there, that looks like gibberish. The message looks something like this:

   commit 3d600e56f185042ce14414803182cb9ea3b0b25b

   Author: lkloh lkloh2410@gmail.com

   Date: Tue Feb 25 22:19:56 2014 -0800

    added function to draw a funny face
   

3. To get rid of that change, do git reset --hard 3d600e56f185042ce14414803182cb9ea3b0b25b

4. Warning: This PERMANENTLY gets rid of the change you just made; its impossible to get it back. But I've found it the best and easiest way to get rid of changes I no longer want. There are other, less permanent ways to do something similar which are more complicated. Look at git cherrypick for examples.

Pulling from a branch/master to get the latest version of the code repository

1. git pull origin master or git pull origin [branch-name] where branch-name is the name of the branch you want to get the latest changes from.

2. You should do git pull origin master regularly to make sure you get the latest updated changes that all collaborators agree on. This will be faster than cloning the repository again as you only need to download the latest changes, not everything on Github.

Reseting a branch

1. I have checked out a branch branch-x, and made some commits, then pushed it to master and merged the branch. Now I realize I don't want any of the commits on the branch.

   git checkout branch-x git fetch origin git checkout master git reset --hard origin/master

2. That gets rid of all commits made on that branch.

Checking who was the last person to touch a portion of the code

1. git blame --show-number [path-to-file]

2. This allows you to see who was the last person to touch that piece of code, so you can blame them if they messed up your stuff.

3. q for quit to exit.

4. Example: Supposed someone messed up the code in the file aimbat/src/pysmo/aimbat/qualctrl.py. I want to see who did it to blame them. I do git blame --show-number /src/pysmo/aimbat/qualctrl.py to see who did it.

Checking which branch you are on

1. You should have the final version you want to keep on branch master. To see which branch you are working on, cd into the project aimbat, wherever you stored it, and inside that folder, type git branch. You should get something like:

   • branch-1 branch-2 master

2. If there is a * in front of the branch, that is the branch you are on.

Adding a new branch

1. Make sure you are on the master branch. Do git pull origin master to get any latest updates from other collaborators (git will just notify you on the command line that there are no changes if no one has done anything to master yet).

2. Get to the master branch. Suppose I wish to call my new branch branch-2.

3. In the command line, type git checkout -b branch-2.

4. Type git branch and you should now be able to verify you are on a new branch, branch-2

Changing between branches

1. If I am on branch-1, and now I want to switch to branch master, type git checkout master.

2. Similarly, if I am on branch master and want to switch to branch branch-1, type git checkout branch-1.

3. To change from branch-1 to branch-2, type git checkout branch-2.

Pushing your branch to Github.

1. Assume I have done some work on branch-1 that I am happy with and want to push to it onto Github to share with other people.

2. Type git branch to make sure I am on branch-1, and not accidentally on branch-2.

3. Now I have verified I am on branch-1, type git push origin branch-1 to push my work to Github.

4. Now, sign in to Github. You should see the branch there. Open the pull request and you can merge it into the master branch there, if there are no merge conflicts.

5. I have now pushed the work on branch-1 onto master. The problem is, the stuff I did is not on the master branch on my personal computer. To get the latest changes, switch branches to master, and type git pull origin master to get the latest version onto my master branch.

Deleting a branch

1. Suppose I am happy with what I did on branch-2. I have done git pull origin master to add the latest changes to branch-2, then did git push origin branch-2 to send my changes to Github, so my collaborators can get my changes. I logged into Github online to merge my changes.

2. Now, I no longer need branch-2 sitting on my command line. To get rid of it, I switch branches to master, and type git branch -D branch-2.

3. Type git branch. You should no longer see branch-2 there anymore.

Adding collaborators

1. In your account page, go to the main page for the repository you are working on.

2. Click on Settings, then Collaborators, and type the Github username of someone you want to add as a collaborator.

Creating Project Pages Manually

Explained here.

Merge Conflicts

1. Happens if Alice and Bob are working on file.py at the same time. Suppose Alice finished first, and pushes her work to master. Now, Bob is done, and he does git pull origin master before trying to push his branch to merge with master.

2. A merge conflict may happen, if Git does not know whether to keep Alice's work or Bob's work. In this case, the compiler will complain about a "merge conflict" to Bob. Bob could resolve it by keeping the work he feels should be kept manually before pushing to master, as described here. Sorry its hard to describe without a live example.

Upstream changes

1. Suppose Alice checked out branch alice-rocks. She did some work and pushed it to alice-rocks.

2. Alice suddenly remembered her advisor said not to do the work she just did since they did not need it anymore.

3. Alice deletes branch alice-rocks on her computer, and does not merge alice-rocks to master.

4. Next week, Alice does some work again, on a branch called alice-rocks, since she names branches that describe her well.

Note: it is good style to name a branch something more descriptive, such as finding-low-freq-events if that is what you are doing.

5. She tries to push stuff to branch alice-rocks, but gets a error message

   ! [rejected] alice-rocks -> alice-rocks (non-fast-forward) error: failed to push some refs to 'https://github.com/lkloh/PysmoTests.git' hint: Updates were rejected because the tip of your current branch is behind hint: its remote counterpart. Integrate the remote changes (e.g. hint: 'git pull ...') before pushing again. hint: See the 'Note about fast-forwards' in 'git push --help' for details.

6. To fix this, on branch alice-rocks, do git checkout -b not-alice-rocks, and push branch not-alice-rocks to Github instead. Then go to Github and delete the existing alice-rocks branch WITHOUT merging with master.

Problems with repository

If anything seems weird with Github somehow, it would be best to delete the repository on your computer, then clone it again from Github. That usually fixes most strange issues.