Introduction to Git and GitLab (22.04.2025 - 23.04.2025, 09:00 - 15:00)

Organizational Details

Day 1: Introduction to Git

• 09:00 - 09:30 Welcome and Introduction
• 09:30 - 11:00 Preparing the working environment, Introduction to version control, Setting up Git, Creating a repository
• 11:00 - 12:00 Tracking changes, Exploring history
• 12:00 - 13:00 Lunch Break
• 13:00 - 14:45 Ignoring things, Working with branches
• 14:45 - 15:00 Wrap up and feedback

We have a 15 minutes break very 90 minutes.

Day 2: Introduction to GitLab

• 09:00 - 09:30 Welcome and introduction
• 09:30 - 11:00 Introduction to GitLab, Remote repositories with GitLab
• 11:00 - 12:00 Contribution workflow: Issues and merge requests
• 12:00 - 13:00 Lunch Break
• 13:00 - 14:45 Contribution workflow: Team exercise
• 14:45 - 15:00 Wrap up and feedback

We have a 15 minutes break every 90 minutes.

Before the Workshop

• You need a computer equipped with
  • a simple text editor (e.g. Notepad++, gedit, …)
  • a recent Web browser (e.g., Chromium, Microsoft Edge, FireFox).
  • and the Git command-line tool.
• Please check that you can log in to the following Helmholtz GitLab Instance.
• Check your connection to the workshop room (see separate email).

During the Workshop

• Please mute yourself if you are not talking.
• Please use a headset.
• Please be back in time after breaks.
• Please ask your questions in the chat during the presentation.

Open Questions

Is it possible to change the commit message later?

• Yes, but be careful when you change a commit message of a commit that you already shared with others. Because changing the commit message will also change the commit ID of your commit. This can cause problems with others using the old commit.
• You can change the commit message of your last commit using git commit --amend. For more details please see: https://www.atlassian.com/git/tutorials/rewriting-history
• If you want to change a commit message of a commit earlier, you have to perform a so-called “interactive rebase”. Please be careful with this route. You can find a nice tutorial about it here: https://thoughtbot.com/blog/git-interactive-rebase-squash-amend-rewriting-history

How to disable the pager mode when running git log / diff etc.?

You can control the behaviour using the configuration options core.pager. From the Git manual:

core.pager

This setting determines which pager is used when Git pages output such as log and diff. You can set it to more or to your favorite pager (by default, it’s less), or you can turn it off by setting it to a blank string:

$ git config --global core.pager ''

If you run that, Git will print the entire output of all commands, no matter how long they are.

Day 1: Introduction to Git

Welcome and Introduction

• Please tell us in a minute about your background and interest in the workshop.
• You can switch on your camera, if you like :)

Preparing the working environment

Overview

In the following, we prepare our working environment to properly use Git from the shell.

Open a shell

A shell (also known as: terminal, command line, console) is a program which allows you to run commands on your computer and to receive their output. We use Git from the shell because it clearer shows the way how Git works.

• Some computers offer a default UNIX shell. Please open it on your computer:
  • Windows: Windows does not offer a default UNIX shell but you can use the Git Bash shell included with Git for Windows. Please open it via a right-click on your Desktop and selecting Open Git Bash here.
  • MacOS: You have a Bash or a Zsh shell available depending on your MacOS version. Please open it, for example, by searching Terminal via the MacOS search functionality.
  • Linux: The default shell is usually Bash. It is often accessible via the Gnome Terminal, the KDE Konsole or xterm. Please open it by using the applications menu or the search bar.
• Your shell has been opened in a specific directory. You can check the location by typing the command pwd:

  pwd
  /home/<USER NAME>
  

  In this case, the shell has been opened in the home directory of a specific user. Please double-check that you are in the right directory.

Prepare your working environment

In the following, we prepare our working environment and try out other useful shell commands:

• Please open your local file browser and switch to the directory in which you are in your shell.
• ls - This command shows the content (directories and files) of the current directory.
• The ls command can be executed with a number of options:

  ls -l -a
  total 8
  drwxr-xr-x 1 user group 0 Sep  2 16:32 ./
  drwxr-xr-x 1 user group 0 Aug 29 14:41 ../
  drwxr-xr-x 1 user group 0 Sep  2 16:32 input/
  

  • -l: Shows a more comprehensive overview of the current directory including information such as permissions, the last modification date and time, etc…
  • -a: Shows hidden directories and files (i.e., names start with .) as well. In this case, it adds the special directory references ./ (refers to the current directory) and ../ (refers to the parent directory).
• mkdir workshop - Creates a new, empty directory named workshop in the current directory. We use this directory to store our local Git repositories later.
• cd workshop - We switch into the newly created directory. Please switch into the directory via your file browser as well.
• touch test.txt - We create an empty file test.txt. If you “touch” an existing file, the command will only update the last modification date and time.
• Please open the file test.txt in your favorite text file editor, add the content Hello Git/GitLab workshop audience! and save the file.
• less test.txt - Shows the file content of test.txt and allows scrolling via the arrow-up and the arrow-down keys. You can quit this view with the help of the q key. Git also makes use of the command when showing longer output.
• rm test.txt - Permanently deletes the file text.txt. Please be careful because you cannot (easily) undo deletions via rm!

Key points

At the end you should have prepared the following:

• Opened a shell from which we later run the Git commands.
• Switched into the created workshop directory.
• Prepared the other tools such as your file browser and editor.

Introduction to version control

Overview

In the following, we provide an overview about the main features of the version control system Git.

“Final”.doc?

Please consider the following example review process:

“Piled Higher and Deeper” by Jorge Cham www.phdcomics.com

Quite often such a review process results in a number of similar files with inconspicuous changes. In addition, it is hard to figure out the recent version manually. In such scenarios, tools such as Git can be quite helpful.

Key points

• Git keeps track of file changes. You are able to decide which of these changes make the next file version. A record of these changes is called a commit. These commits automatically include useful metadata (e.g., author, date and time of the change etc.).
• Git allows you to organize related files in a repository (e.g., code and documentation of a software, a paper, …) including their history of changes and related metadata.
• Repositories can be kept in sync across different computers and support collaboration among different people.

Setting up Git

Overview

In the following, we perform the minimal initial Git setup.

Set your default username and email address

At least, we have to tell Git about our identity because this information is later associated with our commits. Git uses the username and email address settings to represent your identity when creating commits:

• git config --global user.name "Last name, first name" - Sets the default username that Git associates with your commits. This options represents your real name or pseudonym which you use. It does not represent your user account on collaboration platforms such as GitLab or GitHub.
• git config --global user.email "name@organization.org" - Sets the default email address that Git associates with your commits. Collaboration platforms such as GitLab and GitHub usually use this information to map commits to user accounts.
• git config --global --list - Displays the default configuration settings. Here you should find your defined username and email address.

Key points

• Please define your identity metadata (username, email address) when you use Git on a new system.
• Please make sure that you consistently use your identity metadata across different client systems.

Creating a repository

Overview

In the following, we create the Git repository which we use throughout the workshop.

Create the planets Git repository

Imagine we work at Universal Missions. Our famous new clients - Dracula, Wolfman and the Mummy - are looking for potential planets to migrate to. We are here to help them make a good decision. For that reason, we collect relevant information about different planets to support them. We store this information in text files and manage them with Git.

The Software Carpentries, CC-BY 4.0

Now, let us create the planets Git repository:

• mkdir planets - Creates the new, empty directory planets.
• cd planets - Switches into the directory planets.
• git init - Initializes the current directory as a Git repository. You need to initialize a repository only once. Afterwards, every file in the planets directory (or any subdirectory) can be maintained as part of the version history. Finally, you can also initialize a non-empty directory for version control with Git.
• The .git subdirectory contains all data, metadata, and configuration settings of the Git repository. Please be careful: If you delete this directory, the history of all your changes is lost!
• Finally, we check the current repository status with the git status command:

  git status  
  On branch main
  
  No commits yet
  
  nothing to commit (create/copy files and use "git add" to track)
  

  • The git status command is really useful when working with Git on the shell. It provides a detailed overview about the repository status and hints about what you could do next.
  • Later, we explain in more detail the concept of branches. For now, please consider it as the default place in your repository where your commits go.
  • The branch name might be master in your output instead. That is because the Git community is trying to adopt more inclusive language. The default branch will be main but for compatibility reasons this is not fully the case yet. We show you how you can change the default name branch later.

Key points

• git init initializes a new Git repository.
• You only need to initialize a directory for version control with Git once.

Tracking changes

Overview

In the following, we introduce the basic Git change workflow in context of our example.

First commit cycle: Add a new file to the repository

First, we want to start collecting information about planet Mars:

• Create a new file named mars.txt:
  • touch mars.txt - Creates a new, empty file named mars.txt.
  • Edit the file mars.txt and add the following:
    • Add the following line: Cold and dry, but everything in my favorite color
    • Please make sure that you added a closing blank line at the end of the file. The blank line is important to make sure that Git properly shows the changes between different versions.
    • Please make sure that you saved the file. You can check it by running the command cat mars.txt which prints the actual file content.
  • git status - Shows the current status of the planets repository:
    • The output indicates that there is one new file (might be indicated by red colored text output).
    • This file is not yet under version control.
• Put the file under version control:
  • git add mars.txt - Adds the new file to the repository. Git tracks from now on the changes to this file.
  • git status - Indicates the changed repository status:
    • There is one new file.
    • This file has been put under version control (might be indicated by green colored text output).
    • This file is not yet committed.
• Record the changes in the version history:
  • git commit -m "Start notes on Mars as base" - Creates the first commit (the so-called root commit) which records the changes in the history of the repository.
  • git log - Displays the history of the planets repository which shows one commit including its commit ID (full SHA-1 hash), the commit author (your configured name and email address), the commit date, and the commit message (full message).
  • git status - Indicates that there are no uncommitted changes anymore.

Congratulations - You performed your first commit!

Second commit cycle: Change an existing file of the repository

Now, we want to collect further information about Mars and focus on Wolfman:

• Edit the file mars.txt and change the following:
  • Add the following line: The two moons may be a problem for Wolfman
  • Please make sure that you added a closing blank line and saved the file properly.
  • git status - Shows that the file mars.txt has been modified (might be indicated by red colored text output).
• Let us take a look at the actual changes:
  • git diff - Shows all changes in comparison to the last committed version.
  • In our case, the output indicates that we have added one new line to the file mars.txt.
• Add the changes to the repository:
  • git add mars.txt - Adds the changes to the repository and marks them for the next commit.
  • These changes are collected in the so-called staging area.
  • git status - Indicates that these changes go into the next commit (might be indicated by green colored text output).
• Record the changes in the version history:
  • git commit -m "Add concerns about effect of Mars' moons on Wolfman" - Creates the second commit which records the changes in the version history.
  • git log - Shows the second entry in the version history. The first commit is its parent commit.
  • git status - Indicates that there are no uncommitted changes anymore.

We performed the basic Git change workflow for the second time:

• Modify: First, do your changes (e.g., add new files, change / remove files already under version control).
• Add: Add the changes which should go into the next commit into the staging area.
• Commit: Record the accumulated changes of the staging area in the version history.

The Software Carpentries, CC-BY 4.0

Third commit cycle: Local vs. staged changes

Finally, we want to add information about the Mummy:

• Edit the file mars.txt and change the following (Modify):
  • Add the following line: But the Mummy will appreciate a lack of humidity
  • Please make sure that you added a closing blank line and saved the file properly.
• Add the changes to the repository (Add):
  • git add mars.txt - Adds the changes to the staging area.
• Let us take a look at the actual changes:
  • git diff - Indicates no changes because they have been already transferred in the staging area.
  • git diff --staged - Shows the newly added line. It shows the differences between the staging area and the last commit. You can use it to find out about the changes which are part of your next commit.
• Record the changes to the file in the version history (Commit):
  • git commit -m "Discuss concerns about Mars' climate for Mummy" - Creates the third commit which records the changes in the version history.
  • git log - Shows the third entry in the version history.
  • git log --oneline - The option --oneline provides a much more compact view of the history.
  • git status - Indicates that there are no uncommitted changes anymore.

We performed the basic Git change workflow for the third time:

• Git allows you to build your next commit in the staging area from your different modifications step-by-step.
• This approach helps you to create commits which are focused on one aspect and do not mix unrelated changes.
• If you find it hard to find a good commit message subject, you might have accumulated too many unrelated changes in one commit.

The Software Carpentries, CC-BY 4.0

Quiz time

Key points

• We introduced the basic Git change workflow:
  • Modify: Change your files.
  • Add: Add the changes via git add into the staging area.
  • Commit: Record the changes of the staging area via git commit in the version history.
• Files can be stored in a project’s working directory (which users see), the staging area (where the next commit is being built up) and the local repository (where commits are permanently recorded). git status helps you to keep the overview.
• Keep your commits focused on one aspect and do not mix unrelated changes.
• Write a commit message that accurately describes your changes.

Exploring history

Overview

In this episode, we want to work with the version history and explain how you can restore older versions.

Working with the version history

Let us change the mars.txt again and see how we can compare a modification with different committed versions:

• Edit the file mars.txt and change the following:
  • Add the following line: An ill-considered change
  • Please make sure that you added a closing blank line and saved the file properly.
• You can compare the mars.txt with different versions using the HEAD pointer which references the most recent commit:
  • git diff HEAD mars.txt - Compares the mars.txt with the last committed version (represented by HEAD).
  • git diff HEAD~1 mars.txt - Compares the mars.txt with the second last committed version (represented by HEAD~1).
  • git diff HEAD~2 mars.txt - Compares the mars.txt with the third last committed version (represented by HEAD~2).
  • git diff HEAD~3 mars.txt - Tries to compare the mars.txt with the fourth last committed version (represented by HEAD~3). However, this attempt results in an error because such a commit does not exist.

HEAD~<NUMBER> allows you to navigate the commit history relatively starting from the most recent commit. In addition, you can use the commit ID directly to reference a specific version:

• Determine the commit ID of the third last commit:
  • git show HEAD~2 mars.txt - Shows the “content” of the commit including the commit ID.
  • Alternatively, you can use git log --oneline to find out the commit ID.
• Copy the commit ID. Normally, you only require the first 7 digits to uniquely identify a commit.
• git diff <copied commit ID> mars.txt - Shows the same output as git diff HEAD~2 mars.txt

You can usually use a commit ID or a HEAD based expression, if a Git commands expects a reference to a commit.

Restore older versions

Imagine that we changed our mind about our last change and want to discard it:

• git status - Shows that the mars.txt changed but these changes have not yet been staged. In addition, the output indicates that we can use git restore to discard the changes.
• git restore mars.txt - Discards the changes and restores mars.txt to the content of the last commit.
• Let us check the restored the version:
  • cat mars.txt - Shows that mars.txt is back to last committed version.
  • git status - Indicates that there no modifications in the repository.

Now, we want to restore an even older version of mars.txt:

• git restore -s HEAD~2 mars.txt - Restores the mars.txt content of the initial commit.
• cat mars.txt - Shows the content of the initial commit.
• git status - Shows that mars.txt has been modified.

Finally, we want to restore the last committed version again:

• git restore mars.txt - Restores the last committed version of mars.txt.
• cat mars.txt - Shows the content of the last commit.
• git status - Shows no more modifications.

Key points

• You can reference a commit by its commit ID or relatively via HEAD pointer expression.
• You can use git restore to discard (staged) changes and restore the content of older versions.

Ignoring things

Overview

Sometimes, you want to make sure that certain files such as temporary files or files containing sensitive data are not added accidently to your Git repository. Git allows you to define .gitignore files for this purpose.

Create some temporary files

First, we create some temporary files which we do not want in our repository:

• mkdir results - Creates the directory results.
• touch a.dat b.dat c.dat results/a.out results/b.out - Creates different temporary files in the results directory and in the root directory of our repository.
• git status - Shows indicates three new files and one new directory.

In such a situation, you can quickly do mistakes and accidently add some of these files to your repository. For example, if you use git add ..

Add a .gitignore file

We can define which files we want to ignore by adding a .gitignore file:

• touch .gitignore - Creates the file .gitignore which we can use to specify file name patterns of files we want to ignore. Please make sure that you do not misspell the file name because otherwise it will not work.
• Edit the file .gitignore:
  • Please add the following content:

  *.dat
  results/
  
  

  • Please make sure that you added a closing blank line and saved the file properly.
• In this example, we ignore all files with the file ending .dat and the directory results. You can use the * character to express an arbitrary number of characters. Every line can contain one file pattern. Git evaluates the file line by line from top to bottom.
• git status - Indicates that our .gitignore definition works and only shows the new file .gitignore. The other files are no longer indicated as modifications in your repository.

Finally, we add the .gitignore file permanently to our repository:

• git add .gitignore - Adds the .gitignore file to the staging area.
• git commit -m "Ignore data files and the results folder" - Creates a new commit and adds the .gitignore file to your repository.
• git status - Indicates no further modifications in the repository.

From now on, everyone who works with your repository already has the proper definition of ignored files.

Key points

• You can use .gitignore files to avoid adding unwanted files to your Git repository.

Working with branches

Overview

In the following episode, we introduce the concept of branches and how you work with them on the basis of the feature branch workflow.

A branch is a specific series of commits in the repository:

• Right now, we only have one branch named main which contains all our commits and starts from the root commit.
• You can create a new branch starting from any commit and refer to it with a specific name. For example, you could create a new branch named new from our last commit on the main branch.
• You can decide on which branch you add a commit by switching to this branch. For example, you could switch to the branch new. Afterwards, all new commits are associated with the new branch. You have to explicitly switch to the main branch to add commits there again.
• You can integrate the changes of a branch into another branch by merging these branches. For example, you could decide to merge back all our changes on the new branch to the main branch. Afterwards, the commits of the new branch are also part of the main branch’s history.

Branching is a general concept of version controls systems such as Git. There are different reasons to use branches, for example, working in isolation on a specific task. Patterns such as the feature branch workflow provide guidance on how to use branches in a meaningful way.

The main ideas of the feature branch workflow are:

• There is only one long-living branch (main branch) which reflects the current reference version (“truth”) of the repository.
• The main branch acts as a synchronization point for starting new work and integrating finished work.
• The actual work is performed on so called feature branches. Once the work is considered finished and stable, the changes are integrated back into the main branch.
• Feature branches exist only temporary and are short-lived. You do not reuse them to perform new work. Instead you create a new feature branch.

The feature branch workflow is used quite often in context of Git. It also provides the basis for features of code collaboration platforms such as “merge requests” (GitLab) and “pull request” (GitHub).

Working with the feature branch workflow

In the following, we contribute more information about the Mummy concerning Mars by using the feature branch workflow. There are a couple of things which we want to prepare before we start.

1. Check that you are in the right place:
   • pwd - Should indicate that you are in the planets directory.
   • git status - Should indicate that your repository does not contain any modifications.
2. Rename your branch to main if needed:
   • If the output of git status starts with On branch master, you need change the branch name as follows:
     • git branch -m master main - Manually renames your branch from master to main.
     • git status - Should now indicate that you are On branch main.
3. Configure some useful details:
   • git config --global alias.graph "log --oneline --graph --all --decorate" - Configures a new Git command git graph which you can use to see a comprehensive summary of the version history of your repository across all branches.
   • git config --global commit.verbose true - Configures Git to show the changes of a commit when Git launches the editor on committing time.

Now we are ready to start! git graph should indicate a version history similar to the following figure:

Set up the feature branch

We create a new branch named mummy-info:

• git branch - Shows all existing branches. Currently, there is only the main branch.
• git branch mummy-info - Creates a new branch named mummy-info starting from the last commit.

We have created our feature branch but we still have to switch to it:

• git switch mummy-info - Switches to the new branch mummy-info.
• git status - Indicates that you are now On branch mummy-info.

Now, we are ready to start working on our actual task.

Perform the work on the feature branch

We perform two commits on the feature branch:

• Edit the file mars.txt and commit the changes:
  • Add the following line: Mummy will appreciate sand storms on Mars
  • Please make sure that you added a closing blank line and saved the file properly.
  • git add mars.txt- Add the changes to the staging area.
  • git commit -m "Add advantages for the Mummy" - Records the change in the version history. The command output indicates that you performed the commit on branch mummy-info.
• Edit the file mars.txt and commit the changes:
  • Adapt the first line and attach at its end: (for Dracula)
  • git add mars.txt- Add the changes to the staging area.
  • git commit -m "Concretize the first fact" - Records the change in the version history.

We are done with our task. Afterwards, git graph should indicate a version history similar to the following figure:

Simulate ongoing work on the main branch

Imagine that someone else changed mars.txt and integrated the changes back to main. We perform this change directly on main for demonstration purposes.

• Switch back to the branch main:
  • git switch main - Switches to the branch main.
  • git status - Indicates that you are now On branch main again.
  • cat mars.txt - Shows that the content of mars.txt is back to the content of the fourth commit.

    Cold and dry, but everything in my favorite color
    The two moons may be a problem for Wolfman
    But the mummy will appreciate a lack of humidity
    
    

• Edit the file mars.txt and commit the changes:
  • If you have still opened mars.txt in your editor, please double-check that it shows the right content. If in doubt, please close the editor and reopen the file.
  • Add the following line: Generating solar energy is less effective on Mars
  • Please make sure that you added a closing blank line and saved the file properly.
  • git add mars.txt- Add the changes to the staging area.
  • git commit -m "Add information about energy generation" - Records the change in the version history. The command output indicates that you performed the commit on branch main.

git graph indicates a split in the commit history because there are two different commits which are based on the same parent commit:

Merge the feature branch

Now, we want to integrate our work back into the main branch. There are several ways to do this. In this episode, we use the standard way via git merge which preserves the branching structure.

• First, you have to switch to the branch which receives the changes of the other branch. In our example, we want to integrate the changes of the mummy-info branch into the main branch. For that reason, we have to switch to the main branch. Luckily, we are already on the right branch!
• Next, we have to perform the actual merge operation:
  • git merge mummy-info - Starts the merge process and shows the current result.
  • Git tried to automatically merge the changes of mars.txt from both branches. But it failed because both file versions contain a different line 4.
  • For that reason, we have to resolve the conflict manually. Without the conflict, we would be already done.

Let us resolve the merge conflict:

• git status - Indicates that you are still in the merge process and that mars.txt contains conflicts.
• Open the file mars.txt in your editor and resolve the conflict manually:
  • mars.txt should look similar to the following:

    Cold and dry, but everything in my favorite color (for Dracula)
    The two moons may be a problem for Wolfman
    But the mummy will appreciate a lack of humidity
    <<<<<<< HEAD
    Generating solar energy is less effective on Mars
    =======
    Mummy will appreciate sand storms on Mars
    
    >>>>>>> mummy-info
    

  • Conflict markers <<<<<<< HEAD ... ======= ... >>>>>>> <branch name> are used to indicate each conflict.
  • In our case:
    • The first line could be merged without problems but line four could not.
    • We have to resolve the conflict for the last line manually.
    • We decide to keep both facts, remove the conflict markers and save our changes.
• git add mars.txt - Tells Git that the conflict has been resolved.
• git commit - Opens the configured Git editor and shows a default merge commit message. In addition, you can see the resulting changes introduced by this commit. We use the default commit message and close the editor.

git graph shows that both branches have been merged:

The merge operation resulted in a so called merge commit:

• A merge commit is a commit with more than one predecessors. In our case, we have two.
• You can still identify the branch mummy-info including its two commits.

Finally, we want to clean up the feature branch:

• git branch -d mummy-info - Removes the branch mummy-info. If Git found out that the branch has not been already merged, it would not perform the removal operation.
• git graph - Shows the same output but only the label mummy-info is no longer there. However, the branch structure is still in place and a permanent part of the version history of the main branch.

Key points

• Branching is an important concept in Git. Patterns such as the feature branch workflow provide guidance on how to use branches in a meaningful way. Please see Martin Fowler: Patterns for Managing Source Code Branches for more patterns.
• The feature branch workflow works as follows:
  • Create the feature branch and switch to it: git branch <feature branch name> and git switch <feature branch name>.
  • Perform your task: Modify - Add - Commit
  • Merge the feature branch into the main branch: git switch <feature branch name> and git merge <feature branch name>.
• There can be conflicts when branches are merged. The process of resolving a conflict is similar to the usual commit workflow:
  • Modify: Resolve all conflicts.
  • Add: Add all changes to the staging area via git add.
  • Commit: Conclude the conflict resolution and the merge operation via git commit.

Wrap Up

Day 2: Introduction to GitLab

Welcome and Introduction

Introduction to GitLab

Overview

In the following, we start using GitLab and take our first steps.

GitLab is a code collaboration platform built on top of the version control system Git. It is focused on software development and adds features for managing projects, team collaboration, and automating tasks around the core Git features. It is a purely Web-based application which means that you are not forced to install Git. However, it can be practical though depending on the project.

There are different similar systems available:

• GitHub: Popular cloud service, launched 2008, now owned by Microsoft, the current “home of open source”
• Bitbucket: Cloud service launched 2008 by Atlassian
• Codeberg: Cloud service launched 2019 by non-profit Codeberg e.V., cloud service for open source projects only
• SourceForge: Cloud service launched 1999, the former “home of open source”

First steps in GitLab

Now, we want to start working with the GitLab Web interface. In this workshop, we are using the following GitLab instance: Helmholtz GitLab Instance.

• Please open https://codebase.helmholtz.cloud in your Web browser and log in with your credentials. Your welcome screen can look a bit different depending on the fact whether you already work in some GitLab projects on this instance or not.
• The main elements of the Web interface are organized as follows:
  • On the left side, you find the navigation bar. It provides access to the different GitLab features. In addition, you can reach your user profile (top right, profile image) and the help page (bottom left, Help link).
  • On the right side, there you can find the actual content page. For example, there you could see an overview about your projects or the details of a GitLab project.
• GitLab organizes content into GitLab projects and groups:
  • A GitLab project is built around a Git repository. It provides features to access and change the Git repository. In addition, it offers further collaboration and automation functionalities, such as issue tracking for organizing tasks or build pipelines to automatically verify changes of the Git repository.
  • GitLab groups are similar to directories and help you to organize the (potentially) large number of GitLab projects. A GitLab group can contain GitLab projects or another group (sub-group).
  • You have access to a personal space in which you can store a specific number of personal GitLab projects depending on the GitLab instance configuration.

Key points

• GitLab is a Web-based code collaboration platform focused on supporting teams in the software development process.
• GitLab is built around the concepts of Git but offers many more features.
• There are different GitLab instances around, please make sure that you understand which you can use.

Remote Repositories with GitLab

Now, we want to collaborate with others via GitLab.

• So far we have only worked locally. Usually, however, you work with several Git repositories, between which you synchronize.
• We are about to introduce another repository, which is managed by GitLab. This could also be managed by GitHub or another local Git repository.
• Repositories that are not on your own hard drive are called remote repositories.
• See also for different repository topologies: https://git-scm.com/about/distributed

Publish the local Git Repository in GitLab

Set up a personal access token

In the following, we will set up an access token that you can use to authenticate via your Git client.

• Edit your profile (right upper corner) and switch to the section Access Tokens: https://codebase.helmholtz.cloud/-/profile/personal_access_tokens
• Set the name to git-access
• Leave the expiration date as defined. I.e., the access token can only be used until that date.
• Select the scopes read_repository and write_repository. The scopes define what you can do with the access token. In our case, we only want to read/write the Git repository.
• Generate your access token by clicking the Create personal access token button.
• Copy the access token and put it aside in a text editor or similar. We need it for the next step!

Please note that you cannot retrieve the access token after you closed the Web page. But this is actually no problem as you can remove / add new access tokens at any time.

Create a new GitLab Project

• Click the + => New project/repository (toolbar on the top) which opens the dialog for creating a new project:

  • Select Create blank project
  • Project name => planets-<username>
  • Pick a group or namespace => Select 2025-04-22-introduction-to-git-and-gitlab
  • Deselect Initialize repository with a README
  • Click Create project which creates a new GitLab project and redirects you to its overview page.

• Further remarks:

  • The Project URL allows you to select different namespaces (groups, subgroups, your username namespace). We create a project in a group namespace. Later projects can also be moved to other namespaces.

  • Even if the Project description is optional, please use them because they make it easier to navigate in project lists later.

  • You can define different visibility levels:

    • private: Only explicitly added project members can see and do something with the GitLab project.
    • internal: Only authenticated users of the GitLab instance can see/clone/fork the GitLab project.
    • public: The GitLab project is visible/cloneable even for unauthenticated users.
    • Please note that depending on the GitLab instance configuration, not all visibility levels might be available.

  • We do not initialize the GitLab project with a README.md file. Otherwise we have problems pushing our local Git repository directly to our GitLab project.

  • When creating the GitLab project, GitLab runs a git init --bare in the background.

  • GitLab project = Git repository + a lot of further useful tools

• On the GitLab project page:

  • On this page you can directly create files (e.g., README, LICENSE, CHANGELOG, …). We do not use this feature. Otherwise we have problems pushing our local Git repository directly to our GitLab project. But later we might use them :)
  • There are also references to steps that can be carried out (create new repository, link existing folder, push existing repository). automatically GitLab infers the right protocol (HTTPS, SSH) from your user account preferences. We will use the HTTPS protocol for transferring our repository.

Push the local Git Repository to your GitLab Project

• Switch again to your Git shell.
• git status - Please make sure that there are no uncommitted changes and that your on branch main.
• git remote - Only shows the defined remote labels.
• git remote add origin <copied URL> - Creates a link to the remote Git repository on Helmholtz GitLab Instance. URL should look similar to: https://codebase.helmholtz.cloud//2025-04-22-introduction-to-git-and-gitlabplanets-<username>.git
  • Click Clone => Clone with HTTPS and use the copy button on your GitLab project page.
• git remote -v - Displays two entries for origin, one where we ‘push’ changes to and another from where we ‘fetch’ changes. These URLs are usually the same. Different URLs and thus repositories are possible, but are only used in special sync workflows. We do not explain them here.
• So far we have only created the link, but not yet used it. For that we need network access and have to authenticate ourselves in GitLab.
• Use git remote set-url <remote name> <new url> to rename a url
• git push - pushes the content of our repository but shows an error message because we have not connected the branches. Luckily, Git tells us what to do.
• git push --set-upstream origin main - Instructs Git to link the current branch the branch main in repository called origin (which is on GitLab). Link is created and data is transferred. Output shows that a new branch was created on the remote repository and that the files were transferred.
• Reload the GitLab project page. Now you can see the files and their history on GitLab. Congrats :)

Hint: --set-upstream git push --set-upstream origin main Username for ‘https://codebase.helmholtz.cloud’: token Password for ‘https://token@codebase.helmholtz.cloud’: Now enter your access token as the password. This does not appear in the window, do not pay attention, simply press Enter.

Hint: Configure a credential manager

In general, on Windows and Linux (in a window manager) a credential manager ist used to cache your password. If it does not work, you can configure a credential manager.

https://git-scm.com/book/en/v2/Git-Tools-Credential-Storage#_credential_caching

• Click the History button in the GitLab file view. It shows the same entries that are shown by git log --oneline
• git branch - Displays only local branches.
• git branch --all - Displays remote branches as well.
• git graph - Shows where the remote branches are.
• Via Repository > Files > Edit Button you can change files with the web IDE, stage and commit changes. In addition, you will find typical Git functionalities in the Repository menu as well.

Synchronize the local Git Repository with changed Content

Adapt the mars.txt via the GitLab Web Interface

• Open the GitLab Web IDE by clicking “Web IDE” (just above the file listing)
• Similarly, we want to update the mars.txt.
  • Open it by selecting it on the left.
  • In the editor, add another fact:

    We have to bring our own oxygen
    

  • Finish your commit analogue to the process above: Select “Create commit…”
  • Write a good commit message: Add notes about the Mars atmosphere
  • Select “Commit on main branch”
  • Finish your commit (“Commit” button)

Synchronize your local Git Repository

• git graph - Only shows our local commits but not the changes we did in GitLab. These commits are so far only in the repository on GitLab.

• git fetch origin main - Checks if there is anything new in the remote repository on branch main. The output shows that something was fetched.

• git graph - Now we see the 1 new commit objects in the graph and our HEAD still points to the latest local commit.

• git status - Tells us that we are with our local main branch 1 commits behind the main on the remote repository (origin/main). In addition, the output tells us that we can use git pull to retrieve them.

• git pull - Now we retrieve the commits and apply them to our local main branch. You normally run git pull directly. But in this case everything is directly applied to your local branch.git fetch allows you to view the changes first and then to decide whether the changes are wanted. For example, you could display them via git diff main origin/main.

• If you use git pull, it implicitly performs a git merge as well. The git status hint that it can be fast-forwarded tells us it will not create a merge commit and more or less treat the two branches as one.

• git status - Indicates that everything is clean again

• git graph - Now both main branches point to the latest commit.

Contribution Workflow: Issues and Merge Requests

Why bother?

• Agreeing on how to handle day-to-day operations increases productivity and reduces the potential for miscommunication
  • Reduces onboarding time for new project members
  • Reduces setup time for new projects
• Workflows that deal with similar types of projects should be similar
  • There is no one-workflow-to-rule-them-all
  • Adapt established workflows to team- or project-specific needs

An Example Contribution Workflow

A contribution workflow regulates how changes to the files of the project get planned, agreed upon, executed and verified.

In this course, a workflow will be presented that is especially suited for GitLab (or GitHub) and can be applied for many types of projects. The following is an overview, the details will be subject of the following episodes.

1. Open an issue
   • Detail the intended changes
   • Notify potential stakeholders
2. Discuss the details
   • Clarify open questions.
   • When working face-to-face this can be kept to a minimum. Write down the decisions that were made in meetings or attach a protocol.
3. Open a new merge request
   • This signals that someone is working on it
   • A merge request automatically generates a Git branch to be used.
4. Make iterative changes
   • Add commits to the branch
   • When satisfied request a review of the changes made
   • Adapt according to the reviews
5. Once the reviewers approved the changes, merge the working branch into the main branch of the project (or any other target branch for that matter)

As a rule of thumb:

• Discuss the details of the problem and solution approaches in the issue
• Discuss the actual presented solution in the merge request

Issues

• Issues are a conversation-style medium for outlining, planning and managing tasks and processes
• They form the entry point for common use-cases like
  • Bug reports
  • Feature requests
  • Discussions and decision making
• Issues can be assigned to a person who is responsible for handling the issue
• A real world example: https://gitlab.com/gitlab-org/gitlab/-/issues

Live Coding: Create an Issue

• (Issues => New issue, fill in details, Create issue)
  • Title: My first issue
  • Assignee: Yourself
• Start a discussion in the comment section
• See the result in the issue overview page (Issues)

How to Write Good Issues

Writing good issues is a valuable soft-skill for teamwork. A good issue draws attention, has high information density and provides all details to get started with solving it.

• If available, use the appropriate issue template
• Be brief and precise
• Use the markdown formatting
• Provide all required details

When and How to Close Issues

• Issues can lead to merge requests
  • When this merge request gets closed or merged, the associated issue automatically will be closed
• Issues can also be closed directly if no merge request is needed
  • When closing an issue without a merge request, give a reason and/or summary as last comment
• It is recommended to regularly (e.g. monthly) schedule an issue-housekeeping
  • Check if issues are still relevant
  • Add updates to these issues if available
  • Close issues that are no longer valid
    • If the issue has been solved, add a link to the commit or merge request that solved it

Labels

• Labels are a tool for categorization
• They can be attached to issues or merge requests
• Available either for a single project (project label) or all projects within a group (group label)
• Labels have a name, an optional description and a color
  • Colors can be chosen from a list
  • Note: The intuitive meaning of colors can vary between cultures
• Labels can be prioritized and manually given a priority
• Do agree on a label policy and document it in the contribution guide

Example Use Cases for Labels

• Workflow-oriented
  • ToDo, Planning, In Progress, Review
• Type-oriented
  • Bug, Fix, Feature, Maintenance, Chore, Documentation, Discussion
• Priority-oriented
  • Critical, High, Medium, Low
• Affected subsystems
• Expected difficulty
• Common other labels
  • Help Wanted, Good First Issue

Live Coding: Create Labels

• Create the following labels (Project information => Labels, New label):
  • Documentation (color blue)
  • Discussion (color blue)
• Switch to your issue (Issues, Select the issue)
  • Assign the label Discussion to your issue
  • Close the issue (Close issue)
• See the result in the issue overview page (Issues)

Other Notable Features

• Issue Templates
• Milestones
• Boards
• Cross-References in Markdown

Merge Requests

What are Merge Requests

• Merge Requests (short MR) visualize the development process on a git branch, including:

  • Commits
  • Conversations
  • Assignees
  • Relations to issues and other MRs

• They form the basis for reviews

• Note: This feature has different names on different platforms:

  • In GitLab: Merge Requests
  • In GitHub: Pull Requests

Creating Merge Requests

• MRs can be created based on
  • Existing issues (will create a new branch with an automatically generated name)
  • Branches pushed via git
• After creation, a MRs’ title, description and merge options can be set anytime
• Like issues, MRs can have labels and assignees

Making Changes

• To add changes to the MR
  • Push commits to the MR branch via git
  • Use the WebIDE

Interaction

The interaction principles (commenting, adding files, referencing) are similar to the ones already seen for issues. Particularly, when performing reviews, sticking to a good review practice makes the difference between reviews being a dreaded nuisance or a valuable team experience. We refer to Philpp Hauer’s Blog Post on Code Reviews for further information.

Live Demonstration: Contribute a README

The README is the front page of your project. You can learn more about important files here: https://codebase.helmholtz.cloud/hifis/software/education/hifis-workshops/foundations-of-research-software-publication/workshop-materials/-/blob/master/episodes/03_add-essential-documentation.md

• SETUP:

  • One instructor is the Contributor and the other one is the Owner.
  • The Owner adds the Contributor to his/her GitLab project in the role Developer.
  • The Contributor starts by cloning the Git repository of the Owner.

• Create an issue (Issues => New issue, fill in details, Create issue) (role Contributor):

  • Title: Add a README
  • Description: We want to provide an initial README file which serves as an introductory page for the project.
  • Assignee: Yourself
  • Label: Documentation

• Create a merge request from the issue (Create merge request, leave details as they are, Create merge request) (role Contributor)

  • Clone the other’s repository for further development (role Contributor)

• CHANGE: Change the branch from the local Git repository (role Contributor)

  • Pull the remote repository (git pull)
  • Switch to the branch (git switch 2-add-a-readme)
  • Add the README.md file with the following content:

    # Planets
    
    This repository contains notes about potential planets for migration.
    
    

  • Commit message: Add an initial README
  • Push to the remote branch (git push)
  • Show the changes of the merge request
  • Add the Contributor section via a second commit and show the results.

• Go back to the merge request (Click on the link !1) and watch the changes (role Contributor)

  • There are changes to review now
  • Mark the merge request as ready (Mark as ready)
  • Assign the Owner as reviewer

• Review and merge the changes: (role Owner)

  • Review the changes and show some of the interaction options (comments, change proposals)
  • Merge the merge request (Merge)

• Check the result in GitLab: (role Owner)

  • See the changes in merge request list (Merge requests)
  • See the changes in the issue list (Issues)
  • See the changes in the Git history (Repository => Graph)

• Update the local Git repository: (role Contributor)

  • Switch to the Git shell
  • Switch to the main branch: git switch main

    Older versions of Git use git checkout main

  • Pull the changes from the remote repository: git pull
  • Remove the local branch via: git branch -d 2-add-a-readme
  • To get rid of the no longer needed remote branches, do a special fetch: git fetch --prune (will remove all origin/… branches that no longer exist)

Contribution Workflow: Team Exercise

Now we want to try out the full contribution workflow practically in pairs of two persons!

Task:

• Contribute information about Venus using the presented GitLab Contribution Workflow.
• For that purpose, we divide all participants in pairs of two persons and send you to dedicated breakout rooms!

General Process

• Decide about the Owner and Contributor roles:
  • Owner adds the contributor to the project and reviews the changes
  • Contributor solves the actual task
• Perform the workflow together (see below)
• You can use the screen sharing feature to better work together.
• Please return to main room until 14:45! If you have still some time left, please switch roles and try again and/or experiment with the process on your own :)

Task and Workflow Description

Grant the Contributor access to your GitLab Project (OWNER)

• Select Project information => Members and click Invite members
  • Search and select the name of the contributor
  • Select in the Select a role menu the role Developer
  • Click the Invite button
• The contributor should show up in the project member list

Contribute Information about Venus (CONTRIBUTOR)

• Switch to the GitLab project of the Owner
• Create an issue (Issues => New issue, fill in details, Create issue):
  • Title: Add information about Venus
  • Description: We want to collect some basic information about Venus.
  • Assignee: Yourself
  • Label: Documentation
• Create a merge request from the issue (Create merge request, leave details as they are, Create merge request)
• Switch to your Git shell and contribute the information:
  • Visit the GitLab project overview page of the Owner and copy the URL from Clone => Clone with HTTPS
  • Clone the Git repository: git clone <URL> planets-<OWNER NAME>
  • Change into the cloned repository: cd planets-<OWNER NAME>
  • Switch to the branch: git switch 3-add-information-about-venus (Please double-check the name of the branch in your case!)

    Older versions of Git use git checkout 3-add-information-about-venus

  • Add the file venus.txt with the content:

    Venus is full of love
    Wolfman will appreciate the absence of moons
    
    

  • Commit the change locally:
    • git add venus.txt
    • git commit -m "Add initial information about Venus"
  • Push the changes to the remote repository: git push
• Switch to the merge request:
  • Mark the merge request as ready (Mark as ready)
  • Assign the Owner as Reviewer

Review the Contribution and Merge it (OWNER)

• Check and provide feedback via comments
• Approve the merge request (Approve)
• Merge the mere request (Merge)
• Check the following aspects:
  • See the changes in merge request list (Merge requests)
  • See the changes in the issue list (Issues)
  • See the changes in the Git history (Repository => Graph)

Update your local Git Repository (CONTRIBUTOR)

• Switch to the Git shell
• Switch to the main branch: git switch main

  Older versions of Git use git checkout main

• Pull the changes from the remote repository: git pull
• Remove the local branch via: git branch -d <BRANCH NAME>
• To get rid of the no longer needed remote branches, do a special fetch: git fetch --prune (will remove all origin/… branches that no longer exist)

Wrap Up

Further readings

• Official Git reference
• Flight rules for Git
• First aid Git
• Interactive Git cheatsheet
• Martin Fowler: Patterns for managing source code branches

License

The workshop material is based on the swcarpentry/git-novice: Software Carpentry: Version Control with Git, June 2019 lesson which has been created by the Software Carpentries and has been further developed by the German Aerospace Center (DLR) and the Helmholtz-Zentrum Dresden-Rossendorf (HZDR).

If not noted otherwise, all content is licensed under CC-BY 4.0. A detailed overview about the copyright holders and licenses can be found in the workshop materials repository.