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

Modifica o índice. Cada arquivo mencionado é atualizado no índice e em qualquer estado 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 após 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 atual de trabalho. Isso é útil para a verificação mínima da mesclagem.

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

A opção --info-only é usada para registrar os arquivos sem colocá-los no banco de dados de objetos. Isso é útil para repositórios "status-only".

Tanto a opção --cacheinfo quanto a --info-only se comportam de maneira semelhante: o índice é atualizado, mas o banco de dados dos objetos não. A opção --cacheinfo é útil quando o objeto está no banco de dados, mas o arquivo não está localmente disponível. A opção --info-only é útil quando o arquivo está disponível, mas você não quer atualizar o banco de dados dos objetos.

A opção --index-info é um mecanismo mais avançado que permite alimentar várias definições da entrada a partir da entrada predefinida e foi projetado especificamente para scripts. Ele aceita três tipos de 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 o modo para remover o caminho; o SHA-1 não importa, desde que esteja bem formatado. Em seguida, a segunda e a terceira linha alimentam as entradas do estágio 1 e do estágio 2 para este caminho. Após o procedimento acima, o resultado seria o seguinte:

Muitas operações no Git dependem do seu sistema de arquivos para ter uma implementação eficiente do lstat(2), de maneira que as informações do st_mtime para os arquivos da árvore de trabalho possam ser verificadas de maneira econômica para ver se o conteúdo do arquivo foi alterado em relação à versão registrada no arquivo de índice. Infelizmente, alguns sistemas de arquivos têm um lstat(2) ineficiente. Se o seu sistema de arquivos for um deles, você pode definir o bit "assume unchanged" para os caminhos que não foram alterados para que o Git não faça esta verificação. Observe que a configuração deste bit num caminho não significa que o Git verificará o conteúdo do arquivo para ver se ele foi alterado - ele faz com que o Git omita qualquer verificação e assuma que ele não foi alterado. Quando você faz alterações nos arquivos da árvore de trabalho, é necessário informar explicitamente ao Git sobre isso, eliminando o bit "assume unchanged", antes ou após a sua alteração.

Para definir o bit "assume unchanged", use a opção --assume-unchanged. Para remover, use --no-assume-unchanged. Para ver quais os arquivos têm o bit "assume unchanged" definido, use o comando git ls-files -v (consulte git-ls-files[1]).

O comando examina a variável de configuração core.ignorestat. Quando isso for verdadeiro, os caminhos atualizados com o comando git update-index paths... e os caminhos atualizados com outros comandos do Git que atualizam o índice e a árvore de trabalho (git apply --index, git checkout-index -u e git read-tree -u por exemplo) são automaticamente marcados como "assume unchanged". Observe que o bit "assume unchanged" não é definido quando o comando git update-index --refresh encontrar o arquivo correspondente no índice da árvore de trabalho (use o comando git update-index --really-refresh se quiser marcá-los como "assume unchanged").

Às vezes, os usuários confundem o bit "assume unchanged" com o bit "skip-worktree" (ignorar árvore de trabalho). Consulte o parágrafo final da seção "Skip-worktree bit" abaixo para obter uma explicação das diferenças.

Para atualizar e renovar apenas os arquivos já averiguados:

O bit do Skip-worktree pode ser definido numa (longa) frase: Diga ao git para evitar escrever o arquivo no diretório de trabalho quando for razoavelmente possível, e trate o arquivo como inalterado quando ele não estiver presente no diretório de trabalho.

Note que nem todos os comandos do git prestarão atenção a este bit, e alguns, só são parcialmente compatíveis.

Os sinalizadores "update-index" e os recursos "read-tree" relacionados ao bit "skip-worktree" são anteriores à introdução do comando git-sparse-checkout[1], que fornece uma maneira muito mais fácil de configurar e manipular os bits "skip-worktree". Caso queira reduzir a sua árvore de trabalho para lidar apenas com um subconjunto dos arquivos no repositório, recomendamos enfaticamente o uso do git-sparse-checkout[1] em vez dos comandos de baixo nível update-index e read-tree.

O objetivo principal do bit skip-worktree é permitir checkouts esparsos, ou seja, ter diretórios de trabalho com apenas um subconjunto de caminhos presentes. Quando o bit skip-worktree estiver definido, os comandos do Git (como o switch, o pull e o merge) evitarão a gravação destes arquivos. No entanto, estes comandos às vezes gravam estes arquivos de qualquer maneira em casos importantes, como conflitos durante uma mesclagem ou um rebase. Os comandos do Git também evitarão tratar a falta desses arquivos como uma exclusão intencional; por exemplo, o comando git add -u não fará uma exclusão desses arquivos e o comando git commit -a também não fará um commit para excluí-los.

Embora este bit seja parecido com o bit assumido e alterado, seu objetivo é diferente. O bit assume-unchanged serve para deixar o arquivo na árvore de trabalho, mas fazer com que o Git omita a verificação de alterações e presuma que o arquivo não foi alterado (embora, se ele puder determinar, sem declarar o arquivo, que ele foi alterado, ele estará livre para fazer o registro das alterações). O skip-worktree diz ao Git para ignorar a ausência do arquivo, evitar atualizá-lo quando possível com comandos que normalmente atualizam grande parte do diretório de trabalho (por exemplo, checkout, switch, pull, etc.) e não deixar que a sua ausência seja registrada nos commits. Observe que nas verificações esparsas (configuradas por git sparse-checkout ou configurando core.sparseCheckout como true), se um arquivo estiver marcado como skip-worktree no índice, mas for encontrado na árvore de trabalho, o Git limpará o bit skip-worktree deste arquivo.

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 git-fsmonitor--daemon[1] e 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 os arquivos que foram alterados.

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. Se o seu repositório estiver num sistema de arquivos cujos bits executáveis não são confiáveis, isso deve ser definido como false (consulte git-config[1]). Isso faz com que o comando ignore as diferenças nos modos de arquivo registrados no índice e o modo de arquivo no sistema de arquivos se eles diferirem apenas no bit executável. Num sistema de arquivos tão infeliz, talvez seja necessário usar 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 examina a variável de configuração core.ignorestat. Consulte a seção Uso do bit "assuma como inalterado" acima.

O comando também examina a variável de configuração core.trustctime. Pode ser útil quando o tempo de alteração do inode é modificado regularmente por algo fora do Git (os rastreadores do sistema de arquivos e os sistemas de backup usam o ctime para marcar os arquivos 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 assume-unchanged e skip-worktree para dizer ao Git para ignorar as alterações nos arquivos que são rastreados. Isso não funciona como esperado, pois o Git ainda pode verificar os arquivos da árvore de trabalho em relação ao índice ao executar determinadas operações. Em geral, o Git não oferece uma maneira de ignorar as alterações nos arquivos rastreados, portanto, recomenda-se o uso de soluções alternativas.

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

git-config[1], git-add[1], git-ls-files[1]

Parte do conjunto git[1]