Git入門｜電子工作のバージョン管理の始め方

回路図、基板データ、Arduino のスケッチ、部品表、製造用のGerberや資料が増えてくると、電子工作は「作ること」より先に「どれが最新版か」を見失いがちです。
筆者のワークショップでも、この悩みがいちばん多く、まず3つの初期コミットを刻むだけで「いつでも戻れる」という安心感が生まれる場面を何度も見てきました。

この記事は、KiCad と Arduino を使う初心者に向けて、GitとGitHubの違い、コミット・ブランチ・リモートの意味を自分の言葉で説明できるところから、手元で git init から push まで再現する最短ルートをまとめたものです。

Gitは変更履歴を手元に残して戻せる分散型のバージョン管理システムで、GitHubはその履歴を共有する場です。
Atlassianが説明するバージョン管理の考え方を土台にします。
ファイル名に final や v1.2 を足して耐える運用から卒業して、「安全に試して、必要なら戻す」を当たり前にするところまで進めます。

関連記事Linux入門｜初心者向けのインストールと基本操作Linux入門。WSL・仮想環境・実機の選び方を比較し、Ubuntu 24.04 LTSの安全な導入手順と初期設定、基本コマンド10選、権限/sudo、トラブル対処まで1本で網羅。Windows利用者のWSL要件やバックアップ必須ポイントも整理します。

Gitとは何か｜電子工作で使う理由

バージョン管理の定義

Gitをひと言でいうと、ファイルの変更履歴を記録して、必要な時点に戻せる仕組みです。
もう少し具体的にいうと、「いつ・誰が・何を変えたか」を残しながら作業を進めるためのバージョン管理システムです。
Atlassianの説明でも、この追跡と復元がバージョン管理の中心だと整理されています。

電子工作では、この考え方がそのまま役に立ちます。
たとえばKiCadで回路図を編集して、部品の値を変え、配線を引き直し、ついでにArduinoのスケッチも触る、という流れは珍しくありません。
このとき、うまく動いていた時点の状態を残していないと、「LEDは点いていたのに、どこから壊れたのか分からない」「モータ制御を足したら別の機能まで崩れた」といった詰まり方をします。

筆者も以前は、紙の回路メモとPC内の v2_final_本当の最終 のような名前に頼っていました。
ところが、その運用では比較も復元も人力です。
ある日うまく動いていた配線案と、今の回路図の差がすぐ出せません。
Gitを使うようになってからは、変更の節目ごとに記録を残せるので、試作で寄り道しても「一つ前の安定版に戻る」「2案を見比べる」が当たり前になりました。
この安心感が、電子工作では想像以上に効きます。

ポイント: 電子工作のデータは回路図、基板、ファームウェア、部品表、製造データ、作業メモと増えていきます。
ファイル名で世代管理する方法は最初は回りますが、試作が進むほど破綻します。
Gitはその混乱を、履歴という形で整理してくれる道具です。

GitとGitHubの違い

初心者が最初につまずくのが、GitとGitHubは同じものではないという点です。
Gitは変更履歴を扱うツールそのものです。
一方のGitHubは、そのGitの履歴をネット上で共有し、共同作業やレビューを進めるためのプラットフォームです。
Gitは2005年にLinus Torvaldsが作られ、GitHubは2008年に始まったサービスなので、成り立ちから見ても別物です。

たとえば手元のノートPCで git init して履歴を残すだけなら、GitHubのアカウントは不要です。
逆にGitHubを使っていても、裏側で動いている履歴管理の本体はGitです。
この区別が曖昧なままだと、「GitHubにつながらないと履歴を見られない」と誤解しがちですが、実際はローカルだけでも十分に使えます。

共同制作まで視野に入れると、GitHubの役割が見えてきます。
たとえばKiCadの回路変更を共有したり、PlatformIOやESP-IDFのファームウェア更新をレビューしたりするとき、GitHub上で履歴や差分を確認できます。
少人数の開発では、シンプルなGitHub Flowが回しやすいとされるのもこのためです。
基本は main に安定版を置き、作業ごとに枝分かれしたブランチで変更して、確認後に取り込む流れです。
古い記事では既定ブランチ名が master になっていることがありますが、近年の一般的な表記は main です。

補足すると、Git本体は今も継続して更新されています。
Git公式サイトでは、2026-02-02公開の2.53.0や2025-11-17公開の2.52.0といったリリース履歴が確認できます。
ただ、入門で覚える clone、add、commit、branch、push といった基本操作の軸は変わっていません。
学び直しが毎年発生する種類の道具ではないので、最初に覚えた内容がそのまま長く残ります。

分散型の意味と利点

Gitが「分散型バージョン管理システム」と呼ばれるのは、履歴の本体を各自のPCが持てるからです。
中央サーバだけに履歴がある方式ではなく、手元の作業用PCにもコミット履歴が入ります。
だからネットにつながっていない状態でも、過去の変更を見返したり、新しいブランチを切ったりできます。
この性質は、電子工作の作業と相性がいいです。
作業机の横にオシロスコープやはんだごてを置いて、ネットが安定しない場所でノートPCを開くことは珍しくありません。
そういう場面でも、Gitならローカルに履歴があるので、回路図の前バージョンを確認しながら配線の見直しができます。
GitHubは共有や保管の面で便利ですが、日々の作業の土台はローカルだけでも成立します。

Git公式サイトのチュートリアルでも、まずは手元のリポジトリで履歴を積み上げる流れから始まります。
これは初心者にも都合がよく、最初からサーバ運用を意識しなくて済みます。
まず自分のPCで「変更を記録する」「戻す」「別案を枝分かれさせる」を覚え、それから必要に応じてGitHubにつなぐほうが理解が深まります。

電子工作では、試作Aと試作Bを並行したい場面がよくあります。
たとえばセンサのプルアップ値だけ変えた案、電源周りを組み替えた案、ファームウェアのデバッグログを増やした案を別々に試したいとき、ブランチを分けておけば履歴が混線しません。
紙メモや別名保存だと管理対象が散らばりますが、Gitなら「どの案で何を変えたか」が履歴の構造として残ります。

電子工作の悩みとGitの対応関係

電子工作でGitが効く理由は、悩みと機能の対応がはっきりしているからです。
まず多いのが「どれが最新版か分からない」という問題です。
回路図、基板、マイコン用コード、部品表、発注用のGerber、3Dプリント用のSTL、説明用のSVGがフォルダ内に増えると、ファイル名だけでは整理が追いつきません。
Gitなら最新だけでなく、どの変更を経て今の状態になったかまで追えます。
次に、「変更したら動かなくなったが、何を触ったのか思い出せない」という問題があります。
コミットごとに意味のある区切りを付けておけば、「電源LED追加」「I2Cプルアップ修正」「ケース穴位置調整」のように節目が残ります。
壊れた地点の特定が速くなり、原因調査が感覚頼みになりません。

KiCadとの相性も見逃せないポイントです。
KiCadのプロジェクトファイルはテキスト形式なので、Gitで差分を追えます。
もちろん、生のテキストdiffだけでは読み取りにくい箇所もありますが、「この部品が追加された」「ネット名が変わった」といった変更の痕跡を残せるだけでも、手作業の比較より前進です。
DevelopersIOのKiCadのファイルをgitで管理するとどのように見えるか確認してみたのような実例を見ると、回路変更の記録がどう残るか具体的にイメージできます。

さらに、個人制作でもチーム制作でも、プロジェクト全体を一つの単位で扱えるのが便利です。
たとえば Hardware に回路図と基板、Firmware にArduinoやESP-IDFのコード、Docs に組み立てメモ、Production に製造データを置く構成にすると、試作1号機から量産前の整理まで流れが見えます。
回路だけ、コードだけを別管理にするより、「この基板版にはこのファームが対応する」という関係が追いやすくなります。

関連記事Arduinoプログラミング基礎｜変数・関数・制御構文入門Lチカまでは動いたのに、サンプルコードを開くと急に意味がつながらなくなる——という初心者向けのガイドです。この記事ではまず setup() と loop() を軸に、変数・関数・if/for/while/switch を LED、ボタン、アナログ入力の動きと結びつけて整理します。

電子工作プロジェクトでGit管理すると何が楽になるか

回路変更の履歴追跡

電子工作でGit管理の恩恵をいちばん実感しやすいのは、回路図や基板データの変更履歴が一本の流れで見えることです。
たとえばKiCadでプルアップ抵抗を追加した、コネクタのピン順を入れ替えた、LEDの電流制限抵抗を差し替えた、といった修正をコミットごとに分けておくと、「いつからこの不具合が入ったのか」を追いかけやすくなります。
手元のフォルダに sensor_board_v3_fixed_final のような名前が並ぶ状態だと、変更点は推測するしかありませんが、Gitならコミットメッセージごとに理由を残せます。

KiCadのプロジェクトファイルはテキストなので、Gitで差分を持てるのも相性のよい点です。
配線の追加や削除、フットプリント差し替え、ネット名の変更が履歴に残るので、「部品をいつ差し替えたか」が見失われません。
テキスト差分だけでは読みにくい場面もあります。
DevelopersIOのKiCadのファイルをgitで管理するとどのように見えるか確認してみたDevelopersIOのKiCadのファイルをgitで管理するとどのように見えるか確認してみたを見ると、少なくとも変更箇所を追える形にはなると分かります。

筆者の経験でも、試作を進めるほど「1本だけ配線を足したつもり」が後から効いてきます。
センサー入力が不安定で、原因はファームウェアだと思って追っていたら、数日前にGNDの引き回しを変えていた、という流れは珍しくありません。
回路図と基板の変更を細かく刻んでおくと、勘で探す時間が減って、確認する順番がはっきりします。

ハード/ソフトの同期

電子工作では、ハードだけ、ソフトだけで変更が閉じることのほうが少ないです。
GPIOの接続先を変えたら、ファームウェア側のピン定義も変わります。
I2Cセンサーを追加したら、回路図だけでなく初期化コードやライブラリ設定、配線メモも更新が必要です。
Gitで管理していると、これらを同じコミットにまとめられるので、「この配線変更に対応するコードはどれか」が履歴からそのまま読めます。

たとえば hardware/ にKiCadの回路図と基板、firmware/ にArduinoスケッチやPlatformIOのプロジェクト、docs/ に配線メモや部品表を置いておきます。
1回の修正をひとまとまりで保存できます。
InventhubのBetter manage KiCAD projects using GitInventhubのBetter manage KiCAD projects using Gitでも、回路図・基板・Firmware・Docs・Productionのように分けて管理する構成が紹介されています。
電子工作ではこの分け方がそのまま効きます。
発注用データと実験中のコードが混ざりにくくなり、見返したときに迷いません。

この同期管理は、デバッグの場面で特に効きます。
たとえばセンサー値の読み取りが急に崩れたとき、回路図だけ戻しても直らないことがあります。
実際には、プルアップ抵抗の追加とあわせてサンプリング周期も変えていた、という組み合わせが原因だったりするんですよね。
同じコミットでハードとソフトが結びついていれば、「どちらを見ればいいか」ではなく「この変更セットを確認する」に発想を切り替えられます。

マイルストーンと復元

試作の節目をタグやリリースで固定できるのも、電子工作では実用性が高いところです。
たとえば「ブレッドボードで動作確認できた版」「基板発注直前版」「展示会デモ版」のように区切っておくと、その時点の回路図、基板データ、ファームウェア、説明資料をひとかたまりで残せます。
日付だけのフォルダ管理と違って、どの版が何の目的で固めたものかが明確です。

筆者も基板発注の前日に、最新の調整版よりひとつ前の挙動のほうが安定していたと気づいて冷や汗をかいたことがあります。
そのときは発注直前にタグを打っていた版へ戻し、そこを基準にGerberを書き出して難を逃れました。
履歴がなければ、どの回路図とどのファームウェアが組になっていたかを手作業で探すことになっていたはずです。
こういう場面では、「戻せる」こと自体が作業の保険になります。

過去版への復元は、単なる安心材料ではなく、デバッグの速度にも直結します。
いまの状態が不安定なら、前回の安定版へ戻して差分を見るだけで、調べる範囲を絞れます。
基板データを巻き戻し、同じコミットのファームウェアも戻す。
そこから1つずつ変更を載せ直していけば、どこで崩れたかを切り分けられます。
電子工作は変更点が複数箇所へまたがるので、この戻し方ができるだけで作業の見通しがまるで違ってきます。

CIとの親和性

Git管理は履歴を残すだけで終わらず、GitHub ActionsのようなCI（継続的インテグレーション）と組み合わせると、pushのたびに自動処理までつなげられます。
電子工作の文脈では、ファームウェアの自動ビルド、テスト実行、バイナリ成果物の保存が代表例です。
PlatformIOやESP-IDFのプロジェクトなら、ローカルで毎回同じビルド手順を手で回さなくても、リポジトリ側で一定の流れを持てます。

たとえば main に入る前のブランチで、コンパイルが通るか、設定ファイルが欠けていないか、生成された .bin を保存できるかを自動で確認する運用です。
組み込み向けのCI実践としては、InterruptのFirmware Testing with Renode and GitHub ActionsInterruptのFirmware Testing with Renode and GitHub Actionsのように、自動テストまで含めた流れもあります。
入門段階ではここまで一気に広げなくても、まずは「pushしたらビルドが通るか分かる」だけで価値があります）。

電子工作では、PCごとの差でビルド結果がぶれると切り分けが面倒です。
ローカルでは通るのに別の環境では失敗する、という状態を減らせるので、ハードの不具合と開発環境の不整合を混同しにくくなります。
さらに、展示用のデモ版や発注前の版に対応する成果物をCIで残しておけば、「あのとき書き込んだファームはどれだったか」という迷子も防げます。
履歴管理と自動化がつながると、回路・コード・成果物が同じ時間軸に並ぶようになります。

Firmware Testing with Renode and GitHub Actions

A community and blog for embedded software makers

interrupt.memfault.com

比較（手動ファイル名管理 / Gitローカル / Git + GitHub）

電子工作の現場でまず起きがちなのが、main_v2、main_fix2、main_fix2_final、main_fix2_final_2 のようにファイル名で版を表す運用です。
回路図、基板、ファームウェア、部品表、組み立てメモが1種類ならまだ回りますが、試作が2回、3回と進むと破綻します。
回路図だけ sensor_board_revB.kicad_sch になっていて、書き込み済みのArduinoスケッチは led_test_final.ino、発注に使ったGerberは日付入りZIP、説明資料はPDFの別名保存という具合に、同じ試作版に属するはずのファイルがばらけるからです。

この方式で特につらいのは、回路変更の履歴追跡がほぼ人間の記憶頼みになる点です。
たとえばプルアップ抵抗を追加したのが回路図のどの版だったのか、基板上でGND配線を太くしたのがその前か後か、さらにその変更に合わせてPlatformIO側でセンサー初期化順を直したのがどのタイミングかが、ファイル名だけではつながりません。
過去版への復元も、正しいZIPを探して展開し、関連するコードや資料を手で寄せ集める作業になります。

筆者も昔はfinal_最終_ほんとに最終.zipのような名前でしのいでいた時期があります。
あの運用は、その場を切り抜けるには便利でも、あとから見返すと「何を根拠にその版を採用したのか」が消えます。
Gitへ移してからは、変更理由をコミット単位で残せるので、巻き戻しもレビューも別の作業になりました。
探す時間より、直す時間に頭を使えるようになります。

3つの運用を並べると、差は次のように見えてきます。

項目	手動ファイル名管理	Gitローカル運用	Git + GitHub運用
最新版の判別	人手依存で混乱しやすい	履歴で追える	履歴と共有履歴で追える
復元容易性	ZIPや別名保存を探して手で戻す	コミット単位で戻せる	コミットやタグから戻せる
複数人作業	版の衝突が起きやすい	1台中心なら成立	ブランチを分けて並行作業しやすい
レビュー	差分比較がほぼ手作業	同一PC内で確認	Pull Requestで変更箇所を確認できる
電子工作との相性	回路・基板・コード・資料が分断されやすい	個人制作の試作管理に向く	少人数チームの試作と量産前整理に向く

表だけ見ると単純な比較ですが、電子工作では1ファイルだけ戻しても解決しない場面が多いので、この差がそのままデバッグ速度に出ます。
基板だけ旧版、ファームだけ新版という食い違いがあると、症状の切り分けそのものがぶれます。

Gitローカル運用の強み

個人制作なら、まずはGitをローカルだけで使う形でも元が取れます。共有機能よりもまずは過去版への復元と変更のまとまりを優先する運用で始めるのがおすすめです。

たとえば hardware/ にKiCadの回路図と基板、firmware/ にArduinoスケッチやESP-IDFプロジェクト、docs/ に配線メモや部品表を置いておくと、ファーム更新とハード変更を同じコミットで結びつけられます。
これにより同期不整合のリスクが減り、試作機を再現しやすくなります。

KiCadの保存ファイルをGitで追った例としては、classmethodの「『KiCadのファイルをgitで管理するとどのように見えるか確認してみた』」が参考になります。
テキストベースで差分を追えるファイルは、どのネット名や部品情報が変わったのかを後から読み返せます。
基板CADの差分はコードほど読みやすくはありませんが、少なくとも「いつ・どこを触ったか」が消えません。

ローカル運用でも、マイルストーン管理は十分に機能します。
たとえば「ブレッドボードでLED点滅まで確認」「ESP32でWi‑Fi接続確認」「初回基板発注前」といった節目にタグを付けておくと、その時点の回路図、基板データ、ファーム、資料が固定されます。
試作を進めると、動くものが常に最新版とは限りません。
むしろ一つ前の版のほうが安定していることがあり、そこへ戻れるかどうかで作業時間が変わります。

電子工作との相性という点では、差分の見方も押さえておきたいところです。

項目	KiCadテキストdiff	KiCad差分可視化ツール	PDF/SVG出力比較
導入の手軽さ	高い	中程度	中程度
読みやすさ	低〜中	高い	中〜高
細かな変更追跡	可能	可能	見た目中心
初心者向け	慣れが必要	比較的わかりやすい	見た目で追いやすい

回路変更の中身を厳密に追うならテキストdiff、配線や部品位置の変化を直感的に見たいなら可視化ツールやPDF/SVG比較、という使い分けになります。
ローカル運用だけでも、この組み合わせで「変更を残す」「見返す」「戻す」が回るようになります。

KiCadのファイルをgitで管理するとどのように見えるか確認してみた ｜ DevelopersIO

KiCadを使えるようになり、ソフト開発と同様に履歴も管理したくなりましたのでgitで管理できるか確認してみました。

dev.classmethod.jp

Git + GitHub運用の拡張性

GitHubまで広げると、ローカル運用で得られる履歴管理に、共有・レビュー・公開の軸が加わります。
2005年に作られたGitと、2008年に始まったGitHubの組み合わせが長く使われているのは、単にソースコードを置けるからではなく、変更の相談と合意形成まで同じ場所で進められるからです。
少人数の電子工作チームでは、ここが効きます。

たとえば1人がKiCadで電源回路を修正し、別の1人がESP32向けファームを直し、もう1人が組み立て手順書や部品表を更新する、という並行作業でも、ブランチを分けて進められます。
Pull Request を使えば、「この回路変更に合わせてGPIO定義も更新したか」「このファーム更新は基板Rev.B前提か」といった確認が、口頭ではなく変更差分にひも付いて残ります。
手動ファイル名管理だと、レビュー対象そのものが曖昧になりがちですが、ここでは何を変えたかが先に固定されます。

試作の節目を管理する運用も広がります。
GitHub Flowのような軽い流れは少人数の電子工作に合いやすく、Git Flowは release ブランチや hotfix を含むぶん管理が重くなります。
展示会デモ版、基板発注版、量産前確認版のように節目がはっきりしているなら、普段はシンプルなブランチ運用にして、必要な場面だけリリースブランチを切る形が収まりやすいです。

項目	GitHub Flow	Git Flow	リリースブランチ併用
分かりやすさ	高い	低め	中程度
初心者向け	向く	複雑	条件付きで可
小規模開発	向く	やや重い	向く場合あり
電子工作少人数開発	向く	過剰になりやすい	試作節目管理に有効
mainの安定性	PR運用次第	保ちやすい	保ちやすい

この段階になると、レビューだけでなく成果物の置き場としても意味が出ます。
たとえば「このタグのファームを書き込んだ展示機」「このリリースに対応するGerber一式」「この版の説明資料PDF」といった形で、誰が見ても同じ基準点を共有できます。
チームで1台の試作機を回すときも、どの版を焼いたかが履歴に乗るので、口頭の伝達ミスを減らせます。

なお、ベンチマーク結果は計測条件に依存します。
OpenBenchmarking の一例で「数分かかるケースが報告されている」程度に留め、日常的な操作感は環境やリポジトリ構成で大きく変わる点に注意してください（出典例: OpenBenchmarking の測定結果ページ）。
普段の電子工作での快適さは、履歴と運用ルールの整備や PR の往復時間がより大きく影響します。
個人なら最低限のGitローカル運用だけでも、手動の別名保存より得るものが多いです。
少人数で回路、基板、ファーム、資料を並行で触る段階に入ると、Git + GitHubのほうがレビューと共有履歴の面で一段上の運用になります。
なお、ベンチマーク結果は計測条件に依存します。
OpenBenchmarking の測定例では「数分かかるケースが報告されている」ことがありますが、測定環境やリポジトリ構成、日時によって結果は大きく変わるため、該当の測定ページや条件を確認したうえで参考値として扱ってください（出典例: OpenBenchmarking の該当結果ページ）。

作業フォルダの用意

初回は新しい練習用フォルダを作るより、いま手元にある電子工作フォルダをそのまま使うほうが流れをつかみやすいです。
たとえばMakerProjectというフォルダに、回路図、Arduino のスケッチ、README、画像メモが入っている状態から始めます。
Git の基本は、空の理屈を覚えるより、自分のファイルがどう見えるかを一度体験したほうが頭に残ります。

端末でMakerProjectへ移動したら、まずは次の順で進めます。

cd MakerProject
git init
git status

行ごとの意味はこうです。

cd MakerProject

MakerProjectフォルダに移動します。ここが今後の作業場所になります。

git init

このフォルダを Git 管理の対象として初期化します。
実行すると .git フォルダが作られます。
ここには履歴や設定が入っていて、プロジェクトの“心臓”にあたる部分です。
電子工作では KiCad の設計ファイル、ファーム、資料をあとからまとめて追いかけるので、この .git を誤って削除すると履歴ごと失います。

git status

今の状態を確認します。
まだ何もコミットしていないこと、どのファイルが未追跡かがここで見えます。
Git はまず status を見る癖をつけると迷子になりません。

ワークショップでも、この画面があるだけで安心感が出ます。
実際に git add . を実行したあと、受講者の方が git status を見て緑色になったファイルを眺めながら「ちゃんと入ったのが分かる」とほっとしていた場面がありました。
初心者ほど、Git を“見えない仕組み”としてではなく、“今どうなっているかを表示してくれる道具”として捉えたほうが前へ進めます。
可視化されるだけで、操作の意味が急に具体的になります。

Git の導線については、まずローカルリポジトリで履歴を積み上げる手順を体験するのが有効です。
主要な公式ドキュメントにはチュートリアルがあり、基本的な流れ（init→add→commit→log）はそこで丁寧に解説されています。
最初の一歩は init と status を試すことです。

最初のコミットを作る

次は、いまあるファイルを Git に登録して、最初の保存点を作ります。
最短ルートは git add と git commit の組み合わせで、README・firmware・hardware のような雛形を分けてコミットしておくと履歴が読みやすくなります。
次は、いまあるファイルを Git に登録して、最初の保存点を作ります。
最短ルートは git add と git commit の組み合わせです。

git add .
git status
git commit -m "Add initial project skeleton"

行ごとの意味を分けて見ていきます。

git add .

現在のフォルダ以下にある変更を、コミット対象としてステージします。
電子工作の初回なら、README、firmware、hardware、docs のような雛形フォルダをまとめて載せる場面に向いています。

git status

何がコミット対象に入ったかを確認します。git add . の直後にこれを挟むと、想定外のファイルまで入っていないか見分けられます。
筆者はこの確認を省きません。
とくに画像書き出しやビルド生成物が混ざると、最初の履歴が散らかるからです。

git commit -m "Add initial project skeleton"

ステージした内容を1つの履歴として保存します。ここで「この時点のプロジェクトはこうだった」と固定されます。

初心者向けには、最初の3コミットをあらかじめ決めておくと流れが止まりません。MakerProjectなら次の形が扱いやすいです。

1. 雛形構成の追加
2. 回路図初版と README の追加
3. ファームの点滅サンプル追加

たとえば 2 つ目と 3 つ目は、こう切れます。

git add hardware docs README.md
git commit -m "Add first schematic and README"

git add firmware
git commit -m "Add blink sample firmware"

Arduino の標準サンプルとしてBlinkが用意されていることはArduino公式チュートリアルでも確認できます。
LED の点滅サンプルのように、まず動く最小構成を1コミットにしておくと、その後に失敗しても「点滅していた地点」へ戻る基準ができます。
電子工作では、この基準点があるだけで切り分けの速さが変わります。

履歴を眺める

コミットを作ったら、すぐ git log まで触っておくと Git の価値がつながります。
保存しただけで終わるのではなく、「過去を読める」状態まで確認するわけです。

git log

git log --oneline

行ごとの意味は次の通りです。

git log

コミット履歴を詳細表示します。コミットID、作成者、日時、メッセージが順に並びます。

git log --oneline

履歴を1行ずつ短く表示します。最初のうちはこちらのほうが読みやすく、流れも追いやすいです。

もし先ほどの3コミットを作っていれば、表示はたとえば次のようになります。

a1b2c3d Add blink sample firmware
d4e5f6g Add first schematic and README
h7i8j9k Add initial project skeleton

この一覧が出た時点で、ローカル Git の基本体験はひととおり完了です。
作業フォルダを Git 化し、状態を見て、変更を載せて、保存し、履歴を読むところまでつながっています。
電子工作ではファイル種類が多いので、履歴が縦に並ぶだけで頭の整理が進みます。
回路図を直した日と、ファームを書き換えた日と、資料を整えた日が混ざらずに残るからです。

ここでも git status は引き続き役立ちます。
何か編集したあとに git status を見る、コミット前にも見る、という往復を続けると、「今どこまで確定していて、何が未保存か」を常に把握できます。
最初に覚えるコマンドを絞るなら、git init、git status、git add、git commit、git log の5つで十分です。

コミットメッセージ例

コミットメッセージは、未来の自分への見出しです。
短くても、変更の意味が伝わる文にします。
初心者のうちは、まず命令形で要約を書くと整います。
英語でも日本語でもかまいません。
大事なのは、何をしたコミットかが一目で分かることです。

英語なら次のような形が定番です。

Add initial project skeleton
Add first schematic and README
Add blink sample firmware
Fix pin assignment for LED test
Update BOM for prototype A

日本語でも同じ考え方で書けます。

雛形構成を追加
回路図初版とREADMEを追加
点滅サンプルのファームを追加
要約行と本文を分ける書き方の例を示します。コミットメッセージで本文を使うと、変更理由や注意点を補足できます。
試作A向けに部品表を更新

要約行と本文を分ける書き方の実例を示します。
変更理由まで残したいときに使うと、あとで履歴を読み返したときに意図が伝わりやすくなります。
少し慣れてきたら、要約行と本文を分ける書き方も使えます。
変更理由まで残したいときに便利です。

Add blink sample firmware

Use the built-in LED example as the first known-good state.
This commit is the baseline before sensor integration.

回路図初版を追加

電源部とマイコン周辺の最小構成を先に確定。
センサー追加前の基準点として残す。

電子工作の履歴では、「何を変えたか」だけでなく「どの段階の基準点か」が分かると読み返しやすくなります。
たとえば点滅サンプルのコミットは、単なる LED テストではなく、「マイコン書き込み系は通っていた」という証拠になります。
回路図初版のコミットは、「この時点では電源と主要配線がこうだった」という比較軸になります。
メッセージにその文脈が少し入るだけで、あとから履歴をたどる手間が減ります。

なお、よくある失敗は update や fix だけで終わらせることです。
これでは何を更新し、何を直したのか読めません。Update README for wiring notes や Fix LED pin definition のように対象を入れると、履歴の価値が一段上がります。
電子工作のプロジェクトはコードだけで閉じないので、README、回路図、部品表、製造データなど、対象名をメッセージに入れるだけでも見通しがよくなります。

ハンズオン演習：電子工作サンプルで3コミット

サンプル構成の取得/作成

回路図とファームウェアと資料が同居する、ごく小さな電子工作プロジェクトです。
空のKiCadプロジェクト、標準サンプルのArduinoのBlink、それを説明する README の3点だけです。
部品も機能も最小限で、Git の「変更を刻んで残す」感覚がつかみやすく、履歴の読み方まで一気につながります。

フォルダ構成は、たとえば次のようにすると見通しが立ちます。

MyFirstGitElectronics/
├── Hardware/
│   └── KiCad/
│       └── MyFirstGitElectronics.kicad_pcb
├── Firmware/
│   └── Arduino/
│   │   └── Blink/  （参考: Arduino IDE の Examples → 01.Basics → Blink のスタブを置く想定。ファイル名や配置は IDE バージョンで変わる場合があります）
    └── README.md

Firmware/Arduino/ には Blink のサンプルを置く想定です。
IDE の Examples メニューから開ける標準サンプルを参考にしてください。
ファイル名やフォルダ構成は IDE のバージョンや設定で変わることがあります。
Blinkサンプルは Arduino IDE の Examples で提供される基本サンプルです。
IDE のバージョンによってファイルの配置や名前が変わることがあるため、IDE 内の Examples メニューから開くのが確実です。

README は長文である必要はありません。たとえば次の程度で構いません。

Blinkは Arduino IDE の Examples メニューに含まれる基本サンプルです。IDE のバージョンによって配置やファイル名が変わることがあるため、IDE 内の Examples から開くのが確実です。

Git練習用の電子工作サンプルです。

- Hardware/KiCad: KiCadプロジェクト
- Firmware/Arduino: Blinkスケッチ
- Docs: メモと説明

この段階でフォルダとファイルを作ったら、作業フォルダで git status を見ると、新規ファイルが並びます。
前のセクションで触れた基本操作をそのまま使って、まずは土台だけを1つの状態として残します。
ここが演習の出発点です。

3つの変更を順にコミット

演習では、変更を3回に分けてコミットします。
狙いは「まとめて保存する」のではなく、「作業の意味ごとに履歴を分ける」感覚を身につけることです。
順番は、ファイル追加、回路図の小変更、ファームウェアの小変更です。
この並びにすると、資料・回路・コードの3種類が Git で同じように追えることが見えてきます。

1つ目の変更は、サンプル構成そのものの追加です。
まだ回路図が空でも、Hardware、Firmware、Docs が並んでいれば立派な初期状態です。
たとえば README を作り、Blinkのスケッチを置き、KiCadプロジェクトの空ファイルを保存した状態でコミットします。

git add .
git commit -m "Add sample electronics project skeleton"
git log --oneline

ここで git log --oneline を見ると、1行だけ履歴が出ます。
まだ短い履歴ですが、「この時点でサンプル一式がそろった」と言える基準点ができました。

2つ目の変更は、回路図に抵抗を1本追加する作業です。
たとえば LED と直列になる抵抗を回路図に足す、といった変更で十分です。
電子工作を始めたばかりの方は、こういう小さな修正を「わざわざコミットするほどではない」と感じがちですが、実際にはこの粒度がいちばん効きます。
筆者はワークショップでKiCadの差分を受講者と一緒に見ることがありますが、抵抗1本の追加はテキスト差分でも意外なほど輪郭がはっきり出ます。
部品が増え、参照名が増え、接続情報が変わるので、「何を足したのか」が履歴から読み取れます。
この感覚は一度味わうと気持ちがよく、Git を回路図にも使いたくなります。
基板レイアウトの変更になると座標や図形の変化が増えるため、そこは後で視覚的な Diff のほうが追いやすい場面も出てきます。
まずは回路図で、差分が文字として見える手応えをつかむのが近道です。

変更したら、2つ目のコミットを作ります。

git add .
git commit -m "Add resistor to schematic"
git log --oneline

ここで履歴は2行になります。
1行目が抵抗追加、2行目が雛形追加、という縦の並びになれば成功です。
重要なのは、回路変更が README 追加やファーム追加と混ざっていないことです。

3つ目の変更は、Blinkの delay() の値を変える作業です。
Arduino公式のBlinkは delay(1000) を使った1秒ごとの点滅ですから、その値をたとえば短くして、点滅テンポの違いが出る状態にします。
ここで使うスケッチは次のような形になります。

void setup() {
  pinMode(LED_BUILTIN, OUTPUT);
}

void loop() {
  digitalWrite(LED_BUILTIN, HIGH);
  delay(500);
  digitalWrite(LED_BUILTIN, LOW);
  delay(500);
}

変更点は小さくても、コミットは独立させておきましょう。 変更点は小さいですが、コミットは独立させます。

git add .
git commit -m "Change Blink delay value"  # 点滅間隔を500msに変更するコミットを作ります
git log --oneline

3コミットに分けると、履歴の見え方が一気に整います。
もし1回でまとめて保存すると、「README を足した」「抵抗を追加した」「点滅間隔を変えた」が同じ箱に入ってしまいます。
これだとあとで読み返したときに、どの変更が回路由来で、どの変更がコード由来かを頭の中で分解しなければなりません。
コミットを分けておくと、その分解を Git が代わりにやってくれます。

履歴の読み方チェック

3つのコミットができたら、今度は「保存できたか」ではなく「履歴を読めるか」を確認します。
ここまで来ると、Git は単なるバックアップではなく、作業の時系列を説明する道具に変わります。

まず git log --oneline を見て、3つの変更が上から新しい順に並んでいるかを確かめます。表示例は次のようになります。

c3d4e5f Change Blink delay value
b2c3d4e Add resistor to schematic
a1b2c3d Add sample electronics project skeleton

この3行を読んで、頭の中で作業の流れを復元できれば合格です。
最初に土台を置き、その次に回路を1か所直し、そのあとでファームのテンポを変えた、という順番が見えてきます。
電子工作では、回路とコードが影響し合う場面が多いので、履歴の順序が読めるだけで原因の切り分けがしやすくなります。

コミットは「その時点の変更を、意味のまとまりとして残した記録」です。ブランチは「別の作業線を分けるための枝」です。履歴は「コミットが時系列に並んだ記録」で、何をどう変えて今の状態に来たのかをたどる道筋です。

初心者の方がここでつまずくのは、「履歴」と「バックアップ」の違いです。
バックアップは過去の保存が目的ですが、履歴は過去の意味が読めることに価値があります。
今回の3コミットはまさにその練習になっています。
単に古いファイルを持っているだけではなく、「この時点では抵抗がなかった」「この時点で点滅間隔を変えた」と説明できるからです。

もし余裕があれば、git show で直近コミットの差分を眺めると、コミットと差分の関係がさらに結びつきます。
特にKiCadの回路図で抵抗1本を追加したコミットは、部品追加の跡が素直に現れるので、Git が電子工作に向いている感触をつかみやすい場面です。
この演習の到達点は、コマンドを暗記することではありません。
自分の言葉で「コミットは変更の記録、ブランチは作業線、履歴はその並び」と説明できるところまで到達すれば、次のセクションでGitHubやブランチ運用に進んでも迷いにくくなります。

GitHubにつないで共有する手順

リモートリポジトリの作成

ここからは、手元の履歴をGitHubに置いて、ほかの人と同じ履歴を見ながら進める段階です。
ローカルのGitは「自分のPCの中で履歴を残す仕組み」、GitHubは「その履歴を共有する置き場」と考えると整理できます。
電子工作では、回路図、マイコンのスケッチ、部品表、製造用データが別々のファイルとして増えていくので、共有先が1か所にまとまっているだけでも作業の見通しが変わります。

まずGitHub上で空のリポジトリを作ります。
すでにローカル側で README.md を作っている前提なら、GitHubの作成画面では README の自動作成は外しておくのが無難です。
ここで両方に最初のファイルがあると、最初の push の時点で履歴を合わせる話が混ざり、初心者の方がつまずきやすくなります。
空の箱を先に作り、そこへローカルの履歴を送る流れにすると、何が起きているかを追いやすくなります。

リポジトリを作成したら、ローカルのプロジェクトフォルダで次のコマンドを実行します。origin は「このリポジトリの代表的な送り先につける名前」です。

git remote add origin
git branch -M main
git push -u origin main

1行目の git remote add origin ... は、今いるローカルリポジトリにGitHubのURLを登録する操作です。
2行目の git branch -M main は、現在のブランチ名を main にそろえる操作です。
3行目の git push -u origin main で、ローカルの main をGitHubの origin に送ります。-u を付けると、次回以降は git push や git pull だけで送り先と取り込み先を省略できる状態になります。

コマンドの意味が頭の中でつながっていれば、暗記に頼らず進められます。
筆者はワークショップでも、ここを「URLを登録する」「枝の名前をそろえる」「履歴を送る」の3つに分けて説明しています。
1つの長い呪文として覚えるより、作業の意味ごとに切って理解したほうが、あとで別のリポジトリを作るときにも迷いません。

もし git remote -v を実行すると、登録済みの origin が表示されます。
これは「どこにつながっているか」を確認するためのコマンドです。
GitHubに push できないとき、URLの打ち間違いが原因になっていることがあるので、送り先の見取り図として覚えておくと役立ちます。

remote/push/pullの基本

リモート運用で最初に押さえたい言葉は3つです。remote は離れた場所にあるリポジトリ、push は自分の変更を送る操作、pull は相手側にある新しい変更を自分の手元へ取り込む操作です。
ローカルだけで作業していたときは、自分の履歴だけを見ていれば足りましたが、共有が始まると「送る」と「取る」の往復が発生します。

典型的な流れは単純です。
自分のPCで編集してコミットしたら git push で送る。
ほかの人が更新した内容を取り込みたいときは git pull を実行する。
この2つを繰り返します。
たとえば、回路図を修正してコミットしたあとに送るなら次の形です。

git add .
git commit -m "Fix LED net label"
git push

別のPCや別のメンバーが README.md や配線メモを更新していたら、手元に取り込むときはこうなります。

git pull

ここで初心者の方が身構えやすいのが、git pull のあとに競合が出た場面です。
競合は「壊れた」のではなく、同じ場所に別々の変更が入ったので、人間に判断を渡された状態です。
慌てなくて大丈夫です。
まずやることは、差分を読むことです。
どちらの変更が正しいかではなく、どちらを残すと今の設計意図に合うかを見ます。
たとえばKiCadのネット名を2人が別々に直していたなら、回路図の意図に合う表記を残します。
Arduinoの Blink スケッチで delay(500) と delay(1000) がぶつかったなら、今回の動作確認に使うテンポはどちらか、という観点で選びます。

筆者の経験では、競合そのものより「何を比べればいいか分からない」ことのほうが詰まりどころです。
だからこそ、変更を小さなコミットに分けておく意味が出てきます。
回路変更と文章修正が1つに混ざっていると、競合時に読む範囲まで広がります。
逆に、コミットが分かれていれば、どの意図の変更かを追いやすくなります。

共有を始めると、GitHubは単なる保管場所ではなくなります。
履歴を見れば、誰がどの順番で触ったかが分かるので、ローカル運用より「いまの最新版」を判断しやすくなります。
ファイル名の末尾に final や final2 を足していた頃の混乱から抜け出せるのは、この履歴の一本化があるからです。

補足すると、Codespaces や類似のクラウド開発環境ではストレージに有償の料金が発生する場合があります。
Pricing Calculator によるサンプル表示では小容量あたりの目安が示されていますが、実際の料金はプラン・地域・利用形態で変動します。
常時利用を前提にコスト試算する際は、自分の利用条件で最新の料金を確認してください（執筆時点のサンプル表示を参照する場合は明示すること）。

Pull Requestでの共有とレビュー

少人数でもGitHub運用の価値が出るのが、Pull Request です。
これは「この変更を取り込んでよいか」を見てもらうための窓口で、差分、説明、議論、レビュー履歴を1か所にまとめる役割があります。
GitHub Flowが初心者にも入りやすいと言われるのは、この Pull Request を中心に流れが作れるからです。
複雑なブランチモデルを持ち込まなくても、試作段階の電子工作なら十分回せます。
補足すると、Codespaces や類似のクラウド開発環境ではストレージに有償の料金が発生する場合があります。
Pricing Calculator のサンプル表示は目安を示すもので、実際の料金はプラン・地域・利用形態で変動するため、コスト試算を行う際は最新の公式料金ページで自分の利用条件に即した確認を行ってください（執筆時点の例を参照する場合は出典を明示してください）。
最小限の流れを図にすると、次の形です。

main
  │
  ├─ feature/fix-led-label で作業
  │        ↓
  │     commit
  │        ↓
  │      push
  │        ↓
  └─ Pull Request 作成
           ↓
      レビュー・議論・CI
           ↓
        main にマージ

ポイントは、main を直接書き換えず、作業用ブランチで変更をまとめてから Pull Request を作ることです。
たとえば feature/add-sensor-header や fix/power-net-name のような名前にしておくと、何の修正かが一覧で見分けやすくなります。
Pull Request には「何を変えたか」「なぜ変えたか」を短く書き、必要なら回路図のスクリーンショットや生成物の比較画像を添えます。
コードだけでなく、基板や配線の意図まで説明できるのが電子工作では効きます。

Pull Request の役割は3つあります。
1つ目はレビューです。
変更箇所を他の人が読めるので、見落としを減らせます。
2つ目は議論です。
「このネット名のほうが後工程で分かりやすい」「このピン番号はシルクと合わせたほうがよい」といった話を、差分の横でできます。
3つ目はCI のトリガです。
GitHub Actionsと組み合わせると、Pull Request 作成時にビルドや静的チェックを自動で回せます。
ファームウェアならコンパイル確認、資料生成があるなら生成ジョブの起動、といった具合です。
MemfaultのFirmware Testing with Renode and GitHub Actionsのように、組み込みでも自動テストの流れはすでに一般的です。

筆者が少人数の試作チームで main 保護と Pull Request 必須を入れたとき、レビューコメントでコネクタの配線入れ違いに気づけたことがありました。
実装前に止められたので、基板を起こしてからの手戻りを避けられました。
電子工作は、1本の配線ミスが基板再発注やデバッグ時間の増加につながるので、差分の段階で誰かの目が入る意味は大きいです。

最初のうちは、Pull Request を難しく考えなくて構いません。
作業ブランチを切る、コミットする、push する、Pull Request を開く、コメントを見て直す、マージする。
この一連の流れを1回通すだけで、「ローカルで保存する」から「チームで変更を扱う」へ視点が切り替わります。
ここが見えてくると、GitHubはアップロード先ではなく、変更を共有して育てる場所として使えるようになります。

{{product:3}}

関連記事Linuxコマンド 基本20選｜初心者が覚える操作Linuxコマンドは、ターミナルに文字で命令を打ち込んでOSを動かすための基本操作ですが、最初から数を追うより、まずは安全に覚えるべき20個に絞ったほうが手が止まりません。

KiCad・ファームウェア・生成物のおすすめディレクトリ構成

推奨ディレクトリツリー

電子工作のリポジトリは、回路図、基板、マイコンのコード、発注用データ、説明資料が同時に増えていきます。
ここがポイントです。
最初に置き場所のルールを決めておくと、「この .ino はどの基板向けか」「この Gerber は試作1号か2号か」が履歴と一緒に追える形になります。
筆者は、少人数の試作でも個人制作でも、次のような分け方にしておくことが多いです。

project-root/
├─ Hardware/
│  └─ MainBoard/
│     ├─ kicad/
│     │  ├─ MainBoard.kicad_pro
│     │  ├─ MainBoard.kicad_sch
│     │  ├─ MainBoard.kicad_pcb
│     │  └─ sym-lib-table
│     ├─ libraries/
│     └─ outputs/
├─ Firmware/
│  ├─ arduino/
│  │  └─ main-controller/
│  │     ├─ src/
│  │     ├─ lib/
│  │     └─ platformio.ini
│  └─ esp32/
│     └─ sensor-node/
│        ├─ src/
│        ├─ include/
│        └─ platformio.ini
├─ Docs/
│  ├─ README.md
│  ├─ wiring-notes.md
│  ├─ bom/
│  └─ images/
├─ Production/
│  ├─ revA/
│  │  ├─ gerber/
│  │  ├─ drill/
│  │  └─ assembly/
│  └─ revB/
├─ CAD/
│  ├─ enclosure/
│  ├─ step/
│  └─ stl/
└─ .gitignore

この形の狙いは、手で編集するものの置き場と、工程ごとに出てくる成果物の置き場を分けることです。Hardware/ にはKiCadの元データ、Firmware/ にはArduinoやESP32向けのコード、Docs/ には配線メモや部品表、Production/ には製造へ回すデータ、CAD/ にはケースや治具の 3D データを置きます。
ジャンルごとに分けるだけですが、探し物の時間が減ります。

ファームウェアは、さらにボードや役割ごとに分けると収まりがよくなります。
たとえばArduino IDE 同梱のBlinkのような小さなスケッチから始めたプロジェクトでも、センサー用、表示用、通信用と役割が増えると 1 フォルダに全部入れる運用はすぐ苦しくなります。
ESP32もPlatformIOやESP-IDFを使い始めると生成ファイルが増えるので、最初から src/ や include/ を含む標準的な形に寄せておくと後で詰まりません。

生成物とソースの分離

Git で管理するうえで混乱の元になりやすいのが、ソースと生成物が同じ場所に混ざることです。
ソースは MainBoard.kicad_pcb や .kicad_sch、.ino、.cpp、部品表の元原稿のように、人が編集するファイルです。
生成物は、コンパイル後の *.hex や *.bin、Gerber 出力、PDF、SVG、スクリーンショットなど、ソースから作られるものです。

たとえば基板設計では、KiCadの .kicad_pcb と .kicad_sch が主役で、Gerber はその時点の出力結果です。
Gerber 自体は製造に直結するので軽視できませんが、毎回ルート直下にばらまくと、差分一覧が出力ファイルで埋まります。
そこで Hardware/.../outputs/ のような作業用出力先と、発注に使う確定版を置く Production/ を分けておくと、途中の試し出力と正式な製造データを区別できます。

筆者は Production/ に「発注に使った Gerber 一式」をタグと一緒に残す運用にしてから、安心感が一段増しました。
試作が何回か進むと、「この基板屋へ送った ZIP は revA のどの時点だったか」を口頭では思い出せなくなります。v1.0-proto-order のようなタグと、その時点の Production/revA/gerber/ が残っていれば、誰がいつ何を出したかを後から追えます。
再発注や不具合調査の場面で、この一致が取れていることが効きます。

ファームウェアでも考え方は同じです。src/ や lib/ は Git に入れ、build/ や .pio/ のようなビルド生成物は追いかけない、という線引きを徹底すると履歴が素直になります。
コードを 1 行直しただけなのに、生成バイナリまで毎回更新される状態では、レビューで読むべき差分が埋もれます。

.gitignoreの考え方

.gitignore は「いらないファイルを隠す魔法」ではなく、Git に入れるものと入れないものの境界線を明文化するファイルです。
電子工作では、ファームウェアのビルド結果、KiCad の自動生成やバックアップ系、手元だけで使う一時ファイルを外すのが基本になります。

最小限の例を挙げると、次のような内容から始められます。

# Firmware build artifacts
Firmware/**/build/
Firmware/**/.pio/
Firmware/**/*.hex
Firmware/**/*.bin
Firmware/**/*.elf

# KiCad backups / autosave
**/*-backups/
**/*.kicad_prl
**/*.tmp
**/*.bak
**/*.bck

# OS / editor junk
.DS_Store
Thumbs.db
.vscode/

# Temporary outputs
**/outputs/tmp/

考え方としては、再生成できるものは ignore し、手で作った確定成果物は置き場所を決めて残す、です。
たとえば Gerber 一式は普段の出力先では ignore しても構いませんが、発注に使うものは Production/ に固めてコミットする、という分け方が実務では扱いやすいです。
こうしておくと「毎回の試し出力」は履歴を汚さず、「実際に出した製造データ」はタグ付きで残せます。

3D ケースの *.stl、完成写真、測定ログ、オシロの保存波形のように、サイズが膨らみやすいファイルにも注目したいところです。
Git 本体で持てなくはありませんが、履歴が太って扱いづらくなります。
こういう大きなバイナリはGit LFSの対象にするか、少なくともリポジトリ内で置き場を分ける、という発想があると破綻しにくくなります。
Gitの基本はGit公式サイトの説明が出発点として分かりやすく、運用ルールを決める段階でも役立ちます。

KiCad運用のコツ

KiCadはテキストベースのファイルを使うので、Git と相性があります。
配線の追加、部品の追加、ネット名の変更といった差分は、テキスト比較でも追える場面があります。
classmethodのKiCadのファイルをgitで管理するとどのように見えるか確認してみたのような実例を見ると、回路図や基板データが Git に乗る感覚をつかみやすくなります。

ただし、テキストとして差分が取れることと、人間が読んで理解しやすいことは別です。
部品追加やネット変更はテキスト差分でも追えますが、レイアウト変更では座標やセグメントの差分が大量に出て把握しにくくなる点に注意してください。

そこで筆者は、Git の差分に加えて PDF や SVG の出力を併用します。
回路図なら PDF、基板の見た目比較なら SVG や画像を添えると、レビュー側が一気に読みやすくなります。
必要に応じてKiCad Diff Visualizerのような専用の可視化手段を使うと、どこが変わったかを見た目で追えます。
W3C が管理するSVGはベクター形式なので、回路図や基板の比較画像にも向いています。

Gerber 出力時の確認も、見た目の比較が効く代表例です。
GerberはUcamcoが仕様を管理する製造データで、銅箔、シルク、ソルダーマスク、外形、ドリルなどをレイヤごとに分けて扱います。
単位や原点の扱いを取り違えると製造工程で困るので、Git に入れるかどうか以前に、出したものをビューアで確認した形跡が残る運用にしておくと後工程で助かります。
Git の履歴は「何が変わったか」を残し、PDF や SVG、Gerber ビューア確認は「見た目がどう変わったか」を補います。
この二段構えが、KiCad運用では実際に効きます。

ブランチ運用の基本｜1人開発と少人数開発でどう変えるか

電子工作の Git 運用は、最初からGit Flowのような多段ブランチ構成に寄せるより、main と短命の feature ブランチだけで回したほうが続きます。
ここが。
回路図、基板、ファームウェア、発注用データは互いに影響し合うので、長く生きる開発ブランチを増やすと「どれが今の正本か」が逆に見えづらくなります。
小さな変更を 1 本の枝で閉じて、終わったら main に戻す。
この単純さが、電子工作の試作には合っています。

main を常に動く状態に寄せる意識も効きます。
たとえばKiCadで USB コネクタのフットプリントを直す変更と、ArduinoやESP32のファームウェア初期化コード修正を同じ枝で長く抱えると、あとで「どの時点なら基板だけ発注できたか」が見えません。
feature を短期間で閉じる運用なら、「USB コネクタの配線修正まで入った main」「LED 点滅確認まで通った main」のように節目が残ります。
戻る場所が明確なので、試作の判断も早くなります。

GitHub Flowの簡易版

初心者向けに勧めやすい最小構成は、main + 1タスク1ブランチです。
いわゆるGitHub Flowの簡易版で、作業するときだけ feature/xxx を切り、終わったら Pull Request を出して main に取り込む形です。
レビュー相手がいなくても、この形には意味があります。
ブランチ名だけで作業の意図が残り、差分のまとまりも崩れません。

たとえば feature/pcb-usb-c、feature/fw-blink-fix、feature/bom-cleanup のように、対象をそのままブランチ名に入れると履歴を追うときに迷いません。
1 本の feature に「USB コネクタ変更」「電源 LED 追加」「部品表整理」を全部詰め込むと、途中で仕様がぶれたときに差分の切り分けが苦しくなります。
短命ブランチの利点は、失敗しても枝ごと捨てられることと、レビュー側が変更の文脈を一度に理解できることです。

筆者の経験でも、feature/pcb-usb-c で始めた小変更が、コネクタ周辺の電源保護やシルク修正まで広がりかけたことがありました。
そのまま手元で抱え続けると、当初の目的だった「USB Type-C 化」の話と、派生した「保護回路の見直し」の話が混ざります。
そこで早めに Pull Request を開いて、未完成の段階で議論を見える場所に出したところ、どこまでを今回入れるかが整理され、仕様の寄り道を防げました。
少し早い段階で PR を作るのは、完成宣言ではなく、論点を固定する手段でもあります。

リリースブランチとタグ

小規模な電子工作では、普段の運用に長生きする release ブランチを持ち込まなくても回る場面が多いです。
その代わり、節目にタグを付ける発想が役立ちます。
たとえば「試作v1.0発注版」「展示会デモ版」「ケース干渉修正前」のように、あとで意味が分かる名前をタグにしておくと、その時点の回路図、Gerber、ファームウェアをひとかたまりで指せます。
main に残った履歴の中から、製造に使った瞬間を迷わず引けるわけです。

タグだけで足りないのは、「今の開発を進めつつ、安定版にだけ小修正を入れたい」場面です。
たとえば発注済みの基板に対してシルク誤記だけ直したい、展示機のファームだけ別管理したい、というケースでは release/x.y を短期間だけ切る価値があります。
この release ブランチは、開発の本流を分岐させるためではなく、安定版の仕上げを閉じ込めるための箱と考えると運用が軽くなります。
修正が終わったら main に戻し、タグを打って役目を終える形です。

AtlassianのGitflow workflowが説明するような release ブランチ運用は、製品版と開発版を明確に分けたい場面では筋が通っています。
ただ、電子工作の少人数開発でそこまで枝を常設すると、保守コストのほうが先に目立ちます。
日常は main と feature、節目はタグ、必要なときだけ短期の release/x.y。
この順番で考えると、ルールが増えすぎません。

1人と少人数での違い

1人開発でも、ローカル作業だけだから main 直コミットでよいとは限りません。
むしろ筆者は、1人でも feature を切る癖があると後で助かる場面が多いと感じています。
理由は単純で、試作中は「ちょっと触る」が連鎖しやすいからです。
USB 電源まわりを直し始めたつもりが、ついでに LED 配置やシルク名まで触ることは珍しくありません。
そういうとき、main を汚さずに枝の中で広がりを受け止められると、採用する変更と保留にする変更を分けやすくなります。

少人数開発では、その feature ブランチに Pull Request と CI を足すだけで、運用品質が一段上がります。
ここでいう CI は大げさな仕組みでなくても構いません。
ファームウェアがビルドできる、主要ファイルが欠けていない、生成物の置き場が崩れていない、といった確認だけでも意味があります。
レビューも「設計を全面査読する」ではなく、「この変更で USB D+ と D- の配線意図は合っているか」「このコミットに Gerber を含めるべきか」といった狭い観点で回すほうが現実的です。
PR があるだけで、口頭で流れがちな判断が履歴に残ります。

1人開発ではブランチが思考の整理道具になり、少人数開発では PR が合意形成の場所になります。
どちらも目指す先は同じで、main をいつでも取り出せる基準点に保つことです。
作業を feature で短く閉じると、試作を巻き戻す、発注時点を切り出す、レビュー対象を限定する、といった場面で迷いが減ります。
電子工作は変更の影響範囲が見えにくいので、運用は凝るより、追えることを優先したほうが崩れません。

よくあるトラブルと回避策

.gitを守る

初心者がいちばん痛い形でつまずくのは、プロジェクト整理のつもりで .git フォルダまで消してしまうことです。
ここにはコミット履歴、ブランチ、タグといった Git の中身が入っていて、消えた瞬間に「いつ、何を、どう戻せるか」という道しるべが消えます。
KiCad の回路図や Arduino のスケッチ本体が残っていても、それは単なる現在のファイル一式に戻るだけで、履歴管理としての Git ではなくなります。

この事故は、エクスプローラーや Finder で「不要そうな隠しフォルダを掃除した」ときに起きがちです。
筆者はワークショップでも、.git をキャッシュや一時ファイルの類いだと思って消してしまった例を何度も見てきました。
誤操作を減らすには、まずプロジェクトの丸ごとコピーを別の場所に置くより、GitHub などのリモートに push しておくほうが意味があります。
ローカルのディスク故障や削除ミスが起きても、履歴の複製が外に残るからです。
加えて、普段触る作業フォルダと、OS やクラウド同期ソフトが自動整理する領域を近づけすぎないほうが安全です。

既定ブランチ名の混乱も、初期設定の段階で一度は出会います。
古い解説では master が出てきますが、今は main が一般的です。
手元のリポジトリが master で始まっていて、運用をそろえたいなら git branch -m master main でローカル名を変えられます。
履歴そのものは変わらないので、名前だけを今の流儀に合わせる整理として理解すると迷いません。

差分の読みやすさを補助する

KiCad は Git と相性が悪いわけではありませんが、差分の見え方に工夫が要ります。
回路図ファイルはテキストなので、部品参照名やネット名の変更、プロパティ修正のような差分は Git の通常の比較でも追えます。
一方で、基板レイアウトは「文字として読める」ことと「変更の意味がすぐ分かる」ことが一致しません。
フットプリントの位置調整や配線引き直しは、テキスト差分だけ見ても頭の中で絵に戻しにくいからです。

そこで役立つのが、見た目の比較を別に持つことです。
たとえば基板の表裏を PDF や SVG に出しておけば、シルクの欠け、部品位置の移動、外形の変化を目で追えます。
W3Cが管理するSVGはベクター形式なので、拡大しても文字や線がつぶれにくく、図面比較の補助に向いています。
レイアウト変更が多い段階では、KiCad の差分可視化ツールやKiCad Diff Visualizerのような手段を併用すると、「どこが変わったのか」を文章ではなく図で確認できます。

筆者の経験でも、KiCad の自動バックアップと Git の履歴が二重に増えて、どれを見ればよいのか分からなくなった相談がありました。
作業フォルダの中に KiCad のバックアップ群と手動書き出しの PDF と Git 管理対象が混在し、差分を見る前にファイル名の判別で疲れてしまう状態です。
このときはバックアップの保存先を整理し、Git に入れない自動生成物を .gitignore で外しただけで、履歴の視認性が一気に戻りました。
Git は「全部入れる箱」ではなく、「追いたい変化だけを残す箱」と割り切ったほうが、後から読む人の負担が減ります。

{{product:6}}

競合の基本姿勢

コンフリクトは怖いものに見えますが、壊れたというより「同じ場所に別々の変更が入ったので、人間の判断を待っている」状態です。
ここで慌てて片方を丸ごと捨てると、必要な修正まで落としてしまいます。
基本姿勢はシンプルで、まず差分を読むこと、小さいコミットで区切ること、ブランチを長生きさせないことです。
前のセクションで触れた短命ブランチの利点は、競合の量を増やさない点にもあります。

競合が出たら、手順も大きくは変わりません。
自分のブランチに最新の main を取り込み、競合マーカーが入ったファイルを開いて、どちらの変更を残すかを決めます。
KiCad の回路図や設定ファイルなら、両側の変更内容を見て統合し、保存したあとに git add して解消済みにします。
その後で差分を見直し、意図しない消し込みがないか確認してからコミットします。
ここで大切なのは、競合解消そのものを「特別な作業」と考えすぎないことです。
普段の差分確認を少し丁寧にやるだけ、と捉えたほうが手が止まりません。

複数人で KiCad とファームウェアを同時に触るときは、ファイル単位で担当を寄せるのも有効です。
たとえば片方が src/ の Arduino スケッチ、もう片方が hardware/ の回路図と BOM を触る期間を短く分けるだけでも、衝突の面積は減ります。
競合が怖いと感じる人ほど、大きな変更を一度に流し込みがちですが、それでは差分の読解量が膨らみます。
小さいコミットを重ねるほうが、ぶつかった場所を狭く保てます。

生成物コミットの線引き

電子工作のリポジトリは、放っておくと生成ファイルで膨らみます。
KiCad から出した Gerber、ドリルデータ、組立資料の PDF、3D ケースの STL、ビルド済みバイナリ、ログ類まで全部コミットすると、履歴が「設計変更」ではなく「書き出し直し」の記録で埋まります。
Gerber はUcamcoが管理する製造用フォーマットで、製造に渡す節目では残す価値がありますが、毎回の自動出力を無差別に積むのは別の話です。

線引きの考え方としては、再生成できるものは原則コミットしない、配布や発注の基準点として固定した一式だけを残す、の二段構えが扱いやすいです。
たとえば Production/ に「試作発注版」の Gerber、ドリル、部品表 PDF、組立図 PDF だけを置き、それ以外の中間生成物や一時書き出しは .gitignore で外します。
この形なら、設計途中のノイズと、外に渡した確定物が混ざりません。
STL や SVG も同じで、設計ソースから作り直せる途中成果物を全部持つのではなく、意味のある節目だけを残すと履歴の密度が保てます。

ファームウェア側でも、build/ やコンパイル生成物を毎回コミットすると、ソース変更の読解が埋もれます。
Arduino やPlatformIOのプロジェクトでありがちなのは、設定キャッシュやライブラリ取得物まで一緒に上げてしまうことです。
Git 管理に入れるのは、手で編集するソース、設定、回路図、部品表のような一次情報が中心で十分です。
生成物は「発注した版」「展示で配布した版」のように意味を持つタイミングだけ残す。
この切り分けができると、リポジトリが倉庫ではなく履歴帳として機能します。

次のステップ｜CIと差分可視化まで広げる

最小のCIワークフロー

ここまでを手元の運用として回せるようになると、次はGitHub Actionsで「毎回同じ確認を自動で回す」段階に進めます。
電子工作では、回路図と基板だけでなく、Arduino のスケッチやESP-IDFのプロジェクトも一緒に動くため、PR ごとに自動ビルドが走るだけでも安心感が変わります。
人手での確認を減らすというより、見落としを減らす仕組みを先に置く感覚です。

最小構成なら、やることは三つです。
リポジトリを push したらビルドする、失敗したらその場で止める、成功したら成果物を保存する、この骨子だけで十分回り始めます。
たとえばPlatformIOなら CLI で pio run、Arduino 系なら CLI ベースのビルド、ESP32 をESP-IDFで扱うなら idf.py build をジョブに入れる形です。
ここが。
最初からテスト、静的解析、複数ボード対応まで全部入れると、設定を読むだけで疲れます。
まずは main に入る前に「少なくともコンパイルは通る」を機械で保証するだけでも価値があります。

さらに成果物保存まで入れると、現場の流れがぐっと滑らかになります。
筆者の経験では、PR ごとに自動ビルドされた HEX が添付されるようにしただけで、レビュー中のファームを現物へすぐ書き込めるようになり、確認の往復が短くなりました。
ソースを pull してローカル環境を合わせ、ビルドしてから書き込む手間が消えるので、「この変更、実機でどう見えるか」をその日のうちに試せます。
少人数開発ほど、この差は効いてきます。

GitHubが Pull Request を中心にした共同作業の土台を用意しているからこそ、CI はその上に素直に乗ります。
GitHub Actionsのジョブ名を「firmware-build」「kicad-export」くらいの短い単位で分けておくと、失敗箇所も追いやすくなります。
ブランチ運用は前述の通りシンプルなままで構いません。
GitHub Flow に最小の自動ビルドを足すだけで、手作業だった確認が一段整理されます。

エミュレーションでの自動テスト

自動ビルドの次に効いてくるのが、自動テストです。
とはいえ、電子工作では毎回実機を CI にぶら下げるのは現実的ではありません。
そこで候補になるのがRenodeのようなエミュレーション環境です。
PR が作られるたびに、起動できるか、シリアルに想定の初期メッセージを出すか、一定の入力に対して状態遷移するか、といった基本動作を機械的に見ます。

この段階では、ハードウェア固有の全部を再現しようとしないほうが運用が安定します。
LED 点滅、UART 出力、設定値の読み込み、タイムアウト処理のような、ロジック寄りの部分から切り出すのが定石です。
たとえば Arduino 系コードでも、ボード依存部分を薄くし、アプリケーション本体の状態遷移をテスト対象として分離しておけば、エミュレーションやホスト側テストに載せやすくなります。
ESP32 のように無線や周辺機能が絡むと実機検証は残りますが、それでも PR のたびに最低限の起動確認が走るだけで、明らかな退行は早い段階で拾えます。

Renodeを入れる意味は、実機テストを置き換えることではありません。
レビュー前に落としてよい不具合を、机の上の基板まで持ち込まないことです。
筆者がワークショップ教材を整えるときも、教材コードの初期化手順やメニュー遷移のような部分は、実機に書く前に切り分けて見ておくと崩れ方が素直になります。
PR ごとに毎回同じ観点で見られるので、「前の変更で動いていたのに、今回から起動しない」という事故を口頭確認に頼らずに済みます。

KiCad差分の自動可視化

基板設計まで GitHub 上でレビューするなら、コードと同じ感覚で「見た目の差分」も自動で出したくなります。
ここで伸びしろが大きいのが、KiCad 差分可視化ツールの組み込みです。
PR 作成時に回路図や PCB の変更点を画像や HTML のサマリとして出し、レビュー欄に貼れる状態にしておくと、テキスト差分だけでは拾いにくい変更が一気に読みやすくなります。

前のセクションでも触れた通り、KiCad のテキスト diff は追えますが、部品移動や配線の引き回し変更は図として見たほうが判断が早い場面が多くあります。
そこで CI 側で KiCad 差分可視化ツールを走らせ、加えて PDF や SVG を書き出して比較画像を作る運用が効きます。
SVGはW3Cが管理するベクター形式なので、細い配線や文字を拡大しても崩れにくく、PR の添付物として扱いやすい形式です。
初心者にも伝わるのは「どの部品が動いたか」「シルクが消えていないか」「外形が変わっていないか」という見た目の比較なので、レビューの入口としても相性が良いです。

発展案としては、PR ごとに「Top」「Bottom」「Schematic」の差分画像を生成し、コメント欄に一覧で並べる形が分かりやすいです。
コードレビュー担当者が KiCad を開かなくても、変更の輪郭をつかめます。
BOM 更新や製造用データ書き出しまで連動させると、設計変更と製造影響を同じ画面で見比べられます。
手元で KiCad を立ち上げる前に「今回の変更は配線だけか、部品番号にも触れているか」が見えるだけで、レビューの順番が組み立てやすくなります。

タグとリリースでの試作管理

試作が進むと、「今の最新版」より「どの版で発注したか」のほうが大事になる場面が増えます。
そこで効くのが、タグで試作版を切る運用です。
たとえば v0.1-protoA、v0.2-protoB のように、試作の節目ごとにタグを打っておくと、回路図、ファームウェア、部品表、製造データがどの組み合わせだったかを後から正確にたどれます。
ブランチで日々の作業を進め、節目だけタグで固定する形は、小規模な電子工作と相性が良いです。

このタグ運用にGitHubの Release 機能を重ねると、単なる履歴ではなく「製造に渡した一式」の保管庫になります。Production/ にまとめた Gerber、ドリル、組立用 PDF、書き込み用バイナリを Release に添付しておけば、その版で何を出したかが一か所に残ります。
前述の「再生成できるものは常時コミットしない」という整理と矛盾しないのも利点です。
日常の履歴は軽く保ち、節目だけを Release で厚く残すイメージです。

この運用に慣れると、「展示会に持って行ったのはどのファームか」「protoA の基板に載せた部品表はどれか」といった問いに、記憶ではなくタグ名で答えられます。
Git Flow のような重い運用まで広げなくても、少人数開発なら main と短命ブランチ、節目のタグ、必要なら Release という組み合わせで十分回ります。
試作の回数が増えるほど、版名をファイル名に埋め込む管理より、タグで試作版管理したほうが履歴の軸がぶれません。

まとめと次のアクション

本稿の要点

Gitは履歴を残す道具、GitHubはその履歴を共有してレビューや公開までつなぐ場です。

ローカルでの add、commit、status、log を自分の手で再現できれば、管理の軸はもう作れています。

回路図、基板、ファーム、生成物の置き場所と更新ルールを先に決めると、電子工作の版管理は途中で崩れません。

筆者の経験では、最初から凝った運用に広げるより、最初の3コミットとタグを1つ打つところまで進めた時点で、安心感が一段変わります。
回路、基板、ファームが「いま何版か」を同じ言葉で話せるようになり、試作を戻す判断も迷いにくくなります。

チェックリスト：次のアクション

1. 新しい作業用フォルダで Git リポジトリを作成する
2. Hardware/ Firmware/ Docs/ Production/ のようにディレクトリを整理する
3. 初期配置、回路やコードの追加、資料更新の流れで3コミット作る
4. GitHubに push して、手元以外にも履歴を残す
5. 次の1回だけでよいので、feature ブランチ作成かGitHub Actions導入のどちらかに挑戦する

学習リソース

操作を確かめ直すならGit公式ドキュメント、共有や Pull Request の流れはGitHub公式ドキュメント、Arduino 系の最小サンプルはArduinoのBlinkチュートリアル、ESP32 系の発展はPlatformIOやESP-IDFの公式資料が土台になります。
ArduinoのBlinkは Arduino で確認でき、ESP32 の開発基盤は PlatformIO から追えます。
まずは1つの小さな試作を Git 管理し、次にタグ、ブランチ、CI の順で広げていく流れが、遠回りに見えていちばん手堅い進め方です。