GIT-DPM(1) | GIT-DPM | GIT-DPM(1) |
NAME¶
git-dpm - debian packages in git managerSYNOPSIS¶
git-dpm --helpDESCRIPTION¶
Git-dpm is a tool to handle a debian source package in a git repository.SHORT EXPLANATION OF THE BRANCHES¶
- the upstream branch (upstream|upstream-whatever)
- This branch contains the upstream sources. It contents need
to be equal enough to the contents in your upstream tarball.
- 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.
- the debian branch (master|whatever)
- This is the primary branch.
EXAMPLES¶
Let's start with some examples:- Checking out a project
- First get the master branch:
git clone URL
git-dpm prepare
git-dpm checkout-patched
...
git commit
git rebase -i upstream
git-dpm dch -- -i
...
git commit -a
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 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
vim ...
git add resolved files
git rebase --continue
git-dpm dch -- -v newupstream-1 "new upstream version"
git-dpm update-patches
dch -- -v newupstream-1 "new upstream version"
git commit --amend -a
...
git commit -a
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
pristine-tar commit ../example_0.orig.tar.gz upstream-unstable
git-dpm init ../example_0.orig.tar.gz
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"
git-dpm checkout-patched
vim ...
git commit -a
git-dpm dch "fix ... (Closes: num)"
git-dpm status &&
dpkg-buildpackage -rfakeroot -us -uc -I".git*"
git-dpm tag
git push --tags target unstable:unstable pristine-tar:pristine-tar
GLOBAL OPTIONS¶
- --debug
- Give verbose output what git-dpm is doing. Mostly only
useful for debugging or when preparing an bug report.
- --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.
COMMANDS¶
- init [options] tarfile [upstream-commit [ preapplied-commit [patched-commit]]]
- Create a new project.
- --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.
- --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]
-
- checkout-patched
-
- update-patches [options] [branch-name]
-
- --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).
- -m message
- 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.
- dch [options] -- dch-options
- After calling update-patches if necessary, run devscripts'
dch with the specified options and then do a git commit with a
commit message containing changes to the debian/changelog file.
- --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 contain 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.
- --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
git config dpm.BRANCHNAME.dpmIgnoreDeletions true.
- --ignore-deletions
- Disable the behaviour 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).
- 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).
- -m message
- Commit message to use for the new commit created. (If used together with --amend, this disables reusing the old author and date).
- import-new-upstream [options] .orig.tar
- Import the contents of the given tarfile (as with
import-tar) and record this branch (as with new-upstream).
git-dpm import-tar -p upstream filename
git checkout -b upstream
git-dpm new-upstream filename
- --detached
- Don't make the new upstream branch an ancestor of the old upstream branch (unless you readd that with -p).
- -p commit-id|--parent commit-id
- Give import-tar additional parents of the new commit
to create.
- --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).
- -m message
- Commit message to use for the new commit to the Debian
branch recording the new file and upstream branch.
- --component package_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
-
- --branch debianbranch
- Don't derive the debian branch name from current
HEAD but use debianbranch instead. (And upstream branch namd
and patched branch name derived from that as usual).
- --pristine-tar-commit | --ptc
- Call pristine-tar commit for all imported tarballs
not yet found in the pristine-tar branch.
- --no-pristine-tar-commit
- Do not call pristine-tar commit for all imported
tarballs even if configured to do so by
git config dpm.pristineTarCommit true or by
git config branch.debianbranch.dpmPristineTarCommit true.
- --ignore-deletions, --dot-git-files=
- Passed to merge-patched, if called (only done if 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 (especially auto is supported to extract a date from
the tar file).
- 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.
- -p commit-id|--parent commit-id
- Add the given commit as parent. (Can be specified multiple
times).
- --branch branchname
- 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.
- -m message
- Do not start an editor for the commit message, but use the
argument instead.
- --date date
- Date of the commit to create.
- --author author
- Author of the commit to create. It has to be in the usual
git format
author <email>.
- new-upstream [options] .orig.tar [commit]
-
- --rebase-patched
- Automatically call git-dpm rebase-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).
- -m message
- 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.
- --component filename
- 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).
- --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).
- tag [ options ] [ version ]
- Add tags to the uptream, patched and debian branches. If no
version is given, it is taken from debian/changelog.
- --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 git config dpm.tagsNamed true to make this the default)
- --with-name name
- Like --named but 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), %u with the upstream version, %e with the epoch,
%% with a single %.
- 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.
git checkout -b temp commit
git-dpm tag [options] [version]
git checkout previous-head
git branch -D temp
- 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.
- --author author <email>
- Override the author to be recorded.
- --defaultauthor author <email>
- If no author could be determined from the commit, use this.
- --date date
- 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.
- --name name
- Add a Patch-Name: field to tell
update-patches to use name as filename to store this patch
into (relative to debian/patches).
- --category name
- 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
- -m num | --mainline num
- Passed to git's cherry-pick: allow picking a merge by
specifign 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.
- --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.
- -b | --branch branch-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).
- --verbatim branch-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-use commit
- Do not import the .orig.tar nor try to reuse an old import,
but always use the commit specified.
- --detached-upstream
- If importing a .orig.tar as new commit, do not make an
possible commit for an old upstream version parent.
- --upstream-parent commit
- Add commit as (additional) parent if importing a new
upstream version.
- --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-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 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 (especially auto is supported to extract a date from the tar file).
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-context num
- 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.
- --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 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.
- 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.
- 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.
- simple | simple-first | simple-applied
- Like the quilt resp. quilt-first resp.
quilt-applied modes, but instead assume debian/patches/
contains patches suiteable 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.
- --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.
the debian/.git-dpm file¶
You should not need to know about the contents if this file except for debuging git-dpm.First the state of the patched branch when the
patches in debian/patches were last updated.
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.
SHORTCUTS¶
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
new-upstream-branch: new-upstream, n-u
apply-patch: a-p
import-tar: i-t
import-new-upstream: i-n-u, inu
cherry-pick: c-p
BRANCHES¶
- the upstream branch (upstream|upstream-whatever)
- This branch contains the upstream sources. It contents need
to be equal enough to the contents in your upstream tarball.
- the patched branch (patched|patched-whatever)
- This branch contains your patches to the upstream source.
(which of course means it is based on your upstream branch).
- the debian branch (master|whatever)
- This is the primary 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 normaly be considered e.g. 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 error).
git config branch.master.dpmUpstreamBranch upstream
git config branch.master.dpmPatchedBranch patched
COPYRIGHT¶
Copyright © 2009,2010 Bernhard R. LinkREPORTING BUGS AND ISSUES¶
You can report bugs or feature suggestions to git-dpm-devel@lists.alioth.debian.org or tome. Please send questions to git-dpm-user@lists.alioth.debian.org or to me at brlink@debian.org.2012-05-15 | git-dpm |