Patch

From APIDesign

Revision as of 05:45, 21 January 2026

How can a patch be distributed? When accepting API Patches and having proper Git repository infrastructure one can probably think of a patch as a pull request. However, there are older and I'd like to claim still useful ways to deliver patches that work well with Git and other versioning systems. In fact this old good way is still in the heart of these versioning systems. I am talking about:

diff --git channel/Channel.java channel/Channel.java
index da14c1bce6..0db8858d0a 100644
--- a/channel/Channel.java
+++ b/channel/Channel.java
@@ -493,13 +494,10 @@ public final class Channel<Data extends Channel.Config> implements AutoCloseable
    * @return {@code true} if the exception was printed and further details should be printed
    */
   private boolean printStackTrace(Throwable ex, boolean userCode) {
-    if (!userCode) {
       if (ex != null) {
         ex.printStackTrace();
       }
-      return true;
-    }
-    return false;
+    return  true;
   }
 
   /**

Quiz

What do you think about the above text?

• I have a feeling I understand the patch
• I known what those lines starting with + and - mean
• I can apply the same changes to existing Channel.java file manually
• I known tool to apply the changes for me
  • It is a UI application
  • I can do it from command line
  • I ask AI to apply the change for me
• I know the -p argument of the CLI command
• I know the -R argument of the CLI command
• I know something more than you!

Reading

My colleague Ilya wrote: " In most cases, I will just observe the patch without applying it if it is small enough. (it usually is!)". In such case the situation is simple. Lines starting with a single - are the ones being removed and those starting with a single + are those being added. The header identifies the file that's being modified, but one doesn't really have to parse it - it is clear the above patch is related to Channel.java file.

Trying It

However sometimes just reading isn't enough. Sometimes we need to apply the patch locally to try how it behaves. Let's quote Ilya one more time: "If it is small enough (a few lines), I will repeat it manually, if ... typing everything by hand is not an option, I will apply it with git." I am not fully sure how to apply a patch with git, but let's do it with another program (years older than git) which is (unsuprisingly) named patch.

$ patch -p0 <my.diff

The -p argument is very important. Without it patch command doesn't know how to interpret the header and locate the Channel.java file. In such case the patch command switches to interactive mode - which is quite annoying (but it shows how old the patch command is - it comes from ages when interactions with user were happening in terminal and not a GUI). Using -p argument avoids the interactivity.

Embeddable Format

The above diff format can be easily embedded into an email and sent as a part of a message. E.g. surrounding the patch with prose sections as completely OK. The patch command line tool will just ignore everything not having the appropriate diff header

Applying a PR from Another GitHub Repository

$ curl -L https://github.com/enso-org/enso/pull/14666.diff | patch -p1

Conclusion

I have been adding (sometimes complicated) diffs as PR comments for many years and just recently I realized that I am not sure people know how to apply them! That's why I decided to write this down. I find the patch command line utility very useful. I wish its knowledge would spread. Let this little quiz help with that!