GIT-DPM(1)

📦 version 0.10.0, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble, ubuntu resolute, ubuntu stonking

🌸 GIT-DPM(1) 🌸

okay bestie, this is the manual page for git-dpm, aka the Debian packages in git manager, and we are going through every single detail together. no skipping, no skimming, periodt. 💅

💖 NAME 💖

git-dpm — Debian packages in git manager

✨ SYNOPSIS ✨

git-dpm --help
git-dpm [ options ] command [ per-command-options and -arguments ]

🦋 DESCRIPTION 🦋

Git-dpm is a tool to handle a Debian source package in a git repository. fr fr, it's giving "I manage your branches so you don't have to."

Each project contains three branches: a Debian branch (master/whatever), a patched branch (patched/patched-whatever) and an upstream branch (upstream/upstream-whatever). And git-dpm helps you store the information in there so you have your changes exportable as a quilt series. slay.

Git-dpm will guess the other two branches based on the branch it sees. (Most commands act based on the current HEAD, i.e. what branch you have currently checked out, though some — as e.g. status — allows an optional argument instead). So for example, if you are in branch master, git-dpm assumes the corresponding upstream branch is called upstream. If you are in branch upstream-something, it assumes the Debian branch is called something.

Note that most commands may switch to another branch automatically, partly because it is easier to implement that way and hopefully so one does not need to switch branches manually so often. iconic behaviour honestly.

🌈 SHORT EXPLANATION OF THE BRANCHES 🌈

the upstream branch (upstream|upstream-whatever)

This branch contains the upstream sources. Its contents need to be equal enough to the contents in your upstream tarball. like, close enough that nobody clocks it bestie.

the patched branch (patched|patched-whatever)

This branch contains your patches to the upstream source. Every commit will be stored as a single patch in the resulting package.

Most of the time it will not exist as a branch known to git, but only as some point in the history of the Debian branch and possibly as tag for published versions. Git-dpm will create it when needed and remove the branch when no longer needed.

To help git generate a linear patch series, this should ideal be a linear chain of commits, whose description are helpful for other people.

As this branch is regularly rebased, you should not publish it. 💀

the Debian branch (master|whatever)

This is the primary branch. main character energy.

This branch contains the debian/ directory and has the patched branch merged in.

Every change not in debian/, .git* or deleting files must be done in the patched branch. no cap.

🎀 EXAMPLES 🎀

Let's start with some examples:

Checking out a project

First get the master branch:

git clone URL

Then create upstream branch and see if the .orig.tar is ready:

git-dpm prepare

Create the patched branch and check it out:

git-dpm checkout-patched

Do some changes, apply some patches, commit them..

...
git commit

If your modification fixes a previous change (and that is not the last commit, otherwise you could have used --amend), you might want to squash those two commits into one, so use:

git rebase -i upstream

Then you want to get those changes into the Debian branch and the new patch files created (which you can do using git-dpm update-patches), but you most likely want to also document what you did in the changelog, so all in one step:

git-dpm dch -- -i

Perhaps change something in the Debian packaging:

...
git commit -a

Then push the whole thing back:

git push

Switching to a new upstream version

Get a new .orig.tar file. Either upgrade your upstream branch to the contents of that file and call git-dpm record-new-upstream ../new-stuff.orig.tar.gz or tell git-dpm to import and record it:

git-dpm import-new-upstream --rebase ../new-stuff.orig.tar.gz

This will rebase the patched branch to the new upstream branch, perhaps you will need to resolve some conflicts:

vim ...
git add resolved files
git rebase --continue

After rebase is run (with some luck even in the first try):

git-dpm dch -- -v newupstream-1 "new upstream version"

You could have also done the last step in three by:

git-dpm update-patches
dch -- -v newupstream-1 "new upstream version"
git commit --amend -a

Do other debian/ changes:

...
git commit -a

Then push the whole thing back:

git push

Creating a new project

Create an upstream (or upstream-whatever) branch containing the contents of your orig.tar file:

tar -xvf example_0.orig.tar.gz
cd example-0
git init
git add .
git commit -m "import example_0.orig.tar.gz"
git checkout -b upstream-unstable

You might want to use pristine tar to store your tar:

pristine-tar commit ../example_0.orig.tar.gz upstream-unstable

Then let git-dpm know what tarball your upstream branch belongs to:

git-dpm init ../example_0.orig.tar.gz

Note that since you were in upstream-unstable in this example, in the last example git-dpm assumed you want your Debian branch called unstable and not master, so after the command returned you are in the newly created unstable branch. the way it just knows 💅

Do the rest of the packaging:

vim debian/control debian/rules
dch --create --package example -v 0-1
git add debian/control debian/rules debian/changelog
git commit -m "initial packaging"

Then add some patches:

git-dpm checkout-patched
vim ...
git commit -a
git-dpm dch "fix ... (Closes: num)"

The git-dpm checkout-patched created a temporary branch patched-unstable (as you were in a branch called unstable. If you had called it with HEAD being a branch master, it would have been patched) to which you added commits. Then the git-dpm update-patches implied by git-dpm dch merged those changes into unstable, deleted the temporary branch and created new debian/patches/ files.

Then build your package:

git-dpm status &&
 dpkg-buildpackage -rfakeroot -us -uc -I".git*"

Now take a look what happened, perhaps you want to add some files to .gitignore (in the unstable branch), or remove some files from the unstable branch because your clean rule removes them.

Continue the last few steps until the package is finished. Then push your package:

git-dpm tag
git push --tags target unstable:unstable
pristine-tar:pristine-tar

Removing existing patches

First get the master branch:

git clone URL

Create the patched branch and check it out:

git-dpm checkout-patched

Get a list of commits since the last upstream release: git rebase -i upstream-unstable

This will open your default editor with a list of commits. Edit the list to remove undesired commits.

...
git commit

Then you want to get those changes into the Debian branch and the old patch files deleted (which you can do using git-dpm update-patches), but you most likely want to also document what you did in the changelog, so all in one step:

git-dpm dch -- -i

Perhaps change something in the Debian packaging:

...
git commit -a

Then push the whole thing back:

git push

💅 GLOBAL OPTIONS 💅

  • --debug — Give verbose output what git-dpm is doing. Mostly only useful for debugging or when preparing an bug report. iykyk.
  • --debug-git-calls — Output git invocations to stderr. (For more complicated debugging cases).
  • --allow-changes-in-debian-branch — Ignore upstream changes in your Debian branch. This will either discard them if merge-patched is called by come command or them being ignored elsewhere. careful bestie, that's a choice.

👑 COMMANDS 👑

init [options] tarfile [upstream-commit [preapplied-commit [patched-commit]]]

Create a new project. fresh start era ✨

The first argument is an upstream tarball.

You also need to have the contents of that file and the files given with --component unpackaged as some branch or commit in your git repository (or similar enough so dpkg-source will not know the difference). This will be stored in the upstream branch (called upstream or upstream-whatever). If the second argument is non-existing or empty, that branch must already exist, otherwise that branch will be initialized with what that second argument. (It's your responsibility that the contents match. git-dpm does not know what your clean rule does, so cannot check (and does not even try to warn yet)).

You can already have an Debian branch (called master or whatever). If it does not exist, it will exist afterwards. Otherwise it can contain a debian/patches/series file, which git-dpm will import.

The third argument can be a descendant of your upstream branch, that contains the changes of your Debian branch before any patches are applied (Most people prefer to have none and lintian warns, but if you have some, commit/cherry pick them in a new branch/detached head on top of your upstream branch and name them here). Without --patches-applied, your Debian branch may not have any upstream changes compared to this commit (or if it is not given, the upstream branch).

If there is no fourth argument, git-dpm will apply possible patches in your Debian branch on top of the third argument or upstream. You can also do so yourself and give that as fourth argument.

The contents of this commit/branch given in the fourth commit or created by applying patches on top of the third/your upstream branch is then merged into your Debian branch and remembered as patched branch.

Options:

  • --component filename — Record a .orig-component.tar file to be unpacked in your upstream branch.
  • --patches-applied — Denote the Debian branch already has the patches applied.

Without this git-dpm will check there are no changes in the Debian branch outside patch management before applying the patches; with this, it will instead check there are no differences after applying the patches.

okay that's part 1 bestie, the rest of the commands are coming up next, keep scrolling 🫶

  • --create-no-patches — bestie, this one says: do not create or override the debian/patches directory. You're gonna have to call update-patches yourself. It's giving "I'm importing historical data and I keep the original patches chilling in the Debian branch" energy. 🫶
  • --record-patch-category — adds a Patch-Category: field to every imported patch that lives in a subdirectory of debian/patches. This makes update-patches stash it in that same subdirectory. consistency icon 💅
  • --record-patch-name — adds a Patch-Name: field to each imported patch with its name. This makes update-patches store it under its original name. no more mystery filenames 💖

prepare ✨

Makes sure the upstream branch and the upstream orig.tar ball are there and up to date. (Best called after a clone or a pull — like, right after, bestie.)

status [branch]

Checks the status of the current project. Or, if you hand it a branch argument, the status of the project that belongs to that branch. Heads up: it returns a non-zero exit code if it detects something that needs doing. So non-zero = you got homework 📝

checkout-patched 🎀

Checks out the patched branch (patched|patched-whatever) — but only after making sure it exists and that it's the one recorded in the debian/.git-dpm file.

If the patched branch is pointing at an old state (like, one that's already an ancestor of the current Debian branch), it gets changed to the recorded current one.

Otherwise, you can reset it to the last recorded state with the --force option. 💪

update-patches [options] [branch-name] 🌸

After calling merge-patched-into-debian if that's necessary, this updates the contents of debian/patches to the current state of the patched branch.

It also records in debian/.git-dpm which state of the patched branch the patches directory belongs to. 📌

If a branch-name is given, that branch is the one getting processed. Otherwise the name is derived from the currently checked out branch, as usual.

Options:

  • --redo — do something, even if it seems like there's nothing to do. main character refuses to be idle 💅
  • --allow-revert, --ignore-deletions, --dot-git-files=* — these get passed on to merge-patched-into-debian. handing them off, no cap 🤝
  • --amend — do not create a new commit, amend the last one in the Debian branch instead. (I.e. call merge-patched-into-debian with --amend and amend the updated patches into that last commit — even if that commit was not created by merge-patched-into-debian.)
  • -m message — use message as the commit message. (If you use this together with --amend, it does not reuse the old commit message, author or author date — instead it replaces the old commit with a brand new commit carrying that message.) glow-up of a commit fr fr ✨
  • --keep-branch — do not remove an existing patched branch. (Usually that branch gets removed and can be recreated with checkout-patched, so stale copies don't just lurk around being weird.)
  • --allow-nonlinear — passed to merge-patched.

dch [options] -- dch-options 💖

After calling update-patches if necessary, it runs devscripts' dch with the specified options, and then does a git commit with a commit message containing the changes to the debian/changelog file.

Options:

  • --amend — replace the commit that's currently the head of the Debian branch (master|something) instead of stacking a new one on top. The commit message will also include the changes done to debian/changelog in the previous commit (unless they got reverted by the new edit).
  • --ignore-patches — don't call update-patches, just simply ignore the current state of the patched branch (patched|patched-something). pretending I don't see it 🙈
  • --keep-branch, --allow-revert, --allow-nonlinear, --ignore-deletions, --dot-git-files=* — passed to update-patches, if it's called.
  • --latest-only|--latest|-l — only include the changes between the current working directory before calling dch and after calling it (and not since the last commit, or the last commit that wasn't replaced).
  • -e | -v | -a | --all | -s | -n | --no-verify | -u | --untracked-files | -q | --quiet | --cleanup=... | --author=... — passed to git commit.

merge-patched-into-debian [options] [branch-name] 👑

Usually update-patches runs this for you if it deems it necessary.

This command is the core of git-dpm, but bestie, you usually don't call it directly. It gets called by update-patches — and by things that call update-patches, like dch — when it's necessary.

It replaces all files (with only the exceptions described below) in the current Debian branch (master|whatever) with the ones found in the patched branch (patched|patched-whatever).

Only the debian directory and the files in the root directory that start with ".git" are kept from the Debian branch (so .gitignore, .gitattributes, ... they stay). And all files that were found in the last recorded patched branch and got deleted in the current Debian branch will also be deleted in the new one. gone is gone 🫡

On top of that, the debian/.git-dpm file gets updated so the current patched branch is recorded and is marked as belonging to the last recorded upstream branch.

If there's no branch-name on the command line, the base name of the branches to operate on is computed from the currently checked out branch, as usual. Otherwise that argument is used.

Options:

  • --allow-revert — usually, reverting to an old state of the patched branch is not allowed, to avoid mistakes (like having only pulled the Debian branch and forgetting to run checkout-patched 😭). This option changes that, so you can, for example, drop the last patch in your stack.
  • --no-ignore-deletions (default) — files currently deleted in the Debian branch relative to the recorded patched branch will still be deleted in the new Debian branch, and not taken from the new patched branch. This is the default, unless a different default was set with
 git config dpm.BRANCHNAME.dpmIgnoreDeletions true.
  • --ignore-deletions — disables the behavior described in --no-ignore-deletions.
  • *--dot-git-files=method* — specifies how files starting with .git outside of debian/ are handled. Those get special treatment, because .gitattributes and .gitignore might be different in the Debian branch without being part of any patch. (The whole debian/ directory is always taken from the Debian branch, so files in there aren't affected.) 💅

Possible methods are:

  • automatic (default) — any .git* files that are added, modified or removed in the current Debian branch compared to the old upstream branch are set to this state, and everything else is taken as found in the new patched branch.
  • debian — all .git* files are taken from the Debian branch. Files with a name like that from the patched branch are ignored. byeee 👋
  • upstream — files starting with .git get no special handling. They're taken from the patched branch, unless they're deleted in the Debian branch and the default --no-ignore-deletions is active. (i.e. just like any other file outside debian/.)
  • --keep-branch — do not remove an existing patched branch. (Usually that branch gets removed and can be recreated with checkout-patched, so stale copies don't lurk around.)
  • --amend — replace the last commit on your Debian branch (exactly like git commit --amend would do). With the exception that every parent that is an ancestor of, or equal to, the new patched branch or the recorded patched branch is omitted. (That is: you lose not only the commit on the Debian branch, but also a previous state of the patched branch, if your last commit also merged the patched branch.) 💀
  • -m message — the commit message to use for the new commit created. (If used together with --amend, this disables reusing the old author and date.)
  • --allow-nonlinear — do not abort with an error if the patched branch is not a linear series of commits on top of the upstream branch. > Using this option is not recommended, bestie — it easily hides problems with the patched or upstream branch and may introduce a broken debian/patches/ series, because format-patch does no serialisation. 🚨

import-new-upstream [options] .orig.tar 🦋

Imports the contents of the given tarfile (same as import-tar does) and records this branch (same as record-new-upstream does).

This is roughly equivalent to:

 git-dpm import-tar -p upstream filename
 git checkout -b upstream
 git-dpm record-new-upstream filename
  • --detached — don't make the new upstream branch an ancestor of the old upstream branch (unless you re-add that with -p).
  • -p commit-id|--parent commit-id — give import-tar additional parents for the new commit it's about to create.

For example, if you track upstream's git repository in some branch, you can name that here to make it part of the history of your Debian branch. so iconic 🔥

  • --allow-no-parent — if dpm.importWithoutParent is set to false via git config, git-dpm will not allow import-new-upstream to be run without this option, or at least one -p option.
  • --rebase-patched — after recording the new upstream branch, rebase the patched branch onto the new upstream branch.
  • --no-rebase-patched — do not call rebase-patched after recording the new upstream branch. (This is currently the default, but that may change in the future. 👀)
  • -m message — the commit message you wanna use for that brand-new commit on the Debian branch, the one that records the new file and the new upstream branch. 💌
  • --component package_version.orig-component.tar.gz — unpack this exact filename into the component directory and write it down, so prepare and status know to go looking for it later. 🫶
  • --init — literally none of the branches exist yet? cool, this creates them.

Since the branches we're operating on get derived from HEAD when you don't pass --branch, you either need HEAD to point at a branch that doesn't exist yet (like right after git init), or you need to hand over a name with --branch. Otherwise one of the branches already exists and all you get back is an error message. 💀

  • --branch debianbranch — don't derive the Debian branch name from current HEAD, just use debianbranch instead. (And the upstream branch name and the patched branch name get derived from that as usual.) ✨
  • --pristine-tar-commit, --ptc — call pristine-tar commit for every imported tarball that isn't already hanging out in the pristine-tar branch. 👑
  • --no-pristine-tar-commit — do not call pristine-tar commit for those imported tarballs, even when you've configured it to do exactly that via
git config dpm.pristineTarCommit true

or via

git config branch.debianbranch.dpmPristineTarCommit true

🙈

  • --ignore-deletions, --dot-git-files= — these get passed along to merge-patched, if that even gets called (it only does when there were no patches previously). 💅
  • --upstream-author author — used as the --author argument to git-dpm import-tar. 🌸
  • --upstream-date date — used as the --date argument to git-dpm import-tar (and yes, auto is supported here, which pulls a date out of the tar file). 🦋
  • --exclude pattern — the pattern you give gets passed to tar as an exclude pattern while unpacking. You can drop this one multiple times if you need. ⭐

🎀 import-tar [options] .tar-file 🎀

Make a brand-new commit holding the contents of the given file. That commit won't have any parents — unless you hand it some -p options, of course. 🌈

  • -p commit-id, --parent commit-id — add the given commit as a parent. (You can specify this multiple times, go off.) 🔥
  • --branch branchname — create the new branch branchname if it doesn't already exist, or replace branchname with a commit built from the tarball, using the current branchname head as parent. 💜
  • -m message — don't open an editor for the commit message, just use the argument instead. 🫶
  • --date date — the date of the commit to create.

If the value is auto, then the newest date of any file or directory inside the tarball is used. 🕰️

  • --author author — the author of the commit to create. It has to be in the usual git format:
author <email>

✨

  • --exclude pattern — the given pattern is passed to tar as an exclude pattern while unpacking. Can be given multiple times. 💅

🌸 record-new-upstream [options] .orig.tar [commit] 🌸

So you changed your upstream branch (upstream|upstream-whatever)... bestie, git-dpm needs to know which tarball that branch now corresponds to, and you're gonna have to rebase your patched branch (patched|patched-whatever) onto the new upstream branch. That's just the deal. 💖

If there's a second argument, this command first replaces your upstream branch with the specified commit. 👑

Then the new upstream branch gets recorded in your Debian branch's debian/.git-dpm file. 🎀

If you specified --rebase-patched (or the short --rebase), then git-dpm rebase-patched gets called to rebase your patched branch on top of the new upstream branch. 🦋

And after all that (and if the branch then looks like what you want), you still need to call git-dpm merge-patched-into-debian (or directly git-dpm update-patches). No skipping steps. 😭

WARNING, so we avoid any misunderstandings: you have to change the upstream branch before using this command. It's your responsibility to make sure the contents of the tarball match those of the upstream branch. fr fr. 💀
  • --rebase-patched — automatically call git-dpm rebase-patched. ⭐
  • --new-tarball-only — don't refuse the operation if the tarball changes but the upstream branch didn't. (This only makes sense if the tarball changed without changing its contents — see the warning above. 👀)
  • -m message — the commit message to use for the new commit to the Debian branch that records the new file and upstream branch. 💌
  • --amend — replace the last commit instead of creating a new one on top. 🌈
  • --component filename — record filename as the needed component source file (i.e. a sourcename_upstreamversion.orig-component.tar.compression file). It's your responsibility to already have that file's contents as part of your upstream branch (in a component subdirectory). 🫶

(Recorded files will be looked for by status and prepare. The list of recorded component source files gets removed when a new upstream branch or upstream .orig source file is recorded.) 💅

  • --ignore-deletions, --ot-git-files= — passed to merge-patched, if called (which only happens if there were no patches previously, so the new upstream branch gets merged in directly). 🔥

💜 rebase-patched 💜

Try to rebase your current patched branch (patched|patched-whatever) onto your current current upstream branch (upstream|upstream-whatever). (Yes, "current current", we said what we said.) 😌

If those branches don't exist as git branches yet, they get (re)created from the information recorded in debian/.git-dpm first. ✨

This is only a convenience wrapper around git rebase that first tries to figure out what exactly is to be rebased. If there are any conflicts, git rebase will ask you to resolve them and tell rebase to continue. 🌸

After this is finished (and if the branch then looks like what you want), you still need merge-patched-into-debian (or directly update-patches). 😭

⭐ tag [ options ] [ version ] ⭐

Add tags to the upstream, patched and Debian branches. If no version is given, it gets taken from debian/changelog. 👑

Options:

  • --refresh — overwrite the tags if they're already there and they differ (except upstream). 🔄
  • --refresh-upstream — overwrite the upstream if it's there and differs. 💫
  • --allow-stale-patches — don't error out if the patches aren't up to date. This is only useful if you're importing historical data and wanna tag it. 🕰️
  • --named — use the package name as part of the names of the generated tags. (use git config dpm.tagsNamed true to make this the default) 🎀
  • --with-name name — like --named, but you give the name to use. 💅
  • --debian-tag tag-name
  • --patched-tag tag-name
  • --upstream-tag tag-name

Specify the names of the tags to generate. 🌈

%p is replaced with the package name, 🌸

%v with the version (without epoch) with colons (:) and tilde (~) replaced by underscore (_), ✨

%u with the upstream version (without epoch or Debian revision) with colons (:) and tilde (~) replaced by underscore (_), 💖

%e with the epoch, 👑

%f with the epoch followed by an underscore (_) if there is an epoch, and with the empty string if there is no epoch, 🦋

%V with the version (without epoch) with colons (:) and tilde (~) replaced by dots (.), ⭐

%U with the upstream version (without epoch or Debian revision) with colons (:) and tilde (~) replaced by dots (.), 💜

%E with the epoch followed by a dot if there is an epoch, and with the empty string if there is no epoch, 🌈

%% with a single %. 💫

If one of those isn't set via the command line option, git config gets asked about the value of dpm.debianTag, dpm.patchedTag or dpm.upstreamTag. If that's also not set — or it's the special value AUTO — then debian/.git-dpm gets scanned for a line of the form

debianTag="value",
patchedTag="value" or
upstreamTag="value".

(Note: always add those to the end of the file, the first eight lines have fixed line numbers. 🙈)

If this still doesn't result in a pattern to use, the defaults are '%p-debian%e-%v', '%p-patched%e-%v' and '%p-upstream%e-%u' with --named, and 'debian%e-%v', 'patched%e-%v' and 'upstream%e-%u' without. 🎀

If a tag name has the special value NONE, no tag is generated. 🚫

🦋 ref-tag [ options ] commit [ version ] 🦋

Like tag, but it creates tags for commit — meaning commit gets the Debian tag, and the other tags get placed where the debian/.git-dpm file of that commit points to. ✨

So it's mostly equivalent to:

git checkout -b temp commit
git-dpm tag [options] [version]
git checkout previous-head
git branch -D temp

Options like tag. 💅

💅 apply-patch [ options... ] [ filename ] 💅

Switch over to the patched branch (assuming it's up to date — use checkout-patched first to make sure, or you get a warning), and apply the patch given as the argument, or from stdin. 🌸

  • --author author <email> — override the author to be recorded. 👑
  • --defaultauthor author <email> — if no author could be determined from the commit, use this one. 🫶
  • --date date — the date to record this patch as originally being from, if none was found. 🕰️
  • --dpatch — parse the patch as a dpatch patch. (Only works for dpatch patches that are actually a patch — might silently fail for others. 😬)
  • --cdbs — parse that patch as a cdbs simple-patchsys.mk patch. Heads up bestie: this only actually works for dpatch patches that really are patches, and it might silently fail for the others. 🙈
  • --edit — pops open an editor before the commit happens. For when you're feeling too lazy to amend later. 😌
  • --record-name — adds a Patch-Name: field so update-patches exports it back out under the same name. Iconic, keeps the receipts. 🎀
  • --name name — adds a Patch-Name: field telling update-patches to use name as the filename when storing this patch (relative to debian/patches).
  • --category name — adds a Patch-Category: field so update-patches always exports this patch into a subdirectory name of debian/patches.

🍒 cherry-pick

cherry-pick [ options... ] commit

Recreates the patched branch and cherry-picks the commit you hand it. Then it merges that back into the Debian branch and refreshes the debian/patches directory. So yeah, it's mostly equivalent to checkout-patched, git's own cherry-pick, and update-patches all glommed together. 💅

  • --merge-only — only merge the patched branch back into the Debian branch, and do not update the patches directory. You'll have to run update-patches yourself later to actually get that done.
  • -e | --edit — handed straight to git's cherry-pick: lets you edit the commit message being picked. ✏️
  • -s | --signoff — handed to git's cherry-pick: adds a Signed-off-by header.
  • -x — handed to git's cherry-pick: adds a line describing what was picked.
  • -m num | --mainline num — handed to git's cherry-pick: lets you pick a merge by specifying which parent to look at.
  • --repick — don't abort if the commit you named is already contained. 🔁
  • --allow-nonlinear, --ignore-deletions, --dot-git-files= — passed to update-patches, if it gets called.

Also passed to merge-patched-into-debian and update-patches.

  • --keep-branch — do not remove the patched branch once it's no longer needed. 🫶
  • --amend — passed to merge-patched-into-debian: amends the last commit in the Debian branch.

📦 import-dsc

Imports a Debian source package from a .dsc file. You can use this to spin up a brand-new project, or to bring a source package into a project you already have. ✨

Now listen, important detail: while a possible old state of a project gets recorded as a parent commit, the state of the old Debian branch is not taken into account. So basically all file deletions and .gitignore files and stuff like that need to be reapplied / re-added afterwards. (The assumption here is that new source package versions coming from outside might change stuff significantly, so the old info is more likely to be outdated — and reapplying it is easier than reverting those changes anyway. Makes sense, honestly. 💭)

First step: importing the .orig.tar file and possible .orig-component.tar files. You can either specify a branch to use. Otherwise import-dsc will look to see if the previous state of this project already has the needed file, so the old upstream branch can be reused. If there is none, the file gets imported as a new commit, by default with a possible previous upstream branch as parent.

Then import-dsc will try to import the source package in the state that dpkg-source -x would create it. (That means applying the .diff and making debian/rules executable for 1.0 format packages, and replacing the debian directory with the contents of a .debian.tar and applying possible debian/patches/series for 3.0 format packages.) Later on this gets referred to as the verbatim import.

If it's a 1.0 source format package, import-dsc then looks for a set of supported patch systems and tries to apply those patches. Those are then merged with the verbatim state into the new Debian branch. 🌈

Then a debian/.git-dpm file is created and a possible old state of the project is added as parent.

Note: dpkg-source is not used to extract packages — they get extracted manually. In particular, git-apply is used instead of patch. While this generally works (and git-dpm has some magic to work around some of git-apply's shortcomings), unclean patches might sometimes need a -C0 option, and then in some cases be applied at different positions than where patch would apply them. ⚠️

🧾 General options:

  • -b | --branch branch-name — don't look at the current HEAD; instead import the package into the git-dpm project branchname, or create a new project (if that branch doesn't exist yet). 🌱
  • --verbatim branch-name — after import-dsc finishes successfully, branch-name will contain the verbatim import of the .dsc file. If a branch of that name already exists, the new verbatim commit will also have the old one as parent. (This also causes the verbatim commit to not be amended with other changes, which can result in more commits.)
  • --use-changelog — parse debian/changelog of the imported package. Use the description as commit messages, and the author and time as defaults for patches and import commits that don't have that info. (Warning: may still contain some rough edges. 🫠)

🌊 Options about creating the upstream branch:

  • --upstream-to-use commit — don't import the .orig.tar or try to reuse an old import at all; always use the commit you specified.
It is your responsibility that this branch is similar enough to the .orig.tar file plus possible .orig-component.tar in their respective directories. (As usual, "similar enough" means: it does not miss any files that your patches touch or that your build process requires (or recreates unless debian/rules clean removes them again). Every file that differs from .orig.tar or doesn't exist there you must delete in the resulting Debian branch. No patch may touch those files.)

Use with care. 😭 Nothing will warn you — not even if you use the contents of a totally wrong upstream version.

  • --detached-upstream — if importing a .orig.tar as a new commit, don't make a possible commit for an old upstream version its parent.
  • --upstream-parent commit — add commit as an (additional) parent if importing a new upstream version.

(You can use this, for example, to make upstream's git history part of your package's history, which helps git out when cherry-picking stuff. 🍒)

  • --allow-no-parent — if dpm.importWithoutParent is set to false via git config, git-dpm won't allow import-dsc to run without this option, or at least not without an --upstream-parent option.
  • --pristine-tar-commit | --ptc — call pristine-tar commit for all tarballs imported, after the rest of the import-dsc command was successful. 🧚
  • --no-pristine-tar-commit — do not call pristine-tar commit for all imported tarballs, even if it's configured to do so by
git config dpm.pristineTarCommit true

or by

git config branch.debianbranch.dpmPristineTarCommit true
  • --upstream-author author — used as the --author argument to git-dpm import-tar.
  • --upstream-date date — used as the --date argument to git-dpm import-tar (and yes, auto is supported, to extract a date from the tar file). 🗓️
  • --tar-exclude pattern — the given pattern is passed to tar as an exclude pattern when unpacking tarfiles. Can be given multiple times.

🩹 Options about applying patches:

  • -f | --force-commit-reuse — only look at parent and tree, and no longer at the description, when trying to reuse commits that import patches from previous package versions.
  • -Cnum | --patch-context num — passed as -Cnum to git-apply. Specifies how many context lines must match.
  • --dpatch-allow-empty — don't error out if a dpatch file doesn't change anything when treated as a patch.

Since dpatch files can be arbitrary scripts, git-dpm has some trouble detecting whether they're really patches. (It can only cope with patches.) If a script that isn't a patch gets treated as a patch, that usually results in the patch not modifying anything — so those are forbidden without this option.

  • --patch-system mode — specify what patch system is used for source format 1.0 packages.
    • auto — (this is the default) try to determine what patch system is used by looking at debian/rules (and debian/control).
    • none — those are not the patches you are looking for. 👀
    • history — don't try to find any patches in the .diff (like none). If the project already exists and the upstream tarball is the same, create the patched state of the new one by using the patches of the old one and adding a patch on top bringing it to the new state.

If you import multiple revisions of some package where each new revision added at most a single change to upstream, this option lets you almost automatically create a proper set of patches (ideally only missing descriptions). 🎀

If there are the same changes and reverts, those will be visible in the patches created, so this mode isn't very useful in that case.

  • quilt — extract and apply a debian/patches/series quilt-like series on top of possible upstream changes found in the .diff file. 🧵
  • quilt-first — literally the quilt mode but the order is different: apply the patches to an unmodified upstream first, and then cherry-pick the changes you find in the .diff file. ✨
Heads up bestie: this is not the order patches get applied in a normal unpack/build cycle, so it will 💀 if those changes aren't distinct enough — like when patches depend on changes done in the .diff.

But if the .diff only contains unrelated changes that vary with each version, this gives you a much nicer history, because the commits for the patches can more easily be reused. 👑

  • quilt-applied — same as the quilt-first mode, but it assumes the patches are already applied in the .diff. So it applies them on top of an unmodified upstream and then adds a commit bringing it to the state in the .diff. (Or not, if that patch would be empty.) 🙈
  • dpatch | dpatch-first | dpatch-applied — like the quilt / quilt-first / quilt-applied modes respectively, but instead it looks for dpatch-style patches in debian/patches/00list.
Note that only patches are supported, and not dpatch running other commands. 🚫
  • simple | simple-first | simple-applied — like the quilt / quilt-first / quilt-applied modes respectively, but instead it assumes debian/patches/ contains patches suitable for cdbs's simple-patchsys.mk.
  • --patch-author "name <email>" — sets the author for all git commits importing patches. ✍️
  • --patch-default-author "name <email>" — sets an author for all patches that don't contain author information (or where git-dpm can't determine it). 🕵️
  • --edit-patches — for every patch imported, it starts an editor for the commit message. 📝
  • --record-patch-category — adds a Patch-Category: field to each imported patch that lives in a subdirectory of debian/patches. This makes update-patches store it in that same subdirectory. 🗂️
  • --record-patch-name — adds a Patch-Name: field to each imported patch with its name. This makes update-patches store it under its original name. 🏷️

🎀 record-dsc

record-dsc [options] commit .dsc-file

Stores a pristine .dsc file in a dscs branch, after storing the files it contains using pristine-tar. 🫶

The first argument is a tag or commit storing the git-dpm project in the state belonging to the .dsc file, and the second argument is the .dsc file itself. The files it references are expected in the same directory as the file itself (if they are needed). 📁

Some checks are done to make sure the file and its contents are named properly and match the commit in question — but only cursory ones, to avoid obvious mistakes. For example, only the version is checked, but .debian.tar is not unpacked to check the files are really the same. 😬

Options:

  • --create-branch — creates a new dscs branch. 🌱
  • --allow-unsigned — allows recording an unsigned .dsc file. This usually defeats the point of storing them at all. 💀

🦋 the debian/.git-dpm file

You shouldn't need to know about the contents of this file — except for debugging git-dpm. 🔍

The file contains 8 lines, but future versions may contain more.

The first line is a hint about what this file is about, and it's ignored. 🙈

Then there are 4 git commit ids for the recorded states:

  1. First, the state of the patched branch when the patches in debian/patches were last updated.
  2. Then the state of the patched branch when it was last merged into the Debian branch.
  3. Then the state of the upstream branch when the patched branch was last merged.
  4. Finally, the upstream branch.

The following 3 lines are the filename, the sha1 checksum, and the size of the origtarball belonging to the recorded upstream branch. 📦

⚡ SHORTCUTS

Most commands also have shorter aliases, so you don't have to type the whole thing:

update-patches:     up, u-p, ci
prepare:  prep
checkout-patched:   co, c-p
rebase-patched:     r-p
apply-patch:   a-p
import-tar:    i-t
import-new-upstream:     i-n-u, inu
record-new-upstream:     r-n-u, rnu
merge-patched-in-debian: merge-patched

record-new-upstream is also available under the old name new-upstream, though it will likely be removed in future versions (to avoid confusion). 👋

🌈 BRANCHES

the upstream branch (upstream|upstream-whatever)

This branch contains the upstream sources. Its contents need to be equal enough to the contents in your upstream tarball. 💖

"Equal enough" means that dpkg-source should see no difference between your patched tree and an original tarball unpackaged, the patches applied, and debian/rules clean run. Usually the easiest thing is to just store the verbatim contents of your orig tarball here. Then you can also use it for pristine tar. 🎀

This branch may contain a debian/ subdirectory, which will usually just be ignored.

You can either publish that branch, or make it only implicitly visible via the debian/.git-dpm file in the Debian branch. 👀

While it usually makes sense that newer upstream branches contain older ones, this is not needed. You should be able to switch from one created yourself, or one generated by some foreign-vcs importing tool, to a native upstream branch or vice versa without problems. Note that since the Debian branch has the patched branch as ancestor and the patched branch the upstream branch, your upstream branches are part of the history of your Debian branch. ✨

Which has the advantage that you can recreate the exact state of your branches from your history directly, like:

git checkout -b oldstate myoldtagorshaofdebianbranchcommit ; git-dpm prepare ; git checkout unstable-oldstate

but the disadvantage that to remove those histories from your repository you have to do some manual work. 😭

the patched branch (patched|patched-whatever)

This branch contains your patches to the upstream source. (Which of course means it's based on your upstream branch.) 🌸

Every commit will be stored as a single patch in the resulting package.

To help git generate a linear patch series, this should ideally be a linear chain of commits whose descriptions are helpful for other people. 🧚

As this branch is regularly rebased, you should not publish it. Instead you can recreate this branch using git-dpm checkout-patched using the information stored in debian/.git-dpm.

You are not allowed to change the contents of the debian/ subdirectory in this branch. Renaming files or deleting files usually causes unnecessarily large patches. 🙅♀️

the Debian branch (master|whatever)

This is the primary branch. 👑

This branch contains the debian/ directory and has the patched branch merged in.

Every change not in debian/, .git*, or deleting files must be done in the patched branch. 📌

alternative branch names

You can specify alternate branch names for upstream and patched branches of a specific Debian branch, or force a branch to be a Debian branch that would normally be considered, e.g., the upstream branch of another branch, by adding dpmUpstreamBranch and dpmPatchedBranch configure items for the Debian branch in question (you need both — only one is treated as an error). 🚨

The following example is a no-op for all practical purposes:

git config branch.master.dpmUpstreamBranch upstream
git config branch.master.dpmPatchedBranch patched

Copyright © 2009,2010 Bernhard R. Link

This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. 🫶

okay that's the whole page bestie, you're officially a git-dpm girlie now 💅 this was git-dpm, dated 2012-05-15, from the GIT-DPM(1) manual — go forth and rebase responsibly, mwah 🎀✨💖

📦 where this page comes from