Importing SourcesImporting already existing &debian; packagesImporting an already exsting debian package into a git repository is as easy as:
&gbp-import-dsc; package_0.1-1.dsc
This will create a new git repository named after the imported package, put
the upstream sources onto the and the
debian patch on the . In case of a debian
native package only the is being used.
You can specify alternative branch names via the
and
options or via the and
options in the configuration file.
If you want to be able to exactly recreate the original tarball
(orig.tar.gz) from &git; you should also specify the
option. This is recommended.
If you want to import further versions you can change into your shiny new
&git; repository and just continue with the same command:
cd package/
&gbp-import-dsc; package_0.1-2.dsc
&gbp-import-dsc; package_0.1-3.dsc
&gbp-import-dsc; package_0.2-1.dsc
Or you can import all versions at once using &gbp-import-dscs;:
&gbp-import-dscs; /path/to/history/package_*.dsc
This will create a &git; repository if necessary and import all versions sorted
by version number.
Importing a new upstream versionChange into your git repository (which can be empty), make sure it
has all local modifications committed and run either of:
&gbp-import-orig; /path/to/package_0.2.orig.tar.gz
&gbp-import-orig; /path/to/package_0.2.tar.bz2
&gbp-import-orig; /path/to/package-0.2/
This puts the upstream souces onto the and
tags them accordingly (the default tag format is
upstream/%(version)s).
The result is then merged onto the
and a new &debian; changelog entry is created. You can again specify
different branch names via the and
options. You can also filter out content
you don't want imported:
&gbp-import-orig; ='CVS/*'/path/to/package_0.2.orig.tar.gz
The option can be used multiple times for more
complex filtering.
If you expect a merge conflict you can delay the merge to the
via the and pull in
the changes from the later.
If you want to be able to exactly recreate the original tarball
(orig.tar.gz) from &git; you should also specify the
option. This is recommended.
To customize the commit message used by &gbp-import-orig; use
the option. This string is a standard
python format string, into which the
version variable is interpolated. (i.e.,
use %(version)s in your message to get
the imported upstream version).
Converting an existing &git; repository
If the &git; repository wasn't created with &gbp-import-dsc; you have to tell
&gbp-buildpackage; and friends where to find the upstream sources.
Upstream sources on a branch
If the upstream sources are already on a separate branch things are pretty
simple. You can either rename that branch to the default
name upstream with:
&gitcmd; branch upstream theupstream-branch
&gitcmd; branch theupstream-branch
or you can tell &gbp-buildpackage; the name of the branch to use as
:
cat <<EOF > .git/gbp.conf
[DEFAULT]
# this is the upstream-branch:
upstream-branch=theupstream-branch
EOF
If you then use &gbp-import-orig; to import new upstream sources, they will
from now on end up on theupstream-branch and
merged to the .
Upstream sources not on a branch
If you don't have an upstream branch but started your repository with only
the upstream sources (not the debian patch) you can simply branch from that
point. So use &gitkcmd; or &gitcmd;-log to locate the commit-id of that commit
and create the upstream branch from there, e.g.:
COMMIT_ID=`&gitcmd; log --pretty=oneline | tail -1 | awk '{ print $1 }'`
&gitcmd; branch upstream $COMMIT_ID
The important thing here is that the COMMIT_ID specifies a
point on the master branch that carried only the
upstream sources and not the debian modifications. The above example
assumes that this was the first commit to that repository.
There's currently no easy way to create the
if you never had the upstream sources
as a single commit. Using &gbp-import-orig; on such repositories might lead
to unexpected merge results.In order to fix this you can prepend the upstream sources as a
single commit to your tree using &git;'s grafts. Afterwards you
can simply create a branch as explained above and &gbp-import-orig; will
work as expected.Alternatively, if you are only importing source from original tarballs
(for instance when converting from a Subversion repository where the
mergeWithUpstream was set for svn-buildpackage), you can create an empty
upstream branch with the following commands:
git checkoutupstreamgit rm.git commit'Initial upstream branch.'git checkoutmaster
With Git versions lower than 1.7.2.3, the commands are slightly more complicated:
git symbolic-refHEADrefs/heads/upstreamgit rm.git commit'Initial upstream branch.'git checkoutmasterStarting a Debian package from scratch
So far we assumed you already have a &debian; package to start with but
what if you want to start a new package? First create an empty repository:
mkdir package-0.1
cd package-0.1
git initThen you import the upstream sources, branch off the
branch and add the debian files (e.g. via dh_make):
&gbp-import-orig; 0.1../package-0.1.tar.gzdh_make
That's it, you're done. If you want to publish you're new repository you can use &gbp-create-remote-repo;.
When upstream uses GIT
If upstream already uses git for packaging there are several ways to handle packaging. Two of them will
be described in a bit detail here:
No upstream tarballsIf upstream doesn't build upstream tarballs or you don't care about them the simplest
way is to clone upstreams repository and create a separate packaging branch in there.
In order to help &gbp-buildpackage; to find upstream tags you need to specify the format
using the comand line option or the the
configuration variable.
A common upstream format is to put a v in front of the version number.
In this case the configuration option would look like:
[git-buildpackage]
upstream-tag = v%(version)s
version will be replaced with the upstream version number as read from
debian/changelog.
If you're using &pristine-tar; you can make &gbp-buildpackage commit the generated tarball back to the
pristine-tar branch by using the option. This will make sure
others building your package can regenerate the tarball you generated for building the Debian pacakge.
Step by stepTo not make any assumptions about &gbp;'s configuration the following steps have all options given
in its long versions on the command line . You can add these
to &gbp.conf; to save lots of typing.
First we clone the upstream repository. To avoid any dis ambiguities between the Debian packaging repository
and the upstream repository we name the upstream repository ustream instead of the
default origin.
git clone --no-checkout -o upstream git://git.example.com/libgbp.git
cd libgbp
git checkout -b debian/sid v1.0
The above makes sure we have debian/sid for the Debian packaging. We didn't create
any upstream/* branches, they're not needed for the packaging and only need to be
kept up to date. After adding the Debian packaging we build the package. This assumes you're using &pristine-tar;
and upstream uses a version number format as described above:
gbp buildpackage --git-pristine-tar --git-pristine-tar-commit --git-upstream-tag='v%(version)s' --git-debian-branch=debian/sid
When updating to a new upstream version we simply fetch from upstream and merge in the new tag. Afterwards we
update the changelog and build the package:
git fetch upstream
git merge v1.1
gbp dch --debian-branch=debian/sid --snapshot --auto debian/
gbp buildpackage --git-ignore-new --git-pristine-tar --git-pristine-tar-commit --git-upstream-tag='v%(version)s'
Note that the above &gbp-dch; call makes sure we only pickup changes in the debian/
directory. Since we told it to build a snapshot changelog entry and we didn't commit the changelog yet
we need to tell &gbp-buildpackage; that the working directory is unclean via the .
Once everything looks good commit the changelog and build a release version:
gbp dch --release --auto --git-debian-branch=debian/sid
git commit -m"Release 1.1-1" debian/changelog
gbp buildpackage --git-upstream-tag='v%(version)s' --git-debian-branch=debian/sid
If you want to share you're repository with others you can use &gbp-create-remote-repo; and &gbp-pull; as usual.
Upstream tarballsIf you want to track upstream's git but continue to import the upstream tarballs,
e.g. to make sure the tarball uploaded
to &debian; has the same checksum as upstream's you can use the option
when importing new tarballs with &gbp-import-orig;. Assuming you have the upstream source in your
repository with a tag v0.0.1 you can use:
&gbp-import-orig; --upstream-vcs-tag=v0.0.1 foo_0.0.1.orig.tar.gz
to add upstream's tag as additional parent to the merge commit.
See #664771 for more details.
Branch layout
By default &gbp; uses one branch to keep the Debian packaging called master
and a branch to keep the upstream packaging called upstream.
This layout is simple to get started but fails short if one needs to maintain several versions of
the package at the same time. Therefore the following layout is recommended:
debian/<release>
the Debian packaging for a release jessie,
wheezy, sid or experimental.
upstream/<release>
the upstream sources for a release matching one of the above
security/<release>
security updates for a certain release
backports/<release>
backports to a certain release
dfsg/<release>
the dfsg clean upstream sources in case the cleanup is done via a &git;
merge from upstream to this branch.
In case &pristine-tar; is being used there will be a single pristine-tar
branch that keeps all binary deltas.