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

NOME

git-describe - Atribua a um objeto um nome legível para humanos com base num "ref" disponível

RESUMO

git describe [--all] [--tags] [--contains] [--abbrev=<n>] [<commit-ish>…​]
git describe [--all] [--tags] [--contains] [--abbrev=<n>] --dirty[=<mark>]
git describe <blob>

DESCRIÇÃO

O comando localiza a etiqueta mais recente que pode ser acessada a partir de um commit. Se a etiqueta apontar para o commit, apenas a etiqueta será mostrada. Caso contrário, ele sufixa o nome da etiqueta com a quantidade de commits adicionais no topo do objeto marcado e o nome abreviado do objeto do commit mais recente. O resultado é um nome de objeto "legível para humanos" que também pode ser usado para identificar o commit em outros comandos do git.

Por predefinição (sem a opção --all ou --tags) o comando git describe apenas mostra as etiquetas anotadas. Para saber mais sobre a criação de etiquetas com anotações, consulte as opções -a e -s do git-tag[1].

Caso o objeto especificado se refera a uma bolha, este será descrito como <commit-ish>:<caminho>, de modo que a bolha possa ser encontrada em <caminho> que em si descreve o primeiro commit no qual essa bolha ocorre numa revisão reversa do HEAD.

OPÇÕES

<commit-ish>…​

Faz o commit ods nomes dos objetos para descrevê-los. A predefinição retorna é HEAD caso seja omitido.

--dirty[=<mark>]
--broken[=<mark>]

Descreve a condição da árvore de trabalho. Quando a árvore de trabalho corresponde ao HEAD, a saída é a mesma que git describe HEAD. Se a árvore de trabalho tiver alterações locais, -dirty será anexado a ela. No caso um repositório estar corrompido e o Git não puder determinar se há uma alteração local, o Git apresentará um erro, a menos que a opção~ --broken' seja usada, o que em vez disso, acrescentará o sufixo `-broken.

--all

Em vez de usar apenas as etiquetas anotadas, use qualquer referência encontrada no espaços de nomes refs/. Essa opção permite a correspondência com qualquer ramo conhecido, ramo rastreado remotamente ou uma etiqueta simples.

--tags

Em vez de usar apenas as etiquetas anotadas, use qualquer etiqueta encontrada no espaços de nomes refs/tags. Essa opção permite a correspondência de uma etiqueta simples (sem anotação).

--contains

Em vez de encontrar a etiqueta que anteceda um commit, localize a etiqueta que vem após o commit e a contenha. Implica automaticamente no uso da opção --tags.

--abbrev=<n>

Em vez de usar o número padrão de dígitos hexadecimais (que variam de acordo com a quantidade de objetos no repositório com um padrão de 7) do nome abreviado do objeto, utilize <n> dígitos ou quantos dígitos forem necessários para formar um nome do objeto que seja único. Um <n> que seja 0, suprime o formato longo exibindo apenas a tag mais próxima.

--candidates=<n>

Em vez de considerar apenas as 10 etiquetas mais recentes como candidatas para descrever o commit de entrada, considere até <n> candidatos. Aumentar <n> acima de 10 demorará mais, porém, poderá produzir um resultado ainda mais preciso. Um <n> de 0 fará com que apenas as correspondências exatas sejam mostradas.

--exact-match

Produza apenas correspondências exatas (uma etiqueta faz referência direta ao commit informado). Isso é um sinônimo para a opção --candidates=0.

--debug

Exibe informações detalhadas sobre a estratégia de pesquisa que está sendo empregada no erro padrão. O nome da etiqueta ainda será impresso na saída predefinida.

--long

Sempre gera o formato longo (uma etiqueta, o número de commits e o nome abreviado do commit), ainda que corresponda a uma etiqueta. Isto é útil quando você deseja ver partes do nome do objeto do commit na saída na "descrição", mesmo quando o commit em questão for uma versão marcada. Em vez de emitir apenas o nome da etiqueta, ele descreverá esse commit como v1.2-0-gdeadbee (0 commits desde a etiqueta v1.2 que aponta para o objeto deadbee…​.).

--match <padrão>

Considera apenas as etiquetas que correspondem ao padrão glob(7) fornecido, excluindo o prefixo "refs/tags/". Se usado com --all, também considera as ramificações locais e as referências rastreadas remotamente que correspondam ao padrão, excluindo respectivamente o prefixo "refs/heads/" e "refs/remotes/"; as referências de outros tipos nunca são consideradas. Se for usado várias vezes, uma lista de padrões será acumulada, e as etiquetas que corresponderem a qualquer um dos padrões serão consideradas. Use a opção --no-match para limpar e redefinir a lista de padrões.

--exclude <padrão>

Não considere as tags que coincidam com padrão glob (7), excluindo o prefixo "refs/tags/". Se utilizado com --all, também não considera as ramificações locais e as referências do rastreamento remoto coincidentes ao padrão, excluindo respectivamente o prefixo "refs/heads/" e "refs/remotes/"; as referências de outros tipos nunca são consideradas. Caso seja utilizado várias vezes, uma lista de padrões será acumulada e as tags que coincidam a qualquer um dos padrões serão excluídas. Quando combinada com --match, uma tag será considerada quando coincidir a pelo menos um padrão --match e não corresponder a nenhum dos padrões --exclude. Utilize --no-exclude para limpar e redefinir a lista dos padrões.

--always

Exiba o objeto commit abreviado exclusivamente como "fallback" (retirada).

--first-parent

Siga apenas o primeiro commit principal ao ver um commit de mesclado. Isto é útil quando quiser não corresponder às etiquetas nos ramos mesclados no histórico do commit de destino.

EXEMPLOS

Algo como a árvore atual do git.git, recebo:

[torvalds@g5 git]$ git describe parent
v1.0.4-14-g2414721

Ou seja, o cabeçalho atual da minha ramificação principal tem como base na v1.0.4, mas como além disso ele tem alguns commits, o "describe" adicionou a quantidade dos commits adicionais ("14") e um nome de objeto abreviado para o próprio commit ("2414721") no final.

A quantidade de commits adicionais é a quantidade de commits que seriam exibidos pelo "git log v1.0.4..parent". O sufixo do hash é "-g" + uma abreviação não ambígua para o commit principal do cume (que foi 2414721b194453f058079d897d13c4e377f92dc6). O comprimento da abreviação aumenta à medida que o repositório cresce, usando a quantidade aproximado de objetos no repositório e um pouco de matemática em torno do paradoxo do aniversário, e o padrão é um mínimo de 7. O prefixo "g" significa "git" sendo utilizado para permitir a descrição da versão de um software, dependendo do SCM onde o software é gerenciado. Isso é útil num ambiente onde as pessoas podem usar diferentes SCMs .

Ao executar o comando git description no nome de uma tag exibirá apenas o seu nome:

[torvalds@g5 git]$ git describe v1.0.4
v1.0.4

Com a opção --all, o comando pode utilizar os heads (cabeçalhos) do ramo como referência, portanto a saída exibe também o caminho de referência:

[torvalds@g5 git]$ git describe --all --abbrev=4 v1.0.5^2
tags/v1.0.0-21-g975b
[torvalds@g5 git]$ git describe --all --abbrev=4 HEAD^
heads/lt/describe-7-g975b

Com a opção --abbrev definido como 0, o comando pode ser utilizado para encontrar o nome da tag mais próximo sem nenhum sufixo:

[torvalds@g5 git]$ git describe --abbrev=0 v1.0.5^2
tags/v1.0.0

Observe que o sufixo que você recebe caso digite estes comandos hoje, pode ser que ele pareça ser mais longo do que foi antes quando Linus executou estes mesmos comandos, pois o seu repositório Git pode ter novos commits cujos nomes do objeto saem com 975b que não existiam naquela época, e o sufixo "-g975b" sozinho pode não ser suficiente para desambiguar estes commits.

ESTRATÉGIA DE PESQUISA

Para cada commit informado, o comando git describe procurará primeiro uma etiqueta que marque exatamente este commit. As etiquetas anotadas sempre terão preferência sobre as etiquetas simples, já as etiquetas com datas mais recentes sempre terão preferência sobre as etiquetas com datas mais antigas. Se for encontrada uma correspondência exata, o seu nome será exibido e a busca será interrompida.

Se uma correspondência exata não for encontrada, o comando git describe retrocederá no histórico dos commits para localizar um commit ancestral que tenha sido marcado. A etiqueta do ancestral será mostrada junto com uma abreviação do SHA-1 do "commit-ish" de entrada. Se a opção --first-parent tiver sido usada, a navegação considerará apenas o primeiro commit principal de cada commit.

Caso várias tags sejam encontradas durante a navegação, a etiqueta que tiver a mnenor quantidade de commits diferentes do "commit-ish" de entrada será selecionada e criada Aqui, a diferença entre a menor quantidade de commits é definida como a quantidade de commits que seria mostrado por git log tag..input, que será a menor quantidade de commits possíveis.

BUGS

Não poderão ser descritos os objetos da árvore, bem como os objetos etiqueta que não apontem para os commits. Ao descrever as bolhas, serão ignoradas as etiquetas simples que apontem para as bolhas, porém, a bolha ainda é descrita como <commit-ish>:<path> apesar da etiquetas simples ser favorável.

GIT

Parte do conjunto git[1]

scroll-to-top