Skip to content

Versiebeheer met GitHub

Versiebeheer

Zodra je scripts wat ingewikkelder worden begin je tegen hele praktische problemen aan te lopen. Het werkt nu, maar je wilt een flinke aanpassing gaan doen. Werkt het straks nog wel? Hoe ingewikkelder het script, hoe ingewikkelder de wijzigingen en hoe minder het vertrouwen dat het in één keer gaat lukken. Misschien heb je wel eens de ervaring gehad dat het maar niet wil werken en dat je niet goed weet wat je precies had veranderd ten opzichte van toen het nog wel werkte. Veel mensen hebben de neiging om naast een script.py een script-v1.py, script-v2.py, enz. aan te maken. Soms zelfs een script-eindversie.py en met wat pech dan toch nog een script-eindversie-definitief.py. Niet heel fijn. Je ziet dan nog steeds niet goed wat er veranderd is (dat blijft naast elkaar leggen en zoeken) en je map loopt vol met overbodige scripts. Dit kan beter… met versiebeheer!

Versiebeheer (Engels: version control) stelt je in staat om af en toe een momentopname te maken van al je bestanden in een bepaalde map, inclusief alle submappen. Dit doe je niet na iedere regel code, maar bijvoorbeeld wel als je een stukje code af hebt en getest hebt dat het werkt. Zo'n momentopname heet een commit. Hoe vaak je commit is aan jou; maar wacht niet te lang — dan is het geen versiebeheer meer.

Je versiebeheersysteem geeft ondertussen duidelijk al je wijzigingen weer ten opzichte van de laatste commit. Ook kun je de wijzigingen tussen oudere versies bekijken. Alles is relatief: je kunt zien wat er veranderd is tussen twee weken terug en gisteren, of gisteren en vandaag; iedere commit kun je vergelijken met willekeurig iedere andere commit. Heb je iets verprutst en wil je een oude versie terughalen? Prima! Commit die ook, dan kun je zelfs dat weer terugdraaien later. Je verliest nooit meer je werk. En stukmaken mag!1

Git

Ruim tien jaar geleden werden er nog vele concurrerende systemen gebruikt. Die tijd is grotendeels voorbij. Eén van de nieuwste systemen, Git,2 wordt tegenwoordig door bijna iedereen gebruikt of ondersteund. Git is ontwikkeld door Linus Torvalds als alternatief voor het commerciële systeem dat gebruikt werd voor de ontwikkeling van de Linux kernel.6 Het begon als een zeer eenvoudig — en volkomen ongebruiksvriendelijk — programma. Later is het in een veel gebruiksvriendelijker jasje gestoken.

Git werkt in principe via de command-line. Je geeft opdrachten in de map waar je broncode staat: toevoegen van wijzigingen aan de staging area, bekijken van de meest recente wijzigingen, committen van je code, teruggaan en werken met oudere versies, aanmaken van branches,3 je wijzigingen uploaden naar internet, enz. Het geheel van map met broncode en versiegeschiedenis wordt een repository genoemd.

In deze cursus zullen we gebruik maken van een grafische applicatie die eenvoudiger werkt. Je kunt daarna — als je dat wilt — de stap maken naar de command-line waarmee je nog veel meer mogelijkheden tot je beschikking krijgt. Voor meer informatie over Git en het gebruik via de command-line, zie het boek Pro Git.7

GitHub

Git is een distributed version control system (DVCS) wat wil zeggen dat er geen centrale server hoeft te zijn. Je kunt volledig offline werken in je eigen repository en je wijzigingen af en toe committen. Als je daar zin in hebt kun je je wijzigingen naar een collega sturen (pushen) of je kunt een collega toestemming geven om de wijzigingen op te halen (pullen). Je bouwt dan aan één grote versiegeschiedenis met kopieën op meerdere computers. Je bent zo volledig onafhankelijk van bedrijven die servers in de lucht houden of bepalen wie er wel en niet toegang krijgt. Dat is fijn, maar een centrale plek om repositories neer te zetten heeft weer het grote voordeel dat je de wereld kunt laten zien wat voor moois je gemaakt hebt én dat het samenwerking wel vermakkelijkt. Als iedereen uit je team regelmatig commits pusht naar een centrale server en daar vandaan ook ophaalt dan is iedereen altijd up-to-date.

Er zijn tegenwoordig veel websites die een plek bieden voor Git repositories. De bekendste zijn GitHub, GitLab, Bitbucket en SourceForge. GitHub, aangekocht door Microsoft, is op dit moment het bekendste en grootste platform. Veel bekende softwareprojecten vinden daar hun thuis.

Wij gaan werken met GitHub, je moet dan wel een (gratis) account aanmaken. Als student kom je ook nog in aanmerking voor een educatiekorting op een pro-account. Je betaalt dan nog steeds niets.

Account aanmaken

Ga naar https://github.com/ en klik rechtsboven op Sign Up. Maak een account aan onder je privé-emailadres. Op deze manier blijf je toegang houden tot je account ook nadat je afgestudeerd bent.

GitHub Desktop

Om het programmeurs makkelijker te maken met GitHub te werken heeft GitHub een desktop applicatie ontwikkeld met de naam GitHub Desktop. We gaan GitHub Desktop gebruiken om een repository te maken van een map met oefenopdrachten.

Van bestaande map repository maken

Je gaat een repository maken van een bestaande map. Als je van de ECPC een repository maakt, kun je daar geen andere repositories inzetten. Dus maak je in de map ECPC een nieuwe map oefenopdrachten aan en zet daarin alle Python-bestandjes die je hebt gemaakt om te oefenen zoals de opdrachten Pyvisa in pythonscript en KnipperLED.
Je gaat naar GitHub Desktop en logt in met je eigen account. Je ziet bij File drie opties staan, New, Add local en Clone repository. Hoewel New repository een goede optie lijkt, wordt daarmee een nieuwe map aangemaakt en dat is niet nodig. Dus kies je voor Add local repository. Je geeft de map oefenopdrachten op als locatie en krijgt in rode tekst een waarschuwing. De waarschuwing geeft aan dat de map wel bestaat maar dat het geen Git repository is, daarom klik je op de blauwe tekst create a repository. Je vinkt Initialize this repository with a README aan en kiest bij Git ignore voor Python. Je bevestigt dan met de blauwe knop Create Repository.
Vanaf nu duiden we een repository aan met het -symbool.
De repository oefenopdrachten is in GitHub Desktop geopend en als je op het tabblad 'History' klikt dan zie je dat er een Initial commit is met wat git-bestanden en de Pythonscripts die je in de map hebt gezet. Vanaf nu staat oefenopdrachten in versiebeheer en houdt Git je wijzigingen bij, maar je moet wel zelf committen!
ECPC
├── oefenopdrachten
           ├── test_arduino.py
           ├── flashingLED.py
           └── •••

Git ignore Python

Waarom zou je bij Git ignore voor Python kiezen, we gaan toch juist Python bestanden maken? De Git Ignore zorgt ervoor dat allerlei hulpbestanden van Python niet bewaard worden als commit. Maar de Python code wordt wel bewaard.

Checkpunten:

  • De repository oefenopdrachten zit in de map ECPC.
  • In de repository oefenopdrachten is een bestand README.md
  • In de repository oefenopdrachten is een bestand .gitattributes.
  • In de repository oefenopdrachten is een bestand .gitignore.

Projecttraject

  • Pyvisa in pythonscript
  • LED laten branden
  • flashingLED
  • Van bestaande map repository maken
  • Commit
  • Push en pull

Commit

Alle wijzigingen aan bestanden in de repository kun je vanaf nu bijhouden door regelmatig een commit te maken. Met een commit maak je als het ware een snapshot van alle bestanden en hang je daar een labeltje aan. Dit kan in GitHub Desktop, maar ook direct vanuit Visual Studio Code. Elke commit geef je een begeleidend schrijven mee. Je hoopt dat jij, maar ook je collega, na het lezen van het berichtje snel begrijpt wat er veranderd is én waarom. Wanneer je bepaalde wijzigingen ongedaan wilt maken, kan je snel vinden bij welke commit je dan moet zijn. En als je dan je applicatie gaat uitbrengen op Github kun je de commit messages gebruiken om snel op te sommen wat de nieuwste versie van jou app kan!

Commit

Voer de volgende opdrachten uit:

  1. Open GitHub Desktop, klik op Current repository (links onder de menubalk) en selecteer de repository die je in opdracht Repository toevoegen hebt aangemaakt.
  2. Ga naar Repository > Open in Visual Studio Code (of druk op Ctrl+Shift+A ) en open de repository in Visual Studio Code.
  3. Open in Visual Studio Code één van je Pythonscripts.
  4. Type een stukje code erbij — bijvoorbeeld een print-statement — en haal ergens anders iets weg. Bewaar het bestand.
  5. Ga naar GitHub Desktop, controleer bij Current repository (links onder de menubalk) of de juiste repository is geopend.
  6. Klik daaronder op het tabblad Changes
  7. Als er meerdere bestanden gewijzigd zijn kan je met het blauwe vinkje aangeven voor welke bestanden je een commit schrijft.
  8. Onder de lijst met gewijzigde bestanden vind je twee invulvulden. Een smal veld voor een titel en een groot veld voor een uitgebreide beschrijving (Description).
  9. In het titelveld staat in lichtgrijs een nietzeggende commit (bijvoorbeeld: Update test.py). Schrijf daar een nuttige commit message. Dus niet: opdracht: commit, maar zoiets als: feat: lookup port name for device.
  10. Klik op Commit to main. Gefeliciteerd! Je hebt je eerste commit gepleegd!
  1. Open GitHub Desktop, klik op Current repository (links onder de menubalk) en selecteer de repository die je in opdracht Repository toevoegen hebt aangemaakt.
  2. Ga naar Repository > Open in Visual Studio Code (of druk op Ctrl+Shift+A ) en open de repository in Visual Studio Code.
  3. Open in Visual Studio Code één van je Pythonscripts.
  4. Type een stukje code erbij — bijvoorbeeld een print-statement — en haal ergens anders iets weg. Bewaar het bestand.
  5. Links verschijnt een blauw bolletje (Geen blauw bolletje? Bekijk het info blok hieronder.) bij Source Control die laat weten dat er wijzigingen zijn ten opzichte van de vorige commit. Klik op Source Control.
  6. Onder Changes staat een lijst met bestanden waar wijzigingen in aan zijn gebracht. Kies welke bestanden je wilt committen door rechts op het +je te klikken. Deze bestanden komen nu op het podium te staan onder Staged Changes. Je kunt ook alle bestanden in een keer op het podium zetten door naast het kopje Changes op het +je te klikken.
  7. Schrijf een nuttige commit message. Dus niet: opdracht: commit, maar zoiets als: feat: lookup port name for device.4
  8. Klik op het vinkje om te committen. Gefeliciteerd! Je hebt je eerste commit gepleegd!

Geen blauw bolletje

Zie je geen bolletje verschijnen? Kijk of je het bestand zeker weten hebt opgeslagen. Nog steeds geen blauw bolletje? Ga naar GitHub Dekstop en ga verder met stap 5.

Checkpunten:

  • In GitHub Desktop staat onder het History tabblad een nieuw commit message.
  • De commit bevat het bestand waarin je een aanpassing hebt gedaan.
  • De aanpassing is aangegeven met groen (toegevoegd) en rood (weggehaald).

Projecttraject

  • Pyvisa in pythonscript
  • LED laten branden
  • flashingLED
  • Van bestaande map repository maken
  • Commit
  • Push en pull

In GitHub Desktop zie je nu bij history de commit staan, met in een oogopslag alle wijzigingen.

Info

Als je wilt opzoeken hoe iets werkt bij GitHub Desktop, kijk dan in de documentatie: https://docs.github.com/en/desktop.

Hieronder zie je een aantal voorbeelden van commit messages. De titels zijn kort en krachtig, in de description staat specifieke en uitgebreidere informatie.

ECPC logo
ECPC logo
ECPC logo
ECPC logo
ECPC logo
ECPC logo

Push en pull

De repository die je in opdracht Repository toevoegen hebt aangemaakt bestaat alleen nog maar op de computer. Als de computerkabouters 's nachts langskomen kan het zijn dat de computer daarna is gewist en je alles kwijt bent. Daarom is het fijn om de repository ook in de cloud te hebben op GitHub.com. In GitHub desktop is een knop Publish repository; Publish this repository to GitHub, als je daar op drukt kun je nog een andere naam aan de repository geven (dat bepaalt de url op github.com), een description en of de code privé moet zijn. Daarna klik je op de blauwe knop Publish repository. Als je nu naar GitHub.com gaat zie je bij jouw repositories de zojuist gepubliceerde repository staan.

Om je wijzigen ook in de cloud op te slaan kun je commits pushen naar Github.com met de knop Push origin. Als je op een andere computer gaat werken kun je de repository vanuit de cloud naar de computer halen door op Fetch origin te klikken en daarna op Pull origin.

Checkpunten:

  • De repository staat op github.com bij jouw repositories

Projecttraject

  • Pyvisa in pythonscript
  • LED laten branden
  • flashingLED
  • Van bestaande map repository maken
  • Commit
  • Push en pull

GitHub

Om makkelijk je Git repository te delen met vrienden, collega's en de rest van de wereld kan je er voor kiezen om deze op GitHub te zetten. Je kunt dan je commits pushen naar GitHub en wijzigingen die je vrienden hebben gemaakt pullen zodat jij er ook weer aan verder kan werken. Van alle repositories die op GitHub staan én openbaar zijn kun je de broncode clonen en zelf mee aan de slag! Laten we eens een kijkje nemen op GitHub.

Tailor

Als je nog nooit op GitHub bent geweest dan kunnen de pagina's nogal intimiderend overkomen. De informatiedichtheid is nogal hoog. Na een paar bezoeken weet je meestal wel waar je dingen kunt vinden. David heeft een data-analyse app geschreven dat Tailor heet en dat gebruikt wordt bij natuurkundepractica voor studenten medische natuurwetenschappen (MNW) en science, business and innovation (SBI). Laten we eens kijken wat daar allemaal opstaat.

  1. Zoek de repository /davidfokkema/tailor op github.com op.
  2. Je komt terecht op de hoofdpagina, hier zie je een mappenstructuur met een aantal bestanden. Rechts daarvan staat een korte beschrijving onder het kopje About. Een uitgebreidere beschrijving vind je als je naar beneden scrollt onder Readme.
  3. Linksboven zie je een aantal tabbladen (code, issues, pull requests, ...), het tabblad code is de hoofdpagina met de mappenstructuur. Navigeer door de mappen, wat staat er op regel 14 van plot_tab.py?
  4. Ga terug naar de hoofdpagina, kijk onder het groen kopje met code. Hoeveel commits zijn er gemaakt? Klik op commits en daarna op een commit-message. Hoeveel regels zijn er weggehaald of bijgekomen?
  5. Je kan per bestand bekijken wanneer die is aangepast en wat er is aangepast met de history knop. Ga naar het bestand pyproject.toml en klik rechtsboven op History. Wat is er aangepast in pyproject.toml bij de commit Release v2.0.0? Je ziet ook welke bestanden nog meer zijn gewijzigd in deze commit, welk bestand is nog meer gewijzigd bij Release v2.0.0?
  6. Ga terug naar de hoofdpagina. Welke versie van Tailor is als laatste gereleased?
  7. Je kent het misschien wel, dat je een app gebruikt maar dat het niet helemaal goed werkt (bug), of je hebt een idee hoe het nog beter kan worden (enhancement). Daarvoor is op GitHub het tabblad Issues. Hoeveel bugs zijn er gerapporteerd? En hoeveel enhancements?
  8. Als het jou nu gelukt is om een bug te fixen, of je hebt een super handige feature ontworpen, dan kan je de eigenaren van de repository vragen om jouw code te implementeren door een pull request te sturen. Ga naar het tabblad Pull requests, klik op Closed en bekijk welke pull requests zijn geïmplementeerd.
  9. Het meest rechter tabblad Insights geeft je, tegen alle verwachtingen in, inzicht. Je kan zien door hoeveel mensen er aan gewerkt wordt. Kijk bij Code frequency, in welke periode is er het meest aan de code veranderd?
  10. Als je een repository goed/handig/slim/fijn vindt kun je dit aangeven met een ster. Klik daarvoor rechtsboven op star .
  11. Dan tot slot die ene, meest in het oogspringende groene code knop. Met die knop kan je de repository als zip-bestand downloaden of openen met GitHub desktop.
Clone repository

Clone de LMfit-py repository op GitHub:

  1. Zoek de repository op GitHub op (lmfit/lmfit-py)
  2. Kies Code > Open with GitHub Desktop
  3. Kies zelf een map op je harde schijf om de repository te bewaren.
  4. Open Visual Studio Code en open de repository met File > Open Folder.5 Als GitHub Desktop de geïnstalleerde VS Code herkent kan dat direct vanuit GitHub Desktop met Repository > Open in Visual Studio Code.
  5. Open examples README.txt. Verander in de eerste paragraaf Below are examples in Below are different examples en sla het bestand op.
  6. Schakel naar de GitHub Desktop applicatie en bekijk de wijziging.
  7. Linksonder kun je een korte beschrijving van je wijziging intypen en druk dan op de blauwe Commit-knop.
  8. Schakel, rechtsboven, naar History. Bovenaan staat jouw wijziging. Daaronder kun je alle wijzigingen van anderen bekijken.

Aangezien je geen schrijfrechten hebt voor LMfit kun je niet kiezen voor Push origin — de knop die rechtsboven verschijnt. Met die knop duw je je wijzigingen naar GitHub zodat iedereen ze kan zien. Dat is mooi, maar je mag niet zomaar de repository van iemand anders wijzigen.

Git in de terminal

Tot nu toe heb je Visual Studio Code of GitHub Desktop gebruikt om te committen. Maar je kan Git ook bedienen via de terminal. De mogelijkheden van Git zijn in de terminal ook veel groter dan in de grafische applicaties die we gebruikt hebben.

  1. Open een repository in Visual Studio Code
  2. Gebruik de terminal in Visual Studio Code en bekijk de commit geschiedenis met het commando git log. Scroll door de commit messages met spatie.
  3. Zoek via https://initialcommit.com/blog/Git-Cheat-Sheet-Beginner het commando om een commit toe te voegen. Wijzig iets in je code en commit via de terminal.
  4. Dit waren twee dingen wat met GitHub Desktop ook kon, snuffel op het internet om te zien wat je met Git nog meer kunt.
Branches

Branches

Soms wil je je code flink onder handen nemen of iets heel nieuws eraan toevoegen. Terwijl je bezig bent ga je natuurlijk eerst van alles stuk maken voordat je het weer werkend hebt gekregen. Maar ondertussen kan je oude functionaliteit van je code niet gebruiken. Of je bent samen met een vriend aan een package bezig en om de haverklap werkt jouw stukje code niet meer omdat ergens anders de code verbouwd wordt. Dan is het handig dat je vanaf het punt dat je code werkt een zijweg kan inslaan. Daarom zijn branches uitgevonden. Je kunt vanuit Github Desktop, vanuit Visual Studio Code en natuurlijk via de terminal een branch aanmaken.

Branches

  • Open een repository naar keuze en maak een nieuwe branch aan.
  • Maak een aantal wijzigingen en commit.
  • Ga terug naar de main branch.
  • Merge de nieuwe branch in de main branch.

  1. Stukmaken mag, maar het terughalen van een oude versie is niet met een druk op de knop gebeurt. Vraag om hulp als je terug wilt naar een oude versie, wij helpen je graag! ↩

  2. https://initialcommit.com/blog/How-Did-Git-Get-Its-Name ↩

  3. Een branch is een splitsing in je versiegeschiedenis. Je kunt het gebruiken om over een langere tijd een grote wijziging uit te testen terwijl je af en toe heen en weer springt tussen je main branch en de nieuwe branch. Commits in de nieuwe branch blijven gescheiden. Later kun je ervoor kiezen om de wijzigingen in de nieuwe branch te mergen met je main branch, maar dat hoeft niet. ↩

  4. Je kunt je commit message opdelen in een titel (of summary) en een beschrijving. Dit doe je dit door een witregel toe te voegen tussen de titel en de beschrijving. ↩

  5. Als je vergeten bent waar je de repository ook alweer bewaard had kun je met Repository > Show in Finder de folder openen. ↩

  6. Linus Torvalds and others. Git. 2005. URL: https://git-scm.com. ↩

  7. Scott Chacon and Ben Straub. Pro git: Everything you need to know about Git. Apress, second edition, 2014. URL: https://git-scm.com/book/en/v2. ↩