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:

Project	Description	Repository
forgejo-sync-manager-cli	CLI tool for batch synchronization	GitHub
forgejo-sync-manager-gui	Desktop GUI tool for batch synchronization	GitHub

Components

Core Classes

Class	Description
ForgejoAuth	Authentication container for server URL and token
ForgejoAPIClient	API client for Forgejo REST API
ConfigManager	Configuration file management (JSON)
BaseSyncManager	Abstract base class for sync operations

Sync Managers

Class	Purpose
GUISyncManager	Lightweight manager for GUI applications (no console output)
CLISyncManager	Full-featured manager with console progress output

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

Status	Description
CLONED	Repository was successfully cloned
UPDATED	Existing repository was successfully updated
RECLONED	Repository was deleted and re-cloned
FAILED	Operation failed

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