git - template - how to make a good commit

Git Commit Messages: 50/72 Formato (4)

Tim Pope aboga por un estilo particular de mensaje de git commit en su blog: http://www.tpope.net/node/106

Aquí hay un breve resumen de lo que recomienda:

La primera línea es de 50 caracteres o menos
Entonces una linea en blanco
El texto restante debe ser ajustado a 72 caracteres

Su publicación en el blog explica las razones de estas recomendaciones (a las que llamaré "formato 50/72" por brevedad):

En la práctica, algunas herramientas tratan la primera línea como una línea de asunto y el segundo párrafo como un cuerpo (similar al correo electrónico)
git log no maneja el ajuste, por lo que es difícil de leer si las líneas son demasiado largas.
git format-patch --stdout convierte los git format-patch --stdout al correo electrónico, por lo que jugar bien ayuda si sus compromisos ya están bien ajustados.
Me gustaría agregar un punto que creo que Tim estaría de acuerdo: el hecho de resumir su compromiso es una buena práctica inherente en cualquier sistema de control de versiones. Ayuda a otros (oa usted más tarde) a encontrar compromisos relevantes más rápidamente.

Entonces, tengo un par de partes a mi pregunta:

¿Qué parte (aproximadamente) de los ''líderes de pensamiento'' o ''usuarios experimentados'' de git abrazan el estilo de formato 50/72? Le pregunto esto porque, en algún momento, los usuarios más nuevos no saben o no les importan las prácticas de la comunidad.
Para aquellos que no usan este formato, ¿hay una razón de principio para usar un estilo de formato diferente? (Tenga en cuenta que estoy buscando un argumento sobre los méritos, no "Nunca he oído hablar de él" o "No me importa").
Hablando empíricamente, ¿qué porcentaje de repositorios git abrazan este estilo? (En caso de que alguien quiera hacer un análisis en los repositorios de GitHub ... sugerencia, sugerencia).

Mi punto aquí es no recomendar el estilo 50/72 o derribar otros estilos. (Para ser sincero, lo prefiero, pero estoy abierto a otras ideas). Solo quiero conocer la razón por la cual a la gente le gusta o se opone a varios estilos de mensajes de git commit. (No dude en mencionar los puntos que no se han mencionado, también).

Con respecto a la línea "resumen" (los 50 en su fórmula), la documentación del kernel de Linux tiene esto que decir :

For these reasons, the "summary" must be no more than 70-75 characters, and it must describe both what the patch changes, as well as why the patch might be necessary. It is challenging to be both succinct and descriptive, but that is what a well-written summary should do.

Dicho esto, parece que los mantenedores del núcleo intentan mantener las cosas en torno a 50. Aquí hay un histograma de las longitudes de las líneas de resumen en el registro de git para el núcleo:

( )

Hay una pequeña cantidad de confirmaciones que tienen líneas de resumen que son más largas (algunas mucho más largas) de lo que esta trama puede contener sin que la parte interesante se vea como una sola línea. (Probablemente haya alguna técnica estadística sofisticada para incorporar esos datos aquí, pero bueno ... :)).

Si quieres ver las longitudes en bruto:

cd /path/to/repo git shortlog | grep -e ''^ '' | sed ''s/[[:space:]]/+/(.*/)$//1/'' | awk ''{print length($0)}''

o un histograma basado en texto:

cd /path/to/repo git shortlog | grep -e ''^ '' | sed ''s/[[:space:]]/+/(.*/)$//1/'' | awk ''{lens[length($0)]++;} END {for (len in lens) print len, lens[len] }'' | sort -n

Con respecto a los "líderes de opinión": Linus aboga enfáticamente por el ajuste de línea para el mensaje de compromiso completo:

usamos columnas de 72 caracteres para el ajuste de palabras, excepto el material entre comillas que tiene un formato de línea específico

Las excepciones se refieren principalmente al texto "no en prosa", es decir, el texto que no fue escrito por un humano para la confirmación, por ejemplo, los mensajes de error del compilador.

Estoy de acuerdo en que es interesante proponer un estilo particular de trabajo. Sin embargo, a menos que tenga la oportunidad de establecer el estilo, generalmente sigo lo que se ha hecho para mantener la coherencia.

Echando un vistazo a los Compromisos del Kernel de Linux, el proyecto que comenzó con git, si lo desea, http://git.kernel.org/?p=linux/kernel/git/torvalds/linux-2.6.git;a=commit;h=bca476139d2ded86be146dae09b06e22548b67f3 , no siguen la regla 50/72. La primera línea es de 54 caracteres.

Yo diría que la consistencia importa. Establezca los medios adecuados para identificar a los usuarios que han realizado confirmaciones (user.name, user.email, especialmente en redes internas. User @ OFFICE-1-PC-10293982811111 no es una dirección de contacto útil). Dependiendo del proyecto, haga que los detalles apropiados estén disponibles en el compromiso. Es difícil decir lo que debería ser; Pueden ser tareas completadas en un proceso de desarrollo, luego detalles de lo que ha cambiado.

No creo que los usuarios deban usar git de una manera porque ciertas interfaces para git tratan los compromisos de ciertas maneras.

También debo señalar que hay otras formas de encontrar compromisos. Para empezar, git diff te dirá qué ha cambiado. También puede hacer cosas como git log --pretty=format:''%T %cN %ce'' para formatear las opciones de git log .

La separación de la presentación y los datos impulsa mis mensajes de confirmación aquí.

Su mensaje de confirmación no debe incluirse en ningún recuento de caracteres y, en su lugar, deben utilizarse saltos de línea para separar pensamientos, párrafos, etc., como parte de los datos, no de la presentación. En este caso, los "datos" son el mensaje que intenta transmitir y la "presentación" es la forma en que el usuario lo ve.

Utilizo una única línea de resumen en la parte superior e intento que sea breve, pero no me limito a un número arbitrario. Sería mucho mejor si Git realmente proporcionara una manera de almacenar mensajes de resumen como una entidad separada del mensaje, pero como no tengo que piratear uno y uso el primer salto de línea como delimitador (afortunadamente, muchas herramientas son compatibles). esto significa romper los datos).

Para el mensaje en sí, las nuevas líneas indican algo significativo en los datos. Una nueva línea nueva indica un inicio / quiebre en una lista y una nueva línea doble indica un nuevo pensamiento / idea.

This is a summary line, try to keep it short and end with a line break. This is a thought, perhaps an explanation of what I have done in human readable format. It may be complex and long consisting of several sentences that describe my work in essay format. It is not up to me to decide now (at author time) how the user is going to consume this data. Two line breaks separate these two thoughts. The user may be reading this on a phone or a wide screen monitor. Have you ever tried to read 72 character wrapped text on a device that only displays 60 characters across? It is a truly painful experience. Also, the opening sentence of this paragraph (assuming essay style format) should be an intro into the paragraph so if a tool chooses it may want to not auto-wrap and let you just see the start of each paragraph. Again, it is up to the presentation tool not me (a random author at some point in history) to try to force my particular formatting down everyone else''s throat. Just as an example, here is a list of points: * Point 1. * Point 2. * Point 3.

Esto es lo que parece en un visor que envuelve suavemente el texto.

Esta es una línea de resumen, intente que sea breve y termine con un salto de línea.
Este es un pensamiento, tal vez una explicación de lo que he hecho en formato legible para humanos. Puede ser complejo y largo y consistir en varias oraciones que describen mi trabajo en formato de ensayo. No depende de mí decidir ahora (en el momento del autor) cómo el usuario va a consumir estos datos.
Dos saltos de línea separan estos dos pensamientos. El usuario puede leer esto en un teléfono o en un monitor de pantalla ancha. ¿Alguna vez ha intentado leer un texto envuelto de 72 caracteres en un dispositivo que solo muestra 60 caracteres? Es una experiencia verdaderamente dolorosa. Además, la oración de apertura de este párrafo (suponiendo un formato de estilo de ensayo) debe ser una introducción al párrafo, por lo que si una herramienta lo elige, es posible que no desee un ajuste automático y le permita ver el inicio de cada párrafo. Una vez más, depende de la herramienta de presentación no yo (un autor aleatorio en algún momento de la historia) tratar de forzar mi formato particular en la garganta de todos los demás.
A modo de ejemplo, aquí hay una lista de puntos:
* Punto 1.
* Punto 2.
* Punto 3.

Mi sospecha es que el autor de la recomendación de mensaje de confirmación Git que usted vinculó nunca ha escrito software que será utilizado por una amplia gama de usuarios finales en diferentes dispositivos antes (es decir, un sitio web) desde este momento en la evolución de software / computación Es bien sabido que almacenar sus datos con información de presentación codificada es una mala idea en lo que respecta a la experiencia del usuario.