How shall I understand the synopsis of this command?

Help
1

https://nixos.org/manual/nix/stable/command-ref/nix-shell.html

Synopsis

nix-shell [–arg name value] [–argstr name value] [{–attr | -A}
attrPath] [–command cmd] [–run cmd] [–exclude regexp] [–pure]
[–keep name] {{–packages | -p} {packages | expressions} … | [path]}

and

Examples

$ nix-shell '<nixpkgs>' --attr pan

What role in its synopsis does '<nixpkgs>' play?

Is it path? If yes,

  • does path specify the package collection from which the package specified after --attr comes?

  • why isn’t it specified at the end of the command?

2

Yes, it is the path argument.

The fact that the contents of path argument is not described other than as “derivation path” + special case for https?:// should probably be considered as documentation bug. Looks like in addition to URLs, it can take whatever is accepted by path value, including lookup paths.

Indeed:

[nix-shell] will then start an interactive shell in which all environment variables defined by the derivation path have been set to their corresponding values, and the script $stdenv/setup has been sourced.

[--attr selects] an attribute from the top-level Nix expression being evaluated.

For concrete examples:

  • nix-shell foo/bar would more or less evaluate the expression equivalent to possiblyFillInArgumentsIfTheResultIsAFunction (import ./foo/bar/default.nix) and use the resulting derivation environment & co.
  • nix-shell foo/bar --attr hello would similarly evaluate the expression corresponding to (possiblyFillInArgumentsIfTheResultIsAFunction (import ./foo/bar/default.nix)).hello.

Order of arguments of CLI programs usually does not matter unless explicitly specified.

It is probably listed in the docs last because it is orthogonal to the --packages flag which is conventionally used last just like the --attr flag:

{
  {--packages | -p} {packages | expressions} …
  | [path]
}

(With --packages, derivation is not loaded from any path but rather created by Nix at runtime.)