Home / Learn / Code for makers

Git for beginners: version control for your projects

New to this? Read from the top. Already know the basics? Jump to Going deeper for intermediate and advanced detail.

A Git history with a main branch and a feature branch that is merged back in
Beginner

Git keeps a complete history of your project. You can see exactly what changed and when, go back to any earlier version, and try ideas safely on a separate branch. It works for any text-based project: Python scripts, Arduino sketches, websites, even KiCad designs.

Setting up

Install Git from git-scm.com (it's already on most Macs and Linux systems), then tell it your name and email, which are recorded with each change:

git config --global user.name "Your Name"
git config --global user.email "you@example.com"

Your first repository

mkdir weather-station
cd weather-station
git init                      # start tracking this folder

# create or edit some files, then:
git status                    # what's changed?
git add main.py               # stage a file for the next snapshot
git commit -m "Read temperature sensor every minute"

A commit is a snapshot of your project with a message describing it. Commit little and often, with messages that say what changed and why.

Looking at history

git log --oneline             # list of commits
git diff                      # changes not yet staged
git show HEAD~1               # what the previous commit changed

Undoing things

  • git restore main.py throws away uncommitted changes to a file. Careful, there's no undo for this.
  • git restore --staged main.py unstages a file, keeping your changes.
  • git revert <commit> makes a new commit that reverses an old one. It's the safe way to undo shared history.

Branches

A branch is a separate line of work. Make one to try an idea without disturbing your working version:

git switch -c add-display     # create and move to a new branch
# ...edit and commit...
git switch main               # back to the main branch
git merge add-display         # bring the new work in

Backing up to GitHub

Create an empty repository on GitHub (or GitLab, or another host), then connect and upload:

git remote add origin https://github.com/your-name/weather-station.git
git push -u origin main

If Git named your first branch master, rename it first with git branch -M main. After that, git push uploads new commits, and git pull fetches changes made elsewhere.

Keep secrets out

Never commit passwords, API keys or Wi-Fi credentials. List files to ignore in a file called .gitignore:

secrets.py
.env
__pycache__/

If a secret is ever committed and pushed, treat it as leaked: change the password or revoke the key straight away, because it stays in the history even after you delete the file.

Intermediate and advanced

Going deeper

How Git stores your work

Each commit records a snapshot of the project, its parent commit(s), the author and the message, and is identified by a hash of all that content. A branch is simply a movable label pointing at a commit, and HEAD points at the branch you're on. This is why branches are cheap to create, and why changing an old commit changes every hash after it.

Merge or rebase?

  • Merging joins two lines of history with a merge commit. It records what really happened and never rewrites existing commits.
  • Rebasing replays your commits on top of another branch, giving a straight, tidy history. Because it rewrites commits, only rebase work that nobody else has based work on.

Resolving conflicts

If two branches change the same lines, Git stops and marks the conflict in the file between <<<<<<<, ======= and >>>>>>> lines. Edit the file to the version you want, remove the markers, then git add it and finish with git commit (or git rebase --continue).

Rescuing "lost" work

git reflog lists every position HEAD has recently been at, including commits that no branch points to any more after a reset or a bad rebase. Find the commit and create a branch at it: git branch rescue <hash>. Git keeps these unreachable commits for a while before cleaning them up, so act reasonably soon.

Useful habits

  • Use git add -p to review and stage changes piece by piece, so each commit does one thing.
  • Find which commit introduced a bug with git bisect, which binary-searches your history.
  • Tag releases, such as firmware versions, with git tag v1.2.0.
  • Large binary files (videos, big datasets) bloat repositories. Keep them out, or use Git LFS.
  • Pull requests on GitHub let you review changes, and run automated tests, before merging, even on solo projects.

Hardware projects

KiCad's schematic and board files are text, so Git can track them, though their diffs are hard to read. Commit at meaningful points such as "schematic reviewed" or "sent to fab v1", and tag the exact version you ordered, so you can always match a physical board to its design files.

Sources

The main references behind this guide. Numbers we worked out ourselves, such as the code outputs, come from running the code.