githubAdvice

Overview

To install git, do the following: http://git-scm.com/ (if you want command line, which are the instructions on this page) or do github for windows. Then go through this page: https://help.github.com/articles/set-up-git.

We are using the "shared repository" model described on https://help.github.com/articles/using-pull-requests.

The main branch of the code is called the master branch, and we want to make sure the master branch always contains working and debugged code.

Suppose we want to start working on some aspect of the code (fixing a bug, adding a feature etc). We will create a branch (with an appropriate name, such as "addingSupportForX") on which to do this work. As we are working, we will regularly (more often is better than less often) check the code into this branch. We don't have to worry if the code we are checking in is working, since we will only use this branch to do this specific development. Once the work is complete, we will merge this branch back into the master branch.

Useful commands related to your local repository

Here are commands related to your local (i.e. on your hard drive) repository

• To get a copy of the code on your computer
  • set up your ssh key as described here gitSSH
  • git clone git@github.com:UserNameOfTheRepositoryHolder/master_MSQC.git TargetDirectory/master_MSQC
• Get information on current branches
  • git branch (shows all branches with a * before the one you are currently working on)
  • git status (shows differences between the files in your directory, and those in the respository)
• Switch to a different branch
  • git checkout branchName (note that autocomplete works... hit tab once you typed a few letters)
• Commit changes to the current working branch (the one with a * in front of it from git status)
  • git commit -am "Message: Enter text describing the changes you are putting into the repository"
• Merge changes in branchName2 into branchName1
  • git merge branchName2 (run this while branchName1 is the working branch, and branchName2 will be merged into branchName1)

Useful commands for pushing and pulling from your local repository to github

Here are commands related to pushing/pulling branches from your local (i.e. your hard drive) repository to the remote (i.e. github.com) respository. From your local perspective, github is named "origin" (i.e. it is the place you originally got the code from).

• Get a branch from github onto your local computer
  • git pull origin branchName
• Put a branch from your local computer onto github
  • git push origin branchName

Sample workflows

Here is an example workflow for adding a feature or fixing or bug.

• Create a branch so you can begin work
  • git checkout -b branchName
• Do edits on the code, and frequently check in intermediate stages using
  • git commit -am "message"
• You can also feel free to periodically push the branch up to github (so others can see what you are up to, or so you can work on it from other computers)
  • git commit -am "message" (good to always start with a local commit)
  • git push origin branchName
• If you move to another computer, and want to work on your branch there, you can
  • git pull origin branchName (get the branch from github)
  • git checkout branchName (make this the active branch)
  • (edit the code)
  • git commit branchName (check your changes into the local repository)
  • git push origin branchName (push the branch up to github)
• Once you are done and want to merge you changes into the master branch
  • git pull origin master (good idea to make sure you have the lasted version of the master branch from github)
  • git checkout master (make the master branch your current working branch)
  • git merge branchName (merge changes from your branch into the master branch)
  • (if there are conflicts, you need to resolve them)
  • git push origin master (push the master branch up to github)