// blog / guide

How to version prompts in git (and where git falls short)

If your prompts are in a repo, git already gives you history, diff, review and rollback. Here is a layout that makes those features useful for prompts, and an honest list of what it does not cover.

1. One file per prompt

This is also what OpenAI's own prompting guide recommends for production prompts: keep them in code-managed, versioned files and use git history, PR review and release tags to review, ship, compare and roll back changes (read October 16, 2026).

Keep prompts as plain files, not strings buried in code. A change then shows up as a small, readable diff.

layout

prompts/
  code-review.md
  changelog-entry.md
  commit-message.md

prompts/code-review.md

---
name: code-review
tags: review
---
Review this diff for bugs only. Quote the line for every finding.
{{diff}}

Writing variables as {{name}} keeps them visible in diffs. A frontmatter block (name, tags) is optional, but it makes the files easy to load from any language.

2. Commit the reason, not just the change

The diff already shows what changed. The commit message is the only place left for why.

terminal

git add prompts/code-review.md
git commit -m "code-review: quote the line for each finding

Reviews were vague (\"consider error handling\") with no location."

A fixed shape for these notes helps; see the prompt changelog template.

3. Read and compare the history

terminal

git log --oneline -- prompts/code-review.md       # every commit that touched it
git log -p -- prompts/code-review.md              # with the diffs
git diff <old> <new> -- prompts/code-review.md    # any two commits
git diff --word-diff <old> <new> -- prompts/code-review.md

Prompts are prose, so a line diff overstates small edits: one added sentence marks the whole line as changed. --word-diff marks only the words that moved. More on that in how to diff two prompts.

4. Tag what you ship

If an application loads these files, tag the commit it runs, so "which prompt was live last Tuesday" has an answer.

terminal

git tag prompts-2026-10-16
git push origin prompts-2026-10-16

5. Roll back without rewriting history

terminal

git restore --source=<commit> -- prompts/code-review.md
git commit -am "code-review: back to the wording from <commit>"

Restoring the file from an old commit and committing it adds a new commit; the version you undid stays in history. Avoid git reset --hard for this, because it throws away the record of what you tried.

Where git falls short for prompts

Prompts outside a repo. The ones you type into a chat window or a terminal have no file and no history.
Several repos. The same prompt copied into three repos drifts into three prompts.
People who do not use git. A reviewer who only wants to read or tweak wording should not need a clone.
No notion of a prompt. Git sees text files. Finding "the prompt I used for changelogs" is a grep.

If those describe you, a library with history covers them. With the ple CLI the local version is two commands, ple save and ple log, with no account, and ple export can write your prompts back out as an AGENTS.md section or a skill file so they can still live in a repo. The general picture is in prompt version control, and the trade-offs against a plain folder in dotfiles and Gists for prompts.

FAQ

Should prompts live in the same repo as the code?

Production prompts, yes: they change behavior, so they should go through the same review and rollback as code. Scratch prompts you reuse across projects fit better in a separate place.

What format should a prompt file use?

Plain Markdown with a small frontmatter block (name, optional description and tags) is easy to read, diff and load from any language. Write variables as {{name}} so the placeholders are visible in diffs.

How do I see what changed between two prompt versions in git?

Use git diff <old> <new> -- prompts/file.md. Add --word-diff when only a few words changed, because a line-based diff marks the whole line as different.

How do I roll a prompt back in git without rewriting history?

Restore the file from the older commit with git restore --source=<commit> -- <file> and commit the result. The bad version stays in history, so you can see what you undid.

When is git not enough for prompts?

When prompts are used outside a repository (in a chat window, a terminal, an agent), are shared across several repositories, or are edited by people who do not use git.

Try it before you sign up

Not in a repo right now? The same save, diff and rollback flow runs in your browser with no account, and nothing is sent to our servers.

Try it in your browser Or create a free account