feat: git guide

2026-08-13 17:49:32 +02:00
parent abcf1c366a
commit 7614324ce1
1 changed files with 101 additions and 0 deletions
@@ -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 <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](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(<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`.
 ## 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.