[PATCH] docs: update username= option to drop invalid examples

[PATCH] docs: update username= option to drop invalid examples

[Martin Schwenke]

[-- Attachment #1: Type: text/plain, Size: 443 bytes --]

When hurrying and scanning the documentation, my eye was drawn to the
examples ``user%password`` or ``workgroup/user`` and
``workgroup/user%password``, especially because they were rendered in
bold in my terminal.  I didn't read them in the context of them being
deprecated and experienced a non-zero amount of frustration when they
didn't work.  Given that these no longer work at all, remove them and
add clarity.

peace & happiness,
martin

[-- Attachment #2: 0001-docs-update-username-option-to-drop-invalid-examples.patch --]
[-- Type: text/x-patch, Size: 2320 bytes --]

From 036719fde9b55a07831bf015e0e58ed2fbf7bc05 Mon Sep 17 00:00:00 2001
From: Martin Schwenke <martin@meltin.net>
Date: Wed, 10 Sep 2025 19:07:48 +1000
Subject: [PATCH] docs: update username= option to drop invalid examples

When hurrying and scanning the documentation, my eye was drawn to the
examples ``user%password`` or ``workgroup/user`` and
``workgroup/user%password``, especially because they were rendered in
bold in my terminal.  I didn't read them in the context of them being
deprecated and experienced a non-zero amount of frustration when they
didn't work.  Given that these no longer work at all, remove them and
add clarity.

Signed-off-by: Martin Schwenke <martin@meltin.net>
---
 mount.cifs.rst | 19 ++++++++-----------
 1 file changed, 8 insertions(+), 11 deletions(-)

diff --git a/mount.cifs.rst b/mount.cifs.rst
index d489070..936cacb 100644
--- a/mount.cifs.rst
+++ b/mount.cifs.rst
@@ -57,17 +57,14 @@ username=arg|user=arg
   specifies the username to connect as. If this is not
   given, then the environment variable USER is used.
 
-  Earlier versions of mount.cifs also allowed one to specify the
-  username in a ``user%password`` or ``workgroup/user`` or
-  ``workgroup/user%password`` to allow the password and workgroup to
-  be specified as part of the username. Support for those alternate
-  username formats is now deprecated and should no longer be
-  used. Users should use the discrete ``password=`` and ``domain=`` to
-  specify those values. While some versions of the cifs kernel module
-  accept ``user=`` as an abbreviation for this option, its use can
-  confuse the standard mount program into thinking that this is a
-  non-superuser mount. It is therefore recommended to use the full
-  ``username=`` option name.
+  Users must use the discrete ``password=`` and ``domain=`` options to
+  specify relevant values. Including these in the ``username=`` option
+  is no longer supported.
+
+  While some versions of the cifs kernel module accept ``user=`` as an
+  abbreviation for this option, its use can confuse the standard mount
+  program into thinking that this is a non-superuser mount. It is
+  therefore recommended to use the full ``username=`` option name.
 
 password=arg|pass=arg
   specifies the CIFS password. If this option is not given then the
-- 
2.47.3

Re: [PATCH] docs: update username= option to drop invalid examples

[Steve French]

Merged into cifs-utils for-next

On Wed, Sep 10, 2025 at 4:57 AM Martin Schwenke <martin@meltin.net> wrote:
>
> When hurrying and scanning the documentation, my eye was drawn to the
> examples ``user%password`` or ``workgroup/user`` and
> ``workgroup/user%password``, especially because they were rendered in
> bold in my terminal.  I didn't read them in the context of them being
> deprecated and experienced a non-zero amount of frustration when they
> didn't work.  Given that these no longer work at all, remove them and
> add clarity.
>
> peace & happiness,
> martin



-- 
Thanks,

Steve