9  Advanced Git and Github

Abstract
git and GitHub are perfect for the Issue > Branch > PR workflow. This chapter introduces that workflow.

Image by Pierre-Yves Beaudouin

9.1 The Issue > Branch > PR Workflow

There are several popular workflows for collaborating with Git and GitHub. This section outlines an issue-branch-pr workflow which is extremely common and which we use regularly.

9.1.1 GitHub issues

GitHub issues are a GitHub project management tool for managing to-dos and conversations about a code base. This feature of Github can be seen as a built-in alternative to project management softwares like Jira, Trello, and monday, among many others.

For each substantial change to the code base, open a GitHub issue.

9.1.2 Working with Branches

Branching Motivation

The track changes feature in programs like with Microsoft Word follows each and every keystroke or click. In the previous chapter, we compared git to a super-charged version of track changes, and we think this comparison is fair. However, code is different than prose. If a program is not working, it isn’t desirable to document and share a change until that change creates a different, but still working, program. Working with other developers can complicate this desire to always commit sensible changes.

Meet branching. Branching allows multiple versions of the same program to be developed simultaneously and then merged together when those versions are ready and operational.

Branching Diagrammed

Recall the following diagram from last chapter. We need a way to:

  1. Create branches
  2. Switch between branches
  3. Combine branches

A standard git workflow

A second stylized (and cute!) example of this workflow can be seen in this tweet from Jennifer Gilbert. The octopus on the left side of the image represents an existing, operational piece of code. Two programmers create separate copies (branches) of that code, work to create independent features (represented by the heart glasses and a cowboy hat), and then merge those features back to the master branch when those features are operational.

How to branch

git branch prints out important information about the available branches in a repo. It is similar to git status in that it provides useful information while not making any changes.

git switch -c <new branch name> creates a new branch and then navigates you to the new branch.

git switch <new branch name> navigates you from your current branch to the specified branch. It is only possible to switch between branches if there are no uncommitted changes. 1

  1. Use git switch main to navigate to the main branch. Use git pull origin main to update your local version of the main branch with any remote changes.
  2. Use git switch -c <new branch name> to create and switch to a new branch with the name iss<number>, where is the issue number from GitHub.
  3. Work as if you are on the main branch but push to branch iss<number>.

Jenny Bryan provides a more thorough background.

9.1.3 Pull requests

The easiest way to merge branches is on GitHub with pull requests. When you are ready to merge the code, push all of your code to your remote branch.

  1. On GitHub, click the new pull request button.

An New Pull Request
  1. Then set a pull request from the branch on the right to the branch on the left.

  1. Navigate to the pull requests page and review the pull request.

  2. Merge the pull request:

9.1.4 Putting it all together

  1. Open a GitHub issue for a substantial change to the project
  2. Create a new branch named after the GitHub issue number
  3. After one or more commits, create a pull request and merge the code

9.1.5 Merge conflicts

If you run into merge conflicts, either follow the GitHub instructions or follow Jenny Bryan’s instructions for resolving the conflict at the command line. Do not panic!

9.2 GitHub Pages

As we introduced in Section 8.7, GitHub offers a free and simple tool for a hosting website in a GitHub repository called GitHub pages. A basic setup is to use index.html or README.md as an index to connect individual pages together whose URLs are based on their file names.

Let’s walk through an example:

9.2.1 README as homepage

  1. Create a new local directory with a README.md.
  2. Run echo "<h1>Page 1<\h1>" > page1.html at the command line.
  3. git init, git add, and git commit your changes.
  4. Create a remote repository on GitHub and link it to your local repository.
  5. Push your local changes.
  6. Navigate to Settings in your GitHub repo. Go to GitHub pages and set the source to “main branch”. The page will reload and a link will appear. Go to the link.
  7. Add page1 to the end of the link
  8. Add the link to page1 in the README. git add, git commit, and git push.

9.2.2 index as homepage

The Urban Institute R Users Group website does not use the README as a home page. Instead it uses and index page.

  1. Run echo "<h1>Index<\h1>" > index.html at the command line.
  2. Run echo "<a href="https://awunderground.github.io/git-example/page1">Page 1</a>" > index.html at the command line where url is the link to Page 1 on GitHub pages.
  3. Add, commit, and push your code to the main branch.
  4. After a few minutes return to the link provided on GitHub pages.

9.3 Conclusion

GitHub Pages is a great project management tool. It can be integrated perfectly into the Issue > Branch > PR workflow. Branching is useful to allow separate collaborators to work on different features of a codebase simultaneously without interrupting each other. When conflicts do arise, do not fret! Merge conflicts are normal and can be resolved easily.

9.3.1 More resources

  1. git checkout is another exceedingly common git command. Many resources on the internet may encourage the usage of git checkout <branch name> to switch branches, or git checkout -b <new branch name> to create a new branch and then switch to it. This is okay! However, git checkout also has other capabilities, and that glut of functionality can be confusing to users. This makes git switch the simpler, more modern option.]↩︎