git-update-index

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

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

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

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

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

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

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

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

$ git update-index --add --cacheinfo <mode>,<sha1>,<path>

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

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

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

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

Например, если изначально индекс выглядит так:

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

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

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

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

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

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

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

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

Иногда пользователи путают бит «считать неизменённым» с битом skip-worktree. Объяснение различий приведено в заключительном абзаце раздела «Бит skip-worktree» ниже.

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

$ git checkout-index -n -f -a && git update-index --ignore-missing --refresh

Назначение бита 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 не создаст коммит, удаляющий их.

Хотя этот бит похож на бит «считать неизменённым», его назначение другое. Бит «считать неизменённым» позволяет оставить файл в рабочем дереве, но указать Git не проверять его на изменения и считать, что файл не менялся (хотя если 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.

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

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

Если вы хотите включить или отключить эту функцию, проще использовать переменную конфигурации 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 -c core.untrackedCache=false status

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

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

Как и в случае описанной выше ошибки, решение — однократно выполнить «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. См. раздел Using "assume unchanged" bit выше.

Команда также проверяет переменную конфигурации core.trustctime. Она может быть полезна, если время изменения inode регулярно меняется чем-либо вне 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]