Syllabus

Hao Ye Health Science Center Libraries, University of Florida (updated: 2022-07-19)

Intro

  • Motivations
    • Version control can help you manage collaborative work.
    • There are many ways to collaborate using Git… not all of these are ideal for small research teams!
    • “GitHub flow” is a lightweight workflow for individuals and small teams.
  • Learning Outcomes
    • describe how merge conflicts originate and how to resolve them
    • apply the “GitHub flow” workflow for collaborating
    • create and navigate branches on GitHub and using GitHub Desktop
    • create and merge pull requests
    • understand “forks” and open-source-community development on GitHub
  • Prerequisites This lesson assumes you:

Merge Conflicts

  • Inviting Collaborators
    • I have a github repo, and would like to give my collaborator access to work on the project.
    • From the github repo page:
      • Settings -> Manage access
      • Invite a collaborator A screenshot of the website https://github.com/ha0ye/portalDS/settings/access, showing that the repo is visible to the public, and that only the owner can contribute to the repository. There is a green button with the text 'Invite a collaborator'.
  • Example collaboration Two people, A and B, are working together on one repo in GitHub:
    • A creates new commits, A pushes the commits to GitHub.
    • B pulls the latest commits from A (via GitHub), creates new commits, and pushes their commits back to GitHub.
    • A pulls the latest commits from B (via GitHub), creates new commits, etc.
  • What happens if you forget to pull? You get a warning when you try to push to GitHub. A screenshot of the warning from using GitHub Desktop when trying to push new commits to GitHub, and there are commits on GitHub that have not yet been fetched and merged locally. The warning reads 'Newer Commits on Remote; Desktop is unable to push commits to this branch because there are commits on the remote that are not present on your local branch. Fetch these new commits before pushing in order to reconcile them with your local commits.'
  • Merging
    • git merge combines the changes from commits:
      • A and B start with commit: {orig}
      • A makes commit {a}
      • B makes commit {b}
      • git merge combines {a} and {b} into a new commit {c}, that contains both sets of changes.
  • Merging (automatically)
    • IF the changes are in different files OR different parts of the same files
      • git is generally able to create the merged commit without further intervention
    • if git is unable to merge automatically, then there is a merge conflict
  • Resolving merge conflicts
    • when git cannot combine the changes automatically, you must tell it what the correct contents should be for the merge commit.
    • for a text file: A screenshot of BBedit showing the merge conflict. Line 6 is '<<<<<<< HEAD'`' indicating the start of one version of the file. Line 8 is '=======' indicating the end of one version and the beginning of the next. Line 10 shows '>>>>>>>' followed by a hash, indicating the end of the second version.
  • Resolving merge conflicts 2
    • After all the conflicts are resolved, you can create the merged commit.
    • This merged commit can then be pushed to github without issue.
    • For non-text files, git will not show you the differences across versions - you will need to combine changes yourself.
      • e.g. open an image editor to edit the image file and incorporate changes from the two separate commits.
  • Summary
    • This approach works pretty well when:
      • there is one primary contributor
      • collaborators make changes rarely
      • everyone knows the steps to pull, commit, push.
      • everyone communicates that there are updates for others to pull from GitHub.

GitHub Flow

  • Essentials of GitHub Flow
    • Use branches to store all work progress.
    • Merge branches back to the primary branch when the work for that branch is complete. A screenshot of the diagram from https://guides.github.com/introduction/flow/, showing conceptually how the 'GitHub flow' workflow works.
  • Steps
    1. Create a branch and switch to it.
    2. Add commits with desired changes.
    3. Open a pull request (PR).
    4. Review the PR if necessary, and merge.
    5. Delete branch if done.
  • What is a Branch?
  • If Git is a time machine that lets you navigate to different times (commits), then branches are alternate timelines.
  • How do branches work?
    • You start in the primary branch.
      • each commit records changes from the previous commit
      • result: a sequence of project versions
    • Branches let you store multiple sequences.
      • create a new branch - good for experiments
      • merge if/when you want
  • Creating new branches (GitHub) screenshot of the GitHub interface, when clicking on the pulldown menu to switch branches; this interface also enables one to create new branches.
  • DEMO
  • Creating new branches (GitHub Desktop) screenshot of the GitHub Desktop interface, when clicking on the pulldown menu to switch branches; this interface also enables one to create new branches.
  • DEMO

Merging Branches

  • Merging (branches)
    • Nearly the same as merging commits:
      • merge all the changes from another branch to the current branch.
    1. switch to the branch that will hold the merged result
    2. merge from the other branch
  • DEMO (GitHub Desktop)
  • Pull Request (GitHub) Pull Requests:
    • are recommended practice for merges on GitHub
    • let you document the merge
      • you can request official “review”
      • other collaborators can comment, make further changes
  • DEMO (GitHub)

Community-oriented Development on GitHub

  • Issues Issues are conversations on GitHub:
    • reported bugs, feature requests, etc.
    • anyone can contribute to discussion
    • can be referred to by number in commits and pull requests
  • DEMO
  • Forks
    • How do you contribute to other people’s projects?
      • Fork = clone a repo on GitHub
      • Forks retain memory of original repo
      • Pull Requests can include merges from across forks.
  • Contributing to OS Combining this all together, “Fork and PR” is a workflow for contributing to someone else’s project (without write access):
    1. fork a repo to your GitHub account
    2. make changes on the repo in your GitHub account
    3. create a pull request to ask for those changes to be merged into the original project repo ## Thanks
  • Let me know what content you’d like to see
  • Contact me for additional questions or consultation requests!
  • Check back in on the libguide for more modules and contact info: