feedback on version control chapter

[lnnrtwttkhn]

hi @HeidiSeibold and @RabeaMue,

here is my feedback on the version control chapter. overall, I think it gives a very nice short introduction to the basic functions and commands of Git. below are a few thoughts that I had while reading through the chapter. feel free to ignore them, if you think they are not relevant to your target audience. I didn't make any changes re grammar or style because this would be somewhat opinionated anyways (but I added automated typo fixing, see #5). let me know if anything is unclear! great work!

• [x] it's mentioned in the beginning that version control "contributes to reproducibility in several ways", but at this stage it's not entirely clear what those contributions are. Maybe you could hint at a few examples?
• [x] I think the distinction between Git and platforms like GitHub or GitLab is often unclear to beginners and could be clarified. for example, in our version control book (work-in-progress) we use these definitions:

Git is a version control system (software installed on your computer) that allows you to track changes and manage the history of your files locally on your computer. It provides features such as branching, merging, and reverting to previous versions. GitHub is a web-based hosting service for your Git repositories, allowing you to store and share your Git projects online. GitHub provides additional collaboration features such as issue tracking, pull requests, and project management tools. In summary, Git is the version control system itself, while GitHub is a hosting service built on top of Git. Git can be used independently without GitHub, but GitHub relies on Git for its functionality.

• [x] you mention several times that Git is useful for code and text or both. I think it's useful to say that Git works well with plain-text files that can be either code (e.g., Python, R etc.) or text for a paper, report etc.
• [x] consistency: you use both "git" and "Git"
• [x] re installation: you could consider using a tabset or similar for the various operating systems.
• [x] I think that Git should be installed by default on new macOS systems.
• [ ] it wasn't clear to me why there are extra instructions for R users
• [x] it could be useful to add a short explanation what GitHub is (see point above), because it could be unclear for beginners why you explain how to create a repository on GitHub
• [x] relatedly, I think it could be helpful to make clear that Git is a command-line tool that can be used only locally and independently from GitHub while the advantages of GitHub mainly come in when one wants to start collaborating on Git repos
• [x] The purpose of the README.md and especially the .gitignore file could be explained in a bit more detail, if you recommend to add them when creating a new repo on GitHub
• [x] You showcase the "GitHub-first" approach, however it could be useful to mention that one can also start from a local repository and push this to GitHub later. however, this requires to initialize an empty repository on GitHub, otherwise the local repo usually can't be pushed when the initial commit diverges
• [x] it could be useful to discuss the output message of git status
• [x] when introducing git add . it's might be not clear what "Stage" in "Stage the changed files:" means.
• [x] I would highlight the dangers of git add ., i.e., adding all changes instead of staging / committing more selectively e.g., using git add FILE
• [x] "Git really only works with real text files" - I think it's a bit unclear what this means since Git can in principle be used for any files. I think you mean that e.g., the highlighting of line-by-line changes does not work with e.g., binary files.
• [ ] "It is not as advanced and versatile, but a nice way to work in a WYSIWYG (What You See Is What You Get) editor." - I think the relationship betwen versioning, Git and WYSIWYG editors is not entirely clear here. e.g., Quarto / RStudio now offers WYSIWYG editing but the files are still plain-text. I think this is the main point: that git is really powerful for working with plain-text files and e.g., Word (being a proprietary software, does not save text in a way that allows efficient tracking in Git).
• [x] another point: I think's it's worth highlighting key advantages of Git compared to Git which IMO are (1) that you keep the history of changes whereas changes are usually "gone" once you accept them in e.g., Word and (2) branches: being able to work on parallel versions of the same file and integrating them. you didn't mention branchesn in the main text, though...

[HeidiSeibold]

Thanks @lnnrtwttkhn for the thorough feedback. @RabeaMue do you have time to implement these? Let me know what I can do to support!

[RabeaMue]

@HeidiSeibold Yes, I am editing the points from the feedback now and sending you a pull request. Thank you @lnnrtwttkhn !

[RabeaMue]

PR is here: https://github.com/BERD-NFDI/BERD-reproducible-research-course/pull/8