This module is imported using `use increment` (without the glob `*`) and results in the same `increment` command and `increment by` subcommand.

::: note
We'll continue to use this version for further examples below, so notice that the import pattern has changed to `use increment` (rather than `use increment *`) below.
:::

## Submodules

Submodules are modules that are exported from another module. There are two ways to add a submodule to a module:

1. With `export module`: Exports (a) the submodule and (b) its definitions as members of the submodule
2. With `export use`: Exports (a) the submodule and (b) its definitions as members of the parent module

To demonstrate the difference, let's create a new `my-utils` module, with our `increment` example as a submodule. Additionally, we'll create a new `range-into-list` command in its own submodule.

1. Create a directory for the new `my-utils` and move the `increment.nu` into it

   ```nu
   mkdir my-utils
   # Adjust the following as needed
   mv increment/mod.nu my-utils/increment.nu
   rm increment
   cd my-utils
   ```

2. In the `my-utils` directory, create a `range-into-list.nu` file with the following:

   ```nu
   export def main []: range -> list {
       # It looks odd, yes, but the following is just
       # a simple way to convert ranges to lists
       each {||}
   }
   ```

3. Test it:

   ```nu
   use range-into-list.nu
   1..5 | range-into-list | describe
   # => list<int> (stream)
   ```

4. We should now have a `my-utils` directory with the:

   - `increment.nu` module
   - `range-into-list.nu` module

The following examples show how to create a module with submodules.

### Example: Submodule with `export module`

The most common form for a submodule definition is with `export module`.

1. Create a new module named `my-utils`. Since we're in the `my-utils` directory, we will create a `mod.nu` to define it. This version of `my-utils/mod.nu` will contain:

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

2. We now have a module `my-utils` with the two submodules. Try it out:

   ```nu
   # Go to the parent directory of my-utils
   cd ..
   use my-utils *
   5 | increment by 4
   # => 9

   let file_indices = 0..2..<10 | range-into-list
   ls | select ...$file_indices
   # => Returns the 1st, 3rd, 5th, 7th, and 9th file in the directory
   ```

Before proceeding to the next section, run `scope modules` and look for the `my-utils` module. Notice that it has no commands of its own; just the two submodules.

### Example: Submodule with `export use`

Alternatively, we can (re)export the _definitions_ from other modules. This is slightly different from the first form, in that the commands (and other definitions, if they were present) from `increment` and `range-into-list` become _members_ of the `my-utils` module itself. We'll be able to see the difference in the output of the `scope modules` command.

Let's change `my-utils/mod.nu` to:

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

Try it out using the same commands as above:

```nu
# Go to the parent directory of my-utils
cd ..
use my-utils *
5 | increment by 4
# => 9

let file_indices = 0..2..<10 | range-into-list
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: