.. _diff_generation:

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:

.. code-block:: bash

   promptprep --diff PREV_FILE [other options]

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

Example:

.. code-block:: bash

   # 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:

.. code-block:: bash

   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:

.. code-block:: bash

   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:

.. code-block:: text

   --- 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:

.. code-block:: bash

   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:

.. code-block:: bash

   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:

.. code-block:: bash

   # 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:

.. code-block:: bash

   # 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:

.. code-block:: bash

   # 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:

.. code-block:: text

    # 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.