Reading 29: Team Version Control

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.

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 main 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/main, origin/HEAD, main) 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:

export default function greet(name: string): void {
  console.log(greeting() + ", " + name);
}

function greeting(): string {
  return "Hello";
}

export default function greet(name: string): void {
  console.log(greeting() + ", " + name + "!");
}

function greeting(): string {
  return "Ciao";
}

export default function greet(name: string): void {
  console.log(greeting() + ", " + name);
}

function greeting(): string {
  return "Hello";
}

function greeting(): string {
  return "Ciao";
}

export default function greet(name: string): void {
  console.log(greeting() + name);
}

function greeting(): string {
  return "Hello, ";
}

export default function greet(name: string): void {
  console.log(greeting() + ", " + name);
}

function greeting(): string {
  return "Hello";
}

export default function greet(name: string): string {
  return greeting() + ", " + name;
}

import greet from './hello';

greet("Eve");

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. The built-in version control UI in VS Code is also useful for this (for example, the TIMELINE view in the Explorer pane allows you to quickly see the history of a file), but we continue to recommend the command line for running Git commands.

In 6.031, you can use the web interface to review commits that were pushed to github.mit.edu.

• On the summary page for a repo you see the files and folders in the root of the project on the current main branch.

• Click commits to see the commit history.

• Click on a commit message or SHA to see the changes introduced by that commit.

• Then click the Browse Files button on the far right to browse the entire project at that old version.

• While you browse, notice the Tree: …SHA… button on the left, which reminds you that you are looking at an old version of your repo. Normally, when you are browsing the latest version of your repo, this button says Branch: main instead.

git clone

git revert

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

$ git lol
* b0b54b3 (HEAD, origin/main, origin/HEAD, main) Greeting in Java
*   3e62e60 Merge
|\  
| * 6400936 Greeting in Scheme
* | 82e049e Greeting in Ruby
|/  
* 1255f4e Change the greeting
* 41c4b8f Initial commit
$ ls
Hello.java	hello.rb	hello.scm	hello.txt

$ git lol
* b0b54b3 (HEAD, origin/main, origin/HEAD, main) Greeting in Java
*   3e62e60 Merge
|\  
| * 6400936 Greeting in Scheme
* | 82e049e Greeting in Ruby
|/  
* 1255f4e Change the greeting
* 41c4b8f Initial commit
$ ls
Hello.java	hello.rb	hello.scm	hello.txt
$ git revert 82e049e

Revert "Greeting in Ruby"

This reverts commit 82e049e248c63289b8a935ce71b130a74dc04152.

# Please enter the commit message for your changes. Lines starting
# with '#' will be ignored, and an empty message aborts the commit.
# On branch main
# Your branch is up-to-date with 'origin/main'.
#
# Changes to be committed:
#   deleted:    hello.rb
#
~
.git/COMMIT_EDITMSG                              1,1            All

$ git lol
* b0b54b3 (HEAD, origin/main, origin/HEAD, main) Greeting in Java
*   3e62e60 Merge
|\  
| * 6400936 Greeting in Scheme
* | 82e049e Greeting in Ruby
|/  
* 1255f4e Change the greeting
* 41c4b8f Initial commit
$ ls
Hello.java	hello.rb	hello.scm	hello.txt
$ git revert 82e049e
[main abcd123] Revert "Greeting in Ruby"
 1 file changed, 1 deletion(-)
 delete mode 100644 hello.rb

$ git lol
* abcd123 (HEAD, main) Revert "Greeting in Ruby"
* b0b54b3 (origin/main, origin/HEAD) Greeting in Java
*   3e62e60 Merge
|\  
| * 6400936 Greeting in Scheme
* | 82e049e Greeting in Ruby
|/  
* 1255f4e Change the greeting
* 41c4b8f Initial commit
$ ls
Hello.java	hello.scm	hello.txt

git show and git checkout

$ 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!

$ git show b0b54b3
commit b0b54b3780c95ff74d94f374572078a496500a83
Author: Max Goldman <maxg@mit.edu>
Date:   Mon Sep 14 16:02:40 2015 -0400

    Greeting in Java

diff --git a/.classpath b/.classpath
new file mode 100644
index 0000000..52a0197
--- /dev/null
+++ b/.classpath
@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<classpath>
:

new file mode 100644
index 0000000..8624181
--- /dev/null
+++ b/Hello.java
@@ -0,0 +1,10 @@
+public class Hello {
+    
+    public static void main(String[] args) {
+        printGreeting();
+    }
+    
+    public static void printGreeting() {
+        System.out.println("Hello, version control!");
+    }
+}
(END)

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

$ git checkout 41c4b8f -- hello.txt

$ git checkout 41c4b8f -- hello.txt
$ git lol
* b0b54b3 (HEAD, origin/main, origin/HEAD, main) Greeting in Java
*   3e62e60 Merge
|\  
| * 6400936 Greeting in Scheme
* | 82e049e Greeting in Ruby
|/  
* 1255f4e Change the greeting
* 41c4b8f Initial commit

$ git checkout 41c4b8f -- hello.txt
$ git status
On branch main
Your branch is up-to-date with 'origin/main'.
Changes to be committed:
  (use "git reset HEAD <file>..." to unstage)

        modified:   hello.txt

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

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 Mocha, 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 github.mit.edu. 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 debugging print statements 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. Working on separate branches is extremely important when the size of the project, the length of time, or the number of people is much larger than the small, 1–2-week, 3-person final project in this class. For 6.031, focus on clear communication and frequent syncing-up of the whole team.