Skip to content

Commit e78fda6

Browse files
lpantanolpantano
committed
clean up docs
1 parent 26f3bb2 commit e78fda6

File tree

4 files changed

+2130
-261
lines changed

4 files changed

+2130
-261
lines changed

‎docs/github.md‎

Lines changed: 226 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,226 @@
1+
## Setting up GitHub and RStudio
2+
3+
Now, we will connect O2 with GitHub. First, check in your Home directory if a `.gitconfig` file exists. ***You should only need to do this once.*** The contents should look like:
4+
5+
```
6+
[credential]
7+
helper = store
8+
[user]
9+
email = your_email@gmail.com
10+
name = your_GitHub_username
11+
```
12+
13+
Where `your_email@gmail.com` is the e-mail associated with your GitHub account and `your_GitHub_username` is your GitHub username.
14+
15+
If you do not have a `.gitconfig` file in your Home directory, follow the instructions in the dropdown below to create a `.gitconfig` file.
16+
17+
<details>
18+
<summary><b>Click here for instructions for making a <code>.gitconfig</code> file</b></summary>
19+
<br>In order to make a <code>.gitconfig</code>, you will need to run the following command:<br><br>
20+
<pre>
21+
usethis::use_git_config(user.name = "your_GitHub_username", user.email = "your_email@gmail.com")
22+
</pre>
23+
You will replace <code>your_GitHub_username</code> with your GitHub username and <code>your_email@gmail.com</code> with the e-mail associated with your GitHub account.<br><br>
24+
<blockquote>
25+
Reminder: If you already have your GitHub username and e-mail associated with your GitHub account in your `.gitconfig` file then you can skip this step.
26+
</blockquote>
27+
Click on circular arrow in the top right of the <code>Files</code> tab called <code>Refresh file listing</code>. You can check that you have successfully made this <code>.gitconfig</code> file by looking for the hidden file in your home directory. The content should look like:<br><br>
28+
<pre>
29+
[credential]
30+
helper = store
31+
[user]
32+
email = your_email@gmail.com
33+
name = your_GitHub_username
34+
</pre>
35+
<blockquote>
36+
Note: In order to see hidden file in your file browser on the O2 Portal, you will need to click on the cog in the top right of the <code>Files</code> tab and select <code>Show Hidden Files</code>.
37+
</blockquote>
38+
<hr />
39+
</details>
40+
41+
### Getting the Git tab
42+
43+
Now, we would like to get the Git tab into our Workspace Browser (where `Environment`, `History`, `Connections` and `Tutorial` tabs are located). We show this transition below:
44+
45+
<p align="center"><img src="./img/Git_pane_RStudio.png" width="1000"></p>
46+
47+
48+
In order to do this we will use the following command:
49+
50+
```
51+
usethis::use_git()
52+
```
53+
54+
This command is the command one would usually use in order to make a commit. However, if we choose to not make a commit and then restart R, it will give us our Git tab in the Workspace Browser. This command should return:
55+
56+
```
57+
✔ Setting active project to "/home/wig051/git_demo".
58+
✔ Initialising Git repo.
59+
✔ Adding ".Rdata", ".httr-oauth", ".DS_Store", and ".quarto" to .gitignore.
60+
ℹ There are 6 uncommitted files:
61+
• .gitignore
62+
• .Rprofile
63+
• DataManagement-Checklist.pdf
64+
• information.R
65+
• README.md
66+
• reports/
67+
! Is it ok to commit them?
68+
69+
1: Yes
70+
2: Negative
71+
3: Not now
72+
```
73+
74+
We do not want to commit these files yet, so select one of the answers like `Negative`, `No way` or `No`.
75+
76+
> Note: It is unclear why Git gives us three choices. The possible choices are re-arranged each time and have different text. So your option may vary a bit from these, select one of the appropriate options for **NOT** commiting.
77+
78+
Next, you will be prompted as to whether you want to restart R:
79+
80+
```
81+
A restart of RStudio is required to activate the Git pane.
82+
Restart now?
83+
84+
1: For sure
85+
2: Negative
86+
3: Not now
87+
```
88+
89+
We will need to restart R in order to get the Git tab in our R Studio, so select `For sure`, `Yeah` or some other option for answering in the affirmative.
90+
91+
### Creating the first commit
92+
93+
Now, we are going to create our first commit. In order to do this, we need to:
94+
95+
1. Navigate to the Git tab in our Workspace Browser
96+
2. Left-click to check the "Staged" checkboxes next to `README.md` and `.gitignore` to select the files that we would like to add to our first commit
97+
3. Left-click <kbd>Commit</kbd> in the Git tab
98+
4. Add a message for our commit
99+
5. Left-click <kbd>Commit</kbd> underneath the textbox where we added the message for our commit
100+
6. Close both Git windows
101+
102+
These steps are summarized in the GIF below:
103+
104+
<p align="center"><img src="./img/Initial_commit.gif" width="1000"></p>
105+
106+
### Pushing our initial commit
107+
108+
Now we will use the function to push these changes to GitHub with the following command:
109+
110+
```
111+
usethis::use_github(org="hbc", private=TRUE)
112+
```
113+
114+
If you do not have a valid GitHub token, this will give you an error (see [below](#expired-or-non-existent-github-token)). If you already have a valid GitHub token, you will get this text in your console and it will push this repository to the HBC GitHub with the following output:
115+
116+
```
117+
ℹ Defaulting to "https" Git protocol.
118+
✔ Setting active project to "/home/wig051/git_demo".
119+
✔ Creating private GitHub repository "hbc/git_demo".
120+
✔ Setting remote "origin" to "https://github.com/hbc/git_demo.git".
121+
✔ Pushing "master" branch to GitHub and setting "origin/master" as upstream branch.
122+
✔ Opening URL <https://github.com/hbc/git_demo>.
123+
```
124+
125+
If the push is successful, then it will look like this GIF below:
126+
127+
<p align="center"><img src="./img/GitHub_initial_push.gif" width="1000"></p>
128+
129+
> Note: You might get a GitHub 404 error page (see image below) when you do your first push to GitHub. Just refresh the page in your browser and it should be resolve itself.
130+
> <p align="center"><img src="./img/GitHub_404_error_with_label.png" width="700"></p>
131+
132+
#### Expired or non-existent GitHub token
133+
134+
However, if your token is expired or this is your first time using GitHub from O2, then you will get this message:
135+
136+
```
137+
ℹ Defaulting to "https" Git protocol.
138+
✔ Setting active project to "/home/wig051/git_demo".
139+
Error in `usethis::use_github()`:
140+
✖ Unable to discover a GitHub personal access token.
141+
ℹ A token is required in order to create and push to a new repo.
142+
☐ Call usethis::gh_token_help() for help configuring a token.
143+
Run `rlang::last_trace()` to see where the error occurred.
144+
```
145+
146+
If this is the case, then you will need to create a new GitHub token, click on the dropdown box below for instructions on how to create a new GitHub token.
147+
148+
<details>
149+
<summary><b>Click here to see how to create a GitHub Token</b></summary>
150+
<br>The first thing we will need to do when setting up our GitHub token is to set-up our credential helper. We can do this by left-clicking on the <code>Terminal</code> table in the Console Window. You may need to load Git in the Terminal using:<br><br>
151+
<pre>
152+
module load git
153+
</pre>
154+
Then you can provide the following line of code to store your GitHub token for future O2 sessions:<br><br>
155+
<pre>
156+
git config --global credential.helper store
157+
</pre>
158+
This process is summarized in the GIF below:<br><br>
159+
<p align="center"><img src="./img/Git_config.gif" width="1000"></p>
160+
Now that we have let Git know to store our GitHub token, we can create one. In order to create a GitHub token, you will need to run:<br><br>
161+
<pre>
162+
usethis::create_github_token()
163+
</pre>
164+
This will take you to a GitHub Webpage. It may prompt you to sign-in to GitHub. From here, you need to name your token and select an expiration date for your token. Then, scroll to the bottom of the page and left-click <kbd>Generate token</kbd>. These step are summarized in the GIF below:<br><br>
165+
<p align="center"><img src="./img/GitHub_token_Part_1.gif" width="1000"></p>
166+
Next, you will want to copy your GitHub Token and go back to RStudio. We need to set our credentials by using the command:<br><br>
167+
<pre>
168+
gitcreds::gitcreds_set()
169+
</pre>
170+
Paste in your copied GitHub token and hit <kbd>Return/Enter</kbd>. It should return:<br><br>
171+
<pre>
172+
-> Adding new credentials...
173+
-> Removing credentials from cache...
174+
-> Done.
175+
</pre>
176+
These steps are summarized in the GIF below:<br><br>
177+
<p align="center"><img src="./img/GitHub_token_Part_2.gif" width="1000"></p>
178+
Now you should have a hidden file called <code>.git-credentials</code> in your Home directory and it should look like:<br><br>
179+
<pre>
180+
https://PersonalAccessToken:YOUR_GITHUB_TOKEN@github.com
181+
</pre>
182+
Where <code>YOUR_GITHUB_TOKEN</code> has been replaced with your GitHub Token.<br><br>
183+
<blockquote>
184+
Note: In order to see hidden file in your file browser on the O2 Portal, you will need to click on the cog in the top right of the <code>Files</code> tab and select <code>Show Hidden Files</code>.
185+
</blockquote>
186+
Next, try pushing your repository to the HBC GitHub again with:<br><br>
187+
<pre>
188+
usethis::use_github(org="hbc",private=TRUE)
189+
</pre>
190+
<hr />
191+
</details>
192+
193+
## Making your first edit
194+
195+
We will now make an edit and push that to GitHub.
196+
197+
### Editing the `README.md`
198+
199+
We are going to edit the `README.MD` using these steps:
200+
201+
1. Open the `README.md`
202+
2. Change the header from `Guidelines` to the assigned HBC code for the project (`PI_brief_description_hbcXXXX`)
203+
3. Save the changes to `README.md`
204+
4. Select the checkbox in the "Staged" area of the Git tab for the `README.md`
205+
5. Left-click <kbd>Commit</kbd>
206+
6. Add a commit description
207+
7. Left-click commit again
208+
8. Left-click <kbd>Close</kbd> to close the pop-up window for the commit
209+
210+
These steps are summarized in the GIF below:
211+
212+
<p align="center"><img src="./img/Guideline_commit_push.gif" width="1000"></p><br>
213+
214+
### Pushing the edit to GitHub
215+
216+
Now that we have made this commit, we will push it to GitHub using these steps:
217+
218+
1. After completing your commit, left-click <kbd>Push</kbd>
219+
2. Left-click <kbd>Close</kbd> to close the pop-up window for the push
220+
3. Close the additional pop-up window
221+
4. Navigate to the GitHub page for this repository
222+
5. Refresh the page if necessary
223+
224+
You should now see the HBC code as the header to the `README.md` on GitHub. These steps are summarized in the GIF below:
225+
226+
<p align="center"><img src="./img/Guideline_push.gif" width="1000"></p><br>

0 commit comments

Comments
 (0)