Merge pull request #262 from NBISweden/git-checkout

Use Git `switch` and `restore` instead of `checkout`

pages/course-information/pre-course-setup.md

@@ -25,8 +25,8 @@ cd workshop-reproducible-research
 
 > **Tip** <br>
 > If you want to revisit the material from an older instance of this course,
-> you can do that using `git checkout tags/<tag-name>`, e.g.
-> `git checkout tags/course_1905`. To list all available tags, use `git tag`.
+> you can do that using `git switch -d tags/<tag-name>`, e.g.
+> `git switch -d tags/course_1905`. To list all available tags, use `git tag`.
 > Run this command after you have `cd` into `workshop-reproducible-research`
 > as described above. If you do that, you probably also want to view the
 > same older version of this website. Until spring 2021, the website was
@@ -136,17 +136,6 @@ below for more information.
 > instead of using a hard-coded `master`. We at NBIS want to be a part of this
 > change, so we have chosen to use `main` for this course.
 
-> **Tip** <br>
-> If you want to revisit the material from an older instance of this course, you
-> can do that using `git checkout tags/<tag-name>`, _e.g._ `git checkout
-tags/course_1905`. To list all available tags, use `git tag`. Run this command
-> after you have `cd` into `workshop-reproducible-research` as described above.
-> If you do that, you probably also want to view the same older version of this
-> website. Until spring 2021, the website was hosted at
-> [ReadTheDocs](https://nbis-reproducible-research.readthedocs.io/en/latest/).
-> Locate the version box in the bottom right corner of the website and select
-> the corresponding version.
-
 ### GitHub setup
 
 [GitHub](https://github.com) is one of several online hosting platforms for Git

pages/git/git-3-committing-changes.md

@@ -1,29 +1,31 @@
 We will now commit the untracked files. A commit is essentially a set of
 changes to a set of files. Preferably, the changes making out a commit should
-be related to something, *e.g.* a specific bug fix or a new feature.
+be related to something, _e.g._ a specific bug fix or a new feature.
 
-* Our first commit will be to add the copied files to the repository. Run the
+## Adding and committing files
+
+- Our first commit will be to add the copied files to the repository. Run the
   following (as suggested by `git status`):
 
 ```bash
 git add Dockerfile Snakefile
 ```
 
-* Run `git status` again! See that we have added Dockerfile and Snakefile to
-  our upcoming commit (listed under "*Changes to be committed*"). This is
+- Run `git status` again! See that we have added Dockerfile and Snakefile to
+  our upcoming commit (listed under "_Changes to be committed_"). This is
   called the staging area, and the files there are staged to be committed.
 
-* We might as well commit all files in one go! Use `git add` on the remaining
+- We might as well commit all files in one go! Use `git add` on the remaining
   files as well:
 
 ```bash
 git add config.yml environment.yml
 ```
 
-* Run `git status` and see that all files are in the staging area, and that no
+- Run `git status` and see that all files are in the staging area, and that no
   files are listed as untracked.
 
-* We are now ready to commit! Run the following:
+- We are now ready to commit! Run the following:
 
 ```bash
 git commit -m "Add initial files"
@@ -37,14 +39,14 @@ what the commit contains.
 > just starting out. Here are some general guidelines that can help you write
 > good commit messages from the start:
 >
-> * Separate subject from body with a blank line
-> * Limit the subject line to 50 characters
-> * Capitalize the subject line
-> * Do not end the subject line with a period
-> * Use the [imperative mood](https://en.wikipedia.org/wiki/Imperative_mood)
+> - Separate subject from body with a blank line
+> - Limit the subject line to 50 characters
+> - Capitalize the subject line
+> - Do not end the subject line with a period
+> - Use the [imperative mood](https://en.wikipedia.org/wiki/Imperative_mood)
 >   in the subject line
-> * Wrap the body at 72 characters
-> * Use the body to explain *what* and *why* vs. *how*
+> - Wrap the body at 72 characters
+> - Use the body to explain _what_ and _why_ vs. _how_
 >
 > In the command above we just added a short subject line ("Add initial
 > files"). It is capitalized, less than 50 characters, does not end with
@@ -56,8 +58,8 @@ what the commit contains.
 > commit message and body. If you want to read more about the motivation for
 > these points, please see [this website](https://chris.beams.io/posts/git-commit/).
 
-* Run `git status` again. It should tell you *"nothing to commit, working
-  directory clean"*.
+- Run `git status` again. It should tell you _"nothing to commit, working
+  directory clean"_.
 
 What have we done, so far? We had some files in our working directory that we
 added to the Git staging area, which we subsequently committed to our Git
@@ -68,23 +70,23 @@ figure:
 
 Let's repeat this process by editing a file!
 
-* Open up `environment.yml` in your favourite editor, and change the version of
-  Bowtie2 to a different value, *e.g.* `bowtie2=2.2.4`.
+- Open up `environment.yml` in your favourite editor, and change the version of
+  Bowtie2 to a different value, _e.g._ `bowtie2=2.2.4`.
 
-* Run `git status`. It will tell you that there are modifications in one file
+- Run `git status`. It will tell you that there are modifications in one file
   (`environment.yml`) compared to the previous commit. This is nice! We don't
   have to keep track of which files we have edited, Git will do that for us.
 
-* Run `git diff environment.yml`. This will show you the changes made to the
+- Run `git diff environment.yml`. This will show you the changes made to the
   file. A `-` means a deleted line, a `+` means an added line. There are also
   shown a few lines before and after the changes, to put them in context.
 
-* Let's edit another file! Open `config.yml` and change the line `genome_id:
-  NCTC8325` to `genome_id: ST398`. Run `git status`. Run `git diff`. If we
+- Let's edit another file! Open `config.yml` and change the line `genome_id:
+NCTC8325` to `genome_id: ST398`. Run `git status`. Run `git diff`. If we
   don't specify a file, it will show all changes made in any file, compared to
   the previous commit. Do you see your changes?
 
-* Okay, we made our changes. Let's commit them! Run:
+- Okay, we made our changes. Let's commit them! Run:
 
 ```bash
 git add config.yml environment.yml
@@ -94,38 +96,37 @@ This will add both our files to the staging area at the same time. Run `git
 status` and see that the changes in both `config.yml` and `environment.yml` are
 ready to be committed.
 
+## Unstaging files
+
 But wait a minute! Shouldn't each commit optimally be a conceptual unit of
 change? Here we have one change to the genome ID used for an analysis and one
 change where another software version is specified: these should probably be
 separate. We thus want to make two commits, one for each change.
 
-* Let's remove `environment.yml` from the staging area. `git status` tells us
-  how to do this: *"(use "git reset HEAD <file>..." to unstage)"*. So run:
+- Let's remove `environment.yml` from the staging area.
 
 ```bash
-git reset HEAD environment.yml
+git restore --staged environment.yml
 ```
 
 > **Note** <br>
-> Maybe you didn't see the same message as indicated above? Is Git telling you
-> to use a `git restore` instead? This is another one of Git's newer and
-experimental commands, which aims to remove some confusion about what
-commands do what (as many have multiple functions). While we have opted to
-stick with the old and stable commands until the new commands are no longer
-considered experimental, you are very welcome to use `git restore` instead
-of `git reset` to unstage the file above!
-
-* Run `git status` again. See that now only `config.yml` is staged for being
+> Please note the use of the `--staged` flag here, which simply removes the
+> specified file(s) from the staging area without changing the file contents.
+> Using the `restore` command without this flag will not only remove the file
+> from the staging area, but _also_ restore the file to the state it was in the
+> last commit, which is not what we want here.
+
+- Run `git status` again. See that now only `config.yml` is staged for being
   committed, whereas the changes in `environment.yml` are tracked by Git, but
   not ready to be committed.
 
-* Commit the changes in `config.yml`:
+- Commit the changes in `config.yml`:
 
 ```bash
 git commit -m "Change to ST398 for alignment"
 ```
 
-* Add and commit the changes in `environment.yml`:
+- Add and commit the changes in `environment.yml`:
 
 ```bash
 git status
@@ -142,13 +143,15 @@ As you can see, each commit is a point in history. The more often you commit,
 and the more specific you keep your commits, the better (more fine-grained)
 history and version tracking you will have of your files.
 
-* We can also try to delete a file:
+## Deleting files
+
+- We can also try to delete a file:
 
 ```bash
 rm Dockerfile
 ```
 
-* Run `git status`. As you can see, Git tells us that the file is deleted, but
+- Run `git status`. As you can see, Git tells us that the file is deleted, but
   that the deletion is not committed. In the same way as we commit edits to
   files, we need to commit a deletion of a file:
 
@@ -163,26 +166,29 @@ Here we used `rm Dockerfile` to delete the file and `git add Dockerfile` to
 stage the deletion. You can also use `git rm Dockerfile` to do both these
 operations in one step.
 
-* To see a history of our changes so far, run:
+## Browsing the history
+
+- To see a history of our changes so far, run:
 
 ```bash
 git log
 ```
 
-> **Tip** <br>
-> Since Git keeps track of changes in text, *e.g.* code and text-based
-> documentation, there are some files which you should *not* commit. Examples
-> of such files are file formats that are not text-based, *e.g.* Microsoft
+> **Note** <br>
+> Since Git keeps track of changes in text, _e.g._ code and text-based
+> documentation, there are some files which you should _not_ commit. Examples
+> of such files are file formats that are not text-based, _e.g._ Microsoft
 > Word/Excel files or PDFs - although one might sometimes want to track one of
 > these files regardless, such as when you have a static PDF report you
 > received from a sequencing platform that's never going to change. Other
-> files you shouldn't track are vary large text files, *e.g.* those larger
+> files you shouldn't track are vary large text files, _e.g._ those larger
 > than 50 MB.
 
 > **Quick recap** <br>
 > We added four important Git commands to our repertoire:
 >
-> * `git add` adds a file to the staging area
-> * `git commit` commits the changes we have staged
-> * `git rm` is shorthand for `rm <file>; git add <file>`
-> * `git log` shows us the commit history
+> - `git add` adds a file to the staging area
+> - `git commit` commits the changes we have staged
+> - `git restore --staged` to remove files from the staging area
+> - `git rm` is shorthand for `rm <file>; git add <file>`
+> - `git log` shows us the commit history

pages/git/git-5-branches.md

@@ -1,6 +1,6 @@
-One of the most useful features of Git is called *branching*. Branching allows
+One of the most useful features of Git is called _branching_. Branching allows
 you to diverge from the main line of work and edit or update your code and
-files (*e.g.* to test out a new analysis or some experimental feature) without
+files (_e.g._ to test out a new analysis or some experimental feature) without
 affecting your main work. If the work you did in the branch turns out to be
 useful you can merge that back into your `main` branch. On the other hand, if
 the work didn't turn out as planned, you can simply delete the branch and
@@ -10,7 +10,7 @@ can be a way of compartmentalizing your team's work on different parts of the
 project and enables merging back into the `main` branch in a controlled
 fashion; we will learn more about this in the section about working remotely.
 
-* Let's start trying out branching! We can see the current branch by running:
+- Let's start trying out branching! We can see the current branch by running:
 
 ```bash
 git branch
@@ -23,38 +23,38 @@ This tells us that there is only the `main` branch at the moment.
 > well, but do check out the Git section of the [pre-course setup](pre-course-setup)
 > for more details about the choice of default branch names.
 
-* Let's make a new branch:
+- Let's make a new branch:
 
 ```bash
 git branch test_alignment
 ```
 
-* Run `git branch` again to see the available branches. Do you note which one
+- Run `git branch` again to see the available branches. Do you note which one
   is selected as the active branch?
 
-* Let's move to our newly created branch using the `checkout` command:
+- Let's move to our newly created branch using the `switch` command:
 
 ```bash
-git checkout test_alignment
+git switch test_alignment
 ```
 
 > **Tip** <br>
-> You can create and checkout a new branch in one line with `git checkout -b
-> branch_name`.
+> You can create and switch to a new branch in one line with `git switch -c
+branch_name` (or `--create`).
 
 Let's add some changes to our new branch! We'll use this to try out a different
 set of parameters on the sequence alignment step of the case study project.
 
-* Edit the `Snakefile` so that the shell command of the `align_to_genome` rule
+- Edit the `Snakefile` so that the shell command of the `align_to_genome` rule
   looks like this (add the `--very-sensitive-local` option):
 
 ```bash
 bowtie2 --very-sensitive-local -x results/bowtie2/{config[genome_id]} -U {input.fastq} > {output} 2>{log}
 ```
 
-* Add and commit the change!
+- Add and commit the change!
 
-* To get a visual view of your branches and commits you can use the command:
+- To get a visual view of your branches and commits you can use the command:
 
 ```bash
 git log --graph --all --oneline
@@ -76,25 +76,24 @@ This shows the difference between the active branch (`test_alignment`) and
 > displays the difference on a word-per-word basis rather than line-per-line.
 
 > **Note** <br>
-> Git is constantly evolving, along with some of its commands. While the
-> `checkout` command is quite versatile (it's used for more than just switching
-> branches), this versatility can sometimes be confusing. The Git team thus
-> added a new command, `git switch`, that can be used instead. This command is
-> still experimental, however, so we have opted to stick with `checkout` for
-> the course - for now.
+> Git is constantly evolving, along with some of its commands. The `checkout`
+> command was previously used for switching between branches, but this
+> functionality now has the dedicated (and clearer) `switch` command for this.
+> If you've previously learned using `checkout` instead you can keep doing that
+> without any issues, as the `checkout` command itself hasn't changed.
 
 Now, let's assume that we have tested our code and the alignment analysis is run
 successfully with our new parameters. We thus want to merge our work into the
 `main` branch. It is good to start with checking the differences between
 branches (as we just did) so that we know what we will merge.
 
-* Checkout the branch you want to merge into, *i.e.* `main`:
+- Switch to the branch you want to merge into, _i.e._ `main`:
 
 ```bash
-git checkout main
+git switch main
 ```
 
-* To merge, run the following code:
+- To merge, run the following code:
 
 ```bash
 git merge test_alignment
@@ -107,18 +106,18 @@ back the changes made in `test_alignment` to `main`.
 > If working on different features or parts of an analysis on different
 > branches, and at the same time maintaining a working `main` branch for the
 > stable code, it is convenient to periodically merge the changes made to
-> `main` into relevant branches (*i.e.* the opposite to what we did above).
+> `main` into relevant branches (_i.e._ the opposite to what we did above).
 > That way, you keep your experimental branches up-to-date with the newest
 > changes and make them easier to merge into `main` when time comes.
 
-* If we do not want to do more work in `test_alignment` we can delete that
+- If we do not want to do more work in `test_alignment` we can delete that
   branch:
 
 ```bash
 git branch -d test_alignment
 ```
 
-* Run `git log --graph --all --oneline` again. Note that the commits and
+- Run `git log --graph --all --oneline` again. Note that the commits and
   the graph history are still there? A branch is simply a pointer to a
   specific commit, and that pointer has been removed.
 
@@ -128,7 +127,7 @@ git branch -d test_alignment
 > collaborators. While there certainly isn't a single branching model that
 > can be considered to be the "best", it is very often most useful to keep it
 > simple. An example of a simple and functional model is to have a `main`
-> branch that is always working (*i.e.* can successfully run all your code
+> branch that is always working (_i.e._ can successfully run all your code
 > and without known bugs) and develop new code on feature branches (one new
 > feature per branch). Feature branches are short-lived, meaning that they
 > are deleted once they are merged into `main`.
@@ -138,6 +137,6 @@ git branch -d test_alignment
 > them:
 >
 > - `git branch <branch>` creates a new branch.
-> - `git checkout <branch>` moves the repository to the state in which the
+> - `git switch <branch>` moves the repository to the state in which the
 >   specified branch is currently in.
 > - `git merge <branch>` merges the specified branch into the current one.