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

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

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

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

де <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 замість однієї.

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

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

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

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

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

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

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

Назви тегів автоматично мають префікс refs/tags/ під час зберігання в Git, тому імпорт символу гілки CVS RELENG-1_0-FINAL використовуватиме лише RELENG-1_0-FINAL для <назва>, а 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 дозволяє фронтенду видавати нову команду from для існуючої гілки або створювати нову гілку з існуючого коміту без створення нового коміту.

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

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

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

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

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

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

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

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

Зафіксуйте, що знак стосується заданого об’єкта без попереднього створення будь-якого нового об’єкта.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Вбудований 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, щоб видалити фіктивну гілку.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Активна гілка LRU, у поєднанні з пулом рядків імен файлів та лінивим завантаженням піддерев, дозволяє швидко імпортувати проекти з понад 2000 гілками та понад 45 114 файлами з дуже обмеженим обсягом пам’яті (менше 2,7 МіБ на активну гілку).