git-unpack-objects

git unpack-objects [--strict] [-n] [-q] [-r] [--unpack-grafted] [--] < pack-file

-n, --dry-run
    Do not unpack objects. Instead, only verify the integrity of the pack file by checking checksums and object sizes. This can be used to validate a pack before committing to unpacking.

-q, --quiet
    Do not report details of unpacked objects to standard output. By default, the command may list the names of objects it unpacks.

-r, --recursive
    Unpack objects recursively. This option implies --strict and is often used internally when a pack might contain references to other objects that need unpacking or further processing.

--strict
    Abort if any errors are encountered during the unpacking process, such as checksum mismatches or corrupted object data. This ensures stricter error checking and prevents unpacking potentially corrupted or malicious objects into the repository.

--unpack-grafted
    Unpack objects that are referred to by graft points. This is relevant when the core.unpackedGrafts configuration option is enabled, allowing grafts to be handled during the unpack process.

The git-unpack-objects command is a low-level plumbing command in Git. Its primary function is to read a packed archive (a .pack file) from standard input, and then extract and store the objects (commits, trees, blobs, tags) contained within this pack file into the local Git object database. This process makes the objects accessible and usable by the repository.

This command is typically used internally by other higher-level Git operations, such as git-fetch-pack (when fetching or pulling changes from a remote repository), git-receive-pack (when receiving pushed commits), or git-index-pack (which creates an index for a pack and then can unpack it). While it can verify the integrity of the pack file by checking checksums, it is not generally invoked directly by end-users. It serves as a crucial component for the efficient storage, transfer, and management of Git objects.

This command is considered a plumbing command and is not intended for direct use by end-users. It should only be invoked by higher-level Git commands or trusted scripts. Care should be taken when unpacking objects from untrusted sources without the --strict option, as Git's object model, while robust, relies on the integrity of the pack file for security and consistency.

The command expects the packed archive (.pack file) data to be provided via standard input.

The command exits with status 0 on success, indicating that the objects were unpacked or verified without critical errors. It exits with a non-zero status if an error occurs during unpacking or verification (e.g., corrupted pack file, I/O errors).

The git-unpack-objects command has been a fundamental component of Git's object storage and network protocols since the early days of Git. As Git relies heavily on efficient packing and unpacking of objects for both storage optimization and network transfer, this command's core functionality has remained essential and largely unchanged, reflecting its foundational role in Git's internal architecture.

git-pack-objects(1), git-index-pack(1), git-fetch-pack(1), git-receive-pack(1)