diff --git a/_quarto.yml b/_quarto.yml index 97d3cadd2dddf6a3c74c41cdb17b0342d04fa69f..0f7a29a6f2b73a5ed22b7c2fee61ec5bb1d3fbac 100644 --- a/_quarto.yml +++ b/_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: diff --git a/exercises/git.qmd b/exercises/git.qmd new file mode 100644 index 0000000000000000000000000000000000000000..505dfb1a70702df06e68dd0dad7e052067d56ad8 --- /dev/null +++ b/exercises/git.qmd @@ -0,0 +1,12 @@ +--- +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. diff --git a/lectures/custom.scss b/lectures/custom.scss index b774fa221cfd2b68ea7baebd4cf6d9ea191b6877..24223644b164e7bf30d60060bc0da05b1a3f8275 100644 --- a/lectures/custom.scss +++ b/lectures/custom.scss @@ -52,6 +52,10 @@ h2 { font-size: .8em; } +.tiny { + font-size: .4em; +} + .right { text-align: right; } diff --git a/lectures/git/slides.qmd b/lectures/git/slides.qmd new file mode 100644 index 0000000000000000000000000000000000000000..239d82aecbf9a379bd116d9c3942200944a0a7a8 --- /dev/null +++ b/lectures/git/slides.qmd @@ -0,0 +1,420 @@ +--- +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** + +{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 + + + +::: {.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/) + diff --git a/lectures/git/static/mr.png b/lectures/git/static/mr.png new file mode 100644 index 0000000000000000000000000000000000000000..aaa0600172db37d38f67ca00522bd3db6609cbe3 Binary files /dev/null and b/lectures/git/static/mr.png differ