@eliashofmann started the Git/GitHub interactive course

[akbaritabar]

Hi @eliashofmann!

Welcome to the interactive Git and GitHub course.

Participant: eliashofmann
Fork repo: eliashofmann/Git-GitHub-Version-Control-Interactive-Self-paced-Course
Fork sha: ee851a31cd92d4cf0d0e51e6367536ebe5b4d8b3
Enrollment issue: #74
Fork archive: eliashofmann#1

This issue tracks your progress through the course.
Post your answer and the /done N command in a comment to advance. Use /done N in a new line after your answer, with space between /done and N, where N is the step number. The workflow will reply with feedback and the next step. Please do not edit or delete the following lines.

⚠️ Please keep this issue open. Do not click "Close issue". If you accidentally close it, simply reopen it — no progress is lost and the course continues from exactly where you left off.

• 1. Git and version control basics
• 2. GitHub — remote repositories and online collaboration
• 3. Branches, collaboration, and open science
• 4. Advanced Git, GitHub tools, and reproducibility

[akbaritabar]

---

Enable Issues in Your Fork to Receive a Personal Archive

As you complete each step, the course can potentially save a copy of the teaching materials in an issue on your own fork.
This gives you a personal archive to refer back to later.

For this to work, Issues must be enabled in your fork (not in this repository).

How to enable Issues in your fork

1. Go to your fork: https://github.com/eliashofmann/Git-GitHub-Version-Control-Interactive-Self-paced-Course (open in a new tab so that once done you can continue the interactive course in the instructor's repository)
2. Click the Settings tab at the top of the repository page
3. Scroll down to the Features section
4. Check the box next to Issues

Please enable Issues before completing Step 1. The archive is created automatically when you submit your first valid answer. If you enable it later, the archive will be created when you complete the next step, and only that step and subsequent steps' content will be saved.

Your progress in this tracking issue is not affected either way — the archive is a personal reference only.

---

[akbaritabar]

Step 1 materials are ready below.

Step 1: Why do we need Version Control? What is Git?

This step covers why version control matters and how Git works as a local tool on your computer.

Why use version control?

A common problem in research and collaborative writing is ending up with many files such as:

• paper_final.docx
• paper_final_revised.docx
• paper_final_revised_AA_2026-04-18.docx
• paper_REAL_final.docx

That workflow becomes hard to search, hard to merge, and hard to trust.

In the photo below, you see an example from my own collaborative writing for a published article. We used dates to record the version of the file and find the latest one. We used name initials, i.e., AA is mine, and tracked who did the latest changes. Nonetheless, this is difficult and if you ask me what changed between two versions, I would not know precisely.

Of course, you can think of running a review tab, compare on the two Word files, but how much can you learn from that and how easy will it be to track changes? Will it be easier if you had a short memo or note saying what happened?

Version control replaces that file-name chaos with a tracked and auditable history of changes.

You can compare it with ways to share files with others such as Google Drive, DropBox, NextCloud, OpenDrive and similar. But here, you share the files alongside their history of changes. This allows tracking what changed, when, and by whom.

An alternative could be using Google Docs, OpenOffice or something similar offering history of changes, but again, how easy/difficult is it to roll back the changes and go back to a prior version or branch out and open a completely new file and add experimental text that might later be excluded?

Bottom line: You should not be versioning files. Git, and other tools for version control, can do that perfectly. You should focus on the content!

What is Git?

Git is a version control system. It records the history of your project, e.g., every change you commit is saved and can be revisited later.

Think of Git as an endless Ctrl+Z for your entire project, with labels and messages attached to each saved state.

Everything is backed up in Git's history if you stage and commit it (we will cover these topics later in the course).

At any moment, when you visit your project's folder, you have only one text file to edit for the code, the manuscript, etc., and Git keeps track of the history of changes made to that file. If you collaborate with someone (which will be covered in the next steps of this course), they will also have only one file to edit and all changes made are going to be merged into the same file allowing everyone to have the latest version of the file at all times.

Git runs on your local computer and does not require an internet connection. In Step 2 you will learn about GitHub, a separate service that adds online hosting and collaboration on top of Git.

Why plain text matters

Plain text files work well with Git because changes can be compared line by line.
That is much harder with many binary formats such as .docx or .xlsx.

How to install Git and use it locally?

For this interactive course, you do not need to install Git on your computer. But if you were interested to do so and try it out locally as we cover some basics below, use one of the links given here and install the one suitable for your operating system, e.g., Windows, Mac, or Linux.

You can download and install Git for:

• Windows (https://git-scm.com/downloads/win),
• Mac (https://git-scm.com/downloads/mac)
• Linux (https://git-scm.com/downloads/linux).

NOTE: no GUI installation is needed. Only follow the instructions in one of those links, depending on your operating system, and install the Git software. If you were asked for Windows installation to add "context menu shortcut" and "add Git to PATH" please select "yes" for both (which is also selected by default).

After installing it, you can open Windows start menu and type Git bash or open a Terminal (which is the primary way on Mac and Linux) and type commands that will return outputs.

To confirm Git is installed before starting, type this in the terminal (or Git Bash) and press enter. It should print out the version of the git that is installed:

git --version

Alternatively, you can also download and install GitHub Desktop here https://desktop.github.com/download/ which offers you the same functionality using a Graphical User Interface (GUI) with buttons to click to run commands instead of typing them in a terminal to do things which is described below.

Terminal basics

Before practicing Git commands you need a command-line interface (Terminal, Git Bash, or similar). You do not need to memorize everything at once, but these are some of the useful commands to know:

• pwd: show the current working directory/folder
• ls (on Mac and Linux) or dir (on Windows): list files in the folder
• cd NAME-OF-FOLDER: move into another directory

Essential Git commands

• git config --list: inspect your Git configuration
• git config --global user.name "Your Name": set your name
• git config --global user.email "you@example.org": set your email
• git init: start a local Git repository in the current folder
• git status: inspect changed, staged, or untracked files
• git add <file>: stage changes for the next commit
• git commit -m "message": record staged changes in history
• git log: inspect commit history
• git diff --color-words: inspect word-level changes before or after staging (by adding --cached argument after a space) for all files or specific ones (by adding file name)

What is .gitignore?

A .gitignore file tells Git which files or patterns should not be tracked.
This is useful for generated files, logs, temporary files, secrets, username and passwords, and machine-specific clutter.

Examples:

• logs/
• *.tmp
• .DS_Store
• .env

A good habit is to set up your .gitignore early so you never accidentally commit sensitive credentials or large generated files.

To create it, you right click and open a simple text file and replace its name, e.g., new file.txt with .gitignore (note: no name is added, and just an extension is used). You can open it with a text editor like notepad and add patterns of files/folders to exclude. See this course repository for an example of such a file.

Keeping a clear project folder structure

A useful habit is to keep a clear project structure and stick to it.

Many research teams also use numbered scripts or workflow tools so the order of work is explicit and reproducible. This will be (through time) clear to you and your collaborators.

Here is an example of structure that I use often and a description is below what is included where and why.

Folder structure and logic:

• code: R, Python, SQL, etc scripts allowing to run different steps. One would normally want all scripts in this folder to be version controlled using git to allow seeing what changed, when, by whom, and why.
• inputs: raw or unprocessed data files live here. We use code to process them (see the next point)
• outputs: processed data files are here. We use scripts in code folder to modify the inputs and save the resulting data files in outputs. Redoing the process is easy by re-running scripts in code and nothing is lost as we do not save any processed files under inputs.
• figures: visualization files in PDF, PNG and other formats could be saved here. This makes it easier to find them but of course, these could be in a sub-folder under outputs, if needed.
• writing backup: here we can keep a backup of our writing and manuscript in plain text format (in case they are hosted online in an OverLeaf instance and so on, more on this below) which could read and use visualizations from figures folder.

If you are excited to learn more about how to use a cookiecutter tool for new projects and create the same folder structure over and over, I would recommend checking this repository where I use cookiecutter to recreate this folder structure for new projects: https://github.com/akbaritabar/cookiecutter_projects_template.

Later in the course you will learn about scientific workflows and pipelines and tools allowing you to maintain them. Some of those offer best-practices on how to manage your scripts, inputs and outputs which is described later. But, having a clear structure and sticking to it helps you in the long-term.

Where to find more?

If you were interested to see some slides deck and PDF, consider going to (https://github.com/akbaritabar/Using-Git-and-GitHub-for-Open-Science-Workshop) and follow the slides of my previous lecture. The following steps cover many of those topics here, but still, if you prefer seeing a slides deck, that is the option as well!

Your question for step 1

Please reply in this tracking issue with 2–4 full sentences in your own words:

What is Git and what problem does it solve? Why is a .gitignore file useful?

Write as if you were explaining it to a colleague who has never used version control.
There is no need to quote or copy from the materials above as your own words are what matter.

NOTE: When you have answered, add /done 1 to the same comment (Use /done N in a new line after your answer, with space between /done and N, where N is the step number) or in a new comment below.

Tracking issue: #75

[eliashofmann]

Git enables automatic version control and to avoid manual version naming. .gitignore allows us to exclude certain files from having the versions tracked. This may be sensible for passwords, clutter, etc.
/done 1

[akbaritabar]

Step 1 complete.

Your answer covers the Git and version control basics well. Step 2 is now unlocked and covers GitHub — the online hosting and collaboration platform that works with Git.

Step 2: What is GitHub? Remote Repositories and Online Collaboration

This step introduces GitHub, i.e., the online platform where Git-tracked projects are hosted, shared, and collaborated on.

What is GitHub?

GitHub is a hosting and collaboration platform built around Git repositories. While Git runs on your local computer, GitHub provides:

• Online storage for your repositories
• A web interface to browse, search, and discuss code or writing
• Tools for collaboration such as issues, comments, and pull requests
• Public visibility so others can find, fork, and learn from your work

Other similar platforms exist, e.g., GitLab, Bitbucket, Codeberg, and they all work with the same underlying Git tool. So you can directly transfer what you are learning here and use with those platforms. Some universities and institutes provide their self-hosted instances of GitLab and similar, e.g., here is University of Rostock's GitLab: gitlab.uni-rostock.de.

GitHub repositories

A repository (often called a "repo") is the project folder that Git tracks, stored locally and pushed on GitHub as a remote hosting for it.

A common starting workflow is:

1. Create a new repository on GitHub (optionally with a README, .gitignore, and license)
2. Clone it to your computer with git clone <url>
3. Work locally, commit changes, and push them back to GitHub

Fork a repository

Forking creates your own copy of someone else's repository on your GitHub account.

The fork remains linked to the original (upstream) so you can:

• Experiment without affecting the original
• Contribute changes back via a pull request
• Keep your own version of a project

NOTE: That is exactly what you did when you started this course! You forked this repository! Exciting!

Keep your fork in sync

If the upstream repository changes after you fork, your fork can fall behind.
On GitHub, use the Sync fork button to bring those changes into your fork.

On the command line you could do:

git fetch upstream
git merge upstream/main

Essential remote commands

• git clone <url>: copy a remote repository (with its full history) to your local computer. But the clone is not linked to the upstream, as it was the case with a fork (described above), and you do not have permission to contribute your changes back to the main repository if it is owned by someone else (you can only read/pull new changes).
• git remote -v: see where your local repository is connected remotely
• git pull: bring remote changes into your local branch
• git push: send your locally committed changes up to the remote repository

My approach for starting a new project

One practical workflow: create an empty repository on GitHub (with a README, .gitignore, and license), clone it to your computer, then add your local files and start working. This avoids the git init + remote-setup dance.

Here is a photo showing where to obtain the url to use with git clone:

Your question for step 2

Please reply in this tracking issue with 2–4 full sentences in your own words:

What is GitHub and how is it different from Git? What does git clone do, and why would you run git pull before starting work on a shared project?

Write as if you were explaining it to a colleague who has not used Git or GitHub before.
There is no need to quote or copy from the materials above — your own words are what matter.

NOTE: When you have answered, add /done 2 to the same comment (Use /done N in a new line after your answer, with space between /done and N, where N is the step number) or in a new comment below.

Tracking issue: #75

[eliashofmann]

GitHub allows remote hosting of Git-tracked projects. git clone creates a local copy of the remote project. git pull updates the local with the remote version.
/done 2

[akbaritabar]

Step 2 complete.

Your answer covers the GitHub concepts well. Step 3 is now unlocked and covers branches, collaboration workflows, and open science connections.

Step 3: Branches, Collaboration, and Open Science

This step covers how branches and collaborative workflows work, and how version control connects to open and reproducible research.

Branches

A branch lets you work on a feature, experiment, or revision without disturbing the main line of development.

• The default branch is usually called main (or master in older repositories)
• Creating a branch gives you a safe space to try changes
• When you are ready, you can merge the branch back into main

Common use cases:

• Trying out a new idea without risking your working code or text
• Working on multiple features or sections in parallel
• Letting others review a proposed change before it reaches main

Basic branch commands:

git branch feature-idea        # create a new branch
git checkout feature-idea      # switch to it
git checkout -b feature-idea   # create and switch in one command
git checkout main               # go back to main branch
git merge feature-idea         # merge back into main when ready

Pull requests

A pull request (PR) on GitHub is a formal way to propose merging one branch (or fork) into another. It allows:

• Discussion and review of the proposed changes
• Automated checks (GitHub Actions)
• A permanent record of why and how a change was made

In the photo below, you can see where to find Pull requests on a GitHub repository:

Collaboration workflow

A typical open-source or team collaboration workflow:

1. Fork the upstream repository (your own copy on GitHub)
2. Clone your fork locally
3. Create a branch for your work
4. Commit changes and push to your fork
5. Open a pull request from your branch to the upstream repository
6. The maintainer reviews and merges

This keeps the main repository clean and gives the maintainer control over what is merged.

Plain text and reproducibility

Plain text formats such as Markdown, R Markdown, and LaTeX work naturally with Git:

• Every word change shows up as a line-level diff
• It is easy to track contributions and collaborate on writing
• Documents can be compiled from source, ensuring reproducibility

Version-controlled writing means the full history of a manuscript is as transparent as the history of code.

Open Science connections

Version control directly supports Open Science practices:

• Transparency: your analysis and writing history is auditable
• Replication: collaborators can exactly reproduce your steps from the same starting point
• Sharing: a GitHub repository can be published with a DOI on Zenodo or linked to the Open Science Framework (OSF)
• Automation: GitHub Actions can run tests, compile documents, or build websites automatically when you push new commits

Your question for step 3

Please reply in this tracking issue with 2–4 full sentences in your own words:

Why would you create a branch instead of working directly on the main branch? What does forking a repository mean, and how is a fork different from a clone?

Write as if you were explaining it to a colleague who has not used Git or GitHub before.
There is no need to quote or copy from the materials above — your own words are what matter.

NOTE: When you have answered, add /done 3 to the same comment (Use /done N in a new line after your answer, with space between /done and N, where N is the step number) or in a new comment below.

Tracking issue: #75

[eliashofmann]

I would create a branch if I want to try something out I do not want to see (yet) in the main branch. Forking a repository create a own version of the repository. A clone simply copies a remote version locally.
/done 3

[akbaritabar]

Step 3 complete.

Your answer covers branches and collaboration well. Step 4 is now unlocked — it introduces advanced Git tools, reproducibility workflows, and where to go next.

Step 4: Advanced Git, GitHub Tools, and Reproducibility

This final step introduces tools and practices that extend what you can do with Git and GitHub — for research, scientific writing, and software development, e.g., developing an R package in collaboration with others.

Git in popular integrated development environments (IDEs)

You do not have to use the terminal for every Git operation. Popular editors integrate Git directly.

Visual Studio (VS) Code (highly recommended — multilingual and flexible):

• Open a terminal in VS Code and use git commands directly
• The Source Control panel shows staged, unstaged, and committed files at a glance
• The extension Git Graph visualizes your commit history as a tree

RStudio:

• Add the git executable path in Global Options → Version Control
• Use the Git pane to stage, commit, and push without leaving the editor
• Open the terminal inside RStudio for more advanced commands

Git aliases — type less, do more

You can shorten long Git commands with aliases defined in your .gitconfig file:

[alias]
  st  = status
  cm  = commit -m
  ad  = add -A
  pl  = pull --all
  ps  = push --all
  df  = diff --color-words
  lg  = log --pretty=format:'%C(auto)%h%C(blue) %<|(19)%as%C(auto)%d %s'

Here is a photo showing how a .gitconfig file including that alias:

Set one from the command line:

git config --global alias.st "status"

After that, git st runs git status. Over time, aliases like these save a lot of typing.

GitHub Pages — publish directly from a repository

GitHub Pages turns a repository into a hosted website. Common uses:

• Personal or project websites.
  • For example, see Aliakbar Akbaritabar' website and portfolio here https://akbaritabar.github.io/ which depends on GitHub actions that are being run on this repository to operate https://github.com/akbaritabar/akbaritabar.github.io.
  • Each time I create a new page, update my CV or add new files, do git commit and send my changes to repository using git push, it triggers GitHub actions and the website is updated (see photo below).
• Documentation for a code package, or repository. For example, this course's ReadMe page could be seen here https://akbaritabar.github.io/Git-GitHub-Version-Control-Interactive-Self-paced-Course/
• Slide decks compiled from Markdown or HTML

The photo below shows my personal website (left) as an example that is using the codes in a GitHub repository (right) and each commit triggers GitHub actions and updates the website.

GitHub Actions — automation built into GitHub

GitHub Actions runs tasks automatically when you push code or open a pull request:

• Running tests to check that nothing is broken
• Compiling documents or building websites
• Deploying applications or data products

NOTE: This interactive course itself uses GitHub Actions for its automated workflow — every time you post a /done N command, a GitHub Action processes your answer and replies.

Workflow management tools — pipelines with memory

For data analysis pipelines, workflow managers track dependencies between steps and only re-run steps whose inputs have changed:

• SnakeMake: Python-based, widely used in bioinformatics (e.g., for genome sequencing) and computational social science. Allows you to use R, Python, Julia, Rust, or bash scripts for your analysis workflow steps.
  • NOTE: Your workflow can merge these languages and while you do your data preparation in Python, statistical modelling could happen in R and all of these are orchestrated by SnakeMake to run in parallel, if a step's input is not dependent on the other. If they do depend on each other, it runs the step in one language first, sees the exported output, and runs the next step in the other language/tool.
• Targets (R): the same idea for R-based workflows
• Both integrate naturally with version-controlled project structures as they use plain text file formats.

NOTE: If you are interested to see an example, check out this repository which is the code, data and files here that uses SnakeMake workflows: https://github.com/akbaritabar/Internal-and-international-migration-of-scientists and is the replication package for our publication here A. Akbaritabar, M.J. Dańko,X. Zhao, & E. Zagheni (2025) Global subnational estimates of migration of scientists reveal large disparities in internal and international flows, Proc. Natl. Acad. Sci. U.S.A. 122 (15) e2424521122, https://doi.org/10.1073/pnas.2424521122..

This photo shows an example SnakeMake rule (or step) in the data processing and analysis workflow and how it depends on other steps' outputs (top) and how it is defined (bottom):

Reproducible environments — same code, same results

Code that runs on your machine may not run on a collaborator's. Virtual environment tools solve this:

• Renv (R): records and restores the exact R package versions used in a project
• uv (Python): fast modern Python environment and package manager
  • Cookiecutter: In step 1, you learned that having a consistent folder structure for your projects will pay off and make it easier to start. uv allows you to use a tool called Cookiecutter which creates the project folders, ReadMe files and descriptions, according to your wishes.
  • Here is one example that I have set up to create new projects with the same structure with a few terminal commands using uv and Cookiecutter: https://github.com/akbaritabar/cookiecutter_projects_template
• Docker / Podman: containerise the entire computing environment so any machine can reproduce the result exactly. On Mac and Linux, this is very straightforward, on Windows, you need Windows Subsystem for Linux (WSL) to be activated to use it.

NOTE: These will hopefully save you from having to say (or hear): It works on my computer!

Plain text writing workflows

Git is not only for code. It works equally well for academic writing:

• Markdown: lightweight formatting for notes, READMEs, and web content. Everything you read in these comments and course's teaching materials were written using markdown syntax that supports whatever you need from bold, italic, code chunks etc. Cool, no?
• R Markdown / Quarto: combine text, description, and code in one document. It will render the R or Python code and show the figure/table/results alongside the text that describes them. This has been called literate programming.
• LaTeX / Overleaf: professional typesetting with full Git support. You can also consider using Beamer for presentation format using plain text or checkout Quarto presentations!
• latexdiff: a Perl script that shows tracked changes between two LaTeX versions — useful at the revise-and-resubmit stage when you send your paper to a journal and need to revise it and show what was changed and where.

Archiving and sharing research outputs and replication packages

Once your project is ready to share:

• OSF (Open Science Framework): create a project, upload materials, share a view-only link for peer review. See here https://help.osf.io/article/201-create-a-view-only-link-for-a-project
• Zenodo: create a GitHub Release, connect the repository to Zenodo, and automatically receive a DOI suitable for citation

Here is an example of a Zenodo repository sharing code, data and materials for the publication linked earlier: https://doi.org/10.5281/zenodo.15047102.

Q: Did you know that you can directly link and sync your GitHub repository with both OSF and Zenodo? Great!

Where to go next?

• GitHub Skills — interactive GitHub learning paths
• GitHub Education cheat sheet — command reference card
• Atlassian Git tutorials — thorough written tutorials covering beginner to advanced topics
• Article discussing reproducibility issues: Open Science Collaboration. (2015). Estimating the reproducibility of psychological science. Science, 349(6251), aac4716–aac4716. https://doi.org/10.1126/science.aac4716

Your question for step 4

Please reply in this tracking issue with 2–4 full sentences in your own words:

Pick one tool or practice from this step — for example a Git alias, GitHub Actions, SnakeMake, Docker, Renv, Zenodo, or GitHub Pages — and explain briefly what it does and how it could help your own work or research.

Write in your own words. There is no need to quote or copy from the materials above.

NOTE: When you have answered, add /done 4 to the same comment (Use /done N in a new line after your answer, with space between /done and N, where N is the step number) or in a new comment below.

Tracking issue: #75