Merge pull request #154 from ImperialCollegeLondon/fix-links-and-formatting

Various small fixes

Author: alexdewar

CODE_OF_CONDUCT.md

@@ -9,5 +9,5 @@ Instances of abusive, harassing, or otherwise unacceptable behavior
 may be reported by following our [reporting guidelines][coc-reporting].
 
 
-[coc-reporting]: https://docs.carpentries.org/topic_folders/policies/incident-reporting.html
-[coc]: https://docs.carpentries.org/topic_folders/policies/code-of-conduct.html
+[coc-reporting]: https://docs.carpentries.org/policies/coc/incident-reporting.html
+[coc]: https://docs.carpentries.org/policies/coc/

episodes/00-course_overview.md

@@ -20,16 +20,10 @@ exercises: 0
 ## Overview
 
 This course builds on the [Introduction to using Git and GitHub for software
-development][Introduction to using Git and GitHub for software development] course. While it is not a requirement to have completed the introductory
+development][intro-course] course. While it is not a requirement to have completed the introductory
 course, basic familiarity with using Git from the command line is assumed. (Don't worry
 if you're rusty!) You should also have a copy of the `recipe` repository locally. If
-not, please refer to
-
-<!-- markdownlint-disable -->
-
-[the setup instructions][lesson-setup].
-
-<!-- markdownlint-restore -->
+not, please refer to [the setup instructions](../index.md).
 
 This course introduces some of the intermediate-level functionality of Git and GitHub.
 In addition to providing you with a more thorough understanding of Git and how to use it
@@ -77,8 +71,8 @@ style.
 
 
 
-[Introduction to using Git and GitHub for software development]: https://imperialcollegelondon.github.io/rse_introductory_git_course/
-[a handout sheet]: handouts/git-course-handout.pdf
+[intro-course]: https://imperialcollegelondon.github.io/rse_introductory_git_course/
+[a handout sheet]: files/git-course-handout.pdf
 
 
 :::::::::::::::::::::::::::::::::::::::: keypoints

episodes/01-collaborating_with_git.md

@@ -26,12 +26,12 @@ Each of these examples will be shown again in a subsequent section.
 
 ### Differing Goals and Objectives
 
-Developer 1 - "I need a new type of analysis to finish my thesis"
+Developer 1 -- "I need a new type of analysis to finish my thesis"
 
-Developer 2 - "My problem is bigger. I need better performance to process all my
+Developer 2 -- "My problem is bigger. I need better performance to process all my
 data"
 
-Even when working independently you might find you need to need to work on
+Even when working independently you might find you need to work on
 different things at different times. This is greatly compounded however when you
 have multiple developers all wanting to contribute to the same Git repository.
 
@@ -44,9 +44,9 @@ about sorting out conflicts later.
 
 ### Access and Permissions
 
-Developer 1 - "Just email me your changes. I'll save them into the master copy."
+Developer 1 -- "Just email me your changes. I'll save them into the master copy."
 
-Developer 2 - "Ok... so why do all of my changes have to go through you?"
+Developer 2 -- "Ok... so why do all of my changes have to go through you?"
 
 An important practical consideration is where to store the code that you're
 collaborating on. Usually you want everyone's contributions to end up in one
@@ -60,19 +60,19 @@ within a project.
 
 ### Need to Coordinate Efforts
 
-Developer 1 - "I'm still waiting on those changes to the data analysis workflow."
+Developer 1 -- "I'm still waiting on those changes to the data analysis workflow."
 
-Developer 2 - "Huh? I added those a month ago."
+Developer 2 -- "Huh? I added those a month ago."
 
 Successfully coordinating the efforts of multiple contributors is a key
 challenge to avoid delay and duplication of work. GitHub can help here via
 **Issues** that track planned, on-going and completed work and who is doing it.
 
 ### Different Points of View
 
-Developer 1 - "Here's what I've been working on for the last month."
+Developer 1 -- "Here's what I've been working on for the last month."
 
-Developer 2 - "Hmmm... if we tweak things here then it might be faster."
+Developer 2 -- "Hmmm... if we tweak things here then it might be faster."
 
 Two heads, as they say, are better than one and writing software is no
 exception. There is no greater benefit to collaboration than being able to pick
@@ -84,19 +84,19 @@ GitHub provides functionality for peer review via **Pull Requests**.
 
 ### Individual styles and preferences
 
-Developer 1 - "Tabs!"
+Developer 1 -- "Tabs!"
 
-Developer 2 - "Spaces!"
+Developer 2 -- "Spaces!"
 
-Developer 1 - "TABS!"
+Developer 1 -- "TABS!"
 
-Developer 2 - "SPACES!"
+Developer 2 -- "SPACES!"
 
 Whilst it may seem trivial the tabs vs. spaces controversy is a long standing
 debate. A quick google search will reveal any number of discussions on the
 topic. Ultimately, it doesn't matter, but trouble can arise when everyone
 follows their own preference and you end up with a messy combination. The same
-logic applies in many places - consistency is king!
+logic applies in many places -- consistency is king!
 
 To get around these sorts of issues it's a good idea to make a choice and then
 automatically enforce it. GitHub Actions is a **Continuous Integration** system

episodes/02-branching_merging.md

@@ -28,9 +28,9 @@ exercises: 10
 
 ## Differing Goals and Objectives
 
-Developer 1 - "I need a new type of analysis to finish my thesis"
+Developer 1 -- "I need a new type of analysis to finish my thesis"
 
-Developer 2 - "My problem is bigger. I need better performance to process all my
+Developer 2 -- "My problem is bigger. I need better performance to process all my
 data"
 
 ::::::::::::::::::::::::::::::::::::::::::::::::::
@@ -69,7 +69,7 @@ version that contains all changes:
 ![Example of commit history with multiple branches and merges](fig/branching_full_example.png){alt='Git collaborative'}
 
 - We see branching points and merging points.
-- Main line development is often called `main`.
+- Mainline development is usually carried out in a branch called `main`.
 - Other than this convention there is nothing special about `main`, it is just
   a branch.
 - Commits form a directed acyclic graph (arrows point from parent commits to
@@ -228,7 +228,7 @@ As mentioned previously, one of the advantages of using branches is working on
 different features in parallel. You may have already spotted the typo in
 `ingredients.md` but let's say that we've only just seen it in the midst of
 our work on the `experiment` branch. We could correct the typo with a new commit
-in `experiment` but it doesn't fit in very well here - if we decide to discard
+in `experiment` but it doesn't fit in very well here -- if we decide to discard
 our experiment then we also lose the correction. Instead it makes much more
 sense to create a correcting commit in `main`. First, switch to the main branch:
 

episodes/04-rewriting_history.md

@@ -23,7 +23,7 @@ exercises: 15
 ## Rewriting history with Git
 
 While version control is useful to keep track of changes made to a piece of work over
-time, it also lets you to modify the timeline of commits. There are several totally
+time, it also lets you modify the timeline of commits. There are several totally
 legitimate reasons why you might want to do that, from keeping the commit history clean
 of unsuccessful attempts to do something to incorporate work done by someone else.
 
@@ -47,7 +47,8 @@ It is not rare that, while you are working on some feature, you need to check so
 else in another branch. Very often this is the case when you want to try some
 contributor's code as part of a pull request review process (see next episodes). You
 can commit the work you are doing, but if it is not in a state ready to be committed,
-what would you do? Or you start working on a branch only to realise that it is not the one that you were planning to work on?
+what would you do? Or what if you start working on a branch only to realise that it is
+not the one that you were planning to work on?
 
 `git stash` is the answer. It lets you put your current, uncommitted work aside in a
 special state, turning the working directory back to the way it was in the last commit.
@@ -57,47 +58,47 @@ nothing had happened.
 
 The following are the `git stash` commands needed to make this happen:
 
-Stash the current state of the repository, giving some message to remind yourself what
-was this about. The working directory becomes identical to the last commit.
+- Stash the current state of the repository, giving some message to remind yourself what
+  this was about. The working directory becomes identical to the last commit.
 
-```bash
-git stash save "Some informative message"
-```
+  ```bash
+  git stash save "Some informative message"
+  ```
 
-List the stashes available in reverse chronological order (last one stashed goes on
-top).
+- List the stashes available in reverse chronological order (last one stashed goes on
+  top).
 
-```bash
-git stash list
-```
+  ```bash
+  git stash list
+  ```
 
-Extract the **last stash** of the list, updating the working directory
-with its content.
+- Extract the **last stash** of the list, updating the working directory with its
+  content.
 
-```bash
-git stash pop
-```
+  ```bash
+  git stash pop
+  ```
 
-Extract the stash with the given number from the list, updating the working directory
-with its content.
+- Extract the stash with the given number from the list, updating the working directory
+  with its content.
 
-```bash
-git stash pop stash@{NUMBER}
-```
+  ```bash
+  git stash pop stash@{NUMBER}
+  ```
 
-Apply the **last stash** without removing it from the list, so you can apply it to
-other branches, if needed.
+- Apply the **last stash** without removing it from the list, so you can apply it to
+  other branches, if needed.
 
-```bash
-git stash apply
-```
+  ```bash
+  git stash apply
+  ```
 
-Apply the given stash without removing it from the list, so you can apply it to
-other branches, if needed.
+- Apply the given stash without removing it from the list, so you can apply it to
+  other branches, if needed.
 
-```bash
-git stash apply stash@{NUMBER}
-```
+  ```bash
+  git stash apply stash@{NUMBER}
+  ```
 
 If you want more information, you can [read this article on Git
 stash](https://www.atlassian.com/git/tutorials/saving-changes/git-stash).
@@ -122,7 +123,7 @@ stashes changes in either case.
 This is the simplest method of rewriting history: it lets you amend the last commit you
 made, maybe adding some files you forgot to stage or fixing a typo in the commit message.
 
-After you have made those last minute changes - and `staged` them, if needed - all you
+After you have made those last minute changes -- and `staged` them, if needed -- all you
 need to do to amend the last commit while keeping the same commit message is:
 
 ```bash
@@ -160,7 +161,7 @@ detailed description.
 :::::::::::::::::::::::::::::::::::::::  challenge
 
 For details on how to choose which text editor Git will use, see [the setup
-instructions](lesson-setup).
+instructions](../index.md).
 
 ::::::::::::::::::::::::::::::::::::::::::::::::::
 
@@ -178,7 +179,7 @@ git reset --soft HEAD^
 ```
 
 This resets the staging area to match the most recent commit, but leaves the working
-directory unchanged - so no information is lost. Now you can review the files you
+directory unchanged -- so no information is lost. Now you can review the files you
 modified, make more changes or whatever you like. When you are ready, you stage and
 commit your files, as usual. You can go back 2 commits, 3, etc with `HEAD^2`,
 `HEAD^3`... but the further you go, the more chances there are to leave commits

episodes/05-pulling_pushing.md

@@ -42,7 +42,7 @@ in sync.
   ![Push a branch without upstream yet](fig/push_u.png){alt='Git collaborative'}
 
 - `push` only operates on your current branch. If you want to push another
-  branch, you have to `checkout` that branch first.
+  branch, you have to `switch` to that branch first.
 - If the upstream branch has changes you do not have in the local branch, the
   command will fail, requesting you to pull those changes first.
 
@@ -144,7 +144,7 @@ branch 'spicy' set up to track 'origin/spicy'.
   see how your local and remote branch compare in terms of commit history.
 - It's best to make sure your repository is in a clean state with no staged or unstaged
   changes.
-- If the local and upstream branches have diverged - have different commit history - the
+- If the local and upstream branches have diverged -- have different commit history -- the
   command will attempt to merge both. If there are conflicts, you will need deal with
   them in the same way described above.
 - You can get a new branch that exists only in `origin` directly with `git switch BRANCH_NAME` which will automatically create a local branch with the same name