Learn additional tools for working with Git version-controlled projects hosted on GitHub.
We will
README.md
file in a GitHub repository Learn additional tools for working with Git version-controlled projects hosted on GitHub.
We will
README.md
file in a GitHub repository Today we extend the very basic work done in the week 1 slides. If you've never worked with Git/GitHub before, you'll want to review those slides before proceeding.
Today won't make anybody an expert, but will get started doing more with the resources on next slide for when they decide to start doing more
It is standard to have a README.md
file in your GitHub repository. This file is for describing the project you are working on.
Such as why it is important, what the files contain, etc.
It is standard to have a README.md
file in your GitHub repository. This file is for describing the project you are working on.
The README file is a Markdown document. Markdown files render to HTML on GitHub. This mean the information in the file will automatically be included in an easily-readable format on the main page of your repository.
Markdown syntax is what you use to write in R Markdown, so you already know the basic syntax for adding information to your README. 🎉
Such as why it is important, what the files contain, etc.
Information to include may be what is in the project, why you are doing the project, metadata on the project like where data comes from, etc.
Here's an example of part of the README file from the GitHub repository for the class website.
Main point here is that the README renders and is on the repo home page
Let's spend a few minutes looking at examples of README files in the wild.
Some of the easiest examples to find of good README files are for R packages, such as on the palmerpenguins repository.
Follow the link to the the palmerpenguins repo and scroll down to explore the README file there.
Let's spend a few minutes looking at examples of README files in the wild.
Some of the easiest examples to find of good README files are for R packages, such as on the palmerpenguins repository.
Follow the link to the the palmerpenguins repo and scroll down to explore the README file there.
Of course people use repositories for other types of work. Here are two examples of non-R package repositories with information-filled README files:
For research projects you can use GitHub to make a research compendium. See the Marwick et al. paper and an example compendium.
Purposefully focusing on more "applied" README examples, since that is audience here. Not all README's need to go into this much detail.
Have students follow links to look at README files. Then move on to the practical work for the day
Make a new GitHub repository called merge-conflict
.
Remember in Week 1 you learned to
05:00
They may have forgotten how to do this, so be prepared to answer questions.
Right now you are the only person who can make direct changes to files in one of your repositories.
Add collaborators if you'd like others to also be able to work directly on a repository.
Right now you are the only person who can make direct changes to files in one of your repositories.
Add collaborators if you'd like others to also be able to work directly on a repository.
merge-conflict
repository and then go to Settings
.Right now you are the only person who can make direct changes to files in one of your repositories.
Add collaborators if you'd like others to also be able to work directly on a repository.
merge-conflict
repository and then go to Settings
.Manage Access
(second menu item from the top).Right now you are the only person who can make direct changes to files in one of your repositories.
Add collaborators if you'd like others to also be able to work directly on a repository.
merge-conflict
repository and then go to Settings
.Manage Access
(second menu item from the top).Right now you are the only person who can make direct changes to files in one of your repositories.
Add collaborators if you'd like others to also be able to work directly on a repository.
merge-conflict
repository and then go to Settings
.Manage Access
(second menu item from the top).aosmith16
if you'd like to invite me for practice. 😁They can invite me if that's easiest.
Right now you are the only person who can make direct changes to files in one of your repositories.
Add collaborators if you'd like others to also be able to work directly on a repository.
merge-conflict
repository and then go to Settings
.Manage Access
(second menu item from the top).aosmith16
if you'd like to invite me for practice. 😁A merge conflict is when the same lines of a file have been changed in two places, most often by different people. These can become more common once you have collaborators.
I am going to have you create a merge conflict by changing a file on GitHub and in the local version of the repository at the same time.
I don't need collaborators to make merge conflicts, myself. I can manage that all on my own! :-D
A merge conflict is when the same lines of a file have been changed in two places, most often by different people. These can become more common once you have collaborators.
I am going to have you create a merge conflict by changing a file on GitHub and in the local version of the repository at the same time.
We'll use GitKraken's merge conflict tool to address the conflict.
Make sure you have GitKraken installed on your computer.
I don't need collaborators to make merge conflicts, myself. I can manage that all on my own! :-D
Go to your merge-conflict
repository on GitHub and open the README.md
file.
Click on the edit button in the right-hand corner.
The edit button has a picture of a pencil on it.
Replace the current title and description in the README with:
# Merge conflictPractice dealing with a merge conflict
After making the change, scroll down to Commit
the changes. Write a commit message in the first box and then hit the Commit changes
box. I used Update README
as my commit message.
Now go to your local version of the repository in RStudio.
Open the README file there and replace the current title and description with:
# Practice a merge conflictWe will practice a merge conflict
Save your changes and then Stage
- Commit
- Push
.
The Push
will fail, but note the useful message.
This tells us that we are missing work done elsewhere that is on GitHub so we likely need to Pull
.
When working with multiple people or working alone but from multiple devices you need to Pull
changes from GitHub before you can Push
changes you made locally.
The message in the last slide indicated we hadn't done this. Pull
using the pull button in the Git
Pane.
Forgetting to pull before working on a local repo is one of my most common mistakes!
When working with multiple people or working alone but from multiple devices you need to Pull
changes from GitHub before you can Push
changes you made locally.
The message in the last slide indicated we hadn't done this. Pull
using the pull button in the Git
Pane.
Now we get a message about a merge conflict.
Forgetting to pull before working on a local repo is one of my most common mistakes!
Note Git attempted to auto-merge, which can work in many cases. Here it fails since the same lines are changed in both versions of the document.
We will now switch to GitKraken to make use of their merge conflict tool.
You will be asked to sign in to GitKraken. Choose the first option to sign in with your GitHub account.
A new window will pop up in your web browser that will ask you to authorize GitKraken to access GitHub. Continue with the authorization.
You should then get a Success
message, and you are ready to open the local merge-conflict
repository in GitKraken.
In GitKraken, click the Open a repo
button.
In GitKraken, click the Open a repo
button.
Then choose Open a Repository
.
Navigate to the folder that contains the local version of your merge-conflict
repository and Select Folder
. The repository will open in GitKraken.
Since we currently have a merge conflict, you will see the message Merge conflict detected
on the right-hand side of GitKraken.
Any files with a merge conflict are listed in the window under the message. Currently this shows README.md
, the file that has a conflict.
Click on README.md
in the merge conflict window to open GitKraken's merge conflict tool.
This took me a single click, not a double click
The top two panes show the two versions of the document. The bottom pane, "Output", shows the original file and will update to show changes as we choose which lines we want to keep.
We can choose all lines from one of the two versions. Here I show clicking the "A" box to add all content from "A" to Output
. I then remove the second line from Output
by clicking next to that line.
I ultimately add the top line from version "A" and the bottom line from version "B" to make a final, combined version of README.md
. Click on Save
in the upper right when you're done.
Students should play around with adding all lines or just one line or some combination.
After saving you are taken back to the main GitKraken window.
In the right-hand side you can see that your final version of README.md
has been staged.
Write a commit message and then click Commit and Merge
.
Push
these changes to GitHub with the push button found at the top of the GitKraken window.
Once you Push
these changes you're done. If you go back to the Project in RStudio you'll find the merge conflict message is gone and everything is up-to-date.
You can now close GitKraken and close the merge-conflict
Project in RStudio.
We will finish this session by going through the steps for making a pull request to propose changes to a repository.
A pull request is how you can propose changes to a GitHub repository. If accepted, the person who maintains the repository will pull your changes in to change the contents of their repo.
Pull requests can be something as simple as to fix typos or help re-word documentation all the way up to proposing new functions or changing code in a package. For the latter, make sure you use the correct coding style for the package.
We will finish this session by going through the steps for making a pull request to propose changes to a repository.
A pull request is how you can propose changes to a GitHub repository. If accepted, the person who maintains the repository will pull your changes in to change the contents of their repo.
Today we will practice making a pull request on someone else's repository.
Using pull requests is also a reasonable way to approach working with collaborators on a shared repository to avoid merge conflicts.
If working on your own repository, you won't need the step to fork and clone the repository.
Pull requests can be something as simple as to fix typos or help re-word documentation all the way up to proposing new functions or changing code in a package. For the latter, make sure you use the correct coding style for the package.
We'll be using helper functions from package usethis for pull requests.
We will start by setting up a personal access token or PAT from GitHub. This is required for using the pull request functions in package usethis.
This process is necessary only once per computer or if a PAT has been compromised for some reason and you need a new one.
See complete instructions and important additional information about managing your credentials at Managing Git(Hub) Credentials.
This process is necessary only once per computer or if a PAT has been compromised for some reason and you need a new one.
See complete instructions and important additional information about managing your credentials at Managing Git(Hub) Credentials.
Important: I will be showing you a screenshot and example code that includes a GitHub PAT. It is important you do not give or show your PAT to anyone. Since the PAT I used to create these slides was compromised, I deleted it and created a new one.
Make sure they understand that a PAT should be protected and I'm showing one for educational purposes only.
Make sure you are signed in to GitHub. Open a clean R session in RStudio.
Make sure you are signed in to GitHub. Open a clean R session in RStudio.
Create a token using function create_github_token()
from package usethis. Run the following code in your R Console or paste into a script and run from there.
usethis::create_github_token()
Make sure you are signed in to GitHub. Open a clean R session in RStudio.
Create a token using function create_github_token()
from package usethis. Run the following code in your R Console or paste into a script and run from there.
usethis::create_github_token()
You will see a message like the one below and then you will be taken to GitHub.
* Call `gitcreds::gitcreds_set()` to register this token in the local Git credential storeIt is also a great idea to store this token in any password-management software that you use√ Opening URL 'https://github.com/settings/tokens/new?scopes=repo,user,gist,workflow&description=R:GITHUB_PAT'
In GitHub you will give the new PAT a name. This name should allow you to recognize which computer it is for. In my example I create a PAT for my laptop.
After naming, scroll down to the bottom and click Generate token
. usethis has already filled in some recommended scopes and we'll leave them all as is.
Once you create the PAT you will see a page where the token code is visible. Once you leave this page you will not be able to see it again.
Important: Make sure you copy the PAT for the next step using the clipboard button before exiting the page.
Back in R, we can store the PAT using the gitcreds package. This package was installed when you installed usethis.
Note: You must have package gh version 1.2.1 or higher installed for this to work.
Type in and run the following code in R.
I'm avoiding copying and pasting here because your PAT is currently on your clipboard and you'll need it in this next step. 🙂
gitcreds::gitcreds_set()
Students may want to type out the gitcreds command since they have the PAT on the clipboard.
If you have no credentials stored, you will be prompted to enter your token. Paste it and press enter.
If you have no credentials stored, you will be prompted to enter your token. Paste it and press enter.
If you do have credentials stored you will see something like:
-> Your current credentials for 'https://github.com': protocol: https host : github.com path : username: PersonalAccessToken password: <-- hidden -->-> What would you like to do? 1: Keep these credentials2: Replace these credentials3: See the password / tokenSelection:
If you have no credentials stored, you will be prompted to enter your token. Paste it and press enter.
If you do have credentials stored you will see something like:
-> Your current credentials for 'https://github.com': protocol: https host : github.com path : username: PersonalAccessToken password: <-- hidden -->-> What would you like to do? 1: Keep these credentials2: Replace these credentials3: See the password / tokenSelection:
I chose 2
and then was prompted to enter my new token.
Selection: 2-> Removing current credentials...? Enter new password or token:
I then pasted my PAT and pressed enter to finish the process.
? Enter new password or token: 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-> Adding new credentials...-> Removing credetials from cache...-> Done.
Again I have shown my PAT. Since it was compromised I deleted it and made a new one.
Now that we have stored a PAT we can start the pull request process.
For more complete instructions, including instructions on how to edit pull requests, see the usethis article on Pull request helpers.
We're using usethis to do some of the heavy lifting here but you can absolutely do this process without it. You can see a basic "manual" approach in the materials for R programming for biologists
This step is important if you are going to propose a change to someone else's repository.
To fork means you make your own copy of the repository on GitHub.
Then clone to make a local version of the repository.
Students have cloned before manually by copying the github repo URL using the "Code" button on GitHub
This step is important if you are going to propose a change to someone else's repository.
To fork means you make your own copy of the repository on GitHub.
Then clone to make a local version of the repository.
I'll have you practice making a pull request on one of my repository's, called practice-repo
. My user name is aosmith16
.
Copy the following fork and clone code and run it in R:
usethis::create_from_github("aosmith16/practice-repo")
Note you need both the user name and repo name for this step.
Students have cloned before manually by copying the github repo URL using the "Code" button on GitHub
Copy and paste the R code into your R Console to run it.
You will see a series of messages as usethis does work behind the scenes:
i Defaulting to 'https' Git protocol√ Setting `fork = TRUE`√ Creating 'C:/Users/ariel/Desktop/practice-repo/'√ Forking 'aosmith16-testing/practice-repo'√ Cloning repo from 'https://github.com/aosmith16/practice-repo.git' into 'C:/Users/ariel/Desktop/practice-repo'√ Setting active project to 'C:/Users/ariel/Desktop/practice-repo'i Default branch is 'master'√ Adding 'upstream' remote: 'https://github.com/aosmith16/practice-repo.git'√ Pulling changes from 'upstream/master' (default branch of source repo)√ Setting remote tracking branch for local 'master' branch to 'upstream/master'√ Writing 'practice-repo.Rproj'√ Adding '.Rproj.user' to '.gitignore'√ Opening 'C:/Users/ariel/Desktop/practice-repo/' in new RStudio session√ Setting active project to '<no active project>'
When the process finishes, a new RStudio Project will open from a new local directory for the forked repository.
By default usethis will make the local directory on your Desktop. This is usually OK since the local version is temporary; most often you will delete it after finishing your pull request.
You can set a different location for the directory using the destdir
argument in create_from_github()
.
Before you commence making changes to the repository you need to make a new branch. Avoid making changes to the default branch, which is master
here but for newer repositories is often main
.
For this exercise, name your branch with your last name plus "prac". Here I named mine muldoonprac
; name yours based on your own last name. 😉
Run this code with your own branch name in R:
usethis::pr_init(branch = "muldoonprac")
√ Setting active project to 'C:/Users/ariel/Desktop/practice-repo'√ Pulling changes from 'upstream/master'√ Creating and switching to local branch 'muldoonprac'* Use `pr_push()` to create PR.
Now you are working in a new branch and can proceed making your proposed changes.
Today I want each of you to:
firstname_lastname.Rmd
Now you are working in a new branch and can proceed making your proposed changes.
Today I want each of you to:
firstname_lastname.Rmd
Once you have created and saved the new document, Stage
and Commit
your changes. Note the Push
button is grayed out.
No need to knit. It's not the end of the world if they do but trying to keep this simple with just a Rmd doc
After finishing any proposed edits and committing them, create a pull request (PR) using pr_push()
.
Run the following code in R:
usethis::pr_push()
You will see some messages in RStudio:
√ Pushing local 'muldoonprac' branch to 'origin' remote* Create PR at link given below√ Opening URL 'https://github.com/aosmith16/practice-repo/compare/muldoonprac'
And then you will be taken to GitHub. This may take a few minutes! ⏳
You will do the final steps to finish the pull request in GitHub. Click the Create pull request
button.
You then have the option to add a description in addition to your commit message. This is where you can describe what you edited and why. Fill this is in now.
Once you have added a description click the Create pull request
button to create the pull request.
Now you need to wait for the maintainer to respond. A simple pull request may be accepted or merged right away. That is what will happen today with your practice pull request. 😄
A maintainer could ask you to make additional changes or they could make changes on top of the ones you proposed. And, of course, they could decide not to accept any of your pull request.
See how to work with some of these alternatives in the usethis Pull request helpers article.
Once you get a response on your pull request you will see a notification in GitHub (blue dot on bell in upper right-hand corner) and an email.
Click on the notification and then open the pull request in your Inbox on GitHub.
Notification is shown by the blue dot on the bell in the upper right-hand corner.
Once you get a response on your pull request you will see a notification in GitHub (blue dot on bell in upper right-hand corner) and an email.
Click on the notification and then open the pull request in your Inbox on GitHub.
In this case when you open the pull request you will see that it has been merged.
Notification is shown by the blue dot on the bell in the upper right-hand corner.
Once the pull request has been merged we can clean things up on our end.
Back in R, use pr_finish()
to delete the branch.
Run the following code in R:
usethis::pr_finish()
This does some work behind the scenes so don't be alarmed if it at first it doesn't look like it is doing anything.
√ Switching back to default branch ('master')√ Pulling changes from 'upstream/master'√ Deleting local 'muldoonprac' branch√ PR 'aosmith16/practice-repo/#9' has been merged, deleting remote branch 'origin/muldoonprac'
If this was a one-time interaction with a repository, manually delete the local directory from your computer.
If this was a one-time interaction with a repository, manually delete the local directory from your computer.
Back on GitHub, delete the forked repository.
You can do this from the merged pull request if you still have it open. Click on settings
.
Then enter your user name and repository name as requested to delete the forked repository.
If this was a one-time interaction with a repository, manually delete the local directory from your computer.
Back on GitHub, delete the forked repository.
You can do this from the merged pull request if you still have it open. Click on settings
.
Then enter your user name and repository name as requested to delete the forked repository.
Alternatively, go to your version of the GitHub repository and then Settings
. Scroll down, down, down to the "Danger Zone" 😱. Click Delete this repository
and follow instructions.
week08_interaction.Rmd
from website prior to class Code for slides
Slides created via the R packages:
xaringan,
gadenbuie/xaringanthemer,
gadenbuie/xaringanExtra
This work is licensed under the Creative Commons Attribution-NonCommercial 4.0 International License. To view a copy of this license, visit http://creativecommons.org/licenses/by-nc/4.0/.
Learn additional tools for working with Git version-controlled projects hosted on GitHub.
We will
README.md
file in a GitHub repository Keyboard shortcuts
↑, ←, Pg Up, k | Go to previous slide |
↓, →, Pg Dn, Space, j | Go to next slide |
Home | Go to first slide |
End | Go to last slide |
Number + Return | Go to specific slide |
b / m / f | Toggle blackout / mirrored / fullscreen mode |
c | Clone slideshow |
p | Toggle presenter mode |
t | Restart the presentation timer |
?, h | Toggle this help |
s | Toggle scribble toolbox |
o | Tile View: Overview of Slides |
Esc | Back to slideshow |
Learn additional tools for working with Git version-controlled projects hosted on GitHub.
We will
README.md
file in a GitHub repository Learn additional tools for working with Git version-controlled projects hosted on GitHub.
We will
README.md
file in a GitHub repository Today we extend the very basic work done in the week 1 slides. If you've never worked with Git/GitHub before, you'll want to review those slides before proceeding.
Today won't make anybody an expert, but will get started doing more with the resources on next slide for when they decide to start doing more
It is standard to have a README.md
file in your GitHub repository. This file is for describing the project you are working on.
Such as why it is important, what the files contain, etc.
It is standard to have a README.md
file in your GitHub repository. This file is for describing the project you are working on.
The README file is a Markdown document. Markdown files render to HTML on GitHub. This mean the information in the file will automatically be included in an easily-readable format on the main page of your repository.
Markdown syntax is what you use to write in R Markdown, so you already know the basic syntax for adding information to your README. 🎉
Such as why it is important, what the files contain, etc.
Information to include may be what is in the project, why you are doing the project, metadata on the project like where data comes from, etc.
Here's an example of part of the README file from the GitHub repository for the class website.
Main point here is that the README renders and is on the repo home page
Let's spend a few minutes looking at examples of README files in the wild.
Some of the easiest examples to find of good README files are for R packages, such as on the palmerpenguins repository.
Follow the link to the the palmerpenguins repo and scroll down to explore the README file there.
Let's spend a few minutes looking at examples of README files in the wild.
Some of the easiest examples to find of good README files are for R packages, such as on the palmerpenguins repository.
Follow the link to the the palmerpenguins repo and scroll down to explore the README file there.
Of course people use repositories for other types of work. Here are two examples of non-R package repositories with information-filled README files:
For research projects you can use GitHub to make a research compendium. See the Marwick et al. paper and an example compendium.
Purposefully focusing on more "applied" README examples, since that is audience here. Not all README's need to go into this much detail.
Have students follow links to look at README files. Then move on to the practical work for the day
Make a new GitHub repository called merge-conflict
.
Remember in Week 1 you learned to
05:00
They may have forgotten how to do this, so be prepared to answer questions.
Right now you are the only person who can make direct changes to files in one of your repositories.
Add collaborators if you'd like others to also be able to work directly on a repository.
Right now you are the only person who can make direct changes to files in one of your repositories.
Add collaborators if you'd like others to also be able to work directly on a repository.
merge-conflict
repository and then go to Settings
.Right now you are the only person who can make direct changes to files in one of your repositories.
Add collaborators if you'd like others to also be able to work directly on a repository.
merge-conflict
repository and then go to Settings
.Manage Access
(second menu item from the top).Right now you are the only person who can make direct changes to files in one of your repositories.
Add collaborators if you'd like others to also be able to work directly on a repository.
merge-conflict
repository and then go to Settings
.Manage Access
(second menu item from the top).Right now you are the only person who can make direct changes to files in one of your repositories.
Add collaborators if you'd like others to also be able to work directly on a repository.
merge-conflict
repository and then go to Settings
.Manage Access
(second menu item from the top).aosmith16
if you'd like to invite me for practice. 😁They can invite me if that's easiest.
Right now you are the only person who can make direct changes to files in one of your repositories.
Add collaborators if you'd like others to also be able to work directly on a repository.
merge-conflict
repository and then go to Settings
.Manage Access
(second menu item from the top).aosmith16
if you'd like to invite me for practice. 😁A merge conflict is when the same lines of a file have been changed in two places, most often by different people. These can become more common once you have collaborators.
I am going to have you create a merge conflict by changing a file on GitHub and in the local version of the repository at the same time.
I don't need collaborators to make merge conflicts, myself. I can manage that all on my own! :-D
A merge conflict is when the same lines of a file have been changed in two places, most often by different people. These can become more common once you have collaborators.
I am going to have you create a merge conflict by changing a file on GitHub and in the local version of the repository at the same time.
We'll use GitKraken's merge conflict tool to address the conflict.
Make sure you have GitKraken installed on your computer.
I don't need collaborators to make merge conflicts, myself. I can manage that all on my own! :-D
Go to your merge-conflict
repository on GitHub and open the README.md
file.
Click on the edit button in the right-hand corner.
The edit button has a picture of a pencil on it.
Replace the current title and description in the README with:
# Merge conflictPractice dealing with a merge conflict
After making the change, scroll down to Commit
the changes. Write a commit message in the first box and then hit the Commit changes
box. I used Update README
as my commit message.
Now go to your local version of the repository in RStudio.
Open the README file there and replace the current title and description with:
# Practice a merge conflictWe will practice a merge conflict
Save your changes and then Stage
- Commit
- Push
.
The Push
will fail, but note the useful message.
This tells us that we are missing work done elsewhere that is on GitHub so we likely need to Pull
.
When working with multiple people or working alone but from multiple devices you need to Pull
changes from GitHub before you can Push
changes you made locally.
The message in the last slide indicated we hadn't done this. Pull
using the pull button in the Git
Pane.
Forgetting to pull before working on a local repo is one of my most common mistakes!
When working with multiple people or working alone but from multiple devices you need to Pull
changes from GitHub before you can Push
changes you made locally.
The message in the last slide indicated we hadn't done this. Pull
using the pull button in the Git
Pane.
Now we get a message about a merge conflict.
Forgetting to pull before working on a local repo is one of my most common mistakes!
Note Git attempted to auto-merge, which can work in many cases. Here it fails since the same lines are changed in both versions of the document.
We will now switch to GitKraken to make use of their merge conflict tool.
You will be asked to sign in to GitKraken. Choose the first option to sign in with your GitHub account.
A new window will pop up in your web browser that will ask you to authorize GitKraken to access GitHub. Continue with the authorization.
You should then get a Success
message, and you are ready to open the local merge-conflict
repository in GitKraken.
In GitKraken, click the Open a repo
button.
In GitKraken, click the Open a repo
button.
Then choose Open a Repository
.
Navigate to the folder that contains the local version of your merge-conflict
repository and Select Folder
. The repository will open in GitKraken.
Since we currently have a merge conflict, you will see the message Merge conflict detected
on the right-hand side of GitKraken.
Any files with a merge conflict are listed in the window under the message. Currently this shows README.md
, the file that has a conflict.
Click on README.md
in the merge conflict window to open GitKraken's merge conflict tool.
This took me a single click, not a double click
The top two panes show the two versions of the document. The bottom pane, "Output", shows the original file and will update to show changes as we choose which lines we want to keep.
We can choose all lines from one of the two versions. Here I show clicking the "A" box to add all content from "A" to Output
. I then remove the second line from Output
by clicking next to that line.
I ultimately add the top line from version "A" and the bottom line from version "B" to make a final, combined version of README.md
. Click on Save
in the upper right when you're done.
Students should play around with adding all lines or just one line or some combination.
After saving you are taken back to the main GitKraken window.
In the right-hand side you can see that your final version of README.md
has been staged.
Write a commit message and then click Commit and Merge
.
Push
these changes to GitHub with the push button found at the top of the GitKraken window.
Once you Push
these changes you're done. If you go back to the Project in RStudio you'll find the merge conflict message is gone and everything is up-to-date.
You can now close GitKraken and close the merge-conflict
Project in RStudio.
We will finish this session by going through the steps for making a pull request to propose changes to a repository.
A pull request is how you can propose changes to a GitHub repository. If accepted, the person who maintains the repository will pull your changes in to change the contents of their repo.
Pull requests can be something as simple as to fix typos or help re-word documentation all the way up to proposing new functions or changing code in a package. For the latter, make sure you use the correct coding style for the package.
We will finish this session by going through the steps for making a pull request to propose changes to a repository.
A pull request is how you can propose changes to a GitHub repository. If accepted, the person who maintains the repository will pull your changes in to change the contents of their repo.
Today we will practice making a pull request on someone else's repository.
Using pull requests is also a reasonable way to approach working with collaborators on a shared repository to avoid merge conflicts.
If working on your own repository, you won't need the step to fork and clone the repository.
Pull requests can be something as simple as to fix typos or help re-word documentation all the way up to proposing new functions or changing code in a package. For the latter, make sure you use the correct coding style for the package.
We'll be using helper functions from package usethis for pull requests.
We will start by setting up a personal access token or PAT from GitHub. This is required for using the pull request functions in package usethis.
This process is necessary only once per computer or if a PAT has been compromised for some reason and you need a new one.
See complete instructions and important additional information about managing your credentials at Managing Git(Hub) Credentials.
This process is necessary only once per computer or if a PAT has been compromised for some reason and you need a new one.
See complete instructions and important additional information about managing your credentials at Managing Git(Hub) Credentials.
Important: I will be showing you a screenshot and example code that includes a GitHub PAT. It is important you do not give or show your PAT to anyone. Since the PAT I used to create these slides was compromised, I deleted it and created a new one.
Make sure they understand that a PAT should be protected and I'm showing one for educational purposes only.
Make sure you are signed in to GitHub. Open a clean R session in RStudio.
Make sure you are signed in to GitHub. Open a clean R session in RStudio.
Create a token using function create_github_token()
from package usethis. Run the following code in your R Console or paste into a script and run from there.
usethis::create_github_token()
Make sure you are signed in to GitHub. Open a clean R session in RStudio.
Create a token using function create_github_token()
from package usethis. Run the following code in your R Console or paste into a script and run from there.
usethis::create_github_token()
You will see a message like the one below and then you will be taken to GitHub.
* Call `gitcreds::gitcreds_set()` to register this token in the local Git credential storeIt is also a great idea to store this token in any password-management software that you use√ Opening URL 'https://github.com/settings/tokens/new?scopes=repo,user,gist,workflow&description=R:GITHUB_PAT'
In GitHub you will give the new PAT a name. This name should allow you to recognize which computer it is for. In my example I create a PAT for my laptop.
After naming, scroll down to the bottom and click Generate token
. usethis has already filled in some recommended scopes and we'll leave them all as is.
Once you create the PAT you will see a page where the token code is visible. Once you leave this page you will not be able to see it again.
Important: Make sure you copy the PAT for the next step using the clipboard button before exiting the page.
Back in R, we can store the PAT using the gitcreds package. This package was installed when you installed usethis.
Note: You must have package gh version 1.2.1 or higher installed for this to work.
Type in and run the following code in R.
I'm avoiding copying and pasting here because your PAT is currently on your clipboard and you'll need it in this next step. 🙂
gitcreds::gitcreds_set()
Students may want to type out the gitcreds command since they have the PAT on the clipboard.
If you have no credentials stored, you will be prompted to enter your token. Paste it and press enter.
If you have no credentials stored, you will be prompted to enter your token. Paste it and press enter.
If you do have credentials stored you will see something like:
-> Your current credentials for 'https://github.com': protocol: https host : github.com path : username: PersonalAccessToken password: <-- hidden -->-> What would you like to do? 1: Keep these credentials2: Replace these credentials3: See the password / tokenSelection:
If you have no credentials stored, you will be prompted to enter your token. Paste it and press enter.
If you do have credentials stored you will see something like:
-> Your current credentials for 'https://github.com': protocol: https host : github.com path : username: PersonalAccessToken password: <-- hidden -->-> What would you like to do? 1: Keep these credentials2: Replace these credentials3: See the password / tokenSelection:
I chose 2
and then was prompted to enter my new token.
Selection: 2-> Removing current credentials...? Enter new password or token:
I then pasted my PAT and pressed enter to finish the process.
? Enter new password or token: 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-> Adding new credentials...-> Removing credetials from cache...-> Done.
Again I have shown my PAT. Since it was compromised I deleted it and made a new one.
Now that we have stored a PAT we can start the pull request process.
For more complete instructions, including instructions on how to edit pull requests, see the usethis article on Pull request helpers.
We're using usethis to do some of the heavy lifting here but you can absolutely do this process without it. You can see a basic "manual" approach in the materials for R programming for biologists
This step is important if you are going to propose a change to someone else's repository.
To fork means you make your own copy of the repository on GitHub.
Then clone to make a local version of the repository.
Students have cloned before manually by copying the github repo URL using the "Code" button on GitHub
This step is important if you are going to propose a change to someone else's repository.
To fork means you make your own copy of the repository on GitHub.
Then clone to make a local version of the repository.
I'll have you practice making a pull request on one of my repository's, called practice-repo
. My user name is aosmith16
.
Copy the following fork and clone code and run it in R:
usethis::create_from_github("aosmith16/practice-repo")
Note you need both the user name and repo name for this step.
Students have cloned before manually by copying the github repo URL using the "Code" button on GitHub
Copy and paste the R code into your R Console to run it.
You will see a series of messages as usethis does work behind the scenes:
i Defaulting to 'https' Git protocol√ Setting `fork = TRUE`√ Creating 'C:/Users/ariel/Desktop/practice-repo/'√ Forking 'aosmith16-testing/practice-repo'√ Cloning repo from 'https://github.com/aosmith16/practice-repo.git' into 'C:/Users/ariel/Desktop/practice-repo'√ Setting active project to 'C:/Users/ariel/Desktop/practice-repo'i Default branch is 'master'√ Adding 'upstream' remote: 'https://github.com/aosmith16/practice-repo.git'√ Pulling changes from 'upstream/master' (default branch of source repo)√ Setting remote tracking branch for local 'master' branch to 'upstream/master'√ Writing 'practice-repo.Rproj'√ Adding '.Rproj.user' to '.gitignore'√ Opening 'C:/Users/ariel/Desktop/practice-repo/' in new RStudio session√ Setting active project to '<no active project>'
When the process finishes, a new RStudio Project will open from a new local directory for the forked repository.
By default usethis will make the local directory on your Desktop. This is usually OK since the local version is temporary; most often you will delete it after finishing your pull request.
You can set a different location for the directory using the destdir
argument in create_from_github()
.
Before you commence making changes to the repository you need to make a new branch. Avoid making changes to the default branch, which is master
here but for newer repositories is often main
.
For this exercise, name your branch with your last name plus "prac". Here I named mine muldoonprac
; name yours based on your own last name. 😉
Run this code with your own branch name in R:
usethis::pr_init(branch = "muldoonprac")
√ Setting active project to 'C:/Users/ariel/Desktop/practice-repo'√ Pulling changes from 'upstream/master'√ Creating and switching to local branch 'muldoonprac'* Use `pr_push()` to create PR.
Now you are working in a new branch and can proceed making your proposed changes.
Today I want each of you to:
firstname_lastname.Rmd
Now you are working in a new branch and can proceed making your proposed changes.
Today I want each of you to:
firstname_lastname.Rmd
Once you have created and saved the new document, Stage
and Commit
your changes. Note the Push
button is grayed out.
No need to knit. It's not the end of the world if they do but trying to keep this simple with just a Rmd doc
After finishing any proposed edits and committing them, create a pull request (PR) using pr_push()
.
Run the following code in R:
usethis::pr_push()
You will see some messages in RStudio:
√ Pushing local 'muldoonprac' branch to 'origin' remote* Create PR at link given below√ Opening URL 'https://github.com/aosmith16/practice-repo/compare/muldoonprac'
And then you will be taken to GitHub. This may take a few minutes! ⏳
You will do the final steps to finish the pull request in GitHub. Click the Create pull request
button.
You then have the option to add a description in addition to your commit message. This is where you can describe what you edited and why. Fill this is in now.
Once you have added a description click the Create pull request
button to create the pull request.
Now you need to wait for the maintainer to respond. A simple pull request may be accepted or merged right away. That is what will happen today with your practice pull request. 😄
A maintainer could ask you to make additional changes or they could make changes on top of the ones you proposed. And, of course, they could decide not to accept any of your pull request.
See how to work with some of these alternatives in the usethis Pull request helpers article.
Once you get a response on your pull request you will see a notification in GitHub (blue dot on bell in upper right-hand corner) and an email.
Click on the notification and then open the pull request in your Inbox on GitHub.
Notification is shown by the blue dot on the bell in the upper right-hand corner.
Once you get a response on your pull request you will see a notification in GitHub (blue dot on bell in upper right-hand corner) and an email.
Click on the notification and then open the pull request in your Inbox on GitHub.
In this case when you open the pull request you will see that it has been merged.
Notification is shown by the blue dot on the bell in the upper right-hand corner.
Once the pull request has been merged we can clean things up on our end.
Back in R, use pr_finish()
to delete the branch.
Run the following code in R:
usethis::pr_finish()
This does some work behind the scenes so don't be alarmed if it at first it doesn't look like it is doing anything.
√ Switching back to default branch ('master')√ Pulling changes from 'upstream/master'√ Deleting local 'muldoonprac' branch√ PR 'aosmith16/practice-repo/#9' has been merged, deleting remote branch 'origin/muldoonprac'
If this was a one-time interaction with a repository, manually delete the local directory from your computer.
If this was a one-time interaction with a repository, manually delete the local directory from your computer.
Back on GitHub, delete the forked repository.
You can do this from the merged pull request if you still have it open. Click on settings
.
Then enter your user name and repository name as requested to delete the forked repository.
If this was a one-time interaction with a repository, manually delete the local directory from your computer.
Back on GitHub, delete the forked repository.
You can do this from the merged pull request if you still have it open. Click on settings
.
Then enter your user name and repository name as requested to delete the forked repository.
Alternatively, go to your version of the GitHub repository and then Settings
. Scroll down, down, down to the "Danger Zone" 😱. Click Delete this repository
and follow instructions.
week08_interaction.Rmd
from website prior to class Code for slides
Slides created via the R packages:
xaringan,
gadenbuie/xaringanthemer,
gadenbuie/xaringanExtra
This work is licensed under the Creative Commons Attribution-NonCommercial 4.0 International License. To view a copy of this license, visit http://creativecommons.org/licenses/by-nc/4.0/.