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

NOME

git-describe - Atribua a um objeto um nome legível para humanos com base em um "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 tag mais recente que seja acessível a partir de um commit. Caso a tag aponte para o commit, somente a tag será exibida. Caso contrário, é adicionado um sufixo ao nome da tag com a quantidade adicionais de commits na parte superior do objeto marcado e o nome abreviado do objeto commit mais recente. O resultado é um nome do objeto que é "legível para humanos" que também pode ser utilizado para identificar o commit para outros comandos do git.

É predefinido que o comando git description exiba apenas as tags com anotações (sem --all ou --tags). Para mais informações sobre a criação das anotações das tags, consulte as opções -a e -s em git-tag[1].

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

OPÇÕES

<commit-ish>…​

Descrevendo os nomes dos objetos commit. Caso seja omitido, a predefinição retorna para que HEAD seja utilizado.

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

Descreve a condição da árvore de trabalho. Quando a árvore de trabalho corresponder a um HEAD, a saída é a mesma que git describe HEAD. Caso a árvore de trabalho tenha sido modificada localmente, um "-dirty" será anexado a ela. Caso um repositório tenha sido corrompido e o Git não puder determinar se há uma modificação local, o Git exibirá uma mensagem de erro, a menos que a opção --broken seja utilizada.

--all

Em vez de usar apenas as tags anotadas, utilize qualquer "ref" encontrada no espaço de nomes refs/. Essa opção permite fazer com que coincida com qualquer ramificação conhecida, do ramo monitorado remotamente ou de uma tag leve (lightweight).

--tags

Em vez de usar apenas as anotações das tags, utilize qualquer tag que for encontrada no namespace refs/tags. Essa opção permite fazer a coincidência com uma tag "leve" (não anotada).

--contains

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

--abbrev=<n>

Em vez de usar os 7 dígitos hexadecimais predefinidos como o 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 tags mais recentes como candidatas para descrever o commit de entrada, considere até <n> candidatos. Aumentando <n> para acima de 10 haverá um consumo um pouco maior de tempo, no entanto, poderá produzir um resultado mais preciso. Um <n> que seja 0 fará com que apenas as coincidências exatas sejam exibidas.

--exact-match

Apenas os resultados exatos de saída (uma tag faz referência direta ao commit informado). Este é um sinônimo para --candidates=0.

--debug

Exibe de forma detalhada as informações sobre a estratégia de pesquisa que está sendo empregada para o erro predefinido. predefinida. O nome da tag ainda será impresso para a saída.

--long

Sempre imprima o formato longo (a tag, o a quantidade de commits e o nome abreviado do commit), mesmo quando coincidir com uma tag. Isso é útil quando você deseja ver as partes do nome do objeto commit na saída "describe", mesmo quando a confirmação em questão seja uma versão marcada. Em vez de apenas emitir o nome da tag, ele descreverá um commit como v1.2-0-gdeadbee (0º commit desde a tag v1.2 que aponta para o objeto deadbee…​.).

--match <padrão>

Considere apenas as tags que coincidam ao padrão glob (7), excluindo o prefixo "refs/tags/". Se utilizado com --all, também considera as ramificações locais e as referências do monitoramento remoto que coincidam com o padrão, excluindo respectivamente o prefixo "refs/heads/" e "refs/remotes/"; as referências dos outros tipos nunca são consideradas. Caso seja utilizado várias vezes, uma lista de padrões será acumulada e as tags que coincidam com qualquer um dos padrões serão consideradas. Utilize --no-match para limpar e redefinir a lista dos 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 da origem ao ver um commit de mesclagem. Isso é útil quando você quer que as tags não coincidam nos ramos mesclados do 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 do meu ramo "original" tem base na versão v1.0.4, mas como ele tem alguns commits a mais, o description adicionou a quantidade de commits adicionais ("14") e um nome do objeto abreviado para o próprio commit ("2414721") no final.

A quantidade de commits adicionais é a quantidade de commits que seriam exibidas com "git log v1.0.4..parent". O sufixo hash é "-g" + abreviação inequívoca para o commit como uma dica da origem (que era 2414721b194453f058079d897d13c4e377f92dc6). O prefixo "g" significa "git" e é utilizado para permitir a descrição da versão de um software, dependendo do SCM com o qual o software é gerenciado. Isso é útil em um 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-ish informado, o comando git description procurará primeiro em uma tag que identifique exatamente este commit. As tags anotadas sempre serão preferidas às tags leves, as tags com datas mais recentes sempre serão preferidas às tags com datas mais antigas. Em caso de uma coincidência exata ser encontrada, o seu nome será exibido e a pesquisa será interrompida.

Caso uma coincidência exata não seja encontrada, o comando git description retornará ao histórico do commit para encontrar um commit ancestral que tenha sido marcado. A tag do ancestral será gerada juntamente com uma abreviação do SHA-1 do commit-ish da entrada. Caso --first-parent teha sido utilizado, será considerada apenas o primeiro pai de cada commit.

No caso várias tags serem localizadas durante o procedimento, será selecionada e gerada a tag que possuir a menor quantidade de "commit-ish" diferentes na entrada. Aqui, a menor quantidade de commits diferentes é definido pela quantidade de commits que seriam exibidos através do comando git log tag..input, o seu resultado será a menor quantidade de commits possíveis.

BUGS

Os objetos árvore assim como os objetos tag que não apontem para um commit não podem ser descritos. Ao descrever as gotas, as tags mais leves que apontam para as gotas são ignoradas, porém a bolha ainda é descrita como <committ-ish>:<caminho> apesar da tag mais leve ser favorável.

GIT

Parte do conjunto git[1]