Commits Triangle
Un sujet ressemble à ceci :
<zone><comportement ou intention>[modificateur] <ticket> (<portée>): <résumé>
🧩👔 #412 (serveur): autoriser un recours dans les 30 jours suivant le refus
🎨💄 — (jetons): prendre les nouvelles teintes depuis Figma
Les émojis sont les premiers caractères de la ligne, sans rien autour. Le dernier exemple est un commit effectué par un job : il n'a pas de ticket, il porte donc un tiret cadratin.
Le vocabulaire est volontairement vaste, et vous n'avez pas besoin de le mémoriser. La
commande gitmoji le distribue par petites parties. Lisez uniquement la partie dont vous avez besoin.
La commande
Utilisez la commande gitmoji. Si elle n'est pas dans le PATH, lisez references/vocabulary.txt dans le dossier de cette compétence
pour obtenir le vocabulaire complet, et indiquez à la personne que la commande est manquante.
| Quand | Exécutez |
|---|---|
| Vous avez besoin de la liste des zones | gitmoji guide areas |
| Vous connaissez la zone | gitmoji guide 🧩 (n'importe quel émoji ou nom de zone) |
| Rien dans le guide de la zone ne correspond | gitmoji guide groups, puis un groupe : gitmoji guide "repair" |
| Deux entrées semblent toutes deux correspondre | gitmoji guide 🛡️, ou le groupe : gitmoji guide "protection" |
| Le travail est un essai, une solution provisoire ou une rupture | gitmoji guide modifiers |
| Vous avez besoin des noms de portée | gitmoji guide scopes |
| Vous êtes sur le point d'écrire le résumé ou le corps | gitmoji guide message |
Avant git commit | gitmoji staged, puis gitmoji check -m '<sujet>' pour la première ligne, ou gitmoji check <fichier> pour un message entier |
Vous avez tapé des codes courts tels que :jigsaw::necktie: | Rien : le hook écrit les émojis pour vous |
| Vous annulez un commit | git revert <commit> ; la propre première ligne de git reste telle quelle |
| Le hook a refusé un sujet | Lisez son message ; il nomme la correction |
| Vous souhaitez parcourir les commits de votre branche avant qu'elle ne soit fusionnée | gitmoji history trunk..HEAD (la branche sur laquelle elle sera fusionnée, puis la vôtre) |
| Le hook indique que le dépôt a adopté une autre version | Lisez ce qui a changé à l'adresse qu'il donne, et informez l'utilisateur avant de modifier les paramètres |
Avant d'écrire du code : planifiez les commits
Lisez le ticket et écrivez les sujets que vous prévoyez de réaliser, sous forme de liste. Chacun est une
décision qu'un relecteur pourrait accepter de manière autonome, et chacun est une chose que le ticket
demande. La portée de chacun est le package qui possède la décision (gitmoji guide scopes).
Ce sont des suggestions, pas une pile à remplir. Planifiez un commit uniquement là où le ticket apporte une réponse à la question :
- Que décide l'entreprise (
👔), et que se passe-t-il au fil du temps (⛓️)? - Qu'est-ce qui est refusé avant qu'une étape soit tentée (
🛡️)? Lorsqu'une étape échoue, comment se rétablit-elle, quel code d'erreur signale-t-elle et qu'est-ce qui est communiqué aux utilisateurs (🥅)? - Quelle forme est convenue entre les composants (
🏷️), et qu'est-ce qui est stocké (💾)? - Que voient et font les utilisateurs, et à partir de quel commit l'obtiennent-ils pour la première fois (
✨)? - Comment saurons-nous qu'un utilisateur y parvient sur le produit réel (
✅, son propre commit, ajouté une fois que le produit peut être exécuté de cette façon)?
Lorsque le parcours ne peut pas encore être exécuté, livrez la fonctionnalité et indiquez sur le ticket que son ✅
est en attente. Ne mettez pas ✅ sur une vérification plus petite pour combler le vide ; cela correspond à ☑️.
Vérifiez s'il existe un propriétaire existant avant de planifier un nouveau point de terminaison, un nouveau stockage ou une nouvelle politique. Si une décision produit est manquante et modifierait ce qui est livré, écrivez la question et posez-la. Ne la tranchez pas à l'intérieur d'un commit.
Une fonctionnalité qui est une seule décision, avec son seul appelant et les vérifications dont elle a besoin, est un seul commit. Planifiez plus de lignes uniquement là où le ticket contient plus d'une décision qu'un relecteur pourrait prendre séparément. Une ligne que le ticket n'a jamais demandée est trop détaillée.
Avant chaque commit : quatre questions
- À quelle zone appartient le changement, ou à propos de quoi est-il ? Un test, un document et un terrain de jeu prennent la zone de la chose à laquelle ils se rapportent.
- Qu'est-ce qui est différent maintenant, ou qu'avez-vous fait ? Si le commit modifie ce qui est promis, nommez le comportement (un nom). Sinon, nommez l'intention (un verbe).
- Le travail n'est-il pas définitif ? Alors seulement ajoutez un troisième émoji :
🧪un essai,🚧une solution provisoire,💥les consommateurs doivent s'adapter. Un essai conserve🧪sur chaque commit jusqu'à🏁(conservé) ou⚰️(abandonné), et rien de définitif ne peut en dépendre avant cela. Construire la direction qu'un ticket a choisie n'est pas un essai. - Quel ticket ? Utilisez le format de ticket du dépôt. Seul un job écrit
—.
Ensuite, exécutez gitmoji check -m '<sujet>'.
Avant de staguer, lisez le changement en tant que personne qui n'était pas là. Lorsque la raison ne peut pas être vue à partir du code, écrivez un commentaire à côté du code : pourquoi il est comme il est, ce qui ne doit pas être changé, d'où vient une valeur. Dites pourquoi, pas ce que fait la ligne. Un commentaire ne vous coûte presque rien et évite au prochain lecteur, une personne, un junior ou un agent sans votre contexte, de deviner.
Quand une paire ne correspond pas
C'est le signal pour regarder à nouveau, pas pour choisir l'étiquette la plus proche.
- Lorsque deux étiquettes correspondent, nommez ce que le relecteur pourrait accepter maintenant et ce qu'il pourrait
reporter. Séparez lorsque ces deux décisions peuvent différer et que ce qui est conservé fonctionne encore de
manière autonome. Staguez par chemin ou par bloc (
git add -p). - Gardez ensemble le seul appelant, son câblage et les vérifications de refus dont il a besoin lorsqu'aucun d'entre eux n'a de promesse propre. Étiquetez le commit par son point central ; le reste suit.
gitmoji stagedsignale deux portées : posez la même question. Si le changement n'a de sens que dans son ensemble, comme une forme reflétée dans deux langages, gardez-le ensemble et nommez le package qui possède la décision.- Les parties imposées par le changement principal suivent : ses types, ses tests, une histoire, un fichier de verrouillage.
Chaque commit doit toujours se construire et passer les tests de manière autonome. Si la séparation briserait cela, gardez les parties imposées ensemble et mentionnez-le dans le corps.
Rédaction
- Résumé : ce que le système fait maintenant, dans les mots du domaine, en commençant par un verbe
en minuscules. La première ligne entière tient dans 140 caractères, émojis, ticket et portée
inclus, et plus c'est court, mieux c'est ;
gitmoji check -m '<sujet>'le compte pour vous avant de committer. Pas de noms de fichiers, pas de numéros de ticket, pas de « comment ». - Description : chaque commit que vous écrivez en a une, et le hook refuse un commit sans
elle. Seuls un marqueur (
🔖,🔺), un commit effectué par un job et un message écrit par git n'en ont pas besoin. Sous la première ligne, une ligne vide, puis pourquoi la modification a été faite : la raison, pourquoi de cette façon et pas celle évidente, ou la valeur que vous avez choisie. Une ou deux lignes suffisent généralement ; six est le maximum. Conservez les références de ticket à l'intérieur de la phrase (par exemple, « Voir #42 pour la décision »). Git peut supprimer une ligne commençant par#42lorsque quelqu'un édite le commit. Ne racontez pas le diff, ne listez pas les fichiers et ne décrivez pas votre processus. - Émojis, pas de codes courts. Seuls les caractères sont committés.
Qui l'a écrit
Ne vous ajoutez jamais comme auteur ou co-auteur. Pas de ligne Co-Authored-By:, pas d'identité d'agent
dans git config user.* ou --author. L'auteur est la personne responsable, et
le hook refuse un agent à cet endroit. Certains outils ajoutent une ligne de co-auteur pour eux-mêmes sans
qu'on le leur demande ; lorsque le hook refuse un commit pour cela, retirez la ligne et committez à nouveau.
Au lieu de cela, terminez le corps par une ligne vide et une signature qui indique ce qui est entré dans le commit :
_
example-model (high), editor
Claude Code (example-session)
Sous-agents : 2 × example-helper (medium)
Équipe : reviewer, tester
Recherche : 3 recherches, 12 pages
Les trois premières lignes sont toujours présentes. Les trois dernières apparaissent uniquement lorsqu'elles s'appliquent.
Lorsque le commit est effectué, le hook remplace le souligné par △ et, entre guillemets inversés,
la version du vocabulaire avec laquelle le message a été vérifié, donc une signature stockée ressemble à ceci :
△ `1.2.3`
example-model (high), editor
Claude Code (example-session)
Écrivez le souligné ; n'écrivez jamais la ligne △ vous-même. Le hook ferme chaque message
avec elle, également celui d'une personne, qui n'a alors que cette ligne et aucune signature.
gitmoji history la lit pour indiquer quels commits sont sur quelle version.
Les projets peuvent définir signature = "agents" sous [rules] pour exiger les lignes de modèle et de harnais lorsqu'une session d'agent prise en charge exécute le hook de commit. Un humain peut committer avec la description ordinaire. Les marqueurs de version et les messages générés par Git conservent leurs exemptions existantes.
| Ligne | Ce qu'elle signifie |
|---|---|
_ | La signature commence ici. Le hook la transforme en △ `<version>` . |
| ligne de modèle | Le modèle et son effort. Après une virgule, votre nom, uniquement si une personne vous en a donné un. |
| ligne de harnais | Le harnais et, entre parenthèses, l'identifiant de session, s'il y en a un. |
Sous-agents : | Combien de sous-agents ont effectué une partie du travail de ce commit, par modèle et effort. |
Équipe : | Les autres agents avec lesquels vous avez échangé des messages pour ce commit. |
Recherche : | Recherches web, pages lues et consultations de documentation pour ce commit. |
N'écrivez rien de tout cela de mémoire. Exécutez le script pour votre harnais dans scripts/
dans le dossier de cette compétence et collez ce qu'il imprime. Le chemin est relatif au dossier dans lequel
ce fichier se trouve, où que la compétence soit installée :
python3 scripts/claude-code.py
Dans Claude Code, ce dossier est ${CLAUDE_SKILL_DIR}. Le script lit l'enregistrement propre du harnais concernant
la session. Si votre harnais n'a pas de script là-bas, scripts/README.md explique comment
en élaborer une fois et l'ajouter. Lorsqu'aucun enregistrement ne peut être trouvé, le script imprime
unknown. Un dépôt peut vous demander d'omettre une ligne, comme l'identifiant de session ; ses propres
instructions le disent.
Si la session couvre plusieurs tâches ou dépôts, vérifiez les lignes d'activité facultatives par rapport à ce commit. Conservez uniquement les contributions que vous pouvez lui attribuer.
Lignes que le corps peut porter
🩹nécessiteLimitation : <ce que la dépendance ne peut pas faire>.📥nécessiteSource : <l'exécution, l'outil ou le système dont il provient>.🏁et⚰️indiquent ce qui l'a décidé.🐛peut nommer la cause :Brisé-par : <sha>.
Lors de la mise à niveau de Gitmoji
L'interface CLI, la compétence et le vocabulaire partagent un numéro de version. Le hook avertit lorsque les paramètres du dépôt nomment une version différente de celle que la commande
parle. Informez l'utilisateur et lisez ce qui a changé à l'adresse donnée par l'avertissement. Lorsque
l'utilisateur souhaite la nouvelle version, définissez-la sous [vocabulary] dans les paramètres et committez cela
seul, avec la version entre guillemets inversés :
🔺 gitmoji `<version>` : <ce qui change pour ce dépôt>
Ne réécrivez pas un historique qui est déjà partagé, sauf si l'utilisateur le demande : les commits
effectués sous des règles antérieures peuvent rester tels quels. gitmoji history --unmigrated affiche
lesquels d'entre eux ne passeraient pas aujourd'hui. Exécutez gitmoji init après avoir modifié le verrou pour actualiser la compétence installée et les workflows gérés.
Fusionner les Pull Requests et mettre à niveau l'historique
Activez le workflow de titre de PR et sélectionnez Pull request title and description comme message de fusion par défaut. Écrivez le titre humain. Gitmoji maintient son préfixe d'émoji à mesure que les commits changent. Utilisez Create a merge commit avec le message suggéré. GitHub préserve les commits d'origine et ajoute le numéro de PR d'intégration.
Pour un historique existant, utilisez le guide de mise à niveau
et le script installé scripts/gitmoji-upgrade-history.py. Inspectez l'exécution à blanc
avant de créer un candidat local. Les liens nécessitent une preuve de quelle PR a atterri.
Un remplacement de branche partagée est une décision distincte pour les propriétaires du dépôt.
Messages écrits par Git
Une fusion peut avoir n'importe quel titre. Le hook préserve le fichier de message de Git pendant une fusion
en attente, et gitmoji history reconnaît une fusion stockée par ses multiples parents.
Un check -m textuel n'a que le sujet avec lequel travailler. Il reconnaît les
en-têtes de fusion de branche, d'étiquette et de commit Git habituels, les en-têtes de fusion de Pull Request GitHub,
les légendes numérotées Merge #N, les sujets de revert et de réapplication de Git entre guillemets,
les légendes numérotées Revert #N et Reapply #N avec un titre, l'en-tête de journal de squash par défaut de Git
et les préfixes de squash automatique fixup! , squash! et amend! .
Un squash merge avec un titre de PR personnalisé produit un commit ordinaire à un parent. Les cherry-picks et les rebases peuvent également reporter des sujets ordinaires. Vérifiez ceux-ci comme les autres commits d'auteur. Un numéro de PR seul n'identifie pas une fusion.
Pendant l'adoption, un projet peut définir [rules] → untagged = "warn" dans
gitmoji.toml pour accepter les sujets simples et les signaler pour révision. La valeur par défaut
est "error". Avec "off", l'étiquette manquante est acceptée silencieusement. Les autres vérifications
s'appliquent toujours. Utilisez gitmoji history trunk..HEAD sur votre branche pour trouver les sujets
à reformuler avant de partager. L'historique vérifie toujours strictement les sujets non étiquetés.
Quand rien ne correspond
Ne déformez pas une entrée. Utilisez la plus honnête à proximité, ajoutez une ligne de corps
Miss : <ce que vous vouliez dire> et informez l'utilisateur. Les « Miss » sont ainsi que le vocabulaire est corrigé.