Documentation: enhanced "git for CVS users" doc about shared repositories

More detailed instructions on how to set up shared repositories. Added a reference to "git for CVS users" doc in git-init manual.

---
 Documentation/cvs-migration.txt |   72 ++++++++++++++++++++++++++++++--------
 Documentation/git-init.txt      |    7 ++++
 2 files changed, 64 insertions(+), 15 deletions(-)

index 3b6b494..c92ed49 100644
@@ -13,12 +13,12 @@ link:tutorial.html[tutorial introduction to git] should be sufficient.
 Developing against a shared repository
 --------------------------------------
 
-Suppose a shared repository is set up in /pub/repo.git on the host
+Suppose a shared repository is set up in /pub/scm/repo.git on the host
 foo.com.  Then as an individual committer you can clone the shared
 repository over ssh with:
 
 ------------------------------------------------
-$ git clone foo.com:/pub/repo.git/ my-project
+$ git clone foo.com:/pub/scm/repo.git/ my-project
 $ cd my-project
 ------------------------------------------------
 

@@ -68,37 +68,79 @@ other than `master`.
 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).
+We assume you have admin privilege on the remote machine. Moreover, 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).
 
-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
-it:
+First, let's create a common directory for all the projects you'll want to
+track with git:
+
+-----------------------------------------------
+$ mkdir -p /pub/scm
+-----------------------------------------------
+
+It's recommended, but not necessary, to create a specific group of commiters
+for every project/repository. With root credentials launch:
+
+------------------------------------------------
+$ groupadd $group
+------------------------------------------------
+
+Assume your existing repository is at /home/alice/myproject.  Create a new
+"bare" repository (a repository without a working tree) and fetch your project
+into it:
 
 ------------------------------------------------
-$ mkdir /pub/my-repo.git
+$ mkdir /pub/scm/my-repo.git
 $ cd /pub/my-repo.git
 $ git --bare init --shared
 $ git --bare fetch /home/alice/myproject master:master
 ------------------------------------------------
 
+Now, set the group ownership of the git repository you've just created to the
+same group of the commiters:
+
+------------------------------------------------
+$ chgrp -R $group /pub/scm/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:
+First, enable it putting on the trusted shells list of the system:
+
+------------------------------------------------
+$ echo `which git-shell` >> /etc/shells
+------------------------------------------------
+
+Ensure users will not have write permission on /pub/scm. Now, let's create
+them with the following command launched with root credentials:
 
 ------------------------------------------------
-$ chgrp -R $group /pub/my-repo.git
+$ useradd -g $group -d /pub/scm -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.
+They will be enabled to push on repositories owned by the group $group.
+Later, you can give users access to other projects simply by adding them to
+other groups.
+
+[NOTE]
+================================
+With previous versions of git, it could be necessary to set umask variable of
+all commiters with values like 002 or 007. If you still need to support them,
+you can do it in the following way; assuming that all users have their home
+positionated at /pub/scm, like in the previous example, launch the command:
+
+------------------------------------------------
+$ echo "umask 022" >> /pub/scm/.profile
+------------------------------------------------
+
+At the next login, users will have their umask variable automatically set.
+================================
 
 Importing a CVS archive
 -----------------------

index 07484a4..f5f363d 100644
@@ -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 <[email protected]>

Junio C Hamano ha scritto:

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.

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.

I agree!

I agree!

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?

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,

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

Ciao,
Dscho

Johannes Schindelin ha scritto:

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.

---
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(-)

index 3b6b494..849b403 100644
@@ -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
 -----------------------

index 07484a4..f5f363d 100644
@@ -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 <[email protected]>

Honestly speaking, I am not too thrilled about making the cvs-migration document much longer than what it currently is.

Having said that, let's take a look at each hunk.

Junio C Hamano ha scritto:

Honestly speaking, you've spent too much time in looking for every possible objections against these simple additions. At least it should be less than the time I've spent in measuring every single word of this patch, hoping you could consider them for inclusion. You gave me lot of attentions (I am grateful of this, really) so I should probably be surprised of the cleanliness of git code, of the rigor of the code style, of the clarity of the documentation. But unfortunately, I am not. I simply tried to make this document more useful and helpful for a wider audience of people that could ever consider of using git in their life. And yes, I decided to so because I had trouble myself during initial configurations. What's the problem if a document called "git for CVS users" is more explicated? What's the problem if it contains as many as possible informations to set up git in a viable way and, hopefully, to learn something on how it does work?

I'm sad. Not only because you refused a documentation patch, but because i could have sent a "Bug: Documentation Sucks!" to the ml and i would have obtained the same thing: nothing.

Francesco

P.S.:

You were right with usermod (groupadd is ok): that "-a" switch is redhat syntax. Six years of Linux Standard Base and this is still an unsolved problem...

Maybe the description of setting up a shared repository should go to the user-manual and cvs-migration should refer to the user-manual, instead of the other way round. I don't like the idea that the user-manual is referring to a CVS specific guide. The user manual should be as self-contained as possible.

Don't be unfair. Junio made clear that the documentation should not be cluttered with an introduction to Unix commands. But at least two points (git-shell, git-init.txt) would be accepted if you sent an cleaned-up patch.

I have no good idea how to reconcile your idea of giving more guidance to Unix commands with the idea of having a concise document that assumes a reader with decent Unix knowledge

Maybe you could just add some references to the distribution specific information, or just refer to the man pages.

Maybe you could move the introductory comments to a FAQ-like appendix. It could give brief hints on
"How to set up a user account?",
"How to setup a world-writable directory?"
I'm a bit reluctant to this because we'd need to maintain such information. But I suspect that some users would find them helpful.

One last comment: discussing patches is how the world works on the git mailing list. It happend to me, too, that patches were rejected after a brief or after a lengthy discussion. So, yes, finally sometimes there is no change. But often the discussions reveal a better way of achieving the original goal. Nonetheless, it can be frustrating to the original author.

Thanks for you effort of improving the documentation.

Steffen

I'd be interested in patches that did that. If somebody wants to work on that, they might want to start with

git://linux-nfs.org/~bfields/git.git docwork-foreign-scms

which has the skeleton of an "interoperating with foreign scms" chapter.

The thing that's kept me from working on this in the past is that it's a bit of a step backwards for someone that *just* wants to get to the cvs-migration stuff, since now it may appear you have to plow through the rest of the manual to get to it.

We could address that with clearer dependency information ("before reading this chapter, read chapters 1 and 3..."), and/or by providing some more links (e.g. repopulate the howto directory with links to some chapters that address popular questions).

--b.

On the contrary, I think you received some excellent, high-quality feedback. The process that you've been participating in over the last few days is exactly why the Git codebase is as good as it is; only the very best patches get accepted, and those which aren't "the very best" receive detailed feedback that help the submitter to turn weak patches into strong ones. The process works very well and the proof is in the pudding (the quality of the product).

Cheers,
Wincent

Hi,

I refrained from commenting on that patch until now, but alas, you force me to.

I was pretty unimpressed by the additions, as they seemed large in volume, but small in content.

Remember, those who read "git for CVS users" are _unwilling_ to spend the time reading git documentation (at least for the most part). If they encounter something which is not useful to them, they will not just ignore it, they will stop reading.

Ciao,
Dscho

That might overstate the case a little, but I definitely agree that we should get people to the information they need as quickly as possible, and that adding more beginning-unix-administration will interfere with that goal for the intended audience.

And it's not just here--there's probably lots of basic unix-commandline stuff that we could include with the user-manual (how find/xargs pipes work, etc...), and that would similarly help one possible audience at the expense of bogging it down for another audience.

I think the way to help people without those prerequisites is by clearer statements of prerequisites, and references to documentation elsewhere where appropriate.

--b.

Hello,

I must disagree with this analysis (although I didn't read the content of the patch you are commenting). People that are not really interested in git will find many reasons to stop reading the manual anyway. Those who really want to migrate (such as we did) are looking for every tiny bit of information. (We googled git commands and error messages because we didn't
find what we needed in the docs)
The docs are not perfect and somewhat unequal in content but I prefer more information than less, at this particular stage of git development.

- Aghiles.

Could you be a bit more specific? What are the most important points that you did not found in the documentation?

It would be interesting if you could share some details. Sending patches that would fix the deficiencies would even be superior ;)

I agree if it is git specific information. But, personally, I'd get a bit annoyed if a git specific document tried to teach me how to manage Unix accounts. BTW, useradd and such would not help me at all, because I need to talk to my admin anyway and he adds an account to the LDAP database.

Steffen

I suspect this is the case for most companies looking to switch to git. It certainly is here. Personally, I tend to find documents stooping to toddler-level a bit insulting unless they're marked as "walkthrough" or "for beginners" or some such. Especially if they are obviously not correct for all environments.

Andreas Ericsson                   [email protected]
OP5 AB                             www.op5.se
Tel: +46 8-230225                  Fax: +46 8-230231

Johannes Schindelin ha scritto:

That's document isn't for CVS users only. It's referred on the "Git User's Manual" speaking about shared repositories in general. I hope you agree that the time to make your eyes jump a little below is less than the time spent googling around if you don't find what you are looking for.

People who read documentation do this only in order to avoid reading documentation, anyway? This must be about the most stupid argument to refrain from augmenting documentation I have heard in a long time.

It may well be possible that some of the proposed additions don't have a good place in the document. I have not checked so myself. But the above criticism is not constructive for documentation writers since its logical conclusion would boil down to "don't bother writing any documentation".

David Kastrup