Technical • 6 min read

XML Diff Format Explained

• Understanding AI Code Changes

The XML diff format is RepoPrompter's standardized way to receive and apply code changes from AI assistants. Understanding this format helps you work more effectively with AI-generated modifications and troubleshoot issues when they arise.

Why XML Diff Format?

Traditional diff formats work well for version control, but they're not ideal for AI-human collaboration:

  • Ambiguity: Line-based diffs can be ambiguous when files change significantly
  • Context Loss: Traditional diffs lose semantic meaning of changes
  • Error Prone: Manual application of complex diffs is prone to mistakes
  • Limited Scope: Difficult to express file creation, deletion, and moves

XML diff format provides a structured, unambiguous way to express exactly what changes should be made to your codebase.

Basic XML Diff Structure

Every XML diff follows this basic structure:

<root>
  <file name="path/to/file1.js">
    <replace>
      // Complete new file content goes here
    </replace>
  </file>
  
  <file name="path/to/file2.py">
    <replace>
      # Complete new file content goes here  
    </replace>
  </file>
</root>

💡 Key Points:

  • The `<root>` element is optional but recommended
  • Each `<file>` element must have a `name` attribute with the file path
  • The `<replace>` element contains the complete new file content
  • File paths are relative to the repository root

Common Operations

1. Modifying Existing Files

The most common operation is updating existing files:

<file name="src/components/Button.jsx">
  <replace>
import React from 'react';

const Button = ({ children, onClick, variant = 'primary' }) => {
  const baseClasses = 'px-4 py-2 rounded font-medium focus:outline-none';
  const variantClasses = {
    primary: 'bg-blue-500 hover:bg-blue-600 text-white',
    secondary: 'bg-gray-500 hover:bg-gray-600 text-white'
  };

  return (
    <button 
      className={`${baseClasses} ${variantClasses[variant]}`}
      onClick={onClick}
    >
      {children}
    </button>
  );
};

export default Button;
  </replace>
</file>

2. Creating New Files

New files are created the same way as modifications:

<file name="src/hooks/useLocalStorage.js">
  <replace>
import { useState, useEffect } from 'react';

export function useLocalStorage(key, initialValue) {
  const [storedValue, setStoredValue] = useState(() => {
    try {
      const item = window.localStorage.getItem(key);
      return item ? JSON.parse(item) : initialValue;
    } catch (error) {
      console.log(error);
      return initialValue;
    }
  });

  const setValue = (value) => {
    try {
      setStoredValue(value);
      window.localStorage.setItem(key, JSON.stringify(value));
    } catch (error) {
      console.log(error);
    }
  };

  return [storedValue, setValue];
}
  </replace>
</file>

3. Multiple File Changes

Complex refactors often involve multiple files:

<root>
  <file name="src/utils/api.js">
    <replace>
// Updated API utility with error handling
export const apiClient = {
  async get(url) {
    // Implementation here
  }
};
    </replace>
  </file>
  
  <file name="src/components/UserProfile.jsx">
    <replace>
// Updated component using new API utility
import { apiClient } from '../utils/api';
// Rest of component...
    </replace>
  </file>
</root>

Best Practices for AI Prompts

To get properly formatted XML diffs from AI assistants:

1. Be Explicit About Format

Please provide your suggested changes in XML diff format:

<file name="path/to/file">
  <replace>
    // complete file content
  </replace>
</file>

Make sure to include complete file contents, not just the changes.

2. Request Complete Content

Always ask for complete file contents, not partial updates:

❌ Don't ask for:

"Show me just the function that needs to change"

✅ Instead ask for:

"Provide the complete updated file content in XML diff format"

3. Specify File Paths Clearly

Include file context in your prompts to ensure correct paths:

The files in this request are:
- src/components/Header.jsx (main component)
- src/components/Header.module.css (styles)
- src/components/__tests__/Header.test.js (tests)

Please update these files and use the exact paths shown above in your XML diff response.

Common Issues and Solutions

1. Incorrect File Paths

❌ Problem:

<file name="Header.jsx">

✅ Solution:

<file name="src/components/Header.jsx">

2. Missing Replace Tags

❌ Invalid Format:

<file name="src/utils.js">
  // File content directly here - WRONG
</file>

✅ Correct Format:

<file name="src/utils.js">
  <replace>
    // File content goes inside replace tags
  </replace>
</file>

3. Encoding Issues

Special characters in code can cause XML parsing issues:

  • < and >: Use `&lt;` and `&gt;` in JSX or generic types
  • &: Use `&amp;` for logical AND operations
  • Quotes: Use `&quot;` for nested quotes if needed

RepoPrompter's Processing

When you paste an XML diff into RepoPrompter, here's what happens:

  1. XML Parsing: The diff is parsed and validated for correct structure
  2. Path Validation: File paths are checked for security (no traversal attacks)
  3. Preview Generation: A visual diff shows what will change
  4. File Backup: Original files are backed up before modification
  5. Atomic Application: All changes are applied together or rolled back on error

🔒 Security Note:

RepoPrompter validates all file paths to prevent directory traversal attacks. Files outside your project directory cannot be modified through XML diffs.

Advanced Use Cases

1. Configuration Files

XML diffs work perfectly for configuration updates:

<file name="package.json">
  <replace>
{
  "name": "my-project",
  "version": "1.0.0",
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "test": "vitest"
  },
  "dependencies": {
    "react": "^18.2.0",
    "vite": "^4.0.0"
  }
}
  </replace>
</file>

2. Documentation Updates

Markdown files can be updated just like code:

<file name="README.md">
  <replace>
# Project Title

Updated documentation with new features and examples.

## Installation

```bash
npm install
```

## Usage

Updated usage instructions...
  </replace>
</file>

Conclusion

Understanding the XML diff format enables more effective collaboration with AI assistants. By following the best practices outlined here, you can ensure smooth, error-free application of AI-generated code changes to your projects.

Ready to start using XML diffs in your workflow? Download RepoPrompter and streamline your AI-assisted development process.