Merge pull request #4 from biosustain/edition2025

edition 2025 (more basic)

Author: enryH

.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

.github/workflows/build_website.yaml

@@ -0,0 +1,49 @@
+# 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
+      - 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
+          # # create a version for an PR
+          # # will be automatically deleted in case the build in on the root
+          destination_dir: dev

.gitignore

@@ -9,3 +9,5 @@
 .jupyter
 .bash_logout
 .profile
+.DS_Store
+_build

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

README.md

@@ -1,17 +1,40 @@
-# Git Tutorial using
-
-> VS Code on Binder  
-> VS Code on Binder, because sometimes you need a real editor.  
-
-[![PyPI](https://img.shields.io/pypi/v/jupyter-vscode-proxy)](https://pypi.org/project/jupyter-vscode-proxy/)
-[![Install with conda](https://img.shields.io/conda/vn/conda-forge/jupyter-vscode-proxy.svg)](https://github.com/conda-forge/jupyter-vscode-proxy-feedstock)
-
-Start:
- - lab: [![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/biosustain/git-tutorial/master?urlpath=lab)
- - vscode: [![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/biosustain/git-tutorial/master?urlpath=vscode?folder=/home/jovyan/examples)
-
-
-## Explore
+# Git Tutorial
+
+## Announcement
+
+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://enryh.github.io/recipe-book/).
+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. 
+
+If you have specific requests, feel free to reach out to [me](mailto:heweb@dtu.dk). 
+
+What you'll learn:
+- 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
+ 
+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.
+
+
+## Explore locally
 
 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)
@@ -22,19 +45,19 @@ git config --global user.name "Your Name"
 ``` 
 > could be added to local config using `git config user...`
 
-### Steps
 
-- 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)
+## Links to learn more
 
-> try to create your own fork, and try to lauch it on [mybinder](https://mybinder.org/)
+- [git-intro by coderefinery](https://coderefinery.github.io/git-intro/#)
+- [git-moji](https://gitmoji.dev/)
+- [Git Internals - Plumbing and Porcelain](https://git-scm.com/book/en/v2/Git-Internals-Plumbing-and-Porcelain)
+- [Glossary of terms (technical for git)](https://www.git-scm.com/docs/gitglossary)
+- [GitHub Glossary terms](https://docs.github.com/en/get-started/learning-about-github/github-glossary)
+
+
+## Git under the hood (Extended version)
+
+> 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)
@@ -60,19 +83,23 @@ create VSCode sandbox environment above:
 [![Live Demo Hand on Addon](https://img.youtube.com/vi/gcfzruIJ-rw/sddefault.jpg
 )](https://www.youtube.com/watch?v=gcfzruIJ-rw)
 
-## Links
 
-- [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) - 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/) 
+### Instructions
 
-## Inspect git objects
+- 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
@@ -95,9 +122,24 @@ If you wonder what the codes in a tree mean, check this stackexchange
 [answer](https://unix.stackexchange.com/a/450488/349761)
 
 
-## What's happening?
+### 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
 
-- You commited ten commits and dit not yet push. Git complains about too much data.
-  You realize that you commited 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.
+- [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/)

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']

environment.yml

@@ -0,0 +1,13 @@
+```{include} README.md
+```
+
+
+```{toctree}
+:maxdepth: 1
+:hidden:
+
+instructions_251105
+instructions_241113
+
+
+```

index.md

@@ -2,6 +2,8 @@
 
 .. at DTU biosustain and DTU bioengineering.
 
+[![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](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)),

instructions_241113.md

@@ -0,0 +1,27 @@
+# Workshop on the 5th of November 2025
+
+> to be continued.
+
+## 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)
+
+### On the GitHub website
+
+- Create a 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.dev/enryH/recipe-book](https://github.dev/enryH/recipe-book)
+
+### In GitHub Workspace
+
+- Open in GitHub Codespace if you want to build and preview the website without 
+  creating a commit:
+
+  [![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://github.com/codespaces/new?hide_repo_select=true&ref=main&repo=1053356553&skip_quickstart=true)
+
+