From c8ce2d2174fe3eafc85aa2a9bb6cd36dc423d79e Mon Sep 17 00:00:00 2001
From: Xavier Delaruelle <xavier.delaruelle@cea.fr>
Date: Fri, 19 Nov 2021 07:22:35 +0100
Subject: [PATCH] doc: desc. setenv --set-if-undef in man/changes/NEWS

---
 NEWS.rst                  | 4 +++-
 doc/source/changes.rst    | 5 +++++
 doc/source/modulefile.rst | 8 +++++++-
 3 files changed, 15 insertions(+), 2 deletions(-)

diff --git a/NEWS.rst b/NEWS.rst
index 81513a4c..df0441f4 100644
--- a/NEWS.rst
+++ b/NEWS.rst
@@ -57,7 +57,9 @@ Modules 5.1.0 (not yet released)
   to perform no operation when modulefile is unloaded.
 * Add the ``--unset-on-unload`` option to the :mfcmd:`unsetenv` modulefile
   command to also unset environment variable when modulefile is unloaded.
-
+* Add the ``--set-if-undef`` option to the :mfcmd:`setenv` modulefile command
+  to set environment variable when modulefile is loaded only this variable is
+  not yet defined.
 
 .. _Code of conduct: https://github.com/cea-hpc/modules/blob/master/CODE_OF_CONDUCT.md
 
diff --git a/doc/source/changes.rst b/doc/source/changes.rst
index 629bb587..59261e18 100644
--- a/doc/source/changes.rst
+++ b/doc/source/changes.rst
@@ -717,6 +717,11 @@ Modules Specific Tcl Commands
  Starting with version ``5.1``, the ``--noop-on-unload`` option is added to
  perform no operation when modulefile is unloaded.
 
+:mfcmd:`setenv`
+
+ Starting with version ``5.1``, the ``--set-if-undef`` option is added to set
+ environment variable when modulefile is loaded only if not yet defined.
+
 :mfcmd:`unsetenv`
 
  When running on an unload evaluation, do not unset designated environment
diff --git a/doc/source/modulefile.rst b/doc/source/modulefile.rst
index 18335a10..3b2204b7 100644
--- a/doc/source/modulefile.rst
+++ b/doc/source/modulefile.rst
@@ -806,7 +806,7 @@ the *modulefile* is being loaded.
 
     .. versionadded:: 4.2
 
-.. mfcmd:: setenv variable value
+.. mfcmd:: setenv [--set-if-undef] variable value
 
  Set environment *variable* to *value*. The :mfcmd:`setenv` command will also
  change the process' environment. A reference using Tcl's env associative
@@ -822,6 +822,12 @@ the *modulefile* is being loaded.
  previous value cannot be restored! (Unless you handle it explicitly ... see
  below.)
 
+ When the ``--set-if-undef`` option is set, environment variable is defined
+ when *modulefile* is loaded only if not yet defined.
+
+    .. versionchanged:: 5.1
+       Option ``--set-if-undef`` added
+
 .. mfcmd:: source-sh shell script [arg...]
 
  Evaluate with *shell* the designated *script* with defined *arguments* to