-
Notifications
You must be signed in to change notification settings - Fork 0
/
04-lecture-4.Rmd
260 lines (133 loc) · 13.3 KB
/
04-lecture-4.Rmd
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
# Git Branches
In this lecture, you will learn how to create and utilize git branches.
So far, you have been pushing all your files to the master branch. And that's fine when you are working on your own. But not so fine when you are working with other people!
The master branch is the front-facing view of your project. You can think of it as the latest "complete" version of the project, or the most up-to-date version of the project. You may not want all your works in progress to show up in the master branch, especially when decisions are still being made about certain aspects of the project. This becomes more crucial when you are part of a team.
One way to make sure that your collaborators do not overwrite the master branch with their changes without team approval is to have a branch that essentially clones the master branch but acts as a "workspace" for any revisions. This is especially helpful when each individual in a team is assigned a specific task to work on. They could do so in their own branch before merging all the results together.
This might be a relatable example: You have a personal statement for graduate school named `main_personal_statement.docx`. You send the document to your former advisors. Your advisors read the statement and send you a version of document with tracked changes called `main_personal_statement_their_initials.docx`. You want to be able to implement all their feedback into one document, so you open up each of document you get back and implement the feedback in the main version of the document.
With branches, each of your advisors could have worked in a branch, and you could have determined which parts of the duplicate version could be merged back into the main version.
In this lecture, I will go through how to work with branches in the RStudio environment.
## Creating a branch {#create-branch}
1. Open your ps811-project in RStudio.
2. Click on the "branch" icon in the Git pane.
*New branch: test.*
3. In the "New Branch" pop-up, name your new branch "test."
*Git Branch pop-up.*
4. The Git Branch window will pop-up, creating your new branch.
*RStudio Git pane takes you to the "test" branch.*
5. RStudio should have automatically transported you to the new branch on your Git pane.
*Git branches on GitHub.*
6. Go to the GitHub of your ps811-project repository. You should be able to see a branch called `test` in the branch dropdown menu. Next to it, GitHub should tell you that there are 2 branches within your project.
## Working in the branch
1. You are now in the "test" branch.
2. Go to the Files pane and select the `document.Rmd` file.
3. Make some edits to the `document.Rmd` file. Whatever you want!
4. Commit, write a commit message, and push. Do what you always do to push something to your repository.
*Recent push to repositorry.*
5. Go to your GitHub repository. You should see a banner that there has been a push to your test branch.
6. Click on the "Compare & pull request" button.
*Open pull request.*
7. On the "Open a pull request" page, make sure you are pulling the "test" branch to the "master" branch. Check if they are able to merge.
- There could some changes that are too different to merge, but it should not be the case for you right now.
8. If you scroll down the "Open a pull request" page, you can see what changes were made. This tells you exactly what files were changed and where the changes occurred.
9. Scroll back up to the form.
*Create pull request.*
10. Click on the down arrow next to the green "Create pull request" button. You will see two options: "create pull request" and "create draft pull request."
- Create pull request: this is the default option. This simply tells whoever is "in charge" of the repository that it is ready to be reviewed and merged. This hierarchy lends itself well to a team where there's some sort of supervisor.
- Create draft pull request: this is the second option. This allows your team to review and comment on it before your supervisor sees it. I wouldn't worry too much about this option right now.
11. Click on "Create pull request." (You can leave a comment if you want.)
*Merge pull request > Create a merge commit*
12. This should take you to the "Pull Requests" page. You will see one pull request open. You will see three options: "create a merge commit," "squash and merge," and "rebase and merge."
- Create a merge commit: this is the default option. This merges your changes on the test branch to the master branch.
- Squash and merge: this combines your changes in the test branch into one commit and pushes it out to the master branch.
- Rebase and merge: this adds the entire history of the test branch onto the master branch *and* commits your changes. Don't worry about this one, but if you would like to read more about it, [Atlassin Bitbucket](https://www.atlassian.com/git/tutorials/merging-vs-rebasing) has a helpful summary of differences between "merging" and "rebasing."
13. Click on the default, "Merge pull request."
14. Click "Confirm merge."
*Pull request success message.*
15. You will receive a message that "Pull request successfully merged and closed."
15. You should be able to see your recent commits from the test branch transferred to the master branch.
## Deleting the branch {#delete-branch}
There may come a time where you might want to delete your branch. How would you go about it?
1. Click on the "# branches" link.
*Your branches.*
2. Click on the red trash on the far right to "test" under "your branches."
## Restoring the branch {#restore-branch}
The great thing about Git is that, even if you accidentally delete a branch, you can always restore it.
*Pull requests link.*
1. Click on "Pull Requests."
*There are 2 closed branches within your repository.*
2. Click on "# closed."
3. Select the "Test" repository.
4. Click on the "Test" repository.
*Restore branch.*
5. Scroll near the bottom of the page and click on the "Restore branch" button.
6. Go back to the ps811-project main page. You should see "test" restored as a branch.
## Using Git on the command line {#use-cmd}
There are a wealth of other things Git can do, and you will find a wealth of resources about Git online. Many of the resources you encounter will pertain to using Git with the command line, which is how software developers have traditionally used it. You may want to familiarize yourself with that, as many of the help resources tend to be specific to Git command line functions, not RStudio functions.
RStudio provides a good jumping off point, though. The Git pane in RStudio opens a shell that takes you to your exact project. In essence, the shell is a tool that allows you to type in commands that tell the computer what to do. In this case, you can type in all the Git commands you need to do without having to go back and forth in the RStudio and GitHub environments. The [Git Cheat Sheet](https://www.atlassian.com/git/tutorials/atlassian-git-cheatsheet) provides pretty good guidance on Git commands.
I will walk through a command line example with you that shows you how to commit and push a file into your repository using the command line. You should already be pretty familiar with the process at this point, so none of the inputs and outputs should not be a surprise to you.
1. Go to RStudio.
2. Open the `document.Rmd` file.
3. Make some edits to the file. Whatever you want!!
4. Knit the file to a PDF. See the edits you made in the .Rmd file show up in the PDF.
*Open the Shell through the Git pane on RStudio.*
*The shell opened. In MacOS, it's called a "Terminal" (featured here). In Windows, it's called a Command Prompt. They're equivalent.*
5. Now open up the Shell.
*Check out the Git status on the shell.*
6. Type `git status` into the command line. You should see information in the shell that mirrors the information in the Git pane.
*Add, i.e., stage all the files.*
7. Type `git add .` into the command line. This tells the computer that you want to stage all the changes (`git add`) in the ps811-project directory (`.` represents the directory you are currently in). The Git pane reflects this change without you having to check all the boxes.
If you do not see the expected changes on your RStudio Git pane, just click on the RStudio window to make it active again and you will see the changes.
*Reset, i.e., unstage all the files.*
8. Type `git reset .` into the command line. This tells the computer that you want to unstage all the changes in the ps811-project directory. The Git pane reflects this change without you having to uncheck all the boxes.
*Stage the document.pdf file.*
9. Type `git add document.pdf` into the command line. This only stages the `document.pdf` file.
*Commit document.pdf and see what happens to the Git pane on RStudio. This means that the test branch (the branch you are working in) has one more commit than the master branch. Which makes sense, because you just made a commit on the test branch.*
10. Type `git commit -m "<your message>"`. This allows you to commit the file and type a commit message. From my example, my commit message is, `pdf changes only`, but you are welcome to write what you want.
*Push the document.pdf file.*
11. Type `git push`. This is akin to pushing the green push arrow icon in RStudio.
12. Go to the ps811-project repository on GitHub. Go to your test branch. You will see that your `document.pdf` has just been updated a few seconds ago.
*Commit the document.Rmd and document.tex files.*
13. Go back to the Shell. You still have `document.Rmd` and `document.tex` in limbo. Commit both files and push.
```
git add .
git commit -m "i am committing both document.Rmd and document.tex right now"
git push
```
*View all the branches in the repository.*
14. Go back to the Shell. Type in `git branch`. It will show all the branches in your ps811-project repository and the branch you are currently in---the test branch---will be denoted by an asterisk (*). In my operating system, it's showing up as neon green text.
*Go to the master branch.*
15. Type in `git checkout master`.
`git checkout master` is the equivalent of switching from the test branch to the master branch on the GitHub repository.
*Merge the test branch with the master branch.*
16. Type in `git merge test`. This merges everything from the test branch to the master branch.
`git merge test` is *kinda* equivalent to opening a pull request and creating a merge on the GitHub repository.
*The final push.*
17. Type in `git push`. This pushes the merge out into the master branch of your GitHub repository.
`git push` at this point is *kinda* equivalent to confirming the merge on the GitHub repository. This is to make sure the two branches (test and master) are even, or the same.
Most of you might not be comfortable with the command line yet and would prefer the point-and-click ease of RStudio, and that's okay! This is *your* workflow and you should choose to work in a way that makes you the most comfortable. You may want to expedite your workflow someday, and this option is here for you if you want it!