SXXXXXXX_RepoSync/doc/English-manual.md

RepoSync - User Manual

Table of Contents

1. Introduction
2. First Steps
   • Installation
   • Initial Configuration
3. The Main Window
4. Managing Profiles
5. The Export Workflow
6. The Import Workflow
7. Understanding Sync Statuses
8. Frequently Asked Questions (FAQ)

---

1. Introduction

RepoSync is a desktop application that allows you to synchronize Git repositories between two servers without a direct network link. It uses Git's .bundle feature to create a full, portable copy of a repository, which can then be transferred and "unbundled" on another server.

This manual will guide you through all the features of the application.

2. First Steps

Installation

1. Clone the repository from its source.
2. Navigate into the project directory.
3. Install the required Python packages: pip install -r requirements.txt.

Initial Configuration

Before you can use RepoSync, two things must be configured:

1. Bundle Folder: The first time you launch the application, you will be prompted to select a folder. This folder is crucial, as it will store all the exported repository bundles and the manifest.json file. You can change this path later using the "Browse..." button.
2. Server Profiles: You need to tell RepoSync how to connect to your Git servers. Go to the menu File -> Configure Profiles... to set up at least one profile for your source server and one for your destination server.

3. The Main Window

The user interface is divided into four main areas:

• Bundle Folder Path: At the top, this shows the currently selected bundle folder. You can change it with "Browse..." or clear its contents with "Reset".
• Tabs (Export/Import): The main area is split into two tabs, one for each phase of the synchronization.
• Logs: The bottom panel displays detailed logs of all operations, which is useful for debugging.
• Status Bar: At the very bottom, a status bar shows the current operation, a progress bar, and the total size of an export/import.

4. Managing Profiles

The Profile Manager (File -> Configure Profiles...) is where you save connection settings for your Gitea servers.

• Profile Name: A friendly name you choose (e.g., "Home Gitea", "Work Server").
• Server URL: The base URL of your Gitea instance (e.g., http://192.168.1.100:3000).
• Access Token: A personal access token generated from your Gitea account's settings. This is required for API access and Git operations.
• Service Type: Currently supports gitea.

You can New, Save, and Delete profiles from this window.

5. The Export Workflow

This process copies repositories from a source server into your bundle folder.

1. Navigate to the Export from Server tab.
2. Select the correct server profile from the "Export from Server:" dropdown.
3. Click the Fetch Items button. RepoSync will connect to the server and compare its repositories with the contents of your manifest.json.
4. The list will be populated, showing the sync status of each item.
5. Select the repositories and wikis you wish to export. You can use the "Select Modified" button to quickly select all items that are new or have changed on the server.
6. Click the Export Selected button. RepoSync will clone each selected item and create a .bundle file for it in your bundle folder.
7. Once complete, you can physically move the entire bundle folder to your other machine.

6. The Import Workflow

This process copies repositories from your bundle folder to a destination server.

1. Make sure your bundle folder is accessible from your current machine.
2. In RepoSync, set the "Bundle Folder Path" to the correct location.
3. Navigate to the Import to Server tab.
4. Select the correct destination server profile from the "Import to Server:" dropdown.
5. Click the Check Bundle Status button. RepoSync will read the manifest.json and compare its contents with the repositories on the destination server.
6. The list will be populated. Pay close attention to the status:
   • You can only import items with the status NEW_REPO (it doesn't exist on the server) or BEHIND (the bundle has newer changes than the server).
7. Select the items you wish to import.
8. Click the Import Selected button. RepoSync will create or update the repositories on the destination server.

7. Understanding Sync Statuses

The status tells you the relationship between the server and your local bundle/manifest.

In the Export Tab:

• NEW_REPO: This repository exists on the server but not in your bundle folder. It needs to be exported.
• AHEAD: The repository on the server has new commits that are not in your bundle. It needs to be exported.
• IDENTICAL: The server and the bundle are perfectly in sync. No action needed.
• ORPHANED_BUNDLE: A bundle exists for this item, but the repository was deleted from the server.

In the Import Tab:

• NEW_REPO: A bundle exists for this item, but the repository does not exist on the destination server. It's ready to be imported.
• BEHIND: The bundle contains newer commits than the repository on the destination server. It's ready to be imported.
• AHEAD: The repository on the destination server has newer commits than the bundle. You cannot import this, as it would overwrite changes. You must export from this server first.
• DIVERGED: Both the bundle and the server repository have unique new commits. This requires manual intervention.
• IDENTICAL: The bundle and the server are in sync. No action needed.

8. Frequently Asked Questions (FAQ)

Q: My wiki import failed and asked me to do something manually. Why? A: Due to a limitation or bug in some Gitea versions, a wiki repository cannot be created via a git push if it's completely empty. RepoSync will instruct you to visit the Gitea web interface, go to the repository's "Wiki" tab, and click "Create the first page". This initializes the wiki on the server. After that, you can re-run the import in RepoSync, and it will succeed.

Q: What is a .bundle file? A: It's a standard Git feature. A single file that contains the entire history of a Git repository, including all branches and tags. It's a full-fidelity, portable backup.

Q: What is manifest.json? A: It's the "brain" of RepoSync. It stores metadata about each exported repository, including the commit hash of every branch. This file allows RepoSync to determine the sync status without needing to inspect every bundle file on every check.

Q: How do I get a Gitea Access Token? A: Log in to your Gitea account, go to Settings -> Applications, and under "Manage Access Tokens", generate a new token. Ensure it has repository read and write permissions.

Q: Can I use this with GitHub or GitLab? A: Currently, the API client is specifically written for Gitea. The core logic could be adapted to support other services by creating a new client that implements the BaseVCSClient interface.