HOWTO · Git
Tag Checkout dans Git
Ce didacticiel montre comment extraire la dernière balise dans git à l'aide de diverses commandes.
Sur cette page
Un tag Git est une référence qui désigne un commit, souvent pour marquer une version. Contrairement à une branche, un tag n’avance pas au fil des nouveaux commits. Il peut toutefois être déplacé ou supprimé : considérez-le comme une référence dont la cible peut changer, notamment lorsque vous coordonnez votre travail avec un dépôt distant.
Un tag léger est une référence directe vers un commit. Un tag annoté est un objet Git distinct qui peut contenir un message, le nom et la date de la personne qui l’a créé, ainsi qu’une signature facultative. Choisissez selon les métadonnées et le niveau de vérification dont votre projet a besoin ; aucun des deux types n’est intrinsèquement privé ou public.
Ce que désigne un tag Git
Un tag désigne un commit précis de l’historique du dépôt. Si vous créez un tag sans indiquer un autre commit, il pointe vers le commit actuellement extrait, que HEAD identifie. Un tag ne contient pas l’historique évolutif d’une branche : les commits ultérieurs de cette branche ne le font pas avancer.
Lorsque vous extrayez un tag, Git place l’arbre de travail sur le commit correspondant. Comme HEAD désigne alors directement le commit plutôt qu’une branche, vous êtes normalement dans un état où HEAD est détaché. Vous pouvez examiner ou compiler cet instantané sans risque. Si vous créez des commits que vous souhaitez conserver, créez une branche avant ou après.
Créer un tag dans Git
Utilisez git tag v1.0 pour créer un tag léger sur le commit actuel. Pour ajouter un message et les métadonnées de la personne qui l’a créé, utilisez git tag -a v1.0 -m "Release 1.0". L’option -a crée un tag annoté ; -m fournit son message. Vous pouvez aussi créer un tag sur un commit précis en ajoutant l’identifiant de ce commit à la fin de l’une ou l’autre commande.
Ces commandes illustrent la création d’un tag ; elles ne sont pas nécessaires pour extraire un tag existant. Choisissez un nom unique et explicite, et coordonnez avec vos collaborateurs toute modification d’un tag publié, car une référence de tag peut être mise à jour ou supprimée.
Récupérer les tags d’un dépôt distant
Un clone peut ne pas encore contenir le tag dont vous avez besoin, notamment si le dépôt distant a reçu de nouvelles versions depuis votre dernière récupération. Avant d’extraire un tag distant manquant, récupérez les tags : git fetch --tags origin demande à Git de récupérer les tags depuis origin. Pour récupérer les tags de tous les dépôts distants configurés, utilisez git fetch --all --tags. --all désigne tous les dépôts distants configurés ; --tags demande les tags. Ce sont deux options distinctes, et non une option combinée -all.
La récupération met à jour les références locales à partir des dépôts distants, mais n’extrait aucun tag et ne change pas la branche actuelle. Si vous savez que le tag est déjà présent localement, vous pouvez ignorer cette étape.
Extraire un tag précis
Pour examiner l’instantané nommé v1.0, exécutez git checkout v1.0. Git place l’arbre de travail sur le commit associé au tag et laisse normalement HEAD détaché. L’ancienne commande git checkout peut aussi changer de branche : la référence nommée est donc importante. Cette commande extrait le tag si ce nom correspond à un tag.
Un HEAD détaché convient pour lire, tester ou compiler une version. Évitez d’y effectuer du travail que vous souhaitez conserver sans créer de branche : un commit réalisé dans cet état n’est rattaché à aucune branche et peut devenir difficile à retrouver après avoir changé de référence. La section suivante montre comment créer une branche à partir du tag.
Exécutez cet exemple local autonome pour extraire le commit associé au tag et créer une branche de travail :
Le code et les libellés ou sorties affichés dans cette section restent en anglais.
workdir="$(mktemp -d)"
trap 'rm -rf "$workdir"' EXIT
cd "$workdir"
git init -q
git config user.name "Example User"
git config user.email "example@example.com"
printf 'Release snapshot\n' > README.md
git add README.md
git commit -qm "Add release snapshot"
git tag -a v1.0 -m "Release 1.0"
git checkout -q v1.0
git switch -q -c release-work
printf 'Checked out release-work\n'
Checked out release-work
Créer une branche à partir d’un tag
Si vous comptez créer des commits à partir d’un tag, créez une branche sur ce tag. Par exemple, git switch -c release-work v1.0 crée la branche release-work à partir de v1.0 et la sélectionne. La forme plus ancienne équivalente est git checkout -b release-work v1.0. La nouvelle branche commence au commit associé au tag ; les commits suivants font avancer la branche tandis que le tag continue de désigner sa cible initiale, sauf si quelqu’un le déplace.
Si vous avez déjà extrait le tag, git switch -c release-work crée une branche sur le commit actuel. C’est la façon pratique de conserver le travail commencé depuis un état où HEAD est détaché.
Trouver et extraire le tag le plus récent
« Le plus récent » peut désigner le numéro de version le plus élevé ou le tag le plus récent accessible depuis le commit actuel. Ce sont deux questions différentes, et choisir le dernier nom dans l’ordre lexicographique ne permet de répondre correctement à aucune des deux. Récupérez d’abord les tags si nécessaire, puis affichez les noms ressemblant à des versions avec git tag --list 'v*' --sort=-version:refname ; examinez la liste et choisissez la version voulue. Le tri par version est utile si les noms suivent un format cohérent, mais il ne permet pas d’établir quel tag est le plus proche dans l’historique du commit actuel.
Pour trouver un tag descriptif accessible depuis le commit actuel, utilisez git describe --tags. La commande sélectionne un tag selon les règles de Git relatives à l’historique des commits ; si le commit actuel n’est pas lui-même tagué, le résultat comprend souvent la distance en commits et un identifiant abrégé. Ce n’est pas nécessairement la version la plus élevée, et les tags ne sont pas triés selon leur date de création. Après avoir choisi le nom voulu, utilisez git checkout <tag-name> pour examiner le tag, ou git switch -c <branch-name> <tag-name> pour commencer à travailler à partir de celui-ci.
Vérifier le commit extrait
Vérifiez le commit atteint et l’état du dépôt avec git status --short --branch, git rev-parse HEAD et git show --no-patch --decorate --oneline HEAD. L’identifiant fourni par git rev-parse HEAD est celui du commit actuellement extrait. La sortie de git status indique si vous êtes sur une branche ou dans un état où HEAD est détaché ; l’affichage décoré du commit peut montrer un tag qui désigne ce commit.
Le nom d’un tag ne prouve pas que l’arbre de travail se trouve sur ce tag : vérifiez le commit après l’extraction, en particulier lorsque des branches et des tags portent des noms similaires. Si vous avez créé une branche à partir du tag, son nom doit apparaître dans l’état du dépôt, tandis que HEAD identifie toujours le commit actuel.