promptgit-local-prompt-version-control

name	PromptGit Local Prompt Version Control
description	Git for your prompts. Track every change, diff versions, rollback mistakes, never lose a good prompt again. All local, zero dependencies, works offline.
author	@TheShadowRose
version	1.0.2
tags	["version-control","prompts","diff","rollback","history","local"]
license	MIT

PromptGit Local Prompt Version Control

Git for your prompts. Track every change, diff versions, rollback mistakes, never lose a good prompt again. All local, zero dependencies, works offline.

---

Git for your prompts. Track every change, diff versions, rollback mistakes, never lose a good prompt again.

PromptGit gives you version control for AI prompts � system prompts, task prompts, templates, snippets. Save versions with notes, compare changes, tag your best ones, rollback bad edits, and search your entire prompt library. All local, zero dependencies, works offline.

---

The Problem

You're refining an AI prompt. You change a few words. Suddenly it doesn't work as well. What did you change? Can you get the old version back? You have no idea because you just overwrote it.

Or you have 47 variations of "good system prompt" scattered across text files, Google Docs, and Notion. Which one actually works? When was it last updated? Who knows.

What PromptGit Does

Version Control for Prompts

• Save versions with timestamps and notes
• Never lose a good prompt again
• See exactly what changed between versions
• Rollback to any previous version instantly

Organization & Search

• Categories (system, task, template, snippet)
• Tags (best, testing, production, deprecated)
• Search by keyword, tag, date range, or regex
• Find similar prompts automatically

Diff & Compare

• Side-by-side diffs between any two versions
• See exactly what changed (unified diff format)
• A/B comparison mode with notes field for results

Export & Share

• Export prompts as portable JSON
• Share with version history or current version only
• Import prompts from others
• Export to markdown for documentation

---

Quick Start

# Save your first prompt
echo "You are a helpful assistant..." | python3 prompt_git.py save assistant-v1 --note "First version"

# Make changes and save a new version
echo "You are a helpful and friendly assistant..." | python3 prompt_git.py save assistant-v1 --note "Added 'friendly'"

# See version history
python3 prompt_git.py versions assistant-v1

# Compare versions
python3 prompt_git.py diff assistant-v1 abc123 def456

# Rollback to a previous version
python3 prompt_git.py rollback assistant-v1 abc123

---

Usage Guide

Save a Prompt

# From stdin
echo "Your prompt here" | python3 prompt_git.py save my-prompt --note "Initial version"

# From file
python3 prompt_git.py save my-prompt --file prompt.txt --note "v2 with examples"

# With category and tags
python3 prompt_git.py save system-prompt \
  --category system \
  --tag best \
  --tag production \
  --note "Production system prompt"

View Prompts

# List all prompts
python3 prompt_git.py list

# Filter by category
python3 prompt_git.py list --category system

# Filter by tag
python3 prompt_git.py list --tag best

# Get current version
python3 prompt_git.py get my-prompt

# Get specific version
python3 prompt_git.py get my-prompt --version abc123

Version History

# See all versions
python3 prompt_git.py versions my-prompt

# Output:
? def456 � 2026-02-21T15:30:00 � Added examples [production]
  abc123 � 2026-02-21T10:00:00 � Initial version []

# The arrow (?) marks the current version

Diff Versions

# Compare two versions
python3 prompt_git.py diff my-prompt abc123 def456

# Output shows unified diff:
--- my-prompt (abc123)
+++ my-prompt (def456)
@@ -1,2 +1,3 @@
 You are a helpful assistant.
+Please provide examples.

Rollback

# Rollback to a previous version
python3 prompt_git.py rollback my-prompt abc123

# This makes abc123 the current version
# The newer version (def456) is not deleted, just not current

Tag Versions

# Tag a version
python3 prompt_git.py tag my-prompt abc123 best

# Tag meanings are up to you:
# - best: Best-performing version
# - testing: Under testing
# - production: Currently in production
# - deprecated: Don't use this
# - experimental: Risky/untested

Search

# Search content by keyword
python3 prompt_search.py search "helpful assistant"

# Search by tag
python3 prompt_search.py tag best

# Search by date range
python3 prompt_search.py date --start 2026-02-01 --end 2026-02-21

# Regex search
python3 prompt_search.py regex "assistant|helper"

# Find recent prompts
python3 prompt_search.py recent --limit 10

# Find similar prompts
python3 prompt_search.py similar my-prompt --threshold 0.6

# Repository stats
python3 prompt_search.py stats

Export & Import

# Export a prompt (current version only)
python3 prompt_export.py export my-prompt output.json

# Export with full history
python3 prompt_export.py export my-prompt output.json --history

# Export as markdown
python3 prompt_export.py export my-prompt output.md --markdown

# Export multiple prompts
python3 prompt_export.py export-multi bundle.json --names prompt1 prompt2 prompt3 --history

# Import a prompt
python3 prompt_export.py import shared-prompt.json

# Import and overwrite existing
python3 prompt_export.py import shared-prompt.json --overwrite

---

Use Cases

1. Prompt Engineering Iteration

Save every version as you refine your prompt. See what changed. Rollback if something breaks. Never lose a good version.

2. A/B Testing Prompts

Save version A, save version B, tag with results. Compare diffs to see exactly what changed between the winner and loser.

3. Team Prompt Sharing

Export your best prompts. Share the JSON file. Team imports it. Everyone has the same version, with full history if you want.

4. System Prompt Library

Organize all your system prompts by category. Tag the ones that work best. Search across all of them when you need inspiration.

5. Audit Trail

See when a prompt was changed, what changed, and what note was left. Perfect for compliance or debugging "when did this break?"

6. Template Management

Save reusable templates (e.g., "email writer", "code reviewer"). Pull them when needed. Never rewrite from scratch.

---

Storage Structure

~/.promptgit/
  index.json          # Prompt metadata (names, categories, tags, current versions)
  prompts/
    my-prompt/
      versions.json   # Version history for this prompt
      abc123.txt      # Content for version abc123
      def456.txt      # Content for version def456
    another-prompt/
      versions.json
      xyz789.txt

All human-readable, grep-friendly JSON and text files. No binary blobs.

---

Configuration

See config_example.json for reference constants and example values

# Change storage location
STORAGE_DIR = '/path/to/your/prompts'

# Define your own categories
DEFAULT_CATEGORIES = ['system', 'task', 'template', 'snippet', 'general']

# Suggested tags
SUGGESTED_TAGS = ['best', 'testing', 'production', 'deprecated']

# Similarity threshold for "find similar" search
SIMILARITY_THRESHOLD = 0.5

See config_example.json for all options.

---

Examples

Example 1: Refining a System Prompt

# Initial version
echo "You are a helpful assistant." | \
  python3 prompt_git.py save assistant --category system --note "v1"

# After testing, add more detail
echo "You are a helpful assistant. Provide concise answers." | \
  python3 prompt_git.py save assistant --note "v2: added conciseness"

# Hmm, too concise. Rollback
python3 prompt_git.py rollback assistant <v1-version-id>

# Try a different approach
echo "You are a helpful assistant. Provide detailed, thoughtful answers." | \
  python3 prompt_git.py save assistant --note "v3: detailed instead" --tag testing

# This one works! Tag it
python3 prompt_git.py tag assistant <v3-version-id> best
python3 prompt_git.py tag assistant <v3-version-id> production

Example 2: Sharing Prompts with a Team

# Export your best system prompt
python3 prompt_export.py export my-system-prompt team-prompt.json --history

# Teammate imports it
python3 prompt_export.py import team-prompt.json

# Now they have the full history and can see how it evolved
python3 prompt_git.py versions my-system-prompt

Example 3: Finding What Broke

# Prompt stopped working. When?
python3 prompt_git.py versions my-prompt

# Output shows versions with timestamps
# Pick two versions: one that worked, one that didn't
python3 prompt_git.py diff my-prompt <good-version> <broken-version>

# Diff shows exactly what changed
# Fix it and save a new version

---

What's Included

File	Purpose
prompt_git.py	Main version control (save, get, diff, rollback, tag)
prompt_search.py	Search and browse (keyword, tag, date, regex, similar)
prompt_export.py	Export/import (JSON, markdown, bundles)
config_example.json	Configuration template
README.md	This file
LIMITATIONS.md	What it doesn't do
LICENSE	MIT License

---

Requirements

• Python 3.7+
• Zero external dependencies (stdlib only)
• Works on Linux, macOS, Windows

---

Python API

Use PromptGit in your own scripts:

from prompt_git import PromptRepository

# Initialize repo
repo = PromptRepository(storage_dir='~/.promptgit')

# Save a prompt
version_id = repo.save(
    'my-prompt',
    'You are a helpful assistant.',
    note='Initial version',
    category='system',
    tags=['testing']
)

# Get current version
version = repo.get_version('my-prompt')
print(version.content)

# List all prompts
prompts = repo.list_prompts(category='system')

# Diff two versions
diff = repo.diff('my-prompt', version_a_id, version_b_id)
print(diff)

---

quality-verified

---

FAQ

Q: Does it sync across devices?
A: No. It's local-only. But you can export/import to share manually, or put ~/.promptgit in a synced folder (Dropbox, Git, etc.).

Q: Can I use it with Git?
A: Yes! The storage directory is just JSON and text files. You can version the whole thing with Git if you want meta-version-control.

Q: What about collaborative editing?
A: Not built-in. Export/import is the collaboration model. For real-time collab, use a shared folder or Git.

Q: Does it work with images or multimodal prompts?
A: Text only. If your multimodal prompt has a text component, you can save that.

Q: How do I delete a prompt?
A: Currently, no delete command (by design � version control shouldn't delete easily). You can manually delete the folder in ~/.promptgit/prompts/.

---

License

MIT � See LICENSE file.

---

Author

Shadow Rose

Built for AI users who are tired of losing good prompts to accidental overwrites and bad edits.

---

?? Disclaimer

This software is provided "AS IS", without warranty of any kind, express or implied.

USE AT YOUR OWN RISK.

• The author(s) are NOT liable for any damages, losses, or consequences arising from the use or misuse of this software � including but not limited to financial loss, data loss, security breaches, business interruption, or any indirect/consequential damages.
• This software does NOT constitute financial, legal, trading, or professional advice.
• Users are solely responsible for evaluating whether this software is suitable for their use case, environment, and risk tolerance.
• No guarantee is made regarding accuracy, reliability, completeness, or fitness for any particular purpose.
• The author(s) are not responsible for how third parties use, modify, or distribute this software after purchase.

By downloading, installing, or using this software, you acknowledge that you have read this disclaimer and agree to use the software entirely at your own risk.

DATA DISCLAIMER: This software processes and stores data locally on your system. The author(s) are not responsible for data loss, corruption, or unauthorized access resulting from software bugs, system failures, or user error. Always maintain independent backups of important data. This software does not transmit data externally unless explicitly configured by the user.

---

Support & Links

?? Bug Reports	[e-mail]
? Ko-fi	ko-fi.com/theshadowrose
?? Gumroad	shadowyrose.gumroad.com
?? Twitter	@TheShadowyRose
?? GitHub	github.com/TheShadowRose
?? PromptBase	promptbase.com/profile/shadowrose

Built with OpenClaw � thank you for making this possible.

---

??? Need something custom? Custom OpenClaw agents & skills starting at $500. If you can describe it, I can build it. ? Hire me on Fiverr

Security Notes

• Input sanitization enforced (v1.0.2+): Prompt names are validated before use as filesystem path components. Names containing .., /, , or null bytes are rejected with a ValueError. The resolved path is verified to stay within the repository directory. This prevents path traversal via crafted prompt names or malicious import files.
• Import safety: When importing JSON exports, the name field is sanitized using the same validation before any file operations occur. Do not import JSON from untrusted sources.
• Concurrent access: No file locking is implemented. Avoid running multiple PromptGit processes against the same repository simultaneously.