不会所有问题都涵盖，因此当发现没有解决方案时，搜索 https://docs.github.com/cn 查询，然后把解决方案补充到 style guide (提交 PR 完成)。

1 Preparation

安装R、RStudio、Git软件

1.1 安装R及RStudio

R是底层软件，RStudio是使用它比较方便的软件，界面友好。

安装R

1.打开网址 https://cran.r-project.org/banner.shtml

2.选择 Download R for Windows

3.选择 install R for the first time

4.选择 Download R 3.x.x for Windows

5.然后点开对应的.exe文件，安装好

RStudio

1.打开网址 https://rstudio.com/

2.下载 RStudio，Shiny和R Packages两个暂时不用管

3.选择Free的第一个 Download RStudio – RStudio

4.然后点开对应的.exe文件，安装好。

1.2 安装Git

打开官网地址 https://git-scm.com/download/win

Figure 1.1: 选择适合电脑版本的git并下载

注意安装时设置Git可以被第三方软件调用，为后期RStudio使用(如果你们看不到图片，就注意一下next时不选择默认的use git from git bash only,选第二个git from the command line......)

Figure 1.2: 设置Git可被第三方软件调用

2 Git基本使用

2.1 Clone项目

clone项目相当于将Github上的项目（usd-dea里的所有文件夹及文件）复制到本地，这样后续我们可以直接运用git、RStudio完成本地上传文件(push)、从Github更新文件(pull)以保证本地与远程(Github)文件的一致。

打开RStudio，clone你的第一个项目(usd-dea)

github项目地址:圆圈里是地址，点方框复制，如下图

然后等着，成功之后

以上，clone项目完成

2.2 基本Git命令的使用

git pull, git add, git commit, git push, git ignore

这是我们最常用到的命令，建议熟练使用。为了更好理解git命令，这里举例介绍文件更新和上传的方法一：

2.2.1 git pull

目的:将Github上别人提交后的文件更新到本地，保证本地与远程文件的一致
操作:鼠标定位到本地储存项目(usd-dea)的地址——即上面clone项目时自己选择的地址，右键git bash here，命令行输入：git pull origin master

注意：在add 和 push 文件前都要进行git pull操作，否则容易发生错误。如果实在怕错，可以在添加文件前每次都进行pull操作

2.2.2 git add

目的：添加本地文件到缓存区，为接下来push缓存区文件到github(远程)准备
操作：在想要(在github)上上传文件夹的本地文件夹目录下方，添加文件，然后将鼠标定位到本地储存项目(usd-dea)的地址，同样git bash here，或者直接在前一步基础上进行

命令行输入：git add .

在本地的usd-dea文件夹相应位置中添加文件，RStudio中的git就会自动识别，自动进行add的操作。如：将相应的rmd文件零存在../refs下面。后续在RStudio中就可以进行commit和push的操作。

2.2.3 git commit

目的：add 文件后，commit想描述的信息，比如想关联某一issue，可以直接#该issue
操作：附注改文件的XXX信息，并关联第54个issue:git commit -m "XXXX #54"

2.2.4 git push

目的:将add在缓存区的文件push到远程Github上
操作:命令行输入：git push origin master

如果还有不明白的地方，可以参考：

https://www.cnblogs.com/zeo-to-one/p/8367801.html

https://jiaxiangbu.github.io/learn_git/output/git-github-gitlab-learning-notes.html

https://my.oschina.net/u/3828037/blog/1838718

2.2.5 gitignore

目的：gitignore的作用是允许我们将一些本地存储内的文件忽略而不上传至云端，从而允许在commit和push之后本地与云端出现区别。
操作：右键点击Rstudio右上窗口中出现的Diff，点击ignore，则此步骤会被忽略而不同步至云端。
注：通常情况下我们并不需要使用gitignore，只有当我们在本地缓存内创建了包含个人密码或其他不可共享信息的文件时，或者本地文件过大不适合同步至云端时，我们才使用gitignore。

2.2.6 cherry-pick

Figure 2.1: 摘取对应几个 commit id。

2.2.7 错误提交不相关文件

第一种情况是因为不是从 master 开始提交导致的，把某个 branch (相比 master) 多了不必要的 commit id 导致的；第二种情况是因为 gitignore 问题，比如当某个 branch 有 ignore 某个文件，但是 checkout 到 master 时，ignore 没有更新，因此这个文件被 add + commit 了。

Figure 2.2: 第一种情况是因为不是从 master 开始提交导致的，把某个 branch (相比 master) 多了不必要的 commit id 导致的；第二种情况是因为 gitignore 问题，比如当某个 branch 有 ignore 某个文件，但是 checkout 到 master 时，ignore 没有更新，因此这个文件被 add + commit 了。

3 RMarkdown使用

主要包括RMarkdown基本用法、文献综述编写

3.1 RMarkdown基本用法

3.1.1 引用

当我们想引用文献中的某段话时，单引号+这段话：

>XXXXXXXX

3.1.2 加粗部分信息

**XXXXXX**

3.1.3 文字变为斜体

*XXXXXX*

3.1.4 给上传文件路径

方法一:找到上传文件的目录(下图画圈那里)，复制到你想评论issue的comment

方法二:[该文件名称](文件网址)

3.2 RMarkdown文献综述

3.2.1 准备工作

改镜像：安装Rmarkdown之前先把镜像改成清华的，不然容易被墙

如下图：

安装包：必要时安装某些包，用来读取文件

安装包用命令在console里面：install.packages("包名")

调用包时：library(包名)
编辑数学公式：

1.方法：mathpix官网下载后，用mathpix截图需要的公式粘贴后，复制用双$框柱的内容到Rmd文件里即可，很简单，不会使可以问我，也可以看一下学长的这篇文章 https://jiaxiangbu.github.io/awesome-application/learning_notes.html

2.对latex在md文件里无法显示的解决办法：

法一：直接把公式截图，粘贴到Rmd文档。

法二：将md文件转为html文件，按照3.2.3方法输出html文件即可
添加图片：如果综述需要图片，先将图片保存到本地项目的figure文件夹下，然后在RStudio中graphics("图片目录")调用，如下图
bibtex文件：

1.下载bibtex：书写Rmd文献综述前，要找到参考文献的bibtex，一般paper做citizatio时可以直接下载bibtex(谷歌学术可下载)，比如这个paper我要下载为bibtex格式

2.保存为bib文件：本地新建文本文档，把框住的部分复制进去，并另存为XXX.bib(文档拓展名.txt改为.bib)，编码形式也改为UTF-8

注意：

1.为了防止R读取文件出现错误，一定要注意最好英文命名bib文件，不要有空格和特殊字符，同时编码形式改为UTF-8

2.一篇文献综述可能包含几篇文献，可以把这几篇文献的bibtex放到一个bib文件里，这样方便调用

3.2.2 Rmd文献综述

1.新建Rmd文档

默认的output是html文件，要改成github的，如果你需要pdf版本的，也可改成pdf
bibliography后面的是bibtex所在的文件目录，你下载并整理好bibtex之后，把它放到本地项目的refs里，refs后面是bibtex的名字

2.书写文献综述

基本格式：

---
title: "文献综述"
author: "苗蕾蕾"
output: github_document
        word_document: default
        html_document: default
bibliography: ../refs/add.bib
---
{r,include = FALSE} 
knitr::opts_chunk$set(warning = FALSE , message = FALSE)
@XXX 说明借鉴的地方
或者[@XXX] 说明借鉴的地方

# 参考文献 {-}

保持 @xxx 后面空一格，否则会判断为@xxx中文，这样会报错。

解释：

@XXX就是bibtex里@article{后面的内容(逗号别复制)，复制粘贴到这里就好了
@XXX借鉴的地方 表示 XXX认为......
[@XXX]借鉴的地方 表示 ......(XXX)

3.knit出md文件或者其他形式的文件

knit出的结果会自动保存在本地项目的output文件夹中，且与你命名的Rmd文件名称相同

如果我们需要把总结出来的结果给陆老师或者其他没有github账号的人看，可以Knit出md文件的同时，产出一个html文件，也上传到github上，然后找到这个html文件的网址，比如说：https://github.com/JiaxiangBU/usd-spatial_panels/blob/master/analysis/wenxianzongshunengyuanguojia.html 我们把他改成https://jiangxiangbu.github.io/usd-spatial_panels/analysis/wenxianzongshunengyuanguojia.html 在确保项目的github pages开了的情况下，html文件就可以直接访问了。

3.2.3 文献综述提交

方法一：见2中git 基本命令的使用，按顺序先pull、再add这些文件、commit描述信息、push到github上。
方法二：直接在RStudio中操作：

1.做的改动全部选上，或者选择你要选的

2.commit

3.增加commit的信息，一般就是你修改了什么

4.pull

5.push
方法三：直接在github相应的文件夹下upload文件

3.2.4 结语

注意：避免使用中文和特殊字符命名任何文件：包括图片、paper名称、bibtex名称、Rmd文件等等。因为中文是 non-ASCII 编码，当你的电脑默认 encoding 不是 acsii 时，但是服务器是 acsii，就会判断不一致,可能提交的commits会很乱，具体见bug消除。所以避免使用中文和特殊字符命名文件

大家在设置PC的用户名时尽量使用英文，和研究工作相关的重要文件夹也尽量用英文命名，否则在使用各种软件时容易报错。例如，如果用户名为中文，会导致RStudio无法Knit出MD文档，原因是Knit时临时文件的路径问题。但如果PC用户名已经为中文则不建议修改会导致打不开大量文件。这种情况下可以选择Knit出HTML文件并正常commit和push。

3.3 用Rmarkdown完成Gitbook

目的：如果你想写一本书，或者形成我这样的笔记，用Rmarkdown完成gitbook输出即可
基本格式：

---
title: 深度学习相关笔记
author: XXXX
date: "2020-10-27"
output:
    bookdown::gitbook:
      split_by: none
      split_bib: TRUE
      df_print: paged
bibliography: refs/add.bib
---
# 一级标题
## 二级标题
### 三级标题

# 参考文献 {-}

4 Github 使用与管理

4.1 Github使用

4.1.1 新开issue

assign某些人，这样可以让学长或者其他同学看到与自己相关的问题
如果是刚开的issue，可以把它的project(assign的下方)改成 to do，如果是读完了一篇文献然后写了总结才开的新issue，project再从to do 改成in progress，这样我们后续对issue进行管理
同时把对应的label改了，第一次提交问题 good first issue…具体分类见github里issue页面右边的labels

4.1.2 comments回复

引用文献的原文，不要截图，因为截图没法让其他人直接定位到你引用文献的位置，使用 >粘贴你要引用的内容到 comments里。
对应文献上传时 paper上传至项目的 paper/里，bibtex上传至 refs/里，图片放在 figure/ 里，Rmd的综述传到 analysis/，数据上传到data/ 生成的md文档是默认在output文件夹里的，因此md文件和html文件上传至 output/里。同时注意不要中文命名这些文档，上传方式见https://jiaxiangbu.github.io/usd-dea/analysis/git.html 中2.2及3.2的方法一、方法二、方法三

4.2 Github管理

我们使用board管理Github里面的issue，具体来说：

当 issue open 就会进入 to do，当 close 就会进入 done，当 reopen 就会进入doing
目的是我们把 Board 去替换构建 Weekly Issue
节省力气，然后也能抓下当前重点需求的进度

具体操作步骤为：

board name自己命名就好，默认default

4.3 R 相关 bug 提交

Figure 4.1: 清空相关的环境对象后再给复现代码和数据，这样的话，不会导致环境中某个中间对象，复现者没法获取。

5 GitHub Pull Request

参考 https://github.com/JiaxiangBU/usd-dea/pull/67#pullrequestreview-396423491

首先 pull locally 进行代码修改，然后我在 commit 的时候，列举这四点
然后 push 后，在 GitHub 上针对对应的代码行进行备注
这样形成的 review 给人的就会非常清楚哪些地方需要修改、或者讨论。

Figure 5.1: 提交文档，新建 PR 的思路

5.1 在线提交

library(tidyverse)

knitr::include_graphics(fs::dir_ls(here::here("figure/"), regexp = "2020102221"))

5.2 RStudio 里面提交

目的：

运用pull request可以对Rmarkdown文件和实证上传的代码进行点对点的修改。具体来说，pull request上传文件有三大优势：第一，pull request可以对文学编程、代码存在的问题直接点对点注释和修改，并将修改前后的变化展现出来；第二，pull request支持多人协作，也就是说，对于你上传的代码或者Rmd文件，组内的很多人都可以在这个基础上进行review和修改，直到这些代码或者Rmd文件完全不存在问题；第三，一般来说，因为pull request是在分支上进行的，所以在学长merge之前，其他同学或学长所做的修改都不会显示在master上，可以保持master上信息的干净和完整性

举个简单的例子，试想一下考试后老师改卷的场景:首先我们add某些文件提交到分支，就相当于把你自己写完了的卷子给了学长或其他同学，然后你pull request相当于发出一个请求，希望他能修改你的卷子，直到这份卷子完全不存在错误，学长就可以把这份正确的试卷merge到它的master上。

操作：

1.建立branch，并命名：这里我们选择直接在RStudio中进行，如下图

2.add要提交的文件

3.commit：commit changes里信息包括两部分，标题以及list，第一行写标题，比如相关联的issue等，空一行写list，list的主要部分是文件的改动和重要信息。因为pull request里也有标题和list，这样你上传之后计算机会自动识别标题和list内容到pull request

4.git pull

5.git push

6.new pull request，同时选下reviewer、assign等选项

这里为了加深理解，举个例子。 1. 中英文互译，建立一个表格去操作，而非不直接写代码，效率不高， 2. title 可以用中文 3. 用相对路径 4. 长宽表我都帮你建立好了，宽表可以直接进入模型

Figure 5.2: 这里为了加深理解，举个例子。 1. 中英文互译，建立一个表格去操作，而非不直接写代码，效率不高， 2. title 可以用中文 3. 用相对路径 4. 长宽表我都帮你建立好了，宽表可以直接进入模型

附录

5.3 共同编辑

body 每个 issue 第一个文本框，右上角可以点击修改，这个权限是对所有项目人的方便一起编辑。
comment 但是第二个文本框开始，右上角可以点击修改，这个权限是对项目 master 和 comment 所有人才有权限编辑，不方便合著。

6 其他实用性技巧

6.1 caj转Pdf

参考 https://jingyan.baidu.com/article/9f63fb914a181ec8410f0e77.html

点击文件-打印，弹出打印列表；
在打印选项中的打印机中，选择和PDF相关的打印机，常见的如，Microsoft print to pdf、adobe PDF 等,如果安装有WPS的可能会直接有WPS的pdf转换选项，也可以选；
设置打印的范围，如果你想直接转换所有页码，那么基本就不用更改，直接点击确定。在弹出的保存位置中选择好存档位置；
确定后会看到转换的进程，进程结束后，会为我们打开PDF的文档。

Git, Github 使用与 RMarkdown 语法