Test suite: Use t-make-hook-link for mirroring

[dgit.git] / dgit.1

diff --git a/dgit.1 b/dgit.1
index 9ebc7b1694070a5b1387705a6d1a6886912101db..d1bc042d68066a7abdbdf703ed765397ad3a8087 100644 (file)
--- a/dgit.1
+++ b/dgit.1
@@ -27,15 +27,23 @@ dgit \- git integration with the Debian archive
 [\fIdgit\-opts\fP] \fIaction\fR ...
 .SH DESCRIPTION
 .B dgit
 [\fIdgit\-opts\fP] \fIaction\fR ...
 .SH DESCRIPTION
 .B dgit

-allows you to treats the Debian archive as if it were a git
+allows you to treat the Debian archive as if it were a git

 repository.  See \fBdgit\fP(7) for detailed information about the data
 repository.  See \fBdgit\fP(7) for detailed information about the data

-model etc.
+model, common problems likely to arise with certain kinds of package,
+etc.

 
 

-The usual workflow is: 1. clone or fetch; 2. make and commit changes
-in git as desired; 3. run dgit build, dgit sbuild or dgit
-build-source, or generate the source and binary packages for upload
-some other way; 4. do pre-upload tests of the proposed upload; 5. run
-dgit push.
+The usual workflow is:
+.br
+1.     \fBdgit clone\fR or \fBfetch\fR;
+.br
+2.     make, do dev tests, and commit changes in git as desired;
+.br
+3.     build packages for upload, using e.g. \fBdgit sbuild\fR
+.br
+4.     do pre-upload tests of the proposed upload;
+.br
+5.     \fBdgit push\fR.
+.SH OPERATIONS

 .TP
 \fBdgit clone\fR \fIpackage\fP [\fIsuite\fP] [\fB./\fP\fIdir|\fB/\fP\fIdir\fR]
 Consults the archive and dgit-repos to construct the git view of
 .TP
 \fBdgit clone\fR \fIpackage\fP [\fIsuite\fP] [\fB./\fP\fIdir|\fB/\fP\fIdir\fR]
 Consults the archive and dgit-repos to construct the git view of


@@ -190,6 +198,14 @@ You will need similar enough versions of dgit on the build-host and
 the invocation host.  The build-host needs gnupg installed, with your
 public key in its keyring (but not your private key, obviously).
 .TP
 the invocation host.  The build-host needs gnupg installed, with your
 public key in its keyring (but not your private key, obviously).
 .TP

+.B dgit setup-mergechangelogs
+Configures a git merge helper for the file
+.B debian/changelog
+which uses
+.BR dpkg-mergechangelogs .
+You can use this in any git repository, not just ones used with
+the other dgit operations.
+.TP

 .B dgit quilt-fixup
 `3.0 (quilt)' format source packages need changes representing not
 only in-tree but also as patches in debian/patches.  dgit quilt-fixup
 .B dgit quilt-fixup
 `3.0 (quilt)' format source packages need changes representing not
 only in-tree but also as patches in debian/patches.  dgit quilt-fixup


@@ -213,13 +229,13 @@ Tries to fetch a copy of the source code for the dgit-repos-server,
 as actually being used on the dgit git server, as a git tree.
 .SH OPTIONS
 .TP
 as actually being used on the dgit git server, as a git tree.
 .SH OPTIONS
 .TP

-.BR --dry-run | -n
+.BR --dry-run " | " -n

 Go through the motions, fetching all information needed, but do not
 actually update the output(s).  For push, dgit does
 the required checks and leaves the new .dsc in a temporary file,
 but does not sign, tag, push or upload.
 .TP
 Go through the motions, fetching all information needed, but do not
 actually update the output(s).  For push, dgit does
 the required checks and leaves the new .dsc in a temporary file,
 but does not sign, tag, push or upload.
 .TP

-.BR --damp-run | -L
+.BR --damp-run " | " -L

 Go through many more of the motions: do everything that doesn't
 involve either signing things, or making changes on the public
 servers.
 Go through many more of the motions: do everything that doesn't
 involve either signing things, or making changes on the public
 servers.


@@ -239,7 +255,7 @@ Specifies that we should process source package
 rather than looking in debian/control or debian/changelog.
 Valid with dgit fetch and dgit pull, only.
 .TP
 rather than looking in debian/control or debian/changelog.
 Valid with dgit fetch and dgit pull, only.
 .TP

-.BR --clean=git | -wg
+.BR --clean=git " | " -wg

 The source tree should be cleaned, before building a source package
 with one of the build options, using
 .BR "git clean -xdf" .
 The source tree should be cleaned, before building a source package
 with one of the build options, using
 .BR "git clean -xdf" .


@@ -251,19 +267,41 @@ from being run.
 
 --clean=git is useful when the package's clean target is troublesome;
 the downside is simply that git clean may delete files you forgot to
 
 --clean=git is useful when the package's clean target is troublesome;
 the downside is simply that git clean may delete files you forgot to

-git add.
+git add.  --clean=git can also avoid needing the build-dependencies.
+.TP
+.BR --clean=git-ff " | " -wgf
+The source tree should be cleaned, before building a source package
+with one of the build options, using
+.BR "git clean -xdff" .
+This is like
+"git clean -xdf"
+but it also removes any subdirectories containing different git
+trees (which only unusual packages are likely to create).

 .TP
 .TP

-.BR --clean=none | -wn
+.BR --clean=check " | " -wn
+Merely check that the tree is clean (does not contain uncommitted
+files), before building a source package.
+.TP
+.BR --clean=none " | " -wn

 Do not clean the tree before building a source package.  If there are
 files which are not in git, or if the build creates such files, a
 subsequent dgit push will fail.
 .TP
 Do not clean the tree before building a source package.  If there are
 files which are not in git, or if the build creates such files, a
 subsequent dgit push will fail.
 .TP

-.BR --clean=dpkg-source | -wd
+.BR --clean=dpkg-source " | " -wd

 Use dpkg-buildpackage to do the clean, so that the source package
 is cleaned by dpkg-source running the package's clean target.
 This is the default.  It requires the package's build dependencies.
 .TP
 Use dpkg-buildpackage to do the clean, so that the source package
 is cleaned by dpkg-source running the package's clean target.
 This is the default.  It requires the package's build dependencies.
 .TP

-.BR -N | --new
+.BR --clean=dpkg-source-d " | " -wdd
+Use
+.B dpkg-buildpackage -d
+to do the clean, so that the source package
+is cleaned by dpkg-source running the package's clean target.
+The build-dependencies are not checked (due to
+.BR -d ),
+which violates policy, but may work in practice.
+.TP
+.BR -N " | " --new

 The package may be new in this suite.  Without this, dgit will
 refuse to push.
 .TP
 The package may be new in this suite.  Without this, dgit will
 refuse to push.
 .TP


@@ -325,7 +363,7 @@ because the dgit git tree does not have a
 .B .pc
 directory.)
 .TP
 .B .pc
 directory.)
 .TP

-.BR --quilt=nocheck | --no-quilt-fixup
+.BR --quilt=nocheck " | " --no-quilt-fixup

 Do not check whether up source format `3.0 (quilt)' metadata needs
 fixing up.  If you use this option and the metadata did in fact need
 fixing up, dgit push will fail.
 Do not check whether up source format `3.0 (quilt)' metadata needs
 fixing up.  If you use this option and the metadata did in fact need
 fixing up, dgit push will fail.


@@ -360,7 +398,7 @@ Passed to dpkg-genchanges (eventually).
 Specifies a single additional option to pass, eventually, to
 dpkg-genchanges.
 .TP
 Specifies a single additional option to pass, eventually, to
 dpkg-genchanges.
 .TP

-.RI \fB--curl=\fR program |\fB--dput=\fR program |...
+.RI \fB--curl=\fR program " | \fB--dput=\fR" program  " |..."

 Specifies alternative programs to use instead of
 .BR curl ,
 .BR dput ,
 Specifies alternative programs to use instead of
 .BR curl ,
 .BR dput ,


@@ -398,7 +436,7 @@ git to access dgit-repos, only git's idea of what ssh to use (eg,
 .BR GIT_SSH )
 is relevant.
 .TP
 .BR GIT_SSH )
 is relevant.
 .TP

-.RI \fB--curl:\fR option |\fB--dput:\fR option |...
+.RI \fB--curl:\fR option " | \fB--dput:\fR" option " |..."

 Specifies a single additional option to pass to
 .BR curl ,
 .BR dput ,
 Specifies a single additional option to pass to
 .BR curl ,
 .BR dput ,


@@ -549,49 +587,82 @@ Then run
 .BR "dgit push"
 to actually upload the result.
 .SH CONFIGURATION
 .BR "dgit push"
 to actually upload the result.
 .SH CONFIGURATION

-dgit looks at the following git config keys to control its behaviour.
-You may set them with git-config (either in system-global or per-tree
+dgit can be configured via the git config system.
+You may set keys with git-config (either in system-global or per-tree

 configuration), or provide
 .BI -c key = value
 on the dgit command line.
 configuration), or provide
 .BI -c key = value
 on the dgit command line.

+.LP
+Settings likely to be useful for an end user include:

 .TP
 .TP

-.BI dgit-suite. suite .distro
+.BR dgit-suite. \fIsuite\fR .distro " \fIdistro\fR"
+Specifies the distro for a suite.  dgit keys off the suite name (which
+appears in changelogs etc.), and uses that to determine the distro
+which is involved.  The config used is thereafter that for the distro.
+it then looks
+.TP
+.BI dgit.default.distro " distro"
+The default distro for an unknown suite.
+.TP
+.BR dgit-distro. \fIdistro\fR .readonly " " auto | a " | " true | t | y | 1 " | " false | f | n | 0
+Whether you have push access to the distro.
+For Debian, it is OK to use auto, which uses readonly mode if you are
+not pushing right now,
+but setting this to false will avoid relying on the mirror of the dgit
+git repository server.
+.TP
+.BI dgit-distro. distro .keyid

 .TP
 .TP

-.BI dgit.default.distro
+.BI dgit-distro. distro .mirror " url"

 .TP
 .BI dgit-distro. distro .username
 .TP
 .BI dgit-distro. distro .username

+Not relevant for Debian.

 .TP
 .TP

-.BI dgit-distro. distro .git-url
+.BI dgit-distro. distro .upload-host
+Might be useful if you have an intermediate queue server.
+.SH ACCESS CONFIGURATION
+There are many other settings which specify how a particular distro's
+services (archive and git) are provided.  These should not normally be
+adjusted, but are documented for the benefit of distros who wish to
+adopt dgit.
+.TP
+.BR dgit-distro. \fIdistro\fR /push. *
+If set, overrides corresponding non \fB/push\fR config when
+.BR readonly=false ,
+or when pushing and
+.BR readonly=auto .

 .TP
 .TP

-.BI dgit-distro. distro .git-user
+.BI dgit-distro. distro .git-url

 .TP
 .TP

-.BI dgit-distro. distro .git-host
+.BR dgit-distro. \fIdistro\fR .git-url [ -suffix ]

 .TP
 .BI dgit-distro. distro .git-proto
 .TP
 .BI dgit-distro. distro .git-path
 .TP
 .TP
 .BI dgit-distro. distro .git-proto
 .TP
 .BI dgit-distro. distro .git-path
 .TP

-.BI dgit-distro. distro .git-check
+.BR dgit-distro. \fIdistro\fR .git-check " " true | false | url | ssh-cmd

 .TP
 .TP

-.BI dgit-distro. distro .git-create
+.BI dgit-distro. distro .git-check-suffix

 .TP
 .TP

-.BI dgit-distro. distro .upload-host
+.BR dgit-distro. \fIdistro\fR .diverts.divert " " new-distro | / \fIdistro-suffix\fR

 .TP
 .TP

-.BI dgit-distro. distro .mirror
+.BI dgit-distro. distro .git-create " " ssh-cmd | true

 .TP
 .TP

-.BI dgit-distro. distro .archive-query
+.BR dgit-distro. \fIdistro\fR .archive-query " " ftpmasterapi: " | " madison: "\fIdistro\fR | " dummycat: "\fI/path\fR  | " sshpsql: \fIuser\fR @ \fIhost\fR : \fIdbname\fR

 .TP
 .TP

-.BI dgit-distro. distro .archive-query-default-component
+.BR dgit-distro. \fIdistro\fR .archive-query- ( url | tls-key | curl-ca-args )
+.TP
+.BI dgit-distro. distro .madison-distro

 .TP
 .TP

-.BI dgit-distro. distro .sshpsql-user
+.BI dgit-distro. distro .archive-query-default-component

 .TP
 .TP

-.BI dgit-distro. distro .sshpsql-host
+.BI dgit-distro. distro .ssh

 .TP
 .BI dgit-distro. distro .sshpsql-dbname
 .TP
 .TP
 .BI dgit-distro. distro .sshpsql-dbname
 .TP

-.BI dgit-distro. distro .ssh
+.BR dgit-distro. \fIdistro\fR . ( git | sshpsql ) - ( user | host | user-force )

 .TP
 .TP

-.BI dgit-distro. distro .keyid
+.BI dgit-distro. distro .backports-quirk

 .TP
 .BR dgit.default. *
 for each
 .TP
 .BR dgit.default. *
 for each


@@ -612,26 +683,6 @@ and other subprograms and modules used by dgit are affected by various
 environment variables.  Consult the documentaton for those programs
 for details.
 .SH BUGS
 environment variables.  Consult the documentaton for those programs
 for details.
 .SH BUGS

-We should be using some kind of vhost/vpath setup for the git repos on
-alioth, so that they can be moved later if and when this turns out to
-be a good idea.
-
-dgit push should perhaps do `git push origin', or something similar,
-by default.
-
-Debian does not have a working rmadison server, so to find out what
-version of a package is in the archive, or to canonicalise suite
-names, we ssh directly into the ftpmaster server and run psql there to
-access the database.
-
-The mechanism for checking for and creating per-package repos on
-alioth is a hideous bodge.  One consequence is that dgit currently
-only works for people with push access.
-
-Debian Maintainers are currently not able to push, as there is not
-currently any mechanism for determining and honouring the archive's
-ideas about access control.  Currently only DDs can push.
-

 dgit's git representation of format `3.0 (quilt)' source packages does
 not represent the patch stack as git commits.  Currently the patch
 series representation cannot round trip between git and the archive.
 dgit's git representation of format `3.0 (quilt)' source packages does
 not represent the patch stack as git commits.  Currently the patch
 series representation cannot round trip between git and the archive.


@@ -664,10 +715,6 @@ remote tracking suite branch.
 
 The option parser requires values to be cuddled to the option name.
 
 
 The option parser requires values to be cuddled to the option name.
 

-dgit assumes knowledge of the archive database.  (The information dgit
-needs is not currently available via any public online service with a
-well-defined interface, let alone a secure one.)
-

 --dry-run does not always work properly, as not doing some of the git
 fetches may result in subsequent actions being different.  Doing a
 non-dry-run dgit fetch first will help.
 --dry-run does not always work properly, as not doing some of the git
 fetches may result in subsequent actions being different.  Doing a
 non-dry-run dgit fetch first will help.