Pour aider à déboguer les frontaux, fast-import ignore toute ligne commençant par # (ASCII dièse/hash) jusqu’à et y compris la ligne se terminant par LF. Une ligne de commentaire peut contenir n’importe quelle séquence d’octets qui ne contient pas de LF et peut donc être utilisée pour inclure toute information de débogage détaillée qui pourrait être spécifique au frontal et utile lors de l’inspection d’un flux de données d’importation rapide.

Les formats de date suivants sont supportés. Un frontal doit sélectionner le format qu’il utilisera pour cette importation en passant le nom du format dans l’option de ligne de commande --date-format=<fmt>.

fast-import accepte plusieurs commandes pour mettre à jour le dépôt actuel et contrôler le processus d’importation en cours. Une discussion plus détaillée (avec des exemples) de chaque commande suit plus bas.

Créer ou mettre à jour une branche avec un nouveau commit, en enregistrant une modification logique au projet.

où <ref> est le nom de la branche sur laquelle le commit doit être effectué. Typiquement, les noms de branches sont préfixés par refs/heads/ dans Git, donc importer le symbole de branche CVS RELENG-1_0 utilisera refs/heads/RELENG-1_0 pour la valeur de <ref>. La valeur de <ref> doit être un nom de référence valide dans Git. Comme LF n’est pas valide dans un nom de référence Git, aucune syntaxe de citation ou d’échappement n’est supportée ici.

Une commande mark peut optionnellement apparaître, demandant à fast-import de sauvegarder une référence au commit nouvellement créé pour une utilisation future par le frontal (voir ci-dessous pour le format). Il est très courant pour les frontaux de marquer chaque commit qu’ils créent, permettant ainsi la création de branches futures à partir de n’importe quel commit importé.

La commande data qui suit committer doit fournir le message de validation (voir ci-dessous la syntaxe de la commande data). Pour importer un message de validation vide, utilisez des données de longueur 0. Les messages de validation sont de forme libre et ne sont pas interprétés par Git. Actuellement, ils doivent être encodés en UTF-8, car fast-import ne permet pas de spécifier d’autres encodages.

Une ou plusieurs commandes filemodify, filedelete, filecopy, filerename, filedeleteall et notemodify peuvent être incluses pour mettre à jour le contenu de la branche avant de créer le commit. Ces commandes peuvent être fournies dans n’importe quel ordre. Cependant, il est recommandé que la commande filedeleteall précède toutes les commandes filemodify, filecopy, filerename et notemodify dans le même commit, car filedeleteall efface la branche (voir ci-dessous).

Le LF après la commande est facultatif (il était auparavant obligatoire). Notez que pour des raisons de compatibilité ascendante, si le commit se termine par une commande data (c’est-à-dire qu’il n’y a pas de commande from, merge, filemodify, filedelete, filecopy, fileename, filedeleteall ou notemodify), alors deux commandes LF peuvent apparaître à la fin de la commande au lieu d’une seule.

Fait en sorte que l’import rapide sauvegarde une référence à l’objet courant, permettant au frontal de rappeler cet objet à un moment ultérieur, sans connaître son SHA-1. Ici, l’objet courant est la commande de création d’objet dans laquelle la commande mark apparaît. Cela peut être commit, tag, et blob, mais commit est l’usage le plus courant.

où <idnum> est le numéro attribué par le frontal à cette marque. La valeur de <idnum> est exprimée sous la forme d’un nombre entier décimal ASCII. La valeur 0 est réservée et ne peut pas être utilisée comme marque. Seules les valeurs supérieures ou égales à 1 peuvent être utilisées comme marques.

Les nouvelles marques sont créées automatiquement. Les marques existantes peuvent être déplacées vers un autre objet simplement en réutilisant le même <idnum> dans une autre commande mark.

Fournit le nom de l’objet dans le système de contrôle de la source d’origine. fast-import ignorera simplement cette directive, mais les processus de filtrage qui opèrent et modifient le flux avant de l’envoyer à fast-import peuvent avoir besoin de cette information

où <identifiant-objet> est une chaîne quelconque ne contenant pas LF.

Crée une étiquette annotée faisant référence à un commit spécifique. Pour créer des étiquettes légères (non annotés), voir la commande reset ci-dessous.

où <nom> est le nom de l’étiquette à créer.

Les noms des étiquettes sont automatiquement préfixés par refs/tags/ lorsqu’elles sont stockés dans Git, ainsi l’importation du symbole de branche CVS RELENG-1_0-FINAL utilisera juste RELENG-1_0-FINAL pour <nom>, et fast-import écrira la référence correspondante comme refs/tags/RELENG-1_0-FINAL.

La valeur de <nom> doit être un nom de référence valide dans Git et peut donc contenir des barres obliques. Comme LF n’est pas valide dans un nom de référence Git, aucune syntaxe de citation ou d’échappement n’est supportée ici.

La commande from est la même que pour la commande commit ; voir ci-dessus pour plus de détails.

La commande tagger utilise le même format que committer dans commit ; encore une fois, voir ci-dessus pour les détails.

La commande data qui suit tagger doit fournir le message d’étiquette annotée (voir ci-dessous pour la syntaxe de la commande data). Pour importer un message vide, utilisez des données de longueur 0. Les messages d’étiquette sont de forme libre et ne sont pas interprétés par Git. Actuellement, ils doivent être encodés en UTF-8, car fast-import ne permet pas de spécifier d’autres encodages.

La signature des étiquettes annotées pendant l’importation à partir de fast-import n’est pas prise en charge. Essayer d’inclure votre propre signature PGP/GPG n’est pas recommandé, car le frontal n’a pas (facilement) accès à l’ensemble des octets qui composent normalement une telle signature. Si la signature est nécessaire, créez des étiquettes légères depuis fast-import avec reset, puis créez les versions annotées de ces étiquettes hors ligne avec le processus standard git tag.

Crée (ou recrée) la branche nommée, en partant éventuellement d’une révision spécifique. La commande reset permet à un frontal d’émettre une nouvelle commande from pour une branche existante, ou de créer une nouvelle branche à partir d’un commit existant sans créer un nouveau commit.

Pour une description détaillée de <ref> et <commit-esque> voir ci-dessus sous commit et from.

Le LF après la commande est facultatif (il était auparavant obligatoire).

La commande reset peut également être utilisée pour créer des étiquettes légères (non annotées). Par exemple :

créerait l’étiquette légère refs/tags/938 faisant référence à la marque de commit :938.

Demande l’écriture d’une révision de fichier dans le fichier paquet. La révision n’est connectée à aucun commit ; cette connexion doit être formée dans une commande commit ultérieure en référençant le blob par une marque assignée.

La commande mark est optionnelle ici car certains frontaux ont choisi de générer eux-mêmes le SHA-1 de Git pour le blob et de le transmettre directement à commit. Cependant, cela représente généralement plus de travail que cela n’en vaut la peine, car les marques sont peu coûteuses à stocker et faciles à utiliser.

Fournit des données brutes (à utiliser comme contenu de blob/fichier, messages de commit ou messages de tags annotés) à fast-import. Les données peuvent être fournies en utilisant un nombre exact d’octets ou en étant délimitées par une ligne de fin. Les frontaux réels destinés à des conversions de qualité devraient toujours utiliser le format de comptage exact des octets, car il est plus robuste et plus performant. Le format délimité est principalement destiné à tester l’importation rapide.

Les lignes de commentaires apparaissant dans la partie <brut> des commandes data sont toujours considérées comme faisant partie du corps des données et ne sont donc jamais ignorées par fast-import. Cela permet d’importer en toute sécurité tout contenu de fichier/message dont les lignes pourraient commencer par #.

Enregistrer qu’une marque se réfère à un objet donné sans créer au préalable un nouvel objet.

Pour une description détaillée de <commit-esque> voir ci-dessus sous from.

Force fast-import à fermer le fichier paquet en cours, à en commencer un nouveau, et à sauvegarder toutes les références, étiquettes et marques de la branche en cours.

Notez que fast-import change automatiquement de fichier paquet lorsque le fichier paquet actuel atteint --max-pack-size, ou 4 Gio, la limite la plus petite étant retenue. Pendant un changement automatique de fichier paquet, fast-import ne met pas à jour les refs de branche, les étiquettes ou les marques.

Comme un checkpoint peut nécessiter une quantité significative de temps CPU et d’entrées-sorties sur le disque (pour calculer la somme de contrôle SHA-1 du paquet global, générer le fichier d’index correspondant, et mettre à jour les références), il peut facilement prendre plusieurs minutes pour une seule commande checkpoint.

Les frontaux peuvent choisir d’émettre des points de contrôle lors d’importations extrêmement importantes et longues, ou lorsqu’ils doivent permettre à un autre processus Git d’accéder à une branche. Cependant, étant donné qu’un dépôt Subversion de 30 Go peut être chargé dans Git par le biais d’un import rapide en 3 heures environ, la mise en place de points de contrôle explicites peut ne pas être nécessaire.

Le LF après la commande est facultatif (il était auparavant obligatoire).

Demande à fast-import d’afficher la ligne progress entière sans modification sur son canal de sortie standard (descripteur de fichier 1) lorsque la commande est traitée à partir du flux d’entrée. La commande n’a par ailleurs aucun impact sur l’importation en cours, ni sur l’état interne de fast-import’s.

La partie <chaîne-libre> de la commande peut contenir toute séquence d’octets ne contenant pas de LF. Le LF après la commande est facultatif. Les appelants peuvent souhaiter traiter la sortie à l’aide d’un outil tel que sed pour supprimer la partie de tête de la ligne, par exemple :

Placer une commande progress immédiatement après un checkpoint informera le lecteur quand le checkpoint est terminé et qu’il peut accéder en toute sécurité aux refs que l’import rapide a mis à jour.

Demande à fast-import d’imprimer le SHA-1 correspondant à une marque vers stdout ou vers le descripteur de fichier préalablement arrangé avec l’argument --cat-blob-fd. Cette commande n’a pas d’impact sur l’importation en cours ; son but est de récupérer les SHA-1 que les commits ultérieurs pourraient vouloir mentionner dans leurs messages de commit.

Voir "Réponses aux commandes" ci-dessous pour plus de détails sur la façon de lire cette sortie en toute sécurité.

Demande à fast-import d’imprimer un blob sur un descripteur de fichier préalablement défini avec l’argument --cat-blob-fd. La commande n’a autrement aucun impact sur l’importation courante ; son but principal est de récupérer les blobs qui peuvent être dans la mémoire de fast-import mais non accessibles depuis le dépôt cible.

Le <réf-data> peut être soit une référence de marque (:<idnum>) définie précédemment, soit un SHA-1 complet de 40 octets d’un blob Git, préexistant ou prêt à être écrit.

La sortie utilise le même format que git cat-file --batch :

Cette commande peut être utilisée là où une directive filemodify peut apparaître, ce qui permet de l’utiliser au milieu d’un commit. Pour un filemodify utilisant une directive inline, elle peut aussi apparaître juste avant la directive data.

Voir "Réponses aux commandes" ci-dessous pour plus de détails sur la façon de lire cette sortie en toute sécurité.

Affiche des informations sur l’objet à un chemin vers un descripteur de fichier préalablement arrangé avec l’argument --cat-blob-fd. Cela permet d’afficher un blob à partir du commit actif (avec cat-blob) ou de copier un blob ou un arbre à partir d’un commit précédent pour l’utiliser dans le commit actuel (avec filemodify).

La commande ls peut également être utilisée là où une directive filemodify peut apparaître, ce qui permet de l’utiliser au milieu d’un commit.

Voir filemodify ci-dessus pour une description détaillée de <chemin>.

La sortie utilise le même format que git ls-tree <arbre> -- <chemin> :

Le <réf-data> représente le blob, l’arbre ou l’objet commit au <chemin> et peut être utilisé dans les commandes ultérieures get-mark, cat-blob, filemodify, ou ls.

S’il n’y a pas de fichier ou de sous-arbre à ce chemin, git fast-import signalera à la place

Voir "Réponses aux commandes" ci-dessous pour plus de détails sur la façon de lire cette sortie en toute sécurité.

Exige que fast-import prenne en charge la fonctionnalité spécifiée, ou abandonne si ce n’est pas le cas.

La partie <fonction> de la commande peut être l’une des suivantes :

Traite l’option spécifiée afin que git fast-import se comporte d’une manière qui convient aux besoins du frontal Notez que les options spécifiées par le frontal sont remplacées par toutes les options que l’utilisateur peut spécifier à git fast-import lui-même.

La partie <option> de la commande peut contenir n’importe quelle option listée dans la section OPTIONS qui ne change pas la sémantique de l’importation, sans le -- de tête et est traitée de la même manière.

Les commandes d’option doivent être les premières commandes sur l’entrée (sans compter les commandes de fonctionnalité), donner une commande d’option après une commande de non-option est une erreur.

Les options de ligne de commande suivantes modifient la sémantique de l’importation et ne peuvent donc pas être passées en tant qu’option :

Si la fonction done n’est pas utilisée, traitée comme si EOF était lu. Ceci peut être utilisé pour dire à fast-import de finir plus tôt.

Si l’option de ligne de commande --done ou la commande feature done est utilisée, la commande done est obligatoire et marque la fin du flux.

Lors d’une conversion de dépôt, utilisez une marque unique par commit (mark :<n>) et fournissez l’option --export-marks sur la ligne de commande. fast-import va générer un fichier qui liste chaque marque et l’objet Git SHA-1 qui lui correspond. Si le frontal peut relier les marques au dépôt source, il est facile de vérifier l’exactitude et l’exhaustivité de l’importation en comparant chaque commit Git à la révision source correspondante.

Si vous venez d’un système tel que Perforce ou Subversion, cela devrait être assez simple, car la marque d’importation rapide peut également être le numéro de changeset de Perforce ou le numéro de révision de Subversion.

N’essayez pas d’optimiser le frontal pour qu’il s’attache à une seule branche à la fois pendant une importation. Bien que cela puisse être légèrement plus rapide pour l’importation rapide, cela tend à augmenter considérablement la complexité du code frontal.

La LRU des branches intégrée à fast-import tend à se comporter très bien, et le coût d’activation d’une branche inactive est si faible que le fait de rebondir entre les branches n’a pratiquement aucun impact sur les performances d’importation.

Lors de l’importation d’un fichier ou d’un répertoire renommé, il suffit de supprimer le ou les anciens noms et de modifier le ou les nouveaux noms lors du commit correspondant. Git effectue la détection des renommages après coup, plutôt qu’explicitement lors d’un commit.

Certains autres systèmes SCM permettent à l’utilisateur de créer une étiquette à partir de plusieurs fichiers qui ne sont pas du même commit/changeset. Ou de créer des étiquettes qui sont un sous-ensemble des fichiers disponibles dans le dépôt.

Importer ces étiquettes tels quels dans Git est impossible sans faire au moins un commit qui "répare" les fichiers pour qu’ils correspondent au contenu de l’étiquette. Utilisez la commande ‘reset’ de fast-import’pour réinitialiser une branche fictive en dehors de votre espace de branche normal au commit de base pour le tag, puis validez un ou plusieurs commits de correction de fichiers, et enfin étiquetez la branche fictive.

Par exemple, puisque toutes les branches normales sont stockées sous refs/heads/, nommez la branche de correction des étiquettes CORRECTION_ETIQUETTE. De cette façon, il est impossible que la branche de correction utilisée par l’importateur ait des conflits d’espace de noms avec les branches réelles importées depuis la source (le nom CORRECTION_ETIQUETTE n’est pas refs/heads/CORRECTION_ETIQUETTE).

Lorsque vous validez des corrections, pensez à utiliser merge pour connecter le(s) commit(s) qui fournissent des révisions de fichiers à la branche de correction. Cela permettra à des outils tels que git blame de suivre l’historique réel des commits et d’annoter correctement les fichiers sources.

Après que fast-import se termine, le frontal devra faire rm .git/CORRECTION_ETIQUETTE pour supprimer la branche factice.

Dès que l’importation rapide est terminée, le dépôt Git est complètement valide et prêt à être utilisé. En général, cela ne prend que très peu de temps, même pour les projets de grande envergure (plus de 100 000 commits).

Cependant, le repaquetage du dépôt est nécessaire pour améliorer la localité des données et les performances d’accès. Il peut également prendre des heures sur des projets extrêmement importants (surtout si -f et un grand paramètre --window sont utilisés). Puisque le ré-empaquetage est sûr à exécuter en même temps que les lecteurs et les écrivains, exécutez le ré-empaquetage en arrière-plan et laissez-le se terminer quand il se termine. Il n’y a aucune raison d’attendre pour explorer votre nouveau projet Git !

Si vous choisissez d’attendre la fin du ré-empaquetage, n’essayez pas d’exécuter des benchmarks ou des tests de performance tant que le ré-empaquetage n’est pas terminé. fast-import produit des fichiers paquets sous-optimaux qui ne sont tout simplement jamais vus en situation réelle d’utilisation.

Si vous ré-empaquetez des données importées très anciennes (par exemple, plus anciennes que l’année dernière), envisagez de dépenser un peu plus de temps CPU et de fournir --window=50 (ou plus) lorsque vous exécutez git repack. Cela prendra plus de temps, mais produira également un fichier de paquetage plus petit. Vous n’aurez à faire cet effort qu’une seule fois, et tous les utilisateurs de votre projet bénéficieront d’un dépôt plus petit.

Every once in a while have your frontend emit a progress message to fast-import. The contents of the messages are entirely free-form, so one suggestion would be to output the current month and year each time the current commit date moves into the next month. Your users will feel better knowing how much of the data stream has been processed.

fast-import maintains an in-memory structure for every object written in this execution. On a 32 bit system the structure is 32 bytes, on a 64 bit system the structure is 40 bytes (due to the larger pointer sizes). Objects in the table are not deallocated until fast-import terminates. Importing 2 million objects on a 32 bit system will require approximately 64 MiB of memory.

The object table is actually a hashtable keyed on the object name (the unique SHA-1). This storage configuration allows fast-import to reuse an existing or already written object and avoid writing duplicates to the output packfile. Duplicate blobs are surprisingly common in an import, typically due to branch merges in the source.

Marks are stored in a sparse array, using 1 pointer (4 bytes or 8 bytes, depending on pointer size) per mark. Although the array is sparse, frontends are still strongly encouraged to use marks between 1 and n, where n is the total number of marks required for this import.

Branches are classified as active and inactive. The memory usage of the two classes is significantly different.

Inactive branches are stored in a structure which uses 96 or 120 bytes (32 bit or 64 bit systems, respectively), plus the length of the branch name (typically under 200 bytes), per branch. fast-import will easily handle as many as 10,000 inactive branches in under 2 MiB of memory.

Active branches have the same overhead as inactive branches, but also contain copies of every tree that has been recently modified on that branch. If subtree include has not been modified since the branch became active, its contents will not be loaded into memory, but if subtree src has been modified by a commit since the branch became active, then its contents will be loaded in memory.

As active branches store metadata about the files contained on that branch, their in-memory storage size can grow to a considerable size (see below).

fast-import automatically moves active branches to inactive status based on a simple least-recently-used algorithm. The LRU chain is updated on each commit command. The maximum number of active branches can be increased or decreased on the command line with --active-branches=.

Trees (aka directories) use just 12 bytes of memory on top of the memory required for their entries (see “per active file” below). The cost of a tree is virtually 0, as its overhead amortizes out over the individual file entries.

Files (and pointers to subtrees) within active trees require 52 or 64 bytes (32/64 bit platforms) per entry. To conserve space, file and tree names are pooled in a common string table, allowing the filename “Makefile” to use just 16 bytes (after including the string header overhead) no matter how many times it occurs within the project.

The active branch LRU, when coupled with the filename string pool and lazy loading of subtrees, allows fast-import to efficiently import projects with 2,000+ branches and 45,114+ files in a very limited memory footprint (less than 2.7 MiB per active branch).