GitDB2

4.0.12 · active · verified Sun Apr 12

gitdb2 is a 'mirror package' that provides the `gitdb` library, which implements a pure-Python object database for Git. It handles the storage and retrieval of Git objects (blobs, trees, commits, tags) and is a core dependency for libraries like `GitPython`. The current version is 4.0.12, with releases driven primarily by `GitPython`'s needs and Python version compatibility.

Warnings

gotcha The `gitdb2` PyPI package provides the `gitdb` Python package namespace. When importing symbols, always use `from gitdb import ...` instead of `from gitdb2 import ...`.
Fix: Always use `import gitdb` or `from gitdb import ClassName` for all functionality.
breaking Python version support changes: `gitdb2` regularly drops support for End-of-Life (EOL) Python versions and adds support for newer ones. For example, version 4.0.11 dropped Python 3.7 and added 3.12.
Fix: Ensure your project's Python interpreter version matches the requirements of the `gitdb2` version you are using. Upgrade `gitdb2` to the latest version for Python 3.8+.
gotcha `gitdb2` is primarily an internal dependency for `GitPython` and other Git-related libraries. While it can be used directly, its API might not be as user-friendly or stable for general application development compared to its role as a library component.
Fix: If you need Git functionality, consider using `GitPython` which builds upon `gitdb` and provides a higher-level API. Only use `gitdb` directly if you require low-level Git object database interaction.
gotcha `gitdb` has a hard dependency on `smmap>=5.0.0`. Conflicts can arise if other libraries in your environment require an older or incompatible version of `smmap`.
Fix: Use a virtual environment to isolate dependencies. If conflicts persist, check the dependency tree of your project for other libraries requiring `smmap` and try to align their versions, or consider alternative solutions.

Install

pip install gitdb2 Install gitdb2

Imports

GitDB
```
from gitdb import GitDB
```
The `gitdb2` package provides the `gitdb` namespace. Direct imports should always be from `gitdb`, not `gitdb2`.
IStream
```
from gitdb import IStream
```
The `gitdb2` package provides the `gitdb` namespace. Direct imports should always be from `gitdb`, not `gitdb2`.

Quickstart

This quickstart demonstrates how to initialize a `GitDB` instance, store a 'blob' object, and then retrieve it using its SHA1 hash. It utilizes `tempfile` for creating a temporary database location.

import tempfile
import os
import hashlib
from gitdb import GitDB, IStream

# Create a temporary directory for the GitDB
with tempfile.TemporaryDirectory() as temp_dir:
    # GitDB expects an 'objects' directory within its base path
    db_path = os.path.join(temp_dir, 'objects')
    os.makedirs(db_path) # Ensure the 'objects' directory exists

    # Initialize GitDB
    db = GitDB(db_path)
    print(f"GitDB initialized at: {db_path}")

    # Create some dummy content for a Git 'blob' object
    content = b"Hello, GitDB! This is a test blob.\n"
    size = len(content)
    object_type = b"blob"

    # Git objects are stored as: type + space + size + null byte + content
    header = object_type + b" " + str(size).encode('ascii') + b"\0"
    stored_data = header + content
    sha1 = hashlib.sha1(stored_data).hexdigest()

    # Create an IStream object for input
    # IStream takes type (bytes), size (int), and data (bytes)
    istream = IStream(object_type, size, content)

    # Store the object in the GitDB
    # The put method returns an object with the hexsha attribute
    stored_sha = db.put(istream).hexsha
    print(f"Stored object with SHA1: {stored_sha}")

    # Verify the SHA1 matches our expectation
    print(f"Expected SHA1: {sha1}")
    assert stored_sha == sha1

    # Retrieve the object using its SHA1 hash
    retrieved_istream = db.get(stored_sha)
    retrieved_content = retrieved_istream.read()

    print(f"Retrieved content type: {retrieved_istream.type.decode()}")
    print(f"Retrieved content size: {retrieved_istream.size}")
    print(f"Retrieved content: {retrieved_content.decode().strip()}")

    # Assert retrieved data matches original
    assert retrieved_istream.type == object_type
    assert retrieved_istream.size == size
    assert retrieved_content == content

    print("Object stored and retrieved successfully.")

view raw JSON →