Mogsdad Git and Github

Wha?

Git is a Source Control Manager (SCM) which was originally written by the keepers-of-the-Linux-kernel for their own use.^ref Since then, it's become extremely popular for projects large & small.

We could just store the code for our robot on the hard drive of a PC. After all, that's where we're writing it. Ok, so we have several PCs, and even more developers. Each person contributes - but getting the best of all those contributions together into one place is tricky. We never know who did what. And sometimes our experiments go horribly wrong, and we have trouble recovering our code... Oh - is that what this is all about?

Code can be branched off, so that a programmer can work on a single problem or experiment without getting affected by what other programmers are doing - then they can decide to push the perfected code back to the main branch OR toss the junk without further investment of time or effort. Pretty cool.

Git can be run on any machine. But it becomes more powerful when there is some way to replicate the source code in many places. (Like all our robotics laptops.) To do that, we could use a Git server that each separate copy could push and pull changes to & from.

Enter Github, which is a large-scale hosting service for Git repositories. Because of its scale, it is much more reliable than a single server would be. It also provides additional capabilities integrated with repositories, such as simple Wikis (like this one), and Issues management (bug & change request tracking). Bonus: Through FIRST, our club receives a commercial-level service for free. Free == Good.

Github Organizations

Individual users can be grouped together, and given access to projects that are owned by the organization (instead of a single user), and optionally closed to outsiders. Our organization is LdhssRobotics.

Our organization has been created with a handful of psuedo-users as members. These are intended for team use on the development laptops. (swteam-1 through swteam-6) Team members who have their own Github accounts can also be invited to be members in the year(s) that they are active participants.

Creating a repository

These are the recommended steps for creating a new repository in the LdhssRobotics group. If you're copying an existing repository that already contains code that you want to modify, see Cloning a repository.

1. Start process in Github.

2. Complete the Create New Repository dialogue. ^{_{Can you find the typo?}}

Next, we are going to get "real code" into the new repository. For that, we work locally on a development machine.

3. Clone the Github repository to your target machine. You have many options for how to do this, but in this guide we'll use the Eclipse eGit extension, which is included in Eclipse Luna.

   File > Import... > Git > Projects from Git
   

Click "Next" to proceed to "Select Repository Source". Select "Clone URI", then "Next" to open the "Source Git Repository" dialog.

You can find the Clone URI for the master repository in GitHub, on the right hand side, for example:

Copy that value, and paste it into the "Location / URI" field in the Eclipse dialog. Enter the GitHub credentials that will be used by this development machine. Each of our laptops should use a unique psuedo-id. People working on their own machines should use their own GitHub credentials.

Click "Next" to go to the "Branch selection" dialog (should select all) then "Next" again to get to the "Local Destination" dialog.

This is where you chose where the remote Git repository will be cloned on the local machine. You should select a folder that does not currently contain an Eclipse project. (There is a discussion about this in the eGit documentation. Good luck with that.)

4. Create your Eclipse project in the cloned directory. (e.g. copy files, or use the project wizard) Adjust file and directory names as desired.

5. If there are any files that should be skipped by Git (temporary files, for example), make sure that the .gitignore file is properly configured for that.

6. Add the submodules (folders) to the local repository, and commit them.

7. Push the local repository to Github. (Right-click local repository > Team > Synchronize.)

Now, you're ready to clone the Github repository to other machines.

Cloning a repository

To get a copy of the files in a remote repository, we will clone it. As the name implies, we will end up with an exact copy of the remote repository, with the following data:

• Directory structure
• source files (*.cpp, *.h, etc.)
• Eclipse project files (.settings folder, .project & .cproject, and build.*)

We also get metadata with all the history of changes that were ever made in or synchronized to the remote repository. This appears as a hidden directory .git.

Under construction But while we're waiting, it's step 3 from Creating a repository

Clone the Github repository to your target machine. You have many options for how to do this, but in this guide we'll use the Eclipse eGit extension, which is included in Eclipse Luna.

    File > Import... > Git > Projects from Git

Click "Next" to proceed to "Select Repository Source". Select "Clone URI", then "Next" to open the "Source Git Repository" dialog.

You can find the Clone URI for the master repository in GitHub, on the right hand side, for example:

Copy that value, and paste it into the "Location / URI" field in the Eclipse dialog. Enter the GitHub credentials that will be used by this development machine. Each of our laptops should use a unique psuedo-id. People working on their own machines should use their own GitHub credentials.

Click "Next" to go to the "Branch selection" dialog (should select all) then "Next" again to get to the "Local Destination" dialog.

This is where you chose where the remote Git repository will be cloned on the local machine. You should select a folder that does not currently contain an Eclipse project.

Our project repository contains an Eclipse project, so make sure you import it as such.

Learning about Git

Sometimes cookbook instructions aren't enough. Here are a few resources that will help you start down the road to really learning about source control, focused on Git.

• Got 15 minutes and want to learn Git?
• Learn Version Control with Git
• Lots more!
• And not least but last: THE BOOK