Lesson 1: Intro to Git & GitHub

Prerequisites

Read through and complete the Tooling Setup and Java evaluation task.

Learning Goals

• Clone the training-2026 repo, and open it.
• Understand the Git flow well enough to make a branch, commit, pull, and open a PR later.

What is Git?

• A version control system
  • Tool that tracks different versions of your code over time
• Runs locally on your computer
• Tracks changes in files
• Lets you go back to previous versions

What is GitHub?

• A website that hosts your Git repositories online
• Makes it easier to collaborate
• Keeps your work backed up in the cloud
• Allows for code reviews, comments, and teamwork
• (This is the website where you joined the training-2025 repo)

Why Is It Important?

• Prevent losing work
• Collaborate without overwriting each other’s code
• Track changes and history
• Experiment safely with new features

Core Concepts

• Repository (repo): Project folder tracked by Git
  • Example: 971-software-training-2025
• Commit: A snapshot of the latest changes of the source code to the repository
• Branch: A parallel version of the repo that allows you to work on new features or fixes without affecting the main codebase
• Merge: Combining changes from one branch into another
• Push: Upload local changes to GitHub
• Pull: Download changes from GitHub

How A Git Branching Works

Repo Workflow

Typical Workflow

1. Clone the repo (completed last lesson)

2. Create an issue

   

3. Write code

4. Fetch changes from main and merge them into the current branch

   git pull origin main
   

5. Add modified files to your next commit (stage)

   git add .
   

6. Record the changes in the staging area in the repository with a descriptive message

   git commit -m "Your commit message"
   

7. Push your branch to GitHub

   git push
   

   NOTE: If pushing on a local branch for a new time, git push will give you this error:

   fatal: The current branch my-feature-branch has no upstream branch.
   To push the current branch and set the remote as upstream, use
   
       git push --set-upstream origin my-feature-branch
   

   Then, if you follow that advice and run: git push --set-upstream origin my-feature-branch Git will push the branch and say something like:

   Enumerating objects: 5, done.
   Counting objects: 100% (5/5), done.
   Delta compression using up to 8 threads
   Compressing objects: 100% (3/3), done.
   Writing objects: 100% (5/5), 500 bytes | 500.00 KiB/s, done.
   Total 5 (delta 2), reused 0 (delta 0), pack-reused 0
   remote:
   remote: Create a pull request for 'my-feature-branch' on GitHub by visiting:
   remote:      https://github.com/your-user/your-repo/pull/new/my-feature-branch
   remote:
   To github.com:your-user/your-repo.git
    * [new branch]      my-feature-branch -> my-feature-branch
   Branch 'my-feature-branch' set up to track remote branch 'my-feature-branch' from 'origin'.
   

8. Click on the link given in the Git message above to open a Pull Request (PR) and add reviewers

   • When you git push from a branch, GitHub should give you a link to create a PR
   • If not, you can press the "Contribute" button from the branch to make a PR
   

9. Team reviews and merges it into main

   

   Note: Never commit directly to main

PR Workflow

• Go onto main & update main to its most recent version (starts your directory with the most recent code)

  git checkout main
  git pull
  

• Make a new branch off main to put your future changes on

  git checkout -b branch-name
  

• Make changes then commit & click the link given when you push to make a PR

  git add .
  git commit -m "your commit msg"
  git push 
  

  (follow the advice for git push)
• Make a new branch for every task in the training program, and every feature/fix you make in the codebase

How to revert your changes and move them to another branch

• You have some commits on your old branch that are part of what should be in another branch
• Identify the commits that you want on your new branch

git log --oneline

• Create a new branch from main (make a clean branch)

git switch main
git pull origin main  
git checkout -b lesson-3

• Cherrypick/add the commits from your old branch to your new branch

git cherry-pick <commit-hash> # the commit hashes you noted down from the git log command

• Push your changes to your new branch & click the link it gives you to make a PR

git push --set-upstream <new-branch-name> 

• Remove commits from old branch (do for all commits cherrypicked)

git revert [commit hash]

• Push your changes to your old branch

git push

Basic Git Commands

• Clone (make a copy) of an existing repo

  git clone <repository-url>
  

• Add modified files to your next commit (stage)

  git add .
  

• Record the changes in the staging area with a descriptive message

  git commit -m "Your commit message"
  

• Upload local commits to a remote repo

  git push origin main
  

• Fetch changes from a remote repo and merge them into the current branch

  git pull origin main
  

• Show the commit history for the branch

  git log
  

• Switch to the main branch

  git checkout main
  

• Create a new branch and switch to it

  git checkout -b <github-username>/<issue-number>-<short-description>
  

• Temporarily store staged changes

  git stash
  

• Restore the stashed changes

  git stash pop
  

• Show differences of what has changed but hasn’t been staged

  git diff
  

Git Cheat Sheet: education.github.com/git-cheat-sheet-education.pdf

How 971 Robotics Uses GitHub

• Review this page for contributing guidelines: (Pay special attention to the branch naming guidelines)

• Peer reviewing: All code should be approved by:

  1. One person knowledgeable in the area that the code affects
  2. One other person

• Use GitHub Projects to track issues and progress: https://github.com/orgs/frc971/projects/9/views/7

Tips

• Pull often to avoid merge conflicts
• Commit frequently with meaningful messages
• Ask for help when you’re stuck
• Review PRs respectfully and constructively

Post-Lesson Activity

1. Push your solution for the Java evaluation project onto this repo in tasks/java-evaluation/
2. Create a PR and add reviewers
3. Peer review 2 other people’s work (give comments)
4. Resolve any comments that were given

Remember to follow the contributing guidelines!