Branching & Committing

Version control for your prompts

Moxn uses Git-like version control for prompts. This guide covers branching, committing, and managing versions in the web app.

Understanding Branches

A branch is an isolated workspace for changes:

• main: The default branch (like Git’s main/master)
• Feature branches: For experimentation and development

Creating Branches

1. Open branch selector

   Click the branch dropdown in the header.

2. Click Create Branch

   Select Create new branch.

3. Name your branch

   Use descriptive names:

   • feature-better-prompts
   • experiment-new-tone
   • fix-edge-case
4. Create

   Click Create to create and switch to the new branch.

Branch Selector

The branch dropdown shows:

• Current branch (with checkmark)
• All available branches
• Option to create new branch

Git Actions Menu

Click Git Actions to:

• Create a new branch
• Create a merge request
• View branch settings

Branch Naming

Good branch names:

• feature-multilingual-support
• experiment-shorter-responses
• fix-formatting-issue

Avoid:

• test
• my-branch
• changes

Switching Branches

To switch between branches:

1. Click the branch dropdown
2. Select the branch you want
3. Your view updates to show that branch’s content

Uncommitted changes stay on their branch when you switch.

Making Changes

Working State

Changes you make are saved as working state:

• Automatically saved as you edit
• Visible only on your current branch
• Not visible to others until you commit

What Counts as a Change

• Editing message content
• Adding or removing messages
• Modifying prompt settings
• Adding or removing properties
• Changing schemas

Committing Changes

When you’re ready to save a snapshot:

1. Review changes

   Check the Changes panel to see what’s modified.

2. Click Commit

   Click the Commit button.

3. Write a message

   Describe what you changed:

   • “Improved system prompt for clarity”
   • “Added context variable for search results”
   • “Fixed typo in greeting”
4. Confirm

   Click Commit to create the snapshot.

Commit Messages

Write clear commit messages:

Good:

• “Add multilingual greeting support”
• “Reduce system prompt length for faster responses”
• “Add search_results variable for RAG”

Avoid:

• “Updates”
• “Fixed stuff”
• ”.”

Viewing History

See the commit history for your branch:

1. Open commit selector

   Click the commit dropdown (shows current commit or “Working”).

2. Browse commits

   See all commits with:

   • Commit message
   • Timestamp
   • Changes summary
3. Select a commit

   Click to view that commit’s snapshot.

Commit History

The commit selector shows:

• Latest: Current working state
• Commit history: Past snapshots with messages and timestamps
• Click any commit to view that version

Viewing Past Versions

When viewing a past commit:

• Content is read-only
• You’re seeing exactly what was committed
• Make changes by switching back to “Working”

Comparing Versions

Compare different versions:

1. Select the first commit/version
2. Click Compare
3. Select the second commit/version
4. See a diff view showing changes

Rolling Back

To revert to a previous version:

1. View the commit

   Select the commit you want to restore.

2. Click Restore

   Click Restore to this version.

3. Confirm

   This creates new working state matching that commit.

4. Commit

   Commit the restored state with a message like “Revert to commit abc123”.

Merging Branches

To merge changes from one branch to another:

1. Switch to target

   Switch to the branch you want to merge INTO (e.g., main).

2. Click Merge

   Click Merge and select the source branch.

3. Review changes

   See what will be merged.

4. Resolve conflicts

   If there are conflicts, choose which version to keep.

5. Complete merge

   Click Merge to apply the changes.

Deployment Workflow

Development

1. Create feature branch
2. Make changes
3. Test in Studio
4. Commit when satisfied
5. Merge to main

Production

1. Get latest commit ID from main
2. Update code to use that commit ID
3. Deploy

In code:

# Production: pinned to commit
session = await client.create_prompt_session(
    prompt_id="...",
    commit_id="abc123def456"  # From your deployment config
)

Branch Protection

Consider protecting your main branch to prevent accidental changes.

Protection options:

• Require reviews before merging
• Require commit messages
• Lock branch from direct edits

Best Practices

Commit early and often

Small, frequent commits are easier to track and revert.

Use feature branches

Don’t experiment directly on main. Create branches.

Write good commit messages

Future you will thank present you.

Test before committing

Use the Studio to verify prompts work as expected.

Pin production to commits

Never use branch names in production. Always use commit IDs.

Next Steps

Versioning Concept

Deep dive into versioning

Working with Prompts

Access versions in code

Creating Tasks

Create new content

Telemetry

Track which versions are used