diff --git a/config.yaml b/config.yaml index 9a513aed03..ee438dd0d7 100644 --- a/config.yaml +++ b/config.yaml @@ -8,10 +8,10 @@ # lc: Library Carpentry # cp: Carpentries (to use for instructor training for instance) # incubator: The Carpentries Incubator -carpentry: 'swc' +carpentry: 'incubator' # Overall title for pages. -title: 'Version Control with Git' +title: 'Version Control with Git in Rstudio' # Date the lesson was created (YYYY-MM-DD, this is empty by default) created: '2014-12-04' @@ -21,19 +21,19 @@ keywords: 'software, data, lesson, The Carpentries' # Life cycle stage of the lesson # possible values: pre-alpha, alpha, beta, stable -life_cycle: 'stable' +life_cycle: 'alpha' # License of the lesson materials (recommended CC-BY 4.0) license: 'CC-BY 4.0' # Link to the source repository for this lesson -source: 'https://github.com/swcarpentry/git-novice' +source: 'https://github.com/epiverse-trace/git-rstudio-basics' # Default branch of your lesson branch: 'main' # Who to contact if there are any issues -contact: 'team@carpentries.org' +contact: 'andree.valle-campos@lshtm.ac.uk' # Navigation ------------------------------------------------ # @@ -58,7 +58,7 @@ contact: 'team@carpentries.org' # - another-learner.md # Order of episodes in your lesson -episodes: +episodes: - 01-basics.md - 02-setup.md - 03-create.md @@ -68,20 +68,21 @@ episodes: - 07-github.md - 08-collab.md - 09-conflict.md +- 15-wrapup.md +- 14-supplemental-rstudio.md - 10-open.md - 11-licensing.md - 12-citation.md - 13-hosting.md -- 14-supplemental-rstudio.md # Information for Learners -learners: +learners: # Information for Instructors -instructors: +instructors: # Learner Profiles -profiles: +profiles: # Customisation --------------------------------------------- # @@ -89,6 +90,6 @@ profiles: # sandpaper and varnish versions) should live varnish: epiverse-trace/varnish@epiversetheme -url: 'https://swcarpentry.github.io/git-novice' -analytics: carpentries -lang: en +# url: 'https://swcarpentry.github.io/git-novice' +# analytics: carpentries +# lang: en diff --git a/episodes/01-basics.md b/episodes/01-basics.md index 8dc65711f2..15578a79c3 100644 --- a/episodes/01-basics.md +++ b/episodes/01-basics.md @@ -1,7 +1,7 @@ --- title: Automated Version Control -teaching: 5 -exercises: 0 +teaching: 15 +exercises: 10 --- ::::::::::::::::::::::::::::::::::::::: objectives @@ -17,20 +17,60 @@ exercises: 0 :::::::::::::::::::::::::::::::::::::::::::::::::: -We'll start by exploring how version control can be used -to keep track of what one person did and when. +## Tracking changes + +We'll start by exploring how we are usually introduced to version control 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: +version control may have look like this situation: + +![Tracking changes for the `manuscript.docx` file.](fig/git-manual-version-system.png){alt='One same files called manuscript with modification dates as prefix and what a person did as sufix.'} + +We all started by replicating the Version control system of our initial community. We all need to differentiate files from previous versions or different colleagues (supervisors or reviewers). For those reasons, we tag each version to track what one person did (e.g., with a suffix) or when (e.g., with a prefix). + +Does it seem unnecessary to you to have multiple nearly identical versions of the same document? Possibly yes. But this Version control system opens the possibility of returning to a specific version in case you erased something that you think now is essential. + +::::::::::::::::: discussion + +### File names to track changes + +Write down: + +- Is there any file naming convention that is familiar to you? -!["notFinal.doc" by Jorge Cham, ](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"'} +- What was the version control system that you first used? -We've all been in this situation before: it seems unnecessary to have -multiple nearly-identical versions of the same document. Some word +- Share with us your favorite prefix or suffix! + +::::::::::::::::::::::::::::: + +::::::::::::::::::: instructor + +We can use the comments or live participation as ice-breaker. + +:::::::::::::::::::::::::::::: + +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). +LibreOffice's [Recording and Displaying Changes](https://help.libreoffice.org/Common/Recording_and_Displaying_Changes). Let's illustrate how Google Docs works. + +![Tracking changes for the `git-test` file.](fig/gdocs-01.png) + +To use Google Docs version history click `File` > `Version history` > `See version history`. This highlights the new content added to the file in that version only. + +![The most recent version of the `git-test` file is called "third version".](fig/gdocs-03.png) + +We can move to any previous version tagged with two metadata values: the modification date and the name of the author. + +![We can view the "first version" of the file `git-test`. We can also restore it with the `Restore this version` button.](fig/gdocs-04.png) + +Google Docs’ version history tool is an automatic Version control system for single Word/Doc files that works online. + +![The Turing Way project illustration by Scriberia. Used under a CC-BY 4.0 licence. DOI: .](fig/ProjectHistory.jpg) + +## Version control systems Version control systems start with a base version of the document and then record changes you make each step of the way. You can @@ -42,26 +82,34 @@ more recent version. 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'} +resulting in different versions of that document. 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 +effectively creating different versions of our files. + + + +::::::::::::::::: checklist + +### Checklist + +Key characteristics of Version control systems are: + +1. Keep the entire history of a file and inspect a file throughout its lifetime. -::::::::::::::::::::::::::::::::::::::::: callout +2. Tag a particular version so you can return to them easily. + +::::::::::::::::::::::::::: + +::::::::::::::::::::::::::::::::::::::::: instructor ## The Long History of Version Control Systems @@ -95,33 +143,71 @@ the same files concurrently. ## 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. - - +- 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 [this popular PhD Comics cartoon](https://phdcomics.com/comics/archive.php?comicid=1531). + +- 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. Remember this for the collaboration episode! ::::::::::::::::::::::::: :::::::::::::::::::::::::::::::::::::::::::::::::: +## Version control and R files + +For code-like files like `.R` and `.Rmd` files, we can not use Google docs. The software and strategy to track changes in a project depends on the **file type**. + +- Google Docs’ version history tool is a Version control software optimized for single [non-plain text files](https://github.com/epiverse-trace/git-rstudio-basics/discussions/11) like Word/Doc files that works online. + +- `Git` is the Version control software optimized for [plain text files](https://en.wikipedia.org/wiki/Plain_text) that works offline. (Read: “What Not to Put Under Version Control” at [G. Wilson et al. 2017](https://journals.plos.org/ploscompbiol/article?id=10.1371/journal.pcbi.1005510#sec014)) + +Plain text files can be text, code, and data. Example for each of these are Markdown files (`.md`), R files (`.R`), and `.csv` or `.tsv` files, respectively. + +![Examples of non-plain and plain text files.](fig/plain-text-files.png) + +::::::::::::::::: callout + +We can use `Git` to track changes of these plain text files. However, for [plain text data files](https://www.r4epi.com/importing-plain-text-files.html) (like `.csv` and `.tsv`) we prefer different version control systems. + +::::::::::::::::::::::::: + +Plain text files like Markdown files (`.md`) and R files (`.R`) are integrated in Rmarkdown files (`.Rmd`) to generate manuscripts, websites, and R packages. These three products are outputs of **Open Science** projects, that leads to *Reproducible research* and *Sustainable software*. + + +![We can increase the reproducibility of our Open science projects with version control sytems like `Git`. Text and final results can be connected and executable by Data and code. From: "Ciencia reproducible: qué, por qué, cómo" ](fig/gradient-reproducibility.png) + +::::::::::::::::::: instructor + +### Concept map + +![Concept map for automatic version control.](fig/git-concept-03.drawio.png) + +:::::::::::::::::::::::::::::: + +::::::::::::::::: discussion + +### Exercise! + +Tell us about your Open Science project and its file types! + +- Briefly share about one Open Science project in which they are involved or would like to start soon (e.g. thesis, current project, or work); +- Identify the most relevant file types (`.pdf`, `.jpge`, `.csv`, `.xlsx`, `.R`, `.docx`, `.Rmd`) involved in it and classify them as non-plain or plain text files; +- Discuss which ones can use a Version control software like Git? + +:::::::::::::::::::::::::::: + +::::::::::::::::::: instructor + +This exercise can be solved in the shared document of the training. + +:::::::::::::::::::::::::::::: + :::::::::::::::::::::::::::::::::::::::: keypoints -- Version control is like an unlimited 'undo'. +- Version control record changes you make "step-by-step". +- `Git` is a Version control software optimized for plain text files, like `.R` and `.Rmd` files. + + :::::::::::::::::::::::::::::::::::::::::::::::::: diff --git a/episodes/02-setup.md b/episodes/02-setup.md index cb0b915956..dd7d6fdda9 100644 --- a/episodes/02-setup.md +++ b/episodes/02-setup.md @@ -1,39 +1,93 @@ --- title: Setting Up Git -teaching: 5 +teaching: 10 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? +- How do I set up Git? +- What is a token? +- What is a `commit`? +- What is a `repository`? +- What is a `branch`? :::::::::::::::::::::::::::::::::::::::::::::::::: +## The `Git` workflow + +A version control system is a tool that keeps track of these changes for us, effectively creating different versions of our files. Each record of these changes is called a [commit](../learners/reference.md#commit). Each keeps useful metadata about them. Instead of _saving copies_ with different file names, we are _making commits_ in the same file. Consecutive commits generate a linear history of changes. + +![Each record of changes is +called a `commit`.](fig/git-commit.png){alt='Changes Are Saved Sequentially'} + +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. + +Before creating our first repository, we need to setup Git. So, let's open Rstudio and introduce yourself to Git! + + + +::::::::::::::::::: prereq + +### The Rstudio Console + +In this episode, we are going to use the [Rstudio Console](https://docs.posit.co/ide/user/ide/guide/code/console.html). + +![Visual appearance of the Console.](fig/rstudio-tab-console.png) + +:::::::::::::::::::::::::: + +## Set up `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: +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). +You can set your Git user name and email from within R using the `{usethis}` package. + +Using the [Rstudio Console](https://docs.posit.co/ide/user/ide/guide/code/console.html), here is how Dracula sets up his new laptop: + +```r +# install if needed (do this exactly once): +# install.packages("usethis") + +usethis::use_git_config( + user.name = "Vlad Dracula", + user.email = "vlad@tran.sylvan.ia", + github.user = "vlad") +``` + +Substitute this chunk with your name and __the email associated with your GitHub account__. + + + 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/), @@ -53,6 +107,8 @@ If you elect to use a private email address with GitHub, then use that same emai :::::::::::::::::::::::::::::::::::::::::::::::::: + + + + +## Set up your GitHub token + +To interact with GitHub we need to include credentials in the request. We are going to configure one type of credential called _Personal Access Token (PAT)_. We need this to prove that we are a specific GitHub user, allowed to do whatever we’re asking to do. ([Bryan, 2021](https://happygitwithr.com/https-pat.html)) + +__First, let's create your token.__ + +Do this with `usethis::create_github_token()`. This function should redirect you to GitHub on your browser. Once there, check all the options in the figure below. + +```r +usethis::create_github_token() +``` + +Describe the token use case. + +Look over the scopes; the recommended scopes to select are “repo”, “workflow”, and “user”. When using `usethis::create_github_token()` will pre-select all the recommended scopes for you! + + Click “Generate token”. + +![Visual display with the recommended scopes selected. Optional scopes are "gist" and "delete_repo" to create a [gist](https://docs.github.com/en/get-started/writing-on-github/editing-and-sharing-content-with-gists/creating-gists) and delete repositories.](fig/git-token.png) + +Copy your token. Save it for the next step. + +::::::::::::::::: callout + +Briefly: +- `"repo"` will give you control of your _private_ repositories online (YES! you can have private repos!). +- `"workflow"` will allow you to run _automated_ processes for your repository online (This is advanced! so let's get back to this after the episode on GitHub). +- `"user"` will allow you to update your user data (as in the first step here). + +::::::::::::::::::::::::: + + + +__Second, let's configure your token.__ + +To complete the configuration of your token use `gitcreds::gitcreds_set()` ([Bryan, 2021](https://happygitwithr.com/https-pat.html)), then accept that you want to `Replace these credentials`. Write the corresponding number and press ENTER. + +```r +gitcreds::gitcreds_set() +``` + +```output +-> What would you like to do? + +1: Abort update with error, and keep the existing credentials +2: Replace these credentials +3: See the password / token + +Selection: 2 + +``` + +Paste your `token` to save it and complete this step. + +__Lastly, let's confirm your setting.__ + +Run: + +```r +usethis::git_sitrep() +``` + +In the `── Git global (user)` section, the two first lines of the output should look like this: + +```output +── Git global (user) +• Name: 'Vlad Dracula' +• Email: 'vlad@tran.sylvan.ia' +``` + +In the `── GitHub user` section, the three first lines of the output should look like this: + +```output +── GitHub user +• Default GitHub host: 'https://github.com' +• Personal access token for 'https://github.com': '' +• GitHub user: 'vlad' +``` + + + +You should recognize your: + +- Name, +- GitHub login, and +- Token. + + +## Set up a default `branch` name + +As we mentioned before, the complete history of `commits` for a particular project and their metadata make up a `repository`. (We are going to create one in the next episode!) + +A [`branch`](https://glosario.carpentries.org/en/#git_branch) is a snapshot of a version of a repository. In that sense, a repository can have more than one branch. WHAT?!! How is that possible? We are going to see that in coming episodes! + +![Version history within a single branch.](fig/main-branch.png) + 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. +Run the code chunk below: + +```r +usethis::git_default_branch_configure(name = "main") +``` + +To confirm this setting, run: + +```r +usethis::git_sitrep() +``` + +In the `── Git local (project)` section, almost at the end of the message, the third line of the output should say `Default branch: 'main'`: + +```ouput +── Git local (project) +• Name: 'Vlad Dracula' +• Email: 'vlad@tran.sylvan.ia' +• Default branch: 'main' +``` + + + + + +::::::::::::::::::::::::::::::::::::::::: instructor ## Default Git branch naming @@ -148,10 +359,18 @@ 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. +::::::::::::::::: checklist + +### Checklist + +We need to run these commands __only once__! Git will use this settings for every project, in your user account, on this computer. + +::::::::::::::::::::::::::: + + + And if necessary, change your configuration using the -same commands to choose another editor or update your email address. +same commands to update your email address. This can be done as many times as you want. + + + + +::::::::::::::::: instructor + +When using `usethis::git_sitrep()`, check if there is no `✖ ...` line in the output with an error message. + +Some common errors are solved here: + +- [Happy Git with R ebook](https://happygitwithr.com/https-pat.html#pat-troubleshooting) +- [Workbench documentation](https://carpentries.github.io/sandpaper-docs/github-pat.html#common-token-errors) +::::::::::::::::::::::::: + +::::::::::::::::: callout + +When using the [Terminal](https://glosario.carpentries.org/en/#console), this step is known as `git config` with the `--global` option. In the next chapter we are going to interact with the Terminal! + +::::::::::::::::::::::::: + + + +[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. +- Use the `{usethis}` package to configure a user name, email address, and other preferences once per machine. +- Use `usethis::use_git_config()` to configure Git in Rstudio. +- Use `usethis::git_default_branch_configure()` to define the default branch name. +- Use `usethis::git_sitrep()` to verify your configuration. :::::::::::::::::::::::::::::::::::::::::::::::::: diff --git a/episodes/03-create.md b/episodes/03-create.md index 2dfb60f72e..07d71db009 100644 --- a/episodes/03-create.md +++ b/episodes/03-create.md @@ -1,7 +1,7 @@ --- title: Creating a Repository -teaching: 10 -exercises: 0 +teaching: 15 +exercises: 10 --- ::::::::::::::::::::::::::::::::::::::: objectives @@ -17,12 +17,40 @@ exercises: 0 :::::::::::::::::::::::::::::::::::::::::::::::::: +## The `Git` jargon + +`Git` is a topic that contains a lot of words to do version control. + +![Word cloud for Git from ](fig/topic-git.png) + +We will locate them using this workflow bellow as template. We will relate Version control _actions_ that we can perform with specific _`git verb` commands_. These verbs will record your changes between `Git` _spaces_ associated to your folder. + +![Workflow will show actions, `git verb` commands, and spaces.](fig/cut-git-verb_map-00.png) + +In this episode, we are going to learn how to initialize Git to create a Local Repository in our folder, also known as Working directory or Workspace. + +![Initialize a Local Repository in your Workspace with the `git init` command verb](fig/cut-git-verb_map-01.png) + +Let's start with a new R project in Rstudio. + +::::::::::::::::: prereq + +### PREREQUISITES + +To start, you need to be out of any R project. In Rstudio, close you Project from `File` > `Close Project`. You can confirm this in the upper right corner `Project: (None)`. + +:::::::::::::::::::::::: + +## Create a local repository + Once Git is configured, 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. +We will continue with the story of Wolfman and Dracula who are investigating a disease outbreak and build a situational report. + +![Image by Bing, 2023, [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/), created with [Bing Image Creator powered by DALL·E 3](https://www.bing.com/create)](fig/wolfman_dracula-02.jpg){alt='wolfman and dracula using computers for data analysis'} + -First, let's create a new directory in the `Desktop` folder for our work and then change the current working directory to the newly created one: +First, let's create a new project folder for our work. Create a new project as you like. Here we are going to use functions from the `{usethis}` package. +If using RStudio desktop, the project is opened in a new session. Otherwise, the working directory and active project is changed: + +```r +usethis::create_project(path = "cases") +``` + +```output +✔ Creating 'cases/' +✔ Setting active project to 'C:/~/cases' +✔ Creating 'R/' +✔ Writing 'cases.Rproj' +✔ Adding '.Rproj.user' to '.gitignore' +✔ Opening 'C:/~/cases/' in new RStudio session +✔ Setting active project to '' +``` + + -Then we tell Git to make `planets` a [repository](../learners/reference.md#repository) +Then we tell Git to make `cases` a [repository](../learners/reference.md#repository) \-- a place where Git can store versions of our files: +```r +usethis::use_git() +``` + +```output +✔ Setting active project to 'C:/~/cases' +✔ Initialising Git repo +✔ Adding '.Rhistory', '.Rdata', '.httr-oauth', '.DS_Store', '.quarto' to '.gitignore' +There are 2 uncommitted files: +* '.gitignore' +* 'cases.Rproj' +Is it ok to commit them? +``` + +Remember that each record of change can be [commit](../learners/reference.md#commit). So, you can make these two files, `.gitignore` and `cases.Rproj`, part of it. Select that Yes, you agree! + +```output +✔ Adding files +✔ Making a commit with message 'Initial commit' +• A restart of RStudio is required to activate the Git pane +Restart now? +``` + +Agree to restart your session to activate the Git pane in Rstudio: + +![The Git tab in the Environments pane shows the `status` of your repository.](fig/pane-git-01.png) + +The Git tab is in the [Environments pane](https://docs.posit.co/ide/user/ide/guide/ui/ui-panes.html), usually in the upper right corner of the Rstudio IDE. + +In this and next episodes you'll learn the function of all those buttons on the top of the Git tab! + + -It is important to note that `git init` will create a repository that +It is important to note that `usethis::use_git()` will create a repository that can include subdirectories and their files---there is no need to create -separate repositories nested within the `planets` repository, whether +separate repositories nested within the `cases` repository, whether subdirectories are present from the beginning or added later. Also, note -that the creation of the `planets` directory and its initialization as a +that the creation of the `cases` directory and its initialization as a repository are completely separate processes. -If we use `ls` to show the directory's contents, -it appears that nothing has changed: +This step is known as `git init` because it initialise your Git repository. + +::::::::::::::::: checklist + +### Checklist + +![Set up `Git` once per computer. Initialize `Git` once per project.](fig/git-rstudio-06.png) + +::::::::::::::::::::::::::: + +## Find the new files of a local repository + +If we look at the [Files tab in the Output pane](https://docs.posit.co/ide/user/ide/guide/ui/ui-panes.html) to show the directory's contents, it appears that nothing has changed. + +But under the "cogwheel" button we get access to the "More file commands". Click to the `Show hidden files` to show everything. We can see that Git has created a hidden directory within `cases` called `.git`: + +![Show hidden files in an Local repository.](fig/git-rstudio-07.png) + +The `.git` file gives the identity to the `.git` repository also known as the Local Repository “Local Repo”. + +![The `.git` folder is a hidden folder in a Local repository.](fig/git-rstudio-08.png) + +Git uses this special subdirectory to store all the information about the project, +including the tracked files and sub-directories located within the project's directory. +If we ever delete the `.git` subdirectory, +we will lose the project's history. + +::::::::::::::::: prereq + +### From the Console to the Terminal + +Now, we are going to use the [Rstudio Terminal](https://docs.posit.co/ide/user/ide/guide/tools/terminal.html). The Terminal tab is next to the Console tab. + +Click on the Terminal tab and a new terminal session will be created (if there isn’t one already). + +![Visual appearance of the Terminal.](fig/rstudio-tab-terminal.png) + +:::::::::::::::::::::::: + +Alternatively, in the Rstudio Terminal, +with the `ls -a` command we can see the _hidden directory_ called `.git/`: ```bash -$ ls +$ ls -a +``` + +```output +./ .git/ .Rhistory cases.Rproj +../ .gitignore .Rproj.user/ R/ ``` -But if we add the `-a` flag to show everything, -we can see that Git has created a hidden directory within `planets` called `.git`: +::::::::::::::::: callout + +### Important! + +The __`.git` directory__ is the _Local Repository_. This is the one of the `Git` _spaces_ we talk about in the introduction of this episode! + +Git stores all of its repository data (and your coming changes!) in the `.git` directory. + +![Initialize a Local Repository in your Workspace with the `git init` command verb](fig/cut-git-verb_map-01.png) + +::::::::::::::::::::::::: + + -Git uses this special subdirectory to store all the information about the project, -including the tracked files and sub-directories located within the project's directory. -If we ever delete the `.git` subdirectory, -we will lose the project's history. - + + +## Check the status -We can check that everything is set up correctly -by asking Git to tell us the status of our project: +To interact with Git, we can also use the [Rstudio Terminal](https://docs.posit.co/ide/user/ide/guide/tools/terminal.html). + +In the RStudio Terminal, we can check that everything is set up correctly +by asking Git to tell us the `git status` of our project: ```bash $ git status @@ -105,45 +246,76 @@ $ git status ```output On branch main -No commits yet - -nothing to commit (create/copy files and use "git add" to track) +nothing to commit, working tree clean ``` If you are using a different version of `git`, the exact wording of the output might be slightly different. +::::::::::::::::: checklist + +### Checklist + +![Use the `git init` command to initialize a Local Repository in your Workspace. Use `git status` to check the status of the repository.](fig/cut-git-verb_map-02.png) + +::::::::::::::::::::::::::: + +The steps done with `{usethis}` can also be done with commands in the Terminal. For example, instead of `usethis::use_git()` in the Console you can use `git init` in the Terminal. However, we prefer using the first one given their explicit messages, interactivity, and warnings to prevent errors! + +::::::::::::::::: spoiler + +### How to ask Git for help? + +`Git` has a verb command similar to the `help()` function in `R`. + +Always remember that if you forget the subcommands or options of a `git` command, you can access the relevant list of options typing `git -h` or access the corresponding Git manual by typing +`git --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 Q 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 +``` + +For complementary resources, refer to the [Git Cheatsheets for Quick Reference](../learners/reference.md) inside this tutorial website. + +::::::::::::::::::::::::: + ::::::::::::::::::::::::::::::::::::::: challenge ## Places to Create Git Repositories -Along with tracking information about planets (the project we have already created), -Dracula would also like to track information about moons. -Despite Wolfman's concerns, Dracula creates a `moons` project inside his `planets` -project with the following sequence of commands: +Along with tracking information about cases (the project we have already created), +Dracula would also like to track information about interventions. +Despite Wolfman's concerns, Dracula creates a `interventions` project inside his `cases` +project. Additionally, Dracula uses a sequence of commands __in the Rstudio Terminal__: ```bash -$ cd ~/Desktop # return to Desktop directory -$ cd planets # go into planets directory, which is already a Git repository -$ ls -a # ensure the .git subdirectory is still present in the planets directory -$ mkdir moons # make a subdirectory planets/moons -$ cd moons # go into moons subdirectory -$ git init # make the moons subdirectory a Git repository +$ mkdir interventions # make a subdirectory cases/interventions +$ cd interventions # go into interventions subdirectory +$ git init # make the interventions subdirectory a Git repository $ ls -a # ensure the .git subdirectory is present indicating we have created a new Git repository ``` -Is the `git init` command, run inside the `moons` subdirectory, required for -tracking files stored in the `moons` subdirectory? +Is the `git init` command, run inside the `interventions` subdirectory, required for +tracking files stored in the `interventions` subdirectory? ::::::::::::::: solution ## Solution -No. Dracula does not need to make the `moons` subdirectory a Git repository -because the `planets` repository can track any files, sub-directories, and -subdirectory files under the `planets` directory. Thus, in order to track -all information about moons, Dracula only needed to add the `moons` subdirectory -to the `planets` directory. +No. Dracula does not need to make the `interventions` subdirectory a Git repository +because the `cases` repository can track any files, sub-directories, and +subdirectory files under the `cases` directory. Thus, in order to track +all information about interventions, Dracula only needed to add the `interventions` subdirectory +to the `cases` directory. Additionally, Git repositories can interfere with each other if they are "nested": the outer repository will try to version-control @@ -161,13 +333,29 @@ $ git status fatal: Not a git repository (or any of the parent directories): .git ``` +Actually, if you try to create a new project using `{usethis}` within the `cases` repository, you will get this message: + +```r +usethis::create_project(path = "interventions") +``` + +```output +New project 'interventions' is nested inside an existing project './', which is rarely a good idea. +If this is unexpected, the here package has a function, `here::dr_here()` that reveals why './' is regarded as a project. +Do you want to create anyway? +``` + +Using the R functions from the `{usethis}` package can be less error-prone! + +Lastly, Dracula used some _Bash commands_ in the Terminal. If you are interested to learn more about them, we invite you to read this tutorial on [Bash commands](https://swcarpentry.github.io/shell-novice/)! + ::::::::::::::::::::::::: ## 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 -his last `git init` in the `moons` subdirectory? +his last `git init` in the `interventions` subdirectory? ::::::::::::::: solution @@ -191,10 +379,10 @@ becomes another change that we will need to track, as we will see in the next ep Git keeps all of its files in the `.git` directory. To recover from this little mistake, Dracula can just remove the `.git` -folder in the moons subdirectory by running the following command from inside the `planets` directory: +folder in the interventions subdirectory by running the following command from inside the `cases` directory: ```bash -$ rm -rf moons/.git +$ rm -rf interventions/.git ``` But be careful! Running this command in the wrong directory will remove @@ -207,10 +395,23 @@ Therefore, always check your current directory using the command `pwd`. :::::::::::::::::::::::::::::::::::::::::::::::::: + + :::::::::::::::::::::::::::::::::::::::: keypoints -- `git init` initializes a repository. + +- Use `usethis::create_project()` to create an R project. +- Use `usethis::use_git()` to initialize a repository. - Git stores all of its repository data in the `.git` directory. +- Use `git status` in the Terminal to check the status of a repository. :::::::::::::::::::::::::::::::::::::::::::::::::: diff --git a/episodes/04-changes.md b/episodes/04-changes.md index 82c5689faa..7bf1fc4192 100644 --- a/episodes/04-changes.md +++ b/episodes/04-changes.md @@ -1,7 +1,7 @@ --- title: Tracking Changes -teaching: 20 -exercises: 0 +teaching: 30 +exercises: 15 --- ::::::::::::::::::::::::::::::::::::::: objectives @@ -20,29 +20,64 @@ exercises: 0 :::::::::::::::::::::::::::::::::::::::::::::::::: -First let's make sure we're still in the right directory. -You should be in the `planets` directory. +Let’s start to tell the story of your project while you are working on it! -```bash -$ cd ~/Desktop/planets +::::::::::::::::::: prereq + +### The Console and the Terminal + +In this episode, we are going to use both, the [Console](https://docs.posit.co/ide/user/ide/guide/code/console.html) and the [Terminal](https://docs.posit.co/ide/user/ide/guide/tools/terminal.html). + +So look at the upper right corner of the code chunks in this episode: + +- `R < >` belongs to the Console. +- `BASH < >` belongs to the Terminal. + +:::::::::::::::::::::::::: + +## Add changes + +First, in the __Rstudio Console__, let's make sure we're still in the right R project. +You should be in the `cases` directory. + +```r +usethis::proj_path() ``` -Let's create a file called `mars.txt` that contains some notes -about the Red Planet's suitability as a base. -We'll use `nano` to edit the file; -you can use whatever editor you like. -In particular, this does not have to be the `core.editor` you set globally earlier. But remember, the bash command to create or edit a new file will depend on the editor you choose (it might not be `nano`). For a refresher on text editors, check out ["Which Editor?"](https://swcarpentry.github.io/shell-novice/03-create.html#which-editor) in [The Unix Shell](https://swcarpentry.github.io/shell-novice/) lesson. +```output +C:/~/cases +``` -```bash -$ nano mars.txt +Let's create a file called `sitrep.Rmd` that contains the situation report (Sitrep) +describing the data in terms of [person, time, and place](https://r4epis.netlify.app/outbreaks/#analyses). + +We can do this __from the Console__. Run: + +```r +usethis::edit_file("sitrep.Rmd") +``` + +```outputs +• Modify 'sitrep.Rmd' ``` -Type the text below into the `mars.txt` file: +This opens the file in the [Source pane](https://docs.posit.co/ide/user/ide/guide/ui/ui-panes.html) to edit it. + + + + +Type the text below into the `sitrep.Rmd` file: ```output -Cold and dry, but everything is my favorite color +Comparison of attack rates in different age groups ``` +Save the file. + + +Now, __in the Terminal__, +if we check the status of our project again, Git tells us that it's noticed the new file: ```bash @@ -78,17 +114,40 @@ No commits yet Untracked files: (use "git add ..." to include in what will be committed) - mars.txt + sitrep.Rmd nothing added to commit but untracked files present (use "git add" to track) ``` + + The "untracked files" message means that there's a file in the directory that Git isn't keeping track of. We can tell Git to track a file using `git add`: ```bash -$ git add mars.txt +$ git add sitrep.Rmd ``` and then check that the right thing happened: @@ -105,23 +164,47 @@ No commits yet Changes to be committed: (use "git rm --cached ..." to unstage) - new file: mars.txt + new file: sitrep.Rmd ``` -Git now knows that it's supposed to keep track of `mars.txt`, + + +## Commit changes + +Git now knows that it's supposed to keep track of `sitrep.Rmd`, but it hasn't recorded these changes as a commit yet. To get it to do that, +__in the Terminal__, we need to run one more command: ```bash -$ git commit -m "Start notes on Mars as a base" +$ git commit -m "Start Sitrep with attack rate analysis" ``` ```output -[main (root-commit) f22b25e] Start notes on Mars as a base +[main (root-commit) f22b25e] Start Sitrep with attack rate analysis 1 file changed, 1 insertion(+) - create mode 100644 mars.txt + create mode 100644 sitrep.Rmd ``` When we run `git commit`, @@ -133,13 +216,69 @@ This permanent copy is called a [commit](../learners/reference.md#commit) We use the `-m` flag (for "message") to record a short, descriptive, and specific comment that will help us remember later on what we did and why. If we just run `git commit` without the `-m` option, -Git will launch `nano` (or whatever other editor we configured as `core.editor`) +Git will launch `VIM` (or whatever other editor we configured as `core.editor`) so that we can write a longer message. +::::::::::::::::::::::::::::::::::::::::: 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 Esc then type `:q!` and hit Enter or ↵ or on Macs, Return. +If you want to save your changes and quit, press Esc then type `:wq` and hit Enter or ↵ or on Macs, Return. + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +::::::::::::::::: spoiler + +### Do we need to change git core editor? + +With Rstudio you don't need to do change any editor. You can open all your files in the Source pane. + +Also, to write commit messages you can use the Rstudio IDE. We invite you to [read the supplemental episode](14-supplemental-rstudio.md). + +However, if needed, Dracula can 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. + +::::::::::::::::::::::::: + [Good commit messages][commit-messages] start with a brief (\<50 characters) statement about the changes made in the commit. Generally, the message should complete the sentence "If applied, this commit will" . If you want to go into more detail, add a blank line between the summary line and your additional notes. Use this additional space to explain why you made changes and/or what their impact will be. +::::::::::::::::: checklist + +### Good practice + +A good commit: + +- Contains less than 50 characters in first line. + +- Start with an infinitive verb. + +- Recalls an specific action. + +::::::::::::::::::::::::::: + If we run `git status` now: ```bash @@ -152,7 +291,28 @@ nothing to commit, working tree clean ``` it tells us everything is up to date. + + + +## Show the history + If we want to know what we've done recently, +__in the Terminal__, we can ask Git to show us the project's history using `git log`: ```bash @@ -164,7 +324,7 @@ commit f22b25e3233b4645dabd0d81e651fe074bd8e73b Author: Vlad Dracula Date: Thu Aug 22 09:51:46 2013 -0400 - Start notes on Mars as a base + Start Sitrep with attack rate analysis ``` `git log` lists all commits made to a repository in reverse chronological order. @@ -176,11 +336,19 @@ the commit's author, when it was created, and the log message Git was given when the commit was created. +::::::::::::::::::: testimonial + +### These commands are so similar! + +The `git status` command displays the state of the _working directory_ and the _staging area_. It lets you see which changes have been staged, which haven’t, and which files aren’t being tracked by Git. __Status output does not show you__ any information regarding the committed project history (the _local repository_). For this, you need to use `git log`. [(Atlassian, 2023)](https://www.atlassian.com/git/tutorials/inspecting-a-repository) + +:::::::::::::::::::::::::::::: + ::::::::::::::::::::::::::::::::::::::::: callout ## Where Are My Changes? -If we run `ls` at this point, we will still see just one file called `mars.txt`. +If, in the Terminal, we run `ls` at this point, we will still see just one file called `sitrep.Rmd`. That's because Git saves information about files' history in the special `.git` directory mentioned earlier so that our filesystem doesn't become cluttered @@ -189,21 +357,46 @@ so that our filesystem doesn't become cluttered :::::::::::::::::::::::::::::::::::::::::::::::::: -Now suppose Dracula adds more information to the file. + + +## Compare changes + +Now suppose Dracula adds more information to the file. For this, let's return to the `sitrep.Rmd` file: + -```bash -$ nano mars.txt -$ cat mars.txt +```r +usethis::edit_file("sitrep.Rmd") ``` ```output -Cold and dry, but everything is my favorite color -The two moons may be a problem for Wolfman +Comparison of attack rates in different age groups +This can identify priority groups for interventions ``` -When we run `git status` now, +Save the file. + +__In the Terminal__, +when we run `git status` now, it tells us that a file it already knows about has been modified: ```bash @@ -216,7 +409,7 @@ Changes not staged for commit: (use "git add ..." to update what will be committed) (use "git checkout -- ..." to discard changes in working directory) - modified: mars.txt + modified: sitrep.Rmd no changes added to commit (use "git add" and/or "git commit -a") ``` @@ -228,7 +421,9 @@ but we haven't told Git we will want to save those changes (which we do with `git add`) nor have we saved them (which we do with `git commit`). So let's do that now. It is good practice to always review -our changes before saving them. We do this using `git diff`. +our changes before saving them. +In the Terminal, +we do this using `git diff`. This shows us the differences between the current state of the file and the most recently saved version: @@ -237,13 +432,13 @@ $ git diff ``` ```output -diff --git a/mars.txt b/mars.txt +diff --git a/sitrep.Rmd b/sitrep.Rmd index df0654a..315bf3a 100644 ---- a/mars.txt -+++ b/mars.txt +--- a/sitrep.Rmd ++++ b/sitrep.Rmd @@ -1 +1,2 @@ - Cold and dry, but everything is my favorite color -+The two moons may be a problem for Wolfman + Comparison of attack rates in different age groups ++This can identify priority groups for interventions ``` The output is cryptic because @@ -262,10 +457,31 @@ If we break it down into pieces: In particular, the `+` marker in the first column shows where we added a line. + + +## Staging area + After reviewing our change, it's time to commit it: ```bash -$ git commit -m "Add concerns about effects of Mars' moons on Wolfman" +$ git commit -m "Add purpose of attack rate analysis" ``` ```output @@ -274,7 +490,7 @@ Changes not staged for commit: (use "git add ..." to update what will be committed) (use "git checkout -- ..." to discard changes in working directory) - modified: mars.txt + modified: sitrep.Rmd no changes added to commit (use "git add" and/or "git commit -a") ``` @@ -284,12 +500,12 @@ Git won't commit because we didn't use `git add` first. Let's fix that: ```bash -$ git add mars.txt -$ git commit -m "Add concerns about effects of Mars' moons on Wolfman" +$ git add sitrep.Rmd +$ git commit -m "Add purpose of attack rate analysis" ``` ```output -[main 34961b1] Add concerns about effects of Mars' moons on Wolfman +[main 34961b1] Add purpose of attack rate analysis 1 file changed, 1 insertion(+) ``` @@ -310,6 +526,20 @@ where it keeps track of things that have been added to the current [changeset](../learners/reference.md#changeset) but not yet committed. +::::::::::::::::::: instructor + +### Definition: Staging area + +The staging area is the middle ground between what you have done to your files (also known as the working directory) and what you had last committed (the HEAD commit). As the name implies, the staging area gives you space to prepare (stage) the changes that will be reflected on the next commit. [(Coderefinery, 2023)](https://coderefinery.github.io/git-intro/staging-area/#staging-area-commands) + +### What is the use of the Staging area? + +[Read a testimony from StackOver Flow](https://stackoverflow.com/questions/49228209/whats-the-use-of-the-staging-area-in-git). + + +:::::::::::::::::::::::::::::: + + ::::::::::::::::::::::::::::::::::::::::: callout ## Staging Area @@ -331,41 +561,49 @@ Try to stage things manually, or you might find yourself searching for "git undo commit" more than you would like! - :::::::::::::::::::::::::::::::::::::::::::::::::: ![](fig/git-staging-area.svg){alt='The Git Staging Area'} -Let's watch as our changes to a file move from our editor -to the staging area -and into long-term storage. -First, -we'll add another line to the file: +::::::::::::::::: checklist -```bash -$ nano mars.txt -$ cat mars.txt +### Checklist + +![Use `git status` to display the state of the working directory and the staging area. `git add` your changes before you `git commit` them to the Local repository. Use the `git log` to get the history of changes in it. Use `git diff` to compare these changes.](fig/cut-git-verb_map-07.png) + +::::::::::::::::::::::::::: + +## Practice the workflow + +Let's watch as our changes to a file move from our editor to the staging area and into long-term storage. First, __in the Console__, we'll add another line to the file: + +```r +usethis::edit_file("sitrep.Rmd") ``` ```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 +Comparison of attack rates in different age groups +This can identify priority groups for interventions +Maps illustrate the spread and impact of outbreak ``` +Save the file. + +__In the Terminal__, check the difference: + ```bash $ git diff ``` ```output -diff --git a/mars.txt b/mars.txt +diff --git a/sitrep.Rmd b/sitrep.Rmd index 315bf3a..b36abfd 100644 ---- a/mars.txt -+++ b/mars.txt +--- a/sitrep.Rmd ++++ b/sitrep.Rmd @@ -1,2 +1,3 @@ - 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 + Comparison of attack rates in different age groups + This can identify priority groups for interventions ++Maps illustrate the spread and impact of outbreak ``` So far, so good: @@ -375,7 +613,7 @@ Now let's put that change in the staging area and see what `git diff` reports: ```bash -$ git add mars.txt +$ git add sitrep.Rmd $ git diff ``` @@ -391,14 +629,14 @@ $ git diff --staged ``` ```output -diff --git a/mars.txt b/mars.txt +diff --git a/sitrep.Rmd b/sitrep.Rmd index 315bf3a..b36abfd 100644 ---- a/mars.txt -+++ b/mars.txt +--- a/sitrep.Rmd ++++ b/sitrep.Rmd @@ -1,2 +1,3 @@ - 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 + Comparison of attack rates in different age groups + This can identify priority groups for interventions ++Maps illustrate the spread and impact of outbreak ``` it shows us the difference between @@ -407,11 +645,11 @@ and what's in the staging area. Let's save our changes: ```bash -$ git commit -m "Discuss concerns about Mars' climate for Mummy" +$ git commit -m "Add geospatial visualization objective" ``` ```output -[main 005937f] Discuss concerns about Mars' climate for Mummy +[main 005937f] Add geospatial visualization objective 1 file changed, 1 insertion(+) ``` @@ -437,21 +675,23 @@ commit 005937fbe2a98fb83f0ade869025dc2636b4dad5 (HEAD -> main) Author: Vlad Dracula Date: Thu Aug 22 10:14:07 2013 -0400 - Discuss concerns about Mars' climate for Mummy + Add geospatial visualization objective commit 34961b159c27df3b475cfe4415d94a6d1fcd064d Author: Vlad Dracula Date: Thu Aug 22 10:07:21 2013 -0400 - Add concerns about effects of Mars' moons on Wolfman + Add purpose of attack rate analysis commit f22b25e3233b4645dabd0d81e651fe074bd8e73b Author: Vlad Dracula Date: Thu Aug 22 09:51:46 2013 -0400 - Start notes on Mars as a base + Start Sitrep with attack rate analysis ``` +## Relevant callouts + ::::::::::::::::::::::::::::::::::::::::: callout ## Word-based diffing @@ -501,7 +741,7 @@ commit 005937fbe2a98fb83f0ade869025dc2636b4dad5 (HEAD -> main) Author: Vlad Dracula Date: Thu Aug 22 10:14:07 2013 -0400 - Discuss concerns about Mars' climate for Mummy + Add geospatial visualization objective ``` You can also reduce the quantity of information using the @@ -512,9 +752,9 @@ $ git log --oneline ``` ```output -005937f (HEAD -> main) Discuss concerns about Mars' climate for Mummy -34961b1 Add concerns about effects of Mars' moons on Wolfman -f22b25e Start notes on Mars as a base +005937f (HEAD -> main) Add geospatial visualization objective +34961b1 Add purpose of attack rate analysis +f22b25e Start Sitrep with attack rate analysis ``` You can also combine the `--oneline` option with others. One useful @@ -528,9 +768,9 @@ $ git log --oneline --graph ``` ```output -* 005937f (HEAD -> main) Discuss concerns about Mars' climate for Mummy -* 34961b1 Add concerns about effects of Mars' moons on Wolfman -* f22b25e Start notes on Mars as a base +* 005937f (HEAD -> main) Add geospatial visualization objective +* 34961b1 Add purpose of attack rate analysis +* f22b25e Start Sitrep with attack rate analysis ``` :::::::::::::::::::::::::::::::::::::::::::::::::: @@ -541,17 +781,19 @@ $ git log --oneline --graph Two important facts you should know about directories in Git. +### Git track files, not empty directories + 1. Git does not track directories on their own, only files within them. - Try it for yourself: + Try it for yourself using the Terminal: ```bash - $ mkdir spaceships + $ mkdir analyses $ git status - $ git add spaceships + $ git add analyses $ git status ``` - Note, our newly created empty directory `spaceships` does not appear in + Note, our newly created empty directory `analyses` does not appear in the list of untracked files even if we explicitly add it (*via* `git add`) to our repository. This is the reason why you will sometimes see `.gitkeep` files in otherwise empty directories. Unlike `.gitignore`, these files are not special @@ -568,16 +810,16 @@ Two important facts you should know about directories in Git. Try it for yourself: ```bash - $ touch spaceships/apollo-11 spaceships/sputnik-1 + $ touch analyses/attack-rate.R analyses/geospatial.R $ git status - $ git add spaceships + $ git add analyses $ git status ``` Before moving on, we will commit these changes. ```bash - $ git commit -m "Add some initial thoughts on spaceships" + $ git commit -m "Add analysis scripts on attack rate and geospatial" ``` :::::::::::::::::::::::::::::::::::::::::::::::::: @@ -589,16 +831,18 @@ repository (`git commit`): ![](fig/git-committing.svg){alt='The Git Commit Workflow'} +## Challenges + ::::::::::::::::::::::::::::::::::::::: challenge ## Choosing a Commit Message Which of the following commit messages would be most appropriate for the -last commit made to `mars.txt`? +last commit made to `sitrep.Rmd`? 1. "Changes" -2. "Added line 'But the Mummy will appreciate the lack of humidity' to mars.txt" -3. "Discuss effects of Mars' climate on the Mummy" +2. "Added line 'Maps illustrate the spread and impact of outbreak' to sitrep.Rmd" +3. "Discuss effects of Sitrep' climate on the Mummy" ::::::::::::::: solution @@ -658,10 +902,10 @@ to my local Git repository? The staging area can hold changes from any number of files that you want to commit as a single snapshot. -1. Add some text to `mars.txt` noting your decision - to consider Venus as a base -2. Create a new file `venus.txt` with your initial thoughts - about Venus as a base for you and your friends +1. Add some text to `sitrep.Rmd` noting your decision + to consider a data cleaning preliminary step. +2. Create a new file `clean.Rmd` with your initial thoughts + about Data as an step for you and your friends. 3. Add changes from both files to the staging area, and commit those changes. @@ -669,53 +913,53 @@ that you want to commit as a single snapshot. ## Solution -The output below from `cat mars.txt` reflects only content added during +The output below from `sitrep.Rmd` reflects only content added during this exercise. Your output may vary. -First we make our changes to the `mars.txt` and `venus.txt` files: +First we make our changes to the `sitrep.Rmd` and `clean.Rmd` files: -```bash -$ nano mars.txt -$ cat mars.txt +```r +usethis::edit_file("sitrep.Rmd") ``` ```output -Maybe I should start with a base on Venus. +Maybe I should start with a data cleaning step. ``` -```bash -$ nano venus.txt -$ cat venus.txt +```r +usethis::edit_file("clean.Rmd") ``` ```output -Venus is a nice planet and I definitely should consider it as a base. +Data is a messy file and I definitely should consider a data cleaning step. ``` +Save both files. + Now you can add both files to the staging area. We can do that in one line: ```bash -$ git add mars.txt venus.txt +$ git add sitrep.Rmd clean.Rmd ``` Or with multiple commands: ```bash -$ git add mars.txt -$ git add venus.txt +$ git add sitrep.Rmd +$ git add clean.Rmd ``` Now the files are ready to commit. You can check that using `git status`. If you are ready to commit use: ```bash -$ git commit -m "Write plans to start a base on Venus" +$ git commit -m "Write plans to start a data cleaning step" ``` ```output [main cc127c2] - Write plans to start a base on Venus + Write plans to start a data cleaning step 2 files changed, 2 insertions(+) - create mode 100644 venus.txt + create mode 100644 clean.Rmd ``` ::::::::::::::::::::::::: @@ -727,7 +971,7 @@ $ git commit -m "Write plans to start a base on Venus" ## `bio` Repository - Create a new Git repository on your computer called `bio`. -- Write a three-line biography for yourself in a file called `me.txt`, +- Write a three-line biography for yourself in a file called `me.md`, commit your changes - Modify one line, add a fourth line - Display the differences @@ -737,30 +981,30 @@ $ git commit -m "Write plans to start a base on Venus" ## Solution -If needed, move out of the `planets` folder: +If needed, create a project out of the `cases` folder: -```bash -$ cd .. +```r +usethis::create_project(path = "bio") ``` -Create a new folder called `bio` and 'move' into it: +Initialise git: -```bash -$ mkdir bio -$ cd bio +```r +usethis::use_git() ``` -Initialise git: +Create your biography file `me.md` using the Rstudio editor. -```bash -$ git init +```r +usethis::edit_file("me.md") ``` -Create your biography file `me.txt` using `nano` or another text editor. -Once in place, add and commit it to the repository: +Save the file. + +Once in place, in the Terminal add and commit it to the repository: ```bash -$ git add me.txt +$ git add me.md $ git commit -m "Add biography file" ``` @@ -769,14 +1013,22 @@ To display the differences between its updated state and its original state, use `git diff`: ```bash -$ git diff me.txt +$ git diff me.md ``` ::::::::::::::::::::::::: :::::::::::::::::::::::::::::::::::::::::::::::::: + [commit-messages]: https://chris.beams.io/posts/git-commit/ [git-references]: https://git-scm.com/book/en/v2/Git-Internals-Git-References @@ -785,10 +1037,10 @@ $ git diff me.txt :::::::::::::::::::::::::::::::::::::::: keypoints - `git status` shows the status of a repository. -- Files can be stored in a project's working directory (which users see), the staging area (where the next commit is being built up) and the local repository (where commits are permanently recorded). +- Files can be stored in a project's _working directory_ (which users see), the _staging area_ (where the next commit is being built up) and the _local repository_ (where commits are permanently recorded). - `git add` puts files in the staging area. - `git commit` saves the staged content as a new commit in the local repository. -- Write a commit message that accurately describes your changes. +- Write a _commit message_ that accurately describes your changes. :::::::::::::::::::::::::::::::::::::::::::::::::: diff --git a/episodes/05-history.md b/episodes/05-history.md index fcfbd1364f..8701436ae5 100644 --- a/episodes/05-history.md +++ b/episodes/05-history.md @@ -21,42 +21,52 @@ exercises: 0 :::::::::::::::::::::::::::::::::::::::::::::::::: -As we saw in the previous episode, we can refer to commits by their -identifiers. You can refer to the *most recent commit* of the working +## The HEAD + +As we saw in the previous episode, we can [refer to commits by their +identifiers](04-changes.md#commit-changes). You can refer to the *most recent commit* of the working directory by using the identifier `HEAD`. -We've been adding one line at a time to `mars.txt`, so it's easy to track our +We've been adding one line at a time to `sitrep.Rmd`, so it's easy to track our progress by looking, so let's do that using our `HEAD`s. Before we start, -let's make a change to `mars.txt`, adding yet another line. +let's make a change to `sitrep.Rmd`, adding yet another line. + +```r +usethis::edit_file("sitrep.Rmd") +``` + ```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 -An ill-considered change +Comparison of attack rates in different age groups +This can identify priority groups for interventions +Maps illustrate the spread and impact of outbreak +Maps can aid in the identification of hotspots ``` -Now, let's see what we get. +Save the file. + +Now, __in the Terminal__, let's see what we get. ```bash -$ git diff HEAD mars.txt +$ git diff HEAD sitrep.Rmd ``` ```output -diff --git a/mars.txt b/mars.txt +diff --git a/sitrep.Rmd b/sitrep.Rmd index b36abfd..0848c8d 100644 ---- a/mars.txt -+++ b/mars.txt +--- a/sitrep.Rmd ++++ b/sitrep.Rmd @@ -1,3 +1,4 @@ - 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 -+An ill-considered change. + Comparison of attack rates in different age groups + This can identify priority groups for interventions + Maps illustrate the spread and impact of outbreak ++Maps can aid in the identification of hotspots. ``` which is the same as what you would get if you leave out `HEAD` (try it). The @@ -66,34 +76,36 @@ that by adding `~1` to refer to the commit one before `HEAD`. ```bash -$ git diff HEAD~1 mars.txt +$ git diff HEAD~1 sitrep.Rmd ``` 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~3 sitrep.Rmd ``` ```output -diff --git a/mars.txt b/mars.txt +diff --git a/sitrep.Rmd b/sitrep.Rmd index df0654a..b36abfd 100644 ---- a/mars.txt -+++ b/mars.txt +--- a/sitrep.Rmd ++++ b/sitrep.Rmd @@ -1 +1,4 @@ - 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 -+An ill-considered change + Comparison of attack rates in different age groups ++This can identify priority groups for interventions ++Maps illustrate the spread and impact of outbreak ++Maps can aid in the identification of hotspots ``` +## Show changes in old commits + We could also use `git show` which shows us what changes we made at an older commit as well as the commit message, rather than the *differences* between a commit and our working directory that we see by using `git diff`. ```bash -$ git show HEAD~3 mars.txt +$ git show HEAD~3 sitrep.Rmd ``` ```output @@ -101,15 +113,15 @@ commit f22b25e3233b4645dabd0d81e651fe074bd8e73b Author: Vlad Dracula Date: Thu Aug 22 09:51:46 2013 -0400 - Start notes on Mars as a base + Start Sitrep with attack rate analysis -diff --git a/mars.txt b/mars.txt +diff --git a/sitrep.Rmd b/sitrep.Rmd new file mode 100644 index 0000000..df0654a --- /dev/null -+++ b/mars.txt ++++ b/sitrep.Rmd @@ -0,0 +1 @@ -+Cold and dry, but everything is my favorite color ++Comparison of attack rates in different age groups ``` In this way, @@ -120,6 +132,8 @@ so `HEAD~1` means "the previous commit", while `HEAD~123` goes back 123 commits from where we are now. +## Use commit unique ID + We can also refer to commits using those long strings of digits and letters that `git log` displays. @@ -132,19 +146,19 @@ Our first commit was given the ID so let's try this: ```bash -$ git diff f22b25e3233b4645dabd0d81e651fe074bd8e73b mars.txt +$ git diff f22b25e3233b4645dabd0d81e651fe074bd8e73b sitrep.Rmd ``` ```output -diff --git a/mars.txt b/mars.txt +diff --git a/sitrep.Rmd b/sitrep.Rmd index df0654a..93a3e13 100644 ---- a/mars.txt -+++ b/mars.txt +--- a/sitrep.Rmd ++++ b/sitrep.Rmd @@ -1 +1,4 @@ - 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 -+An ill-considered change + Comparison of attack rates in different age groups ++This can identify priority groups for interventions ++Maps illustrate the spread and impact of outbreak ++Maps can aid in the identification of hotspots ``` That's the right answer, @@ -152,26 +166,28 @@ but typing out random 40-character strings is annoying, so Git lets us use just the first few characters (typically seven for normal size projects): ```bash -$ git diff f22b25e mars.txt +$ git diff f22b25e sitrep.Rmd ``` ```output -diff --git a/mars.txt b/mars.txt +diff --git a/sitrep.Rmd b/sitrep.Rmd index df0654a..93a3e13 100644 ---- a/mars.txt -+++ b/mars.txt +--- a/sitrep.Rmd ++++ b/sitrep.Rmd @@ -1 +1,4 @@ - 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 -+An ill-considered change + Comparison of attack rates in different age groups ++This can identify priority groups for interventions ++Maps illustrate the spread and impact of outbreak ++Maps can aid in the identification of hotspots ``` +## Restore old versions + All right! So we can save changes to files and see what we've changed. Now, how can we restore older versions of things? Let's suppose we change our mind about the last update to -`mars.txt` (the "ill-considered change"). +`sitrep.Rmd` (the one about the "hotspots"). `git status` now tells us that the file has been changed, but those changes haven't been staged: @@ -186,7 +202,7 @@ Changes not staged for commit: (use "git add ..." to update what will be committed) (use "git checkout -- ..." to discard changes in working directory) - modified: mars.txt + modified: sitrep.Rmd no changes added to commit (use "git add" and/or "git commit -a") ``` @@ -195,14 +211,19 @@ We can put things back the way they were by using `git checkout`: ```bash -$ git checkout HEAD mars.txt -$ cat mars.txt +$ git checkout HEAD sitrep.Rmd +``` + +Now, read the content in the file: + +```r +usethis::edit_file("sitrep.Rmd") ``` ```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 +Comparison of attack rates in different age groups +This can identify priority groups for interventions +Maps illustrate the spread and impact of outbreak ``` As you might guess from its name, @@ -214,17 +235,21 @@ If we want to go back even further, we can use a commit identifier instead: ```bash -$ git checkout f22b25e mars.txt +$ git checkout f22b25e sitrep.Rmd ``` -```bash -$ cat mars.txt +Now, read the content in the file: + +```r +usethis::edit_file("sitrep.Rmd") ``` ```output -Cold and dry, but everything is my favorite color +Comparison of attack rates in different age groups ``` +Ask the current status: + ```bash $ git status ``` @@ -234,7 +259,7 @@ On branch main Changes to be committed: (use "git reset HEAD ..." to unstage) - modified: mars.txt + modified: sitrep.Rmd ``` @@ -243,7 +268,7 @@ Again, we can put things back the way they were by using `git checkout`: ```bash -$ git checkout HEAD mars.txt +$ git checkout HEAD sitrep.Rmd ``` ::::::::::::::::::::::::::::::::::::::::: callout @@ -253,13 +278,13 @@ $ git checkout HEAD mars.txt Above we used ```bash -$ git checkout f22b25e mars.txt +$ git checkout f22b25e sitrep.Rmd ``` -to revert `mars.txt` to its state after the commit `f22b25e`. But be careful! +to revert `sitrep.Rmd` 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. +if you forget `sitrep.Rmd` in the previous command. ```bash $ git checkout f22b25e @@ -277,7 +302,7 @@ 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 +HEAD is now at f22b25e Start Sitrep with attack rate analysis ``` The "detached HEAD" is like "look, but don't touch" here, @@ -332,6 +357,8 @@ If the introduction and conclusion are stored in separate files, on the other hand, moving backward and forward in time becomes much easier. +## Challenges + ::::::::::::::::::::::::::::::::::::::: challenge ## Recovering Older Versions of a File @@ -425,6 +452,16 @@ else has committed changes to the repository. :::::::::::::::::::::::::::::::::::::::::::::::::: +::::::::::::::::: testimonial + +### These commands are so similar! + +Commands like `git checkout` and `git revert` are useful but so similar that it's very easy to mix them up! + +With the concepts learned in this episode, we invite you to read this chapter on [undoing commits and changes](https://www.atlassian.com/git/tutorials/undoing-changes). + +::::::::::::::::::::::::: + ::::::::::::::::::::::::::::::::::::::: challenge ## Understanding Workflow and History @@ -432,27 +469,27 @@ else has committed changes to the repository. What is the output of the last command in ```bash -$ cd planets -$ 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 -$ cat venus.txt #this will print the contents of venus.txt to the screen +$ cd cases +$ echo "Data is messy and full of typos" > clean.Rmd #this adds a line of text in clean.Rmd +$ git add clean.Rmd +$ echo "Data is too long to be suitable to print" >> clean.Rmd +$ git commit -m "Comment on Data as an unsuitable print" +$ git checkout HEAD clean.Rmd +$ cat clean.Rmd #this will print the contents of clean.Rmd to the screen ``` 1. ```output - Venus is too hot to be suitable as a base + Data is too long to be suitable to print ``` 2. ```output - Venus is beautiful and full of love + Data is messy and full of typos ``` 3. ```output - Venus is beautiful and full of love - Venus is too hot to be suitable as a base + Data is messy and full of typos + Data is too long to be suitable to print ``` 4. ```output - Error because you have changed venus.txt without committing the changes + Error because you have changed clean.Rmd without committing the changes ``` ::::::::::::::: solution @@ -461,22 +498,22 @@ $ cat venus.txt #this will print the contents of venus.txt to the screen The answer is 2. -The command `git add venus.txt` places the current version of `venus.txt` into the staging area. +The command `git add clean.Rmd` places the current version of `clean.Rmd` into the staging area. The changes to the file from the second `echo` command are only applied to the working copy, not the version in the staging area. -So, when `git commit -m "Comment on Venus as an unsuitable base"` is executed, -the version of `venus.txt` committed to the repository is the one from the staging area and +So, when `git commit -m "Comment on Data as an unsuitable print"` is executed, +the version of `clean.Rmd` committed to the repository is the one from the staging area and 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` -replaces the working copy with the most recently committed version of `venus.txt`. +`git status` will show that the file is modified). However, `git checkout HEAD clean.Rmd` +replaces the working copy with the most recently committed version of `clean.Rmd`. -So, `cat venus.txt` will output +So, `cat clean.Rmd` will output ```output -Venus is beautiful and full of love. +Data is messy and full of typos. ``` ::::::::::::::::::::::::: @@ -487,10 +524,10 @@ Venus is beautiful and full of love. ## Checking Understanding of `git diff` -Consider this command: `git diff HEAD~9 mars.txt`. What do you predict this command +Consider this command: `git diff HEAD~9 sitrep.Rmd`. What do you predict this command will do if you execute it? What happens when you do execute it? Why? -Try another command, `git diff [ID] mars.txt`, where [ID] is replaced with +Try another command, `git diff [ID] sitrep.Rmd`, where [ID] is replaced with the unique identifier for your most recent commit. What do you think will happen, and what does happen? @@ -503,7 +540,7 @@ and what does happen? `git checkout` 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`, +Make a change to `sitrep.Rmd`, add that change using `git add`, then use `git checkout` to see if you can remove your change. ::::::::::::::: solution @@ -518,7 +555,7 @@ On branch main Changes to be committed: (use "git reset HEAD ..." to unstage) - modified: mars.txt + modified: sitrep.Rmd ``` @@ -526,18 +563,18 @@ 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 checkout -- sitrep.Rmd` 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 to unstage the file: ```bash -$ git reset HEAD mars.txt +$ git reset HEAD sitrep.Rmd ``` ```output Unstaged changes after reset: -M mars.txt +M sitrep.Rmd ``` Now, `git status` gives us: @@ -552,7 +589,7 @@ Changes not staged for commit: (use "git add ..." to update what will be committed) (use "git checkout -- ..." to discard changes in working directory) - modified: mars.txt + modified: sitrep.Rmd no changes added to commit (use "git add" and/or "git commit -a") ``` @@ -561,7 +598,7 @@ This means we can now use `git checkout` to restore the file to the previous commit: ```bash -$ git checkout -- mars.txt +$ git checkout -- sitrep.Rmd $ git status ``` @@ -581,16 +618,16 @@ nothing to commit, working tree clean Exploring history is an important part of Git, and often it is a challenge to find the right commit ID, especially if the commit is from several months ago. -Imagine the `planets` project has more than 50 files. -You would like to find a commit that modifies some specific text in `mars.txt`. +Imagine the `cases` project has more than 50 files. +You would like to find a commit that modifies some specific text in `sitrep.Rmd`. When you type `git log`, a very long list appeared. How can you narrow down the search? Recall that the `git diff` command allows us to explore one specific file, -e.g., `git diff mars.txt`. We can apply a similar idea here. +e.g., `git diff sitrep.Rmd`. We can apply a similar idea here. ```bash -$ git log mars.txt +$ git log sitrep.Rmd ``` Unfortunately some of these commit messages are very ambiguous, e.g., `update files`. @@ -601,7 +638,7 @@ for you. Is it possible to combine both? Let's try the following: ```bash -$ git log --patch mars.txt +$ git log --patch sitrep.Rmd ``` You should get a long list of output, and you should be able to see both commit messages and @@ -610,11 +647,17 @@ the difference between each commit. Question: What does the following command do? ```bash -$ git log --patch HEAD~9 *.txt +$ git log --patch HEAD~9 *.Rmd ``` :::::::::::::::::::::::::::::::::::::::::::::::::: +::::::::::::::::: checklist + +![Use `git diff` to compare changes since last commit or between commits. Use `git checkout` to undo changes by restoring the staging area (committed changes) or the local repository (last commit)](fig/cut-git-verb_map-08.png) + +::::::::::::::::::::::::::: + :::::::::::::::::::::::::::::::::::::::: keypoints - `git diff` displays differences between commits. diff --git a/episodes/06-ignore.md b/episodes/06-ignore.md index 0bdd8f5d07..6ee93e5bdc 100644 --- a/episodes/06-ignore.md +++ b/episodes/06-ignore.md @@ -17,14 +17,25 @@ exercises: 0 :::::::::::::::::::::::::::::::::::::::::::::::::: +## What not to put under Version Control? + +In the section called “What Not to Put Under Version Control” from [G. Wilson et al. 2017](https://journals.plos.org/ploscompbiol/article?id=10.1371/journal.pcbi.1005510#sec014) on Good Enough Practices in Scientific Computing, authors emphasize, among other notes, in three points: + +- Version control systems are __optimized for plain-text files__; +- __Avoid raw data__, since it should not change; +- __Avoid intermediate files or results__ that can be *re-generated* from raw data and software. + +## Ignore files + What if we have files that we do not want Git to track for us, like backup files created by our editor or intermediate files created during data analysis? -Let's create a few dummy files: +For example, `.csv` files exported from the `reader::write_csv()` function or `.png` files from `ggplot2::ggsave()`. +Let's create a few dummy files __in the Terminal__: ```bash -$ mkdir results -$ touch a.csv b.csv c.csv results/a.out results/b.out +$ mkdir figures +$ touch a.csv b.csv c.csv figures/a.png figures/b.png ``` and see what Git says: @@ -41,7 +52,7 @@ Untracked files: a.csv b.csv c.csv - results/ + figures/ nothing added to commit but untracked files present (use "git add" to track) ``` @@ -51,25 +62,33 @@ What's worse, having them all listed could distract us from changes that actually matter, so let's tell Git to ignore them. -We do this by creating a file in the root directory of our project called `.gitignore`: +We do this by creating a file in the root directory of our project called `.gitignore`. __In the console__, let's use: +```r +usethis::edit_file(".gitignore") +``` + + + +Write these patterns and save the file: ```output *.csv -results/ +figures/ ``` These patterns tell Git to ignore any file whose name ends in `.csv` -and everything in the `results` directory. +and everything in the `figures` directory. (If any of these files were already being tracked, Git would continue to track them.) Once we have created this file, -the output of `git status` is much cleaner: +the output of `git status` is much cleaner. __In the terminal__: ```bash $ git status @@ -93,7 +112,7 @@ Let's add and commit `.gitignore`: ```bash $ git add .gitignore -$ git commit -m "Ignore data files and the results folder" +$ git commit -m "Ignore data files and the figures folder" $ git status ``` @@ -131,39 +150,62 @@ Ignored files: a.csv b.csv c.csv - results/ + figures/ nothing to commit, working tree clean ``` +::::::::::::::::: checklist + +### Good Practice + +A good version control project: + +- Use it mostly for plain-text files + +- Avoid raw data. + +- Avoid intermediate files or results. + +::::::::::::::::::::::::::: + +## Challenges + ::::::::::::::::::::::::::::::::::::::: challenge ## Ignoring Nested Files Given a directory structure that looks like: +```bash +outputs/paper +outputs/templates +``` + + -How would you ignore only `results/plots` and not `results/data`? +How would you ignore only `outputs/templates` and not `outputs/paper`? ::::::::::::::: solution ## Solution If you only want to ignore the contents of -`results/plots`, you can change your `.gitignore` to ignore -only the `/plots/` subfolder by adding the following line to +`outputs/templates`, you can change your `.gitignore` to ignore +only the `/templates/` subfolder by adding the following line to your .gitignore: ```output -results/plots/ +outputs/templates/ ``` -This line will ensure only the contents of `results/plots` is ignored, and -not the contents of `results/data`. +This line will ensure only the contents of `outputs/templates` is ignored, and +not the contents of `outputs/paper`. As with most programming issues, there are a few alternative ways that one may ensure this ignore rule is followed. @@ -184,7 +226,12 @@ Further, the discussion page has more detail on ignore rules. How would you ignore all `.csv` files in your root directory except for `final.csv`? -Hint: Find out what `!` (the exclamation point operator) does + +::::::::::::::: hint + +Find out what `!` (the exclamation point operator) does in the [Git Reference documentation](../learners/reference.md) for `gitignore`. + +::::::::::::::: ::::::::::::::: solution @@ -216,14 +263,23 @@ of `.csv` files added to the root directory will be ignored. Given a directory structure that looks similar to the earlier Nested Files exercise, but with a slightly different directory structure: +```bash +outputs/paper +outputs/templates +outputs/slides +outputs/tables +``` + + -How would you ignore all of the contents in the results folder, but not `results/data`? +How would you ignore all of the contents in the outputs folder, but not `outputs/paper`? Hint: think a bit about how you created an exception with the `!` operator before. @@ -233,13 +289,13 @@ before. ## Solution If you want to ignore the contents of -`results/` but not those of `results/data/`, you can change your `.gitignore` to ignore -the contents of results folder, but create an exception for the contents of the -`results/data` subfolder. Your .gitignore would look like this: +`outputs/` but not those of `outputs/paper/`, you can change your `.gitignore` to ignore +the contents of outputs folder, but create an exception for the contents of the +`outputs/paper` subfolder. Your .gitignore would look like this: ```output -results/* # ignore everything in results folder -!results/data/ # do not ignore results/data/ contents +outputs/* # ignore everything in outputs folder +!outputs/paper/ # do not ignore outputs/paper/ contents ``` ::::::::::::::::::::::::: @@ -253,23 +309,23 @@ results/* # ignore everything in results folder Assuming you have an empty .gitignore file, and given a directory structure that looks like: ```bash -results/data/position/gps/a.csv -results/data/position/gps/b.csv -results/data/position/gps/c.csv -results/data/position/gps/info.txt -results/plots +data/household/position/gps/a.csv +data/household/position/gps/b.csv +data/household/position/gps/c.csv +data/household/position/gps/info.txt +data/survey ``` What's the shortest `.gitignore` rule you could write to ignore all `.csv` -files in `result/data/position/gps`? Do not ignore the `info.txt`. +files in `data/household/position/gps`? Do not ignore the `info.txt`. ::::::::::::::: solution ## Solution -Appending `results/data/position/gps/*.csv` will match every file in `results/data/position/gps` +Appending `data/household/position/gps/*.csv` will match every file in `data/household/position/gps` that ends with `.csv`. -The file `results/data/position/gps/info.txt` will not be ignored. +The file `data/household/position/gps/info.txt` will not be ignored. @@ -279,17 +335,26 @@ The file `results/data/position/gps/info.txt` will not be ignored. ::::::::::::::::::::::::::::::::::::::: challenge -## Ignoring all data Files in the repository +## Ignoring all CSV data Files in the repository Let us assume you have many `.csv` files in different subdirectories of your repository. For example, you might have: +```bash +outputs/a.csv +data/household/b.csv +data/survey/c.csv +data/survey/area_1/d.csv +``` + + How do you ignore all the `.csv` files, without explicitly listing the names of the corresponding folders? @@ -367,6 +432,7 @@ You want to keep them but you do not want to track them through `git`. :::::::::::::::::::::::::::::::::::::::: keypoints +- Avoid the version control of raw data, intermediate files and results that can be re-generated from raw data and software. - The `.gitignore` file tells Git what files to ignore. :::::::::::::::::::::::::::::::::::::::::::::::::: diff --git a/episodes/07-github.md b/episodes/07-github.md index eb72876696..d3dfceb47c 100644 --- a/episodes/07-github.md +++ b/episodes/07-github.md @@ -17,6 +17,16 @@ exercises: 0 :::::::::::::::::::::::::::::::::::::::::::::::::: +::::::::::::::::: prereq + +### PREREQUISITES + +When using `usethis::git_sitrep()`, check if there is no `✖ ...` line in the output with an error message. + +If you an error message like `✖ Token lacks ...` or `✖ Can't retrieve registered email`, [follow the steps in episode 2 to solve it](02-setup.md#set-up-your-github-token). + +:::::::::::::::::::::::: + Version control really comes into its own when we begin to collaborate with other people. We already have most of the machinery we need to do this; the only thing missing is to copy changes from one repository to another. @@ -34,11 +44,11 @@ world. To this end we are going to create a *remote* repository that will be lin ## 1\. Create a remote repository Log in to [GitHub](https://github.com), then click on the icon in the top right corner to -create a new repository called `planets`: +create a new repository called `cases`: ![](fig/github-create-repo-01.png){alt='Creating a Repository on GitHub (Step 1)'} -Name your repository "planets" and then click "Create Repository". +Name your repository `cases` and then click "Create Repository". Note: Since this repository will be connected to a local repository, it needs to be empty. Leave "Initialize this repository with a README" unchecked, and keep "None" as options for both "Add @@ -55,22 +65,22 @@ information on how to configure your local repository: This effectively does the following on GitHub's servers: ```bash -$ mkdir planets -$ cd planets -$ git init +$ mkdir cases # creates a working directory +$ cd cases # go into cases directory +$ git init # make the cases directory a Git repository ``` 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 +committed our earlier work on `sitrep.Rmd`, 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'} 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.png){alt='Freshly-Made GitHub Repository'} -Note that our local repository still contains our earlier work on `mars.txt`, but the +Note that our local repository still contains our earlier work on `sitrep.Rmd`, but the remote repository on GitHub appears empty as it doesn't contain any files yet. ## 2\. Connect local to remote repository @@ -82,27 +92,40 @@ identify it: ![](fig/github-find-repo-string.png){alt='Where to Find Repository URL on GitHub'} + ::::::::::::::::::::::::::::::::::::::::: callout ## HTTPS vs. SSH +The current recommendation is HTTPS because it is the easiest to set up on the widest range of networks and platforms, and by users who are new to all this. HTTPS is less likely to be blocked by a firewall. ([StackOverflow, 2012](https://stackoverflow.com/a/11041782/6702544)) + + :::::::::::::::::::::::::::::::::::::::::::::::::: + -Copy that URL from the browser, go into the local `planets` repository, and run +Copy that URL from the browser, go into the local `cases` repository, and run this command: ```bash -$ git remote add origin git@github.com:vlad/planets.git +$ git remote add origin https://github.com/vlad/cases.git +``` + + Make sure to use the URL for your repository rather than Vlad's: the only difference should be your username instead of `vlad`. @@ -118,13 +141,32 @@ $ git remote -v ``` ```output -origin git@github.com:vlad/planets.git (fetch) -origin git@github.com:vlad/planets.git (push) +origin git@github.com:vlad/cases.git (fetch) +origin git@github.com:vlad/cases.git (push) +``` + +You can also check this steps with `{usethis}`: + +```r +usethis::git_sitrep() +``` + +The output in the last section called `── GitHub project` should look like this: + +```output +── GitHub project +• Type = 'ours' +• Host = 'https://github.com' +• Config supports a pull request = TRUE +• origin = 'vlad/cases' (can push) +• upstream = +• Desc = 'origin' is both the source and primary repo. ``` We'll discuss remotes in more detail in the next episode, while talking about how they might be used for collaboration. + -## 4\. Push local changes to a remote +## 3\. Push local changes to a remote Now that authentication is setup, we can return to the remote. This command will push the changes from our local repository to the repository on GitHub: @@ -309,7 +352,7 @@ Compressing objects: 100% (11/11), done. Writing objects: 100% (16/16), 1.45 KiB | 372.00 KiB/s, done. Total 16 (delta 2), reused 0 (delta 0) remote: Resolving deltas: 100% (2/2), done. -To https://github.com/vlad/planets.git +To https://github.com/vlad/cases.git * [new branch] main -> main ``` @@ -336,6 +379,7 @@ $ git config --global --unset https.proxy :::::::::::::::::::::::::::::::::::::::::::::::::: + 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.png){alt='GitHub Repository After First Push'} ::::::::::::::::::::::::::::::::::::::::: callout @@ -379,6 +424,51 @@ simply use `git push -u origin main` once the remote has been set up. :::::::::::::::::::::::::::::::::::::::::::::::::: + +## All in one step + +You can use `usethis::use_github()` to _create_ a remote repository, _connect_ the local and the remote, and _push_ your local changes to a remote. + +::::::::::::::::::::::::::::::::: challenge + +For the Outbreak response, along with tracking information about cases (the project we have already created), +Dracula would also like to track information about interventions. + +Create new local repository for `interventions` and connect it with a remote repository: + +- First, if you are in Rstudio, close your R Project from `File` > `Close Project`. +- In the Console, run: + +```r +# create a new R project in a new directory +usethis::create_project(path = "interventions") + +# make the interventions directory a Git local repository +usethis::use_git() + +# 1. create a GitHub remote repository +# 2. connect local with remote +# 3. push content to remote +usethis::use_github() +``` + +```output +ℹ Defaulting to 'https' Git protocol +✔ Creating GitHub repository 'vlad/cases' +✔ Setting remote 'origin' to 'https://github.com/vlad/cases.git' +✔ Pushing 'main' branch to GitHub and setting 'origin/main' as upstream branch +✔ Opening URL 'https://github.com/vlad/cases' +``` + +This will open a new tab in your web browser with the URL path of your remote repository in GitHub. + + +::::::::::::::::: + + + +## Pull changes + We can pull changes from the remote repository to the local one as well: ```bash @@ -386,7 +476,7 @@ $ git pull origin main ``` ```output -From https://github.com/vlad/planets +From https://github.com/vlad/cases * branch main -> FETCH_HEAD Already up-to-date. ``` @@ -399,7 +489,7 @@ GitHub, though, this command would download them to our local repository. ## GitHub GUI -Browse to your `planets` repository on GitHub. +Browse to your `cases` repository on GitHub. Underneath the Code button, find and click on the text that says "XX commits" (where "XX" is some number). Hover over, and click on, the three buttons to the right of each commit. What information can you gather/explore from these buttons? @@ -516,7 +606,7 @@ remote: Enumerating objects: 3, done. remote: Counting objects: 100% (3/3), done. remote: Total 3 (delta 0), reused 0 (delta 0), pack-reused 0 Unpacking objects: 100% (3/3), done. -From https://github.com/vlad/planets +From https://github.com/vlad/cases * branch main -> FETCH_HEAD * [new branch] main -> origin/main fatal: refusing to merge unrelated histories @@ -531,7 +621,7 @@ $ git pull --allow-unrelated-histories origin main ``` ```output -From https://github.com/vlad/planets +From https://github.com/vlad/cases * branch main -> FETCH_HEAD Merge made by the 'recursive' strategy. README.md | 1 + @@ -543,10 +633,17 @@ create mode 100644 README.md :::::::::::::::::::::::::::::::::::::::::::::::::: +::::::::::::::::: checklist + +![Use `git pull` to download content from a remote repository to the workspace and update the local repository to match that content. Use `git push` to upload local repository content to a remote repository.](fig/cut-git-verb_map-09.png) + +::::::::::::::::::::::::::: + :::::::::::::::::::::::::::::::::::::::: keypoints - A local Git repository can be connected to one or more remote repositories. -- Use the SSH protocol to connect to remote repositories. + +- Use the HTTPS protocol to connect to remote repositories. - `git push` copies changes from a local repository to a remote repository. - `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 c67f9f098f..c75e71a84e 100644 --- a/episodes/08-collab.md +++ b/episodes/08-collab.md @@ -18,6 +18,44 @@ exercises: 0 :::::::::::::::::::::::::::::::::::::::::::::::::: +## Paper Writing + +From the [first episode](01-basics.md#paper-writing)! + +Imagine you have 3 co-authors. How would you manage the changes and comments they make to your paper? + +If you use Google Docs, you can have access to the history of changes, and also identify how made those changes. + +![](fig/googledocs-collab.png) + +For __plain-text__ files, you can use GitHub to see the changes made per commit. In the left side or in color red are the deletions and in the right side or in color green the additions. + +![](fig/github-collab-10.png) + +Additionally, in GitHub you can use the option `Blame` to read the authors of changes per line. In this way, you can also read any related comment regarding why an specific line was edited. + +![](fig/github-collab-11.png) + +All of these is possible with a _collaboration workflow_ between contributors using Git and GitHub! + +::::::::::::::::: checklist + +### Checklist + +Key characteristics of Version control systems are: + +1. Keep the entire history of a file and inspect a file throughout its lifetime. + +2. Tag a particular version so you can return to them easily. + + + +3. Facilitates collaborations and makes contributions transparent. + +::::::::::::::::::::::::::: + +## Get a copy of remote + For the next step, get into pairs. One person will be the "Owner" and the other will be the "Collaborator". The goal is that the Collaborator add changes into the Owner's repository. We will switch roles at the end, so both persons will @@ -48,46 +86,77 @@ or check for email notification. Once there she can accept access to the Owner's Next, the Collaborator needs to download a copy of the Owner's repository to her machine. This is called "cloning a repo". -The Collaborator doesn't want to overwrite her own version of `planets.git`, so +The Collaborator doesn't want to overwrite her own version of `cases.git`, so needs to clone the Owner's repository to a different location than her own repository with the same name. -To clone the Owner's repo into her `Desktop` folder, the Collaborator enters: +::::::::::::::::: callout + +First, if you are in Rstudio, close your R Project from `File` > `Close Project`. +::::::::::::::::::::::::: + +To clone the Owner's repo into Collaborator's folder, in the Console, the __Collaborator__ enters: + +```bash +$ git clone https://github.com/vlad/cases.git vlad-cases +``` + + Replace 'vlad' with the Owner's username. +::::::::::::::::: callout + If you choose to clone without the clone path -(`~/Desktop/vlad-planets`) specified at the end, -you will clone inside your own planets folder! -Make sure to navigate to the `Desktop` folder first. +(`vlad-cases`) specified at the end, +you will clone inside your own cases folder! + -![](fig/github-collaboration.svg){alt='After Creating Clone of Repository'} +__ALSO:__ You only need to add the "clone path" when you have a local folder with the same name as the remote repository. This is not a common addition. + +::::::::::::::::::::::::: + +![In the Outbreak response scenario, now Wolfman has a local copy of the remote repository. They are already set up to collaborate for one project!](fig/github-collaboration.png){alt='After Creating Clone of Repository'} + +## Edit the clone -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: +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. + + + +First, open the `vlad-cases` R project. If you are in Rstudio: `File` > `New Project...` and navigate to the directory location. + +Now, let's create a new file called `dashboard.Rmd` to complement our Situation report! + +```r +usethis::edit_file("dashboard.Rmd") ``` ```output -It is so a planet! +Let's create a dashboard! ``` ```bash -$ git add pluto.txt -$ git commit -m "Add notes about Pluto" +$ git add dashboard.Rmd +$ git commit -m "Add notes about Dashboard" ``` ```output 1 file changed, 1 insertion(+) - create mode 100644 pluto.txt + create mode 100644 dashboard.Rmd ``` Then push the change to the *Owner's repository* on GitHub: @@ -103,7 +172,7 @@ Delta compression using up to 4 threads. Compressing objects: 100% (2/2), done. Writing objects: 100% (3/3), 306 bytes, done. Total 3 (delta 0), reused 0 (delta 0) -To https://github.com/vlad/planets.git +To https://github.com/vlad/cases.git 9272da5..29aba7c main -> main ``` @@ -151,7 +220,9 @@ associated with a repository. Here are some of the most useful ones: :::::::::::::::::::::::::::::::::::::::::::::::::: -To download the Collaborator's changes from GitHub, the Owner now enters: +## Download contributor edits + +To download the Collaborator's changes from GitHub, in the Console, the __Owner__ now enters: ```bash $ git pull origin main @@ -163,17 +234,17 @@ remote: Counting objects: 100% (4/4), done. remote: Compressing objects: 100% (2/2), done. remote: Total 3 (delta 0), reused 3 (delta 0), pack-reused 0 Unpacking objects: 100% (3/3), done. -From https://github.com/vlad/planets +From https://github.com/vlad/cases * branch main -> FETCH_HEAD 9272da5..29aba7c main -> origin/main Updating 9272da5..29aba7c Fast-forward - pluto.txt | 1 + + dashboard.Rmd | 1 + 1 file changed, 1 insertion(+) - create mode 100644 pluto.txt + create mode 100644 dashboard.Rmd ``` -Now the three repositories (Owner's local, Collaborator's local, and Owner's on +Now the __three repositories__ (Owner's local, Collaborator's local, and Owner's on GitHub) are back in sync. ::::::::::::::::::::::::::::::::::::::::: callout @@ -225,7 +296,7 @@ will see the changes output in the terminal. On GitHub, the Collaborator can go to the repository and click on "commits" to view the most recent commits pushed to the repository. - +![Use `git fetch` to download the remote content but not update your local repo's working state, leaving your current work intact. Use `git pull` to download the remote content for the active local branch and immediately merge it. this can potentially cause conflicts.](fig/cut-git-verb_map-12.png) ::::::::::::::::::::::::: @@ -257,6 +328,38 @@ What are some of the benefits of using version control, Git and GitHub? :::::::::::::::::::::::::::::::::::::::::::::::::: +::::::::::::::::::::::::::::::::: challenge + +### Create your GitHub profile! + +Your profile page introduce you to other contributors on GitHub: + +![](fig/github-create-00.png) + +::::::::::::::::: solution + +To create this, go to the [GitHub Home page](https://github.com/), identify the section called __Introduce yourself with a profile README__. Click on `Create`: + +![](fig/github-create-01.png) + +Edit the lines in the template file. Then click on `Commit changes...` + +![](fig/github-create-02.png) + +To edit this in a local repository, clone it following the steps you learned! + +![](fig/github-create-03.png) + +:::::::::::::::::::::::::: + +::::::::::::::::::::::::::::::::::::::::::: + +::::::::::::::::: checklist + +![Use `git clone` to obtain a development copy of a remote repository. Like `git init`, cloning is generally a one-time operation. Use `git pull` to update the local repository to match the content in the remote repository.](fig/cut-git-verb_map-10.png) + +::::::::::::::::::::::::::: + :::::::::::::::::::::::::::::::::::::::: keypoints - `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 b1e9e0b3dc..3b4aaab6d6 100644 --- a/episodes/09-conflict.md +++ b/episodes/09-conflict.md @@ -17,6 +17,22 @@ exercises: 0 :::::::::::::::::::::::::::::::::::::::::::::::::: +## A story of two collaborators + +Two users can make independent +sets of changes on the same document. + +![](fig/versions.svg){alt='Different Versions Can be Saved'} + +If multiple users make changes to different sections of the document you can +incorporate two sets of changes into the same base document. + +![](fig/merge.svg){alt='Multiple Versions Can be Merged'} + +However, if multiple users make changes to the same sections of the document, this will generate a conflict. + +![](fig/conflict.svg){alt='The Conflicting Changes'} + As soon as people can work in parallel, they'll likely step on each other's toes. This will even happen with a single person: if we are working on a piece of software on both our laptop and a server in the lab, we could make @@ -24,38 +40,52 @@ different changes to each copy. Version control helps us manage these [conflicts](../learners/reference.md#conflict) by giving us tools to [resolve](../learners/reference.md#resolve) overlapping changes. +## Create a conflict + To see how we can resolve conflicts, we must first create one. The file -`mars.txt` currently looks like this in both partners' copies of our `planets` +`sitrep.Rmd` currently looks like this in both partners' copies of our `cases` repository: +```r +usethis::edit_file("sitrep.Rmd") +``` + + ```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 +Comparison of attack rates in different age groups +This can identify priority groups for interventions +Maps illustrate the spread and impact of outbreak ``` -Let's add a line to the collaborator's copy only: +Let's add a line to the __collaborator's__ copy only: + +```r +usethis::edit_file("sitrep.Rmd") +``` + ```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 +Comparison of attack rates in different age groups +This can identify priority groups for interventions +Maps illustrate the spread and impact of outbreak This line added to Wolfman's copy ``` and then push the change to GitHub: ```bash -$ git add mars.txt +$ git add sitrep.Rmd $ git commit -m "Add a line in our home copy" ``` @@ -76,30 +106,36 @@ Compressing objects: 100% (3/3), done. Writing objects: 100% (3/3), 331 bytes | 331.00 KiB/s, done. Total 3 (delta 2), reused 0 (delta 0) remote: Resolving deltas: 100% (2/2), completed with 2 local objects. -To https://github.com/vlad/planets.git +To https://github.com/vlad/cases.git 29aba7c..dabb4c8 main -> main ``` -Now let's have the owner +Now let's have the __owner__ make a different change to their copy *without* updating from GitHub: +```r +usethis::edit_file("sitrep.Rmd") +``` + + ```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 +Comparison of attack rates in different age groups +This can identify priority groups for interventions +Maps illustrate the spread and impact of outbreak We added a different line in the other copy ``` We can commit the change locally: ```bash -$ git add mars.txt +$ git add sitrep.Rmd $ git commit -m "Add a line in my copy" ``` @@ -115,9 +151,9 @@ $ git push origin main ``` ```output -To https://github.com/vlad/planets.git +To https://github.com/vlad/cases.git ! [rejected] main -> main (fetch first) -error: failed to push some refs to 'https://github.com/vlad/planets.git' +error: failed to push some refs to 'https://github.com/vlad/cases.git' hint: Updates were rejected because the remote contains work that you do hint: not have locally. This is usually caused by another repository pushing hint: to the same ref. You may want to first integrate the remote changes @@ -129,8 +165,13 @@ hint: See the 'Note about fast-forwards' in 'git push --help' for details. Git rejects the push because it detects that the remote repository has new updates that have not been incorporated into the local branch. -What we have to do is pull the changes from GitHub, -[merge](../learners/reference.md#merge) them into the copy we're currently working in, and then push that. +What we have to do is `pull` the changes from GitHub, +[`merge`](../learners/reference.md#merge) them into the copy we're currently working in, and then push that. + +## Resolve conflict + +The __owner__ need to solve this conflict to be able to push to the remote repository. + Let's start by pulling: ```bash @@ -143,11 +184,11 @@ remote: Counting objects: 100% (5/5), done. remote: Compressing objects: 100% (1/1), done. remote: Total 3 (delta 2), reused 3 (delta 2), pack-reused 0 Unpacking objects: 100% (3/3), done. -From https://github.com/vlad/planets +From https://github.com/vlad/cases * branch main -> FETCH_HEAD 29aba7c..dabb4c8 main -> origin/main -Auto-merging mars.txt -CONFLICT (content): Merge conflict in mars.txt +Auto-merging sitrep.Rmd +CONFLICT (content): Merge conflict in sitrep.Rmd Automatic merge failed; fix conflicts and then commit the result. ``` @@ -158,14 +199,20 @@ overlap with those made to the remote repository, and therefore refuses to merge stop us from trampling on our previous work. The conflict is marked in in the affected file: +```r +usethis::edit_file("sitrep.Rmd") +``` + + ```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 +Comparison of attack rates in different age groups +This can identify priority groups for interventions +Maps illustrate the spread and impact of outbreak <<<<<<< HEAD We added a different line in the other copy ======= @@ -186,23 +233,29 @@ the change made in the remote repository, write something new to replace both, or get rid of the change entirely. Let's replace both so that the file looks like this: +```r +usethis::edit_file("sitrep.Rmd") +``` + + ```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 +Comparison of attack rates in different age groups +This can identify priority groups for interventions +Maps illustrate the spread and impact of outbreak We removed the conflict on this line ``` To finish merging, -we add `mars.txt` to the changes being made by the merge +we add `sitrep.Rmd` to the changes being made by the merge and then commit: ```bash -$ git add mars.txt +$ git add sitrep.Rmd $ git status ``` @@ -213,7 +266,7 @@ All conflicts fixed but you are still merging. Changes to be committed: - modified: mars.txt + modified: sitrep.Rmd ``` @@ -239,13 +292,15 @@ Compressing objects: 100% (6/6), done. Writing objects: 100% (6/6), 645 bytes | 645.00 KiB/s, done. Total 6 (delta 4), reused 0 (delta 0) remote: Resolving deltas: 100% (4/4), completed with 2 local objects. -To https://github.com/vlad/planets.git +To https://github.com/vlad/cases.git dabb4c8..2abf2b1 main -> main ``` +## Pull before editing + Git keeps track of what we've merged with what, so we don't have to fix things by hand again -when the collaborator who made the first change pulls again: +when the __collaborator__ who made the first change pulls again: ```bash $ git pull origin main @@ -257,25 +312,31 @@ remote: Counting objects: 100% (10/10), done. remote: Compressing objects: 100% (2/2), done. remote: Total 6 (delta 4), reused 6 (delta 4), pack-reused 0 Unpacking objects: 100% (6/6), done. -From https://github.com/vlad/planets +From https://github.com/vlad/cases * branch main -> FETCH_HEAD dabb4c8..2abf2b1 main -> origin/main Updating dabb4c8..2abf2b1 Fast-forward - mars.txt | 2 +- + sitrep.Rmd | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) ``` We get the merged file: +```r +usethis::edit_file("sitrep.Rmd") +``` + + ```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 +Comparison of attack rates in different age groups +This can identify priority groups for interventions +Maps illustrate the spread and impact of outbreak We removed the conflict on this line ``` @@ -302,6 +363,21 @@ Conflicts can also be minimized with project management strategies: project convention that is governing and use code style tools (e.g. `htmltidy`, `perltidy`, `rubocop`, etc.) to enforce, if necessary +::::::::::::::::: checklist + +### Good practices + +A good collaborator: + +- Pull from upstream frequently before new edits. +- Use topic or feature branches to segregate work. +- Make atomic commits. +- Push your work when it is done to reduce work in progress. +- Break large files when appropriate. +- Read contributing guidelines from the project owner. + +::::::::::::::::::::::::::: + ::::::::::::::::::::::::::::::::::::::: challenge ## Solving Conflicts that You Create @@ -328,39 +404,39 @@ that is stored in version control? ## Solution -Let's try it. Suppose Dracula takes a picture of Martian surface and -calls it `mars.jpg`. +Let's try it. Suppose Dracula takes a picture of the laboratory test and +calls it `lab.jpg`. -If you do not have an image file of Mars available, you can create +If you do not have an image file of the lab available, you can create a dummy binary file like this: ```bash -$ head -c 1024 /dev/urandom > mars.jpg -$ ls -lh mars.jpg +$ head -c 1024 /dev/urandom > lab.jpg +$ ls -lh lab.jpg ``` ```output --rw-r--r-- 1 vlad 57095 1.0K Mar 8 20:24 mars.jpg +-rw-r--r-- 1 vlad 57095 1.0K Mar 8 20:24 lab.jpg ``` `ls` shows us that this created a 1-kilobyte file. It is full of random bytes read from the special file, `/dev/urandom`. -Now, suppose Dracula adds `mars.jpg` to his repository: +Now, suppose Dracula adds `lab.jpg` to his repository: ```bash -$ git add mars.jpg -$ git commit -m "Add picture of Martian surface" +$ git add lab.jpg +$ git commit -m "Add picture of laboratory test" ``` ```output -[main 8e4115c] Add picture of Martian surface +[main 8e4115c] Add picture of laboratory test 1 file changed, 0 insertions(+), 0 deletions(-) - create mode 100644 mars.jpg + create mode 100644 lab.jpg ``` Suppose that Wolfman has added a similar picture in the meantime. -His is a picture of the Martian sky, but it is *also* called `mars.jpg`. +His is a picture of the laboratory site, but it is *also* called `lab.jpg`. When Dracula tries to push, he gets a familiar message: ```bash @@ -368,9 +444,9 @@ $ git push origin main ``` ```output -To https://github.com/vlad/planets.git +To https://github.com/vlad/cases.git ! [rejected] main -> main (fetch first) -error: failed to push some refs to 'https://github.com/vlad/planets.git' +error: failed to push some refs to 'https://github.com/vlad/cases.git' hint: Updates were rejected because the remote contains work that you do hint: not have locally. This is usually caused by another repository pushing hint: to the same ref. You may want to first integrate the remote changes @@ -393,20 +469,20 @@ remote: Counting objects: 3, done. remote: Compressing objects: 100% (3/3), done. remote: Total 3 (delta 0), reused 0 (delta 0) Unpacking objects: 100% (3/3), done. -From https://github.com/vlad/planets.git +From https://github.com/vlad/cases.git * branch main -> FETCH_HEAD 6a67967..439dc8c main -> origin/main -warning: Cannot merge binary files: mars.jpg (HEAD vs. 439dc8c08869c342438f6dc4a2b615b05b93c76e) -Auto-merging mars.jpg -CONFLICT (add/add): Merge conflict in mars.jpg +warning: Cannot merge binary files: lab.jpg (HEAD vs. 439dc8c08869c342438f6dc4a2b615b05b93c76e) +Auto-merging lab.jpg +CONFLICT (add/add): Merge conflict in lab.jpg Automatic merge failed; fix conflicts and then commit the result. ``` -The conflict message here is mostly the same as it was for `mars.txt`, but +The conflict message here is mostly the same as it was for `sitrep.Rmd`, but there is one key additional line: ```output -warning: Cannot merge binary files: mars.jpg (HEAD vs. 439dc8c08869c342438f6dc4a2b615b05b93c76e) +warning: Cannot merge binary files: lab.jpg (HEAD vs. 439dc8c08869c342438f6dc4a2b615b05b93c76e) ``` Git cannot automatically insert conflict markers into an image as it does @@ -414,31 +490,31 @@ for text files. So, instead of editing the image file, we must check out the version we want to keep. Then we can add and commit this version. On the key line above, Git has conveniently given us commit identifiers -for the two versions of `mars.jpg`. Our version is `HEAD`, and Wolfman's +for the two versions of `lab.jpg`. Our version is `HEAD`, and Wolfman's version is `439dc8c0...`. If we want to use our version, we can use `git checkout`: ```bash -$ git checkout HEAD mars.jpg -$ git add mars.jpg -$ git commit -m "Use image of surface instead of sky" +$ git checkout HEAD lab.jpg +$ git add lab.jpg +$ git commit -m "Use image of test instead of site" ``` ```output -[main 21032c3] Use image of surface instead of sky +[main 21032c3] Use image of test instead of site ``` If instead we want to use Wolfman's version, we can use `git checkout` with Wolfman's commit identifier, `439dc8c0`: ```bash -$ git checkout 439dc8c0 mars.jpg -$ git add mars.jpg -$ git commit -m "Use image of sky instead of surface" +$ git checkout 439dc8c0 lab.jpg +$ git add lab.jpg +$ git commit -m "Use image of site instead of test" ``` ```output -[main da21b34] Use image of sky instead of surface +[main da21b34] Use image of site instead of test ``` We can also keep *both* images. The catch is that we cannot keep them @@ -447,29 +523,29 @@ and *rename* it, then add the renamed versions. First, check out each image and rename it: ```bash -$ git checkout HEAD mars.jpg -$ git mv mars.jpg mars-surface.jpg -$ git checkout 439dc8c0 mars.jpg -$ mv mars.jpg mars-sky.jpg +$ git checkout HEAD lab.jpg +$ git mv lab.jpg lab-test.jpg +$ git checkout 439dc8c0 lab.jpg +$ mv lab.jpg lab-site.jpg ``` -Then, remove the old `mars.jpg` and add the two new files: +Then, remove the old `lab.jpg` and add the two new files: ```bash -$ git rm mars.jpg -$ git add mars-surface.jpg -$ git add mars-sky.jpg -$ git commit -m "Use two images: surface and sky" +$ git rm lab.jpg +$ git add lab-test.jpg +$ git add lab-site.jpg +$ git commit -m "Use two images: test and site" ``` ```output -[main 94ae08c] Use two images: surface and sky +[main 94ae08c] Use two images: test and site 2 files changed, 0 insertions(+), 0 deletions(-) - create mode 100644 mars-sky.jpg - rename mars.jpg => mars-surface.jpg (100%) + create mode 100644 lab-site.jpg + rename lab.jpg => lab-test.jpg (100%) ``` -Now both images of Mars are checked into the repository, and `mars.jpg` +Now both images of the lab are checked into the repository, and `lab.jpg` no longer exists. @@ -478,6 +554,40 @@ no longer exists. :::::::::::::::::::::::::::::::::::::::::::::::::: +## Atomic commits + +A good commit is also an __atomic commit__, like in the commit of the last challenge: + +```bash +$ git add lab-test.jpg +$ git add lab-site.jpg +$ git commit -m "Use two images: test and site" +``` + +Commits should be ‘atomic’, meaning that they should do one simple thing and they should do it completely. ([The Turing Way Community](https://the-turing-way.netlify.app/reproducible-research/vcs/vcs-git-compare#good-practice)). Atomic commits prioritize one unit of change instead of the quantity of changes. + +![Two related modified lines must be part of the same commit.](fig/git-rstudio-27.png) + +In Rstudio, the Review changes window has a button called “Stage chunk”. This helps to make atomic commits, even if you change a lot of lines in a single edit. You can either select them to make isolated commits or to unite them to be part of the same commit. + +![Two unrelated edits must be part of two isolated commits.](fig/git-rstudio-35.png) + +::::::::::::::::: checklist + +### Good practice + +A good atomic commit: + +- Includes more than one file that involves one unit of change. + +- Isolate or includes multiple edited lines using the "Stage chunk" button in Rstudio. + +- Does not include all the files in one commit. + +::::::::::::::::::::::::::: + +## Challenge + ::::::::::::::::::::::::::::::::::::::: challenge ## A Typical Work Session @@ -486,7 +596,7 @@ You sit down at your computer to work on a shared project that is tracked in a remote Git repository. During your work session, you take the following actions, but not in this order: -- *Make changes* by appending the number `100` to a text file `numbers.txt` +- *Make changes* by appending the number `100` to a text file `numbers.md` - *Update remote* repository to match the local repository - *Celebrate* your success with some fancy beverage(s) - *Update local* repository to match the remote repository @@ -502,7 +612,7 @@ started. | order | action . . . . . . . . . . | command . . . . . . . . . . | | ----- | -------------------------- | --------------------------------------------- | | 1 | | | -| 2 | | `echo 100 >> numbers.txt` | +| 2 | | `echo 100 >> numbers.md` | | 3 | | | | 4 | | | | 5 | | | @@ -515,9 +625,9 @@ 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"` | +| 2 | Make changes | `echo 100 >> numbers.md` | +| 3 | Stage changes | `git add numbers.md` | +| 4 | Commit changes | `git commit -m "Add 100 to numbers.md"` | | 5 | Update remote | `git push origin main` | | 6 | Celebrate! | `AFK` | @@ -527,6 +637,7 @@ started. :::::::::::::::::::::::::::::::::::::::: keypoints +- Version control also allows many people to work in parallel. - Conflicts occur when two or more people change the same lines of the same file. - 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/14-supplemental-rstudio.md b/episodes/14-supplemental-rstudio.md index c1f5d72ab9..6f5364e29c 100644 --- a/episodes/14-supplemental-rstudio.md +++ b/episodes/14-supplemental-rstudio.md @@ -1,5 +1,5 @@ --- -title: 'Supplemental: Using Git from RStudio' +title: 'Supplemental: Using RStudio for Git' teaching: 10 exercises: 0 --- @@ -22,6 +22,14 @@ that reason, the popular development environment integration with Git. While some advanced Git features still require the command-line, RStudio has a nice interface for many common Git operations. +::::::::::::::::: testimonial + +We also invite you to read this blog post about [10 Commands to Get Started with Git](https://rviews.rstudio.com/2020/04/23/10-commands-to-get-started-with-git/) with screenshots of the Rstudio web-based interface. + +::::::::::::::::::::::::::::: + +## Create project + RStudio allows us to create a [project][rstudio-projects] associated with a given directory to keep track of various related files. To be able to track the development of the project over time, to be able to revert to previous @@ -37,6 +45,14 @@ our computer, we choose the option "Existing Directory": ![](fig/RStudio_screenshot_existingdirectory.png){alt='RStudio screenshot showing New Project dialog window with "Create project from existing directory" selected'} +For a new directory, [follow the steps in this section about "Versioning new work"](https://nceas.github.io/oss-lessons/version-control/4-getting-started-with-git-in-RStudio.html#versioning_new_work). + +![](fig/git-rstudio-init-02.png) + +To clone a remote repository from Rstudio, follow these steps: + +![](fig/git-rstudio-init-03.png) + ::::::::::::::::::::::::::::::::::::::::: callout ## Do You See a "Version Control" Option? @@ -84,6 +100,8 @@ Next, RStudio will ask which existing directory we want to use. Click ![](fig/RStudio_screenshot_navigateexisting.png) + + 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 recognized that the current directory is a Git repository, and gives us a @@ -97,11 +115,19 @@ about Pluto: ![](fig/RStudio_screenshot_editfiles.png) + + 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'} +You can also use the buttons from the Git tab, usually in the upper right pane: + +![](fig/git-rstudio-git-tab-01.png) + + + 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 message (in the upper right panel). The icons in the "Status" column indicate @@ -111,6 +137,8 @@ way we want it, we click "Commit": ![](fig/RStudio_screenshot_review.png) + + 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: @@ -128,11 +156,15 @@ 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) + + 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` file: @@ -150,12 +182,60 @@ files and directories. :::::::::::::::::::::::::::::::::::::::::::::::::: + +In the `Rstudio: Review changes` window, you can also open the `.gitignore` files from the `Ignore` button. You can use the `Revert` button to do a `git checkout HEAD`, i.e., to undo changes not yet on staging area by restoring the local repository (last commit). + +![](fig/git-rstudio-review-window.png) + +## Create a branch + +Sometimes you want to experiment with your project without affecting the main version. You can do this by using branches. A branch is a local copy of the main project (also called the `main` branch) where you can make changes and test new ideas. The `main` branch stays safe and unchanged while you work on your branch (a.k.a., `feature branch`). When you are satisfied with the changes, you can merge them into the main branch. This means that the separate lines of development in your branch are combined with the main branch. + +![One feature branch and one main branch in Git.](fig/one-branch.png) + +You can have more than one branch off of your main copy. If one of your branches ends up not working, you can either abandon it or delete it without impacting the main branch of your project. + +![Two feature branches and one main branch in Git.](fig/two-branches.png) + +In the Git tab, in the right hand side you will find the name of your current branch (e.g., `main`). Use the button in its left hand side to create a branch. + +![](fig/pane-git-02.png) + +You can call it `feature-branch`: + +![](fig/github-12.png) + +You are able to switch between different branches using the menu displayed when you click in the branch name: + +![](fig/github-13.png) + +Git is a Version control software optimized for plain-text files. This can register non-linear changes. + +::::::::::::::::: checklist + +### Checklist + +Key characteristics of Version control systems are: + +1. Keep the entire history of a file and inspect a file throughout its lifetime. + +2. Tag a particular version so you can return to them easily. + +3. Facilitates collaborations and makes contributions transparent. + +4. Experiment with code and feature without breaking the main project + +::::::::::::::::::::::::::: + + +The best way to merge branches is on GitHub. We recommend you to read about how to [create a Pull Request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request), and how to [merge a Pull Request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/merging-a-pull-request) + ::::::::::::::::::::::::::::::::::::::: challenge ## Challenge -1. Create a new directory within your project called `graphs`. -2. Modify the `.gitignore` so that the `graphs` directory is not version controlled. +1. Create a new directory within your project called `tests`. +2. Modify the `.gitignore` so that the `tests` directory is not version controlled. ::::::::::::::: solution @@ -164,11 +244,11 @@ files and directories. This can be done in Rstudio: ```r -dir.create("./graphs") +usethis::use_directory("tests") ``` Then open up the `.gitignore` file from the right-hand panel of Rstudio and add -`graphs/` to the list of files to ignore. +`tests/` to the list of files to ignore. @@ -182,10 +262,10 @@ enough to get you started! [rstudio]: https://www.rstudio.com/ [rstudio-projects]: https://support.rstudio.com/hc/en-us/articles/200526207-Using-Projects - :::::::::::::::::::::::::::::::::::::::: keypoints - Using RStudio's Git integration allows you to version control a project over time. +- Feature branches help you experiment with code without breaking the main project. :::::::::::::::::::::::::::::::::::::::::::::::::: diff --git a/episodes/15-wrapup.md b/episodes/15-wrapup.md new file mode 100644 index 0000000000..4038c81576 --- /dev/null +++ b/episodes/15-wrapup.md @@ -0,0 +1,100 @@ +--- +title: Wrap-up +teaching: 5 +exercises: 0 +--- + +::::::::::::::::::::::::::::::::::::::: objectives + +- Show the final concept map of the workshop. +- Share a self-assessment review checklist. +- Remind our communication forum. +- Share the feedback form of the workshop. + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +:::::::::::::::::::::::::::::::::::::::: questions + +- Where is a full view of the concepts covered today? + +- Where can I ask for questions after this workshop? +- Where can I write my feedback on this workshop? + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +## Praise yourself! + +First of all: + +```r +# install.packages("praise") +praise::praise() +``` + +## The goal + +::::::::::::::::: checklist + +![Complete workflow with actions, `git verb` commands, and spaces.](fig/cut-git-verb_map-11.png) + +::::::::::::::::::::::::::: + +## Your next step! + +Good job! We recommend you to __read the supplemental episode__ on how to [use Git with the Rstudio IDE](14-supplemental-rstudio.md). It can make some steps easier to interact with! This also includes a section on how to [create new branches](14-supplemental-rstudio.md#create-a-branch) to experiment new features without affecting the main branch! + +Also! You've now fulfill the core prerequisites for the tutorial on [Improve your code for Epidemic analysis with R](https://epiverse-trace.github.io/research-compendium/introduction.html#why-improve-our-code-for-epidemic-analysis)! + +With `R`, `Git` and `GitHub` you will now extend your skills with a Research compendium, a Reproducible environment, and informative READMEs! + +## Write an individual learning reflection + +Before we wrap up, please take 5 minutes to think over everything we have covered so far. + +- On a piece of paper, write down something that captures what you want to remember about the day. +- The Instructor will not look at this - it is just for you. + +If you do not know where to start, consider the following list for a starting point: + +- Draw a concept map, connecting the material +- Draw pictures or a comic depicting one of the day's concepts +- Write an outline of the topics we covered +- Write a paragraph or "journal" entry about your experience of the workshop today +- Write down one thing that struck you the most + +This exercise should take about 5 minutes. + +## Our communication channel + +:::checklist + +We remind you of our _communication forum_ called [GitHub Discussions](https://github.com/epiverse-trace/git-rstudio-basics/discussions). Here we will ask and solve our and your question on the topic! + +You can fill your questions under the [Q&A category](https://github.com/epiverse-trace/git-rstudio-basics/discussions/categories/q-a)... at any time in the future! + +::: + +## Your constructive feedback + +This form is anonymous: + +If you did not fill out this form, please take 5 minutes to fill it. This form will be beneficial for further improvements to our workshop. + +## Complementary readings + +- A checklist [Make Use of Git from The Turing Way](https://the-turing-way.netlify.app/reproducible-research/vcs/vcs-checklist.html) +- A blog [An introduction to Git and how to use it with RStudio · The R class (r-bio.github.io)](https://r-bio.github.io/intro-git-rstudio/) +- A book [Let’s Git started | Happy Git and GitHub for the useR (happygitwithr.com)](https://happygitwithr.com/index.html) +- A webinar [Managing - Part 2 (Github and RStudio) - RStudio](https://www.rstudio.com/resources/webinars/managing-part-2-github-and-rstudio/) +- A forum [svn - Why should I use version control? - Stack Overflow](https://stackoverflow.com/questions/1408450/why-should-i-use-version-control) +- A forum [git - R and version control for the solo data analyst - Stack Overflow](https://stackoverflow.com/questions/2712421/r-and-version-control-for-the-solo-data-analyst) +- A newsletter + +:::::::::::::::::::::::::::::::::::::::: keypoints + +- Read the tutorial on 'Improve your code for Epidemic analysis with R'. +- Use the `GitHub Discussions` as our communication forum after the workshop. +- Use the feedback form to share your constructive comments. + +:::::::::::::::::::::::::::::::::::::::::::::::::: + diff --git a/episodes/fig/ProjectHistory.jpg b/episodes/fig/ProjectHistory.jpg new file mode 100644 index 0000000000..09e49cc439 Binary files /dev/null and b/episodes/fig/ProjectHistory.jpg differ diff --git a/episodes/fig/cut-git-verb_map-00.png b/episodes/fig/cut-git-verb_map-00.png new file mode 100644 index 0000000000..d587d18bf9 Binary files /dev/null and b/episodes/fig/cut-git-verb_map-00.png differ diff --git a/episodes/fig/cut-git-verb_map-01.png b/episodes/fig/cut-git-verb_map-01.png new file mode 100644 index 0000000000..5a3708c90c Binary files /dev/null and b/episodes/fig/cut-git-verb_map-01.png differ diff --git a/episodes/fig/cut-git-verb_map-07.png b/episodes/fig/cut-git-verb_map-07.png new file mode 100644 index 0000000000..8a820f8e7c Binary files /dev/null and b/episodes/fig/cut-git-verb_map-07.png differ diff --git a/episodes/fig/cut-git-verb_map-08.png b/episodes/fig/cut-git-verb_map-08.png new file mode 100644 index 0000000000..42dd0f5770 Binary files /dev/null and b/episodes/fig/cut-git-verb_map-08.png differ diff --git a/episodes/fig/cut-git-verb_map-09.png b/episodes/fig/cut-git-verb_map-09.png new file mode 100644 index 0000000000..ba2ab99c24 Binary files /dev/null and b/episodes/fig/cut-git-verb_map-09.png differ diff --git a/episodes/fig/cut-git-verb_map-10.png b/episodes/fig/cut-git-verb_map-10.png new file mode 100644 index 0000000000..cfaa682f11 Binary files /dev/null and b/episodes/fig/cut-git-verb_map-10.png differ diff --git a/episodes/fig/cut-git-verb_map-11.png b/episodes/fig/cut-git-verb_map-11.png new file mode 100644 index 0000000000..2d2783a0f6 Binary files /dev/null and b/episodes/fig/cut-git-verb_map-11.png differ diff --git a/episodes/fig/cut-git-verb_map-12.png b/episodes/fig/cut-git-verb_map-12.png new file mode 100644 index 0000000000..c17c3dc98e Binary files /dev/null and b/episodes/fig/cut-git-verb_map-12.png differ diff --git a/episodes/fig/gdocs-01.png b/episodes/fig/gdocs-01.png new file mode 100644 index 0000000000..26f6225e81 Binary files /dev/null and b/episodes/fig/gdocs-01.png differ diff --git a/episodes/fig/gdocs-02.png b/episodes/fig/gdocs-02.png new file mode 100644 index 0000000000..0b62377765 Binary files /dev/null and b/episodes/fig/gdocs-02.png differ diff --git a/episodes/fig/gdocs-03.png b/episodes/fig/gdocs-03.png new file mode 100644 index 0000000000..33dcd18214 Binary files /dev/null and b/episodes/fig/gdocs-03.png differ diff --git a/episodes/fig/gdocs-04.png b/episodes/fig/gdocs-04.png new file mode 100644 index 0000000000..4cf1945e71 Binary files /dev/null and b/episodes/fig/gdocs-04.png differ diff --git a/episodes/fig/git-commit.png b/episodes/fig/git-commit.png new file mode 100644 index 0000000000..a814ddadc8 Binary files /dev/null and b/episodes/fig/git-commit.png differ diff --git a/episodes/fig/git-concept-03.drawio.png b/episodes/fig/git-concept-03.drawio.png new file mode 100644 index 0000000000..4c4a0f2d3b Binary files /dev/null and b/episodes/fig/git-concept-03.drawio.png differ diff --git a/episodes/fig/git-freshly-made-github-repo.png b/episodes/fig/git-freshly-made-github-repo.png new file mode 100644 index 0000000000..32ff6d840c Binary files /dev/null and b/episodes/fig/git-freshly-made-github-repo.png differ diff --git a/episodes/fig/git-manual-version-system.png b/episodes/fig/git-manual-version-system.png new file mode 100644 index 0000000000..288f841ff3 Binary files /dev/null and b/episodes/fig/git-manual-version-system.png differ diff --git a/episodes/fig/git-rstudio-06.png b/episodes/fig/git-rstudio-06.png new file mode 100644 index 0000000000..f52aec43ef Binary files /dev/null and b/episodes/fig/git-rstudio-06.png differ diff --git a/episodes/fig/git-rstudio-07.png b/episodes/fig/git-rstudio-07.png new file mode 100644 index 0000000000..5c64336cea Binary files /dev/null and b/episodes/fig/git-rstudio-07.png differ diff --git a/episodes/fig/git-rstudio-08.png b/episodes/fig/git-rstudio-08.png new file mode 100644 index 0000000000..c283c4750c Binary files /dev/null and b/episodes/fig/git-rstudio-08.png differ diff --git a/episodes/fig/git-rstudio-27.png b/episodes/fig/git-rstudio-27.png new file mode 100644 index 0000000000..80eda9f8c0 Binary files /dev/null and b/episodes/fig/git-rstudio-27.png differ diff --git a/episodes/fig/git-rstudio-35.png b/episodes/fig/git-rstudio-35.png new file mode 100644 index 0000000000..49c86c26bc Binary files /dev/null and b/episodes/fig/git-rstudio-35.png differ diff --git a/episodes/fig/git-rstudio-git-tab-01.png b/episodes/fig/git-rstudio-git-tab-01.png new file mode 100644 index 0000000000..2a41820384 Binary files /dev/null and b/episodes/fig/git-rstudio-git-tab-01.png differ diff --git a/episodes/fig/git-rstudio-init-02.png b/episodes/fig/git-rstudio-init-02.png new file mode 100644 index 0000000000..6244e03076 Binary files /dev/null and b/episodes/fig/git-rstudio-init-02.png differ diff --git a/episodes/fig/git-rstudio-init-03.png b/episodes/fig/git-rstudio-init-03.png new file mode 100644 index 0000000000..5b35a004b9 Binary files /dev/null and b/episodes/fig/git-rstudio-init-03.png differ diff --git a/episodes/fig/git-rstudio-review-window.png b/episodes/fig/git-rstudio-review-window.png new file mode 100644 index 0000000000..107cc338b4 Binary files /dev/null and b/episodes/fig/git-rstudio-review-window.png differ diff --git a/episodes/fig/git-token.png b/episodes/fig/git-token.png new file mode 100644 index 0000000000..d2ad95a0eb Binary files /dev/null and b/episodes/fig/git-token.png differ diff --git a/episodes/fig/github-12.png b/episodes/fig/github-12.png new file mode 100644 index 0000000000..f8e9d7567d Binary files /dev/null and b/episodes/fig/github-12.png differ diff --git a/episodes/fig/github-13.png b/episodes/fig/github-13.png new file mode 100644 index 0000000000..80040a29ac Binary files /dev/null and b/episodes/fig/github-13.png differ diff --git a/episodes/fig/github-collab-10.png b/episodes/fig/github-collab-10.png new file mode 100644 index 0000000000..66a684cae3 Binary files /dev/null and b/episodes/fig/github-collab-10.png differ diff --git a/episodes/fig/github-collab-11.png b/episodes/fig/github-collab-11.png new file mode 100644 index 0000000000..489f4de05f Binary files /dev/null and b/episodes/fig/github-collab-11.png differ diff --git a/episodes/fig/github-collaboration.png b/episodes/fig/github-collaboration.png new file mode 100644 index 0000000000..02df42d1dc Binary files /dev/null and b/episodes/fig/github-collaboration.png differ diff --git a/episodes/fig/github-create-00.png b/episodes/fig/github-create-00.png new file mode 100644 index 0000000000..9e028e6687 Binary files /dev/null and b/episodes/fig/github-create-00.png differ diff --git a/episodes/fig/github-create-01.png b/episodes/fig/github-create-01.png new file mode 100644 index 0000000000..85f2f1e681 Binary files /dev/null and b/episodes/fig/github-create-01.png differ diff --git a/episodes/fig/github-create-02.png b/episodes/fig/github-create-02.png new file mode 100644 index 0000000000..b1e3bd4cb5 Binary files /dev/null and b/episodes/fig/github-create-02.png differ diff --git a/episodes/fig/github-create-03.png b/episodes/fig/github-create-03.png new file mode 100644 index 0000000000..a441cea546 Binary files /dev/null and b/episodes/fig/github-create-03.png differ diff --git a/episodes/fig/github-create-repo-01.png b/episodes/fig/github-create-repo-01.png index 6dc6bf2195..cdb0c64b6c 100644 Binary files a/episodes/fig/github-create-repo-01.png and b/episodes/fig/github-create-repo-01.png differ diff --git a/episodes/fig/github-create-repo-02.png b/episodes/fig/github-create-repo-02.png index 5981881cda..b82adb9b9f 100644 Binary files a/episodes/fig/github-create-repo-02.png and b/episodes/fig/github-create-repo-02.png differ diff --git a/episodes/fig/github-create-repo-03.png b/episodes/fig/github-create-repo-03.png index ebce87d5e6..bc49e7161b 100644 Binary files a/episodes/fig/github-create-repo-03.png and b/episodes/fig/github-create-repo-03.png differ diff --git a/episodes/fig/github-find-repo-string.png b/episodes/fig/github-find-repo-string.png index 97d339bd72..bff093787d 100644 Binary files a/episodes/fig/github-find-repo-string.png and b/episodes/fig/github-find-repo-string.png differ diff --git a/episodes/fig/github-repo-after-first-push.png b/episodes/fig/github-repo-after-first-push.png new file mode 100644 index 0000000000..f5086790ab Binary files /dev/null and b/episodes/fig/github-repo-after-first-push.png differ diff --git a/episodes/fig/googledocs-collab.png b/episodes/fig/googledocs-collab.png new file mode 100644 index 0000000000..19b7baf85f Binary files /dev/null and b/episodes/fig/googledocs-collab.png differ diff --git a/episodes/fig/gradient-reproducibility.png b/episodes/fig/gradient-reproducibility.png new file mode 100644 index 0000000000..f0bb927dc0 Binary files /dev/null and b/episodes/fig/gradient-reproducibility.png differ diff --git a/episodes/fig/main-branch.png b/episodes/fig/main-branch.png new file mode 100644 index 0000000000..bf511726c1 Binary files /dev/null and b/episodes/fig/main-branch.png differ diff --git a/episodes/fig/non-reproducible-workflow.png b/episodes/fig/non-reproducible-workflow.png new file mode 100644 index 0000000000..38b9706815 Binary files /dev/null and b/episodes/fig/non-reproducible-workflow.png differ diff --git a/episodes/fig/one-branch.png b/episodes/fig/one-branch.png new file mode 100644 index 0000000000..f6c71bfed9 Binary files /dev/null and b/episodes/fig/one-branch.png differ diff --git a/episodes/fig/pane-git-01.png b/episodes/fig/pane-git-01.png new file mode 100644 index 0000000000..f77835cae1 Binary files /dev/null and b/episodes/fig/pane-git-01.png differ diff --git a/episodes/fig/pane-git-02.png b/episodes/fig/pane-git-02.png new file mode 100644 index 0000000000..d8894cf7fb Binary files /dev/null and b/episodes/fig/pane-git-02.png differ diff --git a/episodes/fig/plain-text-files.png b/episodes/fig/plain-text-files.png new file mode 100644 index 0000000000..01d745162c Binary files /dev/null and b/episodes/fig/plain-text-files.png differ diff --git a/episodes/fig/rstudio-tab-console.png b/episodes/fig/rstudio-tab-console.png new file mode 100644 index 0000000000..44b3b04b7e Binary files /dev/null and b/episodes/fig/rstudio-tab-console.png differ diff --git a/episodes/fig/rstudio-tab-terminal.png b/episodes/fig/rstudio-tab-terminal.png new file mode 100644 index 0000000000..9b46d4336a Binary files /dev/null and b/episodes/fig/rstudio-tab-terminal.png differ diff --git a/episodes/fig/terminal-basic.png b/episodes/fig/terminal-basic.png new file mode 100644 index 0000000000..c201dc2c8a Binary files /dev/null and b/episodes/fig/terminal-basic.png differ diff --git a/episodes/fig/topic-git.png b/episodes/fig/topic-git.png new file mode 100644 index 0000000000..7ee6311168 Binary files /dev/null and b/episodes/fig/topic-git.png differ diff --git a/episodes/fig/two-branches.png b/episodes/fig/two-branches.png new file mode 100644 index 0000000000..111541b18c Binary files /dev/null and b/episodes/fig/two-branches.png differ diff --git a/episodes/fig/wolfman_dracula-02.jpg b/episodes/fig/wolfman_dracula-02.jpg new file mode 100644 index 0000000000..0fca5f63d3 Binary files /dev/null and b/episodes/fig/wolfman_dracula-02.jpg differ diff --git a/episodes/fig/wolfman_dracula-03.jpg b/episodes/fig/wolfman_dracula-03.jpg new file mode 100644 index 0000000000..499460730e Binary files /dev/null and b/episodes/fig/wolfman_dracula-03.jpg differ diff --git a/index.md b/index.md index 424022b280..894a12ae9d 100644 --- a/index.md +++ b/index.md @@ -3,17 +3,34 @@ permalink: index.html site: sandpaper::sandpaper_site --- -Wolfman and Dracula have been hired by Universal Missions (a space -services spinoff from Euphoric State University) to investigate if it -is possible to send their next planetary lander to Mars. They want to -be able to work on the plans at the same time, but they have run into -problems doing this in the past. If they take turns, each one will -spend a lot of time waiting for the other to finish, but if they work -on their own copies and email changes back and forth things will be +> Do you want to participate in a live workshop? +> [Sign up in our announcement page!](https://epiverse-trace.github.io/learn/git-training-01/) + +## Motivation + +Reproducible science not only reduce errors, but speeds up the process of re-runing your analysis and auto-generate updated documents with the results. **Git is an essential part of this process!** + +!["A reproducible workflow". 1:44 minutes. Video by Ignasi Bartomeus (@ibartomeus) & Francisco Rodríguez-Sánchez (@frod_san). CC-by, ](episodes/fig/non-reproducible-workflow.png){alt='Video: A Non Reproducible Workflow'} + +## The scenario + +![Image by Bing, 2023, [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/), created with [Bing Image Creator powered by DALL·E 3](https://www.bing.com/create)](episodes/fig/wolfman_dracula-03.jpg){alt='wolfman and dracula using computers for data analysis'} + +Wolfman and Dracula have been hired as data analysts by Outbreak Missions (a Rapid Support Team for outbreak response services) to investigate a disease outbreak. +They want to be able to work on the development of a reproducible [Situation report](https://choleraoutbreak.org/book-page/appendix-7-outline-outbreak-situation-report) +at the same time, but they have run into +problems doing this in the past. + +- If they take turns, each one will +spend a lot of time waiting for the other to finish, but +- if they work on their own copies and email changes back and forth things will be lost, overwritten, or duplicated. A colleague suggests using [version control](learners/reference.md#version-control) to -manage their work. Version control is better than mailing files back and forth: +manage their work! + + :::::::::::::::::::::::::::::::::::::::::: prereq ## Prerequisites -In this lesson we use Git from the Unix Shell. -Some previous experience with the shell is expected, +In this lesson we use Git from Rstudio. +Some previous experience with R and Bash is expected, *but isn't mandatory*. diff --git a/learners/discuss.md b/learners/discuss.md index def35b113a..56806c3d15 100644 --- a/learners/discuss.md +++ b/learners/discuss.md @@ -2,10 +2,13 @@ title: Discussion --- +## Your questions + +[Write your question as a Q&A](https://github.com/epiverse-trace/git-rstudio-basics/discussions/new/choose). Your question will appear in the `Discussions` tab of the GitHub repository of this material. + ## Frequently Asked Questions -People often have questions about Git beyond the scope of the core material. -Students who have completed the rest of the lessons might find value in looking through the following topics. +People often have questions about Git beyond the scope of the core material. Students who have completed the rest of the lessons might find value in looking through the following topics. Note that since this material isn't essential for basic Git usage, it won't be covered by the instructor. diff --git a/learners/reference.md b/learners/reference.md index 88b7f30695..e6925453ec 100644 --- a/learners/reference.md +++ b/learners/reference.md @@ -4,6 +4,7 @@ title: 'Git Cheatsheets for Quick Reference' ## Git Cheatsheets for Quick Reference +- [Git Reference documentation](https://git-scm.com/docs) with technical descriptions of the machinery and how to operate it. - Printable Git cheatsheets in several languages are [available here](https://github.github.com/training-kit/) ([English version](https://github.github.com/training-kit/downloads/github-git-cheat-sheet.pdf)). More material is available from the [GitHub training website](https://try.github.io/). - An [interactive one-page visualisation](https://ndpsoftware.com/git-cheatsheet.html) about the relationships between workspace, staging area, local repository, upstream repository, and the commands associated with each (with explanations). diff --git a/learners/setup.md b/learners/setup.md index fc90de6773..18ff8e7b70 100644 --- a/learners/setup.md +++ b/learners/setup.md @@ -2,16 +2,37 @@ title: Setup --- +## Install R and Rstudio + +Follow these instructions + +### Install R packages + +These installation steps could ask you `? Do you want to continue (Y/n)` write `y` and press ENTER. + +Install all these packages: + +```r +if(!require("pak")) install.packages("pak") + +new <- c("gh", + "usethis", + "tidyverse", + "here") + +pak::pak(new) +``` + ## Installing Git -Since several Carpentries lessons rely on Git, please see -[this section of the workshop template][workshop-setup] for -instructions on installing Git for various operating systems. +Follow this instructions on installing Git for various operating systems. - [Git installation on Windows][workshop-setup] - [Git installation on MacOS][workshop-setup] - [Git installation on Linux][workshop-setup] +You can also follow [happygitwithr recommendations](https://happygitwithr.com/install-git.html) for each Operating system. + ## Creating a GitHub Account You will need an account for [GitHub](https://github.com) to follow episodes 7 & 8 in this lesson. @@ -44,6 +65,7 @@ Several options exist for setting up 2FA, which are summarised here: The GitHub documentation provides [more details about configuring 2FA](https://docs.github.com/en/authentication/securing-your-account-with-two-factor-authentication-2fa/configuring-two-factor-authentication). + [workshop-setup]: https://carpentries.github.io/workshop-template/install_instructions/#git