Lab 01 - GitHub

Published

November 6, 2024

Modified

November 7, 2024

Note

The content of this lab is based on UofU’s PHS 7045 (Advanced Programming with R and HPC) (link).

Learning goals

In this lab1, you are expected to learn/put into practice the following skills:

  • Forking on GitHub
  • Git workflow clone/commit/push
  • Using pull requests (PR)

Updating a single repo

One of the most common tasks that people use git for is collaborating. While in general team members organize such that there are no overlapping editing of the files, git is smart enough to avoid clashes when multiple edits are done in the same document2. To show this, we will do a collaborative edit of a file!

We will be working with the repository https://github.com/EpiForeSITE/whoamit

Step 1: For the project in your repo

Not a term/command available in Git, forking is a feature available in GitHub (as in other services) that allows users to create copies of other people’s projects to propose changes (i.e. make pull requests, i.e. “I have this great update to your project! Would you like to add it by pulling it into your repo?”).

To start you just need to use the Fork button available on the project you would like to contribute to3:

Source: GitHub Help

Once you “Fork” a project, GitHub will:

  1. Create a copy (using git clone) of that project in your account.

  2. Set up a pipeline to generate pull requests.

Once you have a copy of the project in your account, you can proceed by “downloading it” to your computer using the git clone command. For example, if your GitHub user name is statsnerd and the original repository is Spoon-Knife (as in the example), you could use the following in your command line

cd a-place-where-you-want-to-download-the-thing
git clone https://github.com/statsnerd/Spoon-Knife.git

And if you have your ssh credentials set up, you can do it instead

cd a-place-where-you-want-to-download-the-thing
git clone git@github.com:statsnerd/Spoon-Knife.git

This way you will get a copy of the repository in your local machine. Now, let’s see how can we update the project!

Step 2: Modifying the corresponding line

If you got the correct copy, you should find a very simple repository with only two files: .gitignore and README.md. The first file is just a reference file for git to know what things it should be “looking at” (checkout the lecture slides), so we will ignore it at this time (pun intended). The second file is the one that we will be playing with. The readme file, which happens to be a Markdown file, contains, or at least will contain, your and your team members’ biographies. Here is what you need to do:

  1. Find the line with your name/student id number.

  2. In that single line (i.e. not spanning multiple lines), write something about yourself, e.g. “I am from XYZ, I love doing ABC, …”.

  3. (optional) if you feel like it, add at the beginning of the line a picture of yourself (or your avatar) using either HTML or Markdown. This will require you to include the figure in the repo (if you are not linking a web fig).

  4. Commit the changes and push the changes to your repo using git commit and git push, e.g.

git commit -a -m "[A short but meaningful message]"
# git add [your-avatar.png] ... if you need to add a picture
git push

You are now one step closer to making your first “pull request”. We will see how that happens in the next part.

Step 3: Do the pull request

This is the final step. Overall, pull requests (PR) are as complex as the proposed changes are. The PR that you are about to make should go smoothly, yet, any time that you make a new PR, the changes should be able to be merged in the original repository without conflicts. Conflicts may only appear if the proposed changes are outdated concerning the main repository, meaning that the main repository was modified after your fork and your proposed changes cannot be merged without generating conflicts4. For now, let’s just look at the simple case.

To create the PR, you just need to go to your online copy of the project and click on the “Compare & pull request” link:

This will create a PR in the reference repository. GitHub will automatically analyze the PR and check whether merging the PR to the master branch will result in a conflict or not. If all is OK, then the owner/admin of the repository can merge the PR. Otherwise, if there’s a conflict, you can go back to your local repo, make the needed changes, commit the changes, and push the changes to your copy on Git Hub. In this stage, the PR will automatically update to reflect the new changes you made in your copy of the project.

For more information check out Creating a pull request from a fork on GitHub.

ForeSITE

Footnotes

  1. This lab was originally developed by George Vega Yon for USC’s Intro to Health Data Science.↩︎

  2. Team members could be working on the same file but editing different lines of code. If this is the case, after pull/push, git will integrate the changes without conflicts.↩︎

  3. For more details, take a look at the Forking Projects article in GitHub guides.↩︎

  4. More info about how to deal with conflicts in this very neat post on stackoverflow.com How to resolve merge conflicts in Git. GitHub also has a way to solve conflicts in PRs, but this is only available to the admins of target repo. More info here,↩︎