699DR git/github Tutorial Sep 20 2017 This tutorial gives a high-level introduction into basic usage of the version control software git in combination with the online platform Github. The git commands that are covered here follow mostly the excellent introduction here: http://rogerdudler.github.io/git-guide/ If you're new to version control, watch this video: http://git-scm.com/video/what-is-version-control 1) Create an account on https://github.com/ 2) Follow these instructions to install and setup git on your computer: https:// help.github.com/articles/set-up-git/ 3) Create a new repository on Github (navigate to the Repositories tab of your profile, and click New ). These options will name the repository 699dr and initialize it:
The MIT License is standard and lets people do anything they want with your code as long as they provide attribution back to you and don t hold you liable. Click the (i) button for more information about other licenses. 4) Next, we will clone the repository from Github to our local machine. To do this, go to the repository and copy the link that shows up after clicking Clone or download. Then, in your terminal, type "git clone" followed by the link you just copied: git clone https://github.com/danxhuber/699dr.git "danxhuber" should be replaced by your Github username. The command should download the repository to your local directory. 4) Next, we will add some code to the local repository (which currently only contains the default license and readme file). We'll use a simple python script called "gaussian.py", which fits a Gaussian function to fake data in a loop. You can grab it here: http://www.ifa.hawaii.edu/~dhuber/teaching/ast699dr/gaussian.py Or copy and past the last page of this pdf to a text file and call it "gaussian.py". After copying "gaussian.py" to our local repository, add it to the repository as follows: git add gaussian.py To commit the file to your local repository, do: git commit -m "initial commit" The -m option add a comment about the commit, which is required (and detailed comments are recommended for good bookkeeping!). The final step is to push the commit to your remote repository on Github. To do this type: git push origin master The "gaussian.py" script should now show up on your Github repository. 5) Everytime you enhance the code, changes can be committed the same way. For example, after commenting out lines 38-42 from gaussian.py (which disables plotting during the loop) you could do: git commit gaussian.py -m "disabled plotting during loop"
git push origin master You can of course also do multiple commits before pushing your changes to Github. You can also make changes on Github directly (for example by editing the README.md file do add some documentation). In that case, you can sync your local copy using: git pull 6) When developing code, you ll sometimes want to implement new features independently of each other. To do this, you can generate a new branch in addition to the default master branch. For example: git checkout -b crazyfeature will create a new branch called crazyfeature, and all changes will now be committed to the crazyfeature branch. After making some changes to gaussian.py (e.g. add a print result[i] in line 38) we can do a commit and push the new branch to Github: git commit gaussian.py -m "added print statement" git push origin crazyfeature If you're happy with the implemented feature, you may want to merge the branch back into master. To do this via the commandline, first change back to the master branch: git checkout master and then merge and push to Github: git merge crazyfeature git push origin master Alternatively you can do this on Github using a "Pull Request", which will prompt you to review and approve the proposed changes in the merge (this is commonly done when contributing to someone else's code after you have forked and modified a copy). Note that merging can cause conflicts if you've made changes to multiple parts of the same code (not done in the example above). git/github will ask you to resolve these conflicts before merging. 7) At some point you may want to revert to a previous version of your code. To get a history of all the commits that have been made for a file: git log gaussian.py which in my case would show:
commit eb33abe96b90f929e2670912fe8e5ef71050873a Date: Wed Sep 20 15:20:07 2017-1000 added print statement commit c32c0090519559c3c34b01e885b933cd4c6fc4ba Date: Wed Sep 20 15:18:19 2017-1000 disabled plotting during loop commit 83ae7cb5c99dc4ae2e027dc21f6c4806dacf8fba Date: Wed Sep 20 15:17:34 2017-1000 initial commit Let's assume we regret everything we've done so far, and want to get back to the version of the initial commit (step 4). You can do this using the commit number stated in the log either by generating a new branch: git checkout -b goodoldtimes 83ae7cb5c99dc4ae2e027dc21f6c4806dacf8fba or by checking out the individual version: git checkout 83ae7cb5c99dc4ae2e027dc21f6c4806dacf8fba 8) When you've reached a stable version of the code (e.g. a version that you used for a paper), it's often useful to create a code release or "tag". From the commandline, creating a "v1.0" tag can be done as follows: git tag v1.0 eb33abe96b90f929e2670912fe8e5ef71050873a To push the tag to Github: git push origin v1.0 This should then show up as a "release" on your Github page. Releases/tagging can also be done directly on Github, and then copied to your local machine using git pull. If you've published a piece of software as part of a paper you can also make it citeable by adding a Digital Object Identifier (DOI). Instructions on how to do this can be found here: https://guides.github.com/activities/citable-code/
# simple script to fit a Gaussian to fake data from scipy.optimize import curve_fit import numpy as np import matplotlib.pyplot as plt # Gaussian function def gaussian(x, a, b, c, d): val = d + (a * np.exp(-(x - b)**2 / c**2)) return val # number of iterations nit=1000 # array to store the result of each iteration result = np.zeros(nit) # fake x-data x = np.arange(0.1,10.,0.1) plt.ion() plt.clf() for i in range(0, nit): # fake y-data y = gaussian(x,5.,5.,1.,2.)+np.random.normal(1.,0.2,x.size) # fit the data popt, pcov = curve_fit(gaussian, x, y, p0=[5.,5.,1.,3.]) # fitted model z=gaussian(x,popt[0],popt[1],popt[2],popt[3]) # save the fitted center of the gaussian result[i] = popt[1] plt.plot(x,y,'or') plt.plot(x,z) plt.draw() raw_input(':') plt.clf() # plot a histogram of fitted centers of the gaussian plt.hist(result,bins=20)