From 7614324ce124b2743ebd345e7e8bf0da0487ef80 Mon Sep 17 00:00:00 2001 From: Janis Hutz Date: Thu, 13 Aug 2026 17:49:32 +0200 Subject: [PATCH] feat: git guide --- ersties/git.md | 101 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 101 insertions(+) create mode 100644 ersties/git.md diff --git a/ersties/git.md b/ersties/git.md new file mode 100644 index 0000000..d6dc7a6 --- /dev/null +++ b/ersties/git.md @@ -0,0 +1,101 @@ +# 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 `, 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](https://www.conventionalcommits.org/en/v1.0.0/#pecification). + +You don't need to take it to that extreme straight away, but I would recommend following the following format: +- `feat(): ` (or `feat: ` if you can't find a simple component name) to describe new features. +- `fix(): ` for a bug fix (again also `fix: ` possible) +- Append a `!` to descriptor if there are breaking changes (like `feat!(cli args): argument x renamed to y`) +- Use `docs(): ` for updating docs +- Use `chore(): ` 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`. + + +## 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.