summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorSean Whitton <spwhitton@spwhitton.name>2019-07-06 16:01:45 +0100
committerSean Whitton <spwhitton@spwhitton.name>2019-07-07 09:54:19 +0100
commiteca709b776801cbd57eed32dab8b59fe8bc9a569 (patch)
tree9bf288fd1536c7465a5ae75b4edf005aad720274
parentf8fe5f19d1ec104f8735dd0d8813ae5e5317f536 (diff)
git-debpush(1): new manpage
Signed-off-by: Sean Whitton <spwhitton@spwhitton.name>
-rw-r--r--.gitignore1
-rw-r--r--Makefile5
-rw-r--r--git-debpush.1.pod191
3 files changed, 197 insertions, 0 deletions
diff --git a/.gitignore b/.gitignore
index b8b1af6..653c53e 100644
--- a/.gitignore
+++ b/.gitignore
@@ -19,5 +19,6 @@ dgit-sponsorship.7
dgit-downstream-dsc.7
git-debrebase.1
git-debrebase.5
+git-debpush.1
substituted
.po4a.translated-only
diff --git a/Makefile b/Makefile
index 7d0c422..890e371 100644
--- a/Makefile
+++ b/Makefile
@@ -154,5 +154,10 @@ git-debrebase.%: git-debrebase.%.pod
--name=$(subst .$*,,$@) \
$^ $@
+git-debpush.1: git-debpush.1.pod
+ pod2man --section=1 --date="Debian Project" --center="git-debpush" \
+ --name git-debpush \
+ $^ $@
+
%.view: %
man -l $*
diff --git a/git-debpush.1.pod b/git-debpush.1.pod
new file mode 100644
index 0000000..926e8cd
--- /dev/null
+++ b/git-debpush.1.pod
@@ -0,0 +1,191 @@
+=head1 NAME
+
+git-debpush - create & push a git tag with metadata for an ftp-master upload
+
+=head1 SYNOPSIS
+
+B<git debpush> [I<option>...]
+
+=head1 DESCRIPTION
+
+B<git-debpush> is a wrapper around git-tag(1) and git-push(1). It
+helps you create and push a specially formatted signed tag which
+indicates that the tagged commit should be pushed (or "uploaded") to a
+Debian-style archive.
+
+Typically, your git server will be configured to notify an
+intermediary service of the new tag that you pushed. That service
+will then fetch your tag, check your PGP signature, do any conversion
+that's needed (such as producing and signing a B<.dsc> and
+B<.changes>), and upload the result to the Debian-style archive.
+
+B<git-debpush> is only for source-only uploads.
+
+=head1 TYPICAL USAGE
+
+B<git-debpush> is designed such that for regular uploads of your
+package, you should be able to just invoke it without passing any
+command line arguments. After you've built and tested some .debs, run
+dch(1) to finalise your changelog and committed the result, just type
+"git debpush", and the intermediary service and your distribution's
+autobuilder network will take care of the rest.
+
+The most common exception to this is the first time you use
+B<git-debpush> for a non-native package. You will need to pass a
+quilt mode option to inform the intermediary service which git branch
+format you are using, for example
+
+=over 4
+
+ % git debpush --gbp
+
+=back
+
+if you are using the git branch format typically used with gbp(1).
+See "QUILT MODE OPTIONS", below, for the available quilt mode options.
+
+Aside from a few sanity checks to help avoid broken uploads,
+B<git-debpush> does not do anything with the information provided by
+the quilt mode option. It simply embeds the corresponding quilt mode
+in its generated tag, for use by the intermediary service.
+
+Future invocations of B<git-debpush> will try to read the quilt mode
+out of the tag generated by B<git-debpush> for your previous upload.
+You can override that on the command line by passing a quilt mode
+option, which always takes precedence.
+
+=head1 SETUP FOR SOURCE FORMAT 1.0
+
+B<git-debpush> needs to tell the intermediary git service whether this
+is a native or non-native package. Given historical Debian practices,
+it is not sufficient for either B<git-debpush> or the intermediary
+service to rely on the version number in debian/changelog.
+
+If you are using one of the 3.0 source package formats, B<git-debpush>
+will just look in debian/source/format to determine whether the
+package is native or non-native, and you can ignore this section of
+the manpage.
+
+If you are using the 1.0 source package format -- either
+debian/source/format does not exist, or contains the string "1.0" --
+then B<git-debpush> must be told whether the package is native or
+non-native. We do this using debian/source/options. If your package
+is non-native, execute
+
+=over 4
+
+ % echo "-sn" >>debian/source/options
+
+=back
+
+If your package is native, execute
+
+=over 4
+
+ % echo "-sk" >>debian/source/options
+
+=back
+
+(With source format 1.0, dpkg-source(1) decides whether the package is
+native or non-native based on the presence of absence of an orig.tar
+in B<..>, but B<git-debpush> is a pure git tool that never looks at
+tarballs.)
+
+=head1 QUILT MODE OPTIONS
+
+=over 4
+
+=item B<--quilt=gbp>|B<--gbp>
+
+You are using the 'unapplied' branch format, typically used with
+gbp(1).
+
+=item B<--quilt=dpm>|B<--dpm>
+
+You are using git-dpm(1)'s branch format.
+
+=item B<--quilt=baredebian[+git]>|B<--baredebian[+git]>
+
+You are using the 'bare debian' branch format, with the upstream
+source in the form of an upstream tag.
+
+=item B<--quilt=baredebian+tarball>|B<--baredebian+tarball>
+
+You are using the 'bare debian' branch format, with the upstream
+source in the form of a tarball.
+
+=item B<--quilt=linear>
+
+You are using the 'manually maintained applied' branch format or
+similar, and each commit touching the upstream source not already
+represented in debian/patches should be added as a new patch.
+
+=item B<--quilt=smash>
+
+You are using the 'manually maintained applied' branch format or
+similar, and you want all changes to the upstream source to be
+squashed into a single patch in debian/patches.
+
+=item B<--quilt=auto>
+
+Tell the intermediary service to try B<--quilt=linear>, and if that
+cannot succeed, fall back to B<--quilt=smash>.
+
+=item B<--quilt=nofix>
+
+You are using the 'manually maintained applied' branch format or
+similar, and you don't want debian/patches to be touched by the
+intermediary service.
+
+If all commits touching the upstream source are not already
+represented in debian/patches, the intermediary service will fail to
+upload your package.
+
+=back
+
+=head1 OTHER OPTIONS
+
+=over 4
+
+=item B<--no-push>|B<-n>
+
+Just tag, don't push.
+
+=item B<--force>|B<-f>
+
+Don't perform checks designed to prevent broken uploads.
+
+=item B<-u> I<keyid>
+
+Passed on to git-tag(1).
+
+=item B<--branch=>I<BRANCH>
+
+Where to place the tag, i.e., what you want to release. If
+unspecified, we put the tag on whatever HEAD points to.
+
+Note that this need not actually be a branch, but any committish (see
+gitglossary(7)). The option name is chosen to fit what is by far the
+most common case.
+
+=item B<--remote=>I<REMOTE>
+
+Where to push tags and branches. If unspecified, use the remote which
+git would use if you typed "git push BRANCH".
+
+=item B<--distro=>I<DISTRO>
+
+What distribution name to embed in the signed tag. Defaults to
+"debian".
+
+=back
+
+=head1 SEE ALSO
+
+Git branch formats in use by Debian maintainers:
+<https://wiki.debian.org/GitPackagingSurvey>
+
+=head1 AUTHOR
+
+B<git-debpush> was written by Sean Whitton <spwhitton@spwhitton.name>
+with much input from Ian Jackson <ijackson@chiark.greenend.org.uk>.