[PATCH] Update setup-git-server-over-http.txt based on my experience.

[PATCH] Update setup-git-server-over-http.txt based on my experience.

[Matthieu Moy]

I managed to set up a Git repository on a preconfigured WebDAV server,
without installing Git on it or changing the configuration. This patch
reflects this (it previously stated that Git was _necessary_ on the
server, which isn't true). Also give a few hints to troubleshoting.

Signed-off-by: Matthieu Moy <Matthieu.Moy@imag.fr>
---
 Documentation/howto/setup-git-server-over-http.txt |   36 +++++++++++++++----
 1 files changed, 28 insertions(+), 8 deletions(-)

diff --git a/Documentation/howto/setup-git-server-over-http.txt b/Documentation/howto/setup-git-server-over-http.txt
index 8eadc20..34d377a 100644
--- a/Documentation/howto/setup-git-server-over-http.txt
+++ b/Documentation/howto/setup-git-server-over-http.txt
@@ -40,9 +40,10 @@ What's needed:
 
 - have permissions to chown a directory
 
-- have git installed at the server _and_ client
+- have git installed on the client, and preferably on the server
 
-In effect, this probably means you're going to be root.
+In effect, this probably means you're going to be root, or that you're
+using a preconfigured WebDAV server.
 
 
 Step 1: setup a bare GIT repository
@@ -50,9 +51,9 @@ Step 1: setup a bare GIT repository
 
 At the time of writing, git-http-push cannot remotely create a GIT
 repository. So we have to do that at the server side with git. Another
-option would be to generate an empty repository at the client and copy
-it to the server with WebDAV. But then you're probably the first to
-try that out :)
+option is to generate an empty repository at the client and copy it to
+the server with a WebDAV client (which is the only option if Git is
+not installed on the server).
 
 Create the directory under the DocumentRoot of the directories served
 by Apache. As an example we take /usr/local/apache2, but try "grep
@@ -169,7 +170,8 @@ On Debian:
 
    Most tests should pass.
 
-A command line tool to test WebDAV is cadaver.
+A command line tool to test WebDAV is cadaver. If you prefer GUIs,
+konqueror can open WebDAV URLs as "webdav://..." or "webdavs://...".
 
 If you're into Windows, from XP onwards Internet Explorer supports
 WebDAV. For this, do Internet Explorer -> Open Location ->
@@ -179,8 +181,10 @@ http://<servername>/my-new-repo.git [x] Open as webfolder -> login .
 Step 3: setup the client
 ------------------------
 
-Make sure that you have HTTP support, i.e. your git was built with curl.
-The easiest way to check is to look for the executable 'git-http-push'.
+Make sure that you have HTTP support, i.e. your git was built with
+curl (and a recent enough version). The easiest way to check is to
+look for the executable 'git-http-push'. The command "git http-push"
+with no argument should display a usage message.
 
 Then, add the following to your $HOME/.netrc (you can do without, but will be
 asked to input your password a _lot_ of times):
@@ -212,6 +216,10 @@ It is important to put the last '/'; Without it, the server will send
 a redirect which git-http-push does not (yet) understand, and git-http-push
 will repeat the request infinitely.
 
+Also note that the URL should point to the git repository itself, that
+is, to the '.git/' directory and not the working tree in case the
+repository is non-bare.
+
 
 Step 4: make the initial push
 -----------------------------
@@ -224,6 +232,13 @@ This pushes branch 'master' (which is assumed to be the branch you
 want to export) to repository called 'upload', which we previously
 defined with git-config.
 
+Using a proxy:
+--------------
+
+If you have to access the WebDAV server from behind an HTTP(S) proxy,
+set the variable 'all_proxy' to 'http://proxy-host.com:port', or
+'http://login-on-proxy:passwd-on-proxy@proxy-host.com:port'. See 'man
+curl' for details.
 
 Troubleshooting:
 ----------------
@@ -248,9 +263,14 @@ Reading /usr/local/apache2/logs/error_log is often helpful.
 
   On Debian: Read /var/log/apache2/error.log instead.
 
+If you access HTTPS locations, git may fail verifying the SSL
+certificate (this is return code 60). Setting http.sslVerify=false can
+help diagnosing the problem, but removes security checks.
+
 
 Debian References: http://www.debian-administration.org/articles/285
 
 Authors
   Johannes Schindelin <Johannes.Schindelin@gmx.de>
   Rutger Nijlunsing <git@wingding.demon.nl>
+  Matthieu Moy <Matthieu.Moy@imag.fr>
-- 
1.5.5.rc0.25.g9d90.dirty

Re: [PATCH] Update setup-git-server-over-http.txt based on my experience.

[Johannes Schindelin]

Hi,

I don't like the commit subject.  At all.

On Thu, 3 Apr 2008, Matthieu Moy wrote:

> -- have git installed at the server _and_ client
> +- have git installed on the client, and preferably on the server

How do you want to initialise the repository on the server, then?  (IOW 
you should mention here that you need a WebDAV client on the client if you 
do not have Git on the server, and that it is way more fiddly.)

> -In effect, this probably means you're going to be root.
> +In effect, this probably means you're going to be root, or that you're
> +using a preconfigured WebDAV server.

Either you strike "probably" or you skip what you added.

> @@ -169,7 +170,8 @@ On Debian:
>  
>     Most tests should pass.
>  
> -A command line tool to test WebDAV is cadaver.
> +A command line tool to test WebDAV is cadaver. If you prefer GUIs,
> +konqueror can open WebDAV URLs as "webdav://..." or "webdavs://...".

What do you do if you have MacOSX, or Windows?

> @@ -179,8 +181,10 @@ http://<servername>/my-new-repo.git [x] Open as webfolder -> login .
>  Step 3: setup the client
>  ------------------------
>  
> -Make sure that you have HTTP support, i.e. your git was built with curl.
> -The easiest way to check is to look for the executable 'git-http-push'.
> +Make sure that you have HTTP support, i.e. your git was built with
> +curl (and a recent enough version).

Say what version.  Otherwise this comment will soon be very, very stale.

> +The easiest way to check is to +look for the executable 
> 'git-http-push'. The command "git http-push" +with no argument should 
> display a usage message.

My search revealed that http-push was in Git since tags/v0.99.9e^2~9^2~4.  
Which is not recent at all.

> @@ -212,6 +216,10 @@ It is important to put the last '/'; Without it, the server will send
>  a redirect which git-http-push does not (yet) understand, and git-http-push
>  will repeat the request infinitely.
>  
> +Also note that the URL should point to the git repository itself, that
> +is, to the '.git/' directory and not the working tree in case the
> +repository is non-bare.

It makes no sense to describe the case of a non-bare repository.

Especially with those many threads on the list these days, describing the 
mess people got into by pushing into non-bare repositories!

> @@ -224,6 +232,13 @@ This pushes branch 'master' (which is assumed to be the branch you
>  want to export) to repository called 'upload', which we previously
>  defined with git-config.
>  
> +Using a proxy:
> +--------------
> +
> +If you have to access the WebDAV server from behind an HTTP(S) proxy,
> +set the variable 'all_proxy' to 'http://proxy-host.com:port', or
> +'http://login-on-proxy:passwd-on-proxy@proxy-host.com:port'. See 'man
> +curl' for details.

You only need http_proxy.

Ciao,
Dscho

Re: [PATCH] Update setup-git-server-over-http.txt based on my experience.

[Johannes Schindelin]

Hi,

On Thu, 3 Apr 2008, Matthieu Moy wrote:

> Johannes Schindelin <Johannes.Schindelin@gmx.de> writes:
> 
> > I don't like the commit subject.  At all.
> 
> Well, I can't think of a better one. The patch introduces several minor 
> changes, and I don't think it deserves a real patch serie for each 
> unrelated change.
> 
> Suggestions welcome.

Since your changes are mostly about using WebDAV to copy an empty git 
repository to the server, you could allude to that.

> > On Thu, 3 Apr 2008, Matthieu Moy wrote:
> >
> >> -- have git installed at the server _and_ client
> >> +- have git installed on the client, and preferably on the server
> >
> > How do you want to initialise the repository on the server, then?  
> > (IOW you should mention here that you need a WebDAV client on the 
> > client if you do not have Git on the server, and that it is way more 
> > fiddly.)
> 
> What part of
> 
>  Another
>  option is to generate an empty repository at the client and copy it to
>  the server with a WebDAV client (which is the only option if Git is
>  not installed on the server).
> 
> is unclear ?

It is too long.

-- have git installed on the client

-- have git installed on the server (or if you cannot, get a WebDAV 
   client such as Konqueror, Internet Exploder, etc.)

> >> -In effect, this probably means you're going to be root.
> >> +In effect, this probably means you're going to be root, or that you're
> >> +using a preconfigured WebDAV server.
> >
> > Either you strike "probably" or you skip what you added.
> 
> Why?

Because you do not need to be "root" if WebDAV is preconfigured?

> >> @@ -169,7 +170,8 @@ On Debian:
> >>  
> >>     Most tests should pass.
> >>  
> >> -A command line tool to test WebDAV is cadaver.
> >> +A command line tool to test WebDAV is cadaver. If you prefer GUIs,
> >> +konqueror can open WebDAV URLs as "webdav://..." or "webdavs://...".
> >
> > What do you do if you have MacOSX, or Windows?
> 
> You read messages instead of truncating them if you're on windows.
> 
> I have no idea about MacOSX, but that's not the point of my patch.

Right, but the text you modify is not supposed to be Linux-specific.

> >> -Make sure that you have HTTP support, i.e. your git was built with curl.
> >> -The easiest way to check is to look for the executable 'git-http-push'.
> >> +Make sure that you have HTTP support, i.e. your git was built with
> >> +curl (and a recent enough version).
> >
> > Say what version.  Otherwise this comment will soon be very, very stale.
> >
> >> +The easiest way to check is to +look for the executable 
> >> 'git-http-push'. The command "git http-push" +with no argument should 
> >> display a usage message.
> >
> > My search revealed that http-push was in Git since tags/v0.99.9e^2~9^2~4.  
> > Which is not recent at all.
> 
> Before my patch, the explanation says that you just need to check
> whether you have git-http-push, which is insufficient. With my patch,
> it gives an accurate check. I believe this is an improvement.

Oh?  So a usage message qualifies for "recent enough"?  In that case, 
v0.99.9f is "recent enough".  I find that hardly helpful.

> >> +Also note that the URL should point to the git repository itself, that
> >> +is, to the '.git/' directory and not the working tree in case the
> >> +repository is non-bare.
> >
> > It makes no sense to describe the case of a non-bare repository.
> 
> Actually, it makes no real sense to have a non-bare repository. But I've 
> been bitten by this (I just typed "git init" without --bare, and 
> uploaded it). Since git-http-push gives _very_ bad error messages, it's 
> good to point the user to potential mistakes to help troubleshooting.

If it makes no real sense to have a non-bare repository, why do you even 
_suggest_ what to do in that case?  You should rather say that it makes no 
sense to have a non-bare repository.  And probably add "because a 
http-push will not update the working directory anyway".

> > >> +Using a proxy:
> >> +--------------
> >> +
> >> +If you have to access the WebDAV server from behind an HTTP(S) proxy,
> >> +set the variable 'all_proxy' to 'http://proxy-host.com:port', or
> >> +'http://login-on-proxy:passwd-on-proxy@proxy-host.com:port'. See 'man
> >> +curl' for details.
> >
> > You only need http_proxy.
> 
> What makes you think that?

I use it in msysgit.

(Okay, not for pushing, but for fetching, which technically uses the 
same protocol.)

> (hint: I've been bitten by this too).

The only way I see this could bite you is if curl does not heed http_proxy 
for https:// protocol.

There's another thing.  My curl manpage insists that ALL_PROXY is all 
capital.  Can you clarify?

Ciao,
Dscho

Re: [PATCH] Update setup-git-server-over-http.txt based on my experience.

[Matthieu Moy]

Johannes Schindelin <Johannes.Schindelin@gmx.de> writes:

> Hi,
>
> I don't like the commit subject.  At all.

Well, I can't think of a better one. The patch introduces several
minor changes, and I don't think it deserves a real patch serie for
each unrelated change.

Suggestions welcome.

> On Thu, 3 Apr 2008, Matthieu Moy wrote:
>
>> -- have git installed at the server _and_ client
>> +- have git installed on the client, and preferably on the server
>
> How do you want to initialise the repository on the server, then?  (IOW 
> you should mention here that you need a WebDAV client on the client if you 
> do not have Git on the server, and that it is way more fiddly.)

What part of

 Another
 option is to generate an empty repository at the client and copy it to
 the server with a WebDAV client (which is the only option if Git is
 not installed on the server).

is unclear ?

>> -In effect, this probably means you're going to be root.
>> +In effect, this probably means you're going to be root, or that you're
>> +using a preconfigured WebDAV server.
>
> Either you strike "probably" or you skip what you added.

Why?

>> @@ -169,7 +170,8 @@ On Debian:
>>  
>>     Most tests should pass.
>>  
>> -A command line tool to test WebDAV is cadaver.
>> +A command line tool to test WebDAV is cadaver. If you prefer GUIs,
>> +konqueror can open WebDAV URLs as "webdav://..." or "webdavs://...".
>
> What do you do if you have MacOSX, or Windows?

You read messages instead of truncating them if you're on windows.

I have no idea about MacOSX, but that's not the point of my patch.

>> -Make sure that you have HTTP support, i.e. your git was built with curl.
>> -The easiest way to check is to look for the executable 'git-http-push'.
>> +Make sure that you have HTTP support, i.e. your git was built with
>> +curl (and a recent enough version).
>
> Say what version.  Otherwise this comment will soon be very, very stale.
>
>> +The easiest way to check is to +look for the executable 
>> 'git-http-push'. The command "git http-push" +with no argument should 
>> display a usage message.
>
> My search revealed that http-push was in Git since tags/v0.99.9e^2~9^2~4.  
> Which is not recent at all.

Before my patch, the explanation says that you just need to check
whether you have git-http-push, which is insufficient. With my patch,
it gives an accurate check. I believe this is an improvement.

>> +Also note that the URL should point to the git repository itself, that
>> +is, to the '.git/' directory and not the working tree in case the
>> +repository is non-bare.
>
> It makes no sense to describe the case of a non-bare repository.

Actually, it makes no real sense to have a non-bare repository. But
I've been bitten by this (I just typed "git init" without --bare, and
uploaded it). Since git-http-push gives _very_ bad error messages,
it's good to point the user to potential mistakes to help
troubleshooting.

>> +Using a proxy:
>> +--------------
>> +
>> +If you have to access the WebDAV server from behind an HTTP(S) proxy,
>> +set the variable 'all_proxy' to 'http://proxy-host.com:port', or
>> +'http://login-on-proxy:passwd-on-proxy@proxy-host.com:port'. See 'man
>> +curl' for details.
>
> You only need http_proxy.

What makes you think that?

(hint: I've been bitten by this too).

-- 
Matthieu