Introduction to Version Control using Git
Contents
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
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¶
Explain why git/GitHub is useful
Track and share your work using git/GitHub (git level 1: commit push)
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
“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¶
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
Go to github.com
Beside Repositories, click New
Enter your repo name
Choose to make your repo Public or Private
Don’t check any boxes
Click Create repository
Link it to your local repo¶
Tell git the URL of your remote repo and name it ‘origin’
git remote add origin https://github.com/<yourusername>/desserts.git
Set the name of your principle branch to main (if it’s not already)
git branch -M main
Push your changes to GitHub
git push -u origin main
Refresh your GitHub repo
Did we meet our goals?¶
1. Explain why git & GitHub are useful¶
… to a new grad student
3. Contribute to a project using git/GitHub (git level 2: branches PRs)¶
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
@peerherholz