Edit patch

[spoorcc]

Related to #614

Sometimes it would be nice to edit the patch, currently this is documented but a little involved.

Updating the patch

If you have further changes to a project with a patch, you can update the patch by first reversing the patch, using
apply and with the --directory argument as shown above. To reverse the patch you also require the -R.
This will return the project to the state before the patch was applied. You can then stage the project and re-apply
the patch to the project to have an editable patch.

   # First apply the reverse patch
   git apply --verbose --directory='some-project' -R some-project.patch

   # Stage the project in its unpatched state
   git add some-project

   # Re-apply the patch
   git apply --verbose --directory='some-project' some-project.patch

Now you can make further changes to the project, and re-generate the patch using the raw git command as shown below.

   # Generate the patch from the directory again
   cd some-project
   git diff --relative --binary --no-ext-diff --no-color . > ../some-project.patch

   # Force a fetch and update the patch to test your changes
   dfetch update -f some-project

Proposal

Add a new dfetch edit-patch <project> command.
It should check if a project has a patch and then perform above steps to make patch editable.

Also extend dfetch diff to have a output file path and that it can diff regularly

[coderabbitai]

📝 CodeRabbit Plan Mode

Generate an implementation plan and prompts that you can use with your favorite coding agent.

✅ Successfully generated implementation plan.

💡 Use @coderabbitai <feedback> to replan

Examples

• Example 1
• Example 2

---

🔗 Related PRs

#882 - Update dfteched dependencies [closed]

👤 Suggested Assignees

• spoorcc

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord or schedule a call!

[coderabbitai]

Coding Plan

Approach

Ticket Summary

Add a new dfetch edit-patch <project> command to automate the process of making patches editable, and extend the existing dfetch diff command to support custom output file paths.

Observations

Codebase Summary

The dfetch project is a dependency management tool that supports Git and SVN repositories. Commands follow an abstract Command base class pattern with create_menu() and __call__() methods, and are manually registered in __main__.py. The project applies patches using the patch-ng library during fetch operations. Projects are defined in YAML manifests and retrieved through the Manifest class. The codebase uses run_on_cmdline() from dfetch.util.cmdline for executing shell commands, and GitLocalRepo.is_git() for detecting git repositories.

Assumptions

Assumption 1: Git Repository Requirement for edit-patch Command

Options Considered:

• Support both Git and SVN with VCS-abstracted implementations
• Implement only for Git with clear error messaging for non-git projects

Chosen Option: Git-only implementation

Rationale: The ticket explicitly demonstrates a git-based workflow, and extending to SVN would add significant complexity for uncertain value. The command should validate that the current working directory is a git repository and provide a clear error message if not. This matches the pragmatic nature of the feature request and can be extended later if SVN support is needed.

Assumption 2: Output File Path for diff Command

Options Considered:

• Make output path required, breaking backward compatibility
• Add optional --output flag with default to current behavior

Chosen Option: Optional --output flag

Rationale: This preserves backward compatibility while adding the requested flexibility. The current behavior (writing {project.name}.patch to the current directory) remains the default, ensuring existing workflows continue to work seamlessly.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Phase 1: Create the edit-patch Command

Create a new command that automates the manual patch editing workflow by reversing, staging, and re-applying patches for projects that have patches configured.

Task 1: Create Command Structure

Implement the new edit_patch.py command file following the established command pattern.

• Create dfetch/commands/edit_patch.py with a class EditPatch inheriting from Command
• Implement create_menu(subparsers) as a static method to register the command with a positional <project> argument
• Implement __call__(self, args) to contain the main command execution logic
• Follow the same structure as existing commands like check.py or diff.py

Task 2: Validate Prerequisites

Add validation logic to ensure the command can execute successfully before attempting git operations.

• Use Manifest.find_name_in_manifest(project_name) to retrieve the project configuration
• Validate that the project exists and has a patch property configured (check project.patch is not empty)
• Validate the patch file exists on disk using file path checks
• Use GitLocalRepo.is_git() to verify the current directory is a git repository
• Check that the project destination has no uncommitted or staged changes using git diff --quiet -- <project.destination> and git diff --cached --quiet -- <project.destination> via run_on_cmdline()
• Handle the return code from git diff to determine if changes exist (non-zero indicates changes present)
• Provide clear error messages for each validation failure (project not found, no patch configured, patch file missing, not a git repository, project has uncommitted/staged changes)

Task 3: Implement Patch Reversal

Execute the git command to reverse the currently applied patch.

• Use run_on_cmdline() from dfetch.util.cmdline to execute git commands
• Construct the git apply command with flags: git apply --verbose --directory=<project.destination> -R <patch_file>
• Handle SubprocessCommandError exceptions and provide meaningful error messages if reversal fails
• Log the operation for user visibility

Task 4: Stage Unpatched Project

Stage the project directory in its unpatched state.

• Execute git add <project.destination> using run_on_cmdline()
• Ensure the entire project directory is staged, making it the baseline for future diff generation
• Handle any git errors that may occur during staging

Task 5: Re-apply Patch

Re-apply the patch to make changes visible in the working directory for editing.

• Execute git apply --verbose --directory=<project.destination> <patch_file> using run_on_cmdline()
• This leaves the changes unstaged but visible, allowing the user to make further modifications
• Handle application errors appropriately
• Provide success message indicating the patch is now editable

Task 6: Register Command

Add the new command to the application's command registry.

• Import EditPatch in dfetch/__main__.py
• Call EditPatch.create_menu(subparsers) in the create_parser() function alongside existing command registrations
• Follow the existing pattern where commands are registered sequentially (around lines 40-48)

🤖 Prompt for AI agents

Implement the edit-patch command to automate making patches editable in git
repositories.

Create dfetch/commands/edit_patch.py with EditPatch class inheriting from
Command:
- Implement create_menu() static method to register command with positional
<project> argument
- Implement __call__(self, args) with validation and git workflow execution

Validation flow:
- Retrieve project using Manifest.find_name_in_manifest(project_name)
- Validate project exists, has patch configured, and patch file exists on disk
- Verify current directory is a git repository using GitLocalRepo.is_git()
- Check project destination has no uncommitted/staged changes using git diff
--quiet and git diff --cached --quiet via run_on_cmdline()
- Provide clear error messages for all validation failures

Patch editing workflow:
- Reverse the patch: git apply --verbose --directory=<project.destination> -R
<patch_file>
- Stage unpatched project: git add <project.destination>
- Re-apply patch: git apply --verbose --directory=<project.destination>
<patch_file>
- Handle SubprocessCommandError exceptions with meaningful error messages
- Log operations and provide success message

Register command in dfetch/__main__.py:
- Import EditPatch
- Call EditPatch.create_menu(subparsers) in create_parser() function

Phase 2: Extend diff Command with Output Path Option

Enhance the existing dfetch diff command to support custom output file paths while maintaining backward compatibility with current behavior.

Task 1: Add Output Argument

Extend the argument parser in the diff command to accept an optional output file path.

• Modify dfetch/commands/diff.py in the create_menu() method
• Add an optional --output or -o argument to the parser using parser.add_argument()
• Set the argument type to accept a file path string
• Document the argument to indicate it specifies where the patch file should be written
• Make it optional with no default value (None when not provided)

Task 2: Update Patch Generation Logic

Modify the patch file writing logic to use the custom output path when provided.

• In the __call__() method of the Diff class, check if args.output is provided
• If provided, use that path directly for writing the patch file
• If not provided, fall back to the current behavior: f"{project.name}.patch" in the current directory
• Validate that the output directory exists if a custom path is provided, and provide a clear error if it doesn't
• Ensure the patch generation function (_dump_patch()) receives the correct output path

Task 3: Update Documentation

Ensure the command's help text and any inline documentation reflect the new capability.

• Update the docstring in dfetch/commands/diff.py to document the --output flag
• Include example usage showing both default behavior and custom output path usage
• Maintain consistency with existing documentation style in the file

🤖 Prompt for AI agents

Extend the dfetch diff command to support custom output file paths with backward
compatibility.

Modify dfetch/commands/diff.py:
- In create_menu() method, add optional --output/-o argument using
parser.add_argument()
- Set argument to accept file path string with appropriate help documentation
- Make it optional with default None

Update __call__() method of Diff class:
- Check if args.output is provided
- Use args.output if provided, otherwise fall back to f"{project.name}.patch"
- Validate output directory exists if custom path provided, error if not
- Pass correct output path to _dump_patch() function

Update documentation:
- Add docstring describing --output flag with example usage
- Show both default behavior and custom output path examples

Phase 3: Create Gherkin Feature Tests

Create comprehensive feature tests to validate the edit-patch command behavior with various scenarios including success cases and failure conditions.

Task 1: Create edit-patch Feature File

Create a Gherkin feature file demonstrating the edit-patch command behavior.

• Create features/edit-patch.feature following the existing feature file patterns
• Add a descriptive Feature header explaining the edit-patch command functionality
• Include a Background section to set up common test conditions (git repository initialization, manifest with patch)
• Structure tests into focused Scenario blocks for different test cases

Task 2: Add Success Scenario

Create a scenario testing successful patch editing workflow.

• Given: A git repository with a manifest defining a project with a patch, the project fetched, and no uncommitted changes
• When: User runs dfetch edit-patch <project>
• Then: Command succeeds, patch is reversed, project is staged, patch is re-applied, and success message is shown
• Use existing reusable steps like @given("the manifest 'dfetch.yaml'"), @when('I run "dfetch edit-patch <project>"'), @then("the output shows")
• Leverage git setup steps from features/steps/git_steps.py for repository initialization

Task 3: Add Precondition Failure Scenarios

Create scenarios testing each precondition validation failure case.

• Scenario: Project not found in manifest (invalid project name provided)
• Scenario: Project has no patch configured in manifest
• Scenario: Patch file specified in manifest does not exist on disk
• Scenario: Current directory is not a git repository
• Scenario: Project destination has uncommitted changes (dirty working tree)
• Scenario: Project destination has staged changes
• Each scenario should verify appropriate error message is displayed and command exits gracefully

Task 4: Implement Required Step Definitions

Add any new step definitions needed for edit-patch feature tests.

• Create step definitions in features/steps/ for edit-patch-specific scenarios not covered by existing reusable steps
• Implement steps for creating projects with patches and verifying patch editing state
• Add steps for setting up dirty/staged file conditions in project destinations
• Follow the patterns in existing step definition files (generic_steps.py, git_steps.py) for consistency
• Reuse existing helpers like call_command(), create_repo(), generate_file() where applicable

🤖 Prompt for AI agents

Create comprehensive Gherkin feature tests for the edit-patch command.

Create features/edit-patch.feature:
- Add Feature header describing edit-patch command functionality
- Include Background section with common test setup (git repo initialization,
manifest with patch)
- Structure tests into focused Scenario blocks

Add success scenario:
- Given: Git repository with manifest defining project with patch, project
fetched, no uncommitted changes
- When: Run dfetch edit-patch <project>
- Then: Verify patch reversed, project staged, patch re-applied, success message
shown
- Use existing steps from git_steps.py and generic_steps.py

Add precondition failure scenarios:
- Project not found in manifest
- Project has no patch configured
- Patch file does not exist on disk
- Not a git repository
- Project destination has uncommitted changes
- Project destination has staged changes
- Each verifies appropriate error message and graceful exit

Implement step definitions in features/steps/:
- Add edit-patch-specific steps not covered by existing reusable steps
- Implement steps for creating projects with patches and verifying patch editing
state
- Add steps for setting up dirty/staged file conditions
- Reuse existing helpers like call_command(), create_repo(), generate_file()

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Implement the edit-patch command to automate making patches editable in git
repositories.

Create dfetch/commands/edit_patch.py with EditPatch class inheriting from
Command:
- Implement create_menu() static method to register command with positional
<project> argument
- Implement __call__(self, args) with validation and git workflow execution

Validation flow:
- Retrieve project using Manifest.find_name_in_manifest(project_name)
- Validate project exists, has patch configured, and patch file exists on disk
- Verify current directory is a git repository using GitLocalRepo.is_git()
- Check project destination has no uncommitted/staged changes using git diff
--quiet and git diff --cached --quiet via run_on_cmdline()
- Provide clear error messages for all validation failures

Patch editing workflow:
- Reverse the patch: git apply --verbose --directory=<project.destination> -R
<patch_file>
- Stage unpatched project: git add <project.destination>
- Re-apply patch: git apply --verbose --directory=<project.destination>
<patch_file>
- Handle SubprocessCommandError exceptions with meaningful error messages
- Log operations and provide success message

Register command in dfetch/__main__.py:
- Import EditPatch
- Call EditPatch.create_menu(subparsers) in create_parser() function
===============================================================================

Task: 2

Extend the dfetch diff command to support custom output file paths with backward
compatibility.

Modify dfetch/commands/diff.py:
- In create_menu() method, add optional --output/-o argument using
parser.add_argument()
- Set argument to accept file path string with appropriate help documentation
- Make it optional with default None

Update __call__() method of Diff class:
- Check if args.output is provided
- Use args.output if provided, otherwise fall back to f"{project.name}.patch"
- Validate output directory exists if custom path provided, error if not
- Pass correct output path to _dump_patch() function

Update documentation:
- Add docstring describing --output flag with example usage
- Show both default behavior and custom output path examples
===============================================================================

Task: 3

Create comprehensive Gherkin feature tests for the edit-patch command.

Create features/edit-patch.feature:
- Add Feature header describing edit-patch command functionality
- Include Background section with common test setup (git repo initialization,
manifest with patch)
- Structure tests into focused Scenario blocks

Add success scenario:
- Given: Git repository with manifest defining project with patch, project
fetched, no uncommitted changes
- When: Run dfetch edit-patch <project>
- Then: Verify patch reversed, project staged, patch re-applied, success message
shown
- Use existing steps from git_steps.py and generic_steps.py

Add precondition failure scenarios:
- Project not found in manifest
- Project has no patch configured
- Patch file does not exist on disk
- Not a git repository
- Project destination has uncommitted changes
- Project destination has staged changes
- Each verifies appropriate error message and graceful exit

Implement step definitions in features/steps/:
- Add edit-patch-specific steps not covered by existing reusable steps
- Implement steps for creating projects with patches and verifying patch editing
state
- Add steps for setting up dirty/staged file conditions
- Reuse existing helpers like call_command(), create_repo(), generate_file()

💡 Iterate on the plan with: @coderabbitai <feedback>

Example Feedback
- @coderabbitai You can skip phase 3. Add a simple unit test case for phase 2.
- @coderabbitai For assumption 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord or schedule a call!

[spoorcc]

@coderabbitai add gherkin feature files to demonstrate the behavior
@coderabbitai check the preconditions: is git, has patch file in manifest and it exists, no files edited or staged from the project.destination

[coderabbitai]

I've updated the plan above based on your feedback. Ready to proceed when you are!

[ben-edna]

Alternatively as suggested by @jgeudens make it a one-shot action:

Given project 'MyProject' with a patch
And some unstaged changes to some files in that project
When i run dfetch update-patch MyProject
Then dfetch stores the current changes temporarily in a patch file
And dfetch restores the original version of MyProject by reverse applying the current patch
And dfetch stages MyProject
And dfetch restores the patched version of MyProject by applying the current patch
And dfetch applies the temporary patch to apply latest changes 
And dfetch updates the current patch file from the manifest with the combined changes using diff
And dfetch updates the metadata to prevent any local changes warnings
And dfetch stages & unstages all MyProject files to have it in a state ready to commit

[spoorcc]

quilt is a commonly used for patch management that can fold patches. It is written in bash, but may give inspiration for approaches and terms.

See a tutorial here: https://raphaelhertzog.com/2012/08/08/how-to-use-quilt-to-manage-patches-in-debian-packages/

Nice take-aways:

• allow for multiple patches (gives opportunity to separate changes and name patch files meaningfully)
• edit command marks a specific file for inclusion in patch (copy made underwater) and text editor is opened for editing (dfetch project level is more logical), but like the edit naming
• possibility to navigate through the stack of patches with push & pop

I like the edit naming, but I am not sure if this would be clear for end users that such a command primes a project for doing local changes