Introducción

Los tags son referencias nombradas a commits específicos. A diferencia de los branches, los tags no están destinados a moverse. Son perfectos para marcar releases (v1.0.0) y otros puntos históricos.

Dos tipos de tags

• Lightweight: solo una ref que apunta a un commit. Sin metadatos.
• Anotados: un objeto Git completo con tagger, fecha, mensaje y firma GPG opcional. Usa estos para releases.

Creando tags

git tag v1.0.0                          # lightweight
git tag -a v1.0.0 -m "First stable release"   # anotado
git tag -s v1.0.0 -m "Signed release"         # firmado GPG

Por defecto los tags se adjuntan a HEAD. Para etiquetar un commit específico:

git tag -a v0.9.0 a1b2c3d -m "Beta"

Listando e inspeccionando

git tag
git tag -l "v1.*"
git show v1.0.0
git tag -l --format='%(refname:short) %(taggerdate:short) %(subject)'

Pusheando tags

Los tags no se pushean por defecto:

git push origin v1.0.0
git push origin --tags                # todos los tags
git push --follow-tags                # solo tags alcanzables desde commits pusheados

--follow-tags es el predeterminado recomendado para pipelines de release.

Eliminando tags

git tag -d v1.0.0                     # local
git push origin --delete v1.0.0       # remoto

Haciendo checkout de un tag

git switch --detach v1.0.0
# o para basar un branch hotfix en un tag
git switch -c hotfix/1.0.1 v1.0.0

Verificando firmas

git tag -v v1.0.0

Requiere la clave pública del tagger en tu GPG keyring.

Describiendo builds con git describe

Una vez que tu repo tenga tags anotados, git describe produce identificadores de build estables que combinan el último tag, la distancia y el SHA abreviado:

git describe
# v1.2.3-7-gabc1234
git describe --always --dirty
# v1.2.3-7-gabc1234-dirty

El sufijo --dirty aparece si el árbol de trabajo tiene cambios no commiteados; --always recurre a un SHA simple cuando no hay tag alcanzable. Los pipelines de CI a menudo embeben esta cadena en los binarios para hacer trivial la solución de problemas en reportes de campo.

Políticas de etiquetado

Para proyectos con soporte a largo plazo, decide y documenta:

• Esquema de nombres: v1.2.3, release-2025-04, 1.2.3 (sin prefijo)?
• Anotados o firmados?
• Quién puede pushear tags? Muchos hosts te permiten proteger nombres de tags con patrones.
• Cuál es la fuente de verdad: solo tags-en-main, o branches de release con sus propios tags?

git for-each-ref --sort=-creatordate --format='%(refname:short) %(creatordate:short)' refs/tags | head

Elige un esquema y apégate a él; el historial de tags es más difícil de migrar que el historial de commits.

Errores comunes

Usar tags lightweight para releases. Carecen de fecha, autor y mensaje, lo que hace dolorosos los registros de auditoría. Siempre usa -a o -s para releases. Mover un tag después de que se ha publicado; los usuarios downstream no recogerán el cambio limpiamente. Crea un nuevo tag (p.ej. v1.0.1) en su lugar. Olvidar pushear tags y preguntarte por qué tu página de release está vacía; recuerda git push --tags o --follow-tags. Finalmente, nombrar tags con caracteres que entran en conflicto con refs (un tag y un branch llamados release crearán ambigüedad); usa una convención clara como v<semver> para releases.