git-update-index - Зареєструвати вміст файлу в робочому дереві в індексі

Змінює індекс. Кожен згаданий файл оновлюється в індексі, а будь-який стан «не об’єднано» або «потребує оновлення» очищується.

Дивіться також git-add[1] для зручнішого способу виконання деяких найпоширеніших операцій з індексом.

Спосіб, у який git update-index обробляє файли, про які йому повідомляють, можна змінити за допомогою різних опцій:

--refresh не обчислює новий sha1-файл і не оновлює індекс для змін режиму/вмісту. Але він дійсно «повторно зіставляє» статистичну інформацію файлу з індексом, щоб ви могли оновити індекс для файлу, який не був змінений, але де запис статистики застарів.

Наприклад, вам потрібно буде зробити це після виконання команди «git read-tree», щоб пов’язати деталі індексу статистики з відповідними файлами.

--cacheinfo використовується для реєстрації файлу, який не знаходиться в поточному робочому каталозі. Це корисно для об’єднання з мінімальним отриманням.

Щоб уявити, що у вас є файл за адресою path з mode та 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. Щоб скасувати встановлення, використовуйте --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, якщо ви хочете позначити їх як "припускати без змін").

Іноді користувачі плутають біт assume-unchanged з бітом skip-worktree. Див. останній абзац розділу «Skip-worktree bit» нижче для пояснення відмінностей.

Щоб оновити та оновити лише ті файли, які вже витягнуті на чергу:

Біт пропуску робочого дерева можна визначити одним (довгим) реченням: наказати 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 пропускав перевірку його на наявність змін і припускав, що файл не був змінений (хоча якщо він може визначити без повідомлення про файл, що він змінився, він може записати зміни). 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) робочих каталогів дерева, а потім пропускає читання каталогів та виклики статистичних даних для файлів у тих каталогах, час зміни яких не змінився. Щоб це працювало, базова операційна система та файлова система повинні змінити поле 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".

Також трапляються випадки, коли існуючі індекси, написані версіями git до версії 2.17, посилатимуться на каталоги, яких більше не існує, що потенційно призведе до появи багатьох попереджень «не вдалося відкрити каталог» у «статусі git». Це нові попередження для існуючих проблем, які раніше були непомітно відкинуті.

Як і у випадку з помилкою, описаною вище, рішенням є одноразове виконання "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. Це може бути корисним, коли час зміни 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]

Частина набору git[1]