Version Control Reference

Contents:

• Introduction
  • Git is insurance against computer crashes
• How Git Works on One Computer
• How Git Works with Multiple Computers
• Git vs Gitlab
• How Git is Used in CSE 331
• Git Pitfalls
• Preventing merge conflicts

Introduction

You may be wondering why we should use version control at all. All version control systems, including git, provide the following functionality:

• It lets multiple users edit the same files independently, working on their own local copies and synchronizing their work. In the case of CSE 331 assignments, it permits you to work from multiple computers (e.g., department machines and your own computer) without having to copy files back and forth.
• It provides backups, permitting you to recreate the state of your files at moments in the past. This is valuable if your computer crashes or is stolen, provided the repository is on another (backed-up) computer (like the department's file servers). It is also valuable if you make some edits, then decide they were a bad idea and you want to recover a previous version.

Git is insurance against computer crashes

Over many years of teaching courses like CSE331, we have observed that on average about one student's computer will either die or be stolen during the quarter. Therefore, you should commit and push your work to the repository often. Committing often:

• Guarantees that as much as possible of your work is saved if your computer dies
• Will convince us that you had been working on the homework when this happens (otherwise, you should expect little sympathy if your computer dies because appropriate use of version control is expected)
• Is good practice for industry

How Git Works on One Computer

Let's start by discussing how Git works when there is only one user working on one computer.

Git maintains a “repository” that sits next to the files you want it to track. (On Linux, the repository is stored in a subdirectory called .git, which you will never need to—or want to—look inside.) Inside of the repository, Git keeps track of every committed version of the files that you tell it about. It will let you look through those past versions, compare the current versions to earlier ones, or even revert to a past version if you liked that better.

Here are some important operations that you may want to perform with Git:

• You can add a file to the repository if you want Git to keep track of it. This becomes the initial version of the file in the repository.
• After making changes, you can check the status of your repository, which shows you the files that are different than their most recent versions stored in the repository. You can also diff an individual file to see the specific changes that have been made.
• You can commit your changes to put them into the repository, where they will be permanently recorded.
• You can tag your commit with a name (and optional message) to help remember what was important about that version of the files. (Note that this tag refers to the state of every file in the repository at that point. You do not need to tag individual files; the tag applies to the state of the entire repository.)
• You can view the log, which shows you all of the past commits that have occurred in the repository. (While the diff command normally shows the changes between your current files and the most recent commit, you can also diff between your current files and earlier versions listed in the log.)
• You can checkout a past version of a file if you want to return to an earlier version. You can also checkout a past version of the entire repository.

Even if you use Git by yourself on a single computer, as you can see, it already provides benefits in its ability to keep track of past versions of files. If you end up breaking something in your code and can't figure out what went wrong, it can be useful to revert to an earlier version and then try making the same changes again in small pieces until the bug shows up again. That will tell you that the problem is likely in the last small piece that you changed.

How Git Works with Multiple Computers

Git's main purpose is to manage files being changed on multiple computers. For example, in this class, you will have versions of your files on at least three different computers:

1. your personal computer or a computer in the CSE lab
2. the Gitlab server, which stores the version that will be graded (see below for more information)
3. the CSE Linux server, attu, where you will validate that your code works as expected

Those different repositories are related to each other like this:

Each of these three computers has its own Git repository. You can use Git's push command to send changes you committed in your local repository into another repository (typically, Gitlab). And you can use Git's pull command to bring changes you checked into another repository (Gitlab) into your local repository.

For example, once your assignment is working correctly on your computer, you commit your changes locally and then push them to the Gitlab repository. Then, you can log into attu and pull, which should bring those same changes into your local repository on attu.

The normal way in which to create the links between two repositories that allow you to push and pull changes between them is to create your local repository as a clone of the other repository. When you do this, your local repository will remember the location of the repository from which it was cloned (which it refers to as the master repository). When you use the push and pull commands, they default to working with the master repository. (It is possible to tell Git about other repositories besides the one from which it was cloned, but we will not need to do so in this course.)

When Git is used on multiple computers, you get backup versions of your files on multiple machines. This can be of critical importance if your computer breaks or is lost. As noted above, this seems to happen to some student every quarter, so make sure that you not only commit your changes often to your local repository but also push them to Gitlab so that you have backups on another machine. Remember: committing your changes just means that you are telling Git to remember that version — it does not mean that you are submitting those as your solution to the homework. (Instead, you indicate your final solution using a tag.) So you should feel free to commit as many versions as you want.

Git vs Gitlab

It is important to note the distinction between git (version control software), and services like Gitlab and Github (code hosting services). The former is software for working with individual repositories (including committing, pushing, and pulling). The latter are services that store master repositories.

How Git is Used in CSE 331

For CSE 331, Gitlab contains the master repository for your code. You will create the repository on your local machine by cloning a special repository created just for your use in this course. When you are done with your assignment (or any time you want to make a backup copy), you push your changes to the master repository on Gitlab. (If your computer is lost, you can restore from your most recent change that you pushed to gitlab, so push your changes often.) When the assignment is due, the staff will clone the final version of your repository and grade it.

Git Pitfalls

Some tips on avoiding common problems while using git:

• Do not edit the repository (the .git directory) manually. It wasn't designed for modifications by humans.
• Try not to make many drastic changes at once. Instead, make multiple commits, each of which has a single logical purpose. This will minimize merge conflicts. This is good coding practice in general.
• Always git pull before editing a file. It's easy to forget this. If you forget, you may end up editing an outdated version, which can cause nasty merge conflicts.
• Don't forget git push after you have made and committed changes. They are not copied to the remote repository until you do a push.

Preventing merge conflicts

Merge conflicts are possible even when you are working by yourself. To avoid them:

• Always commit and push when you finish work on one computer, then pull before you start work on another computer.
• View old versions in your repository as read-only: you can view them, and even copy parts of them into the current version of your code, but you should not edit the old versions. Never revert your repository to a previous version and then begin editing it.

Merge conflicts are much more common, even likely, when working with teammates. That is yet another reason why the effort in building software tends to scale super-linearly with the size of the program.