Workshop: Git en GitHub

Voorbereiding

Het is de bedoeling dat je de voorbereiding voor de start van de workshop doorneemt. Tijdens de workshop ga je zelf de onderstaande instructies in de praktijk brengen.

Wat zijn Git en GitHub?

In de onderstaande video wordt een korte introductie gegeven over Git en Github:

Samenvatting:

  • Git is een computerprogramma dat gebruikt kan worden om wijzigingen in files bij te houden. Zo’n programma noemen we een versiebeheersysteem.
  • Een Git repository is een map met daarin bestanden. Git volgt de wijzigingen in deze bestanden.
  • Met een commit kun je de wijzigingen in bestanden vastleggen.
  • GitHub is een website waar je een kopie van de Git repository kunt delen met anderen.
  • Als je de kopie op GitHub wilt updaten, voer je een push uit. Als je wijzigingen van GitHub naar je computer wilt halen, voer je een pull uit.

Git en Github in de praktijk

Een Git repository aanmaken

In de onderstaande video wordt getoond hoe je een Git repository kunt opzetten met GitHub en RStudio:

Als je een nieuwe Git repository wilt aanmaken, kun je het beste het onderstaande stappenplan volgen:

  1. Maak een nieuwe Git repository aan op GitHub.

  2. Volg de stappen op de website. Kies bewust of je de repository op GitHub private of public maakt. Maak eventueel een gitignore file, readme file en/of licentie file aan.

  3. Download de Git repository (= clonen) naar je computer met RStudio. Doe dit door een nieuw RStudio project aan te maken.

Wijzigingen commiten en pushen

In de onderstaande video wordt getoond hoe je wijzigingen in een bestand kunt commiten en pushen:

Wijzigingen in bestanden kun je via RStudio bijhouden in het ‘Git’ tabblad.

Zorg ervoor dat je regelmatig wijzigingen vastlegt middels een commit. Doe dit meerdere keren per dag en zorg ervoor dat elke commit een informatieve message heeft.

Zorg er ook voor dat je de commits regelmatig pushed naar GitHub. Doe dit in ieder geval één keer per dag, maar het is het handigst om elke commit direct te pushen naar GitHub.

GitHub is een ideale plaats om je code te delen, maar de opslagruimte per repository is beperkt. GitHub is daarom niet geschikt om grote databestanden (zoals sequencing data) te delen! Om ervoor te zorgen dat deze bestanden niet gevolgd worden door Git en dus ook niet gepushed worden naar GitHub, kun je de bestanden (of mappen waar deze bestanden in staan) opnemen in de .gitignore file. Alle bestanden die in de .gitignore file staan, worden genegeerd door Git.

NB: Voor de reproduceerbaarheid van je analyse is het wel van belang dat je in je README bestand van de GitHub repository aangeeft waar de data gevonden kan worden!

Samenwerken met Git: branching & merging

Vaak werk je met meerdere personen aan dezelfde code. Git en GitHub maken dit eenvoudiger. Hiervoor maak je gebruik van extra Git tools, namelijk branching en merging.

Wat is branching en merging?

In de onderstaande video wordt uitgelegd wat branching en merging inhouden:

Samenvatting:

  • De main branch is de hoofdbranch in een Git repository. Hier moet altijd een werkende versie staan van de code.

  • Als je iets nieuws wilt toevoegen aan de code, dan kun je hiervoor het beste een aparte branch aanmaken. Hiermee maak je in feite een kopie van de main branch. In deze nieuwe branch kun je dan dingen toevoegen en testen, zonder dat de code in de main branch veranderd.

  • Als je tevreden bent over je toevoegingen en alles werkt, dan kun je je nieuwe code toevoegen aan de main branch door merging. Op die manier komen je wijzigingen ook beschikbaar voor andere gebruikers die werken met de main branch.

  • Soms ontstaan er conflicten tijdens het mergen. Die kun je dan oplossen in GitHub (zie hierna).

Branching en merging in de praktijk

In de onderstaande video wordt getoond hoe je branching en merging kunt toepassen om wijzigingen in je code aan te brengen:

Als je iets nieuws wilt toevoegen aan je code, dan kun je hiervoor het beste een branch aanmaken. In die branch kun je dan nieuwe dingen uitproberen en testen, zonder dat de werkende code in de main branch veranderd.

Om code te ontwikkelen via een branch kun je de volgende stappen uitvoeren:

  1. Maak een branch aan in RStudio.

  2. Controleer dat je daadwerkelijk aan het werken bent in de nieuwe branch. Maak wijzigingen in je code en commit die zoals je gewend bent.

  3. Push de code naar GitHub.

  4. Als je tevreden bent over je wijzigingen en de code wilt toevoegen aan de main branch, kun je in GitHub een pull request uitvoeren om jouw branch en de main branch te mergen.

  5. Als de merge succesvol was, kun je de wijzigingen in de main branch pullen naar je computer.

Merge conflicten oplossen

Soms is mergen niet direct mogelijk, omdat er sprake is van een merge conflict. Dit kan gebeuren als iemand anders al voor jou wijzigingen heeft doorgevoerd in de main branch (in hetzelfde bestand als waarin jij aan het werken was). Deze merge conflicten kunnen worden opgelost in GitHub en het is daar een standaard onderdeel van een pull request.

Issues bijhouden en oplossen

Als je samenwerkt binnen een Git repository op GitHub, is het aan te raden om gebruik te maken van issues. Iedereen die toegang heeft tot jouw repository kan issues aanmaken. Je kunt deze issues zien als een to-do lijst. Alle dingen die nog aangepast moeten worden in je code, maar ook bijvoorbeeld in de documentatie van de code, kunnen als issue worden benoemd.

Je kunt een nieuw issue aanmaken in de Issues tab van je repository op GitHub. Je kunt in deze tab ook alle aangemaakte issues bekijken. Als je een nieuw issue aanmaakt, kun je hier een persoon aan koppelen die dit issue uit moet werken.

Als je een issue op wilt lossen, kun je het beste dit stappenplan volgen:

  1. Maak een nieuwe branch aan voor het issue.

  2. Wijzig de code en commit de wijzigingen. Als je in de commitmessage Fix #<issue nummer> gebruikt (waarbij je <issue nummer> vervangt door het nummer dat hoort bij jouw issue op GitHub), wordt het issue vanzelf gemarkeerd als ‘Closed’ en verwijderd uit de lijst.

  3. Merge de wijzigingen met de main branch.

Maak een GitHub account

Om tijdens de workshop aan de slag te kunnen gaan met GitHub, moeten jullie een GitHub account aanmaken.

Je kunt je account aanmaken via de GitHub website. Een account aanmaken is gratis. Je kunt voor het aanmaken van je account het beste je school e-mailadres gebruiken.

Workshop

Het doel van de workshop is om een Github repository op te zetten voor jullie project en om te experimenteren met deze omgeving. Het is de bedoeling dat jullie als groep de onderstaande opdrachten uitvoeren.

Maak een Git repository voor jullie project

Maak een git repository aan voor het project. Volg hiervoor de volgende stappen:

  1. Geef je GitHub accountnaam door aan je tutor. Je tutor zal je koppelen aan een projectorganisatie in GitHub.

  2. Maak binnen deze projectorganisatie een private Git repository aan. Dit kan worden gedaan door één van de studenten in de groep.

  3. Voeg de andere studenten toe als collaborators (zie Settings > Collaborators and Teams).

  4. Download (= clone) de repository naar een RStudio project op de server.

Voor elke push/pull vraagt Git om de inloggegevens voor GitHub. Hiervoor heb je je inlognaam nodig en een personal access token. De personal access token kun je aanmaken volgens dit stappenplan.

Als je eenmaal de personal access token hebt aangemaakt, kun je deze koppelen aan RStudio met de volgende R code:

library(gitcreds)
gitcreds_set()

Voeg een bestand toe aan de repository

Eén van de studenten maakt een nieuw bestand aan in de Git repository op de server (bijv. een R script of een Rmarkdown bestand). Voer vervolgens de volgende stappen uit:

  1. Sla het bestand op in de map van de Git repository.

  2. Ga naar het Git tabblad en commit de wijzigingen.

  3. Push de wijzigingen naar GitHub en check of het bestand nu zichtbaar is op GitHub (ververs de pagina eventueel).

  4. De andere studenten kunnen nu in hun Git repository op de server een pull uitvoeren. Het bestand moet dan in hun map verschijnen.

Maak wijzigingen aan via een branch

Eén van de studenten maakt een wijziging in het bestand in de Git repository op de server via een branch. Voer vervolgens de volgende stappen uit:

  1. Maak een nieuwe branch aan.

  2. Wijzig iets in het bestand dat je bij de vorige opdracht hebt aangemaakt. Voeg bijvoorbeeld code toe of een comment.

  3. Ga naar het Git tabblad en commit de wijzigingen.

  4. Push de wijzigingen naar GitHub en check of het bestand nu zichtbaar is op GitHub (ververs de pagina eventueel en bekijk op GitHub de juiste branch).

  5. Voer een pull request uit op GitHub en merge de wijzigingen met de main branch.

  6. Alle studenten in de groep voeren nu een pull uit in de main branch om de wijzigingen naar de Git repository op de server te halen. Het gewijzigde bestand moet dan in hun map verschijnen.

Creëer een merge conflict en los het op

In deze opdracht ga je zelf een merge conflict creëren en dat conflict oplossen. Voer hiervoor de volgende stappen uit.

  1. Zorg ervoor dat alle studenten de meest recente versie van de main branch in hun Git repository op de server hebben. Voer hiervoor eventueel een pull uit.

  2. Eén van de studenten maakt een wijziging aan in het bestand via een test branch. Deze student commit en pusht de wijzigingen naar GitHub.

  3. Een andere student wijzigt dezelfde regels in hetzelfde bestand op een andere manier in de main branch. Ook deze student commit en pusht de wijzigingen naar GitHub.

  4. Probeer de test branch te mergen met de main branch. Los het conflict op.

Maak issues aan voor je project

Kijk vooruit naar de opdracht voor jullie project voor de volgende week. Probeer issues te formuleren voor de opdracht. Wijs deze issues ook toe aan de verschillende groepsleden.

Probeer hierbij niet alleen na te denken over code gerelateerde issues, maar ook over issues voor documentatie (comments en readme file).