Re: [Patch] Documentation: enhanced "git for CVS users" doc about shared repositories

Francesco Pretto [off-list ref] writes:

This part seems an unnecessary change.

Don't assume the "admin privilege" part, as you do not have to.

You are newly hired to work on project-X, and the sysadm throws
you into projectx group.  Thesysadm further prepares a directory
'/pub/project-X' and makes it mode 2775 (aka ug=rwx,o=rx,g+s).

Do you want to create a new repository for projext-X group's
use?  You do:

	$ cd /pub/project-X
        $ GIT_DIR=mine.git git init --shared

and you now have a usable /pub/project-X/mine.git repository for
project members.  I do not think you would need any chmod/chgrp
after this step.

+First, let's create a common directory for all the projects you'll want to
+track with git:
+
+-----------------------------------------------
+$ mkdir -p /pub/scm
+-----------------------------------------------

An organization may use different SCM depending on the projects'
needs, and there is no reason members of projects A and B should
be in the same group 'git' while having members of project C in
group 'hg' only because A and B happen to use git.  It would
make more sense to either (1) make members of all three projects
belong to 'src' group, or (2) make three groups, one for each
project.

IOW, I do not think the above is a good suggestion.

Also with the "create new --shared repository for the project in
a group's directory that has mode 2755" approach, I do not think
there is any need to muck with umask either.

Junio C Hamano ha scritto:

quoted

 ------------------------------------------------
-$ git clone foo.com:/pub/repo.git/ my-project
+$ git clone foo.com:/pub/scm/repo.git/ my-project
 $ cd my-project
 ------------------------------------------------

This part seems an unnecessary change.

Ironically, that's the same configuration of git.kernel.org. And I think is better
to put immediately the project in a appropriate directory than to move it later.

Don't assume the "admin privilege" part, as you do not have to.

Admin privilege SHALL be assumed, as this is a first time configuration, and the best
we can do is to assume it's done on a default *nix installation. Moreover, it's
what HEAD documentation is already doing when it suggests to give users ssh access.

Let's suppose the user "user1" create its own repository on a remote machine.
Now, he wants to selectively give write access on its repository to "user2".
There's 2 cases:
    1) "user2" have a local/ssh account on the machine. In this case, "user1" want
       to be sure only "user2" can write to the repository, so he can ask the admin
       to put "user1" and "user2" in the same group "projectx" or ask him to enable
       ACLs, still turned off in the majority of *nix systems.
    2) "user2" haven't a local/ssh account. Here:
	- a local/ssh account should be given to "user2", returning to 1)
        - mod_dav module has to be enabled for public http dirs of "user1"
        - git daemon has to be started and enabled to write on the repository.

The last 3 tasks all require admin privilege on default linux/bsd/macosx
installations. However, a little distinction can be made. I'll see.

needs, and there is no reason members of projects A and B should
be in the same group 'git'

I agree!

while having members of project C in
group 'hg' only because A and B happen to use git.

I agree!

belong to 'src' group, or (2) make three groups, one for each
project.

It's exactly the point of:

+It's recommended, but not necessary, to create a specific group of commiters
+for every project/repository. With root credentials launch:
+
+------------------------------------------------
+$ groupadd $group
+------------------------------------------------

What you have understood here?

Also with the "create new --shared repository for the project in
a group's directory that has mode 2755" approach, I do not think
there is any need to muck with umask either.

umask requirement is referred to previous version of git. It's still referred as actual
in HEAD documentation. If it's ok for you, we could just cut away that reference.

Conclusion: i can try to amend my patch to be even more clearer. What i am saying
is that official documentation, commands manuals/syntaxes should be easy enough to the
first time user to set up git repositories without looking up the web for
"git tutorial"/"git installation"/"git umask 002", etc. (and consider that even an
expert sysadmin is a first time user, when he install and set up git the first time).
Or was better a "Documentation S**KS!" bug report?

Hi,

On Tue, 6 Nov 2007, Francesco Pretto wrote:

Junio C Hamano ha scritto:

quoted

quoted

 ------------------------------------------------
-$ git clone foo.com:/pub/repo.git/ my-project
+$ git clone foo.com:/pub/scm/repo.git/ my-project
 $ cd my-project
 ------------------------------------------------

This part seems an unnecessary change.

Ironically, that's the same configuration of git.kernel.org. And I think 
is better to put immediately the project in a appropriate directory than 
to move it later.

For most people, neither path is correct.  So I really don't see your 
point.

Ciao,
Dscho

Johannes Schindelin ha scritto:

For most people, neither path is correct.

Yeah, I agree. I'll try to reflect this with a neutral wording :-)
In the context of the documentation, we should just take care of logical
following the example.

Signed-off-by: Francesco Pretto <redacted>
---
 More detailed instructions on how to set up shared repositories.
 Removed an old reference to the need of setting umask of ssh
 users of shared repositories.
 Added a reference to "git for CVS users" doc in git-init manual.

 Documentation/cvs-migration.txt |   61 +++++++++++++++++++++++++++++++++++----
 Documentation/git-init.txt      |    7 ++++
 2 files changed, 62 insertions(+), 6 deletions(-)

diff --git a/Documentation/cvs-migration.txt b/Documentation/cvs-migration.txt
index 3b6b494..849b403 100644
--- a/Documentation/cvs-migration.txt
+++ b/Documentation/cvs-migration.txt

@@ -71,7 +71,40 @@ Setting Up a Shared Repository
 We assume you have already created a git repository for your project,
 possibly created from scratch or from a tarball (see the
 link:tutorial.html[tutorial]), or imported from an already existing CVS
-repository (see the next section).
+repository (see the next section). Moreover, we assume you can write in a
+public accessible directory and give other users the permission to do so.
+You could need or not admin privileges to do so, depending on your
+system configuration and how you decide to export the repository.
+
+It's recommended, but not strictly necessary, to create a specific group for
+every project/repository you'll want to create, so it will be easier to give
+or prevent access of users to specific repositories. With admin privilege launch:
+
+------------------------------------------------
+$ groupadd $group
+------------------------------------------------
+
+If you want to add an user to this group, launch:
+
+------------------------------------------------
+$ usermod -a -G $group $username
+------------------------------------------------
+
+In our example, we will store the shared repository in the /pub dir, so the
+user creating it will need write permission there. There's no problems if you
+choose another directory, but you'll have to ensure it will be accessible by
+other users, on local or by remote (this could be not the case of home
+directories).
+
+If you just want to create a directory that is writable by every users that have
+a local account, launch with privileged credentials:
+
+------------------------------------------------
+$ mkdir /pub
+$ chmod a+w,+t /pub
+------------------------------------------------
+
+Now you can proceed with an unprivileged user.
 
 Assume your existing repo is at /home/alice/myproject.  Create a new "bare"
 repository (a repository without a working tree) and fetch your project into

@@ -84,21 +117,37 @@ $ git --bare init --shared
 $ git --bare fetch /home/alice/myproject master:master
 ------------------------------------------------
 
+If you previously decided to create a specific group for the committers of the
+repository, assign its ownership to that group (you'll have to be a member of it
+or switch to privileged credentials):
+
+------------------------------------------------
+$ chgrp -R $group /pub/my-repo.git
+------------------------------------------------
+
 Next, give every team member read/write access to this repository.  One
 easy way to do this is to give all the team members ssh access to the
 machine where the repository is hosted.  If you don't want to give them a
 full shell on the machine, there is a restricted shell which only allows
 users to do git pushes and pulls; see gitlink:git-shell[1].
 
-Put all the committers in the same group, and make the repository
-writable by that group:
+The following two commands will require admin privileges; first, enable
+git-shell putting it on the trusted shells list of the system:
 
 ------------------------------------------------
-$ chgrp -R $group /pub/my-repo.git
+$ echo `which git-shell` >> /etc/shells
+------------------------------------------------
+
+Now, let's create the commit users:
+
+------------------------------------------------
+$ useradd -g $group -s `which git-shell` $username
 ------------------------------------------------
 
-Make sure committers have a umask of at most 027, so that the directories
-they create are writable and searchable by other group members.
+These users will be enabled to push on repositories owned by the group $group.
+Later, you can give access to other projects simply by adding them to
+other groups. Similarly, you can prevent access to repositories simply
+removing those users from related groups.
 
 Importing a CVS archive
 -----------------------

diff --git a/Documentation/git-init.txt b/Documentation/git-init.txt
index 07484a4..f5f363d 100644
--- a/Documentation/git-init.txt
+++ b/Documentation/git-init.txt

@@ -101,6 +101,13 @@ $ git-add .     <2>
 <2> add all existing file to the index
 
 
+SHARED REPOSITORIES
+-------------------
+
+Please refer to link:cvs-migration.html[git for CVS users], section "Setting Up
+a Shared Repository", for details on how to set up shared repositories.
+
+
 Author
 ------
 Written by Linus Torvalds <torvalds@osdl.org>