• https://docs.google.com/presentation/d/1USOTBichtOkgX5-F-vYios3xhWSj1xtG9H5639Igo1E/edit#slide=id.g18b299f6c57_0_0
• https://www.youtube.com/watch?v=ErzGfcBoLg4
• https://www.dsc-ub.de/verant_detail.php?id=166
• http://www-cs-students.stanford.edu/~blynn//gitmagic/ch01.html
• https://codehorizons.com/making-your-first-github-r-project/
• https://rdm.mpdl.mpg.de/2021/06/01/using-git-for-research-data-management/
• https://reproducibility.rocks/materials/day2/02-git/
• https://code-review.tidyverse.org

align the layout of the various chapters

• move "acknowledgements" section to the bottom and rename to "acknowledgements & further reading"
• move the cheatsheet to the bottom
• "command-line" when used as an adjective, "command line" when used as a noun (see here)
• "Git" instead of "git" throughout, see #37
• add "prerequisites" to all the chapters, linking to previous chapters, as applicable
• add {{< fa eye >}} to hidden outputs
• add to beginning of chapter that readers are encouraged to type the command into the terminal instead of just reading.
• add memes! students love memes!

add content

• add a bit more "computer history" about the command line, making clear that this was for some time the main way to interact with a computer
• add cc-by (or similar licensed) images of the CLI to the beginning of the chapter. maybe a GIF?
• I think the difference between cli, terminal and shell is not yet super clear. maybe we can expand on this a bit. low-priority.
• but based on that we should decide whether / when to use which term and clarify this explicitly
• add instructions for mac, how to find out which OS version the computer runs
• add juypterhub instructions for the terminal, ideally with screenshots
• explain difference between bash and zsh

To verify if your machine is configured to use a shell other than Bash, you can type echo $SHELL in your Terminal window.

• explain what the output of this ☝️ means
• "navigating the file system": add more introduction text that explains how most users are familiar with navigating the file system through a GUI (e.g., Finder on Mac) using their mouse or arrows keys on the keyboard. we can do the same thing using the command line.
• maybe add pictures that show what the same command or operation looks like in the finder
• add explanation what is meant by "working directory"
• add more explanation what hidden files are and why they are hidden
• add a short warning that people should think about where they want to create new directories etc., e.g., on their Desktop and consider deleting it afterwards to not get confused.
• add warning that files that are removed using rm are removed entirely and can not be retrieved from the bin! but please check that information again.

add to the terminology section

• what is a "file"
• what is a "folder"
• what is a "directory"

general todos:

• try out "git bash" on windows
• explore jupyterhub
• add recommendation to use tree command (see here) when viewing files and folders

ATM

may be there is an extension/option in the used system to automagically make them hyperlinks like github does?

❯ git grep -A5 '# References'
chapters/branches.qmd:# References
chapters/branches.qmd-
chapters/branches.qmd-https://www.atlassian.com/git/tutorials/using-branches
chapters/branches.qmd-
chapters/branches.qmd-https://lukemerrett.com/different-merge-types-in-git/
chapters/branches.qmd-
--
chapters/contributing.qmd:## References {#sec-references}
chapters/contributing.qmd-
chapters/contributing.qmd-- {{< fa book >}} ["Citations & Footnotes"](https://quarto.org/docs/authoring/footnotes-and-citations.html) in the Quarto documentation.
chapters/contributing.qmd-- {{< fa book >}} [HTML options for references](https://quarto.org/docs/reference/formats/html.html#references).
chapters/contributing.qmd-
chapters/contributing.qmd-### Cite a reference
--
chapters/datalad-nextcloud.qmd:### References
chapters/datalad-nextcloud.qmd-
chapters/datalad-nextcloud.qmd-- https://www.gwdg.de/storage-services/gwdg-owncloud
--
chapters/github-intro.qmd:## References
chapters/github-intro.qmd-https://www.gitkraken.com/learn/git/tutorials/what-is-a-pull-request-in-git
chapters/github-intro.qmd-
chapters/github-intro.qmd-https://the-turing-way.netlify.app/collaboration/github-novice/github-novice-features.html
chapters/github-intro.qmd-
chapters/github-intro.qmd-https://git-scm.com/book/de/v2/Git-Grundlagen-Mit-Remotes-arbeiten
--
chapters/installation-setup.qmd:# References 
chapters/installation-setup.qmd-
chapters/installation-setup.qmd-https://happygitwithr.com/ 
chapters/installation-setup.qmd-
chapters/installation-setup.qmd-https://swcarpentry.github.io/git-novice
chapters/installation-setup.qmd-
--
chapters/rewriting-history.qmd:## References
chapters/rewriting-history.qmd-
chapters/rewriting-history.qmd-- https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/removing-sensitive-data-from-a-repository
--
chapters/stashing-rebasing.qmd:## References:
chapters/stashing-rebasing.qmd-
chapters/stashing-rebasing.qmd-https://git-scm.com/book/en/v2/Git-Tools-Stashing-and-Cleaning
chapters/stashing-rebasing.qmd-
chapters/stashing-rebasing.qmd-https://dev.to/_mohanmurali/deep-dive-into-git-rebase-5b05

• https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html
• https://xkcd.com/1296/

• schedule: "git basics survey" shows up multiple times

• permission denied when trying to init git repo with invalid path

• git add -A or git add --a not git add -a

• commit hash

• play around with basic git commands, vim etc.
• make multiple commits in one repository
• compare commits across history
• .gitignore
• example use-case: tracking word documents in git
• discussion: advantages / disadvantages of git in combination with binary files like word
• relation to .gitignore: word create a temporary file, something like "~$mypaper.docx"
• gateway to markdown session (session 5): why it's not great to track binary files in git and what are the alternatives to word
• git commit : explain that one can also add a more detailed description, e.g., git commit -m "commit message" -m "longer description"
• idea that one can use the description of the commit message to document changes in binary files in a bit more detail
• discuss different workflows of using git add, git commit etc.
• make minimal changes
• encapsulate only neccessary changes in commit
• reproducibility: recreate temporary files from changes in code
• explain repeated --amend
• add graphics that explain staging environment vs. commit

perhaps it's nice to add a glossary, see https://debruine.github.io/glossary/articles/glossary.html

@konradpa, this is low priority but if you are interested to check this out, let me know if this is a nice option.

• open issues first
• protect main
• branch-based workflow

• acknowledge ddlitlab funding support
• acknowledge helpful resources and references

quote from here (at about 5 min)

liked the quote, saving for later.

• https://openscapes.org/blog/2022-05-27-github-illustrated-series/
• https://openscapes.github.io/series/how-do-i/do-fix-git-things.html
• https://www.physalia-courses.org/courses-workshops/version-control/
• https://tylercipriani.com/blog/2022/11/19/git-notes-gits-coolest-most-unloved-feature/
• https://sebastiandedeyne.com/setting-up-a-global-gitignore-file/
• https://en.m.wikibooks.org/wiki/Git/Repository_on_a_USB_stick
• https://carpentries.org/blog/2020/05/conversations-teaching-git-github/
• https://pad.carpentries.org/git-discussion

• Add section on how to customize CLI visually (Mac: https://medium.com/@charlesdobson/how-to-customize-your-macos-terminal-7cce5823006e)
• Student question: Explain difference between relative/absolute path
• explain directory structure better.
  I have heard that especially today where students use their phones a lot it becomes less clear that a computer has a certain hierarchical directory structure
• add echo command to CLI chapter
• Student Question: Clarify: Where does cd ~/../../.. take you in file system?
• Include using tab to autocomplete paths in command line
• Clarify spacing between commands/flags
  -Student question: "can't access" when using wildcards to search for e.g. .yml files. Maybe change/clarify example?
• re above: yes, use an example where they can actually use ls meanigfully
• add "clear" command?
• clarify what "-alh" output shows
• Student question: "ls" doesn't have help flag (on Mac) ("man ls" works on Mac)
• Using "q" to get out of page in terminal.
• we should make the warning about rm -rf much bigger
• add overview of directory and file structure
• highlight folder structure differences between mac and windows
• delete test results from survey
• don't forget to make questions in survey optional

"true true" at beginning of chapters

I think it would fit there well ;-)

find a new name and include different more advanced commands that might be useful like:
git cherry-pick
git reset
git revert
git clean

• https://github.com/0nn0/terminal-mac-cheatsheet#english-version
• https://github.com/k88hudson/git-flight-rules
• https://biostats-r.github.io/biostats/github/
• https://m.youtube.com/watch?v=9mnKloUiTUc
• http://www.jarrodmillman.com/rcsds/standard/git-intro.html
• https://githubflow.github.io
• https://github.com/jdblischak/git-for-science
• https://www.manning.com/books/git-in-practice

• Idea: parse the bib file and display references as table in some sections
• format license information using shields badges
• package: https://github.com/ropensci/bib2df/

• Switching to new branch only possible after first commit

• using Crl/strg-c to get back to Terminal, getting out of "Quarto mode."

• Uncommited changes switch to new branch

• (Preparing) Demoing merge conflict

• Visualizing differences between branches

• Reference to git log (git log -all)

• Showing merge conflict in GUI (GitKraken)

• When is switching branches not possible?

• Layout
• Decide on PAT or SSH for verification
• @lnnrtwttkhn add SSH key section
• 1. Pushing recipe repo to GitHub, 2. Creating repo on Github and clone it
• Switching forking and cloning in book
• Demoing cloning
• Repository setting - add section in book (private/public, README)
• Creating EMPTY repository to be able to push existing repo
• Creating github organization?
• Exercise: pushing existing repo to GitHub, clone it to different location on PC, make changes in clone, push changes, pull from original location
• Extra Exercise: Create branch and push branch
• Demo/Explain differences between git fetch and git pull
• Put forking in end of book
• Forking/Templaterepos/GitHub alternatives/Branch protection/git blame as extra content
• Send email: Creating GitHub account
• Session 10: Pull requests, collab, Github flow?
• Figure out how to collaborate easily among course members - organization?
• Section about GitHub flow?
• Create slides

basic:
git fetch
git show
git blame
Hashes
git checkout to time/hash

commits:
detailed commit ettiquette
Repeating amends
interactive commits
git cherry-pick
git reset
git revert
git clean

advanced:
git archive
git bisect
git rev-parse
hooks
Mergetools

• Next Session - Zoom?

• PAT: Explain Expiration date

• PAT: Explain Scopes in detail

• PAT: Explain Notes

• Repository: Explain Public vs. Private

• PAT: Multiple ways to when PAT has to be entered

• Cloning: Maybe use repo of others not own?

• Cloning same repo is maybe complicated

• Pulling works only on branch that is pushed to GitHub

• Session build on each other! -> make it more explicit

• cheatsheet explizit erwähnen!. encourage use!

• Emphasize use of git log/status to know about repo

• emphasize cleaning up repos

• Book: creating first repo without readme

• checking branch you're on, before pulling

• demo error: pulling while on "wrong" branch

For inspiration, see https://social.jvns.ca/@b0rk/111370726485532299

If you want to keep your changes you should save them using the stage and commit workflow It is also possible to temporarily stash your changes using git stash or delete your changes using git reset which will both be covered in later chapters.

we should update the references to these chapters once they are in place.

--

Visibility and permissions settings on GitLab

• GitLab (and GitHub) allow setting the project and group visibility
  • GitLab visibility levels: Private Internal Public (details here)
• GitLab (and GitHub) allow setting fine-grained permissions and roles for contributors
  • GitLab roles: Guest Reporter Developer Maintainer Owner (details here)

--

Example workflow

• Your projects are private from the start
• Everyone in your group can view each other's projects (Guest or Reporter)
• Direct collaborators (internal or external) can edit the project (Developer or Maintainer)
• The PI gets access to all projects (Maintainer or Owner; optionally only at the end of a project)
• Project can be set to public later on (e.g., upon publication)

???

• Group members can always view your projects and their current status
• Group members can clone your repository, fork it, open issues and merge requests
• Group members can not make any changes to your project by default
• PI has at least Maingtainer access to all projects for long-term availability

• how can we visualize the difference between git fetch and git pull?

• how can I edit a commit that has too many diffs

I would like to add the all contributors bot.

we had this issue with one course participant on macOS Ventura 13.4.

see https://apple.stackexchange.com/questions/254380/why-am-i-getting-an-invalid-active-developer-path-when-attempting-to-use-git-a

brief (incomplete) roadmap

• I have a folder called "share"
• I want to upload the data from the custer to gin
• check how large the dataset is
• modular datasets or one big dataset?
• setup ssh
• datalad save the dataset (use --force)
• configure gin
• push to gin
• set up DOI

as discusses before, I think it would be nice to include a minimal markdown guide.

when you do git pull one receives this

git pull
hint: You have divergent branches and need to specify how to reconcile them.
hint: You can do so by running one of the following commands sometime before
hint: your next pull:
hint: 
hint:   git config pull.rebase false  # merge
hint:   git config pull.rebase true   # rebase
hint:   git config pull.ff only       # fast-forward only
hint: 
hint: You can replace "git config" with "git config --global" to set a default
hint: preference for all repositories. You can also pass --rebase, --no-rebase,
hint: or --ff-only on the command line to override the configured default per
hint: invocation.

it would be good to clarify what to do in those circumstance.

I think it would be nice to add specific scientific use cases, where version control is particularly for scientific workflows.

a few examples that come to mind:

• ethics applications
• paper writing / feedback from supervisor
• bug fixes in analysis pipelines

• focus on vim (which is the default editor)
• explain relationship between git, vim and other GUI text editors on the computer
• explain the difference between plain text and Word
• basics on how to use vim
• discuss differences between local and global git config
• explain to use same email for git and github
• maybe skip account creation on github
• clarify exercises for creating a recipe
• .gitignore optional?
• .gitignore discussion / ideas
  • keep repositories small / only commit files that are really needed
  • reproducibility: don't add files that can be easily regenerated from the committed code
  • don't add files that are not relevant to other users, e.g., editor configuration files etc.
• differences between local and global .gitignore
• add warning: don't create a new repo e.g., in your user directory
• use ls -a command to show the hidden .git folder (add link to command line chapter)
• add warning: don't mess with the .git folder
• add git init my-project
• add mini-quiz: how to create a project folder, either (1) mkdir my-project && cd my-project & git init or git init my-project
• setup session as live coding session
• separate installation and setup chapter
• move creation of github account to github chapter
• edit installation and setup survey
• send email to ask to verify installation and complete installation survey
• git commands always refer to the "closest" .git file. clarify that.
• beware of nested .git repositories. explain if it's possible to have nested git repositories
• decide for default text editors on Windows (Notepad) and macOS (TextEdit)
• demonstrate interaction between editing text files in vim and through the GUI texteditor
• explain what the staging area is, see e.g., https://youtu.be/HMqUFlu0gFc?t=228
• think about whether to add STOP signs to the chapter for course participants!

• CLI Survey: clarify question about using dashes for flags
• Question: How to show only specific configurations
• Clarify what plain textfiles are
• Clarify Vim (hard to do), creating file with vim
• cat command
• combining vim commands
• Content is not important, does not have to be recipes, can also initialize existing code
• CLI: creating subfolders with mkdir -p
• Git commands apply in git initiliazed-parent director if used in child directory
• Problem: little bit too much content for session, had to rush at the end
• Add using semilicons to combine commands (maybe in CLI chapter)

these are two gitlab functions in issues that AFAIK do not exist on github:

Confidential issues in GitLab

• Confidentiality: Issue visible only for team members

Due dates in Gitlab

• Due date: Set due dates for Issues

Keeping this here for later, if we still want to add it.

• github vs. gitlab vs. bitbucket vs. code berg vs. gitea vs. gin etc.
• add discussion on #GiveUpGitHub etc.
• discuss risk of vendor lock-in

One more idea of me would be to already include some disadvantages of git to "take the wind out of the sails".

github actions crashes

adding:

engine: knitr
execute:
  eval: false

to the yaml header, fixes it. but this is not necessary for all other chapters.

weird, but I will apply this as a hotfix

• hadley's cocktails: https://cocktails.hadley.nz/ https://github.com/hadley/cocktails
• hadley's recipes: https://github.com/hadley/recipes, https://recipes.had.co.nz/

more ideas for exercises:

• http://www.jarrodmillman.com/rcsds/append/git-advanced.html
• https://www.frontiersin.org/articles/10.3389/fninf.2019.00001/full?utm_source=FRN&utm_medium=EMAIL_IRIS&utm_campaign=EMI_FRN_ARTICLEPUBLISHED_COAUTHORS&utm_content=ARTICLE_TITLE
• http://www.jarrodmillman.com/rcsds/standard/git-intro.html

• what is a "good" commit
• reduce diffs
• atomic commits / which level of granularity
• what are good commit messages
• when to branch / how to branch
• link commits to issues

.pull-left[

Basic collaboration workflow:

1. Clone the repository (i.e., "download the project")
2. Switch to a new branch (i.e., "start a separate version")
3. Make changes to the files and push the new version
4. Open a merge / pull request ¹
   {{content}}
   ]

--

The repository maintainer (i.e., you) can ...

• see what was changed when by whom
• add additional changes to the merge request
• run (automated) checks on the contribution
• approve the contribution and merge the changes
  {{content}}

--

Examples:

• A co-author proposes changes to your manuscript
• A collaborator adds new data to your dataset
• A colleague fixes several bugs in your analysis pipeline

sorry, this is not very elegant but I'm quickly dumping a few notes heres:

• "recipes task": (1) add your favorite recipes, (2) add a recipe that you don't like /this will be removed later)
• .gitignore: explain the difference between global and project-specific .gitignore
• .gitignore: explain what .DS_Store is (for mac users only)
• add more categories to the chapters so they show up in the contents page
• labels for difficulty / experience level: beginner, intermediate, advanced
• create one page with all the cheatsheets

@konradpa, could you please review these points and let me know what is already included in the book and what we still could add? let me know if anything is unclear! thanks!

• how to make changes to the project
• how to use quarto
• add software and requirements details

#46