add nextflow d30e48d

nextflow/docs/modules/using-modules.md

@@ -0,0 +1,163 @@
+(using-modules-page)=
+
+# Using modules
+
+:::{versionadded} 26.04.0
+:::
+
+The Nextflow module system allows you to discover, install, and manage reusable modules from centralized registries.
+This page describes how to use modules in your pipelines.
+
+## Discovering modules
+
+Search for available modules using the `module search` command:
+
+```console
+$ nextflow module search alignment
+$ nextflow module search "quality control" -limit 10
+```
+
+Results include module names and descriptions.
+Use `-output json` for machine-readable output.
+
+See {ref}`module search <cli-module-search>` for the full command reference.
+
+## Installing modules
+
+Use the `module install` command to download modules from a registry into your project:
+
+```console
+$ nextflow module install nf-core/fastqc
+$ nextflow module install nf-core/fastqc -version 0.0.0-0c7146d
+```
+
+:::{note}
+Modules mirrored from nf-core do not follow standard semantic versioning.
+Instead, they use the format `0.0.0-<hash>`, where the suffix is a short portion of the nf-core module's commit hash.
+:::
+
+Nextflow stores installed modules in the `modules/` directory and creates a `.module-info` file alongside the module to record installation metadata such as the module checksum and registry URL.
+
+:::{tip}
+Commit the `modules/` directory to your Git repository to ensure reproducibility.
+:::
+
+See {ref}`module install <cli-module-install>` for the full command reference.
+
+## Listing installed modules
+
+View all modules installed in your project with the `module list` command:
+
+```console
+$ nextflow module list
+```
+
+The output shows each module's name, installed version, and whether it has been modified locally.
+Use `-output json` for machine-readable output.
+
+See {ref}`module list <cli-module-list>` for the full command reference.
+
+## Viewing module information
+
+Use the `module view` command to view metadata and a usage template for a module:
+
+```console
+$ nextflow module view nf-core/fastqc
+$ nextflow module view nf-core/fastqc -version 0.0.0-0c7146d
+```
+
+The output includes the module's version, URL, description, authors, maintainers, keywords, tools, input/output channels, and a generated usage template.
+Use `-output json` for machine-readable output.
+
+See {ref}`module view <cli-module-view>` for the full command reference.
+
+## Including modules
+
+Modules installed from a registry can be included by name:
+
+```nextflow
+include { FASTQC } from 'nf-core/fastqc'
+
+workflow {
+    reads = channel.fromPath('data/*.fastq')
+    reads = reads.map { fastq -> tuple([id: fastq.baseName], fastq) }
+    FASTQC(reads)
+}
+```
+
+Local modules must be included by relative path:
+
+```nextflow
+include { FASTQC } from './modules/local/fastqc'
+```
+
+See {ref}`syntax-include` for a full description of the include syntax.
+
+## Running modules directly
+
+For ad-hoc tasks or testing, run a module directly without creating a wrapper workflow:
+
+```console
+$ nextflow module run nf-core/fastqc --meta.id test_sample --reads sample1_R1.fastq.gz
+```
+
+:::{tip}
+Run `nextflow module view` to see the available inputs for a module.
+:::
+
+The command automatically downloads the module if it is not already installed.
+It accepts all standard Nextflow run options (`-profile`, `-resume`, etc.):
+
+```console
+$ nextflow module run nf-core/fastqc \
+    --meta.id test_sample \
+    --reads sample1_R1.fastq.gz \
+    -with-docker
+```
+
+Run a local module by specifying a path starting with `./` or `../`:
+
+```console
+$ nextflow module run ./modules/local/fastqc/main.nf \
+    --meta.id test_sample \
+    --reads sample1_R1.fastq.gz \
+    -with-docker
+```
+
+:::{note}
+The local module should define a single process, or else the command will fail.
+:::
+
+See {ref}`module run <cli-module-run>` for the full command reference.
+
+## Updating modules
+
+To update a module to a newer version, reinstall it with the desired version:
+
+```console
+$ nextflow module install nf-core/fastqc -version 0.0.0-c9h0bv4
+```
+
+Nextflow automatically verifies module integrity using a checksum stored in the `.module-info` file.
+If the module has local modifications, it will not be updated.
+Use the `-force` flag to overwrite local changes:
+
+```console
+$ nextflow module install nf-core/fastqc -version 0.0.0-c9h0bv4 -force
+```
+
+## Removing modules
+
+Use the `module remove` command to uninstall a module from your project:
+
+```console
+$ nextflow module remove nf-core/fastqc
+```
+
+By default, Nextflow removes both the module files and the `.module-info` file.
+Use flags to control this behavior:
+
+- `-keep-files`: Remove the `.module-info` file but keep the module files in the `modules/` directory.
+- `-force`: Remove the module directory even if it has no `.module-info` file or has local modifications.
+
+See {ref}`module remove <cli-module-remove>` for the full command reference.