from gitpandas import Repository
# Create a repository instance
repo = Repository('/path/to/repo')
# Get commit history with filtering
commits_df = repo.commit_history(


    branch='main',


    ignore_globs=['*.pyc'],


    include_globs=['*.py']
)
# Analyze blame information
blame_df = repo.blame(by='repository')
# Calculate bus factor
bus_factor_df = repo.bus_factor()

from gitpandas import ProjectDirectory
project = ProjectDirectory('/path/to/project')

from gitpandas import Repository
repo = Repository(


    working_dir='/path/to/repo/',


    verbose=True,


    default_branch='main'  # Optional, will auto-detect if not specified
)

from gitpandas import Repository
repo = Repository(


    working_dir='git://github.com/user/repo.git',


    verbose=True,


    default_branch='main'  # Optional, will auto-detect if not specified
)

# Commit history analysis
repo.commit_history(


    branch=None,          # Branch to analyze


    limit=None,           # Maximum number of commits


    days=None,           # Limit to last N days


    ignore_globs=None,   # Files to ignore


    include_globs=None   # Files to include
)
# File change history
repo.file_change_history(


    branch=None,


    limit=None,


    days=None,


    ignore_globs=None,


    include_globs=None
)
# Blame analysis
repo.blame(


    rev="HEAD",          # Revision to analyze


    committer=True,      # Group by committer (False for author)


    by="repository",     # Group by 'repository' or 'file'


    ignore_globs=None,


    include_globs=None
)
# Bus factor analysis
repo.bus_factor(


    by="repository",     # How to group results ('repository' or 'file')


    ignore_globs=None,


    include_globs=None
)
# Commit pattern analysis
repo.punchcard(


    branch=None,


    limit=None,


    days=None,


    by=None,            # Additional grouping


    normalize=None,     # Normalize values


    ignore_globs=None,


    include_globs=None
)

# List files in repository
repo.list_files(rev="HEAD")
# Check branch existence
repo.has_branch(branch)
# Check if repository is bare
repo.is_bare()
# Check for coverage information
repo.has_coverage()
repo.coverage()
# Get specific commit content
repo.get_commit_content(


    rev,                # Revision to analyze


    ignore_globs=None,


    include_globs=None
)

Args:

verbose (bool, optional): Whether to print verbose output. Defaults to False. tmp_dir (Optional[str]): Directory to clone remote repositories into. Created if not provided. cache_backend (Optional[object]): Cache backend instance from gitpandas.cache labels_to_add (Optional[List[str]]): Extra labels to add to output DataFrames default_branch (Optional[str]): Name of the default branch to use. If None, will try to detect

Attributes:

verbose (bool): Whether verbose output is enabled git_dir (str): Path to the git repository repo (git.Repo): GitPython Repo instance cache_backend (Optional[object]): Cache backend being used _labels_to_add (List[str]): Labels to add to DataFrames _git_repo_name (Optional[str]): Repository name for remote repos default_branch (str): Name of the default branch

Raises:

ValueError: If default_branch is None and neither 'main' nor 'master' branch exists

Examples:

>>> # Create from local repository
>>> repo = Repository('/path/to/repo')
    

>>> # Create from remote repository
>>> repo = Repository('git://github.com/user/repo.git')
    

Note:

When using remote repositories, they will be cloned to temporary directories. This can be slow for large repositories.

__init__(working_dir=None, verbose=False, tmp_dir=None, cache_backend=None, labels_to_add=None, default_branch=None)

Initialize a Repository instance.

is_bare(*args, **kwargs)

has_coverage(*args, **kwargs)

coverage(*args, **kwargs)

hours_estimate(*args, **kwargs)

commit_history(*args, **kwargs)

file_change_history(*args, **kwargs)

file_change_rates(*args, **kwargs)

blame(*args, **kwargs)

revs(*args, **kwargs)

cumulative_blame(*args, **kwargs)

parallel_cumulative_blame(*args, **kwargs)

branches(*args, **kwargs)

get_branches_by_commit(*args, **kwargs)

commits_in_tags(*args, **kwargs)

tags(*args, **kwargs)

property repo_name

__str__()

Returns a human-readable string representation of the repository.

get_commit_content(*args, **kwargs)

get_file_content(*args, **kwargs)

list_files(*args, **kwargs)

__repr__()

Returns a unique string representation of the repository.

bus_factor(*args, **kwargs)

file_owner(*args, **kwargs)

punchcard(*args, **kwargs)

has_branch(*args, **kwargs)

file_detail(*args, **kwargs)

time_between_revs(rev1, rev2)

Calculates the time difference in days between two revisions.

diff_stats_between_revs(rev1, rev2, ignore_globs=None, include_globs=None)

Computes diff statistics between two revisions.

Calculates the total insertions, deletions, net line change, and number of files changed between two arbitrary revisions (commits or tags). Optionally filters files using glob patterns.

committers_between_revs(rev1, rev2, ignore_globs=None, include_globs=None)

Finds unique committers and authors between two revisions.

Iterates through all commits between two revisions (exclusive of rev1, inclusive of rev2) and returns the unique committers and authors who contributed, filtered by file globs if provided.

files_changed_between_revs(rev1, rev2, ignore_globs=None, include_globs=None)

Lists files changed between two revisions.

Returns a sorted list of all files changed between two arbitrary revisions (commits or tags), optionally filtered by glob patterns.

release_tag_summary(*args, **kwargs)

safe_fetch_remote(remote_name='origin', prune=False, dry_run=False)

Safely fetch changes from remote repository.

Fetches the latest changes from a remote repository without modifying the working directory. This is a read-only operation that only updates remote-tracking branches.

warm_cache(methods=None, **kwargs)

Pre-populate cache with commonly used data.

Executes a set of commonly used repository analysis methods to populate the cache, improving performance for subsequent calls. Only methods that support caching will be executed.

invalidate_cache(keys=None, pattern=None)

Invalidate specific cache entries or all cache entries for this repository.

get_cache_stats()

Get cache statistics for this repository.

blame(*args, **kwargs)

branches(*args, **kwargs)

bus_factor(*args, **kwargs)

commit_history(*args, **kwargs)

commits_in_tags(*args, **kwargs)

committers_between_revs(rev1, rev2, ignore_globs=None, include_globs=None)

Finds unique committers and authors between two revisions.

Iterates through all commits between two revisions (exclusive of rev1, inclusive of rev2) and returns the unique committers and authors who contributed, filtered by file globs if provided.

coverage(*args, **kwargs)

cumulative_blame(*args, **kwargs)

diff_stats_between_revs(rev1, rev2, ignore_globs=None, include_globs=None)

Computes diff statistics between two revisions.

Calculates the total insertions, deletions, net line change, and number of files changed between two arbitrary revisions (commits or tags). Optionally filters files using glob patterns.

file_change_history(*args, **kwargs)

file_change_rates(*args, **kwargs)

file_detail(*args, **kwargs)

file_owner(*args, **kwargs)

files_changed_between_revs(rev1, rev2, ignore_globs=None, include_globs=None)

Lists files changed between two revisions.

Returns a sorted list of all files changed between two arbitrary revisions (commits or tags), optionally filtered by glob patterns.

get_branches_by_commit(*args, **kwargs)

get_cache_stats()

Get cache statistics for this repository.

get_commit_content(*args, **kwargs)

get_file_content(*args, **kwargs)

has_branch(*args, **kwargs)

has_coverage(*args, **kwargs)

hours_estimate(*args, **kwargs)

invalidate_cache(keys=None, pattern=None)

Invalidate specific cache entries or all cache entries for this repository.

is_bare(*args, **kwargs)

list_files(*args, **kwargs)

parallel_cumulative_blame(*args, **kwargs)

punchcard(*args, **kwargs)

release_tag_summary(*args, **kwargs)

property repo_name

revs(*args, **kwargs)

safe_fetch_remote(remote_name='origin', prune=False, dry_run=False)

Safely fetch changes from remote repository.

Fetches the latest changes from a remote repository without modifying the working directory. This is a read-only operation that only updates remote-tracking branches.

tags(*args, **kwargs)

time_between_revs(rev1, rev2)

Calculates the time difference in days between two revisions.

warm_cache(methods=None, **kwargs)

Pre-populate cache with commonly used data.

Executes a set of commonly used repository analysis methods to populate the cache, improving performance for subsequent calls. Only methods that support caching will be executed.

__init__()

Initialize a Repository instance.

from gitpandas import ProjectDirectory
project = ProjectDirectory(


    working_dir='/path/to/dir/',


    ignore_repos=['repo_to_ignore'],


    verbose=True,


    default_branch='main'  # Optional, will auto-detect if not specified
)

from gitpandas import ProjectDirectory
project = ProjectDirectory(


    working_dir=['/path/to/repo1/', '/path/to/repo2/'],


    ignore_repos=['repo_to_ignore'],


    verbose=True,


    default_branch='main'  # Optional, will auto-detect if not specified
)

from gitpandas import ProjectDirectory
project = ProjectDirectory(


    working_dir=['git://github.com/user/repo1.git', 'git://github.com/user/repo2.git'],


    ignore_repos=['repo_to_ignore'],


    verbose=True,


    default_branch='main'  # Optional, will auto-detect if not specified
)

# Commit history across repositories
project.commit_history(


    branch=None,          # Branch to analyze


    limit=None,           # Maximum number of commits


    days=None,           # Limit to last N days


    ignore_globs=None,   # Files to ignore


    include_globs=None   # Files to include
)
# File change history across repositories
project.file_change_history(


    branch=None,


    limit=None,


    days=None,


    ignore_globs=None,


    include_globs=None
)
# Blame analysis across repositories
project.blame(


    rev="HEAD",          # Revision to analyze


    committer=True,      # Group by committer (False for author)


    by="repository",     # Group by 'repository' or 'file'


    ignore_globs=None,


    include_globs=None
)
# Bus factor analysis across repositories
project.bus_factor(


    by="repository",     # How to group results ('projectd', 'repository', or 'file')


    ignore_globs=None,


    include_globs=None
)

Args:

ignore_repos (Optional[List[str]]): List of repository names to ignore verbose (bool, optional): Whether to print verbose output. Defaults to True. tmp_dir (Optional[str]): Directory to clone remote repositories into. Created if not provided. cache_backend (Optional[object]): Cache backend instance from gitpandas.cache default_branch (str, optional): Name of the default branch to use. Defaults to 'main'.

Attributes:

repo_dirs (Union[set, list]): Set of repository directories or list of Repository instances repos (List[Repository]): List of Repository objects being analyzed

Examples:

>>> # Create from directory containing repos
>>> pd = ProjectDirectory(working_dir='/path/to/repos')
    

>>> # Create from explicit local repos
>>> pd = ProjectDirectory(working_dir=['/path/to/repo1', '/path/to/repo2'])
    

>>> # Create from remote repos
>>> pd = ProjectDirectory(working_dir=['git://github.com/user/repo.git'])
    

Note:

When using remote repositories, they will be cloned to temporary directories. This can be slow for large repositories.

__init__(working_dir=None, ignore_repos=None, verbose=True, tmp_dir=None, cache_backend=None, default_branch='main')

Initialize a ProjectDirectory instance.

repo_name()

Returns a DataFrame containing the names of all repositories in the project.

is_bare()

Returns a dataframe of repo names and whether or not they are bare.

has_coverage()

Returns a DataFrame of repo names and whether or not they have a .coverage file that can be parsed

coverage()

Will return a DataFrame with coverage information (if available) for each repo in the project).

If there is a .coverage file available, this will attempt to form a DataFrame with that information in it, which will contain the columns:

If it can't be found or parsed, an empty DataFrame of that form will be returned.

file_change_rates(branch=None, limit=None, coverage=False, days=None, ignore_globs=None, include_globs=None)

Will return a DataFrame containing some basic aggregations of the file change history data, and optionally test coverage data from a coverage_data.py .coverage file. The aim here is to identify files in the project which have abnormal edit rates, or the rate of changes without growing the files size. If a file has a high change rate and poor test coverage, then it is a great candidate for writing more tests.

hours_estimate(branch=None, grouping_window=0.5, single_commit_hours=0.5, limit=None, days=None, committer=True, by=None, ignore_globs=None, include_globs=None)

Returns a DataFrame containing the estimated hours spent by each committer/author.

commit_history(branch=None, limit=None, days=None, ignore_globs=None, include_globs=None)

Returns a DataFrame containing the commit history for all repositories.

file_change_history(branch=None, limit=None, days=None, ignore_globs=None, include_globs=None)

Returns a DataFrame containing the file change history for all repositories.

blame(committer=True, by='repository', ignore_globs=None, include_globs=None)

Analyzes blame information across all repositories.

Retrieves blame information from the current HEAD of each repository and aggregates it based on the specified grouping. Can group results by committer/author and either repository or file.

file_detail(rev='HEAD', committer=True, ignore_globs=None, include_globs=None)

Provides detailed information about all files in the repositories.

Analyzes each file in the repositories at the specified revision, gathering information about size, ownership, and last modification.

branches()

Returns information about all branches across repositories.

Retrieves a list of all branches (both local and remote) from each repository in the project directory.

revs(branch=None, limit=None, skip=None, num_datapoints=None)

Returns a DataFrame containing revision information for all repositories.

cumulative_blame(branch=None, by='committer', limit=None, skip=None, num_datapoints=None, committer=True, ignore_globs=None, include_globs=None)

Returns a DataFrame containing cumulative blame information for all repositories.

commits_in_tags(**kwargs)

Analyze each tag, and trace backwards from the tag to all commits that make up that tag. This method looks at the commit for the tag, and then works backwards to that commits parents, and so on and so, until it hits another tag, is out of the time range, or hits the root commit. It returns a DataFrame with the branches:

tags()

Returns a data frame of all tags in origin. The DataFrame will have the columns:

repo_information()

Returns detailed metadata about each repository.

Retrieves various properties and references from each repository's Git object model.

bus_factor(ignore_globs=None, include_globs=None, by='projectd')

Calculates the "bus factor" for the repositories.

The bus factor is a measure of risk based on how concentrated the codebase knowledge is among contributors. It is calculated as the minimum number of contributors whose combined contributions account for at least 50% of the codebase's lines of code.

punchcard(branch=None, limit=None, days=None, by=None, normalize=None, ignore_globs=None, include_globs=None)

Returns a DataFrame containing punchcard data for all repositories.

bulk_fetch_and_warm(fetch_remote=False, warm_cache=False, parallel=True, remote_name='origin', prune=False, dry_run=False, cache_methods=None, **kwargs)

Safely fetch remote changes and pre-warm cache for all repositories.

Performs bulk operations across all repositories in the project directory, optionally fetching from remote repositories and pre-warming caches to improve subsequent analysis performance.

**

invalidate_cache(keys=None, pattern=None, repositories=None)

Invalidate cache entries across multiple repositories.

get_cache_stats()

Get comprehensive cache statistics across all repositories.

from gitpandas import Repository
from gitpandas.cache import EphemeralCache
# Create an in-memory cache with default settings
cache = EphemeralCache()
# Or customize the cache size
cache = EphemeralCache(max_keys=500)
# Use the cache with a repository
repo = Repository('/path/to/repo', cache_backend=cache)

from gitpandas import Repository
from gitpandas.cache import DiskCache
# Create a disk cache
cache = DiskCache(filepath='/path/to/cache.gz', max_keys=1000)
# Use the cache with a repository
repo = Repository('/path/to/repo', cache_backend=cache)

from gitpandas import Repository
from gitpandas.cache import RedisDFCache
# Create a Redis cache with default settings
cache = RedisDFCache()
# Or customize Redis connection and cache settings
cache = RedisDFCache(


    host='localhost',


    port=6379,


    db=12,


    max_keys=1000,


    ttl=3600  # Cache entries expire after 1 hour
)
# Use the cache with a repository
repo = Repository('/path/to/repo', cache_backend=cache)

from gitpandas import Repository
from gitpandas.cache import EphemeralCache
# Create repository with cache
cache = EphemeralCache()
repo = Repository('/path/to/repo', cache_backend=cache)
# Populate cache with some operations
commit_history = repo.commit_history(limit=10)
file_list = repo.list_files()
# Check what's in the cache and when it was cached
cached_keys = cache.list_cached_keys()
for entry in cached_keys:


    print(f"Key: {entry['key']}")


    print(f"Cached at: {entry['cached_at']}")


    print(f"Age: {entry['age_seconds']:.1f} seconds")
# Get specific cache information
key = "commit_history_main_10_None_None_None_None"
info = cache.get_cache_info(key)
if info:


    print(f"Cache entry age: {info['age_minutes']:.2f} minutes")

from gitpandas.cache import multicache
@multicache(


    key_prefix="method_name",


    key_list=["param1", "param2"],


    skip_if=lambda x: x.get("param1") is None
)
def expensive_method(self, param1, param2):


    # Method implementation


    pass

While it's technically possible to share the same cache object across multiple Repository instances, we strongly recommend using separate cache instances for each repository for the following reasons:

from gitpandas import Repository
from gitpandas.cache import DiskCache
# Create separate cache instances for each repository
cache1 = DiskCache(filepath='repo1_cache.gz')
cache2 = DiskCache(filepath='repo2_cache.gz')
repo1 = Repository('/path/to/repo1', cache_backend=cache1)
repo2 = Repository('/path/to/repo2', cache_backend=cache2)

from gitpandas import Repository
from gitpandas.cache import EphemeralCache
# Shared cache (not recommended but supported)
shared_cache = EphemeralCache(max_keys=1000)
repo1 = Repository('/path/to/repo1', cache_backend=shared_cache)
repo2 = Repository('/path/to/repo2', cache_backend=shared_cache)
# Each repository gets separate cache entries
files1 = repo1.list_files()  # Creates cache key: list_files||repo1||None
files2 = repo2.list_files()  # Creates cache key: list_files||repo2||None

# Small repositories (< 1000 commits)
cache = EphemeralCache(max_keys=100)
# Medium repositories (1000-10000 commits)
cache = EphemeralCache(max_keys=500)
# Large repositories (> 10000 commits)
cache = EphemeralCache(max_keys=1000)
# For disk/Redis caches, you can use larger sizes
cache = DiskCache(filepath='cache.gz', max_keys=5000)

__init__(filepath, max_keys=1000)

Initializes the cache. Tries to load from the specified filepath if it exists.

set(k, v)

Thread-safe set operation that prevents nested save calls.

get(k)

Thread-safe get operation with disk loading capability.

exists(k)

Thread-safe exists check.

evict(n=1)

Thread-safe eviction.

load()

Loads the cache state (_cache dictionary and _key_list) from the specified filepath using pickle. Handles file not found and deserialization errors. Thread-safe operation.

save()

Saves the current cache state (_cache dictionary and _key_list) to the specified filepath using pickle. Creates parent directories if needed. Thread-safe operation.

get_cache_info(k)

Get cache entry metadata for a key.

get_cache_stats()

Get comprehensive cache statistics.

invalidate_cache(keys=None, pattern=None)

Invalidate specific cache entries or all entries.

list_cached_keys()

List all cached keys with their metadata.

Parameters

__init__(host='localhost', port=6379, db=12, max_keys=1000, ttl=None, **kwargs)

evict(n=1)

set(orik, v)

get(orik)

exists(k)

sync()

Syncs the key list with what is in redis. :return: None

get_cache_info(orik)

Get cache entry metadata for a key.

list_cached_keys()

List all cached keys with their metadata.

invalidate_cache(keys=None, pattern=None)

Invalidate specific cache entries or all entries.

get_cache_stats()

Get comprehensive cache statistics.

purge()

Args:

key_prefix (str): Prefix for the cache key. key_list (list[str]): List of argument names (from kwargs) to include in the cache key. skip_if (callable, optional): A function that takes kwargs and returns True

__init__(data, cache_key=None)

to_dict()

Convert to dictionary for serialization.

classmethod from_dict(d)

Create CacheEntry from dictionary.

age_seconds()

Return age of cache entry in seconds.

age_minutes()

Return age of cache entry in minutes.

age_hours()

Return age of cache entry in hours.

Args:

remote_name (str, optional): Name of remote to fetch from. Defaults to 'origin'. prune (bool, optional): Remove remote-tracking branches that no longer exist on remote.

Returns:

Note:

This method is safe as it only fetches remote changes and never modifies the working directory or current branch. It will not perform any merges, rebases, or checkouts.

from gitpandas import Repository
from gitpandas.cache import EphemeralCache
# Create repository with caching
cache = EphemeralCache(max_keys=100)
repo = Repository('/path/to/repo', cache_backend=cache)
# Perform a dry run to see what would be fetched
dry_result = repo.safe_fetch_remote(dry_run=True)
print(f"Would fetch from: {dry_result['message']}")
# Safely fetch changes
if dry_result['remote_exists']:


    result = repo.safe_fetch_remote()


    if result['success']:


        print(f"Fetch completed: {result['message']}")


        if result['changes_available']:


            print("New changes are available!")


    else:


        print(f"Fetch failed: {result['error']}")

# Fetch from a specific remote
result = repo.safe_fetch_remote(remote_name='upstream')
# Fetch and prune deleted remote branches
result = repo.safe_fetch_remote(prune=True)
# Perform dry run to preview without fetching
result = repo.safe_fetch_remote(dry_run=True)

Args:

Returns:

Note:

This method will only execute methods if a cache backend is configured. If no cache backend is available, it will return immediately with a success status but no methods executed.

from gitpandas import Repository
from gitpandas.cache import DiskCache
# Create repository with persistent cache
cache = DiskCache('/tmp/my_cache.gz', max_keys=200)
repo = Repository('/path/to/repo', cache_backend=cache)
# Warm cache with default methods
result = repo.warm_cache()
print(f"Cache warming completed in {result['execution_time']:.2f} seconds")
print(f"Created {result['cache_entries_created']} cache entries")
print(f"Methods executed: {result['methods_executed']}")

# Warm specific methods with custom parameters
result = repo.warm_cache(


    methods=['commit_history', 'blame', 'file_detail'],


    limit=100,


    branch='main',


    ignore_globs=['*.log', '*.tmp']
)
# Check results
if result['success']:


    print(f"Successfully warmed {len(result['methods_executed'])} methods")
else:


    print(f"Errors occurred: {result['errors']}")

import time
# Test cold performance
start = time.time()
history_cold = repo.commit_history(limit=100)
cold_time = time.time() - start
# Warm the cache
repo.warm_cache(methods=['commit_history'], limit=100)
# Test warm performance
start = time.time()
history_warm = repo.commit_history(limit=100)
warm_time = time.time() - start
speedup = cold_time / warm_time
print(f"Cache warming provided {speedup:.1f}x speedup!")

Args:

remote_name (str, optional): Name of remote to fetch from. Defaults to 'origin'. prune (bool, optional): Remove remote-tracking branches that no longer exist.

**

Returns:

Note:

This method safely handles errors at the repository level, ensuring that failures in one repository don't affect processing of others. All operations are read-only and will not modify working directories or current branches.

from gitpandas import ProjectDirectory
from gitpandas.cache import DiskCache
# Create project directory with shared cache
cache = DiskCache('/tmp/project_cache.gz', max_keys=500)
project = ProjectDirectory('/path/to/repos', cache_backend=cache)
# Perform bulk operations
result = project.bulk_fetch_and_warm(


    fetch_remote=True,


    warm_cache=True,


    parallel=True
)
print(f"Processed {result['repositories_processed']} repositories")
print(f"Fetch summary: {result['summary']['fetch_successful']} successful")
print(f"Cache summary: {result['summary']['cache_successful']} successful")

# Customize bulk operations
result = project.bulk_fetch_and_warm(


    fetch_remote=True,


    warm_cache=True,


    parallel=True,


    remote_name='upstream',


    prune=True,


    dry_run=False,


    cache_methods=['commit_history', 'blame'],


    limit=200,


    ignore_globs=['*.log']
)
# Check individual repository results
for repo_name, fetch_result in result['fetch_results'].items():


    if not fetch_result['success']:


        print(f"Fetch failed for {repo_name}: {fetch_result['error']}")
for repo_name, cache_result in result['cache_results'].items():


    print(f"{repo_name}: {cache_result['cache_entries_created']} cache entries")

# Enable parallel processing (default when joblib available)
result = project.bulk_fetch_and_warm(


    fetch_remote=True,


    warm_cache=True,


    parallel=True  # Uses all available CPU cores
)
# Disable parallel processing for sequential execution
result = project.bulk_fetch_and_warm(


    fetch_remote=True,


    warm_cache=True,


    parallel=False
)

# Safe fetch error handling
result = repo.safe_fetch_remote()
if not result['success']:


    if result['remote_exists']:


        print(f"Fetch failed: {result['error']}")


    else:


        print(f"No remote configured: {result['message']}")
# Cache warming error handling
result = repo.warm_cache()
if not result['success']:


    print(f"Failed methods: {result['methods_failed']}")


    for error in result['errors']:


        print(f"Error: {error}")
# Bulk operation error handling
result = project.bulk_fetch_and_warm(fetch_remote=True, warm_cache=True)
for repo_name, repo_result in result['fetch_results'].items():


    if not repo_result['success']:


        print(f"Repository {repo_name} failed: {repo_result.get('error', 'Unknown error')}")

• fetch_successful (int): Number of successful fetches
• fetch_failed (int): Number of failed fetches
• cache_successful (int): Number of successful cache warming operations
• cache_failed (int): Number of failed cache warming operations
• repositories_with_remotes (int): Number of repositories with remotes
• total_cache_entries_created (int): Total cache entries created across all repositories

• Best for: Single-session analysis, development, testing
• Pros: Fast access, no disk I/O, automatic cleanup
• Cons: Data lost when process ends, limited by available RAM
• Use case: Interactive analysis, Jupyter notebooks

• Best for: Multi-session analysis, CI/CD pipelines, long-running processes
• Pros: Survives process restarts, configurable size limits, compression
• Cons: Slower than memory cache, disk space usage
• Use case: Regular analysis workflows, automated reporting

• Best for: Multi-user environments, distributed analysis, shared cache
• Pros: Shared across processes/machines, TTL support, Redis features
• Cons: Requires Redis server, network latency, additional complexity
• Use case: Team environments, production deployments

from gitpandas import Repository
from gitpandas.cache import EphemeralCache, DiskCache, RedisDFCache
# In-memory cache (fastest for single session)
cache = EphemeralCache(max_keys=1000)
repo = Repository('/path/to/repo', cache_backend=cache)
# Persistent cache (best for repeated analysis)
cache = DiskCache('/tmp/gitpandas_cache.gz', max_keys=500)
repo = Repository('/path/to/repo', cache_backend=cache)
# Redis cache (best for shared environments)
cache = RedisDFCache(host='localhost', max_keys=2000, ttl=3600)
repo = Repository('/path/to/repo', cache_backend=cache)

# Warm cache with commonly used methods
result = repo.warm_cache(


    methods=['commit_history', 'branches', 'blame', 'file_detail'],


    limit=100,  # Reasonable limit for cache warming


    ignore_globs=['*.log', '*.tmp']
)
print(f"Cache entries created: {result['cache_entries_created']}")
print(f"Execution time: {result['execution_time']:.2f} seconds")

# Get cache statistics
stats = repo.get_cache_stats()
print(f"Repository entries: {stats['repository_entries']}")
if stats['global_cache_stats']:


    global_stats = stats['global_cache_stats']


    print(f"Cache usage: {global_stats['cache_usage_percent']:.1f}%")


    print(f"Average entry age: {global_stats['average_entry_age_hours']:.2f} hours")
# Invalidate specific cache entries
repo.invalidate_cache(keys=['commit_history'])
# Clear old cache entries by pattern
repo.invalidate_cache(pattern='blame*')
# Clear all cache for repository
repo.invalidate_cache()

# Analyze only Python files
commits = repo.commit_history(include_globs=['*.py'])
# Exclude test and build files
blame = repo.blame(ignore_globs=['test_*.py', 'build/*', '*.pyc'])
# Multiple patterns
rates = repo.file_change_rates(


    include_globs=['*.py', '*.js', '*.html'],


    ignore_globs=['*/tests/*', '*/node_modules/*']
)

# Limit to recent commits
recent_commits = repo.commit_history(limit=500)
# Analyze last 90 days only
recent_changes = repo.file_change_rates(days=90)
# Combine limits with filtering
python_commits = repo.commit_history(


    limit=1000,


    include_globs=['*.py']
)

# Analyze main development branch only
main_commits = repo.commit_history(branch='main')
# Compare specific branches
feature_commits = repo.commit_history(branch='feature/new-ui')

pip install joblib

from gitpandas import ProjectDirectory
# Parallel analysis across repositories
project = ProjectDirectory('/path/to/projects')
# These operations run in parallel when joblib is available:
commits = project.commit_history()  # Parallel across repos
branches = project.branches()       # Parallel across repos
blame = project.cumulative_blame()  # Parallel across commits
# Control parallelization
blame = repo.parallel_cumulative_blame(


    workers=4,  # Number of parallel workers


    limit=100   # Limit for better performance
)

import pandas as pd
# Check memory usage
commits = repo.commit_history(limit=10000)
print(f"Memory usage: {commits.memory_usage(deep=True).sum() / 1024 / 1024:.1f} MB")
# Optimize data types
commits['insertions'] = commits['insertions'].astype('int32')
commits['deletions'] = commits['deletions'].astype('int32')
# Use categorical for repeated strings
commits['committer'] = commits['committer'].astype('category')

def analyze_in_chunks(repo, chunk_size=1000):


    """Analyze repository in chunks to manage memory."""


    all_results = []


    offset = 0


    while True:


        # Get chunk of commits


        chunk = repo.commit_history(limit=chunk_size, skip=offset)


        if chunk.empty:


            break


        # Process chunk


        result = process_chunk(chunk)


        all_results.append(result)


        offset += chunk_size


        # Optional: Clear cache periodically


        if offset % 10000 == 0:


            repo.invalidate_cache(pattern='commit_history*')


    return pd.concat(all_results, ignore_index=True)

# Large repository configuration
cache = DiskCache('/fast/disk/cache.gz', max_keys=10000)
repo = Repository(


    '/path/to/large/repo',


    cache_backend=cache,


    default_branch='main'
)
# Use aggressive filtering
analysis = repo.commit_history(


    limit=5000,  # Reasonable limit


    days=365,    # Last year only


    include_globs=['*.py', '*.js'],  # Core files only


    ignore_globs=['*/tests/*', '*/vendor/*']  # Exclude bulk dirs
)

import time
def benchmark_operation(func, *args, **kwargs):


    """Benchmark any git-pandas operation."""


    start_time = time.time()


    start_memory = get_memory_usage()


    result = func(*args, **kwargs)


    end_time = time.time()


    end_memory = get_memory_usage()


    print(f"Execution time: {end_time - start_time:.2f}s")


    print(f"Memory delta: {end_memory - start_memory:.1f}MB")


    print(f"Result size: {len(result)} rows")


    return result
# Example usage
commits = benchmark_operation(


    repo.commit_history,


    limit=1000,


    include_globs=['*.py']
)

# Slow: No cache means repeated expensive Git operations
repo = Repository('/path/to/repo')  # No cache_backend
for branch in ['main', 'develop', 'feature']:


    commits = repo.commit_history(branch=branch)  # Repeated work

# Fast: Cache reuses expensive operations
cache = DiskCache('/tmp/analysis_cache.gz', max_keys=1000)
repo = Repository('/path/to/repo', cache_backend=cache)
for branch in ['main', 'develop', 'feature']:


    commits = repo.commit_history(branch=branch)  # Cached after first

# Slow: Processes all files including irrelevant ones
blame = repo.blame()  # Includes build files, logs, etc.

# Fast: Only analyzes relevant source files
blame = repo.blame(


    include_globs=['*.py', '*.js', '*.html'],


    ignore_globs=['*/build/*', '*/logs/*', '*.pyc']
)

# Slow: Processes entire repository history
commits = repo.commit_history()  # Could be millions of commits

# Fast: Focuses on recent, relevant commits
commits = repo.commit_history(


    limit=1000,  # Last 1000 commits


    days=90       # Last 90 days
)

# Memory issues: Large DataFrames accumulating
results = []
for i in range(100):


    commits = repo.commit_history(limit=10000)


    results.append(commits)  # Accumulating large DataFrames

# Memory efficient: Process and aggregate
total_commits = 0
for i in range(100):


    commits = repo.commit_history(limit=1000)  # Smaller chunks


    total_commits += len(commits)


    # Don't accumulate DataFrames
print(f"Total commits processed: {total_commits}")

from gitpandas import Repository
repo = Repository('/path/to/repo')
# Get repository name
print(repo.repo_name)
# Check if repository is bare
print(repo.is_bare())
# Get all tags
print(repo.tags())
# Get all branches
print(repo.branches())
# Get all revisions
print(repo.revs())
# Get blame information
print(repo.blame(include_globs=['*.py']))

# Get commit history
commits_df = repo.commit_history()
# Get file change history
changes_df = repo.file_change_history()
# Filter by file extension
python_changes = repo.file_change_history(include_globs=['*.py'])
# Filter by directory
src_changes = repo.file_change_history(include_globs=['src/*'])
# Get commits in tags
tag_commits = repo.commits_in_tags()

from gitpandas import ProjectDirectory
# Create project from multiple repositories
project = ProjectDirectory([


    'git://github.com/user/repo1.git',


    'git://github.com/user/repo2.git'
])
# Get repository information
print(project.repo_information())
# Calculate bus factor
print(project.bus_factor())
# Get file change history
print(project.file_change_history())
# Get blame information
print(project.blame())

# Get cumulative blame
blame_df = repo.cumulative_blame()
# Plot cumulative blame using pandas plotting
import matplotlib.pyplot as plt
blame_df.plot(x='date', y='loc', title='Cumulative Blame Over Time')
plt.show()

# Calculate bus factor for repository
bus_factor = repo.bus_factor()
# Calculate file-wise bus factor (new in v2.5.0)
file_bus_factor = repo.bus_factor(by='file')
# Get detailed blame information
blame_df = repo.blame(by='file')  # Get file-level blame details
# Analyze ownership patterns
ownership_patterns = repo.blame(committer=True, by='repository')

from gitpandas import Repository
from gitpandas.cache import EphemeralCache, DiskCache, RedisDFCache
# Use in-memory caching
cache = EphemeralCache(max_keys=1000)
repo = Repository('/path/to/repo', cache_backend=cache)
# Use persistent disk caching (new in v2.5.0)
disk_cache = DiskCache('/tmp/gitpandas_cache.gz', max_keys=500)
repo = Repository('/path/to/repo', cache_backend=disk_cache)
# Or use Redis for distributed caching
redis_cache = RedisDFCache(


    host='localhost',


    port=6379,


    db=12,


    ttl=3600  # Cache entries expire after 1 hour
)
repo = Repository('/path/to/repo', cache_backend=redis_cache)

# Get cache statistics
stats = repo.get_cache_stats()
print(f"Cache usage: {stats['global_cache_stats']['cache_usage_percent']:.1f}%")
# Invalidate specific cache entries
repo.invalidate_cache(keys=['commit_history'])
# Clear all cache for this repository
repo.invalidate_cache()
# Warm cache for better performance
result = repo.warm_cache(methods=['commit_history', 'blame'], limit=100)
print(f"Created {result['cache_entries_created']} cache entries")

# Get commit history
commit_df = repo.commit_history()
# Plot commits over time using pandas
commit_df.resample('D').size().plot(


    kind='bar',


    title='Commits per Day'
)
plt.show()

# Get file change history
changes_df = repo.file_change_history()
# Plot changes over time using pandas
changes_df.groupby('filename')['insertions'].sum().plot(


    kind='bar',


    title='Lines Added by File'
)
plt.show()

git clone git@github.com:YourLogin/git-pandas.git
cd git-pandas

git checkout -b feature/your-awesome-feature

make test
make coverage

make install-dev

make pre-commit

make test

make docs