Git est un outil de contrôle de version, c'est à dire qu'il permet de garder en mémoire toutes les versions successives de tous les fichiers d'un projet. Il permet aussi d'envoyer vos modifications aux autres, et de recevoir les leurs, en passant par le "dépôt" central qui est stocké sur internet (sur https://git.vhelio.org/vhelio/vheliotech-freecad).

Obtenir les droits d'écriture

Si vous êtes adhérent à l'association Vélo solaire pour tous, il faut demander à l'administrateurs pour obtenir les droits d'écriture. Commencez pas créer un compte, puis vous pouvez par exemple demander sur le canal "CAO" sur nextcloud Talk.

Si vous souhaitez contribuer sans adhérer à l'association, vous pouvez envoyer des pull-request en vous inscrivant sur gitea. Il faudra ensuite faire un "fork" du dépôt git, dans lequel vous pourrez envoyer vos modifications, et finalement vous pourrez envoyer des "pull-request" pour demander à ce que vos modifications soient intégrées dans le dépôt principal. Il n'y a pas encore de tutoriel pour cela, n'hésitez pas à vous manifester si vous avez besoin d'aide (vous pouvez envoyer un e-mail à contact@vhelio.org)

Installation de git

Si vous avez l'habitude de travailler en ligne de commande, vous pouvez suivre par exemple ce Tutoriel git.

Si vous n'avez pas l'habitude de travailler en ligne de commande, il sera probablement plus simple d'utiliser une interface graphique. Il y a de nombreux logiciels proposant cela, dans ce wiki nous ne donnons qu'un exemple parmi d'autres.

Sous Linux

Pour Linux, nous proposons d'utiliser Git Cola (si vous utilisez Windows, passez directement à la section suivante)

Votre distribution Linux permet probablement d'installer des paquets, cherchez et installez le paquet "git-cola". À titre d'exemple, si votre système est Debian, il faut lancer le gestionnaire de paquet Synaptic, cliquer sur "Rechercher" en haut à droite, écrire "git-cola" puis cliquer sur "rechercher". Le paquet "git-cola" devrait s'afficher. Cliquer sur le petit carré à gauche de "git-cola" et choisir "sélectionner pour installation", puis "ajouter à la sélection". Finalement, cliquer sur "Appliquer" dans le menu du haut.

Il devrait ensuite être possible de lancer Git Cola avec le menu habituel dans lequel se trouvent vos applications.

Sous Windows

Téléchargez le fichier zip contenant l'installeur de Git Cola sur ce site : https://github.com/git-cola/git-cola/releases/ . Le fichier devrait avoir un nom se terminant par "windows.zip".

Exécuter le fichier qui se trouve à l'intérieur. Suivez les instructions de l'installateur.

Il devrait ensuite être possible de lancer Git Cola à partir du "menu démarrer".

Utilisation de Git Cola

Cloner le projet

Pour commencer, il faut "cloner" le projet, c'est à dire faire une copie du projet sur votre ordinateur. Après avoir lancé Git Cola, cliquez sur "Cloner..."

Entrez l'URL du dépôt https://git.vhelio.org/vhelio/vheliotech-freecad.git puis cliquez sur "Cloner". Dans la fenêtre qui s'ouvre, choisissez le dossier où le projet sera stocké sur votre ordinateur (un sous-dossier sera ajouté à l'emplacement que vous choisirez).

Le projet va être cloné (tous les fichiers ainsi que leur historique, c'est à dire toutes les versions successives, sont maintenant stockés sur votre ordinateur). La fenêtre principale s'ouvre, dans laquelle la zone Statut indique les modifications que vous avez apportées. Pour l'instant, cette zone est donc vide.

Configurer son identité

Avant de continuer, il faut indiquer votre identité au système (les modifications que vous enverrez seront faites à ce nom). Dans le menu "Fichier" -> "Préférences", en restant sur l'onglet "Tous les dépôts" pour que votre identité soit prise en compte aussi dans les autres dépôts (le cas échéant), entrez votre nom et votre adresse e-mail.

En ce qui concerne cette identité, plusieurs choses sont à savoir :

Si vous souhaitez que vos modifications soient associées à votre compte sur git.vhelio.org, il faut indiquer la même adresse e-mail que vous avez utilisé lors de votre inscription sur gitea. Une autre option est d'utiliser votre nom d'utilisateur gitea et d'ajouter @noreply.locahost. Par exemple si votre nom gitea est "lisa" alors l'email "lisa@noreply.localhost" permettra d'associer les commits avec votre compte gitea.
Le nom indiqué s'affiche sur git.vhelio.org et est donc exposé aux moteurs de recherche sur internet etc. L'adresse e-mail en revanche ne s'affiche nulle part sur le site internet. Elle reste malgré tout une donnée publique, puisqu'il suffit de cloner le projet avec git pour la consulter. Il est peu probable que des spammeurs aillent chercher des adresses e-mail par ce moyen, mais techniquement ce n'est pas impossible.
Il n'y a pas d'obligation d'indiquer ni votre vrai nom, ni une adresse e-mail réelle ; dans tous les cas vous pourrez envoyer vos modifications. Mais si vous le faites de façon anonyme, vous perdez nécessairement la propriété intellectuelle de votre travail (puisque vous ne pourrez pas prouver que c'est vous qui l'avez fait).
Dans tous les cas, il est interdit d'usurper l'identité de quelqu'un d'autre.

Une fois terminé, cliquez sur "Fermer".

Envoyer vos modifications

Imaginons maintenant que vous ayez ajouté deux nouveaux fichiers (Non suivi), et modifié un autre (Modifié). La fenêtre affichera alors ceci (si besoin, appuyer sur CTRL+R pour rafraichir Git Cola).

À ce stade, il est possible de choisir quelles modifications envoyer. Git fonctionne en deux temps : d'abord on commit, ce qui signifie que vous créer une nouvelle version du projet. Mais elle ne sera stockée que sur votre ordinateur. Vous pouvez faire plusieurs commit (en crééant donc une nouvelle version à chaque fois), et cela permet aussi de revenir à une version précédente en cas de problème. La deuxième étape est de faire un push (pousser), ce qui envoie vos commit sur le dépôt git (ce n'est qu'à ce moment que les autres personnes verront vos modifications).

La première étape est donc de faire un commit. Sélectionnez les fichiers à utiliser pour cette nouvelle version (utilisez les touches SHIFT et CTRL pour les sélections multiples) puis faites un clic droit et choisissez "pré-commit". Tout ce qui apparait avec un triangle vert est prêt à intégrer dans le commit. En général, on met tous les fichiers pour envoyer tout le travail effectué. Il faut ensuite écrire une description des modifications dans le champ "Résumé du commit", éventuellement ajouter des détails en dessous, puis cliquer sur "Commiter".

La seule indication sur la fenêtre principale permettant de savoir que le commit a été créé est la petite flèche à droite. Une flèche vers le haut indique que vous avez une version sur votre ordinateur qui est prête à envoyer vers le dépôt. Vous pouvez tout a fait continuer à faire des modifications et des commits, et tout cela est possible sans connexion internet.

La seconde étape est d'envoyer le commit sur le dépôt git. On appelle ça un push (pousser). Il faudra cette fois être connecté à internet. Il faut utiliser le menu "Actions" -> "Pousser...". Il n'y a rien à changer dans la fenêtre qui s'ouvre, il suffit de cliquer sur "Pousser" en bas à droite.

Votre nom d'utilisateur et mot de passe seront demandé, il faut donner vos identifiants de git.vhelio.org (ils ne seront pas publiés, c'est juste pour vérifier que vous avez le droit de modifier le dépôt). Une fois terminé, la petite flèche vers le haut doit disparaitre, puisque tout a été envoyé sur le dépôt.

Recevoir les modifications des autres

La dernière opération courante avec git est de récupérer ce que les autres ont fait. Il faut pour cela faire un pull (tirer). Utilisez le menu "Actions" -> "Tirer...". Il n'y a rien à changer dans cette fenêtre, il suffit de cliquer sur "Tirer" en bas à droite.

C'est tout, le projet est maintenant mis à jour avec la dernière version connue du dépôt.

Gestion des conflits

Si vous n'avez pas de chance, un conflit peut se produire, soit au moment d'un push, soit au moment d'un pull. Cela se produit si vous avez modifié les mêmes fichiers que quelqu'un d'autre en même temps (c'est à dire avant que l'autre personne n'ait récupéré vos modifications). La procédure pour gérer un conflit n'est pas encore détaillée, en cas de problème n'hésitez pas à demander de l'aide sur nextcloud Talk (par exemple dans la discussion "Outils collaboratifs" ou "CAO").