Watch the 7-minute Microsoft video, then layer on the PROS-specific bits the video doesn't cover — the right .gitignore, what to commit, and the branch-naming convention that survives a season.
main_v2_FINAL_REAL_use_this_one.cpp. Git is the engineering practice that prevents all of those.Two weeks before competition, the flash drive carrying the team's autonomous routine disappears between the bus and the engineering room. With Git, the code lives on GitHub. Without it, you're rewriting from memory.
Two coders edit the same file on different laptops. Whoever uploads second silently destroys the other one's work. With Git, conflicts are surfaced and resolved before a merge. Without it, you only find out at the next match.
Every change ships as a new file: main.cpp, main_v2.cpp, main_FINAL.cpp, main_FINAL_USE_THIS.cpp. Nobody knows which one is current. With Git, every version of one file is preserved with a message explaining what changed.
"Auton worked on Tuesday. Doesn't work today." Without Git, you have no idea what changed. With Git, you can git log through every commit since Tuesday and find the one that broke it.
The names get used interchangeably even though they're separate tools that work together. Worth getting the distinction straight from day one:
| Name | What it is | Where it runs |
|---|---|---|
git | The version-control program. Tracks every change in your project's history. | On your laptop |
| GitHub | A website that hosts your Git repositories so the team can share them. | github.com (cloud) |
| VS Code | The editor you write code in. Has a built-in panel that drives Git for you. | On your laptop |
The video in the next section shows VS Code running Git locally and pushing to GitHub. All three tools, working together. That's the full picture.
Your PROS extension already lives inside VS Code. The same window you write robot code in also has a built-in Source Control panel that runs Git for you — no separate terminal commands needed for the basics. One tool, both jobs.
.gitignore in section 4 is one EZ-Template ships with their starter project — that's not yours to "rewrite," it's part of the library. Anything you DO write (commit messages, branch policies in your notebook) should be in your own words.Use these to jump to a specific topic when you re-watch later.
The video uses a generic Node project, not a robotics project. The next sections fill in:
git program in the background. The program has to be installed on your laptop first. Five-minute setup, done once per machine.Every commit gets stamped with a name and email so the team can see who changed what. You set those once, globally, and Git uses them forever after. Open a terminal in VS Code (Terminal → New Terminal) and run:
Run this and confirm it prints a version number:
If you get command not found, the installer didn't add Git to your PATH — restart your terminal, then your laptop. If still broken, reinstall.
git is on your PATH, VS Code's Source Control panel (the third icon in the left sidebar, looks like a branching diagram) lights up and works..gitignore file controls this.If you've made an EZ-Template project, you have a folder that looks like this:
Anything you wrote OR vendored libraries that the build needs:
src/, include/, firmware/, Makefile, common.mk, project.pros, .clang-format, .gitignore
Anything that gets regenerated by a build, plus IDE-local config and OS metadata:
bin/, *.o, *.elf, *.bin, compile_commands.json, .cache/, .vscode/, .DS_Store, *.zip
.gitignoreEZ-Template's starter project ships with a working .gitignore. If you're starting from a fresh PROS project that doesn't have one, this is the minimum that handles the common cases:
Two extra rules teams typically add on top:
.vscode/ is in there. .vscode/settings.json often contains absolute paths from one specific laptop — checking it in can break VS Code on a teammate's machine. Keep it ignored unless your team agrees on a specific shared config worth committing.Once .gitignore is in place, you're ready to take a snapshot. Open the project in VS Code, then:
That's a snapshot. You can do this every time you finish a feature, fix a bug, or just want to mark a known-working state. Commit early, commit often.
mainFor a solo programmer, working directly on main is the simplest workflow that exists. Commit when something works. Push to GitHub at the end of each session. That's it — no branches to remember, no merges to perform, no PRs to open.
This is called trunk-based development. It's what Google, Meta, and most of the software industry use. The reason it works: every commit to main is small enough to be safe, and the history of main tells the story of the project as it actually evolved.
main. Once two coders are pushing, you need branches and PRs to avoid silent overwrites.Two days before a tournament, create a branch named after the event. From that point until the comp is over, all changes go on the comp branch. main is frozen.
| Without comp branches | With comp branches |
|---|---|
A 3am tournament-day patch goes straight to main — if it breaks, you've broken the working version. | The comp branch absorbs all event-day changes. main stays at its known-working state until you decide what to keep. |
| After the competition, you have no clean way to see "what changed during the event." | git diff main..comp/2025-spring-state shows you every change made during the tournament — useful for the engineering notebook. |
Bad fixes pile onto main permanently. | You review the comp branch after the event and only merge the changes that actually worked. |
Once you're home from the event:
comp/2025-spring-state → main on GitHub.The PR review is the engineering retrospective for the competition. Three months later when you're studying for your interview, the PR description plus the merge commit are the record of what your team learned at that event.
The convention used here:
| Pattern | Example | When |
|---|---|---|
main | (just one) | The trunk. Day-to-day work happens here. |
comp/<event-slug> | comp/2026-fall-league-1 | One per tournament. Created 1–2 days before, PR'd back after. |
season/<year> | season/2025-high-stakes | End-of-season snapshot. Created once when a season ends, never modified after. |
Use lowercase with hyphens. No spaces, no underscores. The names show up in the GitHub UI and in git log output — readable matters.
main, used by Google and most modern startups) and git-flow (heavyweight branching with release/hotfix/develop branches, used by older enterprise teams). The trade-off is between iteration speed (favoring trunk-based) and parallel-development isolation (favoring branches). For solo programmers, there's no parallel development to isolate — the only "other person" who'd ever cause a merge conflict is past-you, and past-you is in git log. Trunk-based wins. The single exception — a frozen branch for production-critical moments — is exactly what the comp-branch pattern formalizes.You committed an API key, a binary file, or a half-broken change you weren't ready to share. If you haven't pushed yet, this is easy.
Two coders edited the same lines and Git can't decide which version wins. VS Code shows the conflicting file with both versions side by side and a Resolve in Merge Editor button. Click it. The editor shows:
main or the branch being merged).Pick the lines that should win, save, then commit the merge. Resolving a conflict is a normal part of Git, not a sign that something is broken.
You meant to push to dev/feature but you pushed to main. If main still works, leave it alone — the commits are fine, they're just in the wrong branch. If main is broken because of the push, immediately revert:
git revert is safe to push because it adds a new commit instead of rewriting history. Use it whenever you need to undo something on a branch other people are also using.
Sometimes Git opens vim for a commit message and you can't figure out how to type or exit. The keystrokes are:
i to enter insert mode (now you can type).Esc to leave insert mode.:wq and hit Enter to save and quit.To make this never happen again, set VS Code as your default Git editor:
If you're stuck, panicking, and don't know what's going on — stop typing. Don't run any commands you don't understand. Take a screenshot of the terminal, post it to the team Discord, and ask. The single worst thing you can do is keep trying random fixes and make the situation harder to recover from.
git push --force on a shared branch unless a mentor tells you to. Force-push deletes everyone else's commits on that branch. There are situations where it's the right move, but they're rare and require knowing exactly what you're erasing.Git + VS Code Basics — Local Git, the PROS .gitignore, the trunk-based pattern. Done.
GitHub Getting Started — accept your invite to the spartandesign org, sign in via VS Code, clone your team's repo, push your first commit.
The Comp-Branch Workflow — before the event, during the event, after the event. The PR-back-to-main pattern, end to end.
Version Control Basics — the conceptual companion to this guide. The why behind the how.
Don't wait for the next guide to start using what you learned. Three small exercises before the GitHub-onboarding guide:
.gitignore. Initialize a Git repo. Make your first commit with a real sentence as the message.git log in the terminal. Confirm both your commits show up with your real name and your real commit messages.If the log shows your commits with messages that actually describe what changed, you've got the local Git basics. The next guide takes that and pushes it up to github.com/spartandesign.
comp/2026-fall-league-1 branch. You make a quick auton fix, but it doesn't quite work. Your match is in 10 minutes. What's the safe move?main directly so it's in the "real" branch.comp/2026-fall-league-1 anyway. The whole point of the comp branch is that experimental and panic fixes are isolated from main. After the event, the PR review decides what stays.git push --force over main with the comp branch.