Dovrei usare il tempo passato o presente nei messaggi di git commit? [chiuso]


531

Ho letto una volta che i messaggi di commit git dovrebbero essere nel presente imperativo, ad es. "Aggiungi test per x". Mi trovo sempre a usare il passato, ad esempio "Aggiunti test per x", che mi sembra molto più naturale.

Ecco un recente commit di John Resig che mostra i due in un messaggio:

Modifica alcuni risultati del set jQuery nei test di manipolazione. Risolto anche l'ordine dei risultati dei test previsti.

Importa? Quale dovrei usare?


12
Questa domanda deve quindi essere chiusa principalmente come opinione . Basta guardare le differenze di opinione tra imperativo e passato ! Detto questo, voto per il tempo imperativo, perché aiuta davvero a chiarire cosa stai facendo quando riscrivi la tua storia, scegli la ciliegia, applichi le patch, ecc.




3
@Eonil se è chiuso per essere basato sull'opinione qui sarà chiuso anche per essere basato sull'opinione.
maniaco del cricchetto,

Risposte:


601

La preferenza per i messaggi di commit attuali e di stile imperativo viene dalla stessa Git. Da Documentation / SubmittingPatches nel repository Git:

Descrivi i tuoi cambiamenti nello stato d'animo imperativo, ad esempio "make xyzzy do frotz" invece di "[Questa patch] rende xyzzy do frotz" o "[I] ha cambiato xyzzy in do frotz", come se stessi dando ordini alla base di codice per cambiarne comportamento.

Quindi vedrai molti messaggi di commit di Git scritti in quello stile. Se lavori in team o su software open source, è utile che tutti aderiscano a quello stile per coerenza. Anche se stai lavorando a un progetto privato e sei l'unico che vedrà mai la tua storia di git, è utile usare l'umore imperativo perché stabilisce buone abitudini che saranno apprezzate quando lavori con gli altri.


90
Penso che questa sia una scelta eccellente. Pensa a cosa è un commit, in forma diff: un insieme di istruzioni su come passare da uno stato precedente a un nuovo stato. Proprio come il diff dice "aggiungi questa riga qui, rimuovi questa riga qui", il messaggio di commit dice in termini qualitativi "apporta questa modifica". (Sì, git memorizza il commit semplicemente come un albero con metadati, ma per un essere umano, la parte importante di un commit è il diff.)
Cascabel,

124
È possibile visualizzare un commit come un insieme di istruzioni su come passare dallo stato precedente al nuovo stato; ma lo vedo più come un punto di controllo nell'evoluzione del codice. Per me, il messaggio di commit è un registro di ciò che è stato fatto al codice dal precedente commit; e per un registro, il passato ha molto più senso. Se pensi davvero che il messaggio di commit dovrebbe essere un insieme di istruzioni, allora il tempo imperativo è la strada da percorrere. Non ci penso proprio in quel modo.
karadoc,

10
@oschrenk: Le versioni successive del file hanno dato un motivo: "Descrivi i tuoi cambiamenti nell'umore imperativo, ad esempio 'make xyzzy do frotz' invece di '[Questa patch] rende xyzzy do frotz' o '[I] ha cambiato xyzzy per fare frotz ", come se stessi dando ordini alla base di codice per modificarne il comportamento."
mipadi,

44
Il messaggio di commit dovrebbe essere imperativo, presente perché con Git tu o qualcun altro potresti finire per fare rebaseo cherry-picke in tal caso, il commit può essere usato al di fuori del suo contesto originale. Di conseguenza, il messaggio di commit deve essere scritto autonomamente senza aspettarsi che il lettore visualizzi i messaggi di commit circostanti. Quando si scelgono le patch Cherry, è più logico applicare "Algoritmo Fixsort rapido" o "Ordinamento: migliorare le prestazioni" invece di "Correzione bug n. 124" o "Ordinamento modificato per migliorare le prestazioni".
Mikko Rantalainen

5
Il modo in cui ci penso è che il messaggio dovrebbe dirmi cosa cambierà se decido di applicare questo commit al mio ramo. Non lo considero un registro ma come stati in cui posso spostarmi e ho bisogno di sapere cosa accadrà quando scelgo un determinato stato.
steinybot,

357

Il tuo progetto dovrebbe usare quasi sempre il tempo passato . In ogni caso, il progetto dovrebbe sempre usare lo stesso tempo per coerenza e chiarezza.

Comprendo alcuni degli altri argomenti che sostengono di usare il presente, ma di solito non si applicano. I seguenti punti elenco sono argomenti comuni per la scrittura nel presente e la mia risposta.

  • Scrivere nel tempo presente dice a qualcuno cosa farà l'applicazione del commit , piuttosto che cosa hai fatto.

Questo è il motivo più corretto per cui si vorrebbe usare il tempo presente, ma solo con il giusto stile di progetto. Questo modo di pensare considera tutti gli commit come miglioramenti o funzionalità opzionali e sei libero di decidere quali commit mantenere e quali rifiutare nel tuo specifico repository.

Questo argomento funziona se hai a che fare con un progetto veramente distribuito. Se hai a che fare con un progetto distribuito, probabilmente stai lavorando a un progetto open source. Ed è probabilmente un progetto molto grande se è realmente distribuito. In effetti, probabilmente è il kernel Linux o Git. Dato che Linux è probabilmente ciò che ha causato la diffusione e la popolarità di Git, è facile capire perché le persone considerino il suo stile l'autorità. Sì, lo stile ha senso con quei due progetti. O, in generale, funziona con progetti distribuiti di grandi dimensioni, open source .

Detto questo, la maggior parte dei progetti nel controllo del codice sorgente non funziona in questo modo. Di solito non è corretto per la maggior parte dei repository. È un modo moderno di pensare a un commit: i repository Subversion (SVN) e CVS potrebbero a malapena supportare questo stile di check-in di repository. Di solito un ramo di integrazione gestiva il filtraggio dei check-in non validi, ma quelli generalmente non erano considerati "opzionali" o "funzionalità utili".

Nella maggior parte degli scenari, quando si esegue il commit in un repository di origine, si sta scrivendo una voce del diario che descrive cosa è cambiato con questo aggiornamento, per rendere più facile per gli altri in futuro capire perché è stata apportata una modifica. Generalmente non si tratta di un cambiamento facoltativo: altre persone nel progetto sono tenute a fondersi o rifarsi su di esso. Non scrivi una voce del diario come "Caro diario, oggi incontro un ragazzo e mi saluta ", ma invece scrivi "Ho incontrato un ragazzo e mi ha salutato".

Infine, per tali progetti non distribuiti, il 99,99% delle volte in cui una persona leggerà un messaggio di commit è per leggere la storia - la storia viene letta al passato. 0,01% delle volte deciderà se applicare o meno questo commit o integrarlo nel proprio ramo / repository.

  • Consistenza. È così in molti progetti (incluso Git stesso). Anche gli strumenti git che generano commit (come git merge o git revert) lo fanno.

No, ti garantisco che la maggior parte dei progetti mai registrati in un sistema di controllo della versione ha avuto la sua storia al passato (non ho riferimenti, ma probabilmente è giusto, considerando che l'argomento del presente è nuovo dopo Git). I messaggi di "revisione" o di commit dei messaggi al presente hanno iniziato a dare un senso solo a progetti realmente distribuiti - vedere il primo punto sopra.

  • Le persone non solo leggono la storia per sapere "cosa è successo a questo codebase", ma anche per rispondere a domande come "cosa succede quando seleziono questo commit" o "che tipo di cose nuove accadranno alla mia base di codice a causa di questi commit Potrei o meno unirmi in futuro ".

Vedi il primo punto. Il 99,99% delle volte in cui una persona leggerà un messaggio di commit è per la lettura della cronologia: la cronologia viene letta al passato. 0,01% delle volte deciderà se applicare o meno questo commit o integrarlo nel proprio ramo / repository. Il 99,99% batte lo 0,01%.

  • Di solito è più corto

Non ho mai visto un buon argomento che dice che usare un tempo / grammatica impropri perché è più breve. Probabilmente risparmierai solo 3 caratteri in media per un messaggio standard di 50 caratteri. Detto questo, il tempo presente in media sarà probabilmente più corto di alcuni caratteri.

  • Puoi assegnare un nome ai commit in modo più coerente con i titoli dei ticket nel tracker del numero / funzione (che non usano il tempo passato, anche se a volte in futuro)

I biglietti sono scritti come qualcosa che sta accadendo (ad esempio, l'app mostra un comportamento sbagliato quando faccio clic su questo pulsante) o qualcosa che deve essere fatto in futuro (ad esempio, il testo avrà bisogno di una revisione da parte dell'editor).

La cronologia (ovvero i messaggi di commit) è scritta come qualcosa che è stato fatto in passato (ad esempio, il problema è stato risolto).


79
Ho sentito per la prima volta oggi la presunta preferenza per gli impegni di stile imperativo. A me sembrava così innaturale e bizzarro che decisi di cercare altre opinioni. Mi fa piacere vedere che non sono l'unico a pensare che il passato sia più naturale per i messaggi di commit. :)
karadoc,

57
I messaggi di commit di merge e rebase generati automaticamente da git sono indispensabili e presenti ("Unisci", non "Unita"; "Rebase", non "Rebased"), quindi potresti voler abbinare questo nei tuoi messaggi di commit per coerenza.
mjs

13
Sembra che la differenza sia tra un focus sulla modifica del software - "Risolto X facendo Y" o il repository - "Fai Y per correggere X". +1 per un buon argomento, ma penso che il repository dovrebbe in genere concentrarsi su se stesso piuttosto che sul software risultante.
l0b0

28
Il fatto è che, usando l'imperativo, il tempo presente funziona per grandi progetti (es. Linux), quindi ovviamente si ridimensiona. Inoltre, richiede uno sforzo praticamente nullo utilizzando il tempo passato. Di conseguenza, non vedo alcun motivo (a parte "le persone anziane sono abituate a scrivere messaggi di commit al passato") per usare altro che imperativo, tempo presente. Se riesci a imparare il set di comandi git, puoi imparare a scrivere in modo imperativo e presente.
Mikko Rantalainen

35
L'imperativo non è "nuovo da git". ChangeLog esisteva molto prima di git e l'uso di imperative è sempre stato lo stile raccomandato nel Progetto GNU. gnu.org/prep/standards/html_node/Style-of-Change-Logs.html
ADL

81

Ho scritto una descrizione più completa su 365git .

L'uso dell'imperativo, presente è uno che richiede un po 'di tempo per abituarsi. Quando ho iniziato a menzionarlo, ho incontrato resistenza. Di solito sulla falsariga di "Il messaggio di commit registra ciò che ho fatto". Ma Git è un sistema di controllo di versione distribuito in cui ci sono potenzialmente molti posti da cui ottenere modifiche. Invece di scrivere messaggi che dicono ciò che hai fatto; considera questi messaggi come le istruzioni su cosa farà l'applicazione del commit. Invece di impegnarsi con il titolo:

Renamed the iVars and removed the common prefix.

Ne hai uno come questo:

Rename the iVars to remove the common prefix

Il che dice a qualcuno cosa farà l'applicazione del commit, piuttosto che cosa hai fatto. Inoltre, se guardi la cronologia del tuo repository vedrai che anche i messaggi generati da Git sono scritti in questo tempo - "Unisci" non "Unito", "Rebase" non "Rebased", quindi scrivere nello stesso tempo mantiene le cose coerenti. All'inizio sembra strano ma ha un senso (testimonianze disponibili su richiesta) e alla fine diventa naturale.

Detto questo, è il tuo codice, il tuo repository: quindi imposta le tue linee guida e attenersi a esse.

Se, tuttavia, decidessi di andare in questo modo, allora git rebase -icon l'opzione reword sarebbe una buona cosa da esaminare.


7
Bene, hai confuso due diverse linee guida: il progetto open source Git e l'uso regolare di Git. Il link fornito non menziona affatto il tempo . Il documento Git ufficiale menziona solo il limite di 50 caratteri. Git è un VCS distribuito in cui ci sono molti posti in cui ottenere modifiche ... considera questi messaggi come le istruzioni per l'applicazione del commit. Questo vale solo per alcuni progetti che sono effettivamente progetti distribuiti. Il 99,999% dei commit di Git non verrà mai applicato manualmente in questo modo. Nella maggior parte dei progetti, la cronologia è un registro delle modifiche, che dovrebbe essere al tempo passato.
Matt Quigley,

4
"e dovrebbe saltare il punto"
prendere il

30

Attenersi al presente imperativo perché

  • è bello avere uno standard
  • corrisponde ai ticket nel bug tracker che hanno naturalmente la forma "implementa qualcosa", "correggi qualcosa" o "testa qualcosa".

16

Per chi stai scrivendo il messaggio? E quel lettore che in genere legge il messaggio prima o dopo la proprietà si impegna da solo?

Penso che qui sia stata data una buona risposta da entrambe le prospettive, forse non riuscirei a suggerire che esiste una risposta migliore per ogni progetto. Il voto diviso potrebbe suggerire altrettanto.

cioè per riassumere:

  • È il messaggio principalmente per le altre persone, che in genere leggono ad un certo punto prima di aver assunto il cambiamento: una proposta di cosa farà il cambiamento al loro codice esistente.

  • Il messaggio è principalmente come un diario / record per te stesso (o per il tuo team), ma in genere legge dalla prospettiva di aver assunto il cambiamento e cerca indietro per scoprire cosa è successo.

Forse questo porterà la motivazione per il tuo team / progetto, in entrambi i casi.


10

importa? le persone sono in genere abbastanza intelligenti da interpretare correttamente i messaggi, se non lo sono probabilmente non dovresti comunque consentire loro di accedere al tuo repository!


27
Per alcune persone , cose del genere contano un po '.
Wesley Murch,

2
@mog il link non fa alcuna dichiarazione sul presente e sul passato.
ceving

2
Se il progetto si ridimensiona alla grande, le persone che eseguono la revisione del codice e la caccia ai bug vedranno così tanti impegni che hanno bisogno di tutto l'aiuto che io e te possiamo fornire. Non ha senso risparmiare un paio di secondi ora per causare grossi mal di testa in futuro per non aver scritto un messaggio di commit corretto.
Mikko Rantalainen,

Non sto dicendo di non scrivere un buon messaggio di commit. Sto dicendo che non importa se usi il passato o il presente.
Michael Baldry,

1
Come faresti a sapere che la persona che non è in grado di interpretare il tuo messaggio di commit, è causa di quella persona non abbastanza capace, o non sei abbastanza capace di scrivere un buon messaggio di commit?
Haris,

7

Spetta a voi. Usa il messaggio di commit come desideri. Ma è più facile se non si passa da tempi a lingue.

E se sviluppi in un gruppo, dovrebbe essere discusso e fissato fisso.

Utilizzando il nostro sito, riconosci di aver letto e compreso le nostre Informativa sui cookie e Informativa sulla privacy.
Licensed under cc by-sa 3.0 with attribution required.