Chapters ▾ 2nd Edition

2.6 Fundamentos do Git - Criando Tags

Criando Tags

Como a maioria dos VCSs, o Git tem a capacidade de marcar (tag) pontos específicos no histórico de um repositório como sendo importantes. Normalmente, as pessoas usam essa funcionalidade para marcar pontos de lançamento (v1.0, v2.0 e assim por diante). Nesta seção, você aprenderá como listar as tags existentes, como criar e excluir tags, e quais são os diferentes tipos de tags.

Listando Suas Tags

Listar as tags existentes no Git é simples. Basta digitar git tag (com o opcional -l ou --list):

$ git tag
v1.0
v2.0

Este comando lista as tags em ordem alfabética; a ordem na qual elas são exibidas não tem importância real.

Você também pode pesquisar tags que correspondam a um padrão específico. O repositório de código-fonte do Git, por exemplo, contém mais de 500 tags. Se você estiver interessado apenas em observar a série 1.8.5, você pode executar isto:

$ git tag -l "v1.8.5*"
v1.8.5
v1.8.5-rc0
v1.8.5-rc1
v1.8.5-rc2
v1.8.5-rc3
v1.8.5.1
v1.8.5.2
v1.8.5.3
v1.8.5.4
v1.8.5.5
Note
A listagem de curingas (wildcards) de tags requer a opção -l ou --list

Se você quiser apenas a lista inteira de tags, executar o comando git tag assume implicitamente que você deseja uma lista e fornece uma; o uso de -l ou --list neste caso é opcional.

Se, no entanto, você estiver fornecendo um padrão curinga (wildcard) para corresponder a nomes de tags, o uso de -l ou --list é obrigatório.

Criando Tags

O Git suporta dois tipos de tags: leves (lightweight) e anotadas (annotated).

Uma tag leve (lightweight tag) é muito parecida com um branch que não muda — é apenas um ponteiro para um commit específico.

As tags anotadas (annotated tags), no entanto, são armazenadas como objetos completos no banco de dados do Git. Elas têm checksum; contêm o nome do criador da tag (tagger), e-mail e data; possuem uma mensagem de tag; e podem ser assinadas e verificadas com o GNU Privacy Guard (GPG). Geralmente é recomendado que você crie tags anotadas para que possa ter todas essas informações; mas se você quiser uma tag temporária ou, por algum motivo, não quiser manter as outras informações, as tags leves também estão disponíveis.

Tags Anotadas (Annotated Tags)

Criar uma tag anotada no Git é simples. A maneira mais fácil é especificar -a quando você executar o comando tag:

$ git tag -a v1.4 -m "my version 1.4"
$ git tag
v0.1
v1.3
v1.4

O -m especifica uma mensagem de tag, que é armazenada junto com ela. Se você não especificar uma mensagem para uma tag anotada, o Git iniciará o seu editor para que você possa digitá-la.

Você pode ver os dados da tag junto com o commit que foi tagueado usando o comando git show:

$ git show v1.4
tag v1.4
Tagger: Ben Straub <ben@straub.cc>
Date:   Sat May 3 20:19:12 2014 -0700

my version 1.4

commit ca82a6dff817ec66f44342007202690a93763949
Author: Scott Chacon <schacon@gee-mail.com>
Date:   Mon Mar 17 21:52:11 2008 -0700

    Change version number

Isso mostra as informações de quem criou a tag (tagger), a data em que o commit foi tagueado e a mensagem de anotação antes de mostrar as informações do commit.

Tags Leves (Lightweight Tags)

Outra forma de taguear commits é com uma tag leve (lightweight tag). Isso é basicamente o checksum do commit armazenado em um arquivo — nenhuma outra informação é mantida. Para criar uma tag leve, não forneça nenhuma das opções -a, -s ou -m, forneça apenas o nome da tag:

$ git tag v1.4-lw
$ git tag
v0.1
v1.3
v1.4
v1.4-lw
v1.5

Desta vez, se você executar git show na tag, você não verá as informações extras da tag. O comando apenas mostra o commit:

$ git show v1.4-lw
commit ca82a6dff817ec66f44342007202690a93763949
Author: Scott Chacon <schacon@gee-mail.com>
Date:   Mon Mar 17 21:52:11 2008 -0700

    Change version number

Tagueando Depois

Você também pode taguear commits depois de ter passado por eles. Suponha que o seu histórico de commits seja parecido com este:

$ git log --pretty=oneline
15027957951b64cf874c3557a0f3547bd83b3ff6 Merge branch 'experiment'
a6b4c97498bd301d84096da251c98a07c7723e65 Create write support
0d52aaab4479697da7686c15f77a3d64d9165190 One more thing
6d52a271eda8725415634dd79daabbc4d9b6008e Merge branch 'experiment'
0b7434d86859cc7b8c3d5e1dddfed66ff742fcbc Add commit function
4682c3261057305bdd616e23b64b0857d832627b Add todo file
166ae0c4d3f420721acbb115cc33848dfcc2121a Create write support
9fceb02d0ae598e95dc970b74767f19372d61af8 Update rakefile
964f16d36dfccde844893cac5b347e7b3d44abbc Commit the todo
8a5cbc430f1a9c3d00faaeffd07798508422908a Update readme

Agora, suponha que você esqueceu de taguear o projeto na v1.2, que estava no commit “Update rakefile”. Você pode adicioná-la depois do fato. Para taguear aquele commit, você especifica o checksum do commit (ou parte dele) no final do comando:

$ git tag -a v1.2 9fceb02

Você pode ver que tagueou o commit:

$ git tag
v0.1
v1.2
v1.3
v1.4
v1.4-lw
v1.5

$ git show v1.2
tag v1.2
Tagger: Scott Chacon <schacon@gee-mail.com>
Date:   Mon Feb 9 15:32:16 2009 -0800

version 1.2
commit 9fceb02d0ae598e95dc970b74767f19372d61af8
Author: Magnus Chacon <mchacon@gee-mail.com>
Date:   Sun Apr 27 20:43:35 2008 -0700

    Update rakefile
...

Compartilhando Tags

Por padrão, o comando git push não transfere tags para servidores remotos. Você terá que enviar (push) as tags explicitamente para um servidor compartilhado depois de tê-las criado. Esse processo é igual a compartilhar branches remotos — você pode executar git push origin <tagname>.

$ git push origin v1.5
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@github.com:schacon/simplegit.git
 * [new tag]         v1.5 -> v1.5

Se você tiver muitas tags que deseja enviar (push) de uma só vez, também poderá usar a opção --tags do comando git push. Isso transferirá todas as suas tags para o servidor remoto que ainda não estão lá.

$ git push origin --tags
Counting objects: 1, done.
Writing objects: 100% (1/1), 160 bytes | 0 bytes/s, done.
Total 1 (delta 0), reused 0 (delta 0)
To git@github.com:schacon/simplegit.git
 * [new tag]         v1.4 -> v1.4
 * [new tag]         v1.4-lw -> v1.4-lw

Agora, quando outra pessoa clonar ou extrair (pull) do seu repositório, ela também obterá todas as suas tags.

Note
git push envia ambos os tipos de tags

git push <remote> --tags enviará tags leves e anotadas. No momento, não há opção para enviar apenas tags leves, mas se você usar git push <remote> --follow-tags apenas as tags anotadas serão enviadas para o remoto.

Excluindo Tags

Para excluir uma tag no seu repositório local, você pode usar git tag -d <tagname>. Por exemplo, poderíamos remover a nossa tag leve acima da seguinte maneira:

$ git tag -d v1.4-lw
Deleted tag 'v1.4-lw' (was e7d5add)

Observe que isso não remove a tag de nenhum servidor remoto. Existem duas variações comuns para excluir uma tag de um servidor remoto.

A primeira variação é git push <remote> :refs/tags/<tagname>:

$ git push origin :refs/tags/v1.4-lw
To /git@github.com:schacon/simplegit.git
 - [deleted]         v1.4-lw

A maneira de interpretar o comando acima é lê-lo como o valor nulo antes dos dois pontos (colon) sendo enviado para o nome da tag remota, efetivamente excluindo-a.

A segunda (e mais intuitiva) maneira de excluir uma tag remota é com:

$ git push origin --delete <tagname>

Fazendo Checkout de Tags

Se você quiser ver as versões dos arquivos para as quais uma tag está apontando, você pode fazer um git checkout daquela tag, embora isso coloque seu repositório no estado “detached HEAD”, o que tem alguns efeitos colaterais ruins:

$ git checkout v2.0.0
Note: switching to 'v2.0.0'.

You are in 'detached HEAD' state. You can look around, make experimental
changes and commit them, and you can discard any commits you make in this
state without impacting any branches by performing another checkout.

If you want to create a new branch to retain commits you create, you may
do so (now or later) by using -c with the switch command. Example:

  git switch -c <new-branch-name>

Or undo this operation with:

  git switch -

Turn off this advice by setting config variable advice.detachedHead to false

HEAD is now at 99ada87... Merge pull request #89 from schacon/appendix-final

$ git checkout v2.0-beta-0.1
Previous HEAD position was 99ada87... Merge pull request #89 from schacon/appendix-final
HEAD is now at df3f601... Add atlas.json and cover image

No estado “detached HEAD”, se você fizer alterações e então criar um commit, a tag permanecerá a mesma, mas seu novo commit não pertencerá a nenhum branch e ficará inacessível, exceto pelo hash exato do commit. Portanto, se você precisar fazer alterações — digamos que esteja corrigindo um bug em uma versão mais antiga, por exemplo — geralmente você desejará criar um branch:

$ git checkout -b version2 v2.0.0
Switched to a new branch 'version2'

Se você fizer isso e criar um commit, seu branch version2 será ligeiramente diferente da sua tag v2.0.0, pois ele avançará com as suas novas alterações, portanto tenha cuidado.