From c170b3f3608fde5a0033415dac662d07543b52e6 Mon Sep 17 00:00:00 2001 From: Andree Valle Campos Date: Tue, 5 Mar 2024 04:35:59 +0000 Subject: [PATCH] prioritize using usethis + add push pull section and diff group and individual challenge --- episodes/07-github.md | 459 ++++++++++++++++++------------------------ 1 file changed, 194 insertions(+), 265 deletions(-) diff --git a/episodes/07-github.md b/episodes/07-github.md index d3dfceb47c..2ec737f5d5 100644 --- a/episodes/07-github.md +++ b/episodes/07-github.md @@ -41,7 +41,65 @@ and cons of this in a [later episode](13-hosting.md). Let's start by sharing the changes we've made to our current project with the world. To this end we are going to create a *remote* repository that will be linked to our *local* repository. -## 1\. Create a remote repository +## How to connect from Local to GitHub? + +From your local R project, after using `usethis::use_git()` to initialise your **Local repository**, then you can also use `{usethis}` to connect it with the **Remote repository** (a.k.a, "the remote"): + +```r +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. + +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. + +```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. +``` + +The `(can push)` line of the output above is critical! + +If you remember back to the earlier [episode](04-changes.md) where we added and +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.png){alt='Freshly-Made GitHub Repository'} + +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. + +We'll discuss remotes in more detail in the next episode, while +talking about how they might be used for collaboration. + +::::::::::::::::::::::::::::::::::: spoiler + +## How to connect from GitHub to Local? + +### 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 `cases`: @@ -83,7 +141,7 @@ Now that we have two repositories, we need a diagram like this: 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 +### 2\. Connect local to remote repository Now we connect the two repositories. We do this by making the GitHub repository a [remote](../learners/reference.md#remote) for the local repository. @@ -145,200 +203,85 @@ 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. - - -```output -The authenticity of host 'github.com (192.30.255.112)' can't be established. -RSA key fingerprint is SHA256:nThbg6kXUpJWGl7E1IGOCspRomTxdCARLviKw6E5SY8. -This key is not known by any other names -Are you sure you want to continue connecting (yes/no/[fingerprint])? y -Please type 'yes', 'no' or the fingerprint: yes -Warning: Permanently added 'github.com' (RSA) to the list of known hosts. -git@github.com: Permission denied (publickey). -``` +::::::::::::::::::::::::::::::::::: -Right, we forgot that we need to give GitHub our public key! +## Push local changes to a remote -First, we need to copy the public key. Be sure to include the `.pub` at the end, otherwise you're looking at the private key. +We can add new changes to the remote repository. +Let's make a change to `sitrep.Rmd`, adding yet another line. -```bash -cat ~/.ssh/id_ed25519.pub +```r +usethis::edit_file("sitrep.Rmd") ``` ```output -ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIDmRA3d51X0uu9wXek559gfn6UFNF69yZjChyBIU2qKI vlad@tran.sylvan.ia +Comparison of attack rates in different age groups +This can identify priority groups for interventions +Maps illustrate the spread and impact of outbreak +Read shapefiles with the {sf} R package ``` -Now, going to GitHub.com, click on your profile icon in the top right corner to get the drop-down menu. Click "Settings," then on the -settings page, click "SSH and GPG keys," on the left side "Account settings" menu. Click the "New SSH key" button on the right side. Now, -you can add the title (Dracula uses the title "Vlad's Lab Laptop" so he can remember where the original key pair -files are located), paste your SSH key into the field, and click the "Add SSH key" to complete the setup. - -Now that we've set that up, let's check our authentication again from the command line. +Add and commit this change to the local repository: ```bash -$ ssh -T git@github.com -``` - -```output -Hi Vlad! You've successfully authenticated, but GitHub does not provide shell access. +git add sitrep.Rmd +git commit -m "Add package to read spatial data" ``` -Good! This output confirms that the SSH key works as intended. We are now ready to push our work to the remote repository. ---> - -## 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 +This command will push the changes from our local repository to the repository on GitHub: ```bash -$ git push origin main +$ git push ``` Since Dracula set up a passphrase, it will prompt him for it. If you completed advanced settings for your authentication, it @@ -356,31 +299,7 @@ To https://github.com/vlad/cases.git * [new branch] main -> main ``` -::::::::::::::::::::::::::::::::::::::::: callout - -## Proxy - -If the network you are connected to uses a proxy, there is a chance that your -last command failed with "Could not resolve hostname" as the error message. To -solve this issue, you need to tell Git about the proxy: - -```bash -$ git config --global http.proxy http://user:password@proxy.url -$ git config --global https.proxy https://user:password@proxy.url -``` - -When you connect to another network that doesn't use a proxy, you will need to -tell Git to disable the proxy using: - -```bash -$ git config --global --unset http.proxy -$ git config --global --unset https.proxy -``` - -:::::::::::::::::::::::::::::::::::::::::::::::::: - - + Our local and remote repositories are now in this state: ![](fig/github-repo-after-first-push.png){alt='GitHub Repository After First Push'} -::::::::::::::::::::::::::::::::::::::::: callout +::::::::::::::::::::::::::::::::::::::::: spoiler ## The '-u' Flag @@ -421,23 +340,26 @@ command, and is used to associate the current branch with a remote branch so that the `git pull` command can be used without any arguments. To do this, 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: +1. Create new local repository for `interventions` and connect it with a remote repository. + +2. Create a `read-data.R` file. + +3. Add and commit that change to the local repository. -- First, if you are in Rstudio, close your R Project from `File` > `Close Project`. -- In the Console, run: +4. Push that change to the remote repository. + +::::::::::::::::: solutions + +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 @@ -452,27 +374,30 @@ usethis::use_git() 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' +Create the file + +```r +usethis::edit_file("read-data.R") ``` -This will open a new tab in your web browser with the URL path of your remote repository in GitHub. +In the Terminal, run: +```bash +$ git add read-data.R +$ git commit -m "Add read data file" +$ git push +``` ::::::::::::::::: - +:::::::::::::::::::::::::::::::::: ## Pull changes We can pull changes from the remote repository to the local one as well: ```bash -$ git pull origin main +$ git pull ``` ```output @@ -485,6 +410,69 @@ Pulling has no effect in this case because the two repositories are already synchronized. If someone else had pushed some changes to the repository on GitHub, though, this command would download them to our local repository. +## Group Challenges + +Take 5 minutes to solve this challenge! + +::::::::::::::::::::::::::::::::::::::: challenge + +## GitHub License and README files + +In this episode we learned about creating a remote repository on GitHub, but when you initialized your GitHub repo, you didn't add a README.md or a license file. + +1. Create a README file in the remote repository. + +2. Pull your changes from the remote to the local repository. + +::::::::::::::: hint + +Click in the **Add README** option. + +![](fig/readme-github-01.png) + +Copy and paste this minimal template of a `README.md` file: + +``` +# Situational Report + +This is a report for a disease outbreak investigation by Outbreak Missions. + +## Files + +- sitrep.Rmd + +## Authors + +- Wolfman +- Dracula +``` + +::::::::::::::: + +::::::::::::::: solution + +## Solution + +To pull changes from remote to local, use this command: + +```bash +$ git pull +``` + + +::::::::::::::::::::::::: + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +::::::::::::::::: 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) + +::::::::::::::::::::::::::: + + +## Individual Challenges + ::::::::::::::::::::::::::::::::::::::: challenge ## GitHub GUI @@ -579,65 +567,6 @@ Commit only updates your local repository. :::::::::::::::::::::::::::::::::::::::::::::::::: -::::::::::::::::::::::::::::::::::::::: challenge - -## GitHub License and README files - -In this episode we learned about creating a remote repository on GitHub, but when you initialized -your GitHub repo, you didn't add a README.md or a license file. If you had, what do you think -would have happened when you tried to link your local and remote repositories? - -::::::::::::::: solution - -## Solution - -In this case, we'd see a merge conflict due to unrelated histories. When GitHub creates a -README.md file, it performs a commit in the remote repository. When you try to pull the remote -repository to your local repository, Git detects that they have histories that do not share a -common origin and refuses to merge. - -```bash -$ git pull origin main -``` - -```output -warning: no common commits -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/cases - * branch main -> FETCH_HEAD - * [new branch] main -> origin/main -fatal: refusing to merge unrelated histories -``` - -You can force git to merge the two repositories with the option `--allow-unrelated-histories`. -Be careful when you use this option and carefully examine the contents of local and remote -repositories before merging. - -```bash -$ git pull --allow-unrelated-histories origin main -``` - -```output -From https://github.com/vlad/cases - * branch main -> FETCH_HEAD -Merge made by the 'recursive' strategy. -README.md | 1 + -1 file changed, 1 insertion(+) -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