Why should the Gradle Wrapper be committed to VCS?

问题:

From Gradle's documentation: https://docs.gradle.org/current/dsl/org.gradle.api.tasks.wrapper.Wrapper.html

The scripts generated by this task are intended to be committed to your version control system. This task also generates a small gradle-wrapper.jar bootstrap JAR file and properties file which should also be committed to your VCS. The scripts delegates to this JAR.

From: What should NOT be under source control?

I think Generated files should not be in the VCS.

When are gradlew and gradle/gradle-wrapper.jar needed?

Why not store a gradle version in the build.gradle file?

回答1:

Because the whole point of the gradle wrapper is to be able, without having ever installed gradle, and without even knowing how it works, where to download it from, which version, to clone the project from the VCS, to execute the gradlew script it contains, and to build the project without any additional step.

If all you had was a gradle version number in a build.gradle file, you would need a README explaining everyone that gradle version X must be downloaded from URL Y and installed, and you would have to do it every time the version is incremented.

回答2:

Because the whole point of the gradle wrapper is to be able, without having ever installed gradle

Same argument goes for the JDK, do you want to commit that also? Do you also commit all your dependencie libraries?

The dependencies should be upgraded continuously as new versions are released. To get security and other bug fixes. And because if you get to far behind it can be a very time consuming task to get up to date again.

If the gradle wrapper is incremented for every new release, and it is committed, the repo will grow very large. The problem is obvious when working with distributed VCS where a clone will download all versions of everything.

, and without even knowing how it works

Create a build script that downloads the wrapper and uses it to build. Everyone does not need to know how the script works, they need to agree that the project is build by executing it.

, where to download it from, which version

task wrapper(type: Wrapper) {
 gradleVersion = 'X.X' 
}

And then

gradle wrapper

To download the correct version.

, to clone the project from the VCS, to execute the gradlew script it contains, and to build the project without any additional step.

Solved by the steps above. Downloading the gradle wrapper is not different from downloading any other dependencies. The script could be smart enaugh to check for any current gradle wrapper and only download it if there is a new version.

If the developer has never used Gradle before and maybe not knowing the project is build with Gradle. Then its more obvious to run a "build.sh" compared to running "gradlew build".

If all you had was a gradle version number in a build.gradle file, you would need a README explaining everyone that gradle version X must be downloaded from URL Y an installed,

No, you would not need a README. You could have one, but we are developers and we should automate as much as possible. Creating a script is better.

and you would have to do it every time the version is incremented.

If the developers agree that the correct process is to:

1. Clone repo
2. Run build script

Then there upgrading to latest gradle wrapper is no problem. If the version is incremented since last run, the script could download the new version.

回答3:

I would like to recommend a simple approach.

In your project's README, document that an installation step is required, namely:

gradle wrapper --gradle-version 3.3

This works with Gradle 2.4 or higher. This creates a wrapper without requiring a dedicated task to be added to "build.gradle".

With this option, ignore (do not check in) these files/folders for version control:

• ./gradle
• gradlew
• gradlew.bat

The key benefit is that you don't have to check-in a downloaded file to source control. It costs one extra step on installation. I think it is worth it.

回答4:

What is the "project"?

Maybe exists a technical definition of this idiom that excludes build scripts. But if we accept this definition, then we must say your "project" is not all the things that you need to versioned!

But if we say "your project" is everything you have done. Then we can say you must include it and only it into VCS.

This is very theoretical and maybe not practical in case of our development works. So we change it to "your project is every file (or folder) you need to editing them directly".

^{"directly" means "not indirectly" and "indirectly" means by editing another file and then an effect will be reflected into this file.}

So we reach the same that OP said (and is said here):

I think Generated files should not be in the VCS.

Yes. Because you hadn't created them. So they are not part of "your project" according to the second definition.

---

What is the result about these files:

• build.gradle: Yes. We need to edit it. Our works should be versioned.

  Note: There is no difference where you edit it. Whether in your text editor environment or in Project Structure GUI environment. Anyway you doing it directly!

• gradle-wrapper.properties: Yes. We need to at least determine Gradle version in this file.

• gradle-wrapper.jar and gradlew[.bat]: I haven't created or edited them in any of my development works, till this moment! So the answer is "No". If you have done so, the answer is "Yes" about you at that work (and about the same file you edited).

---

The important note about the latest case is the user who clones your repo, needs to execute this command on repo's <root-directory> to auto-generate wrapper files:

> gradle wrapper --gradle-version=$v --distribution-type=$distType

$v and $distType are determined from gradle-wrapper.properties:

distributionUrl=https\://services.gradle.org/distributions/gradle-{$v}-{$distType}.zip

See https://gradle.org/install/ for more information.

gradle executable is bin/gradle[.bat] in local distribution. It's not required that local distribution be same as that determined in the repo. After wrapper files created then gradlew[.bat] can download determined Gradle distribution automatically (if not exists locally). Then he/she probably must regenerate wrapper files using new gradle executable (in downloaded distribution) using above instructions.

---

Note: In the above instructions, supposed the user has at least one Gradle distribution locally (e.g. ~/.gradle/wrapper/dists/gradle-4.10-bin/bg6py687nqv2mbe6e1hdtk57h/gradle-4.10). It covers almost all real cases. But what happens if the user hasn't any distribution already?

He/She can download it manually using the URL in .properties file. But if he/she doesn't locate it in the path that the wrapper expected, the wrapper will download it again! The expected path is completely predictable but is out of the subject (see here for the most complex part).

There are also some easier (but dirty) ways. For example, he/she can copy wrapper files (except .properties file) from any other local/remote repository to his/her repository and then run gradlew on his/her repository. It will automatically download the suitable distribution.