ls / | sort-by modified | select ...$file_indices
# => Returns the 1st, 3rd, 5th, 7th, and 9th file in the directory, oldest-to-newest
```

Run `scope modules` again and notice that all of the commands from the submodules are re-exported into the `my-utils` module.

::: tip
While `export module` is the recommended and most common form, there is one module-design scenario in which `export use` is required -- `export use` can be used to _selectively export_ definitions from the submodule, something `export module` cannot do. See [Additional Examples - Selective Export](#selective-export-from-a-submodule) for an example.
:::

::: note
`module` without `export` defines only a local module; it does not export a submodule.
:::

## Documenting Modules

As with [custom commands](../custom_commands.md#documenting-your-command), modules can include documentation that can be viewed with `help <module_name>`. The documentation is simply a series of commented lines at the beginning of the module file. Let's document the `my-utils` module:

```nu
# A collection of helpful utility functions

export use ./increment.nu
export use ./range-into-list.nu
```

Now examine the help:

```nu
use my-utils *
help my-utils

# => A collection of helpful utility functions
```

Also notice that, because the commands from `increment` and `range-into-list` are re-exported with `export use ...`, those commands show up in the help for the main module as well.

## Environment Variables

Modules can define an environment using [`export-env`](/commands/docs/export-env.md). Let's extend our `my-utils` module with an environment variable export for a common directory where we'll place our modules in the future. This directory is (by default) in the `$env.NU_LIB_DIRS` search path discussed in [Using Modules - Module Path](./using_modules.md#module-path).

```nu
# A collection of helpful utility functions

export use ./increment.nu
export use ./range-into-list.nu

export-env {
    $env.NU_MODULES_DIR = ($nu.default-config-dir | path join "scripts")
}
```

When this module is imported with `use`, the code inside the [`export-env`](/commands/docs/export-env.md) block is run and the its environment merged into the current scope:

```nu
use my-utils
$env.NU_MODULES_DIR
# => Returns the directory name
cd $env.NU_MODULES_DIR
```

::: tip
As with any command defined without `--env`, commands and other definitions in the module use their own scope for environment. This allows changes to be made internal to the module without them bleeding into the user's scope. Add the following to the bottom of `my-utils/mod.nu`:

```nu
export def examine-config-dir [] {
    # Changes the PWD environment variable
    cd $nu.default-config-dir
    ls
}
```

Running this command changes the directory _locally_ in the module, but the changes are not propagated to the parent scope.

:::

## Caveats

### `export-env` runs only when the `use` call is _evaluated_

::: note
This scenario is commonly encountered when creating a module that uses `std/log`.
:::

Attempting to import a module's environment within another environment may not work as expected. Let's create a new module `go.nu` that creates "shortcuts" to common directories. One of these will be the `$env.NU_MODULES_DIR` defined above in `my-utils`.

We might try:

```nu
# go.nu, in the parent directory of my-utils
use my-utils

export def --env home [] {
    cd ~
}

export def --env modules [] {
    cd $env.NU_MODULES_DIR
}
```

And then import it:

```nu
use go.nu
go home
# => Works
go modules
# => Error: $env.NU_MODULES_DIR is not found
```

This doesn't work because `my-utils` isn't _evaluated_ in this case; it is only _parsed_ when the `go.nu` module is imported. While this brings all of the other exports into scope, it does not _run_ the `export-env` block.

::: important
As mentioned at the start of this chapter, trying this while `my-utils` (and its `$env.NU_MODULES_DIR`) is still in scope from a previous import will _not_ fail as expected. Test in a new shell session to see the "normal" failure.