%%{init:{'theme':'forest', 'flowchart':{'nodeSpacing': 20, 'rankSpacing':30}}}%% graph LR; yours(Your local) -->|Push| github(GitHub) github -->|Pull| yours linkStyle 0,1 stroke-width:1px;
If you find any typos, errors, or places where the text may be improved, please let us know by providing feedback using GitHub.
On GitHub open an issue or submit a pull requests by clicking the " Edit this page" link at the side of this page.
One of the best ways of sharing your code (or really, any scientific output, like this website!) is through GitHub. Connecting your Git repository to GitHub is also a great way to collaborate with others and to keep a backup of your work.
So, let’s connect your project to GitHub! 🥳 Thankfully, usethis has a few functions to help us out. Before you can connect your project’s Git repository to GitHub, you need to inform GitHub (authenticate) that you are the owner of your account.
Any time we do anything on the Internet, there is some risk to having our information maliciously hacked. This is no different when using GitHub, so if we can, we should try to be more secure with what we send across the internet. In fact, most functions that relate to Git or using GitHub require using more secure features in order to work. usethis makes this much easier, thankfully, with several functions. The usethis website has a really well written guide on setting it up. Here is a very simplified version of what they recommend that is relevant for what we are doing in this course.
You very likely haven’t set up a PAT, but if you are uncertain, you can always check with:
usethis::gh_token_help()
• GitHub host: 'https://github.com'
• Personal access token for 'https://github.com': <unset>
• To create a personal access token, call `create_github_token()`
• To store a token for current and future use, call `gitcreds::gitcreds_set()`
ℹ Read more in the 'Managing Git(Hub) Credentials' article:
https://usethis.r-lib.org/articles/articles/git-credentials.html
The output is saying the token is <unset>
, which means we need to make Git and usethis aware of it. We do that by typing the next function in the Console to create the token on GitHub (if you haven’t created one already).
usethis::create_github_token()
This function sends us to the GitHub “Generate new token” webpage with all the necessary settings checked. Set the “Expiry date” to 90 days (this is a good security feature). Then, click the green button at the bottom called “Generate token” and you’ll have a very long string generated for you that starts with ghp_
. Save this token in your password manager. This is the token you will use every time you open up RStudio and interact with GitHub through R. You do not need to create a new token for each R project or package you make, you only need to create one after your current token expires (typically every couple of months), if you’ve forgotten the token or lost it, or if you’ve changed to a new computer.
In the Console, run:
gitcreds::gitcreds_set()
And then copy and paste your token into the prompt in the Console. This token usually gets saved for the day (it gets cached), but after restarting you will need to run the action again. If it asks to replace an existing one, select the “yes” option. Doing this is a bit like using the two-factor authentication (2FA) you often have to do when, for instance, accessing your online bank account or other government website. In this case, you are telling GitHub (when interacting to it through RStudio, like uploading and downloading your changes) that you are who you claim to digitally be.
Now that we can authenticate to GitHub that you are digitally you, we can connect our project’s Git repository to GitHub. If you are new to Git and GitHub, we strongly recommend starting your first work project(s) as private, in case you accidentally add files you aren’t supposed to. It will also help get you feeling comfortable with using Git and GitHub. However, for this course, we will be keeping it public. To make it private, we would add the argument private = TRUE
to the code below. For now, go to the the Console and run this function to make a public repository:
usethis::use_github()
You might notice the word origin
when referring to remotes. The word origin is the default short name to refer to the location of the remote (the GitHub URL). You will probably see this word in many other places to refer to a remote.
This will take your project and upload it to GitHub. Now, whenever you use Git and save your changes to the Git history, whenever you “Push” your changes it will be sent to your project on GitHub. The diagram below shows how it conceptually looks like:
%%{init:{'theme':'forest', 'flowchart':{'nodeSpacing': 20, 'rankSpacing':30}}}%% graph LR; yours(Your local) -->|Push| github(GitHub) github -->|Pull| yours linkStyle 0,1 stroke-width:1px;
The “Your local” is your own computer. Whenever you “push” to GitHub, it means it will upload your file changes (like synchronizing in Dropbox). Whenever you “pull” from GitHub, it takes any changes made on GitHub and downloads them to your “Local” computer.
Why use GitHub? For one, it is one of the most effective ways of collaborating on a shared project. Hundreds of companies and hundreds of thousands of workers use Git and services like GitHub to work together on massive projects. The way collaboration works would conceptually look like:
%%{init:{'theme':'forest', 'flowchart':{'nodeSpacing': 20, 'rankSpacing':30}}}%% graph LR; yours(Your local) -->|Push| github(GitHub) github -->|Pull| yours others(Collaborator's<br>local) -->|Push| github github -->|Pull| others linkStyle 0,1,2,3 stroke-width:1px;
This approach to collaborating makes it much easier to contribute directly (not through emails) to projects and to more easily help others out with issues.