Git Sync - amitsri/rostyman-releases GitHub Wiki

Git Sync

Git Sync lets you version control your API collections using Git. Export collections as .rostyman files into a local Git repository, then commit, push, pull, and branch — all from within Rostyman.

How It Works

  1. Your collections live in Rostyman's local database
  2. Git Sync exports them as .rostyman files into a folder you choose
  3. That folder is (or becomes) a Git repo — you commit, push, pull, branch
  4. Changes pulled from Git can be imported back into Rostyman

Think of it like VS Code's Source Control panel, but for API collections.

Opening Git Sync

Click the Git Sync icon in the left sidebar, or use the keyboard shortcut if configured.

Getting Started

When you first open Git Sync, you'll see a welcome screen with two options:

Open Folder

Click Open Folder to select a local folder using the native file picker. If the folder is already a Git repository, Rostyman connects to it immediately. If not, you'll be prompted to initialize one.

Clone Repository

Click Clone Repository to clone an existing remote repo:

  1. Enter the repository URL (e.g., https://github.com/user/api-collections.git)
  2. Click the folder picker to choose where to clone it
  3. Click Clone

Rostyman will clone the repo and connect to it automatically.

Panel States

Not a Git Repository

If you select a folder that isn't a Git repo, Rostyman shows a warning with an Initialize Repository button. Click it to run git init in that folder.

Connected

Once connected to a valid Git repo, you'll see:

  • Repo path pill — shows the folder name (hover for full path)
  • Branch badge — shows the current branch
  • Disconnect button — detach from the repo and return to the welcome screen

Sections

The connected view has 5 collapsible sections:

1. Sync

The primary action area for exporting and importing collections.

  • Select a collection from the dropdown
  • Export to Repo — exports the selected collection (with folders, requests, variables, auth, and scripts) as .rostyman files into the connected folder
  • Import from Repo — reads .rostyman files from the folder and imports them back into Rostyman
  • Shows a Last synced timestamp after each sync

2. Changes

Shows the working tree status (like git status):

  • File list — each file shows its status badge (A = added, M = modified, D = deleted, R = renamed, ! = conflict)
  • Per-file diff — hover over a file and click the eye icon to see what changed (additions in green, deletions in red)
  • Per-file staging — hover over a file and click the + button to stage it individually
  • Stage All — stages all changed files at once
  • View All Diff — click Diff to see all changes in a single view
  • Commit — type a commit message and press Enter or click Commit

3. Branches

Manage Git branches:

  • View all local branches with the current branch highlighted
  • Checkout — click on any branch to switch to it
  • New Branch — create a new branch from the current HEAD

4. Push & Pull

Synchronize with remote repositories:

  • Pull — fetch and merge changes from the remote
  • Push — push local commits to the remote (auto-sets upstream if needed)
  • Remotes list — shows configured remotes (name + URL)
  • Add Remote — add a new remote (e.g., origin + URL)

5. History

View the commit log:

  • Shows the last 20 commits with hash, message, author, and relative time
  • Commit hashes are clickable badges

Persistence

  • The connected repo path is saved to settings — when you reopen Rostyman, it automatically reconnects to the last used repo
  • Click Disconnect to clear the saved path and return to the welcome screen

Requirements

  • Git must be installed and available in your system PATH
  • If Git is not found, a warning banner appears at the top of the panel

Handling Merge Conflicts

When you pull changes that conflict with local changes:

  1. The pull will show a Merge Conflicts banner with affected file list
  2. Conflicting files appear in the Changes list with a red (!) indicator
  3. Click any conflicting file to see the diff — additions in green, deletions in red
  4. Edit the files manually in your preferred editor to resolve conflicts
  5. Or click Abort Merge to cancel and revert to your pre-pull state
  6. After resolving, stage the files and commit to complete the merge

Authentication

If you see auth errors when pushing or pulling:

  • SSH: ensure your SSH key is added to ssh-agent and registered with your Git hosting provider
  • HTTPS: use a Personal Access Token (GitHub) or App Password (Bitbucket) — Git will prompt for credentials
  • Permission denied: check your remote URL and access permissions
  • Network errors: check your internet connection

Rostyman shows user-friendly error messages instead of raw Git output — each message includes guidance on how to fix the issue.

Tips

  • Review diffs before committing — click the eye icon on changed files to preview
  • Export your collections before making changes, then commit to create a checkpoint
  • Use branches to experiment with different API designs without affecting main
  • Push to a remote (GitHub, GitLab, Bitbucket) to share collections with your team
  • The .rostyman format is human-readable JSON — you can review diffs in any Git tool
  • Commit messages can contain any characters — backticks, newlines, and special characters are handled safely