Diff Generation

The diff generation feature allows you to compare two versions of your codebase and see what has changed. This is particularly useful for code reviews, tracking changes over time, or understanding what changed between different versions of your project.

Overview

When you run promptprep with the --diff option, it will:

  1. Process the current state of your codebase

  2. Compare it with a previous output file

  3. Generate a diff showing what has changed

  4. Highlight additions, deletions, and modifications

This provides a clear view of what has changed between two points in time.

Basic Usage

To generate a diff:

promptprep --diff PREV_FILE [other options]

Where PREV_FILE is the path to a previous output file generated by promptprep.

Example:

# First, generate a baseline
promptprep -d ./my_project -o baseline.txt

# Later, after making changes, generate a diff
promptprep -d ./my_project --diff baseline.txt -o changes.txt

The changes.txt file will contain a diff showing what has changed since the baseline.

Diff Context

By default, promptprep shows 3 lines of context around each change. You can adjust this with the --diff-context option:

promptprep --diff baseline.txt --diff-context 5 -o changes.txt

This will show 5 lines of context around each change, making it easier to understand the surrounding code.

Diff Output

By default, the diff is included in the main output file. You can specify a separate file for the diff using the --diff-output option:

promptprep -d ./my_project -o current.txt --diff baseline.txt --diff-output diff.txt

This will: - Save the current state to current.txt - Save the diff to diff.txt

Diff Format

The diff format follows the unified diff format, which is widely used in tools like Git:

--- baseline.txt
+++ current.txt
@@ -10,7 +10,7 @@
 def hello():
     print("Hello, world!")

-def old_function():
-    return "Old implementation"
+def new_function():
+    return "New implementation"

 if __name__ == "__main__":
     hello()

In this format: - Lines starting with - indicate deletions - Lines starting with + indicate additions - Lines without + or - provide context

Combining with Other Features

Diff generation works well with other promptprep features:

With Incremental Processing

Track changes efficiently by combining diff generation with incremental processing:

promptprep -d . --incremental --diff baseline.txt -o changes.txt

This will: - Only process files that have changed since the baseline - Generate a diff showing what has changed

With Different Output Formats

Diff generation works with all output formats:

promptprep -d . --diff baseline.txt --format markdown -o changes.md
promptprep -d . --diff baseline.txt --format html -o changes.html

The diff will be formatted according to the selected output format.

Advanced Use Cases

Code Reviews

Use diff generation to prepare code for review:

# Generate a baseline from the main branch
git checkout main
promptprep -d . -o main_branch.txt

# Switch to the feature branch and generate a diff
git checkout feature-branch
promptprep -d . --diff main_branch.txt --format highlighted -o review.html

This creates a highlighted HTML file showing what changed in the feature branch.

Release Notes

Generate release notes by comparing versions:

# Generate a baseline for version 1.0
promptprep -d . -o v1.0.txt

# Later, for version 1.1, generate a diff
promptprep -d . --diff v1.0.txt --format markdown -o v1.1_changes.md

The v1.1_changes.md file can serve as a basis for release notes.

Continuous Integration

In a CI/CD pipeline, generate diffs for pull requests:

# In your CI script
git checkout main
promptprep -d . -o main_branch.txt

git checkout $PR_BRANCH
promptprep -d . --diff main_branch.txt -o pr_changes.txt

Best Practices

  1. Consistent Options: Use the same promptprep options when generating the baseline and the diff to ensure a fair comparison.

  2. Version Control: Store baseline outputs for important versions or releases.

  3. Combine with Filtering: Use -x, --extensions and -e, --exclude-dirs to focus on relevant files.

  4. HTML for Readability: Use --format highlighted for the most readable diffs, especially for code reviews.

  5. Context Adjustment: Adjust the context lines with --diff-context based on your needs (more for complex code, less for simple changes).

Troubleshooting

If diff generation isn’t working as expected:

  1. Check Baseline File: Ensure the baseline file exists and was generated by promptprep.

  2. Consistent Options: Make sure you’re using the same options for both runs.

  3. File Paths: If you’ve moved files, the diff might show them as deleted and added rather than modified.

  4. Large Diffs: For very large diffs, consider using incremental processing or focusing on specific directories.

Limitations

There are some limitations to be aware of:

  1. Format Sensitivity: The diff is sensitive to formatting changes, so even whitespace changes will show up.

  2. Binary Files: Binary files are not diffed effectively.

  3. Renamed Files: Renamed files are treated as deleted and added, not as renamed.

  4. Complex Refactoring: Major refactoring might result in diffs that are hard to read.

Example Diff Output

Here’s an example of what a diff might look like in plain text format:

# Diff between baseline.txt and current.txt

## File: src/main.py

@@ -5,7 +5,7 @@
 def main():
     print("Hello, world!")

-    # Old comment
-    old_function()
+    # New comment
+    new_function()

 if __name__ == "__main__":
     main()

@@ -15,5 +15,5 @@

-def old_function():
-    return "Old implementation"
+def new_function():
+    return "New implementation"

## File: src/utils.py

@@ -1,5 +1,8 @@
 def helper_function():
     return "I'm helping!"
+
+def another_helper():
+    return "I'm also helping!"

## File: README.md

@@ -1,4 +1,4 @@
-# My Project
+# My Awesome Project

 A simple project to demonstrate promptprep.