Your First Hardware Repo in 10 Minutes

By the CADPreview Team · Series: Git for Hardware Engineers

"The worst time to discover you have no version history is when you need it."

You have a KiCad project on your machine. Maybe it is a folder called board_v3_FINAL. Maybe it is just my_project. Either way, right now it has no history, no backup, and no way to undo a decision you made two weeks ago.

This article fixes that. By the end you will have your design on GitHub, tracked, versioned, and accessible to your whole team.

No command line. No prior Git experience needed.

What You Need

• A free GitHub account
• GitHub Desktop installed on your machine
• A KiCad project folder

That is it.

Step 1: Open GitHub Desktop and Create a New Repository

Open GitHub Desktop. From the File menu, choose New Repository.

Fill in the form:

• Name — use something clear, like my-sensor-board
• Local Path — this is the parent folder containing your KiCad project folder. If your project lives at ~/Documents/my-sensor-board, set the path to ~/Documents and the name to my-sensor-board
• Description — optional, but useful
• Leave Initialize this repository with a README unchecked for now

Click Create Repository.

Important note for macOS users. At this point, the repository exists only on your local machine. It is not yet on GitHub and it is not yet public or private. You will make that choice in Step 4. For now, you are just setting up the folder structure.

Step 2: Add the KiCad .gitignore File

Before committing anything, you need to tell Git which files to ignore. KiCad generates several files that change constantly and have no value in version history, auto-saves, backup folders, and per-user preference files. Tracking these creates noise and causes unnecessary conflicts between engineers.

Create a file called .gitignore in the root of your project folder and paste in the following:

# KiCad auto-save and backup files
*-backups/
_autosave-*
*.bak
*.000
*.001
*.002
*.003
*.004
*.005
*.006
*.007
*.008
*.009

# Per-user project local settings (not shared between engineers)
*.kicad_prl

# Footprint cache (regenerated automatically)
fp-info-cache

# macOS folder metadata
.DS_Store

What this keeps tracked: your schematic (*.kicad_sch), your board layout (*.kicad_pcb), your project file (*.kicad_pro), any local symbol or footprint libraries (*.kicad_sym, *.kicad_mod), and your library tables (fp-lib-table, sym-lib-table). These are the files that actually define your design.

Save the .gitignore file. GitHub Desktop will pick it up automatically.

Step 3: Make Your First Commit

Switch to GitHub Desktop. You will see a list of changed files on the left side. These are all the files in your project folder that Git has noticed.

[Screenshot: GitHub Desktop showing changed files list]

At the bottom left, there are two fields:

• Summary — a short description of what this commit represents. For a first commit, write something like Initial commit, schematic and layout for rev A
• Description — optional, but useful for recording context

Click Commit to main.

[Screenshot: Commit fields filled in, button highlighted]

Your project now has a saved snapshot in its history. Nothing has left your machine yet.

Step 4: Publish to GitHub

Click the Publish repository button in the toolbar.

[Screenshot: Publish repository button]

A dialog appears. This is where you choose whether the repository is public or private.

• Public — anyone on the internet can view it
• Private — only you and people you invite can see it

For most hardware projects, choose Private. You can always make it public later.

Click Publish Repository.

[Screenshot: Publish dialog with Private selected]

Your design is now on GitHub. Go to github.com and you will see it there.

Step 5: The Commit Habit

Version control only works if you use it. The rule is simple: commit whenever you reach a meaningful checkpoint.

Three good moments to commit during a typical PCB project:

1. Schematic complete, ready for review. Message: Schematic complete, ready for peer review
2. Component placement done, before routing. Message: All components placed, starting routing
3. Before generating fab outputs. Message: Rev A layout finalised, fab outputs next

You do not need to commit every small change. You do need to commit often enough that you can get back to any meaningful state. Think of it as saving your work at the end of a focused session, with a note about what you did.

What You Can Do Now

Your project is version controlled. That means:

• Roll back any change. Right-click any commit in GitHub Desktop and you can restore the project to that state.
• Share the repo. Go to your repository on GitHub, click Settings, then Collaborators, and invite your firmware engineer or a colleague.
• See exactly what changed. GitHub Desktop shows you a diff for every commit, which files changed and what moved.

What Is Coming Next

This article covered the foundation: one engineer, one repository, linear history.

The next article covers commits in practice: when to commit, what to include, and how to write a message that actually means something to the person reading it six months from now.

After that: branching, what to do when two engineers are working on the same board at the same time, how to propose a change without overwriting someone else's work, and how to use pull requests as a lightweight design review process.

CADPreview is a web-based viewer for KiCad projects hosted on GitHub. Connect your repository once, share a link, and your whole team sees the current schematic, layout, and BOM in a browser, on any branch, at any release, without installing anything.

Try it at cadpreview.com