git tag

Branches e merge

Cria, lista e exclui tags

O comando 'git tag' dá um nome fixo a um commit, normalmente uma versão como v1.0. Diferente de um branch, uma tag nunca se move. Uma tag leve é só um nome; uma tag anotada (-a) é um objeto completo com quem a criou, uma data e uma mensagem, e é o tipo recomendado para versões. Tags não são enviadas automaticamente: envie-as com git push origin <tag>.

Sinopse

git tag [-a | -s] [-f] [-m <msg>] <tagname> [<commit>]
git tag -d <tagname>...
git tag [-n[<num>]] -l [<pattern>...]
[ ] opcional| ou<arg> valor a substituir... repetível--flag opção

Opções

Clique em uma opção para expandir

Iniciante (3)

Cria um objeto tag anotado com autor, data e mensagem.

RecomendadoVersões devem registrar quem marcou, quando e por quê

Exemplo

git tag -a v1.0 -m "First release"

Lista as tags, opcionalmente só as que correspondem a um padrão.

RecomendadoFiltrar uma lista longa de tags com um padrão

Exemplo

git tag -l "v1.*"

Exclui as tags locais indicadas.

Quando necessárioCorrigir uma tag local errada; evite excluir tags que outros usam

Exemplo

git tag -d v1.0

Intermediário (1)

Substitui uma tag existente, movendo-a para outro commit.

Não recomendadoMover uma tag publicada confunde todos que a baixaram

Exemplo

git tag -f v1.0

Escolhendo a opção certa

Leve versus anotada

Dois tipos de tags

ComandoGuardaUsar para
git tag v1.0Só o nomeMarcadores pessoais
git tag -a v1.0 -m "..."Autor, data, mensagemVersões publicadas

Tag versus branch

Os dois nomeiam um commit

ComandoAvança a cada commit?Enviada pelo git push?
BranchSimSim (o branch atual)
TagNuncaNão, envie explicitamente

Exemplos

Marcar o commit atual

git tag v1.0

Uma tag leve chamada v1.0.

Tag anotada

git tag -a v1.0 -m "First release"

Uma tag com autor, data e mensagem.

Enviar uma tag

git push origin v1.0

Compartilha a tag no remoto.

Listar tags

git tag -l "v1.*"

Lista as tags que correspondem a um padrão.

Exemplos de fluxos de trabalho

1
git switch main && git pull

Estar no main mais recente

2
git tag -a v1.0 -m "First release"

Criar a tag da versão

3
git push origin v1.0

Compartilhá-la

Solução de problemas

fatal: tag 'v1.0' already exists

Causa: O nome já está em uso

Escolha outro nome, ou exclua-a antes (git tag -d v1.0)

Minha tag não está no GitHub

Causa: git push não envia as tags

git push origin v1.0, ou git push --tags

Uma tag excluída volta depois do fetch

Causa: Ela ainda existe no remoto

Exclua-a lá também: git push origin --delete v1.0

Dicas e armadilhas

Boas práticas

  • ✓Use tags anotadas para versões.
  • ✓Siga o versionamento semântico (v1.2.3).
  • ✓Nunca mova nem reutilize uma tag depois de publicada.

Erros comuns

  • ✗Esperar que git push envie as tags — envie-as explicitamente ou use --follow-tags.
  • ✗Usar tags leves para versões: elas não registram autor, data nem mensagem.
  • ✗Mover uma tag que outros já baixaram.

Perguntas frequentes

A:

git switch --detach v1.0, ou crie um branch a partir dela: git switch -c hotfix v1.0.

A:

git push --tags (ou git push --follow-tags para tags anotadas em commits enviados).

A:

Ele nomeia um commit a partir da tag mais próxima, p. ex. v1.0-3-g1a2b3c4.