From: Ian Jackson Date: Sat, 30 Jun 2018 21:25:28 +0000 (+0100) Subject: WIP X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=commitdiff_plain;h=4050bc1eb81da5c73a45dd8f947009e000390dac;p=dgit.git WIP --- diff --git a/dgit-downstream-dsc.5.pod b/dgit-downstream-dsc.5.pod index d8afcd4b..eebfe999 100644 --- a/dgit-downstream-dsc.5.pod +++ b/dgit-downstream-dsc.5.pod @@ -5,23 +5,9 @@ This guide is to help you if: * you want to publish source packages as well as git branches -Not every option is covered here. dgit(1) has a mostly-complete list -of config options, although not always with useful descriptions. - -You will need to choose a DISTRO name for your distro. This should be -stable; globally unique; preferably not contain full stops or -underscores; and preferably be lowercase. - You will also need: - * Software to manage a Debian-format archive, suitable for use - by apt (including apt-get source). I suggest reprepro. - This guide will not help you much with setting up reprepro. - - * A git server. It must accessible push by ssh, and by anonymous - internet users (by the git https smart protocol, preferably; - failing that, git:// or plain http might do, although they - leave your dgit users vulnerable). + * A git server. [...] There are various options for the git server, depending on how much you trust your uploaders. There are four levels of trust and @@ -78,29 +64,8 @@ Set up your git server, as follows: You should set the following global (or user) git config options: - dgit-distro.DISTRO.git-url - dgit-distro.DISTRO.git-url-suffix - Specifies the publicly accessible git URLs for your - dgit git server. The urls generated are - - The url should be stable. - - dgit-distro.DISTRO/push.git-url "" - dgit-distro.DISTRO/push.git-host - FQDN of your git server's ssh interface - - dgit-distro.DISTRO/push.git-user-force - Set to `dgit' if you are not using `shell account' mode - dgit-distro.DISTRO/push.username - Each user's username on the server, when using `shell - account' mode. - - dgit-distro.DISTRO/push.git-proto "git+ssh://" - dgit-distro.DISTRO/push.git-path "/dgit/DISTRO/repos" - (Or in shell account mode, whereever your repos are.) - dgit-distro.DISTRO.git-check "true" - dgit-distro.DISTRO.git-check-suffix "/info/refs" + dgit-distro.DISTRO.git-check-suffix "" This works with cgit. What's needed is a way to construct a URL which will retrieve some object if the repo exists on the server, or give 404 otherwise. The urls are diff --git a/dgit-downstream-dsc.7.pod b/dgit-downstream-dsc.7.pod index 062ad984..3029ab47 100644 --- a/dgit-downstream-dsc.7.pod +++ b/dgit-downstream-dsc.7.pod @@ -22,6 +22,10 @@ you can work as a Debian downstream purely using dgit and git branches. You can push your source code as a git branch to an ordinary git server. See L. +Not every option is covered here. +L has a mostly-complete list +of config options, although not always with useful descriptions. + =head1 NAMES You need to choose some names. @@ -36,18 +40,22 @@ So in dgit terms, you are setting up a distro. You need a name for yourself (ie for your distro). The name will appear in the git tags made by your tools, and in configuration settings. +It must be globally unique across +all people and institutions who use dgit. You could choose your organisation's domain name, or a part of it if you think that is going to be very unique. -The distro name may contain alphanumerics and B<. + ->, -although B<-> may be confusing and probably best avoided. +The distro name may contain ascii alphanumerics and B<. + ->, +although B<-> may be confusing and is probably best avoided. +Try to avoid uppercase letters (and underscore): +you will be typing this name a lot. For example, if you were the Free Software Foundation Europe (fsfe.org) you might call your distro fsfe or fsfe.org. In the rest of this document we will write -I for your distro name. +I for your distro name. =item "suite" names @@ -86,7 +94,8 @@ Everyone who will use dgit push needs to be able to update BI (note, not BI) on that server, and to make tags -IBI and BIBI. +IBI and BIBI. +Normally this would be done over ssh. The server may host other branches and tags too. So this might be your ordinary git server, @@ -95,6 +104,11 @@ or an instance of a git hosting system. Everyone who obtains one of your source packages, or who will run B and B, needs to have at least read access to the git server. +Ideally everything would be published +via the git smart https protocol. + +The git server should have a stable name and path structure. +Best is to give it a DNS name of its own. Debian's dgit git server has special access control rules, implemented in B and B @@ -123,7 +137,7 @@ Instead, we assume you already have reprepro working. You should also write appropriate dput configuration, since dgit uses dput to upload packages to the archive. This will involve choosing a dput host name. -That's probably your distro name, I. +That's probably your distro name, I. =back @@ -136,46 +150,74 @@ dgit is configured via git's configuration system, so this is done with git configuration. See L. +Below, in the headings, B is literal text and I +is things that vary. +In the descriptions of the effects of config settings, +we refer to the config values C. + =over -=item git url structure +=item BIB<.git-url>, B<.git-url-suffix> -The format of the readonly unauthenticated urls -(hopefully https, but http or git will do) -for your packages' git repos. -These will be of the form: -CBIC. +Specify the publicly accessible git URLs for your +dgit git server. The urls generated are +CIC -Configure: +The url should be stable because its name is published in .dsc files. -BIB<.git-url> = C +=item BIB -BIB<.git-url-suffix> = C (if any) +The domain name of your git server's ssh interface. -=item git server access via ssh +=item BIB BIB -dgit push will either -B IB<@>C -or -B CB<@>C -and expect to find the repos in -CB/>IC +Some git hosting systems expect everyone to +connect over ssh as the same user, often B. +If this is the case, set C to that user. + +If you have a normal git over ssh arrangement, +where people ssh as themselves, +leave C unset. +If a user wishes to override the username +(for example, if their local username is not the same as on the server) +they can set C. + +=item BIB -Configure: +Set this to the empty string. +This will arrange that push accesses to the ssh server will use +C, etc. -BIB "" +=item BIB B -BIB C +=item CIB -dgit-distro.I/push.git-user-force C -(eg you would set this to B if your hosting service -expects every user to ssh to git@service) +The path to your repositories. +dgit push will try to push to +C[C|CB<@>]CBI -CIB B +=item BIB<.git-check>, B<.git-check-suffix> -CIB C (eg BIB) +dgit clone needs to be able to tell whether there is +yet a git repository for a particular package. -CIB C (if any) +If you always have a git repository for every package in your archive, +perhaps because you never use dput/dupload, and always dgit push, +Set C to B. + +Otherwise, set C to a url prefix - ideally, https. +dgit clone will try to fetch +CIC +and expect to get either some successful fetch (it doesn't matter what) +or a file not found error (http 404 status code). +Other outcomes are fatal errors. + +If your git server runs cgit, +then you can set C to the same as C, +and C to B. + +a package actually +has a git repository. =item git repository existence testing @@ -198,28 +240,25 @@ Assuming your git server package -dgit-distro.I.git-url-suffix .git - - -dgit-distro.I.git-check "true" +dgit-distro.I.git-check "true" -dgit-distro.I.git-check-suffix "/info/refs" +dgit-distro.I.git-check-suffix "/info/refs" -dgit-distro.I/push.git-check "ssh-cmd" +dgit-distro.I/push.git-check "ssh-cmd" -dgit-distro.I/push.git-create "true" +dgit-distro.I/push.git-create "true" -dgit-distro.I.upload-host I +dgit-distro.I.upload-host I -dgit-distro.I.mirror http://archive.I.org/I +dgit-distro.I.mirror http://archive.I.org/I -dgit-distro.I.archive-query "aptget:" +dgit-distro.I.archive-query "aptget:" -dgit-suite.wheezy-staging.distro I +dgit-suite.wheezy-staging.distro I -dgit-suite.jessie-staging.distro I +dgit-suite.jessie-staging.distro I -dgit-suite.stretch-staging.distro I +dgit-suite.stretch-staging.distro I