website/guide/infra/git.md

Git & GitLab

::: details {open} If you are already familiar with this, all you need to know is that the D-INFK GitLab can be found at https://gitlab.inf.ethz.ch :::

Git is a Version Control System, short VCS. It enables you to version your code, allowing you to effectively, safely and efficiently work on software together with other people.

While EProg teaches you how to use Git... well... sort of, this guide is designed to give you a much deeper understanding, while also covering what is taught in EProg.

::: tip Why learning Git is so important Git is the predominant VCS system in the industry and has been for a very long time. If used properly, it can save you hours of headaches, preventing loss of progress. But, to get these benefits, you need to know how to use it. And that takes time, but it is well worth investing the time to learn it! :::

The basics (Terms, etc)

First a few terms to remember:

• Repository (= Repo): Can be thought of as a folder, with some metadata.
• Commit: The act of making changes "permanent" in a git repo. Permanent in quotes, because this can be undone
• Remote: A Remote is a computer different from the local one (typically referred to as server) that has a copy of the repo and is connected to the current repo
• Stage: The act of preparing changes for commit. This is used to decide which changes to commit together or not to commit yet
• Diff: Short for difference, a comparison of two versions of a file
• Pull: Pulls commits synced to the remote into the current tree
• Push: Pushes local commits to the remote
• Rebase: If you have committed changes to the repo locally and somebody in the mean time has pushed changes to the remote, your own copy needs to be rebased on that version to make sure that there are no conflicts. If there are, you need to resolve them using a diff viewer / merge tool.
• Conflicts: Conflicts happen if changes to the same line in the same file were made on the remote and locally before the local copy was synchronized.
• Branch: If you envision the commit history to be a tree (which it in fact is), then you can create a new branch to make for example a larger, breaking change that can't yet be added to main due to possibly needing to fix issues in main, etc.
• Merge: The act of combining two development histories, typically of two branches
• Dirty tree: If there are uncommitted changes in your file tree.
• Stash: A stack on which you can store changes that are not ready to be committed, for example to pull in changes without having to a rebase straight away, or if you are working on something, then notice a different issue, but your changes are not ready to commit.

You download a new repo (called cloning) using git clone <url to repo>, or use your IDE (see below)

The art of Commits

Many people, even EProg TAs (trust me, I asked one) would tell you that what you write as your commit message doesn't matter much. They'd be right that for EProg, it doesn't matter much, but if you work in a larger project yourself, or worse still, together with other people, writing proper commit messages is VERY important.

I myself have been doing it wrong for years and still am not doing it right in my summaries repo (because there it doesn't matter as much).

In early 2026 I have finally learned how to write proper commit messages, according to the Conventional Commit V1.0.0 Specification.

You don't need to take it to that extreme straight away, but I would recommend following the following format:

• feat(<component>): <description> (or feat: <description> if you can't find a simple component name) to describe new features.
• fix(<component>): <description> for a bug fix (again also fix: <description> possible)
• Append a ! to descriptor if there are breaking changes (like feat!(cli args): argument x renamed to y)
• Use docs(<component>): <description> for updating docs
• Use chore(<component>): <description> for updating things like CI/CD, etc

This of course means that you have to commit regularly, which is a good practice, as it allows you to more easily roll back changes if something goes wrong. Furthermore, the description mentioned everywhere should be a brief description of your changes, then a more detailed description in the commit description.

Syncing changes (push, pull, etc)

One of the biggest sins in git is to use git push --force, i.e. a Force Push. This IRREVERSIBLY deletes any commits made to the remote and makes the upstream an exact copy of your local repository.

Other than that, remember to always pull changes in before you start work to not accidentally get a merge conflict on rebase. For EProg that is unlikely to ever happen, but you aren't just learning git for EProg, you will be using git more in the future.

Branches

Git branches are very often underused, even though they are very useful. Ideally, when developing software, you only ever touch the main branch when you have a complete implementation of a new feature. This means that the main branch should always compile, work (mostly) as expected and there won't be any unfinished features.

It further means that if there is an issue with the existing version of some feature, you can fix that easily by going back to the main branch, creating a new branch from it, fixing the feature and merging it back.

This is also where pull requests come in. This is a GitHub / GitLab / Gitea / Forejo / etc feature that allows other people to merge changes of their forks (modifiable copies of your repo) into your repo, called the upstream, without you granting them write access to your repository. You have the chance to review their changes, comment on them and finally merge them into a branch.

You switch branches typically using git switch or git checkout.

The Git CLI

The git CLI is very nice to use and its docs are great, so I only point you to man git.

Git GUIs

Most IDEs (Integrated Development Environments) have a built in Git user interface. It typically has a tree-like icons with dots. You can also use them to do the git commands using an inefficient device, commonly referred to as a mouse. They often also allow you to clone repos.

Alternatively, you can use a Git TUI such as lazygit.

I would however advice against only using git GUIs, as typing a short git command is often quicker than reaching for a mouse. Of course, if you need to resolve merge conflicts, go to your graphical mergetool. Also note that NeoVim, etc can be used as a diff viewer and mergetool.

Authentication

If you use an IDE, chances are that it has its own authentication manager. If you use the CLI, you can use git-credential-manager if you want to use HTTPS authentication, or you can create an SSH key using ssh-keygen -f ~/.ssh/gitlab, then copy the public key to your GitLab account's SSH key settings panel. This is much more secure.