From eca709b776801cbd57eed32dab8b59fe8bc9a569 Mon Sep 17 00:00:00 2001
From: Sean Whitton <spwhitton@spwhitton.name>
Date: Sat, 6 Jul 2019 16:01:45 +0100
Subject: git-debpush(1): new manpage

Signed-off-by: Sean Whitton <spwhitton@spwhitton.name>
---
 git-debpush.1.pod | 191 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 191 insertions(+)
 create mode 100644 git-debpush.1.pod

(limited to 'git-debpush.1.pod')

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>.
-- 
cgit v1.2.3