dgit-nmu-simple(7)

📦
version 17.0 · 9 versions
, in ubuntu stonking

💖 dgit-nmu-simple 💖

okay bestie, so like, imagine you're a Debian Developer and you wanna do a cute little NMU. that's this. this is the dgit-nmu-simple page from the dgit manual, and it's literally a whole tutorial for DDs who wanna NMU with git. pull up a chair, grab a boba, we're doing this 🧋✨

🌸 INTRODUCTION AND SCOPE 🌸

so here's the vibe: this tutorial walks a Debian Developer through doing a straightforward NMU of a package in Debian, working only in git. no side quests, no detours, just git 💅

real talk though — this doc is not gonna help you decide whether an NMU is even a good idea, or whether it'll be well received. that's a whole other conversation. the Debian Developers' Reference has some guidance on it (and honestly, sometimes that guidance is... questionable 🙈) but that's on them, not on this page.

the other direction works too: you do not need to know anything about the usual maintainer's git workflow. if it's appropriate, you can bounce between many different packages making similar changes, and never once worry about the individual maintainers' git practices. main character energy, honestly 👑

also scope check: this tutorial only covers changes that can sensibly be expressed as a reasonably small number of linear commits — whether that's to Debian packaging, or to upstream files, or both. that's the lane, we stay in it 🛣️

if you wanna do a new upstream version, that's a different beast. you probably wanna do it the way the maintainer would have done it, which means you gotta figure out what the maintainer's git practices actually are, and then go consult the appropriate dgit-maint-*(7) workflow tutorial. iykyk 🤝

🎀 SUMMARY 🎀

here's the whole recipe, chef's kiss, no notes:

% dgit clone glibc bookworm
% cd glibc
% git am ~/glibc-security-fix.diff
% dch --nmu "Apply upstream's fix for foo bug."
% git add debian/changelog && git commit -m"NMU changelog entry"
% dpkg-buildpackage -uc -b
[ run your tests ]
% dch -r && git add debian/changelog && git commit -m"Finalise NMU"
% dgit -wgf sbuild -A -d trixie
[ any final tests on generated .debs ]
% dgit -wgf [--delayed=5] push-source bookworm
[ enter your gnupg passphrase as prompted ]
[ see that push and upload are successful ]
[ prepare and email NMU diff (git-diff, git-format-patch) ]

slay. that's the whole thing. the rest of this page is just us explaining why each of those steps is the way it is 🫶

✨ WHAT KIND OF CHANGES AND COMMITS TO MAKE ✨

when you're preparing an NMU, the git commits you make on the dgit branch should be a simple linear series of commits with good commit messages. this is not the time for chaos. this is the time for elegance 💅

and why do the commit messages matter so much? because they get published in various ways — including possibly being used as the cover messages for generated quilt patches. so like, write them for an audience, bestie, because they WILL have one 📢

some hard rules, no cap:

  • Do not make merge commits. just don't.
  • Do not try to rebase to drop existing patches. if you need to revert a change which is actually a Debian patch, use git-revert. that's the move.
  • If you need to modify a Debian patch, make a new commit which fixes what needs fixing, and then explain in the commit message which patch it should be squashed with. (a cute way to do this is a commit message in git rebase --autosquash -i format. chef's kiss 🤌)
and obviously, if you have specific instructions from the maintainer, follow those instead. but for the record: the procedure in this tutorial is legit for any maintainer, in the sense that it should generate an upload that the maintainer cannot reasonably object to. so you're safe either way 🌈

🦋 PREPARING AND REVISING THE LOCAL BRANCH 🦋

here's the tea: the dgit/sid branch is a normal local git branch tracking a (synthetic) upstream branch. so you can freely rewrite any commits you've made locally and haven't pushed anywhere, just like normal. go off ✨

the one thing that's weird is the "quilt fixup" commits (those turn up if you do eg dgit sbuild). if you're rebasing them at all, you can and should just drop them — dgit will then regenerate them as needed. bye girl, you won't be missed 👋

all of this follows from one underlying fact:

dgit doesn't have invisible git state somewhere. so if you rebase away the quilt fixup, and rework your branch, your branch is still good — because it looks just like it would do, if you'd just made those commits straight off. (NB git-debrebase does have weird off-branch state. not us though 💀)

💜 RELEVANT BRANCHES 💜

dgit clone will put you on a branch like dgit/sid. there's also a pseudo-remote called dgit which contains a branch like dgit/sid as well.

so you do things like:

git diff dgit/dgit/sid

to see what changes you've made 👀 yes the double dgit/dgit is real, it's not a typo, it's just like that.

🌸 KEEPING YOUR WORKING TREE TIDY 🌸

don't forget to git add any new files you create!! if you don't, git clean — which is requested with the -wgf option in the recipe above — will delete them. gone. poof. 😭

also, many package builds leave dirty git trees. so: commit before building. that way you can just use git reset --hard. problem solved, mind clear 🧘

if you follow this approach you don't need to care about the build dirtying the tree. and bonus: it also means you don't care about the package clean target — which is just as well, because many package clean targets are broken. 🙈 not our problem, bestie.

⭐ OTHER GIT BRANCHES ⭐

the dgit git history (visible in gitk and git log) is not necessarily related to the maintainer's or upstream's git history (if any). different universes, same repo 🌌

but if the maintainer has advertised a git repo with Vcs-Git, dgit will set up a remote for it, so you can do:

% git fetch vcs-git

and then you can cherry pick changes from there, for example 🍒

heads up though: the maintainer's git history may not be suitable for use with dgit. for example, it might be a patches-unapplied branch, or it might even contain only a debian/ directory. vibe check before you commit to anything 💀

👑 UPLOADING TO DELAYED 👑

you can use dgit's --delayed option to upload to the DELAYED queue. very convenient, very iconic.

however, you should read the warning about this option in dgit(1). fr fr, go read it. don't skip it 🙏

💀 WHAT ABOUT GIT-DEBPUSH/TAG2UPLOAD? 💀

uploading with git-debpush is not usually a good fit for NMUs, because an NMUer usually does not want to, or cannot, push to the maintainer's git repository on salsa.debian.org. like, logistically, it's giving "not it" 💅

🌈 SEE ALSO 🌈

and that's the whole page bestie!! 🎀 this was dgit-nmu-simple(7) from the dgit manual, brought to you by the Debian Project and the dgit+tag2upload team (they ate, honestly 👑✨). now go forth and NMU responsibly, and remember: commit before building, drop the quilt fixups, and always read the warnings. mwah 💖🦋🌸

📦 where this page comes from