3209
Comment:
|
10316
|
Deletions are marked like this. | Additions are marked like this. |
Line 3: | Line 3: |
~-[[DebianWiki/EditorGuide#translation|Translation(s)]]: English - [[it/PackagingWithGit|Italiano]] -~ ---- <<TableOfContents>> |
|
Line 5: | Line 9: |
{i} Note, that this is just a very general introductory guide. Full, official documentation can be found in the [http://packages.debian.org/git-buildpackage git-buildpackage] package. |
{i} Note, that this is just a very general introductory guide. Full, official documentation can be found in the DebianPkg:git-buildpackage package (see [[https://honk.sigxcpu.org/piki/projects/git-buildpackage/|online documentation]]). For help converting Subversion repositories created by svn-buildpackage to git, see [[PackagingWithGit/Svn-buildpackageConversion|the svn-buildpackage conversion subpage]]. You should also read about pristine-tar support below. This page describes the workflow using the commands from the git-buildpackage package. Alternatively there is also [[PackagingWithGit/GitDpm|git-dpm]]. == Upstream import methods == There are two main ways to import the upstream code into the debianized repository: * One can import upstream release tarballs into a Debian-specific repository. This creates one commit per release. This is generally done with the {{{git-import-orig}}} tool. This is the most general method, because it assumes ONLY that upstream is releasing tarballs. * If upstream is using git to manage their source, the debianization repository can live in a branch off of the main upstream tree. Clearly this can work only with some upstreams, but the big upside is that the relationship between the debianization and the upstream code is VERY clear. Patching and releasing are much more natural. Since the Debian APT repositories still use tarballs you still have to manage those with this setup, but the {{{pristine-tar}}} exists for that purpose. There's also a third option, which is a combination of the two: {{{git-import-orig --upstream-vcs-tag}}}. This is useful primarily when the orig tarball is not identical to the upstream release tag, which can happen if for instance * the tarball was repacked (to remove non-DFSG pieces, for instance) * the script upstream uses to make tarballs makes changes (the autotools {{{make dist}}} does this in some projects) The various pros-cons are discussed here: * http://www.eyrie.org/~eagle/journal/2013-04/001.html * http://joeyh.name/blog/entry/upstream_git_repositories/ * http://www.eyrie.org/~eagle/notes/debian/git.html#combine |
Line 9: | Line 35: |
There are two ways to start a repository for managing package development: * With an already packaged piece of software, using its {{{dsc}}} file * With a new, unpackaged, piece of software, using its upstream tarball. === Importing an already packaged tool === This is simply imported using the {{{git-import-dsc}}} tool. The directory in which it is called will be the parent directory of the new Git repository. |
=== Importing upstream as tarballs === It is easiest to first create the first version of a package, outside of Git. Once this is done, you should import the package using the {{{git-import-dsc}}} tool. The directory in which it is called will be the parent directory of the new Git repository. |
Line 22: | Line 41: |
Line 25: | Line 43: |
{{{$ ls | {{{ $ ls |
Line 28: | Line 47: |
Line 36: | Line 54: |
=== Importing an unpackaged tool === This uses the {{{git-import-orig}}} tool to import an upstream tarball. TODO |
=== Using the upstream repo === If upstream is already using git, simply make a branch for the debianization. The conventions for names of branches and tags are as in the case just described, so one can branch {{{master}}} off of the {{{upstream}}} release, and add the {{{debian/}}} directory as a commit. |
Line 43: | Line 58: |
Line 46: | Line 60: |
{{{$ commit -a }}} |
{{{ $ git commit -a }}} |
Line 51: | Line 65: |
{{{$ git-buildpackage }}} |
{{{ $ git-buildpackage }}} |
Line 56: | Line 70: |
{{{$ git-buildpackage --git-tag }}} |
{{{ $ git-buildpackage --git-tag }}} |
Line 61: | Line 75: |
== Handling debian patches == The {{{gbp-pq}}} tool can be used to track patches in git, and to export/import them to/from the quilt series in {{{debian/patches}}}. == Upgrading to new upstream version == === Importing upstream as tarballs === When a new upstream version comes out, use the {{{git-import-orig}}} tool to add it to the repository. ==== Using a debian/watch file (recommended) ==== {{{ $ git-import-orig --uscan }}} ==== Using a tarball file ==== {{{ $ git-import-orig /path/to/new-upstream.tar.gz -u 0.2 }}} where 0.2 is the new upstream version number. {i} If the upstream tarball is already in the form ''packagename''_''version''.orig.tar.gz (E.g. {{{package_0.2.orig.tar.gz}}}), then the {{{-u}}} option is not required. === Using the upstream repo === If we're using the upstream repo, we can {{{git fetch}}} the new release tag into the repo, in the {{{upstream}}} branch. We need to {{{git merge}}} this branch into {{{master}}}, and to commit the new tarball with {{{pristine-tar}}}. The patches can be rebased with {{{gbp-pq}}}, and git itself can be used to resolve any conflicts that have been created. == Merging a debian-experimental branch into master for sid == Lets assume you have have the following branches: ||upstream||latest upstream in development|| ||upstream-1.5||upstream's 1.5 series, considered stable|| ||master||branch for building packages for sid|| ||debian-experimental||branch for building packages for experimental|| * You are importing each point release into upstream-1.5 and merging to master * You are merging each beta release (1.6~beta) into upstream and merging to debian-experimental At some point, you want to move the work from debian-experimental to the master branch and release it to unstable. First, it is necessary to make sure debian-experimental has everything correct in debian/* - maybe you committed something on master and didn't cherry-pick it to debian-experimental. You can compare the debian/ subtrees like this: {{{ git checkout master git diff debian-experimental debian }}} If necessary, cherry pick any changes onto debian-experimental. The next merge will obliterate everything on master and replace it with the contents of the debian-experimental branch. The only thing that is kept is debian/changelog because it needs to reflect the change history within sid and does not need to contain details of individual releases to experimental. Here is how we do it (make sure master is a clean workspace): {{{ git checkout master git clean -fd && git checkout . git merge -s ours debian-experimental git diff --binary debian-experimental | git apply -R --index git reset debian/changelog git checkout debian/changelog git commit -m 'Merge 1.6.0~rc1 from debian-experimental' --amend }}} After doing this, it is strongly suggested that you inspect the merge with gitk and with git diff before you push to alioth or any other developer. For example, {{{ git diff debian-experimental }}} invoked in master should only show the changelog, because everything else on master should now be identical to debian-experimental. == Conclusion == |
|
Line 66: | Line 149: |
To use pbuilder, you must simply change {{{builder}}} in either {{{~/.gbp.conf}}} or {{{/etc/git-buildpackage/gbp.conf}}} to {{{/usr/local/bin/git-pbuilder}}}, and then: {{{# cp /usr/share/doc/git-buildpackage/examples/git-pbuilder /usr/local/bin/ }}} {i} {{{/usr/local/bin/git-pbuilder}}} can be edited to use additional options, such as {{{--builddir}}} and {{{--debsign-k}}}... |
To use pbuilder, you must simply change {{{builder}}} in either {{{~/.gbp.conf}}} or {{{/etc/git-buildpackage/gbp.conf}}} to {{{/usr/bin/git-pbuilder}}} {i} {{{/usr/bin/git-pbuilder}}} can be edited to use additional options, such as {{{--builddir}}} and {{{--debsign-k}}}... |
Line 75: | Line 154: |
Line 79: | Line 157: |
Line 80: | Line 159: |
Line 82: | Line 160: |
Line 84: | Line 163: |
== More Info == See also: |
=== pristine-tar === git-buildpackage also supports the use of pristine-tar, a new tool developed by Joey Hess to recreate identical tarballs from a small delta file and the files in the current directory. If you enable pristine-tar, delta files are committed to a pristine-tar branch if you call {{{git-import-dsc}}} or {{{git-import-orig}}}. When you build the package using git-buildpackage, the exact tarball is regenerated using pristine-tar. On calling either of the {{{git-import-dsc}}} or {{{git-import-orig}}} tools, the {{{--pristine-tar}}} option may be used. On calling {{{git-buildpackage}}}, the {{{--git-pristine-tar}}} option may be used. You may also enable the pristine-tar option /etc/git-buildpackage/gbp.conf. === running lintian after the build === Add this to ~/.gbp.conf : {{{ postbuild = lintian -I $GBP_CHANGES_FILE && echo "Lintian OK" }}} === running autopkgtest after the build === First configure an environment for adt (see autopkgtest docs, man adt-run) Then add this to your ~/.gbp.conf : {{{ postbuild = adt-run --changes $GBP_CHANGES_FILE --- schroot sid-amd64-sbuild; [ $? -eq 0 -o $? -eq 8 ] }}} The last check is there to avoid failure when there are no tests to run. == See also == * [[Alioth/Git|Using Git on Alioth]] |
Line 89: | Line 192: |
* Git [http://git.or.cz/ homepage] * Git [http://git.or.cz/gitwiki wiki] * Git [http://www.kernel.org/pub/software/scm/git/docs/ manual] |
* [[cowbuilder]] and [[git-pbuilder]] may also be useful == External Links == * Git [[http://git-scm.com/|homepage]] * Git [[https://git.wiki.kernel.org/index.php/Main_Page|wiki]] * Git [[http://www.kernel.org/pub/software/scm/git/docs/|manual]] * [[http://vcs-pkg.org|the vcs-pkg project]] * [[http://www.eyrie.org/~eagle/notes/debian/git.html|Using Git for Debian Packaging]] by Russ Allbery * [[http://www.eyrie.org/~eagle/journal/2013-04/001.html|discussion on how to include the upstream git in the package's git]] * [[http://people.debian.org/~debalance/packaging-with-git.html|Co-maintaining a Debian package with git, git-buildpackage and pbuilder]] by Philipp Huebner |
Line 94: | Line 206: |
CategoryDeveloper | CategoryDeveloper CategoryPackaging CategoryGit |
Translation(s): English - Italiano
Contents
Packaging with Git
Note, that this is just a very general introductory guide. Full, official documentation can be found in the git-buildpackage package (see online documentation).
For help converting Subversion repositories created by svn-buildpackage to git, see the svn-buildpackage conversion subpage.
You should also read about pristine-tar support below.
This page describes the workflow using the commands from the git-buildpackage package. Alternatively there is also git-dpm.
Upstream import methods
There are two main ways to import the upstream code into the debianized repository:
One can import upstream release tarballs into a Debian-specific repository. This creates one commit per release. This is generally done with the git-import-orig tool. This is the most general method, because it assumes ONLY that upstream is releasing tarballs.
If upstream is using git to manage their source, the debianization repository can live in a branch off of the main upstream tree. Clearly this can work only with some upstreams, but the big upside is that the relationship between the debianization and the upstream code is VERY clear. Patching and releasing are much more natural. Since the Debian APT repositories still use tarballs you still have to manage those with this setup, but the pristine-tar exists for that purpose.
There's also a third option, which is a combination of the two: git-import-orig --upstream-vcs-tag. This is useful primarily when the orig tarball is not identical to the upstream release tag, which can happen if for instance
- the tarball was repacked (to remove non-DFSG pieces, for instance)
the script upstream uses to make tarballs makes changes (the autotools make dist does this in some projects)
The various pros-cons are discussed here:
Getting started
Importing upstream as tarballs
It is easiest to first create the first version of a package, outside of Git. Once this is done, you should import the package using the git-import-dsc tool. The directory in which it is called will be the parent directory of the new Git repository.
$ git-import-dsc /path/to/package_0.1-1.dsc
This will give output of its progress and make a few commits. Afterwards, you will have some new files and directories:
$ ls package/ package_0.1-1.orig.tar.gz
Looking in the new repository shows git-buildpackage has done the following:
Imported the package files (but not debian/ directory) into the upstream branch
This has then been tagged upstream/0.1 where 0.1 is your package's version number
Imported the debian/ directory into master as well as upstream's files
Tagged the last commit as debian/0.1-1 as it assumes the package is finished.
Using the upstream repo
If upstream is already using git, simply make a branch for the debianization. The conventions for names of branches and tags are as in the case just described, so one can branch master off of the upstream release, and add the debian/ directory as a commit.
Further packaging workflow
Now you can work in the master branch to edit the package. Commit with:
$ git commit -a
and build the package with:
$ git-buildpackage
Once you have produced a release-ready package, you should tag it, in the following way:
$ git-buildpackage --git-tag
Make sure that your debian/changelog file is correct, as that is what will be used to create the tag. The tag will be named debian/0.1-2 where 0.1-2 is the Debian version.
Handling debian patches
The gbp-pq tool can be used to track patches in git, and to export/import them to/from the quilt series in debian/patches.
Upgrading to new upstream version
Importing upstream as tarballs
When a new upstream version comes out, use the git-import-orig tool to add it to the repository.
Using a debian/watch file (recommended)
$ git-import-orig --uscan
Using a tarball file
$ git-import-orig /path/to/new-upstream.tar.gz -u 0.2
where 0.2 is the new upstream version number.
If the upstream tarball is already in the form packagename_version.orig.tar.gz (E.g. package_0.2.orig.tar.gz), then the -u option is not required.
Using the upstream repo
If we're using the upstream repo, we can git fetch the new release tag into the repo, in the upstream branch. We need to git merge this branch into master, and to commit the new tarball with pristine-tar. The patches can be rebased with gbp-pq, and git itself can be used to resolve any conflicts that have been created.
Merging a debian-experimental branch into master for sid
Lets assume you have have the following branches:
upstream |
latest upstream in development |
upstream-1.5 |
upstream's 1.5 series, considered stable |
master |
branch for building packages for sid |
debian-experimental |
branch for building packages for experimental |
- You are importing each point release into upstream-1.5 and merging to master
- You are merging each beta release (1.6~beta) into upstream and merging to debian-experimental
At some point, you want to move the work from debian-experimental to the master branch and release it to unstable.
First, it is necessary to make sure debian-experimental has everything correct in debian/* - maybe you committed something on master and didn't cherry-pick it to debian-experimental. You can compare the debian/ subtrees like this:
git checkout master git diff debian-experimental debian
If necessary, cherry pick any changes onto debian-experimental. The next merge will obliterate everything on master and replace it with the contents of the debian-experimental branch. The only thing that is kept is debian/changelog because it needs to reflect the change history within sid and does not need to contain details of individual releases to experimental. Here is how we do it (make sure master is a clean workspace):
git checkout master git clean -fd && git checkout . git merge -s ours debian-experimental git diff --binary debian-experimental | git apply -R --index git reset debian/changelog git checkout debian/changelog git commit -m 'Merge 1.6.0~rc1 from debian-experimental' --amend
After doing this, it is strongly suggested that you inspect the merge with gitk and with git diff before you push to alioth or any other developer. For example,
git diff debian-experimental
invoked in master should only show the changelog, because everything else on master should now be identical to debian-experimental.
Conclusion
That is all to the basics of building packages with Git! I would recommend making copies of packages and trying out the tools on temporary repositories, to start with. Once you feel you have mastered it, there are other options that should be looked at.
Further options
pbuilder
To use pbuilder, you must simply change builder in either ~/.gbp.conf or /etc/git-buildpackage/gbp.conf to /usr/bin/git-pbuilder
/usr/bin/git-pbuilder can be edited to use additional options, such as --builddir and --debsign-k...
Signing tags
On calling either of the git-import-dsc or git-import-orig tools, the following options may be used:
--sign-tags
- Whether to sign tags
--keyid=gpg-keyid
- With what gpg key to sign tags with
pristine-tar
git-buildpackage also supports the use of pristine-tar, a new tool developed by Joey Hess to recreate identical tarballs from a small delta file and the files in the current directory.
If you enable pristine-tar, delta files are committed to a pristine-tar branch if you call git-import-dsc or git-import-orig. When you build the package using git-buildpackage, the exact tarball is regenerated using pristine-tar.
On calling either of the git-import-dsc or git-import-orig tools, the --pristine-tar option may be used. On calling git-buildpackage, the --git-pristine-tar option may be used. You may also enable the pristine-tar option /etc/git-buildpackage/gbp.conf.
running lintian after the build
Add this to ~/.gbp.conf :
postbuild = lintian -I $GBP_CHANGES_FILE && echo "Lintian OK"
running autopkgtest after the build
First configure an environment for adt (see autopkgtest docs, man adt-run) Then add this to your ~/.gbp.conf :
postbuild = adt-run --changes $GBP_CHANGES_FILE --- schroot sid-amd64-sbuild; [ $? -eq 0 -o $? -eq 8 ]
The last check is there to avoid failure when there are no tests to run.
See also
?Using Git on Alioth
- /usr/share/doc/git-buildpackage
cowbuilder and git-pbuilder may also be useful
External Links
Git homepage
Git wiki
Git manual
Using Git for Debian Packaging by Russ Allbery
discussion on how to include the upstream git in the package's git
Co-maintaining a Debian package with git, git-buildpackage and pbuilder by Philipp Huebner