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 clonerécupère le contenu et l’historique, et configureorigintout seul.- Pour publier un dossier existant :
git remote add, puisgit push -u origin main. - Le
-uétablit le lien de suivi : ensuite,git pushetgit pullsuffisent. origin/mainest 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.