source commit: d9604b3

01-basics.md

@@ -0,0 +1,128 @@
+---
+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?
+
+::::::::::::::::::::::::::::::::::::::::::::::::::
+
+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 - 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,225 @@
+---
+title: Setting Up Git
+teaching: 5
+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?
+
+::::::::::::::::::::::::::::::::::::::::::::::::::
+
+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 that same email address for the `user.email` value, e.g. `[email protected]` replacing `username` with your GitHub one.
+
+
+::::::::::::::::::::::::::::::::::::::::::::::::::
+
+:::::::::::::::::::::::::::::::::::::::::  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.
+
+::::::::::::::::::::::::::::::::::::::::::::::::::
+
+