docs updated and support for default branches (#19)

Author: wdm0006

CHANGELOG.md

@@ -1,3 +1,11 @@
+v2.2.0
+======
+
+ * Support for default branch setting instead of assuming master, will infer if not passed
+ * Better handling of ignore repos in project directory setup
+ * Added a branch exists helper in repository 
+ * Docs corrections
+
 v2.1.0
 ======
 

docs/source/cache.rst

@@ -11,43 +11,88 @@ The caching system provides:
 * Redis-based caching for persistent storage
 * Configurable cache durations
 * Automatic cache invalidation
+* Decorator-based caching for expensive operations
 
 Available Cache Backends
 ----------------------
 
-In-Memory Cache
-~~~~~~~~~~~~~
+In-Memory Cache (EphemeralCache)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The default in-memory cache is ephemeral and will be cleared when the process ends:
 
 .. code-block:: python
 
     from gitpandas import Repository
-    repo = Repository('/path/to/repo', cache=True)  # Enable in-memory caching
-
-Redis Cache
-~~~~~~~~~
+    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)
+
+Redis Cache (RedisDFCache)
+~~~~~~~~~~~~~~~~~~~~~~~
 
 For persistent caching across sessions, use Redis:
 
 .. code-block:: python
 
     from gitpandas import Repository
-    repo = Repository(
-        '/path/to/repo',
-        cache=True,
-        cache_backend='redis',
-        redis_url='redis://localhost:6379/0'
+    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)
+
+Using the Cache Decorator
+----------------------
+
+The `@multicache` decorator can be used to cache method results:
+
+.. code-block:: python
+
+    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
 
 Configuration
 ------------
 
-You can configure cache behavior through the following parameters:
+Cache backends can be configured with various parameters:
 
-* ``cache``: Enable/disable caching (default: False)
-* ``cache_backend``: Choose the cache backend ('memory' or 'redis')
-* ``cache_ttl``: Time-to-live for cached results in seconds
+EphemeralCache:
+* ``max_keys``: Maximum number of keys to store in memory (default: 1000)
+
+RedisDFCache:
+* ``host``: Redis host (default: 'localhost')
+* ``port``: Redis port (default: 6379)
+* ``db``: Redis database number (default: 12)
+* ``max_keys``: Maximum number of keys to store (default: 1000)
+* ``ttl``: Time-to-live in seconds for cache entries (default: None, no expiration)
+* Additional keyword arguments are passed to redis.StrictRedis
 
 API Reference
 ------------
@@ -59,16 +104,18 @@ API Reference
    :undoc-members:
    :show-inheritance:
    :inherited-members:
-   :special-members: __init__, __getitem__, __setitem__, __delitem__
+   :special-members: __init__, __getitem__, __setitem__, __delitem__, __contains__, __len__
 
-.. autoclass:: MemoryCache
+.. autoclass:: EphemeralCache
    :members:
    :undoc-members:
    :show-inheritance:
    :inherited-members:
 
-.. autoclass:: RedisCache
+.. autoclass:: RedisDFCache
    :members:
    :undoc-members:
    :show-inheritance:
    :inherited-members:
+
+.. autofunction:: multicache

docs/source/project.rst

@@ -26,15 +26,20 @@ Create a ProjectDirectory from a directory containing multiple repositories:
 .. code-block:: python
 
     from gitpandas import ProjectDirectory
-    project = ProjectDirectory(working_dir='/path/to/dir/', ignore=None, verbose=True)
+    project = ProjectDirectory(
+        working_dir='/path/to/dir/',
+        ignore_repos=['repo_to_ignore'],
+        verbose=True,
+        default_branch='main'  # Optional, will auto-detect if not specified
+    )
 
-The `ignore` parameter can be a list of directories to exclude. This method uses `os.walk` to search for `.git` directories recursively.
+The `ignore_repos` parameter can be a list of repository names to exclude. This method uses `os.walk` to search for `.git` directories recursively.
 
 To check which repositories are included:
 
 .. code-block:: python
 
-    print(project._repo_name())
+    print(project.repo_name())
 
 Explicit Local Repositories
 ~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -46,8 +51,9 @@ Create a ProjectDirectory from a list of local repositories:
     from gitpandas import ProjectDirectory
     project = ProjectDirectory(
         working_dir=['/path/to/repo1/', '/path/to/repo2/'],
-        ignore=None,
-        verbose=True
+        ignore_repos=['repo_to_ignore'],
+        verbose=True,
+        default_branch='main'  # Optional, will auto-detect if not specified
     )
 
 Explicit Remote Repositories
@@ -60,8 +66,9 @@ Create a ProjectDirectory from a list of remote repositories:
     from gitpandas import ProjectDirectory
     project = ProjectDirectory(
         working_dir=['git://github.com/user/repo1.git', 'git://github.com/user/repo2.git'],
-        ignore=None,
-        verbose=True
+        ignore_repos=['repo_to_ignore'],
+        verbose=True,
+        default_branch='main'  # Optional, will auto-detect if not specified
     )
 
 Common Operations
@@ -72,7 +79,7 @@ Here are some common operations you can perform with a ProjectDirectory object:
 .. code-block:: python
 
     # Get commit history across all repositories
-    commits_df = project.commit_history(branch='master')
+    commits_df = project.commit_history()
     
     # Get blame information across all repositories
     blame_df = project.blame()
@@ -85,6 +92,9 @@ Here are some common operations you can perform with a ProjectDirectory object:
     
     # Get file change history across all repositories
     changes_df = project.file_change_history()
+    
+    # Get detailed repository information
+    repo_info = project.repo_information()
 
 API Reference
 ------------
@@ -110,11 +120,5 @@ API Reference
       ~ProjectDirectory.tags
       ~ProjectDirectory.revs
       ~ProjectDirectory.bus_factor
-      ~ProjectDirectory.is_bare
-      ~ProjectDirectory.has_coverage
-
-   .. rubric:: Properties
-
-   .. autosummary::
-      :nosignatures:
+      ~ProjectDirectory.repo_information
       ~ProjectDirectory.repo_name

docs/source/repository.rst

@@ -26,7 +26,11 @@ Create a Repository from a local Git repository:
 .. code-block:: python
 
     from gitpandas import Repository
-    repo = Repository(working_dir='/path/to/repo/', verbose=True)
+    repo = Repository(
+        working_dir='/path/to/repo/',
+        verbose=True,
+        default_branch='main'  # Optional, will auto-detect if not specified
+    )
 
 The directory must contain a `.git` directory. Subdirectories are not searched.
 
@@ -38,7 +42,11 @@ Create a Repository from a remote Git repository:
 .. code-block:: python
 
     from gitpandas import Repository
-    repo = Repository(working_dir='git://github.com/user/repo.git', verbose=True)
+    repo = Repository(
+        working_dir='git://github.com/user/repo.git',
+        verbose=True,
+        default_branch='main'  # Optional, will auto-detect if not specified
+    )
 
 The repository will be cloned locally into a temporary directory. This can be slow for large repositories.
 
@@ -63,6 +71,9 @@ Here are some common operations you can perform with a Repository object:
     
     # Get file change history
     changes_df = repo.file_change_history()
+    
+    # Get repository name
+    repo_name = repo.repo_name
 
 API Reference
 ------------
@@ -90,12 +101,16 @@ API Reference
       ~Repository.bus_factor
       ~Repository.is_bare
       ~Repository.has_coverage
+      ~Repository.has_branch
+      ~Repository.get_branches_by_commit
+      ~Repository.commits_in_tags
 
    .. rubric:: Properties
 
    .. autosummary::
       :nosignatures:
       ~Repository.repo_name
+      ~Repository.default_branch
 
 .. autoclass:: GitFlowRepository
    :members: