=head1 NAME dgit - tutorial for users of Debian-derived distros supported by dgit =head1 INTRODUCTION 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. This tutorial assumes you have basic familiarity with git. It does not assume any initial familiarity with Debian's packaging processes. =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 % 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 Later: =over 4 % 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 =head1 FINDING THE RIGHT SOURCE CODE - DGIT CLONE 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"). =head2 Finding the source package name 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 % 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 (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.) =head2 Finding the Debian release (the "suite") 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). If you don't know what you're running, try this: =over 4 % grep '^deb' /etc/apt/sources.list deb http://the.earth.li/debian/ jessie main non-free contrib ... % =back =head1 EDITING THE SOURCE CODE =head2 What kind of source tree you get when you dgit clone 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. 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. 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 What kind of history you get 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. 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. dgit histories often contain automatically-generated commits, including commits which make no changes but just serve to make a rebasing branch fast-forward. 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. =head1 BUILDING =head2 Always commit first When using git with some arbitrary Debian package you should normally commit before building. 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. =head2 Update the changelog (at least once) 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. 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 % gbp dch -S --since=dgit/dgit/sid --ignore-branch --commit =back which adds a new entry with a new version number chosen in a reasonably sensible way, and commits the result to your git branch. =head1 INSTALLING You can use C to install the .debs that came out of your package. If the dependencies aren't installed, you will get an error, which can usually be fixed with C. =head1 SHARING YOUR WORK The C branch (or whatever) is a normal git branch. You can use C to any suitable git server. 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. Anyone who gets that git branch from you will be able to build binary packages just as you did. 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 multi-arch clash problem xxx =head1 SEE ALSO dgit(1), dgit(7) =head1 AUTHOR This tutorial was written and is maintained by Sean Whitton . It contains contributions from other dgit contributors too - see the dgit copyright file.