292 lines
21 KiB
Markdown
292 lines
21 KiB
Markdown
**(English)**
|
|
|
|
# User Manual: Git Sync Tool
|
|
|
|
## 1. Introduction
|
|
|
|
Welcome to **Git Sync Tool**! This application is designed to simplify the management of your Git repositories, with a particular focus on synchronization via *bundle* files (ideal for offline environments or those with network restrictions) and interaction with remote repositories (such as Gitea, GitHub, GitLab, etc.). It also allows you to manage common Git operations like commits, branches, tags, and view history and changes.
|
|
|
|
This manual will guide you through the main features and some typical usage scenarios.
|
|
|
|
## 2. Getting Started: Profiles
|
|
|
|
The application uses **Profiles** to store specific settings for each repository you manage (paths, bundle names, remote configurations, etc.).
|
|
|
|
* **Selection:** On startup, the application loads the `default` profile or the first available profile. Use the dropdown menu at the top to select an existing profile. Settings are loaded automatically upon selection.
|
|
* **Adding:** Use the **Add New** button to create a new profile. You will be prompted for a name. Default settings will be populated; you will then need to configure at least the "Working Directory Path".
|
|
* **Cloning:** Use the **Clone from Remote** button to clone an existing repository from a remote URL into a new local directory and automatically create an associated profile.
|
|
* **Saving:** After modifying paths or settings for a profile, click **Save Profile** to store the changes in the configuration file (`git_svn_sync.ini`).
|
|
* **Removing:** Select a profile (other than `default`) and click **Remove** to delete it (you will be asked for confirmation).
|
|
|
|
## 3. Interface Overview
|
|
|
|
The interface is organized into several sections:
|
|
|
|
1. **Profile Bar (Top):** Select, save, add, clone, or remove configuration profiles.
|
|
2. **Main Tabs (Notebook):** Contain features grouped by topic (Repository, Remote, Backup, Commit, Tags, Branches, History).
|
|
3. **Log Area (Bottom):** Displays detailed messages about operations performed, errors, and warnings. Useful for debugging and understanding what's happening.
|
|
4. **Status Bar (Very Bottom):** Shows brief messages about the application's current state (Ready, Processing, Error, Success, etc.).
|
|
|
|
## 4. Features by Tab
|
|
|
|
### 4.1. "Repository / Bundle" Tab
|
|
|
|
This tab manages essential paths and operations for creating/using bundle files.
|
|
|
|
* **Working Directory Path:** The **absolute** path to the main folder of your local Git repository (the one containing the hidden `.git` subfolder).
|
|
* **Status Indicator (Dot):** Green indicates the path is valid and contains an initialized Git repository. Red indicates it is not.
|
|
* **Browse...:** Opens a dialog to select the folder.
|
|
* **Bundle Target Directory:** The folder where bundle files will be created or read from (e.g., a USB drive or a shared network folder).
|
|
* **Browse...:** Opens a dialog to select the folder.
|
|
* **Create Bundle Filename:** Name of the bundle file to create (e.g., `my_repo.bundle`).
|
|
* **Fetch Bundle Filename:** Name of the bundle file to read changes from (e.g., `remote_update.bundle`).
|
|
* **Prepare Repository:** (Enabled only if the Working Directory is valid but *not* yet a Git repo). Initializes a new Git repository (`git init`) and ensures the `.svn` folder (if present) is added to the `.gitignore` file.
|
|
* **Create Bundle:** Creates a bundle file (`.bundle`) containing the entire history and all references (branches, tags) of the local repository. Saves the file to the "Bundle Target Directory" with the name specified in "Create Bundle Filename". Useful for transferring the entire repo state. Includes options for backup and autocommit before creation (see Backup and Commit tabs).
|
|
* **Fetch from Bundle:** Reads a bundle file (specified in "Fetch Bundle Filename" and located in the "Bundle Target Directory") and applies the contained changes to the local repository.
|
|
* If the "Working Directory Path" does not exist or is an empty folder, it clones the bundle content into that directory.
|
|
* If the "Working Directory Path" is already a Git repository, it performs a `git fetch` from the bundle and then attempts a `git merge` to integrate the changes. Merge conflicts may occur. Includes an option for backup before fetching (see Backup tab).
|
|
* **Edit .gitignore:** Opens a modal text editor to directly modify the repository's `.gitignore` file. Saving changes will automatically trigger a check to unstage files that should now be ignored.
|
|
|
|
### 4.2. "Remote Repository" Tab
|
|
|
|
This tab manages interaction with remote Git repositories (e.g., Gitea, GitHub).
|
|
|
|
* **Remote URL:** The HTTPS or SSH address of the remote repository.
|
|
* **Local Name:** The local alias for this remote (standard: `origin`).
|
|
* **Apply Config:** Adds or updates the remote configuration in the local `.git/config` file with the specified URL and name.
|
|
* **Check Connection:** Verifies if the remote is reachable and if authentication (if needed) is valid, without transferring data. Updates the status indicator.
|
|
* **Auth/Conn Status Indicator:** Shows the connection/authentication status (Unknown, Checking, Connected, Auth Required, Failed, Error).
|
|
* **Sync Status Label:** Displays the synchronization status of the current local branch relative to its remote *upstream* (e.g., "Up to date", "X commits ahead", "Y commits behind", "Upstream not set", "Detached HEAD").
|
|
* **Refresh Sync Status:** Recalculates and updates the Ahead/Behind status.
|
|
* **Fetch:** Downloads objects and references (commits, branches, tags) from the remote repository without integrating changes into your local branch. Updates *remote-tracking branches* (e.g., `origin/master`).
|
|
* **Pull:** Performs a `fetch` and then attempts to integrate (`merge`) changes from the tracked remote branch into your current local branch. May cause merge conflicts.
|
|
* **Push:** Uploads commits from your current local branch to the corresponding branch on the remote repository. The first time, it automatically sets up tracking (`--set-upstream`).
|
|
* **Push Tags:** Uploads all local tags to the remote repository.
|
|
* **Branch Lists (Side-by-Side):**
|
|
* **Remote Branches:** Shows branches present on the remote (as seen from the last `fetch`). Right-click for actions (Compare, Checkout as local).
|
|
* **Local Branches:** Shows local branches. Right-click for actions (Checkout, Merge into current, Delete, Force Delete, Compare).
|
|
* **Refresh Remote/Local List:** Buttons to update the respective lists.
|
|
|
|
### 4.3. "Backup Settings" Tab
|
|
|
|
Configures options for automatic and manual backups.
|
|
|
|
* **Enable Auto Backup:** If checked, automatically creates a ZIP backup of the "Working Directory" before performing "Create Bundle" and "Fetch from Bundle" actions.
|
|
* **Backup Directory:** The folder where backup ZIP files (automatic or manual) will be saved.
|
|
* **Browse...:** Selects the folder.
|
|
* **Exclude File Exts:** Comma-separated list of file extensions to exclude from the backup (e.g., `.log,.tmp,.obj`).
|
|
* **Exclude Dirs (Name):** Comma-separated list of directory names to exclude from the backup (e.g., `__pycache__,build,node_modules`). `.git` and `.svn` are always excluded.
|
|
* **Backup Now (ZIP):** Immediately creates a ZIP backup of the "Working Directory" in the specified "Backup Directory", using the defined exclusions.
|
|
|
|
### 4.4. "Commit / Changes" Tab
|
|
|
|
Manages staging and execution of local commits.
|
|
|
|
* **Enable Autocommit:** If checked, automatically attempts to commit all changes in the Working Directory *before* the "Create Bundle" action. Uses the message in the field below.
|
|
* **Commit Message:** Multi-line text area for writing the commit message for manual or autocommits.
|
|
* **Working Directory Changes:**
|
|
* **File List:** Shows files that have been modified, added (untracked `??`), or deleted compared to the last commit (`git status`).
|
|
* **Right-Click:**
|
|
* **Add to Staging Area:** (Enabled only for untracked `??` files) Executes `git add` on the selected file.
|
|
* **View Changes (Diff):** Opens a window showing the differences between the Working Directory version and the last commit (HEAD). Not available for `??`, `!!`, `D` files.
|
|
* **Refresh List:** Updates the list of changed files.
|
|
* **Commit Staged Changes:** Executes `git add .` (to stage all current changes, including new files if not untracked) and then `git commit` using the provided message.
|
|
|
|
### 4.5. "Tags" Tab
|
|
|
|
Manages Git tags (labels for specific commits).
|
|
|
|
* **Existing Tags:** List of tags present in the repository, sorted by creation date (newest first). Shows name and message (if annotated).
|
|
* **Refresh Tags:** Updates the tag list.
|
|
* **Create New Tag...:** Opens a dialog to enter a name and message for a new *annotated tag*. Creates the tag pointing to the current commit.
|
|
* **Checkout Selected Tag:** Switches to the "Detached HEAD" state, positioning you at the commit associated with the selected tag. Useful for inspecting an old version, but be aware: new commits made here won't belong to any branch.
|
|
|
|
### 4.6. "Branches (Local Ops)" Tab
|
|
|
|
Manages the repository's local branches.
|
|
|
|
* **Local Branches:** List of local branches. The current branch is marked with `*`.
|
|
* **Right-Click:**
|
|
* **Checkout Branch:** Switches to the selected branch.
|
|
* **Merge '{branch}' into current '{current}'**: Integrates changes from the selected branch into the currently active branch. May cause conflicts. (Enabled only if selecting a different branch than the current one).
|
|
* **Delete Branch:** Deletes the selected local branch (asks for confirmation). Fails if the branch has changes not yet merged into other branches.
|
|
* **Force Delete Branch:** Deletes the selected local branch even if it has unmerged changes (use with caution: potential data loss).
|
|
* **Compare '{branch}' with current '{current}'**: Opens a view showing files that differ between the selected branch and the current one.
|
|
* **Refresh Branches:** Updates the local branch list.
|
|
* **Create New Branch...:** Opens a dialog to enter the name for a new local branch, which will be created based on the current commit.
|
|
* **Checkout Selected Branch:** Switches to the branch selected in the list.
|
|
|
|
### 4.7. "History" Tab
|
|
|
|
Displays the repository's commit history.
|
|
|
|
* **Filter History by Branch/Tag:** Dropdown menu to show history only for a specific branch or tag, or for all (`-- All History --`).
|
|
* **Refresh History:** Reloads the history based on the selected filter.
|
|
* **History List (Treeview):** Shows commits (short hash, date/time, author, message/references). Most recent commits are at the top.
|
|
* **Double-Click:** Opens a detail window for the selected commit, showing full metadata and the list of files changed in that commit. From there, you can view the diff for each individual file compared to its parent commit.
|
|
|
|
### 4.8. Log Area & Status Bar
|
|
|
|
* **Application Log:** Scrollable text area showing detailed messages about all operations, errors, warnings, and debug information. Messages are also written to the `git_svn_sync.log` file.
|
|
* **Status Bar:** Line at the bottom of the window showing concise messages about the current state ("Ready.", "Processing...", "Error...", "Success"). May change color to highlight states (yellow for processing, green for success, red for error).
|
|
|
|
## 5. Common Use Cases (Workflows)
|
|
|
|
### 5.1. Scenario: Starting with an Existing Project (Not Yet Git)
|
|
|
|
**Goal:** Put an existing project (e.g., from SVN or just files) under Git control and set up a profile in the application.
|
|
|
|
**Steps:**
|
|
|
|
1. Open **Git Sync Tool**.
|
|
2. Click **Add New** in the profile bar. Enter a profile name (e.g., `MyProject`) and click OK.
|
|
3. The new profile is selected.
|
|
4. In the **Repository / Bundle** tab, click **Browse...** next to "Working Directory Path" and select your project's main folder.
|
|
5. Click **Save Profile**.
|
|
6. If the folder isn't a Git repository, the indicator dot will be **red**. Click **Prepare Repository**. The indicator should turn **green**.
|
|
7. (Optional) Click **Edit .gitignore** to add project-specific rules (e.g., temporary files, build output). Save and close the editor. The application will check if any tracked files need to be untracked.
|
|
8. Go to the **Commit / Changes** tab. Click **Refresh List**. You should see all project files listed as "Untracked" (`??`).
|
|
9. Write an initial commit message (e.g., "Initial project import") in the "Commit Message" field.
|
|
10. Click **Commit Staged Changes**. This will add all files and create the first commit.
|
|
11. Your local repository is ready.
|
|
|
|
### 5.2. Scenario: Standard Local Workflow
|
|
|
|
**Goal:** Make changes, view them, and create a commit.
|
|
|
|
**Steps:**
|
|
|
|
1. Select the correct profile. Ensure the Working Directory indicator is **green**.
|
|
2. Modify your project files using your external editors.
|
|
3. Go to the **Commit / Changes** tab.
|
|
4. Click **Refresh List**. The "Working Directory Changes" list will show modified (`M`), added (`A` if you used `git add` externally or via context menu), deleted (`D`), or untracked (`??`) files.
|
|
5. (Optional) If you have untracked files (`??`) you want to include, select them and use **Right-Click -> Add to Staging Area**. Then click **Refresh List** again.
|
|
6. (Optional) To see specific changes in a file, **double-click** the file in the list to open the **Diff Viewer**. Close the viewer when done.
|
|
7. Write a descriptive commit message in the "Commit Message" area.
|
|
8. Click **Commit Staged Changes**.
|
|
9. Your changes are now recorded in the local Git history. You can see this by refreshing the **History** tab.
|
|
|
|
### 5.3. Scenario: Offline Synchronization via Bundle
|
|
|
|
**Goal:** Transfer changes between two computers (PC-A and PC-B) without a direct network connection, using removable media (e.g., USB drive).
|
|
|
|
**Steps (on PC-A):**
|
|
|
|
1. Work on the project on PC-A (see Scenario 5.2). Ensure all desired changes are committed.
|
|
2. Select the project's profile.
|
|
3. Go to the **Repository / Bundle** tab.
|
|
4. Set the "Bundle Target Directory" to the path of your USB drive (or other shared folder).
|
|
5. Set a meaningful name in "Create Bundle Filename" (e.g., `project_update_20250428.bundle`).
|
|
6. (Optional but recommended) Go to the **Backup Settings** tab, enable "Enable Auto Backup", and configure the "Backup Directory" (on PC-A) for safety.
|
|
7. Click **Save Profile**.
|
|
8. Return to the **Repository / Bundle** tab and click **Create Bundle**. Wait for completion.
|
|
9. Physically transfer the USB drive (or access the shared folder) from PC-B.
|
|
|
|
**Steps (on PC-B):**
|
|
|
|
1. Launch **Git Sync Tool** and select (or create/configure) the profile for the same project on PC-B. The "Working Directory Path" must point to the local copy of the project on PC-B.
|
|
2. Go to the **Repository / Bundle** tab.
|
|
3. Set the "Bundle Target Directory" to the path of the USB drive (or shared folder).
|
|
4. Set the filename received from PC-A in "Fetch Bundle Filename".
|
|
5. (Optional but recommended) Configure backup in the **Backup Settings** tab for PC-B.
|
|
6. Click **Save Profile**.
|
|
7. Return to the **Repository / Bundle** tab and click **Fetch from Bundle**.
|
|
* If the repository didn't exist on PC-B, it will be cloned from the bundle.
|
|
* If it existed, changes will be integrated (conflicts may occur if unsynchronized changes were also made on PC-B).
|
|
8. PC-B now has the changes from PC-A. You can resume the cycle by transferring a bundle from B to A.
|
|
|
|
### 5.4. Scenario: First Push to a Remote Repository (e.g., Gitea)
|
|
|
|
**Goal:** Upload an existing local repository to a remote server (e.g., Gitea) where an empty project has just been created.
|
|
|
|
**Steps:**
|
|
|
|
1. Ensure you have a ready local repository (see Scenario 5.1).
|
|
2. Create an **empty** project on your Gitea (or GitHub/GitLab) server. Copy the provided URL (HTTPS or SSH).
|
|
3. Open **Git Sync Tool** and select the profile for your local repository.
|
|
4. Go to the **Remote Repository** tab.
|
|
5. Paste the URL copied from Gitea into the **Remote URL** field.
|
|
6. Leave or enter `origin` in the **Local Name** field.
|
|
7. Click **Apply Config**. Check logs or status bar for confirmation.
|
|
8. (Recommended) Click **Check Connection**. Verify the status indicator and resolve any authentication issues if prompted.
|
|
9. Go to the **Branches (Local Ops)** tab and ensure you have **checked out** the main branch (e.g., `master` or `main`) containing the history you want to upload. The asterisk `*` must be next to that branch.
|
|
10. Return to the **Remote Repository** tab.
|
|
11. Click **Push**. The application should detect it's the first push and use the `--set-upstream` option. You might be prompted for credentials.
|
|
12. Wait for completion. Check your Gitea repository in the browser.
|
|
|
|
### 5.5. Scenario: Standard Workflow with a Remote Repository
|
|
|
|
**Goal:** Keep local work synchronized with a remote repository.
|
|
|
|
**Steps:**
|
|
|
|
1. Select the correct profile. Ensure the remote is configured.
|
|
2. **Before starting work:** Go to the **Remote Repository** tab and click **Pull** (or first **Fetch**, then resolve any differences before merging/pulling). This downloads changes made by others (or yourself on another machine) and integrates them locally. Resolve any merge conflicts if they occur.
|
|
3. **Work locally:** Modify files, make commits (see Scenario 5.2).
|
|
4. **When ready to share:** Go to the **Remote Repository** tab.
|
|
5. (Optional) Click **Fetch** and then **Refresh Sync Status** to see if there are new remote changes before pushing. If there are remote changes (`behind > 0`), use **Pull** and integrate them first.
|
|
6. Click **Push** to upload your local commits to the remote.
|
|
|
|
### 5.6. Scenario: Branch Management
|
|
|
|
**Goal:** Create a branch for a new feature, work on it, and then merge it back into the main branch.
|
|
|
|
**Steps:**
|
|
|
|
1. Select the profile and ensure you are on the main branch (e.g., `master`).
|
|
2. Go to the **Branches (Local Ops)** tab.
|
|
3. Click **Create New Branch...**. Enter a name (e.g., `feature/new-idea`) and click OK.
|
|
4. The new branch is created, but you haven't switched to it yet. Select the new branch in the list.
|
|
5. Click **Checkout Selected Branch**. You are now working on the new branch.
|
|
6. Work on the feature: modify files, make commits (Scenario 5.2) *on the `feature/new-idea` branch*.
|
|
7. **When the feature is complete:**
|
|
* Ensure all changes on the `feature/new-idea` branch are committed.
|
|
* Select the main branch (e.g., `master`) in the list.
|
|
* Click **Checkout Selected Branch** to return to main.
|
|
* (Optional but recommended) Do a **Pull** on the main branch to ensure you have the latest remote changes.
|
|
* Select the `feature/new-idea` branch in the list.
|
|
* **Right-Click** on `feature/new-idea` and choose **Merge 'feature/new-idea' into current 'master'**. Confirm.
|
|
* Resolve any merge conflicts, then make a commit from the "Commit / Changes" tab.
|
|
8. The feature is now integrated into the main branch.
|
|
9. (Optional) If you no longer need the `feature/new-idea` branch: select it, **Right-Click**, and choose **Delete Branch 'feature/new-idea'**. Confirm.
|
|
10. (Optional) **Push** the main branch to upload the merged changes to the remote.
|
|
|
|
### 5.7. Scenario: Creating and Using a Tag
|
|
|
|
**Goal:** Mark a specific version of the software (e.g., a release).
|
|
|
|
**Steps:**
|
|
|
|
1. Ensure the commit you want to tag is the current one (checkout the appropriate branch/commit).
|
|
2. Ensure there are no uncommitted local changes.
|
|
3. Go to the **Tags** tab.
|
|
4. Click **Create New Tag...**.
|
|
5. Enter a tag name (common standard: `vX.Y.Z`, e.g., `v1.0.0`) and a descriptive message (e.g., "Release version 1.0.0"). Click OK.
|
|
6. The tag is created locally.
|
|
7. (Optional) To share the tag, go to the **Remote Repository** tab and click **Push Tags**.
|
|
8. (Optional) To view the code state at the time of the tag, select it in the **Tags** tab list and click **Checkout Selected Tag** (remember you'll enter "Detached HEAD").
|
|
|
|
### 5.8. Scenario: Viewing Changes
|
|
|
|
**Goal:** Understand what has changed between different versions or within a specific commit.
|
|
|
|
**Steps:**
|
|
|
|
* **Local Changes (vs Last Commit):**
|
|
1. Go to the **Commit / Changes** tab.
|
|
2. Click **Refresh List**.
|
|
3. **Double-click** a modified file (`M`) to open the **Diff Viewer**.
|
|
* **Changes in a Specific Commit (vs Parent):**
|
|
1. Go to the **History** tab.
|
|
2. **Double-click** the desired commit.
|
|
3. The **Commit Details** window opens.
|
|
4. **Double-click** a file in the "Changed Files" list to open the **Diff Viewer**, showing the changes introduced *by that commit* for that file.
|
|
* **Changes Between Different Branches/Tags/Commits:**
|
|
1. Ensure you are on the branch you want to use as the comparison base (e.g., `master`).
|
|
2. Go to the **Branches (Local Ops)** or **Remote Repository** tab.
|
|
3. **Right-Click** on the branch/tag (local or remote) you want to compare against.
|
|
4. Choose **Compare '{other_ref}' with current '{your_branch}'**.
|
|
5. The **Differences Summary** window opens, listing the differing files.
|
|
6. **Double-click** a file in that window to open the **Diff Viewer** showing the comparison between the two chosen references.
|
|
|
|
--- |