forgejo-sync-manager-core ^v1.0.2

Universal core library for Forgejo repository synchronization.

⚠️ Disclaimer

By using this software, you agree to the full disclaimer terms.

Summary: Software provided "AS IS" without warranty. You assume all risks.

Full legal disclaimer: See DISCLAIMER.md

Overview

forgejo-sync-manager-core is a reusable Python library that provides the core functionality for synchronizing Forgejo repositories. It is designed to be used by both CLI and GUI applications, ensuring code reuse and consistency across different interfaces.

Features

• Forgejo API client with token-based authentication
• Repository discovery with pagination support
• Git repository cloning and updating
• Repository recloning functionality
• Local repository existence checking
• Path management for local storage
• Cross-platform support (Linux, Windows, macOS)
• Abstract base classes for easy extension

Implementations

This core library is used in the following projects:

Components

Core Classes

Sync Managers

Requirements

• Python 3.8+
• Git
• Forgejo server with API access
• requests library

Installation

git clone https://github.com/smartlegionlab/forgejo-sync-manager-core.git
cd forgejo-sync-manager-core
python -m venv venv
pip install -r requirements.txt

Usage

Basic Authentication

from forgejo_sync_manager_core.core.auth import ForgejoAuth

auth = ForgejoAuth(
    token="your_token",
    server_url="http://localhost:3000",
    username="your_username"
)

API Client

from forgejo_sync_manager_core.core.api_client import ForgejoAPIClient

client = ForgejoAPIClient(auth)
user_info = client.get_user_info()
repositories = client.get_user_repos()

Sync Manager for GUI Applications

from forgejo_sync_manager_core.core.sync_manager_gui import GUISyncManager

sync_manager = GUISyncManager(auth)
sync_manager.ensure_directories()

for repo in repositories:
    status = sync_manager.sync_repository(repo)
    # status: "CLONED", "UPDATED", "FAILED"

Sync Manager for CLI Applications

from forgejo_sync_manager_core.core.sync_manager_cli import CLISyncManager

sync_manager = CLISyncManager(auth)
results = sync_manager.sync_all_repositories(repositories)
# results: {"cloned": 0, "updated": 0, "failed": 0}

Check Repository Updates (CLI only)

from forgejo_sync_manager_core.core.sync_manager_cli import CLISyncManager

sync_manager = CLISyncManager(auth)
needs_update = sync_manager.check_updates(repositories)
print(f"Repositories needing update: {len(needs_update)}")

Local Repository Management

# Check if repository exists locally
exists = sync_manager.repo_exists_locally("repo-name")

# Get path to local repository
repo_path = sync_manager.get_repo_path("repo-name")

Configuration

Configuration is stored in ~/forgejo-sync-manager/config.json:

{
    "token": "your_access_token",
    "server_url": "http://localhost:3000",
    "username": "your_username"
}

Return Status Codes

How It Works

1. Authentication: Token-based authentication via Forgejo API
2. Repository Discovery: Fetches complete repository list with pagination (50 per page)
3. Update Detection (CLI only): For each existing repository, executes git fetch and compares HEAD with FETCH_HEAD
4. Sync Operations: Uses authenticated URLs with embedded token for Git operations
5. Directory Structure: ~/forgejo-sync-manager/{username}/repositories/

License

BSD 3-Clause License

Copyright (©) 2026, Alexander Suvorov All rights reserved.

Related Projects

• forgejo-sync-manager - CLI implementation
• forgejo-sync-manager-gui - GUI implementation