Skip to main content
Opal Editor includes full-featured git integration powered by isomorphic-git, providing version control directly in your browser without any backend dependencies.

​
Git Features

Opal’s git implementation supports:
  • Initialize repositories
  • Commit changes automatically
  • Create and switch branches
  • Push and pull from remotes
  • Merge branches with conflict resolution
  • View commit history
  • Git conflict editor with visual resolution
  • GitHub authentication and sync

​
Repository Initialization

Every workspace can have an optional git repository:
1

Automatic initialization

When you connect a GitHub remote, git is automatically initialized
2

Default branch

The default branch is set to main (configurable)
3

Initial commit

Existing files are committed with message “Initial commit”
Git repositories are stored in a .git directory within the workspace, just like regular git

​
Commits and Changes

Opal automatically manages commits for you:

​
Auto-Commit Behavior

Changes are automatically committed in these scenarios:
  • Before branch switch: Saves work before switching branches
  • Before push: Ensures all changes are committed before pushing
  • Before pull: Commits local changes before pulling remote updates
  • Before checkout: Saves changes before checking out a different ref
All auto-commits use the message prefix opal / to distinguish them from manual commits.
You can also create manual commits:
// Example: Create a commit with custom message
await workspace.playbook.addAllCommit({
  message: "Update homepage content",
  filepath: "." // Stage all files
});

​
Git Status

View the current repository state:
  • Uncommitted changes: Files modified since last commit
  • Current branch: Active branch name
  • Latest commit: Most recent commit hash and message
  • Merge state: Whether a merge is in progress
Access git status from the Git modal (click the git icon in the sidebar)

​
Branches

Manage branches directly from Opal:
Create a new branch from the current commit:
1

Open git panel

Click the git icon in the sidebar
2

Click New Branch

Enter a branch name
3

Switch to branch

Optionally checkout the new branch immediately
If a branch name already exists, Opal appends a number (e.g., feature-1, feature-2)

​
Remote Repositories

Connect your workspace to GitHub:
1

Authenticate with GitHub

Use OAuth device flow or GitHub App authentication
2

Add remote

Configure remote URL and authentication
3

Choose repository

Select an existing repo or create a new one

​
GitHub Authentication

Opal supports multiple authentication methods:
Best for: Public use, shared computers
  • No redirect required
  • Token stored in browser
  • Easy to revoke from GitHub settings
  • Works with 2FA
Best for: Advanced users, automation
  • Full control over permissions
  • Stored securely in browser
  • Can be scoped to specific repositories
  • Requires manual token creation

​
CORS Proxy

Git operations use a CORS proxy for browser compatibility:
  • Default proxy: https://cors.isomorphic-git.org
  • Configurable per remote
  • Required for browser-based git operations
  • Can be self-hosted for privacy
The CORS proxy only proxies git protocol traffic, not your file content

​
Push and Pull

​
Pushing Changes

Push commits to your GitHub repository:
1

Commit changes

Opal auto-commits pending changes before push
2

Authenticate

Uses stored GitHub credentials
3

Push to remote

Pushes current branch to remote (e.g., origin/main)
Force push when needed (use with caution):
await workspace.playbook.push({
  remote: "origin",
  force: true
});
Force pushing rewrites remote history. Only use when necessary and you understand the consequences.

​
Pulling Changes

Sync remote changes to your local workspace:
1

Fetch from remote

Downloads new commits from GitHub
2

Merge changes

Automatically merges remote commits with local changes
3

Resolve conflicts

If conflicts occur, use the conflict resolution editor
Pull operations use --no-ff (no fast-forward) to preserve commit history

​
Merge and Conflicts

​
Merging Branches

Merge one branch into another: 
await workspace.repo.merge({
  from: "feature-branch",
  into: "main"
});
The merge process:
  1. Resolves branch names to commit OIDs
  2. Attempts automatic merge
  3. If conflicts occur, enters merge mode
  4. User resolves conflicts manually
  5. Creates merge commit when resolved

​
Conflict Resolution

When merge conflicts occur:
1

Conflict detection

Opal identifies files with conflicts and marks them
2

Open conflict editor

Files with conflicts automatically open in source mode
3

Visual resolution

Use the conflict resolution UI to choose changes
4

Complete merge

After resolving all conflicts, complete the merge commit
The conflict editor shows:
  • Ours: Your local changes (current branch)
  • Theirs: Incoming changes (merging branch)
  • Accept buttons for each section
  • Manual edit capability

​
Conflict Markers

Conflicts appear in source mode with standard git markers: 
<<<<<<< HEAD
Your local content
=======
Incoming remote content
>>>>>>> branch-name
Enable the Git Conflicts Editor toggle in the toolbar to use visual conflict resolution tools

​
Commit History

View and navigate commit history:
  • Recent commits: Last 20 commits by default
  • Commit details: Author, date, message, hash
  • Checkout commits: Time-travel to any commit
  • Create branches: Start new branch from any commit

​
Advanced Operations

​
Reset Operations

Reset operations can lose uncommitted changes. Use with caution.
Reset to a specific commit, discarding all changes:
await workspace.playbook.resetHard({ ref: "HEAD~1" });
Move branch pointer without changing files:
await workspace.playbook.resetSoftParent();

​
Detached HEAD

When you checkout a commit (not a branch):
  • You enter “detached HEAD” state
  • Changes can be committed but aren’t on any branch
  • Create a new branch to save your work
  • Return to previous branch to exit detached state
Opal remembers your previous branch location in .git/PREV_BRANCH

​
Best Practices

Opal’s auto-commit system ensures you never lose work:
  • Changes are committed before risky operations
  • Edit history provides additional safety net
  • Push to GitHub regularly for remote backup
Organize work with branches:
  • Keep main stable
  • Create feature branches for new work
  • Merge back when complete
  • Delete old branches to stay organized
When collaborating or working across devices:
  • Pull before starting work
  • Push when you finish a session
  • Resolve conflicts promptly
  • Communicate with collaborators

Build docs developers (and LLMs) love

Get started for freeTalk to us