=head1 NAME
-dgit-downstream-dsc - tutorial for downstreams publishing source packages
+dgit-downstream-dsc - setting up dgit push for a new distro
=head1 INTRODUCTION
Note that often it is unnecessary to
publish traditional source packages.
-Source packages are complex, idiosyncratic and difficult to work with.
+Debian-format source packages can be complex,
+idiosyncratic and difficult to work with.
You should avoid them if you can.
If you do not need to publish source packages,
-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.
+you can work as a Debian downstream purely using git branches,
+(using dgit to get the source from Debian in git form).
+You can build binaries directly from git,
+and push package source code as a git branch to an ordinary git server.
See L<dgit-user(7)>.
Not every option is covered here.
=over
-=item "distro" name
+=item I<distro> name
dgit understands each thing it interacts with as a B<distro>.
So in dgit terms, you are setting up a distro.
In the rest of this document we will write
I<distro> for your distro name.
-=item "suite" names
+=item I<suite> names
In dgit and Debian archive terminology, a B<suite> is a line of
development, and/or a Debian release.
For example, at the time of writing, Debian has suites like
-sid> aka unstable>, buster aka testing,
-stretch aka stable.
-There are also ancillary suites like stretch-security.
+B<sid> aka B<unstable>, B<buster> aka B<testing>,
+and B<stretch> aka B<stable>.
+There are also ancillary suites like B<stretch-security>.
If your releases align with Debian's releases,
then your suites should contain the Debian suite names.
Suite names end up in git ref and branch names,
and on dgit command lines.
Suite names can contain alphanumerics and C<->.
-Other characters may work but is not recommended.
+Other characters may work but are not recommended.
=back
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.
+The git server name, and public git url structure,
+should be chosen so they will not need to change in the future.
+Best is to give the git server a DNS name of its own.
Debian's dgit git server has special access control rules,
implemented in B<dgit-repos-server> and B<dgit-repos-policy-debian>
If there is no or little distinction between
(i) developers who are entitled to upload (push) and
(ii) repository administrators,
-then a git server with ordinary access control will do.
+then a it is sufficient to provide a
+git server with a unix account for each user who will pushing,
+perhaps using ssh restricted commands.
=item Debian-format archive (repository)
The path to your repositories.
dgit push will try to push to
-C<git-proto>[C<git-user-force>|C<username>B<@>]C<git-path>B</>I<package>
+C<git-proto>[C<git-user-force>|C<username>B<@>]C<git-path>B</>I<package>B<.git>
=item B<dgit-distro.>I<distro>B<.git-check>, B<.git-check-suffix>
=item B<dgit-distro.>I<distro>B</push.git-check>, B</push.git-create>
-dgit push also needs to be able to check whether theh repo exists.
+dgit push also needs to be able to check whether the repo exists.
You can set both of these to B<ssh-cmd>,
which will use an ssh shell command to test repository existence.
Or leave them unset, and dgit push will use the readonly details.
-If repositories are created automatically0 on push, somehow,
+If repositories are created automatically on push, somehow,
you can set C<git-create> to B<true>.
=item B<dgit-distro.>I<distro>B<.upload-host>
=item B<dgit-distro.>I<distro>B<.archive-query>, B<.archive-query-url>
If you have a smallish distro,
-set this to B<aptget:> (with acolon).
+set this to B<aptget:> (with a colon).
If your distro is large
(eg, if it contains a substantial fraction of Debian)
See L<https://api.ftp-master.debian.org/>,
and set C<archive-query> to B<ftpmasterapi:> (with a colon)
and C<archive-query-url> to your API base URL.
+dgit uses these queries:
+B<suites>,
+B<dsc_in_suite/>I<isuite>B</>I<package> and
+B<file_in_archive/>I<pat>
--item B<dgit-suite.>I<suite>B<.distro> I<distro>
+=item B<dgit-suite.>I<suite>B<.distro> I<distro>
Set this for every one of your suites.
You will have to update this when new suites are created.
=back
+=head1 TEMPLATE GIT REPOSITORY
+
+When dgit push is used for I<package> for the first time,
+it must create a git repository on the git server.
+
+If C<git-create> is set to B<ssh-cmd>,
+dgit will use the user's shell access to the server to
+B<cp -a _template.git> I<package>B<.git>.
+So you should create B<_template.git> with suitable contents.
+
+=head1 SSH COMMANDS
+
+When a user who can push runs dgit,
+dgit uses ssh to access the git server.
+
+To make ssh restricted command easier,
+and for the benefit of dgit-repos-server,
+dgit's ssh commands
+each start with a parseable commentish rune.
+
+The ssh commands used by dgit are these:
+
+=over
+
+=item B<: dgit> I<distro> B<git-check> I<package> B<;>...
+
+Test whether I<package> has a git repo on the server already.
+Should print B<0> or B<1> and a newline,
+and exit status zero in either case.
+The rest of the command, after B<;>,
+is a shell implementation of this test.
+Used when C<git-check> is set to B<ssh-cmd>.
+
+=item B<: dgit> I<distro> B<git-create> I<package> B<;>...
+
+Create the git repository for I<package> on the server.
+See L</TEMPLATE GIT REPOSITORY>, above.
+The rest of the command is an appropriate invocation of cd and cp.
+Used when C<git-create> is set to B<ssh-cmd>.
+
+=item B<git-receive-pack>..., B<git-upload-pack>...
+
+dgit invokes git to access the repository;
+git then runs these commands.
+Note that dgit push will first do a git fetch over ssh,
+so you must provide upload-pack as well as receive-pack.
+
+=back
+
+(There are also other ssh commands
+which are historical or obscure.)
+
=head1 SEE ALSO
dgit(1)
~ianmdlvl / dgit.git / commitdiff