SXXXXXXX_GitUtility/manual.md

(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.

---