Git
Português (Brasil) ▾ Topics ▾ Latest version ▾ git-tag last updated in 2.43.0

NOME

git-tag - Crie, liste, exclua or verifique um objeto tag assinado com GPG

RESUMO

git tag [-a | -s | -u <keyid>] [-f] [-m <msg> | -F <arquivo>] [-e]
	<nome da tag> [<commit> | <objeto>]
git tag -d <nome da tag>…​
git tag [-n[<num>]] -l [--contains <commit>] [--no-contains <commit>]
	[--points-at <objeto>] [--column[=<opções>] | --no-column]
	[--create-reflog] [--sort=<chave>] [--format=<formato>]
	[--[no-]merged [<commit>]] [<padrão>…​]
git tag -v [--format=<formato>] <tagname>…​

DESCRIÇÃO

Adicione uma tag de referência em refs/tags/, a menos que -d/-l/-v seja utilizado para excluir, listar ou verificar as tags.

A menos que -f seja utilizado, a tag informada não deve existir ainda.

Caso um dos comandos -a, -s ou -u <keyid> seja informado, o comando criará um objeto tag e exigirá uma mensagem para a tag. A menos que as opções -m <msg> ou -F <arquivo> sejam utilizadas, um editor é iniciado para que o usuário digite a mensagem da tag.

Caso a opção -m <msg> ou -F <arquivo> seja utilizado e a opção -a, -s e -u <keyid> estiverem ausentes, a opção -a estará implícita.

Caso contrário, é criada uma tag de referência que aponte diretamente para o objeto informado (ou seja, uma tag leve).

Um objeto de etiqueta assinada pelo GnuPG será criada quando -s ou -u <keyid> for utilizado. Quando -u <keyid> não é utilizado, a identidade do usuário atual é utilizada para encontrar a assinatura da chave GnuPG. A variável de configuração gpg.program é usada para definir o binário personalizado do GnuPG.

Os objetos tag (criados com -a, -s ou -u) são chamados de tags "anotadas"; eles contêm uma data de criação, o nome e o e-mail do marcador, uma mensagem de marcação e uma assinatura opcional do GnuPG. Enquanto uma tag "leve" é simplesmente um nome para um objeto (geralmente um objeto commit).

As tags anotadas destinam-se ao lançamento, enquanto as tags leves (light) destinam-se aos rótulos dos objetos particulares ou temporários. Por este motivo que é predefinido que alguns comandos git para nomear os objetos (como git description) ignorem essas tags leves.

OPÇÕES

-a
--annotate

Fazendo um objeto sem assinatura, com a tad anotada

-s
--sign

Faça uma etiqueta assinada por GPG utilizando a chave predefinida do endereço de e-mail. O comportamento predefinido da assinatura da tag GPG é controlado pela variável de configuração tag.gpgSign, se existir, caso contrário é desativada. Consulte git-config[1].

--no-sign

Substitua a variável de configuração tag.gpgSign que está configurada para impor a obrigatoriedade da assinatura de cada tag.

-u <keyid>
--local-user=<keyid>

Fazer uma tag assinada por GPG utilizando a chave informada.

-f
--force

Substituir uma tag existente com um determinado nome (em vez de falhar)

-d
--delete

Excluir as tags existentes com os nomes informados.

-v
--verify

Verifique a assinatura GPG com os nomes informados.

-n<num>

O <num> determina a quantidade das linhas de anotação, caso haja, são exibidas quando utilizadas com -l. Implica no uso da opção --list.

A predefinição é não imprimir nenhuma linha de anotação. Caso nenhum número for atribuído para `-n ', apenas a primeira linha será impressa. Caso a tag não seja anotada, a mensagem do commit será exibido.

-l
--list

Listar as tags. Com <padrão>..., exemplo, git tag --list 'v-*' liste apenas as tags que coincidam ao(s) padrões.

Executar "tag git" sem argumentos também lista todas as tags. O padrão é um curinga do shell (exemplo, quando coincidir ao usar fnmatch(3)). Padrões múltiplos podem ser informados; caso haja coincidência entre alguns deles, a tag será exibida.

Esta opção é fornecida de forma implícita caso qualquer outra lista como a opção --contains seja utilizada. Para mais detalhes consulte a documentação de cada uma dessas opções.

--sort=<chave>

Classifique com base na chave informada. O prefixo - é utilizado para classificar em ordem decrescente. Você pode utilizar a opção --sort=<chave> mais de uma vez; nesse caso, a última chave se torna a chave primária. Também é compatível com versão:refname ou v:refname (nomes das tags são tratados como versões). A ordem de classificação versão:refname também pode ser afetada pela variável de configuração versionsort.sufix. As chaves compatíveis são as mesmas que as do git for-each-ref. A classificação da ordem retorna para a predefinição do valor configurado pela variável tag.sort caso exista ou então pela ordem lexicográfica. Consulte git-config[1].

--color[=<quando>]

Respeite todas as cores especificadas com a opção --format. O campo <quando> deve ser always, never ou auto (comporte-se como always caso <quando> esteja ausente).

-i
--ignore-case

As referências de classificação e filtragem não diferenciam maiúsculas de minúsculas.

--coluna[=<opções>]
--no-column

Exiba a listagem de tags nas colunas. See configuration variable column.tag for option syntax.--column and --no-column without options are equivalent to always and never respectively.

Esta opção é aplicável apenas ao listar as tags sem linhas de anotação.

--contains [<commit>]

Liste apenas as tags que contenham um commit em específico (HEAD`caso não esteja definido). Implica no uso da opção `--list.

--no-contains [<commit>]

Liste apenas as tags que não contenham nenhum commit em específico (HEAD`caso não esteja definido). Implica no uso da opção `--list.

--merged [<commit>]

Liste apenas as tags cujos commits sejam acessíveis de um determinado commit (HEAD`caso não esteja definido), é incompatível com `--no-merged.

--no-merged [<commit>]

Liste apenas as tags cujos commits não sejam acessíveis em um commit em específico (HEAD`caso não esteja definido), é incompatível com `--merged.

--points-at <objeto>

Liste apenas as tags dos objetos informados (HEAD`caso não esteja definido). Implica no uso da opção `--list.

-m <msg>
--message=<msg>

Utilize a mensagem da tag informada (em vez de solicitar). Caso múltiplas opções -m sejam utilizadas, os seus valores são concatenados como separados por parágrafo. Implica na utilização de -a caso nenhum dos -a, -s, ou -u <keyid> sejam utilizados.

-F <arquivo>
--file=<arquivo>

Assume a mensagem da tag de um determinado arquivo. Utilize - para ler a mensagem da entrada padrão. Implica na utilização da opção -a caso nenhum -a, -s ou -u <keyid> seja utilizado.

-e
--edit

A mensagem tirada do arquivo com -F e a linha de comando com -m normalmente são utilizadas como mensagens das tags sem alterações. Esta opção permite editar ainda mais a mensagem retirada destas fontes.

--cleanup=<modo>

Esta opção define como a tag da mensagem é limpa. O <modo> pode ser entre verbatim, whitespace e strip. O modo predefinido é strip. O modo verbatim não altera a mensagem de forma alguma, whitespace remove apenas as linhas de espaço iniciais/finais e strip remove o espaço junto com os comentários.

--create-reflog

Cria um "reflog" para a tag. Para ativar globalmente, consulte core.logAllRefUpdates em git-config[1]. A forma negada do comando --no-create-reflog substitui apenas um --create-reflog anterior, mas atualmente não nega a configuração do core.logAllRefUpdates.

--format=<formato>

Uma cadeia de caracteres que interpola %(fieldname) vindo de uma referência sendo exibida e o objeto para o qual aponta. O formato é o mesmo do git-for-each-ref[1]. Quando não for definido, a predefinição retorna para %(refname:strip=2).

<nome-da-tag>

O nome da tag para criar, excluir ou descrever. O novo nome da tag que deve passar em todas as verificações definidas pelo git-check-ref-format[1]. Algumas destas verificações podem limitar os caracteres permitidos em um nome de uma tag.

<commit>
<objeto>

O objeto que a nova tag terá referência, geralmente um commit. A predefinição retorna para HEAD.

CONFIGURAÇÃO

É predefinido que tag git no modo de assinatura com a predefinição (-s) utilizará a identidade de quem fez o commit (no formato Seu Nome <seu@end.email>) para encontrar uma chave. Caso queira utilizar uma chave diferente da predefinida, especifique-a na configuração do repositório da seguinte maneira:

[user]
    signingKey = <gpg-keyid>

A variável pager.tag só é respeitada quando listar as tags, por exemplo, quando -l for utilizada ou indicada. A predefinição é utilizar um pager. Consulte git-config[1].

DISCUSSÃO

Sobre renomeação de tag

O que você deve fazer quando marcar um commit errado e quiser marca-lo novamente?

Caso nunca tenha impulsionado nada, basta remarcá-lo. Utilize "-f" para substituir o antigo. E pronto.

Porém caso você impulsione as coisas para fora (ou as outras pessoas apenas puderam ler o seu repositório diretamente), as outras pessoas já viram a tag antiga. Nesse caso, é possível fazer uma de duas coisas:

  1. A coisa sã. Apenas admita que você estragou tudo e use um nome diferente. Outros já viram um nome da tag e se você mantiver o mesmo nome, pode estar na situação onde as duas pessoas têm a "versão X", porém na verdade têm "X" diferentes. Então, basta chamá-lo de "X.1" e acabar logo com isso.

  2. A coisa insana. Você também quer chamar a nova versão de "X", mesmo que as outras pessoas já tenham visto a antiga. Portanto, basta usar git tag -f novamente, como se você ainda não tivesse publicado o antigo.

No entanto, o Git não (e não deve) alterar as tags sem o conhecimento dos usuários. Portanto, se alguém já recebeu a tag antiga, fazer um git pull na sua árvore não substituirá a antiga.

Caso alguém tenha recebido uma etiqueta de lançamento de você, você não pode simplesmente alterá-la atualizando a sua. Esse é um grande problema de segurança, pois as pessoas DEVEM confiar nos nomes das suas tags. Caso queira realmente fazer uma coisa insana, é necessário apenas confessar e dizer às pessoas que você errou. Você pode fazer isso fazendo um anúncio muito público dizendo:

Ok, eu estraguei tudo e impulsionei uma versão anterior com a tag X. Eu
então consertei alguma coisa e marquei novamente a árvore *corrigida* como X novamente.

Caso tenha pego a etiqueta errada e queira a nova, exclua
o antigo e buscar um novo, fazendo:

	git tag -d X
	git fetch origin tag X

para obter a minha tag atualizada.

Você pode testar qual tag você possui fazendo.

	git rev-parse X

o que também retorna 0123456789abcdef.. caso tenha a nova versão.

Perdoe a inconveniência.

Isso parece um pouco complicado? Deveria. Não há como disto estar correto, apenas "corrigindo-o" de forma automática. As pessoas precisam saber que as suas tags podem ter sido alteradas.

Na sequência automática

Caso esteja seguindo a árvore de outra pessoa, provavelmente está utilizando os ramo monitorado remotamente (como por exemplo, refs/remotes/origin/master). Você geralmente quer as tags que estão do outro lado.

Por outro lado, caso você esteja buscando porque deseja mesclar de uma vez o commit de outra pessoa, geralmente você não vai querer obter as tags a partir daí. Isso acontece com mais frequência para pessoas próximas ao nível mais alto, mas não se limitando a elas. Os meros mortais quando obtém um do outro não necessariamente querem obter automaticamente pontos de ancoragem privados vindos da outra pessoa.

Frequentemente, aparecem mensagens "please pull" na lista de discussão que oferecem apenas duas informações: uma URL do repo e um nome do ramo; foi projetado para ser facilmente cortado e colado no final de uma linha de comando git fetch:

Linus, por favor, capture de

	git://git..../proj.git master

para obter as seguintes atualizações...

se torna:

$ git pull git://git..../proj.git master

Em casos assim, você não quer seguir automaticamente as tags da outra pessoa.

Um aspecto importante do Git é a sua natureza distribuída, o que em geral significa que não há "upstream" ou "downstream" inerente no sistema. Em face disso, o exemplo acima pode parecer indicar que o espaço de nomes da tag pertence ao escalão superior das pessoas e que as tags fluem apenas para baixo, porém este não é o caso. Exibe apenas que o padrão de uso determina quem está interessado em quais tags.

Uma tentativa única é um sinal que o histórico de um commit agora está cruzando a fronteira entre um círculo de pessoas (como por exemplo, "pessoas que estão interessadas principalmente na parte da rede do kernel") que podem ter o seu próprio conjunto das tags (como por exemplo "este é o terceiro candidato ao lançamento do grupo da rede que será proposto para consumo geral com o lançamento da versão 2.6.21") para outro círculo de pessoas (como por exemplo, "pessoas que integraram várias melhorias ao subsistema"). Os últimos geralmente não estão interessados nas tags detalhadas utilizadas internamente no primeiro grupo (é isso que significa "interno"). É por isso que é desejável neste caso, não seguir as tags de maneira automática.

Pode ser que, entre as pessoas da rede, elas possam querer trocar as tags internas ao seu grupo, porém neste fluxo de trabalho eles provavelmente rastreiam o progresso um do outro por terem ramificações de rastreamento remoto. Novamente, a heurística para seguir automaticamente estas tags é uma coisa boa.

Sobre as Tags com Datas Retroativas

Caso tenha importado algumas alterações de outro VCS e queira adicionar as tags para as principais versões do seu trabalho, é útil poder informar a data que será incorporada no objeto tag; estes dados no objeto tag afetam, por exemplo, a ordem das tags na interface gitweb.

Para definir a data usada em objetos com tags futuras, defina a variável de ambiente GIT_COMMITTER_DATE (consulte a discussão posterior sobre os valores possíveis; a forma mais comum é "AAAA-MM-DD HH:MM").

Por exemplo:

$GIT_COMMITTER_DATE="2006-10-02 10:31" git tag -s v1.0.1

OS FORMATOS DA DATA

As variáveis de ambiente GIT_AUTHOR_DATE, GIT_COMMITTER_DATE são compatíveis com os seguintes formatos de data:

Formato interno do Git

É <unix timestamp> <time zone offset>, onde desde a época do UNIX <unix timestamp> é o valor em segundos. O <time zone offset> é o desvio positivo ou negativo com bate no UTC. O CET por exemplo (onde é 1 hora à frente do UTC ) é +0100.

RFC 2822

O formato de e-mail padrão, conforme descrito pela RFC 2822, por exemplo, Thu, 07 Apr 2005 22:13:13 +0200.

ISO 8601

A data e hora definidas pela norma ISO 8601 2005-04-07T22:13:13 por exemplo. O analisador também aceita um espaço em vez do caractere T. O analisador aceita um espaço em vez do caractere T também. As partes fracionadas de um segundo serão ignoradas, logo 2005-04-07T22:13:13.019 por exemplo, será tratada como 2005-04-07T22:13:13.

Note
 Além disso, a parte da data é aceita nos seguintes formatos: YYYY.MM.DD, MM/DD/YYYY e DD.MM.YYYY.

VEJA TAMBÉM

git-check-ref-format[1]. git-config[1].

GIT

Parte do conjunto git[1]

scroll-to-top