Tutorial: How to set up GitHub (in the context of WCSim) - WCSim/WCSim GitHub Wiki

Are you new to GitHub and/or WCSim? Then this is the tutorial for you!

In this tutorial you will learn

  • How to get a GitHub account and how to set up git
  • How to fork and clone your own copy of WCSim
  • How to compile WCSim

Setting up GitHub and Git

Sign up for an account on GitHub

  • Go to http://github.com
  • Fill in the username, email, and password fields
  • Click Sign up for GitHub

screen shot 2015-02-12 at 10 39 38 am

Log on to GitHub to see your home page

screen shot 2015-02-12 at 10 41 17 am

Click on the "Set up Git" box in the GitHub bootcamp section.

screen shot 2015-02-12 at 10 41 54 am

Do the four steps under the Setting up Git heading

  • Download and install Git (probably unnecessary unless you are using your personal computer)
  • Set your username and email using git config

screen shot 2015-02-12 at 10 42 41 am

Optional: Set up ssh keys or cache your GitHub password

  • If you want to clone with https (recommended) you don’t have to do this step. You can cache your password if you like, but otherwise you will just need to enter your password when you push your code to GitHub.
  • If you want to clone git using ssh, you must follow the steps to generate the ssh keys.

screen shot 2015-02-12 at 10 43 30 am

Fork a copy of the WCSim code

Go to the main page for the WCSim code. By default, this should show you the code contained in the development branch.

  • To fork a copy of the code, click the screen shot 2015-02-12 at 11 51 26 am button in the top right corner of the page. You must fork the code in order to contribute to the development of WCSim.

A note on using HTTPS vs. SSH

Using https is the method with the quickest start up since you don't have to generate ssh keys. Older versions of git, however, may not support pushing using the https link provided on your fork's page. If you encounter this problem you can fix it by typing git remote set-url origin https://[email protected]/USERNAME/WCSim.git . You also must make sure you are connected in a way that allows a password prompt to pop up (or that you set up password caching). Sound like too much work? Use the ssh method instead (don't forget to set up your ssh keys).

Clone your fork to your computer

You now have a forked copy of WCSim. In order to work with the code, you will need to clone a copy of your fork on to your computer. Here I will show the https link for cloning. If you are using the ssh method, click the ssh clone URL rather than the HTTPS one.

  • Go to the repository page for your fork, if you are not there already. The URL for this page should be https://github.com/USERNAME/WCSim, with your username substituted for USERNAME.
  • To clone a copy of your fork, copy the HTTPS clone URL from the panel on the right.

screen shot 2015-02-12 at 11 12 20 am

  • In your terminal, type git clone and paste the HTTPS clone URL.

screen shot 2015-02-12 at 11 19 22 am

Compile your forked copy of WCSim

WCSim requires ROOT and GEANT to be installed on your system. As of v1.2.0, WCSim is known to work with the gcc4.3 compiler and with GEANT 4.9.4.p01.

screen shot 2015-02-12 at 11 27 39 am

Set your upstream remote

You will need to set a remote to point to the main version of WCSim. This will be used when you need to merge changes made by other developers on main development branch to your local copy of the development branch (this process is more clearly described in the help document on how to keep your branches up to date ).

To set the address of the upstream remote, type git remote add upstream https://github.com/WCSim/WCSim.git. To check that the remote has been set correctly, type git remote -v. You should see that your origin is set to your cloned version of WCSim and that your upstream is set to https://github.com/WCSim/WCSim.git. The exact address of your origin might be different depending on if you used the ssh or https method for cloning, but when you type git remote -v it should look something like this:

origin	[email protected]:USERNAME/WCSim.git (fetch)
origin	[email protected]:USERNAME/WCSim.git (push)
upstream	https://github.com/WCSim/WCSim.git (fetch)
upstream	https://github.com/WCSim/WCSim.git (push)

Test that your code is working

To test that WCSim is working, try running one of the test macros. We will run WCSim.mac, which runs 10 electrons with 500 MeV of energy in the Super-Kamiokande detector.

  • type: ./bin/Linux-g++/WCSim WCSim.mac

You now have a working copy of WCSim!

Other things to try

Exploring the WCSim page

Go to the organization page for WCSim. You will see two entries: WCSim and WCSim-Documentation. WCSim is where the code is located, while WCSim-Documentation contains the raw LaTeX file for the documentation.

  • Click on WCSim to get to the main code page.
  • Click the screen shot 2015-02-12 at 11 41 58 am button on the top right of the page to get emails about changes to the code.
  • Click the screen shot 2015-02-12 at 11 58 16 am button on the right hand panel of the page. This is where we put ongoing development ideas for the code.
  • The screen shot 2015-02-12 at 11 58 57 am button, also on the right hand panel of the page, provides a fun visualization of the statistics on WCSim development.
  • Try browsing through the WCSim code from the repository page.

Want to start playing around with the WCSim code?

Try out the tutorials on how to add your own photosensor or how to make your own detector. Ready to make a code change and submit a pull request? Check out the help page on how to manage your branches and make a pull request.