init [options] tarfile [upstream-commit [preapplied-commit [patched-commit]]]
Create a new project.
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:
--componentfilename
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.
--create-no-patches
Do not create/override debian/patches directory. You will have to call update-patches
yourself. Useful if you are importing historical data and keep the original patches in the
Debian branch.
--record-patch-category
Add a Patch-Category: field to each imported patch that is in a subdirectory of
debian/patches. This causes update-patches to store it in the same subdirectory.
--record-patch-name
Add a Patch-Name: field to each imported patch with its name. This causes update-patches
to store it under its original name.
prepare
Make sure upstream branch and upstream orig.tar ball are there and up to date. (Best called after
a clone or a pull).
status [branch]
Check the status of the current project (or of the project belonging to the argument branch if
that is given). Returns with non-zero exit code if something to do is detected.
checkout-patched
Checkout the patched branch (patched|patched-whatever) after making sure it exists and is one
recorded in the debian/.git-dpm file.
If the patched branch references an old state (i.e. one that is already ancestor of the current
Debian branch), it is 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 necessary, update the contents of debian/patches to the
current state of the patched branch.
Also record in debian/.git-dpm which state of the patched branch the patches directory belongs to.
If a branch-name is given, that branch is processed. Otherwise the name is derived from the
currently checked out branch as usual.
Options:
--redo Do something, even if it seems like there is nothing to do.
--allow-revert, --ignore-deletions, --dot-git-files=*
passed on to merge-patched-into-debian
--amend
Do not create a new commit, but amend the last one in the Debian branch. (I.e. call
merge-patched-into-debian with --amend and amend the updates patches into the last commit
even if that was not created by merge-patched-into-debian).
-mmessage
Use message as commit message. (If used together with --amend, do not reuse old commit
message, author or author date but replace the old commit with a new commit with that
message).
--keep-branch
do not remove an existing patched branch (usually that is removed and can be recreated with
checkout-patched to avoid stale copies lurking around.
--allow-nonlinear
passed to merge-patched.
dch [options] --dch-options
After calling update-patches if necessary, run devscripts' dch with the specified options and then
do a gitcommit with a commit message containing changes to the debian/changelog file.
Options:
--amend
Replace the commit currently the head of the Debian branch (master|something) instead of
creating a new one on top. The commit message will also include changes done to
debian/changelog in the previous commit (unless reverted by the new edit).
--ignore-patches
Do not call update-patches but simply ignore the current state of the patched branch
(patched|patched-something).
--keep-branch, --allow-revert, --allow-nonlinear, --ignore-deletions, --dot-git-files=*
Passed to update-patches, if called.
--latest-only|--latest|-l
Only include changes between the current working directory before calling dch and after
calling it (and not since the last commit or the last commit not 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 deemed necessary.
This command is the core of git-dpm, but you usually do not call it directly. It is called by
update-patches and things calling update-patches like dch when necessary.
It replaces all files (with only the exceptions described below) in the current Debian branch
(master|whatever) with those found in the patched branch (patched|patched-whatever).
Only the debian directory and files in the root directory starting with ".git" are kept from the
Debian branch (so .gitignore, .gitattributes, ... will stay). And all files that were found in
the last recorded patched branch and deleted in the current Debian branch will also be deleted in
the new one.
Additionally the debian/.git-dpm file will be updated so the current patched branch is recorded
and is marked as belonging to the last recorded upstream branch.
If there is no branch-name given on the command line the base name of the branches to operate on
is computed from the currently checked out branch as usual. Otherwise this 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 forgot 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 deleted currently 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
gitconfigdpm.BRANCHNAME.dpmIgnoreDeletionstrue.
--ignore-deletions
Disable the behavior described in --no-ignore-deletions.
--dot-git-files=method
Specify how files starting with .git outside debian/ are handled. Those are handles
specially as .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 there are not 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, 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.
upstream
Files starting with .git are not given special handling. They are taken from the
patched branch, unless they are 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 is removed and can be recreated with
checkout-patched to avoid stale copies lurking around).
--amend
Replace the last commit on your Debian branch (as 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).
-mmessage
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 no linear series of commits on top of
the upstream branch. Using this option is not recommended as it easily hides problems with
patched or upstream branch and may introduce broken debian/patches/ series, as format-patch
does no serialisation.
import-new-upstream [options] .orig.tar
Import the contents of the given tarfile (as with import-tar) and record this branch (as with
record-new-upstream).
This is roughly equivalent to:
git-dpmimport-tar-pupstreamfilenamegitcheckout-bupstreamgit-dpmrecord-new-upstreamfilename--detached
Don't make the new upstream branch an ancestor of the old upstream branch (unless you re-
add that with -p).
-pcommit-id|--parentcommit-id
Give import-tar additional parents of the new commit 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.
--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 on -p option.
--rebase-patched
After recording the new upstream branch, rebase the patched branch to 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).
-mmessage
Commit message to use for the new commit to the Debian branch recording the new file and
upstream branch.
--componentpackage_version.orig-component.tar.gz
Unpack the specified filename into the component directory and record it so that prepare
and status know to check for it.
--init
None of the branches yet exists, create them.
As the branches to operate on are derived from HEAD if no --branch option is given, you
either need HEAD point to an not yet existing branch (like directly after gitinit) or you
need you give a name with --branch. Otherwise one of the branches already exists and you
only get an error message.
--branchdebianbranch
Don't derive the Debian branch name from current HEAD but use debianbranch instead. (And
upstream branch name and patched branch name derived from that as usual).
--pristine-tar-commit | --ptc
Call pristine-tarcommit for all imported tarballs not yet found in the pristine-tar
branch.
--no-pristine-tar-commit
Do not call pristine-tarcommit for all imported tarballs even if configured to do so by
gitconfigdpm.pristineTarCommittrue or by
gitconfigbranch.debianbranch.dpmPristineTarCommittrue.
--ignore-deletions, --dot-git-files=
Passed to merge-patched, if called (only done if there were no patches previously).
--upstream-authorauthor
Used as the --author argument to git-dpmimport-tar.
--upstream-datedate
Used as the --date argument to git-dpmimport-tar (especially auto is supported to extract
a date from the tar file).
--excludepattern
The given pattern is passed to tar as exclude pattern when unpacking. Can be given
multiple times.
import-tar [options] .tar-file
Create a new commit containing the contents of the given file. The commit will not have any
parents, unless you give -p options.
-pcommit-id|--parentcommit-id
Add the given commit as parent. (Can be specified multiple times).
--branchbranchname
Create new branch branchname if it does not already exist or replace branchname with a
commit created from the tarball with the current branchname head as parent.
-mmessage
Do not start an editor for the commit message, but use the argument instead.
--datedate
Date of the commit to create.
If the value is auto then the newest date of any file or directory in the tarball is used.
--authorauthor
Author of the commit to create. It has to be in the usual git format
author<email>.
--excludepattern
The given pattern is passed to tar as exclude pattern when unpacking. Can be given
multiple times.
record-new-upstream [options] .orig.tar [commit]
If you changed the upstream branch (upstream|upstream-whatever), git-dpm needs to know which
tarball this branch now corresponds to and you have to rebase your patched branch
(patched|patched-whatever) to the new upstream branch.
If there is a second argument, this command first replaces your upstream branch with the specified
commit.
Then the new upstream branch is recorded in your Debian branch's debian/.git-dpm file.
If you specified --rebase-patched (or short --rebase), git-dpmrebase-patched will be called to
rebase your patched branch on top of the new upstream branch.
After this (and if the branch then looks like what you want), you still need to call git-dpmmerge-patched-into-debian (or directly git-dpmupdate-patches).
WARNING to avoid any misunderstandings: You have to change the upstream branch before using this
command. It's your responsibility to ensure the contents of the tarball match those of the
upstream branch.
--rebase-patched
Automatically call git-dpmrebase-patched.
--new-tarball-only
Don't refuse operation if the tarball changes but the upstream branch did not. (This is
only sensible if the tarball changed without changing its contents, see the warning above).
-mmessage
Commit message to use for the new commit to the Debian branch recording the new file and
upstream branch.
--amend
Replace the last commit instead of creating a new one on top.
--componentfilename
Record filename as needed component source file (i.e. a
sourcename_upstreamversion.orig-component.tar.compression file). It's your responsible to
have that file's contents already 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 is 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 is only done if there were no patches previously,
so the new upstream branch is merged in directly).
rebase-patched
Try to rebase your current patched branch (patched|patched-whatever) to your current current
upstream branch (upstream|upstream-whatever).
If those branches do not yet exist as git branches, they are (re)created from the information
recorded in debian/.git-dpm first.
This is only a convenience wrapper around git rebase that first tries to determine what exactly is
to rebase. 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 is taken from
debian/changelog.
Options:
--refresh
Overwrite the tags if they are already there and differ (except upstream).
--refresh-upstream
Overwrite the upstream if that is there and differs.
--allow-stale-patches
Don't error out if patches are not up to date. This is only useful if you are importing
historical data and want to tag it.
--named
Use the package name as part of the names of the generated tags. (use gitconfigdpm.tagsNamedtrue to make this the default)
--with-namename
Like --named but give the name to use.
--debian-tagtag-name--patched-tagtag-name--upstream-tagtag-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 with 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 is not set via the command line option, gitconfig is asked about value of
dpm.debianTag, dpm.patchedTag or dpm.upstreamTag. If that is also not set or the special value
AUTO, then debian/.git-dpm is 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 does not result in an 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 create tags for commit, i.e. commit will get the Debian tag and the other tags are
placed where the debian/.git-dpm file of that commit points to.
So it is mostly equivalent to:
gitcheckout-btempcommitgit-dpmtag [options] [version]
gitcheckoutprevious-headgitbranch-Dtemp
Options like tag.
apply-patch [ options... ] [ filename ]
Switch to the patched branch (assuming it is up to date, use checkout-patched first to make sure
or get an warning), and apply the patch given as argument or from stdin.
--authorauthor<email>
Override the author to be recorded.
--defaultauthorauthor<email>
If no author could be determined from the commit, use this.
--datedate
Date to record this patch originally be from if non found.
--dpatch
Parse patch as dpatch patch (Only works for dpatch patches actually being a patch, might
silently fail for others).
--cdbs Parse patch as cdbs simple-patchsys.mk patch (Only works for dpatch patches actually being
a patch, might silently fail for others).
--edit Start an editor before doing the commit (In case you are too lazy to amend).
--record-name
Add a Patch-Name: field to tell update-patches to export it with the same name again.
--namename
Add a Patch-Name: field to tell update-patches to use name as filename to store this patch
into (relative to debian/patches).
--categoryname
Add a Patch-Category: field to tell update-patches to always export this patch into a
subdirectory name of debian/patches.
cherry-pick [ options... ] commit
Recreate the patched branch and cherry-pick the given commit. Then merge that back into the
Debian branch and update the debian/patches directory (i.e. mostly equivalent to checkout-patched,
git's cherry-pick, and update-patches).
--merge-only
Only merge the patched branch back into the Debian branch but do not update the patches
directory (You'll need to run update-patches later to get this done).
-e | --edit
Passed to git's cherry-pick: edit the commit message picked.
-s | --signoff
Passed to git's cherry-pick: add a Signed-off-by header
-x Passed to git's cherry-pick: add a line describing what was picked
-mnum | --mainlinenum
Passed to git's cherry-pick: allow picking a merge by specifying the parent to look at.
--repick
Don't abort if the specified commit is already contained.
--allow-nonlinear, --ignore-deletions, --dot-git-files=
Passed to update-patches, if called.
passed to merge-patched-into-debian and update-patches.
--keep-branch
do not remove the patched branch when it is no longer needed.
--amend
passed to merge-patched-into-debian: amend the last commit in the Debian branch.
import-dsc
Import a Debian source package from a .dsc file. This can be used to create a new project or to
import a source package into an existing project.
While a possible old state of a project is recorded as parent commit, the state of the old Debian
branch is not taken into account. Especially all file deletions and .gitignore files and the like
need to be reapplied/re-added afterwards. (Assumption is that new source package versions from
outside might change stuff significantly, so old information might more likely be outdated. And
reapplying it is easier then reverting such changes.)
First step is importing the .orig.tar file and possible .orig-component.tar files. You can either
specify a branch to use. Otherwise import-dsc will look if the previous state of this project
already has the needed file so the old upstream branch can be reused. If there is non, the file
will be 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 as dpkg-source-x would create
it. (That is 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). This is later referred to as verbatim import.
If it is 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 added as parent.
Note that dpkg-source is not used to extract packages, but they are extracted manually.
Especially 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 same cases be applied at different positions than where patch would apply them.
General options:
-b | --branchbranch-name
Don't look at the current HEAD, but import the package into the git-dpm project branchname
or create a new project (if that branch does not yet exist).
--verbatimbranch-name
After import-dsc has completed 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 as parent. (This also causes the verbatim commit not being 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 default for patches and import commits without that information.
(Warning: may still contain some rough edges).
Options about creating the upstream branch:
--upstream-to-usecommit
Do not import the .orig.tar nor try to reuse an old import, but always use the commit
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: Does not miss any files that your patches touch or your build process requires (or
recreates unless debian/rulesclean removes them again). Every file different than in
.orig.tar or not existing there you must delete in the resulting Debian branch. No patch
may touch those files.)
Use with care. Nothing will warn you even if you use the contents of a totally wrong
upstream version.
--detached-upstream
If importing a .orig.tar as new commit, do not make an possible commit for an old upstream
version parent.
--upstream-parentcommit
Add commit as (additional) parent if importing a new upstream version.
(This can for example be used to make upstream's git history part of your package's history
and thus help git when cherry-picking stuff).
--allow-no-parent
If dpm.importWithoutParent is set to false via git config, git-dpm will not allow
import-dsc to be run without this option or at least on --upstream-parent option.
--pristine-tar-commit |--ptc
Call pristine-tarcommit for all tarballs imported after the rest of the import-dsc command
was successful.
--no-pristine-tar-commit
Do not call pristine-tarcommit for all imported tarballs even if configured to do so by
gitconfigdpm.pristineTarCommittrue or by
gitconfigbranch.debianbranch.dpmPristineTarCommittrue.
--upstream-authorauthor
Used as the --author argument to git-dpmimport-tar.
--upstream-datedate
Used as the --date argument to git-dpmimport-tar (especially auto is supported to extract
a date from the tar file).
--tar-excludepattern
The given pattern is passed to tar as 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
importing patches from previous package versions.
-Cnum | --patch-contextnum
Passed as -Cnum to git-apply. Specifies the number of context lines that must match.
--dpatch-allow-empty
Do not error out if a dpatch file does not change anything when treated as patch.
As dpatch files can be arbitrary scripts, git-dpm has some problems detecting if they are
really patches. (It can only cope with patches). If a script that is not a patch is
treated as patch that usually results in patch not modify anything, thus those are
forbidden without this option.
--patch-systemmode
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 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 of 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 allows you to almost automatically
create a proper set of patches (ideally only missing descriptions).
If there are same changes and reverts those will be visible in the patches created,
so this mode is not 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
As the quilt mode, but apply the patches to an unmodified upstream first and then
cherry-pick the changes found in the .diff file.
As this is not the order in which patches are applied in a normal unpack/build
cycle, this will fail if those changes are not distinct enough (for example when
patches depend on changes done in the .diff).
But if the .diff only contains unrelated changes which varies with each version,
this gives a much nicer history, as the commits for the patches can more easily be
reused.
quilt-applied
As the quilt-first mode, but assume the patches are already applied in the .diff, so
apply them on top of an unmodified upstream and then add 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 resp. quilt-first resp. quilt-applied modes, but instead look 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 resp. quilt-first resp. quilt-applied modes, but instead assume
debian/patches/ contains patches suitable for cdbs's simple-patchsys.mk.
--patch-author "name <email>"
Set the author for all git commits importing patches.
--patch-default-author "name <email>"
Set an author for all patches not containing author information (or where git-dpm cannot
determine it).
--edit-patches
For every patch imported, start an editor for the commit message.
--record-patch-category
Add a Patch-Category: field to each imported patch that is in a subdirectory of
debian/patches. This causes update-patches to store it in the same subdirectory.
--record-patch-name
Add a Patch-Name: field to each imported patch with its name. This causes update-patches
to store it under its original name.
record-dsc [options] commit.dsc-file
Store a pristine .dsc file in a dscs branch after storing the files it contains using
pristine-tar.
The first argument is an 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 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, for example).
Options:
--create-branch
Create a new dscs branch.
--allow-unsigned
Allow recording a unsigned .dsc file. This usually defeats the point of storing them at
all.
Install Now
