Repository: flox/floxdocs
Pull request #206: feat: composition concept page
Author: login: zmitchell
Labels: name: documentation
description: Improvements or additions to documentation
name: team-cli
description: Tickets relevant to the flox CLI team
Created: 2025-04-09T00:29:09Z | Merged: 2025-04-09T19:27:50Z



Diff:
diff --git a/docs/concepts/composition.md b/docs/concepts/composition.md
new file mode 100644
index 00000000..1c49ac1d
--- /dev/null
+++ b/docs/concepts/composition.md
@@ -0,0 +1,128 @@
+---
+title: Composing environments
+description: How to combine and reuse environments.
+---
+
+# Composing environments
+
+When your company starts work on a new service, it's likely that the tools required to work on this service will be very similar to the tools used to work on other services at the company.
+Similarly, when you work on hobby projects it's likely that you use a similar set of tools from one project to the next.
+With other developer environment solutions it's common to need to recreate your developer environment from scratch for each new project.
+
+With Flox you can define a toolchain or service once and _compose_ it with others to create a composed environment.
+Put another way, **with Flox you can create developer environments from reusable building blocks**.
+Reuse and composition are two features that have long been a Holy Grail for developer environments, and Flox makes these features friendly and easily accessible.
+
+## Building blocks
+
+Environments are the building blocks from which a "composed" environment is created.
+In this composition there is a hierarchy consisting of a "composing" environment and a list of "included" environments that it treats as dependencies.
+The manifests of the included and composing environments are merged and then the resulting "merged" manifest is locked and built.
+
+```d2 scale="0.9"
+composer: "Composing\nenvironment"
+
+includes: Included environments {
+  envA: Env A
+  envB: Env B
+  envC: Env C
+  direction: down
+  envA -> envB: Overridden by
+  envB -> envC: Overridden by
+}
+
+includes -> composer: Overridden by
+```
+
+## Including an environment
+
+The included environments are declared in your manifest in the `include` table under the `environments` array.
+Each entry in this array is an "include descriptor", which specifies where to find the environment.
+
+```text
+IncludedEnvironments ::= [IncludeDescriptor]
+IncludeDescriptor    ::= PathEnvDescriptor
+PathEnvDescriptor    ::= {
+  dir  = <PATH>
+, name = null | <STRING>
+}
+```
+
+Just like you would use the `flox activate --dir` flag to specify an environment to activate by its path, you use the `dir` field to specify the path to an environment to include.
+Every environment has a name built-in, but sometimes there may be name conflicts, or you may just want to provide a different name.
+You can do so with the `name` field.
+
+An example `include` section is shown below:
+
+```toml
+[include]
+environments = [
+  { dir = "../myenv" },
+  # Override the name of this environment
+  { dir = "../other_env", name = "other" }
+]
+```
+
+The order in which the included environments are listed matters.
+The environments specified later in the list will override those earlier in the list.
+
+It is possible to push a composed environment to FloxHub, but not if it includes environments that exist locally e.g. environments that are specified with the `dir` field.
+
+## Merging process
+
+When environments are composed, their manifests are merged into a single merged manifest.
+The manifests are merged, and the merged manifest is locked (as opposed to building the environments and merging their lockfiles).
+This allows manifests to override each other e.g. to ask for a newer version of a package specified in an earlier manifest in the merge process.
+
+Later manifests override earlier manifests when there are conflicts, and the manifest of the composing environment always has the highest priority (it is applied last).
+The `include.environments` array is stripped from included environments and the composing environment's manifest during the merge process.
+
+The manifests are merged during the process of building the environment, and if one manifest overrides another, a warning is displayed.
+
+Most manifest fields are merged the way you would expect:
+
+`install`
+
+:  The install section contains the union of all package descriptors from all manifests. When there are conflicts, the entire package descriptor is overridden.
+
+`services`
+
+: Same behavior as the `install` section.
+
+`vars`
+
+: Same behavior as the `install` section.
+
+`hook.on-activate`
+
+: The `hook.on-activate` scripts are appended to each other.
+
+`profile`
+
+: The corresponding scripts in the `profile` section are also appended to each other e.g. all of the `profile.common` scripts are appended, all of the `profile.bash` scripts are appended, etc.
+
+`containerize`
+
+: The options in the `containerize` section are more complicated because merging some options instead of overriding them would lead to unintuitive behavior.
+`user`, `cmd`, `working-dir`, and `stop-signal` are completely overridden.
+`exposed-ports`, `volumes`, and `labels` are merged.
+
+`options`
+
+: The options in the `options` section are all overridden completely.
+This prevents a merge of `options.systems` from providing more systems than the environment can support.
+Similarly, this prevents a merge of `allow.licenses` from allowing more licenses than intended.
+
+One option to note is `options.activate.mode`.
+Recall that the activation mode determines whether development dependencies of packages are added to `PATH`, etc when the environment is activated.
+Since the default is `dev` mode, and the default doesn't appear in the manifest, a single environment that sets `options.activate.mode = "run"` will cause the merged manifest to also set this option.
+This can be surprising, so check the manifests of the included environments and override this option if you're observing this behavior.
+
+## Getting the latest manifests
+
+It's reasonable to assume that the manifests of the included environments will change over time and at some point you will want to bring in the latest versions of those manifests.
+This is accomplished with the `flox include upgrade` command.
+
+Running this command will check each of the included environments and determine if there were changes to their manifests.
+If the changes to the manifest have been built by the included environment, then the new manifest will be included.
+At this point the merge process runs again, a new merged manifest is produced, and the composed environment is rebuilt from the new merged manifest.
diff --git a/mkdocs.yml b/mkdocs.yml
index e4400cf5..950dc9ec 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -52,6 +52,7 @@ nav:
     - Generations: concepts/generations.md
     - Catalog and Packages: concepts/packages-and-catalog.md
     - Services: concepts/services.md
+    - Composing environments: concepts/composition.md
     - Flox vs. container workflows: concepts/flox-vs-containers.md
   - Cookbook:
     - Languages:


Reviews:
user: login: dcarley
state: APPROVED
author_association: CONTRIBUTOR
submitted_at: 2025-04-09T16:34:33Z
user: login: zmitchell
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-04-09T16:37:03Z
user: login: zmitchell
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-04-09T16:37:19Z
user: login: dcarley
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-04-09T16:42:09Z
user: login: zmitchell
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-04-09T19:19:01Z
user: login: zmitchell
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-04-09T19:19:08Z
user: login: zmitchell
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-04-09T19:20:19Z
user: login: zmitchell
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-04-09T19:20:29Z

Review comments:
diff_hunk: @@ -0,0 +1,134 @@
+---
+title: Composing environments
+description: How to combine and reuse environments.
+---
+
+# Composing environments
+
+When your company starts work on a new service, it's likely that the tools required to work on this service will be very similar to the tools used to work on other services at the company.
+Similarly, when you work on hobby projects it's likely that you use a similar set of tools from one project to the next.
+With other developer environment solutions it's common to need to need to recreate your developer environment from scratch for each new project.
path: docs/concepts/composition.md
user: login: dcarley
body: (non-blocking) "to need to need to" 😀 
```suggestion
With other developer environment solutions it's common to recreate your developer environment from scratch for each new project.
```
created_at: 2025-04-09T16:22:21Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,134 @@
+---
+title: Composing environments
+description: How to combine and reuse environments.
+---
+
+# Composing environments
+
+When your company starts work on a new service, it's likely that the tools required to work on this service will be very similar to the tools used to work on other services at the company.
+Similarly, when you work on hobby projects it's likely that you use a similar set of tools from one project to the next.
+With other developer environment solutions it's common to need to need to recreate your developer environment from scratch for each new project.
+
+With Flox you can define a toolchain or service once and _compose_ it with others to create a composed environment.
+Put another way, **with Flox you can create developer environments from reusable building blocks**.
+Reuse and composition are two features that have long been a Holy Grail for developer environments, and Flox makes these features friendly and easily accessible.
+
+## Building blocks
+
+Environments are the building blocks from which a "composed" environment is created.
+In this composition there is a hierarchy consisting of a "composing" environment and a list of "included" environments that it treats as dependencies.
+The manifests of the included and composing environments are merged and then the resulting "merged" manifest is locked and built.
+
+```d2 scale="0.9"
+composer: "Composing\nenvironment"
+
+includes: Included environments {
+  envA: Env A
+  envB: Env B
+  envC: Env C
+  direction: down
+  envA -> envB: Overridden by
+  envB -> envC: Overridden by
+}
+
+composer -> includes: Overrides
+```
+
+## Including an environment
+
+The included environments are declared in your manifest in the `include` table under the `environments` array.
+Each entry in this array is an "include descriptor", which specifies where to find the environment.
+
+```text
+IncludedEnvironments ::= [IncludeDescriptor]
+IncludeDescriptor    ::= PathEnvDescriptor | RemoteEnvDescriptor
path: docs/concepts/composition.md
user: login: dcarley
body: It seems unlikely that remote is going to be in the RC for Friday for next week's release. So shall we take these references out for now?
created_at: 2025-04-09T16:25:39Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,134 @@
+---
+title: Composing environments
+description: How to combine and reuse environments.
+---
+
+# Composing environments
+
+When your company starts work on a new service, it's likely that the tools required to work on this service will be very similar to the tools used to work on other services at the company.
+Similarly, when you work on hobby projects it's likely that you use a similar set of tools from one project to the next.
+With other developer environment solutions it's common to need to need to recreate your developer environment from scratch for each new project.
+
+With Flox you can define a toolchain or service once and _compose_ it with others to create a composed environment.
+Put another way, **with Flox you can create developer environments from reusable building blocks**.
+Reuse and composition are two features that have long been a Holy Grail for developer environments, and Flox makes these features friendly and easily accessible.
+
+## Building blocks
+
+Environments are the building blocks from which a "composed" environment is created.
+In this composition there is a hierarchy consisting of a "composing" environment and a list of "included" environments that it treats as dependencies.
+The manifests of the included and composing environments are merged and then the resulting "merged" manifest is locked and built.
+
+```d2 scale="0.9"
+composer: "Composing\nenvironment"
+
+includes: Included environments {
+  envA: Env A
+  envB: Env B
+  envC: Env C
+  direction: down
+  envA -> envB: Overridden by
+  envB -> envC: Overridden by
+}
+
+composer -> includes: Overrides
+```
+
+## Including an environment
+
+The included environments are declared in your manifest in the `include` table under the `environments` array.
+Each entry in this array is an "include descriptor", which specifies where to find the environment.
+
+```text
+IncludedEnvironments ::= [IncludeDescriptor]
+IncludeDescriptor    ::= PathEnvDescriptor | RemoteEnvDescriptor
+PathEnvDescriptor    ::= {
+  dir  = <PATH>
+, name = null | <STRING>
+}
+RemoteEnvDescriptor  ::= {
+  remote = <owner/name>
+, name   = null | <STRING>
+}
+```
+
+Just like you would use the `flox activate --dir` flag to specify an environment to activate by its path, you use the `dir` field to specify the path to an environment to include.
+Similarly, you use the `remote` field to specify the owner and name of an environment on FloxHub to include e.g. `"flox/some_env"`.
+Every environment has a name built-in, but sometimes there may be name conflicts, or you may just want to provide a different name.
+You can do so with the `name` field.
+
+An example `include` section is shown below:
+
+```toml
+[include]
+environments = [
+  { dir = "../myenv" },
+  { remote = "flox/some_env" },
+  # Override the name of this environment
+  { dir = "../other_env", name = "other" }
+]
+```
+
+The order in which the included environments are listed matters.
+The environments specified later in the list will override those earlier in the list.
+
+It is possible to push a composed environment to FloxHub, but not if it includes environments that exist locally e.g. environments that are specified with the `dir` field.
+
+## Merging process
path: docs/concepts/composition.md
user: login: dcarley
body: (non-blocking) There's a good chance that this is going to get out-of-step with the `manifest.toml` man page and the implementation. I think we should consider consolidating and linking at some point.
created_at: 2025-04-09T16:30:15Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,134 @@
+---
+title: Composing environments
+description: How to combine and reuse environments.
+---
+
+# Composing environments
+
+When your company starts work on a new service, it's likely that the tools required to work on this service will be very similar to the tools used to work on other services at the company.
+Similarly, when you work on hobby projects it's likely that you use a similar set of tools from one project to the next.
+With other developer environment solutions it's common to need to need to recreate your developer environment from scratch for each new project.
+
+With Flox you can define a toolchain or service once and _compose_ it with others to create a composed environment.
+Put another way, **with Flox you can create developer environments from reusable building blocks**.
+Reuse and composition are two features that have long been a Holy Grail for developer environments, and Flox makes these features friendly and easily accessible.
+
+## Building blocks
+
+Environments are the building blocks from which a "composed" environment is created.
+In this composition there is a hierarchy consisting of a "composing" environment and a list of "included" environments that it treats as dependencies.
+The manifests of the included and composing environments are merged and then the resulting "merged" manifest is locked and built.
+
+```d2 scale="0.9"
+composer: "Composing\nenvironment"
+
+includes: Included environments {
+  envA: Env A
+  envB: Env B
+  envC: Env C
+  direction: down
+  envA -> envB: Overridden by
+  envB -> envC: Overridden by
+}
+
+composer -> includes: Overrides
path: docs/concepts/composition.md
user: login: dcarley
body: This flow feels more natural to me because it's all in the same direction: 
![image](https://github.com/user-attachments/assets/3ec81642-a395-45a2-bad3-e97791e8c67b)

```suggestion
includes -> composer: Overridden by
```
created_at: 2025-04-09T16:34:17Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,134 @@
+---
+title: Composing environments
+description: How to combine and reuse environments.
+---
+
+# Composing environments
+
+When your company starts work on a new service, it's likely that the tools required to work on this service will be very similar to the tools used to work on other services at the company.
+Similarly, when you work on hobby projects it's likely that you use a similar set of tools from one project to the next.
+With other developer environment solutions it's common to need to need to recreate your developer environment from scratch for each new project.
+
+With Flox you can define a toolchain or service once and _compose_ it with others to create a composed environment.
+Put another way, **with Flox you can create developer environments from reusable building blocks**.
+Reuse and composition are two features that have long been a Holy Grail for developer environments, and Flox makes these features friendly and easily accessible.
+
+## Building blocks
+
+Environments are the building blocks from which a "composed" environment is created.
+In this composition there is a hierarchy consisting of a "composing" environment and a list of "included" environments that it treats as dependencies.
+The manifests of the included and composing environments are merged and then the resulting "merged" manifest is locked and built.
+
+```d2 scale="0.9"
+composer: "Composing\nenvironment"
+
+includes: Included environments {
+  envA: Env A
+  envB: Env B
+  envC: Env C
+  direction: down
+  envA -> envB: Overridden by
+  envB -> envC: Overridden by
+}
+
+composer -> includes: Overrides
+```
+
+## Including an environment
+
+The included environments are declared in your manifest in the `include` table under the `environments` array.
+Each entry in this array is an "include descriptor", which specifies where to find the environment.
+
+```text
+IncludedEnvironments ::= [IncludeDescriptor]
+IncludeDescriptor    ::= PathEnvDescriptor | RemoteEnvDescriptor
path: docs/concepts/composition.md
user: login: zmitchell
body: Is it going to be in the release? I'm fine having the docs slightly ahead of the CLI if they're going to be in sync by the release.
created_at: 2025-04-09T16:37:03Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,134 @@
+---
+title: Composing environments
+description: How to combine and reuse environments.
+---
+
+# Composing environments
+
+When your company starts work on a new service, it's likely that the tools required to work on this service will be very similar to the tools used to work on other services at the company.
+Similarly, when you work on hobby projects it's likely that you use a similar set of tools from one project to the next.
+With other developer environment solutions it's common to need to need to recreate your developer environment from scratch for each new project.
+
+With Flox you can define a toolchain or service once and _compose_ it with others to create a composed environment.
+Put another way, **with Flox you can create developer environments from reusable building blocks**.
+Reuse and composition are two features that have long been a Holy Grail for developer environments, and Flox makes these features friendly and easily accessible.
+
+## Building blocks
+
+Environments are the building blocks from which a "composed" environment is created.
+In this composition there is a hierarchy consisting of a "composing" environment and a list of "included" environments that it treats as dependencies.
+The manifests of the included and composing environments are merged and then the resulting "merged" manifest is locked and built.
+
+```d2 scale="0.9"
+composer: "Composing\nenvironment"
+
+includes: Included environments {
+  envA: Env A
+  envB: Env B
+  envC: Env C
+  direction: down
+  envA -> envB: Overridden by
+  envB -> envC: Overridden by
+}
+
+composer -> includes: Overrides
+```
+
+## Including an environment
+
+The included environments are declared in your manifest in the `include` table under the `environments` array.
+Each entry in this array is an "include descriptor", which specifies where to find the environment.
+
+```text
+IncludedEnvironments ::= [IncludeDescriptor]
+IncludeDescriptor    ::= PathEnvDescriptor | RemoteEnvDescriptor
path: docs/concepts/composition.md
user: login: zmitchell
body: That has an impact on how I write the tutorial
created_at: 2025-04-09T16:37:18Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,134 @@
+---
+title: Composing environments
+description: How to combine and reuse environments.
+---
+
+# Composing environments
+
+When your company starts work on a new service, it's likely that the tools required to work on this service will be very similar to the tools used to work on other services at the company.
+Similarly, when you work on hobby projects it's likely that you use a similar set of tools from one project to the next.
+With other developer environment solutions it's common to need to need to recreate your developer environment from scratch for each new project.
+
+With Flox you can define a toolchain or service once and _compose_ it with others to create a composed environment.
+Put another way, **with Flox you can create developer environments from reusable building blocks**.
+Reuse and composition are two features that have long been a Holy Grail for developer environments, and Flox makes these features friendly and easily accessible.
+
+## Building blocks
+
+Environments are the building blocks from which a "composed" environment is created.
+In this composition there is a hierarchy consisting of a "composing" environment and a list of "included" environments that it treats as dependencies.
+The manifests of the included and composing environments are merged and then the resulting "merged" manifest is locked and built.
+
+```d2 scale="0.9"
+composer: "Composing\nenvironment"
+
+includes: Included environments {
+  envA: Env A
+  envB: Env B
+  envC: Env C
+  direction: down
+  envA -> envB: Overridden by
+  envB -> envC: Overridden by
+}
+
+composer -> includes: Overrides
+```
+
+## Including an environment
+
+The included environments are declared in your manifest in the `include` table under the `environments` array.
+Each entry in this array is an "include descriptor", which specifies where to find the environment.
+
+```text
+IncludedEnvironments ::= [IncludeDescriptor]
+IncludeDescriptor    ::= PathEnvDescriptor | RemoteEnvDescriptor
path: docs/concepts/composition.md
user: login: dcarley
body: Let's say it won't.
created_at: 2025-04-09T16:42:09Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,134 @@
+---
+title: Composing environments
+description: How to combine and reuse environments.
+---
+
+# Composing environments
+
+When your company starts work on a new service, it's likely that the tools required to work on this service will be very similar to the tools used to work on other services at the company.
+Similarly, when you work on hobby projects it's likely that you use a similar set of tools from one project to the next.
+With other developer environment solutions it's common to need to need to recreate your developer environment from scratch for each new project.
path: docs/concepts/composition.md
user: login: zmitchell
body: Fixed
created_at: 2025-04-09T19:19:01Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,134 @@
+---
+title: Composing environments
+description: How to combine and reuse environments.
+---
+
+# Composing environments
+
+When your company starts work on a new service, it's likely that the tools required to work on this service will be very similar to the tools used to work on other services at the company.
+Similarly, when you work on hobby projects it's likely that you use a similar set of tools from one project to the next.
+With other developer environment solutions it's common to need to need to recreate your developer environment from scratch for each new project.
+
+With Flox you can define a toolchain or service once and _compose_ it with others to create a composed environment.
+Put another way, **with Flox you can create developer environments from reusable building blocks**.
+Reuse and composition are two features that have long been a Holy Grail for developer environments, and Flox makes these features friendly and easily accessible.
+
+## Building blocks
+
+Environments are the building blocks from which a "composed" environment is created.
+In this composition there is a hierarchy consisting of a "composing" environment and a list of "included" environments that it treats as dependencies.
+The manifests of the included and composing environments are merged and then the resulting "merged" manifest is locked and built.
+
+```d2 scale="0.9"
+composer: "Composing\nenvironment"
+
+includes: Included environments {
+  envA: Env A
+  envB: Env B
+  envC: Env C
+  direction: down
+  envA -> envB: Overridden by
+  envB -> envC: Overridden by
+}
+
+composer -> includes: Overrides
+```
+
+## Including an environment
+
+The included environments are declared in your manifest in the `include` table under the `environments` array.
+Each entry in this array is an "include descriptor", which specifies where to find the environment.
+
+```text
+IncludedEnvironments ::= [IncludeDescriptor]
+IncludeDescriptor    ::= PathEnvDescriptor | RemoteEnvDescriptor
path: docs/concepts/composition.md
user: login: zmitchell
body: Fixed
created_at: 2025-04-09T19:19:08Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,134 @@
+---
+title: Composing environments
+description: How to combine and reuse environments.
+---
+
+# Composing environments
+
+When your company starts work on a new service, it's likely that the tools required to work on this service will be very similar to the tools used to work on other services at the company.
+Similarly, when you work on hobby projects it's likely that you use a similar set of tools from one project to the next.
+With other developer environment solutions it's common to need to need to recreate your developer environment from scratch for each new project.
+
+With Flox you can define a toolchain or service once and _compose_ it with others to create a composed environment.
+Put another way, **with Flox you can create developer environments from reusable building blocks**.
+Reuse and composition are two features that have long been a Holy Grail for developer environments, and Flox makes these features friendly and easily accessible.
+
+## Building blocks
+
+Environments are the building blocks from which a "composed" environment is created.
+In this composition there is a hierarchy consisting of a "composing" environment and a list of "included" environments that it treats as dependencies.
+The manifests of the included and composing environments are merged and then the resulting "merged" manifest is locked and built.
+
+```d2 scale="0.9"
+composer: "Composing\nenvironment"
+
+includes: Included environments {
+  envA: Env A
+  envB: Env B
+  envC: Env C
+  direction: down
+  envA -> envB: Overridden by
+  envB -> envC: Overridden by
+}
+
+composer -> includes: Overrides
+```
+
+## Including an environment
+
+The included environments are declared in your manifest in the `include` table under the `environments` array.
+Each entry in this array is an "include descriptor", which specifies where to find the environment.
+
+```text
+IncludedEnvironments ::= [IncludeDescriptor]
+IncludeDescriptor    ::= PathEnvDescriptor | RemoteEnvDescriptor
+PathEnvDescriptor    ::= {
+  dir  = <PATH>
+, name = null | <STRING>
+}
+RemoteEnvDescriptor  ::= {
+  remote = <owner/name>
+, name   = null | <STRING>
+}
+```
+
+Just like you would use the `flox activate --dir` flag to specify an environment to activate by its path, you use the `dir` field to specify the path to an environment to include.
+Similarly, you use the `remote` field to specify the owner and name of an environment on FloxHub to include e.g. `"flox/some_env"`.
+Every environment has a name built-in, but sometimes there may be name conflicts, or you may just want to provide a different name.
+You can do so with the `name` field.
+
+An example `include` section is shown below:
+
+```toml
+[include]
+environments = [
+  { dir = "../myenv" },
+  { remote = "flox/some_env" },
+  # Override the name of this environment
+  { dir = "../other_env", name = "other" }
+]
+```
+
+The order in which the included environments are listed matters.
+The environments specified later in the list will override those earlier in the list.
+
+It is possible to push a composed environment to FloxHub, but not if it includes environments that exist locally e.g. environments that are specified with the `dir` field.
+
+## Merging process
path: docs/concepts/composition.md
user: login: zmitchell
body: I think that's a post-release thing. Part of the motivation for getting these in early is so that we can point at them for the bug bash, whereas it's not straightforward to get the manpages in early.
created_at: 2025-04-09T19:20:19Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,134 @@
+---
+title: Composing environments
+description: How to combine and reuse environments.
+---
+
+# Composing environments
+
+When your company starts work on a new service, it's likely that the tools required to work on this service will be very similar to the tools used to work on other services at the company.
+Similarly, when you work on hobby projects it's likely that you use a similar set of tools from one project to the next.
+With other developer environment solutions it's common to need to need to recreate your developer environment from scratch for each new project.
+
+With Flox you can define a toolchain or service once and _compose_ it with others to create a composed environment.
+Put another way, **with Flox you can create developer environments from reusable building blocks**.
+Reuse and composition are two features that have long been a Holy Grail for developer environments, and Flox makes these features friendly and easily accessible.
+
+## Building blocks
+
+Environments are the building blocks from which a "composed" environment is created.
+In this composition there is a hierarchy consisting of a "composing" environment and a list of "included" environments that it treats as dependencies.
+The manifests of the included and composing environments are merged and then the resulting "merged" manifest is locked and built.
+
+```d2 scale="0.9"
+composer: "Composing\nenvironment"
+
+includes: Included environments {
+  envA: Env A
+  envB: Env B
+  envC: Env C
+  direction: down
+  envA -> envB: Overridden by
+  envB -> envC: Overridden by
+}
+
+composer -> includes: Overrides
path: docs/concepts/composition.md
user: login: zmitchell
body: Makes sense
created_at: 2025-04-09T19:20:29Z
author_association: CONTRIBUTOR

PR comments:
user: login: github-actions[bot]
created_at: 2025-04-09T00:32:26Z
body: <!-- NETLIFY DEPLOY COMMENT GENERATED BY ACTIONS_NETLIFY - APP ID SHA256: 06b895323362c8b4abe7fd5b4a6903d01c93d35e6664ebc8f53b3f9eff66beaa -->
🚀 Deployed on https://23eed2c052db8b04ae4a473a64f38b00155a8e8f--floxdocs.netlify.app
author_association: NONE
user: login: github-actions[bot]
created_at: 2025-04-09T19:21:56Z
body: <!-- NETLIFY DEPLOY COMMENT GENERATED BY ACTIONS_NETLIFY - APP ID SHA256: 06b895323362c8b4abe7fd5b4a6903d01c93d35e6664ebc8f53b3f9eff66beaa -->
🚀 Deployed on https://5fe2887eef0859e813e4f2bf2283fec759cf87bd--floxdocs.netlify.app
author_association: NONE
user: login: github-actions[bot]
created_at: 2025-04-09T19:27:45Z
body: <!-- NETLIFY DEPLOY COMMENT GENERATED BY ACTIONS_NETLIFY - APP ID SHA256: 06b895323362c8b4abe7fd5b4a6903d01c93d35e6664ebc8f53b3f9eff66beaa -->
🚀 Deployed on https://fecceeb29c8b6b1a4f423ee0bb6664d30c960832--floxdocs.netlify.app
author_association: NONE