-
Notifications
You must be signed in to change notification settings - Fork 1
/
Copy pathindex.qmd
144 lines (97 loc) · 7.06 KB
/
index.qmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
---
title: "Git, GitHub & RStudio"
description: RStudio users can leverage git Version-control which enhances reproducibility.
---
The [`usethis`](https://usethis.r-lib.org/) package and the RStudio IDE will help you orchestrate your version control repositories as RStudio projects.
## Background
This page gives tips on the procedures of configuring Git and GitHub from withing RStudio. The page favors the brevity of highlighting functions in a procedural order. There are also three videos in the sidebar (ranging from 3 minutes to 120 minutes) . The last video explains in more detail why and how you use version control as part of your reproducible workflow.
### Setup
To get started, make a free GitHub.com account. Make sure you have the latest versions of R, RStudio, and usethis. Then, setup your RStudio configuration using two key documents: [Setup](https://usethis.r-lib.org/articles/articles/usethis-setup.html), and [Managing Git(Hub) Credentials](https://usethis.r-lib.org/articles/articles/git-credentials.html).
Note: Check to see if you already have git on your local workstation. You can do this by running `system("git --version")` in the RStudio console. Often, windows users must first manually install [Git](https://git-scm.com/downloads).
## Tips
### Configure git and manage GitHub credentials (PAT)
The following are steps you can inovke **in your RStudio IDE** to securely connect your RStudio instance to GitHub. I **recommend** invoking these functions **in the RStudio console**. The steps in the code chunk below only need to be inovked once per RStudio instance, per active Personal Access Tokens (PAT.) **First, Log in to GitHub**, then it is easy to create new GitHub PATs from the RStudio console: `usethis::create_github_token()`.
By default Personal Access Tokens (PATs) expire every 30 days. GitHub tokens (PATs) can be managed at the [GitHub developer page](https://github.com/settings/apps).
::: column-margin
<iframe width="300" height="200" src="https://www.youtube.com/embed/r5_v5f6128M" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen>
</iframe>
:::
::: callout-note
If this is your first time, you will probably need to run `usethis::use_git_config()`. Typically the process of setting your git configuration with your GitHub ID and associated email is only done once, i.e. the first time.
By contrast, you will need to rerun `usethis::create_github_token()` each time a PAT expires.
:::
```{r}
#| echo: TRUE
#| eval: FALSE
# Sign-in to your GitHub account
# Read: https://usethis.r-lib.org/articles/articles/git-credentials.html
# Read: https://usethis.r-lib.org/articles/articles/usethis-setup.html
usethis::create_github_token() # generates a PAT token you can copy/paste in the next step.
gitcreds::gitcreds_set() # paste the PAT from the previous step
# Now check that your git credentials are set.
# Check whether you have confgigured your git user.name and user.email.
# If not, use usethis::use_git_config()
gh::gh_whoami()
usethis::gh_token_help()
usethis::use_git_config(user.name = "Jane Doe", user.email = "[email protected]")
usethis::gh_token_help()
```
### Create a new RStudio Project
It's recommended to use RStudio to create your local git repository. With this method, after selecting a "[New RStudio Project (Directions)](https://intro2r.library.duke.edu/proj.html#rstudio-projects1)", **select the "Create a git repository" option**. This will ensure your RStudio project is properly configured as a git repository. Then, add a README file and a license, before connecting your local repository to GitHub.
::: column-margin
<iframe width="300" height="200" src="https://www.youtube.com/embed/videoseries?si=hWO26jfu4-ctXAE1&list=PLXsA_OlR0o0PcuagC_TUl32RULZkLHI1D" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen>
</iframe>
:::
```{r}
#| echo: TRUE
#| eval: FALSE
use_readme.md()
use_ccby_license() # Optionally, add a license
# Before next step → stage & commit changes
use_github() # Connect local repo to GitHub
```
### Alternatively, transform an existing folder
On your local workstation, you can transform a local folder into an RStudio project and also make that project a git repository. Then connect the local repository to GitHub.
This will transform the local folder into an RStudio project. Howver, with this approach you must then create local git repository and then connect that repo to GitHub from local.
```{r}
#| echo: TRUE
#| eval: FALSE
library(usethis)
use_git() # initialize a git repo
# use_git_ignore() The .gitignore file is created by default running use_git()
use_readme.md()
use_ccby_license() # Optionally, add a license
# Before next step → stage & commit changes
use_github() # Connect local repo to GitHub
```
### Rename default branch
```{r}
#| echo: TRUE
#| eval: FALSE
library(usethis)
git_default_branch()
git_default_branch_rename()
git_default_branch_rediscover()
```
::: column-margin
<iframe width="300" height="200" src="https://www.youtube.com/embed/VjDM-XsoHUQ" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen>
</iframe>
:::
### Clone or fork from GitHub
```{r}
#| echo: TRUE
#| eval: FALSE
usethis::create_from_github("https://github.com/data-and-visualization/git-tutorial")
```
## Next Level...
Take your reproducibility to the next level. [Make your code citable](https://guides.github.com/activities/citable-code/) by connecting your GitHub repo and your [ORCID](https://orcid.org/register) (unique author ID) through to the [Zenodo](https://zenodo.org/) archival repository. Now, every time you commit a milestone release, you also mint a DOI.
### Share a zero-install compute environment
Publish your code in a binder.org container
- Full documentation to create a sharable RStudio compute environment is [documented on this Quarto page about projects](https://quarto.org/docs/projects/binder.html).
- The key elements are an `install.R` and `runtime.txt` files. The content and format of each file is demonstrated properly at the GitHub repo. Browse and you will see.
- In summary, at the Terminal, type: `quarto use binder`
#### Hints
Generate a binder badge with `usethis::use_binder_badge(urlpath = "rstudio")`. This should store the badge in your GitHub's project `README` file. Then `commit` and `push` your changes to GitHub; go to the README on GitHub, launch the build and wait for the long launch/build time.
Hint: be prepared to wait. The first build can take some time. Sometimes you must launch an initial or dormant build more than once. In my experienced these hiccups are rare, but try the launch twice before getting involved in extensive troubleshooting.
------------------------------------------------------------------------
*The old documentation from this site can be found in the [v.0.2019 release](https://github.com/data-and-visualization/git-tutorial/releases/tag/v0.9.2019) on GitHub*.