You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
"markdown": "The last step to take before you're all set for the workshop is to get these components talking to one another! You set a password for your GitHub which is used for logging in to GitHub but to actually put your code changes from your computer up to GitHub you'll need to _authenticate_ yourself. There are two paths for authentication:\n\n1. Personal Access Token (PAT)\n2. Secure Shell (SSH) \n\nWhat's the difference? Essentially, authenticating via token makes many things \"just work\" while authenticating via SSH will work for some things but in other contexts you would _also_ need to do token-based authentication. For a more complete discussion of the benefits and drawbacks of each, see Dr. Bryan's \"[HTTPS versus SSH](https://happygitwithr.com/https-pat#https-vs-ssh)\" page.\n\nFollow the steps of your chosen authentication method in the tabs below.\n\n::::{.panel-tabset}\n#### Personal Access Token with RStudio\n\n**All of the code chunks for authenticating with a token are {{< fa brands r-project >}} R code that should be run in the \"Console\" pane of RStudio.** You may also create a script and run the code from there if you so desire but you'll likely only need this code once so the script's value would be short-lived.\n\n\n::: {.cell}\n\n```{.r .cell-code}\n# Install the `usethis` and `gitcreds` packages\ninstall.packages(c(\"usethis\", \"gitcreds\"))\n\n# Create a token (Note this will open a GitHub browser tab)\n## See steps 6-10 in GitHub's PAT tutorial (link below)\nusethis::create_github_token() # <1>\n```\n:::\n\n1. Leave parentheses empty\n\n_Copy your token at the end of the above step._ Once you leave the page where your token is displayed you'll <u>never</u> get to see it again! So if you close that page without copying it you'll need to make a new one in order to continue.\n\nOnce you've copied your token, run the code below to save your credentials in RStudio.\n\n\n::: {.cell}\n\n```{.r .cell-code}\n# Now, give your token to RStudio\n## After you run this line follow the prompts in the \"Console\" tab of RStudio\ngitcreds::gitcreds_set() # <2>\n```\n:::\n\n2. Leave parentheses empty here as well!\n\nThis line of code will prompt you to paste your token in the \"Console\" tab. After you do so (and hit \"Enter\"), your token will be safely stored in RStudio! \n\n##### Further Information\n\nYou may also find [GitHub's PAT tutorial](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token) (this is the link referenced in the first token-authentication code chunk!) or the [Happy Git with R PAT tutorial](https://happygitwithr.com/https-pat.html) helpful.\n\n#### SSH\n\n**All of the code chunks for authenticating with SSH are {{< fa terminal >}} command line code that should be agnostic to your programming language.**\n\nFirst, we need to check whether you already have SSH keys created on your computer. If you get a message saying that nothing exists or the path doesn't exist, you do not (yet) have SSH keys.\n\n\n::: {.cell}\n\n```{.bash .cell-code}\nls -al ~/.ssh/\n```\n:::\n\n\nIf you do need to create an SSH key pair you can do so via the command line. When you create a key pair you'll need to include a descriptive comment to help 'future you' if you ever have multiple key pairs in your life. We recommend \"lter\" plus your GitHub username to keep things simple.\n\n\n::: {.cell}\n\n```{.bash .cell-code}\nssh-keygen -t ed25519 -C \"lter-github\"\n```\n:::\n\n\n:::{.callout-tip}\n#### Older Computer?\n\nIf you get a warning/error because your system is too old to support the Ed25519 algorithm (that's the variant recommended by GitHub) you can instead use:\n\n\n::: {.cell}\n\n```{.bash .cell-code}\nssh-keygen -t rsa -b 4096 -C \"lter-github\"\n```\n:::\n\n:::\n\nAccept the prompt to save the key in the default location by hitting Enter. You will be prompted to enter a passphrase that will be required to access your SSH key later on. This step is technically optional but is considered a best practice. <u>If SSH keys are totally new to you, we recommend skipping the passphrase step.</u>\n\nOnce you've generated the key pair, follow [GitHub's instructions](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent#adding-your-ssh-key-to-the-ssh-agent) on adding that key pair to your computer's ssh-agent (roughly equivalent to a password manager but just for SSH key pairs).\n\nFinally, you need to share the public key with your GitHub self. Once again we'll refer you to [the phenomenal materials](https://happygitwithr.com/ssh-keys#provide-public-key-to-github) generated by Dr. Bryan on this topic. \n\n##### Further Information\n\nYou may also find [GitHub's SSH documentation](https://docs.github.com/en/authentication/connecting-to-github-with-ssh) or the [Happy Git with R SSH tutorial](https://happygitwithr.com/ssh-keys) helpful.\n\n::::\n",
"markdown": "Now you should [install R](https://www.r-project.org/) on your computer. If you already have R, <u>check that you have at least version 4.0.0</u> by running the following {{< fa brands r-project >}} R code:\n\n\n::: {.cell}\n\n```{.r .cell-code}\n# Run me in RStudio's \"Console\"\nversion$version.string\n```\n:::\n\n\nIf your version starts with a 3 (e.g., the above code returns \"R version 3...\"), please update R to make sure all packages behave as expected.\n",
This workshop provides an overview of what "version control" systems are and how they fit into collaborative coding within your team. Specifically, **we are focusing here on an introductory approach to version control that focuses on using Git via RStudio and GitHub**. We are always happy to improve workshop content so please don't hesitate to [post an Issue](https://github.com/lter/workshop-github/issues) on our GitHub repository if you see clear areas for improvement!
8
-
9
7
<imgsrc="images/logos/github.png"alt="Logo for GitHub"align="right"width="17%" />
10
8
11
-
To maximize the value of this workshop to you, **we recommend that you take the following steps before the day of the workshop**. Depending on whether you've used RStudio and/or GitHub before you may have already completed some or all of these steps but please read through the following materials regardless to ensure that all participants arrive with a common foundation of installed programs. If anything is unclear, feel free to reach out to us; our contact information can be found in the "SciComp Team" dropdown menu in the "People" page.
9
+
This workshop provides an overview of what "version control" systems are and how they fit into collaborative coding within your team. Specifically, **we are focusing here on an introductory approach to version control that focuses on using GitHub either by itself or with Git via RStudio**. We are always happy to improve workshop content so please don't hesitate to [post an Issue](https://github.com/lter/workshop-github/issues) on our GitHub repository if you see clear areas for improvement!
12
10
13
11
### Citing These Materials
14
12
@@ -18,186 +16,67 @@ If you'd like to cite these materials, please use the following citation:
18
16
19
17
## Workshop Preparation
20
18
21
-
The below preparation includes some code chunks for making sure everything is installed as it should be. All code is either R code ({{< fa brands r-project >}}) or is command line code ({{< fa terminal >}}). **In both cases, you'll run all provided code <u>in RStudio</u>**. {{< fa brands r-project >}} R code should be run in the "Console" tab of RStudio while {{< fa terminal >}} command line code should be run in the "Terminal" tab of RStudio.
22
-
23
-
<u>If you get errors with the provided code, _double check that you are running it in the right place</u>!_
19
+
To maximize the value of this workshop to you, **we recommend that you take the following steps before the day of the workshop**. You may have already completed some or all of these steps but please read through and confirm that you've done all of the steps that are relevant to you to ensure that all participants arrive with a common foundation of installed programs. If anything is unclear, feel free to reach out to us; our contact information can be found in the "SciComp Team" dropdown menu in the "People" page.
24
20
25
21
:::{.callout-note}
26
22
#### Institution-Owned Computers
27
23
28
24
If your institution has a dedicated IT team that has sole power to install software on your computer, you will need to contact them before the workshop to do the installation bits of the prep steps we outline below.
29
25
:::
30
26
31
-
### 1. Install R
32
-
33
-
Begin by [installing R](https://www.r-project.org/). If you already have R, <u>check that you have at least version 4.0.0</u> by running the following {{< fa brands r-project >}} R code:
34
-
35
-
```{r r-ver-check}
36
-
#| eval: false
37
-
38
-
# Run me in RStudio's "Console"
39
-
version$version.string
40
-
```
41
-
42
-
If your version starts with a 3 (e.g., the above code returns "R version 3..."), please update R to make sure all packages behave as expected.
43
-
44
-
### 2. Install RStudio
45
-
46
-
Once you have R (ver. ≥4.0), [install RStudio](https://posit.co/download/rstudio-desktop/). If you already have RStudio installed, you may want to make sure that you're using a recent version to take advantage of some quality of life improvements that are broadly useful.
47
-
48
-
### 3. Install Git
49
-
50
-
With R and RStudio installed you can now install Git! Git is the software that actually does the behind-the-scenes version control operations we'll cover in this workshop. Installing Git differs slightly depending on your operating system so check out the tabs below for the right option for you. These instructions are modified from Jennifer Bryan's excellent "[Happy Git and GitHub for the useR](https://happygitwithr.com/)" ebook.
27
+
There are a couple of distinct use-cases you might have for GitHub that will affect what preparation you need to do before this workshop. Consider the tabs below and follow all of the numbered steps in the choice that best fits your needs.
51
28
52
29
:::{.panel-tabset}
53
-
#### {{< fa brands apple >}} Mac
54
-
55
-
In RStudio's "Terminal" pane, run the following {{< fa terminal >}} command line code.
56
-
57
-
```
58
-
# Run me in RStudio's "Terminal"
59
-
xcode-select --install
60
-
```
30
+
### GitHub By Itself
61
31
62
-
For more detailed instructions, see [here](https://happygitwithr.com/install-git#macos).
63
-
64
-
#### {{< fa brands windows >}} Windows
65
-
66
-
[Install Git for Windows](https://gitforwindows.org/) (a.k.a. "Git Bash"). When asked about "Adjusting your PATH environment", **select "Git from the command line and also from 3rd-party software"**.
67
-
68
-
For more detailed instructions, see [here](https://happygitwithr.com/install-git#install-git-windows).
69
-
70
-
#### {{< fa brands linux >}} Linux
71
-
72
-
Install Git via your distro's package manager (in the {{< fa terminal >}} Terminal).
73
-
74
-
If you use Ubuntu or Debian Linux that {{< fa terminal >}} code is as follows:
75
-
76
-
```
77
-
sudo apt-get install git
78
-
```
79
-
80
-
If instead you use Fedora or RedHat Linux the {{< fa terminal >}} code is instead:
81
-
82
-
```
83
-
sudo yum install git
84
-
```
85
-
86
-
For more detailed instructions, see [here](https://happygitwithr.com/install-git#linux).
87
-
88
-
:::
32
+
#### 1. Create a GitHub Account
89
33
90
-
### 4. Check Git's Installation Worked
34
+
{{< include prep-steps/create_github-acct.qmd >}}
91
35
92
-
Regardless of your operating system, once you've installed Git, check that worked with the following {{< fa terminal >}} command line code. All operating systems should be able to run this in the "Terminal" pane of RStudio.
36
+
#### 2. Celebrate!
93
37
94
-
```
95
-
# Run me in RStudio's "Terminal"
96
-
which git
97
-
```
38
+
{{< include prep-steps/celebrate.qmd >}}
98
39
99
-
RStudio should be able to detect Git so let's check from that side too. In RStudio click through the following menus: "Tools" {{< fa arrow-right >}} "Global Options" {{< fa arrow-right >}} "Git / SVN" (cardboard box icon in left sidebar). **If you see a file path under "Git executable" then you are good to go!**
40
+
### GitHub with RStudio
100
41
101
42
:::{.callout-note}
102
-
#### Git Not Detected?
43
+
#### Running Code in Following Steps
103
44
104
-
If you had your RStudio session open while you installed Git for the first time, RStudio may not have detected Git on your computer. In that case, please close and restart RStudio before checking again.
105
-
:::
106
-
107
-
### 5. Create a GitHub Account
108
-
109
-
Now that you're all done installing programs, it's time to create an account on [GitHub](https://github.com/). GitHub is how you'll be able to collaborate with others. Dr. Bryan has some nice guidelines for [picking a good username](https://happygitwithr.com/github-acct#username-advice) and we also recommend adding a picture of yourself so that group members can more confidently identify one another on GitHub.
110
-
111
-
### 6. Connect Git and GitHub
112
-
113
-
The last step to take before you're all set for the workshop is to get these components talking to one another! You set a password for your GitHub which is used for logging in to GitHub but to actually put your code changes from your computer up to GitHub you'll need to _authenticate_ yourself. There are two paths for authentication:
114
-
115
-
1. Personal Access Token (PAT)
116
-
2. Secure Shell (SSH)
117
-
118
-
What's the difference? Essentially, authenticating via token makes many things "just work" while authenticating via SSH will work for some things but in other contexts you would _also_ need to do token-based authentication. For a more complete discussion of the benefits and drawbacks of each, see Dr. Bryan's "[HTTPS versus SSH](https://happygitwithr.com/https-pat#https-vs-ssh)" page.
119
-
120
-
Follow the steps of your chosen authentication method in the tabs below.
121
-
122
-
:::panel-tabset
123
-
#### Personal Access Token
124
-
125
-
**All of the code chunks for authenticating with a token are {{< fa brands r-project >}} R code that should be run in the "Console" pane of RStudio.** You may also create a script and run the code from there if you so desire but you'll likely only need this code once so the script's value would be short-lived.
126
-
127
-
```{r token-process-1}
128
-
#| eval: false
129
-
130
-
# Install the `usethis` and `gitcreds` packages
131
-
install.packages(c("usethis", "gitcreds"))
132
-
133
-
# Create a token (Note this will open a GitHub browser tab)
134
-
## See steps 6-10 in GitHub's PAT tutorial (link below)
135
-
usethis::create_github_token() # <1>
136
-
```
137
-
1. Leave parentheses empty
45
+
The below preparation steps includes some code for making sure everything is installed as it should be. All code is either R code ({{< fa brands r-project >}}) or is command line code ({{< fa terminal >}}). **In either case, you'll run all provided code <u>in RStudio</u>**. {{< fa brands r-project >}} R code should be run in the "Console" tab of RStudio while {{< fa terminal >}} command line code should be run in the "Terminal" tab of RStudio.
138
46
139
-
_Copy your token at the end of the above step._ Once you leave the page where your token is displayed you'll <u>never</u> get to see it again! So if you close that page without copying it you'll need to make a new one in order to continue.
140
-
141
-
Once you've copied your token, run the code below to save your credentials in RStudio.
142
-
143
-
```{r token-process-2, eval = FALSE}
144
-
# Now, give your token to RStudio
145
-
## After you run this line follow the prompts in the "Console" tab of RStudio
146
-
gitcreds::gitcreds_set() # <2>
147
-
```
148
-
2. Leave parentheses empty here as well!
149
-
150
-
This line of code will prompt you to paste your token in the "Console" tab. After you do so, your token will be safely stored in RStudio!
151
-
152
-
<palign="center">
153
-
<imgsrc="images/external_images/gitcreds_set.png"alt="Screenshot of the Console prompt returned when you run 'gitcreds::gitcreds_set()' in R"width="55%"/>
154
-
</p>
155
-
156
-
##### Further Information
47
+
<u>If you get errors with the provided code, _double check that you are running it in the right place</u>!_
48
+
:::
157
49
158
-
You may also find [GitHub's PAT tutorial](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token) (this is the link referenced in the first token-authentication code chunk!) or the [Happy Git with R PAT tutorial](https://happygitwithr.com/https-pat.html) helpful.
50
+
#### 1. Create a GitHub Account
159
51
160
-
#### SSH
52
+
{{< include prep-steps/create_github-acct.qmd >}}
161
53
162
-
**All of the code chunks for authenticating with SSH are {{< fa terminal >}} command line code that should be run in the "Terminal" pane of RStudio.**
54
+
#### 2. Install R
163
55
164
-
First, we need to check whether you already have SSH keys created on your computer. If you get a message saying that nothing exists or the path doesn't exist, you do not have SSH keys (yet).
56
+
{{< include prep-steps/install_r.qmd >}}
165
57
166
-
```{bash ssh-check, eval = F}
167
-
ls -al ~/.ssh/
168
-
```
58
+
#### 3. Install RStudio
169
59
170
-
If you do need to create an SSH key pair you can do so via the command line. When you create a key pair you'll need to include a descriptive comment to help 'future you' if you ever have multiple key pairs in your life. We recommend "lter" plus your GitHub username to keep things simple.
60
+
{{< include prep-steps/install_rstudio.qmd >}}
171
61
172
-
```{bash ssh-make, eval = F}
173
-
ssh-keygen -t ed25519 -C "lter-github"
174
-
```
62
+
#### 4. Install Git
175
63
176
-
:::callout-tip
177
-
## Older Computer?
64
+
{{< include prep-steps/install_git.qmd >}}
178
65
179
-
If you get a warning/error because your system is too old to support the Ed25519 algorithm (that's the variant recommended by GitHub) you can instead use:
66
+
#### 5. Check that Git's Installation Worked
180
67
181
-
```{bash ssh-make-variant, eval = F}
182
-
ssh-keygen -t rsa -b 4096 -C "lter-github"
183
-
```
184
-
:::
68
+
{{< include prep-steps/check_git-installation.qmd >}}
185
69
186
-
Accept the prompt to save the key in the default location by hitting Enter. You will be prompted to enter a passphrase that will be required to access your SSH key later on. This step is technically optional but is considered a best practice. <u>If SSH keys are totally new to you, we recommend skipping the passphrase step.</u>
70
+
#### 6. Connect Git and GitHub
187
71
188
-
Once you've generated the key pair, follow [GitHub's instructions](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent#adding-your-ssh-key-to-the-ssh-agent) on adding that key pair to your computer's ssh-agent (roughly equivalent to a password manager but just for SSH key pairs).
72
+
{{< include prep-steps/connect_git-github.qmd >}}
189
73
190
-
Finally, you need to share the public key with your GitHub self. Once again we'll refer you to [the phenomenal materials](https://happygitwithr.com/ssh-keys#provide-public-key-to-github) generated by Dr. Bryan on this topic.
74
+
#### 7. Celebrate!
191
75
192
-
##### Further Information
76
+
{{< include prep-steps/celebrate.qmd >}}
193
77
194
-
You may also find [GitHub's SSH documentation](https://docs.github.com/en/authentication/connecting-to-github-with-ssh) or the [Happy Git with R SSH tutorial](https://happygitwithr.com/ssh-keys) helpful.
195
78
:::
196
79
197
-
### 7. Celebrate!
198
-
199
-
After following all the previous preparation steps, your setup should now be complete.
200
-
201
80
## GitHub + Science Publications
202
81
203
82
The reproducibility and collaborative benefits of GitHub for working scientists is well appreciated and increasingly well published upon. See below for brief synopses of papers published in this realm that we think may resonate with your team's disciplinary backgrounds and motivations.
0 commit comments