Tutorial on using Git with RobotC in FTC

[Skinkworks]

Preface - Target

This guide is for anyone who would like to use the version control system git with RobotC in an FTC environment. This could also be used for CAD files, but it is not recommended, since CAD files are binary data which is not handled well with traditional version control systems. The same argument applies for LabVIEW files.
Git is a free software version control system initially developed by Linus Torvalds to help him create his more well-known project, Linux. Git attempts to solve many of the problems posed by earlier version control systems, and in the author's opinion, succeeds at this.

When reading this guide, after any command which is to be typed into the command line, it is implied that you press enter. There are essentially no exceptions to this, and when there are, I will point it out.

Step 0: Learn how it works

Version control is the concept of storing different versions of a piece of software as it is developed, so that if a bug is discovered in a piece of code, its origin can be identified, and the previous version of the code can be looked at to see how the bug could have developed. The other main feature of version control software is that it allows multiple developers to work on one code base, and receive the code changes that others make. This is the feature that will be most used by an FTC team (since the first feature is more useful in projects with many, many coders).
Git works differently than the version control systems the precede it. Git is distributed, fast, and lends itself to a certain workflow. Let's analyze these points:

Distributed

This means that there is no central server to contain your code and its history. The bonus of this is that, say, if the central server is hit with a Tsunami, Earthquake, Alien attack, or other phenomenon that destroys your data, you still have your code, since there isn't any true central server. With Git, you can set up a repository that you treat like a central repository, but that is something that you do yourself, not something imposed by Git. Every repository in Git contains the entire history of the codebase.

Fast

Since your computer doesn't talk to a server when doing a git operation, it permits the Git program to be very fast. This doesn't really apply to FTC, since the codebase is only a couple hundred lines typically, but Git is used to manage massive pieces of software, and it does so quickly.

Lends Itself to a Certain Workflow

In version control, there is an operation called a merge. A merge is when two code bases are folded together to create one code base with the features of both (normally, these code bases come from the same source earlier in time). In other version control softwares, this is a time-consuming, confusing, and difficult operation, rarely performed. In Git, merging is one of the most common operations performed, second to its inverse, forking. This lends itself to a workflow where programmers work on their code, and someone else merges that into the master code base. The Git workflow as it applies to FTC will be more deeply explained below.

Step 1: Decide on a Hosting Service

This is an important first step to make. Since Git is distributed, a hosting service is not required; however, it makes it easier to develop code, since everyone can easily merge the hosted version into their version, a process which in Git is called "pulling". There are two good git hosting services which I know of, which are Github and Google Code. Also, you can use a network server, if your school has one.

Github

Github is a website founded in 2008, which exclusively hosts git repositories. Their website is highly polished (with a hint of comedy), and the Github team has expanded into creating a desktop client for Github, along with Android and iOS apps for their platform. Their influence in the Git world is strong, and a feature of their platform, the pull request, seems like a part of Git itself.

Google Code

Google Code is a code hosting service provided by the software giant Google. Google Code supports multiple code access methods, one of which is Git. The potential downside of using Google Code is that Google can only provide freely available hosting space; using Google Code as a host means that anyone can read your code, and its history.

Local Hosting

If your school or organization provides a directory which all of your team members' computers can access, then you can place a repository there. Members of the team can push code to there, and other members can pull from that repository. This avoids hosting options entirely, and is the preferred option.

None of these hosting options are more difficult to use than the others, they are just different.

Step 2: Obtain Git

Git can be obtained from this location. Git is typically used from a command line interface. Don't let this scare you; it isn't harder than a graphical interface, it just means that you have to know what to type, instead of what to click. If you chose Github as your hosting service, you can use the Github for Windows program, which is rather nice and convenient to use, but this guide will not cover its use.

After you download Git, run its installer. Click through the prompts, until you reach this screen:


You want to pick "Run Git and included Unix tools from the Windows Command Prompt". Don't mind the warning, unless these are tools that you commonly use. Next, you will be given a choice of line endings, which doesn't really apply to a RobotC programmer. Choose the first option, which is selected by default:


Git now installs. Click "Finish" as soon as it finishes. Congratulations, you now have Git! Now you must configure git so that it knows who you are. To do that, run the following commands:

git config --global user.email "deankamen@gmail.com"
git config --global user.name "Dean Kamen"

These settings don't control anything, but they will be tagged along with your commits. If you use an online hosting service, the email address should be the email address should be the one you specify when creating an account there. Remember, if you use an online hosting service, the name you specify will be publicly visible.

To confirm that git works, open a command line, and type the following:

git version

And then press enter.

The result should look like this:


If it doesn't, you have a problem. Start a thread with the problem, and I'll help you get it fixed.

Step 3: Create a Git Repository

Doing this creates the git folder that contains the information that git uses to do its magic. First, change into the directory that houses your code with the "cd" command:

cd "C:\Users\Path\to\your\code\base"

Which should result in something like this:

[Skinkworks]

Then, to initialize the git repository, run

git init

(WARNING: If you are going to be using Github or Google Code for remote hosting, read Step 6 BEFORE you do this.)

Which results in the following:


Congratulations, you now have a git repository on your computer!

Step 4: Add Your Current Files to the Repository

Now, you must add files to your empty git repository. In case you don't remember the specific name of a file, you can list the files in a directory by typing:

ls

(For you linux junkies out there, you may say "hey, ls isn't part of Windows?". You are right; it comes with git.)

Now you will see something like this:



Next, you add the file, Teleop.c, to the git repository with the command:

git add Teleop.c

Which, for those who like pictures, results in:



What? Nothing happened? Don't worry, the file was added to the git repository. Git was originally a Linux command line tool; Linux command line tools don't make a habit of providing unneeded information. If something went wrong, it would tell you, but in general, no news is good news.

But, the file is not added to the git repository. Where is it then? The file is currently indexed. This means git knows that you want to update it the next time you commit your repository. Committing is the process of applying your changes to the repository, and giving these changes a trackable tag. Commits are made with the following command:

git commit -m "First Commit"

Where the quoted string after "-m" is the message which describes what is contained in this commit. This gives the result:



The repository now contains Teleop.c in its current state.

[Skinkworks]

Step 5: Do Work, Update Repository, Repeat

Now, setup is done. At this point, make changes to a file:



Let's say you had a long weekend that, for some strange reason, you weren't working on robotics. When you come back, what if you want to know the difference between the code now and the last time you committed? Well, that can be determined with the command

git diff

Which, in this case, results in:



(On my machine, a warning came up which says "WARNING: terminal is not fully functional". Just hit enter to dismiss that, it won't impact you, if you even see it at all.)

Git now shows you the difference between the latest commit and the working state of the repository. Press 'q' to close out of the diff view.

Now, to commit those changes, you must add Teleop.c to the index, so that Git will modify it in the next commit. Why does git work this way? So that if you change multiple files, you can make multiple commits, in case you want to separate out changes because they make more sense that way.

To add a file to the index, type:

git add Teleop.c

Yes, this is the same add command as before. The result:



And again, just as before, you commit your change, specifying a status message for the commit:

git commit -m "Added awesome features."

(Unlike my examples, commit messages should be descriptive)

Which results in the following:



Git informs you about how many lines were changed. Now, your changes to Teleop.c are in Git, and Git now knows what the file was before, and what it is now.

If you are a lone coder, you can stop here; you now have everything you need to start using Git with RobotC.

[Skinkworks]

Step 6: Setup Sharing with Others

How you share code depends on whether you are using a hosting service or not, and which hosting service you are using.

With a hosting service: Github

First, if you are using Github, you must make an account on github. To do this, go to https://github.com/signup/free, and choose the plan that you want. If you don't want to share your code with the world, you can look into a private git repository plan at https://github.com/edu.
Now, to integrate Github into your workflow, in part 2 of step 3, replace "git init" with:

git clone https://github.com/<USER>/<REPO>.git .

Where <USER> is your username, and <REPO> is the name of your repository. This will automatically set up all references to github in the local repository. The trailing dot is not a typo; it's important.

With a hosting service: Google Code

First, if you don't have a Google Account, make a Google Account, which can be done here: https://accounts.google.com/SignUp?c...e.com%2F&hl=en. (If your school uses Google Apps for email, you can use that account for this process). Now that you have a Google Account, login and go to http://code.google.com/hosting/createProject to create a new project. Fill in the information as required, and make sure to pick "Git" as your Version Control System. For the project labels, I recommend making one of them "FTC"; many teams use that.

Now, your computer needs to know who you are when you connect to Google Code. To do that, open https://code.google.com/hosting/settings to see your Google Code password, which is different from your real Google Account password. Now, make a file called "_netrc" in your home directory (C:\Users\<USERNAME> in Vista or higher, and C:\Documents and Settings\<USERNAME> in XP and lower), and add the following line to it:

machine code.google.com login <GOOGLE> password <PASSWORD>

Where <GOOGLE> is your Google Account (deankamen@gmail.com, for example), and <PASSWORD> is your Google Code password, which you found out earlier. Note that this file is called "_netrc", not "_netrc.txt". There should be no file extension.

Now, to integrate Google Code into your workflow, in part 2 of step 3, replace "git init" with:

git clone https://code.google.com/p/<PROJECT>/ .

Where <PROJECT> is the name of your project. This will automatically set up all references to Google Code in the local repository. The trailing dot is not a typo; it's important.

(I use the words "project" and "repository" interchangably. In this context, they are the same thing.)

Without a hosting service

If elect to use your school's network drive for git repository sharing, you must first determine where you can put the repository. The repository must be in a location that everyone has read-write access to. Once that location has been found, make a folder there that will contain the repository, and then open a new command prompt there, which can be done by shift-right-clicking on the folder, and then choosing "Open command window here":



Once in that network location, run the following command:

git --bare init

The "bare" option means that the repository has no history of itself, so you can safely overwrite it when you push to it. Now, within your working git repository, run the following command:

git remote add origin file:///<PATH>

Where <PATH> is the full path to the network folder. Notice that there are three slashes after "file:", that's not a typo. This adds the the network git repository as a remote, which means we will be pushing to it. Now, run the following command in your command prompt:

git push -u origin master

(If you've been skipping around these instructions, the previous line will fail if you haven't made a commit yet.)

Which results in the following:

[Skinkworks]

Step 7: Sharing Changes

Now that your sharing method is established, the command which actually doe the sharing is the same for everyone:

git push origin master

These four words take your commits and push them to the remote repository, so that others can get them. If you want to get the code from the remote repository, it's only two words:

git pull

Now, you must get the latest version of the remote code before you commit; a pull must precede a push.

Step 8: Getting Others on Board

Adding other programmers to the project is similar to setting things up for yourself. If you are using Github or Google Code, they have to create an account for the service, and you must add them to it. The URL for this is:

Google Code: http://code.google.com/p/<PROJECT>/adminMembers
Github: https://github.com/<USER>/<PROJECT>/admin/collaboration

Where <PROJECT> is the name of the project, and <USER> is your Github username. After that, they follow this tutorial, just as you did, except that if you are using a Network Drive, in Part 2 of Step 3, replace "git init" with:

git clone file:///<PATH> .

Where <PATH> is the path to the network repository, the same one you used when you set up the remote the first time. Otherwise, if you are using Google Code or Github, the process is identical for all team members. The trailing dot is not a typo; it's important.

[Skinkworks]

Conclusion

You now should be set up to use Git with RobotC. You can publish your changes to the codebase to a centralized location, and you can get changes made by others. To learn more about Git, there are plenty of available resources, including Stack Overflow and, of course, the official Git website. If you have any questions, improvements, or suggestions, post them on this forum, or PM me.