Git avec le menu Git

Maintenant que nous sommes connectés à Git, nous pouvons l’utiliser pour contrôler les versions. Comment Git fait-il cela ?

Pour apporter des modifications aux fichiers ou au code sans impacter le code fonctionnel déjà présent dans le référentiel, nous créons des « copies » distinctes du code du référentiel, appelées branches.

• La branche « main » est la branche principale qui contient tout le code le plus à jour et le plus testé

• Chaque fois que vous souhaitez ajouter une nouvelle fonctionnalité ou tester du code, vous créez une nouvelle branche

• La nouvelle branche contient tout le code de « main », mais les modifications apportées à cette branche n’affectent pas « main ».

• Une fois que vous êtes sûr que vos modifications fonctionnent, vous pouvez demander à rajouter vos modifications à « main » dans une demande d’extraction (abordée dans une section ultérieure du guide)

La création de nouvelles branches de travail suit l’un des principes clés de la contribution au code. Il est considéré comme une bonne pratique de conserver tout nouveau travail séparé afin qu’il puisse être testé et révisé avant d’être publié.

Cette section explique comment nous effectuons et obtenons des modifications sur le référentiel. Un diagramme simplifié de nos entités distantes et locales actuelles est présenté dans le diagramme ci-dessus.

Vérifiez que votre fork est à jour

Le moyen le plus rapide de vérifier si votre fork est la dernière version du dépôt d’origine est d’accéder à votre compte GitHub et de consulter vos forks. L’URL du fork peut avoir une structure similaire à :

https://github.com/<your_username>/deafrica-sandbox-notebooks

Si votre fork est en retard, il y aura une bannière en haut de la page indiquant « Cette branche est XYZ commits derrière digitalearthafrica:main. » Un exemple est montré dans l’image ci-dessous.

Dans cet exemple, 12 modifications, ou commits, ont été effectués par d’autres personnes depuis la dernière synchronisation du fork avec l’original.

Pour les rendre à nouveau uniformes, cliquez sur Récupérer en amont, puis sélectionnez Récupérer et fusionner. Vous pouvez « extraire » ces nouvelles mises à jour vers votre clone Sandbox à l’aide du menu Git dans le Sandbox.

Accéder au menu Git

1. Ouvrez le Sandbox et accédez au dossier du clone « deafrica-sandbox-notebooks », dans votre dossier « dev ». Si vous n’avez pas encore configuré le dossier « dev » et le clone du dépôt, veuillez suivre les instructions de la section précédente sur la « connexion à Git <./02_connect_git.ipynb> »__.

Vérifiez que le chemin du fichier en haut de la barre latérale du dossier est /dev/deafrica-sandbox-notebooks/.

2. Cliquez sur l’icône Git dans le menu latéral. Il s’agit d’un losange gris traversé par deux lignes. Cela vous amènera au menu Git.

Menu Git : une décomposition

Le menu Git vous informe sur le référentiel que vous modifiez et vous permet d’accéder aux fonctions de contrôle de version Git les plus courantes. Nous allons passer en revue certains des boutons du menu, puis montrer comment ils sont utilisés à travers un exemple de démonstration que vous pouvez essayer vous-même.

Ne vous inquiétez pas si vous êtes désorienté par tous les éléments du menu. Essayez l’exemple d’exercice ci-dessous : les concepts auront plus de sens lorsque vous les utiliserez.

1. Référentiel actuel : cela m’indique que je suis actuellement dans mon clone de « deafrica-sandbox-notebooks ». Par défaut (et par convention), votre clone aura le même nom que son référentiel parent. Le référentiel actuel est sélectionné par le dossier vers lequel votre navigateur de fichiers est dirigé, c’est pourquoi il était important de vérifier votre chemin de fichier plus tôt.

2. Branche actuelle : cela m’indique que je suis sur la branche « principale ». Cliquez sur la flèche déroulante pour créer une nouvelle branche ou afficher et sélectionner d’autres branches.

3. Extraire les dernières modifications : ceci exécute un Git Pull. Les modifications apportées à la version distante de ce fork (par exemple, si vous avez synchronisé avec le principal via Fetch upstream plus tôt) seront extraites vers ce clone sur le Sandbox. > Si vous n’êtes pas sûr d’avoir extrait toutes les modifications récentes de votre clone, vous devez cliquer sur ce bouton maintenant.

4. Envoyer les modifications validées : lorsque vous avez apporté des modifications au clone local du référentiel, vous pouvez les envoyer à la version distante en « validant la modification », puis en « envoyant ». Le didacticiel d’exemple suivant illustre ces deux actions.

5. Actualisez le référentiel pour détecter les modifications locales et distantes : utilisez ceci pour vérifier que votre menu affiche les informations les plus récentes.

6. Mise en scène : les fichiers répertoriés ici ont été modifiés et ces modifications sont prêtes à être confirmées ou validées. La validation permettra de transférer ces modifications vers le dépôt distant.

7. Modifié : les fichiers dont la version est suivie et qui ont été modifiés s’afficheront ici. Ces modifications n’ont pas encore été validées, elles ne seront donc pas transférées vers le dépôt distant.

8. Non suivi : ces fichiers ne sont pas soumis à un contrôle de version. Ils ne feront partie du dépôt GitHub sur aucune branche. En général, les nouveaux fichiers sont répertoriés ici. En effet, Git ne sait pas encore si les fichiers sont liés à l’une de vos branches.

Les fichiers non suivis sont uniquement stockés sur la mémoire de votre Sandbox. Cette mémoire est sujette à des mises à niveau et des modifications par Digital Earth Africa conformément aux conditions générales de Sandbox, ce qui pourrait affecter vos fichiers. Les fichiers importants doivent être sauvegardés dans au moins un autre emplacement.

Concepts de Git

• Branche : une copie du dépôt. Elle contient tout le code de la branche principale, mais peut être modifiée sans impact sur le dépôt.

• Commit : une « sauvegarde » de vos modifications. Elle confirme qu’il s’agit bien des modifications que vous souhaitez apporter. Seules les modifications validées peuvent être poussées ou extraites des dépôts.

• Pull : récupère les modifications (commits) de la branche distante et les copie dans la branche locale correspondante.

• Push : envoie les commits effectués sur la branche locale à sa branche distante correspondante. Les push et pulls garantissent que les versions locales et distantes du même dépôt sont à jour les unes avec les autres.

• En amont : Le terme utilisé pour indiquer le dépôt suivi par votre fork ou clone. Par exemple, le dépôt original « deafrica-sandbox-notebooks » est en amont de votre fork de ce dépôt. Tous les dépôts n’ont pas d’entité en amont. Dans l’exemple de didacticiel ci-dessous, nous allons créer une branche dans votre clone de dépôt et définir sa branche en amont sur celle de votre fork.

Tutoriel : Utilisez le menu Git pour créer une nouvelle branche et apporter des modifications

Tous les éléments du menu et les nouveaux concepts peuvent être mieux compris en suivant ce tutoriel. Nous utiliserons le menu Git de la barre latérale pour :

• créer une nouvelle branche ;

• ajouter un fichier;

• valider les modifications ; et

• envoyez les modifications au dépôt distant (votre fork sur le site Web GitHub).

Créer une nouvelle branche

1. Dans le menu Git, sélectionnez Nouvelle branche.

2. Nommez votre nouvelle branche (ici nous l’appellerons « git-test »). Pour « Créer une branche basée sur … », sélectionnez « main ». Cela créera une branche qui est une copie exacte de « main ». Sélectionnez Créer une branche pour créer la branche.

3. Nous serons automatiquement déplacés vers la branche. « Branche actuelle » devrait maintenant indiquer « git-test ».

Ajouter un nouveau fichier

1. Sélectionnez l’icône du dossier pour revenir à la vue Dossier. Les fichiers et les dossiers ressembleront exactement à ce qu’ils étaient avant, car vous venez de créer une copie de la branche « main ». Nous allons maintenant modifier quelque chose. Cliquez sur l’icône Notebook > Python 3 dans le lanceur pour créer un nouveau fichier Jupyter Notebook.

2. Le fichier s’ouvrira automatiquement.

3. Tapez quelque chose dans la première cellule du fichier. Ce n’est pas grave si vous ne connaissez pas Python. Dans cet exemple, nous allons saisir print("Ceci est une modification de la branche git-test"). Assurez-vous que le menu déroulant en haut du fichier indique « Code ». Appuyez sur Maj + Entrée sur votre clavier pour exécuter la cellule. Cela imprimera le texte que vous avez saisi sous la cellule de code.

4. Renommons le fichier. Faites un clic droit sur le fichier dans le navigateur de fichiers et sélectionnez Renommer.

5. Tapez votre nouveau nom de fichier. Ici nous l’avons appelé « my-change ». Son extension de fichier est « .ipynb ».

Valider les modifications : suivre les nouveaux fichiers

1. Revenez au menu Git. Il affichera désormais un fichier « non suivi » : votre nouveau fichier Jupyter Notebook !

2. Passez la souris sur le nom du fichier. Un symbole + apparaîtra sur le côté droit. Cliquez sur +. Cela ajoute « my-change.ipynb » à la liste des fichiers « Staged ». Cela signifie que ce fichier est désormais *suivi * ; toutes les modifications seront surveillées. Ceci est en préparation pour que les modifications soient ajoutées au dépôt.

3. Bien que le fichier soit en cours de préparation mais que les modifications ne soient pas encore validées, vous pouvez toujours y apporter des modifications. Revenez à « my-change.ipynb » et ajoutez une autre ligne, comme « print(« Je modifie un fichier en cours de préparation ») ». Maintenant, la lettre à côté du nom du fichier en cours de préparation est passée de « A » (ajouté) à « M » (modifié).

4. Finalisons tous ces changements (le fichier ajouté d’origine ainsi que toutes les modifications) en validant. La validation finalise tous les fichiers intermédiaires modifiés afin que vous puissiez les transférer vers votre fork. Tapez un bref résumé des modifications apportées aux fichiers intermédiaires. Par exemple, « Ajout du fichier my-change ». Cliquez sur Valider.

5. Les modifications validées sont supprimées du menu.

Valider les modifications : définir en amont

Nous y sommes presque ! Il ne nous reste plus qu’à dire à notre branche de pousser le commit vers notre fork. N’oubliez pas que vos modifications se trouvent sur votre clone local du dépôt, tandis que le fork est distant sur votre compte GitHub. Nous allons d’abord lier notre branche à une branche distante correspondante sur le fork. Elles se suivront mutuellement. Lorsque nous pousserons notre modification validée localement, elle ira vers sa branche distante équivalente. Si cela vous semble trop déroutant, n’y réfléchissez pas trop, suivez simplement les étapes.

1. Ouvrez un terminal à partir du navigateur de fichiers. Tapez « git push –set-upstream origin git-test » et appuyez sur « Entrée » sur votre clavier. Il vous demandera vos informations d’identification Git, saisissez-les comme demandé. Dans le terminal, lorsque vous saisissez votre mot de passe ou votre jeton d’accès personnel, le curseur de texte ne bouge pas mais des caractères sont saisis. Pour des raisons de sécurité, vous devez avoir configuré l’authentification multifacteur GitHub ; consultez la page Se connecter à Git pour plus d’informations.

2. Succès ! Vous verrez le message « La branche « git-test » est configurée pour suivre la branche distante « git-test » depuis « origin ». Revenez au menu Git.

Pousser les modifications validées

1. Revenez au menu Git. Cliquez sur l’icône Push commit changes. Elle ressemble à un petit nuage avec une flèche vers le haut à l’intérieur. Saisissez vos identifiants Git comme demandé et cliquez sur OK.

2. Enfin, nous pouvons vérifier si les modifications ont été appliquées. Accédez à votre page de fork GitHub « deafrica-sandbox-notebooks », qui aura une URL similaire à « https://github.com/<your_username>/deafrica-sandbox-notebooks ». Cliquez sur le menu déroulant de la branche en haut de la page. Maintenant, en plus de « main », vous devriez également pouvoir voir et sélectionner « git-test ».

Notez que votre nouveau fichier « my-change.ipynb » n’est pas répertorié sur la branche « main », mais lorsque vous basculez votre vue vers la branche « git-test », il apparaît. Nous avons réussi à effectuer un changement. Félicitations pour avoir franchi toutes ces étapes.

Liste de contrôle Git

Éléments à vérifier lorsque vous vous connectez au Sandbox et commencez à travailler sur votre projet de code open source :

• Avez-vous récupéré et fusionné en amont afin que votre fork soit à jour avec le référentiel d’origine ?

• Sur quelle branche êtes-vous ? Est-ce la bonne branche sur laquelle travailler ?

• Avez-vous extrait et fusionné les dernières modifications apportées à votre clone à partir de votre fork du référentiel ?

Vous pouvez vérifier le premier élément à partir de l’URL de votre fork, ainsi que les deux suivants en accédant au menu Git et en consultant Current Repository et Current Branch.

Problèmes courants

• Impossible de détecter un dépôt Git. Cela peut se produire si vous ne vous êtes pas connecté à Git sur le Sandbox. Suivez les instructions sur connexion à Git. Deuxièmement, vérifiez que votre navigateur de fichiers est dirigé vers votre dossier de clonage. S’il se trouve sur la page d’accueil ou simplement dans le dossier dev, ce ne sont pas des dépôts GitHub.

• Je ne trouve pas mon fichier, mais je sais que j’ai créé un nouveau fichier. Êtes-vous sur la bonne branche ? Si vous passez à une autre branche, votre nouveau fichier peut ne pas apparaître s’il a été suivi dans une autre branche. Par exemple, « my-change.ipynb » ne devrait pas être visible sur la branche « main ».

• J’ai envoyé mes modifications à mon fork, mais je ne les vois pas sur le site Web de GitHub. Avez-vous ajouté et validé les fichiers qui ont été modifiés ? Regardez-vous la branche « main » de votre fork alors que vos modifications se trouvaient en fait sur une branche différente ? « main » est affiché par défaut sur le site Web. Cliquez sur la liste déroulante des branches pour voir les différentes branches de votre fork.

• Je suis « XYZ nombre de commits derrière ``digitalearthafrica:main`` ». Vous n’avez pas récupéré et fusionné les dernières modifications du référentiel d’origine. Cliquez sur le bouton Récupérer en amont sur la page Web GitHub du fork pour récupérer et fusionner les dernières mises à jour. Cliquez ensuite sur le bouton Extraire dans le bac à sable pour mettre à jour votre clone local. Pour minimiser les conflits, cela doit être fait avant de valider les modifications et de les envoyer vers votre fork.

• Git n’accepte pas mon mot de passe Git lorsque des informations d’identification sont demandées. Pour des raisons de sécurité, le Sandbox nécessite un jeton d’accès personnel distinct de votre mot de passe ou une autre forme d’authentification multifacteur. Ils sont simples à configurer. Consultez l’article et le guide officiels de GitHub liés à la page Se connecter à Git.

Prochaines étapes

Expérimentez en apportant des modifications à l’aide du menu Git et familiarisez-vous avec le fonctionnement du suivi des fichiers. Vous pouvez également passer à la partie suivante du didacticiel.

Le menu Git donne accès aux utilisateurs à certaines des fonctions Git les plus courantes. Cependant, pour une flexibilité totale, il est idéal d’utiliser Git à partir du terminal Sandbox. Nous avons déjà utilisé le terminal pour certaines commandes qui ne pouvaient pas être exécutées via le menu. Il se trouve que toutes les commandes Git peuvent être exécutées via le terminal au lieu de cliquer dans les deux sens dans le menu.

Les avantages du Terminal incluent :

• Accès au répertoire complet des commandes Git

• Meilleure surveillance de Git avec la commande « git status »

• Plus de contrôle sur le contrôle des versions de fichiers, y compris l’annulation des validations

• Connaissance des interfaces de type ligne de commande, ce qui est utile pour d’autres tâches administratives non liées à Git dans le Sandbox, et également applicable en dehors du Sandbox

• Moins de clics : tout ce dont vous avez besoin peut être fait depuis le Terminal

Pour les codeurs ou toute personne ayant déjà une expérience de Terminal ou de ligne de commande, c’est la plateforme naturelle à utiliser. Si ces concepts sont nouveaux pour vous, ne vous inquiétez pas ! Ils sont simples à apprendre et nous vous recommandons de les essayer.

Cliquez sur Suivant pour continuer.