1. Version control with Github August 26th, 2014 Daniel Schreij VU Cognitive Psychology departement http://ems.psy.vu.nl/userpages/data-analysis-course

2. What is version control? “Version control is a system that records changes to a file or set of files over time so that you can recall specific versions later. Even though version control is mainly used for software source code, in reality any type of file on a computer can be placed under version control.”

3. Git Designed by Linus Torvalds, the creator of Linux, to keep track of the many changes and additions that were made to the Linux kernel One of the most accessible and easy to adopt VCS of the moment – Others are mercurial (hg) or subversion (svn) Originally a command-line system, but there now are a lot of good GUI tools available too Like “track changes” for Word, but then for software code (and with full history)

4. Github A website on which repositories (or gits) can be stored Website offers pretty graphical overviews of everything concerning your repositories Public repositories are free, private repositories need to be paid for … but not if you register as an academic Good starting point for projects which will be a collaborative effort Like dropbox (but then a bit more labor-intensive)

5. Github | GUI Get the client from http://github.comhttp://github.com and in it, create a Github account (optional)

6. Git basics |.git file Git(hub) puts a hidden folder (.git) in the folder you want to be tracked (e.g. want to be a Git repository) In this.git folder, a history of all tracked changes is kept. If you move your folder and this.git folder moves with it: no harm done (Accidentally) erase this.git folder however… and the log of your changes is lost (but luckily you can often just download it from gihub.com again)

7. Git basics | Creating a repository Use the GUI! Or: from the command line go to the folder in which you want the files to be tracked by Git and initialize it as a Git repository > cd > git init

8. Git basics | Add files to repo Let’s place a file practice.py containing the following code in the folder: words = ["This","is","a","test"] sentence = ",".join(words) If we now check our repo in the Github GUI, it will have detected this file! Indicates file is just added Repo is not on Github yet (needs to be published first)

9. Git basics | Commit from GUI File has been detected, but its state has not been saved (you cannot revert to its current state if you make changes now) You need to commit your changes Enter a short (!) description of the changes in the top field and (optionally) a larger one in the bottom box

10. Git basics | Commit from CLI If you work from the terminal/console, you can commit files with git commit, but first you need to tell Git to start tracking the files > git add practice.py [ … ] or > git add –A (to track all new files) Now you can commit your changes > git commit –a This will open a text editor in which you can enter your commit message (just as in the GUI)

11. Git basics | Commit from GUI GUI will now list entry of commit in history Long description Short commit description

12. Git basics | Moving on… Let’s make some (drastic?) changes to practice.py # Here I say something about this file # @author Daniel Schreij (d.schreij@vu.nl) words = ["This","is","a","test"] sentence = " ".join(words) print sentence After saving the file, these changes will be registered by Git and shown in the GUI

13. Git basics | Moving on… And after committing these changes again…

14. Git basics | Commited again… From CLI just enter git commit –a again (no need for git add ) Revert to this commit No. of changes and ratio: additions vs. deletions vs. unchanged

15. Git basics | 1000 commits later

16. Git basics | Publishing We all know we like publishing, so time to publish our repository on Github.com – Done with the button in the top-right, and that’s it! – From then on, this button will have the label Sync From the CLI it’s some more work: create remote repository git remote add (https://github.com/dschreij/DAT.git) copy(/push) data to remote repository git push

17. Github| Online

18. Github | README README(.md) file in a repository is automatically displayed on the website and in the Github GUI Let’s create one for our repository

19. Github | README Format can be plain text or markdown Markdown is a plain text formatting syntax. For a overview of the possibilities go to: https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet Let’s create a file called README.md in our repo with the contents: # Practice program **copyright**: *VU DAT group* ## About This program has been made to practice Git

20. Github | README After committing and syncing/pushing, our page will look like this: Other users can dowload or clone our repository from here Our README(.md) appears here README(.md) added to repo

21. Git |.gitignore Some OS’s and programs generate a lot of garbage –.DS_store,.pyc, ~files,.tmp, etc. They might not always be visible to the user, but Git sees them and will take them into the commits You can list the files, file extensions and folders to omit in the.gitignore file

22. Git |.gitignore # Windows image file caches Thumbs.db ehthumbs.db # Folder config file Desktop.ini # Recycle Bin used on file shares $RECYCLE.BIN/ # Windows Installer files *.cab *.msi *.msm *.msp

23. Git | Branches Sometimes you want to make some radical changes to your project, but also want to keep a version as it is. You can create a new branch and play around with your changes there In your repository folder, you can create a new branch in the CLI with: > git branch (create the branch) > git checkout (switch to it) or shorthand: > git checkout –b (create & switch) The new branch will contain a copy of your current branch

24. Git | Branches In the GUI, new branches are created by the button at the top-left labelled master (which is the current and main branch) Let’s create a new branch called experimental

25. Git | Branches Any commit you make will only apply to the current branch In the GUI, you can determine which branch you’re in by checking the label at the top-left In the CLI you can check by entering > git status or > git branch * experimental master You can switch back to the main branch with > git checkout master

26. Git | Merging branches If all works out in the experimental branch, we might want to apply all its changes to our master branch too You can do this by merging branches Make sure you are in the branch you want to merge to > git checkout master and then merge the changes from experimental with > git merge experimental

27. Git | Merging branches It is also possible to merge branches in the GUI by clicking in the branches menu There you can drag the individual branches you want to merge to fields at the bottom

28. Github | Merging branches On Github.com you can create network graphs of various branches, and how they originate from, or are merged into, other branches – Also includes branches of collaborators

29. Git | Merge conflicts If changes have been made to both of two branches that are merged, these changes might conflict You need to manually resolve these conflicts and then commit the resulting file(s) afterward Conflicts can be very nasty, but luckily there are so-called merge tools that make solving them easier

30. Git | Merge tools Meld, P4Merge, WinMerge, KDiff3, etc.

31. Git | Remote repositories In its essence, Git is designed to also work with remote repositories (owned by others) to make sharing, distribution of and collaboration on code easier The GUI’s options for these remote operations are very limited at the moment, so it’s a good idea to use the command line for this

32. Git | Cloning Copy the contents of a remote repository to a folder on your computer (also called a local copy) You cannot contribute back to the upstream repo unless it’s yours or you are indicated as "contributor” by its owner Github

33. Git | Cloning Clone (/make a local copy of) a repository in the GUI, or in the CLI with > git clone For example > git clone https://github.com/dschreij/Data-Analysis-Toolboxhttps://github.com/dschreij/Data-Analysis-Toolbox To later update your local copy with the latest version of the remote repo go to its folder and type > git pull (or with the GUI sync button) Note that this might cause merge conflicts with your local version that you need to resolve

34. Github | Forking A fork is a remote copy (on your account at github.com) of another repository Changes you make can (only) be pushed to your own copied repo Github Other accountYour account

35. Github | Pull requests If you want your changes and/or additions to be merged into the upstream repo, you have to send its owner a pull request Github Other accountYour account !

36. Github | Pull requests The owner can then merge all of (or cherry- pick) your commits into his own repo Github Other accountYour account

37. Github | Pull requests

38. Git | Updating forked repo’s If you want to update your copy with newer versions from the original repo, this can be done with: > git fetch upstream > git merge upstream/ ( e.g. git merge upstream/master) or often > git pull also just works Sometimes the link to the upstream repo is not set yet. Do this with: > git remote add upstream ( e.g. git remote add upstream https://github.com/tknapen/analysis_tools)

39. Git(hub) | Tutorials For an elaborate list of Git commands with explanations, have a look at https://www.atlassian.com/git/tutorial/git-basics https://www.atlassian.com/git/tutorial/git-basics For an interactive tutorial, together with example files, go to http://gitimmersion.com/index.html http://gitimmersion.com/index.html Github’s own documentation is also worth a look: https://help.github.com/articles/set-up-git https://help.github.com/articles/set-up-git

40. Tomorrow Numpy + Scipy Pandas + Matplotlib