diff --git a/.github/workflows/README.md b/.github/workflows/README.md index d6edf88dd..7076ddd9f 100644 --- a/.github/workflows/README.md +++ b/.github/workflows/README.md @@ -2,7 +2,7 @@ This directory contains workflows to be used for Lessons using the {sandpaper} lesson infrastructure. Two of these workflows require R (`sandpaper-main.yaml` -and `pr-recieve.yaml`) and the rest are bots to handle pull request management. +and `pr-receive.yaml`) and the rest are bots to handle pull request management. These workflows will likely change as {sandpaper} evolves, so it is important to keep them up-to-date. To do this in your lesson you can do the following in your @@ -94,7 +94,7 @@ branch called `update/workflows` and a pull request is created. Maintainers are encouraged to review the changes and accept the pull request if the outputs are okay. -This update is run ~~weekly or~~ on demand. +This update is run weekly or on demand. ### 03 Maintain: Update Package Cache (update-cache.yaml) @@ -140,7 +140,7 @@ Once the checks are finished, a comment is issued to the pull request, which will allow maintainers to determine if it is safe to run the "Receive Pull Request" workflow from new contributors. -### Recieve Pull Request (pr-recieve.yaml) +### Receive Pull Request (pr-receive.yaml) **Note of caution:** This workflow runs arbitrary code by anyone who creates a pull request. GitHub has safeguarded the token used in this workflow to have no @@ -171,7 +171,7 @@ The artifacts produced are used by the next workflow. ### Comment on Pull Request (pr-comment.yaml) -This workflow is triggered if the `pr-recieve.yaml` workflow is successful. +This workflow is triggered if the `pr-receive.yaml` workflow is successful. The steps in this workflow are: 1. Test if the workflow is valid and comment the validity of the workflow to the diff --git a/.github/workflows/sandpaper-version.txt b/.github/workflows/sandpaper-version.txt index 201a22c8f..19270385e 100644 --- a/.github/workflows/sandpaper-version.txt +++ b/.github/workflows/sandpaper-version.txt @@ -1 +1 @@ -0.16.2 +0.16.5 diff --git a/episodes/01-basics.md b/episodes/01-basics.md index 91d67a467..6633f9205 100644 --- a/episodes/01-basics.md +++ b/episodes/01-basics.md @@ -38,20 +38,20 @@ 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'} +![](fig/play-changes.svg){alt='A diagram demonstrating how a single document grows as the result of sequential changes'} 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'} +![](fig/versions.svg){alt='A diagram with one source document that has been modified in two different ways to produce two different versions of the document'} 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'} +![](fig/merge.svg){alt='A diagram that shows the merging of two different document versions into one document that contains all of the changes from both versions'} 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 @@ -125,5 +125,3 @@ the same files concurrently. - Version control also allows many people to work in parallel. :::::::::::::::::::::::::::::::::::::::::::::::::: - - diff --git a/episodes/03-create.md b/episodes/03-create.md index 2dfb60f72..3cf285bc4 100644 --- a/episodes/03-create.md +++ b/episodes/03-create.md @@ -23,7 +23,7 @@ we can start using it. We will continue with the story of Wolfman and Dracula who are investigating if it is possible to send a planetary lander to Mars. -![](fig/motivatingexample.png){alt='motivatingexample'} +![](fig/motivatingexample.png){alt='The main elements of the story: Dracula, Wolfman, the Mummy, Mars, Pluto and The Moon'} [Werewolf vs dracula](https://www.deviantart.com/b-maze/art/Werewolf-vs-Dracula-124893530) by [b-maze](https://www.deviantart.com/b-maze) / [Deviant Art](https://www.deviantart.com/). [Mars](https://en.wikipedia.org/wiki/File:OSIRIS_Mars_true_color.jpg) by European Space Agency / @@ -95,8 +95,7 @@ $ git checkout -b main Switched to a new branch 'main' ``` -We can check that everything is set up correctly -by asking Git to tell us the status of our project: +We can now start using one of the most important git commands, which is particularly helpful to beginners. `git status` tells us the status of our project, and better, a list of changes in the project and options on what to do with those changes. We can use it as often as we want, whenever we want to understand what is going on. ```bash $ git status @@ -166,7 +165,7 @@ fatal: Not a git repository (or any of the parent directories): .git ## Correcting `git init` Mistakes Wolfman explains to Dracula how a nested repository is redundant and may cause confusion -down the road. Dracula would like to remove the nested repository. How can Dracula undo +down the road. Dracula would like to go back to a single git repository. How can Dracula undo his last `git init` in the `moons` subdirectory? ::::::::::::::: solution @@ -183,14 +182,14 @@ that are not tracked by Git can easily be removed like any other "ordinary" file $ rm filename ``` -Similarly a directory can be removed using `rm -r dirname` or `rm -rf dirname`. +Similarly a directory can be removed using `rm -r dirname`. If the files or folder being removed in this fashion are tracked by Git, then their removal becomes another change that we will need to track, as we will see in the next episode. ### Solution Git keeps all of its files in the `.git` directory. -To recover from this little mistake, Dracula can just remove the `.git` +To recover from this little mistake, Dracula can remove the `.git` folder in the moons subdirectory by running the following command from inside the `planets` directory: ```bash @@ -199,6 +198,7 @@ $ rm -rf moons/.git But be careful! Running this command in the wrong directory will remove the entire Git history of a project you might want to keep. +In general, deleting files and directories using `rm` from the command line cannot be reversed. Therefore, always check your current directory using the command `pwd`. @@ -213,5 +213,3 @@ Therefore, always check your current directory using the command `pwd`. - Git stores all of its repository data in the `.git` directory. :::::::::::::::::::::::::::::::::::::::::::::::::: - - diff --git a/episodes/04-changes.md b/episodes/04-changes.md index 3c06e6501..337dea69b 100644 --- a/episodes/04-changes.md +++ b/episodes/04-changes.md @@ -334,7 +334,7 @@ than you would like! :::::::::::::::::::::::::::::::::::::::::::::::::: -![](fig/git-staging-area.svg){alt='The Git Staging Area'} +![](fig/git-staging-area.svg){alt='A diagram showing how "git add" registers changes in the staging area, while "git commit" moves changes from the staging area to the repository'} Let's watch as our changes to a file move from our editor to the staging area @@ -587,7 +587,7 @@ we first need to add the changed files to the staging area (`git add`) and then commit the staged changes to the repository (`git commit`): -![](fig/git-committing.svg){alt='The Git Commit Workflow'} +![](fig/git-committing.svg){alt='A diagram showing two documents being separately staged using git add, before being combined into one commit using git commit'} ::::::::::::::::::::::::::::::::::::::: challenge @@ -791,5 +791,3 @@ $ git diff me.txt - Write a commit message that accurately describes your changes. :::::::::::::::::::::::::::::::::::::::::::::::::: - - diff --git a/episodes/05-history.md b/episodes/05-history.md index fcfbd1364..b4633ef44 100644 --- a/episodes/05-history.md +++ b/episodes/05-history.md @@ -73,7 +73,7 @@ If we want to see the differences between older commits we can use `git diff` again, but with the notation `HEAD~1`, `HEAD~2`, and so on, to refer to them: ```bash -$ git diff HEAD~3 mars.txt +$ git diff HEAD~2 mars.txt ``` ```output @@ -93,7 +93,7 @@ well as the commit message, rather than the *differences* between a commit and o working directory that we see by using `git diff`. ```bash -$ git show HEAD~3 mars.txt +$ git show HEAD~2 mars.txt ``` ```output @@ -122,7 +122,7 @@ while `HEAD~123` goes back 123 commits from where we are now. We can also refer to commits using those long strings of digits and letters -that `git log` displays. +that both `git log` and `git show` display. These are unique IDs for the changes, and "unique" really does mean unique: every change to any set of files on any computer @@ -184,7 +184,7 @@ $ git status On branch main Changes not staged for commit: (use "git add ..." to update what will be committed) - (use "git checkout -- ..." to discard changes in working directory) + (use "git restore ..." to discard changes in working directory) modified: mars.txt @@ -192,10 +192,10 @@ no changes added to commit (use "git add" and/or "git commit -a") ``` We can put things back the way they were -by using `git checkout`: +by using `git restore`: ```bash -$ git checkout HEAD mars.txt +$ git restore mars.txt $ cat mars.txt ``` @@ -206,15 +206,15 @@ But the Mummy will appreciate the lack of humidity ``` As you might guess from its name, -`git checkout` checks out (i.e., restores) an old version of a file. -In this case, -we're telling Git that we want to recover the version of the file recorded in `HEAD`, +`git restore` restores an old version of a file. +By default, +it recovers the version of the file recorded in `HEAD`, which is the last saved commit. If we want to go back even further, -we can use a commit identifier instead: +we can use a commit identifier instead, using `-s` option: ```bash -$ git checkout f22b25e mars.txt +$ git restore -s f22b25e mars.txt ``` ```bash @@ -231,61 +231,28 @@ $ git status ```output On branch main -Changes to be committed: - (use "git reset HEAD ..." to unstage) - - modified: mars.txt - -``` - -Notice that the changes are currently in the staging area. -Again, we can put things back the way they were -by using `git checkout`: - -```bash -$ git checkout HEAD mars.txt -``` - -::::::::::::::::::::::::::::::::::::::::: callout - -## Don't Lose Your HEAD +Changes not staged for commit: + (use "git add ..." to update what will be committed) + (use "git restore ..." to discard changes in working directory) + modified: mars.txt -Above we used +no changes added to commit (use "git add" and/or "git commit -a") -```bash -$ git checkout f22b25e mars.txt ``` - -to revert `mars.txt` to its state after the commit `f22b25e`. But be careful! -The command `checkout` has other important functionalities and Git will misunderstand -your intentions if you are not accurate with the typing. For example, -if you forget `mars.txt` in the previous command. +Notice that the changes are currently in the staging area. +Again, we can put things back the way they were by using `git restore`: ```bash -$ git checkout f22b25e +$ git restore mars.txt +$ cat mars.txt ``` -```error -Note: checking out 'f22b25e'. - -You are in 'detached HEAD' state. You can look around, make experimental -changes and commit them, and you can discard any commits you make in this -state without impacting any branches by performing another checkout. - -If you want to create a new branch to retain commits you create, you may -do so (now or later) by using -b with the checkout command again. Example: - - git checkout -b - -HEAD is now at f22b25e Start notes on Mars as a base +```output +Cold and dry, but everything is my favorite color +The two moons may be a problem for Wolfman +But the Mummy will appreciate the lack of humidity ``` -The "detached HEAD" is like "look, but don't touch" here, -so you shouldn't make any changes in this state. -After investigating your repo's past state, reattach your `HEAD` with `git checkout main`. - - -:::::::::::::::::::::::::::::::::::::::::::::::::: It's important to remember that we must use the commit number that identifies the state of the repository @@ -293,35 +260,15 @@ we must use the commit number that identifies the state of the repository A common mistake is to use the number of the commit in which we made the change we're trying to discard. In the example below, we want to retrieve the state from before the most -recent commit (`HEAD~1`), which is commit `f22b25e`: +recent commit (`HEAD~1`), which is commit `f22b25e`. We use the `.` to mean all files: -![](fig/git-checkout.svg){alt='Git Checkout'} +![](fig/git-restore.svg){alt='A diagram showing how git restore can be used to restore the previous version of two files'} So, to put it all together, here's how Git works in cartoon form: -![https://figshare.com/articles/How_Git_works_a_cartoon/1328266](fig/git_staging.svg) - -::::::::::::::::::::::::::::::::::::::::: callout - -## Simplifying the Common Case +![https://figshare.com/articles/How_Git_works_a_cartoon/1328266](fig/git_staging.svg){alt='A diagram showing the entire git workflow: local changes are staged using git add, applied to the local repository using git commit, and can be restored from the repository using git checkout'} -If you read the output of `git status` carefully, -you'll see that it includes this hint: - -```output -(use "git checkout -- ..." to discard changes in working directory) -``` - -As it says, -`git checkout` without a version identifier restores files to the state saved in `HEAD`. -The double dash `--` is needed to separate the names of the files being recovered -from the command itself: -without it, -Git would try to use the name of the file as the commit identifier. - - -:::::::::::::::::::::::::::::::::::::::::::::::::: The fact that files can be reverted one by one tends to change the way people organize their work. @@ -344,13 +291,13 @@ Luckily, she has been keeping track of her project's versions using Git! Which c let her recover the last committed version of her Python script called `data_cruncher.py`? -1. `$ git checkout HEAD` +1. `$ git restore` -2. `$ git checkout HEAD data_cruncher.py` +2. `$ git restore data_cruncher.py` -3. `$ git checkout HEAD~1 data_cruncher.py` +3. `$ git restore -s HEAD~1 data_cruncher.py` -4. `$ git checkout data_cruncher.py` +4. `$ git restore -s data_cruncher.py` 5. Both 2 and 4 @@ -360,7 +307,7 @@ let her recover the last committed version of her Python script called The answer is (5)-Both 2 and 4. -The `checkout` command restores files from the repository, overwriting the files in your working +The `restore` command restores files from the repository, overwriting the files in your working directory. Answers 2 and 4 both restore the *latest* version *in the repository* of the file `data_cruncher.py`. Answer 2 uses `HEAD` to indicate the *latest*, whereas answer 4 uses the unique ID of the last commit, which is what `HEAD` means. @@ -368,12 +315,8 @@ unique ID of the last commit, which is what `HEAD` means. Answer 3 gets the version of `data_cruncher.py` from the commit *before* `HEAD`, which is NOT what we wanted. -Answer 1 can be dangerous! Without a filename, `git checkout` will restore **all files** -in the current directory (and all directories below it) to their state at the commit specified. -This command will restore `data_cruncher.py` to the latest commit version, but it will also -restore *any other files that are changed* to that version, erasing any changes you may -have made to those files! -As discussed above, you are left in a *detached* `HEAD` state, and you don't want to be there. +Answer 1 results in an error. You need to specify a file to restore. If you want to restore all files +you should use `git restore .` @@ -392,7 +335,7 @@ repository gets the correct change. The command `git revert [erroneous commit ID new commit that reverses the erroneous commit. The command `git revert` is -different from `git checkout [commit ID]` because `git checkout` returns the +different from `git restore -s [commit ID] .` because `git restore` returns the files not yet committed within the local repository to a previous state, whereas `git revert` reverses changes committed to the local and project repositories. @@ -437,7 +380,7 @@ $ echo "Venus is beautiful and full of love" > venus.txt $ git add venus.txt $ echo "Venus is too hot to be suitable as a base" >> venus.txt $ git commit -m "Comment on Venus as an unsuitable base" -$ git checkout HEAD venus.txt +$ git restore venus.txt $ cat venus.txt #this will print the contents of venus.txt to the screen ``` @@ -470,7 +413,7 @@ the version of `venus.txt` committed to the repository is the one from the stagi has only one line. At this time, the working copy still has the second line (and -`git status` will show that the file is modified). However, `git checkout HEAD venus.txt` +`git status` will show that the file is modified). However, `git restore venus.txt` replaces the working copy with the most recently committed version of `venus.txt`. So, `cat venus.txt` will output @@ -501,23 +444,22 @@ and what does happen? ## Getting Rid of Staged Changes -`git checkout` can be used to restore a previous commit when unstaged changes have +`git restore` can be used to restore a previous commit when unstaged changes have been made, but will it also work for changes that have been staged but not committed? Make a change to `mars.txt`, add that change using `git add`, -then use `git checkout` to see if you can remove your change. +then use `git restore` to see if you can remove your change. ::::::::::::::: solution ## Solution -After adding a change, `git checkout` can not be used directly. +After adding a change, `git restore` can not be used directly. Let's look at the output of `git status`: ```output On branch main Changes to be committed: - (use "git reset HEAD ..." to unstage) - + (use "git restore --staged ..." to unstage) modified: mars.txt ``` @@ -526,19 +468,15 @@ Note that if you don't have the same output you may either have forgotten to change the file, or you have added it *and* committed it. -Using the command `git checkout -- mars.txt` now does not give an error, +Using the command `git restore mars.txt` now does not give an error, but it does not restore the file either. -Git helpfully tells us that we need to use `git reset` first +Git helpfully tells us that we need to use `git restore --staged` first to unstage the file: ```bash -$ git reset HEAD mars.txt +$ git restore --staged mars.txt ``` -```output -Unstaged changes after reset: -M mars.txt -``` Now, `git status` gives us: @@ -550,18 +488,18 @@ $ git status On branch main Changes not staged for commit: (use "git add ..." to update what will be committed) - (use "git checkout -- ..." to discard changes in working directory) + (use "git git restore ..." to discard changes in working directory) modified: mars.txt no changes added to commit (use "git add" and/or "git commit -a") ``` -This means we can now use `git checkout` to restore the file +This means we can now use `git restore` to restore the file to the previous commit: ```bash -$ git checkout -- mars.txt +$ git restore mars.txt $ git status ``` @@ -618,8 +556,6 @@ $ git log --patch HEAD~9 *.txt :::::::::::::::::::::::::::::::::::::::: keypoints - `git diff` displays differences between commits. -- `git checkout` recovers old versions of files. +- `git restore` recovers old versions of files. :::::::::::::::::::::::::::::::::::::::::::::::::: - - diff --git a/episodes/07-github.md b/episodes/07-github.md index eb7287669..9df4b3ab6 100644 --- a/episodes/07-github.md +++ b/episodes/07-github.md @@ -36,7 +36,7 @@ world. To this end we are going to create a *remote* repository that will be lin Log in to [GitHub](https://github.com), then click on the icon in the top right corner to create a new repository called `planets`: -![](fig/github-create-repo-01.png){alt='Creating a Repository on GitHub (Step 1)'} +![](fig/github-create-repo-01.png){alt='The first step in creating a repository on GitHub: clicking the "create new" button'} Name your repository "planets" and then click "Create Repository". @@ -45,12 +45,12 @@ Note: Since this repository will be connected to a local repository, it needs to .gitignore" and "Add a license." See the "GitHub License and README files" exercise below for a full explanation of why the repository needs to be empty. -![](fig/github-create-repo-02.png){alt='Creating a Repository on GitHub (Step 2)'} +![](fig/github-create-repo-02.png){alt='The second step in creating a repository on GitHub: filling out the new repository form to provide the repository name, and specify that neither a readme nor a license should be created'} As soon as the repository is created, GitHub displays a page with a URL and some information on how to configure your local repository: -![](fig/github-create-repo-03.png){alt='Creating a Repository on GitHub (Step 3)'} +![](fig/github-create-repo-03.png){alt='The summary page displayed by GitHub after a new repository has been created. It contains instructions for configuring the new GitHub repository as a git remote'} This effectively does the following on GitHub's servers: @@ -64,11 +64,11 @@ If you remember back to the earlier [episode](04-changes.md) where we added and committed our earlier work on `mars.txt`, we had a diagram of the local repository which looked like this: -![](fig/git-staging-area.svg){alt='The Local Repository with Git Staging Area'} +![](fig/git-staging-area.svg){alt='A diagram showing how "git add" registers changes in the staging area, while "git commit" moves changes from the staging area to the repository'} Now that we have two repositories, we need a diagram like this: -![](fig/git-freshly-made-github-repo.svg){alt='Freshly-Made GitHub Repository'} +![](fig/git-freshly-made-github-repo.svg){alt='A diagram illustrating how the GitHub "planets" repository is also a git repository like our local repository, but that it is currently empty'} Note that our local repository still contains our earlier work on `mars.txt`, but the remote repository on GitHub appears empty as it doesn't contain any files yet. @@ -80,7 +80,7 @@ GitHub repository a [remote](../learners/reference.md#remote) for the local repo The home page of the repository on GitHub includes the URL string we need to identify it: -![](fig/github-find-repo-string.png){alt='Where to Find Repository URL on GitHub'} +![](fig/github-find-repo-string.png){alt='Clicking the "Copy to Clipboard" button on GitHub to obtain the repository\'s URL'} Click on the 'SSH' link to change the [protocol](../learners/reference.md#protocol) from HTTPS to SSH. @@ -95,7 +95,7 @@ minimum level for GitHub. :::::::::::::::::::::::::::::::::::::::::::::::::: -![](fig/github-change-repo-string.png){alt='Changing the Repository URL on GitHub'} +![](fig/github-change-repo-string.png){alt='A screenshot showing that clicking on "SSH" will make GitHub provide the SSH URL for a repository instead of the HTTPS URL'} Copy that URL from the browser, go into the local `planets` repository, and run this command: @@ -199,7 +199,10 @@ Created directory '/c/Users/Vlad Dracula/.ssh'. Enter passphrase (empty for no passphrase): ``` -Now, it is prompting Dracula for a passphrase. Since he is using his lab's laptop that other people sometimes have access to, he wants to create a passphrase. Be sure to use something memorable or save your passphrase somewhere, as there is no "reset my password" option. +Now, it is prompting Dracula for a passphrase. Since he is using his lab's laptop that other people sometimes have access to, he wants to create a passphrase. +Be sure to use something memorable or save your passphrase somewhere, as there is no "reset my password" option. +Note that, when typing a passphrase on a terminal, there won't be any visual feedback of your typing. +This is normal: your passphrase will be recorded even if you see nothing changing on your screen. ```output Enter same passphrase again: @@ -364,7 +367,7 @@ to make Git default to using the terminal for usernames and passwords. Our local and remote repositories are now in this state: -![](fig/github-repo-after-first-push.svg){alt='GitHub Repository After First Push'} +![](fig/github-repo-after-first-push.svg){alt='A diagram showing how "git push origin" will push changes from the local repository to the remote, making the remote repository an exact copy of the local repository.'} ::::::::::::::::::::::::::::::::::::::::: callout @@ -551,5 +554,3 @@ create mode 100644 README.md - `git pull` copies changes from a remote repository to a local repository. :::::::::::::::::::::::::::::::::::::::::::::::::: - - diff --git a/episodes/08-collab.md b/episodes/08-collab.md index c67f9f098..efaeb0eec 100644 --- a/episodes/08-collab.md +++ b/episodes/08-collab.md @@ -39,7 +39,7 @@ The Owner needs to give the Collaborator access. In your repository page on GitH button on the right, select "Collaborators", click "Add people", and then enter your partner's username. -![](fig/github-add-collaborators.png){alt='screenshot of repository page with Settings then Collaborators selected, showing how to add Collaborators in a GitHub repository'} +![](fig/github-add-collaborators.png){alt='A screenshot of the GitHub Collaborators settings page, which is accessed by clicking "Settings" then "Collaborators"'} To accept access to the Owner's repo, the Collaborator needs to go to [https://github.com/notifications](https://github.com/notifications) @@ -65,7 +65,7 @@ If you choose to clone without the clone path you will clone inside your own planets folder! Make sure to navigate to the `Desktop` folder first. -![](fig/github-collaboration.svg){alt='After Creating Clone of Repository'} +![](fig/github-collaboration.svg){alt='A diagram showing that "git clone" can create a copy of a remote GitHub repository, allowing a second person to create their own local repository that they can make changes to.'} The Collaborator can now make a change in her clone of the Owner's repository, exactly the same way as we've been doing before: @@ -262,5 +262,3 @@ What are some of the benefits of using version control, Git and GitHub? - `git clone` copies a remote repository to create a local repository with a remote called `origin` automatically set up. :::::::::::::::::::::::::::::::::::::::::::::::::: - - diff --git a/episodes/09-conflict.md b/episodes/09-conflict.md index b1e9e0b3d..ecaad1ac6 100644 --- a/episodes/09-conflict.md +++ b/episodes/09-conflict.md @@ -125,7 +125,7 @@ hint: (e.g., 'git pull ...') before pushing again. hint: See the 'Note about fast-forwards' in 'git push --help' for details. ``` -![](fig/conflict.svg){alt='The Conflicting Changes'} +![](fig/conflict.svg){alt='A diagram showing a conflict that might occur when two sets of independent changes are merged'} Git rejects the push because it detects that the remote repository has new updates that have not been incorporated into the local branch. @@ -502,11 +502,11 @@ started. | order | action . . . . . . . . . . | command . . . . . . . . . . | | ----- | -------------------------- | --------------------------------------------- | | 1 | | | -| 2 | | `echo 100 >> numbers.txt` | +| 2 | | `echo 100 >> numbers.txt` | | 3 | | | | 4 | | | | 5 | | | -| 6 | Celebrate! | `AFK` | +| 6 | Celebrate! | | ::::::::::::::: solution @@ -514,12 +514,12 @@ started. | order | action . . . . . . | command . . . . . . . . . . . . . . . . . . . | | ----- | -------------------------- | --------------------------------------------- | -| 1 | Update local | `git pull origin main` | -| 2 | Make changes | `echo 100 >> numbers.txt` | -| 3 | Stage changes | `git add numbers.txt` | -| 4 | Commit changes | `git commit -m "Add 100 to numbers.txt"` | -| 5 | Update remote | `git push origin main` | -| 6 | Celebrate! | `AFK` | +| 1 | Update local | `git pull origin main` | +| 2 | Make changes | `echo 100 >> numbers.txt` | +| 3 | Stage changes | `git add numbers.txt` | +| 4 | Commit changes | `git commit -m "Add 100 to numbers.txt"` | +| 5 | Update remote | `git push origin main` | +| 6 | Celebrate! | | ::::::::::::::::::::::::: @@ -531,5 +531,3 @@ started. - The version control system does not allow people to overwrite each other's changes blindly, but highlights conflicts so that they can be resolved. :::::::::::::::::::::::::::::::::::::::::::::::::: - - diff --git a/episodes/12-citation.md b/episodes/12-citation.md index fa3bd229a..ed2b75bee 100644 --- a/episodes/12-citation.md +++ b/episodes/12-citation.md @@ -23,30 +23,18 @@ Carpentry](https://github.com/swcarpentry/website/blob/gh-pages/CITATION) states: ```source -To reference Software Carpentry in publications, please cite both of the following: +To reference Software Carpentry in publications, please cite: -Greg Wilson: "Software Carpentry: Getting Scientists to Write Better -Code by Making Them More Productive". Computing in Science & -Engineering, Nov-Dec 2006. +Greg Wilson: "Software Carpentry: Lessons Learned". F1000Research, +2016, 3:62 (doi: 10.12688/f1000research.3-62.v2). -Greg Wilson: "Software Carpentry: Lessons Learned". arXiv:1307.5448, -July 2013. - -@article{wilson-software-carpentry-2006, - author = {Greg Wilson}, - title = {Software Carpentry: Getting Scientists to Write Better Code by Making Them More Productive}, - journal = {Computing in Science \& Engineering}, - month = {November--December}, - year = {2006}, -} - -@online{wilson-software-carpentry-2013, +@online{wilson-software-carpentry-2016, author = {Greg Wilson}, title = {Software Carpentry: Lessons Learned}, - version = {1}, - date = {2013-07-20}, - eprinttype = {arxiv}, - eprint = {1307.5448} + version = {2}, + date = {2016-01-28}, + url = {http://f1000research.com/articles/3-62/v2}, + doi = {10.12688/f1000research.3-62.v2} } ``` diff --git a/episodes/13-hosting.md b/episodes/13-hosting.md index f17d34f55..80c2a7ba2 100644 --- a/episodes/13-hosting.md +++ b/episodes/13-hosting.md @@ -16,7 +16,8 @@ exercises: 0 :::::::::::::::::::::::::::::::::::::::::::::::::: -The second big question for groups that want to open up their work is where to +After [choosing a license](11-licensing.md), +another big question for groups that want to open up their work is where to host their code and data. One option is for the lab, the department, or the university to provide a server, manage accounts and backups, and so on. The main benefit of this is that it clarifies who owns what, which is particularly diff --git a/episodes/14-supplemental-rstudio.md b/episodes/14-supplemental-rstudio.md index c1f5d72ab..24ced1988 100644 --- a/episodes/14-supplemental-rstudio.md +++ b/episodes/14-supplemental-rstudio.md @@ -82,7 +82,7 @@ to accept the Xcode license if you are using macOS. Next, RStudio will ask which existing directory we want to use. Click "Browse..." and navigate to the correct directory, then click "Create Project": -![](fig/RStudio_screenshot_navigateexisting.png) +![](fig/RStudio_screenshot_navigateexisting.png){alt='RStudio window showing the "Create Project From Existing Directory" dialog. In the dialog, the project working directory has been set to "~/Desktop/planets"'} Ta-da! We have created a new project in RStudio within the existing planets repository. Notice the vertical "Git" menu in the menu bar. RStudio has @@ -95,12 +95,12 @@ To edit the existing files in the repository, we can click on them in the "Files" panel on the lower right. Now let's add some additional information about Pluto: -![](fig/RStudio_screenshot_editfiles.png) +![](fig/RStudio_screenshot_editfiles.png){alt='RStudio window demonstrating the use of the editor panel to modify the "pluto.txt" file'} Once we have saved our edited files, we can use RStudio to commit the changes by clicking on "Commit..." in the Git menu: -![](fig/RStudio_screenshot_commit.png){alt='RStudio screenshot showing the Git menu dropdown with "Commit..." selected'} +![](fig/RStudio_screenshot_commit.png){alt='RStudio screenshot showing the Git menu dropdown with the "Commit..." option selected'} This will open a dialogue where we can select which files to commit (by checking the appropriate boxes in the "Staged" column), and enter a commit @@ -109,13 +109,13 @@ the current status of each file. Clicking on a file shows information about changes in the lower panel (using output of `git diff`). Once everything is the way we want it, we click "Commit": -![](fig/RStudio_screenshot_review.png) +![](fig/RStudio_screenshot_review.png){alt='RStudio screenshow showing the "Review Changes" dialog. The top left panel shows the list of files that can be included or excluded from the commit. The top right panel is for writing a commit message. The bottom panel shows information about the currently selected file in the top left panel.'} The changes can be pushed by selecting "Push Branch" from the Git menu. There are also options to pull from the remote repository, and to view the commit history: -![](fig/RStudio_screenshot_history.png){alt='RStudio screenshot showing the git menu dropdown with "History" selected'} +![](fig/RStudio_screenshot_history.png){alt='RStudio screenshot showing the git menu dropdown with the "History" option selected'} ::::::::::::::::::::::::::::::::::::::::: callout @@ -131,7 +131,7 @@ terminal to the repository and enter the command: `git push -u origin main`. The If we click on "History", we can see a graphical version of what `git log` would tell us: -![](fig/RStudio_screenshot_viewhistory.png) +![](fig/RStudio_screenshot_viewhistory.png){alt='RStudio screenshot showing the "Review Changes" dialog after pressing the "History" button. The top panel lists the commits in the repository, similar to git log. The bottom panel shows the changes included in the commit that has been selected in the top panel.'} RStudio creates a number of files that it uses to keep track of a project. We often don't want to track these, in which case we add them to our `.gitignore` @@ -188,5 +188,3 @@ enough to get you started! - Using RStudio's Git integration allows you to version control a project over time. :::::::::::::::::::::::::::::::::::::::::::::::::: - - diff --git a/episodes/fig/git-checkout.svg b/episodes/fig/git-restore.svg similarity index 95% rename from episodes/fig/git-checkout.svg rename to episodes/fig/git-restore.svg index fe5599d4f..615ca07b2 100644 --- a/episodes/fig/git-checkout.svg +++ b/episodes/fig/git-restore.svg @@ -103,7 +103,7 @@ - git checkout HEAD~1or git checkout f22b25e + git restore -s HEAD~1 .or git restore -s f22b25e . repository diff --git a/episodes/fig/git_staging.svg b/episodes/fig/git_staging.svg index dd59510bd..3db5b3b5a 100644 --- a/episodes/fig/git_staging.svg +++ b/episodes/fig/git_staging.svg @@ -546,7 +546,7 @@ x="0" y="0" sodipodi:role="line" - id="tspan300">git checkout HEAD file1.txt + id="tspan300">git restore file1.txt