Git Notes: la función más genial y más odiada de Git (2022)

 (tylercipriani.com)
3 puntos por GN⁺ 2025-06-23 | 1 comentarios | Compartir por WhatsApp
  • Git notes es una herramienta poderosa que permite añadir metadatos a commits y otros objetos.
  • Esta función permite guardar información complementaria cuando no se puede modificar el mensaje del commit.
  • Puede usarse para almacenar distintos tipos de información, como historial de revisión de código o resultados de pruebas.
  • Incluso se puede implementar un sistema distribuido de revisión de código, pero su usabilidad y reconocimiento son bajos.
  • Tiene poco soporte, como cuando GitHub dejó de mostrarlo, por lo que su adopción cotidiana es baja.

¿Qué es Git notes?

  • Git notes es una función de git que permite añadir metadatos a cualquier objeto rastreado por git (commit, blob, tree).
  • Normalmente, un mensaje de commit una vez registrado no se puede cambiar, pero con git notes se puede añadir información nueva sin modificar el contenido del commit.
  • Por ejemplo, se pueden agregar notes a un commit de la siguiente manera:
    • git notes add -m 'Acked-by: <이메일>'
  • Las notes se muestran junto con git log en una sección separada.

Casos de uso reales

  • En el propio proyecto de git también se usa git notes para vincular commits con hilos de discusión en la lista de correo.
  • Algunos ejemplos de uso real de notes incluyen:
    • seguimiento del tiempo de trabajo por commit o por rama
    • almacenamiento de registros de revisión de código y resultados de pruebas
    • diseño de un sistema de revisión de código completamente distribuido

Almacenamiento de revisiones de código y resultados de pruebas

  • Cada vez hay más casos en los que los forges de código o sistemas de revisión permiten guardar metadatos de revisión de código de forma offline, es decir, dentro del propio git.
  • El plugin reviewnotes de Gerrit muestra en git log, mediante notes, quién realizó la revisión y qué pruebas se ejecutaron.
    • El usuario puede revisar localmente el historial de revisión del código sin tener que abrir el navegador por separado.

Sistema distribuido de revisión de código

  • Existen casos como git-appraise, desarrollado en Google, que hacen posible una revisión de código distribuida usando git notes.
  • git-appraise registra en git notes todo el proceso: solicitud de revisión de código, comentarios sobre los cambios y merge después de la revisión, y funciona de manera independiente de los servicios de hosting de código en línea.
  • Toda la colaboración es posible en un entorno local, e incluso ofrece una interfaz web.

Baja usabilidad y reconocimiento

  • Git notes casi no se usa porque su interfaz es incómoda y no resulta intuitiva para los usuarios generales.
  • GitHub dejó de mostrar commit notes desde 2014, lo que redujo todavía más las oportunidades de uso.
  • La gestión de notes para commits puede facilitarse algo más con configuración de git, pero para adjuntar notes a objetos blob o tree se necesita una comprensión adicional de la estructura interna de git (plumbing).
  • Como resultado, git notes sigue siendo una función de nicho y muy poco conocida.

Independencia de los forges abiertos

  • El propio git puede soportar control de versiones distribuido y revisión de código, pero gran parte del valor agregado, como el historial de revisiones, tiende a depender fuertemente de servicios de hosting como GitHub.
  • Al aprovechar la función Git notes, se abre la posibilidad de guardar y distribuir de forma distribuida no solo la historia de cambios del código, sino también el historial completo del proyecto.
  • Esto tiene una importancia clave para un ecosistema de desarrollo verdaderamente distribuido y para la preservación de los registros.

Lecturas relacionadas

1 comentarios

 
GN⁺ 2025-06-23
Comentarios de Hacker News

  • Comparten que existe una función poco conocida llamada trailers de Git; los trailers permiten insertar metadatos en formato clave-valor al crear un commit. Se usan, por ejemplo, para adjuntar un Change-Id en Gerrit. Enlace al artículo relacionado

    • Comparten que PostgreSQL tiene una función parecida llamada COMMENT; COMMENT permite agregar texto a objetos de la base de datos. Ojalá PostgreSQL también ofreciera una función para editar metadatos estructurados en formato clave-valor. Enlace a la documentación relacionada

    • Comparten una experiencia usando git notes al trabajar upstream en open source para marcar commits cuyas pruebas unitarias ya se habían completado; era útil al pulir una rama con git rebase -i, pero ahora los trailers parecen una mejor opción. Si algo como Change-Id viniera incluido en Git, las herramientas probablemente podrían entenderlo mejor. Distinguir commits por el mensaje de commit es sutilmente frágil; el id del commit es bueno por su unicidad, pero si el mismo cambio se mueve encima de otro commit, pierde utilidad como identificador. Corrección: como los trailers son parte del commit, no pueden reemplazar por completo a notes.

    • Recientemente se enteraron de que GitHub usa un trailer separado en lugar de [skip ci], probablemente para poder separarlo fácilmente del mensaje de commit. No está claro por qué GitHub exige solo el último trailer; la suposición es que puede deberse al manejo con expresiones regulares. Enlace a la documentación relacionada

    • Apenas se enteraron de la existencia de los trailers; como fan de Conventional Commits, parece que los trailers serían mejores para agregar este tipo de metadatos. Les da curiosidad si agregarlos manualmente al mensaje de commit y usar el flag --trailer es funcionalmente lo mismo.

    • Sería natural integrarlo con un sistema de seguimiento de issues, pero meter eso en algo como trailers queda demasiado lejos del issue tracker y resulta ineficiente. Los issue trackers tienen el problema de seguir modas y agregar funciones tarde. También es incómoda la regla de tener que usar sí o sí como título del PR un nombre de rama derivado del nombre del ticket. Quisieran enlazar commits e issues con otros metadatos para que el título del PR sea más significativo, pero no es un problema fácil de cambiar, así que es de esas cosas de las que uno solo se queja en internet.

  • Comparten que Forgejo empezó a soportar trailers desde la versión 10, lanzada en enero de este año. Notas de lanzamiento Pull request

  • Preguntan cómo interactúan git notes y la reescritura del historial (amend, rebase, etc.); como notes está ligado a IDs de commit/tree/blob, quieren saber si al reemplazarse por un commit nuevo las notes se copian o desaparecen. También preguntan qué pasa al combinar varios commits con interactive rebase. Comparten la impresión de que resulta distinto de lo esperado que notes se adjunte al “contenido” de archivos/directorios; por ejemplo, si se adjunta una note al blob con la cadena "Hello world!", se preguntan si la note se aplica a todos los archivos con ese mismo contenido y si se pierde cuando el archivo cambia.

    • En git rebase y similares, la copia de notes puede configurarse para que ocurra por defecto; ver la opción notes.rewrite en git-config(1).

  • En su trabajo actual usan git notes activamente para llevar registro interno de revisiones de código sin complicar el mensaje de commit ni tener que crear un PR para cada cambio. Dejan contexto en la rama sobre a qué ticket corresponde cada commit, restricciones de infraestructura y, en caso de correcciones, enlaces al hilo del incidente. Al guardar esa información en el repo, se vuelve más fácil entender por qué cambió una línea sin tener que buscar en Slack o Jira. Opinan que, a gran escala, esto puede reducir claramente la necesidad de la UI de la plataforma, y que la reproducibilidad no solo hace falta para los builds sino también para la “intención”.

    • Preguntan si no sería mejor que ese tipo de información fuera en el mensaje de commit, o si la idea es también enlazar direcciones futuras, como “este commit introdujo el bug #123”.

  • Opinan que git notes solo es realmente útil cuando hace falta agregar información adicional después del commit. Ejemplos como Acked-By o enlaces a discusiones en la mailing list son cosas que ya se conocen al momento de hacer el commit, así que podrían ir en el mensaje de commit. Más bien, creen que la verdadera ventaja de git note aparece al agregar explicaciones extra después, por ejemplo a commits que luego fueron revertidos.

    • A menudo los mensajes de commit presumen haber arreglado un bug cuando en realidad no fue así. Eso puede provocar cadenas de bugs derivados, y muchas veces colegas pasan por alto la intención original del autor. Después de lidiar con clientes molestos y bugs que reaparecen, sintieron la necesidad de ser más cuidadosos al hablar de bug fixes. A veces también se arreglan varios bugs de una sola vez, o un refactor abre oportunidades de mejora de rendimiento o nuevas funciones.

    • Acked-By, revisiones y discusiones suelen seguir ocurriendo después del commit; no necesariamente se conocen en el momento de hacer el commit. En cambio, en el caso de un commit revert, agregarlos al mensaje de commit sí puede ser útil, porque blame muestra el cambio más reciente y así de forma natural también ofrece trazabilidad sobre el commit revertido.

    • Muchas veces la discusión sigue incluso después del commit.

  • Creen que podría ser un punto interesante explorar la función notes con el objetivo de dar contexto adicional a agentes de código.

  • Esto no es falta de conocimiento, sino un problema de UI; si la UI de GitHub mostrara bien notes, se usaría mucho más.

    • Ojalá GitHub soporte notes.

  • En Git hay muchas funciones “más geniales y menos queridas”, como bisect, pickaxe, reflog, range-diff, archive y annotated tags, pero la mayoría de la gente lo usa poco porque lo ve solo como si fuera Google Drive.

    • De todos modos, git notes se siente redundante porque el contexto no técnico —como features o roadmap— ya se rastrea en herramientas separadas de gestión de proyectos, por ejemplo Jira. Según la filosofía Unix, cada herramienta debería enfocarse en su rol.

    • Nunca habían oído hablar de pickaxe, así que fue una sorpresa; sienten que no deberían confiarse demasiado.

    • Muchas veces estas funciones ornamentales en realidad no son tan útiles, y se ven como técnicas accesorias alrededor de lo esencial.

  • Opinan que git notes no era realmente una feature “genial” pero poco querida, sino algo útil solo en situaciones muy específicas y limitadas. Que toda la información realmente necesaria vaya en el mensaje de commit y luego otros sistemas como JIRA la referencien es, más bien, una ventaja. Sistemas como JIRA también sirven como canal de comunicación con analistas de negocio o personal de soporte que no son desarrolladores, y es razonable que personas no desarrolladoras no tengan acceso al repo ni al código. Cuando se trabaja con varios servicios o repos al mismo tiempo, referenciar features con algo como notes no resulta realista; tiene que integrarse con sistemas externos.

    • Señalan que es ineficiente que analistas de negocio no puedan acceder al código o al repo, porque a veces algo se entiende solo con ver una línea de código y aun así terminan preguntando cada vez. También mencionan que, aunque hay analistas con capacidades técnicas, en la práctica es difícil cambiar esa cultura.

  • Se enteraron por primera vez de notes alrededor de 2020 leyendo la página del man. En principio, notes solo se aplica al repo local, así que no tienen experiencia de uso real; para usarlo en equipo hay que configurar por separado el pushing/fetching y acordarlo como equipo, pero su equipo no lo adoptó.