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

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:

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.

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:

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.

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:

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:

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

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:

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").

Para atualizar e renovar apenas os arquivos já averiguados:

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.

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.

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):

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.

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.

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]).

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-config[1], git-add[1], git-ls-files[1]

Parte do conjunto git[1]