Git trifft Mikrocontroller
Dein umfassender Guide zur Versionierung in Arduino-Projekten inkl. GitHub Beispielen
Markus Edenhauser, MA MSc
Copyright ©November 20231. AuflageSelbstverlag
Markus Edenhauser, MA MScVölser Straße 416020 InnsbruckÖsterreichpixeledi.eu/impressum
Gewidmet der wundervollsten Person in meinem Leben – meiner Partnerin!
Dieses Buch ist dir gewidmet, weil du nicht nur meine größte Inspiration und Unterstützung in allen Lebenslagen bist, sondern auch, weil du weißt, wie man mit Git umgeht. Deine Fähigkeit, selbst die kniffligsten Git-Konflikte zu lösen, ist bewundernswert, genauso wie deine Geduld, wenn du stundenlang über Fachthemen diskutierst, egal ob es um Code oder unsere nächste Tour in den Bergen geht.
Ach ja und Danke fürs Lektorat zu diesem Buch :)
Inhaltsverzeichnis
0 Vorwort 9.
1 Einführung 10
1.1 Prämisse und Idee, die dieses Buch verfolgt 10
1.2 Voraussetzungen zum Mitmachen 11
1.3 Wie liest man dieses Buch 12
1.4 Begleitmaterial und Codeschnipsel zum Downloaden 14
1.5 Das geht sicher auch anders! 14
1.6 Haftungsausschluss 14
2 Git Überblick 16.
2.1 Git – Historie und Entstehung 16.
2.2 Git != GitHub 17
2.3 Git und Arduino, passt das zusammen? 19
3 Git Einrichten 22
3.1 Plattformunabhängig mit CLI, Git Bash und GUI Clients22
3.2 Installation unter Windows und Git Bash 24
3.3 Installation unter Linux 28
3.4 Installation unter MacOS 28
3.5 Mindestkonfiguration 29
3.6 Main vs. Master – ältere Repos 30
3.7 Git Lizenz 31
3.8 Expresseinführung Linux-Kommandos und ohmyz31
3.8.1 Nano als Editor 32
3.8.2 Linux Kommandos 33
3.8.3 Ohmyz 34
3.9 VS Code mit PlatformIO und Git Integration 36
3.10 VS Code mit PlatformIO 36
3.11 Sketche von PlatformIO in Arduino IDE öffnen 38
3.12 Terminal in VS Code 39
3.13 Git Plugins für VS Code 40
4 Versionskontrolle mit Git – Praxisbeispiel mit CCS811 42
4.1 Verdrahtung 43
4.2 Initialisierung eines lokalen Git-Repositorys 44
4.3 Sensorauswertung 46
4.4 Staging-Bereich und Arbeitsverzeichnis 49
4.5 Erster Commit 51
4.6 Aktuelle Commits in den Logs 52
4.7 Die Commit-ID 53
4.8 Sensorwerte am OLED visualisieren 53
4.9 Zweiter Commit – git add 55
4.10 Logo für das OLED hinzufügen 56
4.11 Dritter Commit 60
4.12 Die Tücken von git commit -am 61
4.13 Die letzte Version wiederherstellen – git restore 62
4.14 Zu einer früheren Version springen mit git checkout 63
4.15 Unterschied zwischen git switch und git checkout 66
4.16 Conclusio erstes Praxisbeispiel 66
5 Branches im lokalen Repository 68
5.1 Projektidee 68
5.2 Verdrahtung 69
5.3 DHT20 Auswertung und erster Commit 71
5.4 Temperaturwerte am OLED ausgeben 73
5.5 Was ist ein Branch? 74
5.6 Branches anlegen, löschen und wechseln 75
5.7 DHT20 Sensor ansprechen 76
5.8 Änderungen in anderen Branch übertragen – git stash 78
5.9 Einen Branch mergen – Konflikte und fast-forward 81
5.10 Conclusio zweites Praxisbeispiel 84
6 Remote-Repository mit GitHub 86
6.1 GitHub Authentifizierung 86
6.2 Überblick SSH Keys 87
6.3 GitHub SSH Key einrichten 89
6.4 Ein bestehendes Repo klonen – git clone 91
6.5 Ein (privates) GitHub Repository einrichten 93
6.6 Änderungen herunterladen – git pull 94
6.7 Änderungen hinaufladen – git push 95
6.8 Bestehendes lokales Repository pushen 95
6.9 Conclusio 98
7 Ein GitHub-Repo und mehrere Entwickler 100
7.1 Projektvorstellung 101
7.2 Projekt und Git-Repository anlegen 102
7.3 Logik vom Sketch 103
7.4 Mitarbeiter zum Projekt hinzufügen 106
7.5 Merge auf Develop Branch 108
7.6 Code in Main Branch übernehmen – pull request 112
8 Kurze Praxisbeispiele aus dem Entwicklungsalltag 115
8.1 Bash Script mit Dummy-Dateien für Git 115
8.2 Git Remote Verknüpfung lösen 117
8.3 Dateien ausschließen mit .gitignore (credentials.h) 118
8.4 Einzelne Dateien trotz .gitignore hinzufügen – git add -f 120
8.5 Dateien im Repository wieder ausschließen 120
8.6 Branches von geklonten Repositorys 121
8.7 Dateistruktur aufräumen – git clean 122
8.8 Werden auch alle Dateien getracked? git status 125
8.9 Eine bestimmte Datei wiederherstellen 126
8.10 Bereits versionierte Datei kopieren 128
8.11 Schreibfehler von Commits nachträglich ändern 129
8.12 Commit Historie neu schreiben mit git reset 130
8.13 Commit Widerrufen – git revert 132
8.14 Cherry pick 133
8.15 Einen Merge Konflikt lösen oder abbrechen 136
8.16 Markierung für Meilensteine – git tag 139
8.17 Merge vs. Rebase vs. Squash 140
8.17.1 Rebase Beispiel 143
8.17.2 Squash Beispiel 146
9 Self-hosted Git-Server 148
9.1 Alternative zu GitHub, GitLab, Bitbucket, Forgejo etc. 149
9.2 Gitea der optimale Partner für Arduino Entwicklungen 150
9.3 Offline oder vServer 151
9.4 Docker am vServer einrichten 154
9.5 Gitea docker-compose 156
9.6 NGINX Reverse Proxy Manager 160
9.7 Gitea Installation 164
10 Zusatz 166
10.1 Git Begriffsübersicht 166
10.2 Wichtigste Git-Befehle im Überblick 168
10.3 Weiterführende Links 170
11 Auf Wiedersehen! 171
11.1 Passwort E-Book 171
11.2 Rabattcodes 172
11.3 Stuff that works 173
12 Über den Autor 174
13 Weitere Literatur vom Autor 175
14 Verzeichnisse 176
14.1 Stichwortverzeichnis 176
14.2 Abbildung – und Codeverzeichnis 177
14.3 Literaturverzeichnis 178
0 Vorwort
"Warte mal", mögen einige von euch denken, "Git ist doch diese Sache, mit der man Versionskontrollen macht, oder?" Richtig! Aber wusstest du auch, dass Git so vielseitig ist wie ein Schweizer Taschenmesser? Es kann mehr als nur deine wertvollen Codezeilen bewachen. Es kann auch dein Retter in der Not sein, wenn du versehentlich den berühmt-berüchtigten "Delete"-Knopf drückst, oder wenn deine Software sich entscheidet, einen eigenwilligen Tango auf deinem Mikrocontroller aufzuführen.
Jetzt fragst du dich vielleicht: "Warum zum Teufel braucht es überhaupt ein weiteres Git-Buch?" Gute Frage. Das Buch verfolgt die Idee, die speziellen Anforderungen und Herausforderungen des Einsatzes von Git mit Mikrocontrollern (MCUs) anzugehen.
Nun, wenn du dich bisher mit Arduino bzw. ESPs beschäftigt hast, bist du sicherlich ein erfahrener Abenteurer in der Welt der Mikrocontroller. Du hast Lichter zum Blinken gebracht, Motoren zum Surren und vielleicht sogar deine Kaffeemaschine per WLAN steuerbar gemacht (keine Sorge, das haben wir alle :). Aber hier kommt der Clou: Git kann dein treuer Begleiter sein, um all die aufregenden Reisen durch den Code-Dschungel zu dokumentieren und zu organisieren.
Wir schließen das Vorwort mit einem Zitat aus einem meiner Lieblings-Tech-Bücher "Clean Code":
"You are reading this book for two reasons. First, you are a programmer. Second, you want to be a better programmer. Good. We need better programmers.” [1]
Code-tastische GrüßeDein Git-Guide für die Arduino und ESP-AbenteuerMarkus Edenhauser
1 Einführung
"It is not enough for code to work.”[1]
Dieses Buch hat den Anspruch eines Praxisbuchs, soll heißen, es gibt nur ganz wenig Theorie und mehr Umsetzungsbeispiele. Wir werden gemeinsam Schritt für Schritt die notwendigen Systeme installieren und einrichten und dann widmen wir uns den Praxisprojekten. Lernen funktioniert meiner Meinung nach am besten mit dem Tun. Sobald die ersten DIY-Projekte geklappt haben, kann man sich selber noch weiter in die Materie einlesen, um die Hintergründe besser verstehen zu können. Vermutlich kommen dann sowieso gleich die eigenen Ideen und dann gibt es kein Halten mehr.
1.1 Prämisse und Idee, die dieses Buch verfolgt
Wir tauchen hier nicht in die Tiefen komplexer Arduino-Welten ein. Nein, wir schnappen uns Projekte, bei denen du mitmachen kannst, ohne dir dabei die Haare zu raufen, und die du so leicht übernehmen kannst wie ein Stück Kuchen. Schließlich soll Git im Fokus stehen!
Falls dir Begriffe begegnen, mit denen du nichts anfangen kannst, wirf einen Blick in die Git-Übersicht in Kapitel 10.1 .
Den besten Lernerfolg erzielst du, wenn du das Buch chronologisch durchliest, da die Übungen aufeinander aufbauen. Jedes Praxis-Projekt ist so strukturiert, dass wir verschiedene Entwicklungsschritte eines Projekts durchspielen. Dadurch simulieren wir Situationen, mit denen wir im Entwicklungsalltag immer wieder konfrontiert werden. Das bedeutet, du kannst Schritt für Schritt die Projekte mitentwickeln und erfährst somit, welche Git-Befehle aus welchen Gründen angewandt werden. Selbstverständlich kannst du die Praxis-Projekte für deine eigenen Vorhaben adaptieren, um den Lernerfolg noch weiter zu steigern. Ebenso werden bewusst bestimmte Probleme und Konflikte angesprochen, um auch solche Szenarien abzudecken.
Alle gezeigten Beispiele sind auch auf GitHub verfügbar (siehe Kapitel 1.4 ). Dadurch erhältst du nicht nur Zugriff auf das fertige Projekt, sondern kannst auch die gesamte Entwicklungshistorie verfolgen und die verschiedenen Entwicklungsstadien nachvollziehen. Zudem habe ich gelegentlich zusätzliche Dateien in separaten Branches hinterlegt, die du für das Praxisbeispiel mitnutzen kannst. Am Ende eines jeden Praxisprojekts findest du eine gesonderte Auflistung aller verwendeten Git-Befehle, falls du tiefer in die Materie eintauchen möchtest.
Ach ja, wenn ich über Arduino-Projekte spreche, sind bei mir meistens auch der ESP32 und ESP8266 mit inbegriffen. Schließlich sind die ESPs aus der Welt der Arduino-Entwicklung nicht mehr wegzudenken.
1.2 Voraussetzungen zum Mitmachen
Im Grunde ist es ganz einfach. Wenn du schon einmal einen Arduino oder ESP32 / ESP8266 programmiert hast, dann kannst du alle Beispiele von diesem Buch leicht mitmachen.
Das heißt, ich gehe davon aus, dass du bereits:
Arduino IDE bzw. VS Code mit PlatformIO oder eine andere IDE zum Programmieren eingerichtet hast.
Sketch auf den Arduino / ESP laden kannst
Bereits erste Erfahrung mit C++ mitbringst
Viele der gezeigten Projekte wurden mit dem ESP32 umgesetzt, jedoch ist es auch möglich, den Großteil von ihnen auf einen Arduino Uno oder Nano zu übertragen. Das Hauptziel des Projekts besteht darin, die Praxistauglichkeit zu verdeutlichen, wobei die Wissensvermittlung bezüglich der Arduinoprogrammierung nicht im Mittelpunkt steht.
Du kannst die Git Grundlagen auch ohne die hier gezeigten Beispiele mitmachen, macht halt nicht so viel Spaß :).
1.3 Wie liest man dieses Buch
"So if you want to go fast, if you want to get done quickly, if you want your code to be easy to write, make it easy to read.”[1]
Zur besseren Lesbarkeit markiere ich dir immer wieder gewisse Textpassagen mit folgender Formatierung, sodass sich der Fließtext von den Codezeilen abgrenzt:
In diesem Format findest du Codeschnipsel vor:
if(Formatierung) Serial.println("Der Lesefluss ist besser");
else Serial.println("Hä, hier steht auch was?");
Die Lesbarkeit des Sourcecodes in monochromer Farbe ist natürlich kein Genuss, deshalb gibt es auch das PDF zu diesem Buch zum Herunterladen, siehe Kapitel 1.4 .
Befehle und Kommandos für das Terminal bzw. für die Konsole werden in diesem Format angegeben:
sudo -i
whoami
pwd
Achtung, es kann aufgrund der Formatierung von LibreOffice vorkommen, dass Parameter nur mit einem Bindestrich angezeigt werden. Damit das nicht passiert, gebe ich die Kommandos auch oft in dieser Form an.
git log - -oneliner
Wenn du diesen Befehl kopierst, wirst du einen Fehler erhalten, da zwischen dem ersten Bindestrich und dem zweiten ein Leerzeichen vorhanden ist.
Ebenso wirst du eine Fehlermeldung bekommen, wenn du die Commits vom PDF bzw. E-Book in dein Terminal kopierst:
git commit -m "Diese Anführungszeichen von Libre Writer mag das Terminal nicht besonders gern"
Aus diesem Grund sind alle Befehle, die ich für jedes Beispiel verwende, separat im GitHub-Repository angeführt.
Du findest auch vor jedem Praxisprojekt den genauen Link zum GitHub-Repository.
Es empfiehlt sich allerdings, die Git-Kommandos händisch einzutippen, da man gerade am Anfang damit die Syntax besser verinnerlichen kann. Dann läufst du auch nicht in ein Problem mit den Anführungszeichen.
Die Sourcecodes für die Arduino-Programme musst du nicht selbst eintippen. Diese kannst du dir für jeden Commit immer direkt von GitHub kopieren.
Wenn man ein Repository auf GitHub öffnet, sieht man unter dem grünen "<> Code"-Button die Anzahl der Commits. Wenn man auf diese Zahl klickt, gelangt man zur Commit-History. Dort erhält man eine Übersicht darüber, wer wann welchen Commit durchgeführt hat.
Auf der rechten Seite jedes Commits sind die Hash-Werte und ein "<>"-Button zu sehen. Durch Klicken auf den Hash-Wert können die spezifischen Änderungen des Commits eingesehen werden: grün hinterlegte Zeilen zeigen hinzugefügte Inhalte, während rot hinterlegte Zeilen gelöschte Inhalte darstellen.
Wenn man stattdessen auf das "<>"-Symbol in der Commit-Übersicht klickt, gelangt man zur Repository-Ansicht des jeweiligen Commits und kann den Code ohne Änderungsvermerke einsehen.
Damit wir in diesem Praxisbuch nicht seitenweise Screenshots produzieren und damit unnötig viele Buchseiten erzeugen, werden Menüpunkte meist so dargestellt:
Menüpunkt→ Untermenüpunkt → hier klicken
Ich führe oft mit mir selber einen Dialog und markiere offen gestellte Fragen wie folgt:
Warum stellst du Fragen in einem Buch?
Sollte die Frage nicht lauten: "Wieso redest du als Autor mit dir selbst? ��
1.4 Begleitmaterial und Codeschnipsel zum Downloaden
Arduino bzw. ESP Codes, Linux und Git Befehle pro Kapitel findest du auf GitHub.
https://github.com/git4arduino
In jedem Praxisbeispiel ist der Link für das jeweilige Repository nochmal extra angegeben.
Achja, Infos zum Ebook findest du im Kapitel 11.1 .
1.5 Das geht sicher auch anders!
"You can do things so many ways"-- Linus Torvalds
Programmieren gleicht fast einer Art Glaubensfrage – jeder hat so seine eigenen Erleuchtungen auf dem Weg zum fertigen Projekt. Es kann durchaus passieren, dass der von mir präsentierte Pfad dir wie eine Reise durch ein Labyrinth vorkommt. Natürlich gibt es auch andere Wege, die zum Zielen führen. Die Strategien, die ich hier zeige, sind nur eine Art Wegweiser, ein bisschen wie Karten für eine Schatzsuche. Ich gebe dir meine Erfahrungen in Form von Projekten weiter, sodass du bestmöglich in die Thematik Git findest.
1.6 Haftungsausschluss
Kommst du mir jetzt mit juristischen Fachbegriffen?
Ich möchte betonen, dass ich keine Verantwortung dafür übernehme, wenn dein Arduino plötzlich anfängt, den Moonwalk hinzulegen oder sich in eine hyperintelligente Kaffeemaschine verwandelt. Dieses Buch steckt so voller Begeisterung für Git und Arduino / ESP, dass ich mit bestem Gewissen sämtliche Verdrahtungen und Ausführung kontrolliert habe.
Dennoch kann es sein, dass sich ein Fehler einschleicht und dein Mikrocontroller dadurch Rauchsignale abgibt und sich in den wohl verdienten Ruhestand verabschiedet. Kontrolliere vor Inbetriebnahme die Schaltungen und Drahtverbindungen, sodass du viel Spaß mit deinen Projekten hast.
Der Nachbau erfolgt auf eigene Verantwortung. Ich kann keinerlei Garantie über die Richtigkeit und Funktionalität gewährleisten. Außerdem kann ich euch keine individuelle Hilfestellung leisten. Falls ihr nicht mehr weiter wisst, holt euch Hilfe von fachkundigen Kollegen. Ebenso ist jegliche Haftung für Beschädigungen und Verletzungen ausgeschlossen.
Falls ihr einen Fehler im Buch entdeckt oder sonstige konstruktive Kritik für mich habt, meldet euch unter: hello@pixeledi.eu.
So aber jetzt nützen wir die Zeit und legen los. Viel Spaß dabei!
2 Git Überblick
"Git: Wo jeder Commit eine neue Episode im Abenteuer deines Codes ist. Manchmal ein Drama, manchmal eine Komödie, aber immer ein unverzichtbarer Teil deiner Entwicklungsreise."
-- ausgesprochen kreatives Zitat vom Autor
In den folgenden Abschnitten werfen wir einen Blick auf Git, ein unverzichtbares Tool im Werkzeugkasten eines jeden Arduino-Entwicklers, und verstehen, warum seine Verwendung so wichtig ist.
Git ist viel mehr als nur ein verteiltes Versionskontrollsystem. Es ermöglicht uns als Entwickler den Quellcode zu verfolgen und bietet uns weiters die Möglichkeit, einfach und schnell frühere Versionen wieder herzustellen. Ebenso hilft uns Git mit dem Backups unserer Codes und darüber hinaus erleichtert es uns auch noch die Zusammenarbeit mit Anderen.
Egal ob du alleine als Hobby-Entwickler deine IoT Projekte programmierst oder in größeren Open-Source Projekten zusammen arbeitest, heutzutage kommt man an Git nicht vorbei.
2.1 Git – Historie und Entstehung
Die Geschichte von Git begann aus einem beinahe Streit heraus. Ursprünglich wurden Änderungen am Linux-Kernel als Patches weitergegeben. Ab 2002 wurde das proprietäre DVCS-System BitKeeper verwendet. Doch im Jahr 2005 zerbrach die Beziehung zwischen der Linux-Gemeinschaft und BitKeeper. Tja, Linus Torvalds brauchte nun dringend ein neues Versionskontrollsystem für die Verwaltung des Linux-Kernels. Was machte also Linus? Richtig, er programmierte sich selber eine Software zum Verwalten von Code. Er verbrachte eine Woche offline, entwickelte ein revolutionäres neues System namens Git von Grund auf. Fünfzehn Jahre später ist die Plattform der unbestrittene Marktführer ([2] & [3]).
In einem Interview äußerte Linus einmal, dass er sich nie wirklich für Versionsverwaltung interessiert hat. Er betrachtete sie sogar als das am wenigsten interessante Thema in der Computerwelt, gleich nach Datenbanken [4].
Ja, Linus Torvalds hat neben Linux also auch den Grundpfeiler für Git gelegt. Unglaublich wie ein einziger Mann die hiesige IT-Branche so beeinflusst hat. Die Biografie von Linus Torvalds, "Just for Fun", zeigt übrigens die Entstehungsgeschichte von Linux. Im Jahr 2002 war Git jedoch noch kein Thema. Dennoch kann ich die Biografie wärmstens empfehlen [5].
2.2 Git != GitHub
Kurz gesagt:
Git ist ein Tool für eine lokale Versionskontrolle von Softwareprojekten, mit dem man Schnappschüsse über einen längeren Zeitraum erstellen kann. Git lässt sich also perfekt sowohl von Einzelpersonen als auch im Team verwenden. Das funktioniert offline und auch online über eine der unzähligen Git-Plattformen.
GitHub ist eine webbasierte Plattform, welche Git integriert hat [6].
Zugegeben, das wird jetzt nicht die neueste Schlagzeile für dich sein. Heutzutage stellt man sich also nicht mehr die Frage, ob man Git überhaupt verwenden soll, sondern eher drängt sich die Frage auf, welchem Online-Dienst man seine Daten anvertraut. Im späteren Verlauf werden wir auf die Vor- und Nachteile von Online-Repositorys noch näher eingehen.
---ENDE DER LESEPROBE---