|
| 1 | +Introduction to Version Control and GitHub |
| 2 | +========================================== |
| 3 | + |
| 4 | +These materials are inspired and partially based on Software Carpentry's |
| 5 | +lesson on `Version Control with |
| 6 | +Git <http://swcarpentry.github.io/git-novice/>`__. |
| 7 | + |
| 8 | +Contents |
| 9 | +-------- |
| 10 | + |
| 11 | +- `Motivation <#motivation>`__ |
| 12 | +- `What is version control and why to use it? <#vcs-idea>`__ |
| 13 | +- `What is GitHub? <#GitHub>`__ |
| 14 | +- `Resources <#resources>`__ |
| 15 | + |
| 16 | + Familiar? |
| 17 | +---------- |
| 18 | + |
| 19 | +.. figure:: ../img/version_control_motivation_comics.png |
| 20 | + :alt: Motivation for version control |
| 21 | + |
| 22 | + Motivation for version control |
| 23 | + |
| 24 | +*Source: “Piled Higher and Deeper” by Jorge Cham*, |
| 25 | +http://www.phdcomics.com |
| 26 | + |
| 27 | +**Wouldn't it be nice to learn how to avoid this situation!?!?** |
| 28 | + |
| 29 | +We’ve all been in this situation before: it seems ridiculous to have |
| 30 | +multiple nearly-identical versions of the same document. Some word |
| 31 | +processors let us deal with this a little better, such as Microsoft |
| 32 | +Word’s “Track Changes”. |
| 33 | + |
| 34 | + What is version control and why to use it? |
| 35 | +------------------------------------------- |
| 36 | + |
| 37 | +What is it? |
| 38 | +~~~~~~~~~~~ |
| 39 | + |
| 40 | +`Version control <https://en.wikipedia.org/wiki/Version_control>`__ is |
| 41 | +used to track and store changes in your files without losing the history |
| 42 | +of your past changes. |
| 43 | + |
| 44 | +Version control systems start with a base version of the document and |
| 45 | +then save just the changes you made at each step of the way. You can |
| 46 | +think of it as a tape: if you rewind the tape and start at the base |
| 47 | +document, then you can play back each change and end up with your latest |
| 48 | +version. |
| 49 | + |
| 50 | +.. figure:: ../img/play-changes.PNG |
| 51 | + :alt: Illustration of committing changes |
| 52 | + |
| 53 | + Illustration of committing changes |
| 54 | + |
| 55 | +A version control system is a tool that keeps track of these changes for |
| 56 | +us and helps us version our files *(`and |
| 57 | +merge <https://en.wikipedia.org/wiki/Merge_(version_control)>`__*- not |
| 58 | +covered in this course). It allows you to decide which changes make up |
| 59 | +the next version, called a commit, and keeps useful metadata about them. |
| 60 | +The complete history of commits for a particular project and their |
| 61 | +metadata make up a repository (such as our course material |
| 62 | +repositories). Repositories can be kept in sync across different |
| 63 | +computers facilitating also collaboration among different people. |
| 64 | + |
| 65 | +There are multiple different Version Control Systems (VCS) (i.e. a |
| 66 | +software for doing version control) but one of the most popular one is |
| 67 | +**`Git <https://en.wikipedia.org/wiki/Git_(software)>`__** that was |
| 68 | +created by Linus Torvalds in 2005. Git is the version control system |
| 69 | +that is running behind the scenes and used with GitHub. And that's |
| 70 | +actually where its name 'Git - Hub' originates from. |
| 71 | + |
| 72 | +Why to use it? |
| 73 | +~~~~~~~~~~~~~~ |
| 74 | + |
| 75 | +One of the most obvious reasons why to use version control is to avoid |
| 76 | +the situation illustrated in the `comics above <#motivation>`__, i.e. to |
| 77 | +keep track of the full history of your changes in a systematic way |
| 78 | +without the need to have multiple versions of the same file. One really |
| 79 | +useful feature of version control is the ability to "go back in time", |
| 80 | +i.e. if something goes wrong, you can start from some earlier version of |
| 81 | +the file when everything was still working. You can also compare the |
| 82 | +differences between versions and see what has changed. In addition |
| 83 | +aforementioned aspects, version control makes possible for multiple |
| 84 | +people to work on the same file or project at the same time while still |
| 85 | +keeping track of their own changes to the files. |
| 86 | + |
| 87 | +Some basic vocabulary of Version Control |
| 88 | +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 89 | + |
| 90 | +Few basic terms that are used often when discussing about version |
| 91 | +control (not exhaustive). |
| 92 | + |
| 93 | +- **Repository** = a location where all the files for a particular |
| 94 | + project are stored, usually abbreviated to “repo.” Each project will |
| 95 | + have its own repo, which is usually located on a server and can be |
| 96 | + accessed by a unique URL (a link to GitHub page for example). |
| 97 | + |
| 98 | +- **Commit** = To commit is to write or merge the changes made in the |
| 99 | + working copy back to the repository. Whe you commit, you are |
| 100 | + basically taking a “snapshot” of your repository at that point in |
| 101 | + time, giving you a checkpoint to which you can reevaluate or restore |
| 102 | + your project to any previous state. The terms 'commit' or 'checkin' |
| 103 | + can also be used as nouns to describe the new revision that is |
| 104 | + created as a result of committing. |
| 105 | + |
| 106 | +- **Revision / version** = A revision or a version is any change in |
| 107 | + made in any form to a document(s). |
| 108 | + |
| 109 | +- **Clone** = Cloning means creating a repository containing the |
| 110 | + revisions from another repository. This is equivalent to pushing or |
| 111 | + pulling into an empty (newly initialized) repository. As a noun, two |
| 112 | + repositories can be said to be clones if they are kept synchronized, |
| 113 | + and contain the same revisions. |
| 114 | + |
| 115 | +- **Pull / push** = Copy revisions from one repository into another. |
| 116 | + Pull is initiated by the receiving repository, while push is |
| 117 | + initiated by the source. Fetch is sometimes used as a synonym for |
| 118 | + pull, or to mean a pull followed by an update. |
| 119 | + |
| 120 | +- **Merge** = A merge or integration is an operation in which two sets |
| 121 | + of changes are applied to a file or set of files. |
| 122 | + |
| 123 | + What is GitHub? |
| 124 | +---------------- |
| 125 | + |
| 126 | +Now that you know the basics of version control we can dive into |
| 127 | +explaining what GitHub is. |
| 128 | + |
| 129 | +**Relies on Git** |
| 130 | + |
| 131 | +GitHub in principle is a web based Git repository hosting service. Thus |
| 132 | +it wouldn't exist without the version control system Git. Git is also |
| 133 | +running all the time in the background when using GitHub. |
| 134 | + |
| 135 | +**Social (collaborative) network** |
| 136 | + |
| 137 | +However, GitHub is much more than just a hosting service for Git |
| 138 | +repositories as it is also a social network where people can collaborate |
| 139 | +with each other. It is also easy to invite other GitHub users to work |
| 140 | +with the same project. GitHub is a highly popular place for sharing |
| 141 | +codes openly to the entire world or alternatively only to the |
| 142 | +collaborators working on the same project. |
| 143 | + |
| 144 | +**Open source / science** |
| 145 | + |
| 146 | +All publicly available repositories can also be downloaded to your own |
| 147 | +local computer where you can start modifying the codes for your own |
| 148 | +purpose which is called "forking". However, you should always check and |
| 149 | +follow the license terms mentioned in the project that basically tells |
| 150 | +you what you can do (and what not) with the codes that are shared. |
| 151 | +Usually there might be some limitations for commercial use of the codes |
| 152 | +for example. Sharing your work publicly to others is also the basic |
| 153 | +principle of open science. |
| 154 | + |
| 155 | +**Documentation** |
| 156 | + |
| 157 | +GitHub repositories are often also used as web pages for different |
| 158 | +projects. In GitHub such web pages typically include technical |
| 159 | +documentation, instructions and examples how to use the codes or |
| 160 | +software shared on that page. **It is extremely important that you |
| 161 | +document well your codes and programs that you have done!** GitHub |
| 162 | +provides a nice platform for doing and sharing such documentation. |
| 163 | + |
| 164 | +Each repository (and possibly its subfolders) includes a file called |
| 165 | +``README.md`` that by default is the front-page of the given repository |
| 166 | +in GitHub. Those files are written using a specific simple language |
| 167 | +called `Markdown <https://daringfireball.net/projects/markdown/>`__ that |
| 168 | +can be used to create nice looking web pages with different formattings, |
| 169 | +figures, tables and so on. Markdown is really easy to use once you have |
| 170 | +learned the basic syntax of how different textual elements are written. |
| 171 | + |
| 172 | +**Online tools** |
| 173 | + |
| 174 | +There are multiple useful tools integrated into GitHub such as |
| 175 | +possibility to edit the documents or codes directly from the web site. |
| 176 | +What is even better is that Git is always running in background also in |
| 177 | +the web environment, thus all your changes made in the web browser will |
| 178 | +be saved as commits. It is also possible to browse the whole history of |
| 179 | +a file directly from the GitHub's online interface and track the changes |
| 180 | +that you have done. |
| 181 | + |
| 182 | +Usually Git (the software) is run from the command prompt but GitHub |
| 183 | +provides a way to do Git commands without the need to run any commands |
| 184 | +in the terminal. There are, however, also other graphical user |
| 185 | +interfaces for Git that comes with some `Integrated Development |
| 186 | +Environments |
| 187 | +(IDE) <https://en.wikipedia.org/wiki/Integrated_development_environment>`__. |
| 188 | + |
| 189 | +**Issue tracking** |
| 190 | + |
| 191 | +In GitHub it is also possible to give feedback to the developer by |
| 192 | +creating a specific "Issue" that can be used to report for example a bug |
| 193 | +that was found in the code or software. Issues can also be used to track |
| 194 | +ideas, enhancements, tasks for projects on GitHub. You can use Issues |
| 195 | +also to organize tasks you'd like to accomplish, such as adding new |
| 196 | +features or auditing old ones. |
| 197 | + |
| 198 | + Resources |
| 199 | +---------- |
| 200 | + |
| 201 | +- `Screencast series in Youtube for learning |
| 202 | + GitHub <https://www.youtube.com/playlist?list=PL4Q4HssKcxYsTuqUUvEHJ8XxOVOHTSmle>`__ |
| 203 | +- `Tutorial on few extra features of GitHub not (most probably) covered |
| 204 | + in this course (e.g. branch, pull-request, |
| 205 | + merge) <https://guides.github.com/activities/hello-world/>`__ |
| 206 | +- `A TechCrunch article about 'What is GitHub |
| 207 | + Anyway?' <https://techcrunch.com/2012/07/14/what-exactly-is-github-anyway/>`__ |
| 208 | +- `A list of resources for learning Git and |
| 209 | + GitHub <https://help.github.com/articles/good-resources-for-learning-git-and-github/>`__ |
| 210 | + |
| 211 | +**Next**: `Logging into GitHub <log-in-GitHub.md>`__\ **Home**: `Lesson |
| 212 | +2 main |
| 213 | +page <https://github.com/Python-for-geo-people/Lesson-2-Data-types-Lists>`__\ |
0 commit comments