Git avec le menu Git

Now we’ve connected to Git, we can use it to version control. How does Git do this?

To make file or code changes without impacting working code already on the repository, we make separate « copies » of the repository code, called branches.

  • La branche master est la branche principale qui contient tout le code le plus à jour et testé.

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

  • La nouvelle branche contient tout le code de master, mais toute modification apportée à cette branche n’affecte pas master.

  • Une fois que vous êtes sûr que vos modifications fonctionnent, vous pouvez demander à ce qu’elles soient ajoutées à master dans une demande de révision (traitée dans une section ultérieure du guide).

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

Mécanismes de traction et de poussée dans Git

Cette section couvre la façon dont nous faisons et obtenons des changements sur le référentiel. Un schéma simplifié de nos entités locales et distantes actuelles est présenté dans le diagramme ci-dessus.

Vérifiez que votre fourchette est à jour

Le moyen le plus rapide de vérifier que votre fork est la dernière version du repo original est d’aller sur votre compte GitHub et de regarder vos forks. L’URL du fork peut avoir une structure similaire à :

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

If your fork is behind, there will be a banner at the top of the page saying « This branch is XYZ commits behind digitalearthafrica:master. » An example is shown in the image below.

Cette branche est en retard de 12 commits.

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

To make them even again, click Fetch upstream, then select Fetch and merge. You can « pull » those new updates to your Sandbox clone using the Git menu in the Sandbox.

Accéder au menu Git

  1. Ouvrez le Sandbox et naviguez vers le 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.

    Vérifiez que le chemin d’accès au fichier en haut de la barre latérale du dossier est « /dev/deafrica-sandbox-notebooks/ ».

Sélectionnez le menu Git.

  1. Cliquez sur l’icône Git dans le menu latéral. Il s’agit d’un losange gris traversé par deux lignes. Vous accédez ainsi au menu Git.

Menu Git.

Le menu Git : une ventilation

Le menu Git vous informe sur le dépôt que vous éditez 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.

Don’t be concerned if you are confused by all the menu items. Try the example exercise below: the concepts will make more sense when you use them.

Parties du menu Git.

  1. Dépôt actuel: Ceci 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 dépôt actuel est sélectionné par le dossier vers lequel votre navigateur de fichiers est dirigé, c’est pourquoi il était important de vérifier le chemin de vos fichiers plus tôt.

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

  3. Tirer les derniers changements: Ceci exécute un Git Pull. Les modifications apportées à la version distante de cette bifurcation (par exemple, si vous vous êtes synchronisé avec le master via Fetch upstream plus tôt) seront transférées vers ce clone dans l’Environnement de test. > Si vous n’êtes pas sûr d’avoir tiré toutes les modifications récentes vers votre clone, vous devriez cliquer sur ce bouton maintenant.

  4. Push committed changes: When you have made changes to the local clone of the repository, you can send them to the remote version by « committing the change », then « pushing ». The following example tutorial will demonstrate both those actions.

  5. Rafraîchir le référentiel pour détecter les changements locaux et distants: Utilisez ceci pour vérifier que votre menu affiche les dernières informations.

  6. Staged: Les fichiers listés ici ont été modifiés, et ces changements sont prêts à être confirmés, ou commit. La validation permettra à ces changements d’être poussés vers le dépôt distant.

  7. Changed: Les fichiers qui font l’objet d’un suivi de version, et qui ont été modifiés, apparaîtront ici. Ces changements ne sont pas encore validés, ils ne seront donc pas poussés vers le dépôt distant.

  8. Untracked: These files are not being version controlled. They will not be part of the GitHub repo on any branch. Generally, new files are listed here. This is because Git doesn’t know yet whether the files are related to any of your branches.

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

Concepts de Git

  • Branche: Une copie du dépôt. Elle contient tout le code de la branche principale ou ``master`”, mais peut être éditée sans impacter le dépôt.

  • Commit: A « save » of your changes. It confirms these are the changes you want to make. Only committed changes can be pushed or pulled from repos.

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

  • Push: Envoie les commits effectués sur la branche locale vers la branche distante correspondante. Le push et le pulls permettent de s’assurer que les versions locales et distantes d’un même repo sont à jour les unes par rapport aux autres.

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

Tutoriel : Utiliser le menu Git pour créer une nouvelle branche et effectuer 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 changements ; et

  • pousser les changements vers le repo distant (votre fork sur le site GitHub).

Créer une nouvelle branche

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

Créer une nouvelle branche

  1. Name your new branch (here we will call it git-test). For « Create branch based on… », select master. This will create a branch which is an exact copy of master. Select Create Branch to create the branch.

Créer une nouvelle branche

  1. We will automatically be moved onto the branch. « Current Branch » should now say git-test.

Ajouter un nouveau fichier

  1. Sélectionnez l’icône du dossier pour revenir à la vue Dossier. Les fichiers et les dossiers seront exactement comme avant, parce que vous venez de créer une copie de la branche « master ». Maintenant, nous allons changer quelque chose. Cliquez sur l’icône Notebook > Python 3 dans le Lanceur pour créer un nouveau fichier Jupyter Notebook.

Retourner à la vue des dossiers

  1. Le fichier s’ouvre automatiquement.

Créer un nouveau fichier

  1. Type something in the first cell of the file. It’s okay if you don’t know any Python. In this example, we will enter print("This is a change to the git-test branch"). Ensure the dropdown menu at the top of the file says « Code ». Press Shift + Enter on your keyboard to execute the cell. This will print the text you entered underneath the code cell.

Tapez quelque chose dans le fichier.

  1. Let’s rename the file. Right-click on the file in the file browser and select Rename.

Renommer le fichier

  1. Tapez le nom de votre nouveau fichier. Ici, nous l’avons appelé « ma-modification ». Il porte l’extension .ipynb.

Le fichier est renommé.

Commit changes : track new files

  1. Go back to the Git menu. Now it will show one « Untracked » file - your new Jupyter Notebook file!

Le fichier est renommé.

  1. Hover over the file name with your mouse. A + symbol will appear on the right-hand side. Click +. This adds my-change.ipynb to the « Staged » file list. This means this file is now tracked; all changes will be monitored. This is in preparation for changes to be added back to the repo.

Le fichier est renommé.

  1. Tant que le fichier est indexé mais que les modifications ne sont pas encore validées, vous pouvez encore le modifier. Retournez dans my-change.ipynb et ajoutez une autre ligne, comme print("I am changing a staged file"). Maintenant, la lettre à côté du nom du fichier indexé est passée de « A » (ajouté) à « M » (modifié).

Modifier un fichier mis à disposition.

Le fichier est renommé.

  1. Let’s finalise all these changes (the original added file plus any modifications) by committing. Committing finalises any changes staged files so you can push the changes to your fork. Type a short summary of the changes made to staged files. For example, « Added my-change file. » Click Commit.

Le fichier est renommé.

  1. Les changements validés sont supprimés du menu.

Les changements échelonnés ont été supprimés.

Commit changes : set upstream

We are almost there! Now we just need to tell our branch to push the commit to our fork. Remember, your changes are on your local clone of the repo, while the fork is remote on your GitHub account. We will first link our branch to a corresponding remote branch on the fork. They will track each other. When we push our locally commited change, it will go to its equivalent remote branch. If this is too confusing, don’t overthink it, just follow the steps.

Diagramme de la branche locale distante de Github.

  1. Open a Terminal from the File Browser. Type in git push --set-upstream origin git-test and press Enter on your keyboard. It will ask you for your Git credentials, enter them as prompted. In Terminal, when you are typing your password or Personal Access Token, the text cursor does not move but characters are being entered. For security reasons you must have set up GitHub multi-factor authentication; see the *Connect to Git* page for more information.

Définir la branche distante en amont.

  1. Le succès est au rendez-vous ! Vous verrez le message suivant :  » La branche “git-test” est configurée pour suivre la branche distante “git-test” depuis “origin” « . Retournez au menu Git.

Succès de la liaison avec la branche distante.

Pousser les changements engagés

  1. Retournez au menu Git. Cliquez sur l’icône Push committed changes. Elle ressemble à un petit nuage avec une flèche vers le haut à l’intérieur. Entrez vos informations d’identification Git comme demandé et cliquez sur OK.

S'authentifier pour pousser les changements.

  1. Enfin, nous pouvons vérifier si les changements ont été effectués. Allez sur votre page GitHub deafrica-sandbox-notebooks fork, qui aura une URL similaire à https://github.com/<votre_nom_d'utilisateur>/deafrica-sandbox-notebooks. Cliquez sur le menu déroulant de la branche en haut de la page. Maintenant, en plus de master, vous devriez aussi être capable de voir et de sélectionner git-test.

S'authentifier pour pousser les changements.

La nouvelle branche contient les changements.

Remarquez que votre nouveau fichier my-change.ipynb n’est pas listé sur la branche master, mais lorsque vous basculez votre vue sur la branche git-test, il apparaît. Nous avons réussi à faire une modification. Félicitations pour avoir franchi toutes ces étapes.

Liste de contrôle Git

Les éléments à vérifier lorsque vous vous connectez à l’Environnement de test et que vous commencez à travailler sur votre projet de code source ouvert :

  • Avez-vous récupéré et fusionné en amont pour que votre fork soit à jour avec le dépôt d’origine ?

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

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

Vous pouvez vérifier le premier élément à partir de votre URL de fork, et les deux autres en accédant au menu Git et en regardant Dépôt actuel et Branche actuelle.

Problèmes courants

  • Unable to detect a Git repository. This can happen if you have not logged into Git on the Sandbox. Follow the instructions on connecting to Git. Secondly, check your File Browser is navigated to your clone folder. If it is in the Home page or just in the dev folder, those aren’t GitHub repositories.

  • I can’t find my file, but I know I made a new file. Are you on the correct branch? If you switch to a different branch, your new file may not appear if it has been tracked in a different branch. For example, my-change.ipynb should not be visible on the master branch.

  • I pushed my changes to my fork but I can’t see them on the GitHub website. Did you add and commit the files which were changed? Are you looking at the master branch of your fork when your changes were actually on a different branch? master is displayed by default on the website. Click the branch dropdown to see different branches on your fork.

  • I am « XYZ number of commits behind ``digitalearthafrica:master`` ». You have not fetched and merged the latest changes from the original repository. Click the Fetch upstream button on the fork’s GitHub webpage to fetch and merge the latest updates. Then, click the Pull button in the Sandbox to update your local clone. For minimum conflicts, this should be done before committing the changes and pushing to your fork.

  • **Pour des raisons de sécurité, l’Environnement de test requiert un jeton d’accès personnel distinct de votre mot de passe, ou une autre forme d’authentification multifactorielle. Ils sont simples à mettre en place. Voir l’article officiel de GitHub et le guide lié à la page Connexion à Git.

Prochaines étapes

Essayez d’effectuer des modifications à l’aide du menu Git et familiarisez-vous avec le fonctionnement du suivi des fichiers. Sinon, continuez avec la partie suivante du tutoriel.

Le menu Git permet aux utilisateurs d’accéder à certaines des fonctions les plus courantes de Git. Cependant, pour une flexibilité totale, il est idéal d’utiliser Git à partir du Terminal de l’Environnement de Production. Nous avons déjà utilisé le Terminal pour certaines commandes qui ne pouvaient pas être effectuées via le menu. Il se trouve que toutes les commandes Git peuvent être exécutées via le Terminal au lieu de faire des allers-retours dans le menu.

Les avantages du terminal sont les suivants :

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

  • Meilleur suivi de Git avec la commande « git status ».

  • Plus de contrôle sur le versionnement des fichiers, y compris l’annulation des commits.

  • Familiarité avec les interfaces de type ligne de commande, ce qui est utile pour les autres tâches administratives non Git dans l’Environnement de test, et également applicable en dehors de l’Environnement de test.

  • Moins de clics : tout ce dont vous avez besoin peut être fait à partir du terminal.

For coders or anyone with previous Terminal or command-line experience, this is the natural platform for you to use. If these concepts are new to you, don’t worry! They are uncomplicated to learn and we recommend trying it.

Cliquez sur suivant pour continuer.