From 1dae9fbaf05f67891f829261638dad9bdb80f1e2 Mon Sep 17 00:00:00 2001 From: Kate Hertweck Date: Tue, 16 Nov 2021 20:34:19 -0800 Subject: [PATCH 1/8] chapter outline without unix --- chapters/05-version-control-solo.Rmd | 72 ++++++++-------------------- 1 file changed, 21 insertions(+), 51 deletions(-) diff --git a/chapters/05-version-control-solo.Rmd b/chapters/05-version-control-solo.Rmd index aaf98f9c..07eb2a09 100644 --- a/chapters/05-version-control-solo.Rmd +++ b/chapters/05-version-control-solo.Rmd @@ -5,17 +5,20 @@ not showing output of git in code chunks (they are a pain to edit afterwards). Clearly identify which tasks are best accomplished by each interface. -- Using Git integration in RStudio (standard add-commit-history) -- Using Git in the Terminal of RStudio - - moving in history with checkout +- Using Git integration in RStudio + - standard add-commit + - view history - creating branches + - moving in history - adding and updating remotes -- Setting up GitHub for R package (make use of `usethis`), pushing and pulling +- `gert` and `usethis` commands for git; Setting up GitHub for R package +- working with remote repositories + - pushing and pulling ## Learning objectives * identify why version control, specifically Git, is important for software engineering -* differentiate methods for working with Git and R: RStudio integration, using shell commands in Terminal, `usethis` functions +* differentiate methods for working with Git and R: RStudio integration, `usethis` and `gert` functions * apply the change-stage-commit process as the Git workflow for tracking changes and viewing a repository's commit history * create branches to isolate work in progress and protect the main branch while working on major changes * publish repositories to GitHub and coordinate between remote and local versions @@ -24,7 +27,7 @@ Clearly identify which tasks are best accomplished by each interface. All text (no code): * why to use version control -* why to use Git as a version control system (popularity, GitHub, +* why to use Git as a version control system (popularity, GitHub) * how are Git and GitHub different? * local vs remote * publishing @@ -44,7 +47,7 @@ All text (no code): * creates hidden folder containing git history * some files ignored (note that it's possible to add other files to ignore) -### Tracking changes in RStudio +### Tracking changes All text and images: * exercise: work through basic workflow using RStudio integration @@ -57,63 +60,31 @@ All text and images: * exercise: create new file, commit, delete file, commit -### Viewing history in RStudio +### Working with version history All text and images: * click on clock button in Git pane (don't confuse with history tab; all git buttons are in Git tab) * explain fields: subject, author, date, SHA * click on a previous commit to see changes -## Git in Terminal - -* text: git on command line includes commands for full range of tasks, including those we've already covered: - * initialize repository: `git init` - * basic workflow: `git add` then `git commit` - * view history: `git log` - -### Exploring history in Terminal - -* code: make a change to README, then restore to previous (most recent) commit (pretend changes didn't exist, as if we changed our mind) - * `git status` - * `git restore README.md` - * `git status` +* make a change to README, then restore to previous (most recent) commit (pretend changes didn't exist, as if we changed our mind) * text: if we wanted to use content from a previous commit, like the file we created then deleted earlier * find SHA key in log -* code: - * `git checkout XXXXXXX filename` - * `git status` - * `git restore --staged filename` - * `git restore filename` - * `git status` -### Creating branches in Terminal +### Working with branches * text: what is a branch? * main branch (make sure usethis creates main as default branch) * why work with them? -* code: create branch, make changes, merge with main - * `git branch` - * `git checkout -b new_idea` - * make changes to file - * `git add filename` - * `git commit -m filename` - * `git checkout main` - * `git merge new_idea` - * `git branch -d new_idea` -* text: note working with branches in rstudio tab - -Exercise +* exercise: create branch, make changes, merge with main -Discuss more about branches in git workflows chapter +> Discuss more about branches in git workflows chapter ## Working with remote repositories * text: remote vs local repositories -* code: create remote repo and connect with local - * `usethis::git_remotes` - * `usethis::use_github` - * `usethis::git_remotes` +* exercise: create remote repo and connect with local * text: summarize process above Exercise @@ -138,19 +109,18 @@ TODO: This question makes a change to zipfs, so this should be reflected in any 1. For the `zipfs` previously used for demonstration in this chapter, perform the following tasks: - - Open up a Terminal and create a new branch called `new-feature` with `git`. + - Create a new branch called `new-feature` with `git`. - Open up any file and make a minor change (e.g. add a word like "random"). - In the RStudio Git Interface, add and commit those changes into the history. + Add and commit those changes into the history. - Go back to the main branch by using checkout with `git`. - Think about and consider what will happen if you attempt to merge your - branches? In the Terminal, merge the changes from the `new-feature` branch + branches? Merge the changes from the `new-feature` branch into the `main` branch and find out. 1. Go to your package for your first project assignment and perform the -following tasks, noting the approach you used (Git integration in RStudio, -command-line interface, `usethis`): +following tasks, noting the RStudio features and R functions you used: - Initialize the repository (`use_git()` in the R Console). - - In the RStudio Git Interface, add and commit all the relevant files that + - Add and commit all the relevant files that you've worked on until this point. Are there any you need to ignore? TODO: Should we have this thing about ignore? At this point would there be anything? - Connect your new Git repository to GitHub (`use_github()` in the R Console) From 7b6bb14dd1932a7ea07e92ec1d59f7c151d70cbe Mon Sep 17 00:00:00 2001 From: Kate Hertweck Date: Wed, 17 Nov 2021 21:38:32 -0800 Subject: [PATCH 2/8] cleaning up and overview --- chapters/05-version-control-solo.Rmd | 51 ++++++++++++++-------------- 1 file changed, 25 insertions(+), 26 deletions(-) diff --git a/chapters/05-version-control-solo.Rmd b/chapters/05-version-control-solo.Rmd index 07eb2a09..5914d320 100644 --- a/chapters/05-version-control-solo.Rmd +++ b/chapters/05-version-control-solo.Rmd @@ -1,19 +1,4 @@ -# Version control: Using Git and GitHub as a sole user (part 1) - -Emphasize exercises to practice, -not showing output of git in code chunks (they are a pain to edit afterwards). - -Clearly identify which tasks are best accomplished by each interface. - -- Using Git integration in RStudio - - standard add-commit - - view history - - creating branches - - moving in history - - adding and updating remotes -- `gert` and `usethis` commands for git; Setting up GitHub for R package -- working with remote repositories - - pushing and pulling +# Version control: Introduction to Git and GitHub ## Learning objectives @@ -25,20 +10,34 @@ Clearly identify which tasks are best accomplished by each interface. ## Overview -All text (no code): -* why to use version control -* why to use Git as a version control system (popularity, GitHub) -* how are Git and GitHub different? - * local vs remote - * publishing -* why use version control for software engineering - * basics of version control and why it matters for code - * preview this chapter, connect to other chapters +Version control is the practice of tracking and managing changes to code and other types of files. +If you've used tracked changes in Microsoft Word or Google Docs, +you're already familiar with using version control to track changes to documents. +A version control system, or software used to implement version control, +is an essential part of software engineering because of the history it retains +of who made what changes and when. + +Git is a version control system, +while GitHub is a website for publishing and sharing projects that are tracked using Git. +Git and GitHub are a very popular set of tools used by both academic and commercial organizations, +and correspondingly, +have well-developed help documentation and a large community of users to assist in their use. +Version control is used to record changes to all types of files, +but is especially important for code. +This is because changes made to code may have consequences for other parts of the file or project, +and being able to understand when and where changes caused problems is especially important. + +In this chapter, +we'll introduce version control by tracking the files to our project created so far, +navigating the Git workflow within the context of project development, +and exploring different ways to interact with Git in RStudio. ## Git integration in RStudio ### Setting up Git in RStudio +Installation and Getting Started: https://support.rstudio.com/hc/en-us/articles/200532077-Version-Control-with-Git-and-SVN + * text: connecting Git and RStudio * accessing Git through Global options * tab in environment pane @@ -81,7 +80,7 @@ All text and images: > Discuss more about branches in git workflows chapter -## Working with remote repositories +## Working with remote repositories in GitHub * text: remote vs local repositories * exercise: create remote repo and connect with local From f08e68bffe5e92f251887d6b2c166e7ceb11bb13 Mon Sep 17 00:00:00 2001 From: Kate Hertweck Date: Wed, 17 Nov 2021 21:46:17 -0800 Subject: [PATCH 3/8] remove branches --- chapters/05-version-control-solo.Rmd | 20 -------------------- 1 file changed, 20 deletions(-) diff --git a/chapters/05-version-control-solo.Rmd b/chapters/05-version-control-solo.Rmd index 5914d320..e2c15678 100644 --- a/chapters/05-version-control-solo.Rmd +++ b/chapters/05-version-control-solo.Rmd @@ -5,7 +5,6 @@ * identify why version control, specifically Git, is important for software engineering * differentiate methods for working with Git and R: RStudio integration, `usethis` and `gert` functions * apply the change-stage-commit process as the Git workflow for tracking changes and viewing a repository's commit history -* create branches to isolate work in progress and protect the main branch while working on major changes * publish repositories to GitHub and coordinate between remote and local versions ## Overview @@ -71,15 +70,6 @@ All text and images: * text: if we wanted to use content from a previous commit, like the file we created then deleted earlier * find SHA key in log -### Working with branches - -* text: what is a branch? - * main branch (make sure usethis creates main as default branch) - * why work with them? -* exercise: create branch, make changes, merge with main - -> Discuss more about branches in git workflows chapter - ## Working with remote repositories in GitHub * text: remote vs local repositories @@ -106,16 +96,6 @@ we will use the `kenyaweather` package as an example and reference. TODO: This question makes a change to zipfs, so this should be reflected in any automation we do to it. -1. For the `zipfs` previously used for demonstration in this chapter, -perform the following tasks: - - Create a new branch called `new-feature` with `git`. - - Open up any file and make a minor change (e.g. add a word like "random"). - Add and commit those changes into the history. - - Go back to the main branch by using checkout with `git`. - - Think about and consider what will happen if you attempt to merge your - branches? Merge the changes from the `new-feature` branch - into the `main` branch and find out. - 1. Go to your package for your first project assignment and perform the following tasks, noting the RStudio features and R functions you used: - Initialize the repository (`use_git()` in the R Console). From 3ea975992ec99b29e9c8996eeb8e38137c8a9bdd Mon Sep 17 00:00:00 2001 From: Kate Hertweck Date: Thu, 27 Jan 2022 09:57:59 -0800 Subject: [PATCH 4/8] formatting and refining outline --- chapters/05-version-control-solo.Rmd | 86 ++++++++++++++++++++-------- includes/links.md | 1 + 2 files changed, 63 insertions(+), 24 deletions(-) diff --git a/chapters/05-version-control-solo.Rmd b/chapters/05-version-control-solo.Rmd index e2c15678..8bb56f73 100644 --- a/chapters/05-version-control-solo.Rmd +++ b/chapters/05-version-control-solo.Rmd @@ -1,13 +1,13 @@ # Version control: Introduction to Git and GitHub -## Learning objectives +## Learning objectives {#05-learning-objectives} * identify why version control, specifically Git, is important for software engineering * differentiate methods for working with Git and R: RStudio integration, `usethis` and `gert` functions * apply the change-stage-commit process as the Git workflow for tracking changes and viewing a repository's commit history * publish repositories to GitHub and coordinate between remote and local versions -## Overview +## Introduction to version control {#intro-version-control} Version control is the practice of tracking and managing changes to code and other types of files. If you've used tracked changes in Microsoft Word or Google Docs, @@ -31,61 +31,99 @@ we'll introduce version control by tracking the files to our project created so navigating the Git workflow within the context of project development, and exploring different ways to interact with Git in RStudio. -## Git integration in RStudio +## The basic Git workflow {#git-workflow} -### Setting up Git in RStudio +Two ways to interact with Git: +- git interface in RStudio +- R commands implemented through `usethis` and `gert` -Installation and Getting Started: https://support.rstudio.com/hc/en-us/articles/200532077-Version-Control-with-Git-and-SVN +> popout to explain working with git on command line and with Git Desktop App -* text: connecting Git and RStudio +### Setting up Git in RStudio {#git-rstudio} + +RStudio provides a Installation and Getting Started [rstudio-git] + +* connecting Git and RStudio + * ensure Git is already installed (link to installation instructions) * accessing Git through Global options - * tab in environment pane -* code: `usethis::use_git` to initialize repository -* text: explain what happens when repo is initialized + * tab in environment pane + +* setting global parameters + * name + * email + +* Initializing a repository * creates hidden folder containing git history * some files ignored (note that it's possible to add other files to ignore) -### Tracking changes +### Exercise: initialize repository {#ex-initialize} + +initializing with GUI + +`usethis::use_git` to initialize repository + +### Tracking changes {#tracking-changes} + +explain git workflow + +### Exercise: track existing files in project {#ex-tracking} -All text and images: -* exercise: work through basic workflow using RStudio integration +* work through basic workflow using RStudio integration * all existing files in repo appear in git pane * ensure box is checked so these files are staged * click Commit button, add commit message and click commit * note pop up box with commit report, files no longer appear in window -* reiterate workflow by editing README + +* reiterate workflow by editing README and commiting with `gert` * status difference between tracking new files and editing previously tracked file -* exercise: create new file, commit, delete file, commit +``` +git_add(README.md) +git_commit("message") +``` + +* with your choice of interface, create new file, commit, delete file, commit -### Working with version history +### Working with version history {#git-history} -All text and images: +Viewing history: * click on clock button in Git pane (don't confuse with history tab; all git buttons are in Git tab) * explain fields: subject, author, date, SHA * click on a previous commit to see changes +`gert::git_log(max=-6)` + +### Exercise: discarding a change {#ex-discard} + * make a change to README, then restore to previous (most recent) commit (pretend changes didn't exist, as if we changed our mind) * text: if we wanted to use content from a previous commit, like the file we created then deleted earlier * find SHA key in log -## Working with remote repositories in GitHub +## Working with remote repositories in GitHub {#git-remotes} + +* remote vs local repositories + +### Exercise: connect a remote repository {#ex-remote} + +* create remote repo and connect with local + +### Pushing + +defining push and pull -* text: remote vs local repositories -* exercise: create remote repo and connect with local -* text: summarize process above +explain why you'd want to use these -Exercise +### Exercise: push changes to GitHub {#ex-push} -* text: pushing (define) * make change to file * commit with Rstudio integration * use push button -* explain pulling as inverse (but maybe not explain GitHub interface as thoroughly?) +### Pulling -* text: relate to command line activities +* explain pulling as inverse of pushing +* FIXME: include exercise making change on github and pulling? ## Final exercise {#05-final-exercise} diff --git a/includes/links.md b/includes/links.md index 2c348c64..fbb54619 100644 --- a/includes/links.md +++ b/includes/links.md @@ -311,6 +311,7 @@ [rstudio-addin]: https://rstudio.github.io/rstudioaddins/ [rstudio-cloud]: https://rstudio.cloud/ [rstudio-ide]: https://www.rstudio.com/products/rstudio/ +[rstudio-git]: https://support.rstudio.com/hc/en-us/articles/200532077-Version-Control-with-Git-and-SVN [rstudio-r-projects]: https://support.rstudio.com/hc/en-us/articles/200526207-Using-Projects [rstudio]: https://rstudio.com/ [rubber-duck-debugging]: https://en.wikipedia.org/wiki/Rubber_duck_debugging From 78baee327b2457c7fe035a5dcae0b0d6ece4bb63 Mon Sep 17 00:00:00 2001 From: Kate Hertweck Date: Thu, 27 Jan 2022 12:55:41 -0800 Subject: [PATCH 5/8] add placeholder for appendix --- chapters/01-preface.Rmd | 3 ++- chapters/05-version-control-solo.Rmd | 2 ++ chapters/14-appendix.Rmd | 9 +++++++++ 3 files changed, 13 insertions(+), 1 deletion(-) create mode 100644 chapters/14-appendix.Rmd diff --git a/chapters/01-preface.Rmd b/chapters/01-preface.Rmd index c0b6af19..d0a42f87 100644 --- a/chapters/01-preface.Rmd +++ b/chapters/01-preface.Rmd @@ -136,7 +136,8 @@ Learners will need: - To have [R][r], [Git][git], and [RStudio][rstudio] installed. - A [GitHub][github] account. -TODO: List of packages used and that need to be installed here as well. +TODO: List of packages used and that need to be installed here as well, +link to appendix. ### What's the big picture? diff --git a/chapters/05-version-control-solo.Rmd b/chapters/05-version-control-solo.Rmd index 8bb56f73..64620281 100644 --- a/chapters/05-version-control-solo.Rmd +++ b/chapters/05-version-control-solo.Rmd @@ -41,6 +41,8 @@ Two ways to interact with Git: ### Setting up Git in RStudio {#git-rstudio} +Reference appendix for setup + RStudio provides a Installation and Getting Started [rstudio-git] * connecting Git and RStudio diff --git a/chapters/14-appendix.Rmd b/chapters/14-appendix.Rmd new file mode 100644 index 00000000..fc81700d --- /dev/null +++ b/chapters/14-appendix.Rmd @@ -0,0 +1,9 @@ +# Appendix: Software installation and configuration + +## Software installation + + +## Configuring RStudio + +## Configuring Git + From cb7111beadb746c0cc01edc7130e44362129063e Mon Sep 17 00:00:00 2001 From: Kate Hertweck Date: Thu, 24 Feb 2022 09:23:48 -0800 Subject: [PATCH 6/8] deleting appendix (move to another branch) --- chapters/14-appendix.Rmd | 9 --------- 1 file changed, 9 deletions(-) delete mode 100644 chapters/14-appendix.Rmd diff --git a/chapters/14-appendix.Rmd b/chapters/14-appendix.Rmd deleted file mode 100644 index fc81700d..00000000 --- a/chapters/14-appendix.Rmd +++ /dev/null @@ -1,9 +0,0 @@ -# Appendix: Software installation and configuration - -## Software installation - - -## Configuring RStudio - -## Configuring Git - From 65f4e5d2e0ca1b7ca709406c4d5b87862ae92788 Mon Sep 17 00:00:00 2001 From: Kate Hertweck Date: Thu, 24 Feb 2022 10:58:51 -0800 Subject: [PATCH 7/8] clean preface --- chapters/01-preface.Rmd | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/chapters/01-preface.Rmd b/chapters/01-preface.Rmd index d0a42f87..c0b6af19 100644 --- a/chapters/01-preface.Rmd +++ b/chapters/01-preface.Rmd @@ -136,8 +136,7 @@ Learners will need: - To have [R][r], [Git][git], and [RStudio][rstudio] installed. - A [GitHub][github] account. -TODO: List of packages used and that need to be installed here as well, -link to appendix. +TODO: List of packages used and that need to be installed here as well. ### What's the big picture? From 7d9bef85b47465ecc95095b05ccf3ea1b120319f Mon Sep 17 00:00:00 2001 From: Kate Hertweck Date: Thu, 6 Oct 2022 08:55:06 -0700 Subject: [PATCH 8/8] moving git setup to appendix --- chapters/05-version-control-solo.Rmd | 22 ++++++++++++---------- 1 file changed, 12 insertions(+), 10 deletions(-) diff --git a/chapters/05-version-control-solo.Rmd b/chapters/05-version-control-solo.Rmd index 64620281..adcf40f1 100644 --- a/chapters/05-version-control-solo.Rmd +++ b/chapters/05-version-control-solo.Rmd @@ -29,24 +29,26 @@ and being able to understand when and where changes caused problems is especiall In this chapter, we'll introduce version control by tracking the files to our project created so far, navigating the Git workflow within the context of project development, -and exploring different ways to interact with Git in RStudio. +both while exploring different ways to interact with Git in RStudio. ## The basic Git workflow {#git-workflow} -Two ways to interact with Git: -- git interface in RStudio -- R commands implemented through `usethis` and `gert` +There are many different ways to interact with Git version control software. +For the purposes of this book, +we'll be using two of these approaches: +the Git interface in RStudio, +and R functions that implement Git commands +through the `usethis` and `gert` packages. > popout to explain working with git on command line and with Git Desktop App -### Setting up Git in RStudio {#git-rstudio} +See the [appendix] +for more information on setting up Git and GitHub, +and make sure you can access Git via RStudio prior to continuing with this chapter. -Reference appendix for setup +### Getting started with Git in RStudio {#git-rstudio} -RStudio provides a Installation and Getting Started [rstudio-git] - -* connecting Git and RStudio - * ensure Git is already installed (link to installation instructions) +* Git and RStudio * accessing Git through Global options * tab in environment pane