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

NOME

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

RESUMO

git tag [-a | -s | -u <key-id>] [-f] [-m <msg> | -F <file>] [-e]
	[(--trailer <token>[(=|:)<value>])…​]
	<tagname> [<commit> | <object>]
git tag -d <tagname>…​
git tag [-n[<num>]] -l [--contains <commit>] [--no-contains <commit>]
	[--points-at <object>] [--column[=<options>] | --no-column]
	[--create-reflog] [--sort=<key>] [--format=<format>]
	[--merged <commit>] [--no-merged <commit>] [<pattern>…​]
git tag -v [--format=<format>] <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.

Se um dos itens -a, -s ou -u <id-da-chave> for usada, o comando criará um objeto tags e exigirá uma mensagem para a etiqueta. A menos que a opção -m <msg> ou -F <arquivo> seja usado, um editor é iniciado para que o usuário digite a mensagem das etiquetas.

If -m <msg> or -F <file> or --trailer <token>[=<value>] is given and -a, -s, and -u <key-id> are absent, -a is implied.

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

Um objeto de etiquetas assinado pelo GnuPG será criado quando -s ou -u <id-da-chave> for usado. Quando a opção -u <id-da-chave> não é usado, a identidade de quem fez o commit para o usuário atual é usada para localizar a chave de assinatura GnuPG. A variável de configuração gpg.program é usada para especificar 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

Crie uma etiqueta assinada por GPG, usando a chave do endereço de e-mail predefinido. O comportamento predefinido da assinatura GPG das etiquetas é controlado pela variável de configuração tag.gpgSign, se existir ou caso contrário, é desativado. 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 <key-id>
--local-user=<key-id>

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. Se nenhum número for fornecido para a opção -n, apenas a primeira linha será impressa. Se a etiqueta não estiver anotada, a mensagem do commit será exibida.

-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>

Classifica com base na chave fornecida. Prefixo - para classificar em ordem decrescente do valor. É possível usar a opção --sort=<chave> diversas vezes e, neste caso, a última chave se torna a chave primária. Também suporta "version:refname" ou "v:refname" (os nomes das etiquetas são tratadas como versões). A ordem de classificação "version:refname" também pode ser afetada pela variável de configuração "versionsort.suffix". As chaves compatíveis são as mesmas que as do git for-each-ref. A predefinição da ordem de classificação é o valor configurado para a variável tag.sort, se ela existir, caso contrário, a ordem lexicográfica. Consulte git-config[1].

--color[=<quando>]

Respeite todas as cores usadas 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.

--omit-empty

Não imprima uma nova linha após a formatação das referências onde o formato se expande para a string vazia.

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

Exiba a lista das tags em colunas. Consulte a variável de configuração column.tag para conhecer a sintaxe da opção. --column e --no-column sem opções são respectivamente o mesmo que always e never.

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).

--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).

--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>

Use a mensagem fornecida nas etiquetas (em vez de solicitar). Se forem fornecidas várias opções -m, os seus valores serão concatenados como parágrafos separados. Implica no uso da opção -a se nenhuma das opções -a, -s ou -u <id-da-chave> for usada.

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

Obtém a mensagem da etiqueta do arquivo informado. Use - para ler a mensagem da entrada predefinida. Implica no uso da opção -a se nenhuma das opções -a, -s ou -u <id-da-chave> for usada.

--trailer <token>[(=|:)<valor>]

Specify a (<token>, <value>) pair that should be applied as a trailer. (e.g. git tag --trailer "Custom-Key: value" will add a "Custom-Key" trailer to the tag message.) The trailer.* configuration variables (git-interpret-trailers[1]) can be used to define if a duplicated trailer is omitted, where in the run of trailers each trailer would appear, and other details. The trailers can be extracted in git tag --list, using --format="%(trailers)" placeholder.

-e
--edit

A mensagem extraída do arquivo com -F e da linha de comando com -m geralmente é usada como a mensagem das etiquetas sem alterações. Esta opção permite que você edite ainda mais a mensagem extraída dessas fontes.

--cleanup=<modo>

Esta opção define como a mensagem das etiquetas é limpa. O <modo> pode ser um dos seguintes: verbatim, whitespace e strip. O modo predefinido é strip O modo verbatim não altera a mensagem de forma alguma, whitespace remove apenas as linhas com espaço vazio à esquerda/à direita e strip remove tanto os espaços vazios quanto os comentários.

--create-reflog

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

--format=<formato>

Uma string que interpola %(fieldname) de uma referência na etiqueta que está sendo mostrada e o objeto para onde ela aponta. O formato é o mesmo do git-for-each-ref[1]. Quando não especificado, o padrão é %(refname:strip=2).

<nome-da-tag>

O nome da etiqueta que será criada, excluída ou descrita. O novo nome da etiqueta deve passar em todas as verificações definidas por git-check-ref-format[1]. Algumas destas verificações podem restringir os caracteres permitidos num nome da etiqueta.

<commit>
<objeto>

O objeto onde a nova etiqueta se referirá, geralmente um commit. A predefinição é HEAD.

CONFIGURAÇÃO

É predefinido que o comando git tag no modo sign-with-default (-s) usará a sua identidade para fazer o commit (no formato Seu nome <seu@endereço.e-mail>) para localizar uma chave. Se quiser usar uma chave diferente, você pode especificá-la na configuração do repositório da seguinte maneira:

[user]
    signingKey = <id-da-chave-gpg>

O pager.tag só é respeitado ao listar etiquetas, ou seja, quando a opção -l é usada ou está implícita. A predefinição é usar 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 mais sensata. Admita que fez besteira e use um nome diferente. Outras pessoas já viram um nome na etiqueta e, se você mantiver o mesmo nome, poderá se deparar com a situação onde duas pessoas têm a "versão X", mas na verdade têm "X"s diferentes. Portanto, basta chamá-lo de "X.1" e pronto.

  2. A coisa insana. Você realmente quer chamar a nova versão de "X" também, "mesmo que" outras pessoas já tenham visto a antiga. Portanto, basta usar o comando git tag -f novamente, como se você já 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.

Se alguém recebeu uma etiqueta de liberação de você, você não pode simplesmente alterar a etiqueta para essa pessoa atualizando a sua própria. Este é um grande problema de segurança, pois as pessoas DEVEM ser capazes de confiar em suas etiquetas. Se você realmente quiser fazer uma coisa insana, precisa simplesmente confessar e dizer às pessoas que fez besteira. Você pode fazer isso fazendo um anúncio 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 ser. Não é possível que seja correto simplesmente "consertá-lo" automaticamente. As pessoas precisam saber que suas etiquetas podem ter sido alteradas.

Na sequência automática

Se estiver seguindo a árvore de outra pessoa, é provável que esteja usando ramificações de rastreamento remoto (por exemplo. refs/remotes/origin/master). Normalmente, você deseja as etiquetas da outra extremidade.

Por outro lado, se estiver fazendo um fetch porque deseja uma mesclagem única de outra pessoa, normalmente não deseja obter as etiquetas de lá. Isso acontece com mais frequência com pessoas próximas ao nível superior, mas não se limita apenas a elas. Os meros mortais, quando fazem um pull de um do outro, não querem necessariamente receber automaticamente as etiquetas de pontos de ancoragem privados 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 significa que não há upstream ou downstream inerente no sistema. À primeira vista, o exemplo acima pode parecer indicar que o espaço de nomes das etiquetas pertence ao escalão do topo das pessoas e que as etiquetas só fluem para baixo, mas esse não é o caso. Isso mostra apenas que o padrão de uso determina quem está interessado nas etiquetas de quem.

Um one-shot pull é um sinal de que o histórico de um commit está agora cruzando a fronteira entre um círculo de pessoas ("as pessoas que estão principalmente interessadas na parte de rede do kernel" por exemplo) que podem ter o seu próprio conjunto de etiquetas ("este é o terceiro candidato a lançamento do grupo de rede a ser proposto para consumo geral com o lançamento da versão 2.6.21" por exemplo) para outro círculo de pessoas (por exemplo, "pessoas que integram várias melhorias de subsistema"). Estes últimos geralmente não estão interessados nas etiquetas detalhadas usadas internamente no primeiro grupo (isso é o que significa "interno"). É por isso que, neste caso, é desejável não seguir as etiquetas automaticamente.

Pode ser que, entre as pessoas que trabalham em rede, elas queiram trocar as etiquetas internas do seu grupo, mas nesse fluxo de trabalho elas provavelmente estão acompanhando o progresso umas das outras por meio de filiais rastreadas remotamente. Mais uma vez, a heurística de seguir automaticamente essas etiquetas é 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 e 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 a partir do UTC. O CET por exemplo (onde é 1 hora à frente do UTC ) é +0100.

RFC 2822

The standard date format as described by RFC 2822, for example 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.

ARQUIVOS

$GIT_DIR/TAG_EDITMSG

Esse arquivo contém a mensagem de uma tag anotada em andamento. Se o git tag for encerrado devido a um erro antes de criar uma tag anotada, a mensagem da tag que foi fornecida pelo usuário numa sessão do editor estará disponível nesse arquivo, mas poderá ser substituída pela próxima chamada do comando git tag.

OBSERVAÇÕES

Ao combinar diversos filtros a opção --contains e a opção --no-contains, faz referências apenas aos que contenha pelo menos um dos commits --contains e não contenha nenhum dos commits mostrados com --no-contains.

Ao combinar diversos filtros a opção --merged e a opção --no-merged, faz referências apenas aos que sejam acessíveis a partir um dos commits --merged e de nenhum dos commits mostrados com --no-merged.

GIT

Parte do conjunto git[1]

scroll-to-top