From b8f1b7848cf24682eebd5c2f508f4c98249324c3 Mon Sep 17 00:00:00 2001
From: n-peugnet <n.peugnet@free.fr>
Date: Thu, 31 Mar 2022 15:43:27 +0200
Subject: docs: add first git hosting page

---
 services/git.md | 78 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 78 insertions(+)
 create mode 100644 services/git.md

(limited to 'services/git.md')

diff --git a/services/git.md b/services/git.md
new file mode 100644
index 0000000..e00e435
--- /dev/null
+++ b/services/git.md
@@ -0,0 +1,78 @@
+Dépôts Git publics
+==================
+
+Le dossier `git/`, à la racine de l'**espace personnel** est particulier.
+Les dépôts Git rangés dedans seront automatiquement publiés en _lecture seule_
+à l'adresse `https://git.club1.fr`, par exemple :
+
+[`https://git.club1.fr/nicolas/dna-backup/`](https://git.club1.fr/nicolas/dna-backup/)
+&rarr; `/home/nicolas/git/dna-backup/`
+
+Cette adresse permet 2 choses :
+
+1. Cloner le dépôt Git avec `git clone` grâce au
+   [git-http-backend](https://git-scm.com/docs/git-http-backend).
+2. Consulter rapidement le dépôt et le sources dans un navigateur grâce à
+   l'interface web [cgit](https://git.zx2c4.com/cgit/about/).
+
+Tutoriel d'utilisation
+----------------------
+
+Pour utiliser la fonctionnalité de dépôts Git publics sur CLUB1, il faut tout
+d'abord initialiser le dépôt à distance, avec [SSH](ssh), depuis un ordinateur personnel
+(remplacer `<login>` par votre **identifiant** et `<repo>` par le nom que vous
+voulez donner au dépôt) :
+
+    ssh <login>@club1.fr git init --bare git/<repo>
+
+Dès lors, le dépôt est publié en _lecture seule_ à l'adresse
+`https://git.club1.fr/<login>/<repo>`, mais celui-ci est vide pour le
+moment. La branche affichée par défaut dans l'interface web est `master`.
+Il est possible de la changer en modifiant le fichier `HEAD` du dépôt.
+Par exemple pour la remplacer par la branche `main` :
+
+    echo "ref: refs/heads/main" | ssh <login>@club1.fr tee git/<repo>/HEAD
+
+De la même manière, pour modifier la description du dépôt (cette modification
+ne sera pas forcément visible tout de suite à cause du cache de cgit) :
+
+    echo "ma super description" | ssh <login>@club1.fr tee git/<repo>/description
+
+Il y a ensuite deux cas de figure :
+
+- Création d'un nouveau dépôt
+- Publication d'un dépôt existant
+
+### Création d'un nouveau dépôt
+
+Si le but est de créer un nouveau dépôt, alors le plus simple consiste
+à cloner celui-ci sur votre ordinateur personnel.
+On utilise pour cela l'adresse [SSH](ssh) car elle offre un accès en écriture
+au dépôt :
+
+    git clone <login>@club1.fr:git/<repo>
+
+Un avertissement alertera sur le fait que le dépôt ainsi cloné est vide, ce
+qui est normal :
+
+    warning: You appear to have cloned an empty repository.
+
+Il est désormais possible d'utiliser ce dépôt comme tout autre dépôt Git,
+par exemple :
+
+    cd <repo>
+    echo 'Hello World!' >> README
+    git add README
+    git commit -m "add Hello World README"
+    git push origin
+
+
+### Publication d'un dépôt existant
+
+Si le but est de publier un dépôt existant, alors il suffit d'ajouter le
+dépôt distant aux _remotes_ et d'y pousser la branche désirée, par exemple
+pour la branche `main` (l'option `--set-upstream` permet d'en faire la
+_remote_ par défaut pour cette branche) :
+
+    git remote add club1 <login>@club1:git/<repo>
+    git push --set-upstream club1 main
-- 
cgit v1.2.3