Git-tutorial: een repository aanmaken op GitHub of GitLab

Handig om vooraf te weten, en verder uitgewerkt in de inleiding van deze tutorial: Git draait op je eigen machine, GitHub en GitLab zijn alleen maar hosters van Git-repository’s.

Er zijn twee manieren om bij een project te komen dat door Git wordt gevolgd en aan GitHub of GitLab hangt, en de keuze hangt alleen af van de volgorde waarin de dingen bestaan. Of de remote repository bestaat al en je haalt hem op: dat is clonen. Of je hebt een map op je machine en je publiceert die: dat is initialiseren en dan pushen. Dit hoofdstuk behandelt allebei de gevallen.

De remote repository aanmaken

Op GitHub is dat de knop New op de startpagina, of het adres github.com/new. Op GitLab kies je New project en daarna Create blank project.

Op het moment van aanmaken neem je drie beslissingen.

De naam. Die wordt onderdeel van de URL van de repository. Gebruik bij voorkeur kleine letters en koppeltekens, zonder accenten of spaties.

De zichtbaarheid. Public betekent leesbaar voor iedereen, inclusief de volledige historiek en dus alles wat je er per ongeluk in hebt gecommit. Private beperkt de toegang tot de mensen die je uitnodigt. Bij twijfel begin je private: later van private naar public gaan is een kwestie van seconden, andersom wis je niet wat al gekopieerd is.

Het README-bestand. Vink dat vakje alleen aan als je van plan bent de repository te clonen. Heb je al een map om te publiceren, laat de repository dan helemaal leeg, anders moet je straks twee historieken verzoenen die niets gemeen hebben.

Kiezen tussen het SSH- en het HTTPS-adres

Zodra de repository bestaat, biedt de pagina je een URL in twee vormen aan. Ze wijzen naar dezelfde repository en verschillen alleen in de manier van authenticeren.

Let goed op het verschil in vorm: het SSH-adres zet een dubbele punt achter de hostnaam, geen schuine streep. En vooral: het domein verandert mee met de dienst. Een github.com-URL opgeven voor een project dat op GitLab staat, is een klassieke kopieerfout.

Heb je in het vorige hoofdstuk een SSH-sleutel klaargezet, neem dan het SSH-adres: er wordt je nooit meer iets gevraagd. Het HTTPS-adres verlangt een personal access token, die je credential manager kan onthouden.

Geval één: de repository bestaat en je cloont hem

Dat is de situatie wanneer je bij een project komt, of wanneer je de repository met een README hebt aangemaakt.

git clone git@github.com:utilisateur/projet.git

Git maakt een map projet in de huidige map, downloadt daar de volledige historiek naartoe en zet de remote repository klaar onder de naam origin. Wil je een andere mapnaam, geef die dan als tweede argument mee:

git clone git@github.com:utilisateur/projet.git mon-dossier

Controleer wat je gekregen hebt:

cd projet
git remote -v
git branch --show-current

origin	https://github.com/git/git.git (fetch)
origin	https://github.com/git/git.git (push)
master

Twee opmerkingen bij die uitvoer. origin staat er twee keer omdat Git het leesadres en het schrijfadres apart houdt, die vrijwel altijd hetzelfde zijn. En de branch heet hier master omdat dat de standaardbranch van de gecloonde repository is: bij het clonen neemt Git de naam van de server over en negeert het je instelling init.defaultBranch volledig, die alleen geldt voor repository’s die je zelf aanmaakt.

Geval twee: de map bestaat en je publiceert hem

Dat is de situatie wanneer je al aan het werk was voordat je aan Git dacht. Ga naar de map van het project.

cd ~/projets/ma-boutique
git init

Initialized empty Git repository in /root/a2/.git/

Git heeft zojuist een submap .git aangemaakt met de volledige historiek erin. Die map verwijderen komt neer op het versiebeheer weggooien, de rest van je bestanden blijft ongemoeid.

Leg daarna een eerste commit vast, want anders valt er niets te publiceren:

git add .
git commit -m "Premier commit"

Declareer nu de remote repository en push:

git remote add origin git@github.com:utilisateur/ma-boutique.git
git branch -M main
git push -u origin main

Die drie regels verdienen uitleg, want ze worden vaak overgetypt zonder begrepen te worden.

git remote add origin koppelt de korte naam origin aan de URL van de repository. Er is niets magisch aan origin, het is een conventie, je mag hem anders noemen, maar niemand doet dat.

git branch -M main hernoemt de huidige branch naar main. De hoofdletter -M forceert de hernoeming, ook als er al een branch main bestaat. Deze regel is overbodig als je in het vorige hoofdstuk init.defaultBranch hebt ingesteld, maar hij doet geen kwaad.

git push -u origin main stuurt de branch door en onthoudt dankzij -u het verband tussen je lokale branch en die op de server. Dat verband is wat je daarna toelaat om kortweg git push en git pull te typen. Zonder dat verband houdt Git je tegen:

fatal: No configured push destination.
Either specify the URL from the command-line or configure a remote repository using

    git remote add <name> <url>

and then push using the remote name

    git push <name>

To push to multiple remotes at once, configure a remote group using

    git config remotes.<groupname> "<remote1> <remote2>"

and then push using the group name

    git push <groupname>

De valkuil van het aangevinkte README

Heb je de remote repository met een README aangemaakt terwijl je lokale map al commits had, dan heeft elke kant zijn eigen eerste commit, zonder gemeenschappelijke voorouder. Git weigert ze dan samen te voegen:

fatal: refusing to merge unrelated histories

De oplossing is het hem één keer expliciet te vragen:

git pull origin main --allow-unrelated-histories

Merge made by the 'ort' strategy.
 README.md | 1 +
 1 file changed, 1 insertion(+)
 create mode 100644 README.md

De twee historieken worden door een merge-commit samengebracht en het README komt bij je bestanden terecht. Daarna kun je gewoon pushen.

Remotes beheren

Een paar commando’s die je voor het vervolg moet kennen.

git remote -v                                    # de remotes tonen
git remote set-url origin git@github.com:u/p.git # de URL wijzigen, bijvoorbeeld van HTTPS naar SSH
git remote rename origin upstream                # hernoemen
git remote remove origin                         # loskoppelen

git remote set-url is het commando om te onthouden: daarmee repareer je een repository die je over HTTPS hebt gecloond en die je naar SSH wilt omzetten, zonder alles opnieuw te clonen.

Een lokale repository kan prima zonder server

Niets verplicht je om te publiceren. Een git init gevolgd door commits werkt uitstekend voor een map die je machine nooit verlaat, en je hebt dan al een historiek en de mogelijkheid om terug te gaan. De remote repository voegt drie dingen toe: een back-up ergens anders dan op je schijf, een plek om met anderen te delen, en toegang tot de tools van de hoster.

Je project staat klaar. Het volgende hoofdstuk gaat over de commando’s van het dagelijkse werk, en over hoe je een fout terugdraait.