Git Sync

Istek includes built-in Git integration for version controlling your API collections, enabling collaboration and change tracking.

Overview

Git Sync allows you to:

• Version control your collections in a Git repository
• Track changes to requests, environments, and variables
• Commit and push changes to remote repositories
• View commit history and file diffs
• Create and switch branches

Setting Up Git Sync

1. Configure Sync Path

First, configure a sync path for your workspace:

1. Click the workspace name in the sidebar
2. Select Workspace Settings
3. Set the Sync Path to a local directory (e.g., ~/projects/my-api-collections)
4. Click Save

The sync path is where Istek exports your collections as JSON files.

2. Initialize Git Repository

Once the sync path is configured:

1. Look for the Git Settings button at the bottom of the sidebar
2. Click it to open the Git menu
3. Click Initialize Git Repo

This creates a new Git repository in your sync path.

Existing Repository

If your sync path already contains a Git repository, Istek will automatically detect it.

Git Status Bar

The Git status bar appears at the bottom of the sidebar when sync is enabled. It shows:

Element	Description
Branch name	Current Git branch (e.g., main)
Changes badge	Number of uncommitted changes (yellow)

Click the status bar to open the Git menu.

Committing Changes

When you modify collections, environments, or variables, Istek automatically exports them to your sync path.

Making a Commit

1. Click the Git status bar or branch name
2. Select Commit Changes (requires uncommitted changes)
3. In the Commit Modal:
   • Review the file tree of changes
   • Select/deselect files to include
   • Enter a commit message
4. Click Commit or Commit & Push

File Status Indicators

Status	Color	Description
Untracked	Green	New file not yet tracked
Modified	Yellow	File has been changed
Deleted	Red	File has been removed
Renamed	Blue	File has been renamed

Selecting Files

The commit modal shows a tree view of changed files:

• Select All / Deselect All: Toggle all files at once
• Folder checkbox: Toggle all files in a folder
• File checkbox: Toggle individual files
• Files are grouped by folder for easy navigation

Viewing History

Opening History

1. Click the Git status bar
2. Select View History

History Modal

The history modal has two panels:

Left Panel - Commit List:

• Shows all commits on the current branch
• Displays commit message, short hash, and relative time
• Click a commit to see its changed files

Right Panel - Diff View:

• Shows file-by-file changes
• Syntax-highlighted diff with line numbers
• Green lines = additions, Red lines = deletions

Navigating History

1. Select a commit from the left panel
2. Click a file to view its diff
3. Scroll through the diff to see all changes

Branch Management

Creating a Branch

1. Click the Git status bar
2. Select New Branch
3. Enter the branch name (e.g., feature/new-endpoints)
4. Click Create Branch

Branch names can include:

• Letters (a-z, A-Z)
• Numbers (0-9)
• Hyphens (-)
• Underscores (_)
• Forward slashes (/)

Switching Branches

1. Click the Git status bar
2. Select a branch from the Branches list
3. The current branch shows a checkmark

Uncommitted Changes

Switch branches carefully if you have uncommitted changes. Consider committing or stashing changes first.

Remote Repository

Pushing Changes

After committing, you can push to a remote:

1. In the Commit Modal, click Commit & Push
2. Or commit first, then push separately via command line

Setting Up Remote

If your repository doesn't have a remote configured:

cd ~/projects/my-api-collections
git remote add origin https://github.com/username/repo.git

Once configured, Istek shows "Remote configured" in the commit modal.

Pulling Changes

Currently, pulling changes from remote is done via command line:

cd ~/projects/my-api-collections
git pull origin main

Then restart Istek or switch workspaces to reload the changes.

Auto-Sync

Istek automatically exports collections to the sync path when:

• A collection is saved
• A request is saved
• Collections are imported
• Environments or variables are modified

This ensures your Git repository always has the latest changes ready to commit.

Exported File Structure

When synced, your workspace exports to:

sync-path/
├── collections/
│   ├── my-api.json
│   └── another-api.json
├── environments.json
└── variables.json

Collection Files

Each collection is saved as a separate JSON file:

{
  "name": "My API",
  "requests": [
    {
      "name": "Get Users",
      "method": "GET",
      "url": "{{baseUrl}}/users",
      "headers": [...],
      "body": null
    }
  ]
}

Best Practices

Meaningful Commits

Write descriptive commit messages that explain what changed and why.

Branch Strategy

Use feature branches for major changes:

• feature/auth-endpoints
• fix/header-bug
• refactor/variable-names

Regular Commits

Commit frequently to maintain a clear history of changes.

Review Before Push

Use the history view to review changes before pushing to a shared repository.

Troubleshooting

"Not a Git Repository"

The sync path doesn't contain a Git repository. Click Initialize Git Repo to create one.

"No Uncommitted Changes"

All changes have been committed. Make changes to collections or variables to enable committing.

"Branch Creation Failed"

Ensure:

• Branch name is valid (no spaces or special characters)
• You have at least one commit (empty repos need an initial commit)

"Push Failed"

Check that:

• Remote is configured (git remote -v)
• You have push access to the repository
• Your credentials are configured

Changes Not Appearing

If exported changes don't appear in Git status:

1. Check that the sync path is correct
2. Ensure auto-sync is working by saving a collection
3. Try refreshing the Git status (close and reopen the Git menu)

Limitations

• Selective staging: Currently commits all selected files together
• Pull UI: Pull operations require command line
• Merge conflicts: Must be resolved via command line
• Stashing: Not available in UI, use command line if needed