Why you should care about version control, and why I suggest git

Hi everyone!

As we roll towards this year’s competition, I wanted to suggest something for the volunteers who will be working with control systems programmers (and the teams who have control systems programmers, and the team members who are control systems programmers… Hello, my fellow code-slingers!). If you’re already familiar with version control, feel free to skip all of this. Executive summary:

  • version control is a good thing
  • I recommend git for teams because it doesn’t require the internet
  • I’ve provided some links at the bottom to tools that make git easier to use

Before I dive any deeper into this, I should direct you to the excellent document put together last year by Austin Wright (team 498 alumnus). Document hosted on Google Docs. He already said many things about git that I was going to say, and several of them better; consider this message a refresher on the ideas and an update on some new developments in version control.

Why use version control?

One of the big things I learned about in college that I wish I had known in high school was version control. I remember that when I was working on my team’s robot control code, we would sometimes need to make very quick, experimental changes under a tight deadline. We ended up with dozens of little folders labeled “control system_1”, “control system_2”, etc. It was a disorganized mess; code could get saved in the wrong folder, they would get lost (put on the wrong floppy disk), etc. It’s a pattern I’ve seen repeated with many teams over the years.

Version control software is basically a system to manage the problem of code changing over time. Instead of backing up versions of the code to other folders, you register files with the version control program (VC) and when you want to make a “backup”[1] (checkpoint), just tell the VC to make it. The VC will keep the checkpoint and a log of what was changed, and if you ever need to pull up a backup and use it, you can just say “Give me the code from Monday” or “Give me version 2”. There’s always a “right way” to do save-this-version-so-I-can-get-back-to-it-later, and nothing can ever get lost.

Checkpointing is the main thing a VC does, but the metaphor goes beyond recording the past. VC software also lets you make “branches,” which are like specialized versions of your code to test experimental ideas or for one programmer to make detailed, finicky changes without interfering with the rest of the team. A successful branch can be merged back into the project (becoming part of the regular code), or kept around as a separate part for special purposes. For example, a team might have an automation feature they don’t fully trust; they can keep it on a branch, and if it turns out to not be useful they can just switch back to the regular behavior by moving from the branch to the main code history without losing anything.

There are several VC programs available, the most popular probably being subversion (http://subversion.tigris.org/). I use subversion (svn) regularly, and it’s a great tool. However, it requires the computer to be able to access a subversion server, which may not always be possible for teams that lack a reliable internet connection. Another VC that may serve the needs of FIRST teams better is called git (http://git-scm.com/). Git acts as a more decentralized VC; with a VC like subversion, the server maintains the “repository” (the binary-soup of files that make up the entire history of the project and allow you to pull up any checkpoint that has been made). If you can’t access the repository, you can’t make a new checkpoint or move to another checkpoint. With git, each individual machine using a project keeps a copy of the project’s whole history, so each machine is both a client and a server. Teams can use a centralized server, but they can also do something more “sloppy” like keep the repository on a few loosely-affiliated laptops or desktop machines, synchronizing their histories when it is convenient to do so.

Tips on using git (and version control in general)

Commit early, commit often

One significant difference between version control and keeping a loose bag of backup folders is that is is much cheaper to make a checkpoint (also known as a “commit”) than to copy a project. Much cheaper, both in space used and time used. I try to commit every time I add a new feature, no matter how few files or lines I changed. That makes it easier to roll tiny pieces of the project back if I made a mistake.

Branches are cheap (in git)

The way git is designed, branching (and merging branches back into the main code body) is very easy; it’s assumed every programmer has his or her own personal branch. So make branches whenever you want to experiment with an idea that is in the least bit “risky.” You can always back up if you find it’s not worth the time to chase the idea, and you won’t lose the work you put into it already.

It’s not just for robot code

Does your team do its own promotional materials? Version-control the flyers and announcements. Does the team keep a team contact sheet or roster? Version-control it so you can remember who was on the team in 2009 when you’re doing your five-year anniversary montage in 2014. Does the team have a website? Most definitely version-control that. You can have as many or as few repositories as you want; any file that changes over time could likely benefit from being version-controlled.

It’s not actually a backup

This is an important point to keep in mind: version control isn’t quite the same thing as backing up unless a copy of your repository lives on another computer (such as the GitHub service; see GitHub in “Tools to use with git,” below). Version control basically adds a rewindable history to each file in the form of the repository; while it can be used to fix a file that is damaged, damage to the repository itself will ruin the history. You’ll still need to be able to restore the entire repository from an off-computer backup if you accidentally set your machine on fire[2].

Tools to use with git

documentation

Most of what I know about using git came from one document: the “Pro Git” book (http://progit.org/book/). This is fairly comprehensive and covers more-or-less everything important in a pretty straightforward manner.

user interface

By default, the user interface to git is command-line only: you tell git what to do by invoking commands like “git init”, “git add”, and “git push”. But there are a couple of great GUI tools to simplify that process.

  • tortoisegit (http://code.google.com/p/tortoisegit/) This is the VC I use. I believe it is Windows-only, but it works extremely well. It acts as an extension to Explorer; when you right-click on a file or directory, one of your Windows submenus will be a “git” submenu that lets you perform operations on the given context. I find this to be more convenient than the command-line tool a lot of the time, but it is Windows-only.
  • SmartGit (http://www.syntevo.com/smartgit/index.html) I just started playing with this one. It’s a Java-based GUI tool, so it will work on both Windows and Macintosh computers (I have only tried it on Windows). It’s brand-new, but it seems pretty solid. They have a commercial license for it, but you can download it, install it, and use the free license for the FIRST competition.

hosting

Even though git works perfectly fine without an external server, a centralized server can be useful for collaboration. If a team wishes to, they can certainly set up a machine owned by them to be a central server; however, there is an option for creating a host on the web that can be accessed anywhere in the world with an internet connection.

  • GitHub (http://github.com/) The most well-known public git repository host. They provide private hosting for a monthly fee, but their most commonly-used service is free public hosting. It’s not hard to set up, and it also comes with a bug tracker and a wiki (useful for documentation) with every repository. Note that the “public” in public hosting means that anyone in the world can see and download the data you push to github (although only the team members could do the uploading). I personally find this sort of code-sharing and code re-use to be very much in the spirit of FIRST, but it’s something to keep in mind if your team doesn’t feel comfortable having their algorithms exposed for the world to explore.

Conclusion

  1. Version control saves hair-pulling frustration. Teams perform better when they aren’t worried about their appearance. Save your hair; use version control.
  2. The internet can be hard to find. Git doesn’t require the internet. Use git.

Notes

[1] Checkpoints aren’t exactly like backups; see the “it’s not actually a backup” tip
[2] That happened to me once. If you turn on a computer and it starts clicking instead of booting up, try not to be surprised when after turning it off and on again it lets out the magic smoke.

Nice little post. I played with Git for the first time a few weeks ago and found the same documentation resource as you, which was quite a help. Git is a very nice system versus SVN which I had used a few years ago. It is something that programmers should look at.

My team was thinking about using Git for the next years as it would go along with Java or C++ quite nicely. We were thinking about having the main programming desktop contain the Git server where upon all the programmers would download the code into their laptops and make edits and so forth. If anyone wanted to bring it home, all they would have to do is take their laptop home, do the same edits and commits, and bring it back the next day. The main server would retain all their edits and separate commits. Now to me, that is just cool.

-Tanner

The software’s name is also a mildlly derogatory term for someone <insert undesired behavior here> particularly used in the UK. Kinda like a Nob in Canada.

Strongly agree with this post–team’s that havent looked much into version control should definitely read this… :slight_smile:
I’ve liked git mostly for its amazing automerging system–yes Hg and SVN have merge tools and auto stuff, but git is by far the best.

Could you elaborate? In my experience, Mercurial (AKA Hg) is pretty much the same as git when it comes to merging.

In general I think git has no advantage over Mercurial, the only difference being Mercurial is easier to use (Also, Mercurial is more space efficient than uncompressed git repo’s, and compressing takes FOREVER).

yeah, our team has been using some sort of VC at least ever since I’ve been on the team. 2 years ago, we went ahead and manually ran some sort of VC, which works well, depending on the programming team. Last year, we went with SVN, because it is whats most familiar with our programming team(both of us are heavy on open source development). What you use for VC should be what you programming team is most comfortable with. VC is a must though. It ends up being used quite often.

I completely agree Mercurial is a lot better than Git. Though, I convinced my team to go with Git for multiple reasons:

  1. Tools for Git on Win/Mac/Linux are much more developed IMO
  2. Github’s “Network Graph” is going to be invaluable. I couldn’t find a easy way to do that with Mercurial
  3. Github provides a lot of support for beginners to Distributed Versioning (like many programmers on my team)
  4. Git was just more popular all around…

Though I agree Mercurial is my favorite.

I use Tortoise SVN for revision control and have recently giving a presentation on the topic

One note you DON’T need an internet connection to use TortiseSVN. I put my repositories on my local hard drive.

FYI none of these version control systems need an internet connection. That just allows you to stay synchronized with your team.

I should point out that NI has good merge and diff tools for labview if you are using that.

NI does indeed have good merge and diff tools, but they are not available to FIRST teams. The merge and diff tools are only included in the Professional Development version (The most expensive one), which teams will not be receiving (correct me if I’m wrong). Also, LabVIEW’s diff tool is only available with LabVIEW 2009 (AKA version 9.0), while teams will be getting version 8.x (8.6 I believe). There is however a tool called LVDiff, but I couldn’t get it to work with Mercurial (I suspect this is because LabVIEW can’t compare two VIs with the same name).

According to Joe Ross’s presentation at The FIRST Forums site http://forums.usfirst.org/showthread.php?t=13548 we are getting the Professional version!

I really love everything that was said here. This is certainly a thread I’ll shoot to new programming students, and other people of interest.

I really think its interesting what was said here. Sharing code publicly might not be in the interest of some teams, but maybe we can start a directory of github links of team’s public VC. The amusement factor would shoot through the roof. It would be invaluable during training to use examples from other teams with more complex autonomous or telop modes.

Some might think that they would be embarrassed to show their code(whether labview or C++) due to lack comments, cleanliness, and what have you, but I think if we can keep it all on a professional(the feed back that is) level it can be extremely insightful.

Even if the SCC stuff is included this year has anyone looked for any free products that will interface with it. The list that you can find on the NI site Here doesn’t seem to have anything that is free. Most are limited trials or only work for a few users. At least that was what i have came accross so far from looking into it.

That list is for tools that are integrated. Any SCC tools that can handle binary files will work with LV, but you will then use their command line or GUI to do check-in and check-out. These tools have wrappers already built into the LV IDE so that you start to edit, confirm a checkout, and continue editing.

Depending on the project, I’ve used both, and while integrated is nice, sometime it is useful to learn the tool’s API for advanced stuff anyhow. If not using the integrated tool, a diff would consist of getting both revisions on disk and using the LV Compare tool on those files.

Greg McKaskle

Greg,

Based on your experience with LV, the version we will be getting, and the fact that most teams have little experience with SCC, what would you suggest we use?

I downloaded the tortoiseGIT stuff the other day as I had no experience with it. XMas has prevented me from doing anything except install it.

So, I haven’t formed an opinion yet as to what might be easiest for teams to pickup and use effectively. I’ll try to get back in the next few days with an opinion. Anyone else, feel free to throw in your answer.

Greg McKaskle

I would like to report that I have had success using Mercurial with LabVIEW. With some python hackery (is there any other way? :slight_smile: ) I got LabView Compare to work with Mercurial’s automatic diff tools. I think Mercurial + TortoiseHg + bitbucket is an excellent and simple setup for FRC teams.

Thank you for your work…could you post a White Paper explaining the process?

In the works…

Todah raba!