Git
Chapters ▾ 2nd Edition

6.3 GitHub - Een project onderhouden

Een project onderhouden

Nu we ons op ons gemak voelen met bij te dragen aan een project, laten we het eens van de andere kant bekijken: je eigen project aanmaken, onderhouden en beheren.

Een nieuwe repository aanmaken

Laten we eens een nieuwe repository aanmaken waarmee we de code van ons project delen. Begin met het klikken op de “New repository” knop aan de rechterkant van het dashboard, of vanaf de + knop in de bovenste toolbar naast je gebruikersnaam zoals te zien is in De “New repository” dropdown..

Het ``Your repositories'' gebied.
Figuur 110. Het “Your repositories” gebied.
De ``New repository'' dropdown.
Figuur 111. De “New repository” dropdown.

Dit leidt je naar het “new repository” formulier:

Het ``new repository'' formulier.
Figuur 112. Het “new repository” formulier.

Alles wat je echt moet doen is je project een naam geven, de overige velden zijn volledig optioneel. Voor nu klik je gewoon de “Create Repository” knop en boem - je hebt een nieuwe repository op GitHub, genaamd <gebruiker>/<project_naam>.

Omdat er nog geen code is, zal GitHub je aanwijzigen geven hoe je een gloednieuwe Git repository maakt, of verbindt met een bestaand Git project. We zullen het hier nog niet uitwerken, als je een opfrisser nodig hebt kijk dan nog eens naar Git Basics.

Nu je project op GitHub gehost wordt, kan je het URL aan iedereen geven waarmee je je project wilt delen. Elk project op GitHub is toegankelijk via HTTP als https://github.com/<gebruiker>/<project_naam>, en via SSH als git@github.com:<gebruiker>/<project_naam>. Git kan fetchen van en pushen naar beide URLs, maar toegang wordt bepaald op basis van de gebruikersgegevens van de gebruiker die ze benadert.

Noot

Voor openbare projecten wordt vaak de voorkeur gegeven aan het delen middels de HTTP URL, omdat de gebruiker daarvoor niet perse een GitHub account nodig heeft om het te klonen. Gebruikers moeten wel een account hebben en een geüploade SSH sleutel om je project te benaderen als je ze het SSH URL geeft. De HTTPS variant is exact dezelfde URL die ze in hun browser zouden plakken als ze het project daar zouden willen bekijken.

Medewerkers toevoegen

Als je met andere mensen werkt die je commit toegang wilt geven, moet je ze als “collaborators” toevoegen. Als Ben, Jeff en Louise allemaal GitHub accounts aanvragen, en je wilt ze push toegang geven op jouw repository, kan je ze toevoegen aan je project. Als je dit doet geeft je ze “push” toegang, wat inhoudt dat ze zowel lees als schrijf toegang hebben tot het project en de Git repository.

Klik op de “Settings” link onderaan in de rechter zijkolom.

De repository settings link.
Figuur 113. De repository settings link.

Kies daarna “Collaborators” op het menu aan de linker kant. Daarna type je gewoon een gebruikersnaam in het veld en klikt “Add collaborator.” Je kunt dit zo vaak herhalen als je toegang wilt verlenen aan iedereen die je maar wilt. Als je toegang wilt ontzeggen, klik je gewoon de “X” rechts van de betreffende rij.

Het repository medewerkers veld.
Figuur 114. Repository medewerkers.

Pull Requests beheren

Nu je een project hebt met wat code erin en misschien zelfs een paar medewerkers die ook push toegang hebben, laten we eens behandelen wat je moet doen als je zelf een Pull Request ontvangt.

Pull Requests kunnen komen van een branch in een fork van jouw repository of ze kunnen komen van een andere branch in dezelfde repository. Het enige verschil is dat ze in een fork vaak van mensen komen waar jij niet naar hun branch kan pushen en zij niet naar de jouwe, terwijl bij interne Pull Requests beide partijen over het algemeen de branch kunnen benaderen.

Voor de volgende voorbeelden, laten we aannemen dat jij “tonychacon” bent en dat je een nieuwe Arduino code project genaamd “fade” gemaakt hebt.

Email berichten

Er is nu iemand die een wijziging op je code gemaakt heeft en die je een Pull Request stuurt. Je zou een email bericht moeten krijgen die je over het nieuwe Pull Request bericht en die er ongeveer zo uitziet als Email bericht van een nieuwe Request..

Pull Request email bericht
Figuur 115. Email bericht van een nieuwe Request.

Er zijn een aantal dingen te zien aan deze email. Het geeft je een kleine diffstat — een lijst met bestanden die gewijzigd zijn in de Pull Request en hoezeer ze zijn gewijzigd. Het geeft je een link naar de Pull Request op GitHub. Het geeft je ook een aantal URLs die je vanaf de commando regel kunt gebruiken.

Als je de regel bekijkt waar git pull <url> patch-1 staat, is dit een eenvoudige manier om een remote branch te mergen zonder een remote toe te voegen. We hebben dit kort behandeld in Remote branches uitchecken. Als je wilt, kan je een topic branch maken en ernaar switchen en dit commando aanroepen om de Pull Request wijzigingen erin te mergen.

De andere interessante URLs zijn de .diff en .patch URLs, die zoals je zult vermoeden, de unified diff en patch versies van de Pull Request geven. Je zou technisch gesproken de Pull Request in je werk mergen met zoiets als dit:

$ curl https://github.com/tonychacon/fade/pull/1.patch | git am

Samenwerken op basis van de Pull Request

Zoals behandeld in De GitHub flow, kan je nu een conversatie voeren met de persoon die de Pull Request geopend heeft. Je kunt commentaar geven op specifieke regels code, commentaar geven op hele commits of commentaar geven over de gehele Pull Request; waarbij de GitHub smaak van Markdown overal gebruikt kan worden.

Elke keer als iemand anders commentaar geeft op de Pull Request blijf je e-mails ontvangen zodat je weet dat er activiteit plaatsvindt. Alle betrokkenen krijgen een link naar de Pull Request waar de activiteit op plaatsvindt en je kunt ook direct de mail beantwoorden (reply-to) om commentaar op de Pull Request conversatie te geven.

Antwoord via email
Figuur 116. Antwoorden op de emails worden in de converstatie betrokken.

Zodra de code goed genoeg is en je het wilt mergen, kan je ofwel de code lokaal pullen en mergen met de git pull <url> <branch> syntax die we eerder gezien hebben, of door de fork als remote toe te voegen en dan te fetchen en mergen.

Als de merge triviaal is, kan je ook gewoon de “Merge” knop op de GitHub site klikken. Dit zal een “non-fast-forward” merge uitvoeren, waardoor een merge commit wordt gemaakt zelfs als er een fast-forward merge mogelijk was. Dit houdt in dat hoe dan ook, elke keer als je de merge knop klikt een merge commit gemaakt wordt. Zoals je kunt zien in Merge knop en instructies hoe je een Pull Request handmatig merged., geeft GitHub je al deze informatie als je de hint link klikt.

Merge knop
Figuur 117. Merge knop en instructies hoe je een Pull Request handmatig merged.

Als je besluit dat je het niet wilt mergen, kan je ook gewoon het Pull Request sluiten en de persoon die het geopend heeft krijgt een berichtje.

Pull Request Refs (Pull Request referenties)

Als je te maken hebt met veel Pull Requests en niet elke keer een aantal remotes wilt toevoegen of eenmalige pulls wilt doen, is er een aardige truuk die GitHub je toestaat te doen. Dit is een beetje een truuk voor gevorderden en we zullen de details beter behandelen in De Refspec, maar het kan behoorlijk handig zijn.

GitHub presenteert de Pull Request branches voor een repository als een soort van pseudo-branches op de server. Standaard zal je ze niet krijgen als je kloont, maar ze zijn er wel op een verborgen manier en je kunt ze op een redelijk eenvoudige wijze benaderen.

Om dit te demonstreren, zullen we een low-level (laag niveau) commando (waar vaak aan wordt gerefereerd als een “sanitaire voorziening” (plumbing) commando, waar we meer over zullen lezen in Binnenwerk en koetswerk (plumbing and porcelain)) genaamd ls-remote gebruiken. Dit commando wordt over het algemeen niet gebruikt in de dagelijks Git operaties maar het is handig om te laten zien welke referenties er zich op de server bevinden.

Als we dit commando gebruiken met de “blink” repository die we eerder zagen, krijgen we een lijst van alle branches, tags en andere refernties in de repository.

$ git ls-remote https://github.com/schacon/blink
10d539600d86723087810ec636870a504f4fee4d	HEAD
10d539600d86723087810ec636870a504f4fee4d	refs/heads/master
6a83107c62950be9453aac297bb0193fd743cd6e	refs/pull/1/head
afe83c2d1a70674c9505cc1d8b7d380d5e076ed3	refs/pull/1/merge
3c8d735ee16296c242be7a9742ebfbc2665adec1	refs/pull/2/head
15c9f4f80973a2758462ab2066b6ad9fe8dcf03d	refs/pull/2/merge
a5a7751a33b7e86c5e9bb07b26001bb17d775d1a	refs/pull/4/head
31a45fc257e8433c8d8804e3e848cf61c9d3166c	refs/pull/4/merge

Natuurlijk, als je in je repository bent en je gebruikt git ls-remote origin of welke remote je ook wilt controleren, zal het je iets vergelijkbaars laten zien.

Als de repository op GitHub is en er zijn Pull Requests die open staan, zal je deze referenties krijgen die een prefix refs/pull/ hebben. Dit zijn eigenlijk gewoon branches, maar omdat deze niet onder refs/heads/ vermeld staan krijg je ze normaalgesproken niet als je van de server kloont of fetcht — het proces van fetchen negeert ze gewoonlijk.

Er zijn twee referenties per Pull Request - degene die op /head eindigt wijst naar precies dezelfde commit als de laatste commit in de Pull Request branch. Dus als iemand in onze repository een Pull Request opent en zijn branch heeft de naam bug-fix` en deze wijst naar commit a5a775, dan zal in onze repository geen branch bug-fix aanwezig zijn (omdat deze in hun fork zit), maar we hebben wel pull/<pr#>/head die wijst naar a5a775. Dit betekent dat we relatief eenvoudig in één keer elke Pull Request branch kunnen pullen zonder daarvoor een heleboel remotes hoeven toe te voegen.

Nu kan je iets doen wat lijkt op het direct fetchen van de referentie.

$ git fetch origin refs/pull/958/head
From https://github.com/libgit2/libgit2
 * branch            refs/pull/958/head -> FETCH_HEAD

Dit zegt tegen Git, “Maak contact met de origin remote, en download de ref genaamd refs/pull/958/head.” Git gehoorzaamt trouw, en zal alles downloaden wat je nodig hebt om die ref samen te stellen, en zal een verwijzing naar de commit die je wilt onder .git/FETCH_HEAD zetten. Je kunt daarna een git merge FETCH_HEAD doen in een branch waar je dit in wilt testen, maar dat merge commit bericht zal er wat vreemd uitzien. Daarnaast, als je veel pull requests zal reviewen, wordt dit erg vervelend.

Er is ook een manier om alle pull requests te fetchen en ze up-to-date te houden elke keer als je contact maakt met de remote. Open .git/config in je favoriete editor, en ga op zoek naar de origin remote. Dat zou er zo ongeveer uit moeten zien:

[remote "origin"]
    url = https://github.com/libgit2/libgit2
    fetch = +refs/heads/*:refs/remotes/origin/*

De regel die begint met fetch = is een “refspec.” Het is een manier om namen op de remote te mappen met namen in je lokale .git directory. Deze specifieke zegt tegen Git: "de spullen op de remote die onder refs/heads staan moeten in mijn lokale repository onder refs/remotes/origin worden geplaatst." Je kan deze sectie wijzigen door een andere refspec toe te voegen:

[remote "origin"]
    url = https://github.com/libgit2/libgit2.git
    fetch = +refs/heads/*:refs/remotes/origin/*
    fetch = +refs/pull/*/head:refs/remotes/origin/pr/*

Die laatste regel vertelt Git, “Alle refs die er als refs/pull/123/head uitzien moeten lokaal worden opgeslagen als refs/remotes/origin/pr/123.” Als je dit bestand nu opslaat en een git fetch uitvoert:

$ git fetch
# …
 * [new ref]         refs/pull/1/head -> origin/pr/1
 * [new ref]         refs/pull/2/head -> origin/pr/2
 * [new ref]         refs/pull/4/head -> origin/pr/4
# …

Nu worden alle remote pull request lokaal vertegenwoordigt met refs die zich vrijwel hetzelfde gedragen als tracking branches: ze zijn alleen-lezen, en ze worden geüpdatet als je een fetch doet. Dat maakt het enorm makkelijk om de code van een pull request lokaal uit te checken:

$ git checkout pr/2
Checking out files: 100% (3769/3769), done.
Branch pr/2 set up to track remote branch pr/2 from origin.
Switched to a new branch 'pr/2'

De oplettende lezers tussen jullie zullen de head aan het eind van het remote deel van de refspec hebben opgemerkt. Er is ook een refs/pull/#/merge ref aan de GitHub kant, welke de commit vertegenwoordigt die het resultaat zou zijn als je op de “merge” knop op de site zou klikken. Dit stelt je in staat de merge te testen zelfs voordat je de knop klikt.

Pull Requests op Pull Requests

Je kunt niet alleen Pull Requests openen die de main of master-branch betreffen, je kunt zelfs een Pull Request openen die betrekking heeft op elke willekeurige branch in het netwerk. Je kunt zelfs een Pull Request openen op een andere Pull Request.

Als je een Pull Request ziet die de juiste kant op gaat en je hebt een idee voor een verandering die daarvan afhankelijk is of je weet niet zeker of het een goed idee is, of je hebt domweg geen push-toegang op de doelbranch, kan je een Pull Request direct op de Pull Request openen.

Als je een Pull Request opent, is er een invoerveld bovenaan op de pagina die aangeeft naar welke branch je wilt laten pullen en welke je het van wilt laten pullen. Als je de “Edit” knop rechts van dat invoerveld klikt kan je niet alleen de branches wijzigen, maar ook welke fork.

PR doelen
Figuur 118. Handmatig de Pull Request doelfork en -branch wijzigen.

Hier kan je redelijk eenvoudig aangeven om jouw nieuwe branch in een andere Pull Request te mergen of in een andere fork van het project.

Vermeldingen en meldingen

GitHub heeft ook een redelijk aardig ingebouwde meldingen systeem die handig kan worden als je vragen hebt of terugkoppeling wilt van specifiek individuen of teams.

In elk commentaar kan je een @ teken typen en een automatische aanvulling met de namen en gebruikersnamen van mensen die medewerkers of bijdragers in het project zal beginnen.

Vermeldingen
Figuur 119. Begin @ te typen om iemand te vermelden.

Je kunt ook een gebruiker vermelden die niet in die dropdown staat, maar vaak kan de automatische aanvuller het sneller maken.

Als je eenmaal een commentaar hebt gepost met een gebruikersvermelding, zal die gebruiker een berichtje krijgen. Dat houdt in dat dit een erg effectieve manier is om iemand in een discussie te betrekken in plaats van ze actief hierop te laten controleren. Het gebeurt heel vaak op GitHub dat mensen via Pull Requests anderen in hun team of bedrijf erbij betrekken om een Issue of Pull Request te laten reviewen.

Als iemand vermeld wordt in een Pull Request of Issue, worden ze erop “geabonneerd” en blijven meldingen krijgen voor elke activiteit die erop plaatsvindt. Je wordt ook geabonneerd op iets wat je geopend hebt, als je een repository volgt of als je ergens commentaar op geeft. Als je niet langer deze meldingen wilt krijgen, is er een “Unsubscribe” (Afmeld) knop op de pagina die je kunt klikken om de meldingen te stoppen.

Afmelden
Figuur 120. Afmelden van een Issue of Pull Request.

De meldingen pagina

Als we hier over “meldingen” spreken in de context van GitHub, bedoelen we de specifieke manier waarop GitHub probeert om met je in contact te blijven als er gebeurtenissen zijn en er zijn een aantal manieren waarop je dit kunt configureren. Als je naar de “Notification center” tab van de instellingen pagina gaat, kan je een aantal opties zien die je hebt.

Notification center
Figuur 121. Notification center opties.

De twee keuzes zijn om de berichten via “Email” en via “Web” te ontvangen en je kunt een van twee, geen of beide selecteren als je actief deelneemt aan zaken en voor activiteiten op repositories die je volgt.

Web Meldingen

Web meldingen bestaan alleen binnen GitHub en je kunt ze alleen op GitHub controleren. Als je deze optie geselecteerd hebt in je voorkeuren en een bericht wordt voor je gemaakt, zie je een kleine blauwe stip boven je meldingen ikoon boven in je scherm zoals getoond in Notification center..

Notification center
Figuur 122. Notification center.

Als je hierop klikt, zal je een lijst met alle items zien waar je voor wordt bericht, gegroepeerd per project. Je kunt de meldingen van een specifiek project filtreren door op de naam te klikken in de kolom links. Je kunt ook de meldingen bevestigen door het vink-ikoon te klikken naast elke melding, of alle meldingen in een project bevestigen door de vink boven in de groep te klikken. Er is ook een demp (mute) knop naast elke vinkteken die je kunt klikken om geen enkel bericht meer voor dat bericht te ontvangen.

Al deze instrumenten zijn erg handig voor het afhandelen van grote aantallen meldingen. Veel gevorderde GitHub gebruikers zullen eenvoudigweg alle email berichten uitschakelen en al hun meldingen via dit scherm afhandelen.

E-mail meldingen

E-mail meldingen zijn de andere manier waarop je berichten kunt afhandelen via GitHub. Als je deze ingeschakeld hebt, krijg je per melding een e-mail. We hebben hiervan voorbeelden gezien in Email berichten en Email bericht van een nieuwe Request.. De e-mails zullen ook juist geketend (threaded) worden, wat handig is als je een zgn. threading e-mail client gebruikt.

Er zit ook een behoorlijke hoeveelheid metadata in de headers van de e-mails die GitHub je stuurt, deze kunnen heel handig zijn voor het inrichten van zelfgemaakte filters en regels.

Bijvoorbeeld, als we een kijkje nemen naar de daadwerkelijke e-mail headers die aan Tony zijn gestuurd in de e-mail in Email bericht van een nieuwe Request., zullen we hetvolgende zien in de gestuurde gegevens:

To: tonychacon/fade <fade@noreply.github.com>
Message-ID: <tonychacon/fade/pull/1@github.com>
Subject: [fade] Wait longer to see the dimming effect better (#1)
X-GitHub-Recipient: tonychacon
List-ID: tonychacon/fade <fade.tonychacon.github.com>
List-Archive: https://github.com/tonychacon/fade
List-Post: <mailto:reply+i-4XXX@reply.github.com>
List-Unsubscribe: <mailto:unsub+i-XXX@reply.github.com>,...
X-GitHub-Recipient-Address: tchacon@example.com

Hier zijn een aantal interessante dingen. Als je e-mails wilt vlaggen of routeren naar dit specifieke project of zelfs Pull Request, geeft de informatie in Message-ID je alle gegevens in <user>/<project>/<type>/<id> formaat. Als dit bijvoorbeeld een issue zou zijn zou het <type> veld “issues” zijn niet “pull”.

De List-Post en List-Unsubscribe velden houden in dat als je een mail client hebt die deze velden begrijpt, je eenvoudig een bericht kan sturen naar de thread of ervan kunt “Unsubscriben”. Dat zou effectief hetzelfde zijn als de “mute” knop klikken op de web versie van de melding of “Unsubscribe” op het Issue of Pull Request pagina zelf.

Het is ook de moeite om te vermelden dat als je zowel e-mail als web meldingen aan hebt staan en je de e-mail versie van de melding gelezen hebt, de webversie ook als gelezen wordt gemarkeerd als je het laden van plaatjes toestaat in je mail client.

Speciale Bestanden

Er zijn een aantal speciale bestanden die GitHub zal opmerken als ze in je repository staan.

README

Het eerste is de README file, die kan ongeveer elk formaat hebben die GitHub herkent als vrije tekst. Bijvoorbeeld het zou README, README.md, README.asciidoc, etc. kunnen zijn. Als GitHub een README bestand in je broncode vindt, zal het dit op de ingangspagina van het project tonen.

Veel teams gebruiken dit bestand om alle relevante project informatie te bevatten ter informatie voor iemand die nieuw is binnen de repository of het project. Meestal bevat het zaken als:

  • Waartoe dient het project

  • Hoe deze te configureren en te installeren

  • Een voorbeeld hoe het te gebruiken of het aan te lopen te krijgen

  • De licentie waaronder het project wordt aangeboden

  • Hoe er aan bij te dragen

Omdat GitHub dit bestand toont, kan je plaatjes of links er in opnemen voor het verhogen van het begrip.

CONTRIBUTING

Het andere speciale bestand dat GitHub herkent is het CONTRIBUTING bestand. Als je een bestand genaamd CONTRIBUTING met een willekeurige extentie, zal GitHub Een Pull Request openen als er een CONTRIBUTING file bestaan. tonen als iemand een Pull Request gaat openen.

Contributing melding
Figuur 123. Een Pull Request openen als er een CONTRIBUTING file bestaan.

Het idee hierachter is dat je specifieke zaken kunt aangeven die je wel of niet wilt in een Pull Request die aan je project wordt gestuurd. Op deze manier zouden mensen de richtlijnen misschien echt lezen voordat ze een Pull Request openen.

Project Beheer

Over het algemeen zijn er niet veel beheersmatige zaken die je kunt doen met een enkel project, maar er zijn een aantal dingen die van belang kunnen zijn.

De standaard branch wijzigen

Als je een branch anders dan “master” gebruikt als je standaard branch waarvan je wilt dat mensen er Pull Requests op openen of die ze standaard zien, kan je dat in de instellingen pagina van je repository wijzigen onder de “Options” tab.

Standaard branch
Figuur 124. De default branch van een project wijzigen.

Eenvoudigweg de standaard branch in de dropdown wijzigen en dat wordt vanaf dat moment de standaard-branch voor alle belangrijke handelingen, inclusief welke branch er standaard uitgechecked wordt als iemand de repository kloont.

Een project overdragen

Als je een project wilt overdragen aan een andere gebruiker of organisatie in GitHub, is er een “Transfer ownership” optie onderaan dezelfde “Options” tab van de instellingen pagina van je repository die je dat kan laten doen.

Overdragen
Figuur 125. Draag een project over aan een andere GitHub gebruiker of organisatie.

Dit is handig als je een project verlaat en iemand anders wilt het overnemen, of je project wordt groter en je wilt het in een organisatie onderbrengen.

Niet alleen verplaatst dit de repostory met al zijn volgers en sterren naar een andere plaats, het richt ook een redirect (doorverwijzing) van jouw URL naar de nieuwe plaats. Het zal ook de clones en fetches van Git doorverwijzen, niet alleen de web-aanvragen.

scroll-to-top