6.031
6.031 — Software Construction
Spring 2018

Reading 28: Team Version Control

Software in 6.031

Safe from bugsEasy to understandReady for change
Correct today and correct in the unknown future. Communicating clearly with future programmers, including future you. Designed to accommodate change without rewriting.

Objectives

  • Review Git basics and the commit graph
  • Practice multi-user Git scenarios

Git workflow

You’ve been using Git for problem sets and in-class exercises for a while now. Most of the time, you haven’t had to coordinate with other people pushing and pulling to and from the same repository as you at the same time. For the group projects, that will change.

In this reading, prepare for some in-class Git exercises by reviewing what you know and brushing up on some commands. Now that you’re more comfortable with Git basics, it’s a good time to go back and review some of the resources from the beginning of the semester.

Review Inventing version control: one developer, multiple developers, and branches.

If you need to, review Learn the Git workflow from the Getting Started page.

Viewing commit history

Review 2.3 Viewing the Commit History from Pro Git.

You don’t need to remember all the different command-line options presented in the book! Instead, learn what’s possible so you know what to search for when you need it.

Clone the example repo from Version Control:
https://github.com/6031-sp18/ex05-hello-git.git

Use log commands to make sure you understand the history of the repo.

Graph of commits

Recall that the history recorded in a Git repository is a directed acyclic graph. The history of any particular branch in the repo (such as the default master branch) starts at some initial commit, and then its history may split apart and come back together, if multiple developers made changes in parallel (or if a single developer worked on two different machines without committing-pushing-pulling before the switch).

Here’s the output of git lol for the example repository, which shows an ASCII-art graph:

* b0b54b3 (HEAD, origin/master, origin/HEAD, master) Greeting in Java
*   3e62e60 Merge
|\  
| * 6400936 Greeting in Scheme
* | 82e049e Greeting in Ruby
|/  
* 1255f4e Change the greeting
* 41c4b8f Initial commit

And here is a diagram of the DAG:

In the ex05-hello-git example repo, make sure you can explain where the history of master splits apart, and where it comes back together.

Review Merging from the Version Control reading.

You should understand every step of the process, and how it relates to the result in the example repo.

Review the Getting Started section on merges, including merging and merge conflicts.

reading exercises

Merge

Alice and Bob both start with the same Java file:

public class Hello {
    public static void greet(String name) {
        System.out.println(greeting() + ", " + name);
    }
    public static String greeting() {
        return "Hello";
    }
}

Alice changes greet(..):

public static void greet(String name) {
    System.out.println(greeting() +
                       ", " + name + "!");
}

Bob changes greeting():

public static String greeting() {
    return "Ciao";
}

(missing explanation)

Dangerous Merge Ahead

Same starting program:

public class Hello {
    public static void greet(String name) {
        System.out.println(greeting() + ", " + name);
    }
    public static String greeting() {
        return "Hello";
    }
}

Alice changes greeting():

public static String greeting() {
    return "Ciao";
}

Bob changes how the functions work together:

public static void greet(String name) {
    greeting();
    System.out.println(", " + name);
}
public static void greeting() {
    System.out.println("Hello");
}

(missing explanation)

Continue Merging

Same starting program:

public class Hello {
    public static void greet(String name) {
        System.out.println(greeting() + ", " + name);
    }
    public static String greeting() {
        return "Hello";
    }
}

Alice changes greet(..) to return instead of print:

    public static String greet(String name) {
        return greeting() + ", " + name;
    }

Bob creates a new file, Main.java:

public class Main {
    public static void main(String[] args) {
        // print a greeting to Eve
        Hello.greet("Eve");
    }
}

(missing explanation)

Disaster recovery

As recommended in Version Control, a GUI program can make it easier to navigate your repo and find the data you need to recover from a mistake.

In 6.031, you can use gitweb to review commits that were pushed to Athena.

  • On the summary page you see a list of commits.
  • Click commitdiff to see all the changes introduced by a commit.
    • On a commitdiff or commit page, click blob next to a file to see the entire file at that revision.
  • Or, click tree to browse the entire project at an old revision. You can navigate down folders to see individual files.

    Note that once you start browsing an old revision, clicking a log link might take you back to a log that only goes up to that old revision! To see the whole history again, click a link back to summary.

git clone

Rather than have to recover from a catastrophic loss of work, it would be much better to prevent catastrophe. If you add, commit, and push your work regularly, that work is safely in the remote repo and you can retrieve it with git clone into a fresh folder. The next section has advice about pushing commits when you work on a team.

git revert

If you want to undo an entire commit: find its ID and use git revert. For example, to revert the addition of a Ruby greeting program in ex05-hello-git repo:

Hover or tap on each step:

  1. Use git lol to see the current commit graph.
  2. And use ls to see the current files.
  3. Revert the “Greeting in Ruby” commit…
  4. … and Git asks for a commit message, providing a reasonable default.
  5. Save the commit message, and Git adds a new commit to the project history.
    This new commit undoes the change made by the old commit.
    It does not remove the old commit from the history of the project.
  6. The new commit is now the HEAD, and ls no longer shows hello.rb.
$ git lol
* b0b54b3 (HEAD, origin/master, origin/HEAD, master) Greeting in Java
*   3e62e60 Merge
|\  
| * 6400936 Greeting in Scheme
* | 82e049e Greeting in Ruby
|/  
* 1255f4e Change the greeting
* 41c4b8f Initial commit






git show and git checkout

Most of the time when we make a mistake, we don’t want to revert an entire commit: for example, if the commit improved three different functions, and only one of those improvements was misguided, we’d like to undo just that one.

Often, the easiest way to find the working code you need is to ask Git to show you an old version. Hover or tap on each step in these examples:

Show the diff for a commit

  1. git showrevision will give you the diff for a commit.
    Removed text is in red, added is in green.
  2. If you git show a commit with a diff that doesn’t fit on one screen, you’ll see a : at the bottom of the terminal…
  3. … press space to page down the diff. Press q to quit back to the command prompt.
$ git show 1255f4e
commit 1255f4e4a5836501c022deb337fda3f8800b02e4
Author: Max Goldman <maxg@mit.edu>
Date:   Mon Sep 14 14:58:40 2015 -0400

    Change the greeting

diff --git a/hello.txt b/hello.txt
index c1106ab..3462165 100644
--- a/hello.txt
+++ b/hello.txt
@@ -1 +1 @@
-Hello, version control!
+Hello again, version control!


Show an old version of a file

git showrevision:path/to/file will output an old version of a file.

$ git show 1255f4e:hello.txt
Hello again, version control!
$ git show 41c4b8f:hello.txt
Hello, version control!

When you find an old version that looks good, copy-and-paste is the simplest recovery strategy.

Replace a file with an old version

  1. git checkoutrevision--path/to/file will replace a file in your working directory with an old version. Both the -- (with a space after it) and the path in that command are important, don’t forget them!
  2. This command does not make a commit yet, so our history has not changed…
  3. … but it does stage the changes for commit!
  4. We can look at the staged changes: we’re reverting hello.txt back to its old contents by removing “again”.
$ git checkout 41c4b8f -- hello.txt









Unlike git revert, the revision in this commit is the specific revision we want: the file will look as it did including the changes in that revision, and none afterwards.

You do not want to use the command git checkoutrevision without a --path/to/file. If you do, your HEAD will now point to that old commit, and you will no longer be on branch master. This is called “detached HEAD,” and nobody wants that.

If a command warns you that your HEAD is detached, seek assistance before you continue, to avoid losing work!

Using version control in a team

Every team develops its own standards for version control, and the size of the team and the project they’re working on is a major factor. Here are some guidelines for a small-scope team project of the kind you will undertake in 6.031:

  • Communicate. Tell your teammates what you’re going to work on. Tell them that you’re working on it. And tell them that you worked on it. Communication is the best way to avoid wasted time and effort cleaning up broken code.

  • Write specs. Necessary for the things we care about in 6.031, and part of good communication.

  • Write tests. Don’t wait for a giant pile of code to accumulate before you try to test it. Avoid having one person write tests while another person writes implementation (unless the implementation is a prototype you plan to throw away). Write tests first to make sure you agree on the specs. Everyone should take responsibility for the correctness of their code.

  • Run the tests. Tests can’t help you if you don’t run them. Run them before you start working, run them again before you commit.

  • Automate. You’ve already automated your tests with a tool like JUnit, but now you want to automate running those tests whenever the project changes. For 6.031 group projects, we provide Didit as a way to automatically run your tests every time a team member pushes to Athena. This also removes “it worked on my machine” from the equation: either it works in the automated build, or it needs to be fixed.

  • Review what you commit. Use git diff --staged or a GUI program to see what you’re about to commit. Run the tests. Don’t use commit -a, that’s a great way to fill your repo with printlns and other stuff you didn’t mean to commit. Don’t annoy your teammates by committing code that doesn’t compile, spews debug output, isn’t actually used, etc.

  • Pull before you start working. Otherwise, you probably don’t have the latest version as your starting point — you’re editing an old version of the code! You’re guaranteed to have to merge your changes later, and you’re in danger of having to waste time resolving a merge conflict.

  • Sync up. At the end of a day or at the end of a work session, make sure everyone has pushed and pulled all the changes, you’re all at the same commit, and everyone is satisfied with the state of the project.

We don’t recommend using features like branching or rebasing for 6.031-sized projects.

We do strongly recommend working together in the same place at the same time, especially if this is your first group software engineering experience.

reading exercises

Team version control

Which of these demonstrate good team software development practice?

(missing explanation)

Team project

Most class times during the project phase will be devoted to group work.

These classes are required, just as normal classes are, and you must check in with your project mentor TA during class.