Merge pull request #324 from hercules-ci/issue-323

Document attribute escaping

extras/bundlers.nix

@@ -29,6 +29,13 @@ mkTransposedPerSystemModule {
       `nix bundle --bundler .#<name> .#<package>` bundles `<package>` using bundler `<name>`.
 
       Define a `default` bundler to use `nix bundle --bundler .#`.
+
+      Attribute names containing special characters like `.` must be doubly quoted when used in installable arguments:
+      ```bash
+      nix bundle --bundler '.#"example.com"' .#package
+      ```
+
+      Consider using `:` or `/` as separators instead (e.g., `foo:bar`) for better command-line usability.
     '';
   };
   file = ./bundlers.nix;

modules/apps.nix

@@ -49,7 +49,16 @@ mkTransposedPerSystemModule {
     type = types.lazyAttrsOf appType;
     default = { };
     description = ''
-      Programs runnable with nix run `<name>`.
+      An attribute set of programs runnable with [`nix run`](https://nixos.org/manual/nix/stable/command-ref/new-cli/nix3-run.html).
+
+      `nix run .#<name>` will run `apps.<name>`.
+
+      Attribute names containing special characters like `.` must be doubly quoted when used in installable arguments:
+      ```bash
+      nix run '.#"example.com"'
+      ```
+
+      Consider using `:` or `/` as separators instead (e.g., `foo:bar`) for better command-line usability.
     '';
     example = lib.literalExpression ''
       {

modules/devShells.nix

@@ -16,7 +16,15 @@ mkTransposedPerSystemModule {
     default = { };
     description = ''
       An attribute set of packages to be used as shells.
+
       [`nix develop .#<name>`](https://nixos.org/manual/nix/stable/command-ref/new-cli/nix3-develop.html) will run `devShells.<name>`.
+
+      Attribute names containing special characters like `.` must be doubly quoted when used in installable arguments:
+      ```bash
+      nix develop '.#"example.com"'
+      ```
+
+      Consider using `:` or `/` as separators instead (e.g., `foo:bar`) for better command-line usability.
     '';
     example = literalExpression ''
       {

modules/legacyPackages.nix

@@ -15,6 +15,16 @@ mkTransposedPerSystemModule {
     default = { };
     description = ''
       An attribute set of unmergeable values. This is also used by [`nix build .#<attrpath>`](https://nixos.org/manual/nix/stable/command-ref/new-cli/nix3-build.html).
+
+      `legacyPackages` supports nested attribute sets. Use `.` to access nested attributes:
+      `.#foo.bar` refers to the `bar` attribute in `foo`.
+
+      Attribute names that literally contain special characters like `.` must be doubly quoted when used in installable arguments:
+      ```bash
+      nix build '.#"example.com"'
+      ```
+
+      Consider using `:` or `/` as separators instead (e.g., `foo:bar`) for better command-line usability.
     '';
   };
   file = ./legacyPackages.nix;

modules/packages.nix

@@ -17,6 +17,17 @@ mkTransposedPerSystemModule {
       An attribute set of packages to be built by [`nix build`](https://nixos.org/manual/nix/stable/command-ref/new-cli/nix3-build.html).
 
       `nix build .#<name>` will build `packages.<name>`.
+
+      You can also build attributes of a package using `.` to access nested attributes:
+      `.#foo.tests.simple` builds the `simple` attribute in `foo.tests`.
+      This is a Nixpkgs convention (packages having "passthru" attributes like `tests`) which gets no special treatment in Flakes.
+
+      Attribute names containing special characters like `.` must be doubly quoted when used in installable arguments:
+      ```bash
+      nix build '.#"example.com"'
+      ```
+
+      Consider using `:` or `/` as separators instead (e.g., `foo:bar`) for better command-line usability.
     '';
   };
   file = ./packages.nix;