Tutoriel Git : créer un dépôt sur GitHub ou GitLab et le récupérer en local

Rappel utile avant de commencer, et développé dans l’introduction du tutoriel : Git tourne sur votre machine, GitHub et GitLab ne sont que des hébergeurs de dépôts Git.

Il y a deux façons d’arriver à un projet suivi par Git et relié à GitHub ou GitLab, et le choix dépend uniquement de l’ordre dans lequel les choses existent. Soit le dépôt distant existe déjà et vous le récupérez : c’est cloner. Soit vous avez un dossier sur votre machine et vous le publiez : c’est initialiser puis pousser. Ce chapitre traite les deux cas.

Créer le dépôt distant

Sur GitHub, le bouton New depuis la page d’accueil, ou l’adresse github.com/new. Sur GitLab, New project puis Create blank project.

Trois décisions à prendre au moment de la création.

Le nom. Il devient une partie de l’URL du dépôt. Préférez des minuscules et des tirets, sans accent ni espace.

La visibilité. Public signifie lisible par tout le monde, y compris l’historique complet et donc tout ce que vous y aurez committé par erreur. Privé restreint l’accès aux personnes que vous invitez. Dans le doute, commencez en privé : passer de privé à public plus tard est immédiat, l’inverse n’efface pas ce qui a déjà été copié.

Le fichier README. Cochez la case seulement si vous comptez cloner le dépôt. Si vous avez déjà un dossier à publier, laissez le dépôt entièrement vide, sinon vous devrez réconcilier deux historiques qui n’ont rien en commun.

Choisir entre l’adresse SSH et l’adresse HTTPS

Une fois le dépôt créé, la page vous propose une URL sous deux formes. Elles pointent vers le même dépôt et ne diffèrent que par la méthode d’authentification.

Notez bien la différence de forme : l’adresse SSH utilise deux-points après le nom d’hôte, pas une barre oblique. Et surtout, le domaine change selon le service. C’est une erreur de copier-coller classique que de donner une URL github.com pour un projet hébergé sur GitLab.

Si vous avez posé une clé SSH au chapitre précédent, prenez l’adresse SSH : rien ne vous sera plus jamais demandé. L’adresse HTTPS impose de fournir un jeton d’accès personnel, que le gestionnaire d’identifiants peut mémoriser.

Premier cas : le dépôt existe, vous le clonez

C’est la situation quand vous rejoignez un projet, ou quand vous avez créé le dépôt avec un README.

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

Git crée un dossier projet dans le répertoire courant, y télécharge l’intégralité de l’historique, et place le dépôt distant sous le nom origin. Pour choisir un autre nom de dossier, ajoutez-le en second argument :

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

Vérifiez ce que vous avez obtenu :

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

Deux remarques sur cette sortie. origin apparaît deux fois parce que Git distingue l’adresse de lecture de l’adresse d’écriture, presque toujours identiques. Et la branche s’appelle ici master parce que c’est le nom de la branche par défaut du dépôt cloné : le clonage reprend le nom du serveur et ignore complètement votre réglage init.defaultBranch, qui ne concerne que les dépôts que vous créez vous-même.

Second cas : le dossier existe, vous le publiez

C’est la situation quand vous avez commencé à travailler avant de penser à Git. Placez-vous dans le dossier du projet.

cd ~/projets/ma-boutique
git init

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

Git vient de créer un sous-dossier .git qui contient tout l’historique. Le supprimer reviendrait à supprimer le suivi de version, le reste de vos fichiers n’est pas touché.

Enregistrez ensuite un premier commit, sans quoi il n’y a rien à publier :

git add .
git commit -m "Premier commit"

Déclarez maintenant le dépôt distant et poussez :

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

Ces trois lignes méritent d’être expliquées, parce qu’elles sont souvent recopiées sans être comprises.

git remote add origin associe le nom court origin à l’URL du dépôt. origin n’a rien de magique, c’est une convention, vous pourriez l’appeler autrement, personne ne le fait.

git branch -M main renomme la branche courante en main. Le -M majuscule force le renommage même si une branche main existe déjà. Cette ligne est inutile si vous avez réglé init.defaultBranch au chapitre précédent, mais elle ne fait aucun mal.

git push -u origin main envoie la branche et, grâce à -u, mémorise le lien entre votre branche locale et celle du serveur. C’est ce lien qui permet d’écrire ensuite git push et git pull tout court. Sans lui, Git vous arrête :

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>

Le piège du README coché

Si vous avez créé le dépôt distant avec un README alors que votre dossier local avait déjà des commits, les deux côtés ont chacun leur propre premier commit, sans aucun ancêtre commun. Git refuse alors de les réunir :

fatal: refusing to merge unrelated histories

La solution est de le lui demander explicitement, une seule fois :

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

Les deux historiques sont réunis par un commit de fusion et le README rejoint vos fichiers. Vous pouvez ensuite pousser normalement.

Gérer les dépôts distants

Quelques commandes à connaître pour la suite.

git remote -v                                    # lister les dépôts distants
git remote set-url origin git@github.com:u/p.git # changer l'URL, par exemple passer de HTTPS à SSH
git remote rename origin upstream                # renommer
git remote remove origin                         # détacher

git remote set-url est la commande à retenir : c’est celle qui répare un dépôt cloné en HTTPS que vous voulez basculer en SSH, sans avoir à tout recloner.

Un dépôt local peut vivre sans serveur

Rien ne vous oblige à publier. Un git init suivi de commits fonctionne parfaitement sur un dossier qui ne quittera jamais votre machine, et vous bénéficiez déjà de l’historique et de la possibilité de revenir en arrière. Le dépôt distant apporte trois choses : une sauvegarde ailleurs que sur votre disque, un point de partage avec d’autres, et l’accès aux outils de l’hébergeur.

Votre projet est en place. Le chapitre suivant passe aux commandes du travail quotidien, et à la façon d’annuler une erreur.