Marcação

Este documento discute o conceito da marcação no Git e o comando git tag. Os marcadores são referências que apontam para pontos específicos no histórico do Git. git tag é em geral usado para capturar um ponto no histórico que é usado para uma versão marcada (por exemplo, v1.0.1). Um marcador é como uma ramificação que não muda. Diferente das ramificações, os marcadores depois de criados não têm mais histórico de commits. Para mais informações sobre as ramificações, visite a página git branch. Este documento abrange os diferentes tipos de marcador, como criar marcadores, listar todos os marcadores, excluir marcadores, compartilhar marcadores, entre outros.

Criação de uma marcação

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

git tag <tagname>

Substitua < tagname > 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 um commit. São apenas um nome e um ponteiro para um commit, úteis para criar links rápidos para commits 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 aos commits e mensagens de commit, 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 um novo marcador anotado identificado 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 um novo marcador 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 um marcador leve identificado como v1.4-lw. Os marcadores leves são criados sem as opções -a, -s ou -m. Eles criam uma nova soma de verificação de marcador 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 marcadores, 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 todos os marcadores com prefixo -rc, que costuma ser usado para identificar candidatos ao lançamento.

Marcação de commits antigos

Os exemplos anteriores de marcação demonstraram operações em commits implícitos. Por padrão, git tag vai criar um marcador no commit que HEAD está fazendo referência. Como alternativa, git tag pode ser transmitido como referência a um commit específico. Assim o commit transmitido é marcado, em vez de ser padronizado como HEAD. Para reunir uma lista de commits mais antigos, 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 commits. Neste exemplo, a gente vai escolher o commit mais alto Mescle a ramificação "feature" para o novo marcador. A gente vai precisar referenciar o código SHA do commit para transmitir ao Git:

git tag -a v1.2 15027957951b64cf874c3557a0f3547bd83b3ff6

A execução da invocação git tag acima cria um novo commit anotado identificado como v1.2 para o commit 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: tag 'v0.4' already exists

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

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

git tag -a -f v1.4 15027957951b64cf874c3557a0f3547bd83b3ff6

A execução do comando acima mapeia o commit 15027957951b64cf874c3557a0f3547bd83b3ff6 do identificador de marcador v1.4. Ela substitui qualquer conteúdo existente no marcador v1.4.

Compartilhamento: enviando marcações para remotos

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

$ git push origin v1.4
    Counting objects: 14, done.
    Delta compression using up to 8 threads.
    Compressing objects: 100% (12/12), done.
    Writing objects: 100% (14/14), 2.05 KiB | 0 bytes/s, done.
    Total 14 (delta 3), reused 0 (delta 0)
    To git@bitbucket.com:atlasbro/gittagdocs.git
     * [new tag]         v1.4 -> v1.4

Para enviar diversos marcadores 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 os novos marcadores.

Verificação das marcações

git checkout v1.4

O comando acima faz checkout do marcador v1.4. Essa ação coloca o repositório em um estado de HEAD separado. Assim, quaisquer mudanças realizadas não atualizam o marcador. Elas criam um novo commit separado, que não faz parte de ramificação alguma e apenas pode ser alcançado pelo código SHA do commit. 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 marcadores é uma operação simples. A transmissão da opção -d e um identificador de marcador para git tag excluem o marcador identificado.

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

Neste exemplo, git tag é executado para exibir uma lista de marcadores que exibem v1, v2, v3. Então, git tag -d v1 é executado e exclui o marcador v1.

Resumo

Pronto(a) para aprender Git?

Tente este tutorial interativo.

Comece agora mesmo