git tag

Qué es una etiqueta de Git

Una etiqueta es una referencia con nombre que apunta a un commit específico en el historial de Git. A diferencia de una rama, que avanza cada vez que realizas un commit, una etiqueta permanece fija en el commit para el que fue creada. Esto hace que las etiquetas sean ideales para marcar puntos permanentes y significativos en un proyecto — con mayor frecuencia versiones de lanzamiento como v1.0.0 o v2.3.1.

Esta página cubre cómo crear los dos tipos de etiquetas (anotadas y ligeras), cómo listarlas y filtrarlas, cómo etiquetar commits anteriores, y cómo enviar, inspeccionar y eliminar etiquetas.

Crear una etiqueta de Git

Para crear una etiqueta de Git, ejecuta el siguiente comando:

git tag

git tag <name-of-tag>

Al crear una etiqueta, reemplaza <name-of-tag> con un identificador semántico para el estado del repositorio — por ejemplo v1.3. Git admite dos tipos de etiquetas: anotadas y ligeras. La principal diferencia entre ellas es la cantidad de metadatos que almacenan.

Etiquetas anotadas vs. etiquetas ligeras

Elegir el tipo correcto de etiqueta importa más de lo que parece:

• Las etiquetas anotadas se almacenan como objetos completos en la base de datos de Git. Registran el nombre, el correo electrónico y la fecha del autor de la etiqueta, incluyen un mensaje de etiquetado y pueden firmarse y verificarse criptográficamente con GPG (GNU Privacy Guard). Úsalas para lanzamientos y para todo lo que compartas con otros.
• Las etiquetas ligeras son simplemente un nombre que apunta a un commit — sin metadatos adicionales, sin mensaje, sin firma. Se comportan como un marcador privado. Úsalas para marcadores temporales o locales.

Para versiones publicadas, prefiere las etiquetas anotadas para que el historial registre quién etiquetó el lanzamiento y cuándo.

Etiquetas anotadas

Git almacena las etiquetas anotadas como objetos completos en su base de datos. Contienen metadatos adicionales, como el nombre, el correo electrónico y la fecha del autor de la etiqueta. Al igual que los commits, las etiquetas anotadas incluyen un mensaje de etiquetado.

Ejecutar el siguiente comando crea una nueva etiqueta anotada con el ID v1.3. A continuación, se abrirá el editor de texto predeterminado configurado, pidiéndote que introduzcas un mensaje de etiquetado.

git annotated tag

git tag -a v1.3

Para proporcionar el mensaje directamente en línea y omitir el editor, usa la opción -m:

git annotated tag with inline message

git tag -a v1.3 -m "Release version 1.3"

Etiquetas ligeras

El siguiente comando crea una etiqueta ligera identificada como v1.3-lw. Las etiquetas ligeras se crean sin las opciones -a, -s ni -m. Simplemente almacenan un puntero a un objeto de commit específico en el directorio .git/refs/tags/.

git lightweight tag

git tag v1.3-lw

Lista de etiquetas

Ejecuta el siguiente comando para listar las etiquetas almacenadas:

git tag command

git tag

Como resultado, verás una salida similar a esta:

git tag output

v0.10.0
v0.10.0-rc1
v0.11.0
v0.11.0-rc1
v0.11.1
v0.11.2
v0.12.0
v0.12.0-rc1
v0.12.1
v0.12.2
v0.13.0
v0.13.0-rc1
v0.13.0-rc2

Puedes usar la opción -l con una expresión comodín para filtrar la lista de etiquetas:

git tag with wildcard

git tag -l *-rc*
v0.10.0-rc1
v0.11.0-rc1
v0.12.0-rc1
v0.13.0-rc1
v0.13.0-rc2
v0.14.0-rc1
v0.9.0-rc1
v15.0.0-rc.1
v15.0.0-rc.2
v15.4.0-rc.3

Etiquetar commits anteriores

Por defecto, git tag crea una etiqueta en el commit al que apunta HEAD. También puedes pasar una referencia de commit específica para etiquetar un commit anterior. Ejecuta el comando git log para ver los commits anteriores. En el ejemplo a continuación, se usa un commit de fusión para la nueva etiqueta. Para referenciar un commit específico, proporciona su hash SHA:

git log

git log --pretty=oneline
29389857951b64cf874c3557a0f3547bd83b899a Merging branch 'crossword'
b4a5697498bd301d84096da251c98a07c7723e65 init method for crossword
89f3aaab4479697da7686c15f77a3d64d9165190 little changes in logic
3a4a271eda8725415634dd79daabbc4d9b6008e Merging branch 'how-it-works'

Ejecuta el comando git tag para crear una nueva etiqueta anotada con el ID v1.2 para el commit seleccionado en el ejemplo anterior:

git tag for old commits

git tag -a v1.2 29389857951b64cf874c3557a0f3547bd83b899a

Reemplazar etiquetas antiguas

Intentar crear una etiqueta con un identificador existente resultará en un error. Usa la opción -f (force) para actualizar una etiqueta existente, lo que sobrescribirá su contenido anterior.

git tag replacing old tags

git tag -a -f v1.3 29389857951b64cf874c3557a0f3547bd83b899a

Enviar etiquetas al repositorio remoto

Las etiquetas no se envían automáticamente con git push — por defecto git push transfiere commits pero deja tus etiquetas atrás. Debes enviarlas explícitamente para que cualquiera que clone el repositorio las reciba.

Para enviar una sola etiqueta, pasa su nombre a git push:

git tag, pushing to remote

git push origin v1.3
Counting objects: 9, done.
Delta compression using up to 5 threads.
Compressing objects: 100% (8/8), done.
Writing objects: 100% (12/12), 2.05 KiB | 0 bytes/s, done.
Total 12 (delta 3), reused 0 (delta 0)
To [email protected]:gr8/gittagdocs.git
* [new tag] v1.3 -> v1.3

Para enviar todas las etiquetas locales que el repositorio remoto aún no tenga, usa la opción --tags:

git push all tags

git push origin --tags

Inspeccionar una etiqueta

Usa git show para ver los datos almacenados en una etiqueta. Para una etiqueta anotada, muestra los metadatos de la etiqueta (autor, fecha, mensaje) seguidos del commit al que apunta:

git show on an annotated tag

git show v1.3
tag v1.3
Tagger: Jane Doe <[email protected]m>
Date:   Mon Jun 9 14:21:03 2025 +0000

Release version 1.3

commit 29389857951b64cf874c3557a0f3547bd83b899a
Author: Jane Doe <[email protected]m>
Date:   Mon Jun 9 14:18:55 2025 +0000

    Merging branch 'crossword'

Hacer checkout de una etiqueta

Puedes usar el comando git checkout para inspeccionar un commit etiquetado. Esto coloca el repositorio en un estado de HEAD desacoplado — HEAD apunta directamente a un commit en lugar de a una rama. Cualquier nuevo commit que realices aquí no pertenecerá a ninguna rama y solo será accesible a través de su hash SHA, por lo que puede perderse una vez que cambies de contexto.

git tag, checking out a tag

git checkout v1.3

Si quieres seguir trabajando desde ese punto, crea una rama en ese lugar:

branch from a tag

git checkout -b release-1.3 v1.3

Eliminar etiquetas

Puedes eliminar una etiqueta local pasando la opción -d y el identificador de la etiqueta a git tag. Consulta el ejemplo a continuación:

git tag, deleting tags

git tag
v1
v2
v3
git tag -d v1
git tag
v2
v3

Eliminar una etiqueta localmente no la elimina del repositorio remoto. Para eliminar una etiqueta del repositorio remoto también, envía la eliminación:

git delete remote tag

git push origin --delete v1

Temas relacionados

• git log — encuentra el commit que quieres etiquetar.
• git push — publica tus etiquetas en un repositorio remoto.
• git branch — convierte un commit etiquetado en una rama sobre la que puedas trabajar.

Práctica