Collaborate With GitHub

Session 6

September 19, 2024

Review

Word Bank

repo | commit | remote | push | pull | add

1. A collection of files tracked by git
2. A snapshot of the state of a repository
3. git ___ is used to tell git to track a file
4. For example, a repo on GitHub
5. git ____ is used to synchronize changes on your computer with a remote

Review

What difficulties did you have while putting your repo on GitHub?

Collaborating with GitHub

A GitHub repo can be used to coordinate collaboration

If two people have permissions, both can push changes to the repo

Ask for a volunteer and give them permission to push to a repo

Figure 2 from (Bryan 2018)

Example repo

• Everyone practice cloning this example repo as a new RStudio project: https://github.com/cct-datascience/demo-repo-2024 ¹

• Need one volunteer to edit the README.md and practice commit + push

Dealing with Conflicts

• What happens when two people make conflicting edits to a file and push them?

• Creates a merge conflict

Ok, try git pull

Merge, rebase, fast-forward??

• These are alternative ways to deal with conflicts—we won’t get into the details

• For now, we recommend you stick with the “merge” option

Use:

git config pull.rebase false

Or, if you want to set this option for all future repos too

git config --global pull.rebase false

Fixing a Merge Conflict

1. Resolve the conflict however you want (i.e. keep one of the two sections)

2. Delete all lines with <<<<<<<, >>>>>>>, or =======

3. Save and commit

Let’s have a round of applause for our volunteer!

Avoid merge conflicts by working on branches

Each person works on a “branch”—an independent series of commits that can be merged back into the “main” branch.

gitGraph
   commit
   commit
   branch person_1
   commit
   commit
   commit
   checkout main
   branch person_2
   commit
   commit
   checkout main
   merge person_1
   merge person_2
   commit
       

Working on a Branch

• Make a new branch using RStudio’s Git pane (for this demo, use your name)

• Make some edits (e.g. to README.md), save, add, commit.

• You can go back to the “main” version of your project at any time.

Demonstrate how switching branches changes the files on their computer. Hammer home that this is why it is a bad idea to use git for projects on shared drives.

Working on a Branch

• Push your branch to GitHub

• View changes on GitHub

Show how to look at different branches on GitHub

Pull Requests

A request to merge changes into the main branch

• Need another volunteer to share screen and be guided through making a pull request

• This time, everyone can follow along!

Forks

What if you don’t have permission to push to a GitHub repo but you want to contribute?

Make a fork!

Since you can’t push to “upstream”, you can make a connected copy on GitHub called a “fork”

You can clone the fork and since you own it, you can push to it.

On GitHub, you can sync upstream changes with your fork and you can make pull requests to integrate changes on your fork into upstream.

That means you can contribute to anything! (as long as it is a public repo)

Collaborating with Forks

To contribute to a repo you don’t have push permission for:

1. Fork the repo to your own GitHub
2. Clone the fork to your local computer
3. Make commits (ideally on a branch)
4. Make a pull request to the upstream repo

Tip

Learn more, including handy usethis shortcuts: https://happygitwithr.com/fork-and-clone

Practice

Exercise

In pairs, practice forking and cloning a demo repo you do not have permission to push to: https://github.com/cct-datascience/demo-repo-fork-2024.
Make a new branch, make commits, and make a pull request to the upstream repo.

Encourage learners to use forking and cloning to explore and contribute to any code they can find on GitHub including R packages and research compendia.

Resources

• Forking and cloning

• Pull request helpers in usethis

• #git channel in UA Data Science Slack

Your Tasks

• For the next update to your colloquium project, practice using a branch and and pull request on GitHub

• Clone a repo you do not have permission to push to without forking it and see what happens when you try to use git push

• Fork and clone a repo on GitHub to explore it (e.g. a lab mate’s code, a research compendium, your favorite R package)

References

Bryan, Jennifer. 2018. “Excuse Me, Do You Have a Moment to Talk about Version Control?” The American Statistician 72 (1): 2027. https://doi.org/10.1080/00031305.2017.1399928.

Footnotes

1. Read more about GitHub organizations