git-debpush(1)

📦
version 17.0 · 7 versions
, in ubuntu stonking

🎀 NAME 🎀

git-debpush — bestie, this is the one that makes a git tag with metadata for an ftp-master upload 💖

(also: the manual is literally called git-debpush, we been knew 👑)

✨ SYNOPSIS ✨

git debpush [option...]

🦋 DESCRIPTION 🦋

okay so. git-debpush is a lil wrapper around git-tag(1) and git-push(1). That's it, that's the vibe. It helps you create and push a very specially formatted, signed tag — and that tag is basically screaming "hey, this commit right here should get pushed (or, like, uploaded) to a Debian-style archive" 💅

Typically, your git server is set up to ping some intermediary service the second you push that new tag. Then that service goes and fetches your tag, checks your PGP signature, does whatever conversion is needed (think: producing and signing a .dsc and .changes), and uploads the result to the Debian-style archive. Iconic behaviour, no notes ✨

⚠️ git-debpush is only for source-only uploads. That's the whole lane, babe.

🌸 TYPICAL USAGE 🌸

Here's the tea 🍓: git-debpush was designed so that for your regular, everyday uploads of a package, you literally just run it with no command line arguments at all. Obsessed with the lack of effort tbh.

So the flow is: you build and test some .debs, you run dch(1) to finalise your changelog, you commit that result, and then you just type git debpush — and the intermediary service plus your distribution's autobuilder network handle every single thing after that. Main character delegation energy 💅

% git debpush

Now. The most common exception to this whole "no args needed" fantasy is the first time you use git-debpush for a non-native package. For that one you will need to pass a quilt mode option, so the intermediary service knows which git branch format you're working with. Like, for example:

% git debpush --gbp

if you're using the git branch format that's typically used with gbp(1). The available quilt mode options live down in "QUILT MODE OPTIONS" below, go peek 👀

Aside from a few sanity checks to help you avoid broken uploads, git-debpush does not do anything with the information the quilt mode option gives it. It just embeds the corresponding quilt mode in the tag it generates, for the intermediary service to read. That's it. Lowkey a delivery service 🦋

Future invocations of git-debpush will try to read the quilt mode out of the tag that git-debpush generated for your previous upload. Cute. But you can always override that on the command line by passing a quilt mode option — and the command line always takes precedence. Periodt.

💀 Mistakes 💀

If you used git-debpush to make a tag but you haven't pushed it yet — either because you passed --tag-only/-t, or because the push straight-up failed — then it's totally fine, you can delete it and make another one, no stress 🫶 (and if the push is what failed, you can literally just run git-debpush again without deleting the tag, and it'll retry just the push. Slay.)

BUT. 🚨 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, so it's not even giving you anything, and taking any of these actions may make it unnecessarily difficult to try another upload. Not the vibe. Instead: add a new changelog stanza and run git-debpush again. That's the move 💖

👑 BEHAVIOUR 👑

Short version, iykyk: git-debpush just makes a git tag, and pushes. Then the tag2upload service makes and uploads a source package. Done and dusted ✨

Long version, because you deserve the full lore: after reading command line options and configuration, git-debpush:

  • Checks that your remote is accessible by unauthenticated https. (Private repos don't work, because the tag2upload service can't fetch your intended upload. Sorry bb 💔)
  • Fetches, from your remote, the remote branch corresponding to HEAD, any pristine-tar branch, and any missing debian/ tags.
  • Determines the quilt mode, based on the previous upload tags and command line options.
  • Determines the upstream tag (using the same approach as git-deborig), and determines whether the local pristine-tar branch has data for this upload.
  • Prepares and signs a git tag containing the upload instructions.
  • Pushes the git tag, and any updates to the current branch. Also pushes the upstream tag, the upstream branch (if the upstream tag is upstream/), and the pristine-tar branch, as applicable.

git-debpush makes many other (local) checks for anomalies; these can generally be overridden (interactively, or with --force). And the tag2upload service does even more thorough checks: for example, that an NMU is not being accidentally overwritten, and that the source package corresponds precisely to your tagged commit. She's thorough, she's meticulous, she's that girl 💅

🌈 SETUP FOR SOURCE FORMAT 1.0 🌈

okay so git-debpush needs to tell the intermediary git service whether this is a native or non-native package. And because of historical Debian practices (the lore is long, don't ask), it is not sufficient for either git-debpush or the intermediary service to just rely on the version number in debian/changelog. Nope. Not today 🙈

If you're using one of the 3.0 source package formats, then git-debpush will just look in debian/source/format to figure out whether the package is native or non-native — and you can ignore this entire section of the manpage, bestie. Go live your life 🦋

If you're using the 1.0 source package format — meaning either debian/source/format does not exist, or it contains the string "1.0" — then git-debpush must be told whether the package is native or non-native. We do that using debian/source/options 💖

If your package is non-native, run:

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

If your package is native, run:

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

(And just so you know: with source format 1.0, dpkg-source(1) decides whether the package is native or non-native based on the presence or absence of an orig.tar in .. — but git-debpush is a pure git tool that never looks at tarballs. She doesn't do tarballs, she does tags 💅)

💅 QUILT MODE OPTIONS 💅

  • --quilt=gbp / --gbp — You're using the patches-unapplied branch format, as typically used with gbp(1) or quilt(1).
  • --quilt=dpm / --dpm — You're using git-dpm(1)'s branch format.
  • --quilt=baredebian[+git] / --baredebian[+git] — You're 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. Same thing, different outfit ✨
  • --quilt=linear — You're 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 isn't already represented in debian/patches.
  • --quilt=single — You're editing the upstream source code directly and you do not care about maintaining a broken-down series of patches. Valid.
    • 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 the explanation 🍓)
  • --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, ngl.

💅 OTHER OPTIONS 💅

okay bestie welcome back, we're still in the options section, and these are the rest of the knobs you can turn. strap in, there's a LOT.

  • --dry-run|-n — runs all the checks and generates the tag text, but it does not sign or create the tag, and it does not push. literally just a lil dress rehearsal 🎭
  • --tag-only|-t — just make the tag, don't push it. if you also pass --dry-run|-n this is a noop, like it does nothing, they cancel each other out 🫠
  • --print-tag-text — also prints the (unsigned) tag text to standard output. super useful together with --dry-run|-n if you're doing scripting, iykyk 🖨️
  • --help|-h — prints a brief usage summary and dips out. classic.
  • -u keyid — this gets passed straight on to git-tag(1). not our business, we just hand it over 💌
  • --branch=BRANCH — this is where the tag goes, i.e. what you actually want to release. if you don't specify it, the tag lands on whatever HEAD points to.
lowkey important: this doesn't have to be a real branch! it can be any committish (peep gitglossary(7)). the option is just named branch because that's the 99% case fr fr.
  • --upstream=TAG — when you're pushing a non-native package, git-debpush needs a tag for the upstream part of your package. by default it asks git-deborig(1), which goes hunting for a suitable tag based on the upstream version in debian/changelog. so cozy 🧚
  • --remote=REMOTE — where do we push tags and branches to? if you don't say, we use whatever remote git would use if you typed git push BRANCH.
  • --distro=DISTRO — what distribution name gets embedded in the signed tag. defaults to "debian". simple as that ✨
  • --untaint-history — a convenience alias for --deliberately-include-questionable-history. see below, and go read TAINTED HISTORY in dgit(7). it's giving lore.
  • --deliberately-DELIB — requests certain overrides of checks that are implemented in the server-side processing. from git-debpush(1)'s point of view, this is pure metadata, embedded directly in the tag. but when the server finds them in there, it may change aspects of its behaviour 👀. the following overrides are currently meaningful in Debian:
    • --deliberately-include-questionable-history
    • --deliberately-not-fast-forward

check TAINTED HISTORY in dgit(7) for the details of when to use those. for other upload targets, dgit(1) has details of all known deliberatelies — but heads up, an upload server might define its own. 🤷‍♀️

no cap: unlike --force, your use of one of these options is permanently recorded in the signed tag. it lives there forever, bestie. choose wisely 💀
  • --force|-f — ignore the results of all checks designed to prevent broken uploads. yes, all of them. yolo mode.
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. one thing at a time 🫶
  • --force=check[,check] ... — override individual checks designed to prevent broken uploads. can be specified more than once.
using --force or --force=check might cause the upload to fail at some later point in the process. foreshadowing 🎀

the valid values for check are described next. the checks come in two groups: ones where git-debpush in interactive use will offer to ignore the failure (with a y/n prompt), and ones whose failure always makes git-debpush exit, unless forced.

failures of these checks can be ignored during interactive use:

  • 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.)
  • changed-quilt-mode — ignore the fact that the quilt mode option supplied on the command line is different to the one we would have autodetected. overriding this is appropriate if the package's git workflow practices have changed since the last upload.
  • 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).
  • 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.
  • 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).
  • branch-behind — ignore that the local branch is behind its upstream, risking uploading out-of-date source code. if you override this then only the tag, and not the commit to which it points, can be pushed.
  • 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. this risks uploading out-of-date source code, now or in the future.
  • debian-upstream-diverged — ignore that the local Debian upstream tracking/import branch "upstream" has diverged from the "upstream" branch on the remote. this prevents us pushing the "upstream" branch, but we'll still push the upstream tag. proceeding risks uploading work based on out-of-date upstream source code, now or in the future.
  • pristine-tar-behind — ignore that the local pristine-tar branch is behind upstream (or absent). this risks the use of stale pristine-tar data and therefore possible generation of unintended orig tarballs.
  • pristine-tar-diverged — ignore that the local pristine-tar branch and its upstream have diverged. this prevents us pushing the pristine-tar branch, and risks unexpected orig tarballs being generated now, or in the future.
  • repo-inaccessible — ignore that the repository to which the tag will be pushed does not seem to be publically accessible.
  • remake-tag — ignore that a tag of the same name that git-debpush proposes to make already exists, with different content. overriding this check implies passing -f to git-tag(1).
  • unknown-delibrately — ignore that a --deliberately-* option was supplied that this version of git-debpush doesn't know about. this might be correct, for example if you're running an old version of git-debpush, or uploading elsewhere than to Debian. but otherwise it's likely to be a typo. note that unknown (or inapplicable) --deliberately-* options will be silently ignored by the server.

failures of these checks are always fatal, unless forced:

  • 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.
  • 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). 💡
  • --batch — when used interactively, and a test fails, 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 that interactive prompting. so no more y/n pop-ups, it just decides for you 😌
  • --extra-metadata=<KEY[=VALUE]> — adds an extra metadata item to the tag. KEY[=VALUE] gets inserted in one of the output [dgit ...] lines. this option can be repeated as needed.
you have full manual control. syntax and semantics are completely unchecked. this might be useful, for example, if you're running an old version of git-debpush, or uploading elsewhere than to Debian. free rein, bestie 🦋
  • --no-pristine-tar — prevent detection and use of pristine-tar data. if new origs need to be generated, they'll be made with "git-deborig". 🍓

📁 FILES 📁

  • git configuration — git-debpush is influenced by git configuration options, notably "remote.pushDefault", "branch.BRANCH.pushDefault", "branch.BRANCH.pushRemote", and "remote.REMOTE.url".
  • ".git/git-debpush" — used for temporary working areas. will normally be cleaned up after a successful run, so tidy ✨

👀 SEE ALSO 👀

👑 AUTHOR 👑

the original author of git-debpush and this manpage is Sean Whitton <spwhitton@spwhitton.name>, with much input from Ian Jackson <ijackson@chiark.greenend.org.uk>. absolute icons, we stan 💜

okay so that's the whole page, bestie!! this one comes to you from the Debian Project — the dgit+tag2upload team to be specific — and yeah it's git-debpush(1). go tag something, you've got this 🎀✨💅

📦 where this page comes from