git-update-index — регистрация содержимого файлов в рабочем каталоге в индексе

Изменяет индекс. Каждый упомянутый файл обновляется в индексе, и любое состояние не слит или требует обновления сбрасывается.

См. также git-add[1] для более удобного способа выполнения некоторых наиболее распространённых операций с индексом.

То, как git update-index обрабатывает указанные ему файлы, можно изменить с помощью различных параметров:

--refresh не вычисляет новый файл sha1 и не обновляет индекс для изменений режима/содержимого. Но что он делает, так это "повторно сопоставляет" информацию stat файла с индексом, чтобы вы могли обновить индекс для файла, который не был изменён, но запись stat которого устарела.

Например, вы захотите сделать это после выполнения git read-tree, чтобы связать детали stat индекса с соответствующими файлами.

--cacheinfo используется для регистрации файла, которого нет в текущем рабочем каталоге. Это полезно для слияния с минимальным переключением.

Чтобы сделать вид, что у вас есть файл по пути с режимом и sha1, выполните:

--info-only используется для регистрации файлов без помещения их в базу данных объектов. Это полезно для репозиториев, предназначенных только для статуса.

Оба параметра --cacheinfo и --info-only ведут себя одинаково: индекс обновляется, а база данных объектов — нет. --cacheinfo полезен, когда объект находится в базе данных, но файл недоступен локально. --info-only полезен, когда файл доступен, но вы не хотите обновлять базу данных объектов.

--index-info — это более мощный механизм, который позволяет передавать несколько определений записей из стандартного ввода и предназначен специально для сценариев. Он может принимать входные данные в трёх форматах:

Чтобы поместить запись более высокой стадии в индекс, путь должен быть сначала удалён путём подачи записи с mode=0 для этого пути, а затем подачи необходимых входных строк в третьем формате.

Например, начиная с этого индекса:

вы можете передать следующий ввод в --index-info:

Первая строка ввода подаёт 0 в качестве режима для удаления пути; SHA-1 не имеет значения, если он правильно отформатирован. Затем вторая и третья строки подают записи стадии 1 и стадии 2 для этого пути. После вышеуказанного мы получим это:

Многие операции в Git зависят от того, чтобы ваша файловая система имела эффективную реализацию lstat(2), чтобы информацию st_mtime для файлов рабочего каталога можно было недорого проверить, изменилось ли содержимое файла по сравнению с версией, записанной в файле индекса. К сожалению, некоторые файловые системы имеют неэффективный lstat(2). Если ваша файловая система — одна из них, вы можете установить бит «assume unchanged» для путей, которые вы не изменяли, чтобы Git не выполнял эту проверку. Обратите внимание, что установка этого бита на путь не означает, что Git будет проверять содержимое файла, чтобы увидеть, изменилось ли оно, — это заставляет Git пропускать любую проверку и предполагать, что он не изменился. Когда вы вносите изменения в файлы рабочего каталога, вы должны явно сообщить об этом Git, сбросив бит «assume unchanged», либо до, либо после их изменения.

Чтобы установить бит "assume unchanged", используйте параметр --assume-unchanged. Чтобы сбросить, используйте --no-assume-unchanged. Чтобы увидеть, для каких файлов установлен бит "assume unchanged", используйте git ls-files -v (см. git-ls-files[1]).

Команда обращает внимание на переменную конфигурации core.ignorestat. Когда это истинно, пути, обновлённые с помощью git update-index пути..., и пути, обновлённые с помощью других команд Git, которые обновляют и индекс, и рабочий каталог (например, git apply --index, git checkout-index -u и git read-tree -u), автоматически помечаются как "assume unchanged". Обратите внимание, что бит "assume unchanged" не устанавливается, если git update-index --refresh обнаруживает, что файл рабочего каталога соответствует индексу (используйте git update-index --really-refresh, если вы хотите пометить их как "assume unchanged").

Иногда пользователи путают бит assume-unchanged с битом skip-worktree. См. последний абзац в разделе "Бит skip-worktree" ниже для объяснения различий.

Чтобы обновить и осветить только уже переключённые файлы:

Бит skip-worktree можно определить одним (длинным) предложением: Указать git избегать записи файла в рабочий каталог, когда это разумно возможно, и считать файл неизменным, когда он отсутствует в рабочем каталоге.

Обратите внимание, что не все команды git будут обращать внимание на этот бит, и некоторые поддерживают его лишь частично.

Флаги update-index и возможности read-tree, связанные с битом skip-worktree, появились до введения команды git-sparse-checkout[1], которая предоставляет гораздо более простой способ настройки и обработки битов skip-worktree. Если вы хотите сократить ваш рабочий каталог, чтобы работать только с подмножеством файлов в репозитории, мы настоятельно рекомендуем использовать git-sparse-checkout[1] вместо низкоуровневых примитивов update-index и read-tree.

Основная цель бита skip-worktree — включение частичных переключений, т.е. наличие рабочих каталогов, в которых присутствует только подмножество путей. Когда бит skip-worktree установлен, команды Git (такие как switch, pull, merge) будут избегать записи этих файлов. Однако эти команды иногда всё же будут записывать эти файлы в важных случаях, таких как конфликты во время слияния или перемещения. Команды Git также будут избегать обработки отсутствия таких файлов как преднамеренного удаления; например, git add -u не будет индексировать удаление этих файлов, и git commit -a также не создаст коммит, удаляющий их.

Хотя этот бит похож на бит assume-unchanged, его цель отличается. Бит assume-unchanged предназначен для того, чтобы оставить файл в рабочем каталоге, но заставить Git пропустить проверку его изменений и предполагать, что файл не был изменён (хотя если он может определить без вызова stat, что файл изменился, он может записать изменения). skip-worktree указывает Git игнорировать отсутствие файла, избегать его обновления, когда это возможно, с помощью команд, которые обычно обновляют большую часть рабочего каталога (например, checkout, switch, pull и т.д.), и не записывать его отсутствие в коммиты. Обратите внимание, что в частичных переключениях (настроенных с помощью git sparse-checkout или установкой core.sparseCheckout в true), если файл помечен как skip-worktree в индексе, но найден в рабочем каталоге, Git очистит бит skip-worktree для этого файла.

Этот режим предназначен для репозиториев с очень большими индексами и направлен на сокращение времени, необходимого для многократной записи этих индексов.

В этом режиме индекс разделяется на два файла: $GIT_DIR/index и $GIT_DIR/sharedindex.<SHA-1>. Изменения накапливаются в $GIT_DIR/index, разделённом индексе, в то время как файл общего индекса содержит все записи индекса и остаётся неизменным.

Все изменения в разделённом индексе отправляются обратно в файл общего индекса, когда количество записей в разделённом индексе достигает уровня, указанного переменной конфигурации splitIndex.maxPercentChange (см. git-config[1]).

Каждый раз при создании нового файла общего индекса старые файлы общего индекса удаляются, если время их изменения старше, чем указано переменной конфигурации splitIndex.sharedIndexExpire (см. git-config[1]).

Чтобы избежать удаления файла общего индекса, который всё ещё используется, его время изменения обновляется до текущего времени каждый раз, когда новый разделённый индекс на основе файла общего индекса создаётся или читается.

Этот кэш предназначен для ускорения команд, связанных с определением неотслеживаемых файлов, таких как git status.

Эта функция работает путём записи mtime каталогов рабочего каталога, а затем пропуска чтения каталогов и вызовов stat для файлов в тех каталогах, чьё mtime не изменилось. Чтобы это работало, базовая операционная система и файловая система должны изменять поле st_mtime каталогов, если файлы в каталоге добавляются, изменяются или удаляются.

Вы можете проверить, поддерживает ли файловая система это, с помощью параметра --test-untracked-cache. Параметр --untracked-cache в старых версиях Git неявно выполнял эту проверку, но теперь это не так.

Если вы хотите включить (или отключить) эту функцию, проще использовать переменную конфигурации core.untrackedCache (см. git-config[1]), чем использовать параметр --untracked-cache для git update-index в каждом репозитории, особенно если вы хотите сделать это для всех используемых вами репозиториев, потому что вы можете установить переменную конфигурации в true (или false) в вашем $HOME/.gitconfig всего один раз, и это повлияет на все репозитории, с которыми вы работаете.

Когда переменная конфигурации core.untrackedCache изменяется, кэш неотслеживаемых файлов добавляется в индекс или удаляется из него при следующем чтении индекса командой; в то время как при использовании --[no-|force-]untracked-cache кэш неотслеживаемых файлов немедленно добавляется в индекс или удаляется из него.

До версии 2.17 в кэше неотслеживаемых файлов была ошибка, когда замена каталога символьной ссылкой на другой каталог могла привести к некорректному отображению файлов, отслеживаемых git, как неотслеживаемых. См. коммит "status: add a failing test showing a core.untrackedCache bug" в git.git. Обходной путь (и это может сработать для других необнаруженных ошибок в будущем):

Было также показано, что эта ошибка влияет на случаи, не связанные с символьными ссылками, когда каталог заменяется файлом, что касается внутренних структур кэша неотслеживаемых файлов, но не было сообщений о случаях, когда это приводило к неверному выводу "git status".

Также бывают случаи, когда существующие индексы, записанные версиями git до 2.17, ссылаются на каталоги, которых больше не существует, что может привести к выводу множества предупреждений "could not open directory" при выполнении "git status". Это новые предупреждения для существующих проблем, которые ранее молча игнорировались.

Как и в случае с ошибкой, описанной выше, решение состоит в том, чтобы однократно выполнить "git status" с core.untrackedCache=false, чтобы очистить оставшиеся повреждённые данные.

Эта функция предназначена для ускорения операций git для репозиториев с большими рабочими каталогами.

Она позволяет git работать совместно с монитором файловой системы (см. git-fsmonitor--daemon[1] и раздел "fsmonitor-watchman" в githooks[5]), который может сообщать ему, какие файлы были изменены. Это позволяет git избегать необходимости выполнять lstat() для каждого файла, чтобы найти изменённые файлы.

При использовании совместно с кэшем неотслеживаемых файлов это может ещё больше улучшить производительность, избегая затрат на сканирование всего рабочего каталога в поисках новых файлов.

Если вы хотите включить (или отключить) эту функцию, проще использовать переменную конфигурации core.fsmonitor (см. git-config[1]), чем использовать параметр --fsmonitor для git update-index в каждом репозитории, особенно если вы хотите сделать это для всех используемых вами репозиториев, потому что вы можете установить переменную конфигурации в вашем $HOME/.gitconfig всего один раз, и это повлияет на все репозитории, с которыми вы работаете.

Когда переменная конфигурации core.fsmonitor изменяется, монитор файловой системы добавляется в индекс или удаляется из него при следующем чтении индекса командой. При использовании --[no-]fsmonitor монитор файловой системы немедленно добавляется в индекс или удаляется из него.

Команда учитывает переменную конфигурации core.filemode. Если ваш репозиторий находится в файловой системе, чьи биты выполнения ненадёжны, это должно быть установлено в false (см. git-config[1]). Это заставляет команду игнорировать различия в режимах файлов, записанных в индексе, и режиме файла в файловой системе, если они различаются только по биту выполнения. В такой неудачной файловой системе вам может потребоваться использовать git update-index --chmod=.

Совершенно аналогично, если переменная конфигурации core.symlinks установлена в false (см. git-config[1]), символьные ссылки переключаются как обычные файлы, и эта команда не изменяет записанный режим файла с символьной ссылки на обычный файл.

Команда обращает внимание на переменную конфигурации core.ignorestat. См. раздел Использование бита "предполагать неизменным" выше.

Команда также обращает внимание на переменную конфигурации core.trustctime. Она может быть полезна, когда время изменения инода регулярно изменяется чем-то вне Git (обходчики файловой системы и системы резервного копирования используют ctime для отметки обработанных файлов) (см. git-config[1]).

Расширение кэша неотслеживаемых файлов может быть включено переменной конфигурации core.untrackedCache (см. git-config[1]).

Пользователи часто пытаются использовать биты assume-unchanged и skip-worktree, чтобы указать Git игнорировать изменения в отслеживаемых файлах. Это работает не так, как ожидается, поскольку Git всё равно может проверять файлы рабочего каталога с индексом при выполнении определённых операций. В общем, Git не предоставляет способа игнорировать изменения в отслеживаемых файлах, поэтому рекомендуются альтернативные решения.

Например, если файл, который вы хотите изменить, является каким-то конфигурационным файлом, репозиторий может включать образец конфигурационного файла, который затем можно скопировать в игнорируемое имя и изменить. Репозиторий может даже включать сценарий для обработки образца файла как шаблона, автоматически изменяя и копируя его.

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

Является частью пакета git[1]