Version Control with Git: Instructor Notes

Using a software tool to handle the versions of your project files lets you focus on the more interesting/innovative aspects of your project.

• Version control’s advantages
  • It’s easy to set up
  • Every copy of a Git repository is a full backup of a project and its history
  • A few easy-to-remember commands are all you need for most day-to-day version control tasks
  • The GitHub hosting service provides a web-based collaboration service
• Two main concepts
  • commit: a recorded set of changes in your project’s files
  • repository: the history of all your project’s commits
• Why use GitHub?
  • No need for a server: easy to set up
  • GitHub’s strong community: your colleagues are probably already there

Overall

Version control might be the most important topic we teach, but Git is definitely the most complicated tool. However, GitHub presently dominates the open software repository landscape, so the time and effort required to teach fundamental Git is justified and worthwhile.

Because of this complexity, we don’t teach novice learners about many interesting topics, such as branching, hashes, and commit objects.

Instead we try to convince them that version control is useful for researchers working in teams or not, because it is

• a better way to “undo” changes,
• a better way to collaborate than mailing files back and forth, and
• a better way to share your code and other scientific work with the world.

Teaching Notes

• You can “split” your shell so that recent commands remain in view using this script.

• Make sure the network is working before starting this lesson.

• Drawings are particularly useful in this lesson: if you have a whiteboard, use it!

• Version control is usually not the first subject in a workshop, so get learners to create a GitHub account after the session before. Remind learners that the username and email they use for GitHub (and setup during Git configuration) will be viewable to the public by default. However, there are many reasons why a learner may not want their personal information viewable, and GitHub has resources for keeping an email address private.

• If some learners are using Windows, there will inevitably be issues merging files with different line endings. (Even if everyone’s on some flavor of Unix, different editors may or may not add a newline to the last line of a file.) Take a moment to explain these issues, since learners will almost certainly trip over them again. If learners are running into line ending problems, GitHub has a page that helps with troubleshooting. Specifically, the section on refreshing a repository may be helpful if learners need to change the core.autocrlf setting after already having made one or more commits.

• We don’t use a Git GUI in these notes because we haven’t found one that installs easily and runs reliably on the three major operating systems, and because we want learners to understand what commands are being run. That said, instructors should demo a GUI on their desktop at some point during this lesson and point learners at this page.

• Instructors should show learners graphical diff/merge tools like DiffMerge.

• When appropriate, explain that we teach Git rather than CVS, Subversion, or Mercurial primarily because of GitHub’s growing popularity: CVS and Subversion are now seen as legacy systems, and Mercurial isn’t nearly as widely used in the sciences right now.

• Further resources:

  • git-it is a self-paced command-line Git demo, with git-it-electron its GitHub Desktop successor.
  • Code School has a free interactive course, Try Git.
  • for instructors, the Git parable is useful background reading

Automated Version Control

• Ask, “Who uses ‘undo’ in their editor?” All say “Me”. ‘Undo’ is the simplest form of version control.

• Give learners a five-minute overview of what version control does for them before diving into the watch-and-do practicals. Most of them will have tried to co-author papers by emailing files back and forth, or will have biked into the office only to realize that the USB key with last night’s work is still on the kitchen table. Instructors can also make jokes about directories with names like “final version”, “final version revised”, “final version with reviewer three’s corrections”, “really final version”, and, “come on this really has to be the last version” to motivate version control as a better way to collaborate and as a better way to back work up.

Setting Up Git

• We suggest instructors and students use nano as the text editor for this lessons because

  • it runs in all three major operating systems,
  • it runs inside the shell (switching windows can be confusing to students), and
  • it has shortcut help at the bottom of the window.

  Please point out to students during setup that they can and should use another text editor if they’re already familiar with it.

• When setting up Git, be very clear what learners have to enter: it is common for them to edit the instructor’s details (e.g. email). Check at the end using git config --list.

Creating a Repository

• When you do git status, Mac users may see a .DS_Store file showing as untracked. This a file that Mac OS creates in each directory.

• The challenge “Places to create repositories” tries to reinforce the idea that the .git folder contains the whole Git repo and deleting this folder undoes a git init. It also gives the learner the way to fix the common mistake of putting unwanted folders (like Desktop) under version control.

  Instead of removing the .git folder directly, you can choose to move it first to a safer directory and remove it from there:

  $ mv .git temp_git
  $ rm -rf  temp_git
  

  The challenge suggests that it is a bad idea to create a Git repo inside another repo. For more discussion on this topic, please see this issue.

Tracking Changes

• It’s important that learners do a full commit cycle by themselves (make changes, git diff, git add, and git commit). The “bio repository” challenge does that.

• This is a good moment to show a diff with a graphical diff tool. If you skip it because you’re short on time, show it once in GitHub.

• One thing may cause confusion is recovering old versions. If, instead of doing $ git checkout f22b25e mars.txt, someone does $ git checkout f22b25e, they wind up in the “detached HEAD” state and confusion abounds. It’s then possible to keep on committing, but things like git push origin master a bit later will not give easily comprehensible results. It also makes it look like commits can be lost. To “re-attach” HEAD, use git checkout master.

• This is a good moment to show a log within a Git GUI. If you skip it because you’re short on time, show it once in GitHub.

Remotes in GitHub

• Make it clear that Git and GitHub are not the same thing: Git is an open source version control tool, GitHub is a company that hosts Git repositories in the web and provides a web interface to interact with repos they host.

• If your learners are advanced enough to be comfortable with SSH, tell them they can use keys to authenticate on GitHub instead of passwords, but don’t try to set this up during class: it takes too long, and is a distraction from the core ideas of the lesson.

• It is very useful to draw a diagram showing the different repositories involved.

• When pushing to a remote, the output from Git can vary slightly depending on what leaners execute. The lesson displays the output from git if a learner executes git push origin master. However, some learners might use syntax suggested by GitHub for pushing to a remote with an existing repository, which is git push -u origin master. Learners using syntax from GitHub, git push -u origin master, will have slightly different output, including the line Branch master set up to track remote branch master from origin by rebasing.