Registry / data / gitdb2

gitdb2

JSON →
library4.0.2pypypi✓ verified 23d ago

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.

pip install gitdb2
INSTALL
IMPORT
SIG · GITDB2
G
gitdb2
datapythonv4.0.2
Install
1.6s avg
Import
30ms
Disk
16MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v4.0.2 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.95 runs
installs and imports cleanly · install 0.0s · import 0.032s · 18.4MB
glibc
py 3.103.95 runs
installs and imports cleanly · install 1.6s · import 0.028s · 19MB
16MB installed
● package 16MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

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

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.")
Debug
Known issues
gotchaThe `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.
affects: All versions of gitdb2
breakingPython 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+.
affects: 4.0.11 and later (for Python 3.7 removal); check release notes for specific version compatibility.
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.
affects: All versions
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.
affects: All versions requiring `smmap>=5.0.0`
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'gitdb.utils.compat'
This error occurs due to an incompatibility between GitPython and gitdb/gitdb2 versions, where GitPython expects the `gitdb.utils.compat` module which was removed in newer gitdb releases, particularly during the transition from gitdb 2.x to 3.x/4.x.
fix
Ensure compatible versions of GitPython and gitdb/gitdb2 are installed. For older setups experiencing this, explicitly pin `gitdb2` and `gitdb` to known compatible versions, such as `pip install --upgrade gitdb2==2.0.6 gitdb==0.6.4`, or ensure your GitPython is up-to-date to a version that handles newer gitdb structures.
ImportError: No module named 'gitdb'
This issue arises from the historical naming confusion between the `gitdb` and `gitdb2` PyPI packages. While `gitdb2` is designed to provide the `gitdb` module, an incomplete installation, conflicting installations of both packages, or an environment where `gitdb2` is installed but `gitdb` is missing can lead to this import error.
fix
Ensure `gitdb2` (which provides `gitdb`) is correctly installed. If issues persist, try uninstalling both `gitdb` and `gitdb2` and then reinstalling `gitdb2` (e.g., `pip uninstall gitdb gitdb2 && pip install gitdb2`). If a downstream dependency like `GitPython` is involved, ensure it's also updated or reinstalled to pull the correct `gitdb` dependency.
gitdb2 requires python '>=3.4'
You are attempting to install or use gitdb2 (version 4.0.12) in a Python environment running a version older than 3.4, which does not meet the package's minimum Python version requirement.
fix
Upgrade your Python environment to version 3.4 or higher to meet gitdb2's compatibility requirements.
ValueError: SHA could not be resolved, git returned: b''
This error typically occurs when GitPython (which relies on gitdb for object database interaction) attempts to read a Git object (like a commit) from a repository, but the underlying Git command fails to resolve the SHA-1 hash, often returning an empty byte string. This can indicate repository corruption, malformed Git objects, or an issue with the Git executable itself.
fix
First, verify the integrity of your Git repository using `git fsck`. If the repository is sound, ensure that your Git executable is correctly installed and accessible in the system's PATH. Finally, confirm that GitPython and gitdb2 are updated to their latest compatible versions to rule out software bugs.
Upgrade
Version history
4.0.2latest on PyPI · released Feb 23, 2020
Audit
Dependencies
smmaprequiredProvides memory mapping utilities used by gitdb for efficient object storage and retrieval.
Agent activity
5 hits · last 30 days
node
4
Resources
gitdb2 — pip install gitdb2 · libregistry