Setup and Config
Getting and Creating Projects
Basic Snapshotting
Branching and Merging
Sharing and Updating Projects
Inspection and Comparison
Patching
Debugging
External Systems
Server Admin
Guides
- gitattributes
- Command-line interface conventions
- Everyday Git
- Frequently Asked Questions (FAQ)
- Glossary
- Hooks
- gitignore
- gitmodules
- Revisions
- Submodules
- Tutorial
- Workflows
- All guides...
Administration
Plumbing Commands
- 2.43.0 11/20/23
- 2.37.1 → 2.42.1 no changes
- 2.37.0 06/27/22
- 2.35.1 → 2.36.6 no changes
- 2.35.0 01/24/22
- 2.33.1 → 2.34.8 no changes
- 2.33.0 08/16/21
- 2.32.1 → 2.32.7 no changes
- 2.32.0 06/06/21
- 2.31.1 → 2.31.8 no changes
- 2.31.0 03/15/21
- 2.29.1 → 2.30.9 no changes
- 2.29.0 10/19/20
- 2.27.1 → 2.28.1 no changes
- 2.27.0 06/01/20
SYNOPSIS
git pack-objects [-q | --progress | --all-progress] [--all-progress-implied] [--no-reuse-delta] [--delta-base-offset] [--non-empty] [--local] [--incremental] [--window=<n>] [--depth=<n>] [--revs [--unpacked | --all]] [--keep-pack=<nom-de-paquet>] [--cruft] [--cruft-expiration=<temps>] [--stdout [--filter=<filter-spec>] | <nom-de-base>] [--shallow] [--keep-true-parents] [--[no-]sparse] < <list-d-objests>
DESCRIPTION
Lit la liste des objets de l’entrée standard, et écrit une ou plusieurs archives empaquetées avec le nom de base spécifié sur le disque, ou une archive empaquetée à la sortie standard.
Une archive empaquetée est un moyen efficace de transférer un ensemble d’objets entre deux dépôts ainsi qu’un format d’archive efficace d’accès. Dans une archive empaquetée, un objet est soit stocké en entier compressé, soit comme une différence d’un autre objet. Ce dernier est souvent appelé delta.
Le format d’archive empaqueté (.pack) est conçu pour être auto-contenu afin qu’il puisse être dépaqueté sans autre information. Par conséquent, chaque objet dont dépend un delta doit être présent dans le paquet.
Un fichier d’index de paquet (.idx) est généré pour un accès rapide et aléatoire aux objets dans le pack. Placer à la fois le fichier index (.idx) et l’archive empaquetée (.pack) dans le sous-répertoire /pack de $GIT_OBJECT_DIRECTORY (ou l’un des répertoires sur $GIT_ALTERNATE_OBJECT_DIRECTORIES) permet Git de lire depuis l’archive empaquetée.
La commande git unpack-objects peut lire l’archive empaquetée et développer les objets contenus dans le paquet en format "un fichier - un objet" ; c’est généralement fait par les commandes smart-pull lorsqu’un paquet est créé à la volée pour un transport réseau efficace par leurs pairs.
OPTIONS
- nom-de-base
-
Écrire dans des paires de fichiers (.pack et .idx), en utilisant <nom-de-base> pour déterminer le nom du fichier créé. Lorsque cette option est utilisée, les deux fichiers d’une paire sont écrits dans les fichiers <nom-de-base>-<SHA1>.{pack,idx}. <SHA-1> est une empreinte basée sur le contenu du paquet est écrit à la sortie standard de la commande.
- --stdout
-
Écrire le contenu du paquet (ce qui aurait été écrit dans le fichier .pack) à la sortie standard.
- --revs
-
Lire les arguments de révision de l’entrée standard, au lieu des noms d’objets individuels. Les arguments de révision sont traités de la même manière que git rev-list avec le drapeau
--objects' utilise ses arguments `commit
pour construire la liste des objets qu’il produit. Les objets de la liste résultante sont empaquetés. En plus des révisions, les lignes--not
ou--shallow <SHA-1>
sont également acceptées. - --unpacked
-
Cela implique
--revs
. Lors du traitement de la liste des arguments de révision lus à partir de l’entrée standard, limiter les objets empaquetés à ceux qui ne sont pas déjà empaquetés. - --all
-
Cela implique
--revs
. En plus de la liste des arguments de révision lus à partir de l’entrée standard, prétendre que toutes les réfs sousrefs/
sont spécifiées pour être incluses. - --include-tag
-
Inclure les étiquettes annotées non demandées si l’objet qu’elles références a été inclus dans le fichier paquet. Cela peut être utile pour envoyer de nouvelles étiquettes aux clients Git natifs.
- --stdin-packs
-
Lire les noms de base des fichiers paquets (par exemple,
pack-1234abcd.pack
) depuis l’entrée standard, au lieu des arguments des noms d’objets ou de révision. Le paquet résultant contient tous les objets listés dans les paquets inclus (ceux qui ne commencent pas par^
), excluant les objets énumérés dans les paquets exclus (commençant par^
).Incompatible avec
--revs
, ou options qui impliquent--revs
(comme--all
), à l’exception de--unpacked
, qui est compatible. - --cruft
-
Empaquette les objets inaccessibles dans un paquet séparé "déchet", dénoté par l’existence d’un fichier
.mtimes
. Habituellement utilisé pargit repack --cruft
. Les appelants fournissent une liste de noms de paquets et indiquent quels paquets resteront dans le dépôt, ainsi que quels paquets seront supprimés (indiqués par le préfixe-
). Le contenu du paquet déchet sont tous des objets non contenus dans les paquets survivants qui n’ont pas dépassé la période de grâce (voir--cruft-extension
ci-dessous), ou qui ont dépassé la période de grâce, mais sont accessibles à partir d’un autre objet qui n’a pas survécu.Lorsque l’entrée énumère un paquet contenant tous les objets accessibles (et énumère tous les autres paquets en attente de suppression), le paquet déchet correspondant contiendra tous les objets inaccessibles (avec mtime plus récent que le
-cruft-expiration
) ainsi que tous les objets inaccessibles dont le mtime est plus âgé que le-cruft-expiration', mais qui sont accessibles à partir d'un objet inaccessible dont le mtime est plus récent que `--cruft-expiration
.Incompatible avec
--unpack-unreachable
,--keep-unreachable
,---pack-loose-unreachable
,--stdin-packs
, ainsi que toutes les autres options qui impliquent--revs
. - --cruft-expiration=<approxi-date>
-
Si spécifié, les objets sont éliminés du paquet de déchet s’ils ont un mtime plus âgé que
<approxi-date>
. Si des objets non spécifiés (et avec--cruft
), aucun objet n’est pas éliminé. - --window=<n>
- --depth=<n>
-
Ces deux options affectent la façon dont les objets contenus dans le paquet sont stockés à l’aide de la compression delta. Les objets sont d’abord triés en interne par type, taille et optionnellement par noms et comparés aux autres objets dans --window pour voir si l’utilisation de compression de delta permet d’économiser de l’espace. --depth limite la profondeur maximale du delta ; la rendre trop profonde affecte la performance du côté du dépaqueteur, parce que les données de delta doivent être appliquées autant de fois pour arriver à l’objet nécessaire.
La valeur par défaut pour --window est 10 et --depth est 50. La profondeur maximale est de 4095.
- --window-memory=<n>
-
Cette option fournit une limite supplémentaire par dessus
--window
; la taille de la fenêtre s’étendra dynamiquement vers le bas afin de ne pas prendre plus que <n> octets en mémoire. Ceci est utile dans les dépôts avec un mélange de grands et petits objets afin de ne pas manquer de mémoire avec une grande fenêtre, mais encore être en mesure de profiter de la grande fenêtre pour les petits objets. La taille peut être suffixée par "k", "m", ou "g".--window-memory=0
rend l’utilisation de la mémoire illimitée. La valeur par défaut est tirée de la variable de configurationpack.windowMemory
. - --max-pack-size=<n>
-
Dans des scénarios inhabituels, il se peut que vous ne puissiez pas créer des fichiers plus grands qu’une certaine taille sur votre système de fichiers, et cette option peut être utilisée pour dire à la commande de diviser le fichier de sortie en plusieurs paquets indépendants, chacun pas plus grand que la taille donnée. La taille peut être suffixée avec "k", "m", ou "g". La taille minimale autorisée est limitée à 1 MiB. La valeur par défaut est illimitée, sauf si la variable config
pack.packSizeLimit
est définie. Notez que cette option peut entraîner un dépôt plus gros et plus lent ; voir la discussion danspack.packSizeLimit
. - --honor-pack-keep
-
Ce drapeau fait ignorer un objet déjà dans un paquet local qui a un fichier .keep, même si il aurait été empaqueté par ailleurs.
- --keep-pack=<nom-de-paquet>
-
Ce drapeau fait ignorer un objet déjà dans le paquet donné, même s’il aurait été empaqueté par ailleurs.
nom-de-paquet
est le nom du fichier paquet sans répertoire (par exemplepack-123.pack
). L’option peut être spécifiée plusieurs fois pour garder plusieurs paquets. - --incremental
-
This flag causes an object already in a pack to be ignored even if it would have otherwise been packed.
- --local
-
This flag causes an object that is borrowed from an alternate object store to be ignored even if it would have otherwise been packed.
- --non-empty
-
Only create a packed archive if it would contain at least one object.
- --progress
-
L’état d’avancement est affiché sur la sortie d’erreur standard quand elle est attachée à un terminal, à moins que -q soit spécifié. Ce drapeau force l’état d’avancement même si le flux d’erreur standard n’est pas dirigé vers un terminal.
- --all-progress
-
Lorsque --stdout est spécifié, le rapport de progression est affiché pendant les phases de comptage d’objets et de compression, mais il est inhibé pendant la phase d’écriture. La raison en est que dans certains cas, le flux de sortie est directement lié à une autre commande qui peut souhaiter afficher son propre état d’avancement pendant qu’elle traite les données du paquet entrant. Ce drapeau est comme --progress sauf qu’il force le rapport de progression pour la phase d’écriture même si --stdout est utilisé.
- --all-progress-implied
-
C’est utilisé pour impliquer --all-progress lorsque l’affichage de la progression est activé. Contrairement à --all-progress, ce drapeau ne force pas l’affichage de la progression par lui-même.
- -q
-
Ce drapeau permet à la commande de ne pas signaler sa progression sur le flux d’erreur standard.
- --no-reuse-delta
-
When creating a packed archive in a repository that has existing packs, the command reuses existing deltas. This sometimes results in a slightly suboptimal pack. This flag tells the command not to reuse existing deltas but compute them from scratch.
- --no-reuse-object
-
Ce drapeau indique à la commande de ne pas réutiliser les données d’objet existantes, y compris l’objet non déltifié, forçant la recompression de tout. Cela implique --no-reuse-delta. Utile seulement dans le cas obscur où l’exécution en gros d’un niveau de compression différent sur les données emballées est souhaitée.
- --compression=<n>
-
Spécifie le niveau de compression pour les données nouvellement compressées dans le paquet généré. Si ce n’est pas spécifié, le niveau de compression des paquets est déterminé en premier par pack. compression, puis par core.compression, et par défaut à -1, la valeur par défaut de zlib, si non defini. Ajoutez --no-reuse-object si vous voulez forcer un niveau de compression uniforme sur toutes les données, peu importe la source.
- --[no-]sparse
-
Activer l’algorithme "sparse" pour déterminer quels objets inclure dans le paquet, lorsqu’il est combiné avec l’option "-revs". Cet algorithme ne parcourt que les arbres qui apparaissent dans les chemins qui introduisent de nouveaux objets. Cela peut avoir d’importants avantages de performance lors du calcul d’un paquet pour envoyer une petite modification. Cependant, il est possible que des objets supplémentaires soient ajoutés au fichier de paquet si les commits inclus contiennent certains types de renommages directs. Si cette option n’est pas incluse, elle prend par défaut la valeur de
pack.useSparse
, ce qui est vrai sauf indication contraire. - --thin
-
Créer un paquet "fin" en omettant les objets communs entre un expéditeur et un récepteur afin de réduire le transfert sur le réseau. Cette option n’a de sens qu’avec --stdout.
Note : Un paquet mince viole le format d’archive empaquetée en omettant les objets requis et est donc inutilisable par Git sans le rendre autonome. Utilisez
git index-pack --fix-thin
(voir git-index-pack[1]) pour restaurer la propriété autonome. - --shallow
-
Optimiser un paquet qui sera fourni à un client avec un dépôt superficiel. Cette option, combinée avec --thin, peut générer un paquet plus petit au prix de quelques lenteurs.
- --delta-base-offset
-
A packed archive can express the base object of a delta as either a 20-byte object name or as an offset in the stream, but ancient versions of Git don’t understand the latter. By default, git pack-objects only uses the former format for better compatibility. This option allows the command to use the latter format for compactness. Depending on the average delta chain length, this option typically shrinks the resulting packfile by 3-5 per-cent.
Note : Les commandes de porcelaine comme
git gc
(voir git-gc[1]),git repack
(voir git-repack[1]) passent cette option par défaut dans le Git moderne quand ils mettent des objets dans votre dépôt dans des fichiers paquets. Ainsi faitgit bundle
(voir git-bundle[1]) quand il crée un colis. - --threads=<n>
-
Spécifie le nombre de fils d’exécution à démarrer lors de la recherche de meilleures correspondances de delta. Cela exige que
pack-object
soit compilé avec pthreads sinon cette option est ignorée avec un avertissement. Ceci est destiné à réduire le temps d’empaquetage sur les machines multiprocesseurs. La quantité requise de mémoire pour la fenêtre de recherche de delta est cependant multipliée par le nombre de fils. La spécification de 0 provoquera l’auto-détection par Git du nombre de CPU et la définition du nombre de fils en conséquence. - --index-version=<version>[,<décalage>]
-
Ceci est destiné à être utilisée uniquement par la suite de tests. Permet de forcer la version de l’index de paquet généré, et de forcer les entrées d’index 64 bits sur les objets situés avant le décalage donné.
- --keep-true-parents
-
Avec cette option, les parents qui sont cachés par des greffes sont néanmoins empaquetées.
- --filter=<spéc. du filtre>
-
Omits certain objects (usually blobs) from the resulting packfile. See git-rev-list[1] for valid
<filter-spec>
forms. - --no-filter
-
Désactive tout argument
--filter=
précédent. - --missing=<action-manquante>
-
Une option de débogage pour aider au développement futur de "clones partiels". Cette option spécifie comment les objets manquants sont traités.
La forme --missing=error demande que pack-objects s’arrête avec une erreur si un objet manquant est rencontré. Si le dépôt est un clone partiel, une tentative de récupération des objets manquants sera effectuée avant de les déclarer manquants. C’est l’action par défaut.
La forme --missing=allow-any permet de continuer le parcours d’objet si un objet manquant est rencontré. Il n’y aura pas de récupération d’un objet manquant. Les objets manquants seront silencieusement omis des résultats.
Le forme --missing=allow-promisor est comme allow-any, mais ne permettra la traversée d’objets de continuer que pour les objets manquants du promettant EXPECTED. Il n’y aura pas de récupération d’un objet manquant. Les objets manquants inattendus entraîneront une erreur.
- --exclude-promisor-objects
-
Omit objects that are known to be in the promisor remote. (This option has the purpose of operating only on locally created objects, so that when we repack, we still maintain a distinction between locally created objects [without .promisor] and objects from the promisor remote [with .promisor].) This is used with partial clone.
- --keep-unreachable
-
Objects unreachable from the refs in packs named with --unpacked= option are added to the resulting pack, in addition to the reachable objects that are not in packs marked with *.keep files. This implies
--revs
. - --pack-loose-unreachable
-
Empaqueter les objets seuls inaccessibles (et leurs homologues seuls enlevés). Cela implique
--revs
. - --unpack-unreachable
-
Garder les objets inaccessibles sous forme libre. Cela implique
--revs
. - --delta-islands
-
Restreindre les correspondances de delta basées sur des "îlots". Voir ÎLOTS DE DELTA ci-dessous.
ÎLOTS DE DELTA
Dans la mesure du possible, pack-object
tente de réutiliser les deltas existants sur disque pour éviter d’avoir à rechercher de nouveaux à la volée. C’est une optimisation importante dans le serveur lors des récupérations, parce que cela signifie que le serveur peut éviter de décompresser la plupart des objets et simplement envoyer les octets directement à partir du disque. Cette optimisation ne peut pas fonctionner quand un objet est stocké comme un delta contre une base que le récepteur n’a pas (et que nous n’envoyons pas déjà). Dans ce cas, le serveur « brise » le delta et doit en trouver un nouveau, ce qui a un coût CPU élevé. Par conséquent, il est important pour la performance que l’ensemble des objets dans les relations de delta sur disque correspondent à ce qu’un client allait récupérer.
Dans un dépôt normal, cela tend à fonctionner automatiquement. Les objets sont généralement accessibles depuis les branches et les étiquettes, et c’est ce que les clients récupèrent. Tous les deltas que nous trouvons sur le serveur sont susceptibles d’être entre des objets que le client a ou aura.
Mais dans certaines configurations de dépôt, vous pouvez avoir plusieurs groupes de sommets de réfs connexes mais séparés, avec des clients qui ont tendance à récupérer ces groupes indépendamment. Par exemple, imaginez que vous hébergez plusieurs « bifurcations » d’un dépôt dans un seul dépôt d’objets partagés, et que les clients les considèrent comme des dépôts séparés via GIT_NAMESPACE
ou des dépôts séparés à l’aide d’un autre mécanisme. Un ré-empaquetage naïf peut trouver que le delta optimal pour un objet est contre une base qui se trouve seulement dans une autre bifurcations. Mais quand un client récupère, il n’aura pas l’objet de base, et il faudra trouver un nouveau delta à la volée.
A similar situation may exist if you have many refs outside of refs/heads/
and refs/tags/
that point to related objects (e.g., refs/pull
or refs/changes
used by some hosting providers). By default, clients fetch only heads and tags, and deltas against objects found only in those other groups cannot be sent as-is.
Delta islands solve this problem by allowing you to group your refs into distinct "islands". Pack-objects computes which objects are reachable from which islands, and refuses to make a delta from an object A
against a base which is not present in all of A
's islands. This results in slightly larger packs (because we miss some delta opportunities), but guarantees that a fetch of one island will not have to recompute deltas on the fly due to crossing island boundaries.
When repacking with delta islands the delta window tends to get clogged with candidates that are forbidden by the config. Repacking with a big --window helps (and doesn’t take as long as it otherwise might because we can reject some object pairs based on islands before doing any computation on the content).
Islands are configured via the pack.island
option, which can be specified multiple times. Each value is a left-anchored regular expressions matching refnames. For example:
[pack] island = refs/heads/ island = refs/tags/
puts heads and tags into an island (whose name is the empty string; see below for more on naming). Any refs which do not match those regular expressions (e.g., refs/pull/123
) is not in any island. Any object which is reachable only from refs/pull/
(but not heads or tags) is therefore not a candidate to be used as a base for refs/heads/
.
Refs are grouped into islands based on their "names", and two regexes that produce the same name are considered to be in the same island. The names are computed from the regexes by concatenating any capture groups from the regex, with a - dash in between. (And if there are no capture groups, then the name is the empty string, as in the above example.) This allows you to create arbitrary numbers of islands. Only up to 14 such capture groups are supported though.
Par exemple, imaginez que vous stockez les réfs pour chaque bifurcation dans refs/virtual/ID
, où ID
est un identifiant numérique. Vous pouvez alors configurer :
[pack] island = refs/virtual/([0-9]+)/heads/ island = refs/virtual/([0-9]+)/tags/ island = refs/virtual/([0-9]+)/(pull)/
Cela met les têtes et les étiquettes pour chaque bifurcation dans leur propre îlot (nommée "1234" ou similaire), et les réfs à tirer pour chaque invocation dans leur propre "1234-pull".
Notez que nous choisissons un îlot unique pour y loger chaque regex, en utilisant le classement "le dernier gagne"(qui permet à la configuration par-dépôt de prendre la priorité sur la configuration au niveau utilisateur, et ainsi de suite).
CONFIGURATION
Diverses variables de configuration affectent l’empaquetage, voir git-config[1] (recherchez "paquet" et "delta").
En particulier, la compression de delta n’est pas utilisée sur des objets plus grands que la variable de configuration core.bigFileThreshold
et sur des fichiers avec l’attribut `delta ` réglé à false.
GIT
Fait partie de la suite git[1]
TRADUCTION
Cette page de manuel a été traduite par Jean-Noël Avila <jn.avila AT free DOT fr> et les membres du projet git-manpages-l10n. Veuillez signaler toute erreur de traduction par un rapport de bogue sur le site https://github.com/jnavila/git-manpages-l10n .