=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:

=over 4

    % git debpush

=back

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.

=head2 Mistakes

If you use B<git-debpush> to make a tag but haven't pushed it yet, either
because you used B<--tag-only>|B<-t> or because the push failed, it is okay to
delete it and make another.  (In the case that the push failed you can just
run B<git-debpush> again I<without> deleting the tag, and it will retry just
the push.)

However, if a tag made by this script has been pushed, then B<do not>

=over 4

=item * delete the tag, locally or remotely;

=item * rewind (force push) the branch the tag is on; or

=item * remove any entries from debian/changelog.

=back

The intermediary service won't let you reuse the version number anyway, and
taking any of these actions may make it unnecessarily difficult to try another
upload.  Instead, add a new changelog stanza and run B<git-debpush> again.

=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 "-sk" >>debian/source/options

=back

If your package is native, execute

=over 4

    % echo "-sn" >>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 patches-unapplied branch format, as typically used with
gbp(1) or quilt(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.

B<--quilt=baredebian+git> is an alias for B<--quilt=baredebian>.

=item B<--quilt=linear>

You are using C<git-debrebase> or semi-manually maintaining a
patches-applied branch.

The intermediary service will add a new patch for each commit touching the
upstream source that is not already represented in debian/patches.

=item B<--quilt=single>

You are editing the upstream source code directly and do not care about
maintaining a broken-down series of patches.

All changes to the upstream source will be squashed into a single patch
in debian/patches, replacing any existing patches.

Prefer this to the C<single-debian-patch> dpkg-source option.
(See B<--quilt=single> in L<dgit(1)> for an explaination.)

=item B<--quilt=smash> | B<--quilt=try-linear> | B<--quilt=unapplied> | B<--quilt=nofix>

Identical to the corresponding B<dgit> options.
Please refer to L<dgit(1)>.
Most B<git-debpush> users won't want these modes.

=back

=head1 OTHER OPTIONS

=over 4

=item B<--dry-run>|B<-n>

Run checks and generate the tag text, but don't sign or create the tag, or
push.

=item B<--tag-only>|B<-t>

Just tag, don't push.  A noop if passed together with B<--dry-run>|B<-n>.

=item B<--print-tag-text>

Also print the (unsigned) tag text to standard output.

Useful together with B<--dry-run>|B<-n>, for scripting.

=item B<--help>|B<-h>

Print brief usage summary and exit.

=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<--upstream=>I<TAG>

When pushing a non-native package,
B<git-debpush> needs a tag for the upstream part of your package.

By default B<git-debpush> asks git-deborig(1),
which searches for a suitable tag
based on the upstream version in debian/changelog.

=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".

=item B<--force>|B<-f>

Ignore the results of all checks designed to prevent broken uploads.

Note that this does not imply doing a git force push: B<git-debpush> never
passes B<-f> through to B<git push>.  If you need that, use B<git debpush -t>
and then do your own git force push.

=item B<--force>=I<check>[,I<check>] ...

Override individual checks designed to prevent broken uploads.  May be
specified more than once.

Using B<--force> or B<--force=>I<check> might cause the upload to fail
at some later point in the process.

The valid values for I<check> are described next.  The checks fall into two
groups: those checks for which B<git-debpush> in interactive use will offer to
ignore failures of the check (with a y/n prompt), and those checks whose
failure always causes B<git-debpush> to exit, unless forced.

Failures of these checks can be ignored during interactive use:

=over 4

=item B<uncommitted>

Ignore that there are uncommitted changes to tracked files.

=item B<untracked>

Ignore that there are untracked files.  (For the bare debian branch format,
untracked files outside of debian/ are always ignored.)

=item B<superfluous-quilt-mode>

Ignore the fact that the quilt mode option supplied on the command line is the
same as the one we would have autodetected.

If a package has been uploaded with B<git-debpush> before, you don't need to
pass B<--gbp>|B<--dpm>|B<--quilt=>I<mode>, except in the unusual case that you
are changing your git workflow.

It's better not to get into the habit of specifying the quilt mode, since that
could override B<git-debpush>'s determination, and thereby end up applying the
wrong quilt mode to a different package.

=item B<upstream-nonancestor>

Ignore the fact that the upstream tag is not an ancestor of the branch
to be tagged (skipping this check is implied by B<--quilt=baredebian>).

=item B<unreleased>

Permit upload to a suite called UNRELEASED.

=item B<dgit-view>

Ignore apparently pushing the dgit view of a package (as produced by
B<dgit clone>) to the maintainer branch, where the dgit view and the
maintainer view of the package are not identical.

=item B<pristine-tar>

Ignore that pristine tar data for this new upstream version has been
committed to the pristine-tar branch, despite the fact that the
intermediary service will always ignore this data.  (It will generate
its own orig tarball with git-archive(1).  See Debian bug #1106071.)

=item B<unstitched>

Ignore the fact that the branch to be pushed seems to be a
git-debrebase(1) branch in an unstitched state (see git-debrebase(5)).

=item B<detached>

Ignore the fact that HEAD is to be tagged, but HEAD is detached (this
check is only run when B<--branch=HEAD> or no B<--branch> option is
specified).

=item B<branch-behind>

Ignore that the local branch is behind its upstream, such that only the tag,
and not the commit to which it points, can be pushed.

=item B<branch-diverged>

Ignore that the local branch and its upstream have diverged, such that only
the tag, and not the commit to which it points, can be pushed.

=item B<repo-inaccessible>

Ignore that the repository to which the tag will be pushed does not seem to be
publically accessible.

=item B<remake-tag>

Ignore that a tag of the same name that B<git-debpush> proposes to make
already exists, with different content.  Overriding this check implies passing
B<-f> to git-tag(1).

=back

Failures of these checks are always fatal, unless forced:

=over 4

=item B<upstream-nonidentical>

Ignore any differences between the upstream source in the upstream tag
and the upstream source in the branch to be tagged (this check is only
run when using B<--quilt=gbp> or B<--quilt=unapplied>).

=item B<patches-nonapplicable>

Ignore any failures of the following two checks:

=over 4

=item

With B<--quilt=gbp>, B<--quilt=unapplied>, B<--quilt=baredebian>,
B<--quilt=dpm>, and B<--quilt=nofix>, the quilt patches should apply
cleanly to the upstream source with git-apply(1).

=item

With B<--quilt=dpm> and B<--quilt=nofix>, applying the quilt patches
to the upstream source should produce exactly the source tree to be
tagged.

=back

=item B<submodule>

Ignore that there are git submodule(s).  Submodules are not supported.

=item B<local-options>

Ignore that the file debian/source/local-options exists.
This file is not supported (but note you can use debian/source/options).

=back

=item B<--batch>

When used interactively, and a test fails, B<git-debpush> will sometimes offer
to ignore the failure, depending on the likelihood that ignoring the failure
will result in a broken upload.  Passing this option disables this interactive
prompting.

=back

=head1 SEE ALSO

L<https://wiki.debian.org/tag2upload>, L<tag2upload(5)>

Git branch formats in use by Debian maintainers:
L<https://wiki.debian.org/GitPackagingSurvey>

=head1 AUTHOR

B<git-debpush> and this manpage were written by Sean Whitton
<spwhitton@spwhitton.name> with much input from Ian Jackson
<ijackson@chiark.greenend.org.uk>.