git describe

Inspeção e comparação

Dá a um commit um nome legível baseado na tag mais próxima

O comando 'git describe' nomeia um commit a partir da tag mais próxima que ele alcança: a própria tag se o commit estiver marcado, senão tag-N-gHASH (N commits depois da tag e o hash abreviado). Scripts de build o usam para marcar cada build com uma versão. Por padrão só usa tags anotadas.

Sinopse

git describe [--tags] [--always] [--dirty] [--abbrev=<n>] [<commit-ish>...]
[ ] opcional| ou<arg> valor a substituir... repetível--flag opção

Opções

Clique em uma opção para expandir

Iniciante (3)

Usa qualquer tag, inclusive as leves, não só as anotadas.

Quando necessárioQuando o seu projeto usa tags leves

Exemplo

git describe --tags

Mostra o hash abreviado do commit quando nenhuma tag consegue descrevê-lo.

RecomendadoNunca falhar: imprimir o hash curto quando não há tag

Exemplo

git describe --always

Acrescenta -dirty quando o diretório de trabalho tem alterações não commitadas.

RecomendadoSinalizar builds feitos com alterações não commitadas

Exemplo

git describe --dirty

Escolhendo a opção certa

Ler um nome do describe

v1.0-2-g1a2b3c4

ComandoSignificado
v1.0A tag mais próxima
2Commits desde essa tag
g1a2b3c4«g» de git + o hash abreviado
-dirtyAlterações não commitadas (com --dirty)

Exemplos

Descrever HEAD

git describe

v1.0-2-g1a2b3c4: dois commits depois da v1.0.

Incluir tags leves

git describe --tags

Considerar também tags criadas sem -a.

Nunca falhar

git describe --always --dirty

O hash se não houver tag, -dirty se houver edições locais.

Exemplos de fluxos de trabalho

1
git describe --tags --always --dirty

Calcular a string de versão

2
echo "$(git describe --tags --always)" > version.txt

Gravá-la na build

Solução de problemas

fatal: No names found, cannot describe anything.

Causa: O repositório não tem tags

Crie uma (git tag -a v0.1 -m ...) ou use --always

fatal: No annotated tags can describe ...

Causa: Só existem tags leves

Use --tags, ou recrie a tag com -a

Dicas e armadilhas

Boas práticas

  • ✓Use tags anotadas nas versões para o describe funcionar sem --tags.
  • ✓Use --always em scripts para que nunca falhem.

Erros comuns

  • ✗Receber "No names found" porque o projeto só tem tags leves — adicione --tags.
  • ✗Ler o g de -g1a2b3c4 como parte do hash: ele só significa «git».

Perguntas frequentes

A:

Ele usa a tag com menos commits entre ela e o commit descrito.