Marcação

Este documento discute o conceito da marcação no Git e o comando git tag. As marcações são referências que apontam para momentos específicos no histórico do Git. A marcação costuma ser utilizada para capturar um ponto no histórico usado para um lançamento de versão marcado (ex. v1.0.1). Uma marcação é como uma ramificação que não muda. Diferente das ramificações, as marcações depois de criadas não têm mais histórico de confirmações. Para mais informações sobre as ramificações, visite a página git branch. Este documento abrange os diferentes tipos de marcação, como criar marcações, listar todas as marcações, excluir marcações, compartilhar marcações, entre outros.

Criação de uma marcação

Para criar uma nova marcação, execute o comando a seguir:

 git tag  

Substitua por um identificador semântico para o estado do repositório na hora que a marcação está sendo criada. Um padrão comum é usar números de versão, como git tag v1.4. O git suporta dois tipos diferentes de marcações: anotadas e leves. O exemplo anterior criou uma marcação leve. As marcações leves e as anotadas diferem na quantidade de metadados acompanhantes que elas armazenam. Uma prática recomendada é considerar as Marcações anotadas como públicas e as Marcações leves como privadas. As marcações anotadas armazenam metadados extras, como: nome de quem criou a marcação, e-mail e data. Estes dados são importantes para um lançamento público. As marcações leves são em essência "marcadores" em uma confirmação, elas são apenas um nome e um indicador de uma confirmação, úteis para criar links rápidos para confirmações relevantes.

Marcações anotadas

As marcações anotadas são armazenadas como objetos completos no banco de dados do Git. Para reiterar, elas armazenam metadados extras, como: nome de quem criou a marcação, e-mail e data. Semelhante às confirmações e mensagens de confirmação, as marcações anotadas têm uma mensagem de marcação. Além disso, por motivos de segurança, as marcações anotadas podem ser assinadas e verificadas com o GNU Privacy Guard (GPG). As melhores práticas recomendadas para a marcação do git são preferir marcações anotadas às leves, para que você possa ter todos os metadados associados.

 git tag -a v1.4 

A execução desse comando cria uma nova marcação anotada identificada com v1.4. O comando abre o editor padrão de texto configurado para solicitar a inserção de mais metadados.

 git tag -a v1.4 -m "my version 1.4" 

A execução desse comando é semelhante à invocação anterior, no entanto, esta versão do comando é transmitida com a opção -m e uma mensagem. Este é um método conveniente semelhante ao git commit -m que cria na hora uma nova marcação e não abre o editor de texto local em favor de salvar a mensagem transmitida com a opção -m.

Marcações leves

 git tag v1.4-lw 

A execução desse comando cria uma marcação leve identificada como v1.4-lw. As marcações leves são criadas sem as opções -a, -s ou -m. Elas criam uma nova soma de verificação de marcação e a armazenam no diretório .git/ do repositório do projeto.

Listagem de marcações

Para listar as marcações em um repositório, execute o seguinte:

 git tag 

Isto exibe uma lista de marcações:

 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 

Para refinar a lista de marcações, a opção -l pode ser transmitida com uma expressão curinga:

 $ 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 

Esse exemplo usa a opção -l e a expressão curinga de -rc, que retorna uma lista de todas as marcações marcadas com um prefixo -rc, que costuma ser usado para identificar candidatos ao lançamento.

Marcação de confirmações antigas

Os exemplos anteriores de marcação demonstraram operações em confirmações implícitas. Por padrão, git tag cria uma marcação na confirmação que HEAD está fazendo referência. Como alternativa, git tag pode ser transmitido como referência a uma confirmação específica. Isto marca a confirmação transmitida, em vez de padronizar para HEAD. Para reunir uma lista de confirmações mais antigas, execute o comando git log.

 $ git log --pretty=oneline 15027957951b64cf874c3557a0f3547bd83b3ff6 Merge branch 'feature' a6b4c97498bd301d84096da251c98a07c7723e65 add update method for thing 0d52aaab4479697da7686c15f77a3d64d9165190 one more thing 6d52a271eda8725415634dd79daabbc4d9b6008e Merge branch 'experiment' 

A execução de git log resulta em uma lista de confirmações. Neste exemplo, a gente vai escolher a confirmação mais alta Mescle a ramificação "feature" para a nova marcação. A gente vai precisar referenciar o código SHA da confirmação para transmitir ao Git:

 git tag -a v1.2 15027957951b64cf874c3557a0f3547bd83b3ff6 

A execução da invocação git tag acima cria uma nova confirmação anotada identificada como v1.2 para a confirmação que a gente selecionou no exemplo anterior de git log.

Remarcar/substituir marcações antigas

Se você tentar criar uma marcação com o mesmo identificador de uma marcação existente, o Git vai exibir um erro semelhante a:

 fatal: a marcação "v0.4" já existe 

Além disso, se você tentar marcar uma confirmação mais antiga com um identificador de marcação já existente, o Git vai exibir o mesmo erro.

Caso você queira atualizar uma marcação existente, a opção -f FORCE deve ser usada.

 git tag -a -f v1.4 15027957951b64cf874c3557a0f3547bd83b3ff6 

A execução do comando acima mapeia a confirmação 15027957951b64cf874c3557a0f3547bd83b3ff6 do identificador de marcação v1.4. Ela substitui qualquer conteúdo existente na marcação v1.4.

Compartilhamento: enviando marcações para remotos

O compartilhamento de marcações é semelhante ao envio de ramificações. Por padrão, git push não envia marcações. As marcações exigem transmissão explícita para git push.

 $ git push origin v1.4 Contando objetos: 14, concluído. Compressão delta usando até 8 threads. Comprimindo objetos: 100% (12/12), concluído. Gravando objetos: 100% (14/14), 2.05 KiB | 0 bytes/s, concluído. Total 14 (delta 3), reutilizado 0 (delta 0) Para git@bitbucket.com:atlasbro/gittagdocs.git * [nova marcação] v1.4 -> v1.4 

Para enviar diversas marcações ao mesmo tempo, transmita a opção --tags para o comando git push. Quando outro usuário clona ou puxa um repositório, ele recebe as novas marcações.

Verificação das marcações

Você pode visualizar o estado de um repositório em uma marcação usando o comando git checkout.

 git checkout v1.4 

O comando acima faz checkout da marcação v1.4. Isso coloca o repositório em um estado de HEAD separado. Isso significa que quaisquer mudanças realizadas não atualizam a marcação. Elas criam uma nova confirmação separada, que não faz parte de ramificação alguma e apenas pode ser alcançada pelo código SHA da confirmação. Portanto, é recomendado criar uma nova ramificação sempre que estiver fazendo alterações em um estado HEAD separado.

Exclusão de marcações

A exclusão de marcações é uma operação simples. A transmissão da opção -d e um identificador de marcação para git tag excluem a marcação identificada.

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

Neste exemplo, git tag é executado para exibir uma lista de marcações que exibem v1, v2, v3. Então, git tag -d v1 é executado e exclui a marcação v1.

Resumo

Recapitulando: a marcação é um mecanismo adicional usado para criar um instantâneo de um repositório do Git. Ela é, em geral, usada para criar marcações semânticas de identificadores numéricos da versão, que correspondem aos ciclos da versão do software. O comando git tag é o impulsionador principal da marcação: criação, modificação e exclusão. Existem dois tipos de marcações: anotadas e leves. As marcações anotadas costumam ser recomendadas, pois elas armazenam metadados adicionais valiosos sobre a marcação. Outros comandos de Git abrangidos neste documento foram git push e git checkout. Visite as respectivas páginas para saber mais sobre o uso de cada um.

Pronto para aprender sobre o Git?

Experimente este tutorial interativo.

Comece agora mesmo