diff options
author | Sean Whitton <spwhitton@spwhitton.name> | 2019-07-06 16:01:45 +0100 |
---|---|---|
committer | Sean Whitton <spwhitton@spwhitton.name> | 2019-07-07 09:54:19 +0100 |
commit | eca709b776801cbd57eed32dab8b59fe8bc9a569 (patch) | |
tree | 9bf288fd1536c7465a5ae75b4edf005aad720274 | |
parent | f8fe5f19d1ec104f8735dd0d8813ae5e5317f536 (diff) |
git-debpush(1): new manpage
Signed-off-by: Sean Whitton <spwhitton@spwhitton.name>
-rw-r--r-- | .gitignore | 1 | ||||
-rw-r--r-- | Makefile | 5 | ||||
-rw-r--r-- | git-debpush.1.pod | 191 |
3 files changed, 197 insertions, 0 deletions
@@ -19,5 +19,6 @@ dgit-sponsorship.7 dgit-downstream-dsc.7 git-debrebase.1 git-debrebase.5 +git-debpush.1 substituted .po4a.translated-only @@ -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>. |