So you’re developing code for your robot, but where should you store the master copy of that code?  Keeping everything on a single laptop is a terrible plan;  you at least need backups, maybe multiple backups.  Also, you want to keep the history of the development. You might want to compare the code used in two different competitions. And, if the code worked yesterday but fails today, you want to know what has changed.  In professional software environments, the code is usually stored in a Revision Control System.  FRC teams should also follow this practice.

Software Revision Control systems are databases for storing computer software.  They track the history of all changes to the software and allow groups of programmers to share large programs.  They allow anyone on your team to retrieve the current program, or see the versions of the program from the past. 

Probably the most popular revision control system right now is git, a distributed version control system created by Linus Torvalds, the same guy who created Linux. You can use git from the command line, or from within development environments such as Eclipse, IntelliJ, and Visual Studio Code.  GitHub is a web-based hosting service for git, and the GitHub corporation is a FIRST sponsor.  All programming mentors and students can get free GitHub accounts, and FIRST teams can get upgraded Team Accounts.

To say that git is “distributed” means that every programmer will have a copy of the code, along with the history of the changes.  There is also one remote repository of the code out on the internet. Programmers will occasionally pull changes from the remote repository to their local copy and occasionally push their own changes up to the remote repository.  In this way, everyone eventually has the same code and the same history.

Combinations of the code files are called “commits“, and the word “commit” here is both a noun and a verb.  Committing your changes creates a commit that you can retrieve later.

OK, I know that that was a lot of information.  Honestly, git is a really deep subject, and companies that use it develop really complicated methodologies for its use.  I do not recommend that FRC teams try to use everything in the git toolkit, or try to emulate commercial practices.  Especially at first.  Instead, let’s lay out the minimal functions.

Installing git

If you don’t already have git software installed on you laptop, the basic instructions are at:  https://git-scm.com/ .

After installing, open up a terminal window and execute the following:

git config --global user.email "myEmailAddress@whereever.com"
git config --global user.name "My real name"

Note that starting in 2021 GitHub started requiring that users authenticate using Personal Access Tokens. Hopefully, if you install git using the basic instructions above, this should be automatically taken care of, since the default install should include Git-Credential-Manager-Core.

Cloning an existing repository

Suppose that there is a repository on GitHub that you’d like to download to your laptop.  Making a local copy is called making a clone.

Consider the code repository at:  https://github.com/firebears-frc/testrobot0.  Go ahead and visit that page in a browser.  Press the green button labeled “Clone or Download” and then press the little clipboard button.  This will copy the repository’s formal URL into your clipboard.

Now go to Visual Studio Code.

1. Open the Command Palette by hitting the F1 key (or Control-shift-P on Windows or Command-shift-P on Macintosh).
2. Type “git clone” and hit the return key.
3. VS Code will ask for the repository URL.  Paste the URL in and hit return.  You may also need to give your GitHub username and password.
4. VS Code will ask for the parent directory in which to save the code.  Typically this might be your machine’s Documents directory.
5. VS Code will ask you if you want to open the repository.  Yes, you do.

At this point you now have a clone of the repository on your machine.  You won’t be able to push changes up to the remote repository unless the owner has granted you permission, but you can read, edit, and deploy this code to the robot.

Creating a new repository

Suppose you have a robot project on your local machine that has never been under git control, but you’d like to upload it into GitHub.

Open the project folder into VS Code and then open a browser to https://github.com.

1. In the browser, log into your GitHub account.  Click on a green button that says either “New” or “New Repository”.
   
2. Github will ask for a repository name.  Give it the same name as project directory on your laptop.  You can also specify a description. Probably you should make it a public repository.
   However, do not add a README file or a .gitignore file or a license file.  Your GitHub remote repository must be totally empty at this point.
3. After creating the repository, your browser will go to a page which displays your new repository URL.  Copy this value into your clipboard.
4. In VS Code, open the Command Palette and type “git”.  Select “Git: Initialize Repository”.  A file dialog will pop up.  Click on the “Initialize Repository” button.  Your project will now be under local git control, although no files have yet been committed.  The “Source Control” icon in the Activity Bar will now have a blue circle with the number of uncommitted files.
5. Now you need to commit all your files.
   1. Click on the “Source Control” icon in the Activity Bar.
   2. Click on the plus icon next to Changes.  This will cause all files to be “staged” for a subsequent commit action.
   3. Type in a message describing this commit.  Normally you should put in something informative, but in this case just say “Initial commit”.
   4. Click check-mark icon.  All files are now locally committed.
6. Now we need to add a connection from your local repository to the remote repository.  You must now open a terminal window by typing control-back-quote.  (If you can’t find this key, you can pop down the “View” menu and select “Terminal”).  Type the following lines, with your repository URL pasted into the appropriate spot:

   git remote add origin repository-url
   git push -u origin master

Now go back to your browser and visit the page for your new repository.  You should now see all the files listed on the web page.

Comitting changes to the code

In the Activity Bar there is an icon that opens the Source Control sidebar.  This is where we can manage our git status.

From now on, when you add files, delete files, or modify files, git and VS Code will keep track of how your code differs from the most recent commit.  The Source Control sidebar show you which files have changed.

Let’s make some small changes.  Click to the Explorer tab. Create a README.md file and type some text to describe your current file.  Next, make a minor change to Robot.java, such as modifying a comment.  Click back to the Source Control sidebar and you will see a list of the two files you’ve changed.

Double-clicking on any filename will pop up a window outlining your changes.  Hovering your cursor over any filename will reveal action buttons to discard the changes or to stage the file to be committed.

If you are happy with the changes then you can commit them into git. You do not need to commit all the changed files.  Selecting which ones to commit is called “staging” the changes.  In this case, click the “+” button next to both files to stage them both.

Now type in a message and click the check-mark button. Your changes are now committed to the local repository.

One note about commits: only commit code that you know to be good.  It is bad form to commit code that won’t compile or has some significant problem.  We share code with other programmers by sharing commits.  You don’t want to be the person who breaks other people’s code.

Pulling changes back from the repository

Suppose someone else has made changes to the code and pushed them up to the remote repository.  You’d like to fetch those changes and merge them into our code.  This is called doing a pull from the remote.

You can pull at any time, but it is usually best to commit your code locally before pulling.

Within the Source Control sidebar of VS Code, click on the three little dots to get the More Actions menu.

Select “Pull” from the menu.  This should merge in all changes from the remote repository.

If the incoming changes are in different files from your own changes, then the new adds/updates/deletes will be applied to your collection of files.

If someone has modified a file that you are working on, but where those changes do not overlap your changes, then git will try to cleverly merge the incoming changes into your file.  This might be perfectly fine, or it might break your code.  These things happen.  Keep calm and fix the code.  It is your responsibility to fix and test your code before pushing it up to the repository.

However, if the incoming changes overlap with your changes, then git will declare a “merge conflict” which you must resolve before you can commit and push.  VS Code will show you each conflict and give you options on how to handle it.  If none of the offered options are correct, you may choose to just edit the file until it is right.  When all code has been fixed, you must stage and commit all changed files.

Pushing your changes up to the repository

If you are ready to release your changes to the rest of the group, you can push your commits up to the remote repository.

Open the More Actions menu and select “Push”.  Done.

Synching with the remote repository

There’s an important discipline that everyone must develop with respect to the remote repository, which is that you should always pull in remote changes before pushing up your own.  If there are incoming changes, then you must recheck the merged code to verify that it is OK.

There is a “Sync” option in the More Actions menu that will do the pull and push in one step.  This can be a nice feature if no one else is working on your code.  If multiple people are working, then Sync does increase the risk that the repository will contain combinations of files that do not work together.  With multiple programmers, you should avoid Sync and perform the following steps manually:

1. Stage and commit your changes locally.
2. Pull remote changes, and deal with any merge conflicts.
3. Verify that the merged code compiles correctly and that the code works correctly.  If there are any problems, fix them and then go back to step 1.
4. Push all commits to the remote repository.

Further Reading:

• XKCD explains git
• Pro Git : a free book about git
• The Git Glossary:  because the terminology of git can be pretty inexplicable.
• Version Control in VS Code
• How to Initialize a Git Repository using Visual Studio Code