Revision control systems and wiki technologies

As an example of a revision (version) control system, we will look at Git. Each revision control system has its specifics often related to a different underling philosophy. However, they share a lot in common and Git is currently the most common tool used.

Git

Git is a revision (version) control system. Git is free and open source software [source]:

Git is released under the GNU General Public License version 2.0, which is an open source license. The Git project chose to use GPLv2 to guarantee your freedom to share and change free software-to make sure the software is free for all its users.

Install Git on your computer. You can obtain the instructions and download file on the official Git website:

https://git-scm.com/

Using Overleaf with Git

To get us started, we will use Git together with Overleaf. Although using Git with software source code is the most typical use case, we will see that using it with markup documents such as LaTeX works exactly in the same way.

You will need some experimental document in Overleaf (i.e. some document which is yours only and you can break it). Go to this document and go to Menu and use the Git option. Use this in your local Git installation to clone the repository. In command line, the operation looks like:

git clone https://git.overleaf.com/somehash

Note that GIt will need to ask you for authentication to Overleaf, use your Overleaf user name (typically your email) and password.

Make some changes in the main TeX file (main.tex) using a text editor. Now let's see the status of the repository:

git status

This should show that one file was modified. Let's see what are the changes:

git diff

This showed the changes line by line. For text, it might be good to see changes word by word:

git diff --word-diff

After reviewing the changes, tell Git to record the current state using git commit. Specify also the message to describe the changes:

git commit -am "A test change"

No let's put the these changes to Overleaf using:

git push

Now check if you see the changes you made in Overleaf. You should see the changes in the Source view.

Then try it the other way around. Make some changes in Overleaf and then get them synchronized to your computer using:

git pull

Starting with repository on your computer

Create a new empty directory and navigate your command line to it. Then initialize a Git repository there:

git init

Create a new plain text file using your text editor. Put there few lines of text. Once you created a new file, you have to tell Git to start tracking it:

git add some_file.txt

To see what files where changed, added or deleted use:

git status

Now commit the changes:

git commit -am "A file with trivial content"

Now do some changes in the file; add some lines, remove some lines, and edit some lines. To review the changes in the files use:

git diff

Now again commit the changes:

git commit -am "Some trivial changes"

Let's review the states we have recorded:

git log

If you don't see your command line prompt, i.e. you can't enter more commands, press Q to get out of the log view. The are GUIs for this, but depending on the occasion we may want to use some command line parameters to get a differently formated revision tree in the command line, for example:

git log --oneline --graph --decorate --all

Again, if your log is long, you will be in the log view mode, press Q to get out of it.

Branches in Git

So far we were working in a single branch called master. Now we will create a new branch. This can be done using git branch and then you would switch to the newly created branch using git checkout. Usually this is done together in one command:

git checkout -b experiment

Now we have a branch called experiment and we are currently in it. In other words, the experiment branch is active now. Any changes we do and commit will be recored as part of this branch and won't affect any of the other branches. Modifications done in different branches can be combined together, for example, using git merge command. A common way how branches are used is in combination with pull or merge requests (see the assignment).

Submitting changes to a project

Usually there are two options how to submit a change to the code in the repository of a project we want to contribute code to. You can submit a patch (aka diff) as a file or you can submit a pull or merge request.

The basic way is to submit a patch (aka diff) as a file. First you clone the repository, make changes and then create the patch. The patch (diff) is obtained using command similar to the following example (assuming unix-like command line here, i.e., Git Bash on Windows):

git diff > your_additions.diff

Now open an issue (ticket, bug report) and add the patch as an attachment.

However, now many projects use pull or merge requests instead of sending a file. See the assignment for a pull request workflow.

Software licenses

Proprietary software use is usually governed by end user license agreements (EULA). Users usually buy permission to use the software. This permission is often called license and users are required to read and agree to the EULA before using the software.

Open source software use governed by open source licenses. There are different licenses with different purposes. The following website is meant for choosing a license for your own project and gives a good practical overview of some of the basic concepts and differences:

https://choosealicense.com/

To understand what you can do with a software or source code under a specific license, it is good to check Open Source Definition by the Open Source Initiative and their list of compliant licenses:

https://opensource.org/osd

https://opensource.org/licenses/category

Resources

Texts

Videos

Documentation

Assignment

The assignment has four parts. First, install Git on your computer.

Second, go to your document in Overleaf from the last assignment or create some other test document in Overleaf. Go to Menu and use the Git option. Use this in your local Git installation to clone the repository. In command line, the operation looks something like:

git clone https://git.overleaf.com/somehash

Make some changes, commit, push, and see what happened in Overleaf. Then make some changes in Overleaf and then pull into your desktop installation. You can repeat that so you feel comfortable.

Third, create a repository on GitHub, GitLab, Bitbucket, or some other Git service. You will need to create an account. There will be a guide, wizard, or form which will lead you through everything. Once you have a repository there, clone the repository on your computer and do some commits. Push the changes to the remote repository and inspect them online. You can also make some changes online if that's possible (like in case of GitHub) and pull the changes to your local repository. Again, you can repeat that so you feel comfortable.

Fourth, submit changes to some repository which is not yours. For this we will use GitHub, but the workflow would be similar in other cases as well. However, different projects prefer different practices and it is best to check guidelines for contributing. These are often in a file called something like CONTRIBUTING. We will use the following repository as the repository we are trying to submit changes to. (Tip: Check CONTRIBUTING.md.)

https://github.com/wenzeslaus/test-repository-for-open-science-class

Alternatively, you can use the same steps as for the above repository and submit some corrections or extensions to the repository for this course.