Git
Português (Brasil) ▾ Topics ▾ Latest version ▾ git-update-index last updated in 2.34.1

NOME

git-update-index - Registra o conteúdo do arquivo no índice da árvore de trabalho

RESUMO

git update-index
	     [--add] [--remove | --force-remove] [--replace]
	     [--refresh] [-q] [--unmerged] [--ignore-missing]
	     [(--cacheinfo <modo>,<objeto>,<arquivo>)…​]
	     [--chmod=(+|-)x]
	     [--[no-]assume-unchanged]
	     [--[no-]skip-worktree]
	     [--[no-]ignore-skip-worktree-entries]
	     [--[no-]fsmonitor-valid]
	     [--ignore-submodules]
	     [--[no-]split-index]
	     [--[no-|test-|force-]untracked-cache]
	     [--[no-]fsmonitor]
	     [--really-refresh] [--unresolve] [--again | -g]
	     [--info-only] [--index-info]
	     [-z] [--stdin] [--index-version <n>]
	     [--verbose]
	     [--] [<arquivo>…​]

DESCRIÇÃO

Modifica o cache do índice ou do diretório. Cada arquivo mencionado é atualizado no índice e qualquer condição unmerged (não mesclado) ou que precise ser atualizado será limpo.

Consulte também git-add[1] para conhecer uma maneira mais amigável ao usuário de executar algumas das operações mais comuns no índice.

A maneira como o git update index trata os arquivos mencionados pode ser alterada utilizando as várias opções:

OPÇÕES

--add

Caso um arquivo que foi especificado ainda não esteja no índice, este será adicionado. O comportamento predefinido é ignorar os novos arquivos.

--remove

Caso um arquivo especificado estiver no índice, porém esteja ausente, este será removido. O comportamento predefinido é ignorar o arquivo que foi removido.

--refresh

Examina o índice atual e verifica se as mesclagens são necessárias ou atualizações, verificando as informações do stat().

-q

Silêncio. Caso a opção --refresh descobra que o índice precisa de uma atualização, o comportamento padrão é gerar um erro. Esta opção faz git update-index continue mesmo assim.

--ignore-submodules

Não tente atualizar os submódulos. Esta opção é respeitada apenas quando encaminhada antes da opção --refresh.

--unmerged

Caso a opção --refresh encontre alterações não mescladas no índice, é a predefinição o comportamento gerar um erro. Está opção faz git update-index continue mesmo assim.

--ignore-missing

Ignora os arquivos ausentes durante um --refresh

--cacheinfo <modo>,<objeto>,<caminho>
--cacheinfo <modo> <objeto> <caminho>

Insira diretamente as informações definidas no índice. Por questões de compatibilidade com as versões anteriores, também é possível utilizar estes três argumentos como três parâmetros separados, porém os novos usuários são incentivados a utilizar um formulário com um único parâmetro.

--index-info

Leia a informação do índice a partir do stdin.

--chmod=(+|-)x

Defina as permissões de execução nos arquivos atualizados.

--[no-]assume-unchanged

Quando está opção é definida, os nomes dos objetos registrados para os caminhos não são atualizados. Em vez disso, esta opção define/desativa o bit "assuma como inalterado" nos caminhos. Quando o bit "assuma como inalterado" está ativado, o usuário promete não alterar o arquivo e permite que o Git assuma que o arquivo da árvore de trabalho coincida ao que está registrado no índice. Caso queira alterar o arquivo da árvore de trabalho, informe ao Git desativando o bit. Às vezes, isso é útil quando trabalhar com um grande projeto em um sistema de arquivos que possua uma chamada do sistema lstat(2) muito lenta (como, por exemplo, cifs).

O Git falhará (de forma elegante) caso precise modificar este arquivo no índice, quando for mesclar em um commit por exemplo; portanto, caso o arquivo assumido não monitorado seja alterado na upstream, você precisará lidar com a situação de forma manual.

--really-refresh

Como a opção --refresh, porém verifica as informações das estatísticas incondicionalmente, sem considerar a configuração "assuma como inalterado".

--[no-]skip-worktree

Quando uma destas opções é utilizada, o nome do objeto registrado para os caminhos não é atualizado. Em vez disso, estas opções definem e desabilitam o bit "skip-worktree" (ignore a árvore de trabalho) dos caminhos. Para mais informações, consulte a seção "Skip-worktree bit" abaixo.

--[no-]ignore-skip-worktree-entries

Não remova o skip-worktree (também informado como "index-only"), mesmo quando a opção --remove for utilizada.

--[no-]fsmonitor-valid

Quando uma destas opções é utilizada, o nome do objeto registrado para os caminhos não é atualizado. Em vez disso, essas opções definem e desabilitam o bit "fsmonitor valid" (fsmonitor válido) para os caminhos. Para mais informações, consulte a seção "Monitor do Sistema de Arquivos" abaixo.

-g
--again

Executa o próprio comando git update index nos caminhos cujas entradas do índice sejam diferentes daquelas do commit HEAD.

--unresolve

Restaura a condição unmerged (não mesclado) ou needs updating (precisa ser atualizado) de um arquivo, durante uma mesclagem caso ele tenha sudo eliminado por engano.

--info-only

Não crie os objetos no banco de dados dos objetos para todos os argumentos <arquivo> que seguem esta opção; basta inserir os seus IDs do objeto no índice.

--force-remove

Remova o arquivo do índice, mesmo quando o diretório ativo ainda tenha tal arquivo. (Implica no uso da opção --remove.)

--replace

É predefinido que quando um arquivo path exista no índice, o comando git update-index recusa uma tentativa de adicionar ao path/file. Da mesma forma, caso exista um arquivo path/file, um arquivo path não poderá ser adicionado. Com a opção --replace, serão removidas automaticamente e com mensagens de aviso todos os lançamentos já existentes que entrem em conflito com o lançamento que está sendo adicionado.

--stdin

Em vez de pegar a lista dos caminhos da linha de comando, leia a lista dos caminhos na entrada padrão. É predefinido que os caminhos sejam separados por LF (ou seja, um caminho por linha).

--verbose

Relate o que está sendo adicionado e removido do índice.

--index-version <n>

Escreva o índice resultante na versão informada no formato do disco. As versões compatíveis são 2, 3 e 4. A versão predefinida atualmente é 2 ou 3, dependendo dos recursos extras que serão utilizados, como git add -N.

A versão 4 executa uma compactação do nome do caminho simples que reduz o tamanho do índice em 30%-50% nos repositórios grandes, o que resulta em um tempo de carregamento mais rápido. A versão 4 é relativamente mais nova (lançada pela primeira vez na versão 1.8.0 em outubro de 2012). As outras implementações do Git, como JGit e libgit2, ainda não são compatíveis.

-z

Só faz algum sentido se for utilizado com --stdin or --index-info; os caminhos são separados com caracteres NUL em vez de LF.

--split-index
--no-split-index

Ativar ou desativar o modo com o índice dividido. Se o modo com índice dividido já estiver ativado e a opção --split-index for utilizada novamente, todas as alterações no $GIT_DIR/index serão retornadas ao arquivo do índice compartilhado.

Estas opções entram em vigor independente de quer configuração da variável existente no core.splitIndex (consulte git-config[1]). Porém um aviso é emitido quando a alteração vai contra o valor configurado pois o valor configurado apenas entrará em vigor na próxima vez que o índice for lido, removendo o efeito pretendido da opção.

--untracked-cache
--no-untracked-cache

Ative ou desative o recurso de cache não rastreado. Antes de ativar utilize --test-untracked-cache.

Estas opções entram em vigor independente de quer configuração da variável existente no core.untrackedCache (consulte git-config[1]). Porém um aviso é emitido quando a alteração vai contra o valor configurado pois o valor configurado apenas entrará em vigor na próxima vez que o índice for lido, removendo o efeito pretendido da opção.

--test-untracked-cache

Execute apenas os testes no diretório ativo para garantir que o cache não monitorado possa ser utilizado. Você deve habilitar manualmente o cache não monitorado utilizando a opção --untracked-cache ou --force-untracked-cache ou a variável de configuração core.untrackedCache posteriormente, caso realmente queira utilizá-lo. Caso um teste falhe, o código de encerramento gerado é 1 e uma mensagem explica o que não está funcionando, conforme necessário, caso contrário, o código de encerramento é 0 e um OK é impresso.

--force-untracked-cache

O mesmo que --untracked-cache. Fornece compatibilidade retroativa com as versões mais antigas do Git, onde --untracked-cache costumava implicar com a opção --test-untracked-cache, porém esta opção ativaria a extensão incondicionalmente.

--fsmonitor
--no-fsmonitor

Ativar ou desativar o recurso de monitoramento do sistema de arquivos. Estas opções entram em vigor independente de quer configuração da variável existente no core.fsmonitor (consulte git-config[1]). Porém um aviso é emitido quando a alteração vai contra o valor configurado pois o valor configurado apenas entrará em vigor na próxima vez que o índice for lido, removendo o efeito pretendido da opção.

--

Não interprete mais argumentos como opções.

<arquivo>

Arquivos para agir. Observe que os arquivos que começam com . são descartados. Isso inclui ./arquivo e dir/./arquivo. Caso não queira isso, utilize nomes mais limpos. O mesmo se aplica aos diretórios que terminam com / e aos caminhos com //

USANDO A OPÇÃO --REFRESH

A opção --refresh não calcula um novo arquivo sha1 ou atualiza o índice para as alterações do modo/conteúdo. Porém o que é feito é "repetir a coincidência" das informações estatísticas de um arquivo ao índice, para que você possa atualizar o índice de um arquivo que não foi alterado, porém onde a entrada da estatísticas esteja desatualizada.

Como por exemplo, você gostaria de fazer isso depois de fazer um comando git read-tree, para vincular os detalhes do índice estatístico aos arquivos adequados.

USANDO AS OPÇÕES --CACHEINFO OU --INFO-ONLY

A opção --cacheinfo é usada para registrar um arquivo que não está no diretório de trabalho atual. É útil para mesclar a averiguação mínima.

Para fingir que você tem um arquivo no caminho com modo e o sha1, use:

$ git update-index --add --cacheinfo <modo>,<sha1>,<caminho>

A opção --info-only é usado para registrar os arquivos sem colocá-los no banco de dados do objeto. É útil apenas para os repositórios "condição-apenas".

Ambos os --cacheinfo e o --info-only se comportam da mesma maneira: o índice é atualizado, porém o banco de dados dos objetos não. A opção --cacheinfo é útil quando o objeto está no banco de dados, porém o arquivo não está disponível localmente. A opção --info-only é útil quando o arquivo está disponível, porém você não queira atualizar o banco de dados do objeto.

USANDO A OPÇÃO --INDEX-INFO

A opção --index-info é um mecanismo mais poderoso que permite alimentar as várias definições da entrada a partir da entrada padrão e projetada especificamente para o uso com scripts. Pode receber as entradas de três formatos:

  1. mode SP type SP sha1 TAB path

    Este formato serve para colocar a saída git ls-tree no índice.

  2. mode SP sha1 SP stage TAB path

    Este formato serve para colocar os estágios na ordem superior do arquivo no índice e coincide à saída do git ls-files --stage.

  3. mode SP sha1 TAB path

    Este formato não é mais gerado por nenhum comando Git, mas é e continuará sendo compatível através do comando update-index --index-info.

Para colocar um estágio de lançamento com prioridade mais alta ao índice, o caminho primeiro deve ser removido ao utilizar mode=0 para o caminho e em seguida alimentando as linhas necessárias da entrada ao terceiro formato.

Como por exemplo, começando com este índice:

$ git ls-files -s
100644 8a1218a1024a212bb3db30becd860315f9f3ac52 0       frotz

você pode alimentar a seguinte entrada para --index-info:

$ git update-index --index-info
0 0000000000000000000000000000000000000000	frotz
100644 8a1218a1024a212bb3db30becd860315f9f3ac52 1	frotz
100755 8a1218a1024a212bb3db30becd860315f9f3ac52 2	frotz

A primeira linha da entrada alimenta 0 como sendo o modo para remover o caminho; o SHA-1 não é importante, desde que esteja bem formatado. Em seguida, a segunda e a terceira linha alimentam as entradas stage 1 e o stage 2 para este caminho. Após o exposto, acabaríamos assim:

$ git ls-files -s
100644 8a1218a1024a212bb3db30becd860315f9f3ac52 1	frotz
100755 8a1218a1024a212bb3db30becd860315f9f3ac52 2	frotz

UTILIZANDO O BIT “ASSUME UNCHANGED”

Muitas operações no Git dependem do seu sistema de arquivos para ter uma implementação eficiente lstat(2), de modo que as informações st_mtime para os arquivos da árvore de trabalho possam ser averiguadas com menos custo para ver se o conteúdo do arquivo foi alterado em relação à versão registrada no arquivo do índice. Infelizmente, alguns sistemas de arquivos têm um lstat(2) ineficiente. Caso o seu sistema de arquivos seja um deles, é possível definir o bit "assuma como inalterado" para os caminhos que não foram alterados, fazendo com que o Git não faça essa verificação. Observe que definir este bit em um caminho não significa que o Git verificará o conteúdo do arquivo para ver se ele foi alterado — le faz com que o Git omita qualquer verificação e presuma que ele não foi alterado. Quando você faz alterações nos arquivos da árvore de trabalho, é preciso informar ao Git de forma explicita, removendo o bit "assuma como inalterado", antes ou depois de modificá-los.

Para definir o bit "assume unchanged" (assuma como inalterado), utilize a opção --assume-unchanged. Para remover a definição utilize --no-assume-unchanged. Para ver quais os arquivos tem o bit "assume unchanged" definido, utilize git ls-files -v (consulte git-ls-files[1]).

O comando analisa a variável de configuração core.ignorestat. Quando for true, os caminhos são atualizados com o comando git update-index paths... e os caminhos são atualizados com outros comandos Git que atualizam o índice e a árvore de trabalho (como, por exemplo, o git apply --index, git checkout-index -u e o git read-tree -u) são marcados automaticamente com o bit "assuma como inalterado". Observe que o bit "assuma como inalterado" não está definido caso o comando git update-index --refresh encontre o arquivo da árvore de trabalho que coincida com o índice (utilize o git update-index --really-refresh caso queira marcá-los com o bit "assuma como inalterado").

EXEMPLOS

Para atualizar e renovar apenas os arquivos já averiguados:

$ git checkout-index -n -f -a && git update-index --ignore-missing --refresh
Em um sistema de arquivos ineficiente com o a opção da configuração core.ignorestat definida
$ git update-index --really-refresh              (1)
$ git update-index --no-assume-unchanged foo.c   (2)
$ git diff --name-only                           (3)
$ edit foo.c
$ git diff --name-only                           (4)
M foo.c
$ git update-index foo.c                         (5)
$ git diff --name-only                           (6)
$ edit foo.c
$ git diff --name-only                           (7)
$ git update-index --no-assume-unchanged foo.c   (8)
$ git diff --name-only                           (9)
M foo.c
  1. impõem ao lstat(2) que defina os bits "assuma como inalterado" para os caminhos que coincidam com o índice.

  2. marque o caminho que será editado.

  3. assim faz o lstat(1) e encontra o índice que coincida com o caminho.

  4. assim faz o lstat(2) e encontra o índice que não coincida com o caminho.

  5. registrando uma nova versão nos conjuntos dos índices do bit "assuma como inalterado".

  6. e é assumido como inalterado.

  7. mesmo depois que você o edite.

  8. você pode contar sobre a alteração após o fato.

  9. agora verifica com lstat(2) e descobre o que foi alterado.

SKIP-WORKTREE BIT

Skip-worktree bit (o bit que ignora a árvore de trabalho) pode ser definido com uma sentença (longa): Ao ler uma entrada, caso esteja marcado com skip-work-tree, então o Git finge que a versão do diretório de trabalho está atualizada e em vez disso, lê a versão do índice.

Para elaborar, "ler" significa verificar a existência do arquivo, ler os atributos ou o conteúdo do mesmo. A versão do diretório de trabalho pode estar presente ou não. Caso esteja, o seu conteúdo pode coincidir à versão do índice ou não. A escrita não é afetada por este bit, a segurança do conteúdo ainda é a primeira prioridade. Observe que o Git pode atualizar o arquivo do diretório de trabalho, marcado como skip-worktree (ignore a árvore de trabalho), caso seja seguro fazê-lo (como, por exemplo, se a versão do diretório de trabalho coincide com à versão do índice)

Embora esse bit pareça com o bit assumido como inalterado, o seu objetivo é diferente dos bits que são assumidos como inalterados. Skip-worktree também tem precedência sobre o bit assumido como inalterado quando ambos estão definidos.

ÍNDICE DIVIDIDO

Este modo é projetado para repositórios com índices muito grandes e visa reduzir o tempo necessário para gravar repetidamente tais índices.

Nesse modo, o índice é dividido em dois arquivos, $GIT_DIR/index e $GIT_DIR/sharedindex.<SHA-1>. As alterações são acumuladas no $GIT_DIR/index, o índice dividido, enquanto o arquivo do índice compartilhado contém todas os lançamentos no índice e permanece inalterado.

Todas as alterações feitas índice que foi dividido são retornadas ao arquivo do índice compartilhado quando a quantidade de entradas no índice atinge um nível especificado através da variável de configuração splitIndex.maxPercentChange (consulte git-config[1]).

Sempre que um novo arquivo do índice compartilhado for criado, os arquivos do índice antigos que foram compartilhados são excluídos caso o tempo de alteração seja mais antigo do que o definido pela variável de configuração splitIndex.sharedIndexExpire (consulte git-config[1]).

Para evitar a exclusão de um arquivo do índice compartilhado que ainda esteja em uso, o seu horário de modificação é atualizado para o horário atual sempre que um novo índice dividido tiver como base o arquivo do índice compartilhado seja criado ou lido.

CACHE NÃO MONITORADO

Esse cache destina-se a acelerar os comandos que envolvem a determinação dos arquivos não monitorados, como o git status.

Esse recurso funciona gravando o mtime dos diretórios da árvore de trabalho e em seguida, omitindo a leitura dos diretórios e as chamadas da condição nos arquivos dos diretórios cujo mtime não tenha sido alterado. Para que isso funcione, o sistema operacional e o sistema de arquivos subjacentes devem alterar o campo do diretório st_mtime caso os arquivos no diretório forem adicionados, modificados ou excluídos.

Você pode testar se o sistema de arquivos é compatível com a opção --test-untracked-cache. A opção --untracked-cache usada para executar este teste de forma implícita nas versões mais antigas do Git, porém este não é mais o caso.

Caso queira ativar (ou desativar) este recurso, é mais fácil utilizar a variável de configuração core.untrackedCache (consulte git-config[1]) do que utilizar a opção --untracked-cache para o comando git update-index em cada repositório, especialmente se você quiser fazê-lo em todos os repositórios que você utiliza, pois é possível definir a variável de configuração como true (ou false) no seu $HOME/.gitconfig apenas uma vez e afetar todos os repositórios que você toque.

Quando a variável de configuração core.untrackedCache é alterada, o cache não monitorado é adicionado ou removido do índice da próxima vez que um comando lê o índice; enquanto quando --[no-|force-]untracked-cache são utilizados, o cache não monitorado é imediatamente adicionado ou removido do índice.

Antes da versão 2.17, o cache não monitorado apresentava um erro, ao substituir um diretório por um link simbólico para outro diretório, fazendo com que ele mostrasse de forma incorreta os arquivos monitorados pelo git como não monitorados. Consulte o "status: adicione um teste com falha mostrando um bug core.untrackedCache" commit com git.git. Uma solução alternativa para isso é (e isso pode funcionar para os outros erros que ainda não foram descobertos no futuro):

$ git -c core.untrackedCache=false status

Também foi demonstrado que este bug afeta os casos sem um link simbólico na reposição de um diretório por um arquivo quando se trata das estruturas internas do cache não monitorado, porém nenhum caso foi relatado onde isso tenha resultado na saída incorreta do comando "git status".

Também existem os casos onde os índices existentes escritos pelas versões do git anteriores a versão 2.17 referenciarem os diretórios que não existem mais, potencialmente fazendo com que muitos avisos de "não foi possível abrir o diretório" sejam impressos durante a execução do comando "git status". Estes são os novos avisos para problemas existentes que foram descartados anteriormente sem qualquer aviso prévio.

Assim como no bug descrito acima, a solução é executar um "status git" único com core.untrackedCache=false para liberar os dados ruins restantes.

MONITOR DO SISTEMA DE ARQUIVOS

Este recurso visa acelerar as operações do git para os repositórios que possuem grandes diretórios de trabalho.

Ele permite que o git trabalhe em conjunto com um monitor do sistema de arquivos (consulte a seção "fsmonitor-watchman" do githooks[5]) que pode informá-lo sobre quais os arquivos foram alterados. Isso permite que o git evite ter que fazer um lstat() em todo arquivo para localizar quais arquivos foram modificados.

Quando usado em conjunto com o cache não monitorado, pode melhorar ainda mais o desempenho, evitando o custo de varrer todo o diretório ativo à procura de novos arquivos.

Caso queira ativar (ou desativar) este recurso, é mais fácil utilizar a variável de configuração core.fsmonitor (consulte git-config[1]) do que utilizar a opção --fsmonitor para o comando git update-index em cada repositório, especialmente se você quiser fazê-lo em todos os repositórios que você utiliza, pois é possível definir a variável de configuração no seu $HOME/.gitconfig apenas uma vez e afetar todos os repositórios que você toque.

Quando a variável de configuração core.fsmonitor é alterada, o monitor do sistema de arquivos é adicionado ou removido do índice na próxima vez que um comando leia o índice. Quando --[no-]fsmonitor é usado, o monitor do sistema de arquivos é imediatamente adicionado ou removido do índice.

CONFIGURAÇÃO

O comando honra a variável de configuração core.filemode. Defina como false caso o seu repositório esteja em um sistema de arquivos cujos bits dos executáveis não sejam confiáveis (consulte git-config[1]). Isso faz com que o comando ignore as diferenças nos modos do arquivo registrados no índice e no modo do arquivo do sistema de arquivos caso eles divirjam apenas no bit executável. Em um sistema de arquivos tão infeliz, talvez seja necessário usar o comando git update-index --chmod =.

De maneira semelhante, caso a variável de configuração core.symlinks esteja definida como false (consulte git-config[1]) os links simbólicos serão verificados como arquivos simples e esse comando não modificará o modo de gravação do arquivo vindo de link simbólico para um arquivo regular.

O comando analisa a variável de configuração core.ignorestat. Consulte a seção Usando o bit "assuma como inalterado" acima.

O comando também analisa a variável de configuração core.trustctime. Pode ser útil quando o tempo da alteração do "inode" for alterado regularmente por algo fora do Git (os rastreadores do sistema dos arquivos e os sistemas de backup utilizam o "ctime" para marcar os arquivos que forem processados) (consulte git-config[1]).

A extensão do cache não rastreado pode ser ativado através da configuração de variável core.untrackedCache (consulte git-config[1]).

OBSERVAÇÕES

Os usuários geralmente tentam usar os bits "assuma como inalterado" e ignoram a árvore de trabalho para dizer ao Git para ignorar as alterações nos arquivos monitorados. Isso não funciona conforme o esperado, pois o Git ainda pode verificar os arquivos da árvore de trabalho em relação ao índice durante a execução de determinadas operações. Em geral, o Git não fornece uma maneira de ignorar as alterações nos arquivos monitorados, portanto, as soluções alternativas são recomendadas.

Como por exemplo, caso o arquivo que você deseja alterar seja algum tipo de arquivo de configuração, o repositório poderá incluir um arquivo de configuração de amostra que poderá ser copiado no nome que foi ignorado e modificado. O repositório pode até incluir um script para tratar o arquivo de amostra como um modelo, modificando e copiando-o automaticamente.

GIT

Parte do conjunto git[1]

scroll-to-top