git_timestamps

Git Timestamp Consistency Rule

Always use git commit timestamps instead of current system time for logging, data storage, and operations throughout the system.

Core Principle

• Use commit.committed_datetime or commit.committed_date from GitPython for all timestamp operations
• Never use datetime.now(), time.time(), or other current-time functions when git context is available
• Maintain temporal consistency with the actual development timeline

Implementation Patterns

✅ DO: Use Git Commit Timestamps

# For ISO format timestamps
timestamp = commit.committed_datetime.isoformat()

# For date strings  
date_str = commit.committed_datetime.strftime("%Y-%m-%d")

# For Unix timestamps
timestamp = commit.committed_date

# For datetime objects
dt = commit.committed_datetime

✅ DO: Access Latest Commit Timestamp

def get_git_commit_timestamp(repo_path: str) -> Optional[str]:
    """Get timestamp from most recent git commit."""
    try:
        repo = git.Repo(repo_path)
        if not repo.heads:
            return None
        latest_commit = repo.head.commit
        return latest_commit.committed_datetime.isoformat()
    except Exception:
        return None

✅ DO: Use in Logging with Fallback

def log_with_git_timestamp(message: str, repo_path: str = None):
    """Log with git commit timestamp for consistency."""
    timestamp = get_git_commit_timestamp(repo_path) if repo_path else None
    if timestamp:
        log_message = f"[{timestamp}] {message}"
    else:
        # Fallback only when git context unavailable
        log_message = f"[{datetime.now().isoformat()}] {message}"
    logger.info(log_message)

❌ DON'T: Use Current System Time When Git Context Available

# ❌ Wrong - ignores git timeline
timestamp = datetime.now().isoformat()
log_entry = f"[{datetime.now()}] Generated summary"

# ❌ Wrong - inconsistent with commit history
file_timestamp = time.time()

❌ DON'T: Mix Timestamp Sources