GitPython Documentation

GitDB provides interfaces for read and write access to git repositories. The core db package contains several database types that are combined into a single GitDB instance to represent a complete repository:

• LooseObjectDB: Handles loose object reading and writing.
• PackedDB: Implements pack reading.
• ReferenceDB: Handles git references.
• GitDB: The combined database type that integrates the above components.

Data is handled using streams, ensuring that large files can be processed efficiently by only keeping chunks of the stream in memory.

GitDB uses streams for all data retrieval and storage to maintain low memory usage. There are two primary stream types:

• IStreams: Mutable streams used to provide data to the database for creating new objects. They are implemented as lists.
• OStreams: Immutable streams used to read data from the database. They are implemented as tuples.

Additionally, OInfo contains only the type and size information of a queried object without the actual stream data. Because OInfo and OStream share the same member ordering, they can be converted between each other quickly.

If you are contributing to the project, use the following commands to ensure code quality:

Run Tests

Ensure test dependencies are installed (pip install -e ".[test]"), then run:

pytest

Lint and Format

To run linters and apply automatic code formatting (including Ruff):

pre-commit run --all-files

Typecheck

To run type checking with mypy:

mypy

For applications handling large amounts of data on both 32-bit and 64-bit platforms, use smmap.SlidingWindowMapManager. This manager uses 'sliding windows' to map relatively small regions of a file into memory at a time, rather than mapping the entire file. It is recommended to maintain a single instance of the manager globally throughout your application. You can query the manager for its current state, such as the number of open file handles or the total amount of mapped memory.

import smmap
# This instance should be globally available in your application
mman = smmap.SlidingWindowMapManager()

# Query manager state
mman.num_file_handles()
mman.mapped_memory_size()

The easiest way to install GitDB is using the pip package manager. Note that you may require root permissions depending on your Python distribution.

$ pip install gitdb

To achieve up to 20% faster performance, you can install the gitdb-speedups package.

Note: gitdb-speedups is not currently maintained.

pip install gitdb-speedups

You can install smmap using pip or by running the setup.py script from a downloaded source archive. Note that you may require root permissions for these installations.

Using pip

pip install smmap

Using source

python setup.py install