docs: monorepo guide

Author: domenkozar

docs/guides/.nav.yml

@@ -1,3 +1,4 @@
 nav:
-   - Using with Flakes: using-with-flakes.md
-   - Using with flake.parts: using-with-flake-parts.md
+  - Monorepo: monorepo.md
+  - Using with Flakes: using-with-flakes.md
+  - Using with flake.parts: using-with-flake-parts.md

docs/guides/monorepo.md

@@ -0,0 +1,143 @@
+# Monorepo with Shared Configurations
+
+!!! info "New in version 2.10"
+
+This guide shows how to structure a monorepo where multiple services share common configurations.
+
+!!! tip
+    [Profiles](../profiles.md) provide another powerful way to organize development environments by allowing different variations to activate automatically based on your hostname, username, or manually via CLI flags. They work particularly well with monorepo structures for managing team-specific or environment-specific configurations.
+
+## Project Structure
+
+```
+my-monorepo/
+├── devenv/
+│   └── devenv.nix       # Shared configurations
+├── services/
+│   ├── api/
+│   │   ├── devenv.yaml
+│   │   └── devenv.nix
+│   └── frontend/
+│       ├── devenv.yaml
+│       └── devenv.nix
+```
+
+## Shared Configuration
+
+Create a shared configuration with common settings:
+
+```nix title="devenv/devenv.nix"
+{ pkgs, ... }: {
+  packages = [
+    pkgs.curl
+    pkgs.jq
+  ];
+
+  services.postgres = {
+    enable = true;
+    initialDatabases = [
+      { name = "myapp"; }
+    ];
+  };
+
+  pre-commit.hooks = {
+    prettier.enable = true;
+    nixpkgs-fmt.enable = true;
+  };
+}
+```
+
+## Service Configuration
+
+### API Service
+
+Each service imports the shared configuration using an **absolute import path**. Paths starting with `/` are resolved from the repository root (where `.git` is located), allowing services in different directories to reference shared configurations consistently.
+
+```yaml title="services/api/devenv.yaml"
+imports:
+  - /devenv
+```
+
+```nix title="services/api/devenv.nix"
+{ pkgs, ... }: {
+  # Node.js for the API
+  languages.javascript = {
+    enable = true;
+    package = pkgs.nodejs_20;
+  };
+
+  # API-specific environment
+  env = {
+    API_PORT = "3000";
+    SERVICE_NAME = "api";
+  };
+
+  # API scripts
+  scripts = {
+    dev.exec = "npm run dev";
+    test.exec = "npm test";
+  };
+}
+```
+
+### Frontend Service
+
+```yaml title="services/frontend/devenv.yaml"
+imports:
+  - /devenv
+```
+
+```nix title="services/frontend/devenv.nix"
+{ pkgs, ... }: {
+  languages.javascript = {
+    enable = true;
+    package = pkgs.nodejs_20;
+  };
+
+  # Frontend scripts
+  scripts = {
+    dev.exec = "npm run dev";
+    build.exec = "npm run build";
+  };
+}
+```
+
+## Referencing the Repository Root
+
+When working in a monorepo, you often need to reference paths relative to the repository root. Use `config.git.root` to get the absolute path to the git repository root.
+
+This is particularly useful for running processes from specific directories:
+
+```nix title="services/api/devenv.nix"
+{ pkgs, config, ... }: {
+  processes.api.exec = {
+    exec = "npm run dev";
+    cwd = "${config.git.root}/services/api";
+  };
+
+  processes.frontend.exec = {
+    exec = "npm run dev";
+    cwd = "${config.git.root}/services/frontend";
+  };
+}
+```
+
+This allows you to run multiple service processes from a single devenv shell, regardless of which directory you're in.
+
+## Working with Services
+
+Enter a specific service environment:
+
+```bash
+cd services/api
+devenv shell
+```
+
+The API service will have access to:
+
+- All packages from `shared/devenv.nix` (git, curl, jq)
+- The PostgreSQL database service
+- Common environment variables (PROJECT_NAME, ENVIRONMENT, DATABASE_URL)
+- Its own specific settings (API_PORT, SERVICE_NAME)
+
+Similarly, the frontend service inherits the shared configuration while maintaining its own specific settings.

docs/reference/yaml-options.md

@@ -4,11 +4,7 @@
 |---------------------------------------------------------------|-------------------------------------------------------------------------------|
 | clean.enabled                                                 | Clean the environment when entering the shell. Defaults to `false`.           |
 | clean.keep                                                    | A list of environment variables to keep when cleaning the environment.        |
-<<<<<<< HEAD
-| imports                                                       | A list of relative paths or references to inputs to import ``devenv.nix``.    |
-=======
 | imports                                                       | A list of relative paths, absolute paths, or references to inputs to import ``devenv.nix`` and ``devenv.yaml`` files. |
->>>>>>> c88e9857 (feat: implement configuration merging for devenv.yaml imports)
 | impure                                                        | Relax the hermeticity of the environment.                                     |
 | inputs                                                        | Defaults to `inputs.nixpkgs.url: github:cachix/devenv-nixpkgs/rolling`.       |
 | inputs.&lt;name&gt;                                           | Identifier name used when passing the input in your ``devenv.nix`` function.  |
@@ -90,13 +86,15 @@ imports:
   - ./frontend
   - ./backend
   - ./mymodule.nix
+  - /absolute/path/from/git/root
   - myproject
   - myproject/relative/path
 ```
 
 !!! note "Added in 1.10"
 
     - local imports now merge `devenv.yaml` (remote inputs not yet supported)
+    - absolute path support in imports: `/absolute/path/from/git/root`
 
 !!! note "Added in 1.0"