Collaborative git exercise

Practice with branches, fetches, merges, and pushes

---

Initial code description

code/01_make_output1.R

• generates random numbers
• saves numbers as a .rds object in output/ folder

code/02_render_report.R

• renders report.Rmd

report.Rmd

• reads random numbers generated by code/01_make_output1.R
• makes three histograms

---

Collaborative git exercise description

Determine users

Assign one partner to be User A and one partner to be User B.

User A: Confirm code base is stable

User A should download and unzip the project files. If needed, move the files/directory to a desired location on User A's computer either using the command line or a file browser.

Once the files are in the desired location, confirm that User A can build the report by executing make.

• If the report does not build, correct code until it builds correctly

User B does not need to download and unzip the project folder because they will download it in a later step from User A's GitHub.

User A: Initialize git repository

User A should initialize a local git repository.

1. Use git init to initialize a git repository in your project directory folder
2. Appropriately use git status, git add, and git commit to create your first commit. The commit should include:
   • all contents of the code directory
   • report.Rmd
   • README.md
   • Makefile
   • .gitignore
   • the output directory (i.e., the output/.gitkeep file)

User A: create a GitHub repository

User A should create a GitHub repository using the following steps.

1. Log in to GitHub and create an empty GitHub repository.

• be sure to select the option not to add a README nor a license.
• choose any name for the repository you like

2. User A uses git remote add origin git@github.com:<user_a_github_name>/<user_a_repo_name> to add User A's GitHub repository as a remote of User A's local repository named origin.

• replace <user_a_github_name> and <user_a_repo_name> with User A's GitHub user name and GitHub repository name, repsectively
• be sure to use the "ssh" style syntax for adding a remote and not "https". I.e., your command should be git remote add origin git@github.com:... and not git remote add origin https://github.com/....
• You can confirm what web address was used to add the remote by executing git remote -v. - If the output of git remote -v shows that origin points to https://github.com/<user_a_github_name>/<user_a_repo_name>, then User A should remove the origin remote using git remote remove origin try Step 2 again.

3. Use git push origin <your_branch_name> to push User A's local repository to GitHub.

• <your_branch_name> is probably main, but it may be master for some of you

4. Refresh the web page for User A's GitHub repository's to confirm that the push was successful.

---

User B: Fork and clone the repository

User B should now fork and clone User A's repository on GitHub using the following steps.

1. User B should navigate to https://github.com/<user_a_name>/<user_a_repo> and click "Fork" to create a fork of User A's repository.

• replace <user_a_name> with User A's GitHub user name
• replace <user_a_repo> with User A's GitHub repository name
• Recall that this creates a copy of User A's GitHub repository on User B's GitHub.

2. User B should use cd in their terminal to navigate to a directory where they wish to download User A's repository.
3. User B should execute git clone git@github.com:<user_b_name>/<user_b_repo> to clone the repository.

• be sure to use the git@github.com:<user_b_name>/<user_b_repo> syntax and not https://github.com/<user_b_name>/<user_b_repo> syntax.

4. The git clone command will download a folder called <user_b_repo> into your current working directory. User B should confirm that a folder called <user_b_repo> was added to the current working directory of their terminal.

• E.g., use ls to view the contents of your current working directory. You should see a directory called <user_b_repo>

5. Use cd <user_b_repo> to change your working directory to this directory.
6. Use git remote -v to confirm that the remote was set up properly.

User B: Update the repository and submit a pull request

User B will now make a new branch and make updates to User A's repo on that branch. User B should complete the following steps:

1. Create and checkout a new branch called binomial by executing git checkout -b binomial.

• recall that this simultaneously creates and checks out a new branch called binomial
• confirm that User B has switched to the new branch by executing git branch
  • you should see a star next to binomial

2. Add the following lines to code/01_make_output.R (ignore the lines with back ticks):

set.seed(4)
random_numbers4 <- rbinom(100, 1, 0.25)

3. Add additional lines of code to save random_numbers4 object into the output folder.
4. Confirm that random_numbers4 gets created and saved properly (e.g., by running make random_numbers).
5. Add a few lines of code to report.Rmd to read in random_numbers4.rds and then add a new section to report.Rmd called "Random numbers 4"

• the contents of the section should be exactly the same as the other sections
• e.g., User B can copy/paste the "Random numbers 3" section and appropriately modify its contents

6. Confirm that User B can build the report (e.g., by executing make report.html)
7. Once User B is confident that report.html is building properly, they should appropriately use git add and git commit to make a new commit along the binomial branch that includes updates to both code/01_make_output.R and report.Rmd

• include a meaningful commit message

8. Push the binomial branch to GitHub.

• git push origin binomial

9. Submit a pull request to User A's repository.

• the pull request should request that User B's binomial branch be merged into User A's main branch.

---

User A: test out pull request code

User A will now fetch the code submitted by User B, test it out, and eventually merge it into their main branch, thereby closing the pull request.

1. User A should add User B's repository as a remote.

• git remote add <user_b_remote_name> https://github.com/<user_b_name>/<user_b_repo>
  • in this case, it's OK to use the https:// syntax, because User A does not need to push to User B's repository.
  • "ssh"-style syntax would also be fine here
• replace <user_b_remote_name> with whatever you would like to call this remote
• replace <user_b_name> with User B's GitHub user name
• replace <user_b_repo> with User B's GitHub repository name

2. User A should fetch from User B's repository.

• git fetch <user_b_remote_name>
• Recall that this command downloads the contents of User B's repository, but does not yet put them on any of User A's local branches.

3. User A should create and checkout a new branch named binomial from the <user_b_remote_name>/binomial branch.

• git checkout -b binomial <user_b_remote_name>/binomial
• Recall that this creates a new branch in User A's repository called binomial that looks exactly like the branch fetch'ed from User B's remote.

4. User A should test out the code on the binomial branch.

• E.g., confirm that the report builds properly when you execute make
• If the code does not work, User A should make corrections to the code and commit those changes to their binomial branch.

5. When User A is satisfied that the code works as expected, they should merge the binomial branch into main.

• git checkout main
• git merge binomial

6. User A should push the updated main branch to GitHub.

• git push origin main
• Both users should now see User B's pull request as "merged" on GitHub.

User A: More changes

1. User A should create and checkout a new branch called geometric.

• git checkout -b geometric
• Recall that this simultaneously creates and checks out a new branch called geometric in User A's local repository.

2. Add the following lines to code/01_make_output.R (ignore the lines with back ticks):

set.seed(5)
random_numbers5 <- rgeom(100, 0.25)

3. Add additional lines of code to save random_numbers5 object into the output folder.
4. Confirm that random_numbers5 gets created and saved properly (e.g., by running make random_numbers).
5. Add a few lines of code to load random_numbers5.rds in report.Rmd and add a new section to report.Rmd called "Random numbers 5"

• the contents of the section should be exactly the same as the other sections
• e.g., User A can copy/paste the "Random numbers 3" section and appropriately modify its contents

6. Confirm that User A can build the report (e.g., by executing make report.html)
7. Once User A is confident that report.html is building properly, they should appropriately use git add and git commit to make a new commit along the geometric branch that includes updates to both code/01_make_output.R and report.Rmd

• include a meaningful commit message

8. User A should merge the geometric branch into main.

• git checkout main
• git merge geometric

9. User A should push both the geometric and main branches to GitHub

• git push origin geometric
• git push origin main

---

User B update local repository

1. User B should add a remote called upstream that points to User A's GitHub repository.

• git remote add upstream https://github.com/<user_a_name>/<user_a_repo>
  • in this case, it's OK to use the https:// syntax, because User B does not need to push to User A's repository.
  • "ssh"-style syntax would also be fine here

2. User B should fetch from the upstream remote and merge upstream/main into main

• git fetch upstream
  • Recall that this downloads the contents of User A's repository (i.e., the upstream remote) to User B's computer; however, it does not add User A's commits/branches to User B's local branches.
• git checkout main
  • User B needs to be on their main branch to merge in changes from User A's GitHub repository.
• git merge upstream/main
  • Recall that this will update User B's local files on the main branch to look like User A's files from GitHub.
  • To confirm, User B could look in report.Rmd and locate the random_numbers5-associated code.

3. User B should push their main branch to origin.

• git push origin main

---

Submit to canvas

You should submit a text entry that contains a link to User A and User B's GitHub repositories. Example:

User A: https://github.com/userA/repo

User B: https://github.com/userB/repo

---

Reverse roles and repeat

If you have time, reverse roles of User A and B and repeat the exercise. However, you should not delete the GitHub repository associated with the first run through of the exercise, as you will be graded based on that repository. Make a new repository that has a different name than the one you submitted to Canvas.