File Exclusion & CI Integration

def exclude(src_path: str, globs: List[str]) -> bool:
    """
    Determine if a file path should be excluded from processing.
    
    Parameters:
    - src_path (str): Relative source path of the file
    - globs (List[str]): List of glob patterns to match against
    
    Returns:
    bool: True if file should be excluded, False otherwise
    """

from mkdocs_git_revision_date_localized_plugin.exclude import exclude

# Define exclusion patterns
exclusion_patterns = [
    "drafts/*",
    "*.tmp",
    "temp/**/*",
    "generated/*.md"
]

# Check if file should be excluded
file_path = "docs/drafts/my-draft.md"
should_exclude = exclude(file_path, exclusion_patterns)  # Returns True

file_path = "docs/index.md"
should_exclude = exclude(file_path, exclusion_patterns)  # Returns False

# Examples of supported glob patterns
patterns = [
    "*.tmp",           # All .tmp files
    "drafts/*",        # All files in drafts directory
    "temp/**/*",       # All files in temp directory recursively
    "*/private.md",    # private.md in any directory
    "docs/old/*.md",   # All .md files in docs/old/
]

plugins:
  - git-revision-date-localized:
      exclude:
        - "drafts/*"
        - "*.tmp"
        - "generated/**/*"
        - "private/*.md"

def raise_ci_warnings(repo) -> None:
    """
    Raise warnings for CI environments with shallow git clones.
    
    Parameters:
    - repo: GitPython repository object
    """

def is_shallow_clone(repo) -> bool:
    """
    Determine if repository is a shallow clone.
    
    Parameters:
    - repo: GitPython repository object
    
    Returns:
    bool: True if repository is shallow, False otherwise
    """

def commit_count(repo) -> int:
    """
    Count the number of commits in repository.
    
    Parameters:
    - repo: GitPython repository object
    
    Returns:
    int: Number of commits in repository
    """

from mkdocs_git_revision_date_localized_plugin.ci import raise_ci_warnings, is_shallow_clone, commit_count
from git import Repo

# Initialize repository
repo = Repo("/path/to/repo")

# Check if shallow clone
if is_shallow_clone(repo):
    print("Repository is a shallow clone")
    
    # Count commits
    num_commits = commit_count(repo)
    print(f"Repository has {num_commits} commits")
    
    # Raise appropriate warnings for CI environment
    raise_ci_warnings(repo)

# Detects: GITHUB_ACTIONS environment variable
# Warning triggered when: commit_count == 1 (default fetch-depth: 1)
# Recommendation: Set fetch-depth: 0 in checkout action

# Detects: GITLAB_CI environment variable  
# Warning triggered when: commit_count < 50 (default GIT_DEPTH: 50)
# Recommendation: Set GIT_DEPTH: 0 in .gitlab-ci.yml

# Detects: BITBUCKET_BUILD_NUMBER environment variable
# Warning triggered when: commit_count < 50 (default depth: 50)
# Recommendation: Set clone depth to full

# Detects: Agent.Source.Git.ShallowFetchDepth environment variable
# Warning triggered when: configured depth < actual commits
# Recommendation: Remove shallow fetch settings

- uses: actions/checkout@v4
  with:
    fetch-depth: 0  # Fetch full history

variables:
  GIT_DEPTH: 0  # Fetch full history

job:
  script:
    - mkdocs build

pipelines:
  default:
    - step:
        name: Build docs
        clone:
          depth: full  # Fetch full history
        script:
          - mkdocs build

- checkout: self
  fetchDepth: 0  # Fetch full history

# Configuration options affecting utility behavior
config = {
    "fallback_to_build_date": True,   # Use build date when git fails
    "strict": False,                  # Don't treat warnings as errors
    "enable_parallel_processing": True # Use multiprocessing for performance
}

# When git operations fail, utilities can fall back to:
# 1. Current build timestamp
# 2. File modification time
# 3. Default epoch time

# Controlled by fallback_to_build_date configuration

# Handles both Unix and Windows path separators
# Unix: "docs/drafts/file.md"
# Windows: "docs\\drafts\\file.md"

# Both patterns work on all platforms:
exclude_patterns = [
    "docs/drafts/*",    # Unix-style (works everywhere)
    "docs\\drafts\\*",  # Windows-style (converted automatically)
]

# Exclusion patterns are evaluated in order
# Place most common exclusions first for better performance
exclude_patterns = [
    "*.tmp",        # Fast: simple extension match
    "drafts/*",     # Fast: single directory match  
    "**/temp/*",    # Slower: recursive directory match
]

# CI warnings are cached per repository
# Multiple files in same repo don't trigger repeated warnings

plugins:
  - git-revision-date-localized:
      type: date
      exclude:
        - "drafts/*"
        - "*.tmp"
        - "generated/**/*"
      fallback_to_build_date: true
      strict: false

from mkdocs_git_revision_date_localized_plugin.exclude import exclude

def should_process_file(file_path, config):
    """Custom logic for determining file processing"""
    exclusion_patterns = config.get("exclude", [])
    
    # Use built-in exclusion
    if exclude(file_path, exclusion_patterns):
        return False
    
    # Add custom logic
    if file_path.startswith("api/") and not file_path.endswith(".md"):
        return False
        
    return True

import os
from mkdocs_git_revision_date_localized_plugin.ci import is_shallow_clone, raise_ci_warnings

def configure_for_ci(config):
    """Adjust configuration for CI environments"""
    if any(ci_var in os.environ for ci_var in ["CI", "GITHUB_ACTIONS", "GITLAB_CI"]):
        # Enable fallback for CI environments
        config["fallback_to_build_date"] = True
        config["strict"] = False
        
        # Check for shallow clone issues
        if is_shallow_clone(repo):
            raise_ci_warnings(repo)
    
    return config