-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathgithub.qmd
171 lines (111 loc) · 10.6 KB
/
github.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
---
title: "Git & GitHub"
---
## Module Learning Objectives
By the end of this module, you will be able to:
- <u>Describe</u> the difference between Git and GitHub
- <u>Navigate</u> GitHub via a web browser
- <u>Use</u> GitHub to create a new repository
- <u>Edit</u> a new repository through GitHub's interface
## Version Control Background
Version control systems (including Git) are built to preserve the iterative versions that we create on the way to a final product. For instance, when writing a scientific manuscript we might have several discrete stages (e.g., separate drafts after successive rounds of feedback from collaborators) as well as the sort of small-scale changes we don't necessarily preserve in separate files (e.g., workshopping a particular sentence for rhetorical flow).
**Version control systems provide a framework for preserving these changes without cluttering your computer with all of the files that precede the final version.**
<p align="center">
<img src="images/comics/phd_comics_final.png" alt="Comic of a graduate student naming a file 'final.doc' then getting progressively more frustrated and making worse file names as that file received iterative comments from an advisor" width="60%"/>
</p>
## Git-Specific Background
Git can be enabled on a specific folder/directory on your file system to version files within that directory (including sub-directories). In Git (and other version control systems) terms, this "tracked folder" is called a **repository** (which formally is a specific data structure storing versioning information).
Although there many ways to start a new repository, [GitHub](https://github.com/) (or any other cloud solutions, such as [GitLab](https://about.gitlab.com/)) provide among the most convenient way of starting a repository.
Let's distinguish between Git and GitHub:
- **Git**: version control software used to track files in a folder (a repository)
- Git creates the versioned history of a repository
- **GitHub**: website that allows users to store their Git repositories and share them with others (i.e. a graphical user interface or "GUI")
**GitHub is a company that hosts Git repositories online** and provides several collaboration features. GitHub fosters a great user community and has built a nice web interface to Git, also adding great visualization/rendering capacities of your data.
- **GitHub.com**: [github.com](https://github.com/)
- **A user account**: [github.com/angelchen7](https://github.com/angelchen7)
- **An organization account**: [github.com/lter](https://github.com/lter)
## Exploring GitHub
Let's navigate over to [GitHub](https://github.com/) and explore some of its features. Here is what the home screen looks like as of February 2022.
<p align="center">
<img src="images/github/github-1-website.png" alt="Screenshot of the GitHub landing page when you go to 'github.com' and are not signed in" width="100%"/>
</p>
Log in with your GitHub account that you should have created prior to this workshop.
<p align="center">
<img src="images/github/github-2-login.png" alt="Screenshot of the pop-up that appears when you click 'sign in' on GitHub"width="40%" />
</p>
Once you've logged in, you should see something like this:
<p align="center">
<img src="images/github/github-3-signed-in.png" alt="Screenshot of GitHub home page after you've signed in" width="100%"/>
</p>
This landing page has a nice summary of your recent repositories and activity on the left panel. Click on your icon at the top left corner and navigate to your profile.
<p align="center">
<img src="images/github/github-4-profile-light.png" alt="Screenshot of the landing page on a particular GitHub profile" width="100%"/>
</p>
Your profile page shows the organizations that you're a part of, as well as a more detailed view of your GitHub contributions/activities over time. There are also tabs at the top that lead you to your repositories, projects, packages, and starred repositories. If you would like, you can change your GitHub theme to dark mode by clicking on your icon at the top left corner and going to **Settings** then **Appearances**. For the purposes of this workshop, the rest of the screenshots for the GitHub website will be in dark mode to differentiate it from RStudio.
<p align="center">
<img src="images/github/github-5-dark-mode.png" alt="Screenshot of the 'appearance' section of a GitHub user's settings area" width="100%"/>
</p>
If there is anything else you would like to change about your account, the user settings page should have it.
### Looking at a GitHub Repository
To check the repositories that you've created, click on the **Repositories** tab. Note that the top left corner has a green button that will allow you to create new repositories. We will come back to that later. Let's take a closer look at what the ucsb-ds-capstone-2021.github.io repository contains.
<p align="center">
<img src="images/github/github-6-my-repos.png" alt="Screenshot of the 'repositories' tab of a user on GitHub" width="100%"/>
</p>
This screen shows the copy of a repository stored on GitHub,
with its <span style="color:red">list of files</span>, <span style="color:green">when the files and directories were last modified</span>,
and <span style="color:blue">some information on who made the most recent changes.</span>
<p align="center">
<img src="images/github/github-7-example-repo.png" alt="Screenshot of the landing page for a particular repository. A blue rectangle surrounds the information about the most recent commit, a green box surrounds the 'last modified' date for all files in the repository (on the right side of the page), and a red box surrounds the the file and folder names (left side of the page)" width="100%"/>
</p>
If we look at the blue rectangle, we can see that there have been 151 commits made to this repository. By clicking on them, we can see the history of changes made to all of the files. Looks like 3 users were making changes in April.
<p align="center">
<img src="images/github/github-8-commit-history.png" alt="Screenshot of the commit history of a single repository. Shows a list of commits in reverse chronological order (i.e., most recent on top) along with their dates and their respective commit messages" width="100%"/>
</p>
And finally, if we examine one of the changes made on April 25, we can see exactly what was changed in each file:
<p align="center">
<img src="images/github/github-9-specific-changes.png" alt="Screenshot of the changes made to a single file in one commit. Added lines are in green while deleting lines are in red" width="100%"/>
</p>
The red lines have been deleted while the green lines are new additions. Tracking these changes, and seeing how they relate to released versions of software and files is exactly what Git and GitHub are good for. We will show how they can really be effective for tracking versions of scientific code, figures, and manuscripts to accomplish a reproducible workflow.
Note: it is possible to edit and add files entirely on the GitHub website, by navigating to the specific file or repository. However, for this workshop, we will be editing and adding files through RStudio instead.
<p align="center">
<img src="images/github/github-10-edit-file.png" alt="Screenshot of a file being viewed in GitHub with a yellow circle around the pencil icon on the top right corner of the file. The pencil has a hovering message above it labeled 'edit this file'" width="100%"/>
</p>
<p align="center">
<img src="images/github/github-11-add-file.png" alt="Screenshot of a GitHub repository landing page where the 'add file' button has been clicked and a yellow circle surrounds the 'create new file' and 'upload files' buttons in the sub-menu that action created" width="100%"/>
</p>
### Creating a Repository on GitHub
To stimulate a collaborative GitHub/RStudio workflow, we are going to have 1 person from each group create a new repository on their GitHub account. This will be the repository where everyone shares their files and code.
To create a new repository, follow these steps:
- Navigate to your profile page and click on the **Repositories** tab.
- Click on <span style="color:green">**New**</span>.
<p align="center">
<img src="images/github/rstudio-1-github-profile.png" alt="Screenshot of the 'repositories' landing page of a particular GitHub user" width="100%"/>
</p>
- Enter a descriptive name for your new repository, here we named it `git-practice` (avoid upper case and use `-` or `_` instead of spaces).
- Write a 1-sentence description about the repository content.
- Choose **Public** (as of January 2019, GitHub now offers unlimited free private repositories with a maximum of 3 collaborators).
- Check **Add a README file**.
<p align="center">
<img src="images/github/rstudio-3-new-repo-edits.png" alt="Screenshot of the page on GitHub that appears when you click 'new repository'. Contains empty dialogue fields for the repository name and description as well as options for public versus private repositories among other initialization options" width="60%"/>
</p>
Yay! We've just created a new repository! Here is what the landing page should look like:
<p align="center">
<img src="images/github/rstudio-5-new-repo-code-tab.png" alt="Screenshot of a new repository containing only a README file" width="100%"/>
</p>
This repository is currently public, so it's visible to anyone, but since we are working in groups, we will need to give access to your group members. Click on the **Settings** tab for your repository and go to **Collaborators**.
<p align="center">
<img src="images/github/rstudio-5b-collabs-2-settings-collabs.png" alt="Screenshot of the 'settings' pane of the new repository shown in the prior image" width="100%"/>
</p>
Click on <span style="color:green">**Add people**</span>. Now let's get the usernames of all of your group members and add them as collaborators to your repository.
<p align="center">
<img src="images/github/rstudio-5b-collabs-3-search-for-users.png" alt="Screenshot of the dialogue box prompting the viewer to enter names or emails of people to add as collaborators" width="40%" />
</p>
<p align="center">
<img src="images/github/rstudio-5b-collabs-4-added-new-user.png" alt="Screenshot of the confirmation message to add a collaborator once they've been selected based on their username or email" width="40%" />
</p>
Great! Now everyone in the group should have access to the repository.
## Create a Repository on GitHub
:::callout-note
## Practice
Now that we've walked through how to create a repository on GitHub let's try to make our own! Click over to GitHub and create your own repository (with a README.md). We'll split into breakout groups to try this out and please let us know if any questions come up.
:::