-
Notifications
You must be signed in to change notification settings - Fork 1
/
Copy pathgithub_intro.qmd
120 lines (66 loc) · 8.57 KB
/
github_intro.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
---
title: "Version Control with Git and GitHub"
---
## The problem with "Save As"
Every file in the scientific process changes. Manuscripts are edited. Figures get revised. Code gets fixed when problems are discovered. Data files get combined together, then errors are fixed, and then they are split and combined again. In the course of a single analysis, one can expect thousands of changes to files. And yet, all we use to track this are simplistic *filenames*. You might think there is a better way, and you'd be right: __version control__.
{width=60% fig-align="center" fig-alt="A comic about managing revisions using filenames"}
Version control systems help you track all of the changes to your files, without the spaghetti mess that ensues from simple file renaming. In other words, version control is a system that helps you to manage the different versions of your files in an organized manner. It will help you to never have to duplicate files using "save as" as a way to keep different versions of a file (see below). Version control helps you to develop a timeline of snapshots containing the different versions of a file. At any point in time, you will be able to roll back to a specific version. Bonus: you can add a short description (commit message) to remember what each specific version is about.
**What is the difference between Git and GitHub?**
- __Git__: is version control tool used to track versions of files in a folder or "repository" (to use git's terminology).
- It is open source software -- [the Git project uses Git](https://git.kernel.org/pub/scm/git/git.git)!
- It works best for tracking revisions to plain-text files.
- __GitHub__: is web-based platform for storing git repositories developing software collaboratively.
- It adds many features to manage projects and document your work.
- it is a commercial product from Microsoft.
## Git
This section focuses on the code versioning tool, Git. There are others tools for source code management, such as Mercurial and Subversion, but Git is the most widely used.
Git is a *free* and *open source* distributed *version control system*. It has many functionalities and was originally geared towards software development and production environment. Git was initially designed and developed to track the development of the Linux kernel.
**What git is not:**
- Git is **not a backup** per se.
- Git is not good at versioning large files. It works best with plain-text files, not large data sets.
::: {.callout-note collapse=true}
### Fun fact
Git was initially designed and developed in 2005 to track the development of the Linux kernel. Here is a [fun video](https://www.youtube.com/watch?v=4XpnKHJAok8) of Linus Torvalds touting Git to Google engineers.
:::
### Repository
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 are many ways to start a new repository, [GitHub](https://github.com/) (or any other cloud solution, such as [GitLab](https://about.gitlab.com/)) provides among the most convenient way of starting a repository.
## GitHub
**GitHub is a company that hosts git repositories online** and provides collaboration features like forking and pull requests. GitHub has a large user community and has built a nice web interface to git, also adding great visualization/rendering capacities of your data.
### GitHub Dashboard
This is the default landing page when you log into your account. It provides a mix of the most recent resources and activities of your and your collaborators' actions, as well as some resources relevant to your work. The dashboard therefore changes on a regular basis. Once logged in, you can access your dashboard at <https://github.com>
{width=80% fig-align="center" fig-alt="Screenshot of Github's Dashboard" .lightbox}
### GtiHub User page
This page can be reached using the following URL: https://github.com/`username`. For my username (`brunj7`) it would be: <https://github.com/brunj7>. It is a great space for you to provide some information about yourself and the main repositories you are working on. It also lists the GitHub Organizations you are part of. But more importantly, Users own repositories to host and share their code. You can list repositories from a User by clicking on the _repositories_ tab in the main GitHub menu bar at the top.
{fig-align="center" width=80% fig-alt="Screenshot of Github's user page" .lightbox}
### GitHub Organization page
We will talk more about GitHub Organizations later. In a nutshell, organizations are like groups or teams that users can be members of. Like Users, Organizations can have a landing page and own repositories. However, they add several perks in terms of user management. Similarly to Users, you can access repositories from an Organization by clicking on the _repositories_ tab in the main GitHub menu bar at the top. You can access an organization's page similarly to a user: https://github.com/`organization-name`; e.g. <https://github.com/UCSB-Library-Research-Data-Services>
{fig-align="center" width=80% fig-alt="Screenshot of GitHub's Organization page" .lightbox}
### Let's look at a repository on GitHub
The screenshot below shows the landing page of a repository on GitHub. We would like to highlight different important parts of this view:
- Directly under the navigation bar (top-left) you will find the name of the repository (orange)
- Above the files listing, there is information about the latest commit to this repository (blue)
- On the left, you will have the files and folder names (red)
- In the middle, the last commit message on this file (or file contained in a folder) (purple)
- On the right, the time stamps of the latest commit (green)
{fig-align="center" width=80% fig-alt="Screenshot of a GitHub repository landinglanding page" .lightbox}
Below the file listing, there will be a rendering of the README.md file, one more reason to make sure to add one 🙂.
Looking into more details at the information provided about the last commit, we can see that we know:
- Which user made the last commit (brunj7) and the associated commit message
- The the 7 first digit of unique identifier ([SHA](https://en.wikipedia.org/wiki/Secure_Hash_Algorithms)) of this commit
- When this last commit was made (3 months ago)
= The total number of commits on this branch (43 Commits)
{fig-align="center" width=80% fig-alt="Screenshot of the last commit message for a repo on GitHub" .lightbox}
This total number of commits is a hyperlink that lets you access the full history of the main branch by clicking on it.
{fig-align="center" width=80% fig-alt="Screenshot of a repo's commit history on GitHub" .lightbox}
We can keep drilling and look at a specific commit by clicking on the hash number listed on the right. For example, we can look at the first commit at the top (d2b75a5) and display the exact changes that have been made since the previous (also named `parent`) commit `20bc390`:
{fig-align="center" width=80% fig-alt="Screenshot of a commit's details on GitHub's" .lightbox}
Tracking these changes, and seeing how they relate to scripts and files is exactly what Git and GitHub are good for. We will show how they can be effective for tracking versions of scientific code, figures, and other text files such as manuscripts to develop a reproducible workflow.
## Recap
- **GitHub.com / your dashboard (if logged in)**: <https://github.com>
- **A user account**: <https://github.com/brunj7>
- **An organization account**: <https://github.com/UCSB-Library-Research-Data-Services>
## Recommended reading
Braga PHP, Hébert K, Hudgins EJ, Scott ER, Edwards BPM, Sánchez Reyes LL, et al. _Not just for programmers: How GitHub can accelerate collaborative and reproducible research in ecology and evolution._ Methods in Ecology and Evolution. 2023;14: 1364–1380. [doi:10.1111/2041-210X.14108](https://doi.org/10.1111/2041-210X.14108)
## Aknowledgements
This materials was adapted from [NCEAS Reproducible Research Techniques for Synthesis](https://learning.nceas.ucsb.edu/2021-02-RRCourse/index.html) & [Collaborative Coding with GitHub. LNO Scientific Computing Team](https://github.com/NCEAS/scicomp-workshop-collaborative-coding).