From: Sean Whitton <spwhitton@spwhitton.name>
Date: Sat, 6 Jul 2019 15:01:45 +0000 (+0100)
Subject: git-debpush(1): new manpage
X-Git-Tag: archive/debian/9.1~61
X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=dgit.git;a=commitdiff_plain;h=eca709b776801cbd57eed32dab8b59fe8bc9a569

git-debpush(1): new manpage

Signed-off-by: Sean Whitton <spwhitton@spwhitton.name>
---

diff --git a/.gitignore b/.gitignore
index b8b1af6b..653c53e3 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 7d0c422f..890e371f 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 00000000..926e8cd3
--- /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>.