Introduction to Version Control using Git



This chapter is a practical exercise, where we’ll be learning about how to work with the version control system "Git". A valuable skill for anyone interested in scientific research, software development, or online project collaboration.

We’ll be mostly learning and practicing the basics of Git: creating a repository, making changes, staging changes, and creating commits. If these names are confusing, don’t worry; we’ll explain them in the following sections.

To find out more about the accompanying online service for Git - Github check out the next lesson: Intro to GitHub


Motivation:

Fairly simple: Version control is invaluable; being able to track and restore lost content or restoring earlier versions of files that contain, e.g., mistakes or bugs, is like having a “save button” in a video game, providing a point from which you can instantly restart your work.

Git further is the industry standard for every programmer or scientist working with software for, e.g., statistical analyses. It makes your life easier and elevates your chances of actually finding employment in, e.g., academia.


Before we get started: Setup

For this part of the lecture, you will have to follow along on your own machine.

Windows users will have to download the Windows-subystems-for-linux (wsl) application; this will install a Unix subsystem, which will allow you to work with the bash shell. Simply follow, e.g., the Foss Guide: Install bash on windows. Bash already comes preinstalled on Unix systems such as Linux and Mac.

To use Git on your local machine to log any changes you make to your project and submit your changes to the internet, you’ll need the following:

  • a GitHub account

  • Git

  • Bash

We’ve already discussed how to set up a GitHub account and create an online repo. How to get the rest of the listed software is explained in detail in our complete Setup section.

Bash is used in command-line interfaces for interacting with the operating system. In essence, Bash can be seen as a programming language with the main purpose of navigating the file system, manipulating files and directories, running programs, and automating tasks using scripts and workflows.

It is mainly used in scientific computing and data analysis for its ability to automate complex workflows and control flows of large datasets, but it’s further essential to use the version control system Git from the command line. Find out more about it in our chapter Unix Shell and Bash

Check if you’re ready

  • Can you open a text editor? (e.g., Linux: gedit, nano. macOS: textedit. Windows: notepad)

  • Can you go to your GitHub account?

  • When you open a terminal on your system and type git --version, does it output the version number? (macOS / Linux: you might need to run this: conda install -c anaconda git)


You may not need Bash and instead opt to install the Gitkraken client, a software package including a Graphical-user-interface to manage all your git/Github projects. If you’re not too familiar with coding or simply prefer to have a visual overview of the exact changes you’ve made, your version history, etc., this might just be the better choice for you.

Simply download and install the Gitkraken client and connect it to your online Github profile.



Configure git (if you haven’t already)

As git doesn’t work straight out of the box, we’ll have to first provide our credentials. Just copy paste the following lines into a bash shell (remember how to open those?).

git config --global user.name "<Vlad Dracula>"
git config --global user.email "<vlad@tran.sylvan.ia>"

use the email you used for your GitHub account 👆

macOS / Linux

git config --global core.autocrlf input

Windows

git config --global core.autocrlf true

If you’re confused about the language used or want to understand things in greater detail, there are great resources out there for you to explore:

For more information on how to make Git work for you: Software Carpentry’s tutorial

Goals

  1. Explain why git/GitHub is useful

  2. Track and share your work using git/GitHub (git level 1: commit push)

  3. Contribute to a project using git/GitHub (git level 2: branches PRs)

Import side note:

throughout this lecture/practice you will see a lot of things in <>, within each instance please replace <> with your own info

e.g.,

github.com/<your_username>

becomes

github.com/peerherholz

git-phd

“Piled Higher and Deeper” by Jorge Cham, http://www.phdcomics.com

How does Git work?

The basic idea is to:

Record versions by tracking changes

(It’s like having an unlimited “undo” button)


Make independent changes


And incorporate the changes

https://swcarpentry.github.io/git-novice/


Where does git store information?

Open your Bash shell (where you typed git --version at the beginning)

Create a directory (remember Windows’ slashes are the other way) bing the following lines of bash code into your shell.

cd ~/Desktop
mkdir desserts
cd desserts

To check what’s in our directory, we can use the bash command ls

ls -a

To create create a git repository, we can simply run the following command in our shell

git init

What’s in our directory now?

ls -a

The .git subdirectory is where git stores all the info it needs to do version control

Roadmap

  • Goals

  • Setup

  • Why use git & GitHub?

  • Where does git store information?

  • How do I record changes in git?

  • How do I share my changes on the web?

  • How do I contribute to an existing project?

  • Goals

git add

git commit

Let’s make a change! First, open a new file

<text editor> desserts.md

Write this in the file:

pie
ice cream
cookies

Save and exit

Let’s check the status of our repo

git status

Is this file being tracked by git?

(hint: look at what your terminal says)

How can we include this file in what will be committed?

Let’s stage the change

git add desserts.md

Let’s check the status of our repo

git status

Let’s commit the change

git commit -m "list my favorite desserts"

Let’s check the status of our repo

git status

I change my mind…

cookies are better than ice cream

$ <text editor> desserts.md

pie
cookies
ice cream

Save and exit

Let’s ________________________

git diff

How could we figure out what this command does?

Let’s stage and commit the change

git ____ desserts.md
git ____ -m "switch cookies and ice cream"

Check your understanding

What does git track?

Does git track changes to each letter?

How do I get Git to track a change?

Put these in order:

a) git commit -m "<this is what I did>"
b) make the change
c) git add <file>

Create a remote repo

Note: For a more in-depth explanation on how to do this check the Intro to GitHub

  • Beside Repositories, click New

  • Enter your repo name

  • Choose to make your repo Public or Private

  • Don’t check any boxes

  • Click Create repository

Did we meet our goals?

1. Explain why git & GitHub are useful

… to a new grad student

2. Track and share your work using git/GitHub (git level 1: commit push)

status     add     init     commit     diff     push    

Basic workflow for tracking a change and putting it on GitHub

  • make a change

  • stage the change: git ____ <filename>

  • commit the change: git ____ -m "<commit message>"

  • put the change on GitHub: git ____ origin main

See what’s happening with git

  • show the working tree status: git ____

  • show how the file changed: git ____

3. Contribute to a project using git/GitHub (git level 2: branches PRs)

Contributing task 2: Correct spelling mistakes in desserts lists

General tips:

  • Git is hard

  • Don’t expect to remember everything

  • Keep common commands on a sticky note

  • To learn it, you need to commit to doing it

Quick feedback

How much of this tutorial could you follow?

  • 100 %

  • 75 %

  • 50 %

  • 25 %

  • 0 %

Where there any major hurdles?

Acknowledgements


  • most of what you’ll see within this lecture was prepared by Kendra Oudyk and further adapted by Peer Herholz, Michael Ernst & Felix Körber

  • based on the Software Carpentries “Version control with Git” under CC-BY 4.0

Michael Ernst
Phd student - Fiebach Lab, Neurocognitive Psychology at Goethe-University Frankfurt

Peer Herholz (he/him)
Research affiliate - NeuroDataScience lab at MNI/MIT
Member - BIDS, ReproNim, Brainhack, Neuromod, OHBM SEA-SIG, UNIQUE

logo logo   @peerherholz