{"thread":{"id":"10675","subject":"[Patch] Documentation: enhanced \"git for CVS users\" doc about shared repositories","startedAt":"2007-11-05T22:32:24Z","lastAt":"2007-11-07T17:32:17Z","messageCount":18,"participants":["Francesco Pretto","Junio C Hamano","Johannes Schindelin","Aghiles","Steffen Prohaska","Wincent Colaiuta","Andreas Ericsson","David Kastrup","J. Bruce Fields"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"58440","messageId":"472F99F8.4010904@gmail.com","threadId":"10675","inReplyTo":null,"subject":"[Patch] Documentation: enhanced \"git for CVS users\" doc about shared repositories","fromName":"Francesco Pretto","fromEmail":"ceztkoml@gmail.com","sentAt":"2007-11-05T22:32:24Z","receivedAt":"2007-11-05T22:32:24Z","isPatch":true,"sender":{"key":"ceztkoml@gmail.com","avatar":null},"body":"More detailed instructions on how to set up shared repositories.\nAdded a reference to \"git for CVS users\" doc in git-init manual.\n\nSigned-off-by: Francesco Pretto <ceztkoml@gmail.com>\n---\n Documentation/cvs-migration.txt |   72 ++++++++++++++++++++++++++++++--------\n Documentation/git-init.txt      |    7 ++++\n 2 files changed, 64 insertions(+), 15 deletions(-)\n\ndiff --git a/Documentation/cvs-migration.txt b/Documentation/cvs-migration.txt\nindex 3b6b494..c92ed49 100644\n--- a/Documentation/cvs-migration.txt\n+++ b/Documentation/cvs-migration.txt\n@@ -13,12 +13,12 @@ link:tutorial.html[tutorial introduction to git] should be sufficient.\n Developing against a shared repository\n --------------------------------------\n \n-Suppose a shared repository is set up in /pub/repo.git on the host\n+Suppose a shared repository is set up in /pub/scm/repo.git on the host\n foo.com.  Then as an individual committer you can clone the shared\n repository over ssh with:\n \n ------------------------------------------------\n-$ git clone foo.com:/pub/repo.git/ my-project\n+$ git clone foo.com:/pub/scm/repo.git/ my-project\n $ cd my-project\n ------------------------------------------------\n \n@@ -68,37 +68,79 @@ other than `master`.\n Setting Up a Shared Repository\n ------------------------------\n \n-We assume you have already created a git repository for your project,\n-possibly created from scratch or from a tarball (see the\n-link:tutorial.html[tutorial]), or imported from an already existing CVS\n-repository (see the next section).\n+We assume you have admin privilege on the remote machine. Moreover, we assume\n+you have already created a git repository for your project, possibly created\n+from scratch or from a tarball (see the link:tutorial.html[tutorial]),or\n+imported  from an already existing CVS repository (see the next section).\n \n-Assume your existing repo is at /home/alice/myproject.  Create a new \"bare\"\n-repository (a repository without a working tree) and fetch your project into\n-it:\n+First, let's create a common directory for all the projects you'll want to\n+track with git:\n+\n+-----------------------------------------------\n+$ mkdir -p /pub/scm\n+-----------------------------------------------\n+\n+It's recommended, but not necessary, to create a specific group of commiters\n+for every project/repository. With root credentials launch:\n+\n+------------------------------------------------\n+$ groupadd $group\n+------------------------------------------------\n+\n+Assume your existing repository is at /home/alice/myproject.  Create a new\n+\"bare\" repository (a repository without a working tree) and fetch your project\n+into it:\n \n ------------------------------------------------\n-$ mkdir /pub/my-repo.git\n+$ mkdir /pub/scm/my-repo.git\n $ cd /pub/my-repo.git\n $ git --bare init --shared\n $ git --bare fetch /home/alice/myproject master:master\n ------------------------------------------------\n \n+Now, set the group ownership of the git repository you've just created to the\n+same group of the commiters:\n+\n+------------------------------------------------\n+$ chgrp -R $group /pub/scm/my-repo.git\n+------------------------------------------------\n+\n Next, give every team member read/write access to this repository.  One\n easy way to do this is to give all the team members ssh access to the\n machine where the repository is hosted.  If you don't want to give them a\n full shell on the machine, there is a restricted shell which only allows\n users to do git pushes and pulls; see gitlink:git-shell[1].\n \n-Put all the committers in the same group, and make the repository\n-writable by that group:\n+First, enable it putting on the trusted shells list of the system:\n+\n+------------------------------------------------\n+$ echo `which git-shell` >> /etc/shells\n+------------------------------------------------\n+\n+Ensure users will not have write permission on /pub/scm. Now, let's create\n+them with the following command launched with root credentials:\n \n ------------------------------------------------\n-$ chgrp -R $group /pub/my-repo.git\n+$ useradd -g $group -d /pub/scm -s `which git-shell` $username\n ------------------------------------------------\n \n-Make sure committers have a umask of at most 027, so that the directories\n-they create are writable and searchable by other group members.\n+They will be enabled to push on repositories owned by the group $group.\n+Later, you can give users access to other projects simply by adding them to\n+other groups.\n+\n+[NOTE]\n+================================\n+With previous versions of git, it could be necessary to set umask variable of\n+all commiters with values like 002 or 007. If you still need to support them,\n+you can do it in the following way; assuming that all users have their home\n+positionated at /pub/scm, like in the previous example, launch the command:\n+\n+------------------------------------------------\n+$ echo \"umask 022\" >> /pub/scm/.profile\n+------------------------------------------------\n+\n+At the next login, users will have their umask variable automatically set.\n+================================\n \n Importing a CVS archive\n -----------------------\ndiff --git a/Documentation/git-init.txt b/Documentation/git-init.txt\nindex 07484a4..f5f363d 100644\n--- a/Documentation/git-init.txt\n+++ b/Documentation/git-init.txt\n@@ -101,6 +101,13 @@ $ git-add .     <2>\n <2> add all existing file to the index\n \n \n+SHARED REPOSITORIES\n+-------------------\n+\n+Please refer to link:cvs-migration.html[git for CVS users], section \"Setting Up\n+a Shared Repository\", for details on how to set up shared repositories.\n+\n+\n Author\n ------\n Written by Linus Torvalds <torvalds@osdl.org>\n"},{"id":"58455","messageId":"7v8x5cmern.fsf@gitster.siamese.dyndns.org","threadId":"10675","inReplyTo":"472F99F8.4010904@gmail.com","subject":"Re: [Patch] Documentation: enhanced \"git for CVS users\" doc about shared repositories","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2007-11-05T23:52:28Z","receivedAt":"2007-11-05T23:52:28Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Francesco Pretto <ceztkoml@gmail.com> writes:\n\n> More detailed instructions on how to set up shared repositories.\n> Added a reference to \"git for CVS users\" doc in git-init manual.\n>\n> Signed-off-by: Francesco Pretto <ceztkoml@gmail.com>\n> ---\n>  Documentation/cvs-migration.txt |   72 ++++++++++++++++++++++++++++++--------\n>  Documentation/git-init.txt      |    7 ++++\n>  2 files changed, 64 insertions(+), 15 deletions(-)\n>\n> diff --git a/Documentation/cvs-migration.txt b/Documentation/cvs-migration.txt\n> index 3b6b494..c92ed49 100644\n> --- a/Documentation/cvs-migration.txt\n> +++ b/Documentation/cvs-migration.txt\n> @@ -13,12 +13,12 @@ link:tutorial.html[tutorial introduction to git] should be sufficient.\n>  Developing against a shared repository\n>  --------------------------------------\n>  \n> -Suppose a shared repository is set up in /pub/repo.git on the host\n> +Suppose a shared repository is set up in /pub/scm/repo.git on the host\n>  foo.com.  Then as an individual committer you can clone the shared\n>  repository over ssh with:\n>  \n>  ------------------------------------------------\n> -$ git clone foo.com:/pub/repo.git/ my-project\n> +$ git clone foo.com:/pub/scm/repo.git/ my-project\n>  $ cd my-project\n>  ------------------------------------------------\n\nThis part seems an unnecessary change.\n\n> @@ -68,37 +68,79 @@ other than `master`.\n>  Setting Up a Shared Repository\n>  ------------------------------\n>  \n> -We assume you have already created a git repository for your project,\n> -possibly created from scratch or from a tarball (see the\n> -link:tutorial.html[tutorial]), or imported from an already existing CVS\n> -repository (see the next section).\n> +We assume you have admin privilege on the remote machine. Moreover, we assume\n> +you have already created a git repository for your project, possibly created\n> +from scratch or from a tarball (see the link:tutorial.html[tutorial]),or\n> +imported  from an already existing CVS repository (see the next section).\n\nDon't assume the \"admin privilege\" part, as you do not have to.\n\nYou are newly hired to work on project-X, and the sysadm throws\nyou into projectx group.  Thesysadm further prepares a directory\n'/pub/project-X' and makes it mode 2775 (aka ug=rwx,o=rx,g+s).\n\nDo you want to create a new repository for projext-X group's\nuse?  You do:\n\n\t$ cd /pub/project-X\n        $ GIT_DIR=mine.git git init --shared\n\nand you now have a usable /pub/project-X/mine.git repository for\nproject members.  I do not think you would need any chmod/chgrp\nafter this step.\n\n> +First, let's create a common directory for all the projects you'll want to\n> +track with git:\n> +\n> +-----------------------------------------------\n> +$ mkdir -p /pub/scm\n> +-----------------------------------------------\n\nAn organization may use different SCM depending on the projects'\nneeds, and there is no reason members of projects A and B should\nbe in the same group 'git' while having members of project C in\ngroup 'hg' only because A and B happen to use git.  It would\nmake more sense to either (1) make members of all three projects\nbelong to 'src' group, or (2) make three groups, one for each\nproject.\n\nIOW, I do not think the above is a good suggestion.\n\nAlso with the \"create new --shared repository for the project in\na group's directory that has mode 2755\" approach, I do not think\nthere is any need to muck with umask either.\n"},{"id":"58518","messageId":"47303C2E.2070103@gmail.com","threadId":"10675","inReplyTo":"7v8x5cmern.fsf@gitster.siamese.dyndns.org","subject":"Re: [Patch] Documentation: enhanced \"git for CVS users\" doc about shared repositories","fromName":"Francesco Pretto","fromEmail":"ceztkoml@gmail.com","sentAt":"2007-11-06T10:04:30Z","receivedAt":"2007-11-06T10:04:30Z","isPatch":true,"sender":{"key":"ceztkoml@gmail.com","avatar":null},"body":"Junio C Hamano ha scritto:\n>>  ------------------------------------------------\n>> -$ git clone foo.com:/pub/repo.git/ my-project\n>> +$ git clone foo.com:/pub/scm/repo.git/ my-project\n>>  $ cd my-project\n>>  ------------------------------------------------\n> \n> This part seems an unnecessary change.\n> \n\nIronically, that's the same configuration of git.kernel.org. And I think is better\nto put immediately the project in a appropriate directory than to move it later.\n\n> Don't assume the \"admin privilege\" part, as you do not have to.\n> \n\nAdmin privilege SHALL be assumed, as this is a first time configuration, and the best\nwe can do is to assume it's done on a default *nix installation. Moreover, it's\nwhat HEAD documentation is already doing when it suggests to give users ssh access.\n\nLet's suppose the user \"user1\" create its own repository on a remote machine.\nNow, he wants to selectively give write access on its repository to \"user2\".\nThere's 2 cases:\n    1) \"user2\" have a local/ssh account on the machine. In this case, \"user1\" want\n       to be sure only \"user2\" can write to the repository, so he can ask the admin\n       to put \"user1\" and \"user2\" in the same group \"projectx\" or ask him to enable\n       ACLs, still turned off in the majority of *nix systems.\n    2) \"user2\" haven't a local/ssh account. Here:\n\t- a local/ssh account should be given to \"user2\", returning to 1)\n        - mod_dav module has to be enabled for public http dirs of \"user1\"\n        - git daemon has to be started and enabled to write on the repository.\n\nThe last 3 tasks all require admin privilege on default linux/bsd/macosx\ninstallations. However, a little distinction can be made. I'll see.\n\n>\n> needs, and there is no reason members of projects A and B should\n> be in the same group 'git'\n\nI agree!\n\n> while having members of project C in\n> group 'hg' only because A and B happen to use git.\n\nI agree!\n\n> belong to 'src' group, or (2) make three groups, one for each\n> project.\n> \n\nIt's exactly the point of:\n\n+It's recommended, but not necessary, to create a specific group of commiters\n+for every project/repository. With root credentials launch:\n+\n+------------------------------------------------\n+$ groupadd $group\n+------------------------------------------------\n\nWhat you have understood here?\n\n> Also with the \"create new --shared repository for the project in\n> a group's directory that has mode 2755\" approach, I do not think\n> there is any need to muck with umask either.\n> \n\numask requirement is referred to previous version of git. It's still referred as actual\nin HEAD documentation. If it's ok for you, we could just cut away that reference.\n\nConclusion: i can try to amend my patch to be even more clearer. What i am saying\nis that official documentation, commands manuals/syntaxes should be easy enough to the\nfirst time user to set up git repositories without looking up the web for\n\"git tutorial\"/\"git installation\"/\"git umask 002\", etc. (and consider that even an\nexpert sysadmin is a first time user, when he install and set up git the first time).\nOr was better a \"Documentation S**KS!\" bug report?\n"},{"id":"58521","messageId":"Pine.LNX.4.64.0711061052570.4362@racer.site","threadId":"10675","inReplyTo":"47303C2E.2070103@gmail.com","subject":"Re: [Patch] Documentation: enhanced \"git for CVS users\" doc about shared repositories","fromName":"Johannes Schindelin","fromEmail":"johannes.schindelin@gmx.de","sentAt":"2007-11-06T10:53:24Z","receivedAt":"2007-11-06T10:53:24Z","isPatch":true,"sender":{"key":"johannes.schindelin@gmx.de","avatar":"https://avatars.githubusercontent.com/u/127790?v=4"},"body":"Hi,\n\nOn Tue, 6 Nov 2007, Francesco Pretto wrote:\n\n> Junio C Hamano ha scritto:\n> >>  ------------------------------------------------\n> >> -$ git clone foo.com:/pub/repo.git/ my-project\n> >> +$ git clone foo.com:/pub/scm/repo.git/ my-project\n> >>  $ cd my-project\n> >>  ------------------------------------------------\n> > \n> > This part seems an unnecessary change.\n> > \n> \n> Ironically, that's the same configuration of git.kernel.org. And I think \n> is better to put immediately the project in a appropriate directory than \n> to move it later.\n\nFor most people, neither path is correct.  So I really don't see your \npoint.\n\nCiao,\nDscho\n"},{"id":"58525","messageId":"47304C95.5090208@gmail.com","threadId":"10675","inReplyTo":"Pine.LNX.4.64.0711061052570.4362@racer.site","subject":"Re: [Patch] Documentation: enhanced \"git for CVS users\" doc about shared repositories","fromName":"Francesco Pretto","fromEmail":"ceztkoml@gmail.com","sentAt":"2007-11-06T11:14:29Z","receivedAt":"2007-11-06T11:14:29Z","isPatch":true,"sender":{"key":"ceztkoml@gmail.com","avatar":null},"body":"Johannes Schindelin ha scritto:\n> \n> For most people, neither path is correct.\n\nYeah, I agree. I'll try to reflect this with a neutral wording :-)\nIn the context of the documentation, we should just take care of logical\nfollowing the example.\n"},{"id":"58597","messageId":"4730E056.7080809@gmail.com","threadId":"10675","inReplyTo":"7v8x5cmern.fsf@gitster.siamese.dyndns.org","subject":"Re: [PATCH] Documentation: enhanced \"git for CVS users\" doc about shared repositories","fromName":"Francesco Pretto","fromEmail":"ceztkoml@gmail.com","sentAt":"2007-11-06T21:44:54Z","receivedAt":"2007-11-06T21:44:54Z","isPatch":true,"sender":{"key":"ceztkoml@gmail.com","avatar":null},"body":"Signed-off-by: Francesco Pretto <ceztkoml@gmail.com>\n---\n More detailed instructions on how to set up shared repositories.\n Removed an old reference to the need of setting umask of ssh\n users of shared repositories.\n Added a reference to \"git for CVS users\" doc in git-init manual.\n\n Documentation/cvs-migration.txt |   61 +++++++++++++++++++++++++++++++++++----\n Documentation/git-init.txt      |    7 ++++\n 2 files changed, 62 insertions(+), 6 deletions(-)\n\ndiff --git a/Documentation/cvs-migration.txt b/Documentation/cvs-migration.txt\nindex 3b6b494..849b403 100644\n--- a/Documentation/cvs-migration.txt\n+++ b/Documentation/cvs-migration.txt\n@@ -71,7 +71,40 @@ Setting Up a Shared Repository\n We assume you have already created a git repository for your project,\n possibly created from scratch or from a tarball (see the\n link:tutorial.html[tutorial]), or imported from an already existing CVS\n-repository (see the next section).\n+repository (see the next section). Moreover, we assume you can write in a\n+public accessible directory and give other users the permission to do so.\n+You could need or not admin privileges to do so, depending on your\n+system configuration and how you decide to export the repository.\n+\n+It's recommended, but not strictly necessary, to create a specific group for\n+every project/repository you'll want to create, so it will be easier to give\n+or prevent access of users to specific repositories. With admin privilege launch:\n+\n+------------------------------------------------\n+$ groupadd $group\n+------------------------------------------------\n+\n+If you want to add an user to this group, launch:\n+\n+------------------------------------------------\n+$ usermod -a -G $group $username\n+------------------------------------------------\n+\n+In our example, we will store the shared repository in the /pub dir, so the\n+user creating it will need write permission there. There's no problems if you\n+choose another directory, but you'll have to ensure it will be accessible by\n+other users, on local or by remote (this could be not the case of home\n+directories).\n+\n+If you just want to create a directory that is writable by every users that have\n+a local account, launch with privileged credentials:\n+\n+------------------------------------------------\n+$ mkdir /pub\n+$ chmod a+w,+t /pub\n+------------------------------------------------\n+\n+Now you can proceed with an unprivileged user.\n \n Assume your existing repo is at /home/alice/myproject.  Create a new \"bare\"\n repository (a repository without a working tree) and fetch your project into\n@@ -84,21 +117,37 @@ $ git --bare init --shared\n $ git --bare fetch /home/alice/myproject master:master\n ------------------------------------------------\n \n+If you previously decided to create a specific group for the committers of the\n+repository, assign its ownership to that group (you'll have to be a member of it\n+or switch to privileged credentials):\n+\n+------------------------------------------------\n+$ chgrp -R $group /pub/my-repo.git\n+------------------------------------------------\n+\n Next, give every team member read/write access to this repository.  One\n easy way to do this is to give all the team members ssh access to the\n machine where the repository is hosted.  If you don't want to give them a\n full shell on the machine, there is a restricted shell which only allows\n users to do git pushes and pulls; see gitlink:git-shell[1].\n \n-Put all the committers in the same group, and make the repository\n-writable by that group:\n+The following two commands will require admin privileges; first, enable\n+git-shell putting it on the trusted shells list of the system:\n \n ------------------------------------------------\n-$ chgrp -R $group /pub/my-repo.git\n+$ echo `which git-shell` >> /etc/shells\n+------------------------------------------------\n+\n+Now, let's create the commit users:\n+\n+------------------------------------------------\n+$ useradd -g $group -s `which git-shell` $username\n ------------------------------------------------\n \n-Make sure committers have a umask of at most 027, so that the directories\n-they create are writable and searchable by other group members.\n+These users will be enabled to push on repositories owned by the group $group.\n+Later, you can give access to other projects simply by adding them to\n+other groups. Similarly, you can prevent access to repositories simply\n+removing those users from related groups.\n \n Importing a CVS archive\n -----------------------\ndiff --git a/Documentation/git-init.txt b/Documentation/git-init.txt\nindex 07484a4..f5f363d 100644\n--- a/Documentation/git-init.txt\n+++ b/Documentation/git-init.txt\n@@ -101,6 +101,13 @@ $ git-add .     <2>\n <2> add all existing file to the index\n \n \n+SHARED REPOSITORIES\n+-------------------\n+\n+Please refer to link:cvs-migration.html[git for CVS users], section \"Setting Up\n+a Shared Repository\", for details on how to set up shared repositories.\n+\n+\n Author\n ------\n Written by Linus Torvalds <torvalds@osdl.org>\n"},{"id":"58611","messageId":"7vd4unez2l.fsf@gitster.siamese.dyndns.org","threadId":"10675","inReplyTo":"4730E056.7080809@gmail.com","subject":"Re: [PATCH] Documentation: enhanced \"git for CVS users\" doc about shared repositories","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2007-11-06T23:25:38Z","receivedAt":"2007-11-06T23:25:38Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Francesco Pretto <ceztkoml@gmail.com> writes:\n\n> Signed-off-by: Francesco Pretto <ceztkoml@gmail.com>\n> ---\n>  More detailed instructions on how to set up shared repositories.\n>  Removed an old reference to the need of setting umask of ssh\n>  users of shared repositories.\n>  Added a reference to \"git for CVS users\" doc in git-init manual.\n\nHonestly speaking, I am not too thrilled about making the\ncvs-migration document much longer than what it currently is.\n\nHaving said that, let's take a look at each hunk.\n\n> @@ -71,7 +71,40 @@ Setting Up a Shared Repository\n>  We assume you have already created a git repository for your project,\n>  possibly created from scratch or from a tarball (see the\n>  link:tutorial.html[tutorial]), or imported from an already existing CVS\n> -repository (see the next section).\n> +repository (see the next section). Moreover, we assume you can write in a\n> +public accessible directory and give other users the permission to do so.\n> +You could need or not admin privileges to do so, depending on your\n> +system configuration and how you decide to export the repository.\n\nI do not think the above helps anybody.  Later sections say\n\"make it writable by foo group\" and such specifically, and from\nsuch descriptions, the reader either (1) understands what are\nprerequisite for being able to do so, or (2) is clueless enough\nto get puzzled by failure message from \"chgrp git foo\", and would\nnot even make the connection to the above text after seeing such\na failure anyway.\n\n> +It's recommended, but not strictly necessary, to create a specific group for\n> +every project/repository you'll want to create, so it will be easier to give\n> +or prevent access of users to specific repositories.\n\nI'd say this is not git specific nor cvs migrant specific advice\nbut falls into a common sense category.  Better not clutter the\ndocument with such, and keep it short and readable in one\nsitting.\n\n> +... With admin privilege launch:\n> +\n> +------------------------------------------------\n> +$ groupadd $group\n> +------------------------------------------------\n> +\n> +If you want to add an user to this group, launch:\n> +\n> +------------------------------------------------\n> +$ usermod -a -G $group $username\n> +------------------------------------------------\n\nI tend to edit /etc/group with vi ;-) and I suspect these two\ncommands are specific to the distro you happen to use.\n\nFor something like \"cvs migration\", I really do not want a set\nof step-by-step hand holding instructions.  Just telling them to\n\"pick a group for the project, make repositories belonging to\nthe project owned by that group, and make them writable by the\ngroup members\" should be enough.  CVS migrants may not know how\nthe world works with respect to git, but they are not idiots.\nIntroductory UNIX command guide is not the goal of the document.\nTry to tell them _what_ needs to happen, not _how_, when that\nlevel of the detail is sufficient.\n\n> +In our example, we will store the shared repository in the /pub dir, so the\n> +user creating it will need write permission there. There's no problems if you\n> +choose another directory, but you'll have to ensure it will be accessible by\n> +other users, on local or by remote (this could be not the case of home\n> +directories).\n\nEverything up to \"by other users\" is good, but \", on local or\nby...\" are unnecessary.  If your stress is on shared\nrepositories, do not even mention \"home\", unless you are very\nconvinced that it is a very typical use case, in which case you\nshould be certain about what you recommend and there is no place\nfor expression like \"this could be ...\" for such a sure\nrecommendation.\n\n> +If you just want to create a directory that is writable by every users that have\n> +a local account, launch with privileged credentials:\n> +\n> +------------------------------------------------\n> +$ mkdir /pub\n> +$ chmod a+w,+t /pub\n> +------------------------------------------------\n\nUnneeded --- again, this is not a UNIX command guide --- and\nwrong.  You do not necessarily need to \"launch with privileged\ncredentials\" to do this anyway.  As long as you can chmod the\ndirectory, that is all that is needed.\n\n>  Next, give every team member read/write access to this repository.  One\n>  easy way to do this is to give all the team members ssh access to the\n>  machine where the repository is hosted.  If you don't want to give them a\n>  full shell on the machine, there is a restricted shell which only allows\n>  users to do git pushes and pulls; see gitlink:git-shell[1].\n\nThis part is a very good advice.  It is git specific knowledge\nnew cvs migrants need to learn.  Oops, the reason this part is\ngood is because it is from the original text --- no wonder ;-).\n\n> -Put all the committers in the same group, and make the repository\n> -writable by that group:\n> +The following two commands will require admin privileges; first, enable\n> +git-shell putting it on the trusted shells list of the system:\n>  \n>  ------------------------------------------------\n> -$ chgrp -R $group /pub/my-repo.git\n> +$ echo `which git-shell` >> /etc/shells\n> +------------------------------------------------\n\nSaying that /etc/shells may control what shells are allowed as\nthe login shell on many systems is probably a very good idea.\nHowever, there is no need for an introductory UNIX guide that is\neven WRONG.  Why \"echo `foo`\" when just \"foo\" would work?  Why\naren't you checking if /etc/shells already have git-shell\ndefined?\n\n> +\n> +Now, let's create the commit users:\n> +\n> +------------------------------------------------\n> +$ useradd -g $group -s `which git-shell` $username\n>  ------------------------------------------------\n>  \n> -Make sure committers have a umask of at most 027, so that the directories\n> -they create are writable and searchable by other group members.\n> +These users will be enabled to push on repositories owned by the group $group.\n> +Later, you can give access to other projects simply by adding them to\n> +other groups. Similarly, you can prevent access to repositories simply\n> +removing those users from related groups.\n\nThe original text's point about umask does not apply to modern\ngit anymore, so the above lines can simply deleted.  Almost\neverything else you added to this hunk is unnecessary UNIX\nguide.\n\n> --- a/Documentation/git-init.txt\n> +++ b/Documentation/git-init.txt\n> @@ -101,6 +101,13 @@ $ git-add .     <2>\n>  <2> add all existing file to the index\n>  \n>  \n> +SHARED REPOSITORIES\n> +-------------------\n> +\n> +Please refer to link:cvs-migration.html[git for CVS users], section \"Setting Up\n> +a Shared Repository\", for details on how to set up shared repositories.\n> +\n> +\n>  Author\n>  ------\n>  Written by Linus Torvalds <torvalds@osdl.org>\n\nThis part is a good idea, but instead of putting it at the\nbottom, it may make it more prominent to have this at the end of\noption description for \"--shared\".\n"},{"id":"58624","messageId":"47310ACF.4030103@gmail.com","threadId":"10675","inReplyTo":"7vd4unez2l.fsf@gitster.siamese.dyndns.org","subject":"Re: [PATCH] Documentation: enhanced \"git for CVS users\" doc about shared repositories","fromName":"Francesco Pretto","fromEmail":"ceztkoml@gmail.com","sentAt":"2007-11-07T00:46:07Z","receivedAt":"2007-11-07T00:46:07Z","isPatch":true,"sender":{"key":"ceztkoml@gmail.com","avatar":null},"body":"Junio C Hamano ha scritto:\n> \n> Honestly speaking, I am not too thrilled about making the\n> cvs-migration document much longer than what it currently is.\n> \n\nHonestly speaking, you've spent too much time in looking for every possible\nobjections against these simple additions. At least it should be less than the\ntime I've spent in measuring every single word of this patch, hoping you could\nconsider them for inclusion. You gave me lot of attentions (I am grateful of this,\nreally) so I should probably be surprised of the cleanliness of git code, of the\nrigor of the code style, of the clarity of the documentation. But unfortunately,\nI am not. I simply tried to make this document more useful and helpful for a\nwider audience of people that could ever consider of using git in their life.\nAnd yes, I decided to so because I had trouble myself during initial configurations.\nWhat's the problem if a document called \"git for CVS users\" is more explicated?\nWhat's the problem if it contains as many as possible informations to set up\ngit in a viable way and, hopefully, to learn something on how it does work?\n\nI'm sad. Not only because you refused a documentation patch, but because i could\nhave sent a \"Bug: Documentation Sucks!\" to the ml and i would have obtained the\nsame thing: nothing.\n\nFrancesco\n\nP.S.:\n\n>> +------------------------------------------------\n>> +$ usermod -a -G $group $username\n>> +------------------------------------------------\n> \n> I tend to edit /etc/group with vi ;-) and I suspect these two\n> commands are specific to the distro you happen to use.\n\nYou were right with usermod (groupadd is ok): that \"-a\" switch is redhat syntax.\nSix years of Linux Standard Base and this is still an unsolved problem...\n"},{"id":"58625","messageId":"Pine.LNX.4.64.0711070053320.4362@racer.site","threadId":"10675","inReplyTo":"47310ACF.4030103@gmail.com","subject":"Re: [PATCH] Documentation: enhanced \"git for CVS users\" doc about shared repositories","fromName":"Johannes Schindelin","fromEmail":"johannes.schindelin@gmx.de","sentAt":"2007-11-07T00:55:49Z","receivedAt":"2007-11-07T00:55:49Z","isPatch":true,"sender":{"key":"johannes.schindelin@gmx.de","avatar":"https://avatars.githubusercontent.com/u/127790?v=4"},"body":"Hi,\n\nOn Wed, 7 Nov 2007, Francesco Pretto wrote:\n\n> I simply tried to make this document more useful and helpful for a wider \n> audience of people that could ever consider of using git in their life. \n> And yes, I decided to so because I had trouble myself during initial \n> configurations. What's the problem if a document called \"git for CVS \n> users\" is more explicated? What's the problem if it contains as many as \n> possible informations to set up git in a viable way and, hopefully, to \n> learn something on how it does work?\n\nI refrained from commenting on that patch until now, but alas, you force \nme to.\n\nI was pretty unimpressed by the additions, as they seemed large in volume, \nbut small in content.\n\nRemember, those who read \"git for CVS users\" are _unwilling_ to spend the \ntime reading git documentation (at least for the most part).  If they \nencounter something which is not useful to them, they will not just ignore \nit, they will stop reading.\n\nCiao,\nDscho\n"},{"id":"58626","messageId":"4731108A.20603@gmail.com","threadId":"10675","inReplyTo":"Pine.LNX.4.64.0711070053320.4362@racer.site","subject":"Re: [PATCH] Documentation: enhanced \"git for CVS users\" doc about shared repositories","fromName":"Francesco Pretto","fromEmail":"ceztkoml@gmail.com","sentAt":"2007-11-07T01:10:34Z","receivedAt":"2007-11-07T01:10:34Z","isPatch":true,"sender":{"key":"ceztkoml@gmail.com","avatar":null},"body":"Johannes Schindelin ha scritto:\n> Remember, those who read \"git for CVS users\" are _unwilling_ to spend the \n> time reading git documentation (at least for the most part).  If they \n> encounter something which is not useful to them, they will not just ignore \n> it, they will stop reading.\n>\n\nThat's document isn't for CVS users only. It's referred on the \"Git User's Manual\"\nspeaking about shared repositories in general. I hope you agree that the time to\nmake your eyes jump a little below is less than the time spent googling around\nif you don't find what you are looking for.\n"},{"id":"58630","messageId":"3abd05a90711061736r4c969cddj348c006615ffbdd6@mail.gmail.com","threadId":"10675","inReplyTo":"Pine.LNX.4.64.0711070053320.4362@racer.site","subject":"Re: [PATCH] Documentation: enhanced \"git for CVS users\" doc about shared repositories","fromName":"Aghiles","fromEmail":"aghilesk@gmail.com","sentAt":"2007-11-07T01:36:46Z","receivedAt":"2007-11-07T01:36:46Z","isPatch":true,"sender":{"key":"aghilesk@gmail.com","avatar":null},"body":"Hello,\n>\n> Remember, those who read \"git for CVS users\" are _unwilling_ to spend the\n> time reading git documentation (at least for the most part).  If they\n> encounter something which is not useful to them, they will not just ignore\n> it, they will stop reading.\n>\n\nI must disagree with this analysis (although I didn't read the content of the\npatch you are commenting). People that are not really interested in git will\nfind many reasons to stop reading the manual anyway. Those who really\nwant to migrate (such as we did) are looking for every tiny bit of information.\n(We googled git commands and error messages because we didn't\nfind what we needed in the docs)\nThe docs are not perfect and somewhat unequal in content but I prefer\nmore information than less, at this particular stage of git development.\n\n- Aghiles.\n"},{"id":"58640","messageId":"DED2A61B-B5AE-4BAA-942A-18A61924611E@zib.de","threadId":"10675","inReplyTo":"3abd05a90711061736r4c969cddj348c006615ffbdd6@mail.gmail.com","subject":"Re: [PATCH] Documentation: enhanced \"git for CVS users\" doc about shared repositories","fromName":"Steffen Prohaska","fromEmail":"prohaska@zib.de","sentAt":"2007-11-07T07:35:31Z","receivedAt":"2007-11-07T07:35:31Z","isPatch":true,"sender":{"key":"prohaska@zib.de","avatar":"https://avatars.githubusercontent.com/u/217580?v=4"},"body":"\nOn Nov 7, 2007, at 2:36 AM, Aghiles wrote:\n\n> Hello,\n>>\n>> Remember, those who read \"git for CVS users\" are _unwilling_ to  \n>> spend the\n>> time reading git documentation (at least for the most part).  If they\n>> encounter something which is not useful to them, they will not  \n>> just ignore\n>> it, they will stop reading.\n>>\n>\n> I must disagree with this analysis (although I didn't read the  \n> content of the\n> patch you are commenting). People that are not really interested in  \n> git will\n> find many reasons to stop reading the manual anyway. Those who really\n> want to migrate (such as we did) are looking for every tiny bit of  \n> information.\n> (We googled git commands and error messages because we didn't\n> find what we needed in the docs)\n\nCould you be a bit more specific? What are the most important\npoints that you did not found in the documentation?\n\nIt would be interesting if you could share some details. Sending\npatches that would fix the deficiencies would even be\nsuperior ;)\n\n\n> The docs are not perfect and somewhat unequal in content but I prefer\n> more information than less, at this particular stage of git  \n> development.\n\nI agree if it is git specific information. But, personally,\nI'd get a bit annoyed if a git specific document tried to\nteach me how to manage Unix accounts. BTW, useradd and such\nwould not help me at all, because I need to talk to my admin\nanyway and he adds an account to the LDAP database.\n\n\tSteffen\n"},{"id":"58646","messageId":"D739E20F-BCEF-418C-AE6F-A74C4ACEA4FA@wincent.com","threadId":"10675","inReplyTo":"47310ACF.4030103@gmail.com","subject":"Re: [PATCH] Documentation: enhanced \"git for CVS users\" doc about shared repositories","fromName":"Wincent Colaiuta","fromEmail":"win@wincent.com","sentAt":"2007-11-07T08:03:08Z","receivedAt":"2007-11-07T08:03:08Z","isPatch":true,"sender":{"key":"greg@hurrell.net","avatar":"https://avatars.githubusercontent.com/u/7074?v=4"},"body":"El 7/11/2007, a las 1:46, Francesco Pretto escribió:\n\n> Junio C Hamano ha scritto:\n>>\n>> Honestly speaking, I am not too thrilled about making the\n>> cvs-migration document much longer than what it currently is.\n>>\n>\n> Honestly speaking, you've spent too much time in looking for every  \n> possible\n> objections against these simple additions. At least it should be  \n> less than the\n> time I've spent in measuring every single word of this patch, hoping  \n> you could\n> consider them for inclusion. You gave me lot of attentions (I am  \n> grateful of this,\n> really) so I should probably be surprised of the cleanliness of git  \n> code, of the\n> rigor of the code style, of the clarity of the documentation. But  \n> unfortunately,\n> I am not. I simply tried to make this document more useful and  \n> helpful for a\n> wider audience of people that could ever consider of using git in  \n> their life.\n> And yes, I decided to so because I had trouble myself during initial  \n> configurations.\n> What's the problem if a document called \"git for CVS users\" is more  \n> explicated?\n> What's the problem if it contains as many as possible informations  \n> to set up\n> git in a viable way and, hopefully, to learn something on how it  \n> does work?\n>\n> I'm sad. Not only because you refused a documentation patch, but  \n> because i could\n> have sent a \"Bug: Documentation Sucks!\" to the ml and i would have  \n> obtained the\n> same thing: nothing.\n\nOn the contrary, I think you received some excellent, high-quality  \nfeedback. The process that you've been participating in over the last  \nfew days is exactly why the Git codebase is as good as it is; only the  \nvery best patches get accepted, and those which aren't \"the very best\"  \nreceive detailed feedback that help the submitter to turn weak patches  \ninto strong ones. The process works very well and the proof is in the  \npudding (the quality of the product).\n\nCheers,\nWincent\n"},{"id":"58647","messageId":"277490E5-2B9A-4BA7-9DD7-C1CEE698B348@zib.de","threadId":"10675","inReplyTo":"47310ACF.4030103@gmail.com","subject":"Re: [PATCH] Documentation: enhanced \"git for CVS users\" doc about shared repositories","fromName":"Steffen Prohaska","fromEmail":"prohaska@zib.de","sentAt":"2007-11-07T08:07:58Z","receivedAt":"2007-11-07T08:07:58Z","isPatch":true,"sender":{"key":"prohaska@zib.de","avatar":"https://avatars.githubusercontent.com/u/217580?v=4"},"body":"On Nov 7, 2007, at 1:46 AM, Francesco Pretto wrote:\n\n> Junio C Hamano ha scritto:\n>>\n>> Honestly speaking, I am not too thrilled about making the\n>> cvs-migration document much longer than what it currently is.\n>>\n\nMaybe the description of setting up a shared repository should\ngo to the user-manual and cvs-migration should refer to the\nuser-manual, instead of the other way round. I don't like the\nidea that the user-manual is referring to a CVS specific guide.\nThe user manual should be as self-contained as possible.\n\n\n> Honestly speaking, you've spent too much time in looking for every  \n> possible\n> objections against these simple additions. At least it should be  \n> less than the\n> time I've spent in measuring every single word of this patch,  \n> hoping you could\n> consider them for inclusion. You gave me lot of attentions (I am  \n> grateful of this,\n> really) so I should probably be surprised of the cleanliness of git  \n> code, of the\n> rigor of the code style, of the clarity of the documentation. But  \n> unfortunately,\n> I am not. I simply tried to make this document more useful and  \n> helpful for a\n> wider audience of people that could ever consider of using git in  \n> their life.\n> And yes, I decided to so because I had trouble myself during  \n> initial configurations.\n> What's the problem if a document called \"git for CVS users\" is more  \n> explicated?\n> What's the problem if it contains as many as possible informations  \n> to set up\n> git in a viable way and, hopefully, to learn something on how it  \n> does work?\n>\n> I'm sad. Not only because you refused a documentation patch, but  \n> because i could\n> have sent a \"Bug: Documentation Sucks!\" to the ml and i would have  \n> obtained the\n> same thing: nothing.\n\nDon't be unfair. Junio made clear that the documentation\nshould not be cluttered with an introduction to Unix commands.\nBut at least two points (git-shell, git-init.txt) would be\naccepted if you sent an cleaned-up patch.\n\nI have no good idea how to reconcile your idea of giving more\nguidance to Unix commands with the idea of having a concise\ndocument that assumes a reader with decent Unix knowledge\n\nMaybe you could just add some references to the distribution\nspecific information, or just refer to the man pages.\n\nMaybe you could move the introductory comments to a FAQ-like\nappendix. It could give brief hints on\n\"How to set up a user account?\",\n\"How to setup a world-writable directory?\"\nI'm a bit reluctant to this because we'd need to maintain such\ninformation. But I suspect that some users would find them\nhelpful.\n\nOne last comment: discussing patches is how the world works on\nthe git mailing list. It happend to me, too, that patches were\nrejected after a brief or after a lengthy discussion. So, yes,\nfinally sometimes there is no change. But often the discussions\nreveal a better way of achieving the original goal. Nonetheless,\nit can be frustrating to the original author.\n\nThanks for you effort of improving the documentation.\n\n\tSteffen\n"},{"id":"58652","messageId":"47317B18.7000804@op5.se","threadId":"10675","inReplyTo":"DED2A61B-B5AE-4BAA-942A-18A61924611E@zib.de","subject":"Re: [PATCH] Documentation: enhanced \"git for CVS users\" doc about shared repositories","fromName":"Andreas Ericsson","fromEmail":"ae@op5.se","sentAt":"2007-11-07T08:45:12Z","receivedAt":"2007-11-07T08:45:12Z","isPatch":true,"sender":{"key":"ae@op5.se","avatar":"https://gravatar.com/avatar/426e89595c75a8f5252dd0c989e5fabe5bcac616e68557427ad9aef6b0ca342a?d=mp&s=160"},"body":"Steffen Prohaska wrote:\n>  BTW, useradd and such\n> would not help me at all, because I need to talk to my admin\n> anyway and he adds an account to the LDAP database.\n> \n\nI suspect this is the case for most companies looking to switch\nto git. It certainly is here. Personally, I tend to find documents\nstooping to toddler-level a bit insulting unless they're marked\nas \"walkthrough\" or \"for beginners\" or some such. Especially if\nthey are obviously not correct for all environments.\n\n-- \nAndreas Ericsson                   andreas.ericsson@op5.se\nOP5 AB                             www.op5.se\nTel: +46 8-230225                  Fax: +46 8-230231\n"},{"id":"58656","messageId":"864pfyfmmb.fsf@lola.quinscape.zz","threadId":"10675","inReplyTo":"Pine.LNX.4.64.0711070053320.4362@racer.site","subject":"Re: [PATCH] Documentation: enhanced \"git for CVS users\" doc about shared repositories","fromName":"David Kastrup","fromEmail":"dak@gnu.org","sentAt":"2007-11-07T09:09:16Z","receivedAt":"2007-11-07T09:09:16Z","isPatch":true,"sender":{"key":"dak@gnu.org","avatar":"https://avatars.githubusercontent.com/u/52141349?v=4"},"body":"Johannes Schindelin <Johannes.Schindelin@gmx.de> writes:\n\n> Remember, those who read \"git for CVS users\" are _unwilling_ to\n> spend the time reading git documentation (at least for the most\n> part).  If they encounter something which is not useful to them,\n> they will not just ignore it, they will stop reading.\n\nPeople who read documentation do this only in order to avoid reading\ndocumentation, anyway?  This must be about the most stupid argument to\nrefrain from augmenting documentation I have heard in a long time.\n\nIt may well be possible that some of the proposed additions don't have\na good place in the document.  I have not checked so myself.  But the\nabove criticism is not constructive for documentation writers since\nits logical conclusion would boil down to \"don't bother writing any\ndocumentation\".\n\n-- \nDavid Kastrup\n"},{"id":"58697","messageId":"20071107164748.GA10525@fieldses.org","threadId":"10675","inReplyTo":"277490E5-2B9A-4BA7-9DD7-C1CEE698B348@zib.de","subject":"Re: [PATCH] Documentation: enhanced \"git for CVS users\" doc about shared repositories","fromName":"J. Bruce Fields","fromEmail":"bfields@fieldses.org","sentAt":"2007-11-07T16:47:48Z","receivedAt":"2007-11-07T16:47:48Z","isPatch":true,"sender":{"key":"bfields@citi.umich.edu","avatar":null},"body":"On Wed, Nov 07, 2007 at 09:07:58AM +0100, Steffen Prohaska wrote:\n> On Nov 7, 2007, at 1:46 AM, Francesco Pretto wrote:\n>\n>> Junio C Hamano ha scritto:\n>>>\n>>> Honestly speaking, I am not too thrilled about making the\n>>> cvs-migration document much longer than what it currently is.\n>>>\n>\n> Maybe the description of setting up a shared repository should\n> go to the user-manual and cvs-migration should refer to the\n> user-manual, instead of the other way round. I don't like the\n> idea that the user-manual is referring to a CVS specific guide.\n> The user manual should be as self-contained as possible.\n\nI'd be interested in patches that did that.  If somebody wants to work\non that, they might want to start with\n\n\tgit://linux-nfs.org/~bfields/git.git docwork-foreign-scms\n\nwhich has the skeleton of an \"interoperating with foreign scms\" chapter.\n\nThe thing that's kept me from working on this in the past is that it's a\nbit of a step backwards for someone that *just* wants to get to the\ncvs-migration stuff, since now it may appear you have to plow through\nthe rest of the manual to get to it.\n\nWe could address that with clearer dependency information (\"before\nreading this chapter, read chapters 1 and 3...\"), and/or by providing\nsome more links (e.g. repopulate the howto directory with links to some\nchapters that address popular questions).\n\n--b.\n"},{"id":"58707","messageId":"20071107173217.GB10525@fieldses.org","threadId":"10675","inReplyTo":"Pine.LNX.4.64.0711070053320.4362@racer.site","subject":"Re: [PATCH] Documentation: enhanced \"git for CVS users\" doc about shared repositories","fromName":"J. Bruce Fields","fromEmail":"bfields@fieldses.org","sentAt":"2007-11-07T17:32:17Z","receivedAt":"2007-11-07T17:32:17Z","isPatch":true,"sender":{"key":"bfields@citi.umich.edu","avatar":null},"body":"On Wed, Nov 07, 2007 at 12:55:49AM +0000, Johannes Schindelin wrote:\n> Remember, those who read \"git for CVS users\" are _unwilling_ to spend the \n> time reading git documentation (at least for the most part).  If they \n> encounter something which is not useful to them, they will not just ignore \n> it, they will stop reading.\n\nThat might overstate the case a little, but I definitely agree that we\nshould get people to the information they need as quickly as possible,\nand that adding more beginning-unix-administration will interfere with\nthat goal for the intended audience.\n\nAnd it's not just here--there's probably lots of basic unix-commandline\nstuff that we could include with the user-manual (how find/xargs pipes\nwork, etc...), and that would similarly help one possible audience at\nthe expense of bogging it down for another audience.\n\nI think the way to help people without those prerequisites is by clearer\nstatements of prerequisites, and references to documentation elsewhere\nwhere appropriate.\n\n--b.\n"}]}