Re: [PATCH v2 9/9] doc: git-init: clarify file modes in octal.

From: Junio C Hamano <gitster@pobox.com>
Date: Oct 28, 2021, 17:17 UTC
Message-ID: <xmqqilxhrrva.fsf@gitster.g>
In-Reply-To: <7eef3538f3c3015c4f446961ddca78e2868fe644.1635438124.git.gitgitgadget@gmail.com>

"Jean-Noël Avila via GitGitGadget"  <gitgitgadget@gmail.com> writes:

Show 24 quoted lines

> ---shared[=(false|true|umask|group|all|world|everybody|0xxx)]::
> +--shared[=(false|true|umask|group|all|world|everybody|<umask>)]::
>  
>  Specify that the Git repository is to be shared amongst several users.  This
>  allows users belonging to the same group to push into that
> @@ -110,13 +110,15 @@ the repository permissions.
>  
>  Same as 'group', but make the repository readable by all users.
>  
> -'0xxx'::
> +'<umask>'::
>  
> -'0xxx' is an octal number and each file will have mode '0xxx'. '0xxx' will
> -override users' umask(2) value (and not only loosen permissions as 'group' and
> -'all' does). '0640' will create a repository which is group-readable, but not
> -group-writable or accessible to others. '0660' will create a repo that is
> -readable and writable to the current user and group, but inaccessible to others.
> +'<umask>' is an 3-digit octal number prefixed with `0` and each file
> +will have mode '<umask>'. '<umask>' will override users' umask(2)
> +value (and not only loosen permissions as 'group' and 'all'
> +does). '0640' will create a repository which is group-readable, but
> +not group-writable or accessible to others. '0660' will create a repo
> +that is readable and writable to the current user and group, but
> +inaccessible to others.

Giving it a name that reflects the meaning is a great change.

Unfortunately, I think the original text is wrong to call it umask, as this is bitwise opposite of umask(2). umask 027 for example means that we *drop* bits 020 and 007, causing the group members *losing* write access, and other folks *losing* all access, from the resulting filesystem entity. But with this, as the description says, you would write "0640" to mean "group members cannot write, others have no access".

How about calling it <perm> (or <perm-bits>)?

----- >8 --------- >8 --------- >8 --------- >8 -----
From: Jean-Noël Avila <jn.avila@free.fr>
Subject: [PATCH] doc: git-init: clarify file modes in octal.

The previous explanation was mixing the format with the identity of the field.

Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
---

 * Giving a "3-digit octal prefixed with `0`" would work fine, but
   technically, the value is parsed as an octal without the `0`
   prefix and there is no requirement for the number of digits,
   either.  But giving a stricter-than-necessary instruction is
   probably a good idea in this case.  It makes the description
   simpler.

 Documentation/git-init.txt | 16 +++++++++-------
 1 file changed, 9 insertions(+), 7 deletions(-)

diff --git a/Documentation/git-init.txt b/Documentation/git-init.txt
index fdb7b3f367..af0d2ee182 100644
--- a/Documentation/git-init.txt
+++ b/Documentation/git-init.txt
@@ -79,7 +79,7 @@ repository.  If not specified, fall back to the default name (currently
 `master`, but this is subject to change in the future; the name can be
 customized via the `init.defaultBranch` configuration variable).
 
---shared[=(false|true|umask|group|all|world|everybody|0xxx)]::
+--shared[=(false|true|umask|group|all|world|everybody|<perm>)]::
 
 Specify that the Git repository is to be shared amongst several users.  This
 allows users belonging to the same group to push into that
@@ -110,13 +110,15 @@ the repository permissions.
 
 Same as 'group', but make the repository readable by all users.
 
-'0xxx'::
+'<perm>'::
 
-'0xxx' is an octal number and each file will have mode '0xxx'. '0xxx' will
-override users' umask(2) value (and not only loosen permissions as 'group' and
-'all' does). '0640' will create a repository which is group-readable, but not
-group-writable or accessible to others. '0660' will create a repo that is
-readable and writable to the current user and group, but inaccessible to others.
+'<perm>' is an 3-digit octal number prefixed with `0` and each file
+will have mode '<perm>'. '<perm>' will override users' umask(2)
+value (and not only loosen permissions as 'group' and 'all'
+does). '0640' will create a repository which is group-readable, but
+not group-writable or accessible to others. '0660' will create a repo
+that is readable and writable to the current user and group, but
+inaccessible to others.
 --
 
 By default, the configuration flag `receive.denyNonFastForwards` is enabled

-- 
2.33.1-984-g9137471b0c