Meilleures pratiques de nommage de la twig git

J’utilise un référentiel git local en interaction avec le référentiel CVS de mon groupe depuis plusieurs mois, maintenant. J’ai créé un nombre presque névrotique de twigs, dont la plupart ont heureusement été réintégrées dans mon coffre. Mais la dénomination commence à devenir un problème. Si j’ai une tâche facilement nommée avec une étiquette simple, mais que je l’accomplis en trois étapes qui incluent chacune leur propre twig et leur situation de fusion, alors je peux répéter le nom de twig à chaque fois, mais cela rend l’histoire un peu confuse. Si je deviens plus précis dans les noms, avec une description séparée pour chaque étape, les noms des twigs commencent à être longs et difficiles à manier.

J’ai appris à regarder à travers d’anciens threads ici que je pouvais commencer à nommer des twigs avec un / dans le nom, c’est-à-dire un sujet / une tâche, ou quelque chose comme ça. Je peux commencer à le faire et voir si cela aide à mieux organiser les choses.

Quelles sont les meilleures pratiques pour nommer les twigs git?

Edit: Personne n’a proposé de convention de nommage. Je supprime les twigs lorsque j’en ai fini avec elles. J’en ai juste plusieurs à cause de la gestion qui ajuste constamment mes priorités. 🙂 Comme exemple de la nécessité de plusieurs twigs dans une tâche, supposons que je doive valider le premier jalon discret de la tâche dans le référentiel CVS du groupe. À ce moment-là, en raison de mon interaction imparfaite avec CVS, je ferais cette validation et tuerais cette twig. (J’ai vu trop d’interaction avec CVS ​​si j’essaie de continuer à utiliser la même twig à ce stade.)

Voici quelques conventions de dénomination de twig que j’utilise et les raisons

Conventions de dénomination des twigs

  1. Utilisez des jetons de regroupement (mots) au début de vos noms de twig.
  2. Définissez et utilisez des jetons courts pour différencier les twigs de manière significative pour votre stream de travail.
  3. Utilisez des barres obliques pour séparer les parties de vos noms de twig.
  4. N’utilisez pas de numéros nus comme pièces maîtresses.
  5. Évitez les noms descriptifs longs pour les twigs à vie longue.

Jetons de groupe

Utilisez les jetons “grouper” devant les noms de vos twigs.

 group1/foo group2/foo group1/bar group2/bar group3/bar group1/baz 

Les groupes peuvent être nommés comme vous le souhaitez pour correspondre à votre stream de travail. J’aime utiliser des noms courts pour le mien. Continuez à lire pour plus de clarté.

Jetons courts bien définis

Choisissez des jetons courts afin qu’ils n’ajoutent pas trop de bruit à chacun de vos noms de twig. Je les utilise:

 wip Works in progress; stuff I know won't be finished soon feat Feature I'm adding or expanding bug Bug fix or experiment junk Throwaway branch created to experiment 

Chacun de ces jetons peut être utilisé pour vous indiquer la partie de votre stream de travail à laquelle appartient chaque twig.

Il semble que vous ayez plusieurs twigs pour différents cycles de changement. Je ne sais pas ce que sont vos cycles, mais supposons qu’ils soient «nouveaux», «tests» et «vérifiés». Vous pouvez nommer vos twigs avec des versions abrégées de ces balises, toujours orthographiées de la même manière, pour les regrouper et vous rappeler à quel stade vous vous trouvez.

 new/frabnotz new/foo new/bar test/foo test/frabnotz ver/foo 

Vous pouvez rapidement savoir quelles twigs ont atteint chaque étape et vous pouvez les regrouper facilement à l’aide des options de correspondance de modèle de Git.

 $ git branch --list "test/*" test/foo test/frabnotz $ git branch --list "*/foo" new/foo test/foo ver/foo $ gitk --twigs="*/foo" 

Utilisez des barres obliques pour séparer les pièces

Vous pouvez utiliser la plupart des délimiteurs que vous aimez dans les noms de twig, mais je trouve que les barres obliques sont les plus flexibles. Vous préférerez peut-être utiliser des tirets ou des points. Mais les barres obliques vous permettent de renommer une twig en poussant ou en allant vers / depuis une télécommande.

 $ git push origin 'refs/heads/feature/*:refs/heads/phord/feat/*' $ git push origin 'refs/heads/bug/*:refs/heads/review/bugfix/*' 

Pour moi, les barres obliques fonctionnent également mieux pour l’extension des tabs (achèvement des commandes) dans mon shell. Comme je l’ai configuré, je peux rechercher des twigs avec différentes sous-parties en tapant les premiers caractères de la pièce et en appuyant sur la touche TAB. Zsh me donne alors une liste de twigs correspondant à la partie du jeton que j’ai saisie. Cela fonctionne aussi bien pour les jetons précédents que pour les jetons incorporés.

 $ git checkout new Menu: new/frabnotz new/foo new/bar $ git checkout foo Menu: new/foo test/foo ver/foo 

(Zshell est très configurable en ce qui concerne l’achèvement de la commande et je pourrais également le configurer pour gérer des tirets, des caractères de soulignement ou des points de la même manière. Mais je choisis de ne pas le faire.)

Il vous permet également de rechercher des twigs dans de nombreuses commandes git, comme ceci:

 git branch --list "feature/*" git log --graph --oneline --decorate --twigs="feature/*" gitk --twigs="feature/*" 

Mise en garde: Comme le souligne Slipp dans les commentaires, les barres obliques peuvent causer des problèmes. Comme les twigs sont implémentées en tant que chemins, vous ne pouvez pas avoir une twig nommée “foo” et une autre twig nommée “foo / bar”. Cela peut être déroutant pour les nouveaux utilisateurs.

N’utilisez pas de numéros nus

N’utilisez pas les numéros dénudés (ou les numéros hexadécimaux) dans le cadre du schéma de dénomination de votre succursale. À l’intérieur de la tabulation d’un nom de référence, git peut décider qu’un nombre fait partie d’un sha-1 au lieu d’un nom de twig. Par exemple, mon outil de suivi des problèmes identifie les bogues avec des nombres décimaux. Je nomme mes twigs associées CRnnnnn plutôt que juste nnnnn pour éviter toute confusion.

 $ git checkout CR15032 Menu: fix/CR15032 test/CR15032 

Si je tentais de ne développer que 15032, git ne serait pas sûr de vouloir rechercher les noms de SHA-1 ou de twig, et mes choix seraient quelque peu limités.

Évitez les noms descriptifs longs

Les noms de twig longs peuvent être très utiles lorsque vous consultez une liste de twigs. Mais cela peut gêner la lecture des journaux d’une ligne décorés, car les noms des twigs peuvent absorber la majeure partie de la ligne et abréger la partie visible du journal.

D’un autre côté, les noms de twig longs peuvent être plus utiles dans les “merge commits” si vous ne les réécrivez pas habituellement à la main. Le message de validation de fusion par défaut est Merge branch 'branch-name' . Vous trouverez peut-être plus utile d’afficher les messages de fusion en tant que Merge branch 'fix/CR15032/crash-when-unformatted-disk-inserted' au lieu de simplement Merge branch 'fix/CR15032' .

Un modèle de twigment réussi de Git par Vincent Driessen a de bonnes suggestions. Une image est ci-dessous. Si ce modèle de twigment vous intéresse, envisagez l’ extension de stream à git . D’autres ont commenté le stream

Le modèle de Driessen comprend

  • Une twig principale, utilisée uniquement pour la publication. Nom master typique.

  • Une twig “développer” de cette twig. C’est celui utilisé pour la plupart des travaux de ligne principale. Communément nommé develop .

  • De multiples twigs de fonctionnalités de la twig de développement. Nom basé sur le nom de l’entité. Celles-ci seront fusionnées en développement, pas dans les twigs master ou release.

  • Relâchez la twig pour conserver les versions candidates, avec uniquement des corrections de bogues et aucune nouvelle fonctionnalité. Nom typique rc1.1 .

Les correctifs sont des twigs de courte durée pour les modifications qui proviennent du maître et vont dans le maître sans que la twig de développement soit impliquée.

entrer la description de l'image ici

Ma préférence personnelle est de supprimer le nom de la twig après avoir terminé une twig de sujet.

Au lieu d’essayer d’utiliser le nom de twig pour expliquer la signification de la twig, je lance la ligne d’object du message de validation dans le premier commit sur cette twig avec «Branch:» et inclut d’autres explications dans le corps du message. ne me donne pas assez d’espace.

Le nom de la twig dans mon utilisation est purement un handle pour faire référence à une twig de sujet tout en travaillant dessus. Une fois le travail sur la twig du sujet terminé, je me débarrasse du nom de la twig, parfois en balisant le commit pour référence ultérieure.

Cela rend également la sortie de git branch plus utile: elle ne répertorie que les twigs de longue durée et les twigs de sujets actives, pas toutes les twigs.

J’ai mélangé et assorti de différents schémas que j’ai vus et basés sur les outils que j’utilise. Donc, mon nom de succursale dûment rempli serait:

nom / fonctionnalité / numéro-tracker-numéro / courte description

qui se traduirait par:

mike / blogs / RSSI-12 / logo-fix

Les parties sont séparées par des barres obliques car elles sont interprétées comme des dossiers dans SourceTree pour une organisation facile. Nous utilisons Jira pour le suivi de nos problèmes afin que l’ajout du numéro facilite la recherche dans le système. Si vous incluez ce numéro, vous pouvez le rechercher lorsque vous tentez de trouver ce problème dans Github lorsque vous tentez de soumettre une demande d’extraction.

Pourquoi faut-il trois twigs / fusions pour chaque tâche? Pouvez-vous expliquer plus à ce sujet?

Si vous utilisez un système de suivi des bogues, vous pouvez utiliser le numéro de bogue dans le nom de la twig. Cela gardera les noms de twig uniques, et vous pouvez les préfixer avec un mot court et descriptif ou deux pour les garder lisibles par l’homme, comme "ResizeWindow-43523" . Cela facilite également les choses lorsque vous nettoyez des twigs, car vous pouvez rechercher le bogue associé. C’est comme ça que je nomme habituellement mes twigs.

Comme ces twigs sont finalement fusionnées dans master, vous devriez les supprimer en toute sécurité après la fusion. À moins que vous ne --squash avec --squash , l’historique complet de la twig existera toujours si vous en avez besoin.

Remarque: comme illustré dans le commit e703d7 ou commit b6c2a0d (mars 2014), désormais intégré à Git 2.0, vous trouverez une autre convention de dénomination (que vous pouvez appliquer aux twigs).

“Lorsque vous devez utiliser l’espace, utilisez le tiret” est une façon étrange de dire que vous ne devez pas utiliser d’espace.
Comme il est plus courant que les descriptions de ligne de commande utilisent des mots-clés en pointillés, vous ne souhaitez même pas utiliser d’espaces à ces endroits.

Un nom de twig ne peut pas avoir d’espace (voir ” Quels caractères sont illégaux dans un nom de twig? ” Et page de manuel git check-ref-format ).

Donc, pour chaque nom de twig qui serait représenté par une expression à plusieurs mots, utiliser un « - » (tiret) comme séparateur est une bonne idée.

Suite à la suggestion de farktronix, nous avons utilisé les numéros de ticket Jira pour des articles similaires dans mercurial, et je prévois de continuer à les utiliser pour les twigs git. Mais je pense que le numéro de ticket lui-même est probablement suffisamment unique. Bien qu’il puisse être utile d’avoir un mot descriptif dans le nom de la twig comme noté par farktronix, si vous passez souvent d’une twig à une autre, vous voudrez probablement moins taper. Si vous avez besoin de connaître le nom de la twig, recherchez dans Jira les mots-clés associés si vous ne le connaissez pas. De plus, vous devez inclure le numéro de ticket dans chaque commentaire.

Si votre twig représente une version, il semble que la convention commune consiste à utiliser le format xxx (exemple: “1.0.0”) pour les noms de twig et vx.xx (exemple “v1.0.0”) pour les noms de tags (pour éviter les conflits). . Voir aussi: is-there-an-standard-nommage-convention-pour-git-tags