FR:Potlatch 2/Developer Documentation/git
En février 2011, RichardF a annoncé que nous migrerions à Git, et que Gravitystorm écrirait une documentation d'introduction. Donc la voici.
Contexte
Git est un système décentralisé de gestion de versions, si différent de Svn qu'il n'a pas besoin de serveur central. Cela signifie également que vous pouvez travailler hors ligne et enregistrer plusieurs "commit" (même à plusieurs branches), puis de partager votre code lorsque vous en aurez l'occasion.
Étant donné que nous quittons Svn, la coutume voudrait que soit fournit une liste d'équivalence des commandes Git/Svn pour faciliter les choses à tout le monde. Je ne le ferai pas car considéré comme préjudiciable. En effet, j'ai commencé à apprendre Git en cherchant l'équivalent des commandes Svn ce qui m'a profondément sans intérêt et même embrouillé.
Démarrage
(Installer Git. Il y a un million de guides sur la façon de procéder, je ne suis pas en train d'en écrit un de plus ici.) Vous devez d'abord obtenir une copie du dépôt potlatch2 de quelque part. Peu importe vraiment d'où elle vient, mais il vaut mieux en récupérer une version raisonnablement récente et corrigée. Prenons donc celle hébergée par l'OSMF et clonons-là (clone).
git clone git://git.openstreetmap.org/potlatch2.git
Cette commande réalise un certain nombre de choses, à savoir:
- Création d'un dossier Git. Il contient tout le nécessaire pour que Git fonctionne.
- Copie de tout le code potlatch2 dans ce même dossier Git, y compris toutes les révisions et branches.
- Ajout d'un «distant» (remote) appelé «origine» (origin). Un «distant» (remote) est une autre copie du dépôt ailleurs, on l'appelle «origine» par pure convention, mais on pourrait l'appeler comme bon nous semble. Il est normal d'avoir plusieurs versions "distantes", correspondant à différents serveurs et personnes - une version OSMF, une version Gravitystorm et ainsi de suite...
- Création d'une copie locale de la branche «maître» (master) du serveur «origine» (appelé «maître» (master))
- Vérification la branche locale «maître». Plus d'informations à ce sujet ci-dessous.
À tout moment, vous pouvez vous rappeler à partir de quelle copie d'origine vous avez cloné:
git remote show origin
Branches
Nous sommes dans une position inhabituelle puisque nous commençons déjà avec plusieurs branches. RichardF a demandé que la r25368 (cf., maintenant: 7d4f68) soit la base de la copie stable de p2, et que donc tous les travaux engagés a posteriori dans Svn soient séparée en différents thèmes. Vous pouvez consulter dans quelle branche a été migré chaque commit https://gist.github.com/860288
git status
Cette commande est la plus importante. Elle nous indique dans quelle branche nous sommes "master" (maître), et que rien n'a été modifié depuis. Cela vaut la peine de l'utiliser souvent ! En voici une autre bien utile:
git log
Cette commande nous montre tous les commits réalisés jusqu'à présent que vous pouvez parcourir. Jetez un oeil sur ceux qui existent - ce n'est pas la même liste que sous Svn
git checkout i18n git status git log
Passez à la branche i18n. Pensez que le dossier .git est tel un sac plein de lapins et que vous en avez sorti celui appelé 18n. Par défaut, Git vous informe qu'il existe déjà une branche appelé i18n sur "origin", et donc définit votre branche locale i18n pré-rempli comme origin/i18n. Ce n'est pas très important pour le moment, mais il est bon de le savoir. Le log affiche désormais les différents patches (correctifs), mais si vous parcourez suffisamment loin (actuellement 14 commits), vous vous apercevrez que s'affichent tous les autres commits depuis 7d4f68 à l'envers.
git checkout master git status git log
Revenez où vous avez commencé.
git branch git branche -a
La première commande affiche toutes vos branches locales, la seconde ajoute à celles d'origine celles que nous n'avons pas encore touchées. N'hésitez pas à jeter un oeil sur le reste des branches en appelant "git checkout whatever» et en jetant un oeil sur leurs logs. Il est fort probable que la plupart de ces branches seront peaufinées et rapatriées dans la branche maître (master) au cours des deux prochaines semaines.
Apporter des modifications
Choisissez la branche que vous souhaitez travailler ou créer une nouvelle branche si vous le souhaitez. Il est tout à fait normal de créer une nouvelle branche à chaque nouveau sujet plutôt que de travailler directement dans le maître. Mais commençons par le code déjà présent dans maître et allons-y.
git checkout master git checkout -b bananas
Cela crée une nouvelle branche appelée bananas. Éditer maintenant deux fichiers. Peu importe lesquels. Une fois les modifications réalisées, nous faisons deux choses - a) mettre en place un commit en choisissant quels fichiers et/ou quelles parties de fichiers nous voulons, puis b) commiter avec un message.
git status
# Sur la branche bananas # Modifié, mais pas de mises à jour: # (Utilisez "git add <fichier> ..." pour mettre à jour ce qui va être commité) # (Utilisez "git checkout -- <fichier> ..." pour annuler les modifications dans le répertoire de de travail) # # modifié: README.txt # modifié: TODO.txt # aucun changement ajouté à committer (utilisez "git add" et/ou "git commit -a")
Pour voir les différences entre votre copie de travail et ce que Git en sait, lancer la commande:
git diff
Je veux construire mon commit avec les modifications apportées au fichier README, mais pas dans le fichier TODO. Donc, je n'ajoute que ce fichier à l'environnement de test:
git add README.txt git status # Sur la branche bananas # Modifications à committer: # (Utilisez "git reset HEAD <fichier> ..." pour annuler la mise en environnement de test) # # modifié: README.txt # # Modifié, mais pas de mises à jour: # (Utilisez "git add <fichier> ..." pour mettre à jour ce qui va être committé) # (Utilisez "git checkout -- <fichier> ..." pour annuler les modifications dans le répertoire de travail) # # modifié: TODO.txt #
Les "modifications à committer" ("changes to be committed") sont celles que nous sommes sur le point de committer, les "modifié, mais pas mis à jour" ("changed but not updated") sont celles que nous laissons sur la table, pour l'instant. À ce stade, nous avons besoin d'apprendre les subtilités de la git diff, à savoir:
git diff
Cela vous montre ce que vous avez "changé, mais pas mis à jour" (càd ce qui n'a pas été mis en environnement de test pour committer - ici, c'est TODO.txt)
git diff --cached
Cela vous montre ce que vous avez dans "modifications à committer" (càd. README.txt) Habituez-vous à ces deux commandes, vous en aurez beaucoup besoin. Lorsque vous êtes satisfait de ce que vous avez sur votre liste des "modifications à committer"
git commit
et écrire un message approprié. En guise d'avertissement, git add n'est pas la même chose que svn add. Cela fait des choses subtilement différentes et si vous commencez en pensant "oh, git add c'est comme svn add" vous allez vous embrouillé assez rapidement. git add est pour l'élaboration d'un commit, et personne ne se soucie de svn add puisque nous n'aurons plus à l'utiliser. Donc. Par ailleurs, git add -i vous permet de choisir quelles parties des fichiers vous souhaitez ajouter, si vous avez décidé de committer certaines choses par étapes. C'est plutôt cool, non?
Publier vos changements
Il y a de nombreuses façons de partager vos modifications avec le reste du monde. Voir S'engager dans le Rails Port pour des suggestions, ou demandez des conseils sur IRC (#osm-dev). La façon la plus courante consiste à publier sur un dépôt public, par exemple:
git push origin master
Actuellement, il y a quelques dépôts publics:
- github.com/gravitystorm/potlatch2 - copie du dépôt Gravitystorm
- github.com/systemed/potlatch2 - copie de Richard
- git.openstreetmap.org/potlatch2.git - copie du dépôt des administrateurs système de OSMF. C'est une bonne politique que de conserver une copie du code que les administrateurs systèmes déploient.
Notes
Il y a un million de questions supplémentaires à se poser sur Git et sur comment nous allons l'utiliser pour le développement de potlatch2, et Gravitystorm se fait un plaisir de répondre à toutes vos questions. Je m'attends à ce que d'ici à quelques mois je doive supprimer ce wiki car il sera tout à fait hors de propos.