git tag

O que é uma tag do Git

Uma tag é uma referência nomeada que aponta para um commit específico no histórico do Git. Ao contrário de um branch, que avança cada vez que você faz um commit, uma tag permanece fixada no commit para o qual foi criada. Isso torna as tags ideais para marcar pontos significativos e permanentes em um projeto — mais comumente versões de lançamento como v1.0.0 ou v2.3.1.

Esta página aborda como criar os dois tipos de tags (anotadas e leves), como listá-las e filtrá-las, como adicionar tags a commits antigos e como enviar, inspecionar e excluir tags.

Criando uma tag do Git

Para criar uma tag do Git, execute o comando abaixo:

git tag

git tag <name-of-tag>

Ao criar uma tag, substitua <name-of-tag> por um identificador semântico para o estado do repositório — por exemplo, v1.3. O Git suporta dois tipos de tags: anotadas e leves. A principal diferença entre elas é a quantidade de metadados que armazenam.

Tags anotadas vs. tags leves

Escolher o tipo certo de tag importa mais do que parece:

• Tags anotadas são armazenadas como objetos completos no banco de dados do Git. Elas registram o nome, e-mail e data do criador da tag, incluem uma mensagem de tag e podem ser assinadas e verificadas criptograficamente com GPG (GNU Privacy Guard). Use-as para lançamentos e para tudo que você compartilha com outras pessoas.
• Tags leves são apenas um nome apontando para um commit — sem metadados extras, sem mensagem, sem assinatura. Elas se comportam como um marcador privado. Use-as para marcadores temporários ou locais.

Para versões publicadas, prefira tags anotadas para que o histórico registre quem marcou o lançamento e quando.

Tags anotadas

O Git armazena tags anotadas como objetos completos em seu banco de dados. Elas contêm metadados adicionais, como o nome, e-mail e data do criador da tag. Assim como os commits, as tags anotadas incluem uma mensagem de tag.

Executar o comando abaixo cria uma nova tag anotada com o ID v1.3. O editor de texto padrão configurado será aberto, solicitando que você insira uma mensagem de tag.

git annotated tag

git tag -a v1.3

Para fornecer a mensagem diretamente e ignorar o editor, use a opção -m:

git annotated tag with inline message

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

Tags leves

O comando abaixo cria uma tag leve identificada como v1.3-lw. Tags leves são criadas sem as opções -a, -s ou -m. Elas simplesmente armazenam um ponteiro para um objeto de commit específico no diretório .git/refs/tags/.

git lightweight tag

git tag v1.3-lw

Lista de tags

Execute o comando abaixo para listar as tags armazenadas:

git tag command

git tag

Como resultado, você verá uma saída semelhante 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

Você pode usar a opção -l com uma expressão curinga para filtrar a lista de tags:

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

Adicionando tags a commits antigos

Por padrão, git tag cria uma tag no commit referenciado por HEAD. Você também pode passar uma referência de commit específica para adicionar uma tag a um commit mais antigo. Execute o comando git log para visualizar commits mais antigos. No exemplo abaixo, um commit de merge é usado para a nova tag. Para referenciar um commit específico, forneça seu 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'

Execute o comando git tag para criar uma nova tag anotada com o ID v1.2 para o commit selecionado no exemplo anterior:

git tag for old commits

git tag -a v1.2 29389857951b64cf874c3557a0f3547bd83b899a

Substituindo tags antigas

Tentar criar uma tag com um identificador já existente resultará em um erro. Use a opção -f (forçar) para atualizar uma tag existente, o que substituirá seu conteúdo anterior.

git tag replacing old tags

git tag -a -f v1.3 29389857951b64cf874c3557a0f3547bd83b899a

Enviando tags para o repositório remoto

As tags não são enviadas automaticamente com o git push — por padrão, o git push transfere commits, mas deixa suas tags para trás. Você precisa enviá-las explicitamente para que qualquer pessoa que clone o repositório as receba.

Para enviar uma única tag, passe seu nome para 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 as tags locais que o repositório remoto ainda não possui, use a opção --tags:

git push all tags

git push origin --tags

Inspecionando uma tag

Use o git show para visualizar os dados armazenados em uma tag. Para uma tag anotada, ele exibe os metadados da tag (criador, data, mensagem) seguidos do commit para o qual aponta:

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'

Fazendo checkout de uma tag

Você pode usar o comando git checkout para inspecionar um commit com tag. Isso coloca o repositório em um estado de HEAD desanexado — o HEAD aponta diretamente para um commit em vez de um branch. Quaisquer novos commits que você fizer aqui não pertencerão a um branch e só serão acessíveis por meio do hash SHA, portanto podem ser perdidos quando você mudar de branch.

git tag, checking out a tag

git checkout v1.3

Se você quiser continuar trabalhando a partir desse ponto, crie um branch no local:

branch from a tag

git checkout -b release-1.3 v1.3

Excluindo tags

Você pode excluir uma tag local passando a opção -d e o identificador da tag para git tag. Veja o exemplo abaixo:

git tag, deleting tags

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

Excluir uma tag localmente não a remove do repositório remoto. Para excluir uma tag do remoto também, envie a exclusão:

git delete remote tag

git push origin --delete v1

Tópicos relacionados

• git log — encontre o commit que deseja marcar com uma tag.
• git push — publique suas tags em um repositório remoto.
• git branch — transforme um commit com tag em um branch no qual você pode continuar trabalhando.

Prática