українська мова ▾ Topics ▾ Latest version ▾ git-fast-import last updated in 2.54.0

НАЗВА

git-fast-import — Бекенд для швидких імпортерів даних Git

СИНОПСИС

frontend | git fast-import [<options>]

ОПИС

Зазвичай кінцеві користувачі не використовують цю програму безпосередньо. Більшість з них воліють скористатися однією з наявних програм-інтерфейсів, котрі аналізують певний тип зовнішнього джерела та передають збережений там вміст до git fast-import.

fast-import зчитує змішаний потік команд/даних зі стандартного вводу та записує один або декілька pack-файлів безпосередньо в поточний репозиторій. Коли EOF отримується на стандартний ввід, fast-import записує оновлені посилання на гілки та теги, повністю оновлюючи поточний репозиторій щойно імпортованими даними.

Сам бекенд fast-import може імпортувати дані в порожній репозиторій (який вже було ініціалізовано за допомогою команди git init) або інкрементно оновлювати наявний заповнений репозиторій. Те, чи підтримується інкрементне імпортування з конкретного зовнішнього джерела, залежить від використовуваної програми-інтерфейсу.

ОПЦІЇ

--force

Примусово оновлювати змінені наявні гілки, навіть якщо це призведе до втрати комітів (оскільки новий коміт не містить старого).

--quiet

Вимкнути виведення, яке відображається за допомогою опції --stats, завдяки чому fast-import зазвичай не видає повідомлень у разі успішного виконання. Однак якщо у потоці імпорту містяться директиви, призначені для відображення повідомлень користувачеві (наприклад, директиви progress), відповідні повідомлення все одно будуть показані.

--stats

Показати деякі основні статистичні дані про обʼєкти, створені fast-import, файли пакунків, у яких вони зберігаються, та обсяг пам’яті, використаний fast-import під час цього запуску. Зараз показ цих даних є стандартним, але його можна вимкнути за допомогою параметра --quiet.

--allow-unsafe-features

Багато параметрів командного рядка можна надати як частину самого потоку швидкого імпорту за допомогою команд feature або option. Однак деякі з цих параметрів є небезпечними (наприклад, дозволяючи швидкому імпорту отримувати доступ до файлової системи поза репозиторієм). Ці параметри стандартно вимкнено, але їх можна дозволити, вказавши цей параметр у командному рядку. Наразі це впливає лише на команди функцій export-marks, import-marks та import-marks-if-exists.

Увімкніть цю опцію лише в тому випадку, якщо ви довіряєте програмі, яка генерує потік швидкого імпорту! Ця опція вмикається автоматично для віддалених помічників, які використовують функцію import, оскільки вони вже мають право виконувати власний код.

--signed-tags=(verbatim|warn-verbatim|warn-strip|strip|abort)

Вкажіть, як обробляти підписані теги. Поводиться так само, як і --signed-commits=<mode> нижче, за винятком того, що режим strip-if-invalid ще не підтримується. Як і для підписаних комітів, стандартний режим — verbatim.

--signed-commits=<mode>

Вкажіть, як обробляти підписані коміти. Підтримуються такі режими <mode>:

  • verbatim, що є стандартним значенням, імпортуватиме підписи комітів без попередження.

  • warn-verbatim імпортує їх, але покаже попередження.

  • Команда abort призведе до завершення роботи цієї програми при виявленні підписаного коміту.

  • strip мовчки зробить коміти непідписаними.

  • warn-strip зробить їх непідписаними, але покаже попередження.

  • strip-if-invalid перевірятиме підписи та, якщо вони недійсні, видалятиме їх та покаже попередження. Перевірка виконується так само, як це робить git-verify-commit[1].

  • sign-if-invalid[=<keyid>], подібно до strip-if-invalid, перевіряє підписи комітів і замінює недійсні підписи на новостворені. Дійсні підписи залишаються без змін. Якщо вказано <keyid>, для підписання використовується цей ключ; в іншому випадку використовується сконфігурований стандартний ключ підписання.

Параметри для фронтендів

--cat-blob-fd=<fd>

Записувати відповіді на запити get-mark, cat-blob та ls у файловий дескриптор <fd> замість stdout. Дозволяє відокремити вивід progress, призначений для кінцевого користувача, від інших виводів.

--date-format=<fmt>

Вкажіть тип дат, які фронтенд надаватиме для швидкого імпорту, в командах author, committer та tagger. Див. розділ «Формати дат» нижче для отримання детальної інформації про підтримувані формати та їхній синтаксис.

--done

Завершити з помилкою, якщо в кінці потоку немає команди done. Ця опція може бути корисною для виявлення помилок, які призводять до завершення роботи фронтенду до початку запису потоку.

Розташування файлів Marks

--export-marks=<file>

Згенерує внутрішню таблицю позначок у <file> після завершення. Позначки записуються по одній на рядок як :markid SHA-1. Фронтенди можуть використовувати цей файл для перевірки імпорту після його завершення або для збереження таблиці позначок під час інкрементальних запуску. Оскільки <file> відкривається та обрізається лише на контрольній точці (або завершенні), той самий шлях також можна безпечно надати --import-marks.

--import-marks=<file>

Перед обробкою будь-яких вхідних даних завантажте позначки, зазначені у <file>. Вхідний файл має існувати, бути читабельним та використовувати той самий формат, що й створений за допомогою --export-marks. Для імпорту кількох наборів позначок можна вказати кілька параметрів. Якщо позначка визначена з різними значеннями, перевагу має останній файл.

--import-marks-if-exists=<file>

Подібно до --import-marks, але замість того, щоб видавати помилку, тихо пропускає файл, якщо його немає.

--relative-marks
--no-relative-marks

Після вказівки --relative-marks шляхи, вказані за допомогою --import-marks= та --export-marks=, будуть відносними до внутрішньої теки в поточному репозиторії. У git-fast-import це означає, що шляхи будуть відносними до теки .git/info/fast-import. Однак інші імпортери можуть використовувати інше розташування.

Відносні та невідносні позначки можна комбінувати шляхом переплетення --(no-)-relative-marks з опціями --(import|export)-marks=.

Переписування субмодулів

--rewrite-submodules-from=<name>:<file>
--rewrite-submodules-to=<name>:<file>

Переписати ідентифікатори обʼєктів для субмодуля, вказаного в <name>, замінивши значення, використані у файлі <file> (джерело), на ті, що використовуються у файлі <file> (призначення). Позначки «джерело» мали бути створені командою git fast-export, а позначки «призначення» — командою git fast-import під час імпортування цього ж субмодуля.

<name> може бути будь-яким довільним рядком, що не містить символу двокрапки, але однакове значення має використовуватися з обома опціями при визначенні відповідних позначок. Можна вказати кілька підмодулів з різними значеннями для <name>. Не використовувати ці опції у відповідних парах є помилкою.

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

Налаштування продуктивності та стиснення

--active-branches=<n>

Максимальна кількість гілок, які потрібно підтримувати активними одночасно. Див. розділ «Використання памʼяті» нижче для отримання детальної інформації. Стандартне значення — 5.

--big-file-threshold=<n>

Максимальний розмір блобу, для якого швидкий імпорт спробує створити дельту, виражений у байтах. Стандартне значення — 512m (512 МіБ). Деякі імпортери можуть забажати зменшити це значення на системах з обмеженою памʼяттю.

--depth=<n>

Максимальна глибина дельта для дельта-перетворення блоків і дерев. Стандартне значення — 50.

--export-pack-edges=<file>

Після створення файлу packfile виведіть у файл <file> рядок даних, що містить імʼя файлу packfile та останній коміт у кожній гілці, який було записано до цього файлу. Ця інформація може стати в нагоді після імпортування проєктів, загальний обсяг об’єктів яких перевищує обмеження файлу packfile у 4 Гб, оскільки ці коміти можна використовувати як крайні точки під час викликів команди git pack-objects.

--max-pack-size=<n>

Максимальний розмір кожного вихідного файлу packfile. Стандартне значення — необмежене.

fastimport.unpackLimit

Див. git-config[1]

ПРОДУКТИВНІСТЬ

Архітектура Fast-import дозволяє імпортувати великі проєкти з мінімальним споживанням памʼяті та за найкоротший час. Якщо припустити, що інтерфейс здатний встигати за fast-import і подавати йому постійний потік даних, імпорт проектів, що містять понад 10 років історії та понад 100 000 окремих комітів, зазвичай завершується всього за 1–2 години на досить скромному обладнанні (вартістю близько 2 000 доларів США у цінах 2007 року).

Здебільшого вузькі місця виникають під час доступу до даних із зовнішніх джерел (джерело просто не встигає витягувати зміни достатньо швидко) або під час дискових операцій вводу-виводу (функція fast-import записує дані так швидко, як тільки диск їх приймає). Імпорт відбуватиметься швидше, якщо вихідні дані зберігаються на іншому диску, ніж цільовий репозиторій Git (через меншу конкуренцію за ресурси вводу-виводу).

ВАРТІСТЬ РОЗРОБКИ

Типовий фронтенд для швидкого імпорту зазвичай важить приблизно 200 рядків коду на Perl/Python/Ruby. Більшість розробників змогли створити робочі імпортери всього за кілька годин, навіть якщо це їхнє перше знайомство з швидким імпортом, а іноді навіть з Git. Це ідеальна ситуація, враховуючи, що більшість інструментів конвертації є одноразовими (використовуйте один раз і ніколи не озирайтеся назад).

ПАРАЛЕЛЬНА РОБОТА

Подібно до команд git push або git fetch, імпорт, що виконується за допомогою fast-import, можна безпечно запускати одночасно з паралельними запусками команд git repack -a -d або git gc, а також будь-якими іншими операціями Git (включно з git prune, оскільки fast-import ніколи не використовує незалежні (loose) обʼєкти).

fast-import не блокує посилання на гілки чи теги, які він активно імпортує. Після імпорту, під час фази оновлення посилань, fast-import перевіряє кожне посилання на гілку, щоб переконатися, що оновлення буде оновленням «fast-forward» (коміт, збережений у посиланні, міститься в новій історії коміту, що записується). Якщо оновлення не є оновленням «fast-forward», fast-import пропустить оновлення цього посилання і замість цього виведе застереження. fast-import завжди намагатиметься оновити всі посилання на гілки і не зупиняється після першої невдачі.

Оновлення гілки можна примусово виконати за допомогою опції --force, але рекомендується використовувати її лише для репозиторіїв, у яких не відбувається активної діяльності. Для початкового імпорту в порожній репозиторій використання опції --force не є обовʼязковим.

ТЕХНІЧНІ ПОДРОБИЦІ

Швидкий імпорт відстежує набір гілок у памʼяті. Будь-яку гілку можна створити або змінити в будь-який момент процесу імпорту, надіславши команду commit у вхідний потік. Така конструкція дозволяє фронтенд-програмі обробляти необмежену кількість гілок одночасно, генеруючи коміти в порядку їх доступності з вихідних даних. Це також значно спрощує фронтенд-програми.

fast-import не використовує і не змінює поточну робочу теку або будь-які файли в ній. (Проте він оновлює поточний репозиторій Git, на який вказує змінна GIT_DIR.) Тому інтерфейс імпорту може використовувати робочу теку для власних цілей, наприклад, для вилучення версій файлів із зовнішнього джерела. Таке ігнорування робочої теки також дозволяє fast-import працювати дуже швидко, оскільки йому не потрібно виконувати ресурсомісткі операції з оновлення файлів під час переходу між гілками.

ФОРМАТ ВВЕДЕННЯ

За винятком необроблених файлових даних (які Git не інтерпретує), формат вхідних даних швидкого імпорту базується на тексті (ASCII). Цей текстовий формат спрощує розробку та налагодження фронтенд-програм, особливо коли використовується мова вищого рівня, така як Perl, Python або Ruby.

fast-import дуже суворо ставиться до вхідних даних. Коли нижче ми вживаємо позначення SP, маємо на увазі саме один пробіл. Аналогічно, LF означає один (і лише один) символ переведення рядка, а HT — один (і лише один) знак горизонтальної табуляції. Введення додаткових символів пробілів може призвести до несподіваних результатів, таких як імена гілок або файлів із пробілами на початку чи в кінці, або до дострокового завершення роботи fast-import у разі виявлення несподіваних даних.

Коментарі до потоків

Для полегшення налагодження фронтендів fast-import ігнорує будь-який рядок, що починається з символу # (ASCII-знак «решітка»), аж до рядка, що закінчується символом LF включно. Рядок коментаря може містити будь-яку послідовність байтів, яка не містить символу LF, і тому може використовуватися для включення будь-якої детальної інформації з налагодження, що може бути специфічною для конкретного фронтенду та корисною під час аналізу потоку даних fast-import.

Формати дати

Підтримуються такі формати дати. Фронтенд повинен вибрати формат, який використовуватиметься для цього імпорту, передавши назву формату в параметрі командного рядка --date-format=<fmt>.

raw

Це рідний формат Git, <time> SP <offutc>. Він також є стандартним форматом для fast-import, якщо не було вказано --date-format.

Час події визначається як <time> як кількість секунд з епохи UNIX (північ, 1 січня 1970 року, UTC) та записується як десяткове ціле число ASCII.

Місцевий зсув вказується за допомогою <offutc> як додатний або відʼємний зсув відносно UTC. Наприклад, час за східним стандартним часом (EST), який відстає від UTC на 5 годин, у <tz> позначається як «-0500», тоді як UTC — як «+0000». Місцевий зсув не впливає на <time>; він використовується лише як рекомендація, що допомагає процедурам форматування відображати мітку часу.

Якщо у вихідному матеріалі відсутня інформація про місцевий часовий зсув, використовуйте «+0000» або найпоширеніший місцевий часовий зсув. Наприклад, багато організацій мають репозиторій CVS, до якого завжди зверталися лише користувачі, що знаходяться в одному місці та часовому поясі. У цьому випадку можна припустити прийнятний часовий зсув відносно UTC.

На відміну від формату rfc2822, цей формат є дуже суворим. Будь-яке відхилення від формату призведе до того, що fast-import відхилить значення, а також можуть бути виконані деякі перевірки правильності числових значень.

raw-permissive

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

rfc2822

Це стандартний формат дати, описаний у RFC 2822.

Прикладом такого значення є «Tue Feb 6 11:22:18 2007 -0500». Парсер Git працює точно, але є дещо поблажливим. Це той самий парсер, який використовує команда git am під час застосування латок, отриманих електронною поштою.

Деякі рядки з неправильним форматом можуть бути прийняті як дійсні дати. У деяких із цих випадків Git все ще зможе отримати правильну дату з рядка з неправильним форматом. Існують також деякі типи рядків з неправильним форматом, які Git може неправильно розібрати, але вважати дійсними. Рядки з серйозним дефектом будуть відхилені.

На відміну від наведеного вище формату raw, інформація про часовий пояс/зміщення UTC, що міститься в рядку дати RFC 2822, використовується для коригування значення дати до UTC перед зберіганням. Тому важливо, щоб ця інформація була якомога точнішою.

Якщо вихідний матеріал використовує дати в стилі RFC 2822, інтерфейс має дозволити fast-import виконувати парсинг та конвертацію (а не намагатися робити це самостійно), оскільки парсер Git добре протестований у реальних умовах.

Фронтендам слід надавати перевагу формату raw якщо вихідний матеріал вже використовує формат UNIX-епохи, його можна переконати надавати дати в цьому форматі, або його формат легко конвертувати в нього, оскільки немає двозначності при розборі.

now

Завжди використовуйте поточний час і часовий пояс. Для <when> завжди потрібно вказувати літерал now.

Це фіктивний формат. Поточний час і часовий пояс цієї системи завжди копіюються в ідентифікаційний рядок під час її створення за допомогою fast-import. Немає можливості вказати інший час або часовий пояс.

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

Якщо в команді commit використовуються окремі команди author та committer, часові відбитки можуть не збігатися, оскільки системний годинник опитується двічі (по одному разу для кожної команди). Єдиний спосіб гарантувати, що інформація про автора та виконавця матиме однакову часову мітку, — це опустити author (тобто скопіювати значення з committer) або використати формат дати, відмінний від now.

Команди

fast-import підтримує низку команд для оновлення поточного репозиторію та керування поточним процесом імпорту. Більш детальний опис (із прикладами) кожної команди наведено далі.

commit

Створює нову гілку або оновлює наявну гілку, створюючи новий коміт та оновлюючи гілку, щоб вона вказувала на щойно створений коміт.

tag

Створює об’єкт тегу з анотаціями на основі наявного коміту або гілки. Ця команда не підтримує полегшені теги, оскільки їх не рекомендується використовувати для фіксації значущих моментів у часі.

reset

Скинути наявну гілку (або нову гілку) до певної ревізії. Цю команду потрібно використовувати для зміни гілки до певної ревізії без створення коміту.

blob

Конвертувати необроблені дані файлу в блоб-обʼєкт для подальшого використання в команді commit. Ця команда необовʼязкова і не потрібна для виконання імпорту.

alias

Вкажіть, що маркер посилається на певний об’єкт, не створюючи попередньо жодного нового об’єкта. Використання --import-marks та посилання на відсутні маркери призведе до збою fast-import, тому псевдоніми можуть стати способом присвоєння комітам, які в іншому випадку були б видалені, дійсного значення (наприклад, найближчого предка, що не підлягає видаленню).

checkpoint

Примусово закриває поточний файл packfile під час швидкого імпорту, генерує його унікальну контрольну суму та індекс SHA-1, а також починає новий packfile. Ця команда необовʼязкова та не потрібна для виконання імпорту.

progress

Примушує fast-import вивести весь рядок у власний стандартний вивід. Ця команда необовʼязкова та не потрібна для виконання імпорту.

done

Позначає кінець потоку. Ця команда є необовʼязковою, якщо функцію done не було запитано за допомогою параметра командного рядка --done або команди feature done.

get-mark

Примушує fast-import виводити SHA-1, що відповідає позначці файлового дескриптора, встановленого за допомогою --cat-blob-fd або stdout, якщо не вказано.

cat-blob

Примушує fastimport виводити blob-обʼєкт у форматі cat-file --batch до файлового дескриптора, встановленого за допомогою --cat-blob-fd або stdout, якщо не вказано.

ls

Змушує fast-import вивести рядок з описом елемента теки у форматі ls-tree у файловий дескриптор, заданий параметром --cat-blob-fd, або у stdout, якщо цей параметр не вказано.

feature

Увімкнути вказану функцію. Це вимагає, щоб fast-import підтримував вказану функцію, і перериває роботу, якщо цього не відбувається.

option

Вкажіть будь-який із параметрів, перелічених у розділі ОПЦІЇ, який не змінює семантику потоку відповідно до потреб інтерфейсу. Ця команда є необовʼязковою та не потрібна для виконання імпорту.

commit

Створіть або оновіть гілку новим комітом, записавши одну логічну зміну до проєкту.

	'commit' SP <ref> LF
	mark?
	original-oid?
	('author' (SP <name>)? SP LT <email> GT SP <when> LF)?
	'committer' (SP <name>)? SP LT <email> GT SP <when> LF
	('gpgsig' SP <algo> SP <format> LF data)?
	('encoding' SP <encoding> LF)?
	data
	('from' SP <commit-ish> LF)?
	('merge' SP <commit-ish> LF)*
	(filemodify | filedelete | filecopy | filerename | filedeleteall | notemodify)*
	LF?

де <ref> — це назва гілки, де буде зроблено коміт. Зазвичай назви гілок у Git мають префікс refs/heads/, тому імпорт символу гілки CVS RELENG-1_0 використовуватиме refs/heads/RELENG-1_0 для значення <ref>. Значення <ref> має бути коректним посиланням у Git. Оскільки LF не є коректним у посиланні Git, тут не підтримується синтаксис лапок або екранування.

За потреби може зʼявитися команда mark, яка запитує fast-import для збереження посилання на щойно створений коміт для подальшого використання фронтендом (формат див. нижче). Фронтенди дуже часто позначають кожен створений ними коміт, тим самим дозволяючи створювати гілки з будь-якого імпортованого коміту в майбутньому.

Команда data, що йде після committer, повинна містити повідомлення коміту (синтаксис команди data див. нижче). Щоб імпортувати порожнє повідомлення коміту, використовуйте дані довжиною 0. Повідомлення коміту мають довільну форму та не інтерпретуються Git. Наразі вони мають бути закодовані в UTF-8, оскільки fast-import не дозволяє вказувати інші кодування.

Для оновлення вмісту гілки перед створенням коміту можна включити нуль або більше команд filemodify, filedelete, filecopy, filerename, filedeleteall та notemodify. Ці команди можна вводити в будь-якому порядку. Однак рекомендується, щоб команда filedeleteall передувала всім командам filemodify, filecopy, filerename та notemodify в одному коміті, оскільки filedeleteall очищає гілку (див. нижче).

LF після команди є необовʼязковим (раніше він був обовʼязковим). Зверніть увагу, що з міркувань зворотної сумісності, якщо коміт закінчується командою data (тобто він не має команд from, merge, filemodify, filedelete, filecopy, filerename, filedeleteall або notemodify), то в кінці команди можуть з’явитися дві команди LF замість однієї.

author

Команда author може зʼявлятися додатково, якщо інформація про автора може відрізнятися від інформації про комітера. Якщо author пропущено, то fast-import автоматично використовуватиме інформацію про комітера для частини автора коміта. Дивіться нижче опис полів у author, оскільки вони ідентичні committer.

committer

Команда committer вказує, хто зробив цей коміт і коли.

Тут <name> — це імʼя особи (наприклад, «Com M Itter'»), а <email> — це адреса електронної пошти особи («cm@example.com»). LT та GT — це символи «менше» (\x3c) та «більше» (\x3e). Вони потрібні для розмежування адреси електронної пошти від інших полів у рядку. Зверніть увагу, що <name> та <email> мають вільну форму та можуть містити будь-яку послідовність байтів, окрім LT, GT та LF. <name> зазвичай кодується в UTF-8.

Час зміни визначається параметром <when>, використовуючи формат дати, вибраний параметром командного рядка --date-format=<fmt>. Див. розділ «Формати дати» вище, щоб ознайомитися з набором підтримуваних форматів та їхнім синтаксисом.

gpgsig

Додаткова команда gpgsig використовується для додавання підпису PGP/GPG або іншого криптографічного підпису, який підписує дані коміту.

	'gpgsig' SP <git-hash-algo> SP <signature-format> LF data

Команда gpgsig приймає два аргументи:

  • <git-hash-algo> вказує, до якого формату обʼєкта Git застосовується цей підпис, або sha1, або sha256. Це дозволяє дізнатися, яке представлення коміту було підписано (версія SHA-1 або SHA-256), що допомагає як з перевіркою підпису, так і з сумісністю між репозиторіями з різними хеш-функціями.

  • <signature-format> визначає тип підпису, наприклад openpgp, x509, ssh або unknown. Це зроблено для зручності інструментів, які обробляють потік даних, щоб їм не доводилося розбирати ASCII-шифрування для визначення типу підпису.

Коміт може мати щонайбільше один підпис для формату обʼєкта SHA-1 (зберігається в заголовку "gpgsig") та один для формату обʼєкта SHA-256 (зберігається в заголовку "gpgsig-sha256").

Дивіться нижче детальний опис команди data, яка містить необроблені дані підпису.

Однак у поточній реалізації підписи ще не перевіряються. (Вже налаштований параметр конфігурації extensions.compatObjectFormat може допомогти з перевіркою підписів обʼєктів у форматах SHA-1 та SHA-256, коли це буде реалізовано.)

Note
 Це дуже експериментальна розробка, і формат команди gpgsig може змінитися в майбутньому без гарантій сумісності.

encoding

Додаткова команда encoding вказує кодування повідомлення коміту. Більшість комітів мають UTF-8, і кодування опускається, але це дозволяє імпортувати повідомлення комітів у git без попереднього перекодування.

from

Команда from використовується для визначення коміту, з якого буде ініціалізована ця гілка. Ця ревізія буде першим предком нового коміту. Стан дерева, побудованого в цьому коміті, почнеться зі стану коміту from та буде змінено модифікаціями вмісту в цьому коміті.

Пропуск команди from у першому коміті нової гілки призведе до того, що fast-import створить цей коміт без предка. Зазвичай це бажано лише для початкового коміту проєкту. Якщо фронтенд створює всі файли з нуля під час створення нової гілки, замість from можна використовувати команду merge, щоб розпочати коміт з порожнього дерева. Зазвичай бажано пропускати команду from на наявних гілках, оскільки поточний коміт на цій гілці автоматично вважається першим предком нового коміту.

Оскільки LF не є допустимим символом у refname Git або виразі SHA-1, синтаксис лапок або екранування не підтримується в <commit-ish>.

Тут <commit-ish> може бути будь-яким із наступного:

  • Назва наявної гілки, яка вже є у внутрішній таблиці гілок fast-import. Якщо fast-import не знає назви, вона обробляється як вираз SHA-1.

  • Посилання на мітку, :<idnum>, де <idnum> — номер мітки.

    Причина, через яку fast-import використовує символ : для позначення посилання на мітку, полягає в тому, що цей символ не допускається в імені гілки Git. Початковий символ : дозволяє легко відрізнити мітку 42 (:42) від гілки 42 (42 або refs/heads/42) або від скороченого SHA-1, який випадково складається лише з цифр у десятковій системі числення.

    Маркери необхідно оголосити (за допомогою mark) перед тим, як їх можна буде використовувати.

  • Повний 40-байтовий або скорочений коміт SHA-1 у шістнадцятковому форматі.

  • Будь-який дійсний вираз Git SHA-1, який перетворюється на коміт. Див. «ВИЗНАЧЕННЯ РЕВІЗІЙ» у gitrevisions[7] для отримання детальної інформації.

  • Спеціальний нульовий SHA-1 (40 нулів) вказує, що гілку потрібно видалити.

Окремий випадок перезапуску інкрементального імпорту з поточного значення гілки слід записати так:

	from refs/heads/branch^0

Суфікс ^0 необхідний, оскільки fast-import не дозволяє гілці починатися з самої себе, а гілка створюється в памʼяті ще до того, як команда from буде прочитана з вхідних даних. Додавання ^0 змусить fast-import виконувати коміт через бібліотеку парсингу версій Git, а не через внутрішню таблицю гілок, тим самим завантажуючи наявне значення гілки.

merge

Включає один додатковий коміт-предок. Додаткове посилання на предка не змінює спосіб побудови стану дерева в цьому коміті. Якщо команда from пропущена під час створення нової гілки, перший коміт merge буде першим предком поточного коміту, і гілка розпочнеться без файлів. Швидкий імпорт дозволяє необмежену кількість команд merge на коміт, тим самим створюючи n-стороннє злиття.

Тут <commit-ish> — це будь-який із виразів специфікації комітів, який також приймається from (див. вище).

filemodify

Включено до команди commit для додавання нового файлу або зміни вмісту наявного файлу. Ця команда має два різні способи визначення вмісту файлу.

Формат зовнішніх даних

Дані для файлу вже були надані попередньою командою blob. Фронтенд просто має його підключити.

	'M' SP <mode> SP <dataref> SP <path> LF

Тут зазвичай <dataref> має бути або посиланням на позначку (:<idnum>), встановленим попередньою командою blob, або повним 40-байтовим SHA-1 наявного обʼєкта Git blob. Якщо <mode> дорівнює 040000, тоді <dataref> має бути повним 40-байтовим SHA-1 наявного обʼєкта дерева Git або посиланням на позначку, встановленим за допомогою --import-marks.

Формат даних у тексті

Дані для файлу ще не надано. Фронтенд хоче надати їх як частину цієї команди зміни.

	'M' SP <mode> SP 'inline' SP <path> LF
	data

Дивіться нижче детальний опис команди data.

В обох форматах <mode> — це тип запису файлу, вказаний у вісімковому форматі. Git підтримує лише наступне:

  • 100644 або 644: Звичайний (невиконуваний) файл. Більшість файлів у більшості проєктів використовують цей режим. Якщо сумніваєтеся, це саме те, що вам потрібно.

  • 100755 або 755: Звичайний, але виконуваний файл.

  • 120000: Символічне посилання, вміст файлу буде цільовим посиланням.

  • 160000: Посилання git, SHA-1 обʼєкта, посилається на коміт в іншому репозиторії. Посилання git можна вказати лише за допомогою SHA або через позначку коміту. Вони використовуються для реалізації субмодулів.

  • 040000: Субтека. Субтеки можна вказати лише за допомогою SHA або через мітку дерева, встановлену за допомогою --import-marks.

В обох форматах <шлях> — це повний шлях до файлу, який потрібно додати (якщо він ще не існує) або змінити (якщо він вже існує).

<шлях> може бути записано як байти без лапок або як рядок у лапках у стилі C.

Коли <шлях> не починається з подвійних лапок ("), це рядок без лапок і розбирається як літеральний байт без будь-яких escape-послідовностей. Однак, якщо імʼя файлу містить LF або починається з подвійних лапок, його не можна представити як рядок без лапок і потрібно взяти в лапки. Крім того, джерело <шлях> у копії файлу або імʼя-файлу має бути взяте в лапки, якщо воно містить SP.

Коли <шлях> починається з подвійних лапок ("), це рядок у стилі C, взятий у лапки, де повне імʼя файлу укладено в пару подвійних лапок, а також використовуються escape-послідовності. Деякі символи необхідно екранувати, додаючи перед ними зворотну скісну риску: LF записується як \n, зворотна скісна риска як \\, а подвійні лапки як \". Деякі символи можна додатково записувати з escape-послідовностями: \a для дзвоника, \b для повернення назад, \f для переведення сторінки, \n для переведення рядка, \r для повернення каретки, \t для горизонтальної табуляції та \v для вертикальної табуляції. Будь-який байт можна записати 3-значними вісімковими кодами (наприклад, \033). Усі імена файлів можна представити у вигляді рядків у лапках.

<шлях> повинен використовувати роздільники тек у стилі UNIX (скісна риска /), а його значення має бути в канонічній формі. Тобто він не повинен:

  • містити порожній компонент теки (наприклад, foo//bar є недійсним),

  • закінчуватись роздільником тек (наприклад, foo/ недійсний),

  • починатись з роздільника тек (наприклад, /foo недійсний)

  • містити спеціальний компонент . або .. (наприклад, foo/./bar та foo/../bar є недійсними).

Корінь дерева може бути представлений порожнім рядком як <шлях>.

<шлях> не може містити символ NUL — ані у вигляді звичайного символу, ані у вигляді екранованого символу \000. Рекомендується завжди кодувати ` <шлях>` у форматі UTF-8.

filedelete

Включається в команду commit для видалення файлу або рекурсивного видалення всієї теки з гілки. Якщо внаслідок видалення файлу або теки її батьківська тека стане порожньою, вона також буде автоматично видалена. Цей процес поширюється вгору по дереву, доки не буде досягнуто першої непорожньої теки або кореня.

	'D' SP <path> LF

тут <шлях> — це повний шлях до файлу або теки, яку потрібно видалити з гілки. Див. filemodify вище для детального опису <шляху>.

filecopy

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

	'C' SP <path> SP <path> LF

тут перший <шлях> — це місце розташування джерела, а другий <шлях> — місце призначення. Див. filemodify вище для отримання детального опису того, як може виглядати <шлях>. Щоб використовувати шлях джерела, що містить SP, шлях потрібно взяти в лапки.

Команда filecopy виконується негайно. Після того як вміст теки джерела скопійовано до теки призначення, будь-які подальші команди, застосовані до теки джерела, не впливатимуть на вміст скопійованої теки.

filerename

Перейменовує наявний файл або теку, переміщуючи їх в інше місце в межах гілки. Наявний файл або тека повинні вже існувати. Якщо місце призначення вже існує, воно буде замінено на теку-джерело.

	'R' SP <path> SP <path> LF

тут перший <шлях> — це місце розташування джерела, а другий <шлях> — місце призначення. Див. filemodify вище для отримання детального опису того, як може виглядати <шлях>. Щоб використовувати шлях джерела, що містить SP, шлях потрібно взяти в лапки.

Команда filerename виконується негайно. Після того, як джерело було перейменовано на місце призначення, будь-які подальші команди, застосовані до джерела, створюватимуть там нові файли і не впливатимуть на місце призначення перейменування.

Зверніть увагу, що filerename — це те саме, що й filecopy, за яким слід filedelete вихідного розташування. Використання filerename дає невелику перевагу в продуктивності, але ця перевага настільки мала, що ніколи не варто намагатися перетворити пару видалення/додавання у вихідному матеріалі на перейменування для швидкого імпорту. Ця команда filerename надається лише для спрощення інтерфейсів, які вже мають інформацію про перейменування та не хочуть турбуватися про її розкладання на filecopy, за яким слідує filedelete.

filedeleteall

Включається в команду commit для видалення всіх файлів (а також усіх тек) з гілки. Ця команда скидає внутрішню структуру гілки до стану, коли в ній немає жодних файлів, що дозволяє інтерфейсу згодом додати всі необхідні файли з нуля.

	'deleteall' LF

Ця команда надзвичайно корисна, якщо фронтенд не знає (або не прагне знати), які файли наразі знаходяться у гілці, і тому не може згенерувати відповідні команди filedelete для оновлення вмісту.

Виконання команди filedeleteall, за якою слідують необхідні команди filemodify для встановлення правильного вмісту, дасть ті самі результати, що й відправлення лише необхідних команд filemodify та filedelete. Однак підхід із використанням filedeleteall може вимагати від fast-import використання дещо більшого обсягу пам’яті на кожну активну гілку (менше 1 MiB навіть для найбільших проєктів); тому інтерфейсам, які можуть легко отримати лише шляхи, на які впливає коміт, рекомендується це робити.

notemodify

Використовується в команді commit <notes-ref> для додавання нової примітки до <commit-ish> або зміни її змісту. Внутрішньо це схоже на операцію filemodify 100644 на шляху <commit-ish> (можливо, з розбиттям на субтеки) Не рекомендується використовувати будь-які інші команди для запису в дерево <notes-ref>, крім filedeleteall для видалення всіх наявних нотаток у цьому дереві. Ця команда має два різних способи вказання змісту нотатки.

Формат зовнішніх даних

Вміст даних для нотатки вже було надано попередньою командою blob. Фронтенд просто має підключити його до коміту, який потрібно анотувати.

	'N' SP <dataref> SP <commit-ish> LF

Тут <dataref> може бути або посиланням на мітку (:<idnum>), встановленим попередньою командою blob, або повним 40-байтовим SHA-1 наявного обʼєкта Git blob.

Формат даних у тексті

Дані для нотатки ще не надано. Фронтенд хоче надати їх як частину цієї команди зміни.

	'N' SP 'inline' SP <commit-ish> LF
	data

Дивіться нижче детальний опис команди data.

В обох форматах <commit-ish> — це будь-який із виразів специфікації коміту, який також приймається from (див. вище).

mark

Організовує швидкий імпорт для збереження посилання на поточний обʼєкт, дозволяючи фронтенду викликати цей обʼєкт у майбутньому, не знаючи його SHA-1. Тут поточний обʼєкт — це команда створення обʼєкта, в якій знаходиться команда mark. Це може бути commit, tag та blob, але commit є найпоширенішим використанням.

	'mark' SP ':' <idnum> LF

де <idnum> — це номер, присвоєний інтерфейсом цій позначці. Значення <idnum> подається у вигляді десяткового цілого числа у форматі ASCII. Значення 0 зарезервоване і не може використовуватися як позначка. Як позначки можуть використовуватися лише значення, більші або рівні 1.

Нові позначки створюються автоматично. Наявні позначки можна перемістити на інший обʼєкт, просто повторно використовуючи той самий <idnum> в іншій команді mark.

original-oid

Надає імʼя обʼєкта в оригінальній системі керування версіями. fast-import просто ігноруватиме цю директиву, але процеси фільтрації, які працюють з потоком та змінюють його перед передачею до fast-import, можуть використовувати цю інформацію

	'original-oid' SP <object-identifier> LF

де <object-identifier> — це будь-який рядок, що не містить LF.

tag

Створює анотований тег, що посилається на певний коміт. Щоб створити легкі (неанотовані) теги, див. команду reset нижче.

	'tag' SP <name> LF
	mark?
	'from' SP <commit-ish> LF
	original-oid?
	'tagger' (SP <name>)? SP LT <email> GT SP <when> LF
	data

де <name> — це назва тегу, який потрібно створити.

Назви тегів автоматично мають префікс refs/tags/ під час зберігання в Git, тому імпорт символу гілки CVS RELENG-1_0-FINAL використовуватиме лише RELENG-1_0-FINAL для <name>, а fast-import запише відповідне посилання як refs/tags/RELENG-1_0-FINAL.

Значення <name> має бути коректним посиланням у Git і тому може містити скісну риску. Оскільки LF не є коректним у посиланнях Git, тут не підтримується синтаксис лапок або екранування.

Команда from така ж, як і в команді commit; див. деталі вище.

Команда tagger використовує той самий формат, що й committer у commit; знову ж таки, див. деталі вище.

Команда data, що йде після tagger, повинна містити анотоване повідомлення тегу (синтаксис команди data див. нижче). Щоб імпортувати порожнє повідомлення тегу, використовуйте дані довжиною 0. Повідомлення тегів мають довільну форму та не інтерпретуються Git. Наразі вони мають бути закодовані в UTF-8, оскільки швидкий імпорт не дозволяє вказувати інші кодування.

Підписання анотованих тегів під час імпорту з fast-import не підтримується. Не рекомендується намагатися включити власний підпис PGP/GPG, оскільки фронтенд не має (легкого) доступу до повного набору байтів, які зазвичай входять до такого підпису. Якщо потрібне підписання, створіть легкі теги з fast-import за допомогою reset, а потім створіть анотовані версії цих тегів офлайн за допомогою стандартного процесу git tag.

reset

Створює (або відтворює) вказану гілку, за бажанням починаючи з певної ревізії. Команда reset дозволяє фронтенду видавати нову команду from для наявної гілки або створювати нову гілку з наявного коміту без створення нового коміту.

	'reset' SP <ref> LF
	('from' SP <commit-ish> LF)?
	LF?

Детальний опис <ref> та <commit-ish> див. вище у розділах commit та from.

Символ LF після команди є необовʼязковим (раніше він був обовʼязковим).

Команду reset також можна використовувати для створення легких (неанотованих) тегів. Наприклад:

reset refs/tags/938
from :938

створить легкий тег refs/tags/938, що посилатиметься на будь-який коміт-маркер :938.

blob

Запитує запис однієї ревізії файлу до packfile. Ревізія не повʼязана з жодним комітом; це зʼєднання має бути сформоване в наступній команді commit шляхом посилання на блоб через призначену позначку.

	'blob' LF
	mark?
	original-oid?
	data

Команда mark тут необовʼязкова, оскільки деякі фронтенди вирішили самостійно генерувати Git SHA-1 для блобу та передавати його безпосередньо до commit. Однак це зазвичай більше роботи, ніж того варте, оскільки мітки недорого зберігати та легко використовувати.

data

Надає необроблені дані (для використання як вміст блобу/файлу, повідомлення про коміти або анотовані повідомлення тегів) для fast-import. Дані можна надавати у форматі з точним зазначенням кількості байтів або у форматі, обмеженому кінцевим рядком. Справжні фронтенди, призначені для перетворення даних на професійному рівні, завжди повинні використовувати формат з точним зазначенням кількості байтів, оскільки він є більш надійним і забезпечує кращу продуктивність. Формат з обмеженням призначений переважно для тестування fast-import.

Рядки коментарів, що з’являються в частині <raw> команд data, завжди розглядаються як частина тіла даних і тому ніколи не ігноруються fast-import. Це дозволяє безпечно імпортувати будь-який вміст файлів/повідомлень, рядки якого можуть починатися з символу #.

Точний формат підрахунку байтів

Фронтенд повинен вказувати кількість байтів даних.

	'data' SP <count> LF
	<raw> LF?

де <count> — це точна кількість байтів, що зʼявляються в <raw>. Значення <count> виражається як десяткове ціле число ASCII. LF з обох боків <raw> не включається до <count> і не буде включено до імпортованих даних.

LF після <raw> є необовʼязковим (раніше він був обовʼязковим), але рекомендується. Його постійне включення спрощує налагодження потоку швидкого імпорту, оскільки наступна команда завжди починається у стовпці 0 наступного рядка, навіть якщо <raw> не закінчується на LF.

Формат з роздільниками

Для позначення кінця даних використовується рядок-роздільник. fast-import обчислить довжину, шукаючи роздільник. Цей формат корисний переважно для тестування та не рекомендується для реальних даних.

	'data' SP '<<' <delim> LF
	<raw> LF
	<delim> LF
	LF?

де <delim> — це вибраний рядок-роздільник. Рядок <delim> не повинен стояти окремо всередині <raw>, оскільки інакше fast-import вважатиме, що дані закінчуються раніше, ніж це є насправді. LF, що безпосередньо йде після <raw>, є частиною <raw>. Це одне з обмежень формату з роздільниками: неможливо надати фрагмент даних, який не має LF як останній байт.

LF після <delim> LF є необовʼязковим (раніше він був обовʼязковим).

alias

Вкажіть, що позначка стосується певного об’єкта, не створюючи при цьому жодного нового об’єкта.

	'alias' LF
	mark
	'to' SP <commit-ish> LF
	LF?

Детальний опис <commit-ish> див. вище у розділі from.

checkpoint

Змушує команду fast-import закрити поточний packfile, створити новий та зберегти всі поточні посилання на гілки, теги та мітки.

	'checkpoint' LF
	LF?

Зверніть увагу, що fast-import автоматично перемикає пакетні файли, коли поточний пакетний файл досягає --max-pack-size або 4 ГіБ, залежно від того, яка межа менша. Під час автоматичного перемикання пакетного файлу fast-import не оновлює посилання на гілки, теги чи позначки.

Оскільки виконання команди checkpoint може вимагати значних ресурсів процесора та дискових операцій вводу-виводу (для обчислення загальної контрольної суми SHA-1 пакунка, створення відповідного індексного файлу та оновлення посилань), виконання однієї команди checkpoint може легко зайняти кілька хвилин.

Фронтенди можуть створювати контрольні точки під час імпорту надзвичайно великих і тривалих даних або коли їм потрібно надати іншому процесу Git доступ до гілки. Однак, з огляду на те, що репозиторій Subversion розміром 30 Гб можна завантажити в Git за допомогою fast-import приблизно за 3 години, явне створення контрольних точок може виявитися зайвим.

Символ LF після команди є необовʼязковим (раніше він був обовʼязковим).

progress

Змушує fast-import виводити весь рядок progress без змін у стандартний потік виводу (файловий дескриптор 1) під час обробки команди з вхідного потоку. В іншому випадку команда не впливає на поточний імпорт або на будь-який внутрішній стан fast-import.

	'progress' SP <any> LF
	LF?

Частина команди <any> може містити будь-яку послідовність байтів, яка не містить LF. LF після команди є необовʼязковим. Викликаючі сторони можуть обробити вивід за допомогою інструменту, такого як sed, щоб видалити початкову частину рядка, наприклад:

frontend | git fast-import | sed 's/^progress //'

Розміщення команди progress одразу після checkpoint повідомить читача про завершення checkpoint, і він зможе безпечно отримати доступ до посилань, які було оновлено за допомогою швидкого імпорту.

get-mark

Примушує fast-import вивести SHA-1, що відповідає позначці, в stdout або у файловий дескриптор, попередньо впорядкований за допомогою аргументу --cat-blob-fd. В іншому випадку команда не впливає на поточний імпорт; її метою є отримання SHA-1, на які наступні коміти можуть посилатися у своїх повідомленнях комітів.

	'get-mark' SP ':' <idnum> LF

Дивіться розділ «Відповіді на команди» нижче для отримання детальної інформації про те, як безпечно читати цей вивід.

cat-blob

Примушує fast-import вивести блоб-обʼєкт до файлового дескриптора, попередньо впорядкованого за допомогою аргументу --cat-blob-fd. В іншому випадку команда не впливає на поточний імпорт; її головне призначення — отримати блоби, які можуть бути в памʼяті fast-import, але недоступні з цільового репозиторію.

	'cat-blob' SP <dataref> LF

<dataref> може бути або посиланням на позначку (:<idnum>), встановленим раніше, або повним 40-байтовим SHA-1 блобу Git, що вже існує або готовий до запису.

Вивід використовує той самий формат, що й git cat-file --batch:

<sha1> SP 'blob' SP <size> LF
<contents> LF

Цю команду можна використовувати там, де може зʼявитися директива filemodify, що дозволяє використовувати її посеред коміту. Для filemodify, що використовує вбудовану директиву, вона також може зʼявлятися безпосередньо перед директивою data.

Дивіться розділ «Відповіді на команди» нижче для отримання детальної інформації про те, як безпечно читати цей вивід.

ls

Виводить інформацію про обʼєкт за шляхом до файлового дескриптора, попередньо впорядкованого за допомогою аргументу --cat-blob-fd. Це дозволяє виводити блоб з активного коміту (за допомогою cat-blob) або копіювати блоб чи дерево з попереднього коміту для використання в поточному (за допомогою filemodify).

Команду ls також можна використовувати там, де може зʼявитися директива filemodify, що дозволяє використовувати її посеред коміту.

Читання з активного коміту

Цю форму можна використовувати лише в середині коміту. Шлях вказує на елемент теки в активному коміті fast-import. У цьому випадку шлях має бути взято в лапки.

	'ls' SP <path> LF
Читання з вказаного дерева

<dataref> може бути посиланням на позначку (:<idnum>) або повним 40-байтовим SHA-1 тегу Git, коміту або обʼєкта дерева, що існує вже або очікує на запис. Шлях залежить від верхнього рівня дерева з назвою <dataref>.

	'ls' SP <dataref> SP <path> LF

Дивіться filemodify вище для отримання детального опису <шляху>.

Вивід використовує той самий формат, що й git ls-tree <tree> -- <path>:

<mode> SP ('blob' | 'tree' | 'commit') SP <dataref> HT <path> LF

<dataref> представляє обʼєкт blob, дерево або commit за адресою <path> і може бути використаний у наступних командах get-mark, cat-blob, filemodify або ls.

Якщо за цим шляхом немає файлу або піддерева, git fast-import натомість видасть повідомлення

missing SP <path> LF

Дивіться розділ «Відповіді на команди» нижче для отримання детальної інформації про те, як безпечно читати цей вивід.

feature

Вимагати, щоб fast-import підтримував зазначену функцію, або припинити виконання, якщо це не так.

	'feature' SP <feature> ('=' <argument>)? LF

Частина команди <feature> може бути будь-якою з наступних:

date-format
export-marks
relative-marks
no-relative-marks
force

Дійте так, ніби відповідний параметр командного рядка з початковим символом -- було передано в командному рядку (див. ПАРАМЕТРИ вище).

import-marks
import-marks-if-exists

Подібно до --import-marks, за винятком двох аспектів: по-перше, для кожного потоку дозволена лише одна команда "feature import-marks" або "feature import-marks-if-exists"; по-друге, параметр командного рядка --import-marks= або --import-marks-if-exists перевизначає будь-яку з цих команд "feature" у потоці; по-третє, "feature import-marks-if-exists", як і відповідний параметр командного рядка, непомітно пропускає файл, що не існує.

get-mark
cat-blob
ls

Потрібно, щоб бекенд підтримував відповідно команди get-mark, cat-blob або ls. Версії fast-import, які не підтримують вказану команду, завершать роботу з відповідним повідомленням. Це дозволяє виявити помилку імпорту на ранній стадії з чітким повідомленням, замість того щоб витрачати час на початкові етапи імпорту до виявлення команди, що не підтримується.

notes

Потрібно, щоб бекенд підтримував субкоманду notemodify (N) команди commit. Версії fast-import, які не підтримують нотатки, завершать роботу з відповідним повідомленням.

done

Виводиться помилка, якщо потік завершується без команди done. Без цієї функції помилки, що призводять до раптового завершення фронтенду в зручній точці потоку, можуть залишитися непоміченими. Це може статися, наприклад, якщо фронтенд імпорту завершує роботу посеред операції без генерації SIGTERM або SIGKILL у підпорядкованому екземплярі git fast-import.

option

Обробляє вказаний параметр таким чином, щоб git fast-import працював відповідно до потреб фронтенду. Зверніть увагу, що параметри, вказані фронтендом, перевизначаються будь-якими параметрами, які може вказати користувач.

    'option' SP <option> LF

Частина <option> команди може містити будь-які опції, перелічені в розділі OPTIONS, які не змінюють семантику імпорту, без початкового символу --, і обробляється таким самим чином.

Команди параметрів повинні бути першими командами у рядку вводу (не враховуючи команди функцій); введення команди параметра після будь-якої команди, що не є командою параметра, є помилкою.

Наведені нижче параметри командного рядка змінюють семантику імпорту, тому їх не можна передати як параметри:

  • date-format

  • import-marks

  • export-marks

  • cat-blob-fd

  • force

done

Якщо функція done не використовується, обробляється так, ніби EOF було прочитано. Це можна використовувати, щоб вказати fast-import завершитися раніше.

Якщо використовується параметр командного рядка --done або команда feature done, команда done є обовʼязковою та позначає кінець потоку.

ВІДПОВІДІ НА КОМАНДИ

Нові обʼєкти, створені за допомогою fast-import, не стають доступними негайно. Більшість команд fast-import не дають помітного ефекту до наступної контрольної точки (або завершення). Інтерфейс може надсилати команди для заповнення вхідного каналу fast-import, не турбуючись про те, як швидко вони почнуть діяти, що підвищує продуктивність завдяки спрощенню планування.

Однак для деяких фронтендів корисно мати можливість зчитувати дані з поточного репозиторію під час його оновлення (наприклад, коли вихідний матеріал описує обʼєкти з точки зору латок, які потрібно застосувати до раніше імпортованих обʼєктів). Цього можна досягти, підключивши фронтенд та функцію швидкого імпорту через двонаправлені канали:

mkfifo fast-import-output
frontend <fast-import-output |
git fast-import >fast-import-output

Фронтенд, налаштований таким чином, може використовувати команди progress, get-mark, ls та cat-blob для зчитування інформації з поточного імпорту.

Щоб уникнути взаємоблокування, такі фронтенди повинні повністю спожити будь-який очікуваний вивід від progress, ls, get-mark та cat-blob, перш ніж виконувати запис у fast-import, який може призвести до блокування.

ЗВІТИ ПРО ЗБОЇ

Якщо для fast-import надано недійсні вхідні дані, робота завершиться з ненульовим статусом виходу та створиться звіт про збій на верхньому рівні репозиторію Git, в який імпортувався файл. Звіти про збої містять знімок внутрішнього стану fast-import, а також останні команди, що призвели до збою.

Усі останні команди (включно з коментарями до потоків, змінами файлів та командами відстеження прогресу) показуються в історії команд у звіті про збій, однак необроблені дані файлів та повідомлення комітів виключаються зі звіту про збій. Таке виключення економить місце у файлі звіту та зменшує обсяг буферизації, яку fast-import має виконувати під час роботи.

Після створення звіту про збій fast-import закриє поточний файл пакунку та експортує таблицю міток. Це дозволяє розробнику інтерфейсу перевірити стан репозиторію та відновити імпорт з того місця, де стався збій. Змінені гілки та мітки не оновлюються під час збою, оскільки імпорт не завершився успішно. Інформацію про гілки та мітки можна знайти у звіті про збій, і її необхідно застосувати вручну, якщо оновлення є необхідним.

Приклад збою:

$ cat >in <<END_OF_INPUT
# my very first test commit
commit refs/heads/master
committer Shawn O. Pearce <spearce> 19283 -0400
# who is that guy anyway?
data <<EOF
this is my commit
EOF
M 644 inline .gitignore
data <<EOF
.gitignore
EOF
M 777 inline bob
END_OF_INPUT
$ git fast-import <in
fatal: Corrupt mode: M 777 inline bob
fast-import: dumping crash report to .git/fast_import_crash_8434
$ cat .git/fast_import_crash_8434
fast-import crash report:
    fast-import process: 8434
    parent process     : 1391
    at Sat Sep 1 00:58:12 2007
fatal: Corrupt mode: M 777 inline bob
Most Recent Commands Before Crash
---------------------------------
  # my very first test commit
  commit refs/heads/master
  committer Shawn O. Pearce <spearce> 19283 -0400
  # who is that guy anyway?
  data <<EOF
  M 644 inline .gitignore
  data <<EOF
* M 777 inline bob

Active Branch LRU

active_branches = 1 cur, 5 max

	  pos clock name ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
	   1)      0 refs/heads/master

Inactive Branches

refs/heads/master: status : active loaded dirty tip commit : 0000000000000000000000000000000000000000 old tree : 0000000000000000000000000000000000000000 cur tree : 0000000000000000000000000000000000000000 commit clock: 0 last pack :

------------------- END OF CRASH REPORT

ПОРАДИ ТА РЕКОМЕНДАЦІЇ

Наведені нижче поради та рекомендації були зібрані від різних користувачів fast-import і наводяться тут як пропозиції.

Використовуйте одну позначку на коміт

Під час конвертації репозиторію використовуйте унікальну позначку для кожного коміту (mark :<n>) та вкажіть опцію --export-marks у командному рядку. fast-import створить дамп файлу, який містить список усіх позначок та SHA-1 обʼєкта Git, що їм відповідає. Якщо фронтенд може повʼязати позначки з вихідним репозиторієм, легко перевірити точність та повноту імпорту, порівнявши кожен коміт Git з відповідною вихідною ревізією.

Якщо ви перейшли з таких систем, як Perforce або Subversion, це має бути досить просто, оскільки позначка fast-import може відповідати номеру набору змін у Perforce або номеру ревізії у Subversion.

Вільно переходьте між гілками

Не варто намагатися оптимізувати інтерфейс так, щоб під час імпорту він працював лише з однією гілкою. Хоча це може дещо пришвидшити роботу fast-import, це, як правило, значно ускладнює код фронтенду.

Вбудований LRU гілок для швидкого імпорту, як правило, поводиться дуже добре, а вартість активації неактивної гілки настільки низька, що перемикання між гілками практично не впливає на продуктивність імпорту.

Обробка перейменувань

Під час імпорту перейменованого файлу або теки просто видаліть стару(і) назву(і) та змініть нову(і) назву(і) під час відповідного коміту. Git виконує виявлення перейменування постфактум, а не явно під час коміту.

Використовуйте гілки виправлення тегів

Деякі інші SCM-системи дозволяють користувачеві створювати теги з кількох файлів, які не належать до одного коміту/набору змін. Або створювати теги, які є підмножиною файлів, доступних у репозиторії.

Імпорт цих тегів «як є» в Git неможливий без створення хоча б одного коміту, який «виправляє» файли відповідно до вмісту тегу. Використовуйте команду reset з fast-import, щоб скинути фіктивну гілку за межами вашого звичайного простору гілок до базового коміту для тегу, потім створіть один або кілька комітів виправлення файлів і, нарешті, позначте фіктивну гілку тегом.

Наприклад, оскільки всі звичайні гілки зберігаються в refs/heads/, назвіть гілку fixup з тегом TAG_FIXUP. Таким чином, гілка fixup, що використовується імпортером, не може мати конфліктів простору імен зі справжніми гілками, імпортованими з джерела (імʼя TAG_FIXUP не є refs/heads/TAG_FIXUP).

Під час коміту виправлень розгляньте можливість використання merge для підключення коміту(ів), який(і) надає(ють) ревізії файлів, до гілки fixup. Це дозволить таким інструментам, як git blame, відстежувати реальну історію комітів та правильно анотувати вихідні файли.

Після завершення швидкого імпорту фронтенду потрібно буде виконати rm .git/TAG_FIXUP, щоб видалити фіктивну гілку.

Імпортуйте зараз, перепакуйте пізніше

Як тільки fast-import виконає свою роботу, репозиторій Git стане повністю працездатним і готовим до використання. Зазвичай це займає зовсім небагато часу, навіть у випадку досить великих проєктів (понад 100 000 комітів).

Однак перепакування репозиторію необхідне для покращення локальності даних та продуктивності доступу. Це також може тривати годинами на надзвичайно великих проєктах (особливо якщо використовується параметр -f та великий --window). Оскільки перепакування безпечно виконувати разом із програмами читання та запису, запустіть перепакування у фоновому режимі та дайте йому завершитися. Немає причин чекати, щоб дослідити свій новий проєкт Git!

Якщо ви вирішите почекати на перепакування, не намагайтеся запускати бенчмарки чи тести продуктивності, доки перепакування не буде завершено. fast-import видає неоптимальні файли пакунків, які просто ніколи не зустрічаються в реальних ситуаціях використання.

Перепакування історичних даних

Якщо ви перепаковуєте дуже старі імпортовані дані (наприклад, старіші за минулий рік), подумайте про те, щоб витратити трохи додаткового процесорного часу та вказати параметр --window=50 (або вище) під час запуску git repack. Це займе більше часу, але також призведе до меншого пакетного файлу. Вам потрібно витратити зусилля лише один раз, і всі, хто використовує ваш проєкт, отримають користь від меншого репозиторію.

Додайте деякі повідомлення про прогрес

Час від часу ваш фронтенд має надсилати повідомлення про хід виконання швидкого імпорту. Вміст повідомлень має повністю вільну форму, тому однією з пропозицій було б виводити поточний місяць і рік щоразу, коли поточна дата коміту переходить на наступний місяць. Вашим користувачам буде легше знати, яка частина потоку даних була оброблена.

ОПТИМІЗАЦІЯ PACKFILE

Під час пакування блобу fast-import завжди намагається виконати дельта-версію з останнім записаним блобом. Якщо це спеціально не передбачено фронтендом, це, ймовірно, не буде попередньою версією того ж файлу, тому згенерована дельта не буде найменшою можливою. Отриманий packfile буде стиснутий, але не оптимальний.

Фронтенди, що мають ефективний доступ до всіх версій одного файлу (наприклад, під час читання файлу RCS/CVS .v), можуть надавати всі версії цього файлу у вигляді низки послідовних команд blob. Це дозволяє fast-import обчислювати різницю між різними версіями файлу, заощаджуючи місце в кінцевому пакетному файлі. Позначки можна використовувати для подальшої ідентифікації окремих версій файлу під час виконання низки команд commit.

Файли pack, створені fast-import, не сприяють оптимальній організації доступу до диска. Це пов’язано з тим, що fast-import записує дані в тому порядку, в якому вони надходять зі стандартного вводу, тоді як Git зазвичай упорядковує дані у файлах pack таким чином, щоб найновіші дані (поточна вершина) розміщувалися перед історичними даними. Git також об’єднує коміти в групи, що прискорює обхід версій завдяки кращій локальності кешу.

З цієї причини наполегливо рекомендується, щоб користувачі перепакували репозиторій за допомогою git repack -a -d після завершення швидкого імпорту, що дозволить Git реорганізувати пакетні файли для швидшого доступу до даних. Якщо дельти блобів неоптимальні (див. вище), то додавання опції -f для примусового перерахунку всіх дельт може значно зменшити кінцевий розмір пакетного файлу (на 30-50% менше може бути досить типовим).

Замість запуску git repack ви також можете виконати git gc --aggressive, що також оптимізує інші речі після імпорту (наприклад, пакує вільні посилання). Як зазначено в розділі "AGGRESSIVE" у git-gc[1], опція --aggressive знайде нові дельти з опцією -f для git-repack[1]. З причин, описаних вище, використання --aggressive після швидкого імпорту є одним з небагатьох випадків, коли це відомо як доцільне.

ВИКОРИСТАННЯ ПАМʼЯТІ

Існує низка факторів, які впливають на обсяг пам’яті, необхідний fast-import для виконання імпорту. Подібно до критичних модулів основного коду Git, fast-import використовує власні механізми виділення пам’яті, щоб компенсувати будь-які накладні витрати, пов’язані з використанням malloc. На практиці fast-import, як правило, зводить накладні витрати malloc до нуля завдяки використанню виділення великих блоків пам’яті.

на один обʼєкт

fast-import підтримує структуру в оперативній памʼяті для кожного обʼєкта, записаного під час цього виконання. У 32-бітній системі розмір структури становить 32 байти, а в 64-бітній — 40 байтів (через більший розмір покажчиків). Обʼєкти в таблиці не звільняються до завершення роботи fast-import. Імпорт 2 мільйонів обʼєктів у 32-бітній системі потребуватиме приблизно 64 MiB пам’яті.

Таблиця обʼєктів насправді є хеш-таблицею, ключ якої повʼязаний з назвою обʼєкта (унікальний SHA-1). Така конфігурація сховища дозволяє швидкому імпорту повторно використовувати наявний або вже записаний обʼєкт та уникати запису дублікатів у вихідний packfile. Дублікати блобів напрочуд часто зустрічаються під час імпорту, зазвичай через злиття гілок у вихідному коді.

на позначку

Позначки зберігаються у розрідженому масиві, причому на кожну позначку використовується 1 покажчик (4 або 8 байт, залежно від розміру покажчика). Хоча масив є розрідженим, інтерфейсам все одно наполегливо рекомендується використовувати позначки з номерами від 1 до n, де n — загальна кількість позначок, необхідних для цього імпорту.

на гілку

Гілки класифікуються на активні та неактивні. Використання памʼяті цими двома класами суттєво відрізняється.

Неактивні гілки зберігаються в структурі, яка використовує 96 або 120 байт (відповідно 32-бітні або 64-бітні системи) плюс довжина назви гілки (зазвичай менше 200 байт) на гілку. fast-import легко обробить до 10 000 неактивних гілок у менш ніж 2 MiB памʼяті.

Активні гілки мають такі самі накладні витрати, як і неактивні, але також містять копії кожного дерева, яке нещодавно було змінено на цій гілці. Якщо субдерево include не змінювалося з моменту активації гілки, його вміст не завантажуватиметься в пам’ять, але якщо субдерево src було змінено комітом після активації гілки, його вміст завантажуватиметься в пам’ять.

Оскільки активні гілки зберігають метадані про файли, що містяться в цій гілці, розмір їхнього сховища в оперативній памʼяті може значно зрости (див. нижче).

fast-import автоматично переміщує активні гілки в неактивний стан на основі простого алгоритму, що визначає найменш використовувані гілки. Ланцюг LRU оновлюється з кожною командою commit. Максимальну кількість активних гілок можна збільшити або зменшити в командному рядку за допомогою --active-branches=.

на одне активне дерево

Дерева (тобто теки) займають лише 12 байтів памʼяті на додачу до памʼяті, необхідної для їхніх записів (див. розділ «На кожен активний файл» нижче). Вартість дерева практично дорівнює 0, оскільки його накладні витрати розподіляються між окремими файловими записами.

на кожен активний файл

Файли (та вказівники на субдерева) в активних деревах потребують 52 або 64 байти (32/64-бітні платформи) на кожен елемент. Для економії місця імена файлів і дерев обʼєднуються в загальну таблицю рядків, що дозволяє для імені файлу «Makefile» використовувати лише 16 байт (після врахування заголовка рядка) незалежно від того, скільки разів воно зустрічається в проєкті.

LRU активної гілки в поєднанні з пулом рядків імен файлів та відкладеним завантаженням субдерев дозволяє fast-import ефективно імпортувати проєкти з понад 2 000 гілок і понад 45 114 файлів, використовуючи при цьому дуже обмежений обсяг пам’яті (менше ніж 2,7 MiB на активну гілку).

СИГНАЛИ

Надсилання SIGUSR1 до процесу git fast-import передчасно завершує поточний пакетний файл, імітуючи команду checkpoint. Нетерплячий оператор може використовувати цю можливість для попереднього перегляду обʼєктів та посилань з поточного імпорту, але це призведе до збільшення часу виконання та гіршого стиснення.

КОНФІГУРАЦІЯ

Все, що знаходиться нижче цього рядка в цьому розділі, вибірково включено з документації git-config[1]. Вміст такий самий, як і там:

Warning

Missing uk/config/fastimport.adoc

See original version for this content.

ДИВ. ТАКОЖ

git-fast-export[1]

GIT

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