Git & GitHub —
Complete Beginner Notes

Why Git Exists

Before Git, developers managed projects by duplicating files with different names:

This becomes confusing and unmanageable extremely fast. Git was created to solve this problem entirely.

Core Idea

Think of Git as a save game system for code. Every save point is called a Commit.

You can return to any commit at any time. This means you can experiment freely, knowing you can always get back to a working state.

Git vs GitHub

Repository (Repo)

A Repository is a project folder managed by Git. Once you run git init, Git creates a hidden .git/ folder inside your project that stores the entire history.

cd ESP32_Project
git init

After this, the folder becomes a Git repository. The .git/ directory contains everything Git needs — commit history, branch information, remote connections, and configuration.

The Four-Stage Git Model

The most important concept in Git. Every file change moves through four stages before it reaches GitHub.

Stage 1 — Working Directory

Your actual project files. This is where you write code. Changes here are not yet tracked by Git in any permanent way.

Stage 2 — Staging Area

A temporary holding area. Think of it as a shopping cart — you choose which changes to include before checking out (committing).

git add main.cpp          # add one file
git add .                 # add all changes

Stage 3 — Local Repository

A permanent snapshot stored on your machine. The commit creates a unique ID (hash) and stores the snapshot with your message.

git commit -m "Add UART driver"

Stage 4 — Remote Repository

Your commits uploaded to GitHub — accessible from anywhere, backed up, and shareable.

git push origin main

Commits

A commit is a permanent snapshot of your project. Every commit gets a unique hash ID, stores your message, the exact changes, who made them, and when.

git commit -m "Add UART driver with baud rate config"

Every commit should represent one meaningful, logical change. Think of it as a save game checkpoint.

Branches

A branch is an alternate timeline for your project. The main project continues normally while you experiment freely on a branch without any risk to working code.

# Create and switch to a new branch
git switch -c feature/wifi

# Switch back to main
git switch main

# List all branches
git branch

Merge & Rebase

Merge

Combines a feature branch back into main. It creates a merge commit that preserves the full history of both branches.

git switch main
git merge feature/wifi

Rebase

An alternative that replays commits on top of main, creating a cleaner linear history — but it rewrites commit hashes.

git rebase main

.gitignore & Remote

.gitignore

Some files should never be committed — build artifacts, editor settings, secrets, and large auto-generated files. The .gitignore file tells Git which paths to always skip.

.pio/
build/
.vscode/settings.json
*.log
*.tmp
wifi_credentials.h
secrets.h

Remote

A remote is a named connection between your local repository and a GitHub repository. The default name is origin.

# Connect local repo to GitHub
git remote add origin https://github.com/user/project.git

# See all remotes
git remote -v

Push, Pull & Clone

git push origin main          # upload to GitHub
git pull origin main          # download from GitHub
git clone https://github.com/user/project.git  # copy repo

Stash, Restore, Reset & Revert

Stash — Temporary Drawer

Save unfinished work without committing it. Useful when you need to switch branches mid-task.

git stash          # save unfinished work
git stash pop      # restore it later

Restore — Undo File Changes

Discard changes to a specific file, restoring it to the last committed state.

git restore main.cpp

Reset — Dangerous Undo

Removes all uncommitted changes permanently. Use with extreme caution.

git reset --hard HEAD   # nuclear button — cannot be undone

Revert — Safe History Undo

Creates a new commit that reverses a previous commit — safe for shared repositories because it preserves history.

git revert a3f8c1d    # safely undo a specific commit

Tags & SSH Keys

Tags — Permanent Version Markers

Tags mark important milestones — firmware releases, stable versions, deployment points.

git tag -a v1.0.0 -m "First stable firmware release"
git push origin v1.0.0

SSH Keys — Secure GitHub Login

SSH keys provide secure, password-free authentication with GitHub. A key pair consists of a private key (stays on your machine) and a public key (uploaded to GitHub).

ssh-keygen -t ed25519      # generate key pair
ssh -T git@github.com      # test the connection

Commit Message Rules

Commit messages are communication. They tell your future self and your teammates what changed and why.

• Use the imperative mood: "Add UART driver" not "Added UART driver"
• Keep the subject line under 50 characters
• Each commit should represent one logical change
• Start with a capital letter, no period at the end

Commands Reference

Daily Commands

git status             # see what changed
git add .              # stage all changes
git commit -m "msg"    # commit with message
git push               # upload to GitHub
git pull               # download from GitHub

Branch Commands

git switch -c feature/wifi   # create + switch
git switch main              # switch to main
git branch                   # list branches
git merge feature/wifi       # merge into current

History Commands

git log --oneline      # compact history view
git diff               # see unstaged changes
git diff --staged      # see staged changes

Recovery Commands

git stash              # temporarily save work
git stash pop          # restore stashed work
git restore <file>     # undo file changes
git revert <commit>    # safely undo a commit

Embedded Workflow & Summary

Professional Workflow for Every Project

Mental Model Reference

Code proves you can program. Git history proves you can engineer.