HOWTO · Git

Mover una etiqueta existente en Git

Mueve una etiqueta existente de Git al commit que elijas.

En esta página

Una etiqueta de Git identifica un punto concreto del historial del repositorio, normalmente un commit. Puedes mover una etiqueta local al commit que elijas y, si el equipo está de acuerdo, reemplazar también la referencia remota. Coordínate antes de cambiar una etiqueta que otras personas usan para una versión: quizá ya hayan obtenido el destino anterior, y las compilaciones automatizadas o los registros de versiones podrían depender de él.

Comprender las etiquetas de Git y los riesgos de moverlas

Una etiqueta ligera es una referencia directa a un objeto de Git, normalmente un commit. Una etiqueta anotada es un objeto de Git independiente que contiene un mensaje y metadatos del etiquetador; también puede estar firmada. Al reemplazar una etiqueta, cambia el objeto al que apunta ese nombre. Para recrear una etiqueta anotada, debes volver a proporcionar su mensaje; para recrear una etiqueta firmada, debes firmarla de nuevo. El nuevo objeto de etiqueta no conserva el objeto ni la firma anteriores.

Antes de cambiar una etiqueta, identifica su destino actual con git show --no-patch --format=%H <tag> y decide qué commit la sustituirá. Usa el ID de un commit u otra revisión explícita como nuevo destino, en vez de depender del commit que esté activo en ese momento. Si la etiqueta es compartida, comunica a tus colaboradores cuál será el nuevo destino y avísales de que quizá deban actualizar su copia local.

Mover una etiqueta local a otro commit

Usa git tag -f <tag> <commit> para mover directamente una etiqueta local. La opción -f reemplaza el nombre local existente. Para una etiqueta anotada, vuelve a crear la anotación con git tag -f -a <tag> <commit> -m "<message>"; si la etiqueta debe estar firmada, usa -s en lugar de -a y configura el método de firma que requiere tu repositorio. Cuando corresponda, conserva el mensaje original y el sentido de la versión.

Ejecuta este ejemplo en una shell con Git instalado. El ejemplo muestra en inglés si la etiqueta apunta al commit previsto; tanto el código como ese mensaje de salida se mantienen en inglés.

set -eu
repo_dir=$(mktemp -d)
trap 'rm -rf "$repo_dir"' EXIT
git -C "$repo_dir" init -q
git -C "$repo_dir" config user.name "Example User"
git -C "$repo_dir" config user.email "example@example.com"
printf 'first\n' > "$repo_dir/file.txt"
git -C "$repo_dir" add file.txt
git -C "$repo_dir" commit -qm "first commit"
first_commit=$(git -C "$repo_dir" rev-parse HEAD)
git -C "$repo_dir" tag v1.0 "$first_commit"
printf 'second\n' >> "$repo_dir/file.txt"
git -C "$repo_dir" commit -qam "second commit"
target_commit=$(git -C "$repo_dir" rev-parse HEAD)
git -C "$repo_dir" tag -f v1.0 "$target_commit" >/dev/null
tag_commit=$(git -C "$repo_dir" rev-parse refs/tags/v1.0)
if [ "$tag_commit" = "$target_commit" ]; then
  printf 'tag points to intended commit: yes\n'
else
  printf 'tag points to intended commit: no\n'
fi

En tu repositorio, sustituye los valores por el nombre real de la etiqueta y el commit de destino. Si al ejecutar git tag <tag> <commit> Git indica que la etiqueta ya existe, es lo esperado: usa la opción de fuerza solo después de confirmar el nuevo destino.

Actualizar la etiqueta remota

Después de coordinarte con el equipo, actualiza únicamente la etiqueta remota indicada con git push --force origin <tag>. Esto reemplaza la referencia remota de esa etiqueta, pero no hace que el cambio sea seguro para quienes todavía usan el destino anterior. Evita publicar todas las etiquetas si solo quieres cambiar una. Si el servidor rechaza la actualización, comprueba los permisos del repositorio y las protecciones de etiquetas del servidor en vez de repetir el envío forzado.

Obtener una etiqueta que otra persona actualizó

Si otra persona movió la etiqueta remota, es posible que tu etiqueta local todavía apunte al destino anterior. Obtén la etiqueta indicada con git fetch origin tag <tag>. Si Git informa de que obtenerla sobrescribiría la etiqueta local existente, elimina esa referencia local con git tag -d <tag> y vuelve a obtener la etiqueta indicada. Eliminar la referencia local no elimina la etiqueta remota. Este error es distinto de una descarga correcta que deja la referencia sin cambios; un git pull general no sustituye de forma fiable la obtención explícita de esta etiqueta.

Comprobar que la etiqueta apunta al commit previsto

Comprueba a qué commit apunta la etiqueta local con git rev-parse <tag>^{}. El sufijo ^{} sigue una etiqueta anotada hasta el commit que identifica finalmente. Compara el ID completo de ese commit con el del destino previsto, por ejemplo, con el ID que devuelve git rev-parse <commit>.

Para inspeccionar el remoto sin cambiar las referencias locales, ejecuta git ls-remote --tags origin <tag>. Este patrón selecciona la etiqueta indicada y también coincide con su referencia resuelta. En una etiqueta anotada, la línea que termina en ^{} indica el commit al que apunta finalmente; compara ese ID con el del destino previsto. Si un colaborador cambia una etiqueta compartida, comunica el nuevo destino para que todos puedan comprobar que tienen la misma referencia de versión.