git blame

El comando git blame es una utilidad de resolución de problemas versátil que cuenta con numerosas opciones de uso. A grandes rasgos, la función de git blame es visualizar los metadatos de autor adjuntos a líneas específicas confirmadas en un archivo. Esto sirve para examinar puntos específicos del historial de un archivo y poner en contexto quién fue el último autor que modificó la línea. Esto sirve para explorar el historial del código específico y responder preguntas sobre qué código se ha añadido a un repositorio, cómo se ha añadido y por qué.

Git blame se suele usar con una visualización de interfaz gráfica de usuario. Los sitios que alojan Git en línea como, por ejemplo, Bitbucket, ofrecen blame views o "vistas de acusación", que son contenedores de la interfaz de usuario para git blame. Estas visualizaciones se mencionan en conversaciones de colaboración sobre las solicitudes de incorporación de cambios y las confirmaciones. Además, la mayoría de los IDE que cuentan con integración de Git también disponen de vistas de acusación dinámicas.

Funcionamiento

Para hacer una demostración de git blame necesitamos un repositorio con algo en el historial. Usaremos el proyecto de código abierto git-blame-example. Este proyecto de código abierto consta de un sencillo repositorio que contiene un archivo README.md con unas cuantas confirmaciones de distintos autores. El primer paso de nuestro ejemplo de uso de git blame es usar el comando git clone en el repositorio de ejemplo.

git clone https://kevzettler@bitbucket.org/kevzettler/git-blame-example.git && cd git-blame-example

Ahora que tenemos una copia del código de ejemplo, podemos empezar a examinarlo con git blame. El estado del repositorio de ejemplo se puede examinar con git log. El historial de confirmaciones debería parecerse al siguiente:

$ git log
    commit 548dabed82e4e5f3734c219d5a742b1c259926b2
    Author: Juni Mukherjee <jmukherjee@atlassian.com>
    Date:   Thu Mar 1 19:55:15 2018 +0000

        Another commit to help git blame track the who, the what, and the when

    commit eb06faedb1fdd159d62e4438fc8dbe9c9fe0728b
    Author: Juni Mukherjee <jmukherjee@atlassian.com>
    Date:   Thu Mar 1 19:53:23 2018 +0000

        Creating the third commit, along with Kev and Albert, so that Kev can get git blame docs.

    commit 990c2b6a84464fee153253dbf02e845a4db372bb
    Merge: 82496ea 89feb84
    Author: Albert So <aso@atlassian.com>
    Date:   Thu Mar 1 05:33:01 2018 +0000

        Merged in albert-so/git-blame-example/albert-so/readmemd-edited-online-with-bitbucket-1519865641474 (pull request #2)

        README.md edited online with Bitbucket

    commit 89feb84d885fe33d1182f2112885c2a64a4206ec
    Author: Albert So <aso@atlassian.com>
    Date:   Thu Mar 1 00:54:03 2018 +0000

        README.md edited online with Bitbucket

git blame solo actúa en archivos sueltos. Para generar algún resultado útil, se necesita una ruta de acceso al archivo. La ejecución predeterminada de git blame solo generará el menú de ayuda de comandos. En este ejemplo, trabajaremos en el archivo README.MD. Incluir un archivo README en la raíz de un repositorio de Git como fuente de documentación para el proyecto es una práctica habitual en el ámbito del software de código abierto.

git blame README.MD

Ejecutar el comando anterior nos dará nuestro primer resultado de ejemplo de blame. El siguiente resultado es un subconjunto del resultado completo de blame del archivo README. Además, este resultado es estático y refleja el estado del repositorio en el momento de escribir este artículo.

$ git blame README.md
    82496ea3 (kevzettler     2018-02-28 13:37:02 -0800  1) # Git Blame example
    82496ea3 (kevzettler     2018-02-28 13:37:02 -0800  2)
    89feb84d (Albert So      2018-03-01 00:54:03 +0000  3) This repository is an example of a project with multiple contributors making commits.
    82496ea3 (kevzettler     2018-02-28 13:37:02 -0800  4)
    82496ea3 (kevzettler     2018-02-28 13:37:02 -0800  5) The repo use used elsewhere to demonstrate `git blame`
    82496ea3 (kevzettler     2018-02-28 13:37:02 -0800  6)
    89feb84d (Albert So      2018-03-01 00:54:03 +0000  7) Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod TEMPOR incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum
    89feb84d (Albert So      2018-03-01 00:54:03 +0000  8)
    eb06faed (Juni Mukherjee 2018-03-01 19:53:23 +0000  9) Annotates each line in the given file with information from the revision which last modified the line. Optionally, start annotating from the given revision.
    eb06faed (Juni Mukherjee 2018-03-01 19:53:23 +0000 10)
    548dabed (Juni Mukherjee 2018-03-01 19:55:15 +0000 11) Creating a line to support documentation needs for git blame.
    548dabed (Juni Mukherjee 2018-03-01 19:55:15 +0000 12)
    548dabed (Juni Mukherjee 2018-03-01 19:55:15 +0000 13) Also, it is important to have a few of these commits to clearly reflect the who, the what and the when. This will help Kev get good screenshots when he runs the git blame on this README.

Aquí tenemos un ejemplo de las primeras 13 líneas del archivo README.md. Para comprender mejor este resultado, desglosaremos una línea. La siguiente tabla muestra el contenido de la línea 3 y las columnas de la tabla indican el contenido de la columna.

ID	Autor	Marca de fecha y hora	Número de línea	Contenido de la línea
89feb84d	Albert So	2018-03-01 00:54:03 +0000	3	Este repositorio es un ejemplo de proyecto en el que participan diferentes contribuidores realizando confirmaciones.

Si revisamos la lista de resultados de blame, podemos hacer algunas observaciones. En ella figuran tres autores. Aparte del responsable del proyecto, Kev Zettler, también aparecen Albert So y Juni Mukherjee. Los autores son generalmente la parte más valiosa del resultado de git blame. La columna de marca de fecha y hora también es bastante útil. El cambio realizado se indica en la columna de contenido de la línea.

Opciones comunes

git blame -L 1,5 README.md

La opción -L restringirá el resultado al intervalo de líneas solicitado. Aquí, hemos restringido el resultado a las líneas de la 1 a la 5.

git blame -e README.md

La opción -e muestra la dirección de correo electrónico de los autores en lugar de su nombre de usuario.

git blame -w README.md

La opción -w ignora los cambios en los espacios en blanco. Por desgracia, si un autor anterior ha modificado el espaciado de un archivo cambiando de tabulaciones a espacios o añadiendo nuevas líneas, esto complica el resultado de git blame al mostrar estos cambios.

git blame -M README.md

La opción -M detecta las líneas que se han movido o copiado dentro del mismo archivo. Esto indicará el autor original de las líneas en vez del último autor que las ha movido o copiado.

git blame -C README.md

La opción -C detecta las líneas que se han movido o copiado desde otros archivos. Esto indicará el autor original de las líneas en vez del último autor que las ha movido o copiado.

Comparación entre Git Blame y Git Log

Mientras que git blame muestra el último autor que ha modificado una línea, muchas veces querrás saber cuándo se añadió la línea por primera vez. Esta puede ser una tarea engorrosa si usamos git blame. Requiere una combinación de las opciones -w, -C y -M. En vez de eso, puede resultar mucho más práctico usar el comando git log.

Para enumerar todas las confirmaciones originales en las que se añadió o modificó una parte concreta del código, ejecuta git log con la opción -S. Añade la opción -S con el código que buscas. Vamos a coger una de las líneas del resultado del README anterior para usarla como ejemplo. Usaremos el texto "CSS3D and WebGL renderers" de la línea 12 del resultado del README.

$ git log -S"CSS3D and WebGL renderers." --pretty=format:'%h %an %ad %s'
    e339d3c85 Mario Schuettel Tue Oct 13 16:51:06 2015 +0200 reverted README.md to original content
    509c2cc35 Daniel Tue Sep 8 13:56:14 2015 +0200 Updated README
    cb20237cc Mr.doob Mon Dec 31 00:22:36 2012 +0100 Removed DOMRenderer. Now with the CSS3DRenderer it has become irrelevant.

Este resultado nos muestra que el contenido del archivo README se ha añadido o modificado 3 veces por 3 autores distintos. En primer lugar, se añadió en la confirmación cb20237cc por parte de Mr.doob. En este ejemplo, git log también comienza con la opción --pretty-format. Esta opción convierte el formato de salida predeterminado de git log en uno que se ajuste al formato de git log. Si quieres más información sobre las opciones de uso y configuración, visita la página de git log.

Resumen

El comando git blame sirve para examinar el contenido de un archivo línea a línea y ver cuándo se ha modificado cada línea y quién es el autor de las modificaciones. El formato de salida de git blame se puede modificar con varias opciones de línea de comandos. Las soluciones que alojan Git en línea como, por ejemplo, Bitbucket, ofrecen blame views o "vistas de acusación", que aportan una experiencia de usuario superior al uso de la línea de comandos git blame. git blame y git log se pueden usar de forma combinada para ayudar a descubrir el historial de contenidos de un archivo. El comando git log tiene una funcionalidad parecida a blame. Si quieres más información, visita la página de resumen de git log.