HOWTO · Git
Déplacer une balise existante dans Git
Vous pouvez déplacer une balise Git existante vers le commit de votre choix.
Sur cette page
Une balise Git désigne un point précis de l’historique d’un dépôt, généralement un commit. Vous pouvez déplacer une balise locale vers le commit de votre choix et, avec l’accord de l’équipe, remplacer également la référence distante. Avant de modifier une balise utilisée pour une version publiée, coordonnez-vous avec vos collaborateurs : ils ont peut-être déjà récupéré l’ancienne cible, et des compilations automatisées ou des archives de publication peuvent en dépendre.
Comprendre les balises Git et les risques liés à leur déplacement
Une balise légère est une référence directe vers un objet Git, généralement un commit. Une balise annotée est un objet Git distinct qui contient un message et des métadonnées sur la personne qui l’a créée ; elle peut aussi être signée. Remplacer une balise change l’objet auquel son nom aboutit. Pour recréer une balise annotée, vous devez fournir de nouveau son message ; pour recréer une balise signée, vous devez la signer à nouveau. Le nouvel objet de balise ne conserve ni l’ancien objet ni sa signature.
Avant de la modifier, identifiez sa cible actuelle avec git show --no-patch --format=%H <tag>, puis choisissez le commit qui la remplacera. Indiquez un identifiant de commit ou une autre révision explicite comme nouvelle cible, plutôt que de vous fier au commit actuellement extrait. Si la balise est partagée, informez vos collaborateurs de la cible prévue et précisez qu’ils devront peut-être actualiser leur copie locale.
Déplacer une balise locale vers un autre commit
Utilisez git tag -f <tag> <commit> pour déplacer directement une balise locale. L’option -f remplace le nom local existant. Pour une balise annotée, recréez l’annotation avec git tag -f -a <tag> <commit> -m "<message>" ; remplacez -a par -s si la balise doit être signée, et configurez la signature conformément aux exigences de votre dépôt. Lorsque c’est pertinent, conservez le message d’origine et le sens de la version publiée.
Exécutez cet exemple dans un shell où Git est installé. Le bloc de code et les libellés ou sorties qu’il affiche restent en anglais.
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
Dans votre dépôt, remplacez les valeurs par le nom réel de la balise et le commit cible. Si une commande simple comme git tag <tag> <commit> indique que la balise existe déjà, c’est normal : utilisez l’option de forçage uniquement après avoir vérifié la cible de remplacement.
Mettre à jour la balise distante
Après vous être coordonné avec l’équipe, mettez à jour uniquement la balise distante nommée avec git push --force origin <tag>. Cette commande remplace la référence distante de cette balise ; cela ne rend pas la modification sans risque pour les collaborateurs qui utilisent encore l’ancienne cible. Évitez de pousser toutes les balises si vous souhaitez n’en modifier qu’une seule. Si le serveur refuse la mise à jour, vérifiez les autorisations du dépôt et les protections de balises configurées côté serveur, au lieu de répéter la commande avec l’option de forçage.
Récupérer une balise mise à jour par quelqu’un d’autre
Si quelqu’un d’autre a déplacé la balise distante, votre balise locale peut encore pointer vers son ancienne cible. Récupérez la balise nommée avec git fetch origin tag <tag>. Si Git indique que cette récupération écraserait la balise locale existante, supprimez cette référence locale avec git tag -d <tag>, puis récupérez de nouveau la balise nommée. La suppression de la référence locale ne supprime pas la balise distante. Ce cas diffère d’une récupération réussie qui laisse une référence inchangée ; une commande générale git pull ne remplace pas de façon fiable la récupération explicite de cette balise.
Vérifier que la balise pointe vers le commit voulu
Vérifiez le commit de la balise locale avec git rev-parse <tag>^{}. Le suffixe ^{} résout une balise annotée jusqu’au commit qu’elle désigne finalement. Comparez l’identifiant complet de ce commit à celui du commit voulu, par exemple à l’identifiant renvoyé par git rev-parse <commit>.
Pour examiner la référence distante sans modifier les références locales, exécutez git ls-remote --tags origin <tag>. Ce motif sélectionne la balise nommée et correspond aussi à sa référence résolue. Pour une balise annotée, la ligne qui se termine par ^{} indique le commit qu’elle désigne finalement ; comparez son identifiant à celui du commit voulu. Si un collaborateur modifie une balise partagée, communiquez la nouvelle cible afin que chacun puisse vérifier qu’il dispose de la même référence de version.