Enhance docs about reproducible builds (#1882)

snazy · Goooler · Copilot · web-flow · commit 47a1e7bb9ab0 · 2025-12-05T18:21:34.000+08:00
* Enhance docs about reproducible builds

* Apply suggestions from code review

* Update docs/configuration/reproducible-builds/README.md

Co-authored-by: Copilot &lt;175728472+Copilot@users.noreply.github.com&gt;

---------

Co-authored-by: Zongle Wang &lt;wangzongler@gmail.com&gt;
Co-authored-by: Copilot &lt;175728472+Copilot@users.noreply.github.com&gt;
diff --git a/docs/configuration/reproducible-builds/README.md b/docs/configuration/reproducible-builds/README.md
@@ -3,23 +3,52 @@
 By default, JAR files generated by Gradle (with or without Shadow) for a single project with the same source code may
 not be identical to each other. Sometimes it's desirable to configure a project to consistently output a byte-for-byte
 identical JAR on every build. Gradle supports this with the following configuration, and Shadow will correctly respect
-these settings too:
+these settings too.
+
+Besides file timestamps and file order, this configuration also ensures that all files in the JAR are set to have the
+same permissions, irrespective of the locally configured umask.
+
+More information about reproducible builds can be found at [reproducible-builds.org](https://reproducible-builds.org/).
 
 === "Kotlin"
 
     ```kotlin
+    import java.nio.file.Files
+    import java.nio.file.attribute.PosixFilePermission
+
     tasks.withType<AbstractArchiveTask>().configureEach {
       isPreserveFileTimestamps = false
       isReproducibleFileOrder = true
+
+      eachFile {
+        permissions {
+          val isExec =
+            Files.getPosixFilePermissions(file.toPath()).contains(PosixFilePermission.OWNER_EXECUTE)
+          unix(if (isExec) "755" else "644")
+        }
+      }
+      dirPermissions { unix("755") }
     }
     ```
 
 === "Groovy"
 
     ```groovy
+    import java.nio.file.Files
+    import java.nio.file.attribute.PosixFilePermission
+
     tasks.withType(AbstractArchiveTask).configureEach {
       preserveFileTimestamps = false
       reproducibleFileOrder = true
+
+      eachFile {
+          permissions {
+              def isExec =
+                      Files.getPosixFilePermissions(file.toPath()).contains(PosixFilePermission.OWNER_EXECUTE)
+              unix(isExec ? '755' : '644')
+          }
+      }
+      dirPermissions { unix('755') }
     }
     ```
 
