-
Notifications
You must be signed in to change notification settings - Fork 3
/
skills_faq.qmd
363 lines (218 loc) · 14.2 KB
/
skills_faq.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
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
---
engine: knitr
execute:
freeze: auto # re-render only when source changes
---
# Skills faq {#sec-skills-faq}
## git issues
### Set my name and email
git wants to add your name and email to commits. These are distinct from your `github` account (remember `git` can be used independently of an online service or with online services other than github).
If you are seeing messages that end like this:
```
You can suppress this message by setting them explicitly. Run the
following command and follow the instructions in your editor to edit
your configuration file:
git config --global --edit
After doing this, you may fix the identity used for this commit with:
git commit --amend --reset-author
```
Then you can run these commands to set a username and email. Note that these can be anything, they aren't a login or checked against anything, they are just metadata attached to your commits. Nonetheless having them make sense for your identity makes sense when sharing code publically. They can easily be a made up identifier (pseudonym/handle/accountname).
``` bash
git config --global user.name "John Doe"
git config --global user.email johndoe@example.com
```
### Login to GitHub {#sec-github-login}
On the commandline we have to use the username/PAT combination. The password that works to log into GitHub on the web will not work.
If you see this message:
```
remote: No anonymous write access.
fatal: Authentication failed for <repo_url>
```
Then you need to log in, but first reset the credential cache:
```sh
git config --global credential.helper 'cache --timeout=10000000'
```
Then repeat the command that failed (hit the up-arrow twice usually brings it up).
When you see this prompt, use your GitHub username (not the email address)
```
Username for 'https://github.com': <your_github_username>
```
When you see this prompt, even though it says "password" you must use your PAT token:
```
Password for 'https://<your_github_username>@github.com':
```
On windows you may have to use the right-click context menu to paste into the terminal.
### Password pop-up repeats too often {#sec-pass-popup}
The username/password pop-up can come up too often. Especially with GitHub requiring a PAT (and not the same password used on the website) this can be a hassle, since the PAT is not configurable and has to be copy/pasted.
Rstudio is generating that pop-up, but the frequency is controlled by a gitconfig variable. The default without configuration is 15m so if we don't run a git command for 15m it expires the cache and pops up again. We can make it show up less with:
``` sh
git config --global credential.helper 'cache --timeout=10000000'
```
That means that the cache won't expire for 10,000,000 seconds (which is 16 weeks).
Thanks to <https://happygitwithr.com/https-pat.html#store-credentials-through-organic-git-use> and the Rstudio community forums for helping me with that <https://community.rstudio.com/t/git-user-pass-pop-ups-when-using-git-in-terminal-window/161213>
### Shortcut to find GitHub URL {#sec-find-github-url}
A short cut to find the URL is `git remote -v`
```sh
~/workspace/i320d-testing2024$ git remote -v
origin https://github.com/jameshowison/i320d-testing2024.git (fetch)
origin https://github.com/jameshowison/i320d-testing2024.git (push)
```
And then copy the URL (with or without the .git at the end). On windows you may need to use the right-click context menu for copy and paste in a terminal.
### git commit throws me into a weird mode {#sec-vim}
If you type `git commit` just on its own rather than `git commit -m "Some message"` you will see something like this:
``` bash
# Please enter the commit message for your changes. Lines starting
# with '#' will be ignored, and an empty message aborts the commit.
#
# On branch master
# Your branch is up to date with 'origin/master'.
```
git needs a commit message. When you don't provide one it throws you into a text editor, expecting you to type a small novel.
The editor that you go into by default is the `vi` or `vim` editor. It can be confusing because it has multiple modes (ie typing doesn't always just produce text).
The best option is to:
1. Hit `esc` twice: <kbd>Esc</kbd> <kbd>Esc</kbd>\
2. Type `:q!` and hit <kbd>Enter</kbd>
3. Redo your commit using \`git commit -m "Some message"
See <https://stackoverflow.com/questions/11828270/how-do-i-exit-vim>
**The option below does not work in Rstudio because Rstudio captures the** <kdb>Ctrl</kdb> key commands
You can also configure git to use another editor: <https://stackoverflow.com/questions/2596805/how-do-i-make-git-use-the-editor-of-my-choice-for-editing-commit-messages>
For example, the `nano` editor is easier to use. You can set that run running
``` bash
git config --global core.editor "nano"
```
In `nano` we can type a commit message as usual. The bottom of the screen shows commands. Nano uses the `^` symbol to represent the <kdb>Ctrl</kbd> key. We have to save the file and then exit Nano. So to save the message and return to the commandline we use:
<kbd>Ctrl</kbd> + <kbd>O</kbd>
Then:
<kbd>Ctrl</kbd> + <kbd>X</kbd>
## I accidentally made my home folder a git repo {#sec-faq-home-git-folder}
If you are in your home folder but `git status` doesn't give a "fatal error" then you've accidentially made your home folder into a git repository (probably by running `git init` in that folder).
In this case we need to undo this. We can't delete our home folder, because it has everything else inside it. We have to somehow tell the computer that the home folder should not be a git repo. Happily, then only thing that makes it a git repo is that it has a `.git` folder inside it. You can confirm by running:
``` sh
ls -lah
```
The `-a` flag to `ls` makes it show all files and folders, even the hidden ones that start with a dot.
To fix this we could just delete the `.git` folder but we might lose data that way (if we had already added work to that repo). So safest thing is to make a new folder inside our home folder, and then move the `.git` there.
``` sh
mkdir backup_home_git
mv ./.git ./backup_home_git
```
Now you could `cd backup_home_git` and use that folder as a git repo. But probably you are about to clone from github (in which case a new folder will be created) or you are about to use `git init` to create a new local repo (in which case you should create a folder first, `cd` into it, then run `git init`.
## Vizualizing git trees (aka gitviz) {#sec-gitviz}
In this course we are using a command that I usually call "gitviz" for short:
``` sh
git log --oneline --abbrev-commit --all --graph --decorate --color
```
This produces reasonably readable graphs (especially for the teaching repos used in this course).
They look like this:
``` bash
jlh5498@educcomp04:~/github_repos/i320_test3,,\n git log --oneline --abbrev-commit --all --graph --decorate --color
* d8ab2c1 (HEAD -> main, origin/main, origin/HEAD) Merge pull request #1 from jameshowison/new-feature
|\
| * ffb601d (origin/new-feature, new-feature) added extra
|/
* f256ee7 Added line to README
* 093fb0c Initial commit
```
Or as an image (with coloring as on Edupod Rstudio):
![Image showing output of gitviz command shown as text above](images/gitviz_example.png)
You can read a little more about how to read these graphs here <https://stackoverflow.com/questions/22313343/git-graph-what-do-the-lines-and-asteriks-denote>
Long story short:
- The asterisk characters (`*`) show a single commit
- The lines formed with characters like (`| \ /`) help us follow which branches a commit was on.
- The words in parens show branch names, and can include the names of remotes (e.g., `origin/new-feature` means the `new-feature` branch on the `origin` remote)
It is a long command, so you can either keep it handy in a pastebin (I use Typinator) or you can register it as a command alias for git itself:
``` sh
git config --global alias.viz 'log --oneline --abbrev-commit --all --graph --decorate --color'
```
So then you can just type:
``` sh
git viz
```
## Seeing a merge conflict using git log
In one assignment students have to submit a repo showing a resolved merge conflict when accepting a PR. This raised the question of whether I could see this looking at the repo. Student questions helped me figure that our, leading me to <https://stackoverflow.com/questions/15277708/how-do-you-see-show-a-git-merge-conflict-resolution-that-was-done-given-a-mer> which highlighted this as an issue in presenting merge conflicts for review. The most recent answer, led me to discover a new feature in `git`
``` sh
git log --remerge-diff
```
This enables one to see the files with the `<<<<<<` type conflict markers shown.
```{sh}
#| echo: true
#| output: true
#| collapse: true
rm -rf merge-conflict-example
git clone https://github.com/jameshowison/merge-conflict-example.git
cd merge-conflict-example
git log -1 --skip 1 --remerge-diff
```
```{bash}
#| echo: false
#| output: false
rm -rf merge-conflict-example
```
## Gathering the code as though the PR had been accepted {#sec-fetch-pr}
Sometimes it is useful to be able to work with the code that would result if the PR was accepted, but without actually accepting the PR. Sometimes this is called "previewing the PR". It is useful when working with PRs from others, and can also be useful when working on our own branches, but where we don't want to merge that branch to main (which is a difficult operation to undo).
On GitHub (and other online repositories like Gitlab or BitBucket) we can do this because the pull requests are added to the online repository, somewhat like branches. [We can access these](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/checking-out-pull-requests-locally) using the git `fetch` command pointing to the `pull` part of the repository.
```sh
git fetch origin pull/123/head:pr-123
git checkout pr-123
```
This obtains the code **as though the PR had been accepted** and then makes a new _local branch_ that we can work with. Notice, though, that thje new local branch is not the same branch that the PR is for ... it is a local copy. Therefore we would not push that new local branch back up to GitHub, preferring to work with the PR itself (and [here is documentation about how to allow others to edit your PRs](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/allowing-changes-to-a-pull-request-branch-created-from-a-fork)).
# How to add an image using quarto on edupod
Quarto is like html in that the main `.qmd` document references separate image files, rather than incorporates them inside the main file itself. You have to place the images separetely (and also `git add` the image files separately).
On Edupod getting figures into your quarto document takes two steps:
1. Upload the file to the server
![](images/upload_file_to_edupod.png)
2. Use the Visual mode in the quarto file editor to insert the picture.
![](images/insert_image_to_qmd.png)
Using the Render button will confirm that your images are found.
Then don't forget to `git add` the image files as well. Run a `git status` to check which files are included.
# Tab Set Play
::: {.panel-tabset}
## Mac
Some content
## Windows
Some content
## Other
Still more.
:::
<!-- # Why does ggplot require less tidy data for multiline graphs? (aka longer less tidy) -->
<!-- tl;dr: when using a `group` like aes (`group` itself or `color`) you often need to transform data from a wider (but tidy) format into a longer (and arguably less tidy) format. -->
<!-- In the Tidy Data paper Wickham shows an example of tidying data from a longer format to a wider format. In the example he creates two new columns `tmax` and `tmin`. He argues that this wider format is tidier because each row contains an observation with two measured variables (tmax and tmin). -->
<!-- ![Table 12 from Wickham's Tidy Data paper](images/tidydata_table12_tmax_tmin.png){fig-alt="Tables showing a longer form on the left (a type column called 'element' with the values tmax and tmin), and a wider form on the right (separate columns titled tmax and tmin)"} -->
<!-- ```{r} -->
<!-- table12_df_wider <- tribble( -->
<!-- ~id, ~date, ~element, ~value, -->
<!-- #--------------------------- -->
<!-- "MX17004", 2010-01-30, "tmax", 27.8, -->
<!-- "MX17004", 2010-01-30, "tmin", 14.5, -->
<!-- "MX17004", 2010-02-02, "tmax", 27.3, -->
<!-- "MX17004", 2010-02-02, "tmin", 14.4, -->
<!-- "MX17004", 2010-02-03, "tmax", 24.1, -->
<!-- "MX17004", 2010-02-03, "tmin", 14.4, -->
<!-- "MX17004", 2010-02-11, "tmax", 29.7, -->
<!-- "MX17004", 2010-02-11, "tmin", 13.4, -->
<!-- "MX17004", 2010-02-23, "tmax", 29.9, -->
<!-- "MX17004", 2010-02-23, "tmin", 10.7 -->
<!-- ) -->
<!-- table12_tidy <- table12_df_wider %>% -->
<!-- pivot_wider(names_from = element, values_from = value) -->
<!-- table12_tidy -->
<!-- ``` -->
<!-- Yet it is common to want to graph both of these variables as a multi-line graph. This is possible because both variables are expressed in the same terms (both are degrees), so only a single scale is needed. Nonetheless, this is actually tricky to do in this wider tidier format. Because it requires two column names, which must be hard coded. We also can't easily get a legend. -->
<!-- ```{r} -->
<!-- table12_tidy %>% -->
<!-- ggplot(aes(x = date)) + -->
<!-- geom_line(aes(y = tmin), color = "green") + -->
<!-- geom_line(aes(y = tmax), color = "blue") -->
<!-- ``` -->
<!-- Another approach enables us to get as many lines as there are, and get automatic colors and legends. This uses the `group` aesthetic. But to do this we need all the column names in a single column as strings. This changes our data back into the longer format. -->
<!-- ```{r} -->
<!-- table12_longer_again <- table12_tidy %>% -->
<!-- pivot_longer(cols = c(tmax, tmin), names_to = "measure", values_to = "temperature") -->
<!-- table12_longer_again -->
<!-- ``` -->
<!-- This is identical to where we started, with Table 12a (other than changed column names!). Yet this can be much more easily graphed, giving much easier access and automatic scales (and thus legends). -->
<!-- ```{r} -->
<!-- table12_longer_again %>% -->
<!-- ggplot(aes(x = date, y = temperature, color = measure)) + -->
<!-- geom_line() -->
<!-- ``` -->