Skip to content

Patching

Creating patches in Git involves generating files that represent the changes introduced by one or more commits. These patches can then be shared with others or applied to different repositories.

Using git format-patch

The git format-patch command generates patch files for one or more commits, formatting them in the "mbox" format by default.

git format-patch <start-commit>..<end-commit>


git format-patch HEAD~3..HEAD
- This command generates patch files for the last three commits from the current HEAD commit.

Creating Patches for Specific Commits

You can specify individual commits to create patches for by providing their commit hashes.

git format-patch <commit-hash>


git format-patch abc123
- This command generates a patch file for the commit with the hash abc123.

Specifying Output Directory

You can specify the output directory for the generated patch files using the -o or --output-directory option.

git format-patch -o <output-directory> <start-commit>..<end-commit>

git format-patch -o patches/ HEAD~3..HEAD
  • This command generates patch files for the last three commits and saves them in the patches/ directory.

Including Commit Message in Patch

You can include the commit message as part of the patch file by using the --stdout option.

git format-patch --stdout <commit-hash>

git format-patch --stdout abc123 > patch_file.patch
  • This command generates a patch file for the commit with the hash abc123 and includes the commit message in the output.

Generating Patch for Unpushed Commits

To create patches for unpushed commits, you can specify the branch name along with the git format-patch command.

git format-patch origin/<branch-name>

git format-patch origin/main
  • This command generates patch files for the commits that are present in the local branch but not in the remote main branch.

Inspecting and Applying Patch Files

Once the patch files are generated, you can inspect them using any text editor or view the changes using the git apply --stat command.

git apply --stat <patch-file>
  • This command displays statistics about the changes introduced by the patch file.

The command git apply patchtext.patch is used to apply a patch file to the current working directory. 

git apply <patch-file>

  • git apply: This Git command is used to apply a patch file to the current working directory.

  • patchtext.patch: This is the name of the patch file you want to apply. The patch file contains the changes that you want to apply to your repository.

How It Works

  1. Ensure Correct Context: The patch file must be generated in a compatible format with the changes relative to the repository's current state.

  2. Navigate to Repository: First, navigate to the directory of the Git repository where you want to apply the changes.

  3. Checkout Target Branch/Commit: Ensure that you are on the correct branch or commit where you want the changes to be applied. This step ensures that the changes are applied to the correct codebase.

  4. Run git apply: Execute the git apply command followed by the name of the patch file you want to apply.

  5. Review Changes: After applying the patch, review the changes to ensure they were applied correctly. You can use git diff to inspect the differences before and after applying the patch.

  6. Stage and Commit (if necessary): If the changes are satisfactory, stage and commit them to finalize the application of the patch.

Considerations

  • Patch Compatibility: Ensure that the patch file is compatible with the version of the codebase you are applying it to. Mismatches in context or format can lead to errors or unintended consequences.

  • Review Changes: Always review the changes introduced by the patch to verify correctness and avoid introducing bugs or conflicts.

  • Backup: Consider creating a backup or working on a separate branch before applying patches, especially if the changes are significant or experimental.

Using git apply provides a straightforward way to apply patches to a Git repository, allowing you to integrate changes from external sources or collaborators efficiently.

Sharing Patch Files

You can share the generated patch files with others through email, file sharing services, or version control systems.

Generating patches in Git using git format-patch provides a convenient way to share changes between repositories or with collaborators. By following these steps and examples, you can create patch files for specific commits or ranges of commits and distribute them efficiently.

git diff vs git format-patch for creating patches

Both git diff and git format-patch can be used to create patches, but they are designed for different use cases. Here's a comparison:

git diff

git diff is used to show the differences between two commits, branches, or the working directory and a commit. It generates a raw diff output that can be used to apply changes with git apply.

Pros:
  • Simplicity: Easy to use for quick comparisons or creating simple patch files.
  • Flexible: Can be used to compare uncommitted changes or staged changes.
  • Compatible with non-Git workflows: The output can be applied as a patch outside of Git using standard tools like patch.
Cons:
  • No commit metadata: Does not include author information, commit messages, or timestamps.
  • Limited scope: Cannot represent multiple commits or complex histories in one patch file.
  • Manual tracking: You need to manually ensure the context of the patch (e.g., base commit).
Example Usage:

  1. Create a patch between two branches: 

    git diff branch1 branch2 > my_changes.patch

  2. Apply the patch: 

    git apply my_changes.patch

  3. Check the patch before applying: 

    git apply --check my_changes.patch

  4. Reverse a patch: 

    git apply -R my_changes.patch

git format-patch

git format-patch is designed to generate patches for one or more commits. It creates a file (or files) with commit metadata, making it ideal for sharing changes with collaborators or upstream projects.

Pros:
  • Includes commit metadata: Author, date, and commit message are preserved.
  • Supports multiple commits: Can generate patches for a range of commits, each in its own file.
  • Integrates with email workflows: Works seamlessly with git send-email for sending patches via email.
  • Clear history: Retains the context of commits when applied with git am.
Cons:
  • More complex: Not as straightforward as git diff for quick patch creation.
  • Git-specific: The output is more tailored for Git workflows and may not be as portable for non-Git systems.
  • Separate files: Creates one file per commit unless explicitly concatenated.
Example Usage:

  1. Create a patch for the last commit: 

    git format-patch -1

  2. Create patches for all commits between two branches: 

    git format-patch branch1..branch2

  3. Apply patches: 

    git am *.patch

  4. Send patches via email: 

    git send-email *.patch

  5. Generate a single patch file for multiple commits: 

    git format-patch branch1..branch2 --stdout > changes.patch

Comparison of Use Cases

Feature git diff git format-patch
Metadata Not included Includes author, date, and commit message
Multi-commit patches Not supported Supported
Email integration No Yes
Portability Works with or without Git Primarily designed for Git workflows
Complex histories Not well-suited Handles complex histories with multiple commits
Detailed Workflow Example
Scenario: Applying changes from feature to main

  1. Using git diff: 

    # Create the patch
git diff main..feature > feature_to_main.patch

# Transfer the patch (optional)
scp feature_to_main.patch user@remote:/path/to/project

# Apply the patch
git apply feature_to_main.patch

# Stage the applied changes
git add .

# Commit the changes
git commit -m "Applied patch from feature branch"

  2. Using git format-patch: 

    # Create patches for all commits in feature branch
git format-patch main..feature

# Transfer the patches (optional)
scp *.patch user@remote:/path/to/project

# Apply the patches with commit metadata
git am *.patch

Conclusion

  • Use git diff for simpler use cases, especially when you don’t need commit metadata or are working outside of Git.
  • Use git format-patch when sharing changes with collaborators, contributing to upstream projects, or preserving commit history and metadata.

But if two branches have different code but no distinct commits (e.g., the code changes were made directly to the working tree without committing), you can still use git format-patch in a specific way to capture those changes. This approach mimics the functionality of git diff, while packaging the changes into a patch file that includes metadata.

Using git format-patch Without Different Commits

When there are no distinct commits but you want to create a patch using git format-patch, the steps involve:

  1. Staging the changes (if they aren’t staged yet).
  2. Committing the changes to create a temporary commit.
  3. Generating the patch using git format-patch.
  4. (Optional) Cleaning up the temporary commit after generating the patch.
Example Workflow
Scenario: Two branches (main and feature) have diverged in code but not in commits.

  1. Switch to the branch with the changes: 

    git checkout feature

  2. Stage all changes: If the differences are uncommitted, first stage them: 

    git add .

  3. Create a temporary commit: Commit the staged changes with a temporary message: 

    git commit -m "Temporary commit for patch generation"

  4. Generate a patch with git format-patch: Create a patch that captures the differences between the branches: 

    git format-patch main --stdout > feature_to_main.patch

  5. The --stdout flag outputs the patch as a single file.

  6. The patch includes metadata like the commit author, timestamp, and message.

  7. Apply the patch on the target branch: Switch to the target branch (main) and apply the patch: 

    git checkout main
git am feature_to_main.patch

Using git am ensures the patch is applied with all the original metadata.

  1. (Optional) Clean up the temporary commit: Return to the branch where you created the temporary commit (feature) and reset it to discard the temporary commit: 
    git reset HEAD~1

This removes the temporary commit but leaves the changes intact in the working directory.

Advantages of This Workflow
  • Metadata preservation: Unlike git diff, this approach includes author information, timestamps, and a commit message.
  • Direct integration with Git workflows: The patch can be applied using git am, maintaining Git history.
  • Flexibility: You can revert or reapply the patch later if needed.
Comparison with git diff

If you were using git diff for this scenario, you would directly generate the patch without creating a temporary commit:

git diff main..feature > feature_to_main.patch
git apply feature_to_main.patch

This approach skips commit metadata but works well for quick or simple workflows.

When to Use Each
  • Use git diff when you need a quick and straightforward patch for differences in code but don’t care about commit metadata.
  • Use git format-patch when you need a patch with commit metadata or intend to integrate the patch into a Git-based workflow (e.g., applying with git am).