+ - 0:00:00
Notes for current slide
Notes for next slide

More Git and GitHub

+




Ariel Muldoon

May 11, 2021

1

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

Such as why it is important, what the files contain, etc.

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.

Main point here is that the README renders and is on the repo home page

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

They may have forgotten how to do this, so be prepared to answer questions.

They can invite me if that's easiest.

I don't need collaborators to make merge conflicts, myself. I can manage that all on my own! :-D

I don't need collaborators to make merge conflicts, myself. I can manage that all on my own! :-D

The edit button has a picture of a pencil on it.

This tells us that we are missing work done elsewhere that is on GitHub so we likely need to Pull.

Forgetting to pull before working on a local repo is one of my most common mistakes!

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.

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.

Students should play around with adding all lines or just one line or some combination.

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.

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.

Pull requests

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.

usethis hex sticker

40

Get personal access token (PAT)

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.

41

Get personal access token (PAT)

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.

42

Make sure they understand that a PAT should be protected and I'm showing one for educational purposes only.

Get personal access token (PAT)

Make sure you are signed in to GitHub. Open a clean R session in RStudio.

43

Get personal access token (PAT)

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()
44

Get personal access token (PAT)

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 store
It 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'
45

Get personal access token (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.

Screenshot showing the name given to the created PAT so you can identify which computer it is for. I added 'laptop' to the name so I would remember it was the 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.

46

Get personal access token (PAT)

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.


Screenshot showing an example of a created PAT that needs to be copied to your clipboard

47

Store personal access token (PAT)

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()
48

Students may want to type out the gitcreds command since they have the PAT on the clipboard.

Store personal access token (PAT)

If you have no credentials stored, you will be prompted to enter your token. Paste it and press enter.

49

Store personal access token (PAT)

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 credentials
2: Replace these credentials
3: See the password / token
Selection:
50

Store personal access token (PAT)

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 credentials
2: Replace these credentials
3: See the password / token
Selection:

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.
51

Again I have shown my PAT. Since it was compromised I deleted it and made a new one.

Make pull request

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

52

Fork and clone a repository

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.

53

Students have cloned before manually by copying the github repo URL using the "Code" button on GitHub

Fork and clone a repository

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.

54

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.

Fork and clone a repository

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().

55

Create branch to work in

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.
56

Edit repository

Now you are working in a new branch and can proceed making your proposed changes.

Today I want each of you to:

  • Create a new R Markdown document with HTML output
  • Put your name as the title
  • Save the document using your first and last name, like firstname_lastname.Rmd
57

Edit repository

Now you are working in a new branch and can proceed making your proposed changes.

Today I want each of you to:

  • Create a new R Markdown document with HTML output
  • Put your name as the title
  • Save the document using your first and last name, like firstname_lastname.Rmd



Once you have created and saved the new document, Stage and Commit your changes. Note the Push button is grayed out.

58

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

Create pull request

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! ⏳

59

Create pull request

You will do the final steps to finish the pull request in GitHub. Click the Create pull request button.

Screenshot showing the window you are taken from after using pr_push() from usethis

60

Create pull request

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.

Screenshot showing where you can add a description of your pull request and then finally create it on GitHub

61

Maintainer response

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.

62

Maintainer response

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.

Screenshot showing the blue dot on the bell in GitHub that indicates you have a notification

Click on the notification and then open the pull request in your Inbox on GitHub.

Screenshot showing the inbox after clicking on the notification bell in GitHub. This is where you can see what the maintainer did with the pull request.

63

Notification is shown by the blue dot on the bell in the upper right-hand corner.

Maintainer response

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.

Screenshot showing the blue dot on the bell in GitHub that indicates you have a notification

Click on the notification and then open the pull request in your Inbox on GitHub.

Screenshot showing the inbox after clicking on the notification bell in GitHub. This is where you can see what the maintainer did with the pull request.

-

In this case when you open the pull request you will see that it has been merged.

Screenshot showing a merged pull request

64

Notification is shown by the blue dot on the bell in the upper right-hand corner.

Finish pull request process

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'
65
Paused

Help

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
sToggle scribble toolbox
oTile View: Overview of Slides
Esc Back to slideshow