diff --git a/07-github.md b/07-github.md index 2ec737f5d5..99e78a9dd6 100644 --- a/07-github.md +++ b/07-github.md @@ -281,7 +281,7 @@ This command will push the changes from our local repository to the repository on GitHub: ```bash -$ git push +$ git push origin main ``` Since Dracula set up a passphrase, it will prompt him for it. If you completed advanced settings for your authentication, it @@ -397,7 +397,7 @@ $ git push We can pull changes from the remote repository to the local one as well: ```bash -$ git pull +$ git pull origin main ``` ```output @@ -459,11 +459,24 @@ To pull changes from remote to local, use this command: $ git pull ``` +If you are interested on how to write good READMEs, we invite you to review a dedicated episode in the [Improve your code for Epidemic Analysis with R](https://epiverse-trace.github.io/research-compendium/) tutorial website! ::::::::::::::::::::::::: :::::::::::::::::::::::::::::::::::::::::::::::::: +::::::::::::::::::::::::: testimonial + +### Share your online repository! + +This tutorial have a **Discussions** board also hosted in GitHub. + +1. Access to this [Welcome entry](https://github.com/epiverse-trace/git-rstudio-basics/discussions/10) + +2. Share with us a link to the `case` repository you just uploaded! (For example, this is the link to the repository of one of our participants ) + +::::::::::::::::::::::::: + ::::::::::::::::: 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) diff --git a/08-collab.md b/08-collab.md index c75e71a84e..c34e2d1631 100644 --- a/08-collab.md +++ b/08-collab.md @@ -184,7 +184,7 @@ Take a look at the Owner's repository on GitHub again, and you should be able to see the new commit made by the Collaborator. You may need to refresh your browser to see the new commit. -::::::::::::::::::::::::::::::::::::::::: callout +::::::::::::::::::::::::::::::::::::::::: spoiler ## Some more about remotes @@ -267,14 +267,6 @@ read and review. :::::::::::::::::::::::::::::::::::::::::::::::::: -::::::::::::::::::::::::::::::::::::::: challenge - -## Switch Roles and Repeat - -Switch roles and repeat the whole process. - - -:::::::::::::::::::::::::::::::::::::::::::::::::: ::::::::::::::::::::::::::::::::::::::: challenge @@ -288,20 +280,37 @@ command line? And on GitHub? ## Solution -On the command line, the Collaborator can use `git fetch origin main` +**On GitHub**, the Collaborator can go to the repository and click on +"commits" to view the most recent commits pushed to the repository. + +![Click on "commit". Select one commit.](fig/github-commits-button.png) + +![Replace age with sex commit. The removed content within lines is in red. The added content within lines is in green.](fig/github-commit-diff.png) + +On the **command line**, the Collaborator can use `git fetch origin main` to get the remote changes into the local repository, but without merging them. Then by running `git diff main origin/main` the Collaborator 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) ::::::::::::::::::::::::: :::::::::::::::::::::::::::::::::::::::::::::::::: +## Group challenge + +::::::::::::::::::::::::::::::::::::::: challenge + +## Switch Roles and Repeat + +Switch roles and repeat the whole process. + + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +## Individual challenges + ::::::::::::::::::::::::::::::::::::::: challenge ## Comment Changes in GitHub @@ -332,7 +341,7 @@ What are some of the benefits of using version control, Git and GitHub? ### Create your GitHub profile! -Your profile page introduce you to other contributors on GitHub: +Now your work will be visible online on GitHub. Your profile page introduce you to other contributors on GitHub: ![](fig/github-create-00.png) diff --git a/09-conflict.md b/09-conflict.md index 3b4aaab6d6..4cb56ee1bf 100644 --- a/09-conflict.md +++ b/09-conflict.md @@ -40,6 +40,191 @@ 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. +Before resolving conflicts, we'll review two features that a **good collaborator** puts in practice: Create branches and Atomic commits. + +## Create branches + +First, verify that you are working on the main branch: + +```bash +$ git status +``` + +```output +On branch main +``` + +The `git branch` command **creates** a branch of the name `newbranch`: + +```bash +$ git branch newbranch +``` + +The `git checkout` command **switch** from the current branch (in this case, `main`) to the `newbranch`: + +```bash +$ git checkout newbranch +``` + +```output +Switched to branch 'newbranch' +``` + +Now, you can confirm that we are in `newbranch` using `git status`: + +```bash +$ git status +``` + +```output +On branch newbranch +nothing to commit, working tree clean +``` + +Now, let's make an edit to the `sitrep.Rmd` file: + +```r +usethis::edit_file("sitrep.Rmd") +``` + +```output +Comparison of attack rates in different age groups +This can identify priority groups for interventions +Maps illustrate the spread and impact of outbreak +Use packages listed in the CRAN Task View: Epidemiology +``` + +Add and commit this change to the local repository: + +```bash +$ git add sitrep.Rmd +$ git commit -m "Add edit in new branch" +``` + +```output +[newbranch 60d5ff9] Add edit in new branch + 1 file changed, 1 insertion(+) +``` + +Push commit to the remote repository. NOTE: instead of `git push origin main`, we replace `main` with the name of the new branch: + +```bash +$ git push origin newbranch +``` + +```output +Enumerating objects: 5, done. +Counting objects: 100% (5/5), done. +Delta compression using up to 12 threads +Compressing objects: 100% (3/3), done. +Writing objects: 100% (3/3), 339 bytes | 169.00 KiB/s, done. +Total 3 (delta 2), reused 0 (delta 0), pack-reused 0 +remote: Resolving deltas: 100% (2/2), completed with 2 local objects. +remote: +remote: Create a pull request for 'newbranch' on GitHub by visiting: +remote: https://github.com/vlad/cases/pull/new/newbranch +remote: +To https://github.com/vlad/cases.git + * [new branch] newbranch -> newbranch +``` + +On GitHub, we get a notification to Create a **Pull Request**: + +![](fig/github-branch-pullrequest.png) + +In your local repository, you can leave your work parked for a while on that branch. To return to `main` (or to any other branch), you can use the same command to **switch** between branches: + +```bash +$ git checkout main +``` + +```output +Switched to branch 'main' +Your branch is up to date with 'origin/main'. +``` + +## 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. + +::::::::::::::::::::::::::: + +## Group Challenge + +::::::::::::::::::::::::::::::::::::::: challenge + +## A Typical Work Session + +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.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 +- *Stage changes* to be committed +- *Commit changes* to the local repository + +In what order should you perform these actions to minimize the chances of +conflicts? Put the commands above in order in the *action* column of the table +below. When you have the order right, see if you can write the corresponding +commands in the *command* column. A few steps are populated to get you +started. + +| order | action . . . . . . . . . . | command . . . . . . . . . . | +| ----- | -------------------------- | --------------------------------------------- | +| 1 | | | +| 2 | | `echo 100 >> numbers.md` | +| 3 | | | +| 4 | | | +| 5 | | | +| 6 | Celebrate! | `AFK` | + +::::::::::::::: solution + +## Solution + +| order | action . . . . . . | command . . . . . . . . . . . . . . . . . . . | +| ----- | -------------------------- | --------------------------------------------- | +| 1 | Update local | `git pull origin main` | +| 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` | + +::::::::::::::::::::::::: + +:::::::::::::::::::::::::::::::::::::::::::::::::: + + ## Create a conflict To see how we can resolve conflicts, we must first create one. The file @@ -363,21 +548,6 @@ 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 @@ -554,86 +724,21 @@ 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. +### Good practices -- Isolate or includes multiple edited lines using the "Stage chunk" button in Rstudio. +A good collaborator: -- Does not include all the files in one commit. +- 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 - -::::::::::::::::::::::::::::::::::::::: challenge - -## A Typical Work Session - -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.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 -- *Stage changes* to be committed -- *Commit changes* to the local repository - -In what order should you perform these actions to minimize the chances of -conflicts? Put the commands above in order in the *action* column of the table -below. When you have the order right, see if you can write the corresponding -commands in the *command* column. A few steps are populated to get you -started. - -| order | action . . . . . . . . . . | command . . . . . . . . . . | -| ----- | -------------------------- | --------------------------------------------- | -| 1 | | | -| 2 | | `echo 100 >> numbers.md` | -| 3 | | | -| 4 | | | -| 5 | | | -| 6 | Celebrate! | `AFK` | - -::::::::::::::: solution - -## Solution - -| order | action . . . . . . | command . . . . . . . . . . . . . . . . . . . | -| ----- | -------------------------- | --------------------------------------------- | -| 1 | Update local | `git pull origin main` | -| 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` | - -::::::::::::::::::::::::: - -:::::::::::::::::::::::::::::::::::::::::::::::::: :::::::::::::::::::::::::::::::::::::::: keypoints diff --git a/fig/github-branch-pullrequest.png b/fig/github-branch-pullrequest.png new file mode 100644 index 0000000000..182ebd83ad Binary files /dev/null and b/fig/github-branch-pullrequest.png differ diff --git a/fig/github-commit-diff.png b/fig/github-commit-diff.png new file mode 100644 index 0000000000..a505a10ac2 Binary files /dev/null and b/fig/github-commit-diff.png differ diff --git a/fig/github-commits-button.png b/fig/github-commits-button.png new file mode 100644 index 0000000000..bca0d46885 Binary files /dev/null and b/fig/github-commits-button.png differ diff --git a/md5sum.txt b/md5sum.txt index 17ebbe304a..52b15dc13c 100644 --- a/md5sum.txt +++ b/md5sum.txt @@ -9,9 +9,9 @@ "episodes/03-create.md" "3de74dd9f5ec301adc963ef4ee82ce65" "site/built/03-create.md" "2024-03-04" "episodes/04-changes.md" "23fc29ac095df8ce832f17a4b8a7f23c" "site/built/04-changes.md" "2024-03-05" "episodes/06-ignore.md" "bf7a4188f28d1f08df906e2f38686eb6" "site/built/06-ignore.md" "2024-03-05" -"episodes/07-github.md" "c3f762bd6f37ea25ff4c04fb87d08f44" "site/built/07-github.md" "2024-03-05" -"episodes/08-collab.md" "6ac4663247065e11aeb1562f7f527b7a" "site/built/08-collab.md" "2023-11-27" -"episodes/09-conflict.md" "5b3ea92c07b4c0335bfa616bc27b1792" "site/built/09-conflict.md" "2023-11-27" +"episodes/07-github.md" "406efe5ece1cf7cbd177e81464ccc972" "site/built/07-github.md" "2024-03-05" +"episodes/08-collab.md" "8eded250e354509288962985418c37a4" "site/built/08-collab.md" "2024-03-05" +"episodes/09-conflict.md" "67e044f7679659e2159845e85a7ae527" "site/built/09-conflict.md" "2024-03-05" "episodes/15-wrapup.md" "41c58f051c2a58806f704649236a507e" "site/built/15-wrapup.md" "2023-11-27" "episodes/14-supplemental-rstudio.md" "64f77ad094bc5f8f1189ae22c9713440" "site/built/14-supplemental-rstudio.md" "2023-11-27" "episodes/05-history.md" "b4c1750b2abea51b7b75eacbfe477a29" "site/built/05-history.md" "2023-11-27"