gestor-tareas está a punto de tener su primera versión estable. El equipo quiere poder decir "esto es la 1.0.0" y que dentro de dos años, cuando llegue una incidencia de un cliente que sigue con esa versión, cualquiera pueda situarse exactamente en ese código sin depender de recordar un hash de cuarenta caracteres ni de rebuscar en el git log por fechas.

Para eso están las etiquetas (tags): nombres permanentes que apuntan a un commit concreto. A diferencia de una rama, que avanza cada vez que confirmas, una etiqueta se queda quieta. v1.0.0 significa hoy, mañana y dentro de una década exactamente el mismo commit.

Y hay una segunda cosa que aprender aquí: en la lección 01-04 vimos que la base de datos de Git guarda cuatro tipos de objeto —blob, tree, commit y tag— y del cuarto apenas dijimos nada. Esta lección lo completa. Porque resulta que hay dos clases de etiqueta muy distintas, y la diferencia entre ellas es exactamente si existe o no ese objeto tag.

1. Qué es una etiqueta y en qué se diferencia de una rama
2. Etiquetas ligeras frente a anotadas
3. Crear etiquetas
4. Listar, buscar y examinar etiquetas
5. Etiquetar un commit del pasado
6. Versionado semántico
7. Enviar etiquetas al remoto
8. Borrar etiquetas y por qué no se mueven
9. Etiquetas firmadas
10. git describe: nombrar cualquier commit
11. Trabajar sobre una etiqueta

Recuerda la lección 03-01: una rama es un fichero de 41 bytes en .git/refs/heads/ que contiene un hash. Una etiqueta es lo mismo, pero en .git/refs/tags/:

La diferencia no está en el formato sino en el comportamiento:

Ese "no se mueve sola" es todo el valor de la herramienta. Si te sitúas en v1.0.0 dentro de tres años, ves exactamente lo que había cuando se publicó, aunque main haya recibido mil commits desde entonces.

main sigue avanzando hacia la derecha; v1.0.0 y v1.0.1 se quedan clavadas donde se pusieron.

Aquí está el concepto central de la lección.

Una etiqueta ligera (lightweight) es exactamente lo que acabas de ver: un fichero con un hash dentro. Un puntero pelado, sin nada más. No crea ningún objeto nuevo en la base de datos.

Una etiqueta anotada (annotated) crea un objeto tag completo en la base de datos de Git, con su propio hash, que contiene: a qué commit apunta, quién la creó, cuándo, un mensaje, y opcionalmente una firma criptográfica. Y refs/tags/v1.0.0 apunta a ese objeto, no al commit.

Veámoslo con las herramientas de 01-04:

La referencia resuelve directamente a un commit: no hay objeto intermedio.

Ahí está el cuarto tipo de objeto, por fin en su hábitat natural. Fíjate en la estructura: object (a qué apunta), type (qué es lo apuntado), tag (el nombre), tagger (quién y cuándo) y el mensaje. Y como todo objeto de Git, es inmutable: su hash se calcula sobre ese contenido.

La comparación completa:

Por qué para publicar versiones se usan siempre las anotadas, en cuatro razones concretas:

1. Dejan constancia de quién y cuándo. Un v1.0.0 sin autor ni fecha no responde a "¿quién decidió que esto era la 1.0?".
2. Llevan un mensaje. Ese mensaje es el sitio natural para las notas de la versión, y viaja con el repositorio.
3. Se pueden firmar. Una etiqueta firmada permite verificar criptográficamente que la versión la publicó quien dice.
4. Git las trata como ciudadanas de primera. git describe las prefiere, push --follow-tags solo envía esas, y varias herramientas del ecosistema las esperan.

La regla práctica es simple: etiqueta ligera = marcador personal desechable; etiqueta anotada = todo lo demás.

Cuando se abre el editor, escribe un asunto en la primera línea, una línea en blanco y el cuerpo. Es exactamente la convención de los mensajes de commit (lección 08-01):

Un aviso sobre los nombres: son referencias de Git, así que valen las mismas reglas que para las ramas (lección 03-06). Sin espacios, sin .., sin ~, ^, :, ?, *, [, sin @{, sin terminar en . ni en .lock. La convención abrumadoramente mayoritaria es v seguida del número: v1.0.0, v2.3.1.

Y una precaución que evita un problema clásico: no uses el mismo nombre para una rama y una etiqueta. Si existen v1.0.0 como rama y como etiqueta, git checkout v1.0.0 es ambiguo, Git avisa y aplica una regla de precedencia que nadie recuerda. Lo vimos de pasada en 04-05 al hablar de refspecs completos; la solución es no crear el problema.

Ordenadas alfabéticamente, que es un orden incorrecto para versiones: v1.10.0 sale antes que v1.2.0. Git lo sabe y tiene una solución:

v:refname ordena entendiendo la semántica de los números de versión, y el - invierte para poner la más nueva arriba. Merece quedarse configurado:

Filtrar por patrón con -l (o --list), que acepta comodines de shell:

Ver la información de cada etiqueta en el listado:

Examinar una etiqueta a fondo con git show:

Con una etiqueta anotada ves dos bloques: primero la etiqueta (con su tagger, su fecha y su mensaje) y después el commit al que apunta con su diff. Con una ligera solo verías el commit, porque no hay nada más que ver.

Otras consultas útiles:

Esa última es de las más útiles del repertorio: responde a "¿en qué versión se corrigió esto?" sin abrir nada.

Las etiquetas funcionan como cualquier otra referencia en rangos, diff, log y show. Todo lo que aprendiste en la lección 02-06 vale aquí.

Es habitual darse cuenta de que hay que etiquetar algo después de haber seguido trabajando. Basta con pasar el commit:

Un detalle importante que se ve ahí: la fecha de la etiqueta es la de hoy, no la del commit. Es correcto: la etiqueta se creó hoy, aunque marque algo de hace semanas. Si por algún motivo necesitas que coincida:

Y como el commit puede indicarse con cualquier expresión de las que conoces (lección 02-06), todo esto es válido:

Etiquetar v1.0.0 no significa nada si el equipo no comparte qué quiere decir ese número. El versionado semántico (SemVer) es la convención más extendida para darle significado.

Formato: MAJOR.MINOR.PATCH

Aplicado a la historia real de gestor-tareas:

Dos reglas que a menudo se pasan por alto:

• La versión 0.x.y es territorio sin garantías. Antes de la 1.0.0, la convención dice explícitamente que cualquier cosa puede cambiar. Es el sitio donde estar mientras el diseño no esté asentado.
• Una vez publicada, una versión no se toca jamás. Si v1.0.0 tenía un fallo, se publica v1.0.1. Nunca se reetiqueta v1.0.0 (apartado 8).

SemVer admite además sufijos para versiones previas y metadatos de compilación:

En el orden de SemVer, v2.0.0-alpha.1 < v2.0.0-rc.1 < v2.0.0: los sufijos de prelanzamiento van antes que la versión final. git tag --sort=-v:refname lo entiende correctamente.

Cómo se decide qué entra en cada versión, quién la aprueba, cómo se generan las notas y cómo se automatiza la publicación son temas de proceso de equipo y de integración continua: los verás en los módulos 7 y 10. Aquí nos ocupa el mecanismo de Git.

En la lección 04-05 dejamos esto abierto con una frase que sorprende a todo el mundo: git push no envía etiquetas. Ahora cerramos el tema.

El motivo es el refspec por defecto (lección 04-02): refs/heads/*:refs/heads/*. Solo cubre ramas. refs/tags/* queda fuera.

La etiqueta se ha creado en local y ahí sigue. Las tres formas de enviarla:

--tags tiene un problema real: envía también pruebas-de-hoy, antes-del-rebase y cualquier marcador ligero que tengas por ahí, y una vez en el servidor son de todos. Por eso --follow-tags es casi siempre la opción correcta, y por eso conviene dejarla configurada:

A partir de ahí, un git push normal se lleva las etiquetas anotadas que correspondan y ninguna más.

Un matiz sobre --follow-tags: solo envía etiquetas anotadas y solo las que apuntan a commits que ya están o van a estar en el servidor. Es exactamente lo que quieres, y también otra razón práctica para usar siempre anotadas al publicar versiones.

Al recibir, no hay que hacer nada especial: git fetch y git pull traen las etiquetas de los commits que descargan. Si necesitas traerlas todas explícitamente:

Borrar en local:

Borrar en el remoto (misma sintaxis de borrado de ramas de 04-05):

Y ahora lo importante: ¿por qué mover una etiqueta ya publicada es una mala idea?

Técnicamente se puede. git tag -f v1.0.0 <otro-commit> la reapunta, y git push --force origin v1.0.0 la reapunta en el servidor. Pero:

1. Nadie se entera. Quien ya tenía v1.0.0 descargada no la actualiza en un git fetch normal. Git es deliberadamente conservador con las etiquetas existentes: si el nombre ya existe en local, no lo toca. Resultado: durante meses, tu v1.0.0 y la de Bruno apuntan a commits distintos, y ninguno de los dos lo sabe.
2. Rompe la premisa entera. Una etiqueta vale porque es estable. Una etiqueta que puede cambiar no sirve para nada: ya no puedes citarla en una incidencia, en un despliegue ni en un documento.
3. Los artefactos ya publicados no cambian. Si v1.0.0 está desplegada en un cliente, mover la etiqueta no mueve el código del cliente. Solo consigue que la etiqueta mienta sobre qué se desplegó.
4. Es la misma violación de la regla de oro del módulo. Reescribir algo que otros ya tienen descargado no es una operación local.

Quien recibe una etiqueta movida ve esto, si la fuerza:

Y a partir de ahí puede tener dificultades para saber cuál era la buena.

Qué hacer en su lugar:

En resumen: la etiqueta es un compromiso. Una vez enviada al servidor, se trata como inmutable.

Una etiqueta anotada puede llevar una firma criptográfica que demuestre quién la creó:

Para qué sirve en la práctica: si alguien distribuye gestor-tareas descargando la etiqueta v1.0.0 del servidor, la firma le permite comprobar que esa versión la publicó realmente Ana y no alguien que consiguió acceso al servidor.

Solo funciona con etiquetas anotadas —una ligera no tiene dónde guardar la firma—, y requiere tener configurada una clave (user.signingkey, gpg.format, tag.gpgSign). La configuración completa, incluidas las firmas con claves SSH y la firma de commits, está en la lección 08-05: Mejores Prácticas de Seguridad. Aquí basta con saber que la opción existe y que es una razón más para usar anotadas.

Tienes un commit cualquiera, en medio del desarrollo, y quieres un nombre legible para él. git describe construye uno a partir de la etiqueta más reciente que lo alcanza:

Se lee así:

Si estás exactamente sobre una etiqueta, el nombre es la etiqueta a secas:

Opciones importantes:

La combinación que se usa en la práctica para versionar compilaciones:

Ese identificador es extraordinariamente útil: se incrusta en la aplicación y, cuando alguien reporta un fallo desde una versión intermedia, sabes exactamente de qué commit hablas y si venía de un directorio sucio. Por ejemplo, en gestor-tareas:

Y --contains, para la pregunta inversa:

"Ese commit está dos commits antes de v1.0.1", es decir: entró en la versión 1.0.1.

Situarse en una etiqueta te deja en detached HEAD (lección 03-02), porque una etiqueta no es una rama y no puede avanzar:

Eso está bien para mirar: inspeccionar el código de esa versión, ejecutarla, reproducir un fallo. Pero si vas a trabajar —por ejemplo, corregir un fallo de la 1.0 para publicar una 1.0.1— necesitas una rama:

Ahora sí: rama de mantenimiento que arranca exactamente en la versión publicada. Corriges (o traes la corrección desde main con git cherry-pick -x, lección 05-03), confirmas, etiquetas la nueva versión y la envías:

Ese es el ciclo completo de una versión de mantenimiento, y usa cuatro cosas de este módulo a la vez.

También puedes exportar el contenido de una etiqueta sin clonar nada:

git archive genera un .zip (o .tar.gz) con el árbol de esa etiqueta, sin el directorio .git. Es la forma canónica de producir el paquete de una versión.

Error 1: crear etiquetas ligeras para versiones. git tag v1.0.0 sin -a no guarda quién, ni cuándo, ni por qué, no se puede firmar y --follow-tags no la envía. Para versiones, siempre -a.

Error 2: creer que git push envía las etiquetas. No lo hace. Es la sorpresa clásica: creas v1.0.0, haces push, y en el servidor no está. git push origin v1.0.0 o push.followTags true.

Error 3: usar --tags por costumbre. Envía todas tus etiquetas locales, incluidos los marcadores de pruebas. Una vez en el servidor, limpiarlas es engorroso y hay que avisar a todo el mundo.

Error 4: mover una etiqueta publicada. Quien ya la tenía no la actualiza y acabáis con dos verdades distintas. Si hay un fallo, se publica la siguiente versión.

Error 5: confiar en el orden alfabético. v1.10.0 va antes que v1.2.0 en orden alfabético. Configura tag.sort -v:refname.

Error 6: usar el mismo nombre para una rama y una etiqueta. Genera ambigüedades en checkout, switch y push que después cuesta entender.

Error 7: esperar que git describe vea las ligeras. Por defecto solo mira las anotadas. Si tu repositorio solo tiene ligeras, git describe falla con no names found; ahí hace falta --tags.

Consejo 1: etiqueta desde main y solo lo que se publica. Una etiqueta por versión real. Etiquetar commits intermedios "por si acaso" llena el espacio de nombres de ruido permanente.

Consejo 2: escribe un mensaje de verdad. El mensaje de la etiqueta es el mejor sitio para las notas de la versión: viaja con el repositorio, no depende de ninguna herramienta externa y se lee con git show.

Consejo 3: incrusta git describe --tags --always --dirty en tus compilaciones. Es la forma más barata de que cualquier informe de error incluya la versión exacta.

Consejo 4: git tag --contains <sha> para responder "¿en qué versión entró esto?". Es más rápido y más fiable que buscar en el log por fechas.

Consejo 5: acuerda SemVer con el equipo y escríbelo. El valor de MAJOR.MINOR.PATCH está en que todos entiendan lo mismo. Un número de versión que nadie sabe interpretar es solo un número.

En un repositorio de pruebas con al menos tres commits:

1. Crea una etiqueta ligera y una anotada sobre el mismo commit.
2. Demuestra con git cat-file -t que una resuelve a commit y la otra a tag.
3. Muestra el contenido del objeto tag con git cat-file -p e identifica sus cinco partes.
4. Compara la salida de git show con cada una.

Simula la evolución de gestor-tareas:

1. Tres commits y v1.0.0 (anotada, con mensaje de notas de versión).
2. Un commit de corrección y v1.0.1.
3. Dos commits de funcionalidad nueva y v1.1.0.
4. Lista las etiquetas ordenadas por versión, de la más nueva a la más antigua.
5. Muestra qué cambió entre v1.0.0 y v1.1.0.
6. Averigua en qué versión entró el commit de corrección sin mirar el log.

Partiendo del ejercicio 2:

1. Añade cuatro commits más a main y comprueba la salida de git describe. Interpreta cada parte.
2. Modifica un fichero sin confirmar y observa el efecto de --dirty.
3. Crea una rama de mantenimiento que arranque en v1.0.0.
4. Lleva a esa rama, con cherry-pick, la corrección de la 1.0.1, y etiqueta el resultado como v1.0.2.
5. Comprueba con git describe en cada rama que los nombres son coherentes.

Solución 1:

Las cinco partes: object (el commit apuntado), type (qué es), tag (el nombre), tagger (autoría y fecha) y el mensaje.

La anotada muestra un bloque más: el suyo propio.

Solución 2:

Entró en la v1.0.1 (la primera de la lista) y, naturalmente, sigue presente en la v1.1.0.

Solución 3:

La etiqueta anotada más reciente alcanzable es v1.1.0, han pasado 4 commits desde ella, y el commit actual es 9e2c6b1.

Cada rama se nombra respecto a su propia línea de etiquetas, que es exactamente lo que se espera de un esquema de versiones con mantenimiento.

Las etiquetas son la memoria estable del repositorio. Lo esencial:

• Una etiqueta es una referencia que no se mueve. Vive en refs/tags/, marca un commit concreto para siempre y no puede ser el destino de HEAD (te deja en detached HEAD).
• Hay dos clases. La ligera es un puntero pelado, sin objeto propio. La anotada crea un objeto tag en la base de datos —el cuarto tipo de la lección 01-04— con autor, fecha, mensaje y firma opcional. Para versiones publicadas, siempre anotadas.
• Se crean con git tag -a <nombre> -m "...", opcionalmente sobre un commit del pasado; se listan con git tag -l "<patrón>", -n y --sort=-v:refname; se examinan con git show; y git tag --contains <sha> responde a "¿en qué versión entró esto?".
• El versionado semántico (MAJOR.MINOR.PATCH) da significado compartido al número: incompatible / funcionalidad nueva / corrección. Antes de la 1.0.0 no hay compromiso; después, una versión publicada no se toca nunca.
• Las etiquetas no viajan solas: git push origin <etiqueta> para una concreta, --tags para todas (rara vez lo que quieres) y --follow-tags —o push.followTags true— para las anotadas alcanzables, que es lo correcto en el día a día.
• Se borran con git tag -d en local y git push origin --delete en remoto, pero una etiqueta publicada no se mueve: quien ya la tiene no la actualiza, y el resultado son dos verdades distintas conviviendo. Si hay un fallo, se publica la siguiente versión.
• git describe --tags --always --dirty nombra cualquier commit respecto a la última etiqueta y es la forma canónica de versionar compilaciones.
• Para trabajar sobre una versión publicada, crea una rama desde la etiqueta; la etiqueta sola solo sirve para mirar.

Ya sabemos marcar el pasado. Falta la operación complementaria y la más delicada de todas: deshacerlo.

Porque va a pasar. Alguien va a publicar en main un commit que rompe algo, y va a estar ya en el servidor, y tres personas lo van a tener descargado. La regla de oro prohíbe reescribirlo. ¿Entonces?

Git tiene una respuesta para eso, y es elegante: no borrar el commit, sino añadir otro que aplique el cambio contrario. Es git revert, la única forma segura de deshacer algo que ya es público, y con ella cerramos el módulo en la lección 05-06: Revirtiendo Confirmaciones.