From: Ian Jackson Date: Wed, 26 Oct 2016 17:19:26 +0000 (+0100) Subject: dgit-user(7): More work in progress X-Git-Tag: archive/debian/2.9~12^2~35 X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=dgit.git;a=commitdiff_plain;h=a940f4daeaac4af029412a8836e8153b67044a94 dgit-user(7): More work in progress Signed-off-by: Ian Jackson --- diff --git a/dgit-user.7.pod b/dgit-user.7.pod index 1b125739..54bfa1d0 100644 --- a/dgit-user.7.pod +++ b/dgit-user.7.pod @@ -4,384 +4,224 @@ dgit - tutorial for users of Debian-derived distros supported by dgit =head1 INTRODUCTION -dgit lets you get the source code to every package on your system as a -git tree. +dgit lets you fetch the source code to every package on your +system + as if your distro used git to maintain all of it. -You can then edit it, build updated binary packages and install and -run them. You can also share your work with others. +You can then edit it, +build updated binary packages +and install and run them. +You can also share your work with others. -This tutorial assumes you have basic familiarity with git. It does -not assume any initial familiarity with Debian's packaging processes. +This tutorial assumes you have basic familiarity with git. +It does not assume any initial familiarity with + Debian's packaging processes. -.head1 SUMMARY +=head1 SUMMARY =over 4 -% dgit clone glibc jessie -% cd glibc -% wget 'https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=28250;mbox=yes;msg=89' | patch -p1 -u -% - - -=item - -Maintaining convenient and powerful git workflows takes priority over -the usefulness of the raw Debian source package. The Debian archive -is thought of as an output format. - -For example, we don't spend time curating a series of quilt patches. -However, the information such a series would contain is readily -available from B. - -=item - -It is more important to have the Debian package's git history be a -descendent of upstream's git history than to use exactly the orig.tar -that upstream makes available for download. - -=back - -=head1 GIT CONFIGURATION - -Add the following to your ~/.gitconfig to teach git-archive(1) how to -compress orig tarballs: - -=over 4 - - [tar "tar.xz"] - command = xz -c - [tar "tar.gz"] - command = gzip -c - -=back - -=head1 INITIAL DEBIANISATION - -=head2 When upstream tags releases in git - -Suppose that the latest stable upstream release is 1.2.2, and this has -been tagged '1.2.2' by upstream. - -=over 4 - - % git clone -oupstream https://some.upstream/foo.git - % cd foo - % git verify-tag 1.2.2 - % git reset --hard 1.2.2 - % git branch --unset-upstream - -=back - -The final command detachs your master branch from the upstream remote, -so that git doesn't try to push anything there, or merge unreleased -upstream commits. If you want to maintain a copy of your packaging -branch on B in addition to B, you can -do something like this: - -=over 4 - - % git remote add -f origin git.debian.org:/git/collab-maint/foo.git - % git push --follow-tags -u origin master - -=back - -Now go ahead and Debianise your package. Just make commits on the -master branch, adding things in the I directory. If you need -to patch the upstream source, just make commits that change files -outside of the I directory. It is best to separate commits -that touch I from commits that touch upstream source, so that -the latter can be cherry-picked by upstream. - -Note that there is no need to maintain a separate 'upstream' branch, -unless you also happen to be involved in upstream development. We -work with upstream tags rather than any branches, except when -forwarding patches (see FORWARDING PATCHES UPSTREAM, below). - -Finally, you need an orig tarball. Generate one with git-archive(1): - -=over 4 - - % git archive -o ../foo_1.2.2.orig.tar.xz 1.2.2 - -=back - -If you are using the version 1.0 source package format, replace 'xz' -with 'gz'. - -This tarball is ephemeral and easily regenerated, so we don't commit -it anywhere (e.g. with tools like pristine-tar(1)). - -=head3 Verifying upstream's tarball releases - -=over 4 - -It can be a good idea to compare upstream's released tarballs with the -release tags, at least for the first upload of the package. If they -are different, you might need to add some additional steps to your -I, such as running autotools. - -A convenient way to perform this check is to import the tarball as -described in the following section, using a different value for -'upstream-tag', and then use git-diff(1) to compare the imported -tarball to the release tag. If they are the same, you can use -upstream's tarball instead of running git-archive(1). - -=back - -=head2 When upstream releases only tarballs - -We need a virtual upstream branch with virtual release tags. -gbp-import-orig(1) can manage this for us. To begin - -=over 4 - - % mkdir foo - % cd foo - % git init - -=back - -Now create I: - -=over 4 - - [DEFAULT] - upstream-branch = upstream - debian-branch = master - upstream-tag = %(version)s - - sign-tags = True - pristine-tar = False - pristine-tar-commit = False - -=back - -Then we can import the upstream version: - -=over 4 - - % git add debian/gbp.conf && git commit -m "create gbp.conf" - % gbp import-orig ../foo_1.2.2.orig.tar.xz - -=back - -You are now ready to proceed as above, making commits to both the -upstream source and the I directory. - -If you want to maintain a copy of your repository on -B, you should push both the origin and the upstream -branches: - -=over 4 - - % git remote add -f origin git.debian.org:/git/collab-maint/foo.git - % git push --follow-tags -u origin master upstream + % dgit clone glibc jessie + % cd glibc + % wget 'https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=28250;mbox=yes;msg=89' | patch -p1 -u + % git commit -a -m 'Fix libc lost output bug' + % gbp dch -S --since=dgit/dgit/sid --ignore-branch --commit + % sudo apt-get build-dep glibc + % dpkg-buildpackage -uc -b + % sudo dpkg -i ../libc6_*.deb =back -=head1 SOURCE PACKAGE CONFIGURATION - -=head2 debian/source/options - -We set some source package options such that dgit can transparently -handle the "dropping" and "refreshing" of changes to the upstream -source: +Later: =over 4 - single-debian-patch - auto-commit + % cd glibc + % dgit pull jessie + % gbp dch -S --since=dgit/dgit/sid --ignore-branch --commit + % dpkg-buildpackage -uc -b + % sudo dpkg -i ../libc6_*.deb =back -You don't need to create this file if you are using the version 1.0 -source package format. +=head1 FINDING THE RIGHT SOURCE CODE - DGIT CLONE -=head2 Sample text for README.source +dgit clone needs to be told the source package name +(which might be different to the binary package name) +and the codename of the Debian release +(this is called the "suite"). -It is a good idea to explain how a user can obtain a break down of the -changes to the upstream source: +=head2 Finding the source package name -=over 4 - -The Debian packaging of foo is maintained using dgit. For the sake of -an efficient workflow, Debian modifications to the upstream source are -squashed into a single diff, rather than a series of quilt patches. -To obtain a patch queue for package version 1.2.3-1: +For many packages, the source package name is obvious. +Otherwise, if you know a file that's in the package, +you can look it up with dpkg: =over 4 - # apt-get install dgit - % dgit clone foo - % cd foo - % git log --oneline 1.2.3..debian/1.2.3-1 -- . ':!debian' - -=back - -See dgit(1), dgit(7) and dgit-maint-merge(7) for more information. + % dpkg -S /lib/i386-linux-gnu/libc.so.6 + libc6:i386: /lib/i386-linux-gnu/libc.so.6 + % dpkg -s libc6:i386 + Package: libc6 + Status: install ok installed + ... + Source: glibc =back -=head1 BUILDING AND UPLOADING - -Use B, B, B, and B as detailed in dgit(1). If any command fails, dgit will provide -a carefully-worded error message explaining what you should do. If -it's not clear, file a bug against dgit. Remember to pass I<--new> -for the first upload. - -As an alternative to B and friends, you can use a tool -like gitpkg(1). This works because like dgit, gitpkg(1) enforces that -HEAD has exactly the contents of the source package. gitpkg(1) is -highly configurable, and one dgit user reports using it to produce and -test multiple source packages, from different branches corresponding -to each of the current Debian suites. - -If you want to skip dgit's checks while iterating on a problem with -the package build (for example, you don't want to commit your changes -to git), you can just run dpkg-buildpackage(1) or debuild(1) instead. - -=head1 NEW UPSTREAM RELEASES - -=head2 When upstream tags releases in git - -It's a good idea to preview the merge of the new upstream release. -First, just check for any new or deleted files that may need -accounting for in your copyright file: +(In this example, +libc6 is a "multi-arch: allowed" package, + which means that it exists in several different builds + for different architectures. +That's where C<:i386> comes from.) -=over 4 - - % git remote update - % git diff --stat master..1.2.3 -- . ':!debian' +=head2 Finding the Debian release (the "suite") -=back +Internally, +Debian (and derived) distros normally refer to their releases by codenames. +So for example, at the time of writing +Debian C (Debian 8) is Debian stable and +the current version of Ubuntu is C (Yakkety Yak, 16.10). -You can then review the full merge diff: +If you don't know what you're running, try this: =over 4 - % git merge-tree `git merge-base master 1.2.3` master 1.2.3 | $PAGER + % grep '^deb' /etc/apt/sources.list + deb http://the.earth.li/debian/ jessie main non-free contrib + ... + % =back -Once you're satisfied with what will be merged, update your package: +=head1 EDITING THE SOURCE CODE -=over 4 +=head2 What kind of source tree you get when you dgit clone - % git archive ../foo_1.2.3.orig.tar.xz 1.2.3 - % git merge 1.2.3 - % dch -v1.2.3-1 New upstream release. - % git add debian/changelog && git commit -m changelog +If the Debian package is actually a version of an upstream release, +the code layout should be like the upstream version. +You should find that git commands C work properly. -=back - -and you are ready to try a build. +The package's Debian metadata and the script for building binary +packages are under C. +C, C and C are the +starting points. +The Debian Policy Manual has most of the in-depth +technical details. -Again, if you are using the version 1.0 source package format, replace -'xz' with 'gz'. +For many Debian packages, +there will also be some things in C. +These will probably be in your git history +(one way or another), +and they are not used when building a package +based on a git histroy obtained with dgit. +It is best to ignore them. -=head2 When upstream releases only tarballs +=head2 What kind of history you get -Either +If you're lucky, the history will be a version of, +or based on, +the Debian maintainer's own git history, +or upstream's git history. -=over 4 +But for many packages the real git history +does not exist or +cannot be obtained in a standard form +So yuu may find that the history is a rather short +history invented by dgit. - % gbp import-orig ../foo_1.2.2.orig.tar.xz +dgit histories often contain automatically-generated commits, +including commits which make no changes but just serve +to make a rebasing branch fast-forward. -=back +If the package maintainer is using git then +after dgit clone +you may find that there is a useful C remote +referring to the Debian package maintainers repository +for the pacakge. +You can see what's there with C. +But use what you find there with care: +Debian maintainers' git histories are often in +formats which are very confusing and idiosyncratic +from the point of view of those new to Debian git packaging. -or if you have a working watch file +=head1 BUILDING -=over 4 +=head2 Always commit first - % gbp import-orig --uscan +When using git with some arbitrary Debian package +you should normally commit before building. -=back +This is because Debian package builds are often quite messy: +they may modify files which are also committed to git, +or leave outputs and teporary files not covered by C<.gitignore>. +Kf you always commit, +you can use C and C +to put things back. +But if you create a new file +B to say C, and commit, +as otherwise C will delete your new file. -=head1 HANDLING DFSG-NON-FREE MATERIAL +=head2 Update the changelog (at least once) -=head2 When upstream tags releases in git +The binaries you build will have a version number which ultimately +comes from the C. You want to be able to tell your +binaries apart from your distro's. -We create a DFSG-clean tag to merge to master: +So you should update C +to add a new stanza at the top, +for your build. +An easy way to do this is this rune: =over 4 - % git checkout -b pre-dfsg 1.2.3 - % git rm evil.bin - % git commit -m "upstream version 1.2.3 DFSG-cleaned" - % git tag -s 1.2.3+dfsg - % git checkout master - % git branch -D pre-dfsg + % gbp dch -S --since=dgit/dgit/sid --ignore-branch --commit =back -Before merging the new 1.2.3+dfsg tag to master, you should first -determine whether it would be legally dangerous for the non-free -material to be publicly accessible in the git history on -B. - -If it would be dangerous, there is a big problem; -in this case please consult your archive administrators -(for Debian this is the dgit administrator dgit-owner@debian.org -and the ftpmasters ftpmaster@ftp-master.debian.org). - -=head2 When upstream releases only tarballs - -The easiest way to handle this is to add a B field to -I, and a B setting in -I. See uscan(1). Alternatively, see the I<--filter> -option detailed in gbp-import-orig(1). - -=head1 FORWARDING PATCHES UPSTREAM +which adds a new entry with a new version number chosen in a +reasonably sensible way, and commits the result to your git branch. -The basic steps are: +=head1 INSTALLING -=over 4 - -=item 1. - -Create a new branch based off upstream's master branch. - -=item 2. - -git-cherry-pick(1) commits from your master branch onto your new -branch. - -=item 3. - -Push the branch somewhere and ask upstream to merge it, or use -git-format-patch(1) or git-request-pull(1). +You can use C to install the +.debs that came out of your package. -=back +If the dependencies aren't installed, +you will get an error, which can usually be fixed with +C. -For example (and it is only an example): +=head1 SHARING YOUR WORK -=over 4 +The C branch (or whatever) is a normal git branch. +You can use C to any suitable git server. - % # fork foo.git on GitHub - % git remote add -f fork git@github.com:spwhitton/foo.git - % git checkout -b fix-error upstream/master - % git config branch.fix-error.pushRemote fork - % git cherry-pick master^2 - % git push - % # submit pull request on GitHub +If you want to contribute your changes back to Debian, +you should probably send them as attachments to +an email to the +L +(either a followup to an existing bug, or a new bug). +Patches in C< format are usually very welcome. -=back +Anyone who gets that git branch from you +will be able to build binary packages +just as you did. -Note that when you merge an upstream release containing your forwarded -patches, git and dgit will transparently handle "dropping" the patches -that have been forwarded, "retaining" the ones that haven't. +However, the +git branch is not sufficient to build a I. +Source packages are somewhat awkward to work with. +Indeed many plausible git histories or git trees +cannot be converted into a suitable source package. +So I recommend you share your git branch instead. +If you need to provide a source package, +you will probably want to read one of the other tutorials, +such as L, L or + L -=head1 INCORPORATING NMUS +multi-arch clash problem -=over 4 - - % dgit pull - -=back -Alternatively, you can apply the NMU diff to your repository. The -next push will then require I<--overwrite>. +xxx =head1 SEE ALSO