skip to content

What does the `--incubating` flag do in `gradle init`, and when would you use it?

level: seniorimportance: nice to knowfreq 20%

answer

  1. opts into incubating (non-stable) features
  2. newest conventions: JvmTestSuite, catalogs
  3. unlocks experimental --type templates
  4. @Incubating = no back-compat guarantee
  5. greenfield yes / stable prod no

basics

~20 s

--incubating makes gradle init opt into the latest, possibly-unstable APIs and conventions for the generated build—e.g. newer test-suite or version-catalog defaults—and unlocks incubating project types. It signals you accept that those features may still change.

solid answer

~40 s

`--incubating` tells the build-init plugin to generate a build using Gradle's **incubating** features and most-modern conventions instead of the conservative stable defaults. Incubating features are released but not yet API-stable—they may change or be removed in a later version without the usual deprecation cycle. With the flag, generated scripts may adopt newer constructs (for example the declarative `testing { suites { ... } }` / `JvmTestSuite` block, the latest version-catalog layout, or newer plugin defaults) and some experimental project `--type`s become selectable. You'd use it on greenfield projects where you want the newest ergonomics and can tolerate occasional churn when you upgrade Gradle, or to evaluate upcoming conventions. Avoid it for long-lived production builds that prize stability, since incubating APIs can break across Gradle versions.

code

bash · 6 lines
bash
# Generate with the newest (incubating) conventions
gradle init \
  --type java-application \
  --dsl kotlin \
  --test-framework junit-jupiter \
  --incubating

go deeper

for a junior

Just know it opts into newer, not-yet-stable scaffolding conventions.

for a middle

Explain that incubating features lack back-compat guarantees and give an example like the test-suite DSL.

for a senior

Weigh greenfield ergonomics against upgrade-churn risk and articulate when to use vs avoid it.

for a principal

Set policy on incubating adoption org-wide, balancing early access to conventions against long-term build stability and upgrade cost.

## What "incubating" means in Gradle Gradle marks new APIs and features as **`@Incubating`**: they're shipped and usable, but explicitly *not* covered by Gradle's backward-compatibility guarantees. They can change shape or be removed without going through the normal deprecation period. It's Gradle's way of releasing-then-stabilizing. ## What `--incubating` does in `init` Passing `--incubating` to `gradle init` makes the generated build prefer those newest conventions over the stable defaults: - **Latest scaffolding conventions** — e.g. expressing tests through the incubating test-suite DSL (`testing { suites { val test by getting(JvmTestSuite::class) { useJUnitJupiter() } } }`) rather than the classic `dependencies { testImplementation(...) }` + `tasks.test { useJUnitPlatform() }`. - **Newer version-catalog / convention plugin layouts** for multi-project builds. - **Unlocking incubating `--type` templates** that aren't offered in the stable list. ```kotlin // Roughly what --incubating may generate for tests testing { suites { val test by getting(JvmTestSuite::class) { useJUnitJupiter() } } } ``` ## When to use it - **Greenfield / experimental** projects where you want the newest ergonomics and can re-generate or adjust scripts when you bump Gradle. - **Evaluating** where Gradle's conventions are heading before they stabilize. ## When to avoid it - **Long-lived production builds** valuing stability—incubating constructs may need rework on a future Gradle upgrade. - Teams that pin Gradle conservatively and want zero surprises. ## Relationship to other flags `--incubating` composes with `--type`, `--dsl`, and `--test-framework`; it changes *how* the scaffold is expressed and which experimental types are available, not the fundamental choice of application vs library.

  • What's the risk of building a long-lived project with `--incubating`?
    Incubating APIs aren't covered by Gradle's compatibility guarantees, so a future Gradle upgrade may change or remove constructs in the generated build, forcing rework.
  • Name a concrete convention `--incubating` may adopt.
    The declarative test-suite DSL (`testing { suites { ... useJUnitJupiter() } }` / `JvmTestSuite`) instead of manually adding test dependencies and calling `useJUnitPlatform()`.

saying these in an interview costs you the question

  • Treating `--incubating` as just 'enable more features' without noting the lack of stability guarantees.
  • Recommending it by default for production builds.

context

resolving links…