posts: git-basics: fill out branches & references

content/posts/git-basics.md

@@ -34,17 +34,59 @@ I will also be skipping the explanation for the basic workflow of `git add`,
 year students at EPITA, who have used `git` for a whole year to submit their
 project but have not explored some of its more powerful features.
 
-## Branches and references
+## Starting out with branches and references
 
-* Branches and merges
+To me, this is the most essential thing you need to remember when you using
-  * Decentralised
+`git`. It is part of what makes it special, and will be used though-out your
-  * Merges are easy (assuming no conflicts)
+career.
 
-* What HEAD is
+### Why you should use branches in `git`
-  * Why guillotine
-  * What ARE references anyway
 
-* Relative references and other shortcuts
+What makes `git` so useful, and so powerful, is the fact that it was conceived
+from the ground up to operate in a decentralised manner, to accommodate the
+Linux kernel programming workflow.
+
+That model de facto means that branching must be a lightweight operation, and
+merging should not be hassle. Indeed, as soon as you start having people work
+in parallel on a decentralised system, you end up creating "hidden branches":
+each person's development tree is a branch on its own.
+
+If you try merging branches that do not have any conflict, the operation is
+basically instantaneous: to take advantage of that fact I encourage you to use
+branches in your workflow when using git.
+
+### Where is my HEAD
+
+The notion of `HEAD` in `git` can seem strange. You might first have encountered
+it when checking out an older commit. `git status` helpfully tells you that you
+have been guillotined: `HEAD detached at 78f604b`.
+
+To make it short, `HEAD` is a reference pointing to the commit that you are
+currently working on top of. It usually points to a branch name (e.g: `main` or
+`master`), but can also point to a specific commit (such as in the `checkout`
+scenario I just mentioned).
+
+### Revisions
+
+Most of the commands I will show you need you to provide them with what `git`
+calls a revision. This is usually means a way to specify a commit.
+
+There are multiple ways to specify a `revision`, you should know at least two
+of them: `refname` and `describeOutput` which loosely correspond to branch
+names and git tags respectively. Note that `@` is a shortcut for referring to
+`HEAD`.
+
+You can also specify the `sha1` commit hash directly, or relative revisions.
+A relative revision allows you to select the parent of a specific commit,
+you can use the following revisions specifiers:
+
+* `~`: select the first-parent commit
+* `^`: select the nth-parent commit (useful for merge commits)
+
+You can append numbers to those two specifiers, they differ in how they handle
+merges. If you are applying them to a merge commit, `~2` will give you the
+grand-parent of your commit, following the "*first parent*", whereas `^2` will
+give you the "*second parent*" of your commit.
 
 ## History manipulation