diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
new file mode 100644
index 0000000..b282f8f
--- /dev/null
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -0,0 +1,4 @@
+
+
+See the preview for the last modified PR:
+- https://biosustain.github.io/git-tutorial/dev/index.html
diff --git a/.github/workflows/build_website.yaml b/.github/workflows/build_website.yaml
new file mode 100644
index 0000000..0c58a3a
--- /dev/null
+++ b/.github/workflows/build_website.yaml
@@ -0,0 +1,48 @@
+# Build website and save it on gh-pages branch
+name: build-and-save-website
+
+# Only run this when the master branch is ch
+on:
+ push:
+ branches:
+ - main
+ pull_request:
+ branches:
+ - main
+ # workflow_dispatch:
+
+# This job installs dependencies, builds the website and pushes it to `gh-pages`
+jobs:
+ deploy:
+ runs-on: ubuntu-latest
+ permissions:
+ contents: write
+ steps:
+ - uses: actions/checkout@v4
+ - uses: actions/setup-python@v5
+ - name: Install dependencies
+ run: |
+ pip install -r requirements.txt
+
+ - name: Build the site
+ run: |
+ sphinx-build -nW --keep-going -b html . _build
+
+ # If we've pushed to main, push the book's HTML to github-pages
+ - if: ${{ github.ref == 'refs/heads/main' }}
+ name: Save to gh-pages
+ uses: peaceiris/actions-gh-pages@v4
+ with:
+ github_token: ${{ secrets.GITHUB_TOKEN }}
+ publish_dir: ./_build
+ # # set it to a subfolder of the root to keep all PR previews:
+ # destination_dir: latest
+ # cname: website.com
+ - name: Save to gh-pages
+ uses: peaceiris/actions-gh-pages@v4
+ with:
+ github_token: ${{ secrets.GITHUB_TOKEN }}
+ publish_dir: ./_build
+ # # create a version for an PR
+ # # will be automatically deleted in case the build in on the root
+ destination_dir: dev
diff --git a/.gitignore b/.gitignore
index 1b05c22..fa0e846 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,3 +1,23 @@
+# Byte-compiled Python files
+__pycache__/
+
+# data
+*.csv
+*.json
+*.parquet
+
+# C extensions
+*.so
+
+# Mac OS
+.DS_Store
+*/.DS_Store
+
+# Distribution / packaging
+dist/
+eggs/
+
+
.npm
.yarn
.cache
@@ -9,3 +29,5 @@
.jupyter
.bash_logout
.profile
+.DS_Store
+_build
diff --git a/LICENSE b/LICENSE
index d4196a7..a57193f 100644
--- a/LICENSE
+++ b/LICENSE
@@ -1,6 +1,6 @@
BSD 3-Clause License
-Copyright (c) 2019, Tim Head
+Copyright (c) 2025, Henry Webel
All rights reserved.
Redistribution and use in source and binary forms, with or without
diff --git a/README.md b/README.md
index 4a9cd0b..13c0852 100644
--- a/README.md
+++ b/README.md
@@ -1,66 +1,71 @@
-# Git Tutorial using
+# Git Tutorial
-> VS Code on Binder
-> VS Code on Binder, because sometimes you need a real editor.
+Sign-Up to the workshop here (being logged in with your DTU Microsoft account): [Sign-Up Form](https://forms.office.com/e/62H1nV61R0)
-[](https://pypi.org/project/jupyter-vscode-proxy/)
-[](https://github.com/conda-forge/jupyter-vscode-proxy-feedstock)
+## Announcement
-Start:
- - lab: [](https://mybinder.org/v2/gh/RasmussenLab/git-tutorial/master?urlpath=lab)
- - vscode: [](https://mybinder.org/v2/gh/RasmussenLab/git-tutorial/master?urlpath=vscode?folder=/home/jovyan/examples)
+This workshop will give you the opportunity to practice git as a version control system
+and Github as a website to host your repositories. Using git you can track changes in
+folders. It allows you track your progress and to spot random typos when working on
+many projects and tasks in parallel. In the workshop you will get the time to practice
+the fundamental concepts and actions directly in your browser - either using VSCode in
+GitHub Codespaces or in using the GitHub web interface. If you want, you can also try
+everything on your local computer.
+I will give a brief introduction to git. Then you will specific workflows by
+collaboratively work on extending a [recipe book](https://biosustain.github.io/recipe-book/)
+(please bring a recipe you like).
+You will learn how to work on
+[branches](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-branches),
+review [Pull Requests](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests)
+and merge them into the main branch. If you have specific requests, feel free to reach out to me.
-## Explore
+If you have specific requests, feel free to reach out to [me](mailto:heweb@dtu.dk) and/or write it down in the sign-up form.
-You will need to setup your git email and user-name
-(replace with yours in case you want to commit something, otherwise use copy-paste)
+What you'll learn:
-```bash
-git config --global user.email "you@example.com"
-git config --global user.name "Your Name"
-```
-> could be added to local config using `git config user...`
+- Basic tasks and actions to perform with git (in VSCode or in the browser)
+- How to branch and tag
+- Follow trunk-based development
+- See how to merge and comment a Pull Request based on a branch
+- Solve merge conflicts
+- Familiarize yourself with VSCode’s and GitHub’s interface and user experience
+- Get to know new recipes
-### Steps
+Minimal prerequisite: A [GitHub account](https://github.com/signup).
+If you want to follow along locally, please install
+[GitHub Desktop](https://desktop.github.com/download/) and
+[VSCode](https://code.visualstudio.com/) on your machine.
-- create a folder with an empty repository (default `examples`)
-- `git init` in console to initialize repo
-- setup user.name and user.email
-- create files, stage them and see what files are created in `.git/objects`
-- commit files and check `.git/objects`
-- create branches and checkout `.git/refs` and `git/branches` folder
-- look at `git/HEAD` (maybe `git/ORIG_HEAD` if it exists)
+### Brief timeline of the workshop:
-> try to create your own fork, and try to lauch it on [mybinder](https://mybinder.org/)
+| Time | Activity |
+| ------------- | ------------------------------------------ |
+| 10:00 - 10:15 | Coffee and snacks 🥐 |
+| 10:15 - 10:45 | Introduction and example workflow |
+| 10:45 - 12:00 | Working collaboratively on the recipe book |
+| 12:00 - 12:30 | lunch break (not included) |
+| 12:30 - 13:30 | Your question and advanced content |
-## Links
+## Slides
+
+
+## Local Setup
+
+See [local_setup](local_setup.md) for instructions to setup git on your local computer.
+
+## Links to learn more
+
+- [git-intro by coderefinery](https://coderefinery.github.io/git-intro/#)
- [git-moji](https://gitmoji.dev/)
-- [curious git](https://matthew-brett.github.io/curious-git/) - detailed intro to the inner workings
-- [git parable](http://practical-neuroimaging.github.io/git_parable.html) - why git came to exist
-- Videos:
- - [Python-Git-Client](https://www.youtube.com/watch?v=xvzo_nV9PjU)
- - [Git-Interals](https://www.youtube.com/watch?v=MYP56QJpDr4)
- - [Git PyData Global 2021 talk](https://www.youtube.com/watch?v=rBYC3dEOOyI)
-
-## Inspect git objects
-
-```bash
-git log --format=raw
-git cat-file -p # pretty print
-git cat-file -t # type
-
-# the binary object can also be inspected using different tools,
-# which might make it easier to navigate to certain blobs:
-cat .git/objects/<2c>/<38c> | zlib-flate -uncompress
-```
-
-## Note
-
-> Should be Run the Python Tsunami notebooks on binder.
-?urlpath=vscode/?folder
-Go directly to Python Tsunami repository in
- - VSCode [](https://mybinder.org/v2/gh/RasmussenLab/git-tutorial/master?urlpath=vscode/?folder=/home/jovyan/PythonTsunami)
- - JupyterLab [](https://mybinder.org/v2/gh/RasmussenLab/git-tutorial/master?urlpath=lab/tree/PythonTsunami)
- - Jupyter Notebook [](https://mybinder.org/v2/gh/RasmussenLab/git-tutorial/master?urlpath=tree/PythonTsunami)
+- [Git Internals - Plumbing and Porcelain](https://git-scm.com/book/en/v2/Git-Internals-Plumbing-and-Porcelain)
+- [Glossary of terms for git](https://www.git-scm.com/docs/gitglossary)
+- [Glossary terms for GitHub](https://docs.github.com/en/get-started/learning-about-github/github-glossary)
diff --git a/advanced.md b/advanced.md
new file mode 100644
index 0000000..dc9d744
--- /dev/null
+++ b/advanced.md
@@ -0,0 +1,84 @@
+
+# Git under the hood
+
+> Extended content for those interested in how git works under the hood
+
+You can find a recording of the
+[talk](https://www.youtube.com/watch?v=cAU3BCUkHxM)
+([slides](https://docs.google.com/presentation/d/1RsKMiKquE4wqncrAv9LEtjivGE_dGiHoJ8nKCxgVKeY/edit?usp=sharing))
+and [hands-on tutorial](https://www.youtube.com/watch?v=5iB7qc5zRjQ)
+on YouTube which was done for the Data Club seminar
+between DTU biosustain and DTU bioengineering (see sections in description of Video).
+
+Talk:
+[](https://www.youtube.com/watch?v=cAU3BCUkHxM)
+
+Live Demo:
+[](https://www.youtube.com/watch?v=5iB7qc5zRjQ)
+
+The above Live Demo is not pulling the merge commit after merging the branch on GitHub:
+[github.com/biosustain/git_training_henry_recording](https://github.com/biosustain/git_training_henry_recording)
+
+I show the merge commit in the video below, cloining the recording repository in a newly
+create VSCode sandbox environment above:
+
+[](https://www.youtube.com/watch?v=gcfzruIJ-rw)
+
+## Instructions
+
+- create a folder with an empty repository (default `examples`
+ directly openend in VSCode on binder)
+- open instruction: `code-server ../README.md` (local computer: `code ../README.md`)
+- `git init` in console to initialize repo (or via command palette "Git: Initialize Repository")
+- setup user.name and user.email (see above)
+- create files, stage them and see what files are created in `.git/objects`
+- commit files and check `.git/objects`
+- create branches and checkout `.git/refs` (`git/branches` is a legacy folder,see
+ [here](https://stackoverflow.com/a/10398507/9684872))
+- look at `git/HEAD` (maybe `git/ORIG_HEAD` if it exists)
+
+> try to create your own fork, and try to lauch it on [mybinder](https://mybinder.org/)
+
+## Inspect git objects
+
+```bash
+git log --format=raw
+git cat-file -p # pretty print
+git cat-file -t # type
+
+# the binary object can also be inspected using different tools,
+# which might make it easier to navigate to certain blobs:
+cat .git/objects/<2c>/<38c> | zlib-flate -uncompress
+```
+
+You can find the latest objects and compare it to the log
+
+```bash
+find .git/objects -type f -exec ls -lt {} + | head -n 10
+git log --format=raw -n 3
+```
+
+If you wonder what the codes in a tree mean, check this stackexchange
+[answer](https://unix.stackexchange.com/a/450488/349761)
+
+## What's happening?
+
+Can you explain what happens in the following scenarios?
+
+- You committed ten commits and did not yet push. Git complains about too much data.
+ You realize that you committed your source data. You delete it and commit again,
+ but the problem still persists.
+- You commit something and push. You realize your last commit was wrong. You undo it
+ and commit again. Git complains that you cannot push.
+
+## Git internals resources
+
+- [curious git](https://matthew-brett.github.io/curious-git/) - detailed intro to the
+ inner workings
+- [git parable](http://practical-neuroimaging.github.io/git_parable.html) - why git came to exist
+- Videos:
+ - [Python-Git-Client](https://www.youtube.com/watch?v=xvzo_nV9PjU)
+ - [Git-Interals](https://www.youtube.com/watch?v=MYP56QJpDr4) - shows how git works
+ - [Git PyData Global 2021 talk](https://www.youtube.com/watch?v=rBYC3dEOOyI)
+ - Scoot Chacon’s [“So you thin you know git” talk](https://www.youtube.com/watch?v=aolI_Rz0ZqY) (FOSDEM 2024),
+ notes on [blog](https://blog.gitbutler.com/git-tips-1-theres-a-git-config-for-that/)
diff --git a/conf.py b/conf.py
new file mode 100644
index 0000000..46b51e9
--- /dev/null
+++ b/conf.py
@@ -0,0 +1,106 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+#
+# created from notes_template: https://github.com/enryH/notes_template
+# -- Project information -----------------------------------------------------
+
+project = "Git Tutorial"
+copyright = "2025, DTU Biosustain, Informatics Platform, DSP"
+author = "Henry Webel"
+
+
+# -- General configuration ---------------------------------------------------
+
+
+extensions = [
+ "myst_nb",
+ # "sphinx_design", # https://sphinx-design.readthedocs.io/en/sbt-theme/
+ # "sphinx_copybutton", # https://sphinx-copybutton.readthedocs.io/
+ "sphinx_new_tab_link",
+]
+
+templates_path = ["_templates"]
+# As we can use percent notebooks and markdowns files, we need to exclude some files
+# additinally to the default ones (add to the list if needed)
+exclude_patterns = [
+ "_build",
+ "Thumbs.db",
+ ".DS_Store",
+ "**/pandoc_ipynb/inputs/*",
+ ".nox/*",
+ '.venv/*',
+ # "README.md",
+ "**/.ipynb_checkpoints/*",
+ "jupyter_execute",
+ "conf.py",
+ "check_recipes.py",
+ ".github/PULL_REQUEST_TEMPLATE.md"
+]
+
+
+# -- Notebook related settings -----------------------------------------------
+
+# add notebooks
+# https://myst-nb.readthedocs.io/en/latest/computation/execute.html
+nb_execution_mode = "auto"
+
+myst_enable_extensions = ["dollarmath", "amsmath"]
+
+# Plolty support through require javascript library
+# https://myst-nb.readthedocs.io/en/latest/render/interactive.html#plotly
+# html_js_files = [
+# "https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.4/require.min.js"
+# ]
+
+# https://myst-nb.readthedocs.io/en/latest/configuration.html
+# Execution
+nb_execution_raise_on_error = True
+# Rendering
+nb_merge_streams = True
+
+# https://myst-nb.readthedocs.io/en/latest/authoring/custom-formats.html#write-custom-formats
+nb_custom_formats = {
+ # ".py": ["jupytext.reads", {"fmt": "py:percent"}]
+}
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# 2. Select a tempalate
+# ! you might need additional dependencies in requirements.txt
+# browse available themes: https://sphinx-themes.org/
+
+
+# The theme to use for HTML and HTML Help pages. See the documentation for
+# a list of builtin themes.
+# See:
+# https://github.com/executablebooks/MyST-NB/blob/master/docs/conf.py
+# html_title = ""
+html_theme = "sphinx_book_theme"
+# html_theme = "sphinx_book_theme" # alternative
+# html_logo = "_static/logo-wide.svg"
+# html_favicon = "_static/logo-square.svg"
+html_theme_options = {
+ "github_url": "https://github.com/biosustain/git-tutorial",
+ "repository_url": "https://github.com/biosustain/git-tutorial",
+ # "repository_branch": "main",
+ "home_page_in_toc": True,
+ # "path_to_docs": "docs",
+ "show_navbar_depth": 1,
+ # "use_edit_page_button": True,
+ "use_repository_button": True,
+ "use_download_button": True,
+ "launch_buttons": {
+ "colab_url": "https://colab.research.google.com"
+ # "binderhub_url": "https://mybinder.org",
+ # "notebook_interface": "jupyterlab",
+ },
+ "navigation_with_keys": False,
+}
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+# html_static_path = ['_static']
diff --git a/environment.yml b/environment.yml
deleted file mode 100644
index 49b225a..0000000
--- a/environment.yml
+++ /dev/null
@@ -1,13 +0,0 @@
-channels:
- - conda-forge
-dependencies:
- - numpy
- - jupyter-server-proxy
- - code-server >=3.2
- - pandas
- - matplotlib
- - scikit-learn
- - seaborn
- - plotly
- - bs4
- - rise
diff --git a/index.md b/index.md
new file mode 100644
index 0000000..5a42951
--- /dev/null
+++ b/index.md
@@ -0,0 +1,24 @@
+```{include} README.md
+
+```
+
+```{toctree}
+:maxdepth: 1
+:hidden:
+:caption: Basic introduction
+
+instructions_251105
+
+use_cases
+local_setup
+receipe_book
+```
+
+```{toctree}
+:maxdepth: 1
+:hidden:
+:caption: Advanced content
+
+advanced
+instructions_241113
+```
diff --git a/instructions_241113.md b/instructions_241113.md
new file mode 100644
index 0000000..3a2fb38
--- /dev/null
+++ b/instructions_241113.md
@@ -0,0 +1,97 @@
+# Workshop on the 13th of November 2024
+
+.. at DTU biosustain and DTU bioengineering.
+
+[](https://github.com/codespaces/new?hide_repo_select=true&ref=main&repo=874029589&skip_quickstart=true)
+
+## Plan
+
+- Introduction to git ([slides](https://docs.google.com/presentation/d/1RsKMiKquE4wqncrAv9LEtjivGE_dGiHoJ8nKCxgVKeY/edit?usp=sharing)),
+ see recording [here](https://youtu.be/cAU3BCUkHxM)
+- Hands-on, focusing this time on
+ - working on a shared repository (per group, i.e. e.g. per table)
+ - creating and merging branches
+ - viewing and annotating collaborative work
+ - showing features of GitHub
+
+If time allows - and maybe due to common errors - we will also cover:
+
+- merge conflicts
+- out-of-sync issues
+
+The workshop will require you to have a GitHub account. Please open it here: [github.com/join](https://github.com/join)
+
+### 1. step - create a shared repository
+
+> ONLY one person per group has to do this.
+
+Per group (e.g. table) create one repository on GitHub on one of the group members account
+or under the DTU biosustain organization.
+
+- Use as template this repository from
+ [github.com/enryH/notes_template](https://github.com/enryH/notes_template).
+ Follow the instructions described
+ [here](https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-repository-from-a-template#creating-a-repository-from-a-template) or
+ [the demo-recording](https://youtu.be/XolIezJtSPI?t=98) to use it.
+
+### 2. step - create a clone of the shared repository
+
+Now you have a common repository you can share with each others. You can either
+[work in a codespace](https://docs.github.com/en/codespaces/developing-in-a-codespace/creating-a-codespace-for-a-repository#creating-a-codespace-for-a-repository)
+(opening the repository in a virtual machine in the browser) or clone the repository
+to your local machine.
+
+- we won't cover the website aspect of the template here, but I created a video on how
+ to use the template for a website [here](https://www.youtube.com/watch?v=XolIezJtSPI)
+ (which is also linked in the [repository's README](https://github.com/enryH/notes_template)).
+
+### 3. step - each create a branch
+
+Each of you create a branch, e.g. give it your name. Add a brief description of what you
+are passionate about in a file called `aboutme.md` in a folder with your name.
+
+In order to commit this to the GitHub repository you have to do one of the two options:
+
+- [add all collaborators](https://docs.github.com/en/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-access-to-your-personal-repositories/inviting-collaborators-to-a-personal-repository#inviting-a-collaborator-to-a-personal-repository)
+ of your group to the repository (write access)
+- create a fork on your GitHub account (you will be asked in VSCode if you want to do this)
+
+You can also mix both approaches in your group to find out about the differences.
+
+> You can see how to commit changed files [here](https://www.youtube.com/watch?v=XolIezJtSPI&t=938s)
+> (in one part of the notes template hands on recording)
+
+### 4. step - merge the branches to the main branch
+
+On GitHub open a pull request to merge your branch to the main branch. We will explore
+together some features of the pull request website.
+
+> Hint: Use the extension
+> [Git Graph](https://marketplace.visualstudio.com/items?itemName=mhutchie.git-graph)
+> to visualize your branches and the history of your repository.
+
+### 5. step - view and annotate the collaborative work
+
+Switch back to the `main` branch and get all the latest changes from your coworkers (pull).
+Now, each create (again) a new branch (pick a unique new name) and create a the file name `biosustain.md`.
+In this file write a about what you think biosustain is about.
+
+### 6. step - merge the branches to the main branch
+
+The first pull request will work fine. Everyone else has to deal with merge conflicts, as
+the same named file will be overwritten - and there is no clear way to say which version
+is the correct one or how to combine you changes.
+
+- Hint: In your CodeSpace make sure to checkout the latest changes from the main branch
+ before creating a new branch (pull on main).
+
+### 7. step - merge conflicts
+
+> Advanced!
+
+We will explore how to resolve merge conflicts in VSCode's UI. This is advanced and
+you don't have to do this for now.
+
+## Follow up recording
+
+[](https://www.youtube.com/watch?v=mX3Il5xvKAs)
diff --git a/instructions_251105.md b/instructions_251105.md
new file mode 100644
index 0000000..2c06f50
--- /dev/null
+++ b/instructions_251105.md
@@ -0,0 +1,271 @@
+# Workshop on the 5th of November 2025
+
+## How to work with the repository
+
+You need to be logged in to GitHub and have a GitHub account for all these options:
+[Create a GitHub account](https://github.com/join)
+
+
+These information might be helpful:
+
+ - basic Markdown syntax: [Mastering Markdown](https://guides.github.com/features/mastering-markdown/)
+
+We will by default be using VS Code in the Browser with a GitHub Codespace connected.
+Please have a look at the (video) tutorials before the course:
+- VSCode in the Browser: [vscode-web](https://code.visualstudio.com/docs/setup/vscode-web)
+ ( we will connect a remote machine using a codespace)
+- Codespaces: [codespaces/quickstart](https://docs.github.com/en/codespaces/quickstart)
+
+### On the GitHub website
+
+- [Create a fork](https://github.com/biosustain/recipe-book/fork)
+ of the repository and work there
+
+### In VSCode in the browser without a workspace
+
+You need to be logged in to GitHub and have a GitHub account.
+
+- [github.com/biosustain/recipe-book (Website)](https://github.com/biosustain/recipe-book)
+- [github.dev/biosustain/recipe-book (Editor)](https://github.dev/biosustain/recipe-book)
+
+### In GitHub Workspace
+
+- Open in GitHub Codespace if you want to build and preview the website without
+ creating a commit:
+
+ [
+
+> If you start from the `biosustain/recipe-book` repository you can create a codespace,
+> and it will automatically create a fork for you if you don't have write access.
+
+### On local computer
+
+Install both an editor, e.g. [VSCode](https://code.visualstudio.com/download) (recommended),
+and the command line program [git](https://git-scm.com/install/)
+
+## Exercises
+
+Choose your favourite. We will focus on the basic one, but you can try the others
+as well or instead. Find exercise groups seeing the marks on the tables.
+
+### Add your recipe and request a review [basic]
+
+- [create a fork](https://github.com/biosustain/recipe-book/fork)
+ (or request access as collaborator of the the recipe-repo)
+- create a new branch from `main`, e.g. `add-aioli-pasta`
+- create a commit with your new recipe draft using the template
+
+ See the recipe template
+
+ ```markdown
+ # Title
+
+ ## Ingredients
+
+ (For 4 People)
+
+ - ingredient 1
+ - ingredient 2
+
+ ## Instructions
+
+ 1. first step
+ 2. second step
+
+ ```
+
+ Please make sure to have the headings as shown above for consistency.
+ It will be checked.
+
+
+- open a Pull (Merge) Request on GitHub to `origin/main`
+- ask someone (by inviting them) to review your PR and get an approval
+ - I set-up the repo to require at least one approval before a merge is possible
+ (best-practice)
+- merge the PR into `main` (you can do it yourself after getting the approval)
+ - check out your options (merge, squash, rebase) and choose one
+- syncronize your branch with `main` with `origin/main` (before adding a new recipe)
+
+
+See full pass through exercise
+
+
+
+
+
+Watch this video for a walkthrough of using GitHub Codespaces and VS Code in the browser.
+
+Additional steps:
+- check out to `main` branch
+- sync `fork/main` with `origin/main` on your fork (on GitHub website of your fork)
+- delete your codespaces afterwards to not use up all your credits:
+ [Deleting a codespace](https://docs.github.com/en/codespaces/developing-in-a-codespace/deleting-a-codespace#deleting-a-codespace)
+
+
+### Create a merge conflict [medium]
+
+Work simulatenously on the same files, writing new content to the same sections in text.
+
+- `pasta/boscaiola.md` is incomplete. Complete it on your own branch.
+ - the first to commit to main, will have no problems as the update passes
+ - everyone after has to resolve merge conflicts as the changes are not easy to resolve
+ automatically (draw out the graph to see why)
+
+How to merge:
+
+- Open a GitHub PR, follow the instructions there
+ (see [Web-Editor](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/addressing-merge-conflicts/resolving-a-merge-conflict-on-github))
+- too large differences have to be resolved locally, e.g. using the
+ [VSCode Merge Editor](https://code.visualstudio.com/docs/sourcecontrol/overview). See
+ [this tutorial](https://www.youtube.com/watch?v=HosPml1qkrg).
+
+How and when to integrate changes from the main branch?
+
+- setting in repository on GitHub to suggest to 'Update branch' (you need to own the repo)
+- merge in changes locally using `git merge`
+- leave it to git and create a 'merge commit' which has two parents
+
+### Rewrite history [advanced]
+
+> You can do this on your own repository or the recipe-book repo on a branch.
+
+- add a few more commits (loading the files or what else)
+- `rebase interactive` to remove the files again, see
+ [this tutorial](https://www.atlassian.com/git/tutorials/rewriting-history/git-rebase).
+ Please make sure you understand one of it's main comments:
+ > "It's very important to understand that even though the branch looks the same,
+ > it's composed of entirely new commits."
+- edit, squash, delete or reorder commits
+
+Try an interactive rebase to rewrite history. To edit the last 4 commits, use:
+
+```bash
+git rebase -i HEAD~4
+```
+or with respect to the `main` branch:
+```bash
+git rebase -i main
+```
+
+All the instructions will be visable to you in your default editor. Try to follow them
+using the help of the linked tutorial.
+
+
+What is an interactive rebase?
+
+An Interactive rebase is a Git command that allows you to edit, reorder, squash,
+or delete commits in your branch's history. This is useful for cleaning up your commit
+history before merging changes, combining related commits, or removing mistakes.
+
+Common actions during interactive rebase:
+- `pick`: Use the commit as is.
+- `reword`: Edit the commit message.
+- `edit`: Pause to amend the commit.
+- `squash`: Combine this commit with the previous one.
+- `drop`: Remove the commit.
+
+It will look something similar to this (taken from the tutorial linked above):
+
+```bash
+pick 2231360 some old commit
+pick ee2adc2 Adds new feature
+
+
+# Rebase 2cf755d..ee2adc2 onto 2cf755d (9 commands)
+#
+# Commands:
+# p, pick = use commit
+# r, reword = use commit, but edit the commit message
+# e, edit = use commit, but stop for amending
+# s, squash = use commit, but meld into previous commit
+# f, fixup = like "squash", but discard this commit's log message
+# x, exec = run command (the rest of the line) using shell
+# d, drop = remove commit
+```
+
+workflow:
+1. Run `git rebase -i HEAD~4` to open the last 4 commits in your editor.
+2. Change the action keywords as needed.
+3. Save and close the editor to apply changes.
+4. Resolve any conflicts if prompted.
+
+> Interactive rebase rewrites commit history. Only use it on branches that haven't
+ been shared with others, or coordinate closely with collaborators to avoid confusion.
+
+
+
+### Add and remove large files [advanced]
+
+GitHub set a limit of 100MB per file. It's a _best pratice_ to only commit code and
+documenation, and if needed small example datasets. Adding larger files than 100MB is
+possible locally, but then the commit cannot be syncronized with the remote, hosted
+repository.
+
+- use a large file generating some random large files (e.g. this
+ [one](https://drive.google.com/drive/folders/1xvYoWVzzgU1mGCG07tvv6V03mR7meC1Q?usp=sharing)
+ I created running the Python code below):
+
+ ```python
+ import numpy as np
+ alphabet = np.array(['a', 'b', 'c', 'd', 'e', 'f', 'g', 'h', 'i', 'j', 'k', 'l', 'm',
+ 'n', 'o', 'p', 'q', 'r', 's', 't', 'u', 'v', 'w', 'x', 'y', 'z'],
+ dtype='100MB so GitHub rejects it
+ np.random.choice(np.fromstring(alphabet, dtype='
+ See error you will encounter uploading large files
+
+ I added two commits, where the older one (the first one) contains a large file:
+
+ ```
+ heweb@nnfcb-l1106 recipe-book % git push
+ Enumerating objects: 9, done.
+ Counting objects: 100% (9/9), done.
+ Delta compression using up to 11 threads
+ Compressing objects: 100% (7/7), done.
+ Writing objects: 100% (7/7), 66.75 MiB | 31.34 MiB/s, done.
+ Total 7 (delta 2), reused 0 (delta 0), pack-reused 0
+ remote: Resolving deltas: 100% (2/2), completed with 1 local object.
+ remote: error: Trace: cb745b39bf3e1c2e15b6a344ef0eb8c2610555ec1fb16bb2773facc475e525be
+ remote: error: See https://gh.io/lfs for more information.
+ remote: error: File large_text_file.txt is 105.00 MB; this exceeds GitHub's file size limit of 100.00 MB
+ remote: error: GH001: Large files detected. You may want to try Git Large File Storage - https://git-lfs.github.com.
+ To https://github.com/biosustain/recipe-book.git
+ ! [remote rejected] test-lfs -> test-lfs (pre-receive hook declined)
+ error: failed to push some refs to 'https://github.com/biosustain/recipe-book.git'
+ ```
+
+ As of now git has a built-in support for hinting you at which files are to large to be
+ uploaded to GitHub.
+
+
+- `rebase` to remove the files again, see
+ [this tutorial](https://www.atlassian.com/git/tutorials/rewriting-history/git-rebase).
+ Options:
+ - edit the commit where you added the large files and remove them
+ - commit a new delete commit and squash it into the one where you added the files
+
+> Please not that files synchronized once to GitHub stay there 'forever'. If you update
+> your history (your commits) they are lost by being not referenced anywhere, but anyone
+> who knows the commit-id and has access can in princple find them again
+
+#### How does it happen in practice?
+
+- data is commited, but not every commit is synced to the remote
+- long notebooks with outputs are commited, making it very large text files (espe
+ with interactive plots)
+
+> so check for large individual files if you cannot push your changes
diff --git a/jupyter_vscode_proxy/__init__.py b/jupyter_vscode_proxy/__init__.py
deleted file mode 100644
index bc78f26..0000000
--- a/jupyter_vscode_proxy/__init__.py
+++ /dev/null
@@ -1,46 +0,0 @@
-import os
-import shutil
-
-
-def setup_vscode():
- def _get_vscode_cmd(port):
- executable = "code-server"
- if not shutil.which(executable):
- raise FileNotFoundError("Can not find code-server in PATH")
-
- # Start vscode in CODE_WORKINGDIR env variable if set
- # If not, start in 'current directory', which is $REPO_DIR in mybinder
- # but /home/jovyan (or equivalent) in JupyterHubs
- working_dir = os.getenv("CODE_WORKINGDIR", ".")
-
- extensions_dir = os.getenv("CODE_EXTENSIONSDIR", None)
- extra_extensions_dir = os.getenv("CODE_EXTRA_EXTENSIONSDIR", None)
-
- cmd = [
- executable,
- "--auth",
- "none",
- "--disable-telemetry",
- "--port=" + str(port),
- ]
-
- if extensions_dir:
- cmd += ["--extensions-dir", extensions_dir]
-
- if extra_extensions_dir:
- cmd += ["--extra-extensions-dir", extra_extensions_dir]
-
- cmd.append(working_dir)
- return cmd
-
- return {
- "command": _get_vscode_cmd,
- "timeout": 20,
- "new_browser_tab": True,
- "launcher_entry": {
- "title": "VS Code",
- "icon_path": os.path.join(
- os.path.dirname(os.path.abspath(__file__)), "icons", "vscode.svg"
- ),
- },
- }
diff --git a/jupyter_vscode_proxy/icons/vscode.svg b/jupyter_vscode_proxy/icons/vscode.svg
deleted file mode 100644
index 376182b..0000000
--- a/jupyter_vscode_proxy/icons/vscode.svg
+++ /dev/null
@@ -1,21 +0,0 @@
-
-
diff --git a/local_setup.md b/local_setup.md
new file mode 100644
index 0000000..7f5bb6e
--- /dev/null
+++ b/local_setup.md
@@ -0,0 +1,33 @@
+# Setup git locally
+
+## Download git
+
+Download and install git from [git-scm.com](https://git-scm.com/install)
+for your operating system.
+
+## Configure git
+
+You will need to setup your git email and user-name
+(replace with yours in case you want to commit something, otherwise use copy-paste)
+to identify yourself in the commits:
+
+```bash
+git config --global user.email "you@example.com"
+git config --global user.name "Your Name"
+```
+> could be added to local config using `git config user...`
+
+Then you need to define how to handle merge conflicts, in case you have committed
+changes locally and there are changes in the remote repository. The easiest way is to
+always create a merge commit
+([docs](https://git-scm.com/docs/git-config#Documentation/git-config.txt-pullrebase)):
+
+```bash
+git config --global pull.rebase false
+# or only for this repository
+git config --local pull.rebase false
+```
+
+Setting it to true has a the warning:
+> NOTE: (setting it to true) is a possibly dangerous operation; do not use it unless you understand
+> the implications. (see [git-rebase](https://git-scm.com/docs/git-rebase) for details)
diff --git a/postBuild b/postBuild
deleted file mode 100755
index f096df0..0000000
--- a/postBuild
+++ /dev/null
@@ -1,15 +0,0 @@
-#!/bin/bash
-
-# Enable the proxy extension in notebook and lab
-jupyter serverextension enable --py jupyter_server_proxy
-jupyter labextension install @jupyterlab/server-proxy
-jupyter lab build
-
-code-server --install-extension ms-python.python
-
-pip install jupyterlab-git
-# Install the VS code proxy
-pip install -e.
-
-# git clone https://github.com/Center-for-Health-Data-Science/PythonTsunami
-# conda env update --file PythonTsunami/environment.yml
\ No newline at end of file
diff --git a/receipe_book.md b/receipe_book.md
new file mode 100644
index 0000000..bddc039
--- /dev/null
+++ b/receipe_book.md
@@ -0,0 +1,24 @@
+# Recipe Book
+
+The recipe book is a collection of markdown files which are rendered as a website
+using Sphinx. The static website is hosted using GitHub pages. If you want to learn
+more about how to create static websites with GitHub pages, GitHub Actions and Sphinx
+see our other trainings:
+
+- GitHub Actions for Automation:
+ [biosustain/dsp_actions_tutorial](https://github.com/biosustain/dsp_actions_tutorial)
+ (Data Club seminar)
+- template for Sphinx based websites with instructions (and recording):
+ [enryH/notes_template](https://github.com/enryH/notes_template)
+
+## Preview
+
+
+
+
diff --git a/requirements.txt b/requirements.txt
new file mode 100644
index 0000000..d714a64
--- /dev/null
+++ b/requirements.txt
@@ -0,0 +1,6 @@
+sphinx
+sphinx-book-theme
+myst-nb
+ipywidgets
+sphinx-new-tab-link!=0.2.2
+jupytext
diff --git a/setup.py b/setup.py
deleted file mode 100644
index f51d1b7..0000000
--- a/setup.py
+++ /dev/null
@@ -1,31 +0,0 @@
-import setuptools
-
-
-with open("README.md", encoding="utf8") as f:
- readme = f.read()
-
-
-setuptools.setup(
- name="jupyter-vscode-proxy",
- version="0.1",
- url="https://github.com/betatim/vscode-binder",
- author="Tim Head",
- license="BSD",
- description="VS Code extension for Jupyter",
- long_description=readme,
- long_description_content_type="text/markdown",
- packages=setuptools.find_packages(),
- keywords=["Jupyter", "vscode", "vs code", "editor"],
- classifiers=["Framework :: Jupyter"],
- install_requires=[
- 'jupyter-server-proxy'
- ],
- entry_points={
- "jupyter_serverproxy_servers": ["vscode = jupyter_vscode_proxy:setup_vscode",]
- },
- package_data={"jupyter_vscode_proxy": ["icons/*"]},
- project_urls={
- "Source": "https://github.com/betatim/vscode-binder/",
- "Tracker": "https://github.com/betatim/vscode-binder/issues",
- },
-)
diff --git a/use_cases.md b/use_cases.md
new file mode 100644
index 0000000..cb62df0
--- /dev/null
+++ b/use_cases.md
@@ -0,0 +1,18 @@
+# Use cases for git and GitHub
+
+Two examples:
+
+- VueGen reporting tool - [VueGen repo](https://github.com/Multiomics-Analytics-Group/vuegen)
+- shared notes repository of Data Science Platform - [DSP notes repo](https://github.com/biosustain/dsp_notes)
+- publish analysis code and results ('code availability') - [not just another biomarker repo](https://github.com/RasmussenLab/njab)
+
+## Keep track of changes locally
+
+- if you code, you can keep an eye on your changes. Highlight current differences in
+ your way forward to a solution. Especially usefull when working with Coding Assistents
+ based on AI which rewrite your code
+
+## Collaborate with others and keep changes in sync
+
+- Google Docs, Word or Overleaf is used to work collaborative on manuscripts
+- GitHub and git can be used to do the same on public documentation or code