A practical Git/GitHub workflow for VEX V5RC teams using PROS in VS Code. Covers everything from first push to mentor pull requests. Read Toolchain Onboarding first if you don't yet have VS Code + PROS installed.
Who this is for. Programmers on a V5RC team who want to share code, recover from breakage, and let a mentor see and modify their work. The team is using VS Code + PROS (per our toolchain) — this guide assumes that setup. If your team uses VEXcode, the Git story is harder; consider switching to PROS first.
What Git Does (and Doesn't)
Git is a tool that tracks changes to your code over time. Every time you commit, Git saves a complete snapshot of your project. You can return to any past snapshot, see what changed between any two snapshots, and let multiple people work on the same project without overwriting each other.
Git is the tool. GitHub is a website that hosts Git projects in the cloud, with extra features for collaboration: pull requests, issues, code review, mentor access. Other hosts exist (GitLab, Bitbucket); GitHub is the most common for V5RC teams.
What Git is not:
Not a backup tool. If your laptop dies, Git on your laptop dies with it. The backup happens when you push to GitHub. Push often.
Not magic conflict resolution. If two people edit the same line, Git asks you to manually merge. The merge tooling is decent but you have to think.
Not a build system. Git tracks source code. PROS handles compilation. They're separate concerns; don't commit compiled output (`bin/`).
Why This Specifically Matters For Your Mentor
A programming mentor who can pull your team's code can: review what you wrote between sessions, leave comments on specific lines via GitHub's pull request interface, suggest changes via branches, fix bugs you got stuck on, and see the history of your decisions. Without Git, the mentor only sees what you screen-share when they're physically in the room. With Git, they can help asynchronously — the night before a tournament, between practices, on weekends.
The setup is one-time. Once it's in place, the mentor types two commands (git pull, then git checkout) to see your latest work, and your team types two commands (git add . && git commit -m "msg", then git push) to share theirs. That's the whole workflow once you're past setup.
Conflict Resolution — when two students edited the same file, what to do
Recovery — "I broke main 10 minutes before a match" — revert, reset, checkout
Failures & Tips — common mistakes, security notes, things that go wrong
New to Git entirely? If you've never used Git or the command line before, start with the Git & Version Control intro first — it covers the four commands you actually need and walks through your first commit in one short session. Come back here when you're comfortable with the basics and ready for the full team workflow.
If you only do one thing from this guide: get the team's code into a private GitHub repo this week, and push at the end of every session. That alone is 80% of the value. Branching, pull requests, and code review are upgrades you add once the basic push/pull cycle is a habit.
1 of 8
// Section 02
One-Time Setup ⚙
Install Git, create accounts, configure auth. Done once per team member; takes ~20 minutes.
⏱️
~30
Min Setup
One-time per team member. Then it just works.
🔄
3
Daily Commands
pull · commit · push. Memorize this cycle.
🛡️
5
Recovery Patterns
For when you "broke main 10 minutes before a match."
$git --versiongit version 2.43.0# If you see a version, you're set. If "command not found", install:
Windows: download from git-scm.com/download/win and run installer. Default options are fine. Restart VS Code after.
macOS: open Terminal and type git --version; macOS will prompt to install Xcode Command Line Tools, which includes Git. Or install via Homebrew: brew install git.
Go to github.com and create an account. Use a real-name or team-name email so the mentor can find you. Free accounts are fine — private repos are free now (this changed in 2019; old advice may say otherwise).
Each programmer on the team needs their own GitHub account. Don't share one. Git tracks who made each change by GitHub username; sharing breaks that. The mentor also needs an account.
3. Configure Git Identity
Tell Git who you are. This shows up on every commit you make, forever — pick the name and email you want associated with your work.
Terminal — one-time per machine
$git config --global user.name "Your Name"$git config --global user.email "your-email@example.com"# Use the same email as your GitHub account for clean attribution$git config --global init.defaultBranch main# Modern default; older Git defaulted to "master"
4. Set Up Authentication: Personal Access Token (Recommended)
When you push to GitHub, you have to prove you're you. There are two main options:
HTTPS + Personal Access Token (PAT) — recommended for V5RC teams. Easier to set up. Works on every platform identically. The team uses HTTPS URLs like https://github.com/spartan-design/team-2822-code.git.
SSH keys — more secure long-term, but requires generating a key pair, adding to GitHub, and remembering passphrases. Skip for now; revisit if/when the team has multiple machines per programmer.
To create a Personal Access Token:
1
Go to github.com/settings/tokens (or click your avatar → Settings → Developer settings → Personal access tokens → Tokens (classic)).
2
Click Generate new token (classic). Give it a descriptive name like VRC-laptop-2026.
3
Set expiration to 90 days or 1 year. Token expiration limits damage if it's accidentally committed somewhere.
4
Check the repo scope. That's the only one you need for normal team work. Don't check more than necessary.
5
Click Generate token. Copy the token immediately — GitHub only shows it once. Save it somewhere safe (a password manager is best).
6
When Git prompts for password during your first push, paste the token there (not your GitHub account password — that won't work).
On most systems, Git stores the token after first successful use so you don't have to enter it every time. If it doesn't, install the Git Credential Manager (built into Git for Windows; brew install git-credential-manager on macOS).
Treat the token like a password. Don't paste it into chat, don't commit it to a repo (especially the team's repo!), don't put it in a shared Google Doc. If you suspect it's leaked, go back to the tokens page and revoke it — takes 10 seconds.
5. VS Code Setup
VS Code has Git integration built in. Two recommended extensions for V5RC team work (per toolchain-onboarding):
GitLens — shows who wrote each line and when, inline. Speeds up code review and helps you understand history. Search GitLens in the Extensions panel.
GitHub Pull Requests and Issues — lets you review and merge pull requests directly in VS Code. Installs from Microsoft.
The default Source Control panel (Ctrl+Shift+G) shows changed files, lets you stage/commit, and pushes/pulls. We'll show both VS Code GUI and command-line equivalents throughout this guide so the mentor and students can use whichever they prefer.
2 of 8
// Section 03
Repo Setup 📁
Turn a PROS project into a Git repo, push it to GitHub, invite the mentor. Done once per team.
📌 Quick Take
Done once per team. Init the repo, push to GitHub, invite the mentor. Take 2 minutes. After that, every future session uses the daily flow below.
📚VS Code Extension · VEX Library
VEX’s official VS Code Extension documentation — for advanced students moving past VEXcode.
One person on the team (typically the lead programmer or a coach) creates the GitHub repo:
1
Go to github.com/new.
2
Pick a repository name that's easy to type. Suggested format: team-NUMBER-LETTER-SEASON, e.g., team-2822A-override.
3
Set to Private. RECF student-centred policy means your code is your team's; sharing publicly invites trouble.
4
Do not add a README, .gitignore, or license from GitHub's wizard. The PROS project will provide those. Empty repo only.
5
Click Create repository. GitHub will show a page with HTTPS and SSH URLs — copy the HTTPS one. Looks like https://github.com/your-org/team-2822A-override.git.
2. Initialize Git in Your PROS Project
Open VS Code in your existing PROS project folder. Open the integrated terminal (Ctrl+`). Verify you're in the right directory:
$git initInitialized empty Git repository in /Users/.../team-2822A-override/.git/
This creates a hidden .git directory that stores all version history. The folder itself is now a Git repo.
3. Create a .gitignore for PROS
Some files should not be committed. Compiled binaries (bin/), editor metadata, and OS files like .DS_Store are clutter at best, and can break things at worst. Create a file named .gitignore in the project root with this content:
.gitignore (in project root)
# Compiled outputbin/*.o*.elf*.bin# PROS metadata that gets regenerated.d/# Editor / OS files.vscode/settings.json.DS_StoreThumbs.db*.swp# Personal IDE config — keep team-shared settings, ignore personal.idea/
What to commit vs ignore: commit your source code (src/, include/), the build configuration (Makefile, project.pros), libraries you depend on (firmware/ if PROS keeps those there), and your README. Ignore everything that gets regenerated by the compiler or by your editor.
Alternative: Clone Spartan's Competition Template
Instead of initializing from scratch, your team can clone the Spartan Competition Template — a ready-to-upload PROS + EZ-Template starter repo. This skips the "empty PROS project" step and gives you a competition-ready file structure, an auton selector, and pre-tuned PID defaults out of the box. Use this if your team is starting a fresh season build or rebuilding after a major mechanism change.
What's inside the template: pre-wired auton selector with match-phase hooks and competition switch handling, EZ-Template configuration with drive/turn PID defaults and IMU setup ready to edit, organized file structure with subsystem files separated from main.cpp (easy to find, easy to hand off), README and port map document for motor and sensor assignments, and match-safe defaults for disabled / autonomous / driver-control states.
To clone instead of initializing:
Terminal — in your project parent folder
$git clone https://github.com/spartandesign/competition-template.git$cd competition-template$code .# open in VS Code
Then, to point the cloned project at your team's GitHub repo (not Spartan's), update the remote:
Coach note: as each branch is published, replace the "Coming Soon" badge above with an actual GitHub link. Search for Coming Soon in this file to find them all quickly.
4. First Commit
Stage every file in the project, then commit with a descriptive message:
$git add .# "." means "everything in this directory and below". The .gitignore filters out what shouldn't be added.$git statusOn branch main
Changes to be committed:
new file: .gitignore
new file: Makefile
new file: include/main.h
new file: src/main.cpp
...# Verify the file list looks right. If you see "bin/" in there, your .gitignore isn't being read.$git commit -m "Initial commit: project skeleton at start of Override 2026-27"[main (root-commit) abc1234] Initial commit: project skeleton at start of Override 2026-27
14 files changed, 287 insertions(+)
5. Connect to GitHub and Push
Tell Git where your remote (GitHub) repo is, then push:
$git remote add origin https://github.com/your-org/team-2822A-override.git# "origin" is the conventional name for the main remote. Use the URL from step 1.5.$git branch -M main# Ensures your branch is named "main" (not "master")$git push -u origin main# -u sets up tracking so future pushes can be just "git push"Username for 'https://github.com': spartan-programmer
Password for 'https://...': # paste your PAT here, not your GitHub passwordEnumerating objects: 16, done.
...
To https://github.com/your-org/team-2822A-override.git
* [new branch] main -> main
branch 'main' set up to track 'origin/main'.
Refresh your GitHub page in the browser — you should see all your project files there.
6. Invite Your Mentor (and Other Programmers)
1
On the GitHub repo page, click Settings (top of the repo).
2
In the left sidebar, click Collaborators and teams (you may need to confirm your password).
3
Click Add people. Enter the mentor's GitHub username or email. Same for each programmer on the team.
4
Pick the role: Write for active programmers (can push directly to branches). Maintain for the lead programmer (can manage settings). For the mentor, Write is usually right — lets them push branches and review code.
5
GitHub sends them an invitation email. They accept it on their end. Now they can clone the repo and start working.
Each invited person clones the repo to their own machine:
$git clone https://github.com/your-org/team-2822A-override.git$cd team-2822A-override$code .# Opens the project in VS Code
That's it for setup. The team and mentor now share one repo. Daily workflow is in the next section.
3 of 8
// Section 04
Daily Workflow 📥
The cycle every team member runs every session: pull, work, commit, push. Memorize this.
📌 Quick Take
Three commands. Every. Session. git pull (start of session), git commit (every meaningful change), git push (end of session). Skip the pull at the start, fight conflicts later.
The Cycle
git pull
→
edit code
→
test on robot
→
git add + commit
→
git push
Five steps, every session. Skipping the first (pull) loses you the mentor's overnight work. Skipping the last (push) loses your work if your laptop dies.
Start of Session: Pull
Before you write any code, get the latest from GitHub. This pulls in any commits the mentor or another programmer made since you last worked.
If you see Already up to date, no one made changes since your last pull. If you see a list of files changed, those are the new commits. Skim them so you know what the mentor or your teammates changed.
VS Code GUI equivalent: in the Source Control panel (Ctrl+Shift+G), click the "..." menu → Pull. Or click the sync icon in the bottom-left status bar.
During Session: Edit, Test, Repeat
Work normally. Save files. Compile and test on the robot using PROS. Git is just watching — nothing is committed yet.
You can check what you've changed any time:
$git statusOn branch main
Changes not staged for commit:
modified: src/autons.cpp
modified: src/main.cpp
Or see the actual line-by-line changes:
$git diff# Shows additions (green) and deletions (red) for every modified file# Press space to scroll, q to quit
VS Code GUI: the Source Control panel (Ctrl+Shift+G) shows changed files. Click any file to see the diff visually.
End of Session: Stage and Commit
Before pushing, you commit your changes locally. A commit is a snapshot with a message describing what you did.
Terminal — at end of session
$git add .# Stages every changed file. Or use specific files: git add src/autons.cpp$git commit -m "Tune turn PID kP from 2.0 to 2.4 -- reduces overshoot on 90deg"[main 9e1b2c3] Tune turn PID kP from 2.0 to 2.4 -- reduces overshoot on 90deg
1 file changed, 1 insertion(+), 1 deletion(-)
Writing Good Commit Messages
The commit message is what your mentor (and future-you) sees when reviewing what changed. A good message answers what and why:
Bad: "fixed it" / "updated code" / "wip"
Good: "Tune turn PID kP from 2.0 to 2.4 -- reduces overshoot on 90deg"
Good: "Add limit switch to arm; auto-zero encoder when bottom triggered"
Good: "Fix: claw was opening at start instead of closing -- swapped 0 and 200 in claw_control"
Convention: first line is <72 characters, present tense ("Fix bug", not "Fixed bug"). If more detail is needed, leave a blank line and add a paragraph below. Commit messages also feed your engineering notebook — clean ones write themselves into your weekly log.
Push to GitHub
Commits live only on your laptop until you push. Push at the end of every session.
$git pushEnumerating objects: 5, done.
...
To https://github.com/your-org/team-2822A-override.git
def5678..9e1b2c3 main -> main
If the push is rejected because someone else pushed first, see the Conflicts section. The most common cause: another programmer pushed while you were working. Pull first, resolve any merge, then push.
VS Code GUI Equivalent
The whole cycle in VS Code without command line:
Open Source Control panel (Ctrl+Shift+G).
Click the "..." menu → Pull (start of session).
Edit code as normal.
In the Source Control panel, type a commit message at the top.
Click "Commit". If it warns about no staged changes, click "Yes" to stage all.
Click "Sync" (the cycle icon) to push.
Both work; pick what you prefer. The mentor will probably use command-line for speed; students often start with the GUI.
The end-of-session habit. Every programmer pushes before leaving. If the build is broken, push to a branch (next section), not main. The team should never end a session with uncommitted work on someone's laptop — if that laptop is unavailable next session, the team is blocked.
Practice Session Sequence (Full Cycle)
The git commands above are the version-control half. The other half is testing on the actual robot — a full practice session integrates both. Use this sequence every time you sit down to code:
1
Pull the latest code.git pull before you touch anything. You want the most recent working version, not what was on your laptop last week.
2
Open in VS Code, check the port map. Open robot-config.cpp. Verify motor ports match the robot in front of you before uploading anything — another teammate may have changed wiring.
3
Test controller mapping. Upload to the brain. Drive the robot with no field elements nearby. Confirm all buttons do what you expect. This catches errors from someone else's commits before you build on top of them.
4
Test the autonomous. Select an auton on the brain and run it. Does it match what the code says it should do? If not, fix it before adding new work.
5
Make your changes. Edit the code. One thing at a time. Test after each change — don't stack three edits and then wonder which one broke it.
6
Commit and push when it works. Once the robot behaves correctly, commit with a clear message and push. Use the message format from above: present tense, <72 chars first line, why-not-just-what.
This rhythm ties every commit to a verified-on-robot moment. Future-you (or your mentor) reading git log can trust that every commit corresponds to working hardware behavior at the time it was made.
4 of 8
// Section 05
Mentor Collaboration 🧑🏫
Branches, pull requests, and code review — the patterns that let a mentor help asynchronously without breaking the team's working code.
📌 Quick Take
For features bigger than one session: branch off main, work on the branch, open a PR, mentor reviews, merge. Mentors should review code; team members should write code.
The Two Modes
A mentor can interact with the team's code in two ways:
Read-only review. Mentor pulls, reads, leaves verbal feedback in the next practice. Lowest overhead. Use when the team is healthy and the mentor just wants to keep an eye on things.
Active collaboration via pull requests. Mentor creates a branch, makes changes, opens a pull request. Team reviews and merges (or rejects). Higher overhead but lets the mentor actually fix things between practices.
Both are useful at different times. The pull request flow is the one your mentor most likely wants — it's how professional software teams work and how RECF judges expect to see senior contributors interact with student code.
Why Branches Matter
Until now, everyone has been working on main. That works for a small team where no one is doing anything risky. But:
If the mentor pushes a half-finished change directly to main, the team's next pull may break their robot.
If a programmer is in the middle of a big refactor, others can't pull from main without inheriting incomplete work.
If you need to compete tomorrow with the code as it is today, you don't want surprise commits on main.
Branches solve this. A branch is a parallel line of development. You can experiment, break things, and abandon work without affecting main. When the work is solid, you merge the branch into main via a pull request.
The Mentor's Workflow
When the mentor wants to suggest a change:
Mentor's terminal
$git pull# start from the team's latest$git checkout -b mentor/turn-pid-tuning# new branch, descriptive name# ... edit code ...$git add .$git commit -m "Suggest: lower kI on turn PID to reduce wind-up"$git push -u origin mentor/turn-pid-tuningremote:
remote: Create a pull request for 'mentor/turn-pid-tuning' on GitHub by visiting:
remote: https://github.com/your-org/team-2822A-override/pull/new/mentor/turn-pid-tuning
The mentor follows the link GitHub provides, fills in a description of what the change does and why, and clicks Create pull request. The team gets a notification.
The Team's Review Workflow
When the team sees a pull request from the mentor:
1
Open the PR on GitHub. Read the description — what is the mentor changing and why?
2
Click the Files changed tab. See every modified line side-by-side: red for removed, green for added.
3
Click on any specific line to leave a comment, ask a question, or request a change. The mentor sees your comments and can respond.
4
Test the change: pull the mentor's branch, build, run on robot.
$git fetch$git checkout mentor/turn-pid-tuning$prosv5 mu# build and upload to robot
5
If it works, switch back to main and merge the PR via GitHub:
$git checkout main
Then on GitHub, click the green Merge pull request button. Choose "Squash and merge" for cleanest history.
6
Pull the merged change back into your local main:
$git pull
Suggested Changes (GitHub's Magic)
For small fixes (a typo, a wrong constant), the mentor doesn't even need to make a branch. They can use GitHub's suggested changes feature:
Mentor opens the team's code on GitHub. Clicks the "..." on a line and picks "Reference in new issue" or just navigates to the file.
Click on a line to comment. In the comment box, click the "Suggested change" icon (a plus-and-minus square).
Mentor types the corrected version of the line. GitHub renders it as a side-by-side diff.
The team can click Commit suggestion directly in GitHub — no terminal needed. The change merges into the team's branch immediately.
This is the lightest-weight collaboration mode. Use it for typos, sign errors, and one-line fixes. For bigger changes, full pull requests give more room for discussion.
Branch Naming Conventions
Pick a convention and stick to it. Suggested:
Prefix
Use For
Example
mentor/
Mentor's suggestions
mentor/fix-claw-toggle
feature/
New mechanism or auton routine
feature/red-left-auton
fix/
Bug fixes
fix/arm-overshoot
experiment/
Trying something risky
experiment/lemlib-port
Branch names show up everywhere — in pull requests, in git log, in the GitHub UI. Make them descriptive enough that a teammate knows what the branch is for without having to read the commits.
Notebook Connection
Pull requests are excellent notebook material. A judge looking at your engineering notebook sees: "Mentor proposed lowering turn-PID kI; we tested, observed reduced wind-up but slower convergence; rejected the change with these notes." That's the engineering process documented in artifacts — far more compelling than a written summary. Take screenshots of meaningful PR discussions and embed them in your notebook entries.
5 of 8
// Section 06
Resolving Merge Conflicts ⚡
When two people edited the same file, what to do. This will happen; here's how to handle it without panic.
📌 Quick Take
Conflicts will happen. They're not catastrophes. Open the conflicted file, find the <<<<<<< markers, decide what to keep, save, commit. Three minutes if you don't panic.
What a Conflict Looks Like
You ran git pull or merged a branch. Git couldn't figure out how to combine two changes to the same file. You see something like:
$git pullAuto-merging src/autons.cpp
CONFLICT (content): Merge conflict in src/autons.cpp
Automatic merge failed; fix conflicts and then commit the result.
Open the affected file. Git has marked the conflict zones with special markers:
// drive forward to scoring position
chassis.pid_drive_set(24_in, 90);
<<<<<<< HEAD
chassis.pid_wait_quick();
=======
chassis.pid_wait();
pros::delay(100);
>>>>>>> main
chassis.pid_turn_set(90_deg, 70);
Translation: above the ======= line is your version; below it is the version that's being merged in (from main). Git is asking: which one do you want? Or do you want some combination?
How to Resolve
1
Read both versions. Talk to the other programmer (or the mentor) if you don't understand why they made their change.
2
Decide what the final code should be. Could be your version, their version, both combined, or something new entirely. Use your judgment.
3
Edit the file to remove the conflict markers (<<<<<<<, =======, >>>>>>>) and leave only the resolved code.
4
Save the file. If there are multiple conflicted files, repeat for each.
Test the merged code on the robot. Conflicts often hide bugs — the merged version may compile but behave wrong. Run the affected auton.
7
Push.
VS Code's Built-in Merge Tool
VS Code shows conflicts visually. When you open a conflicted file, you'll see colored highlights and clickable buttons:
Accept Current Change — keep your version, discard theirs.
Accept Incoming Change — keep their version, discard yours.
Accept Both Changes — concatenate both. Often produces broken code; review carefully.
Compare Changes — opens a side-by-side diff so you can pick line-by-line.
For most simple conflicts, "Compare Changes" with manual editing is the right move. Don't blindly "Accept Both".
Avoiding Conflicts in the First Place
Pull at the start of every session. Smaller diffs → fewer conflicts.
Push at the end of every session. Same logic from the other end.
Communicate when working on the same file. A 10-second "hey, I'm editing autons.cpp" in your team chat prevents 30 minutes of merge cleanup.
Use branches for big changes. If you're about to refactor something major, do it on a branch. Merge to main when done.
Keep files focused. If main.cpp has 800 lines, every change touches it. Split into src/autons.cpp, src/mechanisms/arm.cpp, etc., and conflicts become rare.
If you're really stuck, don't panic. git merge --abort reverses any in-progress merge and returns you to the pre-merge state. You can ask the mentor for help, then try again.
6 of 8
// Section 07
Recovery 🚫
"I broke main 10 minutes before a match." The patterns that get you back to working code.
📌 Quick Take
Two patterns: git reset --hard HEAD~1 (undo the last commit), or git checkout <commit-hash> (jump to a known-good earlier version). Have these in your phone notes.
Git's superpower for V5RC is being able to get back to a previous working state in under a minute. The patterns below cover increasing degrees of breakage.
Competition Day Workflow (Prevention > Recovery)
Most recovery scenarios are preventable with the right pre-event sequence. The morning of an event is not the time to experiment — this sequence keeps the robot predictable and the team calm.
1
Confirm you are on the tested version.git log --oneline -5. Is the commit at the top the one you tested at last practice? If not, check out the right tag: git checkout v1.0-statefair.
2
Verify motor and sensor ports. Open robot-config.cpp. Check every port number against the physical robot. One wrong port and your auton won't run. Catches wiring changes that happened between practices.
3
Upload and test drive control. Drive around. Does it feel like it did at practice? Any robot changes since last test should be noted and re-verified.
4
Test the auton selector. Cycle through every auton option on the brain screen. Confirm names match what you planned to run; routines fire correctly.
Log changes after each match. If you make a fix between matches, commit immediately with a time-stamped message. You need to know exactly what was on the robot for each match.
No untested code at events. If you make a change at an event, test it before queuing — even small fixes. "It'll probably be fine" is how teams miss the auton phase.
Scenario 1: I Have Uncommitted Changes That Broke Everything
You edited a file, things stopped working, you want to go back to the last committed state.
$git status# see what's modified$git restore src/autons.cpp# discard changes to one file$git restore .# discard ALL uncommitted changes -- careful!
Scenario 2: I Committed Bad Code, Haven't Pushed
The last commit is bad. No one else has it yet. You can rewrite history safely.
$git reset --soft HEAD~1# undo commit, keep changes staged# Now edit, fix, and re-commit$git reset --hard HEAD~1# undo commit AND discard changes# Use only if you really want to throw the work away
Scenario 3: I Pushed Bad Code, Need to Roll Back
The bad commit is already on GitHub. The team has it. You need to undo it without rewriting shared history.
$git log --oneline -5# see the last 5 commits with their hashes9e1b2c3 Bad commit -- breaks claw control
def5678 Tune turn PID kP from 2.0 to 2.4
abc1234 Initial commit$git revert 9e1b2c3# creates a NEW commit that undoes the bad one$git push
git revert is safer than git reset for shared history. It adds a new "undo" commit instead of removing the bad one. Everyone's history stays intact; the bad code is just no longer in the working state.
Scenario 4: I Need The Code From Last Tuesday
Whatever happened, the team needs to compete in 30 minutes and the working version was the one from before today's changes.
$git log --oneline# find the hash of the good commit$git checkout def5678# go back to that commit (read-only)# Build, upload, compete. Don't make changes here -- this is "detached HEAD" state.# After the match, return to the latest:$git checkout main
Scenario 5: Emergency "Use This Specific Tag"
Best practice: before every tournament, tag the version of code that's known to work. Then if anything goes sideways during the event, you can return to it instantly.
Before tournament: tag the working code
$git tag v1.0-statefair$git push origin v1.0-statefair
During tournament: return to it
$git checkout v1.0-statefair$prosv5 mu# upload to robot
Tagging takes 5 seconds before each event. The peace of mind during the event is worth it.
Scenario 6: Total Disaster — Start Over From GitHub
Local repo is so broken you can't reason about it. Re-clone from GitHub and start fresh.
$cd ..$mv team-2822A-override team-2822A-override-broken# keep old just in case$git clone https://github.com/your-org/team-2822A-override.git$cd team-2822A-override$code .
Anything you'd pushed to GitHub is in the fresh clone. Anything you hadn't pushed is in the old folder — copy it over manually after you're back in working order.
Tag before every tournament. The single most useful Git habit for competition. It costs 5 seconds and prevents tournament-day catastrophes. Make it part of your pre-event checklist.
7 of 8
// Section 08
Failure Modes & Tips ⚠
The five things that go wrong with Git in V5RC team work, plus security and best practices.
📌 Quick Take
The Big Five: (1) wrong account in commits, (2) push rejected (forgot to pull), (3) merge conflicts, (4) detached HEAD state, (5) accidentally committed credentials. Each has a one-liner fix.
Push Rejected
! [rejected] main -> main (fetch first) when you push. Means someone else pushed first.
Fix:git pull, resolve any conflicts, then git push. Don't use --force on shared branches — it overwrites their work.
Authentication Failed
Git asks for password, you type your GitHub account password, it rejects.
Fix: use a Personal Access Token, not your GitHub password. GitHub deprecated password auth in 2021. See section 02 for token setup.
Accidentally Committed Secret
You committed a Personal Access Token, API key, or other secret to the repo. Pushed to GitHub.
Fix: revoke the secret immediately on the issuing site (don't wait). Then use git filter-branch or BFG Repo-Cleaner to remove from history. Force-push the cleaned history. Note: assume the secret was leaked the moment it was pushed; revoking is more important than scrubbing.
Huge Repo Size
Repo is hundreds of MB. Slow clones, slow pushes.
Fix: usually means binaries got committed. Check .gitignore covers bin/ and similar. Remove already-committed binaries with git rm --cached path/to/binary, commit, push. Repo size on GitHub takes a while to actually shrink.
Mentor Made Suggestions, Team Ignored Them
Pull request from mentor sat for two weeks. Mentor stopped offering feedback.
Fix: set a team policy. Every PR gets a response within 48 hours, even if it's "we'll test next session". Mentors notice unresponsive teams; respect their time and they'll keep helping.
Security Checklist
What Never Goes In a Git Repo
[ ]Personal Access Tokens, API keys, OAuth secrets
[ ]Passwords (yours, the team's, anyone's)
[ ]Personal contact info (phone numbers, home addresses)
[ ]Code from other teams (RECF student-centred policy)
[ ]Compiled binaries (bin/) — bloat, no value
Repo Settings to Verify
[ ]Repo visibility set to Private.
[ ]Only team members + mentor invited as collaborators.
[ ]Default branch is main.
[ ].gitignore covers bin/, editor metadata, OS files.
[ ](Optional) Branch protection on main: require PR review before merge.
The Pre-Tournament Git Checklist
Pull on every laptop. Everyone has the same code.
Tag the working version.git tag v-EVENT-NAME && git push origin v-EVENT-NAME.
Test the build on the venue laptop. The laptop you'll bring to the event should have a fresh pull and a successful build before leaving.
Bring the GitHub credentials. If something breaks, you may need to clone fresh on a different machine.
Phone-tether backup plan. Some venues have no Wi-Fi. Have the latest commit cloned to the venue laptop before you leave home.
STEM Highlight
Computer Science: Distributed Version Control & Branch Models. Git applies distributed version control — a system where every team member has a complete copy of the project history. The branch model creates isolated development environments: each feature or fix lives on its own branch. The main branch is protected as the always-deployable state. This mirrors the workflow used at every professional software development organization.
🎤 Interview line: "We follow a professional Git workflow: feature branches, code review before merging to main, and competition tags that freeze the tested codebase. When a teammate broke auton the night before a competition, we reverted to the last tagged release in 30 seconds. Without version control, that failure would have cost us the entire event."
Check for Understanding
You commit directly to main the night before a competition and accidentally break the autonomous. What workflow would have prevented this?
Using git stash to save uncommitted changes before testing
✓ Working on a feature branch and only merging to main after testing — main should always hold tested competition-ready code
Committing more frequently so individual commits are smaller
Why: Stash hides changes but doesn't prevent them from being merged untested. Smaller commits don't prevent buggy ones — they just make the bugs easier to find afterward. The actual fix is keeping main as the always-deployable baseline and doing all risky work on branches that are merged in only after they're verified on the robot.