A tool to generate and apply git diffs using LLMs
Project description
GPTDiff
Table of Contents
- Quick Start
- Example Usage
- Basic Usage
- Simple Command Line Agent Loops
- Why Choose GPTDiff?
- Core Capabilities
- Get Started
- Command Line Usage
🚀 Create and apply diffs with AI
Modify your project using plain English.
More documentation at gptdiff.255labs.xyz
Quick Start
- Install GPTDiff
Example Usage of gptdiff
Apply a Patch Directly
gptdiff "Add button animations on press" --apply
✅ Successfully applied patch
Generate a Patch File
gptdiff "Add API documentation" --call
🔧 Patch written to diff.patch
Generate a Prompt File Without Calling LLM
gptdiff "Improve error messages"
📄 LLM not called, written to prompt.txt
Basic Usage
cd myproject
gptdiff 'add hover effects to the buttons'
Generates a prompt.txt file containing the full request. Copy and paste its content into your preferred LLM (e.g., ChatGPT) for further experimentation.
Simple command line agent loops
while
do
gptdiff "Add missing test cases" --apply
done
Requires reasoning model
Why Choose GPTDiff?
- Describe changes in plain English
- AI gets your whole project
- Auto-fixes conflicts
- Keeps code functional
- Fast setup, no fuss
- You approve every change
- Costs are upfront
Core Capabilities
⚡ CLI Excellence
- Target Specific Files - Change just what you need
- Live Updates - See changes as they're made
- Try Before Applying - Test changes safely first
- Clear Pricing - Know costs upfront
- Preview Changes - See what will change with
--call
- Fix Mistakes - Automatic error correction
✨ Magic Diff Generation
gptdiff "Convert class components to React hooks" --model deepseek-reasoner
- Full project context awareness
- Cross-file refactoring support
- Automatic conflict prevention
🧠 Smart Apply System
Git-native Workflow:
# 1. Apply AI-generated changes
gptdiff "Improve error handling" --apply
# 2. Review each change interactively
git add -p
# 3. Commit or discard
git commit -m "Enhanced error handling"
git reset --hard # To undo all changes
gptdiff "Refactor authentication to use OAuth 2.0" --apply
✅ Successfully applied complex changes across 5 files
Get Started
Installation
Requires Python 3.8+. Install from PyPI:
pip install gptdiff
pip install tiktoken # For token counting
Development install (no pip package yet)
python setup.py install
Configuration
First sign up for an API key at https://nano-gpt.com/api and generate your key. Then configure your environment:
Linux/MacOS
export GPTDIFF_LLM_API_KEY='your-api-key'
# Optional: For switching API providers
export GPTDIFF_MODEL='deepseek-reasoner' # Set default model for all commands
export GPTDIFF_LLM_BASE_URL='https://nano-gpt.com/api/v1/'
Windows
set GPTDIFF_LLM_API_KEY=your-api-key
rem Optional: For switching API providers
set GPTDIFF_MODEL=deepseek-reasoner
set GPTDIFF_LLM_BASE_URL=https://nano-gpt.com/api/v1/
The default base URL points to nano-gpt.com's API. Supported models can be specified with:
gptdiff 'your prompt' --model deepseek-reasoner
# Default model can be set via GPTDIFF_MODEL environment variable
OpenAI will not be called unless you specify --call
or --apply
Prevent files being appended to the prompt by adding them to .gitignore
or .gptignore
Command Line Usage
gptpatch: Apply Diffs Directly
gptpatch
is a companion command-line tool to GPTDiff that applies unified diffs directly to your project.
Usage
Apply a diff provided directly:
gptpatch --diff "<diff text>"
Or apply a diff from a file:
gptpatch path/to/diff.patch
Options
- --project-dir: Specify the target project directory (default: current directory)
- --model: (Optional) Specify the LLM model for advanced conflict resolution
- --max_tokens: (Optional) Define the maximum token count for LLM responses during patch application
- --nobeep: Disable the completion beep notification
Workflow
gptpatch
first attempts to apply the diff using standard patch logic. If that fails, it automatically falls back to a smart apply mechanism that leverages AI-powered conflict resolution.
For more details, see the gptpatch documentation on our docs site.
After installing the package, use the gptdiff
command in your terminal. Change directory into your codebase and run:
gptdiff '<user_prompt>'
any files that are included in .gitignore are ignored when generating prompt.txt.
Specifying Additional Files
You may supply extra files or directories as arguments to the gptdiff
command. If omitted, the tool defaults to the current working directory, excluding those matching ignore rules.
Autopatch Changes
You can also call openai and automatically apply the generated git diff with the --apply
flag:
gptdiff '<user_prompt>' --apply
Dry-Run Validation
Preview changes without applying them by omitting the --apply
flag when using --call
:
gptdiff "Modernize database queries" --call
i️ Diff preview generated - review changes before applying
This often generates incorrect diffs that need to be manually merged.
Smart Apply
For robust handling of complex changes, use smartapply
. It processes each file’s diff individually via the LLM, ensuring nuanced conflict resolution.
Completion Notification
Use the --nobeep
option to disable the default completion beep:
gptdiff '<user_prompt>' --nobeep
Local API Documentation
Preview API docs locally using MkDocs:
pip install .[docs]
mkdocs serve
Open http://localhost:8000 to view the documentation
Python API
Integrate GPTDiff directly into your Python workflows:
from gptdiff import generate_diff, smartapply
import os
os.environ['GPTDIFF_LLM_API_KEY'] = 'your-api-key'
# Create files dictionary
files = {"main.py": "def old_name():\n print('Need renaming')"}
# Generate transformation diff using an environment string built from the files dictionary
environment = ""
for path, content in files.items():
environment += f"File: {path}\nContent:\n{content}\n"
diff = generate_diff(
environment=environment,
goal='Rename function to new_name()',
model='deepseek-reasoner'
)
# Apply changes safely using the files dict
updated_files = smartapply(diff, files)
print("Transformed codebase:")
print(updated_files["main.py"])
Batch Processing Example:
from gptdiff import generate_diff, smartapply
files = load_your_codebase() # Dict of {path: content}
transformations = [
"Add python type annotations",
"Convert string formatting to f-strings",
"Update deprecated API calls"
]
for task in transformations:
files = smartapply(generate_diff(build_environment(files), task), files)
Integration Note: GPTDiff leverages the AI Agent Toolbox for seamless tool usage across AI models and frameworks, making it ideal for both single responses and complex agent workflows.
Core Functions
-
generate_diff(environment: str, goal: str, model: str) -> str
Generates a git diff implementing the requested changesmodel
parameter defaults toGPTDIFF_MODEL
environment variable -
smartapply(diff_text: str, environment_str: str, model: str) -> str
Applies complex diffs while preserving file context
Testing
To run the test suite:
pip install -e .[test]
pytest tests/
This will execute all unit tests verifying core diff generation and application logic.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
File details
Details for the file gptdiff-0.1.31.tar.gz
.
File metadata
- Download URL: gptdiff-0.1.31.tar.gz
- Upload date:
- Size: 31.0 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/6.1.0 CPython/3.9.21
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | 52fe293ace2df3820ad3c4e1b5dedaf75e28304e2a54b920bb798575c12dbdee |
|
MD5 | 9fcdd3321412b3ddc4a60e9b9f92ee5e |
|
BLAKE2b-256 | b2468827a32a2cfd30af3d6b7f25fc031398666c80caee6c13f5a4735cd94050 |
File details
Details for the file gptdiff-0.1.31-py3-none-any.whl
.
File metadata
- Download URL: gptdiff-0.1.31-py3-none-any.whl
- Upload date:
- Size: 20.5 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/6.1.0 CPython/3.9.21
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | 937318c0b31cda3ce2863e540d840f591df0f4f1ba57d8bee10dbeea2398b591 |
|
MD5 | 1c8934fb77e13f64bc6b931260ab7b0a |
|
BLAKE2b-256 | 01c5c0fc8ebfef8c6674d03dab8f38c923431c83d6bd180a339b74cc4fcafee0 |