The basics of Version Control

Ondřej Mottl

Setkání komunity Data Stewardů

10.09.2024

Evolution

Open Science

A better view

The Journey

Version control

Ring a bell ?

What is Version Control? 🤔

It is all about keeping track of changes 📓✍️

Practical Exercise

03:00

Do you recognize some of these questions?

It broke … hopefully I have a working version somewhere?
Can you please send me the latest version?
Which version are you using?
I am sure it used to work. When did it change?
My laptop is gone. Is my data now gone?

How do you keep track of changes?

Git

local software
keep track of changes of files

GitHub

host server
store (git) the data
project management, collaboration, publishing

Git/GitHub setup AKA “git hell”

Follow instructions in Version Control - git hell (a separate presentation).

Getting all the necessary software installed, configured, and playing nicely together is honestly half the battle … Brace yourself for some pain

Basic vocabulary

Every such project is called repository (ie a repo)
Your local repository is called local
Your online repository, is called remote

Note on practital exercises

Git init (project first)

Activate git for a repo

GH Desktop
Command line
RStudio
VS Code

Create new project with git tracking

For existing project

git init

Create new project with git tracking

git init <DIRECTORY>

For existing project

usethis::use_git()

Create new project with git tracking

usethis::create_project("<DIRECTORY>")
# switch to the new project
usethis::use_git()

Git integration is automatic in Source control panel

Practical Exercise

Make a new project with Git tracking

03:00

Git clone (repo first)

Copy (download) for remote repo to local machine

Example of online repo: OndrejMottl/VersionControl_DataStewards_Sep2024

GH Desktop
Command line
RStudio
VS Code

git clone https://github.com/<OWNER>/<REPO>.git <DIRECTORY>

usethis::create_from_github(
  repo_spec = "https://github.com/<OWNER>/<REPO>.git",
  destdir = "<DIRECTORY>",
  fork = FALSE
  )

Open Command Palette (Ctrl+Shift+p)

Paste in URL: "https://github.com/<OWNER>/<REPO>.git"

Practical Exercise

clone a repo (e.g. this one)

05:00

a commit

A commit is a record of a change

If you create or edit a file in your repository and save the changes, you need to record your change via a commit

Chess analogy?

Chess move diary:

Bc4 (Bishop to c4)
Nf3 (Knight to f3)
Qc7 (Queen to c7)

a commit

Pawn to d4

Edit line 32 of file A

a commit

3 states of a file

Staging changes

Make a change to a file and save it. Now stage the change:

GH Desktop
Command line
RStudio
VS Code

The red icon indicates removed files.
The yellow icon indicates modified files.
The green icon indicates added files.

git add <FILE>

two yellow ?? indicates adding a file
a blue M indicates edit a file that has already been committed
a red D indicates deleting a file

Practical Exercise

Make changes to a file
Make a new file
Stage the changes

05:00

a first commit

Commit (record) staged changes:

GH Desktop
Command line
RStudio
VS Code

git commit -am "commit message"

Review history

Dissecting a commit

SHA - unique identifier

Author - who has done this?

Date - when was this done?

Message - description of what has been done

Stats - what has changed?

Practical Exercise

commit some changes
review history

05:00

Commit message

Commits are quick and cheap. Therefore:

commit often (!)
provide useful commit messages.

Commit history

remote

Now we need to sync chnages with the remote using PUSH

GH Desktop
Command line
RStudio
VS Code

Add a remote to existing local repo (only once):

Push local to remote (GitHub):

Add a remote to existing local repo (only once):

git remote add origin https://github.com/<OWNER>/<REPO>

Push local to remote (GitHub):

git push

Add a remote to existing local repo (only once):

usethis::use_github(protocol  = "https")

Push local to remote (GitHub):

Add a remote to existing local repo (only once):

Push local to remote (GitHub):

Practical Exercise

Publish repo to GitHub
make new commit(s)
Push changes to remote

05:00

GitHub intermezzo

A GitHub repo

GitHub creating a repo

README - description of the project

.gitignore - list of files ignored by GitHub (more about it later)

license - tell other what they can do wit your code

A note on {usethis}

{usethis} package provide a lot of usefull helpers

README - description of the project

usethis::use_readme_md()

LICENSE - restict the use of your code

usethis::use_mit_license(name = "Ondřej Mottl")

CONTRIBUTING.md - guidelines for contributors

usethis::use_tidy_contributing()

CODE_OF_CONDUCT.md - set the tone for discourse between contributors

usethis::use_code_of_conduct()

GitHub creating a repo

Practical Exercise

Create a new repo on GitHub

05:00

`.gitignore` file

A guide to the git which files should be ignored for detecting changes

Here is an example of a .gitignore file:

# History files
.Rhistory
.Rapp.history

# Session Data files
.RData

# RStudio files
.Rproj.user/

# OAuth2 token, see https://github.com/hadley/httr/releases/tag/v0.3
.httr-oauth
.Rproj.user

#data (excludes everything in the folder data)
data/*

# you can make exceptions for specific files
!data/dragon_taxonomy.csv

#figures & output (excludes all figure files)
*.png
*.pdf
*.jpeg

update local- PULL

Now we need to sync chnages from the remote to local the using PULL

GH Desktop
Command line
RStudio
VS Code

Pull from remote (GitHub) to local

Pull from remote (GitHub) to local:

git pull

Pull from remote (GitHub) to local

Pull from remote (GitHub) to local

Merge conflict 💩💩💩

A merge conflict can occur when you are changing the same line in one file differently.

Merge conflict 💩💩💩

To https://github.com/picardis/myrepo.git
 ! [rejected]        master -> master (fetch first)
error: failed to push some refs to 'https://github.com/picardis/myrepo.git'
hint: Updates were rejected because the remote contains work that you do
hint: not have locally. This is usually caused by another repository pushing
hint: to the same ref. You may want to first integrate the remote changes
hint: (e.g., 'git pull ...') before pushing again.
hint: See the 'Note about fast-forwards' in 'git push --help' for details.

a good strategy to avoid such conflicts:

Commit often
Work in small steps
Push and pull regularly
Organize your code in small modules (scripts)

Merge conflicts cannot always be avoided (but can be mitigated by branches; later).

Merge conflict 💩💩💩

If you have questions, please
<<<<< HEAD
open an issue
=======
ask your question in IRC.
>>>>> branch-a

Delete the unwanted text (including the decorations)

If you have questions, please
ask your question in IRC.

Then save the file, stage, and commit again

Practical Exercise

In pairs:

Clone someone’s else repo
Add them as a collaborator
Create a merge conflict
fix it

03:00

Ups! I have made a mistake 😮

How to undo last commit?

Variant A: I commited but NOT pushed yet.

GH Desktop
Command line
RStudio
VS Code

git reset --soft HEAD@{1}

RStudio has a range of possibilities to work with Git and GitHub as shown in this tutorial. The Terminal (NOT console) has more commands and options and will be handy for trouble shooting.

git reset --soft HEAD@{1}

Open Command Palette (Ctrl+Shift+p)

Write Git: Undo Last Commit

Ups! I have made a mistake 😮

How to undo last commit?

Variant B: I commited but AND pushed already.

GH Desktop
Command line
RStudio
VS Code

Right-click on the commit you would like to undo to and select Revert a commit.

Copy the SHA of the last commit

git reset --hard <SHA>

We need the Terminal (NOT console) again.

Copy the SHA of the last commit

git reset --hard <SHA>

In the Source control panel -> COMMITS section -> Right-click on the commit you want to revert to -> Select the Reset Current Branch to Previous Commit