Git and GitHub (WIP)

Purpose

Git is the de facto version control system. Most of us use Git every day; our client work involves interacting with, and ultimately delivering, git repositories to our clients.

Git is a powerful tool. This lesson goes through some of the basics, but we recommend that you continue to explore its most advanced features as you use it. We also recommend that you use the command-line git interface, at least to start.

Why use Git? First, it acts as a simple backup, reducing the chances of losing code. It allows multiple developers to edit the code simultaneously and merge their changes (mostly) seamlessly. It lets us write documentation (in commit messages) tied to the state of the code when we wrote it. It lets us roll back to previous versions of the code easily. Git branches let us work on several copies of the code simultaneously, letting us remain flexible to try new approaches and test proofs of concept. There are a host of other benefits too, some of which you will explore in the exercises.

Learning Material

Basics

Commit Messages

The git log command can be a powerful tool to understand changes in a repository, but as with many things, “garbage in, garbage out” applies. Writing concise, descriptive commit messages will help your colleagues and your future self quickly identify the context surrounding changes. Conversely, writing commit messages like fix bug or new feature will force the reader to perform a line-by-line comparison, all without the background context the original author had.

Exercises

To learn as much as possible from these exercises, write your responses before revealing the provided answers. If any exercises seem irrelevant, you can skip them and instead write a justification as to why they are unimportant. These justifications will help us improve the lesson for future students.

Exercise 1

Install git and ssh. Create a GitHub account if you don’t already have one. Create an SSH key and add it to your GitHub account. Create a private repository in your GitHub account with a README. Clone it using ssh (this means you shouldn’t need to enter your github password).

GitHub and SSH

See the tutorials on this page.

Exercise 2

Clone a copy of our DICOM Standard git repository. Use the git blame command to see who has last edited the README for that project.

Answer

To clone the repo using SSH, run git clone git@github.com:innolitics/dicom-standard.git. This will make a copy of the repository within dicom-standard directory. Run git blame README.md to see who has last edited each line.

Exercise 3

Use git to find the oldest commit that includes the word “TODO” in the commit message.

Answer

Run git log --grep 'TODO' --reverse. Here is the oldest commit’s message:

commit 984b4fef5eed30be06ff7001ae8a9c7c5c754158
Author: ReeceStevens <reecestevens24@gmail.com>
Date:   Wed Aug 31 21:58:32 2016 -0500

    Add TODO for uncovered bug

    Accidentally uncovered a bug in the href link generation for references
    to sections other than the current section (i.e. `part03.html`). As
    described in the comment:

    > hrefs to other sections get incorrectly assembled
    > i.e. If we are in part03.html:
    > http://dicom.nema.org/medical/dicom/current/output/html/part03.htmlpart06.html#PS3.6

    Will resolve this bug before merging with master, but I want to keep
    moving forward with the goal of this branch before I get sidetracked bug
    squashing.

Note Reece has written a useful commit message following the conventions in the reading material.

Continuous Lesson Improvement

Please help us make these lessons as relevant and up-to-date for future engineers as possible!

You can help in several ways:

  • Shorten or clarify the writing. We're all busy and less is more.
  • Ask if the purpose of the lesson is unclear. We want all of the lessons to seem useful.
  • Remove exercises or learning material that aren't useful.
  • Add more exercises, exercise answers, or learning material as appropriate.

You can quickly open the lesson page in the GitHub editor. Create a new branch and pull request and assign it to David.