source commit: 327eda9

01-basics.md

@@ -0,0 +1,141 @@
+---
+title: Automated Version Control
+teaching: 5
+exercises: 0
+---
+
+::::::::::::::::::::::::::::::::::::::: objectives
+
+- Understand the benefits of an automated version control system.
+- Understand the basics of how automated version control systems work.
+
+::::::::::::::::::::::::::::::::::::::::::::::::::
+
+:::::::::::::::::::::::::::::::::::::::: questions
+
+- What is version control and why should I use it?
+
+::::::::::::::::::::::::::::::::::::::::::::::::::
+
+::::::::::::::::::::::::::::::::::::::::: instructor
+Original lesson material: https://swcarpentry.github.io/git-novice/ 
+Slides: https://esciencecenter-digital-skills.github.io/digital-skills-slides/modules/git-lesson/git-slides, until https://esciencecenter-digital-skills.github.io/digital-skills-slides/modules/git-lesson/git-slides#/4.
+Please note that slides will be deployed in the 'right place' in due time. Right now nobody knows where that is.
+
+The slides provide visual context to the concepts that are used in the live coding. It would be best to have both the live coding screen and the slides screen side by side. As this is in general not possible, it is best to switch back and forth between command line and slides when necessary (you can use the images in the teaching material as indication when to switch to the slides).
+
+Teach what you think is most useful. See how far you get, usually we get to episode 7 (Remotes in GitHub) in one morning. Ignore the temptation to answer advanced questions. (You can of course do this individually during exercises).
+
+
+::::::::::::::::::::::::::::::::::::::::::::::::::
+
+We'll start by exploring how version control can be used
+to keep track of what one person did and when.
+Even if you aren't collaborating with other people,
+automated version control is much better than this situation:
+
+!["notFinal.doc" by Jorge Cham, <https://www.phdcomics.com>](fig/phd101212s.png){alt='Comic: a PhD student sends "FINAL.doc" to their supervisor, but after several increasingly intense and frustrating rounds of comments and revisions they end up with a file named "FINAL_rev.22.comments49.corrections.10.#@$%WHYDIDCOMETOGRADSCHOOL????.doc"'}
+
+We've all been in this situation before: it seems unnecessary to have
+multiple nearly-identical versions of the same document. Some word
+processors let us deal with this a little better, such as Microsoft
+Word's
+[Track Changes](https://support.office.com/en-us/article/Track-changes-in-Word-197ba630-0f5f-4a8e-9a77-3712475e806a),
+Google Docs' [version history](https://support.google.com/docs/answer/190843?hl=en), or
+LibreOffice's [Recording and Displaying Changes](https://help.libreoffice.org/Common/Recording_and_Displaying_Changes).
+
+Version control systems start with a base version of the document and
+then record changes you make each step of the way. You can
+think of it as a recording of your progress: you can rewind to start at the base
+document and play back each change you made, eventually arriving at your
+more recent version.
+
+![](fig/play-changes.svg){alt='Changes Are Saved Sequentially'}
+
+Once you think of changes as separate from the document itself, you
+can then think about "playing back" different sets of changes on the base document, ultimately
+resulting in different versions of that document. For example, two users can make independent
+sets of changes on the same document.
+
+![](fig/versions.svg){alt='Different Versions Can be Saved'}
+
+Unless multiple users make changes to the same section of the document - a 
+[conflict](../learners/reference.md#conflict) - you can
+incorporate two sets of changes into the same base document.
+
+![](fig/merge.svg){alt='Multiple Versions Can be Merged'}
+
+A version control system is a tool that keeps track of these changes for us,
+effectively creating different versions of our files. It allows us to decide
+which changes will be made to the next version (each record of these changes is
+called a [commit](../learners/reference.md#commit)), and keeps useful metadata
+about them. The complete history of commits for a particular project and their
+metadata make up a [repository](../learners/reference.md#repository).
+Repositories can be kept in sync across different computers, facilitating
+collaboration among different people.
+
+:::::::::::::::::::::::::::::::::::::::::  callout
+
+## The Long History of Version Control Systems
+
+Automated version control systems are nothing new.
+Tools like [RCS](https://en.wikipedia.org/wiki/Revision_Control_System), [CVS](https://en.wikipedia.org/wiki/Concurrent_Versions_System), or [Subversion](https://en.wikipedia.org/wiki/Apache_Subversion) have been around since the early 1980s and are used by
+many large companies.
+However, many of these are now considered legacy systems (i.e., outdated) due to various
+limitations in their capabilities.
+More modern systems, such as Git and [Mercurial](https://swcarpentry.github.io/hg-novice/),
+are *distributed*, meaning that they do not need a centralized server to host the repository.
+These modern systems also include powerful merging tools that make it possible for
+multiple authors to work on
+the same files concurrently.
+
+
+::::::::::::::::::::::::::::::::::::::::::::::::::
+
+:::::::::::::::::::::::::::::::::::::::  challenge
+
+## Paper Writing
+
+- Imagine you drafted an excellent paragraph for a paper you are writing, but later ruin
+  it. How would you retrieve the *excellent* version of your conclusion? Is it even possible?
+
+- Imagine you have 5 co-authors. How would you manage the changes and comments
+  they make to your paper?  If you use LibreOffice Writer or Microsoft Word, what happens if
+  you accept changes made using the `Track Changes` option? Do you have a
+  history of those changes?
+
+:::::::::::::::  solution
+
+## Solution
+
+- Recovering the excellent version is only possible if you created a copy
+  of the old version of the paper. The danger of losing good versions
+  often leads to the problematic workflow illustrated in the PhD Comics
+  cartoon at the top of this page.
+
+- Collaborative writing with traditional word processors is cumbersome.
+  Either every collaborator has to work on a document sequentially
+  (slowing down the process of writing), or you have to send out a
+  version to all collaborators and manually merge their comments into
+  your document. The 'track changes' or 'record changes' option can
+  highlight changes for you and simplifies merging, but as soon as you
+  accept changes you will lose their history. You will then no longer
+  know who suggested that change, why it was suggested, or when it was
+  merged into the rest of the document. Even online word processors like
+  Google Docs or Microsoft Office Online do not fully resolve these
+  problems.
+
+
+
+:::::::::::::::::::::::::
+
+::::::::::::::::::::::::::::::::::::::::::::::::::
+
+:::::::::::::::::::::::::::::::::::::::: keypoints
+
+- Version control is like an unlimited 'undo'.
+- Version control also allows many people to work in parallel.
+
+::::::::::::::::::::::::::::::::::::::::::::::::::
+
+

02-setup.md

@@ -0,0 +1,231 @@
+---
+title: Setting Up Git
+teaching: 10
+exercises: 0
+---
+
+::::::::::::::::::::::::::::::::::::::: objectives
+
+- Configure `git` the first time it is used on a computer.
+- Understand the meaning of the `--global` configuration flag.
+
+::::::::::::::::::::::::::::::::::::::::::::::::::
+
+:::::::::::::::::::::::::::::::::::::::: questions
+
+- How do I get set up to use Git?
+
+::::::::::::::::::::::::::::::::::::::::::::::::::
+
+:::::::::::::::::::::::::::::::::::::::: instructor
+
+There are no slides for this episode. Explain what a command line is, why it is useful, and why we use it in this workshop. Participants are often new to the command line and don't get why we not use a git gui. Only focus on the bare essentials for setting up git. We shall use nano editor so that everyone is on the same page.
+
+::::::::::::::::::::::::::::::::::::::::::::::::::
+
+When we use Git on a new computer for the first time,
+we need to configure a few things. Below are a few examples
+of configurations we will set as we get started with Git:
+
+- our name and email address,
+- what our preferred text editor is,
+- and that we want to use these settings globally (i.e. for every project).
+
+On a command line, Git commands are written as `git verb options`,
+where `verb` is what we actually want to do and `options` is additional optional information which may be needed for the `verb`. So here is how
+Dracula sets up his new laptop:
+
+```bash
+$ git config --global user.name "Vlad Dracula"
+$ git config --global user.email "[email protected]"
+```
+
+Please use your own name and email address instead of Dracula's. This user name and email will be associated with your subsequent Git activity,
+which means that any changes pushed to
+[GitHub](https://github.com/),
+[BitBucket](https://bitbucket.org/),
+[GitLab](https://gitlab.com/) or
+another Git host server
+after this lesson will include this information.
+
+For this lesson, we will be interacting with [GitHub](https://github.com/) and so the email address used should be the same as the one used when setting up your GitHub account. If you are concerned about privacy, please review [GitHub's instructions for keeping your email address private][git-privacy].
+
+:::::::::::::::::::::::::::::::::::::::::  callout
+
+## Keeping your email private
+
+If you elect to use a private email address with GitHub, then use GitHub's no-reply email address for the `user.email` value. It looks like `[email protected]`. You can look up your own address in your GitHub [email settings](https://github.com/settings/emails).
+
+
+::::::::::::::::::::::::::::::::::::::::::::::::::
+
+:::::::::::::::::::::::::::::::::::::::::  callout
+
+## Line Endings
+
+As with other keys, when you hit <kbd>Enter</kbd> or <kbd>↵</kbd> or on Macs, <kbd>Return</kbd> on your keyboard,
+your computer encodes this input as a character.
+Different operating systems use different character(s) to represent the end of a line.
+(You may also hear these referred to as newlines or line breaks.)
+Because Git uses these characters to compare files,
+it may cause unexpected issues when editing a file on different machines.
+Though it is beyond the scope of this lesson, you can read more about this issue
+[in the Pro Git book](https://www.git-scm.com/book/en/v2/Customizing-Git-Git-Configuration#_core_autocrlf).
+
+You can change the way Git recognizes and encodes line endings
+using the `core.autocrlf` command to `git config`.
+The following settings are recommended:
+
+On macOS and Linux:
+
+```bash
+$ git config --global core.autocrlf input
+```
+
+And on Windows:
+
+```bash
+$ git config --global core.autocrlf true
+```
+
+::::::::::::::::::::::::::::::::::::::::::::::::::
+
+Dracula also has to set his favorite text editor, following this table:
+
+| Editor                                | Configuration command | 
+| :-----------                          | :------------------------------ |
+| Atom                                  | `$ git config --global core.editor "atom --wait"`                      | 
+| nano                                  | `$ git config --global core.editor "nano -w"`                      | 
+| BBEdit (Mac, with command line tools) | `$ git config --global core.editor "bbedit -w"`                      | 
+| Sublime Text (Mac)                    | `$ git config --global core.editor "/Applications/Sublime\ Text.app/Contents/SharedSupport/bin/subl -n -w"`                      | 
+| Sublime Text (Win, 32-bit install)    | `$ git config --global core.editor "'c:/program files (x86)/sublime text 3/sublime_text.exe' -w"`                      | 
+| Sublime Text (Win, 64-bit install)    | `$ git config --global core.editor "'c:/program files/sublime text 3/sublime_text.exe' -w"`                      | 
+| Notepad (Win)                         | `$ git config --global core.editor "c:/Windows/System32/notepad.exe"`                      | 
+| Notepad++ (Win, 32-bit install)       | `$ git config --global core.editor "'c:/program files (x86)/Notepad++/notepad++.exe' -multiInst -notabbar -nosession -noPlugin"`                      | 
+| Notepad++ (Win, 64-bit install)       | `$ git config --global core.editor "'c:/program files/Notepad++/notepad++.exe' -multiInst -notabbar -nosession -noPlugin"`                      | 
+| Kate (Linux)                          | `$ git config --global core.editor "kate"`                      | 
+| Gedit (Linux)                         | `$ git config --global core.editor "gedit --wait --new-window"`                      | 
+| Scratch (Linux)                       | `$ git config --global core.editor "scratch-text-editor"`                      | 
+| Emacs                                 | `$ git config --global core.editor "emacs"`                      | 
+| Vim                                   | `$ git config --global core.editor "vim"`                      | 
+| VS Code                               | `$ git config --global core.editor "code --wait"`                      | 
+
+It is possible to reconfigure the text editor for Git whenever you want to change it.
+
+:::::::::::::::::::::::::::::::::::::::::  callout
+
+## Exiting Vim
+
+Note that Vim is the default editor for many programs. If you haven't used Vim before and wish to exit a session without saving
+your changes, press <kbd>Esc</kbd> then type `:q!` and hit <kbd>Enter</kbd> or <kbd>↵</kbd> or on Macs, <kbd>Return</kbd>.
+If you want to save your changes and quit, press <kbd>Esc</kbd> then type `:wq` and hit <kbd>Enter</kbd> or <kbd>↵</kbd> or on Macs, <kbd>Return</kbd>.
+
+
+::::::::::::::::::::::::::::::::::::::::::::::::::
+
+Git (2.28+) allows configuration of the name of the branch created when you
+initialize any new repository.  Dracula decides to use that feature to set it to `main` so
+it matches the cloud service he will eventually use.
+
+```bash
+$ git config --global init.defaultBranch main
+```
+
+:::::::::::::::::::::::::::::::::::::::::  callout
+
+## Default Git branch naming
+
+Source file changes are associated with a "branch."
+For new learners in this lesson, it's enough to know that branches exist, and this lesson uses one branch.  
+By default, Git will create a branch called `master`
+when you create a new repository with `git init` (as explained in the next Episode). This term evokes
+the racist practice of human slavery and the
+[software development community](https://github.com/github/renaming)  has moved to adopt
+more inclusive language.
+
+In 2020, most Git code hosting services transitioned to using `main` as the default
+branch. As an example, any new repository that is opened in GitHub and GitLab default
+to `main`.  However, Git has not yet made the same change.  As a result, local repositories
+must be manually configured have the same main branch name as most cloud services.
+
+For versions of Git prior to 2.28, the change can be made on an individual repository level.  The
+command for this is in the next episode.  Note that if this value is unset in your local Git
+configuration, the `init.defaultBranch` value defaults to `master`.
+
+::::::::::::::::::::::::::::::::::::::::::::::::::
+
+The five commands we just ran above only need to be run once: the flag `--global` tells Git
+to use the settings for every project, in your user account, on this computer.
+
+Let's review those settings and test our `core.editor` right away:
+
+```bash
+$ git config --global --edit
+```
+
+Let's close the file without making any additional changes.  Remember, since typos in the config file will cause
+issues, it's safer to view the configuration with:
+
+```bash
+$ git config --list
+```
+
+And if necessary, change your configuration using the
+same commands to choose another editor or update your email address.
+This can be done as many times as you want.
+
+:::::::::::::::::::::::::::::::::::::::::  callout
+
+## Proxy
+
+In some networks you need to use a
+[proxy](https://en.wikipedia.org/wiki/Proxy_server). If this is the case, you
+may also need to tell Git about the proxy:
+
+```bash
+$ git config --global http.proxy proxy-url
+$ git config --global https.proxy proxy-url
+```
+
+To disable the proxy, use
+
+```bash
+$ git config --global --unset http.proxy
+$ git config --global --unset https.proxy
+```
+
+::::::::::::::::::::::::::::::::::::::::::::::::::
+
+:::::::::::::::::::::::::::::::::::::::::  callout
+
+## Git Help and Manual
+
+Always remember that if you forget the subcommands or options of a `git` command, you can access the
+relevant list of options typing `git <command> -h` or access the corresponding Git manual by typing
+`git <command> --help`, e.g.:
+
+```bash
+$ git config -h
+$ git config --help
+```
+
+While viewing the manual, remember the `:` is a prompt waiting for commands and you can press <kbd>Q</kbd> to exit the manual.
+
+More generally, you can get the list of available `git` commands and further resources of the Git manual typing:
+
+```bash
+$ git help
+```
+
+::::::::::::::::::::::::::::::::::::::::::::::::::
+
+[git-privacy]: https://help.github.com/articles/keeping-your-email-address-private/
+
+
+:::::::::::::::::::::::::::::::::::::::: keypoints
+
+- Use `git config` with the `--global` option to configure a user name, email address, editor, and other preferences once per machine.
+
+::::::::::::::::::::::::::::::::::::::::::::::::::
+
+