Ubuntu Manpage: git-debpush - create & push a git tag with metadata for an ftp-master upload

NAME

       git-debpush - create & push a git tag with metadata for an ftp-master upload

SYNOPSIS

       git debpush [option...]

DESCRIPTION

       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 .dsc and .changes), and upload the result to the Debian-style archive.

       git-debpush is only for source-only uploads.

TYPICAL USAGE

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

% git debpush --gbp

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, 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 git-debpush will try to read the quilt mode out of the tag generated by git-debpush
for your previous upload. You can override that on the command line by passing a quilt mode option,
which always takes precedence.

Mistakes
If you use git-debpush to make a tag but haven't pushed it yet, either because you used --tag-only|-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 git-debpush again without deleting the tag, and it will retry just the push.)

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

• delete the tag, locally or remotely;

• rewind (force push) the branch the tag is on; or

• remove any entries from debian/changelog.

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
git-debpush again.

SETUP FOR SOURCE FORMAT 1.0

       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  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,  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 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

           % echo "-sk" >>debian/source/options

       If your package is native, execute

           % echo "-sn" >>debian/source/options

       (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  ..,  but  git-debpush is a pure git tool that never looks at
       tarballs.)

QUILT MODE OPTIONS

       --quilt=gbp|--gbp
           You are using the patches-unapplied branch format, as typically used with gbp(1) or quilt(1).

       --quilt=dpm|--dpm
           You are using git-dpm(1)'s branch format.

       --quilt=baredebian[+git]|--baredebian[+git]
           You are using the 'bare debian' branch format, with the upstream source in the form  of  an  upstream
           tag.

           --quilt=baredebian+git is an alias for --quilt=baredebian.

       --quilt=linear
           You are using "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.

       --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 "single-debian-patch" dpkg-source option.  (See --quilt=single in dgit(1)  for  an
           explaination.)

       --quilt=smash | --quilt=try-linear | --quilt=unapplied | --quilt=nofix
           Identical  to the corresponding dgit options.  Please refer to dgit(1).  Most git-debpush users won't
           want these modes.

OTHER OPTIONS

--dry-run|-n
Run checks and generate the tag text, but don't sign or create the tag, or push.

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

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

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

--help|-h
Print brief usage summary and exit.

-u keyid
Passed on to git-tag(1).

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

--upstream=TAG
When pushing a non-native package, git-debpush needs a tag for the upstream part of your package.

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

--remote=REMOTE
Where to push tags and branches. If unspecified, use the remote which git would use if you typed
"git push BRANCH".

--distro=DISTRO
What distribution name to embed in the signed tag. Defaults to "debian".

--force|-f
Ignore the results of all checks designed to prevent broken uploads.

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

--force=check[,check] ...
Override individual checks designed to prevent broken uploads. May be specified more than once.

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

Valid values for check are:

uncommitted
Ignore that there are uncommitted changes to tracked files.

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

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 git-debpush before, you don't need to pass
--gbp|--dpm|--quilt=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
git-debpush's determination, and thereby end up applying the wrong quilt mode to a different
package.

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 --quilt=baredebian).

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 --quilt=gbp or --quilt=unapplied).

patches-nonapplicable
Ignore any failures of the following two checks:

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

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

unreleased
Permit upload to a suite called UNRELEASED.

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

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.)

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

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

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)).

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

--batch
When used interactively, and a test fails, git-debpush will offer to ignore the failure. Passing
this option disables this interactive prompting.

AUTHOR

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

Debian Project                                dgit+tag2upload team                                git-debpush(1)