3.2 : Créer un dépôt sur la forge et le cloner

Deux situations, deux chemins

Vous arriverez toujours dans l’une de ces deux configurations :

A — Vous partez de la forge. Le dépôt n’existe nulle part, vous le créez sur le serveur puis vous le récupérez. C’est le cas le plus simple, et celui que vous utiliserez le plus souvent une fois la forge en place.

B — Vous avez déjà un dossier local. C’est votre situation actuelle : le TP 1 vous a laissé un dépôt tp1-nordika avec quatre enregistrements, sur votre disque. Il faut maintenant le publier.

Le second chemin comporte un piège que rencontre absolument tout le monde. Nous allons donc le traiter en détail.


Créer le dépôt sur la forge

Depuis l’interface, le bouton + en haut à droite → Nouveau dépôt.

Le propriétaire

Premier champ, premier réflexe à prendre : choisissez l’organisation, pas votre compte personnel.

Souvenez-vous de la leçon 2.9 : un dépôt de travail sous un compte personnel, c’est votre nom dans l’URL, et cette URL finira dans vos stratégies de groupe. Le menu déroulant propose votre compte en premier — ne le laissez pas par défaut.

Le nom

Il apparaîtra dans l’URL. Les mêmes règles que pour les organisations : minuscules, sans accent, tirets plutôt qu’espaces.

https://forge.nordika.local/infrastructure/scripts-powershell
                                            └──────┬───────┘
                                              le nom du dépôt

Un nom descriptif vaut mieux qu’un nom court : scripts-powershell plutôt que ps, stacks-docker plutôt que docker.

La visibilité

Privé par défaut — c’est le comportement que nous avons imposé en 2.4 avec DEFAULT_PRIVATE. Ne le changez que pour les dépôts destinés à la distribution large, comme vu en 2.10.

⚠️ Les cases d’initialisation

Forgejo propose d’initialiser le dépôt avec un fichier README, un .gitignore et une licence.

C’est ici que se joue la différence entre les deux scénarios.

Votre situation Que faire
A — Dépôt neuf Cochez l’initialisation. Un README de départ est confortable.
B — Vous avez déjà un dossier local Ne cochez rien. Laissez le dépôt totalement vide.

Si vous initialisez un dépôt côté serveur alors que vous avez déjà un historique local, vous créez deux historiques indépendants, sans ancêtre commun. Git refusera de les réunir, et vous obtiendrez un message qui a fait perdre du temps à des générations d’utilisateurs.

Nous y venons.


Scénario A — Cloner un dépôt existant

Copiez l’adresse HTTPS proposée sur la page du dépôt, puis :

cd ~/travail
git clone https://forge.nordika.local/infrastructure/scripts-powershell.git
cd scripts-powershell

Git a créé un dossier portant le nom du dépôt, y a placé son contenu, et son historique complet.

Vérifions ce qu’il a configuré tout seul :

git remote -v
origin  https://forge.nordika.local/infrastructure/scripts-powershell.git (fetch)
origin  https://forge.nordika.local/infrastructure/scripts-powershell.git (push)

origin est simplement le nom donné par convention au dépôt distant d’origine. Rien de magique : c’est une étiquette, que vous pourriez renommer. Elle vous évite de retaper l’URL complète à chaque échange.

C’est tout. Vous pouvez travailler.


Scénario B — Publier un dossier local existant

Reprenons le dépôt du TP 1. Il a un historique, mais il ne connaît aucun serveur.

Créez le dépôt vide sur la forge — sans README, sans .gitignore, sans licence — puis, dans votre dossier local :

1. Déclarer le dépôt distant

cd ~/lab/tp1-nordika
git remote add origin https://forge.nordika.local/infrastructure/scripts-powershell.git

Vous venez de dire à votre dépôt local : « le serveur que j’appellerai origin se trouve à cette adresse ».

Vérifiez :

git remote -v

2. Vérifier le nom de la branche

git branch

Si vous avez suivi la leçon 1.6, elle s’appelle main. Sinon, renommez-la pour être cohérent avec la forge :

git branch -M main

3. Publier

git push -u origin main
Enumerating objects: 15, done.
Writing objects: 100% (15/15), 2.31 KiB | 2.31 MiB/s, done.
To https://forge.nordika.local/infrastructure/scripts-powershell.git
 * [new branch]      main -> main
branch 'main' set up to track 'origin/main'.

Rafraîchissez la page du dépôt : vos quatre enregistrements sont là, avec leurs messages, leurs auteurs et leurs dates.

Que fait le -u ?

Il établit un lien de suivi entre votre branche locale main et la branche main du serveur.

Concrètement, sans lui, il faudrait préciser à chaque fois :

git push origin main
git pull origin main

Avec lui, une seule fois suffit — ensuite, git push et git pull savent où aller :

git push
git pull

Vous ne l’utiliserez donc qu’à la première publication d’une branche. Nous en reparlerons en section 4, quand vous créerez d’autres branches.


Le piège des historiques non liés

Voici le message que vous obtiendrez si vous avez coché l’initialisation alors que vous aviez déjà un historique local :

 ! [rejected]        main -> main (fetch first)
error: failed to push some refs
hint: Updates were rejected because the remote contains work that you do
hint: not have locally.

Et si vous tentez un git pull pour arranger les choses :

fatal: refusing to merge unrelated histories

Ce qui se passe réellement

Vous avez deux histoires parallèles qui ne se sont jamais croisées.

   VOTRE DÉPÔT LOCAL              LE DÉPÔT SUR LA FORGE

   4 enregistrements              1 enregistrement
   (vos scripts)                  (le README créé par Forgejo)
        │                                 │
        └──── aucun ancêtre commun ───────┘

Git ne refuse pas par caprice : il n’a aucun moyen de savoir comment ces deux histoires devraient s’articuler. C’est une protection, pas un bug — elle vous empêche de fusionner par erreur deux projets sans rapport.

La bonne solution

Recommencez proprement. Le dépôt sur la forge ne contient qu’un README généré automatiquement : il n’y a rien à sauver.

Supprimez-le depuis Paramètres du dépôt → Supprimer ce dépôt, recréez-le sans rien cocher, puis reprenez au scénario B.

C’est plus rapide que n’importe quel contournement, et vous obtenez un historique propre.

La solution de dépannage

Si le dépôt distant contient réellement quelque chose que vous voulez conserver :

git pull origin main --allow-unrelated-histories

Git fusionnera les deux histoires en créant un point de jonction artificiel. Ça fonctionne, mais votre historique gardera la trace de cette bizarrerie. À réserver aux cas où vous n’avez pas le choix.


Comprendre les branches de suivi

Une notion à installer maintenant, elle vous servira pendant toute la formation.

Après un clone ou un push -u, vous avez en réalité deux références :

Référence Ce qu’elle désigne
main Votre branche locale, celle sur laquelle vous travaillez
origin/main Votre dernière connaissance de la branche du serveur

Le point important est dans le mot « dernière connaissance ». origin/main n’est pas le serveur en direct : c’est un instantané, mis à jour uniquement lorsque vous communiquez avec lui.

git branch -vv
* main a3f9c21 [origin/main] Documentation du rôle de chaque script

La mention entre crochets confirme le lien de suivi.

C’est ce qui permet à Git de vous dire « votre branche est en avance de 2 enregistrements » ou « en retard de 3 » — et c’est aussi pourquoi cette information peut être périmée si vous n’avez pas récupéré depuis un moment. Nous exploiterons cela en 3.4.


Gérer ses dépôts distants

Un dépôt distant n’est qu’une adresse enregistrée sous un nom. Le manipuler ne touche jamais à votre historique : vous ne risquez rien à corriger une URL ou à renommer une étiquette.

Quatre commandes couvrent tous les cas.

Consulter ce qui est déclaré :

git remote -v

Corriger une URL. Le cas le plus fréquent : vous avez cloné avec une mauvaise adresse, ou hérité d’un dépôt dont l’URL contient un jeton — souvenez-vous de la leçon 3.1, c’est exactement ce qu’il ne faut pas faire.

git remote set-url origin https://forge.nordika.local/infrastructure/scripts.git

C’est aussi la commande à utiliser le jour où votre forge change de nom, ou lors d’une migration depuis une autre plateforme.

Renommer une étiquette. Utile lorsqu’un dépôt provient d’ailleurs et que vous voulez clarifier :

git remote rename origin github

Vous pourrez alors ajouter votre forge interne sous le nom origin, ce qui reflète mieux la réalité : votre référence quotidienne devient l’interne, GitHub n’étant plus qu’une destination secondaire.

Ajouter un second dépôt distant. Rien n’oblige à n’en avoir qu’un. C’est le mécanisme qui permet de pousser vers votre forge interne et vers un dépôt public :

git remote add github https://github.com/nordika/scripts.git
git push github main

Nous l’exploiterons dans la partie finale de la formation, pour maintenir automatiquement un miroir public des projets que vous souhaitez partager.

Supprimer une déclaration — quand un dépôt distant n’existe plus, ou après une migration :

git remote remove github

Vous perdez uniquement l’adresse enregistrée. Le dépôt distant lui-même n’est pas touché, et votre historique local non plus.


Les erreurs classiques

Symptôme Cause
remote origin already exists Un dépôt distant est déjà déclaré : utilisez set-url au lieu de add
refusing to merge unrelated histories Le dépôt distant a été initialisé alors que vous aviez déjà un historique
src refspec main does not match any Aucun enregistrement local, ou branche portant un autre nom
Authentication failed Jeton absent ou périmé — voir leçon 3.1
403 Forbidden au push Authentifié, mais sans droit d’écriture : question d’équipe
Repository not found Erreur dans l’URL, ou dépôt privé auquel vous n’avez pas accès
Le clone crée un dossier au mauvais nom Précisez-le : git clone <url> mon-dossier

Ce qu’il faut retenir

  • Créez le dépôt dans l’organisation, jamais sous votre compte personnel.
  • Si vous avez déjà un historique local, créez le dépôt distant totalement vide.
  • git clone récupère le contenu et l’historique, et configure origin tout seul.
  • Pour publier un dossier existant : git remote add, puis git push -u origin main.
  • Le -u établit le lien de suivi : ensuite, git push et git pull suffisent.
  • origin/main est votre dernière connaissance du serveur, pas son état en direct.
  • Face à des historiques non liés, recréez le dépôt vide plutôt que de forcer la fusion.

Dans la leçon suivante

Votre dépôt vit maintenant à deux endroits : sur votre poste et sur la forge. Il est temps d’installer le geste que vous répéterez des milliers de fois.

Nous verrons le cycle complet — modifier, poser sur le plateau, enregistrer, publier — et surtout quand publier : à chaque enregistrement, en fin de journée, ou seulement quand c’est fini ? La réponse n’est pas la même selon que vous travaillez seul ou à plusieurs, et elle a des conséquences directes en section 12, quand un simple envoi déclenchera un déploiement.