Unit 3: Git & Version Control
Unit 3 · Lesson 1
Why Version Control Matters in FRC
Every serious FRC team uses version control. The ones that don't find out why it matters the hard way — usually at the worst possible moment. This lesson explains the problem Git solves before teaching the commands that solve it.
By the end of this lesson, you will:
- Explain what version control is in plain language
- Describe at least four specific FRC scenarios where version control prevents disaster
- Identify the common anti-patterns teams use instead of version control — and why each fails
- Understand the four zones of the Git mental model: working directory, staging area, local repository, and remote
- Explain why FRC teams use GitHub specifically, not just Git
What Version Control Actually Is
Version control is a system that records changes to a set of files over time so that you can recall specific versions later. That definition sounds dry, so here's the concrete version: version control is the ability to answer three questions about any piece of code you've ever written.
- What did it look like before? — See any previous state of any file at any point in history.
- What changed, and when? — See exactly which lines changed, who changed them, and why.
- Can we go back? — Restore any previous working state in seconds, without losing what came after.
When your code controls a 120-pound robot that can injure someone if it misbehaves, those three questions become less academic and more urgent. FRC programming is not a context where "I think it was working before I made that change" is an acceptable answer.
💡 Version control is not a backup system
A common misunderstanding: version control is not the same as making a copy of a folder. Backup systems preserve files. Version control tracks meaning — what changed, who changed it, and why. The commit message on a Git commit is the difference between "I can restore this file" and "I can restore this file and understand what the code was trying to do." At competition, that context is everything.
The FRC Chaos Problem
FRC programming has a set of constraints that make version control more important than in most software contexts, not less.
- Multiple programmers, one codebase. A typical FRC programming subteam has three to six students all touching the same files. Without coordination, the last person to save wins — and overwrites everyone else's work.
- Hard deadline with no extensions. Kickoff is in January. The regional is in March. The code has to work on a specific day. There is no "ship it next week" option.
- High-frequency iteration under pressure. During a competition, teams may make five or six code changes in a single day — between practice matches, between quals, in a ten-minute pit window. Each change needs to be recoverable if it breaks something.
- Team continuity across seasons. Students graduate. Mentors change. A team that doesn't use version control loses its institutional knowledge every four years when the seniors leave.
- Experimental changes with stakes. Testing a risky autonomous change the morning of qualifications affects real match outcomes. You need to be able to try it and immediately revert if it doesn't work.
🔍 Event Observation
The most heartbreaking version of this problem: a team's autonomous routine works perfectly in the shop. A programmer makes "one small change" the night before the regional. The autonomous breaks. Nobody can remember exactly what the change was. They spend the entire first day of qualifications with no autonomous — not because they couldn't write autonomous code, but because they had no way to recover the version that worked.
This scenario plays out at nearly every regional. The teams it doesn't happen to are the ones using version control.
What Teams Do Instead — and Why It Fails
Before Git, teams invented their own version control systems. All of them fail in predictable ways.
Robot_FINAL_v2_REAL.java
The filename version
Duplicating files with version numbers in the name. Collapses immediately when multiple people work simultaneously. Nobody knows which "FINAL" is actually final.
robot_backup_march4/
The folder backup
Copying the entire project folder before each change. Takes disk space, loses history between copies, and the metadata (who changed what, why) is gone entirely.
// old code, don't delete
The commented-out graveyard
Leaving previous implementations as comments "just in case." Files become unreadable. The comments rot as surrounding code changes. And there's still no history — just clutter.
Google Drive / OneDrive sync
The cloud sync
Syncing the project folder to cloud storage. Looks like collaboration, isn't. Two people editing the same file simultaneously creates conflicts that cloud sync resolves by keeping whichever version saved last. No merge, no history, no recovery.
"just email me the file"
The email hand-off
Passing code via email or Discord messages. Creates a scattered history across inboxes. When something breaks at midnight, "which Discord message had the working version" is not a debugging strategy.
one laptop, one programmer
The hero coder
One student owns all the code because "it's easier that way." When that student is sick during competition week — and this happens — the team has nothing. This is the most dangerous anti-pattern of all.
The Same Moment, Two Timelines
The best way to understand what version control gives you is to see the same FRC scenario play out with and without it. Select a scenario below.
FRC Scenario Explorer
select a scenario →
01
Autonomous broke overnight before qualifications
▶
02
Two programmers edited the same file at the same time
▶
03
A student accidentally deleted the drivetrain subsystem
▶
04
The lead programmer graduated. Nobody else knows the code.
▶
05
Testing a risky autonomous change before eliminations
▶
❌ Without version control
✅ With Git
The Git Mental Model
Before learning Git commands, you need a mental picture of the four zones Git works in. Click each zone to understand what it is and what lives there.
Working Directory
your files
git add
→
git restore
Staging Area
index
git commit
→
git reset
Local Repository
.git folder
git push
→
git pull
Remote Repository
GitHub
← click a zone to learn what it is
💡 The commands live between zones, not inside them
A useful way to think about Git: the commands (add, commit, push, pull) are the arrows that move your changes from one zone to the next. When something goes wrong, knowing which zone your changes are in tells you exactly which command will fix it. Unit 3, Lesson 2 covers all four commands in depth — for now, just internalize the zones.
Why Git? Why GitHub?
Git is not the only version control system — Subversion, Mercurial, and Perforce are alternatives. FRC uses Git because the broader software engineering world converged on Git roughly fifteen years ago, and because GitHub (the most popular remote hosting platform for Git repositories) is where the entire FRC open-source ecosystem lives.
There is an important distinction between the two:
- Git is the version control tool itself — a program that runs on your laptop and tracks changes to files. It works entirely offline. You can use Git with no internet connection.
- GitHub is a website that hosts Git repositories remotely. It provides a web interface for your code, enables collaboration between team members across different computers, and is where teams publish their open-source code for the community.
For FRC teams, GitHub does something else that matters: it is your disaster recovery system. When a laptop is lost, stolen, or destroyed during competition travel, the code on GitHub is intact. The first thing a team should do when they set up a new robot project is push it to GitHub — before they write a single line of robot logic.
🔍 Event Observation
A team's driver station laptop was stolen from their hotel room the night before their regional. Their robot code lived only on that laptop — no version control, no backup. They rebuilt the code from memory overnight and made it to their matches, but they ran a fraction of what they had built over six weeks of build season. The code that survived was only what their lead programmer remembered. The team that had pushed their project to GitHub the morning of travel had nothing to worry about.
🔌 System Check
⚙️ What You Need Before Lesson 2
Lesson 2 covers the actual Git commands. Before you get there, verify the following:
- Git is installed. Open a terminal (any terminal — the one inside WPILib VS Code works) and run
git --version. You should see something likegit version 2.4x.x. If the command is not found, download Git from git-scm.com and install it. On macOS, running anygitcommand will prompt you to install Xcode Command Line Tools if Git isn't present. - You have a GitHub account. If you don't, create one at github.com. Use an email address you'll have access to after you graduate — GitHub will become a professional portfolio. Set up your profile with your real name.
- You have a WPILib project from Unit 0. Lesson 2's practice prompt puts a real robot project under version control. You need a project to work with.
- No hardware required. Git and GitHub are entirely software-side. You'll put your robot project under version control before you've connected to any physical hardware in this unit.
Knowledge Check
Click an answer to check your understanding.
A teammate suggests using a shared Google Drive folder to collaborate on robot code since "it's basically the same as GitHub." What is the most significant problem with this approach?
Your autonomous routine was working perfectly yesterday. After a late-night session, it's broken and nobody can pinpoint what changed. What Git capability would have made this a five-second fix rather than an all-night investigation?
A new student asks what the difference is between Git and GitHub. What is the most accurate answer?
💪 Practice Prompt
Audit Your Team's Current Situation
Before you learn the commands, understand the problem you're solving for your specific team.
- Open a terminal and run
git --version. Record the version number. If Git isn't installed, install it now before moving to Lesson 2. - Check whether your team has an existing GitHub organization or repository. Ask a mentor or search GitHub for your team number. Write down: Does a repo exist? When was the last commit? How many contributors have touched it?
- Look at your team's current robot project (or your Unit 0 project if this is your first season). Without using Git, answer this: What changed in this project in the last week? If you can't answer that question confidently, you've just experienced the core problem version control solves.
- Pick two of the six anti-pattern cards from this lesson (filename versions, folder backups, commented-out graveyards, cloud sync, email hand-off, or hero coder). Write one paragraph each: have you seen this pattern in FRC or elsewhere? What was the consequence when something went wrong?
- Bonus: Look at Team 2910's GitHub repository. How many commits are in their most recent robot project? Click on any three commits and read the commit messages. What information does a well-written commit message give you that a filename like
Robot_v3.javanever could?