Release 1.1.0 (#35)

* Add introduction episode

* Correct link to homepage in navbar

* Add acknowledgements to Software Carpentry

* Add content for motivation episode

* Add content for Git vs GitHub episode

* Add content for making repositories episode

* Enable copyright notice on course notes pages

* Add episode on creating example repo

* Add material on configuring Git/GitHub

* Turn on display of course notes

* Create episode on recording changes

* Add option for including custom attribution

* Add episode on Git log and viewing diffs

* Add further episode on recording changes

  Covers pathspecs, incremental staging and 'git rm' and 'git mv'.

* Add episode on undoing changes

* Add episode on ignoring things in Git

* Issue 11: Session 1, Episode 10 (#33)

  Add material for episode 10

* Add acknowledgement to Software Carpentry course

* Fix hyperlinks (#34)

  Internal hyperlinks now use the site.url liquid variable. Links to
  external resources will now target a new tab.

---------

Co-authored-by: Felicity Guest <[email protected]>

_config.yml

@@ -6,7 +6,7 @@ description: Learn to use version control to manage your software development an
 n_sessions: 3
 prereq: NA
 url: https://uniexeterrse.github.io/intro-version-control
-notes_on: false
+notes_on: true
 
 # Specify that things in the episodes collection should be output.
 collections:

_episodes/01_intro.md

@@ -0,0 +1,63 @@
+---
+layout: page
+title: Introductions
+order: 1
+session: 1
+length: 5
+toc: true
+adapted: false
+---
+
+## Welcome
+
+This workshop was put together by the Research Software Engineering Group.
+This is as part of an ongoing initiative to provide training for staff and
+students to expand their skill sets and position themselves to confidently
+perform the informatics elements of their research projects in an efficient and
+reproducible way. The programme and workshops are under constant evolution, and
+we are grateful for your feedback which is a core component of this process.
+
+We will start by introducing the workshop leaders and helpers. We are all here
+because we are passionate about sharing our knowledge and supporting the
+development of our colleagues.
+
+
+## Housekeeping
+
+The workshop in organised into episodes of content, which can be seen in the
+[workshop schedule]({{ site.url }}/schedule.html). Our aim is to have an official break
+every 60-90 minutes, but there will also be periods in-between demonstrations
+where you are free to take additional comfort breaks if required.
+
+This workshop will be delivered mainly by live coding and exercises, with
+participants expected to follow along with the worked examples. Our aim is to be
+responsive to the needs of the group, both in person and
+virtually. Therefore, think of the schedule as a guide rather than a strict
+timetable. We welcome questions and queries as we go along: there are helpers
+in the room so if you need assistance at any point please do indicate this to
+them. There is also a dedicated
+helper for the virtual participants so please raise your virtual hand to
+attract their attention, or drop a question in the meeting chat if you prefer.
+
+Please conduct yourselves in line with the
+[code of conduct]({{ site.url }}/code.html) —
+essentially, be respectful and aware that we all have different backgrounds,
+experiences and viewpoints.
+
+
+## Acknowledgement
+
+This course has been adapted from Software Carpentry's
+<a href="https://swcarpentry.github.io/git-novice/" target="_blank" rel="external noreferrer">Version Control with Git</a>
+course [[^1]], which is &copy; <a href="https://software-carpentry.org/" target="_blank" rel="external noreferrer">Software Carpentry</a> and licensed
+under <a href="https://creativecommons.org/licenses/by/4.0/" target="_blank" rel="external noreferrer">Creative Commons BY 4.0</a>.
+Changes have been made from the original content.
+
+
+### References
+
+[^1]: Ivan Gonzalez; Daisie Huang;  Nima Hejazi;  Katherine Koziar; 
+      Madicken Munk (eds): "Software Carpentry: Version Control with Git."  
+      Version 2019.06.1, July 2019,
+      <a href="https://github.com/swcarpentry/git-novice">https://github.com/swcarpentry/git-novice</a>,
+      10.5281/zenodo.3264950

_episodes/02_motivation.md

@@ -0,0 +1,139 @@
+---
+layout: page
+title: "Motivation: Why use Version Control Systems?"
+order: 2
+session: 1
+length: 10
+toc: true
+adapted: false
+---
+
+## Learning Objectives
+
+At the end of this episode you will be able to describe what version control
+systems are and why they are useful.
+
+
+## What is a version control system?
+
+A **version control system** is software that enables you to
+record and manage the history of versions of files as they change. They are
+typically used for tracking the changes to software source code, such as Python
+files, R files, C/C++ source files, or other text-based documents like HTML, LaTeX, Markdown, etc.
+With a version control system, you
+make changes to a file (or files) as normal, but then use the version control
+system to capture the updated version. You can attach comments to each captured
+version to explain the changes made. In this way, you incrementally
+build up a history of versions of the file(s). The version control system
+allows you to view the evolution of files and 'roll back' to any previous
+version you like. It also takes care of storing away this history out of your
+day-to-day sight.
+
+So a version control system acts as a record-keeping device. This is useful, but
+the real power of a version control system is that that they
+_facilitate collaboration_ when multiple
+people work on a set of files, such as when a team of people are developing
+code. In particular, they provide a set of
+tools that allow you to easily share your changes with others and, crucially,
+_combine other peoples' changes with your own_. The tooling enables you to do
+this in a structured way that makes combining changes transparent
+and less error-prone. Furthermore, the histories of each person's changes are
+shared with each other, so that the record of changes to files is not split out
+amongst multiple person's computers.
+
+
+## Why bother to use a version control system?
+
+There is, of course, a disadvantage to using a version control system: you need
+to learn how to use it. Is it perhaps easier to use other methods to keep track
+of versioning your files?
+
+Let's compare version control systems to a couple of other options.
+
+### Cloud-based synchronisation e.g. Google Drive, DropBox, OneDrive/SharePoint
+
+These days there are cloud-based services that allow you to sync your local
+files with copies kept in the cloud: e.g. Google Drive, DropBox, OneDrive etc.
+These services can keep a record of file versions and allow you to roll back to
+previous versions, so why not just use these?
+
+- **Answer 1:** These kinds of features tend to capture versions
+  of files as they are saved and are more geared to recovery from e.g.
+  accidental deletion or modification. It is almost certain they won't give you an
+  organised 'chunking up' of the evolution of a file. For example, perhaps you
+  are fixing a bug and end up taking a day to fix it, saving the file dozens of
+  times while you try to fix it. This will likely lead to lots of small revisions
+  to files that are ultimately unhelpful and make finding a
+  meaningful previous version of the code more difficult. Besides this, the
+  log of versions of the file(s) probably won't have any helpful description to
+  help you understand the content of each version — you'll likely only get
+  a timestamp giving when the file was last modified. With a version control
+  system, you control the snapshots of a file's history and provide helpful
+  descriptions, so that a more helpful 'story' of the file's evolution is
+  recorded.
+
+- **Answer 2**: These services offer little to help with collaboration
+  on files (except perhaps files like word processing documents, spreadsheets
+  and the like). If you want to combine edits to a file from multiple people, you
+  need to do things like agree that only one person can work on the file at
+  once, which is cumbersome. They also don't give a way for you to quickly view the
+  changes that were made to a file by someone else. Version control systems
+  address both of these shortcomings.
+
+
+### Multiple versions of files locally
+
+Have you ever created a folder of code that ends up looking something like
+this?
+
+![Versioning software with chaotic file names]({{ site.url }}/images/folder-chaos.png)
+
+Sure, you can remember which of these files you need to use as you're in the
+thick of developing your code. But what about when you come back to it a
+month later?
+
+... Or 6 months later?
+
+... Or three years from now, when you've forgotten all
+those little bits of working knowledge of the code, and you receive a question
+from someone who, having 'just a
+small query' about the validity of your findings, asks you to send them
+the code used to generate the results?
+
+Which files would you send?
+
+Wouldn't you rather turn back to that folder and find this?
+
+![A clean folder of software]({{ site.url }}/images/folder-calm.png)
+
+(Note: the `.git` folder is particular to the version control system Git,
+which you'll learn about in this course!)
+
+Even if you're much more disciplined about keeping versions of your files than
+the chaotic example above, it's worth considering the following:
+
+* Your system probably doesn't help you much when collaborating with others, like
+  when you need to merge changes from others into your code. Version control
+  systems include tools to help with this.
+
+* If you work together with others on the same files, do they follow the same
+  conventions for keeping track of versions as you? If everyone is using the
+  same version control system, then this provides consistency of approach.
+
+* Let's face it, keeping up a discipline of manually versioning your files is a
+  drag, and will likely go out the window when the pressure of a deadline starts
+  biting. Using a version control system significantly reduces the effort
+  required to keep a good, orderly record of development, and to combine your
+  work with others'. Sure, it still requires discipline to use a version control system,
+  but like all good disciplines it _helps to make your life easier_.
+  In quite a short space of time, using a version control system just becomes
+  part of your rhythm of work.
+
+
+## Note for the course
+
+In this episode we have talked about version control systems being used to
+keep track of the evolution of files in general. Going forward, we will often
+discuss the use of version control in the context of developing code for
+software, which is arguably the most
+common context in which version control systems are used.

_episodes/03_git_vs_github.md

@@ -0,0 +1,121 @@
+---
+layout: page
+title: "Git vs GitHub"
+order: 3
+session: 1
+length: 5
+toc: true
+adapted: false
+---
+
+## Learning Objectives
+
+At the end of this episode you will be able to tell your friends and colleagues
+what Git and GitHub are and describe how they are different.
+
+
+## Git: our version control system of choice
+
+In the last episode we explained what version control systems are and why they
+are useful. This course teaches you the basics of using a particular version
+control system, called
+<a href="https://git-scm.com/" target="_blank" rel="external noreferrer">Git</a>.
+
+Git is one of the most popular and relied-upon version control systems used
+today, both in research and commercially. Git is simply a piece of software that
+you run on your computer. You can use it
+directly from the command line, using the command `git`.
+
+> ### Terminals
+>
+> In this course we will work through examples with command line syntax that
+> you would find on most Unix-style systems (MacOS or Linux). If you are using
+> Windows and have followed the installation instructions, you will have
+> installed _Git for Windows_. This comes with the _Git Bash_ program, which
+> emulates a Unix Bash shell (e.g. it uses forward slashes `/` for path
+> separators and comes with common Unix programs like `ls` for listing the
+> contents of a directory). We recommend you use Git Bash to follow through the
+> course. You can launch Git Bash by opening the Start menu
+> and typing `Git Bash` to find the program.
+
+
+If you have Git installed
+on your machine, you can run it right now: open up a terminal and try running the following
+command:
+
+``` bash
+git --version
+```
+
+If you have Git installed, your output should looking something like this (your
+version number may differ):
+
+``` output
+git version 2.25.1
+```
+
+Because Git is so popular, there is a lot of software that integrates with it,
+which can lead to confusion about exactly what Git is. For example,
+you may have used programs like Visual Studio Code, RStudio or PyCharm to write
+your code. These additionally provide graphical user interfaces to help
+developers interact with Git via 'point and click' while you work on code,
+giving developers a more 'integrated' experience. But it's helpful to remember
+that these programs are just using Git under the hood and that it's perfectly
+possible to use Git without these. Indeed, it's best _not_ to rely on these
+integrated facilities for using Git, because you may well come up against
+situations in your work where you need to use Git in environments which force
+you to use it at the command line, such as remote servers.
+
+Chances are that, at some
+point, you will want to share your work, either with collaborators as the code is developed or
+in order to publicise your work. On it's own, Git doesn't provide the means to
+do this — for that, you also need somewhere to host a 'remote' version
+of your code which others can access. Many web platforms have been created to
+provide this service. They use Git as the core version control technology, while
+providing additional layers of functionality to facilitate sharing and collaboration
+with other developers. Examples of these platforms include
+<a href="https://about.gitlab.com/" target="_blank" rel="external noreferrer">GitLab</a>,
+<a href="https://codeberg.org/" target="_blank" rel="external noreferrer">Codeberg</a> and
+<a href="https://github.com/" target="_blank" rel="external noreferrer">GitHub</a>.
+It is possible to use Git completely 'locally'; that is,
+without interacting over the internet with some remote service. This is
+perfectly fine if you just want to version control your own software project
+that you have no intention of sharing with anyone. 
+
+
+## Managing collaboration with GitHub
+
+As well as teaching you the basics of using Git, this course will give you an
+introduction to using GitHub as a way of sharing your code and managing its
+development.
+
+In some ways, the naming of GitHub is unfortunate, because it could easily sound
+like it's Git but 'on the web'. But that's not really true and to think
+of it in these terms can lead to confusion, especially early on. Remember that
+_Git_ is a tool that software developers use as they write code on their machines.
+_GitHub_ is a web
+platform that makes it easy to share code and provides extra functionality to
+support teams of software developers in their collaboration. Taking an analogy
+from scientific research, Git is more
+akin to a lab book that a scientist might use day-to-day to record what they
+did that day, the results of experiments, etc., whereas GitHub sits more at the
+level of planning and project management that a Principal Investigator would do
+to ensure the project runs smoothly and everyone is kept on the same page. It
+should also be noted that GitHub is not a replacement for Git. In fact, you will
+typically interact with GitHub _via Git_ while you develop your code. 
+
+The full suite of facilities that GitHub provides is multi-faceted and it is far
+beyond the scope of this course for us to cover all of it. We will focus on
+features that support:
+
+* Sharing your code within your development team and the wider world
+
+* Ways to keep track of proposed additions or improvements to a codebase (via
+  GitHub _issues_) and to ensure significant changes to the codebase are
+  integrated in a controlled way (via GitHub _pull requests_).
+
+If you feel somewhat hazy on exactly how Git and GitHub differ, then don't worry:
+this should become clearer as we go through the course. For now, the key thing
+to bear in mind is that they play different roles: Git for day-to-day
+record-keeping while writing code, and GitHub for sharing and collaborating with
+others.