GIT-DPM(1) | GIT-DPM | GIT-DPM(1) |
git-dpm - Debian packages in git manager
git-dpm --help
git-dpm [ options ] command [ per-command-options and -arguments ]
Git-dpm is a tool to handle a Debian source package in a git repository.
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 quilt series.
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.
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.
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.
Let's start with some examples:
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
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
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.
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
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
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:
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.
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 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.
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:
Options:
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:
Possible methods are:
This is roughly equivalent to:
git-dpm import-tar -p upstream filename
git checkout -b upstream
git-dpm record-new-upstream filename
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.
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 git init) or you need you give a name with --branch. Otherwise one of the branches already exists and you only get an error message.
If the value is auto then the newest date of any file or directory in the tarball is used.
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-dpm rebase-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-dpm merge-patched-into-debian (or directly git-dpm update-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.
(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).
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).
Options:
%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, git
config 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.
So it is mostly equivalent to:
git checkout -b temp commit
git-dpm tag [options] [version]
git checkout previous-head
git branch -D temp
Options like tag.
passed to merge-patched-into-debian and update-patches.
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:
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/rules clean 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.
(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).
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.
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.
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.
Note that only patches are supported and not dpatch running other commands.
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:
You should not need to know about the contents if this file except for debugging git-dpm.
The file contains 8 lines, but future version may contain more.
The first line is hint what this file is about and ignored.
Then there are 4 git commit ids for the recorded states:
Then the state of the patched branch when it was last merged into the Debian branch.
Then the state upstream branch when the patched branch was last merged.
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.
Most commands also have shorter aliases, to avoid typing:
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 likely will be removed in future versions (to avoid confusion).
Equal enough means that dpkg-source should see no difference between your patched tree and and original tarball unpackaged, the patched applied and debian/rules clean run. Usually it is easiest 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 be just 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 by some foreign-vcs importing tool generated one to an 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.
Every commit will be stored as a single patch in the resulting package.
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 rebase d, 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 unnecessary large patches.
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.
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.
2012-05-15 | git-dpm |