Re: [PATCH] Clarify documentation of git-cvsserver, particularly in relation to git-shell

From: Johannes Schindelin <johannes.schindelin@gmx.de>
Date: Apr 19, 2008, 15:43 UTC
Message-ID: <alpine.DEB.1.00.0804191620380.20708@eeepc-johanness>
In-Reply-To: <1208293415-19212-1-git-send-email-scc@ScottCollins.net>

Hi,

On Tue, 15 Apr 2008, Scott Collins wrote:

> Currently, for SSH clients restricted to git-shell, CVS_SERVER should
> not be changed: git-shell understands the default value of 'cvs' to mean
> git-cvsserver and actually _doesn't_ understand the command
> 'git-cvsserver'.

How about a new paragraph here?

> This makes it totally transparent to CVS users, but the
> original wording here perhaps less so to the person setting-up CVS
> access.  Previous wording mentioning GIT_AUTHOR, GIT_COMMITTER variables
> may not have made clear we really meant GIT_AUTHOR_(NAME|EMAIL), etc.

Likewise here.

Show 19 quoted lines

> Add a bit of text to differentiate cvs -d (setting CVSROOT) from cvs co
> -d (setting the name of the newly checked out directory).  Removed an
> extra 'Example:' string.
> 
> Signed-off-by: Scott Collins <scc@ScottCollins.net>
> ---
>  Documentation/git-cvsserver.txt |   27 +++++++++++++++------------
>  1 files changed, 15 insertions(+), 12 deletions(-)
> 
> diff --git a/Documentation/git-cvsserver.txt b/Documentation/git-cvsserver.txt
> index 9cec802..44734e8 100644
> --- a/Documentation/git-cvsserver.txt
> +++ b/Documentation/git-cvsserver.txt
> @@ -106,11 +106,13 @@ Note: Newer CVS versions (>= 1.12.11) also support specifying
>  CVS_SERVER directly in CVSROOT like
>  
>  ------
> -cvs -d ":ext;CVS_SERVER=git-cvsserver:user@server/path/repo.git" co <HEAD_name>
> +cvs -d ":ext;CVS_SERVER=git-cvsserver:user@server/path/repo.git" co <HEAD_name> -d <dir_name>

I am not really sure.  Normal usage AFAIAC is without -d.

Show 7 quoted lines

>  ------
>  This has the advantage that it will be saved in your 'CVS/Root' files and
>  you don't need to worry about always setting the correct environment
> -variable.
> +variable.  SSH users restricted to git-shell don't need to override the default
> +with CVS_SERVER (and probably shouldn't) as git-shell understands 'cvs' to mean
> +git-cvsserver.

Please make these lines shorter.

Show 12 quoted lines

> @@ -141,25 +143,26 @@ allowing access over SSH.
>          enabled=1
>  ------
>  --
> -3. On the client machine you need to set the following variables.
> -   CVSROOT should be set as per normal, but the directory should point at the
> -   appropriate git repo. For example:
> +3. If you didn't specify the CVSROOT/CVS_SERVER directly in the checkout command,
> +   automatically saving it in your 'CVS/Root' files, then you need to set them
> +   explicitly in your environment.  CVSROOT should be set as per normal, but the
> +   directory should point at the appropriate git repo.  As above, for SSH clients
> +   _not_ restricted to git-shell, CVS_SERVER should be set to git-cvsserver.

Please make the lines shorter.

Also, I seem to recall that "didn't" is considered colloquial speech, while you should write "did not" in written documentation.

Another thing: "CVSROOT should be set as per normal" strikes me as a little short on concrete, helpful details.

Thanks, Dscho