-
Notifications
You must be signed in to change notification settings - Fork 72
/
cm004.Rmd
164 lines (100 loc) · 9.61 KB
/
cm004.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
# The version control workflow
Today's topic is version control..
## Learning Objectives
From this lesson, students are expected to be able to demonstrate each of the git/GitHub functionality listed here.
## Working with git and GitHub
Before we dive into concepts, it's important to distinguish between a __local__ repo and __remote__ repo.
- __Local__ refers to things on your own computer. A local repo is a repo found on your hard drive.
- __Remote__ refers to things on the internet. A remote repo lives on GitHub (and possibly other places).
Note that you can have more than one remote repo! Because of this, git names the remote repos. We will only ever be using one remote in STAT 545, and by default, this remote is named __origin__.
### Preliminary: configuring git (3 min)
You'll need to [config your git](http://happygitwithr.com/hello-git.html) using the command line.
Your RStudio will probably be able to "find" git. But if it can't, you'll encounter errors. See [happygitwithr: see-git](http://happygitwithr.com/rstudio-see-git.html) for help.
__Optional__ (but recommended): After class, you might want to [cache](http://happygitwithr.com/credential-caching.html) your credentials so that you don't have to keep inserting your password.
### The typical workflow (8 min)
The majority of your interaction with version control will be a pull/stage/commit/push workflow, explained here. For another resource on this, check out [happygitwithr: rstudio-git-github](http://happygitwithr.com/rstudio-git-github.html).
0. __Clone__ your repository if you don't have a local copy.
Once you have a local copy of the repository, then working on a project involves frequent use of these three steps:
1. __Pull__ the remote repo.
2. Make changes to your files, __stage__ and __commit__ them.
3. __Push__ the changes (after perhaps pulling again).
Git treats the remote repository as the "official" version of the repository. This means that your local copy is a second class citizen -- the repository you have locally must be up-to-date with the remote repository before you are allowed to push your work. If there are commits on the remote repository that are not present locally, git will throw an error if you try to push your changes.
Integrate version control as you do work!
- Workflow without version control: save your files spontaneously.
- Workflow with version control: save your files spontaneously, commit your changes after every "step" in your work, and push your changes [in case of fire](https://github.com/louim/in-case-of-fire).
Committing often ensures that you can trace back all the work you did. This results in transparency with the way your project has developed, which is a very effective workflow. But, from my experience at least, making half baked work viewable might face you with feelings of vulnerability. I encourage you to push past this.
### The typical workflow: Activity (5 min)
Let's make a change to our repository from local.
1. Cloning your participation repo.
- In RStudio, File -> New Project -> Version Control -> Git.
- You should see a `Git` tab in RStudio, upper-right corner window. If not, see [happygitwithr: see-git](http://happygitwithr.com/rstudio-see-git.html) for help.
- Take a look at the files you just downloaded!
2. Make your README a little nicer. Maybe fix up the title.
3. Stage and commit the changes:
- In the Git tab in RStudio, click the checkboxes for the files that you want to commit. This is called "staging".
- Click the "Commit" button.
- Enter a commit message.
- Click "commit".
4. Push to your remote repository (which is named "origin")
- Click the up arrow in the Git panel in RStudio.
### Git Clients (3 min)
We just saw that RStudio can "talk to" git. But there are other ways we can use git locally. To "directly" interact with git, we type commands in the terminal (or bash) like `git clone`, `git commit`, etc. If you want to access the full functionality of git, you'll need to use the terminal.
Alternatively, there are _git clients_ that provide a visual dashboard for interacting with git. RStudio is one example. Others:
- GitHub Desktop
- Source Tree
- Gitkraken
- ...
In STAT 545, we'll be using the RStudio git client, but you can use whichever method you prefer.
### Merge conflicts (5 min)
If you change a file locally, and that same file (_and_ the same lines) get changed on the remote repository in a different way, you'll end up with a _merge conflict_ that you'll need to resolve. Remember that your local copy is a second class citizen compared to the remote version, so you'll have to resolve things locally before pushing to the remote.
### Merge conflicts: Activity (5 min)
Let's make a merge conflict, and fix it.
1. Edit a line of your README both locally and remotely to something different in both cases. Commit both changes.
2. Try pulling your remote changes. You'll get a _merge conflict_.
3. Update the file that has the conflict, commit your changes, and push.
### Branching (8 min)
Branching is the idea of making commits somewhere other than your main repository on GitHub. Even cloning a repo is a type of branch.
Git and GitHub allow us to make branches _within a repository_, and we can do this both locally and on GitHub (although it seems the RStudio git client doesn't provide functionality for local merging). Let's check out the [STAT545-UBC.github.io](https://github.com/STAT545-UBC/STAT545-UBC.github.io/) repo to see some branches (which is actually being phased out).
Eventually, you may want to merge a branch back to its predecessor. This is called __merging__. A merge specifically on GitHub initiates a __pull request__ -- the idea here being that you'd like the predecessor branch to _pull_ the commits from the child branch, and you're _requesting_ it from the collaborators on your repository (which is sometimes just yourself). [Example from STAT545-UBC.github.io](https://github.com/STAT545-UBC/STAT545-UBC.github.io/pull/64) again. For more info on pull requests, see this [GitHub tutorial](https://help.github.com/articles/about-pull-requests/).
There are many reasons you may want to branch. Here are some:
- A collaborator wants to make a change to the repo, but the end product of the change requires review from collaborators.
- You want to make changes, but don't want to "deploy" the changes until later (such as if pushing to github triggers a website build).
- If you want to try something "risky", it's just safer to work on a branch.
### Branching: Activity (5 min)
Let's organize our participation repo in a branch.
1. Create a new branch locally, called "organizing" (we could have also made this on GitHub):
- Click the "Git" tab in the upper-right panel of RStudio
- Within that window's option bar, click .
- Name your branch and create!
2. Stage and commit the new files.
3. Restructure your repository in a more sensible way, using folders (locally).
4. Stage and commit the changes; push to GitHub.
5. Explore:
- switch between branches to see that the repo structure is different.
6. Merge the branch to "master" via GitHub by making a pull request.
### Undoing Changes (5 min)
There are many ways that work can be "undone" in git. We will only investigate two of the simpler methods. For more advanced methods, like reverting to a previous commit, check out these resources by [bitbucket](https://www.atlassian.com/git/tutorials/undoing-changes) and [GitHub](https://blog.github.com/2015-06-08-how-to-undo-almost-anything-with-git/) -- you'll need to use the command line.
The two most useful "undo"s are:
1. Undoing your (uncommited) work to the previous commit.
2. Browsing the repo at previous states, and taking files from there.
We'll demonstrate (1) in an activity.
### Undoing Changes: Activity (2 min)
Here's how to go back to the most recent commit.
1. First, make and save a change to (say) a README file in your participation repo.
2. In the Git panel of RStudio, stage the file that you want to return to the previous commit. Click "More" -> "Revert..." -> "Yes"
That's it!
### Getting errors? (3 min)
It's not unusual to experience some errors in git, especially if you're first learning how to use it. Try to get yourself unstuck with the concepts we've discussed here first.
But, you might find yourself stuck. The git documentation is full of jargon, making it difficult to read and therefore difficult to debug things. There's even a [parody](https://git-man-page-generator.lokaltog.net/) on it. If you are in this position, it's best to just [burn it all down](http://happygitwithr.com/burn.html). There's even an [xkcd comic](https://xkcd.com/1597/) on this.
### Tagging a Release (5 min)
Tagging a release on GitHub is like putting a "star" next to a particular commit. It highlights a particular point in time of your repository that is noteworthy, typically after achieving some milestone. It's just easier than having to manually keep track of noteworthy points in your commit history.
Examples:
- After every year of finishing STAT 545A/547M, we tag a release so that we can easily navigate to earlier versions of the course.
- After sufficient development of an R package like [ggplot2](https://github.com/tidyverse/ggplot2/releases), a new release is tagged corresponding to the version of the package.
### Tagging a Release: Activity (3 min)
Congratulations! We finished the first two weeks of STAT 545A, which focussed on _tools_. To mark this milestone, let's tag a release on our participation repositories.
1. On your GitHub repo, click "releases"
2. Click "Create a new release"
3. Fill in the fields:
- It probably makes sense to use a versioning system like `cm004` here.
4. "Publish Release".