JMRI:FAQ Git

Ceci est une Liste des Questions Fréquentes concernants GIT particulièrement comment utiliser Git avec JMRI.

Il y a une page d'aide JMRI séparées sur comment comment obtenir le code avec Git.

Voir aussi le Technical index pour de plus amples informations sue la maintenance du code JMRI.

Sujets Communs Utilisateur

Comment Installer Git?

Git est un logiciel libre. Selon votre type ordinateur et vos préférences il y a plusieurs façons de l'installer. Il y a plus d'informations sur le guide de la communauté Git Getting Started.

L'obtenir depuis la page Téléchargement Git.
Il est livré avec l'application GitHub Desktop, disponible depuis la page Téléchargement Git desktop (OS X et Windows seulement).
Pour le Mac, il est inclut quand vous installer Xcode.
Pour Linux vous pouvez essayer le paquet installateur, exemple: sudo yum install git ou sudo apt-get install git.

Configuration d'un environnement Git pour les Développeurs JMRI

Vous pouvez régler votre répertoire local pour qu'il "pull" automatiquement depuis le JMRI Master sur GitHub et "push" sur votre "fork" ( et aussi sur GitHub ):

Cette flèche horizontale est la "Pull Request" ( et par conséquent "pull" ) qui enregistre des informations sur la façon dont les choses entrent dans le référentiel.

Les flêches sont les deux opérations ( "push", "pull" ) et aussi les définitions de où pour voir par exemple: un URL. Git peut stocker un raccourci pour une URL, appelé " remote " Le remote par défaut est appelé "origin". Vous pouvez avoir plusieurs remotes définis.

Via l'outil ligne de commande git vous pouvez faire ceci par la commande:

$ git remote set-url --push origin https://github.com/username/JMRI.git

où username est votre nom utilisateur github. Vous pouvez vérifier l'état actuel des répertoires push et pull avec:

$ git remote -v
origin https://github.com/JMRI/JMRI.git (fetch)
origin https://github.com/username/JMRI.git (push)

Ceci dit que, par défaut, fetches et pulls viennent du référentiel principal JMRI/JMRI. Quand vous "push", d'autre part il va sur votre propre répertoire

Une fois que vous avez une copie de vos changements sur GitHub, il est facile de générer un pull request (Lien vers GitHub)

Dans un navigateur, naviguez jusqu'á répertoire sur GitHub qui a les changements que vous voulez que quelqu'un "push" et
pressez l'icone de comparaison verte , puis cliquez sur "Create a Pull Resquest".
Après votre "pull request" a bien été revu, il peut être fusionné dans le référentiel principal JMRI/JMRI. Le développeur JMRI qui "pulls" vos changements dans la source de la communauté a besoin d'avoir accès á un répertoire en ligne qui a vos changements, ce qui explique pourquoi vous avez besoin d'avoir une place sur GitHub en premier lieu ...

Travailler avec Git

Avec SVN et CVS vous extrayez un "répertoire de travail" pour y effectuer vos modifications. Travailler pendant un certain temps, et éventuellement engager ( commit ) toutes vos modifications dans le dépôt principal.

Git travaille avec un concept différent. Au lieu d'avoir de multiples répertoires de travail, vous avez un simple répertoire qui a été "cloné" depuis le référentiel principal. Si vous faites un petit changement individuel, vous pouvez travailler directement sur la branche "master" en son sein. Si non, voir ci-dessous: Branchement.

Pour comprendre Git, il est bon de connaitre les places variés dans votre répertoire git local:

Le contenu depuis le répertoire "remote", qui vit sous le répertoire caché .git/ ,
La zone "staging" ( appelée aussi "index" ou "cache" ), et
La "branche" nommée que vous utilisée, qui est dans
L'arbre de travail.

Quand vous clonez un répertoire git, vous créez une structure répertoire qui contient tous ces éléments. Á moins que vous arrêtiez, l'arbre de travail commence rempli avec le contenu de la master branch du répertoire que vous avez cloné- et le staging area est vide quand vous faites des changements dans les fichiers de l'arbre de travail, vous avez besoin de les ajouter explicitement dans la la zone de préparation. Git connait ces fichiers, mais ils ne font pas encore officiellement partie de votre répertoire local.

Une fois que vous avez rempli la zone de préparation avec tout ce que vous avez changé, une opération commit ( soumission ) engagera officiellement vos modifications dans votre structure répertoire .git/.

Quand vous pull ou push, vous dites á Git de synchroniser votre contenu git/ avec avec celui du répertoire distant dont vous avez initialement cloné le contenu.

La documentation suivante devrait vous aider á démarrer en utilisant soit la ligne de commande git ou GitHub Desktop:

Connectez-vous á GitHub et clonez votre propre copie du référentiel principal JMRI. Ceci vous donne un endroit sûr où vous pourrez collez et extraire sans affecter les autres.
Utilisation de Git:
- Clonez le référentiel JMRI sur votre système local ( ou actualisez le ):
  $ git clone https://github.com/JMRI/JMRI.git
  ou
  $ git fetch
  $ git diff ...origin
  $ git merge origin/master Auto-merging ... files ... CONFLICT (content): Merge conflict in some_file Échec Fusion Automatique; corriger les conflits et soumettez le résultat. $ vi some_file # Le fichier a des conflits marqués, éditer le pour correction... $ git add some_file $ git commit -m "Merged master fixed conflict" $ git merge origin/master
  ou
  $ git pull https://github.com/JMRI/JMRI.git
- Faites vos changement localement, testez les, etc.
  $ git add newfile
  $ git rm newfile
  $ git add .
  
  $ git status
  
  $ git fetch
  $ git merge
- Rendez vos changements disponibles pour la communauté
  $ git commit -m "commit message"
  or
  $ git commit -a -m "commit message"

Utilisation de GitHub Desktop

Clonez le référentiel JMRI sur votre système local en choisissant un élément de l'onglet "Clone" dans le fichier >Clone repository.. menu et cliquez "Clone":
Faites vos changement localement, testez les, etc.
Quand tout cela fonctionne, soumettez votre modification á votre référentiel JMRI local en retournant á l'application GitHub Desktop, examinez tous les changements constatés par le programme, entrez un Résumé [1] et une Description [2] et enfin en cliquant sur le bouton [3] soumettre la < branche> Bouton:

Après votre Soumission, un point blanc apparaìtra près de la fin de la ligne qui ressemble á une voie d'évitement dans un plan de voie. Cliquez pour lire le titre. Pour voir les fichiers modifiés á un autre moment dans le temps, cliquez sur un ancien point de soumission:

Après une soumission, vos nouvelles modifications sont seulement ajoutées avotre copie locale de votre branche. Pour les faire apparaìtre dans un endroit où d'autres personnes peuvent les voir soit vous cliquez le bouton Sync en haut á droite, choisissez Sync ( Cmd-S ) depuis le menu répertoire, ou synchroniser automatiquement Github Desktop en cochant dans le menu Edit l'élément Automatically Sync after Committing:
Quand vous avez travaillé sur quelque chose dans GhDt durant une semaine ou plus, d'autres ont pu travailler définitivement sur d'autres parties de JMRI. Pour intégrer ces nouvelles données dans votre copy, cliquez sur le bouton Update from JMRI/master en haut á gauche du panneau ( ou choisissez "Pull" depuis le menu "Repository )
Vous verrez une animation d'un symbôle de branche dans un cercle, passant de la ligne blanche vers le bas á la ligne en dessous:

Ceci vous dit que du nouveau code a été copié dans votre répertoire, et dans quelques secondes cclui-ci sera aussi copié sur votre ordinateur, aussi vous pourrez z voir ou l'utiliser, á moins que qu'ils aient travaillé sur les mêmes lignes de code ( Voir Résoudre un Conflit de Fusion, ci-dessous )

pour rendre vos changements disponibles pour la communauté cliquez "Pull Request" ( bouton en haut á droite ), entrez un titre et cliquez "Create".

Le nom du bouton PR changera en #123
signalant que vous ne pouvez pas faire d'autre PR dans cette branche
depuis ici ( mais vous pouvez encore soumettre des modifications ):

Normalement, un PR est destiné á la branche principale du référentiel original, dit JMRI: master. Vous pouvez "pull" votre propre répertoire distant, mais seuls, les maintenanciers, pourront "pull" vos modifications dans le "vrai" JMRI:master. Avant de le faire, ils étudient ce que vous avez écrit, peut être même les mettre sur leur propre répertoire pout les tester avant de les fusionner pour que tous les autres utilisateurs de JMRI les voient.
Quand votre PR est pulled & fusionné & fermé, le nom PR #123 disparaìtra et vous pourrez effacer la branche en toute sécurité.

Branchement

Toujours travailler sur une branche nommée, jamais sur une nommée "master". Bien que vous puissiez travailler directement sur la branche "master" par défaut, une bonne "Pratique Git" vous encourage á créer une branche afin que vous puissiez travailler sur elle et ne jamais gâcher votre copie locale de JMRI: master. Les branches dans Git sont faciles et pas chères á créer et utiliser; vous pouvez avoir de multiple branches en même temps, et basculer entre elles si vous travaillez sur des projets différents.

nous recommandons que vous nommiez les branches démarrant avec votre nom d'utilisateur GitHub ou vos initiales (par exepmle, "abc") ou quelque chose qui suggère que vous travaillez dessus: "abc-decoder-xml-change", "abc-2015-09-14", "abc-next-cool-thing", et "abc-patch-NNNN" sont tous correcte. De cette manière, nous savons que c'est vous.

Utilisation de Git:
- Pour créer une branche appelée ;branchname", vous faites
  
  git checkout -b nomdebranche
  
  Le "-b" dit de créer la branche. Pour basculer sur une branche existante, il suffit d'oublier cette option:
  
  git checkout nomdebranche
  
  Pour voir toutes les branches actuelles, faire
  
  git branch
- Si d'autres personnes dans la communauté font des changements sur la branche master, vous pouvez garder votre branche á jour en fusionnant ces changements avec votre branche
  
  git checkout branchname git merge -m"merging in current contents of master" master
  
  ( Si vous omettez l'option de message, vous pouvez être invité á en ajouter un dans un éditeur ) Si des modifications ont été collectées et fusionnées, vous pouvez ensuite les soumettre á votre branche:
  git commit -a
- Lorsque vous avez terminé, fusionner vos modifications dans la ligne commune de développement avec
  
  git checkout master git merge -m"merging to master" branchname git commit -a
- Vous popuvez alors effacer votre branche ( si vous avez réellement fini avec elle ) avec
  
  git checkout master git branch -d branchname
Utilisation de GitHub Desktop:
- Cliquez sur le bouton "Add a Branch( + )", donnez un nom pour votre nouvelle branche et en utilisant "From": sélectionnez la branche où vous voulez créer la nouvelle branche:
- Pour effacer une branche, sélectionnez la dans le menu contextuel "Show Branches", et sélectionnez Delete "my-patch" depuis le menu Branch.
  Vous ne pouvez pas le faire avec la branche master, aussi ne travaillez pas sur elle, mais sur une branche nommée.
Vous pouvez opter pour créer et effacer des branches sur le web GitHub aussi facilement. Plus d'aide sur Github Web Branching.

Partage de Branches

Un des avantages des branches Git est qu'il est aisé pour les gens de les partager. Ceci permet á une personne de travailler avec quelque chose qu'un autre a terminé, y compris l'édition et de l'amélioration, sans qu'elle soit accessible pour tout le monde.

Arnie a développé quelque chose sur la branche ""arnie-great-tool". Bill veut essayer de l'utiliser sur sa mise en page. Les étapes sont les suivantes:

Arnie le soumet au repertoire local,et ensuite le met sur son répertoire GitHub.
git checkout arnie-great-tool (work on changes) git commit -m"Added support for the Frobnab 2000" git push
Bill peut ensuite le récupérer depuis le répertoire d'Arnie
git pull https://github.com/arnie/JMRI.git arnie-great-tool git checkout arnie-great-tool
où la première partie de "pull" est l'URL du répertoire d'Arnie.
Bill peut travailler avec le code, et même le changer si nécessaire. S'il fait des changement et veut les envoyer á Arnie, il fait le même processus á l'envers:
git commit -m"Fixed a bug in sternerstat handling" git push
Puis Arnie peut fusionner ces changements dans sa propre copie avec:
git checkout arnie-great-tool git pull https://github.com/bill/JMRI.git arnie-great-tool

La résolution d'un conflit de fusion

Il est pas rare que deux personnes ou plus ont des idées sur la même partie du programme ou le site Web JMRI, chacun faisant des soumissions et et des PRs pour des parties des mêmes fichiers. S'ils ont travaillé sur différentes lignes de texte ou de code dans un fichier, GitHub sait comment combiner ces changements dans un seul fichier actualisé. Vous pourriez avoir á vérifier que votre proposition fonctionne encore, car quelqu'un pourrait avoir supprimer l'ancrage auquel vous sous référez etc. Si GHDt découvre qu'un changement venant d'une personne a été inséré dans le master, et que vous avez préparé des changements pour la même ligne, GitHub Desktop vous demande de l'aider á décider quoi faire en affichant l'écran des Conflits ( Notez les points orange á côté de l'un des noms de fichier ):

Cliquez sur ce nom et choisissez Show in Finder ou Open with External Editor ( GhDt n'a pas d'outils d'édition).
Pour trouver le point où le conflit est survenu, regarder les marqueurs <<< HEAD ==== >>> master qui sont insérés par GitHub:

Choisissez laquelle des deux versions vous souhaitez conserver ( ou faire quelque combinaison) et enlever les lignes < === >!

Cette nouvelle proposition devra encore être soumise á JMRI, en lui donnant un titre approprié, ex: Conflit résolu et cliquez Commit ( et Sync ). Cette soumission supplémentaire sera ajoutée á votre PR et fera partie de la proposition que les maintenanciers verront. Vous ne devriez pas garder de conflit de fusion pendant la nuit, car les maintenanciers n'ont pas de possibilité de les corriger pour vous et ils devront l'ignorer jusqu'á vous l'ayrésolu.

Tests d'Intégration Continue

Les référentiels principaux de JMRI exécutent un jeu de tests sur tous les Pull Request ( PR ). C'est appelé Intégration Continue ( CI ), et est une méthode éprouvée pour maintenir le code á une qualité supèrieure.

vous pouvez ajouter ceci á vos répertoires afin que chaque "push" soit automatiquement testé

Les deux services de test CI sont appelés "Travis CI" et "GitHub":

Travis fonctionne sur Linux. il fait d'abord un contrôle des mauvaises fins de ligne (voir plus loin ). puis exécute le jeu complet de tests JUnits, y compris les opérations de tests d'écran.

Pour ajouter ceux-ci á votre répertore personnel:

Pour Travis aller á la page web Travis et "Inscrivez vous". Utilisez votre compte GitHub et Email. Á la fin du processus, il vous sera demandé vos répertoires GitHub á surveiller; vous pouvez sélectionner á la fois le "JMRI" et fourches "du site".

A partir de lá, en "poussant" á votre propre référentiel va exécuter les tests. Vous recevrez un email lorsque les tests sont terminés, ou vous pouvez vérifier sur le web.

Manipulation des Fins de Ligne

Mac et Linux utilise un caractère LF á la fin de chaque ligne; Windows utilise la paire CRLF. Les fichiers textes JMRI sont, par convention, chargés dans Git avec les fins de ligne LF.

Il est très important que les utilisateurs Windows ne convertissent pas accidentellement un fichier avec fin de ligne CRLF. Quand cela se produit Git pense que toutes les lignes ont été changées: Git ne peut plus fournir d'informations utiles et parcellaires sur les changements faits plus tôt sur les fichiers.

Il y a un fichier ".gitattributes" qui en dit plus sur l'implantations des lignes de commande Git qui gèrent cela correctement. Malheureusement , tous les IDEs n'obéissent pas aux directives dans les fichiers. Par exemple, pour voir NetBeans sur windows gérer proprement les fins de lignes, un plugin spécifique doit être installé. Voir la page JMRI NetBeans pour les spécificités.

Si dans un fichier avec des fins de ligne changées est accidentellement soumis etet transmis dans un pull-request ( PR ), Le mauvais fichier dans ce PR sera détecté pendant le test Travis et le PI ne sera ni accepté ni fusionné. En outre, le PR sera marqué avec une étiquette "CR LF". Puisque l'historique a déjá été perdu dans ce fichier, l'étiquette CRLF rappelle au maintenanciers qu'l ne suffit pas de simplement changer les fins de ligne par LF, soumettre et "push": 'historique a été perdu et des mesures plus compliquées doivent être prises
Les deux approches sont:

Abandonner Le PR et les modifications sous-jacentes, effacer la branche, et refaire comme il faut. Si vous travaillez proprement, avec vos changements dans une branche séparée et la soumission de petits changements, c'est le plan d'action recommandé.
Alternativement, il est possible d'utiliser les outils Git pour enlever la soumission impropre de la branche. C'est beaucoup plus compliqué. Demander á un des développeurs ayant l'expertise de Git de le faire pour vous et n'oubliez de les remercier.

Les maintenanciers qui rencontre un PR actualisé avec une étiquette CRLF voudront vérifier que tous les fichiers dans le PR ne montrent pas toutes les lignes changées. Si elles le sont, même si elles ont la fin de ligne LF correcte, le PR ne pourra pas être fusionné.

Beaucoup d'Éditeurs XML ont un Réglage des Préférences pour les fins de ligne.
Par exemple, dans Expresso cochez que les Line Ending sont paramétrées pour Unix (LF) avant de démarrer l'édition de fichier JMRI:

Test d'un Pull Request

Les Pull requests sont juste un cas particulier d'une branche. Si vous voulez les tester avant de les fusionner dans un master, vous pouvez les apporter dans votre répertoire local et travailler avec eux.

Dans quelques cas, le site web GitHub fournit des instructions disponibles sur la droite du pull-request lui-même. Regardez près du bas du lien de discussion, dans le dernier bloc d'information. La bonne chose á propos de ceux-ci est qu'elles comportent automatiquement les bons noms de branche, etc, inclus.

S'il n'y a pas d'instruction d'affichée, il y a ici une séquence de choses á faire:

Chercher le référentiel source et le nom de branche. Pour le faire, regarder en haut de la demande de branche pour une ligne disant:
user wants to merge 3 commits into JMRI:master from user:branch
Ensuite, pousser cette branche sur votre propre machine avec la commande:
```
        git fetch https://github.com/user/JMRI.git branch:local-branch
        
```
où vous avez remplacer chaque valeur soulignée:
- Changez "user" par le nom utilisateur GitHub correcte
- Changez "branch" par le nom de branche dans le pull request ( c'est OK si c'est par ex: master )
- changez "local-branch" par ce que vous voulez appeler la branche sur votre propre machine. Celle-ci ne doit pas déjá existé.Quelque chose comme "ma-branche-utilisateur" Vous rappellera de qui est le dépôt dont vous l'avez tiré, tout en marquant les changements ultérieurs comme les vôtres si vous les partagez plus tard avec quelqu'un d'autre. ( Il est recommandé que vous démarriez vos noms de branches avec votre propre nom, cela simplifie tout sorte s d'opérations )
La branche existe manitenant dans votre machine, Et vous pouvez juste vous déplacer vers elle:
```
        git checkout local-branch
        
```
puis compler, tester, etc, comme vous le voulez. Vous pouvez même soumettre et partager les changements si vous le désirez, parce que c'est maintenant votre propre branche de développement: Elle a commencé á une autre personne, mais c'est maintenant la votre.

Manipuler un Patch SF.net

Éventuellement, nous allons passer de l'utilisation du traqueur SF.net pour les questions GitHub pour manipuler le code auquel les gens souhaitent participer. En attendant, voici un moyen suggéré pour traiter un patch SF.net.

Dans votre répertoire local, créer une branche pour maintenir le patch:
git checkout -b patch-NNNN
Ou NNNN est le numéro du patch.
Fusionnez dans le code modifié si nécessaire.
Soumettez vos changements:
git commit -m"Patch-NNNN plus the patch subject line (author name)"
Il est maintenant dans votre répertoire sur une branche qui lui est propre, où vous pouvez où vous pouvez tester des choses comme d'habitude
Quand vous êtes satisfait, poussez le contenu soumis de votre répertoire local vers votre répertoire GitHub ( En supposant que la configuration par défaut, où " pousser " va á votre propre dépôt sur GitHub) avec
git push origin patch-NNNN
Allez á votre répertoire sur GitHub et démarrez le processus "pull request".
Sur le second écran, commutez la branche à comparer dans votre répertoire depuis "master" vers "patch-NNNN". Puis le reste du Pull Request se passe comme avant..
Éventuellement, un maintenancier JMRI peut manipuler et fusionner le pull request, qui mettra le patch des changements sur la branche master dans le référentiel.
Vous pouvez attendre pour fusionner sur le référentiel principal, et ensuite réaliser un
git pull
pour actualiser votre répertoire local avec le patch sur votre master local via
git checkout master git merge patch-NNNN

L'avantage de cette approche est qu'elle vous permet de garder votre propre travail séparé de tous les correctifs que vous manipulez. Les patches sont sur des branches différentes de votre travail, de sorte qu'ils ne se chevauchent pas.

Opérations Moins-Courantes

Migration des modifications non validées á partir d'un fichier SVN

Comme nous avons migré de SVN á Git depuis 2015, vous pouvez avoir encore des éditions basées sur un vieux code. Si vous avez des changements pour le code JMRI dans un fichier SVN que vous souhaitez soumettre dans la version en développement actuel sur Git. Voici ce que nous recommandons:

"Actualisez"vers le Head de SVN. Vous pouvez faire cela n'importe où, parce que vous devez le faire avant que vos changemenets puissent être soumis. Faites le maintenant et résolvez les problèmes.
$ svn update
Vérifiez l'état et sauvez la sortie. Double vérification qu'ils n'y aient pas de conflits de montrés.
$ svn status

save a copy to reference later ...

$ svn status > saved-status.txt
Diff les sources et enregistrer la sortie
$ svn diff > patch.txt
Clonez une copie du référentiel JMRI Git sur votre machine. ( Voir les pages précédentes pour les instructions détaillées. )
$ git clone https://github.com/JMRI/JMRI.git
Dans votre nouveau répertoire cloneé, vérifier les sources comme elles étaient quand le code a été changé de SVN vers Git:
$ git checkout tags/svn-30001
Ceci définit votre copie de travail pour qu'elle soit exactement la même que le dernier contenu de SVN, la même que la base pour le svn diff vous avez pris plus tôt.
Appliquez les changements que vous avez fait dans SVN dans le nouvel arbre Git
$ patch -p0 < patch.txt
Si vous avez créé et complété de nouveaux fichiers dans le répertoire de travail SVN, par ex: des fichiers avec l'état "A" or "?":
- Copiez ces fichiers á leur place correspondantes dans Git.
- Ajoutez les á la file d'attente de l'environnement de test Git: Pour que git ajoute ( chemin ) sur chacun d'entre eux pour dire quelque chose á Git á leur sujet
  $ git add pathname/to/new/file
Vérifiez l'état pour avoir une liste des changements.
$ git status
Vous devez voir la même liste de fichiers changés que l'"état SVN" vous avez exécuté plus tôt.
git stash save
git checkout master
git stash pop

Selon la progression dans Git, des conflits pourraient apparaìtre. Si oui, vous devez les résoudre ici.

Maintenant vous pouvez démarrer le développement, sans avoir perdu quoique ce soit.

Les cookies CVS, RCS et SVN embarqués

Quand JMRI utilisait á l'origine CVS, nous utilisions des lignes comme: # La ligne suivante est maintenue par CVS, SVP ne la changz pas # $Revision$ comme moyen de suivre les versions des fichiers. Quand nous avons migré vers SVN, nous avons conservéces lignes dans certains fichiers, comme decodeur XML, Fichier properties, etc que les utilisateurs étaient susceptibles de modifier et soumettre de nouveau pour l'inclusion.

Mais avec Git il y a moins de besoin pour ces derniers. Donc, nous supprimons ces lignes. Si lors de travaux sur un fichier vous en voyez, habituellement dans l'en tête, vous pouvez les effacer.