skip to content

How can you compose a build temporarily without editing settings.gradle.kts, and when is that useful?

level: middleimportance: should knowfreq 30%

answer

  1. --include-build <dir> on the CLI
  2. ephemeral: this invocation only
  3. not persisted to settings.gradle.kts
  4. ad-hoc bug repro / CI job
  5. can repeat flag for multiple builds

basics

~10 s

Pass --include-build on the command line: gradle --include-build ../my-library run. It composes that build for the single invocation only, without changing settings.gradle.kts.

solid answer

~40 s

Besides the declarative `includeBuild("../other")` in `settings.gradle.kts`, Gradle accepts `--include-build <dir>` on the command line. This composes the named build for **that invocation only** — nothing is persisted to the settings file. It is useful for **ad-hoc, throwaway composition**: temporarily verifying your app against a local checkout of a library you don't normally develop together, or letting CI swap in a source build for a particular job without polluting the committed settings. Because it isn't committed, every developer's everyday build stays unaffected. The substitution rules are the same as the declarative form: outputs of the included build replace external dependencies whose `group:name` coordinates match. You can pass the flag multiple times to include several builds in one run.

code

bash · 5 lines
bash
# Compose a local library source build for one run only
gradle --include-build ../my-library :app:run

# settings.gradle.kts stays untouched; next build ignores it
gradle :app:run

go deeper

for a junior

Know the --include-build flag exists for one-off composition.

for a middle

Explain ephemeral vs declarative composition and pick the right one per workflow.

for a senior

Use CLI inclusion in CI matrices and bug-repro flows while keeping the committed settings clean.

for a principal

Standardize when teams should commit includeBuild vs rely on ephemeral CLI composition to keep everyday builds reproducible and lightweight.

## Two ways to compose 1. **Declarative** — `includeBuild("../my-library")` in `settings.gradle.kts`. Persistent; everyone who checks out the repo gets the composition. 2. **Command-line** — `gradle --include-build ../my-library <task>`. Ephemeral; affects only that one invocation. ## The CLI form ```bash # compose ../my-library just for this run gradle --include-build ../my-library :app:run # include several builds in one invocation gradle --include-build ../lib-a --include-build ../lib-b build ``` Nothing is written to disk. The next plain `gradle build` ignores the temporary composition. ## When the CLI form shines - **One-off verification** — you cloned a library locally to reproduce a bug; compose it for a single run, confirm, move on. - **CI matrix jobs** — a specific job builds against source instead of a published artifact, without a branch that edits `settings.gradle.kts`. - **Keeping the default build clean** — most developers never need the library source on disk, so you don't want `includeBuild` committed and breaking their build when `../my-library` is absent. ## Trade-off vs declarative - Declarative is reproducible and shared — good when the team *always* co-develops the two builds. - CLI is transient and personal — good when composition is the exception, not the rule. ## Same substitution semantics Either way, Gradle substitutes the included build's outputs for external dependencies with matching coordinates, so dependency declarations in your build scripts don't change.

  • Does --include-build change dependency substitution behavior compared to the declarative form?
    No — both substitute the included build's outputs for external dependencies with matching group:name coordinates. Only persistence differs.
  • Why might you prefer CLI inclusion over editing settings.gradle.kts?
    It keeps the committed build clean for developers who don't have the other build checked out, and avoids a throwaway settings edit.

saying these in an interview costs you the question

  • Thinking --include-build permanently modifies the settings file — it affects only the current invocation.
  • Believing the CLI form has different substitution semantics from the declarative one.

context

resolving links…