From mboxrd@z Thu Jan 1 00:00:00 1970 From: ng0 Subject: Re: [PATCH] gnu: service: Add git-service. Date: Tue, 30 Aug 2016 11:45:06 +0000 Message-ID: <874m62pjjx.fsf@we.make.ritual.n0.is> References: <87poor4tgx.fsf@we.make.ritual.n0.is> <878tvf7jfd.fsf@igalia.com> <878tvfr6ec.fsf@we.make.ritual.n0.is> <87eg57tk6t.fsf@we.make.ritual.n0.is> <87eg5666y4.fsf@igalia.com> Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit Return-path: Received: from eggs.gnu.org ([2001:4830:134:3::10]:36728) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1behTe-00020y-RN for guix-devel@gnu.org; Tue, 30 Aug 2016 07:45:16 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1behTa-000050-5R for guix-devel@gnu.org; Tue, 30 Aug 2016 07:45:14 -0400 Received: from mithlond.libertad.in-berlin.de ([2001:67c:1400:2490::1]:52809 helo=beleriand.n0.is) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1behTZ-0008V1-Na for guix-devel@gnu.org; Tue, 30 Aug 2016 07:45:10 -0400 In-Reply-To: <87eg5666y4.fsf@igalia.com> List-Id: "Development of GNU Guix and the GNU System distribution." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: guix-devel-bounces+gcggd-guix-devel=m.gmane.org@gnu.org Sender: "Guix-devel" To: Andy Wingo Cc: guix-devel@gnu.org Hi, Andy Wingo writes: > On Mon 29 Aug 2016 22:05, ng0 writes: > >> +@node Version Control >> +@subsubsection Version Control >> + >> +The @code{(gnu services version-control)} module provides the following services: >> + >> +@deffn {Scheme Procedure} git-service [git @var{git}] @ >> + [base-path ``/var/git/repositories''] @ >> + [port ``9418''] > > Though there are no strict conventions for this, the right way to do > this is to use #:foo for keyword arguments, and then regular scheme for > the default value initializers. So > > @deffn {Scheme Procedure} git-service [#:git git] @ > [#:base-path "/var/git/repositories"] @ > [#:port 9418] > > Note lack of smart quotes on base-path. I had this at first, but then I found a service which did not use #:keyword, so I got confused. Writing this service was hard enough because I understand scheme in general more than 9 months ago, but not enough to explain or understand all of what I've written in this service, as it started as a modification of parts of other services. I will adjust and we'll see if it works. Thanks. >I also think that "path" might > not be the right word, which in GNU manuals is only used for search > paths. See the "GNU Manuals" section of standards.texi for more. > Anyway I suggest #:base-directory. Make sure the port is an integer and > not a string. See 'man git daemon'. The switch is called --base-path. Looking at the openrc conf.d/git or what the config file was called again, they stick to this name too. It would just cause confusion if we go ahead and call it differently. Upstream should be fixed, but I'm not going there. If you think we should break expectations, I can rename it. >> +Return a service to run the @uref{https://git-scm.com, git} daemon version control >> +daemon. > > Extra "daemon" here. Probably needs a sentence on what running the > daemon will do (namely, expose local repositories for remote access). > > What about authentication? Is this purely anonymous? Exactly, authentication is handled via other daemons, for example ssh or gitolite. git daemon supports no authentication and is read-only, as far as I know. At the servers I use and setup, I pull via git://,http://,https:// and push via ssh. Its selfdescription is: git-daemon - A really simple server for Git repositories. A really simple TCP Git daemon that normally listens on port "DEFAULT_GIT_PORT" aka 9418. It waits for a connection asking for a service, and will serve that service if it is enabled. It verifies that the directory has the magic file "git-daemon-export-ok", and it will refuse to export any Git directory that hasn’t explicitly been marked for export this way (unless the --export-all parameter is specified). If you pass some directory paths as git daemon arguments, you can further restrict the offers to a whitelist comprising of those. By default, only upload-pack service is enabled, which serves git fetch-pack and git ls-remote clients, which are invoked from git fetch, git pull, and git clone. This is ideally suited for read-only updates, i.e., pulling from Git repositories. An upload-archive also exists to serve git archive. >> +The git daemon runs as the @code{git} unprivileged user. It is started with >> +the fixed parameters @code{--informative-errors} and @code{--syslog}. You can > >> +pass the parameter @var{base-path}, which remaps all the pathrequests as >> +relative to the given path. If you run git daemon with >> +@var{base-path /var/git/repositories} on example.com, then if you later try >> +to pull @code{git://example.com/hello.git}, git daemon will interpret the path >> +as /var/git/repositories/hello.git. > > Need @code{} on this last file name. >Use "file name" instead of path in general. Why? It is 1 or more files in a path which happens to sit in $base-path/$repository. You will also requests a number of files, not one individual file and the .git is not a file but a directory. Path for me reads correct, can you give me some explanation why you think file name should be used instead of path? >> +Furthermore it takes the parameter @var{port} which defaults to 9418. >> +Run @command{man git daemon} for information about the options. > > This man command does not work. Works for me. As far as I know man pages were merged into git package recently. When I run this on debian with guix, 'man git daemon' works too. >> +(define %git-accounts >> + ;; User account and groups for git-daemon. >> + ;; We can give it git-shell for now, otherwise we can switch to /bin/sh. > > What does this comment mean? Why would we switch? I am not sure about the limitations of git-shell compared to /bin/sh. If this turns out to be a mistake, it can be corrected. The only thing I know about git-shell is that it allows no logins. >> +(define* (git-service #:key >> + (git git) >> + (base-path "/var/git/repositories") >> + (port 9418)) >> + "Return a service that runs @url{https://git-scm.org,git} as a daemon. >> +The daemon will listen on the port specified in @var{port}. >> +In addition, @var{base-path} specifies the path which will repositories >> +which can be exported by adding 'git-daemon-export-ok' files to them." > > This docstring needs updating as regards the word "path" I think and > also this info about git-daemon-export-ok probably needs to go in the > manual. I'm not sure what has to be documented. I find the upstream documentation complete enough. If we stick to our current general view on documentation we should not provide this info at all. When I got started it was as easy as adding base-path and port to the config of the service on gentoo and some additional switches. I then had to read the upstream docs to discover that git-daemon-export-ok was needed. If services in guix are translated, and in upstream they aren't that is the only reason why I would include more info than necessary. I would even remove most of the description as this was just to test what needs to go in there. >From your first email I assume you have never run or setup git daemon on a computer. Could you read the upstream documentation and tell me if there are open questions after readin them? Those are the things I must point out in the service documentation. man page: https://git-scm.com/docs/git-daemon documentation: https://git-scm.com/book/en/v2/Git-on-the-Server-Git-Daemon > Other than that, looking good :) > > Andy Many thanks for taking your time to review this. -- ng0 For non-prism friendly talk find me on http://www.psyced.org