Merge branch '02-git' into 'main'

git lecture

See merge request generic-software-skills/lecture-materials!38

_quarto.yml

@@ -27,7 +27,7 @@ website:
           # - "lectures/example-lecture/slides.qmd"
           - "lectures/intro/slides.qmd"
           - "lectures/command-line/slides.qmd"
-          # - "lectures/git/slides.qmd"
+          - "lectures/git/slides.qmd"
           # - "lectures/programming-paradigms/slides.qmd"
           # - "lectures/data-structures/slides.qmd"
           # - "lectures/complexity/slides.qmd"
@@ -41,7 +41,22 @@ website:
           # - "lectures/file-and-data-systems/slides.qmd"
           # - "lectures/memory-hierarchies/slides.qmd"
           # - "lectures/student-talks/slides.qmd"
-
+      - section: "Exercises"
+        contents:
+          - "exercises/git.qmd"
+          # - "exercises/programming_paradigms.qmd"
+          # - "exercises/data_structures.qmd"
+          # - "exercises/complexity.qmd"
+          # - "exercises/debugging.qmd"
+          # - "exercises/good_scientific_practice.qmd"
+          # - "exercises/user_experience.qmd"
+          # - "exercises/testing.qmd"
+          # - "exercises/git2.qmd"
+          # - "exercises/parallelism.qmd"
+          # - "exercises/hardware.qmd"
+          # - "exercises/file_and_data_systems.qmd"
+          # - "exercises/memory_hierarchies.qmd"
+          # - "exercises/student_talks.qmd"
 
 format:
   html:

exercises/git.qmd

+---
+title: "Git"
+---
+
+Think about different occasions in your studies or work in which Git may help
+you. Are there any limitations?  Summarise your thoughts in a text file and add
+it to your personal course repository.
+
+If you already have some existing scripts/code from you day-to-day work, you
+may want to add those to a git repository and refer to it.
+
+Next week we will randomly select some participants to discuss their thoughts.

lectures/custom.scss

@@ -52,6 +52,10 @@ h2 {
     font-size: .8em;
 }
 
+.tiny {
+    font-size: .4em;
+}
+
 .right {
     text-align: right;
 }

lectures/git/slides.qmd

+---
+title: "Git"
+subtitle: "A Brief Introduction into Git"
+author: "Lukas Kluft and Georgiana Mania"
+---
+
+
+# Version control systems
+
+* Manage a sequence of snapshots (e.g. of folders)
+* Provide tools to handle changes
+* Provide tools for collaboration
+
+## Why version control?
+
+::: {.incremental}
+* **Exchange** _I'll send you my script via mail._
+* **Collaboration** _Sample File (conflicted copy 2019-11-21)_
+* **Storing versions** (properly) _But it worked yesterday..._ 😭
+* **Tracking** _I did not change anything!!11!_ 🤬
+* **Backup** _I replaced the wrong my_file_2_final_final.py_ 😱
+:::
+
+## Git
+
+There are many version control systems out there (e.g. Subversion, CVS, Mercurial). We will focus on [Git](http://git-scm.com) which is the **de facto standard**
+
+![](https://git-scm.com/images/logos/downloads/Git-Logo-2Color.svg "Git logo"){height=10%}
+
+## As easy as **1, 2, 3**
+```bash
+git init .  # Initialize a repository
+git add .  # Add the whole directory content (don't do that)
+git commit -m "Initial commit"  # Commit your changes
+```
+
+```{mermaid}
+gitGraph
+   commit id: "df21a: Initial commit"
+```
+
+## Sequence of snapshots
+
+Commits are linked to form a sequence of snapshots:
+
+```bash
+echo "hello" > world.txt
+git add world.txt
+git commit -m "add world"
+```
+
+```{mermaid}
+gitGraph
+   commit id: "df21a: Initial commit"
+   commit id: "315f2: add world"
+```
+
+## The basic workflow
+
+* Git offers plenty of functionality that is extensively documented
+
+* You will only need a **handful of commands** in your day to day work:
+
+  ```bash
+  git status  # show which files have changed
+  git diff my_file  # show what has changed
+  git add my_file  # stage changes
+  git commit  # commit your changes
+  ```
+
+## Configuration
+
+* Each commit is attributed to an author
+
+* The concept or authorship is heavily used on other platforms (e.g. GitLab)
+
+```bash
+git config --global user.name "Your Name"
+git config --global user.email "youremail@yourdomain.com"
+```
+
+## Hands-on Session {background-color=var(--dark-bg-color)}
+
+1. Configure the username and email adress in your local git client
+2. Initialize an empty Git repository
+3. Create a file and add it to the repo
+3. Change the file, inspect the differences, and commit the changes
+
+:::{.info .smaller}
+On Levante: `module load git`
+:::
+
+# Branches
+
+::: {.incremental}
+* Are versions of the code identified with a name (besides the existing hash)
+* Are used to encapsulate the changes required for a feature/bugfix
+* Allow incremental development without impacting the other branches
+:::
+
+::: {.notes}
+Make sure to introduce feature and bugfix
+:::
+
+## Create a branch {.leftalign}
+
+Create a branch `develop` to work on a feature
+
+```bash
+git branch develop
+git switch develop
+```
+
+```{mermaid}
+gitGraph
+   commit
+   commit
+   branch develop
+   checkout develop
+   commit
+   commit
+```
+
+::: {.fragment fragment-index=0}
+Show differences between two branches
+```bash
+git diff develop..main
+```
+:::
+
+::: {.notes}
+* Git branches are just pointers to a hash!
+* Sometimes it is nice to visualize a branch as a sequence of commits (e.g. "feature branch"), but technically it is just a label for a commit
+:::
+
+## Merge a branch
+
+Merge the commits of `develop` into `main`
+
+```bash
+git checkout main
+git merge develop
+```
+
+```{mermaid}
+gitGraph
+   commit
+   commit
+   branch develop
+   checkout develop
+   commit
+   commit
+   checkout main
+   merge develop
+```
+
+## Hands-on session {background-color=var(--dark-bg-color)}
+
+1. Create a branch
+3. Commit something in the branch
+4. Merge the new branch
+5. Check the log of the `main` branch
+6. Delete the new branch (`git branch --help`)
+
+## Conflicts {.leftalign}
+
+Collaboration can lead to disagreements
+
+:::: {.columns}
+
+::: {.column width="30%"}
+
+```{mermaid}
+gitGraph
+   commit
+   commit
+   branch alice
+   checkout alice
+   commit
+   checkout main
+   branch bob
+   checkout bob
+   commit
+```
+
+:::
+
+::: {.column width="70%"}
+
+::: {.fragment fragment-index=0}
+Alice fixes an obvious error `file.txt`
+
+```{diff}
+-This course is lame
++This course is nice!
+```
+:::
+
+::: {.fragment fragment-index=1}
+Bob is doing the same
+
+```{diff}
+-This course is lame
++This course is awesome!
+```
+:::
+
+:::
+
+::::
+
+## Conflicts {.leftalign}
+
+This creates a conflict when merging both branches
+
+```{mermaid}
+gitGraph
+   commit
+   commit
+   branch alice
+   checkout alice
+   commit
+   checkout main
+   branch bob
+   checkout main
+   merge alice
+   checkout bob
+   commit
+   checkout main
+   merge bob
+```
+
+```{raw}
+Auto-merging file.txt
+CONFLICT (content): Merge conflict in test.txt
+Recorded preimage for 'file.txt'
+Automatic merge failed; fix conflicts and then commit the result.
+```
+
+## Solving conflicts {auto-animate=true .leftalign}
+
+Solving conflicts requires **your decision**
+
+```{.raw filename=file.txt}
+<<<<<<< HEAD
+This course is nice!
+=======
+This course is awesome!
+>>>>>>> bob
+```
+
+## Solving conflicts {auto-animate=true visibility="uncounted" .leftalign}
+
+Solving conflicts requires **your decision**
+
+```{.raw filename=file.txt}
+This course is awesome!
+```
+
+:::{.fragment}
+After resolving the conflict, you have to commit your changes
+```{sh}
+git add file.txt
+git commit
+```
+:::
+
+## Hands-on session {background-color=var(--dark-bg-color) .leftalign}
+
+1. Create `file.txt` in two different branches with different content
+2. Merge both branches into `main` (`CONFLICT`)
+3. Resolve the conflict and commit your changes
+
+
+# Best practices
+
+Commits should deal with only one task; one logical unit
+
+* Ensure regular commits to track progress effectively
+* Commit each fix or task independently for clarity and easier management
+* Commit self-consistent (i.e. working) states
+
+## Best practices {visibility="uncounted"}
+
+Write **meaningful** commit messages
+
+1. Use the **imperative mood** in the subject line (**what** is done)
+1. **Limit** the subject line to 50 characters
+1. Use the body to elaborate **why** changes have been
+performed
+
+## {.rightalign}
+
+```{raw}
+ice: Fix freeing uninitialized pointers
+
+Automatically cleaned up pointers need to be initialized before exiting
+their scope.  In this case, they need to be initialized to NULL before
+any return statement.
+
+Fixes: 90f821d72e11 ("ice: avoid unnecessary devm_ usage")
+Signed-off-by: Dan Carpenter <dan.carpenter@linaro.org>
+Reviewed-by: Jiri Pirko <jiri@nvidia.com>
+Reviewed-by: Simon Horman <horms@kernel.org>
+Signed-off-by: Tony Nguyen <anthony.l.nguyen@intel.com>
+```
+
+Example from [kernel.org](https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=90ca6956d3834db4060f87700e2fcbb699c4e4fd)
+
+
+# Remotes
+
+* Adding a remote repository
+  ```bash
+  git remote add origin <PATH_TO_REPO>
+  ```
+* List the available remotes
+  ```bash
+  git remote -v
+  ```
+* Push your local references to the remote repo
+  ```bash
+  git push origin feature-branch
+  ```
+* Pull remote changes to your local repo
+  ```bash
+  git pull
+  ```
+
+## Merge request on GitLab DKRZ
+
+![](static/mr.png)
+
+::: {.notes}
+GitLab can act as a remote (like Github or even a local copy could also).
+:::
+
+## Hands-on session {background-color=var(--dark-bg-color) .leftalign}
+
+1. Upload your public SSH key to the DKRZ GitLab
+2. Push your repository to GitLab
+3. Create a branch and add a new file
+4. Create a merge request  (add author, reviewer, ...)
+5. Approve and merge it to `main`
+
+:::{.info .tiny}
+https://gitlab.dkrz.de/generic-software-skills/students2024/\<YOUR_USERNAME\>.git
+:::
+
+## Take home messages
+
+* You should use git frequently!
+* Industry is using it as de facto standard
+* Use branches to organize your work
+
+
+# Shotgun buffet
+
+## Rebase vs merge
+
+Instead of merging branches, one can also [rebase](https://git-scm.com/book/en/v2/Git-Branching-Rebasing)
+
+:::: {.columns}
+
+::: {.column width="50%"}
+```{mermaid}
+%%{init: {'gitGraph': {'showCommitLabel': false}} }%%
+gitGraph
+   commit
+   commit
+   branch develop
+   checkout develop
+   commit
+   commit
+   checkout main
+   commit
+```
+:::
+
+::: {.column width="50%"}
+```{mermaid}
+%%{init: {'gitGraph': {'showCommitLabel': false}} }%%
+gitGraph
+   commit
+   commit
+   commit
+   branch develop
+   checkout develop
+   commit
+   commit
+```
+:::
+
+::::
+Rebasing retains a linear history<br/> by **changing the commit history (!!!)**
+
+## Forks
+
+* A fork is a copy of a repository on server side
+* Used to work on public repositories without granting ownership
+* Standard names for locally defined remotes:
+  ```{raw}
+  origin	https://github.com/lkluft/numpy (fetch)
+  origin	https://github.com/lkluft/numpy (push)
+  upstream	https://github.com/numpy/numpy (fetch)
+  upstream	https://github.com/numpy/numpy (push)
+
+  ```
+
+## Tools for graphical merge
+
+VSCode, meld
+
+
+# Further reading
+
+* [The official git documentation pages](https://git-scm.com/doc)
+* [Introductions by GitLab](https://university.gitlab.com/pages/getting-started)
+* [Software Carpentry on git](https://swcarpentry.github.io/git-novice/)
+